From d4614f92d658c30b36835549776f8acc409eb7a3 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 11:59:52 +0800 Subject: [PATCH 01/67] feat(fs): add a model-facing directory listing tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `ctx.fs.listDir` has shipped since the filesystem seam gained it, with skill discovery as its only consumer; the model-facing tool was deferred to a separate decision. Nothing else could answer "what is in this directory": `rg --files` backs glob and grep and never emits a directory entry, so an empty directory is invisible, no output says which names are directories, and no output gives an entry count. `list` takes an optional `path`, defaulting to the session workspace so the common question needs no argument, and returns the direct children of one directory with their type. Two presentation rules carry it: directories sort first, then files, then non-regular children, each alphabetically — so truncation loses leaves rather than the tree — and the footer always states the complete listing's size and composition, so a capped view can never read as a whole directory. It emits no `fs/observed`: seeing a filename is not reading a file, and a listing must never satisfy the read-before-write gate. --- docs/config-catalog.md | 4 +- docs/tool-catalog.md | 22 ++- examples/acp-agent/tests/acp.snapshot.ts | 4 + .../system-prompt.expected.md | 14 ++ .../tool-schemas.expected.json | 13 ++ .../both-mode-turn/system-prompt.expected.md | 14 ++ .../both-mode-turn/tool-schemas.expected.json | 13 ++ .../code-mode-turn/system-prompt.expected.md | 14 ++ .../system-prompt.expected.md | 14 ++ .../system-prompt.expected.md | 2 + .../tool-schemas.expected.json | 13 ++ .../tests/snapshots/fs-list/input.json | 7 + .../tests/snapshots/fs-list/session.jsonl | 32 +++++ .../snapshots/fs-list/stdout.expected.jsonl | 4 + .../snapshots/fs-list/workspace/README.txt | 1 + .../fs-list/workspace/docs/guide.txt | 1 + .../snapshots/fs-list/workspace/package.json | 1 + .../snapshots/fs-list/workspace/src/index.txt | 1 + .../lsp-definition/system-prompt.expected.md | 2 + .../lsp-definition/tool-schemas.expected.json | 13 ++ .../pty-tools/system-prompt.expected.md | 2 + .../pty-tools/tool-schemas.expected.json | 13 ++ .../system-prompt.expected.md | 2 + .../tool-schemas.expected.json | 13 ++ .../skill-load/system-prompt.expected.md | 2 + .../skill-load/tool-schemas.expected.json | 13 ++ .../text-turn/system-prompt.expected.md | 2 + .../text-turn/tool-schemas.expected.json | 13 ++ .../web-fetch/system-prompt.expected.md | 2 + .../web-fetch/tool-schemas.expected.json | 13 ++ .../system-prompt.expected.md | 2 + .../tool-schemas.expected.json | 13 ++ .../advanced-toolchain/session.1.jsonl | 2 +- .../advanced-toolchain/session.2.jsonl | 2 +- .../advanced-toolchain/session.jsonl | 2 +- .../tests/snapshots/pty-tools/session.jsonl | 2 +- .../terminal.expected.txt | 2 +- .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- packages/fs/tool-fs/README.i18n.yaml | 6 +- packages/fs/tool-fs/README.md | 43 ++++-- packages/fs/tool-fs/README.zh.md | 43 ++++-- packages/fs/tool-fs/package.json | 2 +- packages/fs/tool-fs/src/index.ts | 18 ++- packages/fs/tool-fs/src/list-render.ts | 82 +++++++++++ packages/fs/tool-fs/src/list.ts | 120 ++++++++++++++++ packages/fs/tool-fs/tests/list-render.spec.ts | 69 +++++++++ packages/fs/tool-fs/tests/tools.spec.ts | 131 +++++++++++++++++- scripts/gen-tool-catalog.ts | 2 +- 48 files changed, 761 insertions(+), 46 deletions(-) create mode 100644 examples/acp-agent/tests/snapshots/fs-list/input.json create mode 100644 examples/acp-agent/tests/snapshots/fs-list/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl create mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt create mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt create mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/package.json create mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt create mode 100644 packages/fs/tool-fs/src/list-render.ts create mode 100644 packages/fs/tool-fs/src/list.ts create mode 100644 packages/fs/tool-fs/tests/list-render.spec.ts diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 47a8acfd30..0b0045b668 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1449,6 +1449,8 @@ Requires: `tools` · `fs` · `systemPrompt` ```ts config-catalog /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { + /** Maximum entries one `list` call renders inline; the footer still reports the complete count. */ + listMaxEntries?: number /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number /** Maximum characters returned for a single line before truncation. */ @@ -1460,7 +1462,7 @@ export interface Config { } ``` -Source: [`packages/fs/tool-fs/src/index.ts:24`](../packages/fs/tool-fs/src/index.ts) +Source: [`packages/fs/tool-fs/src/index.ts:27`](../packages/fs/tool-fs/src/index.ts) ## `@deepseek-ai/dsh-tool-fs-search` diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 311791e594..6edd5be644 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -20,7 +20,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. | | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. | | `@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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header 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-fs` | `edit`, `list`, `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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. | | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. | | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. | | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `user/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. | @@ -316,6 +316,24 @@ Edit an existing UTF-8 text file by replacing literal text. Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) +### `list` + +List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. + +```json +{ + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } +} +``` + +Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) + ### `read` Read a UTF-8 text file and return line-numbered content. @@ -371,7 +389,7 @@ Create or fully replace a UTF-8 text file. Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) -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. +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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. ## `@deepseek-ai/dsh-tool-fs-search` diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 4fb6f9493b..6b04b0038e 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -121,6 +121,10 @@ const SCENARIOS: Scenario[] = [ hasModelTurn: true, recorded: true, }, + // A workspace whose subdirectories are what the answer depends on: `glob` + // could not produce them at all, so this scenario pins the listing envelope + // end to end (see the directory-listing Agent Note). + { name: 'fs-list', hasModelTurn: true, recorded: true }, { name: 'fs-read', hasModelTurn: true, recorded: true }, { name: 'fs-write', hasModelTurn: true, recorded: true }, { name: 'fs-edit', hasModelTurn: true, recorded: true }, diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md index 3a37f3da6a..c78b763fec 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. @@ -97,6 +99,11 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + list: { + /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ + path?: string; + } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -298,6 +305,13 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; + list: { + path: string; + entries: ({ + name: string; + type: "file" | "directory" | "other"; + })[]; + }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json index 1abccfd566..f9aea468b5 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json @@ -172,6 +172,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md index 0cee2a6517..ede2684ae4 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. @@ -80,6 +82,11 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + list: { + /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ + path?: string; + } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -269,6 +276,13 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; + list: { + path: string; + entries: ({ + name: string; + type: "file" | "directory" | "other"; + })[]; + }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json index b61d7bf623..1333345b48 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md index 0cee2a6517..ede2684ae4 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. @@ -80,6 +82,11 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + list: { + /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ + path?: string; + } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -269,6 +276,13 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; + list: { + path: string; + entries: ({ + name: string; + type: "file" | "directory" | "other"; + })[]; + }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md index 0cee2a6517..ede2684ae4 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. @@ -80,6 +82,11 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + list: { + /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ + path?: string; + } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -269,6 +276,13 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; + list: { + path: string; + entries: ({ + name: string; + type: "file" | "directory" | "other"; + })[]; + }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md index e3437ad61a..edca40eed4 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json index 01ac777a42..ffb310c278 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/fs-list/input.json b/examples/acp-agent/tests/snapshots/fs-list/input.json new file mode 100644 index 0000000000..67a0bc3f42 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Call the list tool exactly once, with no arguments at all (NOT bash, NOT glob, and do not pass a path). Then reply with exactly the names of the subdirectories it reported, alphabetically, separated by a single space, and nothing else." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/fs-list/session.jsonl b/examples/acp-agent/tests/snapshots/fs-list/session.jsonl new file mode 100644 index 0000000000..0a05e2b1fe --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/session.jsonl @@ -0,0 +1,32 @@ +{"type":"session","version":0,"id":"ea640046-d959-4644-9a03-ff3d08133d4b","createdAt":1785159113359,"cwd":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6","delegationDepth":0} +{"type":"turn/start","seq":0,"time":1785159113361,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1785159113362,"data":{"content":[{"type":"text","text":"Call the list tool exactly once, with no arguments at all (NOT bash, NOT glob, and do not pass a path). Then reply with exactly the names of the subdirectories it reported, alphabetically, separated by a single space, and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"session/title","seq":2,"time":1785159113363,"data":{"title":"Call the list tool exactly","messageSeqs":[1],"source":{"kind":"fallback"}}} +{"type":"step/start","seq":3,"time":1785159113368,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":4,"time":1785159113369,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":5,"time":1785159115248,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":6,"time0":1785159115249,"data":{"turn":1,"step":1,"index":0,"dt":[146,45,3,0,0,1,43,1,0,0,1,1,31,1,46,0,0,0,0,0,41,1,0,0,45,2,2,0,0,1,44,3,3,0],"texts":["The"," user"," wants"," me"," to"," call"," the"," list"," tool"," with"," no"," arguments"," and"," then"," reply"," with"," the"," names"," of"," the"," sub","direct","ories"," it"," reports",","," alphabet","ically",","," separated"," by"," a"," single"," space","."]}} +{"type":"assistant/chunk","seq":41,"time":1785159115836,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":42,"time":1785159115837,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","argumentsDelta":""}}} +{"type":"assistant/chunk","seq":43,"time":1785159115837,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","argumentsDelta":"{}"}}} +{"type":"assistant/chunk","seq":44,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call the list tool with no arguments and then reply with the names of the subdirectories it reports, alphabetically, separated by a single space."}}}} +{"type":"assistant/chunk","seq":45,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}}}} +{"type":"assistant/chunk","seq":46,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":5513,"outputTokens":62,"cacheReadTokens":0,"reasoningTokens":35}}}} +{"type":"assistant/chunk","seq":47,"time":1785159115922,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":48,"time":1785159115926,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call the list tool with no arguments and then reply with the names of the subdirectories it reports, alphabetically, separated by a single space."},{"type":"tool-call","id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":5513,"outputTokens":62,"cacheReadTokens":0,"reasoningTokens":35}},"sourceEventSeqs":[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],"surfaceOp":"append"} +{"type":"tool/call","seq":49,"time":1785159115927,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}} +{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\ndirectory\n\ndocs/\nsrc/\npackage.json\nREADME.txt\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} +{"type":"step/end","seq":51,"time":1785159115950,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":52,"time":1785159115951,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":53,"time":1785159116889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":54,"time0":1785159116890,"data":{"turn":1,"step":2,"index":0,"dt":[145,49,1,0,60,0,0,1,0,39,1,0,0,0,0,23,1,46,3,0,0],"texts":["The"," sub","direct","ories"," reported"," are"," `","docs","/","`"," and"," `","src","/","`."," Alphabet","ically",":"," docs",","," src","."]}} +{"type":"assistant/chunk","seq":76,"time":1785159117259,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":77,"time":1785159117259,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"docs"}}} +{"type":"assistant/chunk","seq":78,"time":1785159117297,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" src"}}} +{"type":"assistant/chunk","seq":79,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The subdirectories reported are `docs/` and `src/`. Alphabetically: docs, src."}}}} +{"type":"assistant/chunk","seq":80,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"docs src"}}}} +{"type":"assistant/chunk","seq":81,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":161,"outputTokens":25,"cacheReadTokens":5504,"reasoningTokens":22}}}} +{"type":"assistant/chunk","seq":82,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":83,"time":1785159117301,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The subdirectories reported are `docs/` and `src/`. Alphabetically: docs, src."},{"type":"text","text":"docs src"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":161,"outputTokens":25,"cacheReadTokens":5504,"reasoningTokens":22}},"sourceEventSeqs":[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],"surfaceOp":"append"} +{"type":"step/end","seq":84,"time":1785159117308,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":85,"time":1785159117309,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl new file mode 100644 index 0000000000..22d36a3c79 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl @@ -0,0 +1,4 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"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_message_chunk","content":{"type":"text","text":"docs src"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt new file mode 100644 index 0000000000..dab306f45e --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt @@ -0,0 +1 @@ +# Project diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt new file mode 100644 index 0000000000..8c0d02fadc --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt @@ -0,0 +1 @@ +# Guide diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json b/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json new file mode 100644 index 0000000000..e36fa754cf --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json @@ -0,0 +1 @@ +{ "name": "demo" } diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt new file mode 100644 index 0000000000..eab39ce89c --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt @@ -0,0 +1 @@ +export const answer = 42 diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md index 7bde8fe289..5a5df6233c 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json index 9b5925605c..3a0e7c1408 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "lsp", "description": "Query a language server for precise code navigation. operation is one of goToDefinition, findReferences, goToImplementation, hover. line and character are one-based UTF-16 cursor coordinates. findReferences includes the declaration.", diff --git a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md index df065a83cb..70dd754517 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json index 8e093db8bd..c529ad9077 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md index 68bdd841c7..658fa4e07c 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json index beb93c6b53..4eff11591a 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md index 17e6773a03..6d926a90a8 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json index 01ac777a42..ffb310c278 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md index 17e6773a03..6d926a90a8 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json index 01ac777a42..ffb310c278 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md index 45705db0a5..4c20e18272 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json index 70940f8907..59e3baf6b1 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md index 6cd8d5725f..6c5155f262 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md @@ -5,6 +5,8 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. + Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json index 01ac777a42..ffb310c278 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json @@ -115,6 +115,19 @@ "properties": {} } }, + { + "name": "list", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + } + } + } + }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl index 6cae860e36..c0f80e3cdf 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884563,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884563,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884564,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950001005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":6,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}} {"type":"assistant/chunk","seq":7,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}} diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl index c00a4119c7..2bf8be7bfb 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884700,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884700,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884700,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950002005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":6,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}} {"type":"assistant/chunk","seq":7,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}} diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl index 9d2b188a45..8f531cf789 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884479,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884479,"data":{"title":"Run this advanced flow exactly","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record)[];\n } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":true,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} {"type":"assistant/chunk","seq":6,"time":1783950000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}} {"type":"assistant/chunk","seq":7,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}} diff --git a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl index 99eaf6e4ee..2cde7d9e42 100644 --- a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl +++ b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Exercise the six PTY tools in order, including one missing-session signal error, then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":0,"data":{"title":"Exercise the six PTY tools","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\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 a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"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","additionalProperties":true,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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 a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"pty-spawn","name":"terminal_open","argumentsDelta":"{\"type\":\"shell\",\"name\":\"main\"}"}}} {"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"pty-spawn","name":"terminal_open","arguments":"{\"type\":\"shell\",\"name\":\"main\"}"}}}} diff --git a/examples/tui-agent/tests/snapshots/code-mode-dispatch-spill/terminal.expected.txt b/examples/tui-agent/tests/snapshots/code-mode-dispatch-spill/terminal.expected.txt index aad4b2cd50..7a2024ac06 100644 --- a/examples/tui-agent/tests/snapshots/code-mode-dispatch-spill/terminal.expected.txt +++ b/examples/tui-agent/tests/snapshots/code-mode-dispatch-spill/terminal.expected.txt @@ -59,7 +59,7 @@ buffer style 1-1 inverse 27| "────────────────────────────────────────────────────────────────────────────────────────────────────" style 0-99 dim -28| "deepseek-v4-flash /workspace/project ↑123 ↓208 cache 99% 3% c" +28| "deepseek-v4-flash /workspace/project ↑123 ↓208 cache 99% 4% c" style 0-93 dim style 96-99 dim 29-35| diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index 3754595f56..974d88c18c 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -23,7 +23,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(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write']) + expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'list', 'lsp', 'ralph', 'read', 'run_code', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', '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/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index 13f1ecd649..e6f4ccf9c0 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write -README.md: 4ff9b043525e8e7a0b59e3d91410951d88bb9a69 -README.zh.md: f94a903c9c37f7d45b7f8cebabe21082388bd041 +# pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md +README.md: 08a4f74b928a38b92fdce5f6a03dd7c6c8f0af7c +README.zh.md: cdb45a12eb644e4882f7b92ac77b5bc7fc33f906 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 4ff9b04352..08a4f74b92 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -2,23 +2,24 @@ English | [中文](README.zh.md) -The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly** — it injects `fs` (plus `tools`/`systemPrompt`), **not** a policy service. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. +The **model-facing filesystem tools** — `list`, `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, **listing order**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly** — it injects `fs` (plus `tools`/`systemPrompt`), **not** a policy service. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. ```ts ignore-check // Default deployment: a ctx.fs provider, the policy plugin, then the tools. await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local await ctx.plugin(FsPolicy) // @deepseek-ai/dsh-fs-policy (policy gate) -await ctx.plugin(ToolFs) // this package — registers read/write/edit +await ctx.plugin(ToolFs) // this package — registers list/read/write/edit ``` `@deepseek-ai/dsh-fs-policy` is **optional**: omit it and the tools run against the bare provider (unconditional write/overwrite/edit, no observed-state). A deployment that loads these tools is expected to also load it, so the behavior is read-before-write/edit. ## Config -All keys are optional; the defaults are the shipped read caps. +All keys are optional; the defaults are the shipped listing and read caps. | Key | Default | Meaning | |---|---|---| +| `listMaxEntries` | `200` | Entries one `list` call renders inline; the footer still reports the complete directory's size and composition. | | `readLimit` | `2000` | Default and maximum lines returned by one `read` call (the tool schema advertises it as the `limit` default). | | `readMaxLineLength` | `2000` | Characters kept per line before truncation (the suffix names the cap). | | `readMaxBytes` | `51200` | Byte cap on one `read` call's selected lines; overflow ends the window with a "capped" footer. | @@ -28,18 +29,20 @@ All keys are optional; the defaults are the shipped read caps. | Tool | Arguments | Behavior | |---|---|---| +| `list` | `path?` | Direct children of one directory with their type, defaulting to the session workspace. Ordered directories first, then files, then non-regular children, each alphabetical, and capped at the configured `listMaxEntries` (200). | | `read` | `file_path`, `offset?`, `limit?` | Line-numbered UTF-8 content with a pagination footer. `offset` is 1-based; `limit` defaults to and caps at the configured `readLimit` (2000). | | `write` | `file_path`, `content` | Create or fully replace a file. With the policy plugin: overwriting an existing file requires a prior `read` at the unchanged version; creating a new file does not. Without it: unconditional. | | `edit` | `file_path`, non-empty `old_string`, `new_string`, `replace_all?` | Literal replacement; unique match required unless `replace_all` is true. With the policy plugin: requires a prior `read` (any window) and the file unchanged since. Without it: unconditional. | Field names are snake_case to match Claude Code and existing harness tool schemas. -Canonical successes are `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. +Canonical successes are `list` → `{ path, entries: [{ name, type: 'file' | 'directory' | 'other' }] }`, `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. ## The tool is the executor; policy is an event gate The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then: +- **list** — one `ctx.fs.listDir`; the seam already answers absence with `FS_NOT_FOUND` and a non-directory target with `FS_NOT_DIRECTORY`, so no probe precedes it. No `fs/observed`: a listing reads no file content and must not satisfy the read-before-write gate. (0 stat.) - **read** — one `ctx.fs.stat` (type + size routing + version), then `readText`/`streamText`, then builds the line window, then emits `fs/observed` with a plain `ctx.emit`. (1 stat.) - **write** — `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.writeText(target, content, intent)`, then `fs/observed`. (0 stat.) - **edit** — `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.editText(target, edit, intent)`, then `fs/observed`. (0 stat.) @@ -50,9 +53,9 @@ The tool passes `exec` (the tool-execution context) as the opaque `actor` on eve `fs/observed` fires AFTER the read/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — async or fallible observation does not belong on this event. -`read` opts into concurrent scheduling because its only mutation is the synchronous version recorder. Recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock; both mutation tools remain exclusive. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md). +`list` and `read` opt into concurrent scheduling — `list` mutates nothing at all, and `read`'s only mutation is the synchronous version recorder. Recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock; both mutation tools remain exclusive. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md). -The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them. +The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Pure presentation lives beside the executors and is independently unit-tested: read windowing and output formatting in `src/read-render.ts`, listing order and envelope in `src/list-render.ts` (both Cordis-free); `src/list.ts`/`read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them. ## Model Experience @@ -60,7 +63,13 @@ The package root exports only the Cordis plugin contract (`name`, `inject`, `Con #### What the model sees -Every request in this plugin's registration scope receives the independently registered read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections. +Every request in this plugin's registration scope receives the independently registered list, read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections. + +##### List guidance + +```markdown +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +``` ##### Read guidance @@ -92,7 +101,7 @@ Prefix-stable while the plugin scope and guidance text are unchanged. Tool restr #### What the model sees -The model sees the generated [`read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent. +The model sees the generated [`list`, `read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent. #### Token effect @@ -102,6 +111,20 @@ Fixed schema cost on every request in that tool view. Prefix-stable while the visible tool definitions and order are unchanged. Registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token. +### List result + +#### What the model sees + +A successful listing is exactly ``, newline, `directory`, newline, ``, one line per entry, a blank line, one footer, and ``. A directory entry carries a trailing `/` and a non-regular child a trailing `@`; a regular file carries neither. The footer is exactly `(Empty directory)`, `( entries: directories, files)` — with `, other` appended only when such a child exists, and singulars where the count is one — or, when the view is capped, `(Showing of entries: directories, files. Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)`. The complete count and composition are stated whether or not the view was capped, so a partial listing can never read as a whole directory. + +#### Token effect + +Listing output is capped by `listMaxEntries`; the retained call and result are resent until compaction. + +#### KV Cache effect + +Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries. + ### Read result #### What the model sees @@ -134,7 +157,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, and `offset is out of range for "" ( lines)`; provider and policy templates are quoted in their package READMEs. +Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `path must be a non-empty string when given`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, and `offset is out of range for "" ( lines)`; provider and policy templates are quoted in their package READMEs. #### Token effect @@ -146,6 +169,6 @@ Append-only; newly visible content follows the reusable request prefix and does ## Known Limitations and Deferred Work -- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam. +- **`list` reads one directory level and has no spill path** — recursion, pagination, and per-directory child counts are absent, and a listing past `listMaxEntries` is summarized by its footer rather than saved anywhere retrievable; the model lists a subdirectory instead. - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`. - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)). diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index f94a903c9c..cdb45a12eb 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -2,23 +2,24 @@ [English](README.md) | 中文 -**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON schema、参数校验、提示词段、**读取窗口逻辑** 和结果格式化。它**直接** 通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取/写入/编辑：注入 `fs`（以及 `tools`/`systemPrompt`），**不** 注入政策服务。新鲜度/观察政策由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。 +**面向模型的文件系统工具**（`list`、`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON schema、参数校验、提示词段、**读取窗口逻辑**、**列出顺序** 和结果格式化。它**直接** 通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取/写入/编辑：注入 `fs`（以及 `tools`/`systemPrompt`），**不** 注入政策服务。新鲜度/观察政策由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。 ```ts ignore-check // Default deployment: a ctx.fs provider, the policy plugin, then the tools. await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local await ctx.plugin(FsPolicy) // @deepseek-ai/dsh-fs-policy (policy gate) -await ctx.plugin(ToolFs) // this package — registers read/write/edit +await ctx.plugin(ToolFs) // this package — registers list/read/write/edit ``` `@deepseek-ai/dsh-fs-policy` 是**可选的**：省略时，工具直接使用裸提供方（无条件写入/覆盖/编辑，无已观察状态）。加载这些工具的部署也应加载该插件，从而提供编辑前读取行为。 ## 配置 -所有键均为可选；默认值是随产品交付的读取上限。 +所有键均为可选；默认值是随产品交付的列出与读取上限。 | 键 | 默认值 | 含义 | |---|---|---| +| `listMaxEntries` | `200` | 一次 `list` 调用内联渲染的条目数；footer 仍会报告整个目录的规模与构成。 | | `readLimit` | `2000` | 一次 `read` 调用返回的默认和最大行数（工具 schema 将其声明为 `limit` 默认值）。 | | `readMaxLineLength` | `2000` | 每行截断前保留的字符数（后缀会说明上限）。 | | `readMaxBytes` | `51200` | 一次 `read` 调用所选行的字节上限；溢出时以「已达上限」footer 结束窗口。 | @@ -28,18 +29,20 @@ await ctx.plugin(ToolFs) // this package — re | 工具 | 参数 | 行为 | |---|---|---| +| `list` | `path?` | 单个目录的直接子项及其类型，默认取会话工作区。顺序为先目录、再文件、最后非常规子项，各组内按字母序排列，并受配置的 `listMaxEntries`（200）限制。 | | `read` | `file_path`、`offset?`、`limit?` | 带行号的 UTF-8 内容和分页 footer。`offset` 从 1 开始；`limit` 默认为配置的 `readLimit`（2000），上限也为该值。 | | `write` | `file_path`、`content` | 创建文件或完整替换文件。有政策插件时：覆盖现有文件要求先在未变版本上执行 `read`；创建新文件不需要。没有插件时：无条件执行。 | | `edit` | `file_path`、非空 `old_string`、`new_string`、`replace_all?` | 字面量替换；除非 `replace_all` 为 true，否则要求唯一匹配。有政策插件时：要求先执行 `read`（任何窗口），且文件此后未变。没有插件时：无条件执行。 | 字段名使用 snake_case，与 Claude Code 和现有 harness 工具 schema 一致。 -规范成功值分别为：`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。Native 渲染器会保留下方带行号的读取结果和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 +规范成功值分别为：`list` → `{ path, entries: [{ name, type: 'file' | 'directory' | 'other' }] }`，`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。Native 渲染器会保留下方带行号的读取结果和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 ## 工具就是执行器；政策是事件门禁 工具**不** 注入政策服务，也不检查任何缓存。每个工具通过 `ctx.fs.resolve(path, { cwd, signal })` 解析路径；它会传入调用 agent（智能体）的会话 cwd（`exec.agent.session.header.cwd`），使相对路径以会话工作区为基准解析并与 `dsh-tool-bash` 一致，同时把工具取消转发到解析过程（见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)）。随后执行： +- **list**：一次 `ctx.fs.listDir`；seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，因此前面不需要任何探测。不发出 `fs/observed`：列出不读取任何文件内容，也不得满足编辑前读取门禁。（0 次 stat。） - **read**：一次 `ctx.fs.stat`（用于类型、大小路由和版本），随后调用 `readText`/`streamText`，构建行窗口，再发出 `fs/observed`，使用普通 `ctx.emit`。（1 次 stat。） - **write**：调用 `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.writeText(target, content, intent)`，再发出 `fs/observed`。（0 次 stat。） - **edit**：调用 `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.editText(target, edit, intent)`，再发出 `fs/observed`。（0 次 stat。） @@ -50,9 +53,9 @@ await ctx.plugin(ToolFs) // this package — re `fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的契约是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。 -`read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。 +`list` 与 `read` 都允许并发调度：`list` 完全不做任何变更，而 `read` 的唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。 -包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。 +包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。纯展示逻辑与执行器并列存放并单独进行单元测试：读取窗口与输出格式化位于 `src/read-render.ts`，列出顺序与包络位于 `src/list-render.ts`（两者均不依赖 Cordis）；`src/list.ts`/`read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。 ## 模型体验 @@ -60,7 +63,13 @@ await ctx.plugin(ToolFs) // this package — re #### 模型看到的内容 -该插件注册作用域内的每个请求都会收到下方独立注册的 read、write 与 edit 指导。作用域工具限制可以隐藏 schema，而不移除这些段。 +该插件注册作用域内的每个请求都会收到下方独立注册的 list、read、write 与 edit 指导。作用域工具限制可以隐藏 schema，而不移除这些段。 + +##### List 指导 + +```markdown +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +``` ##### Read 指导 @@ -92,7 +101,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -模型会看到已生成的 [`read`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。作用域工具限制可以为某个 agent 移除任一定义。 +模型会看到已生成的 [`list`、`read`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。作用域工具限制可以为某个 agent 移除任一定义。 #### Token 影响 @@ -102,6 +111,20 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces 只要可见工具定义和顺序不变，前缀就保持稳定。注册生命周期或作用域限制可能从首个变化的 schema token 开始使复用失效。 +### 列出结果 + +#### 模型看到的内容 + +成功列出结果精确为 ``、换行、`directory`、换行、``、每个条目一行、一个空行、一条 footer 和 ``。目录条目带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。footer 精确为 `(Empty directory)`、`( entries: directories, files)`（仅当存在此类子项时才追加 `, other`，计数为一时使用单数形式），或在视图被截断时为 `(Showing of entries: directories, files. Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)`。无论视图是否被截断，都会说明完整计数与构成，因此部分列出结果绝不会被读成整个目录。 + +#### Token 影响 + +列出输出受 `listMaxEntries` 限制；保留的调用与结果会反复发送，直到上下文压缩。 + +#### KV Cache 影响 + +仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。 + ### 读取结果 #### 模型看到的内容 @@ -134,7 +157,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file` 和 `offset is out of range for "" ( lines)`；提供方和政策模板在各自包的 README 中逐字列出。 +失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`path must be a non-empty string when given`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file` 和 `offset is out of range for "" ( lines)`；提供方和政策模板在各自包的 README 中逐字列出。 #### Token 影响 @@ -146,6 +169,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces ## 已知限制与延期工作 -- **未交付面向模型的目录列出工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。 +- **`list` 只读取一层目录，且没有溢出落盘路径**：不提供递归、分页和逐目录子项计数，超出 `listMaxEntries` 的部分只由 footer 概括，不会保存到任何可取回的位置；模型改为列出对应子目录。 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。 - **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见有意采用的 [fs 能力族立场](../README.md)）。 diff --git a/packages/fs/tool-fs/package.json b/packages/fs/tool-fs/package.json index 737f7ac26b..936d125013 100644 --- a/packages/fs/tool-fs/package.json +++ b/packages/fs/tool-fs/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-tool-fs", - "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)", + "description": "Model-facing filesystem tools (list, read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)", "version": "0.0.1", "private": true, "type": "module", diff --git a/packages/fs/tool-fs/src/index.ts b/packages/fs/tool-fs/src/index.ts index a4c96d606b..c8376ed123 100644 --- a/packages/fs/tool-fs/src/index.ts +++ b/packages/fs/tool-fs/src/index.ts @@ -1,16 +1,19 @@ /** - * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation, - * read windows, formatting, and observation events, never a concrete provider. An optional - * event policy supplies mutation guards; without one the tools use unconditional provider calls. + * Model-facing list, read, write, and edit tools over `ctx.fs`. This package owns schemas, + * validation, read windows, listing order, formatting, and observation events, never a concrete + * provider. An optional event policy supplies mutation guards; without one the tools use + * unconditional provider calls. * @module @deepseek-ai/dsh-tool-fs */ import type { Context } from 'cordis' import z from 'schemastery' import type {} from '@deepseek-ai/dsh-user-approval' +import { applyListTool } from './list.ts' import { applyReadTool, READ_LIMIT, STREAM_MIN_SIZE } from './read.ts' import { applyWriteTool } from './write.ts' import { applyEditTool } from './edit.ts' +import { LIST_MAX_ENTRIES } from './list-render.ts' import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from './read-render.ts' import { FsSandboxSurface } from './sandbox.ts' @@ -22,6 +25,8 @@ export const inject = ['tools', 'fs', 'systemPrompt'] /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { + /** Maximum entries one `list` call renders inline; the footer still reports the complete count. */ + listMaxEntries?: number /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number /** Maximum characters returned for a single line before truncation. */ @@ -33,6 +38,7 @@ export interface Config { } export const Config: z = z.object({ + listMaxEntries: z.number().default(LIST_MAX_ENTRIES), readLimit: z.number().default(READ_LIMIT), readMaxLineLength: z.number().default(READ_MAX_LINE_LENGTH), readMaxBytes: z.number().default(READ_MAX_BYTES), @@ -42,21 +48,23 @@ export const Config: z = z.object({ /** The shape after schemastery applied the defaults. */ type ResolvedConfig = Required -/** Every read cap counts lines/chars/bytes — a positive integer, or windowing arithmetic misbehaves silently. */ +/** Every read or listing cap counts lines/chars/bytes/entries — a positive integer, or windowing arithmetic misbehaves silently. */ function assertPositiveInteger(name: string, value: number): void { if (!Number.isInteger(value) || value < 1) { throw new Error(`tool-fs: ${name} must be a positive integer`) } } -/** Register the full `read`/`write`/`edit` filesystem tool suite. */ +/** Register the full `list`/`read`/`write`/`edit` filesystem tool suite. */ export function apply(ctx: Context, config: Config): void { // schemastery (Config) has already filled every defaulted field. const resolved = config as ResolvedConfig + assertPositiveInteger('listMaxEntries', resolved.listMaxEntries) assertPositiveInteger('readLimit', resolved.readLimit) assertPositiveInteger('readMaxLineLength', resolved.readMaxLineLength) assertPositiveInteger('readMaxBytes', resolved.readMaxBytes) assertPositiveInteger('readStreamMinSize', resolved.readStreamMinSize) + applyListTool(ctx, { maxEntries: resolved.listMaxEntries }) applyReadTool(ctx, { limit: resolved.readLimit, maxLineLength: resolved.readMaxLineLength, diff --git a/packages/fs/tool-fs/src/list-render.ts b/packages/fs/tool-fs/src/list-render.ts new file mode 100644 index 0000000000..d7a65cbb27 --- /dev/null +++ b/packages/fs/tool-fs/src/list-render.ts @@ -0,0 +1,82 @@ +/** + * Pure listing presentation: order one directory's direct children so a capped + * view still shows the navigable structure, and render the model-facing + * envelope. Cordis-free and independently unit-tested, mirroring + * {@link module:@deepseek-ai/dsh-tool-fs/read-render}. + * @module @deepseek-ai/dsh-tool-fs/list-render + */ + +/** Default and maximum number of entries one `list` call renders inline (the `listMaxEntries` config). */ +export const LIST_MAX_ENTRIES = 200 + +/** One direct child in a rendered listing — the canonical entry shape the tool returns. */ +export interface ListedEntry { + /** Basename of the child inside the listed directory. */ + name: string + /** Whether the child is a regular file, a directory, or something else (symlink, socket, device). */ + type: 'file' | 'directory' | 'other' +} + +/** + * Order direct children so truncation cannot hide the directory tree: + * directories first, then files, then everything else, each group by name. + * + * The provider seam returns children in stable name order, which puts a + * subdirectory wherever the alphabet puts it; capping such a list can drop every + * subdirectory and leave the model believing a directory holds only files. This + * is the listing counterpart of the `glob` coverage footer. + * + * @param entries - the seam's direct children, in any order. + * @returns a new array in directory-first display order; the input is not mutated. + */ +export function orderEntries(entries: readonly T[]): T[] { + const rank = { directory: 0, file: 1, other: 2 } + return [...entries].sort((a, b) => rank[a.type] - rank[b.type] || a.name.localeCompare(b.name)) +} + +/** `1 directory` / `4 directories` — a count the model reads as prose, not as `1 directorie(s)`. */ +function count(n: number, singular: string, plural: string): string { + return `${n} ${n === 1 ? singular : plural}` +} + +/** The ` directories, files[, other]` breakdown; the `other` clause appears only when non-empty. */ +function breakdown(entries: readonly ListedEntry[]): string { + const directories = entries.filter(entry => entry.type === 'directory').length + const other = entries.filter(entry => entry.type === 'other').length + const files = entries.length - directories - other + const parts = [count(directories, 'directory', 'directories'), count(files, 'file', 'files')] + if (other > 0) parts.push(`${other} other`) + return parts.join(', ') +} + +/** + * Render the model-facing `list` result: the displayed entries, then a footer + * that always states the COMPLETE listing's size and composition, so a capped + * view can never read as the whole directory. + * + * Directories carry a trailing `/` and non-regular children a trailing `@`, so + * the model can tell what it may descend into without a second call. + * + * @param displayPath - the resolved directory as the backend displays it. + * @param entries - the complete listing, already in {@link orderEntries} order. + * @param maxEntries - how many entries to show inline; the rest are summarized by the footer. + * @returns the model-facing text. + */ +export function formatListOutput(displayPath: string, entries: readonly ListedEntry[], maxEntries: number): string { + const shown = entries.slice(0, maxEntries) + const suffix = { directory: '/', file: '', other: '@' } + const footer = shown.length < entries.length + ? `(Showing ${shown.length} of ${count(entries.length, 'entry', 'entries')}: ${breakdown(entries)}. ` + + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)' + : entries.length === 0 + ? '(Empty directory)' + : `(${count(entries.length, 'entry', 'entries')}: ${breakdown(entries)})` + const body = shown.length > 0 + ? `${shown.map(entry => `${entry.name}${suffix[entry.type]}`).join('\n')}\n\n${footer}` + : footer + return `${displayPath} +directory + +${body} +` +} diff --git a/packages/fs/tool-fs/src/list.ts b/packages/fs/tool-fs/src/list.ts new file mode 100644 index 0000000000..de6c6d1ddd --- /dev/null +++ b/packages/fs/tool-fs/src/list.ts @@ -0,0 +1,120 @@ +/** + * Model-facing directory listing. It enumerates ONE directory level through the + * provider seam's `listDir`, orders children so a capped view keeps the + * navigable structure, and renders the entries with their type. + * + * This is the orientation tool: `glob` and `grep` answer "where is the thing I + * can already name", while `list` answers "what is here at all". `rg --files` + * never emits directories, so no pattern makes `glob` describe a directory's + * shape — the gap this tool closes. + * @module @deepseek-ai/dsh-tool-fs/list + */ + +import type { Context } from 'cordis' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type { GenericCallView } from '@deepseek-ai/dsh-tools' +import type {} from '@deepseek-ai/dsh-fs' +import type {} from '@deepseek-ai/dsh-system-prompt' +import { formatListOutput, orderEntries } from './list-render.ts' +import { sessionResolveOptions } from './session-cwd.ts' + +/** Resolved list-tool caps — plugin config after defaulting (see `Config` in index.ts). */ +export interface ListToolCaps { + /** Maximum entries rendered inline; the footer still reports the complete listing's size. */ + maxEntries: number +} + +/** Validated `list` arguments after defaulting. */ +export interface ListInput { + /** Directory to list; `.` means the calling agent's session workspace. */ + path: string +} + +/** + * Validate value constraints the schema DSL can't express, and default an + * omitted `path` to `.` — the session workspace, so "what is in this project" + * needs no argument at all. + * + * @param args - the schema-validated `list` arguments. + * @returns the accepted input with `path` defaulted. + */ +export function parseListArgs(args: { path?: string }): ListInput { + if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given') + return { path: args.path ?? '.' } +} + +/** + * Pending-call presentation: a generic card titled by the directory, with a + * follow-along location so a capable editor can reveal it. + * + * @param args - the raw tool arguments; only `path` is read. + * @returns the generic card view shown while the call runs. + */ +export function presentListCall(args: { path?: string }): GenericCallView { + const path = args.path ?? '.' + return { card: 'generic', title: `List ${path}`, kind: 'read', locations: [{ path }] } +} + +/** + * Register the `list` tool and its system-prompt guidance. + * + * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service. + * @param caps - the deployment's resolved list caps (plugin config after defaulting). + */ +export function applyListTool(ctx: Context, caps: ListToolCaps): void { + ctx.systemPrompt.section({ + name: 'tool:list', + order: 99, + text: 'Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, ' + + 'and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. ' + + 'Reach for glob or grep once you know the path pattern or the text you are looking for.', + }) + + ctx.tools.register(defineTool({ + name: 'list', + description: 'List the direct children of one directory, with their type. ' + + `Entries are directories first, then files, each alphabetical; the first ${caps.maxEntries} are returned inline and the footer reports the complete count. ` + + 'Unlike glob, this shows subdirectories, so it is how to see what a directory contains.', + parameters: { + path: { type: 'string', description: 'Directory to list. Defaults to the session workspace; a relative path resolves against it.' }, + }, + output: { + schema: { + type: 'object', + additionalProperties: false, + properties: { + path: { type: 'string', required: true }, + entries: { + type: 'array', + required: true, + items: { + type: 'object', + additionalProperties: false, + properties: { + name: { type: 'string', required: true }, + type: { type: 'string', required: true, enum: ['file', 'directory', 'other'] }, + }, + }, + }, + }, + }, + render: (_args, value) => [{ type: 'text', text: formatListOutput(value.path, value.entries, caps.maxEntries) }], + }, + // Listing reads directory metadata only: no content, no version recorded, + // nothing a concurrent call could observe out of order. + isConcurrencySafe: () => true, + async execute(args, exec) { + const input = parseListArgs(args) + const target = await ctx.fs.resolve(input.path, sessionResolveOptions(exec, input.path)) + // No stat first: the seam already answers absence with FS_NOT_FOUND and a + // non-directory target with FS_NOT_DIRECTORY, so a probe would only add a + // round-trip and a second source of truth. (0 stat.) + const entries = await ctx.fs.listDir(target, exec.signal) + return { + path: target.displayPath, + entries: orderEntries(entries).map(({ name, type }) => ({ name, type })), + } + }, + presentCall: presentListCall, + })) +} diff --git a/packages/fs/tool-fs/tests/list-render.spec.ts b/packages/fs/tool-fs/tests/list-render.spec.ts new file mode 100644 index 0000000000..3d0a3ac5ce --- /dev/null +++ b/packages/fs/tool-fs/tests/list-render.spec.ts @@ -0,0 +1,69 @@ +/** + * Pure listing-presentation tests: display ordering and the model-facing + * envelope, exercised without a context or provider. + */ + +import { describe, expect, it } from 'vitest' +import { formatListOutput, orderEntries } from '../src/list-render.ts' +import type { ListedEntry } from '../src/list-render.ts' + +const entry = (name: string, type: ListedEntry['type'] = 'file'): ListedEntry => ({ name, type }) + +describe('orderEntries', () => { + it('groups directories, then files, then other, each by name', () => { + const ordered = orderEntries([ + entry('zeta.txt'), + entry('socket', 'other'), + entry('beta'), + entry('src', 'directory'), + entry('assets', 'directory'), + ]) + expect(ordered.map(e => e.name)).toEqual(['assets', 'src', 'beta', 'zeta.txt', 'socket']) + }) + + it('leaves the input array untouched and preserves extra entry fields', () => { + const input = [{ name: 'b', type: 'file' as const, size: 2 }, { name: 'a', type: 'file' as const, size: 1 }] + const ordered = orderEntries(input) + expect(input.map(e => e.name)).toEqual(['b', 'a']) + expect(ordered).toEqual([{ name: 'a', type: 'file', size: 1 }, { name: 'b', type: 'file', size: 2 }]) + }) +}) + +describe('formatListOutput', () => { + it('marks directories and non-regular children, and counts the whole listing', () => { + expect(formatListOutput('/w', [entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')], 10)).toBe(`/w +directory + +src/ +a.txt +sock@ + +(3 entries: 1 directory, 1 file, 1 other) +`) + }) + + it('omits the "other" clause when every child is a file or a directory', () => { + expect(formatListOutput('/w', [entry('a.txt'), entry('b.txt')], 10)).toContain('(2 entries: 0 directories, 2 files)') + }) + + it('says a one-entry listing in the singular', () => { + expect(formatListOutput('/w', [entry('only', 'directory')], 10)).toContain('(1 entry: 1 directory, 0 files)') + }) + + it('states the complete size and composition when the view is capped', () => { + const entries = [entry('src', 'directory'), ...Array.from({ length: 5 }, (_, i) => entry(`f${i}.txt`))] + const rendered = formatListOutput('/w', entries, 2) + expect(rendered).toContain('src/\nf0.txt\n') + expect(rendered).not.toContain('f2.txt') + expect(rendered).toContain('(Showing 2 of 6 entries: 1 directory, 5 files. ' + + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)') + }) + + it('renders an empty directory as a footer alone', () => { + expect(formatListOutput('/w', [], 10)).toBe(`/w +directory + +(Empty directory) +`) + }) +}) diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 8f93b524a9..66f88a6348 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -38,6 +38,7 @@ const testToolSignal = new AbortController().signal class FakeFs extends FileSystem { files = new Map() rejectWith?: FsError + dirs = new Map() writeIntents: (FsWriteIntent | undefined)[] = [] editIntents: ({ version: FsVersion } | undefined)[] = [] @@ -66,8 +67,9 @@ class FakeFs extends FileSystem { const content = this.files.get(target.targetKey) ?? '' return (async function* () { yield content })() } - override async listDir(_target: FsTarget): Promise { - return [] + override async listDir(target: FsTarget): Promise { + this.throwIfArmed() + return this.dirs.get(target.targetKey) ?? [] } override async writeText(target: FsTarget, content: string, expected?: FsWriteIntent): Promise { this.throwIfArmed() @@ -139,13 +141,15 @@ describe('session cwd resolution', () => { }) describe('registration', () => { - it('registers read, write, and edit', async () => { + it('registers list, read, write, and edit', async () => { const { ctx } = await setup() - expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['edit', 'read', 'write']) + expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['edit', 'list', 'read', 'write']) }) - it('declares read parallel-safe while write/edit remain exclusive', async () => { + it('declares list and read parallel-safe while write/edit remain exclusive', async () => { const { ctx } = await setup() + expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('list-safe'), name: 'list', arguments: {} })) + .toEqual({ kind: 'parallel' }) expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('read-safe'), name: 'read', arguments: { file_path: 'a.txt' } })) .toEqual({ kind: 'parallel' }) expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('write-exclusive'), name: 'write', arguments: { file_path: 'a.txt', content: 'x' } })) @@ -157,6 +161,7 @@ describe('registration', () => { it('registers prompt sections for each tool', async () => { const { ctx } = await setup() const prompt = renderPrompt(await ctx.systemPrompt.assemble()) + expect(prompt).toContain('Use the list tool') expect(prompt).toContain('Use the read tool') expect(prompt).toContain('Use the write tool') expect(prompt).toContain('Use the edit tool') @@ -179,9 +184,10 @@ describe('registration', () => { const fiber = await ctx.plugin(ToolFs) // Each tool contributes BOTH a schema and a prompt section; disposal must // withdraw both, not just the schemas. - expect(ctx.tools.schemas()).toHaveLength(3) + expect(ctx.tools.schemas()).toHaveLength(4) const sectionNames = (a: { sections: { name: string }[] }) => a.sections.map(s => s.name).sort() - expect(sectionNames(await ctx.systemPrompt.assemble())).toEqual(['deployment:persona', 'harness:identity', 'tool:edit', 'tool:read', 'tool:write']) + expect(sectionNames(await ctx.systemPrompt.assemble())) + .toEqual(['deployment:persona', 'harness:identity', 'tool:edit', 'tool:list', 'tool:read', 'tool:write']) await fiber.dispose() expect(ctx.tools.schemas()).toHaveLength(0) // Only the system-prompt plugin's own built-in sections remain. @@ -189,6 +195,107 @@ describe('registration', () => { }) }) +describe('list tool', () => { + /** Seed one directory's children; `listDir` order is deliberately NOT display order. */ + function seedDir(fs: FakeFs, path: string, children: readonly { name: string; type: 'file' | 'directory' | 'other' }[]): void { + fs.dirs.set(`key:${path}`, children.map(({ name, type }) => ({ + name, + type, + target: { targetKey: FsTargetKey(`key:${path}/${name}`), displayPath: `/abs/${path}/${name}` }, + }))) + } + + it('defaults to the session workspace and shows directories before files', async () => { + const { ctx, fs } = await setup() + seedDir(fs, '.', [ + { name: 'notes.md', type: 'file' }, + { name: 'zeroomega-3.3.23', type: 'directory' }, + { name: 'archive', type: 'directory' }, + { name: 'link-to-nowhere', type: 'other' }, + ]) + const result = await call(ctx, 'list', {}) + expect(result.isError).toBe(false) + if (result.isError) throw new Error('expected list success') + // The canonical value carries display order, so a Code Mode caller and the + // model see the same ordering contract. + expect(result.value).toEqual({ + path: '/abs/.', + entries: [ + { name: 'archive', type: 'directory' }, + { name: 'zeroomega-3.3.23', type: 'directory' }, + { name: 'notes.md', type: 'file' }, + { name: 'link-to-nowhere', type: 'other' }, + ], + }) + expect(text(result)).toBe(`/abs/. +directory + +archive/ +zeroomega-3.3.23/ +notes.md +link-to-nowhere@ + +(4 entries: 2 directories, 1 file, 1 other) +`) + }) + + it('lists an explicit path and reports an empty directory as such', async () => { + const { ctx, fs } = await setup() + seedDir(fs, 'empty', []) + const result = await call(ctx, 'list', { path: 'empty' }) + expect(text(result)).toContain('(Empty directory)') + expect(text(result)).toContain('/abs/empty') + }) + + it('caps the rendered entries but still reports the complete composition', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(FakeFs) + await ctx.plugin(ToolFs, { listMaxEntries: 2 }) + const fs = ctx.fs as FakeFs + seedDir(fs, '.', [ + { name: 'a.txt', type: 'file' }, + { name: 'b.txt', type: 'file' }, + { name: 'c.txt', type: 'file' }, + { name: 'src', type: 'directory' }, + ]) + const result = await call(ctx, 'list', {}) + const rendered = text(result) + // The one directory survives the cap because directories sort first — the + // failure mode this ordering exists to prevent. + expect(rendered).toContain('src/\na.txt\n') + expect(rendered).not.toContain('c.txt') + expect(rendered).toContain('(Showing 2 of 4 entries: 1 directory, 3 files. ' + + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)') + }) + + it('rejects a blank path and surfaces provider failures', async () => { + const { ctx, fs } = await setup() + const blank = await call(ctx, 'list', { path: ' ' }) + expect(blank.isError).toBe(true) + expect(text(blank)).toContain('path must be a non-empty string when given') + + fs.rejectWith = new FsError('cannot list "/abs/a.txt": not a directory', 'FS_NOT_DIRECTORY') + const failed = await call(ctx, 'list', { path: 'a.txt' }) + expect(failed.isError).toBe(true) + expect(failed.error).toMatchObject({ info: { code: 'FS_NOT_DIRECTORY' } }) + }) + + it('records no observation, so a listing never authorizes a mutation', async () => { + const { ctx, fs } = await setup() + fs.files.set('key:a.txt', 'hello') + seedDir(fs, '.', [{ name: 'a.txt', type: 'file' }]) + const observed = vi.fn() + ctx.on('fs/observed', observed) + await call(ctx, 'list', {}) + expect(observed).not.toHaveBeenCalled() + // Seeing a name is not reading a file: the policy gate still demands a read. + const edit = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'h', new_string: 'j' }, { session: { header: {} } }) + expect(edit.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } }) + }) +}) + describe('read tool', () => { it('formats line-numbered content with a footer', async () => { const { ctx, fs } = await setup() @@ -439,6 +546,15 @@ describe('tool-owned presentation (pure presentCall)', () => { }) }) + it('list: titles by the directory, falling back to the workspace "." when unset', async () => { + expect(await presentCall('list', { path: 'src' })).toEqual({ + card: 'generic', title: 'List src', kind: 'read', locations: [{ path: 'src' }], + }) + expect(await presentCall('list', {})).toEqual({ + card: 'generic', title: 'List .', kind: 'read', locations: [{ path: '.' }], + }) + }) + it('read: bare title and line-1 location when offset/limit are unset', async () => { expect(await presentCall('read', { file_path: 'a.txt' })).toEqual({ card: 'generic', title: 'Read a.txt', kind: 'read', locations: [{ path: 'a.txt', line: 1 }], @@ -621,6 +737,7 @@ describe('read caps are plugin config', () => { }) it.each([ + ['listMaxEntries', { listMaxEntries: 0 }], ['readLimit', { readLimit: 0 }], ['readLimit', { readLimit: 2.5 }], ['readMaxLineLength', { readMaxLineLength: -1 }], diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 3103b9878c..f25084917e 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -230,7 +230,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFs) }, note: - '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.', + '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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate.', }, { pkg: '@deepseek-ai/dsh-tool-fs-search', From 9b9b45e65efc383c84b92f2607aad4cc891601ec Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 12:05:36 +0800 Subject: [PATCH 02/67] fix(fs-search): sample an over-cap glob result across the tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Asked what a workspace contained, an agent described one subfolder as the whole project. `glob {"pattern": "*"}` matched 10030 paths across 22 top-level entries and the inline page was the first 100 of them, all under a single unpacked archive. Three properties compose into that page: a pattern with no `/` matches basenames at any depth, so `*` means the whole tree rather than its top level; `--sort=modified` orders oldest first, and unpacking an archive restores timestamps that predate everything the user wrote; and the page was the head of that order. Each is defensible alone, and together they make the most ordinary request an agent receives produce a confident wrong answer. A result within `globMaxResults` is unchanged — shown whole, in modification-time order. Beyond it the page is filled round-robin across the complete result's top-level entries, so one subtree cannot own every slot, and the footer states that the page was sampled rather than taken in modification-time order. Measured on a 24-entry, 716-file reproduction, the head of 100 reaches 7 top-level names and the sampled page reaches 21. The spill artifact still holds the complete sorted list. The guidance and schema stop steering away from `ls`, state the any-depth pattern rule, say results are files and never directories, and point at `list` for a directory's contents. --- docs/tool-catalog.md | 8 +- packages/fs/tool-fs-search/README.i18n.yaml | 6 +- packages/fs/tool-fs-search/README.md | 9 +- packages/fs/tool-fs-search/README.zh.md | 9 +- packages/fs/tool-fs-search/src/glob.ts | 138 +++++++++++++++--- packages/fs/tool-fs-search/src/index.ts | 4 +- .../fs/tool-fs-search/tests/tools.spec.ts | 70 +++++++++ scripts/gen-tool-catalog.ts | 2 +- 8 files changed, 208 insertions(+), 38 deletions(-) diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 6edd5be644..0884910bde 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -21,7 +21,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. | | `@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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `list`, `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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. | -| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. | +| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. | | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. | | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `user/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. | | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. | @@ -395,7 +395,7 @@ The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an ` ### `glob` -Find files whose paths match a glob pattern. Returns matching paths sorted by modification time, including hidden and ignored files (VCS metadata directories are excluded). Returns the first 100 paths inline; a capped result reports where the complete list was saved. +Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 100 paths come back in modification-time order; a larger result instead returns 100 paths sampled across top-level directories, says so, and reports where the complete sorted list was saved. To see what a directory contains, use the list tool instead. ```json { @@ -403,7 +403,7 @@ Find files whose paths match a glob pattern. Returns matching paths sorted by mo "properties": { "pattern": { "type": "string", - "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\")." + "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth." }, "path": { "type": "string", @@ -447,7 +447,7 @@ Search file contents with a ripgrep regular expression. Returns matching lines w Source: [`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts) -glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. +glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. ## `@deepseek-ai/dsh-tool-pty` diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml index 07aaa3c9dc..ec8f6f8968 100644 --- a/packages/fs/tool-fs-search/README.i18n.yaml +++ b/packages/fs/tool-fs-search/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write -README.md: 88a80fb51d7161e6940a3460b7f506575592f9cb -README.zh.md: 87be92bb5a8e06dfc275aa6a1fcf97274a761025 +# pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md +README.md: 33792a6f4b72baa2626c6e8d37c672fb39681554 +README.zh.md: 5d13a7ff2cb3ddfda8168a34e4a4a897d3413e11 diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md index 88a80fb51d..33792a6f4b 100644 --- a/packages/fs/tool-fs-search/README.md +++ b/packages/fs/tool-fs-search/README.md @@ -24,7 +24,7 @@ All keys are optional; the defaults are the shipped search caps. | Key | Default | Meaning | |---|---|---| -| `globMaxResults` | `100` | Max paths one `glob` call retains inline (matches Claude Code's `GlobTool` limit); later paths go to the formatted spill artifact. | +| `globMaxResults` | `100` | Max paths one `glob` call shows inline (matches Claude Code's `GlobTool` limit). Within it the result is shown whole in modification-time order; beyond it the inline page is sampled across top-level entries and the complete sorted list goes to the formatted spill artifact. | | `grepMaxMatches` | `250` | Max flat matches one `grep` call retains inline (matches Claude Code's `GrepTool` `head_limit`); later matches go to the formatted spill artifact. | | `grepMaxLineBytes` | `2000` | Byte cap per matched-line preview; the cut preserves UTF-8 boundaries and is marked `(line truncated)`. | | `rawOutputMaxBytes` | `20000000` | Max complete raw `rg` stdout a search will parse (matches Claude Code's ripgrep raw buffer); larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. | @@ -34,7 +34,7 @@ All keys are optional; the defaults are the shipped search caps. | Tool | Arguments | Behavior | |---|---|---| -| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one path per line, modification-time ordered. | +| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line, modification-time ordered — `rg --files` never emits a directory, so no pattern makes `glob` describe a directory's contents; that is [`dsh-tool-fs`](../tool-fs/)'s `list`. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. | | `grep` | `pattern`, `path?`, `include?` | Line-oriented `rg --json` parse (no colon-splitting ambiguity). `pattern` is a ripgrep regex; `path` is an optional **file or directory** target; `include` is ONE positive glob filter — a comma-separated list or a negated (`!…`) value is rejected up front (brace alternation like `*.{ts,tsx}` is fine). Returns matches grouped by file as `Line N: `. | Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`case_insensitive`/output modes): a model that needs surrounding context reads the matched file with `read`; one that needs later results follows the returned spill locator's retrieval hint. @@ -58,7 +58,7 @@ After the load-time `rg` probe succeeds, every request in this plugin's registra ##### Glob guidance ```markdown -Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files. +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, so it spans the tree instead of one subtree. Use the list tool to see what a directory contains. ``` ##### Grep guidance @@ -93,7 +93,7 @@ Prefix-stable while tool visibility and definitions are unchanged. Registration #### What the model sees -`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. +`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. An over-cap `glob` result does not show the head of the sorted list: its inline page takes paths round-robin across the complete result's top-level entries, so one recently-written subtree cannot own every slot, and the footer says the page was sampled rather than taken in modification-time order, together with how many top-level entries it reached. When it could not reach them all, the footer also points at `list`. A result that fits inline is untouched, and a flat result — every path its own top-level entry — keeps the plain footer, because there the sample IS the recency-ordered head. The spill artifact always holds the complete list in modification-time order. #### Token effect @@ -122,3 +122,4 @@ Append-only; newly visible content follows the reusable request prefix and does - **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation. - **Ripgrep is a deployment dependency** — a missing `rg` executable makes the package register no tools or guidance; an incompatible executable or one that disappears after registration fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located executor or another search consumer. - **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend. +- **Sampling groups by first path segment only** — an over-cap `glob` page balances across top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred. diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md index 87be92bb5a..5d13a7ff2c 100644 --- a/packages/fs/tool-fs-search/README.zh.md +++ b/packages/fs/tool-fs-search/README.zh.md @@ -24,7 +24,7 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- | 键 | 默认值 | 含义 | |---|---|---| -| `globMaxResults` | `100` | 一次 `glob` 调用内联保留的最大路径数（与 Claude Code 的 `GlobTool` 上限相同）；后续路径写入格式化 spill 产物。 | +| `globMaxResults` | `100` | 一次 `glob` 调用内联展示的最大路径数（与 Claude Code 的 `GlobTool` 上限相同）。未超过时结果整体按修改时间展示；超过时内联页面改为跨顶层条目取样，完整的排序列表写入格式化 spill 产物。 | | `grepMaxMatches` | `250` | 一次 `grep` 调用内联保留的最大平铺匹配数（与 Claude Code 的 `GrepTool` `head_limit` 相同）；后续匹配写入格式化 spill 产物。 | | `grepMaxLineBytes` | `2000` | 每条匹配行预览的字节上限；截断会保留 UTF-8 边界，并标记为 `(line truncated)`。 | | `rawOutputMaxBytes` | `20000000` | 搜索将解析的完整原始 `rg` stdout 上限（与 Claude Code 的 ripgrep 原始 buffer 相同）；更大的原始输出以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败。 | @@ -34,7 +34,7 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- | 工具 | 参数 | 行为 | |---|---|---| -| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录** 搜索根；省略时使用解析后的 bash 工作目录。每行返回一个路径，按修改时间排序。 | +| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录** 搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件** 路径；`rg --files` 从不输出目录条目，因此任何 pattern 都无法让 `glob` 描述一个目录的内容，那是 [`dsh-tool-fs`](../tool-fs/) 的 `list`。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。未超过 `globMaxResults` 的结果按修改时间排序；超过时内联页面改为跨顶层条目取样（见下）。 | | `grep` | `pattern`、`path?`、`include?` | 按行解析 `rg --json`，避免按冒号拆分的歧义。`pattern` 是 ripgrep 正则表达式；`path` 是可选的**文件或目录** 目标；`include` 是一个正向 glob 过滤器，前置拒绝逗号分隔列表或否定值（`!…`），但允许 `*.{ts,tsx}` 等花括号交替。返回按文件分组、形如 `Line N: ` 的匹配。 | 常规预算不进入面向模型的 schema（没有 `head_limit`/`offset`/`case_insensitive`/输出模式）：模型需要周边上下文时，用 `read` 读取匹配文件；需要后续结果时，遵循返回的 spill locator 检索提示。 @@ -58,7 +58,7 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- ##### Glob 指导 ```markdown -Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files. +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, so it spans the tree instead of one subtree. Use the list tool to see what a directory contains. ``` ##### Grep 指导 @@ -93,7 +93,7 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read #### 模型看到的内容 -`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。 +`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。超过上限的 `glob` 结果不再展示排序列表的头部：其内联页面按轮转方式跨完整结果的顶层条目取样，因此单个新近写入的子树无法占满所有位置；footer 会说明该页面是取样得到而非按修改时间取用，并给出它触达了多少个顶层条目。未能触达全部时，footer 还会指向 `list`。未超过上限的结果原样不动；扁平结果（每个路径各自构成一个顶层条目）保留朴素 footer，因为此时取样结果就等于按新近度排序的头部。spill 产物始终保存按修改时间排序的完整列表。 #### Token 影响 @@ -122,3 +122,4 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read - **搜索和文件访问没有共享工作区证明**：只有 bash 工作目录和文件系统根目录表示同一工作区时，返回路径才能继续读取；本包不执行运行时跨服务校验。 - **Ripgrep 是部署依赖**：缺失 `rg` 可执行文件时，本包不注册工具或指导；可执行文件不兼容或注册后消失时，调用以 `SEARCH_FAILED` 失败。远程或虚拟文件系统需要共置执行器或其他搜索消费方。 - **schema 只公开一个有界页面**：offset 分页、大小写模式开关、其他输出模式和提供方支持的发现均不在本包内；达到上限的完整输出需要 spill 后端。 +- **取样只按路径首段分组**：超过上限的 `glob` 页面在顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。 diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index 6d42acee66..d46b1d352d 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -3,17 +3,21 @@ * pattern, sorted by modification time. Execution goes through the bash seam * (`ctx.bash`) with a fixed `rg --files` command — this module owns the * model-facing schema, argument validation, shell-safe command construction, - * result parsing, retention, and formatting; process concerns (defaulting, + * result parsing, inline sampling, and formatting; process concerns (defaulting, * scrubbing, kill, backend substitution) stay behind `ctx.bash`. * + * A complete result keeps ripgrep's modification-time order. A result too large + * to show inline does NOT: its inline page is sampled across the complete + * result's top-level entries ({@link sampleAcrossTopLevel}), because the sorted + * head of a broad match is routinely one subtree's worth of files and reads as + * if the workspace held nothing else. + * * @module @deepseek-ai/dsh-tool-fs-search/glob */ import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' import type { GenericCallView } from '@deepseek-ai/dsh-tools' -import { ItemRetainer } from '@deepseek-ai/dsh-retention' -import type { RetainedItems } from '@deepseek-ai/dsh-retention' import type { SpillRef } from '@deepseek-ai/dsh-spill' import type {} from '@deepseek-ai/dsh-bash' import type {} from '@deepseek-ai/dsh-system-prompt' @@ -99,30 +103,116 @@ export function buildGlobCommand(input: GlobInput): string { } /** - * Format the model-facing `glob` result: the retained paths, then — when the - * result was capped — a footer carrying either the formatted-spill recovery - * locator or the could-not-save explanation. The omitted count is a budget fact: - * the search itself completed. + * The inline page of a capped `glob` result, plus how much of the complete + * result's top level it reaches. + */ +export interface GlobSample { + /** Paths to show inline: grouped by top-level entry, recency-ordered within each group. */ + items: string[] + /** Distinct top-level entries the shown paths reach. */ + shown: number + /** Distinct top-level entries across the complete result. */ + total: number +} + +/** + * The leading path segment of one display path — the top-level entry, relative + * to the search root, that the path sits under. A path with no separator is its + * own top-level entry. Leading separators are stripped first so an absolute path + * (one outside the workdir, which {@link toWorkdirRelative} leaves untouched) + * groups by its first real name instead of collapsing every such path into one + * empty group. + */ +function topLevelSegment(path: string): string { + const trimmed = path.replace(/^[\\/]+/, '') + const cut = trimmed.search(/[\\/]/) + return cut === -1 ? trimmed : trimmed.slice(0, cut) +} + +/** + * Choose the inline page of an over-cap result by round-robin across the + * complete result's top-level entries, instead of taking its head. * - * @param retained - the retention outcome over every discovered path. + * `--sort=modified` (oldest first) is the right order for a complete result and + * the wrong basis for a sample of one: a broad pattern in a workspace holding one + * unpacked archive — whose restored timestamps predate everything the user + * wrote — gives a head that is entirely that subtree, and the model reads the + * page as the workspace. Round-robin gives every top-level entry a slot before + * any entry gets a second, so the page spans the tree; an entry that runs out of + * paths drops out and its remaining slots go to the rest. + * + * Modification-time order survives where it still means something: groups are + * visited in the order ripgrep first emits them, and each group's own paths keep + * their relative order. With one path per group — a flat result — this + * reproduces the sorted head exactly, so nothing changes for a result that has + * no subtree to hide. + * + * @param paths - the complete result, in ripgrep's modification-time order. + * @param maxItems - how many paths the page may hold; the caller has already established it is smaller than `paths`. + * @returns the page grouped by top-level entry, with the shown/total top-level spread. + */ +export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number): GlobSample { + const groups = new Map() + for (const path of paths) { + const group = groups.get(topLevelSegment(path)) + if (group === undefined) groups.set(topLevelSegment(path), [path]) + else group.push(path) + } + // Bounding the rounds by the largest group makes termination structural: the + // page can only fill or the groups run out, never spin on empty rounds. + const rounds = Math.max(0, ...[...groups.values()].map(group => group.length)) + const taken = new Map() + let count = 0 + for (let round = 0; round < rounds && count < maxItems; round += 1) { + for (const [key, group] of groups) { + if (count >= maxItems) break + const path = group[round] + if (path === undefined) continue + count += 1 + const bucket = taken.get(key) + if (bucket === undefined) taken.set(key, [path]) + else bucket.push(path) + } + } + return { items: [...taken.values()].flat(), shown: taken.size, total: groups.size } +} + +/** + * Format a CAPPED `glob` result: the inline page, then a footer stating that + * the page is a cross-directory sample rather than the most recent paths, how + * much of the top level it reaches, and either the formatted-spill recovery + * locator or the could-not-save explanation. The omitted count is a budget + * fact: the search itself completed. A result that fits inline never reaches + * here — it is emitted verbatim, in ripgrep's order. + * + * A result whose every path is its own top-level entry keeps the plain footer: + * the sample is the recency-ordered head, and naming a spread would only + * restate the path counts already there. + * + * @param sample - the inline page and its top-level spread. + * @param seen - how many paths the complete result holds; always more than the page. * @param spillRef - the saved complete-result reference, or `undefined` when unsaved. * @returns the model-facing text. */ -export function formatGlobOutput(retained: RetainedItems, spillRef: SpillRef | undefined): string { - const body = retained.items.join('\n') - if (!retained.truncated) return body +export function formatGlobOutput(sample: GlobSample, seen: number, spillRef: SpillRef | undefined): string { + const body = sample.items.join('\n') const recovery = spillRef !== undefined ? `Full sorted result stored at: ${spillRef.locator}. ${spillRef.retrievalHint}` : 'The complete result could not be saved; narrow pattern or path to see more.' - return `${body}\n\n(Showing ${retained.kept} of ${retained.seen} paths. ${recovery})` + const basis = sample.total === seen + ? '.' + : `, sampled across ${sample.shown} of the ${sample.total} top-level entries this pattern matched instead of taken in modification-time order.` + + (sample.shown < sample.total ? ' Use the list tool to see what a directory contains.' : '') + return `${body}\n\n(Showing ${sample.items.length} of ${seen} paths${basis} ${recovery})` } -/** Retain and format one canonical path list for the Native surface. */ +/** Bound and format one canonical path list for the Native surface. */ function renderGlobPaths(paths: string[], maxResults: number, spillRef?: SpillRef): string { if (paths.length === 0) return 'No files found' - const retainer = new ItemRetainer({ kind: 'head', maxItems: maxResults }) - for (const path of paths) retainer.push(path) - return formatGlobOutput(retainer.finish(), spillRef) + // A result that fits is shown whole, untouched: modification-time order is the + // tool's contract, and over a complete result it is what answers age questions. + if (paths.length <= maxResults) return paths.join('\n') + return formatGlobOutput(sampleAcrossTopLevel(paths, maxResults), paths.length, spillRef) } /** @@ -147,16 +237,24 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { ctx.systemPrompt.section({ name: 'tool:glob', order: 103, - text: 'Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files.', + text: 'Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. ' + + 'Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, ' + + 'so it spans the tree instead of one subtree. Use the list tool to see what a directory contains.', }) const tool = defineTool({ name: 'glob', - description: 'Find files whose paths match a glob pattern. Returns matching paths sorted by modification time, ' + description: 'Find files whose paths match a glob pattern. Returns matching file paths — never directories — ' + 'including hidden and ignored files (VCS metadata directories are excluded). ' - + `Returns the first ${caps.maxResults} paths inline; a capped result reports where the complete list was saved.`, + + `Up to ${caps.maxResults} paths come back in modification-time order; a larger result instead returns ${caps.maxResults} paths sampled across top-level directories, ` + + 'says so, and reports where the complete sorted list was saved. To see what a directory contains, use the list tool instead.', parameters: { - pattern: { type: 'string', required: true, description: 'Glob pattern to match file paths against (e.g. "**/*.ts", "src/**/*.test.js").' }, + pattern: { + type: 'string', + required: true, + description: 'Glob pattern to match file paths against (e.g. "**/*.ts", "src/**/*.test.js"). ' + + 'A pattern with no "/" matches the basename at any depth, so "*" and "*.ts" both search the whole tree; include a separator to anchor the depth.', + }, path: { type: 'string', description: 'Directory to search in. Defaults to the session workspace; a relative path resolves against it.' }, }, timeoutMs: caps.timeoutMs, diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts index 5930890b7a..b6ae6ebbad 100644 --- a/packages/fs/tool-fs-search/src/index.ts +++ b/packages/fs/tool-fs-search/src/index.ts @@ -33,8 +33,8 @@ import { GLOB_MAX_RESULTS, applyGlobTool } from './glob.ts' import { GREP_MAX_LINE_BYTES, GREP_MAX_MATCHES, applyGrepTool } from './grep.ts' import { RAW_OUTPUT_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts' -export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall } from './glob.ts' -export type { GlobInput, GlobToolCaps } from './glob.ts' +export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall, sampleAcrossTopLevel } from './glob.ts' +export type { GlobInput, GlobSample, GlobToolCaps } from './glob.ts' export { GREP_MAX_LINE_BYTES, GREP_MAX_MATCHES, diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 1951d97a8d..0bbe0e0bf5 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -29,6 +29,7 @@ import { presentGlobCall, presentGrepCall, previewLine, + sampleAcrossTopLevel, toWorkdirRelative, } from '@deepseek-ai/dsh-tool-fs-search' @@ -498,6 +499,38 @@ describe('raw output acquisition', () => { }) }) +describe('cross-directory sampling', () => { + it('gives every top-level entry a slot before any entry gets a second', () => { + const paths = ['v/a', 'v/b', 'v/c', 'v/d', 'src/e', 'guide/f'] + // The head of 3 would be all `v/`; the sample reaches all three entries. + expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['v/a', 'src/e', 'guide/f'], shown: 3, total: 3 }) + // Extra slots go round again — to the only entry with paths left — and the + // page stays grouped by entry rather than interleaved. + expect(sampleAcrossTopLevel(paths, 5)).toEqual({ items: ['v/a', 'v/b', 'v/c', 'src/e', 'guide/f'], shown: 3, total: 3 }) + }) + + it('hands an exhausted entry the remaining slots go to entries that still have paths', () => { + const paths = ['solo/a', 'many/b', 'many/c', 'many/d'] + expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['solo/a', 'many/b', 'many/c'], shown: 2, total: 2 }) + }) + + it('reports the entries it could not reach when the page is smaller than the top level', () => { + const paths = ['a/1', 'b/1', 'c/1', 'd/1'] + expect(sampleAcrossTopLevel(paths, 2)).toEqual({ items: ['a/1', 'b/1'], shown: 2, total: 4 }) + }) + + it('groups an absolute path by its first real name, not by its empty root segment', () => { + // Paths outside the workdir stay absolute; without stripping the leading + // separator every one of them would collapse into a single empty group. + expect(sampleAcrossTopLevel(['/out/a', '/out/b', '/away/c', '/away/d'], 2)) + .toEqual({ items: ['/out/a', '/away/c'], shown: 2, total: 2 }) + }) + + it('reproduces the recency-ordered head for a flat result', () => { + expect(sampleAcrossTopLevel(['a.ts', 'b.ts', 'c.ts'], 2)).toEqual({ items: ['a.ts', 'b.ts'], shown: 2, total: 3 }) + }) +}) + describe('glob results', () => { it('lists workdir-relative paths (absolute output under the workdir is relativized)', async () => { const { ctx, bash } = await setup() @@ -545,6 +578,43 @@ describe('glob results', () => { expect(result.additionalContexts?.[0]?.content).toEqual([{ type: 'text', text: 'glob context' }]) }) + it('samples an over-cap result across top-level entries instead of taking its head', async () => { + // The shipped failure: `*` matches the whole tree, mtime order puts one + // freshly-unpacked subtree first, and a head-of-3 reads like the entire + // workspace. The sample reaches every top-level entry instead. + const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) + bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md', 'top.txt'].join('\n')) + const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }) + expect(text(result)).toBe('vendor/a.ts\nsrc/d.ts\nguide/e.md\n\n' + + '(Showing 3 of 6 paths, sampled across 3 of the 4 top-level entries this pattern matched ' + + 'instead of taken in modification-time order. Use the list tool to see what a directory contains. ' + + 'The complete result could not be saved; narrow pattern or path to see more.)') + }) + + it('drops the list hint when the sample does reach every top-level entry', async () => { + const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) + bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts'].join('\n')) + expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) + .toBe('vendor/a.ts\nvendor/b.ts\nsrc/d.ts\n\n' + + '(Showing 3 of 4 paths, sampled across 2 of the 2 top-level entries this pattern matched ' + + 'instead of taken in modification-time order. ' + + 'The complete result could not be saved; narrow pattern or path to see more.)') + }) + + it('keeps modification-time order untouched when the whole result fits', async () => { + const { ctx, bash } = await setup({ config: { globMaxResults: 4 } }) + bash.handler = () => runResult('vendor/a.ts\nvendor/b.ts\nsrc/c.ts\n') + expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) + .toBe('vendor/a.ts\nvendor/b.ts\nsrc/c.ts') + }) + + it('keeps the plain footer for a flat result, where the sample IS the recency head', async () => { + const { ctx, bash } = await setup({ config: { globMaxResults: 2 } }) + bash.handler = () => runResult('a.ts\nb.ts\nc.ts\n') + expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) + .toBe('a.ts\nb.ts\n\n(Showing 2 of 3 paths. The complete result could not be saved; narrow pattern or path to see more.)') + }) + it('does not create a spill file when the result fits inline', async () => { const { ctx, bash, spill } = await setup({ spill: true }) bash.handler = () => runResult('a.ts\nb.ts\n') diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index f25084917e..8ac6dd247b 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -248,7 +248,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFsSearch) }, note: - 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.', + 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match.', }, { pkg: '@deepseek-ai/dsh-tool-pty', From a9c0e006202d09307a76a5ecd6e47ddfc85aba34 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 12:06:25 +0800 Subject: [PATCH 03/67] docs: record the directory-listing and glob-sampling decision Agent Note for the two changes: what the session log showed, what ordering can and cannot fix (measured, correcting the first diagnosis), why the page is sampled only past the cap, why `list` is needed alongside it, and the alternatives each one beat. --- ...026-07-27-directory-listing-tool.i18n.yaml | 6 + .../2026-07-27-directory-listing-tool.md | 110 ++++++++++++++++++ .../2026-07-27-directory-listing-tool.zh.md | 110 ++++++++++++++++++ 3 files changed, 226 insertions(+) create mode 100644 .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md create mode 100644 .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml new file mode 100644 index 0000000000..27a498cb46 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md +2026-07-27-directory-listing-tool.md: 4292c173f07064ff8825462e08096780c20ad9d6 +2026-07-27-directory-listing-tool.zh.md: 4033254b08a77ba7ed9b1f3e638213f019abb692 diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md new file mode 100644 index 0000000000..4292c173f0 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md @@ -0,0 +1,110 @@ +# Agent Note: Sample over-cap glob results across the tree, and give the model a directory-listing tool + +Status: implemented + +English | [中文](2026-07-27-directory-listing-tool.zh.md) + +## Problem + +Asked what a workspace contained, an agent described one subfolder as if it were the whole project. + +The session log shows exactly how. The workspace held 22 top-level entries and 11,485 files. The model called `glob {"pattern": "*"}`, which matched 10,030 paths; the tool showed the first 100, and all 100 sat under a single recently-unpacked subdirectory holding 355 of those files. The model never saw the other 21 top-level entries and answered from the one it did see. The session cwd was correct throughout — nothing was misconfigured, and every number the tool printed was true. + +Three properties of `glob` compose into that page: + +- **A pattern with no `/` matches at any depth.** The pattern goes to ripgrep as `--glob=`, where a glob without a separator matches the basename anywhere in the tree. `*` therefore means "every file in the workspace", not "the top level" — the opposite of what it means in a shell. The tool said nothing about this, and every example in its schema was `**/…`, so nothing suggested the plain form was recursive. +- **`--sort=modified` orders oldest first.** Unpacking an archive restores the timestamps stored inside it, which predate everything the user wrote, so a freshly unpacked subtree lands at the very front of any broad match. (Ripgrep sorts ascending; `--sortr` is the descending form and is not used here.) +- **The inline page was the head of that order.** `globMaxResults` (100) paths were kept from the front. Under the first two properties, one subtree takes every slot. + +Each property is defensible alone. Together they make the most ordinary request an agent receives — "what is in this directory" — reliably produce a confident wrong answer, because nothing in the result distinguishes "the 100 newest files in this workspace" from "this workspace". + +### What ordering can and cannot fix + +A directory's name reaches the model only as the prefix of one of its files' paths, since `rg --files` emits files and never directory entries. That is enough for ordering to matter a great deal, and not enough for `glob` to answer the question. + +Measured on a reproduction of the failure's shape — 24 top-level entries, 716 files, one recently-written subtree: + +| First 100 paths chosen by | Distinct top-level names visible | +| --- | --- | +| modification time, oldest first (the shipped behavior) | 7 | +| round-robin across top-level entries | 21 | + +So a differently chosen page does surface most of the missing names, and the original diagnosis that ordering could not have helped was wrong. What no ordering fixes: an entry with no files beneath it never appears at all (the reproduction's empty directory is absent from the complete 716-path output), and nothing in the output says which names are directories or how many entries a directory holds. `glob` can therefore convey a tree's rough shape; it cannot state a directory's contents. + +## Decision + +Two changes, in the two packages that own the two halves of the failure. + +### The inline page of an over-cap `glob` result is sampled, not taken from the head + +`@deepseek-ai/dsh-tool-fs-search`. A result within `globMaxResults` is unchanged: shown whole, in modification-time order. Only when the result is larger does the page change — and there, taking the head is what fails. + +`sampleAcrossTopLevel` groups the complete result by leading path segment and fills the page round-robin: every top-level entry gets a slot before any entry gets a second, and an entry that runs out of paths drops out so its remaining slots go to the rest. Sort order survives where it still carries meaning — groups are visited in the order ripgrep first emits them, and each group's own paths keep their relative order. The page is emitted grouped by entry rather than interleaved, so the breadth is legible at a glance. + +The footer states the basis, because a page that silently stopped being "the newest N" would be a second, quieter version of the same lie: + +``` +(Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched +instead of taken in modification-time order. Full sorted result stored at: …) +``` + +When the page cannot reach every top-level entry — more entries than slots — the footer says so with the shown/total spread and points at `list`. A flat result, where every path is its own top-level entry, keeps the plain `(Showing k of n paths. …)` footer: there the round-robin *is* the sorted head, and naming a spread would only restate the counts. The spill artifact always holds the complete list in modification-time order, so the sorted view is never lost. + +The guidance and schema stop misleading in the same change: "not shell find or ls" becomes "not shell find"; both now state that a pattern without `/` matches basenames at any depth, that results are files and never directories, that a fitting result is modification-time ordered while a larger one is sampled, and that `list` is the tool for a directory's contents. + +### `list`, in `@deepseek-ai/dsh-tool-fs` + +A fourth model-facing filesystem tool over the existing `ctx.fs.listDir` primitive, which until now shipped with skill discovery as its only consumer; [the seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) deferred the model-facing consumer to a separate decision, which this is. + +It takes an optional `path` — defaulting to `.`, the calling agent's session workspace, so the common question needs no argument — and returns the direct children of one directory as `{ path, entries: [{ name, type }] }`, where `type` is `file`, `directory`, or `other`. It calls `listDir` and nothing else: the seam already reports absence as `FS_NOT_FOUND` and a non-directory target as `FS_NOT_DIRECTORY`, so a preceding `stat` would add a round-trip and a second source of truth. + +Two presentation rules carry the decision: + +- **Directories sort first, then files, then non-regular children, each alphabetically** — in the canonical value as well as the rendered text, so a Code Mode caller and the model see one ordering contract. The seam returns stable name order, which scatters subdirectories through the alphabet; capping such a list can drop every subdirectory and reproduce, inside `list`, the same blindness. Directory-first ordering makes truncation lose leaves, never structure. +- **The footer always states the complete listing's size and composition** — `(22 entries: 18 directories, 4 files)`, and when the view is capped at `listMaxEntries` (default 200, configurable), `(Showing 200 of 5000 entries: 12 directories, 4988 files. …)`. A partial listing therefore cannot read as a whole directory. + +Directory entries render with a trailing `/` and non-regular children with `@`, so the model can tell what it may descend into without a second call. + +`list` emits no `fs/observed`. Seeing a filename is not reading a file, and a listing must never satisfy the read-before-write gate that `@deepseek-ai/dsh-fs-policy` enforces. It declares `isConcurrencySafe`, because it mutates nothing at all. + +### Why both + +They answer different questions and neither substitutes for the other. `list` answers "what is here" exactly — entry names, their types, the complete count — which `glob` cannot do at any ordering. Sampling fixes the page a broad `glob` returns for every *other* question, which stays wrong even once a better tool exists, because the model has no reason to abandon a page that looks representative. + +## Alternatives considered + +**Leave `glob` ordering alone and only warn in the footer.** This is what the first implementation did: keep the recency head and add a clause saying the head covered 1 of 22 top-level entries. Rejected once measured. A warning asks the model to distrust the only data it has and go elsewhere; a better page just is not wrong. The warning also does nothing for a model that stops reading at the paths, which is the failure being fixed. + +**Sample always, replacing modification-time order outright.** Rejected. Over a complete result the order answers age questions — what is stale, what was touched last — a genuinely useful and separate purpose, and a complete result is the case where the order costs nothing and means everything. Sampling only past the cap is the point where the order has already stopped describing the result: the head of a 10,030-path list is not "the oldest files worth knowing about", it is an arbitrary 1% of them. + +**Sample by a skew threshold — head unless the head is badly concentrated.** Rejected. A threshold is a deployment-varying tunable with no evidence behind any value, and it makes the result's ordering contract conditional on data the model cannot see. "Over the cap" is a boundary the model already knows about from the footer. + +**Balance recursively, not just at the top level.** Deferred, and recorded as a Known Limitation. Top-level balance fixes the observed failure and is explainable in one sentence of tool description; per-level balancing needs a policy for how depth trades against breadth, which no current evidence settles. + +**Reject `*`, or silently rewrite it to a top-level-anchored pattern.** Rejected. The same basename-at-any-depth rule that makes `*` recursive is what makes `*.ts` mean "every TypeScript file", the overwhelmingly common and correct use; anchoring one and not the other is an arbitrary special case, and rejecting a pattern ripgrep accepts turns a working call into an error. Documenting the rule costs nothing and generalizes. + +**Add `list` without touching `glob`.** Rejected, for the reason stated under *Why both* above. The misleading page is reachable from any broad pattern, and a model that believes its sample is representative has no reason to reach for another tool. + +**Fix `glob` without adding `list`.** Rejected for the same reason in reverse. A sampled page shows most top-level *names*, but not which are directories, not the empty ones, and not the entry count; "what is in this directory" deserves a tool that answers it rather than a sample the model must infer from. + +**Report per-directory child counts in `list`.** Rejected. Counting each entry's children means one `listDir` per child — an N+1 fan-out across a seam that may be remote or sandboxed, paid on every listing, to sharpen a decision the model can settle by listing the one subdirectory it cares about. + +**Make `list` recursive with a depth argument.** Rejected for now. One level composes: the model lists what it needs to descend into. Recursion reintroduces the size and truncation problems this note exists to fix, and the provider primitive is deliberately one-level. + +**Spill a capped listing through `ctx.spillStore`, as `glob` does.** Rejected for v1. `glob` needs spill because a truncated path list has no cheap successor call; a truncated listing does, and the footer states the complete size and composition, so the model knows both that it is looking at part of a directory and what to do about it. + +## Consequences + +An over-cap `glob` result no longer returns the most recently modified paths. That is a real contract change on a hot path, and it is why the footer, the prompt section, and the schema all state the sampled basis rather than leaving the model to infer it. A result within the cap is byte-identical to before, so age-ordered reading keeps working wherever it was working. + +Balancing is by first path segment only, so a result concentrated deeper — one enormous directory inside an otherwise even tree — is still shown unevenly below the top level. Recorded in the package's Known Limitations. + +The shipped tool surface grows by one tool in every deployment that loads `@deepseek-ai/dsh-tool-fs`, which is all of them: a fixed schema and prompt cost on every request, and an invalidated pinned request header in the ACP snapshot scenario that pins full system-prompt and tool-schema content. The gain is that the harness's most common question has a correct answer; the previous state was not a missing convenience but a capability hole that produced confidently wrong answers. + +`ctx.fs.listDir` gains its first model-facing consumer, which makes its contract load-bearing for a product surface: a future remote or sandboxed backend must implement direct-child listing well enough for a model to navigate by, not merely well enough for skill discovery. The `other` type stays collapsed at the seam, so `list` cannot distinguish a symlink from a socket and marks both `@`. + +## Testing + +Package tests pin the model-visible text of both surfaces. For `glob`: `sampleAcrossTopLevel` over a concentrated result, an exhausted group handing its slots on, a page smaller than the top level, absolute paths outside the workdir, and a flat result that must reproduce the sorted head; plus end-to-end assertions that a fitting result is untouched, that an over-cap result returns the sampled page with the sampled-basis footer, that the list hint disappears once the page reaches every entry, and that a flat over-cap result keeps the plain footer. For `list`: the envelope, type markers, singular and plural footers, the empty-directory footer, and the capped footer that keeps the sole directory visible. A registry-level test asserts that a listing emits no `fs/observed` and that a following `edit` still fails `FS_NOT_OBSERVED`, so the tool cannot become an accidental read-before-write bypass. Prompt-section registration, schema registration, and HMR disposal cover the fourth tool alongside the existing three. + +The assembled transcript is the `fs-list` ACP scenario: a workspace whose answer is its subdirectories, where the model calls `list` with no arguments and the pinned tool result carries the directory-first envelope and its composition footer — an answer `glob` could not have produced at all. diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md new file mode 100644 index 0000000000..4033254b08 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md @@ -0,0 +1,110 @@ +# Agent Note: Sample over-cap glob results across the tree, and give the model a directory-listing tool + +Status: implemented + +[English](2026-07-27-directory-listing-tool.md) | 中文 + +## Problem + +被问到工作区里有什么时，agent（智能体）把其中一个子目录当作整个项目描述了一遍。 + +会话日志把过程说得很清楚。该工作区有 22 个顶层条目、11485 个文件。模型调用了 `glob {"pattern": "*"}`，匹配到 10030 条路径；工具展示了前 100 条，而这 100 条全部位于同一个新近解包的子目录下，该子目录只占其中 355 个文件。模型从未看到另外 21 个顶层条目，只能依据它看到的那一个作答。整个过程中会话 cwd 都是正确的——没有任何配置错误，工具打印的每个数字也都是真的。 + +`glob` 的三项性质合成了那个页面： + +- **不含 `/` 的 pattern 匹配任意深度。** pattern 直接作为 `--glob=` 交给 ripgrep，而不含分隔符的 glob 匹配树中任何位置的基名。因此 `*` 的含义是「工作区里的每个文件」，而不是「顶层」——与它在 shell 里的含义正好相反。工具对此只字未提，schema 里的示例又全是 `**/…`，没有任何线索表明朴素写法是递归的。 +- **`--sort=modified` 按从旧到新排序。** 解包压缩档会还原档案内部保存的时间戳，它们早于用户自己写下的一切，因此新近解包的子树会落在任何宽泛匹配的最前面。（ripgrep 按升序排序；降序是 `--sortr`，此处未使用。） +- **内联页面取的是该顺序的头部。** 从最前面保留 `globMaxResults`（100）条路径。在前两项性质之下，一个子树吃掉全部位置。 + +单看每一项都站得住。合在一起，它们让 agent 收到的最普通的请求——「这个目录里有什么」——稳定地产出一个笃定的错误答案，因为结果里没有任何信息能区分「本工作区最新的 100 个文件」与「本工作区」。 + +### 排序能修什么，不能修什么 + +由于 `rg --files` 输出文件、从不输出目录条目，一个目录的名字只能作为其下某个文件路径的前缀抵达模型。这既足以让排序变得非常重要，也不足以让 `glob` 回答那个问题。 + +在一份复现该失败形态的目录上实测——24 个顶层条目、716 个文件、一个新近写入的子树： + +| 前 100 条路径的挑选方式 | 可见的顶层名个数 | +| --- | --- | +| 按修改时间、从旧到新（已交付的行为） | 7 | +| 跨顶层条目轮转 | 21 | + +也就是说，换一种页面挑选方式确实能呈现出大部分缺失的名字，最初那句「排序帮不上忙」的诊断是错的。排序修不了的是：没有任何文件的条目根本不会出现（复现目录里的空目录在完整的 716 条输出中一次都没出现），而且输出里没有任何信息说明哪些名字是目录、某个目录有多少条目。因此 `glob` 能传达一棵树的大致形状，却说不出一个目录的内容。 + +## Decision + +两项改动，分别落在承担这次失败两半责任的两个包中。 + +### 超过上限的 `glob` 结果，内联页面改为取样而非取头部 + +`@deepseek-ai/dsh-tool-fs-search`。未超过 `globMaxResults` 的结果完全不变：整体展示，按修改时间排序。只有结果更大时页面才改变——而恰恰在这种情况下，取头部是会失败的做法。 + +`sampleAcrossTopLevel` 按路径首段对完整结果分组，并以轮转方式填充页面：每个顶层条目都先拿到一个位置，任何条目才可能拿到第二个；某个条目的路径用尽后退出，其剩余份额交给其余条目。排序在仍有意义的地方被保留下来——分组按 ripgrep 首次输出它们的顺序访问，而每个分组内部的路径保持原有相对顺序。页面按条目分组输出而非交错输出，使覆盖广度一眼可辨。 + +footer 会说明取用依据，因为一个悄悄不再是「最新 N 条」的页面，只会成为同一个谎言更安静的版本： + +``` +(Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched +instead of taken in modification-time order. Full sorted result stored at: …) +``` + +当页面无法触达全部顶层条目时——条目数多于位置数——footer 会给出已触达/总计的分布并指向 `list`。扁平结果（每个路径各自构成一个顶层条目）保留朴素的 `(Showing k of n paths. …)` footer：此时轮转结果**就是**排序后的头部，说明分布只会重复计数。spill 产物始终保存按修改时间排序的完整列表，排序视图不会丢失。 + +同一次改动里，指导与 schema 也不再误导：「not shell find or ls」改为「not shell find」；两处现在都写明：不含 `/` 的 pattern 匹配任意深度的基名、结果只有文件从不包含目录、未超上限的结果按修改时间排序而更大的结果为取样所得、目录内容请用 `list`。 + +### `list`，位于 `@deepseek-ai/dsh-tool-fs` + +在既有的 `ctx.fs.listDir` 原语之上新增第四个面向模型的文件系统工具；该原语此前交付时唯一的消费方是 skill（技能）发现，[seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) 把面向模型的消费方推迟为一项单独的决策，也就是本文。 + +它接受可选的 `path`，默认为 `.`，即调用 agent 的会话工作区，因此那个最常见的问题不需要任何参数；返回单个目录的直接子项，形如 `{ path, entries: [{ name, type }] }`，其中 `type` 为 `file`、`directory` 或 `other`。它只调用 `listDir`：seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，前置 `stat` 只会多一次往返并制造第二个真源。 + +有两条展示规则承载了这个决策： + +- **先目录、再文件、最后非常规子项，各组内按字母序** —— 规范值与渲染文本采用同一顺序，使 Code Mode 调用方和模型看到同一份顺序契约。seam 返回的是稳定名称序，会把子目录散落在字母表各处；对这样的列表设上限可能丢掉全部子目录，在 `list` 内部重演同一种盲区。目录优先的顺序让截断只丢叶子，绝不丢结构。 +- **footer 始终说明完整列表的规模与构成** —— 例如 `(22 entries: 18 directories, 4 files)`；视图受 `listMaxEntries`（默认 200，可配置）截断时则为 `(Showing 200 of 5000 entries: 12 directories, 4988 files. …)`。因此部分列出结果不可能被读成整个目录。 + +目录条目渲染带尾部 `/`，非常规子项带 `@`，使模型无需第二次调用就能判断哪些可以继续进入。 + +`list` 不发出 `fs/observed`。看到文件名不等于读过文件，列出绝不能满足 `@deepseek-ai/dsh-fs-policy` 施加的编辑前读取门禁。它声明 `isConcurrencySafe`，因为它完全不做任何变更。 + +### 为什么两者都要 + +它们回答的是不同的问题，彼此无法替代。`list` 精确回答「这里有什么」——条目名、类型、完整计数——这是 `glob` 在任何排序下都做不到的。取样修的是宽泛 `glob` 为**其他**所有问题返回的那个页面；即便有了更好的工具，那个页面依然是错的，因为模型没有理由放弃一个看起来有代表性的页面。 + +## Alternatives considered + +**不动 `glob` 排序，只在 footer 里警告。** 这正是第一版实现的做法：保留新近序头部，加一句「该头部只覆盖 22 个顶层条目中的 1 个」。实测之后否决。一句警告是在要求模型不信任它手上唯一的数据并另寻他处；而一个更好的页面本身就不是错的。对于读到路径就停下的模型，警告也毫无作用——而那正是本次要修的失败。 + +**一律取样，彻底取消按修改时间排序。** 已否决。在完整结果上，该顺序回答的是与新旧有关的问题——哪些已经陈旧、哪些最后被动过——这是一个确实有用且独立的用途；而未超上限的完整结果恰恰是该顺序毫无代价、意义最大的场景。只在超过上限后取样，正好落在该顺序已经不再描述结果的那个点上：一份 10030 条列表的头部不是「最值得知道的最旧文件」，而是其中任意的 1%。 + +**按偏斜阈值决定是否取样——头部不太集中时仍取头部。** 已否决。阈值是随部署而变的可调参数，且其取值没有任何证据支撑；它还会让结果的顺序契约取决于模型看不到的数据。而「是否超过上限」是模型本来就能从 footer 得知的边界。 + +**递归均衡，而不只在顶层均衡。** 已延期，并记入已知限制。顶层均衡修好了已观察到的失败，且能用一句工具描述解释清楚；逐层均衡需要一套关于深度与广度如何权衡的策略，目前没有证据能定下来。 + +**拒绝 `*`，或悄悄将其改写为锚定顶层的 pattern。** 已否决。让 `*` 递归的那条「任意深度匹配基名」规则，同样让 `*.ts` 意为「每个 TypeScript 文件」，而后者是压倒性常见且正确的用法；只锚定其一是任意的特例，而拒绝一个 ripgrep 本可接受的 pattern 则把可用调用变成错误。把规则写进文档不花任何代价，而且可以推广。 + +**只加 `list`，不动 `glob`。** 已否决，理由见上文《为什么两者都要》。任何宽泛 pattern 都能触达那个误导性页面，而一个相信自己样本有代表性的模型，没有理由改用别的工具。 + +**只修 `glob`，不加 `list`。** 出于对称的理由否决。取样页面能展示大部分顶层**名字**，但说不出哪些是目录、看不到空目录、也给不出条目总数；「这个目录里有什么」值得一个直接回答它的工具，而不是一份需要模型去推断的样本。 + +**在 `list` 中报告每个目录的子项数。** 已否决。统计每个条目的子项意味着对每个子项各调用一次 `listDir`——在一个可能是远程或沙箱的 seam 上做 N+1 扇出，每次列出都要付费，只为了让模型少做一个它本可以通过列出所关心的那一个子目录就完成的判断。 + +**让 `list` 支持递归和深度参数。** 暂时否决。单层是可组合的：模型列出它需要进入的那一层即可。递归会重新引入本 Agent Note 要解决的规模与截断问题，而且提供方原语本身就有意只做一层。 + +**像 `glob` 那样，把达到上限的列出结果通过 `ctx.spillStore` 落盘。** v1 已否决。`glob` 需要 spill，是因为被截断的路径列表没有廉价的后继调用；被截断的列出结果有，而且 footer 已说明完整规模与构成，模型既知道自己只看到目录的一部分，也知道该怎么办。 + +## Consequences + +超过上限的 `glob` 结果不再返回修改时间最新的那些路径。这是热路径上一项真实的契约变更，也正因如此，footer、提示词段和 schema 都写明了取样这一依据，而不是留给模型去推断。未超上限的结果与此前逐字节相同，因此按新旧顺序阅读结果的用法在原本能用的地方继续能用。 + +均衡只按路径首段进行，因此集中在更深层的结果——一棵总体均匀的树里某个特别庞大的目录——在顶层以下仍然分布不均。已记入该包的已知限制。 + +随产品交付的工具接口在每个加载 `@deepseek-ai/dsh-tool-fs` 的部署中都多出一个工具，而这是全部部署：每个请求都要支付固定的 schema 与提示词成本，并且会使 ACP（Agent Client Protocol）快照场景中那份钉住完整系统提示词与工具 schema 内容的请求头失效。换来的是：harness 最常见的问题终于有了正确答案；此前的状态不是缺少一项便利，而是一个会产出笃定错误答案的能力空洞。 + +`ctx.fs.listDir` 拥有了第一个面向模型的消费方，其契约由此成为产品接口的承重部分：未来的远程或沙箱后端实现直接子项列出时，标准不再是「够 skill 发现用」，而是「够模型据以导航」。`other` 类型在 seam 处仍是合并的，因此 `list` 无法区分符号链接与套接字，两者都标记为 `@`。 + +## Testing + +包测试钉住两个接口面向模型的文本。`glob` 方面：`sampleAcrossTopLevel` 在集中结果、某分组用尽后交出份额、页面小于顶层条目数、工作目录之外的绝对路径，以及必须复现排序头部的扁平结果上的行为；另有端到端断言——未超上限的结果原样不动、超上限结果返回取样页面并带取样依据 footer、页面覆盖全部条目后 list 提示消失、扁平的超上限结果保留朴素 footer。`list` 方面：包络、类型标记、单复数 footer、空目录 footer，以及让唯一那个目录留在视野内的截断 footer。一项注册表层级的测试断言列出不会发出 `fs/observed`，且随后的 `edit` 仍以 `FS_NOT_OBSERVED` 失败，使该工具不会变成意外的编辑前读取绕过口。提示词段注册、schema 注册与 HMR（热模块替换）dispose（资源释放）覆盖了这第四个工具与既有三个工具。 + +组装后的 transcript（文本记录）由 `fs-list` ACP 场景承担：该工作区的答案就是它的子目录，模型不带任何参数调用 `list`，被钉住的工具结果携带目录优先的包络及其构成 footer —— 这个答案 `glob` 根本无法给出。 From 717852423fa4587134b2879378c5f5dbc4244ad4 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 13:01:26 +0800 Subject: [PATCH 04/67] fix(fs): harden directory listing and glob sampling --- ...026-07-27-directory-listing-tool.i18n.yaml | 4 +- .../2026-07-27-directory-listing-tool.md | 31 +++-- .../2026-07-27-directory-listing-tool.zh.md | 31 +++-- docs/config-catalog.md | 2 +- docs/tool-catalog.md | 16 ++- .../system-prompt.expected.md | 13 +- .../tool-schemas.expected.json | 6 +- .../both-mode-turn/system-prompt.expected.md | 13 +- .../both-mode-turn/tool-schemas.expected.json | 6 +- .../code-mode-turn/system-prompt.expected.md | 13 +- .../system-prompt.expected.md | 13 +- .../system-prompt.expected.md | 2 +- .../tool-schemas.expected.json | 6 +- .../tests/snapshots/fs-list/session.jsonl | 2 +- .../lsp-definition/system-prompt.expected.md | 2 +- .../lsp-definition/tool-schemas.expected.json | 6 +- .../pty-tools/system-prompt.expected.md | 2 +- .../pty-tools/tool-schemas.expected.json | 6 +- .../system-prompt.expected.md | 2 +- .../tool-schemas.expected.json | 6 +- .../skill-load/system-prompt.expected.md | 2 +- .../skill-load/tool-schemas.expected.json | 6 +- .../text-turn/system-prompt.expected.md | 2 +- .../text-turn/tool-schemas.expected.json | 6 +- .../web-fetch/system-prompt.expected.md | 2 +- .../web-fetch/tool-schemas.expected.json | 6 +- .../system-prompt.expected.md | 2 +- .../tool-schemas.expected.json | 6 +- .../advanced-toolchain/session.1.jsonl | 2 +- .../advanced-toolchain/session.2.jsonl | 2 +- .../advanced-toolchain/session.jsonl | 2 +- .../tests/snapshots/pty-tools/session.jsonl | 2 +- packages/fs/tool-fs-search/README.i18n.yaml | 4 +- packages/fs/tool-fs-search/README.md | 10 +- packages/fs/tool-fs-search/README.zh.md | 10 +- packages/fs/tool-fs-search/src/glob.ts | 57 +++++--- .../fs/tool-fs-search/tests/tools.spec.ts | 76 +++++++++-- packages/fs/tool-fs/README.i18n.yaml | 4 +- packages/fs/tool-fs/README.md | 18 +-- packages/fs/tool-fs/README.zh.md | 18 +-- packages/fs/tool-fs/src/index.ts | 2 +- packages/fs/tool-fs/src/list-render.ts | 123 +++++++++++------- packages/fs/tool-fs/src/list.ts | 58 +++++++-- packages/fs/tool-fs/tests/list-render.spec.ts | 36 +++-- packages/fs/tool-fs/tests/tools.spec.ts | 57 ++++++-- scripts/gen-tool-catalog.ts | 4 +- 46 files changed, 480 insertions(+), 219 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml index 27a498cb46..79b30290b5 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md -2026-07-27-directory-listing-tool.md: 4292c173f07064ff8825462e08096780c20ad9d6 -2026-07-27-directory-listing-tool.zh.md: 4033254b08a77ba7ed9b1f3e638213f019abb692 +2026-07-27-directory-listing-tool.md: a23cdb0090f1a88b783d9717aa3f0434b6c2782e +2026-07-27-directory-listing-tool.zh.md: bab0138a79ae770ae7e841392b879940e8ac2dc4 diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md index 4292c173f0..a23cdb0090 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md @@ -16,13 +16,13 @@ Three properties of `glob` compose into that page: - **`--sort=modified` orders oldest first.** Unpacking an archive restores the timestamps stored inside it, which predate everything the user wrote, so a freshly unpacked subtree lands at the very front of any broad match. (Ripgrep sorts ascending; `--sortr` is the descending form and is not used here.) - **The inline page was the head of that order.** `globMaxResults` (100) paths were kept from the front. Under the first two properties, one subtree takes every slot. -Each property is defensible alone. Together they make the most ordinary request an agent receives — "what is in this directory" — reliably produce a confident wrong answer, because nothing in the result distinguishes "the 100 newest files in this workspace" from "this workspace". +Each property is defensible alone. Together they make the most ordinary request an agent receives — "what is in this directory" — reliably produce a confident wrong answer, because nothing in the result distinguishes "the 100 oldest files in this workspace" from "this workspace". ### What ordering can and cannot fix A directory's name reaches the model only as the prefix of one of its files' paths, since `rg --files` emits files and never directory entries. That is enough for ordering to matter a great deal, and not enough for `glob` to answer the question. -Measured on a reproduction of the failure's shape — 24 top-level entries, 716 files, one recently-written subtree: +Measured on a reproduction of the failure's shape — 24 top-level entries, 716 files, one old-timestamped subtree: | First 100 paths chosen by | Distinct top-level names visible | | --- | --- | @@ -39,31 +39,30 @@ Two changes, in the two packages that own the two halves of the failure. `@deepseek-ai/dsh-tool-fs-search`. A result within `globMaxResults` is unchanged: shown whole, in modification-time order. Only when the result is larger does the page change — and there, taking the head is what fails. -`sampleAcrossTopLevel` groups the complete result by leading path segment and fills the page round-robin: every top-level entry gets a slot before any entry gets a second, and an entry that runs out of paths drops out so its remaining slots go to the rest. Sort order survives where it still carries meaning — groups are visited in the order ripgrep first emits them, and each group's own paths keep their relative order. The page is emitted grouped by entry rather than interleaved, so the breadth is legible at a glance. +`sampleAcrossTopLevel` removes the displayed search-root prefix, groups the complete result by the next path segment, and fills the page round-robin: every entry immediately beneath the actual relative or absolute root gets a slot before any entry gets a second, and an entry that runs out of paths drops out so its remaining slots go to the rest. Sort order survives where it still carries meaning — groups are visited in the order ripgrep first emits them, and each group's own paths keep their relative order. The page is emitted grouped by entry rather than interleaved, so the breadth is legible at a glance. -The footer states the basis, because a page that silently stopped being "the newest N" would be a second, quieter version of the same lie: +The footer states the basis, because a page that silently stopped being "the first N in modification-time order" would be a second, quieter version of the same lie: ``` (Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched instead of taken in modification-time order. Full sorted result stored at: …) ``` -When the page cannot reach every top-level entry — more entries than slots — the footer says so with the shown/total spread and points at `list`. A flat result, where every path is its own top-level entry, keeps the plain `(Showing k of n paths. …)` footer: there the round-robin *is* the sorted head, and naming a spread would only restate the counts. The spill artifact always holds the complete list in modification-time order, so the sorted view is never lost. +When the page cannot reach every top-level entry — more entries than slots — the footer says so with the shown/total spread and tells the model to narrow `path`. A flat result, where every path is its own top-level entry, keeps the plain `(Showing k of n paths. …)` footer: there the round-robin *is* the sorted head, and naming a spread would only restate the counts. The spill artifact always holds the complete list in modification-time order, so the sorted view is never lost. -The guidance and schema stop misleading in the same change: "not shell find or ls" becomes "not shell find"; both now state that a pattern without `/` matches basenames at any depth, that results are files and never directories, that a fitting result is modification-time ordered while a larger one is sampled, and that `list` is the tool for a directory's contents. +The guidance and schema stop misleading in the same change: "not shell find or ls" becomes "not shell find"; both now state that a pattern without `/` matches basenames at any depth, that results are files and never directories, and that a fitting result is modification-time ordered while a larger one is sampled across top-level entries. They do not recommend sibling-package tools that may be absent from the current composition. ### `list`, in `@deepseek-ai/dsh-tool-fs` A fourth model-facing filesystem tool over the existing `ctx.fs.listDir` primitive, which until now shipped with skill discovery as its only consumer; [the seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) deferred the model-facing consumer to a separate decision, which this is. -It takes an optional `path` — defaulting to `.`, the calling agent's session workspace, so the common question needs no argument — and returns the direct children of one directory as `{ path, entries: [{ name, type }] }`, where `type` is `file`, `directory`, or `other`. It calls `listDir` and nothing else: the seam already reports absence as `FS_NOT_FOUND` and a non-directory target as `FS_NOT_DIRECTORY`, so a preceding `stat` would add a round-trip and a second source of truth. +It takes optional `path` and 1-based `offset` arguments, defaulting to the calling agent's session workspace and entry 1, and returns one bounded page as `{ path, offset, entries: [{ name, type }], totalEntries, counts }`, where `type` is `file`, `directory`, or `other`. It calls `listDir` and nothing else: the seam already reports absence as `FS_NOT_FOUND` and a non-directory target as `FS_NOT_DIRECTORY`, so a preceding `stat` would add a round-trip and a second source of truth. -Two presentation rules carry the decision: +Three presentation rules carry the decision: -- **Directories sort first, then files, then non-regular children, each alphabetically** — in the canonical value as well as the rendered text, so a Code Mode caller and the model see one ordering contract. The seam returns stable name order, which scatters subdirectories through the alphabet; capping such a list can drop every subdirectory and reproduce, inside `list`, the same blindness. Directory-first ordering makes truncation lose leaves, never structure. -- **The footer always states the complete listing's size and composition** — `(22 entries: 18 directories, 4 files)`, and when the view is capped at `listMaxEntries` (default 200, configurable), `(Showing 200 of 5000 entries: 12 directories, 4988 files. …)`. A partial listing therefore cannot read as a whole directory. - -Directory entries render with a trailing `/` and non-regular children with `@`, so the model can tell what it may descend into without a second call. +- **Directories sort first, then files, then non-regular children, each alphabetically** before paging, so every offset traverses one stable order and the first page keeps navigable structure. +- **The canonical value and Native result carry one recoverable page** of at most `listMaxEntries` (default 200, configurable). The footer states the complete size and composition and gives `offset=` until the final page, so omitted sibling names remain reachable. +- **Filesystem text cannot forge presentation structure.** The path and entry names render as JSON strings with envelope-significant characters escaped; directory `/` and non-regular `@` markers sit outside the quoted name, so a regular filename ending in `@` remains distinguishable. `list` emits no `fs/observed`. Seeing a filename is not reading a file, and a listing must never satisfy the read-before-write gate that `@deepseek-ai/dsh-fs-policy` enforces. It declares `isConcurrencySafe`, because it mutates nothing at all. @@ -73,7 +72,7 @@ They answer different questions and neither substitutes for the other. `list` an ## Alternatives considered -**Leave `glob` ordering alone and only warn in the footer.** This is what the first implementation did: keep the recency head and add a clause saying the head covered 1 of 22 top-level entries. Rejected once measured. A warning asks the model to distrust the only data it has and go elsewhere; a better page just is not wrong. The warning also does nothing for a model that stops reading at the paths, which is the failure being fixed. +**Leave `glob` ordering alone and only warn in the footer.** This is what the first implementation did: keep the oldest-first head and add a clause saying the head covered 1 of 22 top-level entries. Rejected once measured. A warning asks the model to distrust the only data it has and go elsewhere; a better page just is not wrong. The warning also does nothing for a model that stops reading at the paths, which is the failure being fixed. **Sample always, replacing modification-time order outright.** Rejected. Over a complete result the order answers age questions — what is stale, what was touched last — a genuinely useful and separate purpose, and a complete result is the case where the order costs nothing and means everything. Sampling only past the cap is the point where the order has already stopped describing the result: the head of a 10,030-path list is not "the oldest files worth knowing about", it is an arbitrary 1% of them. @@ -91,11 +90,11 @@ They answer different questions and neither substitutes for the other. `list` an **Make `list` recursive with a depth argument.** Rejected for now. One level composes: the model lists what it needs to descend into. Recursion reintroduces the size and truncation problems this note exists to fix, and the provider primitive is deliberately one-level. -**Spill a capped listing through `ctx.spillStore`, as `glob` does.** Rejected for v1. `glob` needs spill because a truncated path list has no cheap successor call; a truncated listing does, and the footer states the complete size and composition, so the model knows both that it is looking at part of a directory and what to do about it. +**Spill a capped listing through `ctx.spillStore`, as `glob` does.** Rejected for v1. `glob` needs spill because its schema has no offset; `list` has a cheap successor call through the exact next offset in the footer, while every page repeats the complete size and composition. ## Consequences -An over-cap `glob` result no longer returns the most recently modified paths. That is a real contract change on a hot path, and it is why the footer, the prompt section, and the schema all state the sampled basis rather than leaving the model to infer it. A result within the cap is byte-identical to before, so age-ordered reading keeps working wherever it was working. +An over-cap `glob` result no longer returns the oldest paths at the head of modification-time order. That is a real contract change on a hot path, and it is why the footer, the prompt section, and the schema all state the sampled basis rather than leaving the model to infer it. A result within the cap is byte-identical to before, so age-ordered reading keeps working wherever it was working. Balancing is by first path segment only, so a result concentrated deeper — one enormous directory inside an otherwise even tree — is still shown unevenly below the top level. Recorded in the package's Known Limitations. @@ -105,6 +104,6 @@ The shipped tool surface grows by one tool in every deployment that loads `@deep ## Testing -Package tests pin the model-visible text of both surfaces. For `glob`: `sampleAcrossTopLevel` over a concentrated result, an exhausted group handing its slots on, a page smaller than the top level, absolute paths outside the workdir, and a flat result that must reproduce the sorted head; plus end-to-end assertions that a fitting result is untouched, that an over-cap result returns the sampled page with the sampled-basis footer, that the list hint disappears once the page reaches every entry, and that a flat over-cap result keeps the plain footer. For `list`: the envelope, type markers, singular and plural footers, the empty-directory footer, and the capped footer that keeps the sole directory visible. A registry-level test asserts that a listing emits no `fs/observed` and that a following `edit` still fails `FS_NOT_OBSERVED`, so the tool cannot become an accidental read-before-write bypass. Prompt-section registration, schema registration, and HMR disposal cover the fourth tool alongside the existing three. +Package tests pin the model-visible text of both surfaces. For `glob`: sampling over a concentrated result, an explicit relative root, more top-level groups than JavaScript's argument limit, an exhausted group handing its slots on, a page smaller than the top level, absolute paths outside the workdir, and a flat result that must reproduce the sorted head. For `list`: ordering, complete composition, offset continuation and rejection, empty directories, and filesystem names containing newlines, tag text, or marker suffixes. A registry-level test asserts that a listing emits no `fs/observed` and that a following `edit` still fails `FS_NOT_OBSERVED`, so the tool cannot become an accidental read-before-write bypass. Prompt-section registration, schema registration, and HMR disposal cover the fourth tool alongside the existing three. The assembled transcript is the `fs-list` ACP scenario: a workspace whose answer is its subdirectories, where the model calls `list` with no arguments and the pinned tool result carries the directory-first envelope and its composition footer — an answer `glob` could not have produced at all. diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md index 4033254b08..bab0138a79 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md @@ -16,13 +16,13 @@ Status: implemented - **`--sort=modified` 按从旧到新排序。** 解包压缩档会还原档案内部保存的时间戳，它们早于用户自己写下的一切，因此新近解包的子树会落在任何宽泛匹配的最前面。（ripgrep 按升序排序；降序是 `--sortr`，此处未使用。） - **内联页面取的是该顺序的头部。** 从最前面保留 `globMaxResults`（100）条路径。在前两项性质之下，一个子树吃掉全部位置。 -单看每一项都站得住。合在一起，它们让 agent 收到的最普通的请求——「这个目录里有什么」——稳定地产出一个笃定的错误答案，因为结果里没有任何信息能区分「本工作区最新的 100 个文件」与「本工作区」。 +单看每一项都站得住。合在一起，它们让 agent 收到的最普通的请求——「这个目录里有什么」——稳定地产出一个笃定的错误答案，因为结果里没有任何信息能区分「本工作区按从旧到新顺序排在最前的 100 个文件」与「本工作区」。 ### 排序能修什么，不能修什么 由于 `rg --files` 输出文件、从不输出目录条目，一个目录的名字只能作为其下某个文件路径的前缀抵达模型。这既足以让排序变得非常重要，也不足以让 `glob` 回答那个问题。 -在一份复现该失败形态的目录上实测——24 个顶层条目、716 个文件、一个新近写入的子树： +在一份复现该失败形态的目录上实测——24 个顶层条目、716 个文件、一个时间戳较旧的子树： | 前 100 条路径的挑选方式 | 可见的顶层名个数 | | --- | --- | @@ -39,31 +39,30 @@ Status: implemented `@deepseek-ai/dsh-tool-fs-search`。未超过 `globMaxResults` 的结果完全不变：整体展示，按修改时间排序。只有结果更大时页面才改变——而恰恰在这种情况下，取头部是会失败的做法。 -`sampleAcrossTopLevel` 按路径首段对完整结果分组，并以轮转方式填充页面：每个顶层条目都先拿到一个位置，任何条目才可能拿到第二个；某个条目的路径用尽后退出，其剩余份额交给其余条目。排序在仍有意义的地方被保留下来——分组按 ripgrep 首次输出它们的顺序访问，而每个分组内部的路径保持原有相对顺序。页面按条目分组输出而非交错输出，使覆盖广度一眼可辨。 +`sampleAcrossTopLevel` 移除所显示的搜索根前缀，再按下一个路径段对完整结果分组，并以轮转方式填充页面：实际相对或绝对搜索根正下方的每个条目都先拿到一个位置，任何条目才可能拿到第二个；某个条目的路径用尽后退出，其剩余份额交给其余条目。排序在仍有意义的地方被保留下来——分组按 ripgrep 首次输出它们的顺序访问，而每个分组内部的路径保持原有相对顺序。页面按条目分组输出而非交错输出，使覆盖广度一眼可辨。 -footer 会说明取用依据，因为一个悄悄不再是「最新 N 条」的页面，只会成为同一个谎言更安静的版本： +footer 会说明取用依据，因为一个悄悄不再是「按修改时间排序的前 N 条」的页面，只会成为同一个谎言更安静的版本： ``` (Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched instead of taken in modification-time order. Full sorted result stored at: …) ``` -当页面无法触达全部顶层条目时——条目数多于位置数——footer 会给出已触达/总计的分布并指向 `list`。扁平结果（每个路径各自构成一个顶层条目）保留朴素的 `(Showing k of n paths. …)` footer：此时轮转结果**就是**排序后的头部，说明分布只会重复计数。spill 产物始终保存按修改时间排序的完整列表，排序视图不会丢失。 +当页面无法触达全部顶层条目时——条目数多于位置数——footer 会给出已触达/总计的分布，并要求模型缩小 `path`。扁平结果（每个路径各自构成一个顶层条目）保留朴素的 `(Showing k of n paths. …)` footer：此时轮转结果**就是**排序后的头部，说明分布只会重复计数。spill 产物始终保存按修改时间排序的完整列表，排序视图不会丢失。 -同一次改动里，指导与 schema 也不再误导：「not shell find or ls」改为「not shell find」；两处现在都写明：不含 `/` 的 pattern 匹配任意深度的基名、结果只有文件从不包含目录、未超上限的结果按修改时间排序而更大的结果为取样所得、目录内容请用 `list`。 +同一次改动里，指导与 schema 也不再误导：「not shell find or ls」改为「not shell find」；两处现在都写明：不含 `/` 的 pattern 匹配任意深度的基名、结果只有文件从不包含目录、未超上限的结果按修改时间排序，而更大的结果跨顶层条目取样。它们不会推荐当前组合中可能不存在的兄弟包工具。 ### `list`，位于 `@deepseek-ai/dsh-tool-fs` 在既有的 `ctx.fs.listDir` 原语之上新增第四个面向模型的文件系统工具；该原语此前交付时唯一的消费方是 skill（技能）发现，[seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) 把面向模型的消费方推迟为一项单独的决策，也就是本文。 -它接受可选的 `path`，默认为 `.`，即调用 agent 的会话工作区，因此那个最常见的问题不需要任何参数；返回单个目录的直接子项，形如 `{ path, entries: [{ name, type }] }`，其中 `type` 为 `file`、`directory` 或 `other`。它只调用 `listDir`：seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，前置 `stat` 只会多一次往返并制造第二个真源。 +它接受可选的 `path` 和从 1 开始的 `offset` 参数，默认取调用 agent 的会话工作区和第 1 个条目，并返回一个有界页面，形如 `{ path, offset, entries: [{ name, type }], totalEntries, counts }`，其中 `type` 为 `file`、`directory` 或 `other`。它只调用 `listDir`：seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，前置 `stat` 只会多一次往返并制造第二个真源。 -有两条展示规则承载了这个决策： +有三条展示规则承载了这个决策： -- **先目录、再文件、最后非常规子项，各组内按字母序** —— 规范值与渲染文本采用同一顺序，使 Code Mode 调用方和模型看到同一份顺序契约。seam 返回的是稳定名称序，会把子目录散落在字母表各处；对这样的列表设上限可能丢掉全部子目录，在 `list` 内部重演同一种盲区。目录优先的顺序让截断只丢叶子，绝不丢结构。 -- **footer 始终说明完整列表的规模与构成** —— 例如 `(22 entries: 18 directories, 4 files)`；视图受 `listMaxEntries`（默认 200，可配置）截断时则为 `(Showing 200 of 5000 entries: 12 directories, 4988 files. …)`。因此部分列出结果不可能被读成整个目录。 - -目录条目渲染带尾部 `/`，非常规子项带 `@`，使模型无需第二次调用就能判断哪些可以继续进入。 +- **先目录、再文件、最后非常规子项，各组内按字母序**，然后再分页，使每个 offset 都遍历同一稳定顺序，且第一页保留可导航的结构。 +- **规范值和 Native 结果携带一个可继续取回的页面**，最多包含 `listMaxEntries` 个条目（默认 200，可配置）。footer 会说明完整规模与构成，并在最后一页之前给出 `offset=`，因此被省略的同级名称仍可取回。 +- **文件系统文本无法伪造展示结构。** 路径和条目名渲染为 JSON 字符串，并转义对包络有意义的字符；目录 `/` 与非常规子项 `@` 标记位于带引号名称之外，因此以 `@` 结尾的常规文件名仍可区分。 `list` 不发出 `fs/observed`。看到文件名不等于读过文件，列出绝不能满足 `@deepseek-ai/dsh-fs-policy` 施加的编辑前读取门禁。它声明 `isConcurrencySafe`，因为它完全不做任何变更。 @@ -73,7 +72,7 @@ instead of taken in modification-time order. Full sorted result stored at: …) ## Alternatives considered -**不动 `glob` 排序，只在 footer 里警告。** 这正是第一版实现的做法：保留新近序头部，加一句「该头部只覆盖 22 个顶层条目中的 1 个」。实测之后否决。一句警告是在要求模型不信任它手上唯一的数据并另寻他处；而一个更好的页面本身就不是错的。对于读到路径就停下的模型，警告也毫无作用——而那正是本次要修的失败。 +**不动 `glob` 排序，只在 footer 里警告。** 这正是第一版实现的做法：保留从旧到新的头部，加一句「该头部只覆盖 22 个顶层条目中的 1 个」。实测之后否决。一句警告是在要求模型不信任它手上唯一的数据并另寻他处；而一个更好的页面本身就不是错的。对于读到路径就停下的模型，警告也毫无作用——而那正是本次要修的失败。 **一律取样，彻底取消按修改时间排序。** 已否决。在完整结果上，该顺序回答的是与新旧有关的问题——哪些已经陈旧、哪些最后被动过——这是一个确实有用且独立的用途；而未超上限的完整结果恰恰是该顺序毫无代价、意义最大的场景。只在超过上限后取样，正好落在该顺序已经不再描述结果的那个点上：一份 10030 条列表的头部不是「最值得知道的最旧文件」，而是其中任意的 1%。 @@ -91,11 +90,11 @@ instead of taken in modification-time order. Full sorted result stored at: …) **让 `list` 支持递归和深度参数。** 暂时否决。单层是可组合的：模型列出它需要进入的那一层即可。递归会重新引入本 Agent Note 要解决的规模与截断问题，而且提供方原语本身就有意只做一层。 -**像 `glob` 那样，把达到上限的列出结果通过 `ctx.spillStore` 落盘。** v1 已否决。`glob` 需要 spill，是因为被截断的路径列表没有廉价的后继调用；被截断的列出结果有，而且 footer 已说明完整规模与构成，模型既知道自己只看到目录的一部分，也知道该怎么办。 +**像 `glob` 那样，把达到上限的列出结果通过 `ctx.spillStore` 落盘。** v1 已否决。`glob` 需要 spill，是因为其 schema 没有 offset；`list` 可以通过 footer 中精确的下一 offset 廉价地继续调用，而且每一页都会重复完整规模与构成。 ## Consequences -超过上限的 `glob` 结果不再返回修改时间最新的那些路径。这是热路径上一项真实的契约变更，也正因如此，footer、提示词段和 schema 都写明了取样这一依据，而不是留给模型去推断。未超上限的结果与此前逐字节相同，因此按新旧顺序阅读结果的用法在原本能用的地方继续能用。 +超过上限的 `glob` 结果不再返回按修改时间从旧到新排序时位于头部的那些路径。这是热路径上一项真实的契约变更，也正因如此，footer、提示词段和 schema 都写明了取样这一依据，而不是留给模型去推断。未超上限的结果与此前逐字节相同，因此按新旧顺序阅读结果的用法在原本能用的地方继续能用。 均衡只按路径首段进行，因此集中在更深层的结果——一棵总体均匀的树里某个特别庞大的目录——在顶层以下仍然分布不均。已记入该包的已知限制。 @@ -105,6 +104,6 @@ instead of taken in modification-time order. Full sorted result stored at: …) ## Testing -包测试钉住两个接口面向模型的文本。`glob` 方面：`sampleAcrossTopLevel` 在集中结果、某分组用尽后交出份额、页面小于顶层条目数、工作目录之外的绝对路径，以及必须复现排序头部的扁平结果上的行为；另有端到端断言——未超上限的结果原样不动、超上限结果返回取样页面并带取样依据 footer、页面覆盖全部条目后 list 提示消失、扁平的超上限结果保留朴素 footer。`list` 方面：包络、类型标记、单复数 footer、空目录 footer，以及让唯一那个目录留在视野内的截断 footer。一项注册表层级的测试断言列出不会发出 `fs/observed`，且随后的 `edit` 仍以 `FS_NOT_OBSERVED` 失败，使该工具不会变成意外的编辑前读取绕过口。提示词段注册、schema 注册与 HMR（热模块替换）dispose（资源释放）覆盖了这第四个工具与既有三个工具。 +包测试钉住两个接口面向模型的文本。`glob` 方面：对集中结果取样、显式相对根、顶层分组数量超过 JavaScript 参数上限、某分组用尽后交出份额、页面小于顶层条目数、工作目录之外的绝对路径，以及必须复现排序头部的扁平结果。`list` 方面：顺序、完整构成、offset 续页与拒绝、空目录，以及包含换行、标签文本或标记后缀的文件系统名称。一项注册表层级的测试断言列出不会发出 `fs/observed`，且随后的 `edit` 仍以 `FS_NOT_OBSERVED` 失败，使该工具不会变成意外的编辑前读取绕过口。提示词段注册、schema 注册与 HMR（热模块替换）dispose（资源释放）覆盖了这第四个工具与既有三个工具。 组装后的 transcript（文本记录）由 `fs-list` ACP 场景承担：该工作区的答案就是它的子目录，模型不带任何参数调用 `list`，被钉住的工具结果携带目录优先的包络及其构成 footer —— 这个答案 `glob` 根本无法给出。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 0b0045b668..e87fc92c05 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1449,7 +1449,7 @@ Requires: `tools` · `fs` · `systemPrompt` ```ts config-catalog /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { - /** Maximum entries one `list` call renders inline; the footer still reports the complete count. */ + /** Maximum entries one `list` page returns; the footer still reports the complete count. */ listMaxEntries?: number /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 0884910bde..97bf0cac1d 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -20,8 +20,8 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. | | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. | | `@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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes. | -| `@deepseek-ai/dsh-tool-fs` | `edit`, `list`, `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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. | -| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. | +| `@deepseek-ai/dsh-tool-fs` | `edit`, `list`, `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. `list` paginates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. | +| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across entries immediately beneath the actual search root and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. | | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. | | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `user/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. | | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. | @@ -318,7 +318,7 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts ### `list` -List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. +List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. ```json { @@ -327,6 +327,10 @@ List the direct children of one directory, with their type. Entries are director "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } @@ -389,13 +393,13 @@ Create or fully replace a UTF-8 text file. Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts) -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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. +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. `list` paginates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate. ## `@deepseek-ai/dsh-tool-fs-search` ### `glob` -Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 100 paths come back in modification-time order; a larger result instead returns 100 paths sampled across top-level directories, says so, and reports where the complete sorted list was saved. To see what a directory contains, use the list tool instead. +Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 100 paths come back in modification-time order; a larger result instead returns 100 paths sampled across top-level entries, says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries. ```json { @@ -447,7 +451,7 @@ Search file contents with a ripgrep regular expression. Returns matching lines w Source: [`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts) -glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. +glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across entries immediately beneath the actual search root and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match. ## `@deepseek-ai/dsh-tool-pty` diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md index c78b763fec..94bc0823bb 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. @@ -99,10 +99,12 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ list: { /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ path?: string; + /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ + offset?: number; } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { @@ -307,10 +309,17 @@ interface ToolOutputMap { }; list: { path: string; + offset: number; entries: ({ name: string; type: "file" | "directory" | "other"; })[]; + totalEntries: number; + counts: { + directories: number; + files: number; + other: number; + }; }; ralph: { runId: string; diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json index f9aea468b5..dcacaad8ff 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json @@ -174,13 +174,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md index ede2684ae4..1a8589a47b 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. @@ -82,10 +82,12 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ list: { /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ path?: string; + /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ + offset?: number; } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { @@ -278,10 +280,17 @@ interface ToolOutputMap { }; list: { path: string; + offset: number; entries: ({ name: string; type: "file" | "directory" | "other"; })[]; + totalEntries: number; + counts: { + directories: number; + files: number; + other: number; + }; }; ralph: { runId: string; diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json index 1333345b48..9f55d9291f 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md index ede2684ae4..1a8589a47b 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. @@ -82,10 +82,12 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ list: { /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ path?: string; + /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ + offset?: number; } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { @@ -278,10 +280,17 @@ interface ToolOutputMap { }; list: { path: string; + offset: number; entries: ({ name: string; type: "file" | "directory" | "other"; })[]; + totalEntries: number; + counts: { + directories: number; + files: number; + other: number; + }; }; ralph: { runId: string; diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md index ede2684ae4..1a8589a47b 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. @@ -82,10 +82,12 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */ + /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ list: { /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ path?: string; + /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ + offset?: number; } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { @@ -278,10 +280,17 @@ interface ToolOutputMap { }; list: { path: string; + offset: number; entries: ({ name: string; type: "file" | "directory" | "other"; })[]; + totalEntries: number; + counts: { + directories: number; + files: number; + other: number; + }; }; ralph: { runId: string; diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md index edca40eed4..cd3c81f6f8 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json index ffb310c278..7094daf44e 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/fs-list/session.jsonl b/examples/acp-agent/tests/snapshots/fs-list/session.jsonl index 0a05e2b1fe..533571ee3f 100644 --- a/examples/acp-agent/tests/snapshots/fs-list/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-list/session.jsonl @@ -15,7 +15,7 @@ {"type":"assistant/chunk","seq":47,"time":1785159115922,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":48,"time":1785159115926,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call the list tool with no arguments and then reply with the names of the subdirectories it reports, alphabetically, separated by a single space."},{"type":"tool-call","id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":5513,"outputTokens":62,"cacheReadTokens":0,"reasoningTokens":35}},"sourceEventSeqs":[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],"surfaceOp":"append"} {"type":"tool/call","seq":49,"time":1785159115927,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}} -{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\ndirectory\n\ndocs/\nsrc/\npackage.json\nREADME.txt\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} +{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"\"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\"\ndirectory\n\n\"docs\"/\n\"src\"/\n\"package.json\"\n\"README.txt\"\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} {"type":"step/end","seq":51,"time":1785159115950,"data":{"turn":1,"step":1}} {"type":"step/start","seq":52,"time":1785159115951,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":53,"time":1785159116889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md index 5a5df6233c..d02b6d0859 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json index 3a0e7c1408..ab1bda91f3 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md index 70dd754517..c5496aeed5 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json index c529ad9077..0d20d22762 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md index 658fa4e07c..7d13160613 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json index 4eff11591a..caee8e049e 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md index 6d926a90a8..e6ab6361db 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json index ffb310c278..7094daf44e 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md index 6d926a90a8..e6ab6361db 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json index ffb310c278..7094daf44e 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md index 4c20e18272..451746f412 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json index 59e3baf6b1..6c389246e2 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md index 6c5155f262..fdacca4b7f 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md @@ -5,7 +5,7 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. Use 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. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json index ffb310c278..7094daf44e 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json @@ -117,13 +117,17 @@ }, { "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.", + "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", "parameters": { "type": "object", "properties": { "path": { "type": "string", "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." + }, + "offset": { + "type": "number", + "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." } } } diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl index c0f80e3cdf..0471db78e0 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884563,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884563,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884564,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */\n offset?: number;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n offset: number;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n totalEntries: number;\n counts: {\n directories: number;\n files: number;\n other: number;\n };\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."},"offset":{"type":"number","description":"1-based first entry to return. Defaults to 1; use the footer value to continue."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950001005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":6,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}} {"type":"assistant/chunk","seq":7,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}} diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl index 2bf8be7bfb..f0cad5bcd7 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884700,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884700,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884700,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */\n offset?: number;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n offset: number;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n totalEntries: number;\n counts: {\n directories: number;\n files: number;\n other: number;\n };\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."},"offset":{"type":"number","description":"1-based first entry to return. Defaults to 1; use the footer value to continue."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950002005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":6,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}} {"type":"assistant/chunk","seq":7,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}} diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl index 8f531cf789..883feaf563 100644 --- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl +++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":1783957884479,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":1783957884479,"data":{"title":"Run this advanced flow exactly","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is /tmp/advanced-headless.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer.\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\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\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 typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\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\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. */\n bash: {\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 (collect with task_output, stop with task_kill). No timeout applies. */\n run_in_background?: boolean;\n } & Record;\n /** 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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n cordis_inspect: {\n /** Limit the report to one section. Omit for all sections. */\n what?: \"services\" | \"plugins\" | \"tools\" | \"dynamic\" | \"api\" | \"events\";\n /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n name?: string;\n } & Record;\n /** 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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. */\n cordis_mount: {\n /** Body of an async JS function; must `return` the plugin to mount. */\n code: string;\n } & Record;\n /** 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). */\n cordis_unmount: {\n /** The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\"). */\n id: string;\n } & Record;\n /** Edit an existing UTF-8 text file by replacing literal text. */\n edit: {\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 } & Record;\n /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */\n list: {\n /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */\n path?: string;\n /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */\n offset?: number;\n } & Record;\n /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n ralph: {\n /** The immutable completion objective for every fresh Ralph round. */\n objective: string;\n /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n maxRounds?: number;\n } & Record;\n /** Read a UTF-8 text file and return line-numbered content. */\n read: {\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 } & Record;\n /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n skill: {\n /** The exact skill name from the available skills list. */\n name: string;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */\n subagent_fork: {\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 /** Run as a background task and return its id; collect with task_output or stop with task_kill. */\n run_in_background?: boolean;\n } & Record;\n /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n task_kill: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Optional short reason, recorded in the log and forwarded to the task. */\n reason?: string;\n } & Record;\n /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n task_list: Record;\n /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n task_output: {\n /** Task id returned by the tool that started the background work. */\n task_id: string;\n /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n wait?: boolean;\n /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n timeout_ms?: number;\n } & Record;\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: {\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 } & Record;\n /** 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 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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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; 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. */\n workflow: {\n /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `). */\n script: string;\n /** The workflow identity block (plain JSON — never code). */\n meta: {\n /** Short kebab-case workflow name. */\n name: string;\n /** One-line description of what the workflow does. */\n description: string;\n /** Optional guidance on when this workflow applies. */\n whenToUse?: string;\n /** Optional phase declarations matched by phase() calls. */\n phases?: ({\n /** The phase title phase() calls match by exact string. */\n title: string;\n /** Optional one-line description of the phase. */\n detail?: string;\n /** Optional provider override this phase is expected to use. */\n provider?: string;\n /** Optional model override this phase is expected to use. */\n model?: string;\n } & Record)[];\n } & Record;\n /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n args?: Record;\n } & Record;\n /** Create or fully replace a UTF-8 text file. */\n write: {\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 } & Record;\n}\n\ninterface ToolOutputMap {\n bash: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n exitCode: number | null;\n signal: string | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n stderr: {\n text: string;\n truncated: boolean;\n spillPath?: string;\n };\n sandbox?: {\n mode: string;\n denied: boolean;\n enforcement?: string;\n runnerFailed?: boolean;\n };\n };\n cordis_inspect: string;\n cordis_mount: {\n id: string;\n pluginName: string;\n state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n provides: string[];\n waitingFor: string[];\n };\n cordis_unmount: {\n id: string;\n pluginName: string;\n };\n edit: {\n path: string;\n before: string;\n after: string;\n };\n list: {\n path: string;\n offset: number;\n entries: ({\n name: string;\n type: \"file\" | \"directory\" | \"other\";\n })[];\n totalEntries: number;\n counts: {\n directories: number;\n files: number;\n other: number;\n };\n };\n ralph: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n read: {\n path: string;\n offset: number;\n lines: {\n number: number;\n text: string;\n }[];\n totalLines: number;\n };\n skill: {\n name: string;\n provider: string;\n resourceBase?: {\n kind: \"directory\";\n path: string;\n } | {\n kind: \"url\";\n url: string;\n } | {\n kind: \"opaque\";\n description: string;\n };\n content: string;\n };\n subagent: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n subagent_fork: {\n kind: \"background\";\n taskId: string;\n } | {\n kind: \"foreground\";\n runId: string;\n output: JsonValue[];\n };\n task_kill: {\n outcome: \"cancellation-requested\" | \"already-finished\";\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n task_list: ({\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n })[];\n task_output: {\n text: string;\n task: {\n id: string;\n kind: string;\n label: string;\n status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n };\n };\n todo_write: {\n todos: ({\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n })[];\n counts: {\n pending: number;\n inProgress: number;\n completed: number;\n };\n };\n workflow: {\n runId: string;\n agentsStarted: number;\n result: JsonValue;\n };\n write: {\n path: string;\n operation: \"create\" | \"update\";\n before: string | null;\n after: string;\n };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n readonly name: \"ToolCallError\";\n readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n [K in ToolName]: (args: ToolArgsMap[K]) => 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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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` (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. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","dynamic","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"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) => { … }` — 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 } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. 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.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"Body of an async JS function; must `return` the plugin to mount."}},"required":["code"]}},{"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":{"type":"object","properties":{"id":{"type":"string","description":"The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")."}},"required":["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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."},"offset":{"type":"number","description":"1-based first entry to return. Defaults to 1; use the footer value to continue."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":1783950000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} {"type":"assistant/chunk","seq":6,"time":1783950000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}} {"type":"assistant/chunk","seq":7,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}} diff --git a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl index 2cde7d9e42..fd122fc594 100644 --- a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl +++ b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl @@ -3,7 +3,7 @@ {"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Exercise the six PTY tools in order, including one missing-session signal error, then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"session/title","seq":2,"time":0,"data":{"title":"Exercise the six PTY tools","messageSeqs":[1],"source":{"kind":"fallback"}}} {"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for.\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 a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; the first 200 are returned inline and the footer reports the complete count. Unlike glob, this shows subdirectories, so it is how to see what a directory contains.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer.\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 a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\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.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_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 (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"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":"list","description":"List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.","parameters":{"type":"object","properties":{"path":{"type":"string","description":"Directory to list. Defaults to the session workspace; a relative path resolves against it."},"offset":{"type":"number","description":"1-based first entry to return. Defaults to 1; use the footer value to continue."}}}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"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":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.","parameters":{"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."},"run_in_background":{"type":"boolean","description":"Run as a background task and return its id; collect with task_output or stop with task_kill."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"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","additionalProperties":false,"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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).","additionalProperties":true,"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","additionalProperties":true,"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."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"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\": [...]}).","additionalProperties":true}},"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":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} {"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"pty-spawn","name":"terminal_open","argumentsDelta":"{\"type\":\"shell\",\"name\":\"main\"}"}}} {"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"pty-spawn","name":"terminal_open","arguments":"{\"type\":\"shell\",\"name\":\"main\"}"}}}} diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml index ec8f6f8968..68c621949d 100644 --- a/packages/fs/tool-fs-search/README.i18n.yaml +++ b/packages/fs/tool-fs-search/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md -README.md: 33792a6f4b72baa2626c6e8d37c672fb39681554 -README.zh.md: 5d13a7ff2cb3ddfda8168a34e4a4a897d3413e11 +README.md: 51b3fa5385330cdaba0b36dd71a6efe4fd3d0db5 +README.zh.md: 855db224652b818d5f3dadffd275581b5b760007 diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md index 33792a6f4b..51b3fa5385 100644 --- a/packages/fs/tool-fs-search/README.md +++ b/packages/fs/tool-fs-search/README.md @@ -34,14 +34,14 @@ All keys are optional; the defaults are the shipped search caps. | Tool | Arguments | Behavior | |---|---|---| -| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line, modification-time ordered — `rg --files` never emits a directory, so no pattern makes `glob` describe a directory's contents; that is [`dsh-tool-fs`](../tool-fs/)'s `list`. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. | +| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line, modification-time ordered; `rg --files` never emits directory entries. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. | | `grep` | `pattern`, `path?`, `include?` | Line-oriented `rg --json` parse (no colon-splitting ambiguity). `pattern` is a ripgrep regex; `path` is an optional **file or directory** target; `include` is ONE positive glob filter — a comma-separated list or a negated (`!…`) value is rejected up front (brace alternation like `*.{ts,tsx}` is fine). Returns matches grouped by file as `Line N: `. | Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`case_insensitive`/output modes): a model that needs surrounding context reads the matched file with `read`; one that needs later results follows the returned spill locator's retrieval hint. ## Two budgets, two artifacts -Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps every acquired path in `{ paths }`; `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with a head page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`. +Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps the displayed search root and every acquired path in `{ root, paths }`; `root` lets the Native renderer group an explicit relative or absolute search path by entries beneath that root rather than by its workdir prefix. `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with a head page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`. ## Errors @@ -58,7 +58,7 @@ After the load-time `rg` probe succeeds, every request in this plugin's registra ##### Glob guidance ```markdown -Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, so it spans the tree instead of one subtree. Use the list tool to see what a directory contains. +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. ``` ##### Grep guidance @@ -93,7 +93,7 @@ Prefix-stable while tool visibility and definitions are unchanged. Registration #### What the model sees -`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. An over-cap `glob` result does not show the head of the sorted list: its inline page takes paths round-robin across the complete result's top-level entries, so one recently-written subtree cannot own every slot, and the footer says the page was sampled rather than taken in modification-time order, together with how many top-level entries it reached. When it could not reach them all, the footer also points at `list`. A result that fits inline is untouched, and a flat result — every path its own top-level entry — keeps the plain footer, because there the sample IS the recency-ordered head. The spill artifact always holds the complete list in modification-time order. +`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. An over-cap `glob` result does not show the head of the sorted list: its inline page takes paths round-robin across entries immediately beneath the actual search root, so one old-timestamped subtree cannot own every slot, and the footer states the sampled basis and how many top-level entries it reached. When it cannot reach them all, the footer tells the model to narrow `path`. A result that fits inline is untouched, and a flat result — every path its own top-level entry — keeps the plain footer, because there the sample is the modification-time-ordered head. The spill artifact always holds the complete list in modification-time order. #### Token effect @@ -122,4 +122,4 @@ Append-only; newly visible content follows the reusable request prefix and does - **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation. - **Ripgrep is a deployment dependency** — a missing `rg` executable makes the package register no tools or guidance; an incompatible executable or one that disappears after registration fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located executor or another search consumer. - **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend. -- **Sampling groups by first path segment only** — an over-cap `glob` page balances across top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred. +- **Sampling groups by first path segment beneath the search root only** — an over-cap `glob` page balances across those top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred. diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md index 5d13a7ff2c..855db22465 100644 --- a/packages/fs/tool-fs-search/README.zh.md +++ b/packages/fs/tool-fs-search/README.zh.md @@ -34,14 +34,14 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- | 工具 | 参数 | 行为 | |---|---|---| -| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录** 搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件** 路径；`rg --files` 从不输出目录条目，因此任何 pattern 都无法让 `glob` 描述一个目录的内容，那是 [`dsh-tool-fs`](../tool-fs/) 的 `list`。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。未超过 `globMaxResults` 的结果按修改时间排序；超过时内联页面改为跨顶层条目取样（见下）。 | +| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录** 搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件** 路径；`rg --files` 从不输出目录条目。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。未超过 `globMaxResults` 的结果按修改时间排序；超过时内联页面改为跨顶层条目取样（见下）。 | | `grep` | `pattern`、`path?`、`include?` | 按行解析 `rg --json`，避免按冒号拆分的歧义。`pattern` 是 ripgrep 正则表达式；`path` 是可选的**文件或目录** 目标；`include` 是一个正向 glob 过滤器，前置拒绝逗号分隔列表或否定值（`!…`），但允许 `*.{ts,tsx}` 等花括号交替。返回按文件分组、形如 `Line N: ` 的匹配。 | 常规预算不进入面向模型的 schema（没有 `head_limit`/`offset`/`case_insensitive`/输出模式）：模型需要周边上下文时，用 `read` 读取匹配文件；需要后续结果时，遵循返回的 spill locator 检索提示。 ## 两类预算、两类产物 -原始 `rg` stdout 是内部传输细节。每次搜索从 bash seam 请求 `stdoutMaxBytes: rawOutputMaxBytes`，且只解析完整保留的 stdout；如果执行器仍返回 `stdout.truncated`，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询。成功的 `glob` 在 `{ paths }` 中保留所有已取得路径；`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于 Native 渲染器。直接接口调用的逻辑结果超过内联上限时，后置政策会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为头部页面加 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。 +原始 `rg` stdout 是内部传输细节。每次搜索从 bash seam 请求 `stdoutMaxBytes: rawOutputMaxBytes`，且只解析完整保留的 stdout；如果执行器仍返回 `stdout.truncated`，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询。成功的 `glob` 在 `{ root, paths }` 中保留所显示的搜索根及所有已取得路径；借助 `root`，Native 渲染器能以显式的相对或绝对搜索路径为根，按该根下的条目分组，而不是按其工作目录前缀分组。`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于 Native 渲染器。直接接口调用的逻辑结果超过内联上限时，后置政策会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为头部页面加 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。 ## 错误 @@ -58,7 +58,7 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- ##### Glob 指导 ```markdown -Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, so it spans the tree instead of one subtree. Use the list tool to see what a directory contains. +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. ``` ##### Grep 指导 @@ -93,7 +93,7 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read #### 模型看到的内容 -`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。超过上限的 `glob` 结果不再展示排序列表的头部：其内联页面按轮转方式跨完整结果的顶层条目取样，因此单个新近写入的子树无法占满所有位置；footer 会说明该页面是取样得到而非按修改时间取用，并给出它触达了多少个顶层条目。未能触达全部时，footer 还会指向 `list`。未超过上限的结果原样不动；扁平结果（每个路径各自构成一个顶层条目）保留朴素 footer，因为此时取样结果就等于按新近度排序的头部。spill 产物始终保存按修改时间排序的完整列表。 +`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。超过上限的 `glob` 结果不再展示排序列表的头部：其内联页面按轮转方式跨实际搜索根正下方的条目取样，因此单个时间戳较旧的子树无法占满所有位置；footer 会说明取样依据及其触达的顶层条目数。无法触达全部时，footer 会要求模型缩小 `path`。未超过上限的结果原样不动；扁平结果（每个路径各自构成一个顶层条目）保留朴素 footer，因为此时取样结果就是按修改时间排序的头部。spill 产物始终保存按修改时间排序的完整列表。 #### Token 影响 @@ -122,4 +122,4 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read - **搜索和文件访问没有共享工作区证明**：只有 bash 工作目录和文件系统根目录表示同一工作区时，返回路径才能继续读取；本包不执行运行时跨服务校验。 - **Ripgrep 是部署依赖**：缺失 `rg` 可执行文件时，本包不注册工具或指导；可执行文件不兼容或注册后消失时，调用以 `SEARCH_FAILED` 失败。远程或虚拟文件系统需要共置执行器或其他搜索消费方。 - **schema 只公开一个有界页面**：offset 分页、大小写模式开关、其他输出模式和提供方支持的发现均不在本包内；达到上限的完整输出需要 spill 后端。 -- **取样只按路径首段分组**：超过上限的 `glob` 页面在顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。 +- **取样只按搜索根下的路径首段分组**：超过上限的 `glob` 页面在这些顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。 diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index d46b1d352d..94d9b0e627 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -107,7 +107,7 @@ export function buildGlobCommand(input: GlobInput): string { * result's top level it reaches. */ export interface GlobSample { - /** Paths to show inline: grouped by top-level entry, recency-ordered within each group. */ + /** Paths to show inline: grouped by top-level entry, modification-time ordered within each group. */ items: string[] /** Distinct top-level entries the shown paths reach. */ shown: number @@ -115,6 +115,18 @@ export interface GlobSample { total: number } +/** Remove the displayed search-root prefix before choosing a top-level group. */ +function relativeToSearchRoot(path: string, root: string): string { + if (root === '.') return path.replace(/^\.[\\/]/, '') + const trimmedRoot = root.replace(/[\\/]+$/, '') + if (trimmedRoot.length === 0) return path.replace(/^[\\/]+/, '') + if (path === trimmedRoot) return '' + if (path.startsWith(`${trimmedRoot}/`) || path.startsWith(`${trimmedRoot}\\`)) { + return path.slice(trimmedRoot.length + 1) + } + return path +} + /** * The leading path segment of one display path — the top-level entry, relative * to the search root, that the path sits under. A path with no separator is its @@ -149,18 +161,19 @@ function topLevelSegment(path: string): string { * * @param paths - the complete result, in ripgrep's modification-time order. * @param maxItems - how many paths the page may hold; the caller has already established it is smaller than `paths`. + * @param root - the search root in the same display-path space as `paths`. * @returns the page grouped by top-level entry, with the shown/total top-level spread. */ -export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number): GlobSample { +export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number, root = '.'): GlobSample { const groups = new Map() for (const path of paths) { - const group = groups.get(topLevelSegment(path)) - if (group === undefined) groups.set(topLevelSegment(path), [path]) + const key = topLevelSegment(relativeToSearchRoot(path, root)) + const group = groups.get(key) + if (group === undefined) groups.set(key, [path]) else group.push(path) } - // Bounding the rounds by the largest group makes termination structural: the - // page can only fill or the groups run out, never spin on empty rounds. - const rounds = Math.max(0, ...[...groups.values()].map(group => group.length)) + let rounds = 0 + for (const group of groups.values()) rounds = Math.max(rounds, group.length) const taken = new Map() let count = 0 for (let round = 0; round < rounds && count < maxItems; round += 1) { @@ -186,7 +199,7 @@ export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number) * here — it is emitted verbatim, in ripgrep's order. * * A result whose every path is its own top-level entry keeps the plain footer: - * the sample is the recency-ordered head, and naming a spread would only + * the sample is the modification-time-ordered head, and naming a spread would only * restate the path counts already there. * * @param sample - the inline page and its top-level spread. @@ -202,17 +215,17 @@ export function formatGlobOutput(sample: GlobSample, seen: number, spillRef: Spi const basis = sample.total === seen ? '.' : `, sampled across ${sample.shown} of the ${sample.total} top-level entries this pattern matched instead of taken in modification-time order.` - + (sample.shown < sample.total ? ' Use the list tool to see what a directory contains.' : '') + + (sample.shown < sample.total ? ' Narrow path to inspect a specific subtree.' : '') return `${body}\n\n(Showing ${sample.items.length} of ${seen} paths${basis} ${recovery})` } -/** Bound and format one canonical path list for the Native surface. */ -function renderGlobPaths(paths: string[], maxResults: number, spillRef?: SpillRef): string { +/** Bound and format one canonical path list for the Native surface relative to its search root. */ +function renderGlobPaths(paths: string[], maxResults: number, root: string, spillRef?: SpillRef): string { if (paths.length === 0) return 'No files found' // A result that fits is shown whole, untouched: modification-time order is the // tool's contract, and over a complete result it is what answers age questions. if (paths.length <= maxResults) return paths.join('\n') - return formatGlobOutput(sampleAcrossTopLevel(paths, maxResults), paths.length, spillRef) + return formatGlobOutput(sampleAcrossTopLevel(paths, maxResults, root), paths.length, spillRef) } /** @@ -238,16 +251,16 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { name: 'tool:glob', order: 103, text: 'Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. ' - + 'Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level directories, ' - + 'so it spans the tree instead of one subtree. Use the list tool to see what a directory contains.', + + 'Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, ' + + 'so it spans the tree instead of one subtree.', }) const tool = defineTool({ name: 'glob', description: 'Find files whose paths match a glob pattern. Returns matching file paths — never directories — ' + 'including hidden and ignored files (VCS metadata directories are excluded). ' - + `Up to ${caps.maxResults} paths come back in modification-time order; a larger result instead returns ${caps.maxResults} paths sampled across top-level directories, ` - + 'says so, and reports where the complete sorted list was saved. To see what a directory contains, use the list tool instead.', + + `Up to ${caps.maxResults} paths come back in modification-time order; a larger result instead returns ${caps.maxResults} paths sampled across top-level entries, ` + + 'says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries.', parameters: { pattern: { type: 'string', @@ -263,15 +276,17 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { type: 'object', additionalProperties: false, properties: { + root: { type: 'string', required: true }, paths: { type: 'array', required: true, items: { type: 'string' } }, }, }, - render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults) }], + render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults, value.root) }], }, async execute(args, exec) { const input = parseGlobArgs(args) const run = await runRipgrep(ctx, exec, 'glob', buildGlobCommand(input), caps.rawOutputMaxBytes) - if (run.noMatches) return { paths: [] } + const root = input.path === undefined ? '.' : toWorkdirRelative(input.path, run.workdir) + if (run.noMatches) return { root, paths: [] } const all: string[] = [] for (const line of run.stdout.split('\n')) { @@ -279,7 +294,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { const displayPath = toWorkdirRelative(line, run.workdir) all.push(displayPath) } - return { paths: all } + return { root, paths: all } }, presentCall: presentGlobCall, }) @@ -287,14 +302,14 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { ctx.on('tools/post-execute', async (exec, result, next) => { const decision = await next() - const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { paths: string[] } | undefined + const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { root: string; paths: string[] } | undefined if (value === undefined) return decision const paths = value.paths if (paths.length <= caps.maxResults) return decision const spillRef = await trySaveFormattedResult(ctx, exec, 'glob-results.txt', paths.join('\n')) return { kind: 'accept', - content: [{ type: 'text', text: renderGlobPaths(paths, caps.maxResults, spillRef) }], + content: [{ type: 'text', text: renderGlobPaths(paths, caps.maxResults, value.root, spillRef) }], ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {}, } }) diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 0bbe0e0bf5..df49ce33aa 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -185,6 +185,10 @@ describe('registration', () => { const prompt = renderPrompt(await ctx.systemPrompt.assemble()) expect(prompt).toContain('Use the glob tool') expect(prompt).toContain('Use the grep tool') + expect(prompt).toContain('sampled across top-level entries') + expect(prompt).not.toContain('sampled across top-level directories') + const glob = ctx.tools.schemas().find(schema => schema.name === 'glob') + expect(glob?.description).toContain('sampled across top-level entries') }) it('does not register glob or grep when the bash executor cannot find rg', async () => { @@ -526,9 +530,37 @@ describe('cross-directory sampling', () => { .toEqual({ items: ['/out/a', '/away/c'], shown: 2, total: 2 }) }) - it('reproduces the recency-ordered head for a flat result', () => { + it('reproduces the modification-time-ordered head for a flat result', () => { expect(sampleAcrossTopLevel(['a.ts', 'b.ts', 'c.ts'], 2)).toEqual({ items: ['a.ts', 'b.ts'], shown: 2, total: 3 }) }) + + it('groups paths relative to an explicit search root', () => { + expect(sampleAcrossTopLevel([ + 'workspace/vendor/a.ts', + 'workspace/vendor/b.ts', + 'workspace/source/c.ts', + 'workspace/guides/d.md', + ], 3, 'workspace')).toEqual({ + items: ['workspace/vendor/a.ts', 'workspace/source/c.ts', 'workspace/guides/d.md'], + shown: 3, + total: 3, + }) + expect(sampleAcrossTopLevel(['./vendor/a.ts', './src/b.ts'], 2, '.')) + .toEqual({ items: ['./vendor/a.ts', './src/b.ts'], shown: 2, total: 2 }) + expect(sampleAcrossTopLevel(['/vendor/a.ts', '/src/b.ts'], 2, '/')) + .toEqual({ items: ['/vendor/a.ts', '/src/b.ts'], shown: 2, total: 2 }) + expect(sampleAcrossTopLevel(['C:\\root\\a\\one', 'C:\\root\\b\\two'], 2, 'C:\\root')) + .toEqual({ items: ['C:\\root\\a\\one', 'C:\\root\\b\\two'], shown: 2, total: 2 }) + expect(sampleAcrossTopLevel(['other/a.ts'], 1, 'src')) + .toEqual({ items: ['other/a.ts'], shown: 1, total: 1 }) + expect(sampleAcrossTopLevel(['src'], 1, 'src')) + .toEqual({ items: ['src'], shown: 1, total: 1 }) + }) + + it('handles more top-level groups than the JavaScript argument limit', () => { + const paths = Array.from({ length: 125_000 }, (_, index) => `dir-${index}/file.txt`) + expect(sampleAcrossTopLevel(paths, 100)).toMatchObject({ shown: 100, total: 125_000 }) + }) }) describe('glob results', () => { @@ -537,7 +569,7 @@ describe('glob results', () => { bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n') const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') }) if (result.isError) throw new Error('expected glob success') - expect(result.value).toEqual({ paths: [join('src', 'a.ts'), '/elsewhere/b.ts', 'rel/c.ts'] }) + expect(result.value).toEqual({ root: '.', paths: [join('src', 'a.ts'), '/elsewhere/b.ts', 'rel/c.ts'] }) expect(text(result)).toBe(`${join('src', 'a.ts')}\n/elsewhere/b.ts\nrel/c.ts`) }) @@ -565,7 +597,7 @@ describe('glob results', () => { const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') }) expect(result.isError).toBe(false) if (result.isError) throw new Error('expected glob success') - expect(result.value).toEqual({ paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] }) + expect(result.value).toEqual({ root: '.', paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] }) expect(text(result)).toBe('a.ts\nb.ts\n\n(Showing 2 of 4 paths. Full sorted result stored at: /spill/glob-results.txt. Use the fake retrieval hint.)') expect(spill?.saves).toHaveLength(1) expect(spill?.saves[0]).toMatchObject({ @@ -587,11 +619,37 @@ describe('glob results', () => { const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }) expect(text(result)).toBe('vendor/a.ts\nsrc/d.ts\nguide/e.md\n\n' + '(Showing 3 of 6 paths, sampled across 3 of the 4 top-level entries this pattern matched ' - + 'instead of taken in modification-time order. Use the list tool to see what a directory contains. ' + + 'instead of taken in modification-time order. Narrow path to inspect a specific subtree. ' + 'The complete result could not be saved; narrow pattern or path to see more.)') }) - it('drops the list hint when the sample does reach every top-level entry', async () => { + it('samples relative to the explicit search root instead of its workdir prefix', async () => { + const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) + bash.handler = () => runResult([ + 'workspace/vendor/a.ts', + 'workspace/vendor/b.ts', + 'workspace/source/c.ts', + 'workspace/guides/d.md', + ].join('\n')) + const result = await call(ctx, 'glob', { pattern: '*', path: 'workspace' }, { agent: agent('/w') }) + expect(text(result)).toContain('workspace/vendor/a.ts\nworkspace/source/c.ts\nworkspace/guides/d.md') + expect(text(result)).toContain('sampled across 3 of the 3 top-level entries') + }) + + it('samples relative to an absolute search root after workdir display conversion', async () => { + const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) + bash.handler = () => runResult([ + '/w/workspace/vendor/a.ts', + '/w/workspace/vendor/b.ts', + '/w/workspace/source/c.ts', + '/w/workspace/guides/d.md', + ].join('\n')) + const result = await call(ctx, 'glob', { pattern: '*', path: '/w/workspace' }, { agent: agent('/w') }) + expect(text(result)).toContain('workspace/vendor/a.ts\nworkspace/source/c.ts\nworkspace/guides/d.md') + expect(text(result)).toContain('sampled across 3 of the 3 top-level entries') + }) + + it('drops the narrowing hint when the sample reaches every top-level entry', async () => { const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts'].join('\n')) expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) @@ -608,7 +666,7 @@ describe('glob results', () => { .toBe('vendor/a.ts\nvendor/b.ts\nsrc/c.ts') }) - it('keeps the plain footer for a flat result, where the sample IS the recency head', async () => { + it('keeps the plain footer for a flat result, where the sample is the modification-time head', async () => { const { ctx, bash } = await setup({ config: { globMaxResults: 2 } }) bash.handler = () => runResult('a.ts\nb.ts\nc.ts\n') expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) @@ -627,14 +685,14 @@ describe('glob results', () => { const { ctx, bash, spill } = await setup({ config: { globMaxResults: 1 }, spill: true }) ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, - value: { paths: ['replacement-a.ts', 'replacement-b.ts'] }, + value: { root: '.', paths: ['replacement-a.ts', 'replacement-b.ts'] }, })) bash.handler = () => runResult('old-a.ts\nold-b.ts\n') const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') }) if (result.isError) throw new Error('expected glob replacement success') - expect(result.value).toEqual({ paths: ['replacement-a.ts', 'replacement-b.ts'] }) + expect(result.value).toEqual({ root: '.', paths: ['replacement-a.ts', 'replacement-b.ts'] }) expect(text(result)).toContain('replacement-a.ts') expect(text(result)).not.toContain('old-a.ts') expect(spill?.saves).toHaveLength(0) @@ -648,7 +706,7 @@ describe('glob results', () => { parent: Symbol('run_code') as ToolExecutionToken, }) if (result.isError) throw new Error('expected glob success') - expect(result.value).toEqual({ paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] }) + expect(result.value).toEqual({ root: '.', paths: ['a.ts', 'b.ts', 'c.ts', 'd.ts'] }) expect(text(result)).toBe('a.ts\nb.ts\n\n(Showing 2 of 4 paths. The complete result could not be saved; narrow pattern or path to see more.)') expect(spill?.saves).toHaveLength(0) }) diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index e6f4ccf9c0..687b72d93e 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md -README.md: 08a4f74b928a38b92fdce5f6a03dd7c6c8f0af7c -README.zh.md: cdb45a12eb644e4882f7b92ac77b5bc7fc33f906 +README.md: 3917356b0e4cf48708f2769a6387249f795115ca +README.zh.md: b1ea0b42ed146241ee35d628825e0152c1bc1669 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 08a4f74b92..3917356b0e 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -19,7 +19,7 @@ All keys are optional; the defaults are the shipped listing and read caps. | Key | Default | Meaning | |---|---|---| -| `listMaxEntries` | `200` | Entries one `list` call renders inline; the footer still reports the complete directory's size and composition. | +| `listMaxEntries` | `200` | Maximum entries one `list` page returns; the footer reports complete size and composition plus a next offset when more remain. | | `readLimit` | `2000` | Default and maximum lines returned by one `read` call (the tool schema advertises it as the `limit` default). | | `readMaxLineLength` | `2000` | Characters kept per line before truncation (the suffix names the cap). | | `readMaxBytes` | `51200` | Byte cap on one `read` call's selected lines; overflow ends the window with a "capped" footer. | @@ -29,14 +29,14 @@ All keys are optional; the defaults are the shipped listing and read caps. | Tool | Arguments | Behavior | |---|---|---| -| `list` | `path?` | Direct children of one directory with their type, defaulting to the session workspace. Ordered directories first, then files, then non-regular children, each alphabetical, and capped at the configured `listMaxEntries` (200). | +| `list` | `path?`, `offset?` | One page of direct children with their type, defaulting to the session workspace and entry 1. Ordered directories first, then files, then non-regular children, each alphabetical; when more remain, continue from the footer's next offset. | | `read` | `file_path`, `offset?`, `limit?` | Line-numbered UTF-8 content with a pagination footer. `offset` is 1-based; `limit` defaults to and caps at the configured `readLimit` (2000). | | `write` | `file_path`, `content` | Create or fully replace a file. With the policy plugin: overwriting an existing file requires a prior `read` at the unchanged version; creating a new file does not. Without it: unconditional. | | `edit` | `file_path`, non-empty `old_string`, `new_string`, `replace_all?` | Literal replacement; unique match required unless `replace_all` is true. With the policy plugin: requires a prior `read` (any window) and the file unchanged since. Without it: unconditional. | Field names are snake_case to match Claude Code and existing harness tool schemas. -Canonical successes are `list` → `{ path, entries: [{ name, type: 'file' | 'directory' | 'other' }] }`, `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. +Canonical successes are `list` → `{ path, offset, entries: [{ name, type }], totalEntries, counts: { directories, files, other } }`, `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. `list.entries` is one bounded page; `type` is `file`, `directory`, or `other`, while its totals describe the complete directory. Native renderers preserve the listing/read envelopes and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. ## The tool is the executor; policy is an event gate @@ -68,7 +68,7 @@ Every request in this plugin's registration scope receives the independently reg ##### List guidance ```markdown -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. ``` ##### Read guidance @@ -115,11 +115,11 @@ Prefix-stable while the visible tool definitions and order are unchanged. Regist #### What the model sees -A successful listing is exactly ``, newline, `directory`, newline, ``, one line per entry, a blank line, one footer, and ``. A directory entry carries a trailing `/` and a non-regular child a trailing `@`; a regular file carries neither. The footer is exactly `(Empty directory)`, `( entries: directories, files)` — with `, other` appended only when such a child exists, and singulars where the count is one — or, when the view is capped, `(Showing of entries: directories, files. Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)`. The complete count and composition are stated whether or not the view was capped, so a partial listing can never read as a whole directory. +A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. Each entry name is a JSON string with `<`, `>`, and `&` additionally Unicode-escaped so filesystem text cannot forge the envelope; a directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. The footer is `(Empty directory)`, `( entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. #### Token effect -Listing output is capped by `listMaxEntries`; the retained call and result are resent until compaction. +Listing output and its canonical `entries` page are capped by `listMaxEntries`; the retained call and result are resent until compaction. #### KV Cache effect @@ -157,7 +157,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `path must be a non-empty string when given`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, and `offset is out of range for "" ( lines)`; provider and policy templates are quoted in their package READMEs. +Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `path must be a non-empty string when given`, `offset must be a positive integer`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, `offset is out of range for "" ( entries)`, and the corresponding ` lines` read error; provider and policy templates are quoted in their package READMEs. #### Token effect @@ -169,6 +169,6 @@ Append-only; newly visible content follows the reusable request prefix and does ## Known Limitations and Deferred Work -- **`list` reads one directory level and has no spill path** — recursion, pagination, and per-directory child counts are absent, and a listing past `listMaxEntries` is summarized by its footer rather than saved anywhere retrievable; the model lists a subdirectory instead. +- **`list` reads one directory level** — recursion and per-directory child counts are absent; offset pagination traverses only the current directory's ordered direct children. - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`. -- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)). +- **No timeout surface** — `list`/`read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)). diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index cdb45a12eb..b1ea0b42ed 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -19,7 +19,7 @@ await ctx.plugin(ToolFs) // this package — re | 键 | 默认值 | 含义 | |---|---|---| -| `listMaxEntries` | `200` | 一次 `list` 调用内联渲染的条目数；footer 仍会报告整个目录的规模与构成。 | +| `listMaxEntries` | `200` | 单个 `list` 页面返回的最大条目数；footer 会报告完整规模与构成，并在仍有条目时给出下一 offset。 | | `readLimit` | `2000` | 一次 `read` 调用返回的默认和最大行数（工具 schema 将其声明为 `limit` 默认值）。 | | `readMaxLineLength` | `2000` | 每行截断前保留的字符数（后缀会说明上限）。 | | `readMaxBytes` | `51200` | 一次 `read` 调用所选行的字节上限；溢出时以「已达上限」footer 结束窗口。 | @@ -29,14 +29,14 @@ await ctx.plugin(ToolFs) // this package — re | 工具 | 参数 | 行为 | |---|---|---| -| `list` | `path?` | 单个目录的直接子项及其类型，默认取会话工作区。顺序为先目录、再文件、最后非常规子项，各组内按字母序排列，并受配置的 `listMaxEntries`（200）限制。 | +| `list` | `path?`、`offset?` | 单个目录的一页直接子项及其类型，默认取会话工作区并从第 1 个条目开始。顺序为先目录、再文件、最后非常规子项，各组内按字母序排列；仍有条目时按 footer 给出的下一 offset 继续。 | | `read` | `file_path`、`offset?`、`limit?` | 带行号的 UTF-8 内容和分页 footer。`offset` 从 1 开始；`limit` 默认为配置的 `readLimit`（2000），上限也为该值。 | | `write` | `file_path`、`content` | 创建文件或完整替换文件。有政策插件时：覆盖现有文件要求先在未变版本上执行 `read`；创建新文件不需要。没有插件时：无条件执行。 | | `edit` | `file_path`、非空 `old_string`、`new_string`、`replace_all?` | 字面量替换；除非 `replace_all` 为 true，否则要求唯一匹配。有政策插件时：要求先执行 `read`（任何窗口），且文件此后未变。没有插件时：无条件执行。 | 字段名使用 snake_case，与 Claude Code 和现有 harness 工具 schema 一致。 -规范成功值分别为：`list` → `{ path, entries: [{ name, type: 'file' | 'directory' | 'other' }] }`，`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。Native 渲染器会保留下方带行号的读取结果和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 +规范成功值分别为：`list` → `{ path, offset, entries: [{ name, type }], totalEntries, counts: { directories, files, other } }`，`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。`list.entries` 是一个有界页面；`type` 为 `file`、`directory` 或 `other`，而总计信息描述的是完整目录。Native 渲染器会保留下方的列出/读取包络和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 ## 工具就是执行器；政策是事件门禁 @@ -68,7 +68,7 @@ await ctx.plugin(ToolFs) // this package — re ##### List 指导 ```markdown -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. Reach for glob or grep once you know the path pattern or the text you are looking for. +Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. ``` ##### Read 指导 @@ -115,11 +115,11 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -成功列出结果精确为 ``、换行、`directory`、换行、``、每个条目一行、一个空行、一条 footer 和 ``。目录条目带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。footer 精确为 `(Empty directory)`、`( entries: directories, files)`（仅当存在此类子项时才追加 `, other`，计数为一时使用单数形式），或在视图被截断时为 `(Showing of entries: directories, files. Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)`。无论视图是否被截断，都会说明完整计数与构成，因此部分列出结果绝不会被读成整个目录。 +成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。每个条目名都是 JSON 字符串，并额外对 `<`、`>` 和 `&` 做 Unicode 转义，使文件系统文本无法伪造包络；目录带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。footer 为 `(Empty directory)`、`( entries: directories, files)`（可选追加 `, other`），或 `(Showing entries - of : . Use offset= to continue.)`；最后一页省略继续提示。每一页都会说明完整计数与构成。 #### Token 影响 -列出输出受 `listMaxEntries` 限制；保留的调用与结果会反复发送，直到上下文压缩。 +列出输出及其规范 `entries` 页面受 `listMaxEntries` 限制；保留的调用与结果会反复发送，直到上下文压缩。 #### KV Cache 影响 @@ -157,7 +157,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`path must be a non-empty string when given`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file` 和 `offset is out of range for "" ( lines)`；提供方和政策模板在各自包的 README 中逐字列出。 +失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`path must be a non-empty string when given`、`offset must be a positive integer`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file`、`offset is out of range for "" ( entries)`，以及对应的 ` lines` 读取错误；提供方和政策模板在各自包的 README 中逐字列出。 #### Token 影响 @@ -169,6 +169,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces ## 已知限制与延期工作 -- **`list` 只读取一层目录，且没有溢出落盘路径**：不提供递归、分页和逐目录子项计数，超出 `listMaxEntries` 的部分只由 footer 概括，不会保存到任何可取回的位置；模型改为列出对应子目录。 +- **`list` 只读取一层目录**：不提供递归和逐目录子项计数；offset 分页只遍历当前目录中按顺序排列的直接子项。 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。 -- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见有意采用的 [fs 能力族立场](../README.md)）。 +- **没有超时接口**：`list`/`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见有意采用的 [fs 能力族立场](../README.md)）。 diff --git a/packages/fs/tool-fs/src/index.ts b/packages/fs/tool-fs/src/index.ts index c8376ed123..7890d5084d 100644 --- a/packages/fs/tool-fs/src/index.ts +++ b/packages/fs/tool-fs/src/index.ts @@ -25,7 +25,7 @@ export const inject = ['tools', 'fs', 'systemPrompt'] /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { - /** Maximum entries one `list` call renders inline; the footer still reports the complete count. */ + /** Maximum entries one `list` page returns; the footer still reports the complete count. */ listMaxEntries?: number /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number diff --git a/packages/fs/tool-fs/src/list-render.ts b/packages/fs/tool-fs/src/list-render.ts index d7a65cbb27..eef3392ec0 100644 --- a/packages/fs/tool-fs/src/list-render.ts +++ b/packages/fs/tool-fs/src/list-render.ts @@ -1,80 +1,111 @@ /** - * Pure listing presentation: order one directory's direct children so a capped - * view still shows the navigable structure, and render the model-facing - * envelope. Cordis-free and independently unit-tested, mirroring - * {@link module:@deepseek-ai/dsh-tool-fs/read-render}. + * Pure directory-listing presentation: order direct children, count complete + * composition, and render a bounded page without allowing filesystem text to + * forge the result envelope. * @module @deepseek-ai/dsh-tool-fs/list-render */ -/** Default and maximum number of entries one `list` call renders inline (the `listMaxEntries` config). */ +/** Default and maximum number of entries one `list` call returns (the `listMaxEntries` config). */ export const LIST_MAX_ENTRIES = 200 -/** One direct child in a rendered listing — the canonical entry shape the tool returns. */ +/** One direct child in a directory listing. */ export interface ListedEntry { /** Basename of the child inside the listed directory. */ name: string - /** Whether the child is a regular file, a directory, or something else (symlink, socket, device). */ + /** Whether the child is a regular file, a directory, or something else. */ type: 'file' | 'directory' | 'other' } +/** Complete-listing composition retained on every page. */ +export interface ListCounts { + directories: number + files: number + other: number +} + +/** Canonical bounded result returned by one `list` call. */ +export interface ListPage { + /** Backend display path of the listed directory. */ + path: string + /** 1-based index of the first returned entry. */ + offset: number + /** Current page in directory-first, name-sorted order. */ + entries: ListedEntry[] + /** Number of direct children in the complete listing. */ + totalEntries: number + /** Composition of the complete listing, not only this page. */ + counts: ListCounts +} + /** - * Order direct children so truncation cannot hide the directory tree: - * directories first, then files, then everything else, each group by name. - * - * The provider seam returns children in stable name order, which puts a - * subdirectory wherever the alphabet puts it; capping such a list can drop every - * subdirectory and leave the model believing a directory holds only files. This - * is the listing counterpart of the `glob` coverage footer. - * - * @param entries - the seam's direct children, in any order. - * @returns a new array in directory-first display order; the input is not mutated. + * Sort directories before files before other entries, each group by name. + * @param entries - direct children in provider order. + * @returns a new directory-first array without mutating `entries`. */ export function orderEntries(entries: readonly T[]): T[] { const rank = { directory: 0, file: 1, other: 2 } return [...entries].sort((a, b) => rank[a.type] - rank[b.type] || a.name.localeCompare(b.name)) } -/** `1 directory` / `4 directories` — a count the model reads as prose, not as `1 directorie(s)`. */ +/** + * Count every entry type in a complete listing. + * @param entries - every direct child in the listed directory. + * @returns the complete directory/file/other composition. + */ +export function countEntries(entries: readonly ListedEntry[]): ListCounts { + const counts: ListCounts = { directories: 0, files: 0, other: 0 } + for (const entry of entries) { + if (entry.type === 'directory') counts.directories += 1 + else if (entry.type === 'file') counts.files += 1 + else counts.other += 1 + } + return counts +} + +/** `1 directory` / `4 directories`. */ function count(n: number, singular: string, plural: string): string { return `${n} ${n === 1 ? singular : plural}` } -/** The ` directories, files[, other]` breakdown; the `other` clause appears only when non-empty. */ -function breakdown(entries: readonly ListedEntry[]): string { - const directories = entries.filter(entry => entry.type === 'directory').length - const other = entries.filter(entry => entry.type === 'other').length - const files = entries.length - directories - other - const parts = [count(directories, 'directory', 'directories'), count(files, 'file', 'files')] - if (other > 0) parts.push(`${other} other`) +/** Complete-listing composition as model-facing prose. */ +function breakdown(counts: ListCounts): string { + const parts = [ + count(counts.directories, 'directory', 'directories'), + count(counts.files, 'file', 'files'), + ] + if (counts.other > 0) parts.push(`${counts.other} other`) return parts.join(', ') } +/** JSON-string encode untrusted filesystem text and neutralize envelope tags. */ +function encodeFilesystemText(value: string): string { + return JSON.stringify(value) + .replaceAll('<', '\\u003c') + .replaceAll('>', '\\u003e') + .replaceAll('&', '\\u0026') +} + /** - * Render the model-facing `list` result: the displayed entries, then a footer - * that always states the COMPLETE listing's size and composition, so a capped - * view can never read as the whole directory. + * Render one bounded listing page. Entry names are JSON strings followed by `/` + * for directories or `@` for non-regular children; regular files have no suffix. + * The footer carries complete composition and an exact continuation offset. * - * Directories carry a trailing `/` and non-regular children a trailing `@`, so - * the model can tell what it may descend into without a second call. - * - * @param displayPath - the resolved directory as the backend displays it. - * @param entries - the complete listing, already in {@link orderEntries} order. - * @param maxEntries - how many entries to show inline; the rest are summarized by the footer. - * @returns the model-facing text. + * @param page - the canonical listing page. + * @returns the model-facing directory envelope. */ -export function formatListOutput(displayPath: string, entries: readonly ListedEntry[], maxEntries: number): string { - const shown = entries.slice(0, maxEntries) +export function formatListOutput(page: ListPage): string { const suffix = { directory: '/', file: '', other: '@' } - const footer = shown.length < entries.length - ? `(Showing ${shown.length} of ${count(entries.length, 'entry', 'entries')}: ${breakdown(entries)}. ` - + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)' - : entries.length === 0 - ? '(Empty directory)' - : `(${count(entries.length, 'entry', 'entries')}: ${breakdown(entries)})` - const body = shown.length > 0 - ? `${shown.map(entry => `${entry.name}${suffix[entry.type]}`).join('\n')}\n\n${footer}` + const end = page.entries.length === 0 ? 0 : page.offset + page.entries.length - 1 + const footer = page.totalEntries === 0 + ? '(Empty directory)' + : page.offset > 1 || page.entries.length < page.totalEntries + ? `(Showing entries ${page.offset}-${end} of ${page.totalEntries}: ${breakdown(page.counts)}.` + + (end < page.totalEntries ? ` Use offset=${end + 1} to continue.)` : ')') + : `(${count(page.totalEntries, 'entry', 'entries')}: ${breakdown(page.counts)})` + const body = page.entries.length > 0 + ? `${page.entries.map(entry => `${encodeFilesystemText(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` : footer - return `${displayPath} + return `${encodeFilesystemText(page.path)} directory ${body} diff --git a/packages/fs/tool-fs/src/list.ts b/packages/fs/tool-fs/src/list.ts index de6c6d1ddd..270e2803b8 100644 --- a/packages/fs/tool-fs/src/list.ts +++ b/packages/fs/tool-fs/src/list.ts @@ -13,14 +13,15 @@ import type { Context } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' import type { GenericCallView } from '@deepseek-ai/dsh-tools' +import { FsError } from '@deepseek-ai/dsh-fs' import type {} from '@deepseek-ai/dsh-fs' import type {} from '@deepseek-ai/dsh-system-prompt' -import { formatListOutput, orderEntries } from './list-render.ts' +import { countEntries, formatListOutput, orderEntries } from './list-render.ts' import { sessionResolveOptions } from './session-cwd.ts' /** Resolved list-tool caps — plugin config after defaulting (see `Config` in index.ts). */ export interface ListToolCaps { - /** Maximum entries rendered inline; the footer still reports the complete listing's size. */ + /** Maximum entries returned on one page; the footer still reports complete size and composition. */ maxEntries: number } @@ -28,6 +29,8 @@ export interface ListToolCaps { export interface ListInput { /** Directory to list; `.` means the calling agent's session workspace. */ path: string + /** 1-based first entry to return from the directory-first ordering. */ + offset: number } /** @@ -36,23 +39,26 @@ export interface ListInput { * needs no argument at all. * * @param args - the schema-validated `list` arguments. - * @returns the accepted input with `path` defaulted. + * @returns the accepted input with `path` and `offset` defaulted. */ -export function parseListArgs(args: { path?: string }): ListInput { +export function parseListArgs(args: { path?: string; offset?: number }): ListInput { if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given') - return { path: args.path ?? '.' } + const offset = args.offset ?? 1 + if (!Number.isInteger(offset) || offset < 1) throw new Error('offset must be a positive integer') + return { path: args.path ?? '.', offset } } /** * Pending-call presentation: a generic card titled by the directory, with a * follow-along location so a capable editor can reveal it. * - * @param args - the raw tool arguments; only `path` is read. + * @param args - the raw tool arguments; `path` and `offset` feed the title. * @returns the generic card view shown while the call runs. */ -export function presentListCall(args: { path?: string }): GenericCallView { +export function presentListCall(args: { path?: string; offset?: number }): GenericCallView { const path = args.path ?? '.' - return { card: 'generic', title: `List ${path}`, kind: 'read', locations: [{ path }] } + const window = args.offset !== undefined ? ` (from entry ${args.offset})` : '' + return { card: 'generic', title: `List ${path}${window}`, kind: 'read', locations: [{ path }] } } /** @@ -67,16 +73,17 @@ export function applyListTool(ctx: Context, caps: ListToolCaps): void { order: 99, text: 'Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, ' + 'and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. ' - + 'Reach for glob or grep once you know the path pattern or the text you are looking for.', + + 'When a result is capped, continue with the offset named in its footer.', }) ctx.tools.register(defineTool({ name: 'list', description: 'List the direct children of one directory, with their type. ' - + `Entries are directories first, then files, each alphabetical; the first ${caps.maxEntries} are returned inline and the footer reports the complete count. ` - + 'Unlike glob, this shows subdirectories, so it is how to see what a directory contains.', + + `Entries are directories first, then files, each alphabetical; up to ${caps.maxEntries} are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. ` + + 'It includes subdirectories and is the tool for seeing one directory\'s contents.', parameters: { path: { type: 'string', description: 'Directory to list. Defaults to the session workspace; a relative path resolves against it.' }, + offset: { type: 'number', description: '1-based first entry to return. Defaults to 1; use the footer value to continue.' }, }, output: { schema: { @@ -84,6 +91,7 @@ export function applyListTool(ctx: Context, caps: ListToolCaps): void { additionalProperties: false, properties: { path: { type: 'string', required: true }, + offset: { type: 'integer', required: true }, entries: { type: 'array', required: true, @@ -96,9 +104,20 @@ export function applyListTool(ctx: Context, caps: ListToolCaps): void { }, }, }, + totalEntries: { type: 'integer', required: true }, + counts: { + type: 'object', + required: true, + additionalProperties: false, + properties: { + directories: { type: 'integer', required: true }, + files: { type: 'integer', required: true }, + other: { type: 'integer', required: true }, + }, + }, }, }, - render: (_args, value) => [{ type: 'text', text: formatListOutput(value.path, value.entries, caps.maxEntries) }], + render: (_args, value) => [{ type: 'text', text: formatListOutput(value) }], }, // Listing reads directory metadata only: no content, no version recorded, // nothing a concurrent call could observe out of order. @@ -109,10 +128,21 @@ export function applyListTool(ctx: Context, caps: ListToolCaps): void { // No stat first: the seam already answers absence with FS_NOT_FOUND and a // non-directory target with FS_NOT_DIRECTORY, so a probe would only add a // round-trip and a second source of truth. (0 stat.) - const entries = await ctx.fs.listDir(target, exec.signal) + const entries = orderEntries(await ctx.fs.listDir(target, exec.signal)) + if (input.offset > entries.length && !(entries.length === 0 && input.offset === 1)) { + throw new FsError( + `offset ${input.offset} is out of range for "${target.displayPath}" (${entries.length} entries)`, + 'FS_NOT_FOUND', + ) + } return { path: target.displayPath, - entries: orderEntries(entries).map(({ name, type }) => ({ name, type })), + offset: input.offset, + entries: entries + .slice(input.offset - 1, input.offset - 1 + caps.maxEntries) + .map(({ name, type }) => ({ name, type })), + totalEntries: entries.length, + counts: countEntries(entries), } }, presentCall: presentListCall, diff --git a/packages/fs/tool-fs/tests/list-render.spec.ts b/packages/fs/tool-fs/tests/list-render.spec.ts index 3d0a3ac5ce..2c26c1be2c 100644 --- a/packages/fs/tool-fs/tests/list-render.spec.ts +++ b/packages/fs/tool-fs/tests/list-render.spec.ts @@ -4,11 +4,22 @@ */ import { describe, expect, it } from 'vitest' -import { formatListOutput, orderEntries } from '../src/list-render.ts' -import type { ListedEntry } from '../src/list-render.ts' +import { countEntries, formatListOutput, orderEntries } from '../src/list-render.ts' +import type { ListedEntry, ListPage } from '../src/list-render.ts' const entry = (name: string, type: ListedEntry['type'] = 'file'): ListedEntry => ({ name, type }) +function page(entries: ListedEntry[], options: { offset?: number; totalEntries?: number; all?: ListedEntry[] } = {}): ListPage { + const all = options.all ?? entries + return { + path: '/w', + offset: options.offset ?? 1, + entries, + totalEntries: options.totalEntries ?? all.length, + counts: countEntries(all), + } +} + describe('orderEntries', () => { it('groups directories, then files, then other, each by name', () => { const ordered = orderEntries([ @@ -31,36 +42,35 @@ describe('orderEntries', () => { describe('formatListOutput', () => { it('marks directories and non-regular children, and counts the whole listing', () => { - expect(formatListOutput('/w', [entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')], 10)).toBe(`/w + expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`"/w" directory -src/ -a.txt -sock@ +"src"/ +"a.txt" +"sock"@ (3 entries: 1 directory, 1 file, 1 other) `) }) it('omits the "other" clause when every child is a file or a directory', () => { - expect(formatListOutput('/w', [entry('a.txt'), entry('b.txt')], 10)).toContain('(2 entries: 0 directories, 2 files)') + expect(formatListOutput(page([entry('a.txt'), entry('b.txt')]))).toContain('(2 entries: 0 directories, 2 files)') }) it('says a one-entry listing in the singular', () => { - expect(formatListOutput('/w', [entry('only', 'directory')], 10)).toContain('(1 entry: 1 directory, 0 files)') + expect(formatListOutput(page([entry('only', 'directory')]))).toContain('(1 entry: 1 directory, 0 files)') }) it('states the complete size and composition when the view is capped', () => { const entries = [entry('src', 'directory'), ...Array.from({ length: 5 }, (_, i) => entry(`f${i}.txt`))] - const rendered = formatListOutput('/w', entries, 2) - expect(rendered).toContain('src/\nf0.txt\n') + const rendered = formatListOutput(page(entries.slice(0, 2), { totalEntries: entries.length, all: entries })) + expect(rendered).toContain('"src"/\n"f0.txt"\n') expect(rendered).not.toContain('f2.txt') - expect(rendered).toContain('(Showing 2 of 6 entries: 1 directory, 5 files. ' - + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)') + expect(rendered).toContain('(Showing entries 1-2 of 6: 1 directory, 5 files. Use offset=3 to continue.)') }) it('renders an empty directory as a footer alone', () => { - expect(formatListOutput('/w', [], 10)).toBe(`/w + expect(formatListOutput(page([]))).toBe(`"/w" directory (Empty directory) diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 66f88a6348..74268b72ca 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -162,6 +162,7 @@ describe('registration', () => { const { ctx } = await setup() const prompt = renderPrompt(await ctx.systemPrompt.assemble()) expect(prompt).toContain('Use the list tool') + expect(prompt).not.toContain('glob or grep') expect(prompt).toContain('Use the read tool') expect(prompt).toContain('Use the write tool') expect(prompt).toContain('Use the edit tool') @@ -220,20 +221,23 @@ describe('list tool', () => { // model see the same ordering contract. expect(result.value).toEqual({ path: '/abs/.', + offset: 1, entries: [ { name: 'archive', type: 'directory' }, { name: 'zeroomega-3.3.23', type: 'directory' }, { name: 'notes.md', type: 'file' }, { name: 'link-to-nowhere', type: 'other' }, ], + totalEntries: 4, + counts: { directories: 2, files: 1, other: 1 }, }) - expect(text(result)).toBe(`/abs/. + expect(text(result)).toBe(`"/abs/." directory -archive/ -zeroomega-3.3.23/ -notes.md -link-to-nowhere@ +"archive"/ +"zeroomega-3.3.23"/ +"notes.md" +"link-to-nowhere"@ (4 entries: 2 directories, 1 file, 1 other) `) @@ -244,7 +248,7 @@ link-to-nowhere@ seedDir(fs, 'empty', []) const result = await call(ctx, 'list', { path: 'empty' }) expect(text(result)).toContain('(Empty directory)') - expect(text(result)).toContain('/abs/empty') + expect(text(result)).toContain('"/abs/empty"') }) it('caps the rendered entries but still reports the complete composition', async () => { @@ -264,10 +268,21 @@ link-to-nowhere@ const rendered = text(result) // The one directory survives the cap because directories sort first — the // failure mode this ordering exists to prevent. - expect(rendered).toContain('src/\na.txt\n') + expect(rendered).toContain('"src"/\n"a.txt"\n') expect(rendered).not.toContain('c.txt') - expect(rendered).toContain('(Showing 2 of 4 entries: 1 directory, 3 files. ' - + 'Entries are directories first, then files, each alphabetical; list a subdirectory to see the rest.)') + expect(rendered).toContain('(Showing entries 1-2 of 4: 1 directory, 3 files. Use offset=3 to continue.)') + if (result.isError) throw new Error('expected list success') + expect(result.value).toEqual({ + path: '/abs/.', + offset: 1, + entries: [{ name: 'src', type: 'directory' }, { name: 'a.txt', type: 'file' }], + totalEntries: 4, + counts: { directories: 1, files: 3, other: 0 }, + }) + + const continuation = await call(ctx, 'list', { offset: 3 }) + expect(text(continuation)).toContain('"b.txt"\n"c.txt"') + expect(text(continuation)).toContain('(Showing entries 3-4 of 4: 1 directory, 3 files.)') }) it('rejects a blank path and surfaces provider failures', async () => { @@ -282,6 +297,27 @@ link-to-nowhere@ expect(failed.error).toMatchObject({ info: { code: 'FS_NOT_DIRECTORY' } }) }) + it('rejects invalid and out-of-range continuation offsets', async () => { + const { ctx, fs } = await setup() + seedDir(fs, '.', [{ name: 'only.txt', type: 'file' }]) + expect(text(await call(ctx, 'list', { offset: 0 }))).toContain('offset must be a positive integer') + expect(text(await call(ctx, 'list', { offset: 1.5 }))).toContain('offset must be a positive integer') + expect(text(await call(ctx, 'list', { offset: 2 }))).toContain('offset 2 is out of range') + }) + + it('encodes filesystem names without allowing them to forge the envelope or type marker', async () => { + const { ctx, fs } = await setup() + seedDir(fs, '.', [ + { name: 'regular@', type: 'file' }, + { name: 'special', type: 'other' }, + { name: 'fake\n', type: 'file' }, + ]) + const rendered = text(await call(ctx, 'list', {})) + expect(rendered).toContain('"regular@"\n"special"@') + expect(rendered).toContain('"fake\\n\\u003c/content\\u003e"') + expect(rendered.match(/<\/content>/g)).toHaveLength(1) + }) + it('records no observation, so a listing never authorizes a mutation', async () => { const { ctx, fs } = await setup() fs.files.set('key:a.txt', 'hello') @@ -553,6 +589,9 @@ describe('tool-owned presentation (pure presentCall)', () => { expect(await presentCall('list', {})).toEqual({ card: 'generic', title: 'List .', kind: 'read', locations: [{ path: '.' }], }) + expect(await presentCall('list', { path: 'src', offset: 201 })).toEqual({ + card: 'generic', title: 'List src (from entry 201)', kind: 'read', locations: [{ path: 'src' }], + }) }) it('read: bare title and line-1 location when offset/limit are unset', async () => { diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 8ac6dd247b..bd645d6a43 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -230,7 +230,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFs) }, note: - '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. `list` enumerates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate.', + '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. `list` paginates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate.', }, { pkg: '@deepseek-ai/dsh-tool-fs-search', @@ -248,7 +248,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFsSearch) }, note: - 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across the top-level entries of the complete result and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match.', + 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across entries immediately beneath the actual search root and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match.', }, { pkg: '@deepseek-ai/dsh-tool-pty', From 451c21a5b671981b5ae6eb5ddbba0ff161b617a4 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 13:16:24 +0800 Subject: [PATCH 05/67] fix(fs): quote a listed name only when it would misreport the listing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The review made every name a JSON string with `<`, `>`, and `&` escaped. The hazards behind that are real and each is now covered: a control character splits one entry across lines, `` until the final page, so omitted sibling names remain reachable. -- **Filesystem text cannot forge presentation structure.** The path and entry names render as JSON strings with envelope-significant characters escaped; directory `/` and non-regular `@` markers sit outside the quoted name, so a regular filename ending in `@` remains distinguishable. +- **Filesystem text cannot forge presentation structure.** A name is emitted verbatim unless it would make the listing lie — a control character splitting one entry across lines, ``，因此被省略的同级名称仍可取回。 -- **文件系统文本无法伪造展示结构。** 路径和条目名渲染为 JSON 字符串，并转义对包络有意义的字符；目录 `/` 与非常规子项 `@` 标记位于带引号名称之外，因此以 `@` 结尾的常规文件名仍可区分。 +- **文件系统文本无法伪造展示结构。** 条目名默认原样输出；只有当它会让列出结果失真时才转为 JSON 字符串并中和 `\"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\"\ndirectory\n\n\"docs\"/\n\"src\"/\n\"package.json\"\n\"README.txt\"\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} +{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\ndirectory\n\ndocs/\nsrc/\npackage.json\nREADME.txt\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} {"type":"step/end","seq":51,"time":1785159115950,"data":{"turn":1,"step":1}} {"type":"step/start","seq":52,"time":1785159115951,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":53,"time":1785159116889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index 687b72d93e..3e7c989373 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md -README.md: 3917356b0e4cf48708f2769a6387249f795115ca -README.zh.md: b1ea0b42ed146241ee35d628825e0152c1bc1669 +README.md: 8fdd54fb36353ca6c1dbcf71cdad38c4bcf26b7d +README.zh.md: 567c8e0df58950369c59785859948e32cbccdef4 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 3917356b0e..8fdd54fb36 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -115,7 +115,7 @@ Prefix-stable while the visible tool definitions and order are unchanged. Regist #### What the model sees -A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. Each entry name is a JSON string with `<`, `>`, and `&` additionally Unicode-escaped so filesystem text cannot forge the envelope; a directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. The footer is `(Empty directory)`, `( entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. +A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. A directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. A name is emitted verbatim unless it could make the listing say something untrue — a control character, a leading `"`, a backslash, ` entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. #### Token effect diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index b1ea0b42ed..567c8e0df5 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -115,7 +115,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。每个条目名都是 JSON 字符串，并额外对 `<`、`>` 和 `&` 做 Unicode 转义，使文件系统文本无法伪造包络；目录带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。footer 为 `(Empty directory)`、`( entries: directories, files)`（可选追加 `, other`），或 `(Showing entries - of : . Use offset= to continue.)`；最后一页省略继续提示。每一页都会说明完整计数与构成。 +成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。目录带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。条目名默认原样输出，只有当它可能让列出结果失真时才转为 JSON 字符串并中和 ` entries: directories, files)`（可选追加 `, other`），或 `(Showing entries - of : . Use offset= to continue.)`；最后一页省略继续提示。每一页都会说明完整计数与构成。 #### Token 影响 diff --git a/packages/fs/tool-fs/src/list-render.ts b/packages/fs/tool-fs/src/list-render.ts index eef3392ec0..86b57d02b3 100644 --- a/packages/fs/tool-fs/src/list-render.ts +++ b/packages/fs/tool-fs/src/list-render.ts @@ -77,17 +77,41 @@ function breakdown(counts: ListCounts): string { return parts.join(', ') } -/** JSON-string encode untrusted filesystem text and neutralize envelope tags. */ -function encodeFilesystemText(value: string): string { - return JSON.stringify(value) - .replaceAll('<', '\\u003c') - .replaceAll('>', '\\u003e') - .replaceAll('&', '\\u0026') +/** + * Names this renderer cannot emit verbatim, because POSIX allows every byte but + * `/` and NUL in a name and each of these would make the listing say something + * untrue: + * + * - a control character (a newline above all) splits one entry across lines; + * - ` 0 - ? `${page.entries.map(entry => `${encodeFilesystemText(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` + ? `${page.entries.map(entry => `${renderName(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` : footer - return `${encodeFilesystemText(page.path)} + return `${renderName(page.path)} directory ${body} diff --git a/packages/fs/tool-fs/tests/list-render.spec.ts b/packages/fs/tool-fs/tests/list-render.spec.ts index 2c26c1be2c..792c91bd18 100644 --- a/packages/fs/tool-fs/tests/list-render.spec.ts +++ b/packages/fs/tool-fs/tests/list-render.spec.ts @@ -42,12 +42,12 @@ describe('orderEntries', () => { describe('formatListOutput', () => { it('marks directories and non-regular children, and counts the whole listing', () => { - expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`"/w" + expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`/w directory -"src"/ -"a.txt" -"sock"@ +src/ +a.txt +sock@ (3 entries: 1 directory, 1 file, 1 other) `) @@ -64,13 +64,13 @@ describe('formatListOutput', () => { it('states the complete size and composition when the view is capped', () => { const entries = [entry('src', 'directory'), ...Array.from({ length: 5 }, (_, i) => entry(`f${i}.txt`))] const rendered = formatListOutput(page(entries.slice(0, 2), { totalEntries: entries.length, all: entries })) - expect(rendered).toContain('"src"/\n"f0.txt"\n') + expect(rendered).toContain('src/\nf0.txt\n') expect(rendered).not.toContain('f2.txt') expect(rendered).toContain('(Showing entries 1-2 of 6: 1 directory, 5 files. Use offset=3 to continue.)') }) it('renders an empty directory as a footer alone', () => { - expect(formatListOutput(page([]))).toBe(`"/w" + expect(formatListOutput(page([]))).toBe(`/w directory (Empty directory) diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 74268b72ca..1ab91fb665 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -231,13 +231,13 @@ describe('list tool', () => { totalEntries: 4, counts: { directories: 2, files: 1, other: 1 }, }) - expect(text(result)).toBe(`"/abs/." + expect(text(result)).toBe(`/abs/. directory -"archive"/ -"zeroomega-3.3.23"/ -"notes.md" -"link-to-nowhere"@ +archive/ +zeroomega-3.3.23/ +notes.md +link-to-nowhere@ (4 entries: 2 directories, 1 file, 1 other) `) @@ -248,7 +248,7 @@ describe('list tool', () => { seedDir(fs, 'empty', []) const result = await call(ctx, 'list', { path: 'empty' }) expect(text(result)).toContain('(Empty directory)') - expect(text(result)).toContain('"/abs/empty"') + expect(text(result)).toContain('/abs/empty') }) it('caps the rendered entries but still reports the complete composition', async () => { @@ -268,7 +268,7 @@ describe('list tool', () => { const rendered = text(result) // The one directory survives the cap because directories sort first — the // failure mode this ordering exists to prevent. - expect(rendered).toContain('"src"/\n"a.txt"\n') + expect(rendered).toContain('src/\na.txt\n') expect(rendered).not.toContain('c.txt') expect(rendered).toContain('(Showing entries 1-2 of 4: 1 directory, 3 files. Use offset=3 to continue.)') if (result.isError) throw new Error('expected list success') @@ -281,7 +281,7 @@ describe('list tool', () => { }) const continuation = await call(ctx, 'list', { offset: 3 }) - expect(text(continuation)).toContain('"b.txt"\n"c.txt"') + expect(text(continuation)).toContain('b.txt\nc.txt') expect(text(continuation)).toContain('(Showing entries 3-4 of 4: 1 directory, 3 files.)') }) @@ -313,8 +313,10 @@ describe('list tool', () => { { name: 'fake\n', type: 'file' }, ]) const rendered = text(await call(ctx, 'list', {})) - expect(rendered).toContain('"regular@"\n"special"@') - expect(rendered).toContain('"fake\\n\\u003c/content\\u003e"') + // A regular file really named `regular@` must not read as a socket named + // `regular`, and a newline in a name must not become a second entry. + expect(rendered).toContain('"regular@"\nspecial@') + expect(rendered).toContain('"fake\\n<\\/content>"') expect(rendered.match(/<\/content>/g)).toHaveLength(1) }) From 57cf1379186ef04c56c2688dbb48ebed8bc2d0c8 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 14:42:59 +0800 Subject: [PATCH 06/67] fix(fs-search): keep broad glob samples representative Remove the duplicate model-facing list tool from this branch; directory orientation remains available through bash ls. Keep the glob sampling fix, add a real ACP composition snapshot, and narrow the decision record to the shipped bug fix. --- .../2026-07-27-glob-sampling.i18n.yaml} | 6 +- .../bug-fix/2026-07-27-glob-sampling.md | 45 ++ .../bug-fix/2026-07-27-glob-sampling.zh.md | 45 ++ .../2026-07-27-directory-listing-tool.md | 109 ---- .../2026-07-27-directory-listing-tool.zh.md | 109 ---- docs/config-catalog.md | 4 +- docs/tool-catalog.md | 4 +- .../acp-agent/fs-search.cordis.snapshot.yml | 24 + examples/acp-agent/fs-search.cordis.yml | 13 + examples/acp-agent/tests/acp.snapshot.ts | 19 +- .../acp-agent/tests/fixtures/fs-search-bin/rg | 8 + .../system-prompt.expected.md | 23 - .../tool-schemas.expected.json | 17 - .../both-mode-turn/system-prompt.expected.md | 23 - .../both-mode-turn/tool-schemas.expected.json | 17 - .../code-mode-turn/system-prompt.expected.md | 23 - .../system-prompt.expected.md | 23 - .../system-prompt.expected.md | 2 - .../tool-schemas.expected.json | 17 - .../snapshots/fs-glob-sampling/input.json | 7 + .../snapshots/fs-glob-sampling/session.jsonl | 24 + .../stdout.expected.jsonl | 2 +- .../system-prompt.expected.md | 29 + .../tool-schemas.expected.json | 517 ++++++++++++++++++ .../tests/snapshots/fs-list/input.json | 7 - .../tests/snapshots/fs-list/session.jsonl | 32 -- .../snapshots/fs-list/workspace/README.txt | 1 - .../fs-list/workspace/docs/guide.txt | 1 - .../snapshots/fs-list/workspace/package.json | 1 - .../snapshots/fs-list/workspace/src/index.txt | 1 - .../lsp-definition/system-prompt.expected.md | 2 - .../lsp-definition/tool-schemas.expected.json | 17 - .../pty-tools/system-prompt.expected.md | 2 - .../pty-tools/tool-schemas.expected.json | 17 - .../system-prompt.expected.md | 2 - .../tool-schemas.expected.json | 17 - .../skill-load/system-prompt.expected.md | 2 - .../skill-load/tool-schemas.expected.json | 17 - .../text-turn/system-prompt.expected.md | 2 - .../text-turn/tool-schemas.expected.json | 17 - .../web-fetch/system-prompt.expected.md | 2 - .../web-fetch/tool-schemas.expected.json | 17 - .../system-prompt.expected.md | 2 - .../tool-schemas.expected.json | 17 - .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- packages/fs/tool-fs/README.i18n.yaml | 6 +- packages/fs/tool-fs/README.md | 45 +- packages/fs/tool-fs/README.zh.md | 45 +- packages/fs/tool-fs/package.json | 2 +- packages/fs/tool-fs/src/index.ts | 18 +- packages/fs/tool-fs/src/list-render.ts | 137 ----- packages/fs/tool-fs/src/list.ts | 150 ----- packages/fs/tool-fs/tests/list-render.spec.ts | 79 --- packages/fs/tool-fs/tests/tools.spec.ts | 172 +----- scripts/gen-tool-catalog.ts | 4 +- 55 files changed, 775 insertions(+), 1171 deletions(-) rename .agents/notes/implemented/{feature/2026-07-27-directory-listing-tool.i18n.yaml => bug-fix/2026-07-27-glob-sampling.i18n.yaml} (58%) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md delete mode 100644 .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md delete mode 100644 .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.zh.md create mode 100644 examples/acp-agent/fs-search.cordis.snapshot.yml create mode 100644 examples/acp-agent/fs-search.cordis.yml create mode 100755 examples/acp-agent/tests/fixtures/fs-search-bin/rg create mode 100644 examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json create mode 100644 examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl rename examples/acp-agent/tests/snapshots/{fs-list => fs-glob-sampling}/stdout.expected.jsonl (90%) create mode 100644 examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md create mode 100644 examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/input.json delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/session.jsonl delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/package.json delete mode 100644 examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt delete mode 100644 packages/fs/tool-fs/src/list-render.ts delete mode 100644 packages/fs/tool-fs/src/list.ts delete mode 100644 packages/fs/tool-fs/tests/list-render.spec.ts diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml similarity index 58% rename from .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml rename to .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml index 9bf1c8cb73..88e4ec9fc8 100644 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md -2026-07-27-directory-listing-tool.md: fd8e8fb22d0b75a4d457e800296fa3ce2c2b5bd5 -2026-07-27-directory-listing-tool.zh.md: 7d4e797878858ea1ca09f1eea6c6a3953c9abae6 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md +2026-07-27-glob-sampling.md: c583f0cd8110684a94d0cd04f5cf2ae861ce7aa3 +2026-07-27-glob-sampling.zh.md: 97025a7714237fc716dee745a858140cd783ba2d diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md new file mode 100644 index 0000000000..c583f0cd81 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md @@ -0,0 +1,45 @@ +# Agent Note: Sample over-cap glob results across the tree + +Status: implemented + +English | [中文](2026-07-27-glob-sampling.zh.md) + +## Problem + +Asked what a workspace contained, an agent described one subfolder as if it were the whole project. The workspace held 22 top-level entries and 11,485 files. `glob {"pattern":"*"}` matched 10,030 paths, but all 100 inline paths sat under one recently unpacked subtree, so the model never saw the other 21 entries. + +Three individually valid behaviors composed into the false impression. A glob without `/` matches basenames at any depth, so `*` means every file in the tree rather than the shell's current-directory expansion. Ripgrep's `--sort=modified` is ascending, so an archive's restored old timestamps put that subtree first. The inline page then took the head of that order without saying that it represented only one concentrated slice. + +## Decision + +A result that fits within `globMaxResults` remains complete and byte-for-byte modification-time ordered. An over-cap result is sampled round-robin across the complete result's top-level entries: every entry receives one slot before any receives a second, exhausted groups drop out, and relative order remains stable within each group. Grouping is relative to the actual search root, including an explicit `path`. + +The footer states that the page is a cross-entry sample rather than the modification-time head, reports how many top-level entries it reaches when that fact adds information, and preserves the complete sorted list in the spill artifact. When more top-level entries exist than inline slots, it tells the model to narrow `path`. + +The prompt and schema also state that a pattern without `/` matches at any depth and that glob returns files, never directory entries. Directory orientation remains ordinary shell work in deployments that expose the model-facing bash tool: use `ls` for one directory, and glob for a named file-path pattern across the tree. `ctx.fs.listDir` remains an internal provider primitive used by skill discovery; this decision adds no model-facing `list` tool. + +## Alternatives considered + +**Keep the modification-time head and only warn about concentration.** Rejected after measuring the failure shape. A warning asks the model to distrust the only paths it received; representative data fixes the answer directly. + +**Sample every result.** Rejected. A complete result loses nothing to truncation, so modification-time order remains useful for age-oriented questions. Sampling begins only when the head stops describing the whole. + +**Switch to newest-first order.** Rejected. It merely changes which concentrated subtree can dominate and removes the existing oldest-first contract without making a capped page representative. + +**Sample only past a skew threshold.** Rejected. No current evidence supports a deployment-wide threshold, and the model could not know which ordering contract applied. The existing cap is the explainable transition. + +**Balance recursively below the top level.** Deferred. First-segment balance fixes the observed failure; deeper balancing needs an unsupported depth-versus-breadth policy. + +**Add a model-facing `list` tool.** Rejected after implementation review. The default coding composition already exposes general bash and the model understands `ls`; a duplicate tool would add permanent schema/prompt tokens plus ordering, pagination, symlink, escaping, UI, and snapshot contracts without a distinct security or policy benefit. Thin deployments without a model-facing bash tool do not gain directory orientation from this change. + +**Reject `*` or silently anchor separator-free patterns.** Rejected. The same basename-at-any-depth behavior makes `*.ts` useful across a tree. Documenting the rule preserves working ripgrep semantics. + +## Consequences + +An over-cap glob page no longer answers age-order questions from its inline paths; its footer says so, and the spill artifact retains the complete sorted view. Sampling balances only the first segment beneath the search root, so a deeper hot subtree can still dominate within one top-level entry. + +The tool surface does not grow. The fix changes glob's prompt, schema description, canonical output (`root` records the sampling basis), and over-cap Native rendering while leaving fitting results unchanged. + +## Testing + +Package tests pin concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario boots the real Loader/app/sandbox-bash composition and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head. diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md new file mode 100644 index 0000000000..97025a7714 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md @@ -0,0 +1,45 @@ +# Agent Note: 跨目录树采样超出上限的 glob 结果 + +Status: implemented + +[English](2026-07-27-glob-sampling.md) | 中文 + +## 问题 + +用户询问工作区包含什么内容时，一个 agent（智能体）把某个子文件夹描述成了整个项目。该工作区有 22 个顶层条目和 11,485 个文件。`glob {"pattern":"*"}` 匹配到 10,030 条路径，但内联显示的 100 条路径全部位于一棵近期解压的子树中，因此模型完全没有看到其余 21 个条目。 + +三个单独看都合理的行为叠加后造成了错误印象。不含 `/` 的 glob 会匹配任意深度的文件名，因此 `*` 表示目录树中的每个文件，而不是 shell 对当前目录执行的展开。Ripgrep 的 `--sort=modified` 按升序排列，因此归档包还原出的旧时间戳会让该子树排在最前。随后，内联页面直接截取这一顺序的前部，却没有说明它只代表集中于一处的切片。 + +## 决策 + +未超过 `globMaxResults` 的结果仍保持完整，且按修改时间排序的内容逐字节不变。超过上限时，系统会在完整结果的顶层条目之间按轮转方式采样：每个条目都先获得一个位置，之后才有条目获得第二个位置；已经用尽的分组会退出轮转；各组内部的相对顺序保持稳定。分组始终以实际搜索根为基准，显式指定 `path` 时也如此。 + +footer 会说明当前页面是跨条目的样本，而不是按修改时间排序的前部；当顶层条目覆盖数能提供额外信息时，还会报告该数量；完整排序列表仍保存在 spill 产物中。若顶层条目数量超过内联位置数，footer 会要求模型缩小 `path`。 + +提示词与 schema 还会说明：不含 `/` 的模式会匹配任意深度，glob 只返回文件，绝不返回目录条目。在向模型暴露 bash 工具的部署中，目录定位仍由普通 shell 操作完成：查看一个目录使用 `ls`，跨目录树按指定文件路径模式查找则使用 glob。skill（技能）发现流程仍将 `ctx.fs.listDir` 作为内部提供方原语使用；本决策不会新增面向模型的 `list` 工具。 + +## 考虑过的替代方案 + +**保留按修改时间排序的前部，只警告结果过于集中。** 测量实际故障形态后否决。警告只会要求模型怀疑自己拿到的唯一一批路径；具有代表性的数据能直接修正答案。 + +**对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。 + +**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先契约，也没有让受限页面更具代表性。 + +**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序契约。现有上限是可以清楚解释的切换点。 + +**在顶层以下递归平衡。** 暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。 + +**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照契约，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。 + +**拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。** 否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。 + +## 影响 + +超过上限的 glob 页面无法再根据内联路径回答按时间判断新旧的问题；footer 会明确说明这一点，spill 产物仍保留完整的排序视图。采样只平衡搜索根下的第一路径段，因此某个顶层条目内部较深处、结果密集的子树仍可能占据主导。 + +工具接口不会扩大。此修复会更改 glob 的提示词、schema 描述、规范输出（`root` 记录采样基准）以及超过上限时的 Native 渲染，未超过上限的结果保持不变。 + +## 测试 + +包测试锁定了结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会启动真实的 Loader/app/sandbox-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。 diff --git a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md b/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md deleted file mode 100644 index fd8e8fb22d..0000000000 --- a/.agents/notes/implemented/feature/2026-07-27-directory-listing-tool.md +++ /dev/null @@ -1,109 +0,0 @@ -# Agent Note: Sample over-cap glob results across the tree, and give the model a directory-listing tool - -Status: implemented - -English | [中文](2026-07-27-directory-listing-tool.zh.md) - -## Problem - -Asked what a workspace contained, an agent described one subfolder as if it were the whole project. - -The session log shows exactly how. The workspace held 22 top-level entries and 11,485 files. The model called `glob {"pattern": "*"}`, which matched 10,030 paths; the tool showed the first 100, and all 100 sat under a single recently-unpacked subdirectory holding 355 of those files. The model never saw the other 21 top-level entries and answered from the one it did see. The session cwd was correct throughout — nothing was misconfigured, and every number the tool printed was true. - -Three properties of `glob` compose into that page: - -- **A pattern with no `/` matches at any depth.** The pattern goes to ripgrep as `--glob=`, where a glob without a separator matches the basename anywhere in the tree. `*` therefore means "every file in the workspace", not "the top level" — the opposite of what it means in a shell. The tool said nothing about this, and every example in its schema was `**/…`, so nothing suggested the plain form was recursive. -- **`--sort=modified` orders oldest first.** Unpacking an archive restores the timestamps stored inside it, which predate everything the user wrote, so a freshly unpacked subtree lands at the very front of any broad match. (Ripgrep sorts ascending; `--sortr` is the descending form and is not used here.) -- **The inline page was the head of that order.** `globMaxResults` (100) paths were kept from the front. Under the first two properties, one subtree takes every slot. - -Each property is defensible alone. Together they make the most ordinary request an agent receives — "what is in this directory" — reliably produce a confident wrong answer, because nothing in the result distinguishes "the 100 oldest files in this workspace" from "this workspace". - -### What ordering can and cannot fix - -A directory's name reaches the model only as the prefix of one of its files' paths, since `rg --files` emits files and never directory entries. That is enough for ordering to matter a great deal, and not enough for `glob` to answer the question. - -Measured on a reproduction of the failure's shape — 24 top-level entries, 716 files, one old-timestamped subtree: - -| First 100 paths chosen by | Distinct top-level names visible | -| --- | --- | -| modification time, oldest first (the shipped behavior) | 7 | -| round-robin across top-level entries | 21 | - -So a differently chosen page does surface most of the missing names, and the original diagnosis that ordering could not have helped was wrong. What no ordering fixes: an entry with no files beneath it never appears at all (the reproduction's empty directory is absent from the complete 716-path output), and nothing in the output says which names are directories or how many entries a directory holds. `glob` can therefore convey a tree's rough shape; it cannot state a directory's contents. - -## Decision - -Two changes, in the two packages that own the two halves of the failure. - -### The inline page of an over-cap `glob` result is sampled, not taken from the head - -`@deepseek-ai/dsh-tool-fs-search`. A result within `globMaxResults` is unchanged: shown whole, in modification-time order. Only when the result is larger does the page change — and there, taking the head is what fails. - -`sampleAcrossTopLevel` removes the displayed search-root prefix, groups the complete result by the next path segment, and fills the page round-robin: every entry immediately beneath the actual relative or absolute root gets a slot before any entry gets a second, and an entry that runs out of paths drops out so its remaining slots go to the rest. Sort order survives where it still carries meaning — groups are visited in the order ripgrep first emits them, and each group's own paths keep their relative order. The page is emitted grouped by entry rather than interleaved, so the breadth is legible at a glance. - -The footer states the basis, because a page that silently stopped being "the first N in modification-time order" would be a second, quieter version of the same lie: - -``` -(Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched -instead of taken in modification-time order. Full sorted result stored at: …) -``` - -When the page cannot reach every top-level entry — more entries than slots — the footer says so with the shown/total spread and tells the model to narrow `path`. A flat result, where every path is its own top-level entry, keeps the plain `(Showing k of n paths. …)` footer: there the round-robin *is* the sorted head, and naming a spread would only restate the counts. The spill artifact always holds the complete list in modification-time order, so the sorted view is never lost. - -The guidance and schema stop misleading in the same change: "not shell find or ls" becomes "not shell find"; both now state that a pattern without `/` matches basenames at any depth, that results are files and never directories, and that a fitting result is modification-time ordered while a larger one is sampled across top-level entries. They do not recommend sibling-package tools that may be absent from the current composition. - -### `list`, in `@deepseek-ai/dsh-tool-fs` - -A fourth model-facing filesystem tool over the existing `ctx.fs.listDir` primitive, which until now shipped with skill discovery as its only consumer; [the seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) deferred the model-facing consumer to a separate decision, which this is. - -It takes optional `path` and 1-based `offset` arguments, defaulting to the calling agent's session workspace and entry 1, and returns one bounded page as `{ path, offset, entries: [{ name, type }], totalEntries, counts }`, where `type` is `file`, `directory`, or `other`. It calls `listDir` and nothing else: the seam already reports absence as `FS_NOT_FOUND` and a non-directory target as `FS_NOT_DIRECTORY`, so a preceding `stat` would add a round-trip and a second source of truth. - -Three presentation rules carry the decision: - -- **Directories sort first, then files, then non-regular children, each alphabetically** before paging, so every offset traverses one stable order and the first page keeps navigable structure. -- **The canonical value and Native result carry one recoverable page** of at most `listMaxEntries` (default 200, configurable). The footer states the complete size and composition and gives `offset=` until the final page, so omitted sibling names remain reachable. -- **Filesystem text cannot forge presentation structure.** A name is emitted verbatim unless it would make the listing lie — a control character splitting one entry across lines, `` 交给 ripgrep，而不含分隔符的 glob 匹配树中任何位置的基名。因此 `*` 的含义是「工作区里的每个文件」，而不是「顶层」——与它在 shell 里的含义正好相反。工具对此只字未提，schema 里的示例又全是 `**/…`，没有任何线索表明朴素写法是递归的。 -- **`--sort=modified` 按从旧到新排序。** 解包压缩档会还原档案内部保存的时间戳，它们早于用户自己写下的一切，因此新近解包的子树会落在任何宽泛匹配的最前面。（ripgrep 按升序排序；降序是 `--sortr`，此处未使用。） -- **内联页面取的是该顺序的头部。** 从最前面保留 `globMaxResults`（100）条路径。在前两项性质之下，一个子树吃掉全部位置。 - -单看每一项都站得住。合在一起，它们让 agent 收到的最普通的请求——「这个目录里有什么」——稳定地产出一个笃定的错误答案，因为结果里没有任何信息能区分「本工作区按从旧到新顺序排在最前的 100 个文件」与「本工作区」。 - -### 排序能修什么，不能修什么 - -由于 `rg --files` 输出文件、从不输出目录条目，一个目录的名字只能作为其下某个文件路径的前缀抵达模型。这既足以让排序变得非常重要，也不足以让 `glob` 回答那个问题。 - -在一份复现该失败形态的目录上实测——24 个顶层条目、716 个文件、一个时间戳较旧的子树： - -| 前 100 条路径的挑选方式 | 可见的顶层名个数 | -| --- | --- | -| 按修改时间、从旧到新（已交付的行为） | 7 | -| 跨顶层条目轮转 | 21 | - -也就是说，换一种页面挑选方式确实能呈现出大部分缺失的名字，最初那句「排序帮不上忙」的诊断是错的。排序修不了的是：没有任何文件的条目根本不会出现（复现目录里的空目录在完整的 716 条输出中一次都没出现），而且输出里没有任何信息说明哪些名字是目录、某个目录有多少条目。因此 `glob` 能传达一棵树的大致形状，却说不出一个目录的内容。 - -## Decision - -两项改动，分别落在承担这次失败两半责任的两个包中。 - -### 超过上限的 `glob` 结果，内联页面改为取样而非取头部 - -`@deepseek-ai/dsh-tool-fs-search`。未超过 `globMaxResults` 的结果完全不变：整体展示，按修改时间排序。只有结果更大时页面才改变——而恰恰在这种情况下，取头部是会失败的做法。 - -`sampleAcrossTopLevel` 移除所显示的搜索根前缀，再按下一个路径段对完整结果分组，并以轮转方式填充页面：实际相对或绝对搜索根正下方的每个条目都先拿到一个位置，任何条目才可能拿到第二个；某个条目的路径用尽后退出，其剩余份额交给其余条目。排序在仍有意义的地方被保留下来——分组按 ripgrep 首次输出它们的顺序访问，而每个分组内部的路径保持原有相对顺序。页面按条目分组输出而非交错输出，使覆盖广度一眼可辨。 - -footer 会说明取用依据，因为一个悄悄不再是「按修改时间排序的前 N 条」的页面，只会成为同一个谎言更安静的版本： - -``` -(Showing 100 of 10030 paths, sampled across 22 of the 22 top-level entries this pattern matched -instead of taken in modification-time order. Full sorted result stored at: …) -``` - -当页面无法触达全部顶层条目时——条目数多于位置数——footer 会给出已触达/总计的分布，并要求模型缩小 `path`。扁平结果（每个路径各自构成一个顶层条目）保留朴素的 `(Showing k of n paths. …)` footer：此时轮转结果**就是**排序后的头部，说明分布只会重复计数。spill 产物始终保存按修改时间排序的完整列表，排序视图不会丢失。 - -同一次改动里，指导与 schema 也不再误导：「not shell find or ls」改为「not shell find」；两处现在都写明：不含 `/` 的 pattern 匹配任意深度的基名、结果只有文件从不包含目录、未超上限的结果按修改时间排序，而更大的结果跨顶层条目取样。它们不会推荐当前组合中可能不存在的兄弟包工具。 - -### `list`，位于 `@deepseek-ai/dsh-tool-fs` - -在既有的 `ctx.fs.listDir` 原语之上新增第四个面向模型的文件系统工具；该原语此前交付时唯一的消费方是 skill（技能）发现，[seam Agent Note](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md) 把面向模型的消费方推迟为一项单独的决策，也就是本文。 - -它接受可选的 `path` 和从 1 开始的 `offset` 参数，默认取调用 agent 的会话工作区和第 1 个条目，并返回一个有界页面，形如 `{ path, offset, entries: [{ name, type }], totalEntries, counts }`，其中 `type` 为 `file`、`directory` 或 `other`。它只调用 `listDir`：seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，前置 `stat` 只会多一次往返并制造第二个真源。 - -有三条展示规则承载了这个决策： - -- **先目录、再文件、最后非常规子项，各组内按字母序**，然后再分页，使每个 offset 都遍历同一稳定顺序，且第一页保留可导航的结构。 -- **规范值和 Native 结果携带一个可继续取回的页面**，最多包含 `listMaxEntries` 个条目（默认 200，可配置）。footer 会说明完整规模与构成，并在最后一页之前给出 `offset=`，因此被省略的同级名称仍可取回。 -- **文件系统文本无法伪造展示结构。** 条目名默认原样输出；只有当它会让列出结果失真时才转为 JSON 字符串并中和 `; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ - list: { - /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ - path?: string; - /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ - offset?: number; - } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -307,20 +298,6 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; - list: { - path: string; - offset: number; - entries: ({ - name: string; - type: "file" | "directory" | "other"; - })[]; - totalEntries: number; - counts: { - directories: number; - files: number; - other: number; - }; - }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json index 93457f0e37..314b24e2be 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json @@ -172,23 +172,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md index 1a8589a47b..0cee2a6517 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. @@ -82,13 +80,6 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ - list: { - /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ - path?: string; - /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ - offset?: number; - } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -278,20 +269,6 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; - list: { - path: string; - offset: number; - entries: ({ - name: string; - type: "file" | "directory" | "other"; - })[]; - totalEntries: number; - counts: { - directories: number; - files: number; - other: number; - }; - }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json index 9f55d9291f..b61d7bf623 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md index 1a8589a47b..0cee2a6517 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. @@ -82,13 +80,6 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ - list: { - /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ - path?: string; - /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ - offset?: number; - } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -278,20 +269,6 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; - list: { - path: string; - offset: number; - entries: ({ - name: string; - type: "file" | "directory" | "other"; - })[]; - totalEntries: number; - counts: { - directories: number; - files: number; - other: number; - }; - }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md index 1a8589a47b..0cee2a6517 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. @@ -82,13 +80,6 @@ interface ToolArgsMap { } & Record; /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */ get_goal: Record; - /** List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents. */ - list: { - /** Directory to list. Defaults to the session workspace; a relative path resolves against it. */ - path?: string; - /** 1-based first entry to return. Defaults to 1; use the footer value to continue. */ - offset?: number; - } & Record; /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */ ralph: { /** The immutable completion objective for every fresh Ralph round. */ @@ -278,20 +269,6 @@ interface ToolOutputMap { }; activation: "armed" | "disarmed"; }; - list: { - path: string; - offset: number; - entries: ({ - name: string; - type: "file" | "directory" | "other"; - })[]; - totalEntries: number; - counts: { - directories: number; - files: number; - other: number; - }; - }; ralph: { runId: string; agentsStarted: number; diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md index cd3c81f6f8..e3437ad61a 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/escalation-approved/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json index 7094daf44e..01ac777a42 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/escalation-approved/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json b/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json new file mode 100644 index 0000000000..cc5fc95e59 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Call glob exactly once with pattern * and no path. Then reply with exactly GLOB_SAMPLED and nothing else." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl new file mode 100644 index 0000000000..16a7d9b631 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl @@ -0,0 +1,24 @@ +{"type":"session","version":0,"id":"f5a99d52-3eaa-4ce7-858d-61d4fd77df2a","createdAt":1785218400000,"cwd":"/tmp/acp-fs-glob-sampling","delegationDepth":0} +{"type":"turn/start","seq":0,"time":1785218400001,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":1785218400002,"data":{"content":[{"type":"text","text":"Call glob exactly once with pattern * and no path. Then reply with exactly GLOB_SAMPLED and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"session/title","seq":2,"time":1785218400003,"data":{"title":"Call glob exactly once with","messageSeqs":[1],"source":{"kind":"fallback"}}} +{"type":"step/start","seq":3,"time":1785218400004,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":4,"time":1785218400005,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":5,"time":1785218400006,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":6,"time":1785218400007,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"glob-sampling-call","name":"glob","argumentsDelta":"{\"pattern\":\"*\"}"}}} +{"type":"assistant/chunk","seq":7,"time":1785218400008,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}}}} +{"type":"assistant/chunk","seq":8,"time":1785218400009,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}} +{"type":"assistant/chunk","seq":9,"time":1785218400010,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":10,"time":1785218400011,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-pro"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"} +{"type":"tool/call","seq":11,"time":1785218400012,"data":{"turn":1,"step":1,"callId":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}} +{"type":"tool/result","seq":12,"time":1785218400013,"data":{"turn":1,"step":1,"callId":"glob-sampling-call","content":[{"type":"text","text":"archive/a.ts\nsrc/index.ts\ndocs/guide.md\ntest/spec.ts\n\n(Showing 4 of 6 paths, sampled across 4 of the 4 top-level entries this pattern matched instead of taken in modification-time order. The complete result could not be saved; narrow pattern or path to see more.)"}],"isError":false},"sourceEventSeqs":[11],"surfaceOp":"append"} +{"type":"step/end","seq":13,"time":1785218400014,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":14,"time":1785218400015,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":15,"time":1785218400016,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":16,"time":1785218400017,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"GLOB_SAMPLED"}}} +{"type":"assistant/chunk","seq":17,"time":1785218400018,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"GLOB_SAMPLED"}}}} +{"type":"assistant/chunk","seq":18,"time":1785218400019,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":1,"outputTokens":1}}}} +{"type":"assistant/chunk","seq":19,"time":1785218400020,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":20,"time":1785218400021,"data":{"turn":1,"step":2,"content":[{"type":"text","text":"GLOB_SAMPLED"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-pro"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"} +{"type":"step/end","seq":21,"time":1785218400022,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":22,"time":1785218400023,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-glob-sampling/stdout.expected.jsonl similarity index 90% rename from examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl rename to examples/acp-agent/tests/snapshots/fs-glob-sampling/stdout.expected.jsonl index 22d36a3c79..691b11cef0 100644 --- a/examples/acp-agent/tests/snapshots/fs-list/stdout.expected.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/stdout.expected.jsonl @@ -1,4 +1,4 @@ {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"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_message_chunk","content":{"type":"text","text":"docs src"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"GLOB_SAMPLED"}}}} {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md new file mode 100644 index 0000000000..467b05904b --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md @@ -0,0 +1,29 @@ +You are an AI agent powered by the DeepSeek Harness SDK. + +You are a coding assistant powered by the deepseek-v4-pro model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug. + +Verify your work by running the code or tests. Keep answers brief and factual. + + +Use 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. + +Use 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. + +Use 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. + +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. + +Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context. + +Check the [exit code: N] marker on every bash result; investigate failures before moving on. + +Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering. + +Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked. + +Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`). + + +Use 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. + +Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out. diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json new file mode 100644 index 0000000000..1b25291c5c --- /dev/null +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json @@ -0,0 +1,517 @@ +{ + "initial": [ + { + "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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.", + "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 (collect with task_output, stop with task_kill). No timeout applies." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access." + } + }, + "required": [ + "command", + "description" + ] + } + }, + { + "name": "create_goal", + "description": "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.", + "parameters": { + "type": "object", + "properties": { + "objective": { + "type": "string", + "description": "The concrete completion objective inferred from the direct human request." + }, + "max_goal_rounds": { + "type": "number", + "description": "Optional positive safe-integer limit on automatic continuation rounds." + } + }, + "required": [ + "objective" + ] + } + }, + { + "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." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access." + } + }, + "required": [ + "file_path", + "old_string", + "new_string" + ] + } + }, + { + "name": "get_goal", + "description": "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.", + "parameters": { + "type": "object", + "properties": {} + } + }, + { + "name": "glob", + "description": "Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 4 paths come back in modification-time order; a larger result instead returns 4 paths sampled across top-level entries, says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries.", + "parameters": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth." + }, + "path": { + "type": "string", + "description": "Directory to search in. Defaults to the session workspace; a relative path resolves against it." + } + }, + "required": [ + "pattern" + ] + } + }, + { + "name": "grep", + "description": "Search file contents with a ripgrep regular expression. Returns matching lines with line numbers, grouped by file. Returns the first 250 matches inline; a capped result reports where the complete match list was saved. Use read on a matched file for surrounding context.", + "parameters": { + "type": "object", + "properties": { + "pattern": { + "type": "string", + "description": "Regular expression to search for (ripgrep syntax)." + }, + "path": { + "type": "string", + "description": "File or directory to search. Defaults to the session workspace; a relative path resolves against it." + }, + "include": { + "type": "string", + "description": "One glob filter for which files to search (e.g. \"*.ts\", \"*.{js,jsx}\"). Not a list; negation is not supported." + } + }, + "required": [ + "pattern" + ] + } + }, + { + "name": "ralph", + "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", + "parameters": { + "type": "object", + "properties": { + "objective": { + "type": "string", + "description": "The immutable completion objective for every fresh Ralph round." + }, + "maxRounds": { + "type": "number", + "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling." + } + }, + "required": [ + "objective" + ] + } + }, + { + "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": "skill", + "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The exact skill name from the available skills list." + } + }, + "required": [ + "name" + ] + } + }, + { + "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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "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." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "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." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "task_kill", + "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "reason": { + "type": "string", + "description": "Optional short reason, recorded in the log and forwarded to the task." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "task_list", + "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.", + "parameters": { + "type": "object", + "properties": {} + } + }, + { + "name": "task_output", + "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "wait": { + "type": "boolean", + "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive." + }, + "timeout_ms": { + "type": "number", + "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "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", + "additionalProperties": false, + "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": "update_goal", + "description": "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.", + "parameters": { + "type": "object", + "properties": { + "goal_id": { + "type": "string", + "description": "Exact id returned by get_goal." + }, + "revision": { + "type": "number", + "description": "Exact positive revision returned by get_goal." + }, + "action": { + "type": "string", + "description": "edit | pause | resume | complete | blocked", + "enum": [ + "edit", + "pause", + "resume", + "complete", + "blocked" + ] + }, + "objective": { + "type": "string", + "description": "Replacement objective; valid only with action edit." + }, + "max_goal_rounds": { + "type": "number", + "description": "Replacement cap; valid only with action edit." + }, + "blocked_reason": { + "type": "string", + "description": "Concrete blocking condition; required only with action blocked." + } + }, + "required": [ + "goal_id", + "revision", + "action" + ] + } + }, + { + "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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).", + "additionalProperties": true, + "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", + "additionalProperties": true, + "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." + }, + "provider": { + "type": "string", + "description": "Optional provider override this phase is expected to use." + }, + "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\": [...]}).", + "additionalProperties": true + } + }, + "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." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access." + } + }, + "required": [ + "file_path", + "content" + ] + } + } + ], + "changes": [] +} diff --git a/examples/acp-agent/tests/snapshots/fs-list/input.json b/examples/acp-agent/tests/snapshots/fs-list/input.json deleted file mode 100644 index 67a0bc3f42..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/input.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "steps": [ - { "op": "initialize" }, - { "op": "newSession" }, - { "op": "prompt", "text": "Call the list tool exactly once, with no arguments at all (NOT bash, NOT glob, and do not pass a path). Then reply with exactly the names of the subdirectories it reported, alphabetically, separated by a single space, and nothing else." } - ] -} diff --git a/examples/acp-agent/tests/snapshots/fs-list/session.jsonl b/examples/acp-agent/tests/snapshots/fs-list/session.jsonl deleted file mode 100644 index 0a05e2b1fe..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/session.jsonl +++ /dev/null @@ -1,32 +0,0 @@ -{"type":"session","version":0,"id":"ea640046-d959-4644-9a03-ff3d08133d4b","createdAt":1785159113359,"cwd":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6","delegationDepth":0} -{"type":"turn/start","seq":0,"time":1785159113361,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} -{"type":"user/message","seq":1,"time":1785159113362,"data":{"content":[{"type":"text","text":"Call the list tool exactly once, with no arguments at all (NOT bash, NOT glob, and do not pass a path). Then reply with exactly the names of the subdirectories it reported, alphabetically, separated by a single space, and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"} -{"type":"session/title","seq":2,"time":1785159113363,"data":{"title":"Call the list tool exactly","messageSeqs":[1],"source":{"kind":"fallback"}}} -{"type":"step/start","seq":3,"time":1785159113368,"data":{"turn":1,"step":1}} -{"type":"request/header","seq":4,"time":1785159113369,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} -{"type":"assistant/chunk","seq":5,"time":1785159115248,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"reasoning-chunks","seq0":6,"time0":1785159115249,"data":{"turn":1,"step":1,"index":0,"dt":[146,45,3,0,0,1,43,1,0,0,1,1,31,1,46,0,0,0,0,0,41,1,0,0,45,2,2,0,0,1,44,3,3,0],"texts":["The"," user"," wants"," me"," to"," call"," the"," list"," tool"," with"," no"," arguments"," and"," then"," reply"," with"," the"," names"," of"," the"," sub","direct","ories"," it"," reports",","," alphabet","ically",","," separated"," by"," a"," single"," space","."]}} -{"type":"assistant/chunk","seq":41,"time":1785159115836,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} -{"type":"assistant/chunk","seq":42,"time":1785159115837,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","argumentsDelta":""}}} -{"type":"assistant/chunk","seq":43,"time":1785159115837,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","argumentsDelta":"{}"}}} -{"type":"assistant/chunk","seq":44,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call the list tool with no arguments and then reply with the names of the subdirectories it reports, alphabetically, separated by a single space."}}}} -{"type":"assistant/chunk","seq":45,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}}}} -{"type":"assistant/chunk","seq":46,"time":1785159115921,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":5513,"outputTokens":62,"cacheReadTokens":0,"reasoningTokens":35}}}} -{"type":"assistant/chunk","seq":47,"time":1785159115922,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","seq":48,"time":1785159115926,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to call the list tool with no arguments and then reply with the names of the subdirectories it reports, alphabetically, separated by a single space."},{"type":"tool-call","id":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":5513,"outputTokens":62,"cacheReadTokens":0,"reasoningTokens":35}},"sourceEventSeqs":[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],"surfaceOp":"append"} -{"type":"tool/call","seq":49,"time":1785159115927,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","name":"list","arguments":"{}"}} -{"type":"tool/result","seq":50,"time":1785159115944,"data":{"turn":1,"step":1,"callId":"call_00_BSi06gcYvl6oad3I5qqG9244","content":[{"type":"text","text":"/var/folders/8k/kj35k1fd6t90n0czg7k3hv140000gn/T/acp-snap-cwd-QJ2ZC6\ndirectory\n\ndocs/\nsrc/\npackage.json\nREADME.txt\n\n(4 entries: 2 directories, 2 files)\n"}],"isError":false},"sourceEventSeqs":[49],"surfaceOp":"append"} -{"type":"step/end","seq":51,"time":1785159115950,"data":{"turn":1,"step":1}} -{"type":"step/start","seq":52,"time":1785159115951,"data":{"turn":1,"step":2}} -{"type":"assistant/chunk","seq":53,"time":1785159116889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} -{"type":"reasoning-chunks","seq0":54,"time0":1785159116890,"data":{"turn":1,"step":2,"index":0,"dt":[145,49,1,0,60,0,0,1,0,39,1,0,0,0,0,23,1,46,3,0,0],"texts":["The"," sub","direct","ories"," reported"," are"," `","docs","/","`"," and"," `","src","/","`."," Alphabet","ically",":"," docs",","," src","."]}} -{"type":"assistant/chunk","seq":76,"time":1785159117259,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} -{"type":"assistant/chunk","seq":77,"time":1785159117259,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"docs"}}} -{"type":"assistant/chunk","seq":78,"time":1785159117297,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":" src"}}} -{"type":"assistant/chunk","seq":79,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The subdirectories reported are `docs/` and `src/`. Alphabetically: docs, src."}}}} -{"type":"assistant/chunk","seq":80,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"docs src"}}}} -{"type":"assistant/chunk","seq":81,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":161,"outputTokens":25,"cacheReadTokens":5504,"reasoningTokens":22}}}} -{"type":"assistant/chunk","seq":82,"time":1785159117300,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","seq":83,"time":1785159117301,"data":{"turn":1,"step":2,"content":[{"type":"reasoning","text":"The subdirectories reported are `docs/` and `src/`. Alphabetically: docs, src."},{"type":"text","text":"docs src"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":161,"outputTokens":25,"cacheReadTokens":5504,"reasoningTokens":22}},"sourceEventSeqs":[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],"surfaceOp":"append"} -{"type":"step/end","seq":84,"time":1785159117308,"data":{"turn":1,"step":2}} -{"type":"turn/end","seq":85,"time":1785159117309,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt deleted file mode 100644 index dab306f45e..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/workspace/README.txt +++ /dev/null @@ -1 +0,0 @@ -# Project diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt deleted file mode 100644 index 8c0d02fadc..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/workspace/docs/guide.txt +++ /dev/null @@ -1 +0,0 @@ -# Guide diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json b/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json deleted file mode 100644 index e36fa754cf..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/workspace/package.json +++ /dev/null @@ -1 +0,0 @@ -{ "name": "demo" } diff --git a/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt b/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt deleted file mode 100644 index eab39ce89c..0000000000 --- a/examples/acp-agent/tests/snapshots/fs-list/workspace/src/index.txt +++ /dev/null @@ -1 +0,0 @@ -export const answer = 42 diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md index d02b6d0859..7bde8fe289 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json index ab1bda91f3..9b5925605c 100644 --- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "lsp", "description": "Query a language server for precise code navigation. operation is one of goToDefinition, findReferences, goToImplementation, hover. line and character are one-based UTF-16 cursor coordinates. findReferences includes the declaration.", diff --git a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md index c5496aeed5..df065a83cb 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/pty-tools/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json index 0d20d22762..8e093db8bd 100644 --- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md index 7d13160613..68bdd841c7 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/session-query-spill/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json index caee8e049e..beb93c6b53 100644 --- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md index e6ab6361db..17e6773a03 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json index 7094daf44e..01ac777a42 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md index e6ab6361db..17e6773a03 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json index 7094daf44e..01ac777a42 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md index 451746f412..45705db0a5 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/web-fetch/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-pro model. Your working di Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json index 6c389246e2..70940f8907 100644 --- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md index fdacca4b7f..6cd8d5725f 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md @@ -5,8 +5,6 @@ You are a coding assistant powered by the deepseek-v4-flash model. Your working Verify your work by running the code or tests. Keep answers brief and factual. -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. - Use 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. Use 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. diff --git a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json index 7094daf44e..01ac777a42 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json @@ -115,23 +115,6 @@ "properties": {} } }, - { - "name": "list", - "description": "List the direct children of one directory, with their type. Entries are directories first, then files, each alphabetical; up to 200 are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. It includes subdirectories and is the tool for seeing one directory's contents.", - "parameters": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "Directory to list. Defaults to the session workspace; a relative path resolves against it." - }, - "offset": { - "type": "number", - "description": "1-based first entry to return. Defaults to 1; use the footer value to continue." - } - } - } - }, { "name": "ralph", "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index 974d88c18c..3754595f56 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -23,7 +23,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(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'list', 'lsp', 'ralph', 'read', 'run_code', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write']) + expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', '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/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index 3e7c989373..13f1ecd649 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md -README.md: 8fdd54fb36353ca6c1dbcf71cdad38c4bcf26b7d -README.zh.md: 567c8e0df58950369c59785859948e32cbccdef4 +# pnpm run verify-translation-pairing --write +README.md: 4ff9b043525e8e7a0b59e3d91410951d88bb9a69 +README.zh.md: f94a903c9c37f7d45b7f8cebabe21082388bd041 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 8fdd54fb36..4ff9b04352 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -2,24 +2,23 @@ English | [中文](README.zh.md) -The **model-facing filesystem tools** — `list`, `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, **listing order**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly** — it injects `fs` (plus `tools`/`systemPrompt`), **not** a policy service. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. +The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly** — it injects `fs` (plus `tools`/`systemPrompt`), **not** a policy service. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. ```ts ignore-check // Default deployment: a ctx.fs provider, the policy plugin, then the tools. await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local await ctx.plugin(FsPolicy) // @deepseek-ai/dsh-fs-policy (policy gate) -await ctx.plugin(ToolFs) // this package — registers list/read/write/edit +await ctx.plugin(ToolFs) // this package — registers read/write/edit ``` `@deepseek-ai/dsh-fs-policy` is **optional**: omit it and the tools run against the bare provider (unconditional write/overwrite/edit, no observed-state). A deployment that loads these tools is expected to also load it, so the behavior is read-before-write/edit. ## Config -All keys are optional; the defaults are the shipped listing and read caps. +All keys are optional; the defaults are the shipped read caps. | Key | Default | Meaning | |---|---|---| -| `listMaxEntries` | `200` | Maximum entries one `list` page returns; the footer reports complete size and composition plus a next offset when more remain. | | `readLimit` | `2000` | Default and maximum lines returned by one `read` call (the tool schema advertises it as the `limit` default). | | `readMaxLineLength` | `2000` | Characters kept per line before truncation (the suffix names the cap). | | `readMaxBytes` | `51200` | Byte cap on one `read` call's selected lines; overflow ends the window with a "capped" footer. | @@ -29,20 +28,18 @@ All keys are optional; the defaults are the shipped listing and read caps. | Tool | Arguments | Behavior | |---|---|---| -| `list` | `path?`, `offset?` | One page of direct children with their type, defaulting to the session workspace and entry 1. Ordered directories first, then files, then non-regular children, each alphabetical; when more remain, continue from the footer's next offset. | | `read` | `file_path`, `offset?`, `limit?` | Line-numbered UTF-8 content with a pagination footer. `offset` is 1-based; `limit` defaults to and caps at the configured `readLimit` (2000). | | `write` | `file_path`, `content` | Create or fully replace a file. With the policy plugin: overwriting an existing file requires a prior `read` at the unchanged version; creating a new file does not. Without it: unconditional. | | `edit` | `file_path`, non-empty `old_string`, `new_string`, `replace_all?` | Literal replacement; unique match required unless `replace_all` is true. With the policy plugin: requires a prior `read` (any window) and the file unchanged since. Without it: unconditional. | Field names are snake_case to match Claude Code and existing harness tool schemas. -Canonical successes are `list` → `{ path, offset, entries: [{ name, type }], totalEntries, counts: { directories, files, other } }`, `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. `list.entries` is one bounded page; `type` is `file`, `directory`, or `other`, while its totals describe the complete directory. Native renderers preserve the listing/read envelopes and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. +Canonical successes are `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. Write/edit derive replayable diff-card metadata from these values; the values themselves are execution-local and are not added to `tool/result`. ## The tool is the executor; policy is an event gate The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then: -- **list** — one `ctx.fs.listDir`; the seam already answers absence with `FS_NOT_FOUND` and a non-directory target with `FS_NOT_DIRECTORY`, so no probe precedes it. No `fs/observed`: a listing reads no file content and must not satisfy the read-before-write gate. (0 stat.) - **read** — one `ctx.fs.stat` (type + size routing + version), then `readText`/`streamText`, then builds the line window, then emits `fs/observed` with a plain `ctx.emit`. (1 stat.) - **write** — `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.writeText(target, content, intent)`, then `fs/observed`. (0 stat.) - **edit** — `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.editText(target, edit, intent)`, then `fs/observed`. (0 stat.) @@ -53,9 +50,9 @@ The tool passes `exec` (the tool-execution context) as the opaque `actor` on eve `fs/observed` fires AFTER the read/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — async or fallible observation does not belong on this event. -`list` and `read` opt into concurrent scheduling — `list` mutates nothing at all, and `read`'s only mutation is the synchronous version recorder. Recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock; both mutation tools remain exclusive. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md). +`read` opts into concurrent scheduling because its only mutation is the synchronous version recorder. Recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock; both mutation tools remain exclusive. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md). -The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Pure presentation lives beside the executors and is independently unit-tested: read windowing and output formatting in `src/read-render.ts`, listing order and envelope in `src/list-render.ts` (both Cordis-free); `src/list.ts`/`read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them. +The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them. ## Model Experience @@ -63,13 +60,7 @@ The package root exports only the Cordis plugin contract (`name`, `inject`, `Con #### What the model sees -Every request in this plugin's registration scope receives the independently registered list, read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections. - -##### List guidance - -```markdown -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. -``` +Every request in this plugin's registration scope receives the independently registered read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections. ##### Read guidance @@ -101,7 +92,7 @@ Prefix-stable while the plugin scope and guidance text are unchanged. Tool restr #### What the model sees -The model sees the generated [`list`, `read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent. +The model sees the generated [`read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent. #### Token effect @@ -111,20 +102,6 @@ Fixed schema cost on every request in that tool view. Prefix-stable while the visible tool definitions and order are unchanged. Registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token. -### List result - -#### What the model sees - -A successful listing is ``, newline, `directory`, newline, ``, one line per page entry, a blank line, one footer, and ``. A directory carries a trailing `/`, a non-regular child a trailing `@`, and a regular file neither. A name is emitted verbatim unless it could make the listing say something untrue — a control character, a leading `"`, a backslash, ` entries: directories, files)` with optional `, other`, or `(Showing entries - of : . Use offset= to continue.)`; the final page omits the continuation sentence. Every page states the complete count and composition. - -#### Token effect - -Listing output and its canonical `entries` page are capped by `listMaxEntries`; the retained call and result are resent until compaction. - -#### KV Cache effect - -Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries. - ### Read result #### What the model sees @@ -157,7 +134,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `path must be a non-empty string when given`, `offset must be a positive integer`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, `offset is out of range for "" ( entries)`, and the corresponding ` lines` read error; provider and policy templates are quoted in their package READMEs. +Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, and `offset is out of range for "" ( lines)`; provider and policy templates are quoted in their package READMEs. #### Token effect @@ -169,6 +146,6 @@ Append-only; newly visible content follows the reusable request prefix and does ## Known Limitations and Deferred Work -- **`list` reads one directory level** — recursion and per-directory child counts are absent; offset pagination traverses only the current directory's ordered direct children. +- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam. - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`. -- **No timeout surface** — `list`/`read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)). +- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)). diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index 567c8e0df5..f94a903c9c 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -2,24 +2,23 @@ [English](README.md) | 中文 -**面向模型的文件系统工具**（`list`、`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON schema、参数校验、提示词段、**读取窗口逻辑**、**列出顺序** 和结果格式化。它**直接** 通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取/写入/编辑：注入 `fs`（以及 `tools`/`systemPrompt`），**不** 注入政策服务。新鲜度/观察政策由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。 +**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON schema、参数校验、提示词段、**读取窗口逻辑** 和结果格式化。它**直接** 通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取/写入/编辑：注入 `fs`（以及 `tools`/`systemPrompt`），**不** 注入政策服务。新鲜度/观察政策由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。 ```ts ignore-check // Default deployment: a ctx.fs provider, the policy plugin, then the tools. await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local await ctx.plugin(FsPolicy) // @deepseek-ai/dsh-fs-policy (policy gate) -await ctx.plugin(ToolFs) // this package — registers list/read/write/edit +await ctx.plugin(ToolFs) // this package — registers read/write/edit ``` `@deepseek-ai/dsh-fs-policy` 是**可选的**：省略时，工具直接使用裸提供方（无条件写入/覆盖/编辑，无已观察状态）。加载这些工具的部署也应加载该插件，从而提供编辑前读取行为。 ## 配置 -所有键均为可选；默认值是随产品交付的列出与读取上限。 +所有键均为可选；默认值是随产品交付的读取上限。 | 键 | 默认值 | 含义 | |---|---|---| -| `listMaxEntries` | `200` | 单个 `list` 页面返回的最大条目数；footer 会报告完整规模与构成，并在仍有条目时给出下一 offset。 | | `readLimit` | `2000` | 一次 `read` 调用返回的默认和最大行数（工具 schema 将其声明为 `limit` 默认值）。 | | `readMaxLineLength` | `2000` | 每行截断前保留的字符数（后缀会说明上限）。 | | `readMaxBytes` | `51200` | 一次 `read` 调用所选行的字节上限；溢出时以「已达上限」footer 结束窗口。 | @@ -29,20 +28,18 @@ await ctx.plugin(ToolFs) // this package — re | 工具 | 参数 | 行为 | |---|---|---| -| `list` | `path?`、`offset?` | 单个目录的一页直接子项及其类型，默认取会话工作区并从第 1 个条目开始。顺序为先目录、再文件、最后非常规子项，各组内按字母序排列；仍有条目时按 footer 给出的下一 offset 继续。 | | `read` | `file_path`、`offset?`、`limit?` | 带行号的 UTF-8 内容和分页 footer。`offset` 从 1 开始；`limit` 默认为配置的 `readLimit`（2000），上限也为该值。 | | `write` | `file_path`、`content` | 创建文件或完整替换文件。有政策插件时：覆盖现有文件要求先在未变版本上执行 `read`；创建新文件不需要。没有插件时：无条件执行。 | | `edit` | `file_path`、非空 `old_string`、`new_string`、`replace_all?` | 字面量替换；除非 `replace_all` 为 true，否则要求唯一匹配。有政策插件时：要求先执行 `read`（任何窗口），且文件此后未变。没有插件时：无条件执行。 | 字段名使用 snake_case，与 Claude Code 和现有 harness 工具 schema 一致。 -规范成功值分别为：`list` → `{ path, offset, entries: [{ name, type }], totalEntries, counts: { directories, files, other } }`，`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。`list.entries` 是一个有界页面；`type` 为 `file`、`directory` 或 `other`，而总计信息描述的是完整目录。Native 渲染器会保留下方的列出/读取包络和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 +规范成功值分别为：`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。Native 渲染器会保留下方带行号的读取结果和变更确认。写入/编辑从这些值派生可回放的 diff 卡片元数据；值本身仅用于执行，不会添加到 `tool/result`。 ## 工具就是执行器；政策是事件门禁 工具**不** 注入政策服务，也不检查任何缓存。每个工具通过 `ctx.fs.resolve(path, { cwd, signal })` 解析路径；它会传入调用 agent（智能体）的会话 cwd（`exec.agent.session.header.cwd`），使相对路径以会话工作区为基准解析并与 `dsh-tool-bash` 一致，同时把工具取消转发到解析过程（见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)）。随后执行： -- **list**：一次 `ctx.fs.listDir`；seam 已经把不存在报告为 `FS_NOT_FOUND`、把非目录目标报告为 `FS_NOT_DIRECTORY`，因此前面不需要任何探测。不发出 `fs/observed`：列出不读取任何文件内容，也不得满足编辑前读取门禁。（0 次 stat。） - **read**：一次 `ctx.fs.stat`（用于类型、大小路由和版本），随后调用 `readText`/`streamText`，构建行窗口，再发出 `fs/observed`，使用普通 `ctx.emit`。（1 次 stat。） - **write**：调用 `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.writeText(target, content, intent)`，再发出 `fs/observed`。（0 次 stat。） - **edit**：调用 `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.editText(target, edit, intent)`，再发出 `fs/observed`。（0 次 stat。） @@ -53,9 +50,9 @@ await ctx.plugin(ToolFs) // this package — re `fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的契约是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。 -`list` 与 `read` 都允许并发调度：`list` 完全不做任何变更，而 `read` 的唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。 +`read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。 -包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。纯展示逻辑与执行器并列存放并单独进行单元测试：读取窗口与输出格式化位于 `src/read-render.ts`，列出顺序与包络位于 `src/list-render.ts`（两者均不依赖 Cordis）；`src/list.ts`/`read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。 +包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。 ## 模型体验 @@ -63,13 +60,7 @@ await ctx.plugin(ToolFs) // this package — re #### 模型看到的内容 -该插件注册作用域内的每个请求都会收到下方独立注册的 list、read、write 与 edit 指导。作用域工具限制可以隐藏 schema，而不移除这些段。 - -##### List 指导 - -```markdown -Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. When a result is capped, continue with the offset named in its footer. -``` +该插件注册作用域内的每个请求都会收到下方独立注册的 read、write 与 edit 指导。作用域工具限制可以隐藏 schema，而不移除这些段。 ##### Read 指导 @@ -101,7 +92,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -模型会看到已生成的 [`list`、`read`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。作用域工具限制可以为某个 agent 移除任一定义。 +模型会看到已生成的 [`read`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。作用域工具限制可以为某个 agent 移除任一定义。 #### Token 影响 @@ -111,20 +102,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces 只要可见工具定义和顺序不变，前缀就保持稳定。注册生命周期或作用域限制可能从首个变化的 schema token 开始使复用失效。 -### 列出结果 - -#### 模型看到的内容 - -成功列出结果为 ``、换行、`directory`、换行、``、页面中的每个条目一行、一个空行、一条 footer 和 ``。目录带尾部 `/`，非常规子项带尾部 `@`，常规文件两者都不带。条目名默认原样输出，只有当它可能让列出结果失真时才转为 JSON 字符串并中和 ` entries: directories, files)`（可选追加 `, other`），或 `(Showing entries - of : . Use offset= to continue.)`；最后一页省略继续提示。每一页都会说明完整计数与构成。 - -#### Token 影响 - -列出输出及其规范 `entries` 页面受 `listMaxEntries` 限制；保留的调用与结果会反复发送，直到上下文压缩。 - -#### KV Cache 影响 - -仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。 - ### 读取结果 #### 模型看到的内容 @@ -157,7 +134,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`path must be a non-empty string when given`、`offset must be a positive integer`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file`、`offset is out of range for "" ( entries)`，以及对应的 ` lines` 读取错误；提供方和政策模板在各自包的 README 中逐字列出。 +失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file` 和 `offset is out of range for "" ( lines)`；提供方和政策模板在各自包的 README 中逐字列出。 #### Token 影响 @@ -169,6 +146,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces ## 已知限制与延期工作 -- **`list` 只读取一层目录**：不提供递归和逐目录子项计数；offset 分页只遍历当前目录中按顺序排列的直接子项。 +- **未交付面向模型的目录列出工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。 -- **没有超时接口**：`list`/`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见有意采用的 [fs 能力族立场](../README.md)）。 +- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见有意采用的 [fs 能力族立场](../README.md)）。 diff --git a/packages/fs/tool-fs/package.json b/packages/fs/tool-fs/package.json index 936d125013..737f7ac26b 100644 --- a/packages/fs/tool-fs/package.json +++ b/packages/fs/tool-fs/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-tool-fs", - "description": "Model-facing filesystem tools (list, read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)", + "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)", "version": "0.0.1", "private": true, "type": "module", diff --git a/packages/fs/tool-fs/src/index.ts b/packages/fs/tool-fs/src/index.ts index 7890d5084d..a4c96d606b 100644 --- a/packages/fs/tool-fs/src/index.ts +++ b/packages/fs/tool-fs/src/index.ts @@ -1,19 +1,16 @@ /** - * Model-facing list, read, write, and edit tools over `ctx.fs`. This package owns schemas, - * validation, read windows, listing order, formatting, and observation events, never a concrete - * provider. An optional event policy supplies mutation guards; without one the tools use - * unconditional provider calls. + * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation, + * read windows, formatting, and observation events, never a concrete provider. An optional + * event policy supplies mutation guards; without one the tools use unconditional provider calls. * @module @deepseek-ai/dsh-tool-fs */ import type { Context } from 'cordis' import z from 'schemastery' import type {} from '@deepseek-ai/dsh-user-approval' -import { applyListTool } from './list.ts' import { applyReadTool, READ_LIMIT, STREAM_MIN_SIZE } from './read.ts' import { applyWriteTool } from './write.ts' import { applyEditTool } from './edit.ts' -import { LIST_MAX_ENTRIES } from './list-render.ts' import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from './read-render.ts' import { FsSandboxSurface } from './sandbox.ts' @@ -25,8 +22,6 @@ export const inject = ['tools', 'fs', 'systemPrompt'] /** Plugin config (all optional — `Config` supplies the defaults). */ export interface Config { - /** Maximum entries one `list` page returns; the footer still reports the complete count. */ - listMaxEntries?: number /** Default and maximum number of lines returned by one `read` call. */ readLimit?: number /** Maximum characters returned for a single line before truncation. */ @@ -38,7 +33,6 @@ export interface Config { } export const Config: z = z.object({ - listMaxEntries: z.number().default(LIST_MAX_ENTRIES), readLimit: z.number().default(READ_LIMIT), readMaxLineLength: z.number().default(READ_MAX_LINE_LENGTH), readMaxBytes: z.number().default(READ_MAX_BYTES), @@ -48,23 +42,21 @@ export const Config: z = z.object({ /** The shape after schemastery applied the defaults. */ type ResolvedConfig = Required -/** Every read or listing cap counts lines/chars/bytes/entries — a positive integer, or windowing arithmetic misbehaves silently. */ +/** Every read cap counts lines/chars/bytes — a positive integer, or windowing arithmetic misbehaves silently. */ function assertPositiveInteger(name: string, value: number): void { if (!Number.isInteger(value) || value < 1) { throw new Error(`tool-fs: ${name} must be a positive integer`) } } -/** Register the full `list`/`read`/`write`/`edit` filesystem tool suite. */ +/** Register the full `read`/`write`/`edit` filesystem tool suite. */ export function apply(ctx: Context, config: Config): void { // schemastery (Config) has already filled every defaulted field. const resolved = config as ResolvedConfig - assertPositiveInteger('listMaxEntries', resolved.listMaxEntries) assertPositiveInteger('readLimit', resolved.readLimit) assertPositiveInteger('readMaxLineLength', resolved.readMaxLineLength) assertPositiveInteger('readMaxBytes', resolved.readMaxBytes) assertPositiveInteger('readStreamMinSize', resolved.readStreamMinSize) - applyListTool(ctx, { maxEntries: resolved.listMaxEntries }) applyReadTool(ctx, { limit: resolved.readLimit, maxLineLength: resolved.readMaxLineLength, diff --git a/packages/fs/tool-fs/src/list-render.ts b/packages/fs/tool-fs/src/list-render.ts deleted file mode 100644 index 86b57d02b3..0000000000 --- a/packages/fs/tool-fs/src/list-render.ts +++ /dev/null @@ -1,137 +0,0 @@ -/** - * Pure directory-listing presentation: order direct children, count complete - * composition, and render a bounded page without allowing filesystem text to - * forge the result envelope. - * @module @deepseek-ai/dsh-tool-fs/list-render - */ - -/** Default and maximum number of entries one `list` call returns (the `listMaxEntries` config). */ -export const LIST_MAX_ENTRIES = 200 - -/** One direct child in a directory listing. */ -export interface ListedEntry { - /** Basename of the child inside the listed directory. */ - name: string - /** Whether the child is a regular file, a directory, or something else. */ - type: 'file' | 'directory' | 'other' -} - -/** Complete-listing composition retained on every page. */ -export interface ListCounts { - directories: number - files: number - other: number -} - -/** Canonical bounded result returned by one `list` call. */ -export interface ListPage { - /** Backend display path of the listed directory. */ - path: string - /** 1-based index of the first returned entry. */ - offset: number - /** Current page in directory-first, name-sorted order. */ - entries: ListedEntry[] - /** Number of direct children in the complete listing. */ - totalEntries: number - /** Composition of the complete listing, not only this page. */ - counts: ListCounts -} - -/** - * Sort directories before files before other entries, each group by name. - * @param entries - direct children in provider order. - * @returns a new directory-first array without mutating `entries`. - */ -export function orderEntries(entries: readonly T[]): T[] { - const rank = { directory: 0, file: 1, other: 2 } - return [...entries].sort((a, b) => rank[a.type] - rank[b.type] || a.name.localeCompare(b.name)) -} - -/** - * Count every entry type in a complete listing. - * @param entries - every direct child in the listed directory. - * @returns the complete directory/file/other composition. - */ -export function countEntries(entries: readonly ListedEntry[]): ListCounts { - const counts: ListCounts = { directories: 0, files: 0, other: 0 } - for (const entry of entries) { - if (entry.type === 'directory') counts.directories += 1 - else if (entry.type === 'file') counts.files += 1 - else counts.other += 1 - } - return counts -} - -/** `1 directory` / `4 directories`. */ -function count(n: number, singular: string, plural: string): string { - return `${n} ${n === 1 ? singular : plural}` -} - -/** Complete-listing composition as model-facing prose. */ -function breakdown(counts: ListCounts): string { - const parts = [ - count(counts.directories, 'directory', 'directories'), - count(counts.files, 'file', 'files'), - ] - if (counts.other > 0) parts.push(`${counts.other} other`) - return parts.join(', ') -} - -/** - * Names this renderer cannot emit verbatim, because POSIX allows every byte but - * `/` and NUL in a name and each of these would make the listing say something - * untrue: - * - * - a control character (a newline above all) splits one entry across lines; - * - ` 1 || page.entries.length < page.totalEntries - ? `(Showing entries ${page.offset}-${end} of ${page.totalEntries}: ${breakdown(page.counts)}.` - + (end < page.totalEntries ? ` Use offset=${end + 1} to continue.)` : ')') - : `(${count(page.totalEntries, 'entry', 'entries')}: ${breakdown(page.counts)})` - const body = page.entries.length > 0 - ? `${page.entries.map(entry => `${renderName(entry.name)}${suffix[entry.type]}`).join('\n')}\n\n${footer}` - : footer - return `${renderName(page.path)} -directory - -${body} -` -} diff --git a/packages/fs/tool-fs/src/list.ts b/packages/fs/tool-fs/src/list.ts deleted file mode 100644 index 270e2803b8..0000000000 --- a/packages/fs/tool-fs/src/list.ts +++ /dev/null @@ -1,150 +0,0 @@ -/** - * Model-facing directory listing. It enumerates ONE directory level through the - * provider seam's `listDir`, orders children so a capped view keeps the - * navigable structure, and renders the entries with their type. - * - * This is the orientation tool: `glob` and `grep` answer "where is the thing I - * can already name", while `list` answers "what is here at all". `rg --files` - * never emits directories, so no pattern makes `glob` describe a directory's - * shape — the gap this tool closes. - * @module @deepseek-ai/dsh-tool-fs/list - */ - -import type { Context } from 'cordis' -import { defineTool } from '@deepseek-ai/dsh-tools' -import type { GenericCallView } from '@deepseek-ai/dsh-tools' -import { FsError } from '@deepseek-ai/dsh-fs' -import type {} from '@deepseek-ai/dsh-fs' -import type {} from '@deepseek-ai/dsh-system-prompt' -import { countEntries, formatListOutput, orderEntries } from './list-render.ts' -import { sessionResolveOptions } from './session-cwd.ts' - -/** Resolved list-tool caps — plugin config after defaulting (see `Config` in index.ts). */ -export interface ListToolCaps { - /** Maximum entries returned on one page; the footer still reports complete size and composition. */ - maxEntries: number -} - -/** Validated `list` arguments after defaulting. */ -export interface ListInput { - /** Directory to list; `.` means the calling agent's session workspace. */ - path: string - /** 1-based first entry to return from the directory-first ordering. */ - offset: number -} - -/** - * Validate value constraints the schema DSL can't express, and default an - * omitted `path` to `.` — the session workspace, so "what is in this project" - * needs no argument at all. - * - * @param args - the schema-validated `list` arguments. - * @returns the accepted input with `path` and `offset` defaulted. - */ -export function parseListArgs(args: { path?: string; offset?: number }): ListInput { - if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given') - const offset = args.offset ?? 1 - if (!Number.isInteger(offset) || offset < 1) throw new Error('offset must be a positive integer') - return { path: args.path ?? '.', offset } -} - -/** - * Pending-call presentation: a generic card titled by the directory, with a - * follow-along location so a capable editor can reveal it. - * - * @param args - the raw tool arguments; `path` and `offset` feed the title. - * @returns the generic card view shown while the call runs. - */ -export function presentListCall(args: { path?: string; offset?: number }): GenericCallView { - const path = args.path ?? '.' - const window = args.offset !== undefined ? ` (from entry ${args.offset})` : '' - return { card: 'generic', title: `List ${path}${window}`, kind: 'read', locations: [{ path }] } -} - -/** - * Register the `list` tool and its system-prompt guidance. - * - * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service. - * @param caps - the deployment's resolved list caps (plugin config after defaulting). - */ -export function applyListTool(ctx: Context, caps: ListToolCaps): void { - ctx.systemPrompt.section({ - name: 'tool:list', - order: 99, - text: 'Use the list tool — not shell ls — to see what a directory contains. It returns the direct children of one directory, files and subdirectories alike, ' - + 'and defaults to the session workspace, so it is the first step for orienting in an unfamiliar project. ' - + 'When a result is capped, continue with the offset named in its footer.', - }) - - ctx.tools.register(defineTool({ - name: 'list', - description: 'List the direct children of one directory, with their type. ' - + `Entries are directories first, then files, each alphabetical; up to ${caps.maxEntries} are returned from the requested offset, and the footer gives the complete count plus a next offset when more remain. ` - + 'It includes subdirectories and is the tool for seeing one directory\'s contents.', - parameters: { - path: { type: 'string', description: 'Directory to list. Defaults to the session workspace; a relative path resolves against it.' }, - offset: { type: 'number', description: '1-based first entry to return. Defaults to 1; use the footer value to continue.' }, - }, - output: { - schema: { - type: 'object', - additionalProperties: false, - properties: { - path: { type: 'string', required: true }, - offset: { type: 'integer', required: true }, - entries: { - type: 'array', - required: true, - items: { - type: 'object', - additionalProperties: false, - properties: { - name: { type: 'string', required: true }, - type: { type: 'string', required: true, enum: ['file', 'directory', 'other'] }, - }, - }, - }, - totalEntries: { type: 'integer', required: true }, - counts: { - type: 'object', - required: true, - additionalProperties: false, - properties: { - directories: { type: 'integer', required: true }, - files: { type: 'integer', required: true }, - other: { type: 'integer', required: true }, - }, - }, - }, - }, - render: (_args, value) => [{ type: 'text', text: formatListOutput(value) }], - }, - // Listing reads directory metadata only: no content, no version recorded, - // nothing a concurrent call could observe out of order. - isConcurrencySafe: () => true, - async execute(args, exec) { - const input = parseListArgs(args) - const target = await ctx.fs.resolve(input.path, sessionResolveOptions(exec, input.path)) - // No stat first: the seam already answers absence with FS_NOT_FOUND and a - // non-directory target with FS_NOT_DIRECTORY, so a probe would only add a - // round-trip and a second source of truth. (0 stat.) - const entries = orderEntries(await ctx.fs.listDir(target, exec.signal)) - if (input.offset > entries.length && !(entries.length === 0 && input.offset === 1)) { - throw new FsError( - `offset ${input.offset} is out of range for "${target.displayPath}" (${entries.length} entries)`, - 'FS_NOT_FOUND', - ) - } - return { - path: target.displayPath, - offset: input.offset, - entries: entries - .slice(input.offset - 1, input.offset - 1 + caps.maxEntries) - .map(({ name, type }) => ({ name, type })), - totalEntries: entries.length, - counts: countEntries(entries), - } - }, - presentCall: presentListCall, - })) -} diff --git a/packages/fs/tool-fs/tests/list-render.spec.ts b/packages/fs/tool-fs/tests/list-render.spec.ts deleted file mode 100644 index 792c91bd18..0000000000 --- a/packages/fs/tool-fs/tests/list-render.spec.ts +++ /dev/null @@ -1,79 +0,0 @@ -/** - * Pure listing-presentation tests: display ordering and the model-facing - * envelope, exercised without a context or provider. - */ - -import { describe, expect, it } from 'vitest' -import { countEntries, formatListOutput, orderEntries } from '../src/list-render.ts' -import type { ListedEntry, ListPage } from '../src/list-render.ts' - -const entry = (name: string, type: ListedEntry['type'] = 'file'): ListedEntry => ({ name, type }) - -function page(entries: ListedEntry[], options: { offset?: number; totalEntries?: number; all?: ListedEntry[] } = {}): ListPage { - const all = options.all ?? entries - return { - path: '/w', - offset: options.offset ?? 1, - entries, - totalEntries: options.totalEntries ?? all.length, - counts: countEntries(all), - } -} - -describe('orderEntries', () => { - it('groups directories, then files, then other, each by name', () => { - const ordered = orderEntries([ - entry('zeta.txt'), - entry('socket', 'other'), - entry('beta'), - entry('src', 'directory'), - entry('assets', 'directory'), - ]) - expect(ordered.map(e => e.name)).toEqual(['assets', 'src', 'beta', 'zeta.txt', 'socket']) - }) - - it('leaves the input array untouched and preserves extra entry fields', () => { - const input = [{ name: 'b', type: 'file' as const, size: 2 }, { name: 'a', type: 'file' as const, size: 1 }] - const ordered = orderEntries(input) - expect(input.map(e => e.name)).toEqual(['b', 'a']) - expect(ordered).toEqual([{ name: 'a', type: 'file', size: 1 }, { name: 'b', type: 'file', size: 2 }]) - }) -}) - -describe('formatListOutput', () => { - it('marks directories and non-regular children, and counts the whole listing', () => { - expect(formatListOutput(page([entry('src', 'directory'), entry('a.txt'), entry('sock', 'other')]))).toBe(`/w -directory - -src/ -a.txt -sock@ - -(3 entries: 1 directory, 1 file, 1 other) -`) - }) - - it('omits the "other" clause when every child is a file or a directory', () => { - expect(formatListOutput(page([entry('a.txt'), entry('b.txt')]))).toContain('(2 entries: 0 directories, 2 files)') - }) - - it('says a one-entry listing in the singular', () => { - expect(formatListOutput(page([entry('only', 'directory')]))).toContain('(1 entry: 1 directory, 0 files)') - }) - - it('states the complete size and composition when the view is capped', () => { - const entries = [entry('src', 'directory'), ...Array.from({ length: 5 }, (_, i) => entry(`f${i}.txt`))] - const rendered = formatListOutput(page(entries.slice(0, 2), { totalEntries: entries.length, all: entries })) - expect(rendered).toContain('src/\nf0.txt\n') - expect(rendered).not.toContain('f2.txt') - expect(rendered).toContain('(Showing entries 1-2 of 6: 1 directory, 5 files. Use offset=3 to continue.)') - }) - - it('renders an empty directory as a footer alone', () => { - expect(formatListOutput(page([]))).toBe(`/w -directory - -(Empty directory) -`) - }) -}) diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts index 53b58d2dcf..de844dcaf4 100644 --- a/packages/fs/tool-fs/tests/tools.spec.ts +++ b/packages/fs/tool-fs/tests/tools.spec.ts @@ -38,7 +38,6 @@ const testToolSignal = new AbortController().signal class FakeFs extends FileSystem { files = new Map() rejectWith?: FsError - dirs = new Map() writeIntents: (FsWriteIntent | undefined)[] = [] editIntents: ({ version: FsVersion } | undefined)[] = [] @@ -67,9 +66,8 @@ class FakeFs extends FileSystem { const content = this.files.get(target.targetKey) ?? '' return (async function* () { yield content })() } - override async listDir(target: FsTarget): Promise { - this.throwIfArmed() - return this.dirs.get(target.targetKey) ?? [] + override async listDir(_target: FsTarget): Promise { + return [] } override async writeText(target: FsTarget, content: string, expected?: FsWriteIntent): Promise { this.throwIfArmed() @@ -141,15 +139,13 @@ describe('session cwd resolution', () => { }) describe('registration', () => { - it('registers list, read, write, and edit', async () => { + it('registers read, write, and edit', async () => { const { ctx } = await setup() - expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['edit', 'list', 'read', 'write']) + expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['edit', 'read', 'write']) }) - it('declares list and read parallel-safe while write/edit remain exclusive', async () => { + it('declares read parallel-safe while write/edit remain exclusive', async () => { const { ctx } = await setup() - expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('list-safe'), name: 'list', arguments: {} })) - .toEqual({ kind: 'parallel' }) expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('read-safe'), name: 'read', arguments: { file_path: 'a.txt' } })) .toEqual({ kind: 'parallel' }) expect(ctx.tools.executionMode({ signal: testToolSignal, callId: CallId('write-exclusive'), name: 'write', arguments: { file_path: 'a.txt', content: 'x' } })) @@ -161,8 +157,6 @@ describe('registration', () => { it('registers prompt sections for each tool', async () => { const { ctx } = await setup() const prompt = renderPrompt(await ctx.systemPrompt.assemble()) - expect(prompt).toContain('Use the list tool') - expect(prompt).not.toContain('glob or grep') expect(prompt).toContain('Use the read tool') expect(prompt).toContain('Use the write tool') expect(prompt).toContain('Use the edit tool') @@ -185,10 +179,9 @@ describe('registration', () => { const fiber = await ctx.plugin(ToolFs) // Each tool contributes BOTH a schema and a prompt section; disposal must // withdraw both, not just the schemas. - expect(ctx.tools.schemas()).toHaveLength(4) + expect(ctx.tools.schemas()).toHaveLength(3) const sectionNames = (a: { sections: { name: string }[] }) => a.sections.map(s => s.name).sort() - expect(sectionNames(await ctx.systemPrompt.assemble())) - .toEqual(['deployment:persona', 'harness:identity', 'tool:edit', 'tool:list', 'tool:read', 'tool:write']) + expect(sectionNames(await ctx.systemPrompt.assemble())).toEqual(['deployment:persona', 'harness:identity', 'tool:edit', 'tool:read', 'tool:write']) await fiber.dispose() expect(ctx.tools.schemas()).toHaveLength(0) // Only the system-prompt plugin's own built-in sections remain. @@ -196,144 +189,6 @@ describe('registration', () => { }) }) -describe('list tool', () => { - /** Seed one directory's children; `listDir` order is deliberately NOT display order. */ - function seedDir(fs: FakeFs, path: string, children: readonly { name: string; type: 'file' | 'directory' | 'other' }[]): void { - fs.dirs.set(`key:${path}`, children.map(({ name, type }) => ({ - name, - type, - target: { targetKey: FsTargetKey(`key:${path}/${name}`), displayPath: `/abs/${path}/${name}` }, - }))) - } - - it('defaults to the session workspace and shows directories before files', async () => { - const { ctx, fs } = await setup() - seedDir(fs, '.', [ - { name: 'notes.md', type: 'file' }, - { name: 'zeroomega-3.3.23', type: 'directory' }, - { name: 'archive', type: 'directory' }, - { name: 'link-to-nowhere', type: 'other' }, - ]) - const result = await call(ctx, 'list', {}) - expect(result.isError).toBe(false) - if (result.isError) throw new Error('expected list success') - // The canonical value carries display order, so a Code Mode caller and the - // model see the same ordering contract. - expect(result.value).toEqual({ - path: '/abs/.', - offset: 1, - entries: [ - { name: 'archive', type: 'directory' }, - { name: 'zeroomega-3.3.23', type: 'directory' }, - { name: 'notes.md', type: 'file' }, - { name: 'link-to-nowhere', type: 'other' }, - ], - totalEntries: 4, - counts: { directories: 2, files: 1, other: 1 }, - }) - expect(text(result)).toBe(`/abs/. -directory - -archive/ -zeroomega-3.3.23/ -notes.md -link-to-nowhere@ - -(4 entries: 2 directories, 1 file, 1 other) -`) - }) - - it('lists an explicit path and reports an empty directory as such', async () => { - const { ctx, fs } = await setup() - seedDir(fs, 'empty', []) - const result = await call(ctx, 'list', { path: 'empty' }) - expect(text(result)).toContain('(Empty directory)') - expect(text(result)).toContain('/abs/empty') - }) - - it('caps the rendered entries but still reports the complete composition', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRegistry) - await ctx.plugin(FakeFs) - await ctx.plugin(ToolFs, { listMaxEntries: 2 }) - const fs = ctx.fs as FakeFs - seedDir(fs, '.', [ - { name: 'a.txt', type: 'file' }, - { name: 'b.txt', type: 'file' }, - { name: 'c.txt', type: 'file' }, - { name: 'src', type: 'directory' }, - ]) - const result = await call(ctx, 'list', {}) - const rendered = text(result) - // The one directory survives the cap because directories sort first — the - // failure mode this ordering exists to prevent. - expect(rendered).toContain('src/\na.txt\n') - expect(rendered).not.toContain('c.txt') - expect(rendered).toContain('(Showing entries 1-2 of 4: 1 directory, 3 files. Use offset=3 to continue.)') - if (result.isError) throw new Error('expected list success') - expect(result.value).toEqual({ - path: '/abs/.', - offset: 1, - entries: [{ name: 'src', type: 'directory' }, { name: 'a.txt', type: 'file' }], - totalEntries: 4, - counts: { directories: 1, files: 3, other: 0 }, - }) - - const continuation = await call(ctx, 'list', { offset: 3 }) - expect(text(continuation)).toContain('b.txt\nc.txt') - expect(text(continuation)).toContain('(Showing entries 3-4 of 4: 1 directory, 3 files.)') - }) - - it('rejects a blank path and surfaces provider failures', async () => { - const { ctx, fs } = await setup() - const blank = await call(ctx, 'list', { path: ' ' }) - expect(blank.isError).toBe(true) - expect(text(blank)).toContain('path must be a non-empty string when given') - - fs.rejectWith = new FsError('cannot list "/abs/a.txt": not a directory', 'FS_NOT_DIRECTORY') - const failed = await call(ctx, 'list', { path: 'a.txt' }) - expect(failed.isError).toBe(true) - expect(failed.error).toMatchObject({ info: { code: 'FS_NOT_DIRECTORY' } }) - }) - - it('rejects invalid and out-of-range continuation offsets', async () => { - const { ctx, fs } = await setup() - seedDir(fs, '.', [{ name: 'only.txt', type: 'file' }]) - expect(text(await call(ctx, 'list', { offset: 0 }))).toContain('offset must be a positive integer') - expect(text(await call(ctx, 'list', { offset: 1.5 }))).toContain('offset must be a positive integer') - expect(text(await call(ctx, 'list', { offset: 2 }))).toContain('offset 2 is out of range') - }) - - it('encodes filesystem names without allowing them to forge the envelope or type marker', async () => { - const { ctx, fs } = await setup() - seedDir(fs, '.', [ - { name: 'regular@', type: 'file' }, - { name: 'special', type: 'other' }, - { name: 'fake\n', type: 'file' }, - ]) - const rendered = text(await call(ctx, 'list', {})) - // A regular file really named `regular@` must not read as a socket named - // `regular`, and a newline in a name must not become a second entry. - expect(rendered).toContain('"regular@"\nspecial@') - expect(rendered).toContain('"fake\\n<\\/content>"') - expect(rendered.match(/<\/content>/g)).toHaveLength(1) - }) - - it('records no observation, so a listing never authorizes a mutation', async () => { - const { ctx, fs } = await setup() - fs.files.set('key:a.txt', 'hello') - seedDir(fs, '.', [{ name: 'a.txt', type: 'file' }]) - const observed = vi.fn() - ctx.on('fs/observed', observed) - await call(ctx, 'list', {}) - expect(observed).not.toHaveBeenCalled() - // Seeing a name is not reading a file: the policy gate still demands a read. - const edit = await call(ctx, 'edit', { file_path: 'a.txt', old_string: 'h', new_string: 'j' }, { session: { header: {} } }) - expect(edit.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } }) - }) -}) - describe('read tool', () => { it('formats line-numbered content with a footer', async () => { const { ctx, fs } = await setup() @@ -589,18 +444,6 @@ describe('tool-owned presentation (pure presentCall)', () => { }) }) - it('list: titles by the directory, falling back to the workspace "." when unset', async () => { - expect(await presentCall('list', { path: 'src' })).toEqual({ - card: 'generic', title: 'List src', kind: 'read', locations: [{ path: 'src' }], - }) - expect(await presentCall('list', {})).toEqual({ - card: 'generic', title: 'List .', kind: 'read', locations: [{ path: '.' }], - }) - expect(await presentCall('list', { path: 'src', offset: 201 })).toEqual({ - card: 'generic', title: 'List src (from entry 201)', kind: 'read', locations: [{ path: 'src' }], - }) - }) - it('read: bare title and line-1 location when offset/limit are unset', async () => { expect(await presentCall('read', { file_path: 'a.txt' })).toEqual({ card: 'generic', title: 'Read a.txt', kind: 'read', locations: [{ path: 'a.txt', line: 1 }], @@ -813,7 +656,6 @@ describe('read caps are plugin config', () => { }) it.each([ - ['listMaxEntries', { listMaxEntries: 0 }], ['readLimit', { readLimit: 0 }], ['readLimit', { readLimit: 2.5 }], ['readMaxLineLength', { readMaxLineLength: -1 }], diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index c507ae0e0d..7bdc8b68a8 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -230,7 +230,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFs) }, note: - '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. `list` paginates one directory level through `ctx.fs.listDir` and records no observation, so seeing a filename never satisfies that read-before-write gate.', + '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.', }, { pkg: '@deepseek-ai/dsh-tool-fs-search', @@ -248,7 +248,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolFsSearch) }, note: - 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. An over-cap glob result does not return the head of the sorted list: its inline page is taken round-robin across entries immediately beneath the actual search root and the footer states that basis, because modification-time order is ascending and the restored timestamps of an unpacked archive put one subtree in front of every broad match.', + 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.', }, { pkg: '@deepseek-ai/dsh-tool-pty', From 6b79ce08c580c1921f545ac447b543cbc3970893 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Tue, 28 Jul 2026 16:21:29 +0800 Subject: [PATCH 07/67] test(fs-search): minimize glob snapshot composition Boot the glob sampling scenario from a standalone ACP composition that exposes only bash, glob, and grep. Regenerate the smaller header fixtures and trim implementation narration already owned by the Agent Note. --- .../2026-07-27-glob-sampling.i18n.yaml | 4 +- .../bug-fix/2026-07-27-glob-sampling.md | 2 +- .../bug-fix/2026-07-27-glob-sampling.zh.md | 2 +- .../acp-agent/fs-search.cordis.snapshot.yml | 24 - examples/acp-agent/fs-search.cordis.yml | 13 - examples/acp-agent/tests/acp.snapshot.ts | 2 +- .../tests/fs-search.cordis.snapshot.yml | 34 ++ examples/acp-agent/tests/fs-search.cordis.yml | 32 ++ .../system-prompt.expected.md | 22 +- .../tool-schemas.expected.json | 437 +----------------- packages/fs/tool-fs-search/src/glob.ts | 35 +- 11 files changed, 78 insertions(+), 529 deletions(-) delete mode 100644 examples/acp-agent/fs-search.cordis.snapshot.yml delete mode 100644 examples/acp-agent/fs-search.cordis.yml create mode 100644 examples/acp-agent/tests/fs-search.cordis.snapshot.yml create mode 100644 examples/acp-agent/tests/fs-search.cordis.yml diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml index 88e4ec9fc8..7c11db5207 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md -2026-07-27-glob-sampling.md: c583f0cd8110684a94d0cd04f5cf2ae861ce7aa3 -2026-07-27-glob-sampling.zh.md: 97025a7714237fc716dee745a858140cd783ba2d +2026-07-27-glob-sampling.md: b9dfc7fc89ff61824094ccd5297f766c665f4edb +2026-07-27-glob-sampling.zh.md: 4f022467e461247c746e906b32f5ecffcb885d56 diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md index c583f0cd81..b9dfc7fc89 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md @@ -42,4 +42,4 @@ The tool surface does not grow. The fix changes glob's prompt, schema descriptio ## Testing -Package tests pin concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario boots the real Loader/app/sandbox-bash composition and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head. +Package tests pin concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario boots a minimal real Loader/app/local-bash composition and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head. diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md index 97025a7714..4f022467e4 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md @@ -42,4 +42,4 @@ footer 会说明当前页面是跨条目的样本，而不是按修改时间排 ## 测试 -包测试锁定了结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会启动真实的 Loader/app/sandbox-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。 +包测试锁定了结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会启动最小化的真实 Loader/app/local-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。 diff --git a/examples/acp-agent/fs-search.cordis.snapshot.yml b/examples/acp-agent/fs-search.cordis.snapshot.yml deleted file mode 100644 index 1541cd96ce..0000000000 --- a/examples/acp-agent/fs-search.cordis.snapshot.yml +++ /dev/null @@ -1,24 +0,0 @@ -# Keyless counterpart to fs-search.cordis.yml: the search plugin and sandboxed -# bash execution remain real; only the model adapter is replaced by replay. -- id: base - name: '@cordisjs/plugin-include' - config: - path: ./cordis.yml - patches: - - id: llm-deepseek - name: '@deepseek-ai/dsh-llm-deepseek' - disabled: true - - insert: - - id: llm-replay - name: '@deepseek-ai/dsh-llm-replay' - config: - providers: - - id: deepseek - name: DeepSeek - models: - - id: deepseek-v4-flash - - id: deepseek-v4-pro - - id: tool-fs-search - name: '@deepseek-ai/dsh-tool-fs-search' - config: - globMaxResults: 4 diff --git a/examples/acp-agent/fs-search.cordis.yml b/examples/acp-agent/fs-search.cordis.yml deleted file mode 100644 index fd1eec2a38..0000000000 --- a/examples/acp-agent/fs-search.cordis.yml +++ /dev/null @@ -1,13 +0,0 @@ -# Search snapshot composition: mount the real model-facing search plugin over -# the shipped sandboxed bash stack. A four-path inline cap keeps the fixture -# small while forcing the over-cap sampling branch. -- id: base - name: '@cordisjs/plugin-include' - config: - path: ./cordis.yml - patches: - - insert: - - id: tool-fs-search - name: '@deepseek-ai/dsh-tool-fs-search' - config: - globMaxResults: 4 diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 9af14d850f..28e814a258 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -42,7 +42,7 @@ const RETRY_CONFIG = fileURLToPath(new URL('../retry.cordis.yml', import.meta.ur const SESSION_TITLE_CONFIG = fileURLToPath(new URL('../session-title.cordis.yml', import.meta.url)) const LSP_CONFIG = fileURLToPath(new URL('./lsp.cordis.yml', import.meta.url)) const WEB_CONFIG = fileURLToPath(new URL('../web.cordis.yml', import.meta.url)) -const FS_SEARCH_CONFIG = fileURLToPath(new URL('../fs-search.cordis.yml', import.meta.url)) +const FS_SEARCH_CONFIG = fileURLToPath(new URL('./fs-search.cordis.yml', import.meta.url)) const FS_SEARCH_BIN = fileURLToPath(new URL('./fixtures/fs-search-bin', import.meta.url)) const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots') const PACKED_CHUNKS_SOURCE = 'hook-cc-pretool-deny' diff --git a/examples/acp-agent/tests/fs-search.cordis.snapshot.yml b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml new file mode 100644 index 0000000000..e1755ec9d4 --- /dev/null +++ b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml @@ -0,0 +1,34 @@ +# Minimal keyless composition: real app, bash, and search tool; replayed model. +- id: llm-replay + name: '@deepseek-ai/dsh-llm-replay' + config: + providers: + - id: deepseek + name: DeepSeek + models: + - id: deepseek-v4-pro + +- id: subprocess + name: '@deepseek-ai/dsh-subprocess-local' + +- id: bash + name: '@deepseek-ai/dsh-bash-local' + +- id: acp-agent + name: '@deepseek-ai/dsh-acp-demo' + config: + provider: deepseek + model: deepseek-v4-pro + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + persistenceCompression: none + workspaceContext: false + skills: + enabled: false + toolTasks: false + goals: false + persona: You are a concise snapshot agent working in {{cwd}}. + +- id: tool-fs-search + name: '@deepseek-ai/dsh-tool-fs-search' + config: + globMaxResults: 4 diff --git a/examples/acp-agent/tests/fs-search.cordis.yml b/examples/acp-agent/tests/fs-search.cordis.yml new file mode 100644 index 0000000000..171ab88980 --- /dev/null +++ b/examples/acp-agent/tests/fs-search.cordis.yml @@ -0,0 +1,32 @@ +# Minimal live counterpart for the glob-sampling snapshot composition. +- 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: + - id: deepseek-v4-pro + +- id: subprocess + name: '@deepseek-ai/dsh-subprocess-local' + +- id: bash + name: '@deepseek-ai/dsh-bash-local' + +- id: acp-agent + name: '@deepseek-ai/dsh-acp-demo' + config: + provider: deepseek + model: deepseek-v4-pro + persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions' + workspaceContext: false + skills: + enabled: false + toolTasks: false + goals: false + persona: You are a concise snapshot agent working in {{cwd}}. + +- id: tool-fs-search + name: '@deepseek-ai/dsh-tool-fs-search' + config: + globMaxResults: 4 diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md index 467b05904b..eb22966cdb 100644 --- a/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/system-prompt.expected.md @@ -1,29 +1,9 @@ You are an AI agent powered by the DeepSeek Harness SDK. -You are a coding assistant powered by the deepseek-v4-pro model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug. - -Verify your work by running the code or tests. Keep answers brief and factual. - - -Use 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. - -Use 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. - -Use 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. +You are a concise snapshot agent working in {{cwd}}. Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context. Check the [exit code: N] marker on every bash result; investigate failures before moving on. - -Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering. - -Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked. - -Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`). - - -Use 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. - -Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out. diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json index 1b25291c5c..4cb292798a 100644 --- a/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/tool-schemas.expected.json @@ -2,7 +2,7 @@ "initial": [ { "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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.", + "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]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. 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; read its output with `task_output` and stop it with `task_kill`.", "parameters": { "type": "object", "properties": { @@ -25,18 +25,6 @@ "run_in_background": { "type": "boolean", "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies." - }, - "sandbox_permissions": { - "type": "string", - "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.", - "enum": [ - "workspace-write", - "danger-full-access" - ] - }, - "justification": { - "type": "string", - "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access." } }, "required": [ @@ -45,76 +33,6 @@ ] } }, - { - "name": "create_goal", - "description": "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.", - "parameters": { - "type": "object", - "properties": { - "objective": { - "type": "string", - "description": "The concrete completion objective inferred from the direct human request." - }, - "max_goal_rounds": { - "type": "number", - "description": "Optional positive safe-integer limit on automatic continuation rounds." - } - }, - "required": [ - "objective" - ] - } - }, - { - "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." - }, - "sandbox_permissions": { - "type": "string", - "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.", - "enum": [ - "workspace-write", - "danger-full-access" - ] - }, - "justification": { - "type": "string", - "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access." - } - }, - "required": [ - "file_path", - "old_string", - "new_string" - ] - } - }, - { - "name": "get_goal", - "description": "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.", - "parameters": { - "type": "object", - "properties": {} - } - }, { "name": "glob", "description": "Find files whose paths match a glob pattern. Returns matching file paths — never directories — including hidden and ignored files (VCS metadata directories are excluded). Up to 4 paths come back in modification-time order; a larger result instead returns 4 paths sampled across top-level entries, says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries.", @@ -158,359 +76,6 @@ "pattern" ] } - }, - { - "name": "ralph", - "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.", - "parameters": { - "type": "object", - "properties": { - "objective": { - "type": "string", - "description": "The immutable completion objective for every fresh Ralph round." - }, - "maxRounds": { - "type": "number", - "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling." - } - }, - "required": [ - "objective" - ] - } - }, - { - "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": "skill", - "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.", - "parameters": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The exact skill name from the available skills list." - } - }, - "required": [ - "name" - ] - } - }, - { - "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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", - "parameters": { - "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." - }, - "run_in_background": { - "type": "boolean", - "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." - } - }, - "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. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", - "parameters": { - "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." - }, - "run_in_background": { - "type": "boolean", - "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." - } - }, - "required": [ - "description", - "prompt" - ] - } - }, - { - "name": "task_kill", - "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.", - "parameters": { - "type": "object", - "properties": { - "task_id": { - "type": "string", - "description": "Task id returned by the tool that started the background work." - }, - "reason": { - "type": "string", - "description": "Optional short reason, recorded in the log and forwarded to the task." - } - }, - "required": [ - "task_id" - ] - } - }, - { - "name": "task_list", - "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.", - "parameters": { - "type": "object", - "properties": {} - } - }, - { - "name": "task_output", - "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.", - "parameters": { - "type": "object", - "properties": { - "task_id": { - "type": "string", - "description": "Task id returned by the tool that started the background work." - }, - "wait": { - "type": "boolean", - "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive." - }, - "timeout_ms": { - "type": "number", - "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum." - } - }, - "required": [ - "task_id" - ] - } - }, - { - "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", - "additionalProperties": false, - "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": "update_goal", - "description": "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.", - "parameters": { - "type": "object", - "properties": { - "goal_id": { - "type": "string", - "description": "Exact id returned by get_goal." - }, - "revision": { - "type": "number", - "description": "Exact positive revision returned by get_goal." - }, - "action": { - "type": "string", - "description": "edit | pause | resume | complete | blocked", - "enum": [ - "edit", - "pause", - "resume", - "complete", - "blocked" - ] - }, - "objective": { - "type": "string", - "description": "Replacement objective; valid only with action edit." - }, - "max_goal_rounds": { - "type": "number", - "description": "Replacement cap; valid only with action edit." - }, - "blocked_reason": { - "type": "string", - "description": "Concrete blocking condition; required only with action blocked." - } - }, - "required": [ - "goal_id", - "revision", - "action" - ] - } - }, - { - "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?, provider?, 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/oneOf — no 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), and independent `provider`/`model` LLM target overrides (either may be provided alone). 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).", - "additionalProperties": true, - "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", - "additionalProperties": true, - "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." - }, - "provider": { - "type": "string", - "description": "Optional provider override this phase is expected to use." - }, - "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\": [...]}).", - "additionalProperties": true - } - }, - "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." - }, - "sandbox_permissions": { - "type": "string", - "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.", - "enum": [ - "workspace-write", - "danger-full-access" - ] - }, - "justification": { - "type": "string", - "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access." - } - }, - "required": [ - "file_path", - "content" - ] - } } ], "changes": [] diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index 94d9b0e627..12af97a24b 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -5,13 +5,6 @@ * model-facing schema, argument validation, shell-safe command construction, * result parsing, inline sampling, and formatting; process concerns (defaulting, * scrubbing, kill, backend substitution) stay behind `ctx.bash`. - * - * A complete result keeps ripgrep's modification-time order. A result too large - * to show inline does NOT: its inline page is sampled across the complete - * result's top-level entries ({@link sampleAcrossTopLevel}), because the sorted - * head of a broad match is routinely one subtree's worth of files and reads as - * if the workspace held nothing else. - * * @module @deepseek-ai/dsh-tool-fs-search/glob */ @@ -145,19 +138,9 @@ function topLevelSegment(path: string): string { * Choose the inline page of an over-cap result by round-robin across the * complete result's top-level entries, instead of taking its head. * - * `--sort=modified` (oldest first) is the right order for a complete result and - * the wrong basis for a sample of one: a broad pattern in a workspace holding one - * unpacked archive — whose restored timestamps predate everything the user - * wrote — gives a head that is entirely that subtree, and the model reads the - * page as the workspace. Round-robin gives every top-level entry a slot before - * any entry gets a second, so the page spans the tree; an entry that runs out of - * paths drops out and its remaining slots go to the rest. - * - * Modification-time order survives where it still means something: groups are - * visited in the order ripgrep first emits them, and each group's own paths keep - * their relative order. With one path per group — a flat result — this - * reproduces the sorted head exactly, so nothing changes for a result that has - * no subtree to hide. + * Every top-level entry receives a slot before any receives a second; exhausted + * groups drop out. Group order and order within each group follow `paths`, so a + * flat result reproduces the modification-time head. * * @param paths - the complete result, in ripgrep's modification-time order. * @param maxItems - how many paths the page may hold; the caller has already established it is smaller than `paths`. @@ -191,16 +174,8 @@ export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number, } /** - * Format a CAPPED `glob` result: the inline page, then a footer stating that - * the page is a cross-directory sample rather than the most recent paths, how - * much of the top level it reaches, and either the formatted-spill recovery - * locator or the could-not-save explanation. The omitted count is a budget - * fact: the search itself completed. A result that fits inline never reaches - * here — it is emitted verbatim, in ripgrep's order. - * - * A result whose every path is its own top-level entry keeps the plain footer: - * the sample is the modification-time-ordered head, and naming a spread would only - * restate the path counts already there. + * Format a capped sampled page and its complete-result recovery path. A flat + * result keeps the plain footer because its sample is the modification-time head. * * @param sample - the inline page and its top-level spread. * @param seen - how many paths the complete result holds; always more than the page. From ec0786e099e487526785e4bdf870868ed640e9aa Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 28 Jul 2026 17:30:12 +0800 Subject: [PATCH 08/67] feat(settings): add user-settings seam (ctx.settings) + file provider MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two-package capability family mirroring session-persistence/: - dsh-settings: abstract Settings service — namespace registry with caller-fiber effect registrations, layered resolution (schema defaults < composition base < user document), schemastery validation, per-namespace deep-equal commit detection, and the settings/updated event. Boot/registration validation fails loud; provider publishes keep last-good per namespace. - dsh-settings-local: settings.yaml/.json provider — resolveSpec defaulting to $DSH_HOME/settings.yaml, chokidar hot reload, content-equality self-write suppression, atomic 0600 tmp+rename writes, comment-preserving YAML namespace patching. Consumers register inside ctx.inject(['settings'], …), so every composition works unchanged without a mounted provider. Real Loader + Include composition test proves cordis.yml boot and external-edit hot propagation; HMR disposal test proves registry cleanup. Both packages hold per-file 100% coverage. Doc budgets rise 1705→1710 (AGENTS.md) and 835→845 (packages/README.md): one structural line per file for the new package group. Agent Note: .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md --- .../2026-07-28-user-settings-seam.i18n.yaml | 6 + .../2026-07-28-user-settings-seam.md | 35 ++ .../2026-07-28-user-settings-seam.zh.md | 35 ++ AGENTS.md | 1 + docs/capability-seams.md | 6 + docs/config-catalog.md | 19 ++ docs/cordis-catalog/events.md | 22 ++ docs/cordis-catalog/services.md | 42 +++ docs/event-producer-consumer.md | 1 + packages/README.i18n.yaml | 4 +- packages/README.md | 1 + packages/README.zh.md | 1 + .../cordis/tool-cordis/src/api-catalog.ts | 49 +++ packages/settings/README.i18n.yaml | 6 + packages/settings/README.md | 12 + packages/settings/README.zh.md | 12 + .../settings/settings-local/README.i18n.yaml | 6 + packages/settings/settings-local/README.md | 36 ++ packages/settings/settings-local/README.zh.md | 36 ++ packages/settings/settings-local/package.json | 46 +++ packages/settings/settings-local/src/index.ts | 226 +++++++++++++ .../settings/settings-local/src/invariant.ts | 31 ++ .../tests/loader-composition.spec.ts | 112 +++++++ .../settings-local/tests/local.spec.ts | 254 +++++++++++++++ .../settings-local/tests/watcher.spec.ts | 118 +++++++ .../settings/settings-local/tsconfig.json | 30 ++ packages/settings/settings/README.i18n.yaml | 6 + packages/settings/settings/README.md | 35 ++ packages/settings/settings/README.zh.md | 35 ++ packages/settings/settings/package.json | 41 +++ packages/settings/settings/src/index.ts | 304 +++++++++++++++++ packages/settings/settings/src/invariant.ts | 41 +++ .../settings/settings/tests/invariant.spec.ts | 41 +++ packages/settings/settings/tests/memory.ts | 53 +++ .../settings/settings/tests/settings.spec.ts | 307 ++++++++++++++++++ packages/settings/settings/tsconfig.json | 27 ++ pnpm-lock.yaml | 40 +++ scripts/doc-budgets.manifest.json | 4 +- scripts/gen-cordis-catalog.ts | 6 + scripts/gen-doc-graphs.ts | 9 + .../verify-package-readme-model-experience.ts | 2 + tsconfig.base.json | 2 + tsconfig.host.json | 2 + 43 files changed, 2098 insertions(+), 4 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md create mode 100644 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md create mode 100644 packages/settings/README.i18n.yaml create mode 100644 packages/settings/README.md create mode 100644 packages/settings/README.zh.md create mode 100644 packages/settings/settings-local/README.i18n.yaml create mode 100644 packages/settings/settings-local/README.md create mode 100644 packages/settings/settings-local/README.zh.md create mode 100644 packages/settings/settings-local/package.json create mode 100644 packages/settings/settings-local/src/index.ts create mode 100644 packages/settings/settings-local/src/invariant.ts create mode 100644 packages/settings/settings-local/tests/loader-composition.spec.ts create mode 100644 packages/settings/settings-local/tests/local.spec.ts create mode 100644 packages/settings/settings-local/tests/watcher.spec.ts create mode 100644 packages/settings/settings-local/tsconfig.json create mode 100644 packages/settings/settings/README.i18n.yaml create mode 100644 packages/settings/settings/README.md create mode 100644 packages/settings/settings/README.zh.md create mode 100644 packages/settings/settings/package.json create mode 100644 packages/settings/settings/src/index.ts create mode 100644 packages/settings/settings/src/invariant.ts create mode 100644 packages/settings/settings/tests/invariant.spec.ts create mode 100644 packages/settings/settings/tests/memory.ts create mode 100644 packages/settings/settings/tests/settings.spec.ts create mode 100644 packages/settings/settings/tsconfig.json diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml new file mode 100644 index 0000000000..cc409d8403 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md +2026-07-28-user-settings-seam.md: f0f45d77c8f98fc15625b1a1bf116ec10b965676 +2026-07-28-user-settings-seam.zh.md: eb562099b1ff0b5b0a019e9956d6e36e71857236 diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md new file mode 100644 index 0000000000..f0f45d77c8 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md @@ -0,0 +1,35 @@ +# Agent Note: user-settings seam (`ctx.settings`) and the file provider + +Status: implemented + +English | [中文](2026-07-28-user-settings-seam.zh.md) + +> Scope: the `packages/settings/` capability family — the abstract seam, the file-backed provider, and the composition boundary between user settings and `cordis.yml`. The [web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) recorded "the profile write path" as a deferral; this seam is that write path's owner. Consumer migrations (theme, locale, default model route) and the web `settings.*` RPC surface are follow-ups, not part of this note's shipped scope. + +## Problem + +User-editable configuration had no owner: `dsh web` read a cwd-anchored profile json through a static whitelist with no write path, the TUI read `$DSH_HOME/config.yaml` raw loader patches, and both froze at boot. A personal-settings page (web GUI) needs one cross-surface user layer with schema validation, a write path, and hot propagation — and peer products (Codex, Claude Code, Kimi, OpenCode, Pi) all converged on separating user preferences from extension composition. Loader-reactive config updates cannot carry this: `fiber.update` swaps entry config in place, so a plugin that read config at construction observes nothing and no callback tells it otherwise. + +## Decision + +**Two planes with a litmus test.** `cordis.yml` (+ Include patches) stays the composition plane: which plugins exist, wiring, deployment config, owned by the orchestrator and upgraded with the product. A settings namespace carries only the user-editable subset; the test is "should the personal config page edit it?" Values live in both planes without ambiguity because layering is the contract: schema defaults, then the registrant's composition `base` (its entry-config subset), then the user document section. + +**Three-package seam mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `/settings.yaml`), chokidar watch, atomic `0600` tmp+rename writes, comment-preserving YAML patching of exactly one namespace key, and content-equality self-write suppression. + +**Registrations are caller-fiber effects.** `register()` runs through the service proxy, so `this.ctx` is the registrant's context and the registration rides `ctx.effect`: disposing the registrant removes the namespace and its watchers (proven by the HMR disposal test), while the user's section keeps living in storage for the next owner. + +**Fail loud at rest, last-good in motion.** Boot-time and registration-time validation throw (invalid stored section fails the registering plugin; an existing-but-unparsable document fails provider load). Once live, a bad external edit warns and keeps the last good state per namespace — a hot reload must never take the process down. This asymmetry mirrors `Include.refresh()` and Kimi's safe runtime reload. + +**Consumers stay optional-by-construction.** A consumer registers inside `ctx.inject(['settings'], …)`; without a mounted provider it keeps resolving entry config alone, so every existing composition, demo, and snapshot works unchanged and migration is per-plugin. + +## Alternatives considered + +- **Include write-back as the user layer** (per-plugin config pages writing loader entry files, cordis-webui style): write-back would target per-composition files, binding user preferences to one `cordis.yml`; a per-user layer must survive template upgrades and serve TUI and web from one document. +- **Loader-reactive `fiber.update` as the propagation channel**: constructor-time reads observe nothing; the seam's explicit `watch()` makes hot-update a consumer contract instead of framework magic. +- **A domain-aware settings service** (getters per product area): the coupling objection from design review stands; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema. +- **Multi-layer precedence now** (system/managed/project tiers à la Codex/Claude Code): deferred until a real second layer exists; the resolve step is the single place layering would extend. +- **A cross-process lockfile now** (Pi's proper-lockfile): atomic replace plus watcher convergence (last write wins) is documented behavior until real contention shows up. + +## Consequences + +Deferred, in dependency order: the web `settings.raw`/`settings.describe`/`settings.update` RPC surface (which must redact `role('secret')` fields before exposure); first consumer migrations (`ui-theme`, locale, api-gateway default route) retiring `PROFILE_MAPPINGS` and the profile json; `${env:VAR}` value indirection for secrets; provider-side layering. The keyless snapshot obligation lands with the first model- or product-user-visible consumer, not with this infrastructure step. diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md new file mode 100644 index 0000000000..eb562099b1 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md @@ -0,0 +1,35 @@ +# Agent Note：用户设置 seam（`ctx.settings`）与文件 provider + +Status: implemented + +[English](2026-07-28-user-settings-seam.md) | 中文 + +> 范围：`packages/settings/` 能力族——抽象 seam、文件 provider，以及用户设置与 `cordis.yml` 的组合边界。[web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) 曾把"profile 写路径"记为延后项；本 seam 就是该写路径的归属。消费者迁移（主题、语言、默认模型路由）与 web `settings.*` RPC 面是后续工作，不在本 note 已交付范围内。 + +## 问题 + +用户可编辑配置没有归属：`dsh web` 经静态白名单读 cwd 锚定的 profile json 且无写路径，TUI 读 `$DSH_HOME/config.yaml` 裸 loader patch，两者都在启动时冻结。个人设置页（web GUI）需要一个跨 surface 的用户层，带 schema 校验、写路径与热传导——同类产品（Codex、Claude Code、Kimi、OpenCode、Pi）也全部收敛于"用户偏好与扩展组合分离"。Loader 的 reactive 配置更新承载不了这件事：`fiber.update` 原地替换 entry config，构造期读过配置的插件毫无感知，也没有任何回调通知它。 + +## 决策 + +**两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是契约：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。 + +**镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `/settings.yaml` 的 YAML/JSON、chokidar 监听、`0600` tmp+rename 原子写、只修补目标 namespace 键的保注释 YAML 写回、按内容相等抑制自写。 + +**注册是调用方 fiber 上的 effect。**`register()` 经服务代理调用，`this.ctx` 即注册方 context，注册挂在 `ctx.effect` 上：dispose 注册方即移除 namespace 及其观察者（HMR disposal 测试证明），而用户的分节继续留在存储中等待下一任 owner。 + +**静止时响亮报错，运行中保留最后可用值。**启动期与注册期校验直接抛错（非法存量分节使注册插件加载失败；存在但不可解析的文档使 provider 加载失败）。运行中坏的外部编辑只告警并按 namespace 保留最后可用状态——热重载绝不拖垮进程。该不对称镜像 `Include.refresh()` 与 Kimi 的安全运行时重载。 + +**消费者天然可选。**消费者在 `ctx.inject(['settings'], …)` 内注册；不挂 provider 时仍只按 entry 配置解析，因此所有既有组合、demo、snapshot 原样工作，迁移按插件渐进。 + +## Alternatives considered + +- **以 Include 写回为用户层**（cordis-webui 式的按插件配置页写 loader entry 文件）：写回目标是按组合的文件，会把用户偏好绑死在某个 `cordis.yml` 上；用户层必须在模板升级中存活，并以同一文档服务 TUI 与 web。 +- **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者契约而非框架魔法。 +- **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。 +- **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。 +- **现在就上跨进程锁**（Pi 的 proper-lockfile）：原子替换加 watcher 收敛（后写胜出）是已记录的行为，真实冲突出现再说。 + +## 后果 + +按依赖顺序延后：web `settings.raw`/`settings.describe`/`settings.update` RPC 面（暴露前必须对 `role('secret')` 字段脱敏）；首批消费者迁移（`ui-theme`、语言、api-gateway 默认路由）并退役 `PROFILE_MAPPINGS` 与 profile json；面向密钥的 `${env:VAR}` 值间接引用；provider 侧分层。keyless snapshot 义务随第一个模型或产品用户可见的消费者落地，而非本基础设施步骤。 diff --git a/AGENTS.md b/AGENTS.md index c987801c17..7112dd3aee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ packages/ @deepseek-ai/dsh- workspaces at packages/// 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 + settings/ user-settings seam + file-backed provider acp/ automation-only Agent Client Protocol server ui/ TUI/JSON-RPC bridges; boot, approval, interaction plugins examples/ demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 9093f41f15..74f7c63c0d 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -35,6 +35,9 @@ flowchart LR pkg_tool_bash["tool-bash"] pkg_hooks_claude["hooks-claude"] pkg_hooks_codex["hooks-codex"] + pkg_settings["settings"] + svc_settings["ctx.settings
User-settings seam"] + pkg_settings_local["settings-local"] pkg_session_telemetry["session-telemetry"] svc_telemetry["ctx.telemetry
Session telemetry seam"] pkg_session_telemetry_otel["session-telemetry-otel"] @@ -188,6 +191,8 @@ flowchart LR pkg_session_title --> svc_sessionTitle pkg_session_title_all_messages_llm --> svc_sessionTitle pkg_session_title_first_message_llm --> svc_sessionTitle + pkg_settings --> svc_settings + pkg_settings_local --> svc_settings pkg_skill --> svc_skills pkg_skill_local --> svc_skills pkg_spill --> svc_spillStore @@ -316,6 +321,7 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. | | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. | | `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), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. | +| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | - | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. No production consumer is migrated yet. | | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. | | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. | | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index dcb4fa69e7..1305dd7270 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1177,6 +1177,24 @@ Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-ll Source: [`packages/session-title/session-title-first-message-llm/src/index.ts:15`](../packages/session-title/session-title-first-message-llm/src/index.ts) +## `@deepseek-ai/dsh-settings-local` + +```ts config-catalog +/** Plugin config: file location and hot-reload behavior. */ +export interface Config { + /** Settings document path; defaults to `settings.yaml` under the harness home. */ + path?: string + /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */ + dshHome?: string + /** Watch the document and hot-publish external edits; defaults to true. */ + watch?: boolean + /** Watcher write-settle window in milliseconds; defaults to 100. */ + debounceMs?: number +} +``` + +Source: [`packages/settings/settings-local/src/index.ts:18`](../packages/settings/settings-local/src/index.ts) + ## `@deepseek-ai/dsh-skill` ```ts config-catalog @@ -2192,6 +2210,7 @@ Abstract service classes — a deployment loads a concrete implementation packag - `@deepseek-ai/dsh-sandbox` — abstract `SandboxProvider` ([`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts)) - `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts)) - `@deepseek-ai/dsh-session-query` — abstract `SessionQueryService` ([`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts)) +- `@deepseek-ai/dsh-settings` — abstract `Settings` ([`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts)) - `@deepseek-ai/dsh-spill` — abstract `SpillStore` ([`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts)) - `@deepseek-ai/dsh-subprocess` — abstract `SubprocessService` ([`packages/subprocess/subprocess/src/index.ts`](../packages/subprocess/subprocess/src/index.ts)) - `@deepseek-ai/dsh-tasks` — abstract `TaskService` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts)) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index ca0e9b82fc..aea04f4acd 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -640,6 +640,28 @@ Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-stru Source: [`packages/core/session/src/index.ts:102`](../../packages/core/session/src/index.ts) +## `settings/*` + +### `settings/updated` — emit + +Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. + +```ts cordis-catalog +/** + * Committed change to one registered namespace's resolved value. Emitted + * after the provider persisted (for `update`) or published (`provider`) + * the change; never emitted when the resolved value is deep-equal. + * @param ns - the namespace whose resolved value changed. + * @param next - the new resolved value. + * @param prev - the previous resolved value. + * @param source - whether the change entered through `update()` or the provider. + * @mode emit + */ +'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void +``` + +Source: [`packages/settings/settings/src/index.ts:90`](../../packages/settings/settings/src/index.ts) + ## `slash/*` ### `slash/input-begin-command` — bail diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 19d7d7765d..a0271083d6 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1388,6 +1388,48 @@ Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](. Source: [`packages/session-title/session-title/src/index.ts:232`](../../packages/session-title/session-title/src/index.ts) +## `ctx.settings` — `Settings` (abstract seam) + +Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event. + +```ts cordis-catalog +/** + * Register a namespace schema and receive its owner scope. The registration + * is an effect on the calling plugin's fiber: disposing that fiber removes + * the namespace and its observers. An invalid stored section fails the + * registration itself — the earliest point where the schema can judge it. + * @param ns - unique namespace; duplicate registration fails loud. + * @param schema - schemastery schema resolving this namespace's value. + * @param options - composition `base` layer and effect timing. + * @returns the owner scope for reads, observation, and updates. + */ +register(ns: SettingsNamespace, schema: z, options?: SettingsRegisterOptions): SettingsScope + +/** + * Describe every registered namespace for configuration surfaces. + * @returns one descriptor per registered namespace, in registration order. + */ +describe(): SettingsDescriptor[] + +/** + * Read one registered namespace's resolved value. + * @param ns - the namespace to read. + * @returns the resolved value, or `undefined` while unregistered. + */ +get(ns: SettingsNamespace): unknown + +/** + * Merge a patch into one registered namespace's user layer, validate the + * resolved candidate, persist through the provider, then commit and emit. + * A validation failure rejects before anything is persisted. + * @param ns - the registered namespace to update. + * @param patch - plain-object patch over the user section. + */ +async update(ns: SettingsNamespace, patch: object): Promise +``` + +Source: [`packages/settings/settings/src/index.ts:140`](../../packages/settings/settings/src/index.ts) + ## `ctx.skills` — `SkillService` Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted model-visible summaries, and loads full skill bodies on demand. diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index e9e5bb6e6a..49bdf3fe35 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -35,6 +35,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:80`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:92`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:102`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | +| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:90`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`emit`) | [`settings`](../packages/settings/settings) | | `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:230`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:244`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-insert-reference` | `bail` | [`packages/client/ui-slash/src/types.ts:237`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml index 5dd168f03e..360687f197 100644 --- a/packages/README.i18n.yaml +++ b/packages/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/README.md -README.md: d16e395a42e491461c0862227205931894c27e39 -README.zh.md: 3fb4181ce7ae7b0d79a13ca4358b9df39d83ef1f +README.md: 7b415bdbbd3e442c952da49b6f9f8823a636f643 +README.zh.md: d3347ecd6db68d99bc00e340c632da51cf825c63 diff --git a/packages/README.md b/packages/README.md index d16e395a42..7b415bdbbd 100644 --- a/packages/README.md +++ b/packages/README.md @@ -37,6 +37,7 @@ Packages live at `packages///`; groups are containers, while names r | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface | | [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service, shared LLM policy, and opt-in providers | Product — stable surface | +| [`settings/`](settings/README.md) | User-settings capability family: the seam + file-backed provider | Product — stable surface | | [`telemetry/`](telemetry/README.md) | Session reporting: capture/redact seam, OTel backend | Product — stable surface | | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface | | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface | diff --git a/packages/README.zh.md b/packages/README.zh.md index 3fb4181ce7..d3347ecd6d 100644 --- a/packages/README.zh.md +++ b/packages/README.zh.md @@ -37,6 +37,7 @@ | [`session-persistence/`](session-persistence/README.md) | 持久化能力系列：seam + JSONL/SQLite 后端 | 产品：稳定表面 | | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 | | [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务、共享 LLM 策略和选用提供方 | 产品：稳定表面 | +| [`settings/`](settings/README.md) | 用户设置能力族：seam + 文件 provider | 产品：稳定表面 | | [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 | | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 | | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 | diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 47f8a1a54f..81e3c79d05 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -666,6 +666,28 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, ], }, + { + key: 'settings', + summary: 'Abstract settings service.', + methods: [ + { + signature: 'register(ns: SettingsNamespace, schema: z, options?: SettingsRegisterOptions): SettingsScope', + jsDoc: '/**\n * Register a namespace schema and receive its owner scope. The registration\n * is an effect on the calling plugin\'s fiber: disposing that fiber removes\n * the namespace and its observers. An invalid stored section fails the\n * registration itself — the earliest point where the schema can judge it.\n * @param ns - unique namespace; duplicate registration fails loud.\n * @param schema - schemastery schema resolving this namespace\'s value.\n * @param options - composition `base` layer and effect timing.\n * @returns the owner scope for reads, observation, and updates.\n */', + }, + { + signature: 'describe(): SettingsDescriptor[]', + jsDoc: '/**\n * Describe every registered namespace for configuration surfaces.\n * @returns one descriptor per registered namespace, in registration order.\n */', + }, + { + signature: 'get(ns: SettingsNamespace): unknown', + jsDoc: '/**\n * Read one registered namespace\'s resolved value.\n * @param ns - the namespace to read.\n * @returns the resolved value, or `undefined` while unregistered.\n */', + }, + { + signature: 'async update(ns: SettingsNamespace, patch: object): Promise', + jsDoc: '/**\n * Merge a patch into one registered namespace\'s user layer, validate the\n * resolved candidate, persist through the provider, then commit and emit.\n * A validation failure rejects before anything is persisted.\n * @param ns - the registered namespace to update.\n * @param patch - plain-object patch over the user section.\n */', + }, + ], + }, { key: 'skills', summary: 'Registry of skill providers.', @@ -1188,6 +1210,13 @@ export const EVENT_API: readonly EventApiEntry[] = [ jsDoc: '/**\n * Awaited parallel durability checkpoint: every listener runs and the\n * caller awaits all of them, with no waterfall veto. Dispatch through\n * {@link SessionStore.flush}. Scope-filtered dispatch\n * (`@deepseek-ai/dsh-scope`) reuses the session\'s owner scope.\n * @param session - the session whose buffered events must reach durable storage.\n * @dshScopeScan unsupported\n * @mode parallel\n */', summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.', }, + { + name: 'settings/updated', + mode: 'emit', + signature: '\'settings/updated\'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void', + jsDoc: '/**\n * Committed change to one registered namespace\'s resolved value. Emitted\n * after the provider persisted (for `update`) or published (`provider`)\n * the change; never emitted when the resolved value is deep-equal.\n * @param ns - the namespace whose resolved value changed.\n * @param next - the new resolved value.\n * @param prev - the previous resolved value.\n * @param source - whether the change entered through `update()` or the provider.\n * @mode emit\n */', + summary: 'Committed change to one registered namespace\'s resolved value.', + }, { name: 'slash/input-begin-command', mode: 'bail', @@ -2181,6 +2210,26 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionTitleUserMessage', declaration: 'export interface SessionTitleUserMessage {\n readonly seq: number;\n readonly text: string;\n}', }, + { + name: 'SettingsApplies', + declaration: 'export type SettingsApplies = \'live\' | \'restart\';', + }, + { + name: 'SettingsDescriptor', + declaration: 'export interface SettingsDescriptor {\n ns: SettingsNamespace;\n schema: unknown;\n value: unknown;\n applies: SettingsApplies;\n}', + }, + { + name: 'SettingsNamespace', + declaration: 'export type SettingsNamespace = Branded<\'SettingsNamespace\'>;', + }, + { + name: 'SettingsRegisterOptions', + declaration: 'export interface SettingsRegisterOptions {\n base?: Partial;\n applies?: SettingsApplies;\n}', + }, + { + name: 'SettingsScope', + declaration: 'export interface SettingsScope {\n get(): T;\n watch(callback: (next: T, prev: T) => void): () => void;\n update(patch: object): Promise;\n}', + }, { name: 'SkillCandidate', declaration: 'export interface SkillCandidate extends SkillSummary {\n readonly rank: number;\n readonly locator: unknown;\n readonly path?: string;\n readonly metadata?: Readonly>;\n}', diff --git a/packages/settings/README.i18n.yaml b/packages/settings/README.i18n.yaml new file mode 100644 index 0000000000..7c78505615 --- /dev/null +++ b/packages/settings/README.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write packages/settings/README.md +README.md: 7a91355dd01805938944f0abce77765021288e6d +README.zh.md: 2df40b67eb8ce6cfc693ed6bf3574815c0219ec0 diff --git a/packages/settings/README.md b/packages/settings/README.md new file mode 100644 index 0000000000..7a91355dd0 --- /dev/null +++ b/packages/settings/README.md @@ -0,0 +1,12 @@ +# settings/ — user-settings capability family + +English | [中文](README.zh.md) + +The user-settings seam and its providers. The interface package owns the abstract `Settings` service — namespace registration, layered resolution, and change commits; providers implement raw-document storage and push external edits through the seam. All **product** packages. + +| Package | Role | ctx key | +|---|---|---| +| `settings/` | Settings seam: namespace registry, layered resolution, commit events | `ctx.settings` | +| `settings-local/` | File-backed provider (`settings.yaml`/`.json`) with hot reload and comment-preserving write-back | (registers `ctx.settings`) | + +The interface lives at `settings/settings/`; providers are flat siblings. A network configuration-center provider (for example a nacos-style backend) joins here and registers on `ctx.settings`. Composition config stays in `cordis.yml`: a settings namespace carries only the user-editable subset, resolved as schema defaults, then the registrant's composition `base`, then the user document. diff --git a/packages/settings/README.zh.md b/packages/settings/README.zh.md new file mode 100644 index 0000000000..2df40b67eb --- /dev/null +++ b/packages/settings/README.zh.md @@ -0,0 +1,12 @@ +# settings/ — 用户设置能力族 + +[English](README.md) | 中文 + +用户设置 seam 及其 provider。接口包拥有抽象 `Settings` 服务——namespace 注册、分层解析与变更提交；provider 实现原始文档存储并把外部修改推入 seam。全部为**产品**包。 + +| 包 | 角色 | ctx key | +|---|---|---| +| `settings/` | 设置 seam：namespace 注册表、分层解析、提交事件 | `ctx.settings` | +| `settings-local/` | 文件 provider（`settings.yaml`/`.json`），热重载与保留注释的写回 | （注册 `ctx.settings`） | + +接口位于 `settings/settings/`；provider 平级并列。网络配置中心 provider（例如 nacos 类后端）加入本组并注册到 `ctx.settings`。组合配置仍留在 `cordis.yml`：settings namespace 只承载用户可编辑子集，解析顺序为 schema 默认值、注册方的组合 `base`、用户文档。 diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml new file mode 100644 index 0000000000..f7ca57e86e --- /dev/null +++ b/packages/settings/settings-local/README.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write packages/settings/settings-local/README.md +README.md: 90428f98055d8e49fa1ec54e571453db2e0a5054 +README.zh.md: 3532d6cee99cb46f54e23889ef1bb54b2548ecfa diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md new file mode 100644 index 0000000000..90428f9805 --- /dev/null +++ b/packages/settings/settings-local/README.md @@ -0,0 +1,36 @@ +# @deepseek-ai/dsh-settings-local + +English | [中文](README.zh.md) + +File-backed settings provider. One YAML or JSON document carries every namespace section; external edits hot-publish through `ctx.settings`, and `update()` writes back atomically while preserving the user's YAML comments and any section owned by a plugin that is not currently loaded. + +## Config + +| Field | Meaning | Default | +|---|---|---| +| `path` | Settings document path; extension picks the format (`.yaml`/`.yml`/`.json`) | `settings.yaml` under the harness home | +| `dshHome` | Harness home used when `path` is omitted | `$DSH_HOME` or `~/.dsh` | +| `watch` | Watch the document and hot-publish external edits | `true` | +| `debounceMs` | Watcher write-settle window in milliseconds | `100` | + +Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension fails at load. + +## Behavior + +- **Boot fails loud, reload keeps last-good.** An existing-but-invalid document fails plugin load; once live, an unreadable or unparsable edit warns and keeps the last good sections. A missing document resolves every namespace from defaults and `base`; deleting it publishes the same empty state. +- **Write-back is atomic and owner-only.** `persist` writes `.tmp` with mode `0600` and renames over the target. YAML writes patch one namespace in the comment-preserving document; JSON re-serializes. +- **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op. + +## Model Experience + +Indirectly, through consumers of `ctx.settings`: this provider only stores and publishes namespace sections, and each consumer's own surface documents any model effect. + +#### KV Cache effect + +No direct invalidation; the consuming plugin owns any request-prefix changes. + +## Known Limitations and Deferred Work + +- **No cross-process write lock** — concurrent writers (for example TUI and web on one home) converge by atomic replace plus watcher reload, last write wins; a lockfile is deferred until real contention shows up. +- **Comment preservation is YAML-only** — JSON documents re-serialize without comments (JSON has none) and lose hand formatting. +- **No value indirection** — sections hold literal values; `${env:VAR}`-style references for secrets are a deferred seam-level feature. diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md new file mode 100644 index 0000000000..3532d6cee9 --- /dev/null +++ b/packages/settings/settings-local/README.zh.md @@ -0,0 +1,36 @@ +# @deepseek-ai/dsh-settings-local + +[English](README.md) | 中文 + +文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 原子写回，并保留用户的 YAML 注释以及当前未加载插件所拥有的分节。 + +## 配置 + +| 字段 | 含义 | 默认 | +|---|---|---| +| `path` | 设置文档路径；扩展名决定格式（`.yaml`/`.yml`/`.json`） | harness home 下的 `settings.yaml` | +| `dshHome` | `path` 省略时使用的 harness home | `$DSH_HOME` 或 `~/.dsh` | +| `watch` | 监听文档并热发布外部编辑 | `true` | +| `debounceMs` | watcher 写入稳定窗口（毫秒） | `100` | + +默认值解析是一步显式的 `resolveSpec(config)`；不支持的扩展名在加载时报错。 + +## 行为 + +- **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。 +- **写回原子且仅属主可读。** `persist` 以 `0600` 权限写 `.tmp` 后 rename 覆盖目标。YAML 写回在保留注释的文档里只修补目标 namespace；JSON 重新序列化。 +- **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。 + +## Model Experience + +间接生效：本 provider 只存储并发布 namespace 分节，模型效果经由 `ctx.settings` 的消费插件产生，由各消费者自己的文档描述。 + +#### KV Cache effect + +无直接失效；请求前缀的变更由消费插件拥有。 + +## Known Limitations and Deferred Work + +- **无跨进程写锁** — 并发写入者（例如同一 home 上的 TUI 与 web）靠原子替换加 watcher 重载收敛，后写胜出；lockfile 等真实冲突出现再做。 +- **注释保留仅限 YAML** — JSON 文档重新序列化，无注释（JSON 本身没有）且丢失手工排版。 +- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是 seam 层的延后特性。 diff --git a/packages/settings/settings-local/package.json b/packages/settings/settings-local/package.json new file mode 100644 index 0000000000..aefb1ccd33 --- /dev/null +++ b/packages/settings/settings-local/package.json @@ -0,0 +1,46 @@ +{ + "name": "@deepseek-ai/dsh-settings-local", + "description": "File-backed settings provider (settings.yaml) for the DeepSeek Harness", + "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" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-invariants": "^0.0.1", + "@deepseek-ai/dsh-paths": "^0.0.1", + "@deepseek-ai/dsh-settings": "^0.0.1", + "cordis": "^4.0.0-rc.7" + }, + "dependencies": { + "chokidar": "^4.0.3", + "schemastery": "^3.18.0", + "yaml": "^2.9.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-paths": "workspace:^", + "@deepseek-ai/dsh-settings": "workspace:^", + "cordis": "^4.0.0-rc.7" + } +} diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts new file mode 100644 index 0000000000..421411ea50 --- /dev/null +++ b/packages/settings/settings-local/src/index.ts @@ -0,0 +1,226 @@ +/** + * File-backed settings provider. One YAML or JSON document under the user's + * harness home carries every namespace section; external edits hot-publish + * through the seam and `update()` writes back preserving the user's comments. + * @module @deepseek-ai/dsh-settings-local + */ + +import { Context, Service } from 'cordis' +import z from 'schemastery' +import { watch as chokidarWatch } from 'chokidar' +import { mkdir, readFile, rename, writeFile } from 'node:fs/promises' +import { dirname, extname, join, resolve } from 'node:path' +import { Document, parseDocument } from 'yaml' +import { resolveDshHome } from '@deepseek-ai/dsh-paths' +import { Settings, type SettingsNamespace } from '@deepseek-ai/dsh-settings' + +/** Plugin config: file location and hot-reload behavior. */ +export interface Config { + /** Settings document path; defaults to `settings.yaml` under the harness home. */ + path?: string + /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */ + dshHome?: string + /** Watch the document and hot-publish external edits; defaults to true. */ + watch?: boolean + /** Watcher write-settle window in milliseconds; defaults to 100. */ + debounceMs?: number +} + +/** Document format derived from the configured file extension. */ +type SettingsFormat = 'yaml' | 'json' + +const FORMATS: Record = { + '.yaml': 'yaml', + '.yml': 'yaml', + '.json': 'json', +} + +/** Fully resolved provider parameters; defaulting happens here, never inline. */ +interface ResolvedSpec { + filename: string + format: SettingsFormat + watch: boolean + debounceMs: number +} + +/** + * Resolve the runtime spec from plugin config: an explicit `path` wins, + * otherwise the document lives at `/settings.yaml`. + * @param config - raw plugin config. + * @returns the resolved file location, format, and watch behavior. + */ +export function resolveSpec(config: Config): ResolvedSpec { + const filename = resolve(config.path ?? join(resolveDshHome(config.dshHome), 'settings.yaml')) + const format = FORMATS[extname(filename)] + if (format === undefined) { + throw new Error(`settings-local: extension "${extname(filename)}" is not supported (use .yaml, .yml, or .json)`) + } + return { + filename, + format, + watch: config.watch ?? true, + debounceMs: config.debounceMs ?? 100, + } +} + +/** Whether a filesystem error means absence; every non-ENOENT failure must surface. */ +function isENOENT(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT' +} + +/** File-backed settings provider (`settings.yaml`/`.json`). */ +export class SettingsLocal extends Settings { + static Config: z = z.object({ + path: z.string(), + dshHome: z.string(), + watch: z.boolean().default(true), + debounceMs: z.number().min(0).default(100), + }) + + private readonly spec: ResolvedSpec + /** + * Raw text of the last successfully parsed or persisted document; + * `undefined` while the file is absent. Watcher events whose content equals + * this cache are no-ops, which is also the self-write suppression. + */ + private text: string | undefined + /** Serializes watcher-triggered reloads so reads never interleave. */ + private refreshTask: Promise = Promise.resolve() + + constructor(ctx: Context, public config: Config) { + super(ctx) + // Programmatic construction may bypass Schemastery normalization; resolve + // the same defaults in one explicit step either way. + this.spec = resolveSpec(config) + } + + /** The local document is always writable through {@link Settings.update}. */ + get writable(): boolean { + return true + } + + protected async load(): Promise> { + let text: string + try { + text = await readFile(this.spec.filename, 'utf8') + } catch (error) { + if (!isENOENT(error)) throw error + this.text = undefined + return {} + } + const doc = this.parse(text) + this.text = text + return doc + } + + protected async persist(ns: SettingsNamespace, section: Record): Promise { + const output = this.spec.format === 'yaml' + ? this.renderYaml(ns, section) + : this.renderJson(ns, section) + await mkdir(dirname(this.spec.filename), { recursive: true }) + const temp = `${this.spec.filename}.tmp` + // Owner-only permissions apply to the temp file and survive the rename, so + // a document that may carry personal values is never world-readable. + await writeFile(temp, output, { mode: 0o600 }) + await rename(temp, this.spec.filename) + this.text = output + } + + async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { + // A parse failure here is a boot failure: an existing-but-invalid document + // must fail loud, never be silently ignored or overwritten. + this.publish(await this.load()) + if (!this.spec.watch) return + const watcher = chokidarWatch(this.spec.filename, { + ignoreInitial: true, + awaitWriteFinish: { + stabilityThreshold: this.spec.debounceMs, + pollInterval: Math.max(1, Math.min(this.spec.debounceMs, 10)), + }, + }) + watcher.on('all', () => { + this.refreshTask = this.refreshTask.then(() => this.refresh()) + }) + watcher.on('error', (error) => { + this.ctx.logger.warn('settings-local: watcher error on %s', this.spec.filename) + this.ctx.logger.warn(error) + }) + yield () => watcher.close() + } + + /** Parse one document text into raw sections, failing on a non-map root. */ + private parse(text: string): Record { + let root: unknown + if (this.spec.format === 'yaml') { + const document = parseDocument(text, { prettyErrors: true }) + if (document.errors.length > 0) { + throw new Error(`settings-local: invalid document at ${this.spec.filename}: ${ + document.errors.map(error => error.message).join('; ')}`) + } + root = document.toJS() ?? {} + } else { + root = text.trim().length === 0 ? {} : JSON.parse(text) + } + if (typeof root !== 'object' || root === null || Array.isArray(root)) { + throw new TypeError(`settings-local: ${this.spec.filename} must be a map of namespace sections`) + } + return root as Record + } + + /** + * Re-read the document after a watcher event. Unchanged content (including + * this provider's own writes) is a no-op; an unreadable or unparsable + * document keeps the last good sections and warns — a live hot-reload must + * never take the process down. + */ + private async refresh(): Promise { + let text: string + try { + text = await readFile(this.spec.filename, 'utf8') + } catch (error) { + if (!isENOENT(error)) { + this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename) + this.ctx.logger.warn(error) + return + } + if (this.text === undefined) return + this.text = undefined + this.publish({}) + return + } + if (text === this.text) return + let doc: Record + try { + doc = this.parse(text) + } catch (error) { + this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename) + this.ctx.logger.warn(error) + return + } + this.text = text + this.publish(doc) + } + + /** Render the next YAML text by patching one namespace in the comment-preserving document. */ + private renderYaml(ns: SettingsNamespace, section: Record): string { + if (this.text === undefined) { + return new Document({ [ns]: section }).toString() + } + // this.text only ever caches content that parsed successfully, so this + // re-parse (for the mutable comment-preserving tree) cannot fail. + const document = parseDocument(this.text) + document.set(ns, section) + return document.toString() + } + + /** Render the next JSON text by replacing one namespace key. */ + private renderJson(ns: SettingsNamespace, section: Record): string { + const root = this.text === undefined + ? {} + : this.parse(this.text) + root[ns] = section + return `${JSON.stringify(root, null, 2)}\n` + } +} + +export default SettingsLocal diff --git a/packages/settings/settings-local/src/invariant.ts b/packages/settings/settings-local/src/invariant.ts new file mode 100644 index 0000000000..b59b798298 --- /dev/null +++ b/packages/settings/settings-local/src/invariant.ts @@ -0,0 +1,31 @@ +/** + * Package-owned invariant companion for `@deepseek-ai/dsh-settings-local`. + * @module @deepseek-ai/dsh-settings-local/invariant + */ + +/* jscpd:ignore-start */ +import type { Context } from 'cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-settings-local' + +/** Cordis companion plugin name. */ +export const name = 'settings-local-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** + * No runtime invariant: this provider's contracts are file round-trip, + * watcher timing, and atomic-write behavior — IO effects proven by package + * tests; the in-process commit relation is owned by `@deepseek-ai/dsh-settings`. + */ +const install: InvariantInstaller = () => {} + +/** + * Register this package's invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) +/* jscpd:ignore-end */ diff --git a/packages/settings/settings-local/tests/loader-composition.spec.ts b/packages/settings/settings-local/tests/loader-composition.spec.ts new file mode 100644 index 0000000000..5744e92f46 --- /dev/null +++ b/packages/settings/settings-local/tests/loader-composition.spec.ts @@ -0,0 +1,112 @@ +/** + * Real-composition guard: the provider and a consumer plugin boot from a + * test-only cordis.yml through the actual Loader + Include path, and an + * external edit of settings.yaml hot-publishes into the consumer's scope. + */ + +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import Include from '@cordisjs/plugin-include' +import z from 'schemastery' +import { settingsNamespace, type SettingsScope } from '@deepseek-ai/dsh-settings' +import SettingsLocal from '../src/index.ts' + +interface ThemeConfig { + theme: 'dark' | 'light' + fontSize: number +} + +const ThemeSchema: z = z.object({ + theme: z.union(['dark', 'light']).default('dark'), + fontSize: z.number().default(14), +}) + +let root: string | undefined +let context: Context | undefined + +afterEach(async () => { + await context?.fiber.dispose() + context = undefined + if (root !== undefined) await rm(root, { recursive: true, force: true }) + root = undefined +}) + +interface ConsumerState { + scope: SettingsScope | undefined + seen: ThemeConfig[] +} + +async function loadComposition(): Promise<{ ctx: Context; state: ConsumerState; settingsPath: string }> { + root = await mkdtemp(join(tmpdir(), 'dsh-settings-composition-')) + const settingsPath = join(root, 'settings.yaml') + await writeFile(settingsPath, 'ui-theme:\n theme: light\n') + + const state: ConsumerState = { scope: undefined, seen: [] } + const consumer = { + name: 'settings-consumer', + inject: ['settings'], + apply: (ctx: Context) => { + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { fontSize: 16 }, + }) + state.scope = scope + scope.watch(next => state.seen.push(next)) + }, + } + + const configPath = join(root, 'cordis.yml') + await writeFile(configPath, [ + '- id: settings', + " name: '@deepseek-ai/dsh-settings-local'", + ' config:', + ` path: ${JSON.stringify(settingsPath)}`, + ' debounceMs: 10', + '- id: consumer', + ' name: test-settings-consumer', + '', + ].join('\n')) + + const ctx = new Context() + context = ctx + ctx.baseUrl = pathToFileURL(root).href + '/' + await ctx.plugin(Loader) + ctx.loader.builtins.include = Include + const modules = new Map([ + ['@deepseek-ai/dsh-settings-local', SettingsLocal], + ['test-settings-consumer', consumer], + ]) + ctx.loader.internal = { + version: 'v2', + async import(specifier: string) { + if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`) + return modules.get(specifier) + }, + } as unknown as NonNullable + await ctx.loader.create({ + name: 'cordis:include', + config: { path: pathToFileURL(configPath).href }, + }) + await ctx.loader.await() + return { ctx, state, settingsPath } +} + +describe('settings-local real composition', () => { + it('boots from cordis.yml and hot-publishes an external settings edit', async () => { + const { ctx, state, settingsPath } = await loadComposition() + + // Composition resolution: user layer over the consumer's composition base. + expect(state.scope!.get()).toEqual({ theme: 'light', fontSize: 16 }) + expect(ctx.get('settings')!.describe().map(entry => entry.ns)).toEqual(['ui-theme']) + + await writeFile(settingsPath, 'ui-theme:\n theme: dark\n fontSize: 20\n') + await vi.waitFor(() => { + expect(state.scope!.get()).toEqual({ theme: 'dark', fontSize: 20 }) + }, { timeout: 5000 }) + expect(state.seen.at(-1)).toEqual({ theme: 'dark', fontSize: 20 }) + }) +}) diff --git a/packages/settings/settings-local/tests/local.spec.ts b/packages/settings/settings-local/tests/local.spec.ts new file mode 100644 index 0000000000..9c9d472bac --- /dev/null +++ b/packages/settings/settings-local/tests/local.spec.ts @@ -0,0 +1,254 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import { chmod, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { settingsNamespace } from '@deepseek-ai/dsh-settings' +import { SettingsLocal, resolveSpec } from '../src/index.ts' + +interface ThemeConfig { + theme: 'dark' | 'light' + fontSize: number +} + +const ThemeSchema: z = z.object({ + theme: z.union(['dark', 'light']).default('dark'), + fontSize: z.number().default(14), +}) + +const cleanups: Array<() => Promise> = [] + +afterEach(async () => { + while (cleanups.length > 0) await cleanups.pop()!() +}) + +async function tempDir(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-local-')) + cleanups.push(() => rm(dir, { recursive: true, force: true })) + return dir +} + +async function boot(config: ConstructorParameters[1]): Promise { + const ctx = new Context() + const fiber = ctx.plugin(SettingsLocal, config) + cleanups.push(async () => { await fiber.dispose() }) + await fiber + return ctx +} + +describe('resolveSpec', () => { + it('defaults watch and debounce when construction bypasses schema normalization', () => { + const spec = resolveSpec({ path: '/tmp/anywhere/settings.yaml' }) + expect(spec.watch).toBe(true) + expect(spec.debounceMs).toBe(100) + }) +}) + +describe('boot and reads', () => { + it('resolves defaults over an absent file and reports writable', async () => { + const dir = await tempDir() + const ctx = await boot({ path: join(dir, 'settings.yaml'), watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { fontSize: 16 }, + }) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 }) + expect(ctx.settings.writable).toBe(true) + }) + + it('reads sections from an existing yaml document', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 }) + }) + + it('reads sections from a json document', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.json') + await writeFile(path, JSON.stringify({ 'ui-theme': { fontSize: 18 } })) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 }) + }) + + it('defaults the file location under the configured harness home', async () => { + const dir = await tempDir() + const ctx = await boot({ dshHome: dir, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + const written = await readFile(join(dir, 'settings.yaml'), 'utf8') + expect(written).toContain('theme: light') + }) + + it('reads an empty yaml document as no sections', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, '') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + }) + + it('reads an empty json document as no sections', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.json') + await writeFile(path, '') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + }) + + it('fails loud at boot when the document exists but is unreadable', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + await chmod(path, 0o000) + cleanups.push(() => chmod(path, 0o600)) + await expect(boot({ path, watch: false })).rejects.toThrow(/EACCES|permission/i) + }) + + it('fails loud on an unsupported extension', async () => { + const dir = await tempDir() + await expect(boot({ path: join(dir, 'settings.toml'), watch: false })) + .rejects.toThrow(/not supported/) + }) + + it('fails loud at boot on unparsable yaml', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme: [unclosed\n') + await expect(boot({ path, watch: false })).rejects.toThrow() + }) + + it('fails loud at boot when the root is not a map of sections', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, '- just\n- a list\n') + await expect(boot({ path, watch: false })).rejects.toThrow(/map of namespace sections/) + }) +}) + +describe('persist', () => { + it('writes the merged section, creating the file with owner-only permissions', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + + const written = await readFile(path, 'utf8') + expect(written).toContain('theme: light') + expect((await stat(path)).mode & 0o777).toBe(0o600) + // Atomic replace leaves no temp artifact behind. + expect((await readdir(dir)).sort()).toEqual(['settings.yaml']) + }) + + it('preserves comments and unregistered sections across updates', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, [ + '# personal settings', + 'ui-theme:', + ' theme: light', + '# owned by a plugin that is not loaded right now', + 'future-plugin:', + ' keep: me', + '', + ].join('\n')) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ fontSize: 18 }) + + const written = await readFile(path, 'utf8') + expect(written).toContain('# personal settings') + expect(written).toContain('# owned by a plugin that is not loaded right now') + expect(written).toContain('keep: me') + expect(written).toContain('fontSize: 18') + expect(written).toContain('theme: light') + }) + + it('creates a json document from scratch', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.json') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + const written = JSON.parse(await readFile(path, 'utf8')) as Record + expect(written).toEqual({ 'ui-theme': { theme: 'light' } }) + }) + + it('round-trips a json document', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.json') + await writeFile(path, JSON.stringify({ other: { keep: true } }, null, 2)) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + const written = JSON.parse(await readFile(path, 'utf8')) as Record + expect(written).toEqual({ other: { keep: true }, 'ui-theme': { theme: 'light' } }) + }) +}) + +describe('watch', () => { + it('publishes an external edit to registered scopes', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 10 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get().theme).toBe('light') + + await writeFile(path, 'ui-theme:\n theme: dark\n fontSize: 20\n') + await vi.waitFor(() => { + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 20 }) + }, { timeout: 5000 }) + }) + + it('keeps the last good document over an invalid edit, then recovers', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 10 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + + await writeFile(path, 'ui-theme: [unclosed\n') + // The bad edit must never take the live tree down or reset the value. + await new Promise(resolve => setTimeout(resolve, 300)) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 }) + + await writeFile(path, 'ui-theme:\n theme: dark\n') + await vi.waitFor(() => { + expect(scope.get().theme).toBe('dark') + }, { timeout: 5000 }) + }) + + it('treats file removal as an empty document', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 10 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + + await rm(path) + await vi.waitFor(() => { + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + }, { timeout: 5000 }) + }) + + it('does not republish its own persisted write', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, debounceMs: 10 }) + const events: unknown[] = [] + ctx.on('settings/updated', (ns, _next, _prev, source) => { + events.push({ ns, source }) + }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + await new Promise(resolve => setTimeout(resolve, 300)) + expect(events).toEqual([{ ns: 'ui-theme', source: 'update' }]) + }) +}) diff --git a/packages/settings/settings-local/tests/watcher.spec.ts b/packages/settings/settings-local/tests/watcher.spec.ts new file mode 100644 index 0000000000..00c67eacc7 --- /dev/null +++ b/packages/settings/settings-local/tests/watcher.spec.ts @@ -0,0 +1,118 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { settingsNamespace } from '@deepseek-ai/dsh-settings' +import { SettingsLocal } from '../src/index.ts' + +// chokidar is the nondeterministic OS boundary: faking it lets these tests +// drive the event pipeline (error events, races with unreadable files) +// deterministically. Real end-to-end watching stays covered by local.spec.ts. +vi.mock('chokidar', async () => { + const { EventEmitter } = await import('node:events') + class FakeWatcher extends EventEmitter { + close = vi.fn(() => Promise.resolve()) + } + const instances: Array<{ path: string; options: unknown; watcher: InstanceType }> = [] + return { + watch: vi.fn((path: string, options: unknown) => { + const watcher = new FakeWatcher() + instances.push({ path, options, watcher }) + return watcher + }), + __instances: instances, + } +}) + +interface FakeChokidar { + __instances: Array<{ + path: string + options: { awaitWriteFinish: { stabilityThreshold: number; pollInterval: number } } + watcher: import('node:events').EventEmitter + }> +} + +async function fakeInstances(): Promise { + const chokidar = await import('chokidar') as unknown as FakeChokidar + return chokidar.__instances +} + +const ThemeSchema: z<{ theme: string }> = z.object({ + theme: z.string().default('dark'), +}) + +const cleanups: Array<() => Promise> = [] + +afterEach(async () => { + while (cleanups.length > 0) await cleanups.pop()!() + ;(await fakeInstances()).length = 0 +}) + +async function tempDir(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-watch-')) + cleanups.push(() => rm(dir, { recursive: true, force: true })) + return dir +} + +async function boot(config: ConstructorParameters[1]): Promise { + const ctx = new Context() + const fiber = ctx.plugin(SettingsLocal, config) + cleanups.push(async () => { await fiber.dispose() }) + await fiber + return ctx +} + +describe('watcher pipeline', () => { + it('clamps the write-settle poll interval for a zero debounce', async () => { + const dir = await tempDir() + await boot({ path: join(dir, 'settings.yaml'), debounceMs: 0 }) + const [instance] = await fakeInstances() + expect(instance!.options.awaitWriteFinish).toEqual({ stabilityThreshold: 0, pollInterval: 1 }) + }) + + it('survives a watcher error and keeps publishing later edits', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const [instance] = await fakeInstances() + + instance!.watcher.emit('error', new Error('watch backend failure')) + expect(scope.get()).toEqual({ theme: 'dark' }) + + await writeFile(path, 'ui-theme:\n theme: light\n') + instance!.watcher.emit('all', 'change', path) + await vi.waitFor(() => { + expect(scope.get()).toEqual({ theme: 'light' }) + }) + }) + + it('keeps the last good document when the file turns unreadable at runtime', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + + await chmod(path, 0o000) + cleanups.push(() => chmod(path, 0o600)) + const [instance] = await fakeInstances() + instance!.watcher.emit('all', 'change', path) + // The warn-and-keep path is asynchronous; give the serialized refresh a turn. + await new Promise(resolve => setTimeout(resolve, 50)) + expect(scope.get()).toEqual({ theme: 'light' }) + }) + + it('treats an event for a still-absent file as a no-op', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const [instance] = await fakeInstances() + instance!.watcher.emit('all', 'add', path) + await new Promise(resolve => setTimeout(resolve, 50)) + expect(scope.get()).toEqual({ theme: 'dark' }) + }) +}) diff --git a/packages/settings/settings-local/tsconfig.json b/packages/settings/settings-local/tsconfig.json new file mode 100644 index 0000000000..67a746c982 --- /dev/null +++ b/packages/settings/settings-local/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": "../../util/paths" + }, + { + "path": "../settings" + }, + { + "path": "../../support/invariants" + } + ] +} diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml new file mode 100644 index 0000000000..51f30f2ca6 --- /dev/null +++ b/packages/settings/settings/README.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write packages/settings/settings/README.md +README.md: e57db00c095a87f9f0b51397e030dec364f48e62 +README.zh.md: 8733823106f0ef3880cbe2c567de2edcdeff2c86 diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md new file mode 100644 index 0000000000..e57db00c09 --- /dev/null +++ b/packages/settings/settings/README.md @@ -0,0 +1,35 @@ +# @deepseek-ai/dsh-settings + +English | [中文](README.zh.md) + +Abstract user-settings seam (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings. + +## Service API + +- `register(ns, schema, { base?, applies? })` — returns the owner `SettingsScope` (`get`/`watch`/`update`). The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. A stored section the schema rejects fails the registration itself; a duplicate namespace fails loud. +- `describe()` — one descriptor per namespace (`schema.toJSON()` envelope, resolved value, `applies`) for configuration surfaces. +- `get(ns)` — resolved value, `undefined` while unregistered. +- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every update. +- Resolved values are deep-frozen snapshots; watchers receive `(next, prev)` after each commit, and watcher failures are contained. + +## Provider contract + +Subclasses implement `writable`, `load()`, and `persist(ns, section)`, and push externally observed documents through the protected `publish(doc)`. At publish, each registered namespace re-resolves independently: an invalid section keeps that namespace's last good value and warns — a live reload never takes the process down — while boot-time and registration-time validation fail loud. + +## Events + +`settings/updated (ns, next, prev, source)` fires after each commit; `source` is `update` (in-process write) or `provider` (external change). It never fires for a deep-equal resolved value. + +## Model Experience + +Indirectly, through consumer plugins that resolve model-affecting values (for example a default model route) from their namespaces; each consumer's own surface documents the effect. + +#### KV Cache effect + +No direct invalidation; a consumer that folds a settings value into the request prefix owns that change. + +## Known Limitations and Deferred Work + +- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet. +- **Cross-process concurrency is provider-defined** — the seam serializes nothing across processes; concurrent writers converge by provider behavior (the local file provider is last-write-wins). +- **No secret-field redaction** — `describe()` returns resolved values verbatim; a wire surface (RPC/UI) must redact `role('secret')` fields before exposure. diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md new file mode 100644 index 0000000000..8733823106 --- /dev/null +++ b/packages/settings/settings/README.zh.md @@ -0,0 +1,35 @@ +# @deepseek-ai/dsh-settings + +[English](README.md) | 中文 + +抽象用户设置 seam（`ctx.settings`）。一个 provider 持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载 provider 时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。 + +## 服务 API + +- `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。 +- `describe()` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、`applies`），供配置界面使用。 +- `get(ns)` — 解析值；未注册时为 `undefined`。 +- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切更新。 +- 解析值是深冻结快照；每次提交后观察者收到 `(next, prev)`，观察者异常被隔离。 + +## Provider 契约 + +子类实现 `writable`、`load()`、`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。 + +## 事件 + +`settings/updated (ns, next, prev, source)` 在每次提交后触发；`source` 为 `update`（进程内写入）或 `provider`（外部变更）。解析值深相等时绝不触发。 + +## Model Experience + +间接生效：消费插件从各自 namespace 解析影响模型的值（例如默认模型路由）；效果由各消费者自己的文档描述。 + +#### KV Cache effect + +无直接失效；把设置值折叠进请求前缀的消费者拥有该变更。 + +## Known Limitations and Deferred Work + +- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。 +- **跨进程并发由 provider 定义** — seam 不做跨进程串行化；并发写入者按 provider 行为收敛（本地文件 provider 为后写胜出）。 +- **无 secret 字段脱敏** — `describe()` 原样返回解析值；wire 面（RPC/UI）在暴露前必须对 `role('secret')` 字段脱敏。 diff --git a/packages/settings/settings/package.json b/packages/settings/settings/package.json new file mode 100644 index 0000000000..7586b4bb24 --- /dev/null +++ b/packages/settings/settings/package.json @@ -0,0 +1,41 @@ +{ + "name": "@deepseek-ai/dsh-settings", + "description": "Abstract user-settings seam (ctx.settings) for the DeepSeek Harness", + "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" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-invariants": "^0.0.1", + "cordis": "^4.0.0-rc.7", + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "cordis": "^4.0.0-rc.7", + "schemastery": "^3.18.0" + } +} diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts new file mode 100644 index 0000000000..bec60dfdea --- /dev/null +++ b/packages/settings/settings/src/index.ts @@ -0,0 +1,304 @@ +/** + * User-settings seam (`ctx.settings`). Providers store one raw document of + * per-namespace sections; plugins register a namespace schema and read the + * resolved value, which layers schema defaults, the registrant's composition + * `base`, and the user document section, in that order. + * @module @deepseek-ai/dsh-settings + */ + +import { Context, Service } from 'cordis' +import { deepEqual } from 'cosmokit' +import type z from 'schemastery' +import type { Branded } from '@deepseek-ai/dsh-brand' + +/** Nominal id of one registered settings namespace. */ +export type SettingsNamespace = Branded<'SettingsNamespace'> + +const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/ + +/** + * Brand a raw string as a {@link SettingsNamespace}. + * @param value - candidate namespace; lowercase kebab-case, as in plugin short names. + * @returns the branded namespace. + */ +export function settingsNamespace(value: string): SettingsNamespace { + if (!NAMESPACE_PATTERN.test(value)) { + throw new TypeError(`settings namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`) + } + return value as SettingsNamespace +} + +/** When a namespace's changes take effect for its owner. */ +export type SettingsApplies = 'live' | 'restart' + +/** Origin of one committed settings change. */ +export type SettingsUpdateSource = 'update' | 'provider' + +/** Registration options beyond the namespace schema. */ +export interface SettingsRegisterOptions { + /** Composition-layer values resolved below the user layer (entry-config subset). */ + base?: Partial + /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */ + applies?: SettingsApplies +} + +/** One registered namespace as surfaced to configuration UIs. */ +export interface SettingsDescriptor { + /** The registered namespace. */ + ns: SettingsNamespace + /** Serialized schemastery schema (`schema.toJSON()`). */ + schema: unknown + /** Current resolved value. */ + value: unknown + /** Owner's declared effect timing. */ + applies: SettingsApplies +} + +/** Owner-facing handle for one registered namespace. */ +export interface SettingsScope { + /** Current resolved value: schema defaults, then `base`, then the user layer. */ + get(): T + /** + * Observe committed changes to this namespace's resolved value. + * @param callback - invoked after each commit with the next and previous values. + * @returns the disposer removing this observer. + */ + watch(callback: (next: T, prev: T) => void): () => void + /** + * Merge a partial patch into this namespace's user layer and persist it. + * @param patch - plain-object patch over the user section. + */ + update(patch: object): Promise +} + +declare module 'cordis' { + interface Context { + settings: Settings + } + + interface Events { + /** + * Committed change to one registered namespace's resolved value. Emitted + * after the provider persisted (for `update`) or published (`provider`) + * the change; never emitted when the resolved value is deep-equal. + * @param ns - the namespace whose resolved value changed. + * @param next - the new resolved value. + * @param prev - the previous resolved value. + * @param source - whether the change entered through `update()` or the provider. + * @mode emit + */ + 'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void + } +} + +/** Whether a value is a plain data object (not an array, null, or class instance). */ +function isPlainObject(value: unknown): value is Record { + if (typeof value !== 'object' || value === null || Array.isArray(value)) return false + const proto: unknown = Object.getPrototypeOf(value) + return proto === Object.prototype || proto === null +} + +/** + * Layer `over` onto `under`: plain objects merge recursively, every other + * value (arrays included) replaces the lower layer wholesale, and `undefined` + * entries in `over` are ignored so a sparse patch cannot erase lower keys. + */ +function mergeLayers(under: unknown, over: unknown): unknown { + if (over === undefined) return under + if (!isPlainObject(under) || !isPlainObject(over)) return over + const merged: Record = { ...under } + for (const [key, value] of Object.entries(over)) { + if (value === undefined) continue + merged[key] = key in merged ? mergeLayers(merged[key], value) : value + } + return merged +} + +/** Recursively freeze one resolved value so handed-out snapshots stay immutable. */ +function deepFreeze(value: T): T { + if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value + for (const entry of Object.values(value)) deepFreeze(entry) + return Object.freeze(value) +} + +/** One live namespace registration owned by a registrant fiber. */ +interface SettingsRegistration { + ns: SettingsNamespace + schema: z + base: unknown + applies: SettingsApplies + resolved: unknown + watchers: Set<(next: never, prev: never) => void> +} + +/** + * Abstract settings service. Providers implement raw-document storage + * (`load`/`persist`) and push external changes through {@link Settings.publish}; + * the base class owns namespace registration, resolution, validation, change + * detection, and the `settings/updated` commit event. + */ +export abstract class Settings extends Service { + private readonly registrations = new Map() + /** Latest published raw document; empty until the provider's first publish. */ + private document: Record = {} + + constructor(ctx: Context) { + super(ctx, 'settings') + } + + /** Whether {@link update} may persist through this provider. */ + abstract readonly writable: boolean + + /** + * Read the provider's current raw document (namespace to raw section). + * @returns the detached raw document. + */ + protected abstract load(): Promise> + + /** + * Durably store one namespace's merged user section. + * @param ns - the namespace being written. + * @param section - the complete merged user section to store. + */ + protected abstract persist(ns: SettingsNamespace, section: Record): Promise + + /** + * Register a namespace schema and receive its owner scope. The registration + * is an effect on the calling plugin's fiber: disposing that fiber removes + * the namespace and its observers. An invalid stored section fails the + * registration itself — the earliest point where the schema can judge it. + * @param ns - unique namespace; duplicate registration fails loud. + * @param schema - schemastery schema resolving this namespace's value. + * @param options - composition `base` layer and effect timing. + * @returns the owner scope for reads, observation, and updates. + */ + register(ns: SettingsNamespace, schema: z, options?: SettingsRegisterOptions): SettingsScope { + if (this.registrations.has(ns)) { + throw new Error(`settings namespace "${ns}" is already registered`) + } + const registration: SettingsRegistration = { + ns, + schema: schema as z, + base: options?.base, + applies: options?.applies ?? 'live', + resolved: deepFreeze(this.resolve(schema, options?.base, this.section(ns))), + watchers: new Set(), + } + this.ctx.effect(() => { + this.registrations.set(ns, registration) + return () => this.registrations.delete(ns) + }, `settings.register(${JSON.stringify(String(ns))})`) + return { + get: () => registration.resolved as T, + watch: (callback) => { + registration.watchers.add(callback) + return () => registration.watchers.delete(callback) + }, + update: patch => this.update(ns, patch), + } + } + + /** + * Describe every registered namespace for configuration surfaces. + * @returns one descriptor per registered namespace, in registration order. + */ + describe(): SettingsDescriptor[] { + return [...this.registrations.values()].map(registration => ({ + ns: registration.ns, + schema: registration.schema.toJSON(), + value: registration.resolved, + applies: registration.applies, + })) + } + + /** + * Read one registered namespace's resolved value. + * @param ns - the namespace to read. + * @returns the resolved value, or `undefined` while unregistered. + */ + get(ns: SettingsNamespace): unknown { + return this.registrations.get(ns)?.resolved + } + + /** + * Merge a patch into one registered namespace's user layer, validate the + * resolved candidate, persist through the provider, then commit and emit. + * A validation failure rejects before anything is persisted. + * @param ns - the registered namespace to update. + * @param patch - plain-object patch over the user section. + */ + async update(ns: SettingsNamespace, patch: object): Promise { + const registration = this.registrations.get(ns) + if (registration === undefined) { + throw new Error(`settings namespace "${ns}" is not registered`) + } + if (!this.writable) { + throw new Error(`settings provider is read-only: "${ns}" cannot be updated in-process`) + } + if (!isPlainObject(patch)) { + throw new TypeError(`settings update for "${ns}" must be a plain object patch`) + } + const section = mergeLayers(this.section(ns) ?? {}, patch) as Record + const next = deepFreeze(this.resolve(registration.schema, registration.base, section)) + await this.persist(ns, section) + this.document[ns] = section + this.commit(registration, next, 'update') + } + + /** + * Provider hook: commit a complete raw document observed in storage. Each + * registered namespace re-resolves; an invalid section keeps that + * namespace's last good value and warns, other namespaces still commit. + * @param doc - the detached raw document (unregistered sections preserved). + * @param source - change origin; defaults to `provider`. + */ + protected publish(doc: Record, source: SettingsUpdateSource = 'provider'): void { + this.document = doc + for (const registration of this.registrations.values()) { + let next: unknown + try { + next = deepFreeze(this.resolve(registration.schema, registration.base, this.section(registration.ns))) + } catch (error) { + this.ctx.logger.warn('settings: keeping last good "%s" after invalid stored section', registration.ns) + this.ctx.logger.warn(error) + continue + } + this.commit(registration, next, source) + } + } + + /** Read one namespace's raw user section, rejecting non-object sections. */ + private section(ns: SettingsNamespace): Record | undefined { + const section = this.document[ns] + if (section === undefined) return undefined + if (!isPlainObject(section)) { + throw new TypeError(`settings section "${ns}" must be an object of keys`) + } + return section + } + + /** Resolve one namespace value: schema defaults, then `base`, then the user layer. */ + private resolve(schema: z, base: unknown, section: Record | undefined): T { + // The merged candidate is untyped by construction; the schema call is the + // runtime validation that admits it into T. + return schema(mergeLayers(base, section) as never) + } + + /** Commit a resolved value when changed: swap, notify watchers, emit the event. */ + private commit(registration: SettingsRegistration, next: unknown, source: SettingsUpdateSource): void { + const prev = registration.resolved + if (deepEqual(next, prev)) return + registration.resolved = next + for (const watcher of [...registration.watchers]) { + try { + watcher(next as never, prev as never) + } catch (error) { + this.ctx.logger.warn('settings: watcher for "%s" failed', registration.ns) + this.ctx.logger.warn(error) + } + } + this.ctx.emit('settings/updated', registration.ns, next, prev, source) + } +} + +export default Settings diff --git a/packages/settings/settings/src/invariant.ts b/packages/settings/settings/src/invariant.ts new file mode 100644 index 0000000000..235f413aae --- /dev/null +++ b/packages/settings/settings/src/invariant.ts @@ -0,0 +1,41 @@ +/** + * Package-owned invariant companion for `@deepseek-ai/dsh-settings`. + * @module @deepseek-ai/dsh-settings/invariant + */ + +import type { Context } from 'cordis' +import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-settings' + +/** Cordis companion plugin name. */ +export const name = 'settings-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** + * Install the commit-event contract: `settings/updated` fires only for a + * currently registered namespace and only when the resolved value changed. + */ +const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => { + ctx.on('settings/updated', (ns, next, prev) => { + const settings = ctx.get('settings') + if (settings === undefined) { + fail(`settings/updated for "${ns}" emitted without a live settings service`) + } + if (settings.get(ns) === undefined) { + fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`) + } + if (JSON.stringify(next) === JSON.stringify(prev)) { + fail(`settings/updated for "${ns}" emitted without a resolved-value change`) + } + }) +} + +/** + * Register this package's invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) diff --git a/packages/settings/settings/tests/invariant.spec.ts b/packages/settings/settings/tests/invariant.spec.ts new file mode 100644 index 0000000000..f12ff6126c --- /dev/null +++ b/packages/settings/settings/tests/invariant.spec.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import InvariantService from '@deepseek-ai/dsh-invariants' +import * as SettingsInvariant from '../src/invariant.ts' +import { settingsNamespace } from '../src/index.ts' +import { MemorySettings } from './memory.ts' + +async function setup(withProvider: boolean): Promise { + const ctx = new Context() + await ctx.plugin(InvariantService) + await ctx.plugin(SettingsInvariant) + if (withProvider) await ctx.plugin(MemorySettings) + return ctx +} + +describe('settings invariants', () => { + it('fails a settings/updated emission without a live settings service', async () => { + const ctx = await setup(false) + expect(() => { + ctx.emit('settings/updated', settingsNamespace('ghost'), { a: 1 }, { a: 2 }, 'provider') + }).toThrow(/without a live settings service/) + }) + + it('fails a settings/updated emission for an unregistered namespace', async () => { + const ctx = await setup(true) + expect(() => { + ctx.emit('settings/updated', settingsNamespace('ghost'), { a: 1 }, { a: 2 }, 'provider') + }).toThrow(/unregistered/) + }) + + it('fails a settings/updated emission without a resolved-value change', async () => { + const ctx = await setup(true) + ctx.settings.register(settingsNamespace('ui-theme'), z.object({ + theme: z.string().default('dark'), + })) + expect(() => { + ctx.emit('settings/updated', settingsNamespace('ui-theme'), { theme: 'dark' }, { theme: 'dark' }, 'update') + }).toThrow(/without a resolved-value change/) + }) +}) diff --git a/packages/settings/settings/tests/memory.ts b/packages/settings/settings/tests/memory.ts new file mode 100644 index 0000000000..0b20771cbe --- /dev/null +++ b/packages/settings/settings/tests/memory.ts @@ -0,0 +1,53 @@ +/** + * In-memory settings provider fixture: the smallest real subclass of the seam, + * used by the base-class behavior suite in place of a file- or network-backed + * provider. Kept in `tests/` because production providers live in their own + * packages. + */ + +import { Service } from 'cordis' +import { Settings, type SettingsNamespace } from '../src/index.ts' + +/** In-memory provider exposing the protected seam hooks to tests. */ +export class MemorySettings extends Settings { + /** Raw document the provider "storage" currently holds. */ + doc: Record + /** Every persist() call observed, in order. */ + persisted: Array<{ ns: SettingsNamespace; section: Record }> = [] + /** When false, update() must reject before reaching persist(). */ + writableFlag: boolean + + constructor(ctx: ConstructorParameters[0], options?: { + doc?: Record + writable?: boolean + }) { + super(ctx) + this.doc = structuredClone(options?.doc ?? {}) + this.writableFlag = options?.writable ?? true + } + + get writable(): boolean { + return this.writableFlag + } + + protected load(): Promise> { + return Promise.resolve(structuredClone(this.doc)) + } + + protected persist(ns: SettingsNamespace, section: Record): Promise { + this.persisted.push({ ns, section: structuredClone(section) }) + this.doc[ns] = structuredClone(section) + return Promise.resolve() + } + + /** Simulate an external storage change reaching the provider. */ + pushExternal(doc: Record): void { + this.doc = structuredClone(doc) + this.publish(structuredClone(doc)) + } + + async* [Service.init](): AsyncGenerator<() => void, void, void> { + this.publish(await this.load()) + yield () => { this.persisted.length = 0 } + } +} diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts new file mode 100644 index 0000000000..a3d223c3f7 --- /dev/null +++ b/packages/settings/settings/tests/settings.spec.ts @@ -0,0 +1,307 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import { settingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts' +import { MemorySettings } from './memory.ts' + +interface ThemeConfig { + theme: 'dark' | 'light' + fontSize: number +} + +const ThemeSchema: z = z.object({ + theme: z.union(['dark', 'light']).default('dark'), + fontSize: z.number().default(14), +}) + +interface NestedConfig { + retry: { attempts: number; delayMs: number } + tags: string[] +} + +const NestedSchema: z = z.object({ + retry: z.object({ + attempts: z.number().default(2), + delayMs: z.number().default(100), + }), + tags: z.array(z.string()).default(['default']), +}) + +async function boot(options?: ConstructorParameters[1]) { + const ctx = new Context() + await ctx.plugin(MemorySettings, options) + const provider = ctx.get('settings') as MemorySettings + return { ctx, provider } +} + +/** Record every settings/updated emission. */ +function recordUpdates(ctx: Context) { + const events: Array<{ ns: string; next: unknown; prev: unknown; source: SettingsUpdateSource }> = [] + ctx.on('settings/updated', (ns, next, prev, source) => { + events.push({ ns, next, prev, source }) + }) + return events +} + +describe('settingsNamespace', () => { + it('brands lowercase kebab-case names', () => { + expect(settingsNamespace('ui-theme')).toBe('ui-theme') + }) + + it.each(['', 'UI', '9lives', 'a_b', '-lead'])('rejects %j', (value) => { + expect(() => settingsNamespace(value)).toThrow(TypeError) + }) +}) + +describe('registration', () => { + it('resolves schema defaults, then composition base, then the user layer', async () => { + const { ctx } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { fontSize: 16 }, + }) + // theme: user layer wins; fontSize: base wins over the schema default. + expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 }) + }) + + it('rejects a duplicate namespace loud', async () => { + const { ctx } = await boot() + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)) + .toThrow(/already registered/) + }) + + it('fails registration when the stored section is invalid for the schema', async () => { + const { ctx } = await boot({ doc: { 'ui-theme': { fontSize: 'big' } } }) + expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)).toThrow() + }) + + it('fails registration when the stored section is not an object', async () => { + const { ctx } = await boot({ doc: { 'ui-theme': 'dark' } }) + expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)) + .toThrow(/must be an object/) + }) + + it('describes registered namespaces with schema JSON, value, and applies', async () => { + const { ctx } = await boot() + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + ctx.settings.register(settingsNamespace('workspace'), NestedSchema, { applies: 'restart' }) + const descriptors = ctx.settings.describe() + expect(descriptors.map(entry => [entry.ns, entry.applies])).toEqual([ + ['ui-theme', 'live'], + ['workspace', 'restart'], + ]) + expect(descriptors[0]!.value).toEqual({ theme: 'dark', fontSize: 14 }) + // schemastery's canonical wire form: a { uid, refs } envelope whose root ref + // is the object schema — the shape schema-driven form UIs reconstruct from. + const serialized = descriptors[0]!.schema as { uid: number; refs: Record } + expect(serialized.refs[String(serialized.uid)]?.type).toBe('object') + }) + + it('reads undefined for an unregistered namespace', async () => { + const { ctx } = await boot() + expect(ctx.settings.get(settingsNamespace('missing'))).toBeUndefined() + }) + + it('hands out frozen resolved values', async () => { + const { ctx } = await boot({ doc: { workspace: { retry: { attempts: 5 } } } }) + const scope = ctx.settings.register(settingsNamespace('workspace'), NestedSchema) + const value = scope.get() + expect(Object.isFrozen(value)).toBe(true) + expect(Object.isFrozen(value.retry)).toBe(true) + expect(() => { (value.retry as { attempts: number }).attempts = 0 }).toThrow(TypeError) + }) + + it('removes the namespace and its observers when the registrant fiber disposes', async () => { + const { ctx, provider } = await boot() + const seen: unknown[] = [] + let scope: SettingsScope | undefined + const fiber = ctx.plugin({ + inject: ['settings'], + apply: (child: Context) => { + scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + scope.watch(next => seen.push(next)) + }, + }) + await fiber + expect(ctx.settings.get(settingsNamespace('ui-theme'))).toEqual({ theme: 'dark', fontSize: 14 }) + + await fiber.dispose() + expect(ctx.settings.get(settingsNamespace('ui-theme'))).toBeUndefined() + expect(ctx.settings.describe()).toEqual([]) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(seen).toEqual([]) + + // The namespace is free again, and re-registration resolves the user layer + // that kept living in storage while nobody owned the namespace. + const again = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(again.get()).toEqual({ theme: 'light', fontSize: 14 }) + }) +}) + +describe('update', () => { + it('persists the merged user section without baking in the base layer', async () => { + const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { fontSize: 16 }, + }) + await scope.update({ theme: 'dark' }) + expect(provider.persisted).toEqual([ + { ns: 'ui-theme', section: { theme: 'dark' } }, + ]) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 }) + }) + + it('deep-merges nested objects and replaces arrays wholesale', async () => { + const { ctx, provider } = await boot({ + doc: { workspace: { retry: { attempts: 5, delayMs: 300 }, tags: ['a', 'b'] } }, + }) + const scope = ctx.settings.register(settingsNamespace('workspace'), NestedSchema) + await scope.update({ retry: { attempts: 7 }, tags: ['c'] }) + expect(provider.persisted[0]!.section).toEqual({ + retry: { attempts: 7, delayMs: 300 }, + tags: ['c'], + }) + expect(scope.get()).toEqual({ retry: { attempts: 7, delayMs: 300 }, tags: ['c'] }) + }) + + it('commits, notifies watchers, and emits with source update', async () => { + const { ctx } = await boot() + const events = recordUpdates(ctx) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const watcher = vi.fn() + scope.watch(watcher) + await scope.update({ theme: 'light' }) + expect(watcher).toHaveBeenCalledWith( + { theme: 'light', fontSize: 14 }, + { theme: 'dark', fontSize: 14 }, + ) + expect(events).toEqual([{ + ns: 'ui-theme', + next: { theme: 'light', fontSize: 14 }, + prev: { theme: 'dark', fontSize: 14 }, + source: 'update', + }]) + }) + + it('rejects an invalid patch before persisting anything', async () => { + const { ctx, provider } = await boot() + const events = recordUpdates(ctx) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await expect(scope.update({ fontSize: 'big' })).rejects.toThrow() + expect(provider.persisted).toEqual([]) + expect(events).toEqual([]) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + }) + + it('ignores explicit undefined entries so a sparse patch cannot erase keys', async () => { + const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: undefined, fontSize: 18 }) + expect(provider.persisted[0]!.section).toEqual({ theme: 'light', fontSize: 18 }) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 18 }) + }) + + it('rejects a non-object patch', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await expect(scope.update([1])).rejects.toThrow(TypeError) + await expect(scope.update(new Date() as unknown as object)).rejects.toThrow(TypeError) + }) + + it('accepts a null-prototype patch object', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const patch: { fontSize?: number } = Object.create(null) as { fontSize?: number } + patch.fontSize = 18 + await scope.update(patch) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 }) + }) + + it('rejects an unregistered namespace', async () => { + const { ctx } = await boot() + await expect(ctx.settings.update(settingsNamespace('missing'), {})) + .rejects.toThrow(/not registered/) + }) + + it('rejects on a read-only provider before reaching persist', async () => { + const { ctx, provider } = await boot({ writable: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await expect(scope.update({ theme: 'light' })).rejects.toThrow(/read-only/) + expect(provider.persisted).toEqual([]) + }) +}) + +describe('publish', () => { + it('notifies watchers of an external change with source provider', async () => { + const { ctx, provider } = await boot() + const events = recordUpdates(ctx) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const watcher = vi.fn() + scope.watch(watcher) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(watcher).toHaveBeenCalledWith( + { theme: 'light', fontSize: 14 }, + { theme: 'dark', fontSize: 14 }, + ) + expect(events[0]!.source).toBe('provider') + }) + + it('stays silent when the resolved value is deep-equal', async () => { + const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) + const events = recordUpdates(ctx) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const watcher = vi.fn() + scope.watch(watcher) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(watcher).not.toHaveBeenCalled() + expect(events).toEqual([]) + }) + + it('keeps the last good value for an invalid section while other namespaces commit', async () => { + const { ctx, provider } = await boot() + const events = recordUpdates(ctx) + const theme = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const workspace = ctx.settings.register(settingsNamespace('workspace'), NestedSchema) + provider.pushExternal({ + 'ui-theme': { fontSize: 'broken' }, + workspace: { retry: { attempts: 9 } }, + }) + expect(theme.get()).toEqual({ theme: 'dark', fontSize: 14 }) + expect(workspace.get()).toEqual({ retry: { attempts: 9, delayMs: 100 }, tags: ['default'] }) + expect(events.map(event => event.ns)).toEqual(['workspace']) + }) + + it('recovers from a bad section once storage turns valid again', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + provider.pushExternal({ 'ui-theme': { fontSize: 'broken' } }) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + provider.pushExternal({ 'ui-theme': { fontSize: 18 } }) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 }) + }) +}) + +describe('watch', () => { + it('stops after its disposer runs', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const watcher = vi.fn() + const dispose = scope.watch(watcher) + dispose() + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(watcher).not.toHaveBeenCalled() + }) + + it('contains a throwing watcher without blocking the commit or other watchers', async () => { + const { ctx, provider } = await boot() + const events = recordUpdates(ctx) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + scope.watch(() => { throw new Error('watcher boom') }) + const second = vi.fn() + scope.watch(second) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(second).toHaveBeenCalledTimes(1) + expect(events).toHaveLength(1) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 }) + }) +}) diff --git a/packages/settings/settings/tsconfig.json b/packages/settings/settings/tsconfig.json new file mode 100644 index 0000000000..dd18d27fc3 --- /dev/null +++ b/packages/settings/settings/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/schemastery" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../support/invariants" + } + ] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b9538051cd..fce89446a6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3636,6 +3636,46 @@ importers: specifier: ^4.0.0-rc.7 version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + packages/settings/settings: + devDependencies: + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../support/invariants + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + + packages/settings/settings-local: + dependencies: + chokidar: + specifier: ^4.0.3 + version: 4.0.3 + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + yaml: + specifier: ^2.9.0 + version: 2.9.0 + devDependencies: + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../support/invariants + '@deepseek-ai/dsh-paths': + specifier: workspace:^ + version: link:../../util/paths + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../settings + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + packages/skill/skill: dependencies: schemastery: diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 4cae854147..a27d6af22b 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1705, + "AGENTS.md": 1710, "docs/AGENTS.md": 1150, "docs/architecture.md": 1800, "docs/cordis-primer.md": 600, @@ -7,5 +7,5 @@ "docs/testing.md": 1100, "examples/AGENTS.md": 310, "packages/AGENTS.md": 675, - "packages/README.md": 835 + "packages/README.md": 845 } diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index b10ad9dfac..b7df3dc622 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -217,6 +217,12 @@ const FOUNDATION_TYPE_NAMES = new Set([ /** Project types deliberately documented outside the core-data catalog. */ const TYPE_LINK_EXEMPTIONS: Readonly> = { AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md', + SettingsNamespace: 'settings seam vocabulary is owned by packages/settings/settings/README.md', + SettingsUpdateSource: 'settings seam vocabulary is owned by packages/settings/settings/README.md', + SettingsRegisterOptions: 'settings seam vocabulary is owned by packages/settings/settings/README.md', + SettingsScope: 'settings seam vocabulary is owned by packages/settings/settings/README.md', + SettingsDescriptor: 'settings seam vocabulary is owned by packages/settings/settings/README.md', + z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)', BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts', InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts', ConsumeTokenRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 1d4a7e447d..a077042d3c 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -137,6 +137,15 @@ const SERVICE_ROLES: ServiceRole[] = [ consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'], note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.', }, + { + key: 'settings', + pkg: 'settings', + title: 'User-settings seam', + mode: 'seam', + implementations: ['settings-local'], + consumers: [], + note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. No production consumer is migrated yet.', + }, { key: 'telemetry', pkg: 'session-telemetry', diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index 13dc2def8d..dc02127a17 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -90,6 +90,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' }, 'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' }, 'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers no model surface.' }, + 'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model surface a value feeds.' }, + 'packages/settings/settings-local': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model surface.' }, 'packages/telemetry/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' }, 'packages/telemetry/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' }, 'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index d4beec7afa..8f39d3ec5f 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -75,6 +75,7 @@ "./packages/hooks/*/src/invariant.ts", "./packages/session-persistence/*/src/invariant.ts", "./packages/session-query/*/src/invariant.ts", + "./packages/settings/*/src/invariant.ts", "./packages/telemetry/*/src/invariant.ts", "./packages/acp/*/src/invariant.ts", "./packages/storage/*/src/invariant.ts", @@ -156,6 +157,7 @@ "./packages/session-persistence/*/src", "./packages/session-query/*/src", "./packages/session-title/*/src", + "./packages/settings/*/src", "./packages/telemetry/*/src", "./packages/acp/*/src", "./packages/storage/*/src", diff --git a/tsconfig.host.json b/tsconfig.host.json index 9cf2a86bda..2c9bc2a652 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -58,6 +58,8 @@ { "path": "./packages/session-persistence/session-persistence-sqlite" }, { "path": "./packages/session-query/session-query" }, { "path": "./packages/session-query/session-query-sqlite" }, + { "path": "./packages/settings/settings" }, + { "path": "./packages/settings/settings-local" }, { "path": "./packages/session-query/tool-session-query" }, { "path": "./packages/storage/storage" }, { "path": "./packages/storage/storage-json" }, From f44b4db1f22b44b5d280065ad0bd8170d36b8d1a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 28 Jul 2026 18:18:34 +0800 Subject: [PATCH 09/67] fix(settings): harden seam and provider per review findings Confirmed and fixed, each with a regression test that failed first: - Concurrent update() lost patches (merge over one stale snapshot): per-namespace serialized write queues; a failed write cannot poison the queue for later writers. - Fixed-name .tmp write followed planted symlinks and kept stale modes: random-suffix sibling, exclusive-create (wx), 0600, cleanup on failure, then rename. - A throwing settings/updated listener escaped commit and permanently wedged the provider reload chain (rejected refreshTask): commit now contains listener failures (INVARIANT-coded errors still propagate), async watcher rejections are adopted and contained (watch callbacks are officially void | Promise), and the provider chains refreshes on a settled tail with an error log. - No way to remove a user override: scope/service replace(section) sets the user section wholesale; replace({}) re-inherits base and schema defaults. - The three-primitive provider contract did not hold (base never called load()): the base Service.init loads and publishes once; settings-local delegates via yield* super[Service.init](). - Dispose did not quiesce: teardown flags closed, closes the watcher, then awaits queued/in-flight reloads; closed is re-checked across await points. - Invariant now checks the authoritative relation with the seam's own deepEqualJson: emitted next must equal settings.get(ns), and next/prev must differ structurally (cosmokit dependency dropped). - New docs/core-data-structures/settings.{md,zh.md} with type-equiv blocks + manifest entries; catalog types moved from exemptions to LINK_MAP; website page registered. Both packages stay at per-file 100% coverage. --- docs/config-catalog.md | 2 +- docs/cordis-catalog/events.md | 4 +- docs/cordis-catalog/services.md | 18 ++- docs/core-data-structures/settings.i18n.yaml | 6 + docs/core-data-structures/settings.md | 94 +++++++++++++ docs/core-data-structures/settings.zh.md | 94 +++++++++++++ docs/event-producer-consumer.md | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 8 +- .../settings/settings-local/README.i18n.yaml | 4 +- packages/settings/settings-local/README.md | 3 +- packages/settings/settings-local/README.zh.md | 3 +- packages/settings/settings-local/src/index.ts | 58 +++++++-- .../tests/loader-composition.spec.ts | 2 +- .../settings-local/tests/local.spec.ts | 33 ++++- .../settings-local/tests/watcher.spec.ts | 54 ++++++++ packages/settings/settings/README.i18n.yaml | 4 +- packages/settings/settings/README.md | 9 +- packages/settings/settings/README.zh.md | 9 +- packages/settings/settings/src/index.ts | 123 +++++++++++++++--- packages/settings/settings/src/invariant.ts | 13 +- .../settings/settings/tests/invariant.spec.ts | 11 ++ packages/settings/settings/tests/memory.ts | 17 +-- .../settings/settings/tests/settings.spec.ts | 114 +++++++++++++++- scripts/gen-cordis-catalog.ts | 10 +- scripts/project-doc-site.spec.ts | 2 +- scripts/type-equiv.manifest.json | 30 +++++ website/docs.ts | 1 + 27 files changed, 655 insertions(+), 73 deletions(-) create mode 100644 docs/core-data-structures/settings.i18n.yaml create mode 100644 docs/core-data-structures/settings.md create mode 100644 docs/core-data-structures/settings.zh.md diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 1305dd7270..2a1eb47da5 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1193,7 +1193,7 @@ export interface Config { } ``` -Source: [`packages/settings/settings-local/src/index.ts:18`](../packages/settings/settings-local/src/index.ts) +Source: [`packages/settings/settings-local/src/index.ts:19`](../packages/settings/settings-local/src/index.ts) ## `@deepseek-ai/dsh-skill` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index aea04f4acd..74e1e6cfda 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -660,7 +660,9 @@ Committed change to one registered namespace's resolved value. Emitted after the 'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void ``` -Source: [`packages/settings/settings/src/index.ts:90`](../../packages/settings/settings/src/index.ts) +Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md) + +Source: [`packages/settings/settings/src/index.ts:96`](../../packages/settings/settings/src/index.ts) ## `slash/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index a0271083d6..e915952ffb 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1421,14 +1421,28 @@ get(ns: SettingsNamespace): unknown /** * Merge a patch into one registered namespace's user layer, validate the * resolved candidate, persist through the provider, then commit and emit. - * A validation failure rejects before anything is persisted. + * A validation failure rejects before anything is persisted. Writes to one + * namespace are serialized: concurrent updates apply in call order, each + * merging over the previous write's committed section. * @param ns - the registered namespace to update. * @param patch - plain-object patch over the user section. */ async update(ns: SettingsNamespace, patch: object): Promise + +/** + * Replace one registered namespace's user section wholesale, validate, + * persist, then commit and emit. Keys absent from `section` fall back to the + * composition `base` and schema defaults — this is the removal/reset path a + * merge-only patch cannot express (`replace({})` re-inherits everything). + * @param ns - the registered namespace to replace. + * @param section - the complete next user section. + */ +async replace(ns: SettingsNamespace, section: object): Promise ``` -Source: [`packages/settings/settings/src/index.ts:140`](../../packages/settings/settings/src/index.ts) +Types: [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md) + +Source: [`packages/settings/settings/src/index.ts:168`](../../packages/settings/settings/src/index.ts) ## `ctx.skills` — `SkillService` diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/core-data-structures/settings.i18n.yaml new file mode 100644 index 0000000000..6dc8750dfb --- /dev/null +++ b/docs/core-data-structures/settings.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/core-data-structures/settings.md +settings.md: 851087065c627f2390041dd6e69273e31be3917d +settings.zh.md: 955c4fbf7c147b3d0a8be62c33c031d7bd2c4ba2 diff --git a/docs/core-data-structures/settings.md b/docs/core-data-structures/settings.md new file mode 100644 index 0000000000..851087065c --- /dev/null +++ b/docs/core-data-structures/settings.md @@ -0,0 +1,94 @@ +# User Settings + +English | [中文](settings.zh.md) + +The user-settings seam of [dsh-settings](../../packages/settings/settings) holds one user-owned document of per-namespace sections and resolves each registered namespace as schema defaults, then the registrant's composition `base`, then the user section. Providers such as [dsh-settings-local](../../packages/settings/settings-local) store the raw document and push external edits; consumer plugins register a schema and read or observe the resolved value. Composition config stays in `cordis.yml` — a namespace carries only the user-editable subset. + +Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts) + +## Identity + +A namespace names one plugin-owned section of the user document. The brand keeps namespaces from mixing with other cross-boundary ids; construction validates the lowercase kebab-case shape. + +```ts type-equiv +/** Nominal id of one registered settings namespace. */ +type SettingsNamespace = Branded<'SettingsNamespace'> +``` + +## Registration + +Registration binds a schemastery schema to a namespace on the calling plugin's fiber — disposing that fiber removes the namespace and its observers. The options carry the composition layer and the owner's effect timing. + +```ts type-equiv +/** Registration options beyond the namespace schema. */ +interface SettingsRegisterOptions { + /** Composition-layer values resolved below the user layer (entry-config subset). */ + base?: Partial + /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */ + applies?: SettingsApplies +} +``` + +`applies` is a UI hint, not a mechanism: a `restart` owner simply never watches, so its value is read once at construction and configuration surfaces can badge the pending change. + +```ts type-equiv +/** When a namespace's changes take effect for its owner. */ +type SettingsApplies = 'live' | 'restart' +``` + +## Owner scope + +The scope is the owner-facing handle. `update` merges a sparse patch over the user section only (never into `base`); `replace` sets the section wholesale, which is the removal/reset path — keys absent from the replacement re-inherit `base` and schema defaults. Writes to one namespace are serialized in call order, and resolved values are deep-frozen snapshots. + +```ts type-equiv +/** Owner-facing handle for one registered namespace. */ +interface SettingsScope { + /** Current resolved value: schema defaults, then `base`, then the user layer. */ + get(): T + /** + * Observe committed changes to this namespace's resolved value. A callback + * may be async; a rejection is contained and logged like a sync throw. + * @param callback - invoked after each commit with the next and previous values. + * @returns the disposer removing this observer. + */ + watch(callback: (next: T, prev: T) => void | Promise): () => void + /** + * Merge a partial patch into this namespace's user layer and persist it. + * @param patch - plain-object patch over the user section. + */ + update(patch: object): Promise + /** + * Replace this namespace's user section wholesale; absent keys re-inherit + * the composition `base` and schema defaults (`replace({})` resets all). + * @param section - the complete next user section. + */ + replace(section: object): Promise +} +``` + +## Descriptors + +`describe()` serializes every registered namespace for configuration surfaces: the schemastery `toJSON()` envelope drives schema-rendered forms, and the resolved value fills them. + +```ts type-equiv +/** One registered namespace as surfaced to configuration UIs. */ +interface SettingsDescriptor { + /** The registered namespace. */ + ns: SettingsNamespace + /** Serialized schemastery schema (`schema.toJSON()`). */ + schema: unknown + /** Current resolved value. */ + value: unknown + /** Owner's declared effect timing. */ + applies: SettingsApplies +} +``` + +## Change commits + +Every committed change — an in-process write or an externally observed provider edit — emits `settings/updated (ns, next, prev, source)` after the new value is authoritative, and never when the resolved value is deep-equal. The source tag separates the two entry paths. + +```ts type-equiv +/** Origin of one committed settings change. */ +type SettingsUpdateSource = 'update' | 'provider' +``` diff --git a/docs/core-data-structures/settings.zh.md b/docs/core-data-structures/settings.zh.md new file mode 100644 index 0000000000..955c4fbf7c --- /dev/null +++ b/docs/core-data-structures/settings.zh.md @@ -0,0 +1,94 @@ +# 用户设置 + +[English](settings.md) | 中文 + +[dsh-settings](../../packages/settings/settings) 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 `base`，最后用户分节。[dsh-settings-local](../../packages/settings/settings-local) 这类 provider 存储原始文档并推送外部编辑；消费插件注册 schema 后读取或观察解析值。组合配置仍留在 `cordis.yml`——namespace 只承载用户可编辑子集。 + +Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts) + +## 标识 + +namespace 命名用户文档中一个插件所有的分节。brand 使其不与其他跨边界 id 混用；构造时校验小写 kebab-case 形态。 + +```ts type-equiv +/** Nominal id of one registered settings namespace. */ +type SettingsNamespace = Branded<'SettingsNamespace'> +``` + +## 注册 + +注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose 该 fiber 即移除 namespace 及其观察者。options 携带组合层与 owner 的生效时机。 + +```ts type-equiv +/** Registration options beyond the namespace schema. */ +interface SettingsRegisterOptions { + /** Composition-layer values resolved below the user layer (entry-config subset). */ + base?: Partial + /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */ + applies?: SettingsApplies +} +``` + +`applies` 是 UI 提示而非机制：`restart` 的 owner 只是从不 watch，其值在构造期读取一次，配置界面可为待生效变更加标。 + +```ts type-equiv +/** When a namespace's changes take effect for its owner. */ +type SettingsApplies = 'live' | 'restart' +``` + +## Owner scope + +scope 是面向 owner 的句柄。`update` 把稀疏 patch 只合并进用户分节（绝不进 `base`）；`replace` 整体替换分节，是删除/重置路径——替换中缺席的键重新继承 `base` 与 schema 默认值。同一 namespace 的写入按调用顺序串行，解析值是深冻结快照。 + +```ts type-equiv +/** Owner-facing handle for one registered namespace. */ +interface SettingsScope { + /** Current resolved value: schema defaults, then `base`, then the user layer. */ + get(): T + /** + * Observe committed changes to this namespace's resolved value. A callback + * may be async; a rejection is contained and logged like a sync throw. + * @param callback - invoked after each commit with the next and previous values. + * @returns the disposer removing this observer. + */ + watch(callback: (next: T, prev: T) => void | Promise): () => void + /** + * Merge a partial patch into this namespace's user layer and persist it. + * @param patch - plain-object patch over the user section. + */ + update(patch: object): Promise + /** + * Replace this namespace's user section wholesale; absent keys re-inherit + * the composition `base` and schema defaults (`replace({})` resets all). + * @param section - the complete next user section. + */ + replace(section: object): Promise +} +``` + +## 描述符 + +`describe()` 为配置界面序列化每个已注册 namespace：schemastery 的 `toJSON()` 信封驱动 schema 渲染的表单，解析值填充表单。 + +```ts type-equiv +/** One registered namespace as surfaced to configuration UIs. */ +interface SettingsDescriptor { + /** The registered namespace. */ + ns: SettingsNamespace + /** Serialized schemastery schema (`schema.toJSON()`). */ + schema: unknown + /** Current resolved value. */ + value: unknown + /** Owner's declared effect timing. */ + applies: SettingsApplies +} +``` + +## 变更提交 + +每次提交的变更——进程内写入或 provider 观察到的外部编辑——在新值成为权威值之后发出 `settings/updated (ns, next, prev, source)`，解析值深相等时绝不发出。source 标记区分两条入口路径。 + +```ts type-equiv +/** Origin of one committed settings change. */ +type SettingsUpdateSource = 'update' | 'provider' +``` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 49bdf3fe35..e3eb1d9435 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -35,7 +35,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:80`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:92`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:102`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | -| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:90`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`emit`) | [`settings`](../packages/settings/settings) | +| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:96`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`emit`) | [`settings`](../packages/settings/settings) | | `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:230`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:244`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-insert-reference` | `bail` | [`packages/client/ui-slash/src/types.ts:237`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 81e3c79d05..4190a94a90 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -684,7 +684,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'async update(ns: SettingsNamespace, patch: object): Promise', - jsDoc: '/**\n * Merge a patch into one registered namespace\'s user layer, validate the\n * resolved candidate, persist through the provider, then commit and emit.\n * A validation failure rejects before anything is persisted.\n * @param ns - the registered namespace to update.\n * @param patch - plain-object patch over the user section.\n */', + jsDoc: '/**\n * Merge a patch into one registered namespace\'s user layer, validate the\n * resolved candidate, persist through the provider, then commit and emit.\n * A validation failure rejects before anything is persisted. Writes to one\n * namespace are serialized: concurrent updates apply in call order, each\n * merging over the previous write\'s committed section.\n * @param ns - the registered namespace to update.\n * @param patch - plain-object patch over the user section.\n */', + }, + { + signature: 'async replace(ns: SettingsNamespace, section: object): Promise', + jsDoc: '/**\n * Replace one registered namespace\'s user section wholesale, validate,\n * persist, then commit and emit. Keys absent from `section` fall back to the\n * composition `base` and schema defaults — this is the removal/reset path a\n * merge-only patch cannot express (`replace({})` re-inherits everything).\n * @param ns - the registered namespace to replace.\n * @param section - the complete next user section.\n */', }, ], }, @@ -2228,7 +2232,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SettingsScope', - declaration: 'export interface SettingsScope {\n get(): T;\n watch(callback: (next: T, prev: T) => void): () => void;\n update(patch: object): Promise;\n}', + declaration: 'export interface SettingsScope {\n get(): T;\n watch(callback: (next: T, prev: T) => void | Promise): () => void;\n update(patch: object): Promise;\n replace(section: object): Promise;\n}', }, { name: 'SkillCandidate', diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml index f7ca57e86e..455255941a 100644 --- a/packages/settings/settings-local/README.i18n.yaml +++ b/packages/settings/settings-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings-local/README.md -README.md: 90428f98055d8e49fa1ec54e571453db2e0a5054 -README.zh.md: 3532d6cee99cb46f54e23889ef1bb54b2548ecfa +README.md: 9d0aa3982507ca16b382aaa918ca1536a98e29ea +README.zh.md: 075de7ee5b3e0ef0a4ee27eeb8cb098ca0d73456 diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md index 90428f9805..9d0aa39825 100644 --- a/packages/settings/settings-local/README.md +++ b/packages/settings/settings-local/README.md @@ -18,7 +18,8 @@ Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension ## Behavior - **Boot fails loud, reload keeps last-good.** An existing-but-invalid document fails plugin load; once live, an unreadable or unparsable edit warns and keeps the last good sections. A missing document resolves every namespace from defaults and `base`; deleting it publishes the same empty state. -- **Write-back is atomic and owner-only.** `persist` writes `.tmp` with mode `0600` and renames over the target. YAML writes patch one namespace in the comment-preserving document; JSON re-serializes. +- **Write-back is atomic, owner-only, and symlink-proof.** `persist` exclusive-creates a random-suffix temp sibling with mode `0600` (`wx` refuses to follow a planted symlink) and renames over the target, cleaning the temp up on failure. YAML writes patch one namespace in the comment-preserving document; JSON re-serializes. +- **Dispose quiesces.** Teardown stops accepting watcher events, closes the watcher, then waits out any queued or in-flight reload, so nothing publishes after disposal. - **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op. ## Model Experience diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md index 3532d6cee9..075de7ee5b 100644 --- a/packages/settings/settings-local/README.zh.md +++ b/packages/settings/settings-local/README.zh.md @@ -18,7 +18,8 @@ ## 行为 - **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。 -- **写回原子且仅属主可读。** `persist` 以 `0600` 权限写 `.tmp` 后 rename 覆盖目标。YAML 写回在保留注释的文档里只修补目标 namespace；JSON 重新序列化。 +- **写回原子、仅属主可读、抗符号链接。** `persist` 以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。YAML 写回在保留注释的文档里只修补目标 namespace；JSON 重新序列化。 +- **Dispose 保证静止。** 卸载先停止接收 watcher 事件、关闭 watcher，再等完排队与进行中的重载，之后不再有任何发布。 - **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。 ## Model Experience diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts index 421411ea50..2c020da63c 100644 --- a/packages/settings/settings-local/src/index.ts +++ b/packages/settings/settings-local/src/index.ts @@ -8,7 +8,8 @@ import { Context, Service } from 'cordis' import z from 'schemastery' import { watch as chokidarWatch } from 'chokidar' -import { mkdir, readFile, rename, writeFile } from 'node:fs/promises' +import { randomBytes } from 'node:crypto' +import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises' import { dirname, extname, join, resolve } from 'node:path' import { Document, parseDocument } from 'yaml' import { resolveDshHome } from '@deepseek-ai/dsh-paths' @@ -86,6 +87,13 @@ export class SettingsLocal extends Settings { private text: string | undefined /** Serializes watcher-triggered reloads so reads never interleave. */ private refreshTask: Promise = Promise.resolve() + /** Set at dispose: refuse new watcher events and let in-flight work no-op. */ + private closed = false + + /** Opaque read of {@link closed}: control flow cannot narrow it across awaits. */ + private isClosed(): boolean { + return this.closed + } constructor(ctx: Context, public config: Config) { super(ctx) @@ -118,18 +126,26 @@ export class SettingsLocal extends Settings { ? this.renderYaml(ns, section) : this.renderJson(ns, section) await mkdir(dirname(this.spec.filename), { recursive: true }) - const temp = `${this.spec.filename}.tmp` - // Owner-only permissions apply to the temp file and survive the rename, so - // a document that may carry personal values is never world-readable. - await writeFile(temp, output, { mode: 0o600 }) - await rename(temp, this.spec.filename) + // Exclusive-create (`wx`) a random-suffix sibling: the open refuses to + // follow any planted symlink at a guessable temp path, and the fresh inode + // carries owner-only permissions that survive the rename — a document that + // may hold personal values is never world-readable and never a symlink. + const temp = `${this.spec.filename}.${randomBytes(6).toString('hex')}.tmp` + try { + await writeFile(temp, output, { mode: 0o600, flag: 'wx' }) + await rename(temp, this.spec.filename) + } catch (error) { + await rm(temp, { force: true }) + throw error + } this.text = output } - async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { - // A parse failure here is a boot failure: an existing-but-invalid document - // must fail loud, never be silently ignored or overwritten. - this.publish(await this.load()) + override async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { + // The base init loads and publishes; a parse failure there is a boot + // failure: an existing-but-invalid document must fail loud, never be + // silently ignored or overwritten. + yield* super[Service.init]() if (!this.spec.watch) return const watcher = chokidarWatch(this.spec.filename, { ignoreInitial: true, @@ -139,13 +155,26 @@ export class SettingsLocal extends Settings { }, }) watcher.on('all', () => { - this.refreshTask = this.refreshTask.then(() => this.refresh()) + if (this.closed) return + this.refreshTask = this.refreshTask.then(() => this.refresh()).catch((error: unknown) => { + // Only an invariant violation escaping the commit path can reject a + // refresh; keep the reload queue alive and surface it as an error so + // one poisoned commit cannot silently end hot reloading forever. + this.ctx.logger.error('settings-local: reload commit failed at %s', this.spec.filename) + this.ctx.logger.error(error) + }) }) watcher.on('error', (error) => { this.ctx.logger.warn('settings-local: watcher error on %s', this.spec.filename) this.ctx.logger.warn(error) }) - yield () => watcher.close() + yield async () => { + // Quiesce: stop accepting events, close the watcher, then wait out any + // queued or in-flight refresh so nothing publishes after disposal. + this.closed = true + await watcher.close() + await this.refreshTask + } } /** Parse one document text into raw sections, failing on a non-map root. */ @@ -174,6 +203,7 @@ export class SettingsLocal extends Settings { * never take the process down. */ private async refresh(): Promise { + if (this.closed) return let text: string try { text = await readFile(this.spec.filename, 'utf8') @@ -183,12 +213,12 @@ export class SettingsLocal extends Settings { this.ctx.logger.warn(error) return } - if (this.text === undefined) return + if (this.text === undefined || this.isClosed()) return this.text = undefined this.publish({}) return } - if (text === this.text) return + if (text === this.text || this.isClosed()) return let doc: Record try { doc = this.parse(text) diff --git a/packages/settings/settings-local/tests/loader-composition.spec.ts b/packages/settings/settings-local/tests/loader-composition.spec.ts index 5744e92f46..d584c11899 100644 --- a/packages/settings/settings-local/tests/loader-composition.spec.ts +++ b/packages/settings/settings-local/tests/loader-composition.spec.ts @@ -55,7 +55,7 @@ async function loadComposition(): Promise<{ ctx: Context; state: ConsumerState; base: { fontSize: 16 }, }) state.scope = scope - scope.watch(next => state.seen.push(next)) + scope.watch((next) => { state.seen.push(next) }) }, } diff --git a/packages/settings/settings-local/tests/local.spec.ts b/packages/settings/settings-local/tests/local.spec.ts index 9c9d472bac..1c74429153 100644 --- a/packages/settings/settings-local/tests/local.spec.ts +++ b/packages/settings/settings-local/tests/local.spec.ts @@ -1,7 +1,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import z from 'schemastery' -import { chmod, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises' +import { chmod, lstat, mkdtemp, readFile, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { settingsNamespace } from '@deepseek-ai/dsh-settings' @@ -146,6 +146,23 @@ describe('persist', () => { expect((await readdir(dir)).sort()).toEqual(['settings.yaml']) }) + it('never follows a planted symlink at a temp path and never leaves the document a symlink', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const victim = join(dir, 'victim.txt') + await writeFile(victim, 'precious') + // A hostile sibling plants the historic fixed temp name as a symlink. + await symlink(victim, `${path}.tmp`) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + + expect(await readFile(victim, 'utf8')).toBe('precious') + expect((await lstat(path)).isSymbolicLink()).toBe(false) + expect((await stat(path)).mode & 0o777).toBe(0o600) + expect(await readFile(path, 'utf8')).toContain('theme: light') + }) + it('preserves comments and unregistered sections across updates', async () => { const dir = await tempDir() const path = join(dir, 'settings.yaml') @@ -180,6 +197,20 @@ describe('persist', () => { expect(written).toEqual({ 'ui-theme': { theme: 'light' } }) }) + it('rejects and leaves no temp residue when the directory turns unwritable', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await chmod(dir, 0o500) + cleanups.push(() => chmod(dir, 0o700)) + await expect(scope.update({ theme: 'dark' })).rejects.toThrow() + await chmod(dir, 0o700) + expect((await readdir(dir)).sort()).toEqual(['settings.yaml']) + expect(scope.get().theme).toBe('light') + }) + it('round-trips a json document', async () => { const dir = await tempDir() const path = join(dir, 'settings.json') diff --git a/packages/settings/settings-local/tests/watcher.spec.ts b/packages/settings/settings-local/tests/watcher.spec.ts index 00c67eacc7..439f213473 100644 --- a/packages/settings/settings-local/tests/watcher.spec.ts +++ b/packages/settings/settings-local/tests/watcher.spec.ts @@ -105,6 +105,60 @@ describe('watcher pipeline', () => { expect(scope.get()).toEqual({ theme: 'light' }) }) + it('keeps the reload queue alive after an invariant violation escapes a commit', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + let arm = true + ctx.on('settings/updated', () => { + if (!arm) return + throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' }) + }) + const [instance] = await fakeInstances() + + await writeFile(path, 'ui-theme:\n theme: broken-commit\n') + instance!.watcher.emit('all', 'change', path) + await vi.waitFor(() => { + expect(scope.get().theme).toBe('broken-commit') + }) + + arm = false + await writeFile(path, 'ui-theme:\n theme: recovered\n') + instance!.watcher.emit('all', 'change', path) + await vi.waitFor(() => { + expect(scope.get().theme).toBe('recovered') + }) + }) + + it('quiesces the refresh pipeline before dispose completes', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = new Context() + const fiber = ctx.plugin(SettingsLocal, { path, debounceMs: 5 }) + await fiber + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + let disposed = false + let postDisposeCommits = 0 + ctx.on('settings/updated', () => { + if (disposed) postDisposeCommits += 1 + }) + + await writeFile(path, 'ui-theme:\n theme: darker\n') + const [instance] = await fakeInstances() + // Two queued refreshes: dispose interrupts one mid-flight and the other + // before it starts, so both closed guards must hold. + instance!.watcher.emit('all', 'change', path) + instance!.watcher.emit('all', 'change', path) + await fiber.dispose() + disposed = true + instance!.watcher.emit('all', 'change', path) + await new Promise(resolve => setTimeout(resolve, 100)) + expect(postDisposeCommits).toBe(0) + }) + it('treats an event for a still-absent file as a no-op', async () => { const dir = await tempDir() const path = join(dir, 'settings.yaml') diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml index 51f30f2ca6..6f5e5c6beb 100644 --- a/packages/settings/settings/README.i18n.yaml +++ b/packages/settings/settings/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings/README.md -README.md: e57db00c095a87f9f0b51397e030dec364f48e62 -README.zh.md: 8733823106f0ef3880cbe2c567de2edcdeff2c86 +README.md: f7858a247f6011cd0654a73b5325d81c118441e5 +README.zh.md: 67ecba695066389bfe3a69f517d52f91b48b6c75 diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md index e57db00c09..f7858a247f 100644 --- a/packages/settings/settings/README.md +++ b/packages/settings/settings/README.md @@ -9,12 +9,13 @@ Abstract user-settings seam (`ctx.settings`). One provider holds a raw document - `register(ns, schema, { base?, applies? })` — returns the owner `SettingsScope` (`get`/`watch`/`update`). The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. A stored section the schema rejects fails the registration itself; a duplicate namespace fails loud. - `describe()` — one descriptor per namespace (`schema.toJSON()` envelope, resolved value, `applies`) for configuration surfaces. - `get(ns)` — resolved value, `undefined` while unregistered. -- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every update. -- Resolved values are deep-frozen snapshots; watchers receive `(next, prev)` after each commit, and watcher failures are contained. +- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every write. Writes to one namespace are serialized in call order. +- `replace(ns, section)` — sets the user section wholesale: the removal/reset path a merge cannot express (`replace({})` re-inherits `base` and schema defaults). +- Resolved values are deep-frozen snapshots; watchers receive `(next, prev)` after each commit, and watcher failures — sync throws and async rejections alike — are contained. ## Provider contract -Subclasses implement `writable`, `load()`, and `persist(ns, section)`, and push externally observed documents through the protected `publish(doc)`. At publish, each registered namespace re-resolves independently: an invalid section keeps that namespace's last good value and warns — a live reload never takes the process down — while boot-time and registration-time validation fail loud. +Subclasses implement `writable`, `load()`, and `persist(ns, section)`, and push externally observed documents through the protected `publish(doc)`. The base service init loads and publishes the document once before the service becomes injectable; a provider with its own init (watcher, connection) delegates first via `yield* super[Service.init]()`. At publish, each registered namespace re-resolves independently: an invalid section keeps that namespace's last good value and warns — a live reload never takes the process down — while boot-time and registration-time validation fail loud. ## Events @@ -31,5 +32,5 @@ No direct invalidation; a consumer that folds a settings value into the request ## Known Limitations and Deferred Work - **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet. -- **Cross-process concurrency is provider-defined** — the seam serializes nothing across processes; concurrent writers converge by provider behavior (the local file provider is last-write-wins). +- **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider is last-write-wins). - **No secret-field redaction** — `describe()` returns resolved values verbatim; a wire surface (RPC/UI) must redact `role('secret')` fields before exposure. diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md index 8733823106..67ecba6950 100644 --- a/packages/settings/settings/README.zh.md +++ b/packages/settings/settings/README.zh.md @@ -9,12 +9,13 @@ - `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。 - `describe()` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、`applies`），供配置界面使用。 - `get(ns)` — 解析值；未注册时为 `undefined`。 -- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切更新。 -- 解析值是深冻结快照；每次提交后观察者收到 `(next, prev)`，观察者异常被隔离。 +- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。 +- `replace(ns, section)` — 整体替换用户分节：merge 表达不了的删除/重置路径（`replace({})` 重新继承 `base` 与 schema 默认值）。 +- 解析值是深冻结快照；每次提交后观察者收到 `(next, prev)`；观察者异常——同步抛出与异步拒绝——均被隔离。 ## Provider 契约 -子类实现 `writable`、`load()`、`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。 +子类实现 `writable`、`load()`、`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。 ## 事件 @@ -31,5 +32,5 @@ ## Known Limitations and Deferred Work - **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。 -- **跨进程并发由 provider 定义** — seam 不做跨进程串行化；并发写入者按 provider 行为收敛（本地文件 provider 为后写胜出）。 +- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 为后写胜出）。 - **无 secret 字段脱敏** — `describe()` 原样返回解析值；wire 面（RPC/UI）在暴露前必须对 `role('secret')` 字段脱敏。 diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts index bec60dfdea..10b21c2154 100644 --- a/packages/settings/settings/src/index.ts +++ b/packages/settings/settings/src/index.ts @@ -7,7 +7,6 @@ */ import { Context, Service } from 'cordis' -import { deepEqual } from 'cosmokit' import type z from 'schemastery' import type { Branded } from '@deepseek-ai/dsh-brand' @@ -59,16 +58,23 @@ export interface SettingsScope { /** Current resolved value: schema defaults, then `base`, then the user layer. */ get(): T /** - * Observe committed changes to this namespace's resolved value. + * Observe committed changes to this namespace's resolved value. A callback + * may be async; a rejection is contained and logged like a sync throw. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ - watch(callback: (next: T, prev: T) => void): () => void + watch(callback: (next: T, prev: T) => void | Promise): () => void /** * Merge a partial patch into this namespace's user layer and persist it. * @param patch - plain-object patch over the user section. */ update(patch: object): Promise + /** + * Replace this namespace's user section wholesale; absent keys re-inherit + * the composition `base` and schema defaults (`replace({})` resets all). + * @param section - the complete next user section. + */ + replace(section: object): Promise } declare module 'cordis' { @@ -91,6 +97,28 @@ declare module 'cordis' { } } +/** + * Deep equality over JSON-shaped data (objects, arrays, primitives) — the + * seam's single change-detection predicate, exported so the invariant + * companion checks exactly the implementation's relation. + * @param a - one JSON-shaped value. + * @param b - the other JSON-shaped value. + * @returns whether the two values are structurally equal. + */ +export function deepEqualJson(a: unknown, b: unknown): boolean { + if (a === b) return true + if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false + if (Array.isArray(a) || Array.isArray(b)) { + if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false + return a.every((entry, index) => deepEqualJson(entry, b[index])) + } + const left = a as Record + const right = b as Record + const keys = Object.keys(left) + if (keys.length !== Object.keys(right).length) return false + return keys.every(key => key in right && deepEqualJson(left[key], right[key])) +} + /** Whether a value is a plain data object (not an array, null, or class instance). */ function isPlainObject(value: unknown): value is Record { if (typeof value !== 'object' || value === null || Array.isArray(value)) return false @@ -128,7 +156,7 @@ interface SettingsRegistration { base: unknown applies: SettingsApplies resolved: unknown - watchers: Set<(next: never, prev: never) => void> + watchers: Set<(next: never, prev: never) => void | Promise> } /** @@ -141,11 +169,22 @@ export abstract class Settings extends Service { private readonly registrations = new Map() /** Latest published raw document; empty until the provider's first publish. */ private document: Record = {} + /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */ + private readonly writeQueues = new Map>() constructor(ctx: Context) { super(ctx, 'settings') } + /** + * Load the provider's document once and publish it before the service + * becomes injectable. Providers with their own init (watchers, connections) + * delegate here first via `yield* super[Service.init]()`. + */ + async* [Service.init](): AsyncGenerator<() => void, void, void> { + this.publish(await this.load()) + } + /** Whether {@link update} may persist through this provider. */ abstract readonly writable: boolean @@ -195,6 +234,7 @@ export abstract class Settings extends Service { return () => registration.watchers.delete(callback) }, update: patch => this.update(ns, patch), + replace: section => this.replace(ns, section), } } @@ -223,11 +263,30 @@ export abstract class Settings extends Service { /** * Merge a patch into one registered namespace's user layer, validate the * resolved candidate, persist through the provider, then commit and emit. - * A validation failure rejects before anything is persisted. + * A validation failure rejects before anything is persisted. Writes to one + * namespace are serialized: concurrent updates apply in call order, each + * merging over the previous write's committed section. * @param ns - the registered namespace to update. * @param patch - plain-object patch over the user section. */ async update(ns: SettingsNamespace, patch: object): Promise { + return this.write(ns, patch, 'merge') + } + + /** + * Replace one registered namespace's user section wholesale, validate, + * persist, then commit and emit. Keys absent from `section` fall back to the + * composition `base` and schema defaults — this is the removal/reset path a + * merge-only patch cannot express (`replace({})` re-inherits everything). + * @param ns - the registered namespace to replace. + * @param section - the complete next user section. + */ + async replace(ns: SettingsNamespace, section: object): Promise { + return this.write(ns, section, 'replace') + } + + /** Validate a write, then queue it on the namespace's serialized write chain. */ + private write(ns: SettingsNamespace, input: object, mode: 'merge' | 'replace'): Promise { const registration = this.registrations.get(ns) if (registration === undefined) { throw new Error(`settings namespace "${ns}" is not registered`) @@ -235,14 +294,23 @@ export abstract class Settings extends Service { if (!this.writable) { throw new Error(`settings provider is read-only: "${ns}" cannot be updated in-process`) } - if (!isPlainObject(patch)) { - throw new TypeError(`settings update for "${ns}" must be a plain object patch`) + if (!isPlainObject(input)) { + throw new TypeError(`settings ${mode === 'merge' ? 'update' : 'replace'} for "${ns}" must be a plain object`) } - const section = mergeLayers(this.section(ns) ?? {}, patch) as Record - const next = deepFreeze(this.resolve(registration.schema, registration.base, section)) - await this.persist(ns, section) - this.document[ns] = section - this.commit(registration, next, 'update') + const previous = this.writeQueues.get(ns) ?? Promise.resolve() + // Chain past a failed predecessor: one rejected write must not poison the + // namespace queue for every later caller. + const run = previous.catch(() => undefined).then(async () => { + const section = mode === 'merge' + ? mergeLayers(this.section(ns) ?? {}, input) as Record + : structuredClone(input) + const next = deepFreeze(this.resolve(registration.schema, registration.base, section)) + await this.persist(ns, section) + this.document[ns] = section + this.commit(registration, next, 'update') + }) + this.writeQueues.set(ns, run) + return run } /** @@ -287,17 +355,38 @@ export abstract class Settings extends Service { /** Commit a resolved value when changed: swap, notify watchers, emit the event. */ private commit(registration: SettingsRegistration, next: unknown, source: SettingsUpdateSource): void { const prev = registration.resolved - if (deepEqual(next, prev)) return + if (deepEqualJson(next, prev)) return registration.resolved = next for (const watcher of [...registration.watchers]) { try { - watcher(next as never, prev as never) + // A watcher may be async: adopt its promise so a rejection is contained + // here instead of surfacing as an unhandled rejection. + const outcome = watcher(next as never, prev as never) as unknown + if (outcome instanceof Promise) { + outcome.catch((error: unknown) => { + this.warnWatcherFailure(registration.ns, error) + }) + } } catch (error) { - this.ctx.logger.warn('settings: watcher for "%s" failed', registration.ns) - this.ctx.logger.warn(error) + this.warnWatcherFailure(registration.ns, error) } } - this.ctx.emit('settings/updated', registration.ns, next, prev, source) + try { + this.ctx.emit('settings/updated', registration.ns, next, prev, source) + } catch (error) { + // Invariant violations are harness-fatal by design; any other listener + // failure is contained so one broken observer cannot wedge the commit + // path (and, through it, a provider's reload loop). + if ((error as { code?: unknown } | null)?.code === 'INVARIANT') throw error + this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', registration.ns) + this.ctx.logger.warn(error) + } + } + + /** Contained-watcher diagnostic shared by the sync and async failure paths. */ + private warnWatcherFailure(ns: SettingsNamespace, error: unknown): void { + this.ctx.logger.warn('settings: watcher for "%s" failed', ns) + this.ctx.logger.warn(error) } } diff --git a/packages/settings/settings/src/invariant.ts b/packages/settings/settings/src/invariant.ts index 235f413aae..d8db41bce4 100644 --- a/packages/settings/settings/src/invariant.ts +++ b/packages/settings/settings/src/invariant.ts @@ -5,6 +5,7 @@ import type { Context } from 'cordis' import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' +import { deepEqualJson } from './index.ts' const PACKAGE_NAME = '@deepseek-ai/dsh-settings' @@ -15,7 +16,9 @@ export const inject = ['invariants'] /** * Install the commit-event contract: `settings/updated` fires only for a - * currently registered namespace and only when the resolved value changed. + * currently registered namespace, only when the resolved value changed, and + * only with the service's authoritative resolved value — all judged with the + * seam's own equality predicate. */ const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => { ctx.on('settings/updated', (ns, next, prev) => { @@ -23,10 +26,14 @@ const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => { if (settings === undefined) { fail(`settings/updated for "${ns}" emitted without a live settings service`) } - if (settings.get(ns) === undefined) { + const current = settings.get(ns) + if (current === undefined) { fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`) } - if (JSON.stringify(next) === JSON.stringify(prev)) { + if (!deepEqualJson(current, next)) { + fail(`settings/updated for "${ns}" does not match the authoritative resolved value`) + } + if (deepEqualJson(next, prev)) { fail(`settings/updated for "${ns}" emitted without a resolved-value change`) } }) diff --git a/packages/settings/settings/tests/invariant.spec.ts b/packages/settings/settings/tests/invariant.spec.ts index f12ff6126c..0976827368 100644 --- a/packages/settings/settings/tests/invariant.spec.ts +++ b/packages/settings/settings/tests/invariant.spec.ts @@ -38,4 +38,15 @@ describe('settings invariants', () => { ctx.emit('settings/updated', settingsNamespace('ui-theme'), { theme: 'dark' }, { theme: 'dark' }, 'update') }).toThrow(/without a resolved-value change/) }) + + it('fails a settings/updated emission whose value diverges from the authoritative state', async () => { + const ctx = await setup(true) + ctx.settings.register(settingsNamespace('ui-theme'), z.object({ + theme: z.string().default('dark'), + })) + // Fabricated next ≠ the service's current resolved value ({theme: 'dark'}). + expect(() => { + ctx.emit('settings/updated', settingsNamespace('ui-theme'), { theme: 'forged' }, { theme: 'dark' }, 'update') + }).toThrow(/authoritative/) + }) }) diff --git a/packages/settings/settings/tests/memory.ts b/packages/settings/settings/tests/memory.ts index 0b20771cbe..bb310c939d 100644 --- a/packages/settings/settings/tests/memory.ts +++ b/packages/settings/settings/tests/memory.ts @@ -5,7 +5,6 @@ * packages. */ -import { Service } from 'cordis' import { Settings, type SettingsNamespace } from '../src/index.ts' /** In-memory provider exposing the protected seam hooks to tests. */ @@ -17,13 +16,18 @@ export class MemorySettings extends Settings { /** When false, update() must reject before reaching persist(). */ writableFlag: boolean + /** Artificial persist latency so tests can interleave concurrent updates. */ + persistDelayMs: number + constructor(ctx: ConstructorParameters[0], options?: { doc?: Record writable?: boolean + persistDelayMs?: number }) { super(ctx) this.doc = structuredClone(options?.doc ?? {}) this.writableFlag = options?.writable ?? true + this.persistDelayMs = options?.persistDelayMs ?? 0 } get writable(): boolean { @@ -34,10 +38,12 @@ export class MemorySettings extends Settings { return Promise.resolve(structuredClone(this.doc)) } - protected persist(ns: SettingsNamespace, section: Record): Promise { + protected async persist(ns: SettingsNamespace, section: Record): Promise { + if (this.persistDelayMs > 0) { + await new Promise(resolve => setTimeout(resolve, this.persistDelayMs)) + } this.persisted.push({ ns, section: structuredClone(section) }) this.doc[ns] = structuredClone(section) - return Promise.resolve() } /** Simulate an external storage change reaching the provider. */ @@ -45,9 +51,4 @@ export class MemorySettings extends Settings { this.doc = structuredClone(doc) this.publish(structuredClone(doc)) } - - async* [Service.init](): AsyncGenerator<() => void, void, void> { - this.publish(await this.load()) - yield () => { this.persisted.length = 0 } - } } diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts index a3d223c3f7..c413e948ed 100644 --- a/packages/settings/settings/tests/settings.spec.ts +++ b/packages/settings/settings/tests/settings.spec.ts @@ -1,9 +1,32 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import z from 'schemastery' -import { settingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts' +import { Settings, deepEqualJson, settingsNamespace, type SettingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts' import { MemorySettings } from './memory.ts' +/** A provider implementing only the three primitives: the seam owns init. */ +class BareProvider extends Settings { + doc: Record + + constructor(ctx: ConstructorParameters[0], options?: { doc?: Record }) { + super(ctx) + this.doc = structuredClone(options?.doc ?? {}) + } + + get writable(): boolean { + return true + } + + protected load(): Promise> { + return Promise.resolve(structuredClone(this.doc)) + } + + protected persist(ns: SettingsNamespace, section: Record): Promise { + this.doc[ns] = structuredClone(section) + return Promise.resolve() + } +} + interface ThemeConfig { theme: 'dark' | 'light' fontSize: number @@ -119,7 +142,7 @@ describe('registration', () => { inject: ['settings'], apply: (child: Context) => { scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema) - scope.watch(next => seen.push(next)) + scope.watch((next) => { seen.push(next) }) }, }) await fiber @@ -191,6 +214,9 @@ describe('update', () => { expect(provider.persisted).toEqual([]) expect(events).toEqual([]) expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 }) + // The failed write must not poison the namespace queue for later writers. + await scope.update({ fontSize: 18 }) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 }) }) it('ignores explicit undefined entries so a sparse patch cannot erase keys', async () => { @@ -206,6 +232,7 @@ describe('update', () => { const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) await expect(scope.update([1])).rejects.toThrow(TypeError) await expect(scope.update(new Date() as unknown as object)).rejects.toThrow(TypeError) + await expect(scope.replace([1])).rejects.toThrow(/replace for "ui-theme"/) }) it('accepts a null-prototype patch object', async () => { @@ -231,6 +258,89 @@ describe('update', () => { }) }) +describe('deepEqualJson', () => { + it.each([ + [{ a: [1, 2] }, { a: [1, 2] }, true], + [{ a: [1, 2] }, { a: [1] }, false], + [{ a: [1] }, { a: { 0: 1 } }, false], + [{ a: 1 }, { b: 1 }, false], + [{ a: 1 }, {}, false], + [{ a: null }, { a: null }, true], + [{ a: null }, { a: {} }, false], + ])('compares %j vs %j as %s', (a, b, equal) => { + expect(deepEqualJson(a, b)).toBe(equal) + }) +}) + +describe('review regressions', () => { + it('propagates an invariant-coded listener failure instead of containing it', async () => { + const { ctx, provider } = await boot() + ctx.on('settings/updated', () => { + throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' }) + }) + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(() => { provider.pushExternal({ 'ui-theme': { theme: 'light' } }) }) + .toThrow(/forged relation/) + }) + + it('serializes concurrent updates so neither patch is lost', async () => { + const { ctx, provider } = await boot({ persistDelayMs: 10 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await Promise.all([ + scope.update({ theme: 'light' }), + scope.update({ fontSize: 20 }), + ]) + expect(provider.doc['ui-theme']).toEqual({ theme: 'light', fontSize: 20 }) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 20 }) + }) + + it('contains a throwing settings/updated listener and keeps later commits alive', async () => { + const { ctx, provider } = await boot() + ctx.on('settings/updated', () => { + throw new Error('listener boom') + }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(() => { provider.pushExternal({ 'ui-theme': { theme: 'light' } }) }).not.toThrow() + expect(scope.get().theme).toBe('light') + provider.pushExternal({ 'ui-theme': { theme: 'dark' } }) + expect(scope.get().theme).toBe('dark') + }) + + it('contains an async watcher rejection', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + scope.watch(async () => { + throw new Error('async watcher boom') + }) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(scope.get().theme).toBe('light') + // Give the rejected watcher promise a microtask turn; containment means + // vitest observes no unhandled rejection out of this test. + await new Promise(resolve => setTimeout(resolve, 10)) + }) + + it('loads the provider document through the base init without provider boilerplate', async () => { + const ctx = new Context() + await ctx.plugin(BareProvider, { doc: { 'ui-theme': { fontSize: 7 } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 7 }) + }) + + it('replaces the user section wholesale so overrides can be removed', async () => { + const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light', fontSize: 20 } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { fontSize: 16 }, + }) + await scope.replace({ theme: 'light' }) + // fontSize override is gone: resolution falls back to the base layer. + expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 }) + expect(provider.doc['ui-theme']).toEqual({ theme: 'light' }) + await scope.replace({}) + expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 }) + expect(provider.doc['ui-theme']).toEqual({}) + }) +}) + describe('publish', () => { it('notifies watchers of an external change with source provider', async () => { const { ctx, provider } = await boot() diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index b7df3dc622..971576f35f 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -189,6 +189,11 @@ export const LINK_MAP: Record = { ToolRegistry: 'tools.md', ToolRestriction: 'tools.md', ToolSchema: 'tools.md', + SettingsNamespace: 'settings.md', + SettingsRegisterOptions: 'settings.md', + SettingsScope: 'settings.md', + SettingsDescriptor: 'settings.md', + SettingsUpdateSource: 'settings.md', AskUserQuestionAnswer: 'user-interaction.md', AskUserQuestionRequest: 'user-interaction.md', UserInteractionProvider: 'user-interaction.md', @@ -217,11 +222,6 @@ const FOUNDATION_TYPE_NAMES = new Set([ /** Project types deliberately documented outside the core-data catalog. */ const TYPE_LINK_EXEMPTIONS: Readonly> = { AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md', - SettingsNamespace: 'settings seam vocabulary is owned by packages/settings/settings/README.md', - SettingsUpdateSource: 'settings seam vocabulary is owned by packages/settings/settings/README.md', - SettingsRegisterOptions: 'settings seam vocabulary is owned by packages/settings/settings/README.md', - SettingsScope: 'settings seam vocabulary is owned by packages/settings/settings/README.md', - SettingsDescriptor: 'settings seam vocabulary is owned by packages/settings/settings/README.md', z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)', BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts', InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts', diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts index e6cc11ae6e..28f854fe9b 100644 --- a/scripts/project-doc-site.spec.ts +++ b/scripts/project-doc-site.spec.ts @@ -197,7 +197,7 @@ describe('docsPages locale routes', () => { const translated = rootPages.filter(page => page.contentLocale === 'zh-CN') const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US') - expect(translated).toHaveLength(18) + expect(translated).toHaveLength(19) expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true) expect(fallbacks.map(page => page.source).sort()).toEqual([ 'docs/core-data-structures/commands.md', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index b607995003..7bd9c09177 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1308,6 +1308,36 @@ "doc": "docs/core-data-structures/subprocess.md", "symbol": "SubprocessCollectedOutputs", "source": "packages/subprocess/subprocess/src/types.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsNamespace", + "source": "packages/settings/settings/src/index.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsRegisterOptions", + "source": "packages/settings/settings/src/index.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsApplies", + "source": "packages/settings/settings/src/index.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsScope", + "source": "packages/settings/settings/src/index.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsDescriptor", + "source": "packages/settings/settings/src/index.ts" + }, + { + "doc": "docs/core-data-structures/settings.md", + "symbol": "SettingsUpdateSource", + "source": "packages/settings/settings/src/index.ts" } ] } diff --git a/website/docs.ts b/website/docs.ts index 1888cd908c..cbc8d9e627 100644 --- a/website/docs.ts +++ b/website/docs.ts @@ -256,6 +256,7 @@ const coreDataReference = pairedPages(([ ['sandbox.md', '沙箱', 'Sandboxing', 18], ['web.md', 'Web 访问', 'Web access', 19], ['persistence.md', '会话持久化', 'Session persistence', 20], + ['settings.md', '用户设置', 'User settings', 21], ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({ source: `docs/core-data-structures/${file}`, route: `reference/core-data-structures/${file}`, From 1010291fe6cd764deff8e5e3056bb57f94c3fa4f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 29 Jul 2026 10:07:28 +0800 Subject: [PATCH 10/67] fix(settings): close cross-namespace, dispatch, and lifecycle races from second review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Confirmed and fixed, each with a regression test that failed first: - Concurrent writes to different namespaces lost whole sections on disk (each persist rendered the full document from a stale text): the local provider serializes render->write->rename->text-commit on one internal persist chain shared by every namespace queue. - One throwing settings/updated listener starved the rest (cordis emit stops at the first throw): commit fans out per listener via events.dispatch, contains individual failures, and rethrows the first INVARIANT-coded error only after every listener ran. - Write queues ignored fiber/service lifecycle: the base init now registers a teardown that refuses new writes and drains queued chains; queued tasks re-verify service liveness and namespace ownership before running and again before committing, so a registrant disposed mid-flight is never notified and a disposed service never commits. - Async watcher invocations could interleave (a slow stale call applied last): each watcher carries a serialized invocation chain — one call at a time, in commit order; JSDoc/doc pages state the async timing. - update/replace borrowed the caller's object until the queued task ran: inputs are structured-clone snapshotted at call time; non-cloneable plain objects reject with a typed error. - Composition guard now proves the documented fallback: the consumer uses the optional scoped-inject shape and boots both with the settings entry (hot publish) and without it (entry-config resolution, no scope). - core-data-structures index: settings.md row added to the sub-page table in core.md/core.zh.md. Both packages hold per-file 100% coverage across repeated runs. --- docs/cordis-catalog/events.md | 2 +- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/core.i18n.yaml | 4 +- docs/core-data-structures/core.md | 1 + docs/core-data-structures/core.zh.md | 1 + docs/core-data-structures/settings.i18n.yaml | 4 +- docs/core-data-structures/settings.md | 5 +- docs/core-data-structures/settings.zh.md | 5 +- docs/event-producer-consumer.md | 2 +- .../settings/settings-local/README.i18n.yaml | 4 +- packages/settings/settings-local/README.md | 1 + packages/settings/settings-local/README.zh.md | 1 + packages/settings/settings-local/src/index.ts | 14 +- .../tests/loader-composition.spec.ts | 63 +++++-- .../settings-local/tests/local.spec.ts | 20 +++ packages/settings/settings/README.i18n.yaml | 4 +- packages/settings/settings/README.md | 3 +- packages/settings/settings/README.zh.md | 3 +- packages/settings/settings/src/index.ts | 114 +++++++++---- .../settings/settings/tests/settings.spec.ts | 157 +++++++++++++++++- 20 files changed, 339 insertions(+), 71 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 74e1e6cfda..44fcc62e88 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -662,7 +662,7 @@ Committed change to one registered namespace's resolved value. Emitted after the Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:96`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:97`](../../packages/settings/settings/src/index.ts) ## `slash/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index e915952ffb..c2e5451699 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1442,7 +1442,7 @@ async replace(ns: SettingsNamespace, section: object): Promise Types: [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:168`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:176`](../../packages/settings/settings/src/index.ts) ## `ctx.skills` — `SkillService` diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index f0d078c123..d0bdbc5dd2 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/core.md -core.md: 647c7f273183e0890ef191d98ab009ad129db572 -core.zh.md: 8b0f439f09a6e6609dbe69c3056aa74d553a0943 +core.md: ca8426e6fbece18a277cc31f5e86d3058b3feb32 +core.zh.md: 6b297ca233428d38dbe022e58344e98fab7a15ad diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 647c7f2731..ca8426e6fb 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 | [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views | | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events | | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` | +| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits | | [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages | | [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract | | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly | diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 8b0f439f09..6b297ca233 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -24,6 +24,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数 | [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 | | [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 | | [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` | +| [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 | | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 | | [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 | | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 | diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/core-data-structures/settings.i18n.yaml index 6dc8750dfb..cca43c251b 100644 --- a/docs/core-data-structures/settings.i18n.yaml +++ b/docs/core-data-structures/settings.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/settings.md -settings.md: 851087065c627f2390041dd6e69273e31be3917d -settings.zh.md: 955c4fbf7c147b3d0a8be62c33c031d7bd2c4ba2 +settings.md: abbfecb35f67b27e16dffb9558a35cf368c90beb +settings.zh.md: c746e3cc181f8347cbe634b9231cfee1b3beecd3 diff --git a/docs/core-data-structures/settings.md b/docs/core-data-structures/settings.md index 851087065c..abbfecb35f 100644 --- a/docs/core-data-structures/settings.md +++ b/docs/core-data-structures/settings.md @@ -46,8 +46,9 @@ interface SettingsScope { /** Current resolved value: schema defaults, then `base`, then the user layer. */ get(): T /** - * Observe committed changes to this namespace's resolved value. A callback - * may be async; a rejection is contained and logged like a sync throw. + * Observe committed changes to this namespace's resolved value. Invocations + * of one callback run asynchronously, one at a time, in commit order; a + * rejection is contained and logged like a sync throw. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ diff --git a/docs/core-data-structures/settings.zh.md b/docs/core-data-structures/settings.zh.md index 955c4fbf7c..c746e3cc18 100644 --- a/docs/core-data-structures/settings.zh.md +++ b/docs/core-data-structures/settings.zh.md @@ -46,8 +46,9 @@ interface SettingsScope { /** Current resolved value: schema defaults, then `base`, then the user layer. */ get(): T /** - * Observe committed changes to this namespace's resolved value. A callback - * may be async; a rejection is contained and logged like a sync throw. + * Observe committed changes to this namespace's resolved value. Invocations + * of one callback run asynchronously, one at a time, in commit order; a + * rejection is contained and logged like a sync throw. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index e3eb1d9435..74645a1674 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -35,7 +35,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:80`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:92`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:102`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | -| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:96`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`emit`) | [`settings`](../packages/settings/settings) | +| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:97`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | | `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:230`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:244`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | | `slash/input-insert-reference` | `bail` | [`packages/client/ui-slash/src/types.ts:237`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` | diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml index 455255941a..5d44f50f9d 100644 --- a/packages/settings/settings-local/README.i18n.yaml +++ b/packages/settings/settings-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings-local/README.md -README.md: 9d0aa3982507ca16b382aaa918ca1536a98e29ea -README.zh.md: 075de7ee5b3e0ef0a4ee27eeb8cb098ca0d73456 +README.md: af8df7c030757b330e034a1c46507fbe75c9bab8 +README.zh.md: fc8943263b339baad1a92a1d0b0977b926e40f6e diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md index 9d0aa39825..af8df7c030 100644 --- a/packages/settings/settings-local/README.md +++ b/packages/settings/settings-local/README.md @@ -19,6 +19,7 @@ Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension - **Boot fails loud, reload keeps last-good.** An existing-but-invalid document fails plugin load; once live, an unreadable or unparsable edit warns and keeps the last good sections. A missing document resolves every namespace from defaults and `base`; deleting it publishes the same empty state. - **Write-back is atomic, owner-only, and symlink-proof.** `persist` exclusive-creates a random-suffix temp sibling with mode `0600` (`wx` refuses to follow a planted symlink) and renames over the target, cleaning the temp up on failure. YAML writes patch one namespace in the comment-preserving document; JSON re-serializes. +- **Cross-namespace writes serialize on one document.** Every namespace shares the file, so persists from different namespace queues chain internally; each render sees the text the previous write committed. - **Dispose quiesces.** Teardown stops accepting watcher events, closes the watcher, then waits out any queued or in-flight reload, so nothing publishes after disposal. - **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op. diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md index 075de7ee5b..fc8943263b 100644 --- a/packages/settings/settings-local/README.zh.md +++ b/packages/settings/settings-local/README.zh.md @@ -19,6 +19,7 @@ - **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。 - **写回原子、仅属主可读、抗符号链接。** `persist` 以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。YAML 写回在保留注释的文档里只修补目标 namespace；JSON 重新序列化。 +- **跨 namespace 写入在同一文档上串行。** 所有 namespace 共享一个文件，来自不同 namespace 队列的 persist 在内部串联；每次渲染都基于上一次写入提交后的文本。 - **Dispose 保证静止。** 卸载先停止接收 watcher 事件、关闭 watcher，再等完排队与进行中的重载，之后不再有任何发布。 - **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。 diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts index 2c020da63c..b305f61fe7 100644 --- a/packages/settings/settings-local/src/index.ts +++ b/packages/settings/settings-local/src/index.ts @@ -87,6 +87,8 @@ export class SettingsLocal extends Settings { private text: string | undefined /** Serializes watcher-triggered reloads so reads never interleave. */ private refreshTask: Promise = Promise.resolve() + /** Serializes whole-document writes across namespace queues; settled tail. */ + private persistChain: Promise = Promise.resolve() /** Set at dispose: refuse new watcher events and let in-flight work no-op. */ private closed = false @@ -121,7 +123,17 @@ export class SettingsLocal extends Settings { return doc } - protected async persist(ns: SettingsNamespace, section: Record): Promise { + protected persist(ns: SettingsNamespace, section: Record): Promise { + // One document backs every namespace, so writes from different namespace + // queues must serialize here: each render must see the text the previous + // write committed, or the loser's section silently vanishes from disk. + // The stored tail is settled on both outcomes, so chaining needs no catch. + const task = this.persistChain.then(() => this.persistSection(ns, section)) + this.persistChain = task.then(() => undefined, () => undefined) + return task + } + + private async persistSection(ns: SettingsNamespace, section: Record): Promise { const output = this.spec.format === 'yaml' ? this.renderYaml(ns, section) : this.renderJson(ns, section) diff --git a/packages/settings/settings-local/tests/loader-composition.spec.ts b/packages/settings/settings-local/tests/loader-composition.spec.ts index d584c11899..c7cea89e41 100644 --- a/packages/settings/settings-local/tests/loader-composition.spec.ts +++ b/packages/settings/settings-local/tests/loader-composition.spec.ts @@ -1,7 +1,9 @@ /** * Real-composition guard: the provider and a consumer plugin boot from a - * test-only cordis.yml through the actual Loader + Include path, and an - * external edit of settings.yaml hot-publishes into the consumer's scope. + * test-only cordis.yml through the actual Loader + Include path, an external + * edit of settings.yaml hot-publishes into the consumer's scope, and the same + * consumer booted WITHOUT a settings entry keeps its entry-config resolution — + * the documented optional-inject fallback. */ import { mkdtemp, rm, writeFile } from 'node:fs/promises' @@ -39,33 +41,50 @@ afterEach(async () => { interface ConsumerState { scope: SettingsScope | undefined seen: ThemeConfig[] + /** What the consumer is actually running with, settings or not. */ + applied: ThemeConfig | undefined } -async function loadComposition(): Promise<{ ctx: Context; state: ConsumerState; settingsPath: string }> { +async function loadComposition( + options?: { withSettings?: boolean }, +): Promise<{ ctx: Context; state: ConsumerState; settingsPath: string }> { + const withSettings = options?.withSettings ?? true root = await mkdtemp(join(tmpdir(), 'dsh-settings-composition-')) const settingsPath = join(root, 'settings.yaml') await writeFile(settingsPath, 'ui-theme:\n theme: light\n') - const state: ConsumerState = { scope: undefined, seen: [] } + const state: ConsumerState = { scope: undefined, seen: [], applied: undefined } const consumer = { name: 'settings-consumer', - inject: ['settings'], apply: (ctx: Context) => { - const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { - base: { fontSize: 16 }, + // The documented consumer shape: no hard dependency — entry config alone + // is the running state, and the scoped inject overlays the user layer + // only while a settings service exists. + const base: Partial = { fontSize: 16 } + state.applied = ThemeSchema(base as ThemeConfig) + ctx.inject(['settings'], (child: Context) => { + const scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { base }) + state.scope = scope + state.applied = scope.get() + scope.watch((next) => { + state.seen.push(next) + state.applied = next + }) }) - state.scope = scope - scope.watch((next) => { state.seen.push(next) }) }, } const configPath = join(root, 'cordis.yml') await writeFile(configPath, [ - '- id: settings', - " name: '@deepseek-ai/dsh-settings-local'", - ' config:', - ` path: ${JSON.stringify(settingsPath)}`, - ' debounceMs: 10', + ...withSettings + ? [ + '- id: settings', + " name: '@deepseek-ai/dsh-settings-local'", + ' config:', + ` path: ${JSON.stringify(settingsPath)}`, + ' debounceMs: 10', + ] + : [], '- id: consumer', ' name: test-settings-consumer', '', @@ -100,7 +119,9 @@ describe('settings-local real composition', () => { const { ctx, state, settingsPath } = await loadComposition() // Composition resolution: user layer over the consumer's composition base. - expect(state.scope!.get()).toEqual({ theme: 'light', fontSize: 16 }) + await vi.waitFor(() => { + expect(state.scope!.get()).toEqual({ theme: 'light', fontSize: 16 }) + }) expect(ctx.get('settings')!.describe().map(entry => entry.ns)).toEqual(['ui-theme']) await writeFile(settingsPath, 'ui-theme:\n theme: dark\n fontSize: 20\n') @@ -109,4 +130,16 @@ describe('settings-local real composition', () => { }, { timeout: 5000 }) expect(state.seen.at(-1)).toEqual({ theme: 'dark', fontSize: 20 }) }) + + it('boots the same consumer without a settings entry and keeps entry-config resolution', async () => { + const { ctx, state } = await loadComposition({ withSettings: false }) + + // No settings service anywhere in the composition… + expect(ctx.get('settings')).toBeUndefined() + // …so the consumer runs on schema defaults plus its composition base, and + // never receives a scope. + expect(state.applied).toEqual({ theme: 'dark', fontSize: 16 }) + expect(state.scope).toBeUndefined() + expect(state.seen).toEqual([]) + }) }) diff --git a/packages/settings/settings-local/tests/local.spec.ts b/packages/settings/settings-local/tests/local.spec.ts index 1c74429153..4c3c24ccd9 100644 --- a/packages/settings/settings-local/tests/local.spec.ts +++ b/packages/settings/settings-local/tests/local.spec.ts @@ -146,6 +146,23 @@ describe('persist', () => { expect((await readdir(dir)).sort()).toEqual(['settings.yaml']) }) + it('serializes cross-namespace writes into one on-disk document', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const alpha = ctx.settings.register(settingsNamespace('alpha'), ThemeSchema) + const beta = ctx.settings.register(settingsNamespace('beta'), ThemeSchema) + await Promise.all([ + alpha.update({ theme: 'light' }), + beta.update({ fontSize: 20 }), + ]) + const text = await readFile(path, 'utf8') + expect(text).toContain('alpha:') + expect(text).toContain('beta:') + expect(alpha.get().theme).toBe('light') + expect(beta.get().fontSize).toBe(20) + }) + it('never follows a planted symlink at a temp path and never leaves the document a symlink', async () => { const dir = await tempDir() const path = join(dir, 'settings.yaml') @@ -209,6 +226,9 @@ describe('persist', () => { await chmod(dir, 0o700) expect((await readdir(dir)).sort()).toEqual(['settings.yaml']) expect(scope.get().theme).toBe('light') + // The failed persist must not poison the document write chain. + await scope.update({ theme: 'dark' }) + expect(scope.get().theme).toBe('dark') }) it('round-trips a json document', async () => { diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml index 6f5e5c6beb..63a274dd4d 100644 --- a/packages/settings/settings/README.i18n.yaml +++ b/packages/settings/settings/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings/README.md -README.md: f7858a247f6011cd0654a73b5325d81c118441e5 -README.zh.md: 67ecba695066389bfe3a69f517d52f91b48b6c75 +README.md: ff6cdeb57a265dbaa9d5f50de1d558f1e3cb581f +README.zh.md: d820a5c1fa804455c439f1a155e7628f5118a49b diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md index f7858a247f..ff6cdeb57a 100644 --- a/packages/settings/settings/README.md +++ b/packages/settings/settings/README.md @@ -11,7 +11,8 @@ Abstract user-settings seam (`ctx.settings`). One provider holds a raw document - `get(ns)` — resolved value, `undefined` while unregistered. - `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every write. Writes to one namespace are serialized in call order. - `replace(ns, section)` — sets the user section wholesale: the removal/reset path a merge cannot express (`replace({})` re-inherits `base` and schema defaults). -- Resolved values are deep-frozen snapshots; watchers receive `(next, prev)` after each commit, and watcher failures — sync throws and async rejections alike — are contained. +- Resolved values are deep-frozen snapshots. Watchers receive `(next, prev)` after each commit: invocations of one callback run asynchronously, one at a time, in commit order (a slow stale invocation can never apply after a newer one), and failures — sync throws and async rejections alike — are contained. The `settings/updated` event fans out one listener at a time, so one throwing listener cannot starve the rest. +- Service teardown refuses new writes and drains every queued write before disposal completes; a write whose registrant fiber was disposed mid-flight still reaches storage but commits and notifies nobody. ## Provider contract diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md index 67ecba6950..d820a5c1fa 100644 --- a/packages/settings/settings/README.zh.md +++ b/packages/settings/settings/README.zh.md @@ -11,7 +11,8 @@ - `get(ns)` — 解析值；未注册时为 `undefined`。 - `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。 - `replace(ns, section)` — 整体替换用户分节：merge 表达不了的删除/重置路径（`replace({})` 重新继承 `base` 与 schema 默认值）。 -- 解析值是深冻结快照；每次提交后观察者收到 `(next, prev)`；观察者异常——同步抛出与异步拒绝——均被隔离。 +- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener。 +- 服务卸载先拒绝新写入并排干全部排队写入后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。 ## Provider 契约 diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts index 10b21c2154..a7e9366048 100644 --- a/packages/settings/settings/src/index.ts +++ b/packages/settings/settings/src/index.ts @@ -58,8 +58,9 @@ export interface SettingsScope { /** Current resolved value: schema defaults, then `base`, then the user layer. */ get(): T /** - * Observe committed changes to this namespace's resolved value. A callback - * may be async; a rejection is contained and logged like a sync throw. + * Observe committed changes to this namespace's resolved value. Invocations + * of one callback run asynchronously, one at a time, in commit order; a + * rejection is contained and logged like a sync throw. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ @@ -149,6 +150,13 @@ function deepFreeze(value: T): T { return Object.freeze(value) } +/** One registered watcher and its serialized invocation chain. */ +interface SettingsWatcher { + callback: (next: never, prev: never) => void | Promise + /** Settled tail: invocations of this callback run one at a time, in commit order. */ + tail: Promise +} + /** One live namespace registration owned by a registrant fiber. */ interface SettingsRegistration { ns: SettingsNamespace @@ -156,7 +164,7 @@ interface SettingsRegistration { base: unknown applies: SettingsApplies resolved: unknown - watchers: Set<(next: never, prev: never) => void | Promise> + watchers: Set } /** @@ -171,6 +179,13 @@ export abstract class Settings extends Service { private document: Record = {} /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */ private readonly writeQueues = new Map>() + /** Set at service dispose: refuse new writes while queued ones drain. */ + private stopped = false + + /** Opaque read of {@link stopped}: control flow cannot narrow it across awaits. */ + private isStopped(): boolean { + return this.stopped + } constructor(ctx: Context) { super(ctx, 'settings') @@ -178,10 +193,17 @@ export abstract class Settings extends Service { /** * Load the provider's document once and publish it before the service - * becomes injectable. Providers with their own init (watchers, connections) - * delegate here first via `yield* super[Service.init]()`. + * becomes injectable, and register the write-drain teardown. Providers with + * their own init (watchers, connections) delegate here first via + * `yield* super[Service.init]()`; their disposers then run before the drain. */ - async* [Service.init](): AsyncGenerator<() => void, void, void> { + async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { + yield async () => { + // Teardown: refuse new writes, then wait until every queued write chain + // settles so disposal completes only once storage is quiescent. + this.stopped = true + await Promise.allSettled([...this.writeQueues.values()]) + } this.publish(await this.load()) } @@ -230,8 +252,9 @@ export abstract class Settings extends Service { return { get: () => registration.resolved as T, watch: (callback) => { - registration.watchers.add(callback) - return () => registration.watchers.delete(callback) + const watcher: SettingsWatcher = { callback: callback, tail: Promise.resolve() } + registration.watchers.add(watcher) + return () => registration.watchers.delete(watcher) }, update: patch => this.update(ns, patch), replace: section => this.replace(ns, section), @@ -287,27 +310,50 @@ export abstract class Settings extends Service { /** Validate a write, then queue it on the namespace's serialized write chain. */ private write(ns: SettingsNamespace, input: object, mode: 'merge' | 'replace'): Promise { + const verb = mode === 'merge' ? 'update' : 'replace' const registration = this.registrations.get(ns) if (registration === undefined) { throw new Error(`settings namespace "${ns}" is not registered`) } + if (this.isStopped()) { + throw new Error(`settings service is disposed: "${ns}" cannot be written`) + } if (!this.writable) { throw new Error(`settings provider is read-only: "${ns}" cannot be updated in-process`) } if (!isPlainObject(input)) { - throw new TypeError(`settings ${mode === 'merge' ? 'update' : 'replace'} for "${ns}" must be a plain object`) + throw new TypeError(`settings ${verb} for "${ns}" must be a plain object`) + } + // Snapshot at call time: the queue must never read a caller-owned object + // the caller may keep mutating while the write waits its turn. + let snapshot: Record + try { + snapshot = structuredClone(input) + } catch { + throw new TypeError(`settings ${verb} for "${ns}" must be JSON-shaped (structured-cloneable) data`) } const previous = this.writeQueues.get(ns) ?? Promise.resolve() // Chain past a failed predecessor: one rejected write must not poison the // namespace queue for every later caller. const run = previous.catch(() => undefined).then(async () => { + if (this.isStopped()) { + throw new Error(`settings service was disposed before the queued "${ns}" ${verb} ran`) + } + if (this.registrations.get(ns) !== registration) { + throw new Error(`settings namespace "${ns}" registration was disposed before the queued ${verb} ran`) + } const section = mode === 'merge' - ? mergeLayers(this.section(ns) ?? {}, input) as Record - : structuredClone(input) + ? mergeLayers(this.section(ns) ?? {}, snapshot) as Record + : snapshot const next = deepFreeze(this.resolve(registration.schema, registration.base, section)) await this.persist(ns, section) + // The write reached storage either way; the cache must say so. Commit + // only when this registration is still the namespace owner — a fiber + // disposed (or replaced) mid-persist must not receive the notification. this.document[ns] = section - this.commit(registration, next, 'update') + if (this.registrations.get(ns) === registration && !this.isStopped()) { + this.commit(registration, next, 'update') + } }) this.writeQueues.set(ns, run) return run @@ -358,29 +404,35 @@ export abstract class Settings extends Service { if (deepEqualJson(next, prev)) return registration.resolved = next for (const watcher of [...registration.watchers]) { + // Serialize per watcher: invocations of one callback run one at a time + // in commit order, so a slow stale invocation can never apply after a + // newer one. Sync throws and async rejections land in the same handler. + watcher.tail = watcher.tail + .then(() => watcher.callback(next as never, prev as never)) + .then(() => undefined, (error: unknown) => { + this.warnWatcherFailure(registration.ns, error) + }) + } + // Fan the event out one listener at a time (the plain emit stops at the + // first throwing listener, starving the rest). Invariant violations are + // harness-fatal by design and rethrow after every listener ran; any other + // failure is contained so one broken observer cannot wedge the commit + // path (and, through it, a provider's reload loop). + let invariantFailure: unknown + const args = ['settings/updated', registration.ns, next, prev, source] + for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) { try { - // A watcher may be async: adopt its promise so a rejection is contained - // here instead of surfacing as an unhandled rejection. - const outcome = watcher(next as never, prev as never) as unknown - if (outcome instanceof Promise) { - outcome.catch((error: unknown) => { - this.warnWatcherFailure(registration.ns, error) - }) - } + listener(registration.ns, next, prev, source) } catch (error) { - this.warnWatcherFailure(registration.ns, error) + if ((error as { code?: unknown } | null)?.code === 'INVARIANT') { + invariantFailure ??= error + continue + } + this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', registration.ns) + this.ctx.logger.warn(error) } } - try { - this.ctx.emit('settings/updated', registration.ns, next, prev, source) - } catch (error) { - // Invariant violations are harness-fatal by design; any other listener - // failure is contained so one broken observer cannot wedge the commit - // path (and, through it, a provider's reload loop). - if ((error as { code?: unknown } | null)?.code === 'INVARIANT') throw error - this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', registration.ns) - this.ctx.logger.warn(error) - } + if (invariantFailure !== undefined) throw invariantFailure as Error } /** Contained-watcher diagnostic shared by the sync and async failure paths. */ diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts index c413e948ed..a989d9a5cc 100644 --- a/packages/settings/settings/tests/settings.spec.ts +++ b/packages/settings/settings/tests/settings.spec.ts @@ -52,9 +52,10 @@ const NestedSchema: z = z.object({ async function boot(options?: ConstructorParameters[1]) { const ctx = new Context() - await ctx.plugin(MemorySettings, options) + const fiber = ctx.plugin(MemorySettings, options) + await fiber const provider = ctx.get('settings') as MemorySettings - return { ctx, provider } + return { ctx, provider, fiber } } /** Record every settings/updated emission. */ @@ -341,6 +342,144 @@ describe('review regressions', () => { }) }) +describe('second review regressions', () => { + it('runs every settings/updated listener even when an earlier one throws', async () => { + const { ctx, provider } = await boot() + ctx.on('settings/updated', () => { + throw new Error('first listener boom') + }) + const second = vi.fn() + ctx.on('settings/updated', second) + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(second).toHaveBeenCalledTimes(1) + }) + + it('rejects an update queued after the registrant fiber disposed', async () => { + const { ctx } = await boot() + let scope: SettingsScope | undefined + const fiber = ctx.plugin({ + inject: ['settings'], + apply: (child: Context) => { + scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + }, + }) + await fiber + await fiber.dispose() + await expect(scope!.update({ theme: 'light' })).rejects.toThrow(/disposed|not registered/) + }) + + it('does not notify a registrant disposed while its update was in flight', async () => { + const { ctx, provider } = await boot({ persistDelayMs: 30 }) + const events = recordUpdates(ctx) + let scope: SettingsScope | undefined + const watcher = vi.fn() + const fiber = ctx.plugin({ + inject: ['settings'], + apply: (child: Context) => { + scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + scope.watch(watcher) + }, + }) + await fiber + const pending = scope!.update({ theme: 'light' }) + await new Promise(resolve => setTimeout(resolve, 5)) + await fiber.dispose() + await pending.catch(() => undefined) + await new Promise(resolve => setTimeout(resolve, 10)) + expect(watcher).not.toHaveBeenCalled() + expect(events).toEqual([]) + // The persist was already in flight, so storage keeps the write — but no + // commit reached the disposed registration. + expect(provider.doc['ui-theme']).toEqual({ theme: 'light' }) + }) + + it('drains in-flight writes at service dispose and rejects later ones', async () => { + const { ctx, provider, fiber } = await boot({ persistDelayMs: 20 }) + const service = ctx.settings + const scope = service.register(settingsNamespace('ui-theme'), ThemeSchema) + const pending = scope.update({ theme: 'light' }) + await new Promise(resolve => setTimeout(resolve, 5)) + await fiber.dispose() + // The teardown drained the in-flight write before completing… + await pending.catch(() => undefined) + const persistedAtDispose = provider.persisted.length + expect(persistedAtDispose).toBe(1) + // …and afterwards nothing writes and new writes reject. + await expect(service.update(settingsNamespace('ui-theme'), { theme: 'dark' })) + .rejects.toThrow(/disposed|not registered/) + await new Promise(resolve => setTimeout(resolve, 40)) + expect(provider.persisted.length).toBe(persistedAtDispose) + }) + + it('serializes invocations of one async watcher in commit order', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const applied: number[] = [] + let firstCall = true + scope.watch(async (next) => { + // The first (stale) invocation is slow; unserialised it would finish + // last and clobber the newer applied state. + const delay = firstCall ? 30 : 0 + firstCall = false + await new Promise(resolve => setTimeout(resolve, delay)) + applied.push(next.fontSize) + }) + provider.pushExternal({ 'ui-theme': { fontSize: 1 } }) + provider.pushExternal({ 'ui-theme': { fontSize: 2 } }) + await vi.waitFor(() => { + expect(applied).toHaveLength(2) + }) + expect(applied).toEqual([1, 2]) + }) + + it('rejects a plain object that is not structured-cloneable', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await expect(scope.update({ theme: () => 'dark' })) + .rejects.toThrow(/JSON-shaped/) + }) + + it('rejects a write still queued when the service disposes', async () => { + const { ctx, fiber } = await boot({ persistDelayMs: 20 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const first = scope.update({ theme: 'light' }) + const second = scope.update({ fontSize: 20 }) + await new Promise(resolve => setTimeout(resolve, 5)) + await fiber.dispose() + await first + await expect(second).rejects.toThrow(/disposed before the queued/) + }) + + it('rejects a write still queued when the registrant disposes', async () => { + const { ctx } = await boot({ persistDelayMs: 20 }) + let scope: SettingsScope | undefined + const fiber = ctx.plugin({ + inject: ['settings'], + apply: (child: Context) => { + scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + }, + }) + await fiber + const first = scope!.update({ theme: 'light' }) + const second = scope!.update({ fontSize: 20 }) + await new Promise(resolve => setTimeout(resolve, 5)) + await fiber.dispose() + await first + await expect(second).rejects.toThrow(/registration was disposed before the queued/) + }) + + it('snapshots the patch at call time so caller mutation cannot leak in', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const patch = { fontSize: 18 } + const pending = scope.update(patch) + patch.fontSize = 99 + await pending + expect(scope.get().fontSize).toBe(18) + }) +}) + describe('publish', () => { it('notifies watchers of an external change with source provider', async () => { const { ctx, provider } = await boot() @@ -349,10 +488,12 @@ describe('publish', () => { const watcher = vi.fn() scope.watch(watcher) provider.pushExternal({ 'ui-theme': { theme: 'light' } }) - expect(watcher).toHaveBeenCalledWith( - { theme: 'light', fontSize: 14 }, - { theme: 'dark', fontSize: 14 }, - ) + await vi.waitFor(() => { + expect(watcher).toHaveBeenCalledWith( + { theme: 'light', fontSize: 14 }, + { theme: 'dark', fontSize: 14 }, + ) + }) expect(events[0]!.source).toBe('provider') }) @@ -410,7 +551,9 @@ describe('watch', () => { const second = vi.fn() scope.watch(second) provider.pushExternal({ 'ui-theme': { theme: 'light' } }) - expect(second).toHaveBeenCalledTimes(1) + await vi.waitFor(() => { + expect(second).toHaveBeenCalledTimes(1) + }) expect(events).toHaveLength(1) expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 }) }) From 42de60347acbf5953747f4ad4208f5bb53011a9b Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 29 Jul 2026 10:26:29 +0800 Subject: [PATCH 11/67] docs: raise packages/README.md budget ceiling to 850 The group table legitimately gained one row for the new settings group; the row itself is already condensed to the minimum. The intended raise missed the merge commit because a pipeline swallowed the failing edit's exit status. --- 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 80766e314d..48a570a20d 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -7,5 +7,5 @@ "docs/testing.md": 1100, "examples/AGENTS.md": 310, "packages/AGENTS.md": 675, - "packages/README.md": 845 + "packages/README.md": 850 } From d9a11dc91efaff295cc0d99c77d5e253fb86374a Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 16:13:36 +0800 Subject: [PATCH 12/67] fix(tui,host): project the human transcript from append-origin events MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The terminal and history pagination both treated the model-visible surface as the human transcript. A landed compaction replacement therefore erased the conversation it summarized — messages the reader had already seen — and a model-only replacement copy consumed a page's `maxMessages` quota, which could also split a compaction's provenance from the replacement citing it. `dsh-session` now exports the marker split `isAppendSurfaceEvent` / `isReplacementSurfaceEvent`. The terminal replays append-origin surface events, keeps a shadowed step's tool cards paired through its append-origin assistant message, and renders one dim marker where a compaction landed; the checkpoint is recognized through the compaction seam's `isCompactCheckpointSource` contract, not the shape of the replacement. `session.history` counts only append-origin human messages. Everything model-facing keeps reading `session.surface`. --- ...9-human-transcript-append-origin.i18n.yaml | 6 + ...26-07-29-human-transcript-append-origin.md | 47 +++++++ ...07-29-human-transcript-append-origin.zh.md | 47 +++++++ ...cated-full-screen-tui-front-door.i18n.yaml | 4 +- ...17-dedicated-full-screen-tui-front-door.md | 4 +- ...dedicated-full-screen-tui-front-door.zh.md | 4 +- docs/cordis-catalog/services.md | 2 +- docs/module-graph.md | 3 +- packages/core/session/README.i18n.yaml | 4 +- packages/core/session/README.md | 1 + packages/core/session/README.zh.md | 1 + packages/core/session/src/index.ts | 2 +- packages/core/session/src/surface.ts | 30 +++++ packages/core/session/tests/surface.spec.ts | 36 ++++++ packages/host/apiproxy/README.i18n.yaml | 4 +- packages/host/apiproxy/README.md | 2 + packages/host/apiproxy/README.zh.md | 2 + packages/host/apiproxy/src/api-proxy.ts | 16 ++- packages/host/apiproxy/src/api/sessions.ts | 8 +- .../apiproxy/tests/api-proxy-view.spec.ts | 80 +++++++++++- packages/ui/tui/README.i18n.yaml | 4 +- packages/ui/tui/README.md | 2 +- packages/ui/tui/README.zh.md | 2 +- packages/ui/tui/package.json | 2 + packages/ui/tui/src/chat/helpers.ts | 42 +++--- packages/ui/tui/src/index.ts | 46 +++++-- ...rface-after-compaction-narrow.expected.txt | 48 ++++--- ...surface-after-compaction-wide.expected.txt | 44 +++++-- .../surface-before-compaction.expected.txt | 33 ++--- packages/ui/tui/tests/tui.snapshot.ts | 11 +- packages/ui/tui/tests/tui.spec.ts | 120 ++++++++++++++++-- packages/ui/tui/tsconfig.json | 3 + pnpm-lock.yaml | 3 + 33 files changed, 544 insertions(+), 119 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md create mode 100644 .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml new file mode 100644 index 0000000000..530d982f0e --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md +2026-07-29-human-transcript-append-origin.md: 51602148810b0c400ec7b0f7996b37dd666bf93f +2026-07-29-human-transcript-append-origin.zh.md: 77e9a691f06978ac6875e8f4330d96ecca23a1b5 diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md new file mode 100644 index 0000000000..5160214881 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md @@ -0,0 +1,47 @@ +# Agent Note: The human transcript projects append-origin events + +Status: implemented + +English | [中文](2026-07-29-human-transcript-append-origin.zh.md) + +## Problem + +The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message`, `assistant/message`, and `steering/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it. + +Nothing was lost from the log. `Session.events` still held every original message and full tool result; the surface only decides what the model is sent next. The defect was entirely in the projection. + +## Decision + +Model and human projections are separate, and the event's own marker decides which one an event belongs to. `dsh-session` exports the marker split `isAppendSurfaceEvent(event)` and `isReplacementSurfaceEvent(event)` over the two `SurfaceOp` variants, from the browser-safe `surface` module. Append-origin events are the durable source for a transcript; replacement copies stay model-only. Everything that must send exactly what the model sees — `deriveMessages`, token accounting, the compaction backends, tool pairing, injected-context liveness, cross-session reference projection — keeps reading `session.surface`. + +The terminal replays the transcript from append-origin surface events and keeps a shadowed step's tool cards paired through `transcriptToolCallIds`, which reads the append-origin `assistant/message` rather than surface membership. A landed compaction contributes one dim `… earlier context was compacted …` row at its own log position: the marker reports where the model stopped seeing that history instead of erasing it. The framed checkpoint payload never renders, and the replay and live paths share one rule, so a compaction that arrives live and the same log replayed after resume produce the same transcript. + +A checkpoint is recognized through the compaction seam's own contract — `isCompactCheckpointSource`, the backend-independent marker `CompactService` requires on the replacement user message — so the terminal depends on the declared vocabulary, not on the shape of the replacement. `dsh-session-reference` already consumes that predicate to project another session's log; this is the same question asked by a different reader. Other replacements are silent: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation. + +`session.history` counts only append-origin human messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it. + +No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required. + +## Deferred + +The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here. + +## Alternatives considered + +**Recognize a checkpoint by shape (a replacement `user/message`).** Rejected: it reads a coincidence of today's producers instead of a declared contract, and any future producer that replaces a range with a user message would silently inherit the compaction marker. The seam already publishes `COMPACT_CHECKPOINT_SOURCE` precisely so consumers can recognize a checkpoint independently of the backend. + +**Keep rendering the checkpoint as an injected-context card.** Rejected: the framed checkpoint is an instruction envelope written for the model, not human conversation content. Showing it while hiding the history it replaced inverts what the reader needs. + +**Persist a second display transcript.** Rejected: the append-only log already contains the authoritative source material, so a parallel record buys nothing and adds migration and consistency work. + +**Derive the marker from the `compact/*` bracket instead of the checkpoint.** Rejected for the transcript: the bracket is a pair of time-point markers around an operation, while the transcript needs the position where the surface actually changed. The bracket is the right source for progress and duration, which this change does not render. + +**Classify events by re-folding the log, as `session-query` does for search (`current` / `shadowed` / `log-only`).** Rejected: a fold answers a whole-log question, while a projection asks a per-event one that the event's own marker already answers in constant time. + +## Consequences + +Compaction no longer erases terminal history; a session compacted several times shows one marker per landed compaction, in log order. Pagination pages can carry more raw events than before, because quota is spent only on messages a human or model actually produced. + +`dsh-tui` gains a dependency on the `dsh-compact` seam for one pure predicate, mirroring `dsh-session-reference`'s existing use. The terminal still needs no compaction backend at runtime. + +Two behaviors changed with their tests. The surface-replacement terminal test previously pinned erasure ("hides shadowed tool calls") and now pins preservation plus exactly one marker, including a pruned result copy, a regenerated assistant message, and a foreign plugin's replacement all rendering nothing. The compaction snapshot scenario wrote a `workspace-context` source while claiming to pin compaction; it now writes a real checkpoint source, and its three fixtures are re-recorded to show the preserved prompt, the full tool card, and the marker. diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md new file mode 100644 index 0000000000..77e9a691f0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md @@ -0,0 +1,47 @@ +# Agent Note: 人类可读记录投影追加来源的事件 + +Status: implemented + +[English](2026-07-29-human-transcript-append-origin.md) | 中文 + +## Problem + +终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message`、`assistant/message` 和 `steering/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。 + +日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。 + +## Decision + +模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是记录的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。 + +终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且回放路径与实时路径共用同一条规则，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。 + +检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。 + +`session.history` 只把追加来源的人类消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。 + +持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。 + +## Deferred + +浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。 + +## Alternatives considered + +**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。 + +**继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。 + +**持久化第二份展示用记录。** 被否决：仅追加的日志已经包含权威源材料，平行记录换不来任何东西，反而增加迁移与一致性工作。 + +**用 `compact/*` 括号而不是检查点来推导标记。** 就记录而言被否决：括号是围绕一次操作的一对时间点标记，而记录需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。 + +**像 `session-query` 为搜索所做的那样重新折叠日志来分类事件（`current`／`shadowed`／`log-only`）。** 被否决：折叠回答的是整份日志的问题，而投影问的是逐事件的问题，事件自身的标记已能以常数时间给出答案。 + +## Consequences + +压缩不再抹掉终端历史；被压缩多次的会话会按日志顺序显示每次落地压缩对应的一行标记。分页的每一页可以携带比以前更多的原始事件，因为额度只花在人类或模型真正产生的消息上。 + +`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` 接缝的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。 + +两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（“隐藏被遮蔽的工具调用”），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture，以显示被保留的提示、完整的工具卡片和那行标记。 diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml index 3df1059e1f..14e1c4f1e3 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md -2026-07-17-dedicated-full-screen-tui-front-door.md: a3f3d6b51e85ad20218ce5aebf526bd96946be55 -2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 6a0c2f12815e9418a2b5bcb237d3db3616ccd133 +2026-07-17-dedicated-full-screen-tui-front-door.md: 7cc09652a7033c216e3835d33dc9e4a623666259 +2026-07-17-dedicated-full-screen-tui-front-door.zh.md: c5bb6e54e89ec3d1e0e7d2229a120ad158d1f9bc diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md index a3f3d6b51e..7cc09652a7 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md @@ -20,7 +20,7 @@ The selected front door receives the exact generated or resumed `SessionId` used ### Session projection and interaction -The TUI rebuilds the transcript from the active `session.surface` and reprojects it whenever an event carries a `surfaceOp`, so resumed and compacted history matches the model-visible conversation. It renders Markdown text and reasoning, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle. +The TUI rebuilds the transcript from the append-origin session events, so resumed history keeps every message the reader already saw; a compacted range stays readable behind one marker instead of matching the model-visible conversation ([append-origin transcript](../bug-fix/2026-07-29-human-transcript-append-origin.md)). It renders Markdown text and reasoning, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle. Editor input calls `agent.send()` while idle and `agent.steer()` while a turn is running. Cancellation, reasoning visibility, tool-card expansion, redraw, transcript clearing, and exit are terminal-only controls. `/exit` and `/quit` share the same exit path: they cancel an active turn, wait for idle, and then restore and close the terminal. The idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; the panel's controls hint lists only actions meaningful for the current option count, omitting navigation when exactly one option is shown; agent behavior and answer logging remain owned by their existing services. @@ -47,6 +47,6 @@ The implemented [TUI terminal-state snapshot Agent Note](../testing/2026-07-18-t - Interactive terminal work has a stateful Markdown, card, plan, and question interface with no second terminal protocol to keep aligned. - The TUI carries a pi-tui dependency and a strict TTY requirement; non-TTY deployments use the Headless app or a structured protocol. -- Session projection makes resume and compaction consistent with the durable conversation, but one configured session owns the transcript and editor. +- Session projection makes resume consistent with the durable conversation, but one configured session owns the transcript and editor. - Tool packages extend terminal cards through their existing presentation methods without adding tool-specific branches to the TUI. - Model and reasoning-effort selection use adapter-advertised metadata without turning catalog membership into request validation; unused selections are not durable state. diff --git a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md index 6a0c2f1281..c5bb6e54e8 100644 --- a/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md +++ b/.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md @@ -20,7 +20,7 @@ DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README ### 会话投影与交互 -TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。 +TUI 从追加来源的会话事件重建 transcript（文本记录），因此恢复后的历史会保留读者已经看到的每条消息；被压缩的范围不再与模型可见会话保持一致，而是留在一行标记之后仍可阅读（[追加来源的 transcript](../bug-fix/2026-07-29-human-transcript-append-origin.md)）。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。 agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。`/exit` 和 `/quit` 共用同一条退出路径：先取消进行中的轮次，等待 agent 空闲，然后恢复并关闭终端。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；面板的操作提示只列出在当前选项数量下有意义的操作，仅有一个选项时不显示导航项；agent 行为和答案日志仍由既有服务负责。 @@ -47,6 +47,6 @@ agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调 - 交互式终端拥有带状态的 Markdown、卡片、计划和提问界面，无需再对齐第二套终端协议。 - TUI 会引入 pi-tui 依赖并严格要求 TTY；非 TTY 部署使用 Headless app 或结构化协议。 -- 会话投影使恢复和压缩与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。 +- 会话投影使恢复与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。 - 工具包通过既有呈现方法扩展终端卡片，无需在 TUI 中增加工具专用分支。 - 模型和推理强度选择使用适配器公布的元数据，但不会把目录成员关系变成请求校验；未使用的选择不属于持久化状态。 diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index db31daaf06..57b6a5aedf 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -2174,7 +2174,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession ``` -Source: [`packages/ui/tui/src/index.ts:247`](../../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:250`](../../packages/ui/tui/src/index.ts) ## `ctx.userInteraction` — `UserInteractionService` diff --git a/docs/module-graph.md b/docs/module-graph.md index e83228b00d..45c316b096 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -837,6 +837,7 @@ flowchart TD pkg_tui --> pkg_agent pkg_tui --> pkg_agent_loop pkg_tui --> pkg_commands + pkg_tui --> pkg_compact pkg_tui --> pkg_goal pkg_tui --> pkg_invariants pkg_tui --> pkg_llm @@ -1114,7 +1115,7 @@ flowchart TD | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) | | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) | | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | +| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) | | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) | | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index 9fb097d9fb..51f8aad777 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/core/session/README.md -README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412 -README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989 +README.md: 9fa6cf5251d480be9d2388bdb32393fa2827168c +README.zh.md: 5170d5d4b362a0f19ff6953e1636adef9aa7e8b8 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index a9b6905dcf..9fa6cf5251 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -60,6 +60,7 @@ Providers stream token-sized deltas, so a raw log stores hundreds of `assistant/ - `SessionSurface` — the readonly live `nodes` and `replaceGeneration` projection exposed by `session.surface`; candidate validation remains private to `Session`. - `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, replacements that fail to cite every shadowed surface entry, and a `tool/result` replacement that changes anything except one current result's `content`; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache. - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log. +- `isAppendSurfaceEvent(event)` / `isReplacementSurfaceEvent(event)` — split a formed surface event by marker variant. Append-origin events are the durable source for a human transcript, which is not the model-visible surface: a landed replacement shadows the range it summarizes, so projecting a transcript from `session.surface` erases conversation the reader already saw. Consumers that must send exactly what the model sees keep reading `session.surface`. ### Request-header reconstruction (`request-header.ts`) diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md index f1a5e97e32..5170d5d4b3 100644 --- a/packages/core/session/README.zh.md +++ b/packages/core/session/README.zh.md @@ -60,6 +60,7 @@ - `SessionSurface`：实时只读 `nodes` 和 `replaceGeneration` 投影，由 `session.surface` 暴露；候选校验仍由 `Session` 私有。 - `foldSurface(events)`：回放规范 surface 契约，得到脱离的当前事件序列与实际替换范围。同一趟处理会拒绝不连续序号、错位或畸形元数据、空或重复溯源信息、来源并非更早事件、无效位置范围，以及没有引用所有已遮蔽 surface 条目的替换。如果一个 `tool/result` 替换修改了当前某个结果的 `content` 之外的任何内容，也会被拒绝；`SurfaceManager` 共享该原子状态转换，但只保留自己的增量序列缓存。 - `isSurfaceEvent(event)`／`isSurfaceEligibleType(type)`：前者将 `SessionEvent` 收窄为形态完整的 surface 事件；后者在校验种子或已加载日志时，检测缺少标记的可进入 surface 事件。 +- `isAppendSurfaceEvent(event)`／`isReplacementSurfaceEvent(event)`：按标记变体拆分形态完整的 surface 事件。追加来源的事件是人类可读记录（transcript）的持久来源，而该记录并非模型可见的 surface：已落地的替换会遮蔽它所概括的范围，因此从 `session.surface` 投影记录会抹掉读者已经看到的对话。必须准确发送模型所见内容的消费方仍继续读取 `session.surface`。 ### 请求头重建（`request-header.ts`） diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index e42414503b..b86bc0285a 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -27,7 +27,7 @@ export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from ' export { decodeStorageRecord, packChunkRuns } from './chunk-rows.ts' export type { ChunkRow, StorageRecord } from './chunk-rows.ts' export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts' -export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts' +export { foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts' export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts' /** diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts index 9677c5ec2c..4b2594d35a 100644 --- a/packages/core/session/src/surface.ts +++ b/packages/core/session/src/surface.ts @@ -37,6 +37,36 @@ export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent { return (event as SessionEvent).surfaceOp !== undefined } +/** + * Narrow an event to an append-origin surface event: one that entered the + * surface at its own log position and was never itself a replacement copy. + * + * The model-visible surface deliberately shadows replaced ranges, so it is the + * wrong source for a human transcript — a landed replacement would erase + * conversation the user already saw. Append-origin events are that transcript's + * durable source material; replacement copies stay model-only. + * @param event - event to test. + * @returns true when the event appended to the surface tail. + */ +export function isAppendSurfaceEvent( + event: SessionEvent, +): event is SurfaceEvent & { surfaceOp: 'append' } { + return isSurfaceEvent(event) && event.surfaceOp === 'append' +} + +/** + * Narrow an event to a surface replacement: a node that shadowed an existing + * surface range instead of appending to the tail. The counterpart of + * {@link isAppendSurfaceEvent} over the two {@link SurfaceOp} variants. + * @param event - event to test. + * @returns true when the event replaced a surface range. + */ +export function isReplacementSurfaceEvent( + event: SessionEvent, +): event is SurfaceEvent & { surfaceOp: { op: 'replace'; start: number; end: number } } { + return isSurfaceEvent(event) && event.surfaceOp !== 'append' +} + /** One replacement operation observed while folding a session surface. */ export interface SurfaceFoldReplacement { /** Seq of the event that replaced the prior surface range. */ diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts index 4078f526e6..017f0e0163 100644 --- a/packages/core/session/tests/surface.spec.ts +++ b/packages/core/session/tests/surface.spec.ts @@ -4,6 +4,8 @@ import { Session, SessionId, foldSurface, + isAppendSurfaceEvent, + isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, } from '@deepseek-ai/dsh-session' @@ -861,6 +863,40 @@ describe('surface type guards', () => { expect(isSurfaceEligibleType(markerless.type)).toBe(true) expect(isSurfaceEvent(markerless)).toBe(false) }) + + it('splits surface events into append-origin and replacement by their marker', () => { + const s = surfaceSession() + s.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'checkpoint' }], source: { kind: 'plugin', plugin: 'compact' }, + }), { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] }) + const appended = s.events.find(e => e.type === 'user/message')! + const replacement = s.events.at(-1)! + + expect(isAppendSurfaceEvent(appended)).toBe(true) + expect(isReplacementSurfaceEvent(appended)).toBe(false) + expect(isAppendSurfaceEvent(replacement)).toBe(false) + expect(isReplacementSurfaceEvent(replacement)).toBe(true) + }) + + it('rejects log-only and markerless events from both marker guards', () => { + const s = surfaceSession() + const turnStart = s.events.find(e => e.type === 'turn/start')! + // A surface-eligible type whose mandatory marker is absent has no origin at + // all: it never entered the surface. + const markerless: SessionEvent = { + type: 'user/message', + seq: 0, + time: 0, + data: createUserMessage({ + content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' }, + }), + } + + expect(isAppendSurfaceEvent(turnStart)).toBe(false) + expect(isReplacementSurfaceEvent(turnStart)).toBe(false) + expect(isAppendSurfaceEvent(markerless)).toBe(false) + expect(isReplacementSurfaceEvent(markerless)).toBe(false) + }) }) describe('SurfaceManager.replaceGeneration', () => { diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 73b0845370..6fb44f9b57 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md -README.md: ca4471454f5be5d3fcba38ce665d4fb3fbd85e74 -README.zh.md: 953539e1198a52b2bf7cdd9ca1b0d263cc2ae6f9 +README.md: 190e7f8d36f74bfd7232cc5b4dbb937f265ef1d5 +README.zh.md: 9fb9d24412e950b0648cd07c4b5c73aa0174405c diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index ca4471454f..190e7f8d36 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -10,6 +10,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md). +`session.history` pages on append-origin human-message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it. + `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface. Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 953539e119..9fb9d24412 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -10,6 +10,8 @@ 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。 +`session.history` 按追加来源的人类消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。 + `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。 diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index f178bfefd0..df4d02dba8 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -14,6 +14,7 @@ import type { import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm' import { errorChain } from '@deepseek-ai/dsh-llm' import type { MessageId, MessageSource } from '@deepseek-ai/dsh-llm' +import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session' import type { Session, SessionEvent, SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session' import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence' import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace' @@ -57,14 +58,17 @@ import { openNativePath } from './native-path-opener.ts' /** Page size when history is called without maxMessages. */ const DEFAULT_MAX_MESSAGES = 50 -/** Surface message event types (the pagination counting unit). */ +/** Human message event types (the pagination counting unit). */ const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message']) /** - * Message-boundary pagination: count maxMessages surface messages backwards from - * the window tail; the cut is the starting seq of the oldest message group - * (chunks group via sourceEventSeqs — never cut mid-message). The tail page - * naturally includes the in-progress partial. + * Message-boundary pagination: count maxMessages append-origin human messages + * backwards from the window tail. Replacement copies are model-only, so they + * consume no quota; the page stays one contiguous raw range, which keeps a + * compaction's log-only provenance on the same page as its replacement. The cut + * is the starting seq of the oldest message group (chunks group via + * sourceEventSeqs — never cut mid-message). The tail page naturally includes the + * in-progress partial. */ function paginate( events: readonly SessionEvent[], @@ -76,7 +80,7 @@ function paginate( let cut = 0 for (let i = window.length - 1; i >= 0; i--) { const event = window[i] as SessionEvent - if (!MESSAGE_TYPES.has(event.type)) continue + if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event)) continue count++ const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index f952c7c542..5917555b69 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -176,9 +176,11 @@ export interface SessionsApi { Promise> /** - * Reads a window of history events; page boundaries align to message boundaries: one page = - * all raw events owned by a whole number of messages (including their chunk / tool events), - * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight + * Reads a window of history events; page boundaries align to append-origin human-message + * boundaries: one page = all raw events owned by a whole number of such messages (including + * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no + * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail + * page (beforeSeq absent) additionally carries the in-flight * partial — chunk events already emitted for the last unfinalized message. * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose * presenter produced one, evaluated against the registry at pagination time); the client diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts index b970755d6b..717081dc7d 100644 --- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts @@ -14,7 +14,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import SessionStore from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools' -import { CallId, createToolResultMessage } from '@deepseek-ai/dsh-llm' +import { CallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session' import type { ToolDefinition } from '@deepseek-ai/dsh-tools' @@ -35,6 +35,35 @@ function tool(name: string, presenters: Pick SessionEvent)(type, data) +} + async function harness(): Promise<{ ctx: Context }> { const ctx = new Context() await ctx.plugin(SessionStore) @@ -207,6 +236,55 @@ describe('mux live view computation', () => { expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false) }) + it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => { + const { ctx } = await harness() + const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }) + const session = ctx.sessions.create() + ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent) + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + const first = appendUserText(session, 'first prompt') + appendAssistantText(session, 'first reply', 1) + const third = appendUserText(session, 'second prompt') + appendAssistantText(session, 'second reply', 2) + const shadowed = [...session.surface.nodes] + // A compaction transaction: log-only provenance immediately followed by the + // replacement that shadows the range. + const summary = appendExtension(session, 'compact/summary', { + summary: [{ type: 'text', text: 'summary' }], + shadowedRange: { start: shadowed[0], end: shadowed.at(-1) }, + shadowedSeqs: shadowed, + shadowedTokenCount: 0, + provider: 'p', + model: 'm', + }) + session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'summary' }], + source: { kind: 'plugin', plugin: 'compact' }, + }), { + surfaceOp: { op: 'replace', start: shadowed[0] as number, end: shadowed.at(-1) as number }, + sourceEventSeqs: [...shadowed, summary.seq], + }) + + const response = await api.sessions.history({ + rpcId: RpcId('t-hist-compact'), + payload: { sessionId: session.id, maxMessages: 2 }, + }) + if (!response.result.ok) throw new Error('unreachable') + const page = response.result.value.events.map(entry => entry.event) + // Two append-origin messages fill the page even though a replacement copy of + // the same event type sits in the window: the copy is model-only. + const messages = page.filter(event => event.type === 'user/message' || event.type === 'assistant/message') + expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3]) + expect(page.some(event => event.seq === first.seq)).toBe(false) + expect(response.result.value.hasMore).toBe(true) + // The range stays contiguous, so the checkpoint's provenance is readable on + // the same page as the checkpoint itself. + const summaryIndex = page.findIndex(event => event.seq === summary.seq) + expect(summaryIndex).toBeGreaterThan(-1) + expect(page[summaryIndex + 1]?.seq).toBe(summary.seq + 1) + expect(page.map(event => event.seq)).toEqual(page.map((_event, index) => third.seq + index)) + }) + it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => { const { ctx } = await harness() const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }) diff --git a/packages/ui/tui/README.i18n.yaml b/packages/ui/tui/README.i18n.yaml index 8ab63910fa..e2195e2e07 100644 --- a/packages/ui/tui/README.i18n.yaml +++ b/packages/ui/tui/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/ui/tui/README.md -README.md: 0b358520b863f0b9ee7a128cf4807f582fc46d8d -README.zh.md: 7e89197bd82d16dfbabeb715e953275e2f6dd68b +README.md: c6542cf5383e46f43024782c89e364c92a4c518e +README.zh.md: 7fbdaace128f779abf27de9042cd13b85ceef37f diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md index 0b358520b8..c6542cf538 100644 --- a/packages/ui/tui/README.md +++ b/packages/ui/tui/README.md @@ -12,7 +12,7 @@ This package owns interactive terminal presentation and input only. It injects ` After terminal startup succeeds, the package provides the terminal-local `ctx.tui` extension service. A plugin that injects it can call `openOverlay()` with a component factory and constrained layout options; the host exposes the viewport, semantic theme, display-text escaping, redraw, close, and a lifetime signal, but not the pi-tui tree, terminal, focus controller, or overlay handle. Plugin overlays, the model selector, and user questions share one FIFO modal queue. Each request is an effect of the calling plugin fiber, so unload removes queued work or closes visible work before cleanup settles; terminal shutdown unloads dependents before stopping pi-tui. Overlay state is not logged or replayed. Component code is trusted and may render ANSI styling, but must pass untrusted text through `host.display()`. The [interactive-extension Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md) owns the boundary and rejected alternatives. -The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes ` — `. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear. +The TUI rebuilds resumed history from the append-origin session events, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes ` — `. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. A surface replacement never rewrites the rendered transcript: the conversation it shadows stays readable, and a landed compaction checkpoint adds one dim `… earlier context was compacted …` marker at its log position, so the terminal reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies — a pruned tool result, a regenerated assistant message — render nothing. An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`. diff --git a/packages/ui/tui/README.zh.md b/packages/ui/tui/README.zh.md index 7e89197bd8..7fbdaace12 100644 --- a/packages/ui/tui/README.zh.md +++ b/packages/ui/tui/README.zh.md @@ -12,7 +12,7 @@ DeepSeek Harness agent（智能体）的交互式终端入口，基于 [`@earend 终端成功启动后，本包会提供终端本地的 `ctx.tui` 扩展服务。注入该服务的插件可以使用组件工厂和受限布局选项调用 `openOverlay()`；宿主会公开 viewport、语义化主题、显示文本转义、重绘、关闭和生命周期信号，但不公开 pi-tui 树、终端、焦点控制器或 overlay 句柄。插件 overlay、模型选择器和用户问题共用一个 FIFO 模态队列。每个请求都是调用方插件 fiber 的 effect，因此卸载会移除排队工作，或在清理结算前关闭可见工作；终端关闭会先卸载依赖项，再停止 pi-tui。Overlay 状态不会记录或回放。组件代码受信任，可以渲染 ANSI 样式，但必须通过 `host.display()` 处理不受信任文本。[交互式扩展 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md)持有该边界和未采用的替代方案。 -TUI 从活跃会话表层重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 ` — `。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换事件会重建 transcript，使经过压缩（compaction）的历史不会再次出现。 +TUI 从追加来源的会话事件重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 ` — `。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换从不重写已渲染的 transcript：被它遮蔽的对话仍可阅读，而已落地的压缩（compaction）检查点会在其日志位置添加一行暗色 `… earlier context was compacted …` 标记，因此终端报告的是模型从何处起不再看到那段历史，而不是把它抹掉。仅供模型使用的替换副本——被裁剪的工具结果、重新生成的 assistant 消息——不渲染任何内容。 如果逻辑工作区标签与会话宿主目录不同，嵌入方可以提供 `TuiRuntime.formatCwd`。该覆盖只改变 footer 标签；工具仍使用会话 `cwd`。 diff --git a/packages/ui/tui/package.json b/packages/ui/tui/package.json index f9260e3231..5158a6d9a8 100644 --- a/packages/ui/tui/package.json +++ b/packages/ui/tui/package.json @@ -35,6 +35,7 @@ "@deepseek-ai/dsh-agent": "^0.0.1", "@deepseek-ai/dsh-agent-loop": "^0.0.1", "@deepseek-ai/dsh-commands": "^0.0.1", + "@deepseek-ai/dsh-compact": "^0.0.1", "@deepseek-ai/dsh-invariants": "^0.0.1", "@deepseek-ai/dsh-llm": "^0.0.1", "@deepseek-ai/dsh-llm-retry": "^0.0.1", @@ -73,6 +74,7 @@ "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-goal": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", + "@deepseek-ai/dsh-compact": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-llm-retry": "workspace:^", diff --git a/packages/ui/tui/src/chat/helpers.ts b/packages/ui/tui/src/chat/helpers.ts index 58c2a71b21..c9c54b8aa6 100644 --- a/packages/ui/tui/src/chat/helpers.ts +++ b/packages/ui/tui/src/chat/helpers.ts @@ -1,6 +1,6 @@ /** * Zero-state helpers for the interactive chat channel: prompt-directory and - * Git-branch formatting, surface/tool-call derivations over the session log, + * Git-branch formatting, transcript/tool-call derivations over the session log, * session-reference context cards, the placeholder editor, and banner-reveal * timing constants. None of these close over channel state. * @module @deepseek-ai/dsh-tui/chat/helpers @@ -15,7 +15,9 @@ import { truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui' -import type { Session } from '@deepseek-ai/dsh-session' +import { isCompactCheckpointSource } from '@deepseek-ai/dsh-compact' +import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session' +import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' /** Editor that shows a placeholder without making it editable content. */ export class HintEditor extends Editor { @@ -83,24 +85,16 @@ export function gitBranch(cwd: string): string | undefined { } /** - * Sequence numbers currently visible on the session surface. - * @param session - session whose surface nodes to read. - * @returns the set of visible event sequence numbers. - */ -export function activeSurfaceSeqs(session: Session): Set { - return new Set(session.surface.nodes) -} - -/** - * Tool-call ids whose owning assistant message is on the active surface. + * Tool-call ids whose owning assistant message is append-origin, so its tool + * cards stay paired in the transcript after a replacement shadowed the message + * on the model surface. * @param session - session whose events to scan. - * @param active - sequence numbers currently on the surface. - * @returns the set of active tool-call ids. + * @returns the set of transcript tool-call ids. */ -export function activeToolCallIds(session: Session, active: ReadonlySet): Set { +export function transcriptToolCallIds(session: Session): Set { const ids = new Set() for (const event of session.events) { - if (event.type !== 'assistant/message' || !active.has(event.seq)) continue + if (event.type !== 'assistant/message' || !isAppendSurfaceEvent(event)) continue for (const block of event.data.message.content) { if (block.type === 'tool-call') ids.add(block.id) } @@ -108,6 +102,22 @@ export function activeToolCallIds(session: Session, active: ReadonlySet) return ids } +/** + * Whether an event is a landed compaction checkpoint. Recognition goes through + * {@link isCompactCheckpointSource} — the compaction seam's backend-independent + * contract for the source every backend stamps on its replacement user message — + * rather than the shape of the replacement. Other replacements (a pruned + * `tool/result`, a regenerated `assistant/message`) rewrite one node for the + * model and mark no boundary in the conversation. + * @param event - event to test. + * @returns true when the event compacted a surface range. + */ +export function isCompactCheckpoint(event: SessionEvent): boolean { + return event.type === 'user/message' + && isCompactCheckpointSource(event.data.source) + && isReplacementSurfaceEvent(event) +} + /** * Read a session-reference context card's display labels from an event source. * @param source - event source to inspect. diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index d1ba37e61d..823d125b1c 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -35,6 +35,9 @@ import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-llm-retry' import { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import { + isAppendSurfaceEvent, + isReplacementSurfaceEvent, + isSurfaceEligibleType, SessionId, type SessionEvent, type UserMessage, @@ -118,14 +121,14 @@ import { } from './chat/skill-invocation.ts' import { ReferenceAutocompleteProvider } from './chat/autocomplete.ts' import { - activeSurfaceSeqs, - activeToolCallIds, BANNER_REVEAL_INTERVAL_MS, BANNER_REVEAL_STEPS, formatCwd, gitBranch, HintEditor, + isCompactCheckpoint, sessionReferenceCard, + transcriptToolCallIds, } from './chat/helpers.ts' import { createModelController, @@ -268,6 +271,13 @@ export const inject = ['agents', 'sessions', 'commands', 'userInteraction', 'too /** Model guidance for path-only file references selected through the TUI. */ export const FILE_REFERENCE_PROMPT = 'Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.' +/** + * Transcript row standing in for one compacted range. The conversation the + * compaction replaced stays rendered above it: the marker reports where the + * model stopped seeing that history, not that the history is gone. + */ +const COMPACTION_MARKER = '… earlier context was compacted …' + interface RunningStatus { turn: number | undefined timer: ReturnType @@ -816,6 +826,17 @@ export function createTuiChat( } } + const renderCompactionMarker = (): void => { + chat.addChild(new Spacer(1)) + chat.addChild(new Text(palette.dim(COMPACTION_MARKER), 0, 0)) + } + + /** + * Replay the human transcript from the append-only log. The model-visible + * surface shadows compacted ranges, so it is not the source here: every + * append-origin message stays rendered, and a replacement contributes at most + * the compaction marker at its own log position. + */ const rebuildTranscript = (populateHistory: boolean): void => { chat.clear() toolCards.clear() @@ -823,15 +844,13 @@ export function createTuiChat( contextCards.clear() streaming = undefined todo.update([]) - const active = activeSurfaceSeqs(agent.session) - const activeCalls = activeToolCallIds(agent.session, active) + const transcriptCalls = transcriptToolCallIds(agent.session) for (const event of agent.session.events) { - const isSurface = event.type === 'user/message' - || event.type === 'assistant/message' - || event.type === 'tool/result' - || event.type === 'steering/message' - if (isSurface && !active.has(event.seq)) continue - if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue + if (isSurfaceEligibleType(event.type) && !isAppendSurfaceEvent(event)) { + if (isCompactCheckpoint(event)) renderCompactionMarker() + continue + } + if (event.type === 'tool/call' && !transcriptCalls.has(event.data.callId)) continue renderEvent(event, { addHistory: populateHistory, renderChunks: false }) } requestRender() @@ -1438,8 +1457,11 @@ export function createTuiChat( recordEventUsage(tokens, event) if (event.type === 'turn/start' && runningStatus !== undefined) runningStatus.turn = event.data.turn if (event.type === 'assistant/message' && streaming?.isSettled()) streaming = undefined - if ('surfaceOp' in event && typeof event.surfaceOp === 'object') { - rebuildTranscript(false) + // A replacement mutates only the model surface, so the rendered transcript + // keeps what it already showed; a landed summary checkpoint adds its marker. + if (isReplacementSurfaceEvent(event)) { + if (isCompactCheckpoint(event)) renderCompactionMarker() + requestRender() return } renderEvent(event, { addHistory: false, renderChunks: true }) diff --git a/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt b/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt index e1686f3574..e071335d14 100644 --- a/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt +++ b/packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt @@ -1,7 +1,7 @@ -terminal 44x18 buffer=normal length=18 base=0 viewport=0 +terminal 44x18 buffer=normal length=24 base=6 viewport=6 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=14 bufferRow=14 +cursor hidden column=7 viewportRow=17 bufferRow=23 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -13,25 +13,39 @@ buffer 3| 4| "Assistant " style 0-8 fg=bright-magenta bold underline -5| "Model wait 0.0s " +5| +6| "You " + style 0-2 fg=bright-magenta bold underline +7| "Old prompt with a long line that exercises " +8| "wrapping and stays visible after compaction." +9| +10| "● Tool / bash / Run the coverage gate" + style 0-36 fg=green +11| "$ pnpm run test:coverage " + style 0-23 dim +12| "/workspace/project " + style 0-17 dim +13| "packages/ui/tui 100% " + style 0-19 dim +14| "… +1 lines (Ctrl+O to expand) " + style 0-28 dim +15| "1 test skipped " + style 0-13 dim +16| "coverage complete " + style 0-16 dim +17| "[exit 0] " + style 0-7 dim +18| "Model wait 0.0s " style 0-14 dim -6| -7| "Context · workspace-context" - style 0-26 dim -8| "Additional instructions from: " - style 0-43 dim -9| "nested/AGENTS.md " - style 0-15 dim -10| " " -11| "Render workspace context XML clearly. " - style 0-36 dim -12| -13| "/workspace/project (tui-staging) deepseek-v" +19| +20| "… earlier context was compacted … " + style 0-32 dim +21| +22| "/workspace/project (tui-staging) deepseek-v" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-43 dim -14| " dsh > " +23| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse -15-17| diff --git a/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt b/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt index 0724786b40..81460f09b7 100644 --- a/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt +++ b/packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt @@ -1,7 +1,7 @@ terminal 104x30 buffer=normal length=30 base=0 viewport=0 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=13 bufferRow=13 +cursor hidden column=7 viewportRow=22 bufferRow=22 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -13,25 +13,41 @@ buffer 3| 4| "Assistant " style 0-8 fg=bright-magenta bold underline -5| "Model wait 0.0s " +5| +6| "You " + style 0-2 fg=bright-magenta bold underline +7| "Old prompt with a long line that exercises wrapping and stays visible after compaction. " +8| +9| "● Tool / bash / Run the coverage gate" + style 0-36 fg=green +10| "$ pnpm run test:coverage " + style 0-23 dim +11| "/workspace/project " + style 0-17 dim +12| "packages/ui/tui 100% " + style 0-19 dim +13| "… +1 lines (Ctrl+O to expand) " + style 0-28 dim +14| "1 test skipped " + style 0-13 dim +15| "coverage complete " + style 0-16 dim +16| "[exit 0] " + style 0-7 dim +17| "Model wait 0.0s " style 0-14 dim -6| -7| "Context · workspace-context" - style 0-26 dim -8| "Additional instructions from: nested/AGENTS.md " - style 0-45 dim -9| " " -10| "Render workspace context XML clearly. " - style 0-36 dim -11| -12| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" +18| +19| "… earlier context was compacted … " + style 0-32 dim +20| +21| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-50 dim style 53-57 dim style 60-69 dim -13| " dsh > " +22| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse -14-29| +23-29| diff --git a/packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt b/packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt index cf3915dab7..f599ef75cc 100644 --- a/packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt +++ b/packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt @@ -1,7 +1,7 @@ terminal 80x24 buffer=normal length=24 base=0 viewport=0 lifecycle started=1 stopped=0 progress=inactive title "DSH snapshot" -cursor hidden column=7 viewportRow=20 bufferRow=20 +cursor hidden column=7 viewportRow=21 bufferRow=21 buffer 0| " DEEPSEEK HARNESS" style 1-8 fg=bright-magenta bold @@ -16,35 +16,36 @@ buffer 5| 6| "You " style 0-2 fg=bright-magenta bold underline -7| "Old prompt with a long line that exercises wrapping before compaction. " -8| -9| "● Tool / bash / Run the coverage gate" +7| "Old prompt with a long line that exercises wrapping and stays visible after " +8| "compaction. " +9| +10| "● Tool / bash / Run the coverage gate" style 0-36 fg=green -10| "$ pnpm run test:coverage " +11| "$ pnpm run test:coverage " style 0-23 dim -11| "/workspace/project " +12| "/workspace/project " style 0-17 dim -12| "packages/ui/tui 100% " +13| "packages/ui/tui 100% " style 0-19 dim -13| "… +1 lines (Ctrl+O to expand) " +14| "… +1 lines (Ctrl+O to expand) " style 0-28 dim -14| "1 test skipped " +15| "1 test skipped " style 0-13 dim -15| "coverage complete " +16| "coverage complete " style 0-16 dim -16| "[exit 0] " +17| "[exit 0] " style 0-7 dim -17| "Model wait 0.0s " +18| "Model wait 0.0s " style 0-14 dim -18| -19| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" +19| +20| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" style 0-17 fg=bright-magenta bold style 18-31 dim style 34-50 dim style 53-57 dim style 60-69 dim -20| " dsh > " +21| " dsh > " style 1-3 fg=bright-magenta bold style 5-6 dim style 7-7 inverse -21-23| +22-23| diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts index adf1c071bd..b0c63bda04 100644 --- a/packages/ui/tui/tests/tui.snapshot.ts +++ b/packages/ui/tui/tests/tui.snapshot.ts @@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url' import { afterAll, describe, expect, it, vi } from 'vitest' import type { Context } from 'cordis' import { agentEvents } from '@deepseek-ai/dsh-agent' +import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact' import { createUserMessage, CallId, type ContentBlock , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-llm-retry' import { SessionId, type JsonValue, type Session, type SessionEvent } from '@deepseek-ai/dsh-session' @@ -684,7 +685,7 @@ describe('TUI terminal-state snapshots', () => { await disposeSnapshot(harness) }) - it('pins compaction surface replacement and narrow-to-wide reflow', async () => { + it('pins preserved history, the compaction marker, and narrow-to-wide reflow', async () => { // Freeze the clock: the timing header hides zero-duration buckets, so a // real-clock millisecond tick between the fixture appends and the render // would flip `Tools 0.0s` in and out of the pinned header. @@ -696,7 +697,7 @@ describe('TUI terminal-state snapshots', () => { tools: ADVANCED_CARD_TOOLS, beforeMount(session) { const user = session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping before compaction.' }], + content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping and stays visible after compaction.' }], source: { kind: 'user' }, }), { surfaceOp: 'append' }) const assistant = session.append('assistant/message', { @@ -717,7 +718,7 @@ describe('TUI terminal-state snapshots', () => { step: 1, message: createToolResultMessage({ callId: CallId('old-tool'), - content: [{ type: 'text', text: 'obsolete output that must disappear' }], + content: [{ type: 'text', text: 'tool output that stays readable after compaction' }], isError: false, }), }, { surfaceOp: 'append' }) @@ -732,9 +733,9 @@ describe('TUI terminal-state snapshots', () => { harness.session.append('user/message', createUserMessage({ content: [{ type: 'text', - text: '\nAdditional instructions from: nested/AGENTS.md\n\nRender workspace context XML clearly.\n', + text: '\nModel-only summary payload that must never reach the transcript.\n', }], - source: { kind: 'plugin', plugin: 'workspace-context' }, + source: COMPACT_CHECKPOINT_SOURCE, }), { surfaceOp: { op: 'replace', start: replacementStart, end: replacementEnd }, sourceEventSeqs: replacementSources, diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index e918f9b299..8d88d005a5 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -16,6 +16,7 @@ import { createUserMessage, } from '@deepseek-ai/dsh-llm' import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeMeta } from '@deepseek-ai/dsh-goal' import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands' +import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact' import SessionStore, { SessionId, type JsonValue, type SessionEvent, type SessionHeader, type TurnEndReason } from '@deepseek-ai/dsh-session' import type { SessionRecord } from '@deepseek-ai/dsh-session-query' import SkillService, { type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill' @@ -4365,10 +4366,10 @@ describe('tool cards and surface replay', () => { await dispose(result) }) - it('rebuilds after a surface replacement and hides shadowed tool calls', async () => { + it('keeps append-origin history and marks a landed compaction, live and on rebuild', async () => { const result = await setup({ tools }) appendUser(result.session, 'old prompt') - const assistant = result.session.append('assistant/message', { + result.session.append('assistant/message', { turn: 1, step: 1, message: createMessage({ @@ -4391,21 +4392,116 @@ describe('tool cards and surface replay', () => { isError: false, }), }, { surfaceOp: 'append' }) - const start = result.session.surface.nodes[0] as number - result.session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'summary replacement' }], - source: { kind: 'plugin', plugin: 'compact' }, - }), { - surfaceOp: { op: 'replace', start, end: toolResult.seq }, - sourceEventSeqs: [start, assistant.seq, toolResult.seq], + // Result pruning rewrites one node's content in place: model-only, and no + // boundary in the conversation, so the terminal keeps the full output. + const originalResult = toolResult.data.message.content[0] + result.session.append('tool/result', { + ...toolResult.data, + message: freezeMessage({ + ...toolResult.data.message, + content: [{ ...originalResult, content: [{ type: 'text', text: 'pruned result copy' }] }] as [typeof originalResult], + }), + }, { + surfaceOp: { op: 'replace', start: toolResult.seq, end: toolResult.seq }, + sourceEventSeqs: [toolResult.seq], }) + const nodes = [...result.session.surface.nodes] + const checkpoint = result.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'model-only summary payload' }], + source: COMPACT_CHECKPOINT_SOURCE, + }), { + surfaceOp: { op: 'replace', start: nodes[0] as number, end: nodes.at(-1) as number }, + sourceEventSeqs: nodes, + }) + // A regenerated assistant message replaces one node without summarizing + // anything, so it marks no boundary either. + const generic = result.session.append('assistant/message', { + turn: 1, + step: 1, + message: createMessage({ + role: 'assistant', + content: [{ type: 'text', text: 'generic replacement copy' }], + source: { + kind: 'model', + ...{ provider: 'mock', model: 'deepseek-v4-flash' }, + }, + }), + }, { surfaceOp: { op: 'replace', start: checkpoint.seq, end: checkpoint.seq }, sourceEventSeqs: [checkpoint.seq] }) + // Only a checkpoint carrying the compaction seam's source marks a boundary: + // another plugin replacing a node is model-only. + result.session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'foreign plugin replacement copy' }], + source: { kind: 'plugin', plugin: 'other' }, + }), { surfaceOp: { op: 'replace', start: generic.seq, end: generic.seq }, sourceEventSeqs: [generic.seq] }) await tick() result.terminal.resize(89) await tick() - const lastFullRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J')) - expect(lastFullRender).toContain('summary replacement') - expect(lastFullRender).not.toContain('old output') + const liveRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J')) + expect(liveRender).toContain('old prompt') + // The shadowed step keeps its card: one call row, one full result, no + // second card from the pruned copy. + expect(liveRender.split('$ printf hello')).toHaveLength(2) + expect(liveRender).toContain('third') + expect(liveRender.split('[exit 0]')).toHaveLength(2) + expect(liveRender.split('… earlier context was compacted …')).toHaveLength(2) + expect(liveRender).not.toContain('model-only summary payload') + expect(liveRender).not.toContain('generic replacement copy') + expect(liveRender).not.toContain('foreign plugin replacement copy') + + // Ctrl+R rebuilds the transcript from the log; the replayed projection + // matches what the live appends produced, including the shadowed assistant + // message's tool card. + result.terminal.send('\x12') + await tick() + result.terminal.resize(90) + await tick() + const replayRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J')) + expect(replayRender).toContain('old prompt') + expect(replayRender.split('$ printf hello')).toHaveLength(2) + expect(replayRender).toContain('third') + expect(replayRender.split('[exit 0]')).toHaveLength(2) + expect(replayRender.split('… earlier context was compacted …')).toHaveLength(2) + expect(replayRender).not.toContain('model-only summary payload') + expect(replayRender).not.toContain('generic replacement copy') + expect(replayRender).not.toContain('foreign plugin replacement copy') + await dispose(result) + }) + + it('replays a stored compaction as preserved history plus its marker', async () => { + const result = await setup({ + beforeMount(session) { + appendUser(session, 'prompt before compaction') + session.append('assistant/message', { + turn: 1, + step: 1, + message: createMessage({ + role: 'assistant', + content: [{ type: 'text', text: 'reply before compaction' }], + source: { + kind: 'model', + ...{ provider: 'mock', model: 'deepseek-v4-flash' }, + }, + }), + }, { surfaceOp: 'append' }) + const nodes = [...session.surface.nodes] + session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'stored model-only payload' }], + source: COMPACT_CHECKPOINT_SOURCE, + }), { + surfaceOp: { op: 'replace', start: nodes[0] as number, end: nodes.at(-1) as number }, + sourceEventSeqs: nodes, + }) + }, + }) + result.terminal.resize(89) + await tick() + + const mounted = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J')) + expect(mounted).toContain('prompt before compaction') + expect(mounted).toContain('reply before compaction') + expect(mounted.split('… earlier context was compacted …')).toHaveLength(2) + expect(mounted).not.toContain('stored model-only payload') await dispose(result) }) }) diff --git a/packages/ui/tui/tsconfig.json b/packages/ui/tui/tsconfig.json index 3560d6bc9d..906d8a24c1 100644 --- a/packages/ui/tui/tsconfig.json +++ b/packages/ui/tui/tsconfig.json @@ -53,6 +53,9 @@ { "path": "../commands" }, + { + "path": "../../compact/compact" + }, { "path": "../../skill/skill" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 66ea5bea26..a6dac9263d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -4987,6 +4987,9 @@ importers: '@deepseek-ai/dsh-commands': specifier: workspace:^ version: link:../commands + '@deepseek-ai/dsh-compact': + specifier: workspace:^ + version: link:../../compact/compact '@deepseek-ai/dsh-goal': specifier: workspace:^ version: link:../../goal/goal From 035a99f922019aa54325cc69956409fd8d80ebbf Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 17:17:19 +0800 Subject: [PATCH 13/67] =?UTF-8?q?fix(tui,host):=20pin=20replayed=20compact?= =?UTF-8?q?ion=20and=20correct=20projection=20wording=20Review=20follow-up?= =?UTF-8?q?s=20on=20the=20append-origin=20transcript=20projection.=20The?= =?UTF-8?q?=20live/replay=20equivalence=20claim=20was=20stated=20unconditi?= =?UTF-8?q?onally=20but=20does=20not=20cover=20`tool/call`:=20only=20repla?= =?UTF-8?q?y=20re-derives=20call=20pairing,=20because=20a=20call=20event?= =?UTF-8?q?=20carries=20no=20`surfaceOp`=20of=20its=20own=20and=20inherits?= =?UTF-8?q?=20transcript=20membership=20from=20the=20`assistant/message`?= =?UTF-8?q?=20that=20advertised=20it=20=E2=80=94=20which=20the=20live=20li?= =?UTF-8?q?stener=20has=20necessarily=20just=20rendered.=20Narrow=20the=20?= =?UTF-8?q?claim=20in=20the=20TUI=20README=20and=20Agent=20Note,=20and=20r?= =?UTF-8?q?ecord=20at=20`rebuildTranscript`=20why=20the=20filter=20is=20re?= =?UTF-8?q?play-only=20rather=20than=20a=20missing=20live=20branch.=20Add?= =?UTF-8?q?=20`surface-replayed-compaction`:=20the=20three=20existing=20fi?= =?UTF-8?q?xtures=20all=20come=20from=20the=20live=20path,=20leaving=20the?= =?UTF-8?q?=20resume=20case=20the=20bug=20report=20leads=20with=20pinned?= =?UTF-8?q?=20only=20by=20a=20unit=20test.=20The=20new=20checkpoint=20moun?= =?UTF-8?q?ts=20with=20the=20replacement=20already=20stored=20and=20record?= =?UTF-8?q?s=20byte-identical=20to=20`surface-after-compaction-wide`,=20so?= =?UTF-8?q?=20the=20two=20fixtures=20now=20pin=20the=20equivalence=20they?= =?UTF-8?q?=20assert.=20The=20shared=20fixture=20appends=20move=20into=20`?= =?UTF-8?q?appendPreCompactionLog`=20/=20`appendCompactionCheckpoint`.=20`?= =?UTF-8?q?MESSAGE=5FTYPES`=20is=20not=20"human=20message=20event=20types"?= =?UTF-8?q?=20=E2=80=94=20it=20includes=20`assistant/message`.=20Say=20wha?= =?UTF-8?q?t=20the=20code=20distinguishes=20(append-origin=20conversation?= =?UTF-8?q?=20messages=20vs.=20model-only=20replacement=20copies)=20at=20t?= =?UTF-8?q?he=20const,=20the=20`paginate`=20and=20`session.history`=20JSDo?= =?UTF-8?q?c,=20the=20apiproxy=20README,=20and=20the=20Agent=20Note.=20Als?= =?UTF-8?q?o:=20spell=20the=20replace=20shape=20as=20`Extract`=20for=20symmetry=20with=20the=20mo?= =?UTF-8?q?dule's=20two=20other=20uses;=20document=20why=20`isCompactCheck?= =?UTF-8?q?point`=20keeps=20a=20replacement=20check=20that=20is=20redundan?= =?UTF-8?q?t=20at=20both=20call=20sites;=20say=20that=20Ctrl+R=20toggles?= =?UTF-8?q?=20reasoning,=20which=20rebuilds=20the=20transcript;=20and=20qu?= =?UTF-8?q?alify=20"the=20sole=20source=20of=20derived=20history"=20as=20d?= =?UTF-8?q?erived=20*model*=20history=20now=20that=20the=20transcript=20is?= =?UTF-8?q?=20the=20other=20projection.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...9-human-transcript-append-origin.i18n.yaml | 4 +- ...26-07-29-human-transcript-append-origin.md | 4 +- ...07-29-human-transcript-append-origin.zh.md | 4 +- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/session.i18n.yaml | 4 +- docs/core-data-structures/session.md | 5 +- docs/core-data-structures/session.zh.md | 5 +- packages/core/session/src/index.ts | 3 +- packages/core/session/src/surface.ts | 2 +- packages/host/apiproxy/README.i18n.yaml | 4 +- packages/host/apiproxy/README.md | 2 +- packages/host/apiproxy/README.zh.md | 2 +- packages/host/apiproxy/src/api-proxy.ts | 17 +-- packages/host/apiproxy/src/api/sessions.ts | 2 +- packages/ui/tui/src/chat/helpers.ts | 4 + packages/ui/tui/src/index.ts | 6 + .../surface-replayed-compaction.expected.txt | 53 ++++++++ packages/ui/tui/tests/tui.snapshot.ts | 127 +++++++++++------- packages/ui/tui/tests/tui.spec.ts | 6 +- 19 files changed, 180 insertions(+), 76 deletions(-) create mode 100644 packages/ui/tui/tests/snapshots/surface-replayed-compaction.expected.txt diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml index 530d982f0e..c7945bcf78 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md -2026-07-29-human-transcript-append-origin.md: 51602148810b0c400ec7b0f7996b37dd666bf93f -2026-07-29-human-transcript-append-origin.zh.md: 77e9a691f06978ac6875e8f4330d96ecca23a1b5 +2026-07-29-human-transcript-append-origin.md: c4b00dd7093ab1501a83011cf37c9841b15ce1a9 +2026-07-29-human-transcript-append-origin.zh.md: 783baaf47c137d1617c3a983c0a7bb2fa7bc50bb diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md index 5160214881..c4b00dd709 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md @@ -14,11 +14,11 @@ Nothing was lost from the log. `Session.events` still held every original messag Model and human projections are separate, and the event's own marker decides which one an event belongs to. `dsh-session` exports the marker split `isAppendSurfaceEvent(event)` and `isReplacementSurfaceEvent(event)` over the two `SurfaceOp` variants, from the browser-safe `surface` module. Append-origin events are the durable source for a transcript; replacement copies stay model-only. Everything that must send exactly what the model sees — `deriveMessages`, token accounting, the compaction backends, tool pairing, injected-context liveness, cross-session reference projection — keeps reading `session.surface`. -The terminal replays the transcript from append-origin surface events and keeps a shadowed step's tool cards paired through `transcriptToolCallIds`, which reads the append-origin `assistant/message` rather than surface membership. A landed compaction contributes one dim `… earlier context was compacted …` row at its own log position: the marker reports where the model stopped seeing that history instead of erasing it. The framed checkpoint payload never renders, and the replay and live paths share one rule, so a compaction that arrives live and the same log replayed after resume produce the same transcript. +The terminal replays the transcript from append-origin surface events and keeps a shadowed step's tool cards paired through `transcriptToolCallIds`, which reads the append-origin `assistant/message` rather than surface membership. A landed compaction contributes one dim `… earlier context was compacted …` row at its own log position: the marker reports where the model stopped seeing that history instead of erasing it. The framed checkpoint payload never renders, and both paths classify a surface event by the same marker, so a compaction that arrives live and the same log replayed after resume produce the same transcript. Only replay re-derives `tool/call` pairing: a call event carries no marker of its own and inherits membership from the `assistant/message` that advertised it, which the live listener has necessarily just rendered. A checkpoint is recognized through the compaction seam's own contract — `isCompactCheckpointSource`, the backend-independent marker `CompactService` requires on the replacement user message — so the terminal depends on the declared vocabulary, not on the shape of the replacement. `dsh-session-reference` already consumes that predicate to project another session's log; this is the same question asked by a different reader. Other replacements are silent: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation. -`session.history` counts only append-origin human messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it. +`session.history` counts only append-origin messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it. No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required. diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md index 77e9a691f0..783baaf47c 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md @@ -14,11 +14,11 @@ Status: implemented 模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是记录的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。 -终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且回放路径与实时路径共用同一条规则，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。 +终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。 检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。 -`session.history` 只把追加来源的人类消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。 +`session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。 持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。 diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 57b6a5aedf..87ab289fcd 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1590,7 +1590,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:694`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:695`](../../packages/core/session/src/index.ts) ## `ctx.sessionTitle` — `SessionTitleService` diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml index 4f6391518d..f1a8879202 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/docs/core-data-structures/session.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/session.md -session.md: 6ae0ab79b5c7bc3bc1859bf819ce25679672a7f0 -session.zh.md: 79ed40f7eee7a8cae05a366d646f85580c73d5d2 +session.md: 0facaa3583a00e8065535832cf99ac4183694a71 +session.zh.md: 00168b0ebdd1ff9d9be77cba616ef81498c01f37 diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index 6ae0ab79b5..0facaa3583 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -246,7 +246,7 @@ interface SurfaceIntent { } ``` -Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived history. Non-surface types reject it at compile time. +Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived model history. A human-facing transcript is the other projection and reads the log's append-origin events instead, because the surface deliberately shadows the ranges a replacement summarizes (`isAppendSurfaceEvent` in [dsh-session](../../packages/core/session/README.md)). Non-surface types reject it at compile time. The same provenance distinction applies here: only `assistant/message` may carry a present empty `sourceEventSeqs`; omission does not assert that its source stream was empty. @@ -353,7 +353,8 @@ declare class Session { * the ordered surface; `sourceEventSeqs` records provenance (the seq * numbers of events this one derives from). REQUIRED for * {@link SurfaceEventType} events (every message-producing event must - * declare how it joins the surface, the sole source of derived history) and + * declare how it joins the surface, the sole source of derived model + * history) and * rejected by the compiler for non-surface types like `turn/start` or * `assistant/chunk`. * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md index 79ed40f7ee..00168b0ebd 100644 --- a/docs/core-data-structures/session.zh.md +++ b/docs/core-data-structures/session.zh.md @@ -248,7 +248,7 @@ interface SurfaceIntent { } ``` -对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生历史的唯一来源）。非 surface 类型在编译期拒绝此参数。 +对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的记录（transcript）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。 此处适用相同的溯源区分：只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段并不表示其源流为空。 @@ -355,7 +355,8 @@ declare class Session { * the ordered surface; `sourceEventSeqs` records provenance (the seq * numbers of events this one derives from). REQUIRED for * {@link SurfaceEventType} events (every message-producing event must - * declare how it joins the surface, the sole source of derived history) and + * declare how it joins the surface, the sole source of derived model + * history) and * rejected by the compiler for non-surface types like `turn/start` or * `assistant/chunk`. * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index b86bc0285a..ac7ae4963d 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -461,7 +461,8 @@ export class Session { * the ordered surface; `sourceEventSeqs` records provenance (the seq * numbers of events this one derives from). REQUIRED for * {@link SurfaceEventType} events (every message-producing event must - * declare how it joins the surface, the sole source of derived history) and + * declare how it joins the surface, the sole source of derived model + * history) and * rejected by the compiler for non-surface types like `turn/start` or * `assistant/chunk`. * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts index 4b2594d35a..d743387901 100644 --- a/packages/core/session/src/surface.ts +++ b/packages/core/session/src/surface.ts @@ -63,7 +63,7 @@ export function isAppendSurfaceEvent( */ export function isReplacementSurfaceEvent( event: SessionEvent, -): event is SurfaceEvent & { surfaceOp: { op: 'replace'; start: number; end: number } } { +): event is SurfaceEvent & { surfaceOp: Extract } { return isSurfaceEvent(event) && event.surfaceOp !== 'append' } diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 6fb44f9b57..c64479918c 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md -README.md: 190e7f8d36f74bfd7232cc5b4dbb937f265ef1d5 -README.zh.md: 9fb9d24412e950b0648cd07c4b5c73aa0174405c +README.md: 7f5a469b02853642649220e20a093ce98e7bb063 +README.zh.md: ff909cf66f5d3fdf7f10778b094f3203920abb8e diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index 190e7f8d36..7f5a469b02 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -10,7 +10,7 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md). -`session.history` pages on append-origin human-message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it. +`session.history` pages on append-origin message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it. `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface. diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 9fb9d24412..ff909cf66f 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -10,7 +10,7 @@ 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。 -`session.history` 按追加来源的人类消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。 +`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。 diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index df4d02dba8..689f66073f 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -58,17 +58,18 @@ import { openNativePath } from './native-path-opener.ts' /** Page size when history is called without maxMessages. */ const DEFAULT_MAX_MESSAGES = 50 -/** Human message event types (the pagination counting unit). */ +/** Conversation message event types (the pagination counting unit). */ const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message']) /** - * Message-boundary pagination: count maxMessages append-origin human messages - * backwards from the window tail. Replacement copies are model-only, so they - * consume no quota; the page stays one contiguous raw range, which keeps a - * compaction's log-only provenance on the same page as its replacement. The cut - * is the starting seq of the oldest message group (chunks group via - * sourceEventSeqs — never cut mid-message). The tail page naturally includes the - * in-progress partial. + * Message-boundary pagination: count maxMessages append-origin messages + * backwards from the window tail. Replacement copies never entered the + * conversation a reader sees — they restate a shadowed range for the model + * alone — so they consume no quota; the page stays one contiguous raw range, + * which keeps a compaction's log-only provenance on the same page as its + * replacement. The cut is the starting seq of the oldest message group (chunks + * group via sourceEventSeqs — never cut mid-message). The tail page naturally + * includes the in-progress partial. */ function paginate( events: readonly SessionEvent[], diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index 5917555b69..9bcd472911 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -176,7 +176,7 @@ export interface SessionsApi { Promise> /** - * Reads a window of history events; page boundaries align to append-origin human-message + * Reads a window of history events; page boundaries align to append-origin message * boundaries: one page = all raw events owned by a whole number of such messages (including * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail diff --git a/packages/ui/tui/src/chat/helpers.ts b/packages/ui/tui/src/chat/helpers.ts index c9c54b8aa6..3121cbc586 100644 --- a/packages/ui/tui/src/chat/helpers.ts +++ b/packages/ui/tui/src/chat/helpers.ts @@ -109,6 +109,10 @@ export function transcriptToolCallIds(session: Session): Set { * rather than the shape of the replacement. Other replacements (a pruned * `tool/result`, a regenerated `assistant/message`) rewrite one node for the * model and mark no boundary in the conversation. + * + * The replacement check is redundant at both current call sites, which already + * reached a replacement: it keeps the exported predicate true to its name for a + * third caller, rather than making that caller repeat the check. * @param event - event to test. * @returns true when the event compacted a surface range. */ diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index 823d125b1c..e259fec7c2 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -836,6 +836,12 @@ export function createTuiChat( * surface shadows compacted ranges, so it is not the source here: every * append-origin message stays rendered, and a replacement contributes at most * the compaction marker at its own log position. + * + * The `tool/call` pairing check has no live counterpart, because only replay + * can meet an orphan: `tool/call` carries no `surfaceOp` of its own, so it + * inherits transcript membership from the `assistant/message` that advertised + * it, which the live listener has necessarily just rendered. A loaded log is a + * replay boundary, so the pairing is re-derived here instead of assumed. */ const rebuildTranscript = (populateHistory: boolean): void => { chat.clear() diff --git a/packages/ui/tui/tests/snapshots/surface-replayed-compaction.expected.txt b/packages/ui/tui/tests/snapshots/surface-replayed-compaction.expected.txt new file mode 100644 index 0000000000..81460f09b7 --- /dev/null +++ b/packages/ui/tui/tests/snapshots/surface-replayed-compaction.expected.txt @@ -0,0 +1,53 @@ +terminal 104x30 buffer=normal length=30 base=0 viewport=0 +lifecycle started=1 stopped=0 progress=inactive +title "DSH snapshot" +cursor hidden column=7 viewportRow=22 bufferRow=22 +buffer +0| " DEEPSEEK HARNESS" + style 1-8 fg=bright-magenta bold + style 10-16 bold +1| " Snapshot agent ready." + style 1-21 dim +2| " main-session" + style 1-12 dim +3| +4| "Assistant " + style 0-8 fg=bright-magenta bold underline +5| +6| "You " + style 0-2 fg=bright-magenta bold underline +7| "Old prompt with a long line that exercises wrapping and stays visible after compaction. " +8| +9| "● Tool / bash / Run the coverage gate" + style 0-36 fg=green +10| "$ pnpm run test:coverage " + style 0-23 dim +11| "/workspace/project " + style 0-17 dim +12| "packages/ui/tui 100% " + style 0-19 dim +13| "… +1 lines (Ctrl+O to expand) " + style 0-28 dim +14| "1 test skipped " + style 0-13 dim +15| "coverage complete " + style 0-16 dim +16| "[exit 0] " + style 0-7 dim +17| "Model wait 0.0s " + style 0-14 dim +18| +19| "… earlier context was compacted … " + style 0-32 dim +20| +21| "/workspace/project (tui-staging) deepseek-v4-flash ↑0 ↓0 0% context" + style 0-17 fg=bright-magenta bold + style 18-31 dim + style 34-50 dim + style 53-57 dim + style 60-69 dim +22| " dsh > " + style 1-3 fg=bright-magenta bold + style 5-6 dim + style 7-7 inverse +23-29| diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts index b0c63bda04..e4626b1436 100644 --- a/packages/ui/tui/tests/tui.snapshot.ts +++ b/packages/ui/tui/tests/tui.snapshot.ts @@ -51,6 +51,7 @@ const CHECKPOINTS = [ 'surface-before-compaction', 'surface-after-compaction-narrow', 'surface-after-compaction-wide', + 'surface-replayed-compaction', 'model-selector', 'model-selector-filtered', 'model-switching', @@ -182,6 +183,64 @@ function appendToolResult( }, { surfaceOp: 'append' }) } +/** Frozen clock for the compaction fixtures; see the live scenario for why. */ +const COMPACTION_FIXTURE_TIME = new Date(2026, 6, 21, 14, 40, 0).getTime() + +/** The surface range a compaction checkpoint replaces, with its provenance. */ +interface CompactionRange { + start: number + end: number + sources: number[] +} + +/** + * Append one prompt / tool-call / tool-result step, the history a compaction + * shadows on the model surface and the transcript must keep showing. + */ +function appendPreCompactionLog(session: Session): CompactionRange { + const user = session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping and stays visible after compaction.' }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + const assistant = session.append('assistant/message', { + turn: 1, + step: 1, + message: createMessage({ + role: 'assistant', + content: [{ type: 'tool-call', id: CallId('old-tool'), name: 'bash', arguments: '{}' }], + source: { + kind: 'model', + ...{ provider: 'mock', model: 'deepseek-v4-flash' }, + }, + }), + }, { surfaceOp: 'append' }) + session.append('tool/call', { turn: 1, step: 1, callId: CallId('old-tool'), name: 'bash', arguments: '{}' }) + const result = session.append('tool/result', { + turn: 1, + step: 1, + message: createToolResultMessage({ + callId: CallId('old-tool'), + content: [{ type: 'text', text: 'tool output that stays readable after compaction' }], + isError: false, + }), + }, { surfaceOp: 'append' }) + return { start: user.seq, end: result.seq, sources: [user.seq, assistant.seq, result.seq] } +} + +/** Land a compaction: replace the range with the framed model-only checkpoint. */ +function appendCompactionCheckpoint(session: Session, range: CompactionRange): void { + session.append('user/message', createUserMessage({ + content: [{ + type: 'text', + text: '\nModel-only summary payload that must never reach the transcript.\n', + }], + source: COMPACT_CHECKPOINT_SOURCE, + }), { + surfaceOp: { op: 'replace', start: range.start, end: range.end }, + sourceEventSeqs: range.sources, + }) +} + function visualTool( name: string, call: NonNullable, @@ -689,57 +748,18 @@ describe('TUI terminal-state snapshots', () => { // Freeze the clock: the timing header hides zero-duration buckets, so a // real-clock millisecond tick between the fixture appends and the render // would flip `Tools 0.0s` in and out of the pinned header. - const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(new Date(2026, 6, 21, 14, 40, 0).getTime()) - let replacementStart = 0 - let replacementEnd = 0 - let replacementSources: number[] = [] + const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(COMPACTION_FIXTURE_TIME) + // beforeMount runs synchronously inside setupSnapshot, so the range the + // checkpoint replaces is assigned before the first await below. + let compacted!: CompactionRange const harness = await setupSnapshot({ tools: ADVANCED_CARD_TOOLS, - beforeMount(session) { - const user = session.append('user/message', createUserMessage({ - content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping and stays visible after compaction.' }], - source: { kind: 'user' }, - }), { surfaceOp: 'append' }) - const assistant = session.append('assistant/message', { - turn: 1, - step: 1, - message: createMessage({ - role: 'assistant', - content: [{ type: 'tool-call', id: CallId('old-tool'), name: 'bash', arguments: '{}' }], - source: { - kind: 'model', - ...{ provider: 'mock', model: 'deepseek-v4-flash' }, - }, - }), - }, { surfaceOp: 'append' }) - session.append('tool/call', { turn: 1, step: 1, callId: CallId('old-tool'), name: 'bash', arguments: '{}' }) - const result = session.append('tool/result', { - turn: 1, - step: 1, - message: createToolResultMessage({ - callId: CallId('old-tool'), - content: [{ type: 'text', text: 'tool output that stays readable after compaction' }], - isError: false, - }), - }, { surfaceOp: 'append' }) - replacementStart = user.seq - replacementEnd = result.seq - replacementSources = [user.seq, assistant.seq, result.seq] - }, + beforeMount(session) { compacted = appendPreCompactionLog(session) }, }, { columns: 80, rows: 24 }) await checkpoint('surface-before-compaction', harness.terminal, { includeScrollback: true }) await renderAfter(harness, () => { - harness.session.append('user/message', createUserMessage({ - content: [{ - type: 'text', - text: '\nModel-only summary payload that must never reach the transcript.\n', - }], - source: COMPACT_CHECKPOINT_SOURCE, - }), { - surfaceOp: { op: 'replace', start: replacementStart, end: replacementEnd }, - sourceEventSeqs: replacementSources, - }) + appendCompactionCheckpoint(harness.session, compacted) harness.terminal.resize(44, 18) }) await checkpoint('surface-after-compaction-narrow', harness.terminal, { includeScrollback: true }) @@ -750,6 +770,23 @@ describe('TUI terminal-state snapshots', () => { nowSpy.mockRestore() }) + // The resume path, which is what regressed for real users: the replacement is + // already stored when the terminal mounts, so the transcript comes from replay + // rather than from live appends. Pinned against the same log the live scenario + // ends on, at its wide size, so the two fixtures are directly comparable. + it('pins a stored compaction replayed at mount', async () => { + const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(COMPACTION_FIXTURE_TIME) + const harness = await setupSnapshot({ + tools: ADVANCED_CARD_TOOLS, + beforeMount(session) { + appendCompactionCheckpoint(session, appendPreCompactionLog(session)) + }, + }, { columns: 104, rows: 30 }) + await checkpoint('surface-replayed-compaction', harness.terminal, { includeScrollback: true }) + await disposeSnapshot(harness) + nowSpy.mockRestore() + }) + it('pins wrapped and explicit multiline shell-prompt input', async () => { const harness = await setupSnapshot({}, { columns: 44, rows: 18 }) await renderAfter(harness, () => { diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts index 8d88d005a5..4eebfdc01b 100644 --- a/packages/ui/tui/tests/tui.spec.ts +++ b/packages/ui/tui/tests/tui.spec.ts @@ -4449,9 +4449,9 @@ describe('tool cards and surface replay', () => { expect(liveRender).not.toContain('generic replacement copy') expect(liveRender).not.toContain('foreign plugin replacement copy') - // Ctrl+R rebuilds the transcript from the log; the replayed projection - // matches what the live appends produced, including the shadowed assistant - // message's tool card. + // Ctrl+R toggles reasoning, which rebuilds the transcript from the log; the + // replayed projection matches what the live appends produced, including the + // shadowed assistant message's tool card. result.terminal.send('\x12') await tick() result.terminal.resize(90) From b7bb4842df2dc5d9f943ba1eb3bbb4a04d0a1fb9 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 17:43:05 +0800 Subject: [PATCH 14/67] doc(tui): record rebuild cost, replay fixture, and the A2 fold interaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups on b9b2e593f, all documentation precision. The redundancy note on `isCompactCheckpoint` leaned on a reading its call site does not state: `index.ts` reaches it for surface-eligible non-append events, which is the same set as replacements only because the marker is mandatory. Say that instead. The Agent Note now owns three facts it was leaving to a future reader. `rebuildTranscript` materializes a component per append-origin event and runs on mount, color-scheme change, and every reasoning toggle — work compaction used to bound for exactly the long sessions it serves, so the cost now tracks session length rather than the surface. `Consequences` names `surface-replayed-compaction` as the durable evidence for the live/replay equivalence claim, so the two fixtures that must move together are findable from the Note rather than the PR thread. `Deferred` records that a page can now carry a checkpoint whose `surfaceOp.start` fell out of the window: pagination no longer cuts on the checkpoint's provenance group, `FoldAdapter` pads with a non-surface sentinel, and `nodes()` degrades to `degradedSeqs()` — which is already close to the transcript projection A2 should build deliberately. Also corrects the definite-assignment comment in the snapshot scenario: the assertion rests on the awaited setup invoking `beforeMount`, not on that call being synchronous. --- .../2026-07-29-human-transcript-append-origin.i18n.yaml | 4 ++-- .../bug-fix/2026-07-29-human-transcript-append-origin.md | 8 +++++++- .../2026-07-29-human-transcript-append-origin.zh.md | 8 +++++++- packages/ui/tui/src/chat/helpers.ts | 8 +++++--- packages/ui/tui/tests/tui.snapshot.ts | 4 ++-- 5 files changed, 23 insertions(+), 9 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml index c7945bcf78..e329e8c0f1 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md -2026-07-29-human-transcript-append-origin.md: c4b00dd7093ab1501a83011cf37c9841b15ce1a9 -2026-07-29-human-transcript-append-origin.zh.md: 783baaf47c137d1617c3a983c0a7bb2fa7bc50bb +2026-07-29-human-transcript-append-origin.md: 615bec584053bdb775afbe6ad8f726132d75d6c1 +2026-07-29-human-transcript-append-origin.zh.md: d6559f2f08b730f5c7e9550cf5555c36ececd3af diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md index c4b00dd709..615bec5840 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md @@ -24,7 +24,9 @@ No persisted event, RPC envelope, compaction transaction, or model-visible surfa ## Deferred -The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here. +The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. + +That work must handle a page whose checkpoint cites a `surfaceOp.start` outside the window: pagination no longer spends quota on the checkpoint, so it never cuts on the checkpoint's provenance group, and `FoldAdapter` pads absent events with a non-surface sentinel — so `SurfaceManager` rejects the range and `nodes()` falls back to `degradedSeqs()` with a logged error. The hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page. `degradedSeqs()` — every surface-eligible event in append order — is already close to the transcript projection A2 needs, which is the shape to build deliberately rather than reach as a degradation. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here. ## Alternatives considered @@ -42,6 +44,10 @@ The browser client still builds its conversation from the model surface through Compaction no longer erases terminal history; a session compacted several times shows one marker per landed compaction, in log order. Pagination pages can carry more raw events than before, because quota is spent only on messages a human or model actually produced. +`rebuildTranscript` now materializes a component per append-origin event in the whole log, and it runs on mount, on a terminal color-scheme change, and on every reasoning toggle. Compaction used to bound that work for exactly the long sessions compaction serves, so the cost now grows with session length instead of with the surface. That is the trade the fix exists to make — preserved history is the point — but a windowing or reuse strategy belongs to whoever first measures a slow rebuild, not to a later profiler wondering why the work grew. + `dsh-tui` gains a dependency on the `dsh-compact` seam for one pure predicate, mirroring `dsh-session-reference`'s existing use. The terminal still needs no compaction backend at runtime. Two behaviors changed with their tests. The surface-replacement terminal test previously pinned erasure ("hides shadowed tool calls") and now pins preservation plus exactly one marker, including a pruned result copy, a regenerated assistant message, and a foreign plugin's replacement all rendering nothing. The compaction snapshot scenario wrote a `workspace-context` source while claiming to pin compaction; it now writes a real checkpoint source, and its three fixtures are re-recorded to show the preserved prompt, the full tool card, and the marker. + +The live/replay equivalence above is fixture-pinned, not only asserted here: `surface-replayed-compaction` mounts with the replacement already stored and records byte-identical to the live path's `surface-after-compaction-wide`. Changing either path breaks that equality, which is the point — the resume projection is what regressed for users, and the two fixtures must move together. diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md index 783baaf47c..d6559f2f08 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md @@ -24,7 +24,9 @@ Status: implemented ## Deferred -浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。 +浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。 + +该工作必须处理这样一页：其检查点引用的 `surfaceOp.start` 落在窗口之外。分页不再为检查点消耗额度，因此永远不会按检查点的溯源分组切分；而 `FoldAdapter` 会用一个非 surface 的哨兵事件填补缺失事件——于是 `SurfaceManager` 拒绝该范围，`nodes()` 退化为 `degradedSeqs()` 并记录一条错误。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。`degradedSeqs()`——按追加顺序的每个 surface 可入事件——已经很接近 A2 所需的记录投影，因此那正是应当刻意构建的形态，而不是作为退化路径被动落到的结果。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。 ## Alternatives considered @@ -42,6 +44,10 @@ Status: implemented 压缩不再抹掉终端历史；被压缩多次的会话会按日志顺序显示每次落地压缩对应的一行标记。分页的每一页可以携带比以前更多的原始事件，因为额度只花在人类或模型真正产生的消息上。 +`rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换 reasoning 时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。 + `dsh-tui` 为一个纯谓词新增了对 `dsh-compact` 接缝的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。 两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（“隐藏被遮蔽的工具调用”），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture，以显示被保留的提示、完整的工具卡片和那行标记。 + +上文的实时／回放等价性由 fixture 钉住，而不只是在此断言：`surface-replayed-compaction` 在挂载时替换已经存在，其录制结果与实时路径的 `surface-after-compaction-wide` 逐字节一致。改动任一路径都会破坏这项相等——这正是要点：回放投影才是当初对用户造成回归的部分，两份 fixture 必须一起变动。 diff --git a/packages/ui/tui/src/chat/helpers.ts b/packages/ui/tui/src/chat/helpers.ts index 3121cbc586..e411ce27c9 100644 --- a/packages/ui/tui/src/chat/helpers.ts +++ b/packages/ui/tui/src/chat/helpers.ts @@ -110,9 +110,11 @@ export function transcriptToolCallIds(session: Session): Set { * `tool/result`, a regenerated `assistant/message`) rewrite one node for the * model and mark no boundary in the conversation. * - * The replacement check is redundant at both current call sites, which already - * reached a replacement: it keeps the exported predicate true to its name for a - * third caller, rather than making that caller repeat the check. + * The replacement check is redundant at both current call sites, because a + * surface-eligible non-append event is a replacement: the marker is mandatory, + * so `Session.append` and the replay fold reject an event that carries none. + * The check keeps the exported predicate true to its name for a third caller, + * rather than making that caller repeat it. * @param event - event to test. * @returns true when the event compacted a surface range. */ diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts index e4626b1436..f563c88b16 100644 --- a/packages/ui/tui/tests/tui.snapshot.ts +++ b/packages/ui/tui/tests/tui.snapshot.ts @@ -749,8 +749,8 @@ describe('TUI terminal-state snapshots', () => { // real-clock millisecond tick between the fixture appends and the render // would flip `Tools 0.0s` in and out of the pinned header. const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(COMPACTION_FIXTURE_TIME) - // beforeMount runs synchronously inside setupSnapshot, so the range the - // checkpoint replaces is assigned before the first await below. + // The awaited setup always invokes beforeMount, so the range the checkpoint + // replaces is assigned by the time the appends below need it. let compacted!: CompactionRange const harness = await setupSnapshot({ tools: ADVANCED_CARD_TOOLS, From b0c7a4f324fb787a05cf53199a10b520815f45fc Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 17:56:24 +0800 Subject: [PATCH 15/67] refactor(tui): classify replay by marker, matching the live listener MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The replay loop spelled the classification as `isSurfaceEligibleType(event.type) && !isAppendSurfaceEvent(event)` while the live listener used `isReplacementSurfaceEvent(event)`. Under the mandatory-marker invariant these select the same set: the only divergence is a surface-eligible event carrying no marker, which no active Session can hold — `Session.append` and the seed construction loop both reject it through the same `planSurfaceEvent`. Using the same predicate on both paths makes "both paths classify a surface event by the same marker" structural rather than argued, and retires the TUI's last `isSurfaceEligibleType` use. No behavior change: the TUI suite and all 113 snapshot fixtures pass unchanged. --- packages/ui/tui/src/index.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts index e259fec7c2..8a6f8213ce 100644 --- a/packages/ui/tui/src/index.ts +++ b/packages/ui/tui/src/index.ts @@ -35,9 +35,7 @@ import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-llm-retry' import { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import { - isAppendSurfaceEvent, isReplacementSurfaceEvent, - isSurfaceEligibleType, SessionId, type SessionEvent, type UserMessage, @@ -852,7 +850,7 @@ export function createTuiChat( todo.update([]) const transcriptCalls = transcriptToolCallIds(agent.session) for (const event of agent.session.events) { - if (isSurfaceEligibleType(event.type) && !isAppendSurfaceEvent(event)) { + if (isReplacementSurfaceEvent(event)) { if (isCompactCheckpoint(event)) renderCompactionMarker() continue } From fc5e2632d6349f04009f2eb6cfcbcdeaade0a428 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 18:16:31 +0800 Subject: [PATCH 16/67] doc(tui): drop a stale justification and clarify the fixture's tool text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two comment-only corrections from the final review round. The `isCompactCheckpoint` redundancy note appealed to the mandatory-marker invariant to explain something the enclosing branch now states outright: after e029ffb88 both call sites are literally inside an `isReplacementSurfaceEvent` branch, so the appeal became retained reasoning. Say the call sites test it directly. `appendPreCompactionLog` implied its tool-result content is what survives compaction, but `bash`'s presenter is static, so the string never reaches a fixture — the fixtures pin that the shadowed step's card survives. Neutral text plus a note on where the card body comes from, so a later reader does not "fix" a fixture to make the sentence true. Verified by the absence of fixture drift from changing the string. --- packages/ui/tui/src/chat/helpers.ts | 8 +++----- packages/ui/tui/tests/tui.snapshot.ts | 7 +++++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/packages/ui/tui/src/chat/helpers.ts b/packages/ui/tui/src/chat/helpers.ts index e411ce27c9..08e6fa050f 100644 --- a/packages/ui/tui/src/chat/helpers.ts +++ b/packages/ui/tui/src/chat/helpers.ts @@ -110,11 +110,9 @@ export function transcriptToolCallIds(session: Session): Set { * `tool/result`, a regenerated `assistant/message`) rewrite one node for the * model and mark no boundary in the conversation. * - * The replacement check is redundant at both current call sites, because a - * surface-eligible non-append event is a replacement: the marker is mandatory, - * so `Session.append` and the replay fold reject an event that carries none. - * The check keeps the exported predicate true to its name for a third caller, - * rather than making that caller repeat it. + * Both current call sites already test the replacement themselves. The check + * keeps the exported predicate true to its name for a third caller, rather than + * making that caller repeat it. * @param event - event to test. * @returns true when the event compacted a surface range. */ diff --git a/packages/ui/tui/tests/tui.snapshot.ts b/packages/ui/tui/tests/tui.snapshot.ts index f563c88b16..09ff6ba26e 100644 --- a/packages/ui/tui/tests/tui.snapshot.ts +++ b/packages/ui/tui/tests/tui.snapshot.ts @@ -195,7 +195,10 @@ interface CompactionRange { /** * Append one prompt / tool-call / tool-result step, the history a compaction - * shadows on the model surface and the transcript must keep showing. + * shadows on the model surface and the transcript must keep showing. The prompt + * text is rendered verbatim; the tool card's body comes from `bash`'s static + * presenter, so the fixtures pin that the shadowed step's card survives rather + * than the result content below. */ function appendPreCompactionLog(session: Session): CompactionRange { const user = session.append('user/message', createUserMessage({ @@ -220,7 +223,7 @@ function appendPreCompactionLog(session: Session): CompactionRange { step: 1, message: createToolResultMessage({ callId: CallId('old-tool'), - content: [{ type: 'text', text: 'tool output that stays readable after compaction' }], + content: [{ type: 'text', text: 'shadowed step tool output' }], isError: false, }), }, { surfaceOp: 'append' }) From fff0eae0ca8055848b624e01cd0b38fb2d964d77 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 18:27:26 +0800 Subject: [PATCH 17/67] doc: regenerate the cordis services catalog The `ctx.tui` source line moved when e029ffb88 retired two imports from `packages/ui/tui/src/index.ts`. Regenerated; `verify-cordis-catalog` is green again, which is the gate CI caught. --- docs/cordis-catalog/services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 87ab289fcd..1f27744341 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -2174,7 +2174,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession ``` -Source: [`packages/ui/tui/src/index.ts:250`](../../packages/ui/tui/src/index.ts) +Source: [`packages/ui/tui/src/index.ts:248`](../../packages/ui/tui/src/index.ts) ## `ctx.userInteraction` — `UserInteractionService` From c249ad8253c8ec834015fc25fb5e22d29182cb77 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Wed, 29 Jul 2026 18:28:47 +0800 Subject: [PATCH 18/67] doc: record the marker-scale plan with its refactor prerequisite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Marker scale was deferred in a resolved review thread but only the compaction-progress half was written down. Deferred now names it, says where the count comes from (`sourceEventSeqs`), and why it belongs with progress rather than here. Adds the prerequisite: the terminal's replay and live replacement branches are textually identical and 600 lines apart, so marker content needs one home — fold them into a single `renderReplacement(event)` before giving the row a payload that must stay consistent across both paths. --- .../2026-07-29-human-transcript-append-origin.i18n.yaml | 4 ++-- .../bug-fix/2026-07-29-human-transcript-append-origin.md | 2 +- .../bug-fix/2026-07-29-human-transcript-append-origin.zh.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml index e329e8c0f1..edb6ac6e4a 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md -2026-07-29-human-transcript-append-origin.md: 615bec584053bdb775afbe6ad8f726132d75d6c1 -2026-07-29-human-transcript-append-origin.zh.md: d6559f2f08b730f5c7e9550cf5555c36ececd3af +2026-07-29-human-transcript-append-origin.md: a296b93d538d9c28bd61ee8fd0530863b4bfd878 +2026-07-29-human-transcript-append-origin.zh.md: 96e0cd1038fe8904dfd4c1eceaae9b25339c5dca diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md index 615bec5840..a296b93d53 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md @@ -26,7 +26,7 @@ No persisted event, RPC envelope, compaction transaction, or model-visible surfa The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. -That work must handle a page whose checkpoint cites a `surfaceOp.start` outside the window: pagination no longer spends quota on the checkpoint, so it never cuts on the checkpoint's provenance group, and `FoldAdapter` pads absent events with a non-surface sentinel — so `SurfaceManager` rejects the range and `nodes()` falls back to `degradedSeqs()` with a logged error. The hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page. `degradedSeqs()` — every surface-eligible event in append order — is already close to the transcript projection A2 needs, which is the shape to build deliberately rather than reach as a degradation. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here. +That work must handle a page whose checkpoint cites a `surfaceOp.start` outside the window: pagination no longer spends quota on the checkpoint, so it never cuts on the checkpoint's provenance group, and `FoldAdapter` pads absent events with a non-surface sentinel — so `SurfaceManager` rejects the range and `nodes()` falls back to `degradedSeqs()` with a logged error. The hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page. `degradedSeqs()` — every surface-eligible event in append order — is already close to the transcript projection A2 needs, which is the shape to build deliberately rather than reach as a degradation. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here. The marker also carries no scale: the checkpoint's `sourceEventSeqs` already hold the shadowed count, so a count or range would tell a reader how much each row folded. That belongs with progress, where the reader meets the other half of the same information. Whoever takes it should fold the terminal's two replacement branches — replay and the live listener, textually identical and 600 lines apart — into one `renderReplacement(event)` first, so the marker's content has a single home. ## Alternatives considered diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md index d6559f2f08..96e0cd1038 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md @@ -26,7 +26,7 @@ Status: implemented 浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。 -该工作必须处理这样一页：其检查点引用的 `surfaceOp.start` 落在窗口之外。分页不再为检查点消耗额度，因此永远不会按检查点的溯源分组切分；而 `FoldAdapter` 会用一个非 surface 的哨兵事件填补缺失事件——于是 `SurfaceManager` 拒绝该范围，`nodes()` 退化为 `degradedSeqs()` 并记录一条错误。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。`degradedSeqs()`——按追加顺序的每个 surface 可入事件——已经很接近 A2 所需的记录投影，因此那正是应当刻意构建的形态，而不是作为退化路径被动落到的结果。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。 +该工作必须处理这样一页：其检查点引用的 `surfaceOp.start` 落在窗口之外。分页不再为检查点消耗额度，因此永远不会按检查点的溯源分组切分；而 `FoldAdapter` 会用一个非 surface 的哨兵事件填补缺失事件——于是 `SurfaceManager` 拒绝该范围，`nodes()` 退化为 `degradedSeqs()` 并记录一条错误。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。`degradedSeqs()`——按追加顺序的每个 surface 可入事件——已经很接近 A2 所需的记录投影，因此那正是应当刻意构建的形态，而不是作为退化路径被动落到的结果。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。标记同样不携带规模信息：检查点的 `sourceEventSeqs` 已经包含被遮蔽的数量，因此一个计数或区间可以告诉读者每一行折叠了多少内容。这件事属于进度那一侧，读者正是在那里遇到同一份信息的另一半。接手者应当先把终端里两处替换分支——回放与实时监听器，文本完全相同却相隔 600 行——合并为一个 `renderReplacement(event)`，让标记的内容只有一个归处。 ## Alternatives considered From 8cec74748bb4b894a7a2c139b0cd227d232ecaa1 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Wed, 29 Jul 2026 18:34:06 +0800 Subject: [PATCH 19/67] feat(host): adaptive directory-picker default via -auto chooser Add @deepseek-ai/dsh-host-directory-picker-auto, a node-half-only chooser that samples the host situation once at boot (bind host via a new httpServer.host getter, SSH markers, platform, DISPLAY/WAYLAND_DISPLAY) and mounts the matching dual-face backend (-native or -browse) as a real Loader entry in the in-memory root tree; the effect disposer removes it. Entry-level mounting keeps the seam's one-row-swaps-both-faces invariant: the client module table discovers the mounted backend's browser half exactly as a config row's. apps/cli now composes -auto as its directory-picker row; composing a backend row directly remains the pin. --- ...directory-picker-capability-seam.i18n.yaml | 4 +- ...-07-28-directory-picker-capability-seam.md | 2 +- ...-28-directory-picker-capability-seam.zh.md | 2 +- ...irectory-picker-adaptive-default.i18n.yaml | 6 + ...07-29-directory-picker-adaptive-default.md | 29 ++++ ...29-directory-picker-adaptive-default.zh.md | 29 ++++ apps/cli/cordis.yml | 13 +- apps/cli/package.json | 1 + docs/config-catalog.md | 1 + packages/host/README.i18n.yaml | 4 +- packages/host/README.md | 1 + packages/host/README.zh.md | 1 + .../directory-picker-auto/README.i18n.yaml | 6 + packages/host/directory-picker-auto/README.md | 20 +++ .../host/directory-picker-auto/README.zh.md | 20 +++ .../host/directory-picker-auto/package.json | 47 ++++++ .../host/directory-picker-auto/src/index.ts | 52 +++++++ .../directory-picker-auto/src/invariant.ts | 25 ++++ .../host/directory-picker-auto/src/resolve.ts | 46 ++++++ .../tests/loader-composition.spec.ts | 139 ++++++++++++++++++ .../tests/resolve.spec.ts | 37 +++++ .../host/directory-picker-auto/tsconfig.json | 27 ++++ .../host/directory-picker/README.i18n.yaml | 4 +- packages/host/directory-picker/README.md | 2 +- packages/host/directory-picker/README.zh.md | 2 +- packages/host/webserver/README.i18n.yaml | 4 +- packages/host/webserver/README.md | 2 +- packages/host/webserver/README.zh.md | 2 +- packages/host/webserver/src/index.ts | 5 + pnpm-lock.yaml | 30 ++++ .../verify-package-readme-model-experience.ts | 1 + tsconfig.host.json | 8 + 32 files changed, 553 insertions(+), 19 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md create mode 100644 .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md create mode 100644 packages/host/directory-picker-auto/README.i18n.yaml create mode 100644 packages/host/directory-picker-auto/README.md create mode 100644 packages/host/directory-picker-auto/README.zh.md create mode 100644 packages/host/directory-picker-auto/package.json create mode 100644 packages/host/directory-picker-auto/src/index.ts create mode 100644 packages/host/directory-picker-auto/src/invariant.ts create mode 100644 packages/host/directory-picker-auto/src/resolve.ts create mode 100644 packages/host/directory-picker-auto/tests/loader-composition.spec.ts create mode 100644 packages/host/directory-picker-auto/tests/resolve.spec.ts create mode 100644 packages/host/directory-picker-auto/tsconfig.json diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index bb9425fa64..0500ccfb3f 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: 7c8f8cb67690cb4c5858cefb52b8cd79e649ec38 -2026-07-28-directory-picker-capability-seam.zh.md: 05545fc3cd758523814b31afa705249972d86464 +2026-07-28-directory-picker-capability-seam.md: c44717d46445a992e563497ed011930a6044a1bb +2026-07-28-directory-picker-capability-seam.zh.md: 42fedf64ba97fed032c4847b68ce321ae32dc463 diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index 7c8f8cb676..c44717d464 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -33,7 +33,7 @@ Placement and policy rulings folded into this decision: ## Consequences -- `cordis.yml` chooses the interaction; `apps/cli` mounts `-browse` (the shipped default — remote-capable picking out of the box), one row having swapped backend and UI together; `-native` remains the host-display alternative. +- `cordis.yml` chooses the interaction; `apps/cli` mounts the [`-auto` chooser](../feature/2026-07-29-directory-picker-adaptive-default.md), which resolves the host's situation at boot and mounts `-native` or `-browse` itself, one row still swapping backend and UI together; composing a backend row directly pins the interaction. - The wire gains `host.listDirectory`/`host.createDirectory` and four error codes; the connection fixture serves a deterministic browse tree and a deterministic `pickDirectory` path for keyless assembled tests. - A future interaction (or an Electron provider of the `native` interaction) is one dual-face backend package — no gateway surgery, no ui-workspace edits. - `ApiProxyDefaults.pickDirectory` (test-only injection) is gone; tests provide a stub `ctx.directoryPicker` like any other service. diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 05545fc3cd..42fedf64ba 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -33,7 +33,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick ## 后果 -- `cordis.yml` 决定交互形态；`apps/cli` 挂 `-browse`（随附默认——开箱即得可远程的选取），一行同时切换了后端与 UI；`-native` 仍是宿主屏幕方案。 +- `cordis.yml` 决定交互形态；`apps/cli` 挂 [`-auto` 选择器](../feature/2026-07-29-directory-picker-adaptive-default.md)，它在启动时判定宿主处境并自行挂载 `-native` 或 `-browse`，一行仍同时切换后端与 UI；直接组合某个后端行即固定交互。 - 协议新增 `host.listDirectory`／`host.createDirectory` 与四个错误码；connection fixture 提供确定性浏览树与确定性 `pickDirectory` 路径供无密钥组装测试使用。 - 未来的新交互（或提供 `native` 交互的 Electron 实现）只是一个双面后端包——无需网关手术，也不动 ui-workspace。 - `ApiProxyDefaults.pickDirectory`（仅测试注入）删除；测试像提供其他服务一样提供 stub `ctx.directoryPicker`。 diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml new file mode 100644 index 0000000000..cd921886f6 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md +2026-07-29-directory-picker-adaptive-default.md: ae5748259f162503300360d6cca43bec996afdb6 +2026-07-29-directory-picker-adaptive-default.zh.md: acabeb80604b473289fa441e6d9d913e4a8f87d0 diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md new file mode 100644 index 0000000000..ae5748259f --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md @@ -0,0 +1,29 @@ +# Agent Note: Adaptive default for the directory-picker interaction + +Status: implemented + +English | [中文](2026-07-29-directory-picker-adaptive-default.zh.md) + +## Problem + +The [directory-picker seam](../architecture/2026-07-28-directory-picker-capability-seam.md) made the interaction a `cordis.yml` swap point, but the shipped composition still had to pin one backend: `-browse` everywhere meant a local operator never got the OS chooser, `-native` everywhere breaks every remote deployment. The right default depends on facts only the running host knows — where the server binds, whether the process was launched over SSH, whether a display session exists — so no static row is correct for all deployments. + +## Decision + +A third sibling package, **`dsh-host-directory-picker-auto`**: a node-half-only *chooser* that owns no picking code and no UI. Its `apply` samples the host facts exactly once at boot — bind host from the injected `httpServer` (a new `host` getter mirrors the existing `port`), `SSH_CONNECTION`/`SSH_TTY`, platform, `DISPLAY`/`WAYLAND_DISPLAY` — resolves them through one exported pure function, and mounts the chosen dual-face backend with `ctx.loader.create({name})` into the Loader's **in-memory root tree**; the effect's disposer removes the entry again. `native` requires every attended-host signal (loopback bind ∧ no SSH markers ∧ display session, assumed on darwin/win32); anything ambiguous resolves to `browse`, which works everywhere. `apps/cli` now mounts `-auto` as its `directory-picker` row; composing `-native` or `-browse` directly remains the pin. + +Why entry-level mounting is the load-bearing mechanism: the client module table (`dsh-client-modules`) reconciles **Loader entries** reactively over `internal/plugin`, so a backend mounted as a real entry gets its browser half discovered exactly as a config-row's would be — the seam's one-row-swaps-both-faces invariant survives adaptivity with zero duplicated client code. The dev HMR row (`AppCLIEntry`) is the mechanism precedent. Root-tree targeting matters: the root tree's `write()` is a no-op, so the resolved row can never be persisted back into `cordis.yml` (the Include subtree *does* write). + +## Alternatives considered + +- **Boot-glue resolution in `AppCLIEntry`** (ship both rows with static `disabled`, patch `disabled` from a `--directory-picker=auto|native|browse` flag). Works — `PatchOptions` patches metadata, and the modules scan skips disabled rows — but leaves the decision app-private where every future composition re-implements it; the chooser plugin gives any `cordis.yml` the same one-row adaptivity. Reintroduce the flag only when a deployment needs to *force* a backend without editing its yml. +- **One merged plugin branching per call** (client tries `pick`, falls back to the browse dialog on `directory-picker-unavailable`). Rejected: the client would need both flows in one bundle — the bundle-purity gate forbids cross-plugin value imports and jscpd forbids copying the dialog — and per-call probing pays a doomed RPC on every open of a browse host. +- **Resurrecting the wire advertisement** so both client flows mount and branch on the host's kind. Rejected: reverses the seam note's deletion for no consumer the chooser doesn't already serve, and collides with the `single` directory-flow holes. +- **Per-connection adaptivity** (native for a loopback browser, browse for a remote one, same server). Deferred: needs a per-client capability, the advertisement above, and both flows mounted; no deployment serves both operator shapes at once today. + +## Consequences + +- The shipped web GUI adapts out of the box: attended local host → OS chooser; SSH launch, all-interfaces bind, or headless host → in-app browser. Detection is a heuristic (a detached tmux session loses `SSH_*`; a non-Aqua darwin process still counts as displayed) — a wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` pins the safe interaction. +- One resolution per boot keeps the seam's capability-stability contract; per-connection shapes remain out of scope until a deployment demands them. +- Mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service; duplicate flow in the `single` holes). +- The host typecheck aggregate now references the two backend projects (declarations only, node entries carry no client merge) so the chooser's REAL-composition test can mount them — the mirror of the client aggregate's `webserver` reference. diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md new file mode 100644 index 0000000000..acabeb8060 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md @@ -0,0 +1,29 @@ +# Agent Note：目录选择交互的自适应默认值 + +状态：已实现 + +[English](2026-07-29-directory-picker-adaptive-default.md) | 中文 + +## 问题 + +[目录选择 seam](../architecture/2026-07-28-directory-picker-capability-seam.md)把交互形态做成了 `cordis.yml` 的切换点，但随附的组合仍必须固定一个后端：处处用 `-browse` 意味着本地操作者永远得不到 OS 选择器，处处用 `-native` 则弄坏所有远程部署。正确的默认值取决于只有运行中的宿主才知道的事实——服务器绑定在哪里、进程是否经 SSH 启动、是否存在显示会话——因此没有哪一静态行对所有部署都正确。 + +## 决策 + +第三个同级包 **`dsh-host-directory-picker-auto`**：一个只有 node 半侧的*选择器*，不持有任何选取代码，也没有 UI。它的 `apply` 在启动时恰好采样一次宿主事实——从注入的 `httpServer` 读绑定宿主（新增的 `host` getter 与既有的 `port` 对称）、`SSH_CONNECTION`／`SSH_TTY`、平台、`DISPLAY`／`WAYLAND_DISPLAY`——经由一个导出的纯函数判定，再用 `ctx.loader.create({name})` 把选中的双面后端挂进 Loader 的**内存根树**；该 effect 的 disposer 会再次移除该条目。`native` 要求全部有人值守宿主信号（回环绑定 ∧ 无 SSH 标记 ∧ 显示会话，darwin／win32 上视为存在）；任何含糊情形都判定为处处可用的 `browse`。`apps/cli` 现在把 `-auto` 挂为它的 `directory-picker` 行；直接组合 `-native` 或 `-browse` 仍是固定交互的方式。 + +条目级挂载之所以是承重机制：client 模块表（`dsh-client-modules`）基于 `internal/plugin` 对 **Loader 条目**做响应式协调，因此以真实条目挂载的后端，其 browser half 被发现的方式与配置行完全相同——seam 的“一行同时换两面”不变式在自适应下依然成立，且没有一行重复的 client 代码。开发环境的 HMR 行（`AppCLIEntry`）是该机制的先例。瞄准根树很关键：根树的 `write()` 是 no-op，因此判定出的行绝不会被持久化回 `cordis.yml`（Include 子树*会*写回）。 + +## 曾考虑的替代方案 + +- **在 `AppCLIEntry` 里做启动胶水判定**（随附两行并带静态 `disabled`，由 `--directory-picker=auto|native|browse` 标志修补 `disabled`）。可行——`PatchOptions` 能修补元数据，模块扫描也会跳过禁用行——但把决策留成应用私有，此后每个组合都要重新实现；选择器插件让任何 `cordis.yml` 都获得同样的一行自适应。只有当某个部署需要不改自己的 yml 就*强制*指定后端时，才重新引入该标志。 +- **合并成一个按调用分支的插件**（client 先试 `pick`，收到 `directory-picker-unavailable` 再回退到浏览对话框）。否决：client 得把两套流程装进同一个 bundle——bundle 纯净门禁禁止跨插件的值导入，jscpd 禁止复制对话框——而且按调用探测让 browse 宿主每次打开都付出一次注定失败的 RPC。 +- **复活 wire 广播**，让两套 client 流程都挂载并按宿主的 kind 分支。否决：推翻 seam Agent Note 的那次删除，却服务不了任何选择器尚未服务的消费方，还与 `single` 目录流洞相冲突。 +- **按连接自适应**（同一台服务器，回环浏览器用 native、远程浏览器用 browse）。延期：需要按客户端的能力对象、上述广播，以及同时挂载两套流程；今天没有部署同时服务两种操作者形态。 + +## 后果 + +- 随附的 web GUI 开箱即自适应：有人值守的本地宿主 → OS 选择器；SSH 启动、全网卡绑定或无头宿主 → 应用内浏览器。探测是启发式的（脱离的 tmux 会话会丢失 `SSH_*`；非 Aqua 的 darwin 进程仍被算作有显示）——错误的 `native` 选择会退化为后端既有的可重试失败对话框，组合 `-browse` 即固定住安全的交互。 +- 每次启动只判定一次，维持 seam 的能力稳定性契约；按连接的形态在有部署提出需求前仍不在范围内。 +- 同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务；`single` 洞中的重复流程）。 +- host 类型检查聚合现在引用两个后端项目（仅声明，node 入口不携带 client 合并），使选择器的 REAL-composition 测试能挂载它们——与 client 聚合对 `webserver` 的引用互为镜像。 diff --git a/apps/cli/cordis.yml b/apps/cli/cordis.yml index ed44f75c7f..d9cbd4b08a 100644 --- a/apps/cli/cordis.yml +++ b/apps/cli/cordis.yml @@ -314,12 +314,15 @@ # The API gateway: the transport-agnostic dispatch face every client shape # shares. provider/model are the host default routing — the profile json's # mapping target (user config overrides these engineering defaults). -# Directory-picking package, dual-face: the node half serves the gateway's -# host.* picker RPCs, the browser half fills ui-workspace's directory-flow -# slots — one row composes the whole interaction. Swap point: mount -# '-native' instead for the host-display OS chooser. +# Directory-picking composition, adaptive default: the chooser resolves the +# host's situation once at boot (bind host, SSH launch, display session) and +# mounts the matching dual-face backend row — its node half serves the +# gateway's host.* picker RPCs, its browser half fills ui-workspace's +# directory-flow slots. Swap point: mount '-native' (host-display OS chooser) +# or '-browse' (in-app browsing, remote-capable) directly to pin the +# interaction. - id: directory-picker - name: '@deepseek-ai/dsh-host-directory-picker-browse' + name: '@deepseek-ai/dsh-host-directory-picker-auto' - id: api-gateway name: '@deepseek-ai/dsh-host-apiproxy' diff --git a/apps/cli/package.json b/apps/cli/package.json index 0914aaf5aa..4538d326cf 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -54,6 +54,7 @@ "@deepseek-ai/dsh-goal": "workspace:^", "@deepseek-ai/dsh-goal-session": "workspace:^", "@deepseek-ai/dsh-host-apiproxy": "workspace:^", + "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^", "@deepseek-ai/dsh-host-webserver": "workspace:^", diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 3c0543e4ca..8a169a4dbe 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -2224,6 +2224,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts)) - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts)) - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts)) +- `@deepseek-ai/dsh-host-directory-picker-auto` — requires `httpServer` · `loader` ([`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts)) - `@deepseek-ai/dsh-host-directory-picker-native` ([`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts)) - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)) - `@deepseek-ai/dsh-lsp` ([`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts)) diff --git a/packages/host/README.i18n.yaml b/packages/host/README.i18n.yaml index afc0e2a695..cd09dca013 100644 --- a/packages/host/README.i18n.yaml +++ b/packages/host/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/README.md -README.md: d44770f70be16c12f44b78155089e092a3e9bba0 -README.zh.md: 2b6878b08be6489dcd510a0a0e0f0e833c2a8014 +README.md: 4f56afc45d594bf1f3f0784b848958cf62f52ae5 +README.zh.md: 888301282e272966b9d99e299b893afc90670906 diff --git a/packages/host/README.md b/packages/host/README.md index d44770f70b..4f56afc45d 100644 --- a/packages/host/README.md +++ b/packages/host/README.md @@ -11,5 +11,6 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and | `directory-picker/` | Workspace-directory picking seam: discriminated `native`/`browse` capability the gateway's picker RPCs delegate to | `ctx.directoryPicker` | | `directory-picker-native/` | Dual-face native interaction: OS-chooser backend (osascript / PowerShell / Zenity+KDialog, host-display only) + the browser half filling ui-workspace's directory-flow slots | (registers `ctx.directoryPicker`) | | `directory-picker-browse/` | Dual-face browse interaction: listing/creation primitives over Node stdlib (remote-capable) + the browser half rendering the in-app Select Workspace Directory dialog | (registers `ctx.directoryPicker`) | +| `directory-picker-auto/` | Adaptive chooser: resolves the host's situation once at boot (bind host, SSH, display) and mounts the matching dual-face backend as an in-memory Loader entry | (mounts a backend row) | `apiproxy` is transport-agnostic by design — it registers no routes; carriers wrap `ctx.apiProxy` themselves. The HTTP carrier route (with its `/api` browser-trust fence) is mounted by [`client/connection`](../client/connection/README.md)'s node half, which is why that package lives in the client group: it owns both ends of the wire. diff --git a/packages/host/README.zh.md b/packages/host/README.zh.md index 2b6878b08b..888301282e 100644 --- a/packages/host/README.zh.md +++ b/packages/host/README.zh.md @@ -11,5 +11,6 @@ dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承 | `directory-picker/` | 工作区目录选择 seam：网关的 picker RPC 委托的可辨识 `native`／`browse` 能力 | `ctx.directoryPicker` | | `directory-picker-native/` | 双面原生交互：OS 选择器后端（osascript／PowerShell／Zenity+KDialog，仅宿主屏幕可用）+ 填入 ui-workspace 目录流 slot 的 browser half | （注册 `ctx.directoryPicker`） | | `directory-picker-browse/` | 双面浏览交互：基于 Node 标准库的列举／创建原语（可远程）+ 渲染应用内选择工作区目录对话框的 browser half | （注册 `ctx.directoryPicker`） | +| `directory-picker-auto/` | 自适应选择器：启动时一次性判定宿主处境（绑定宿主、SSH、显示），并把匹配的双面后端挂载为内存中的 Loader 条目 | （挂载一个后端行） | `apiproxy` 在设计上与传输方式无关——它不注册任何路由；载体自行包装 `ctx.apiProxy`。HTTP 载体路由（连同其 `/api` 浏览器信任栅栏）由 [`client/connection`](../client/connection/README.md) 的 node 半侧挂载，这正是该包住在 client 组的原因：它拥有这条线的两端。 diff --git a/packages/host/directory-picker-auto/README.i18n.yaml b/packages/host/directory-picker-auto/README.i18n.yaml new file mode 100644 index 0000000000..fa4907698b --- /dev/null +++ b/packages/host/directory-picker-auto/README.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write packages/host/directory-picker-auto/README.md +README.md: 73692d1fb5af1e7b23b2a99d0a5cd48507f68ce5 +README.zh.md: 5bc9ced01f86d021db256df2c9e69e97ec6a7ab1 diff --git a/packages/host/directory-picker-auto/README.md b/packages/host/directory-picker-auto/README.md new file mode 100644 index 0000000000..73692d1fb5 --- /dev/null +++ b/packages/host/directory-picker-auto/README.md @@ -0,0 +1,20 @@ +# @deepseek-ai/dsh-host-directory-picker-auto + +English | [中文](README.zh.md) + +The **adaptive chooser** of the [directory-picker seam](../directory-picker/README.md): a node-half-only plugin that resolves the host's situation once at boot and mounts the matching dual-face backend — [`-native`](../directory-picker-native/README.md) or [`-browse`](../directory-picker-browse/README.md) — as a real Loader entry in the in-memory root tree (never persisted to a config file; the root tree's `write()` is a no-op). Because the backend arrives as an ordinary entry, its browser half is discovered by the client module table exactly as a config-row's would be, so the seam's one-row-swaps-both-faces invariant holds for the resolved choice. Unloading the chooser removes the entry again, unloading both faces with it. + +Resolution is one pure boot-time sample (`resolveDirectoryPickerBackend`), exported for reuse and tests. `native` requires every signal that the operator can see the host display: a loopback-only bind (read from the injected `httpServer`; an all-interfaces bind admits remote browsers no OS chooser can reach), no SSH launch (`SSH_CONNECTION`/`SSH_TTY` unset or blank — under SSH port-forwarding the chooser would open on the unattended server), and a display session (assumed on darwin/win32; `DISPLAY`/`WAYLAND_DISPLAY` elsewhere). Anything ambiguous resolves to `browse`, which works everywhere. The sample happens exactly once per boot so the mounted capability stays stable for the service lifetime, as the seam requires. Pinning an interaction is not a config field here — compose the `-native` or `-browse` row directly instead of this one, the seam's documented swap point; mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service, duplicate client flow in the `single` holes). + +## Model Experience + +None, as the chooser only composes the GUI host's directory selection; nothing here reaches a model request. + +#### KV Cache effect + +None; this package neither assembles nor sends a provider request. + +## Known Limitations and Deferred Work + +- **Detection is a heuristic, not a proof** — a tmux session detached from its SSH launch loses the `SSH_*` markers, and a darwin process outside an Aqua session still counts as displayed; a wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` directly pins the safe interaction. +- **Boot-time only** — one resolution serves every client of the boot; per-connection adaptivity (native for a local browser, browse for a remote one, same server) would need a per-client capability and the wire advertisement the seam deliberately deleted, and waits for a deployment that serves both at once. diff --git a/packages/host/directory-picker-auto/README.zh.md b/packages/host/directory-picker-auto/README.zh.md new file mode 100644 index 0000000000..5bc9ced01f --- /dev/null +++ b/packages/host/directory-picker-auto/README.zh.md @@ -0,0 +1,20 @@ +# @deepseek-ai/dsh-host-directory-picker-auto + +[English](README.md) | 中文 + +[目录选择 seam](../directory-picker/README.md) 的**自适应选择器**：一个只有 node 半侧的插件，在启动时一次性判定宿主处境，并把匹配的双面后端——[`-native`](../directory-picker-native/README.md) 或 [`-browse`](../directory-picker-browse/README.md)——作为真实的 Loader 条目挂进内存根树（绝不持久化到配置文件；根树的 `write()` 是 no-op）。由于后端以普通条目的形式到达，其 browser half 被 client 模块表发现的方式与配置行完全相同，因此对判定出的选择，seam 的“一行同时换两面”不变式依然成立。卸载该选择器会再次移除该条目，连同两面一起卸载。 + +判定是一次纯函数的启动时采样（`resolveDirectoryPickerBackend`），已导出供复用与测试。`native` 要求“操作者看得到宿主屏幕”的全部信号：仅回环的绑定（从注入的 `httpServer` 读取；全网卡绑定会接入任何 OS 选择器都触及不到的远程浏览器）；非 SSH 启动（`SSH_CONNECTION`／`SSH_TTY` 未设置或为空——SSH 端口转发下选择器会弹在无人值守的服务器上）；以及存在显示会话（darwin／win32 上视为存在，其余平台看 `DISPLAY`／`WAYLAND_DISPLAY`）。任何含糊情形都判定为处处可用的 `browse`。采样每次启动恰好发生一次，因此挂载的能力在服务生命周期内保持稳定，符合 seam 的要求。固定某种交互在这里不是配置字段——直接组合 `-native` 或 `-browse` 行来替代本行，那才是 seam 文档化的切换点；同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务、`single` 洞中的重复 client 流程）。 + +## 模型体验 + +无。该选择器仅组合 GUI 宿主的目录选择；这里没有任何内容进入模型请求。 + +#### KV 缓存影响 + +无；该包既不组装也不发送提供方请求。 + +## 已知限制与延期工作 + +- **探测是启发式，不是证明**——从 SSH 启动中脱离的 tmux 会话会丢失 `SSH_*` 标记，Aqua 会话之外的 darwin 进程也仍被算作有显示；错误的 `native` 选择会退化为后端既有的可重试失败对话框，而直接组合 `-browse` 即固定住安全的交互。 +- **仅在启动时判定**——一次判定服务本次启动的所有客户端；按连接自适应（同一台服务器，本地浏览器用 native、远程浏览器用 browse）需要按客户端的能力对象以及 seam 有意删除的 wire 广播，等到出现同时服务两种形态的部署再做。 diff --git a/packages/host/directory-picker-auto/package.json b/packages/host/directory-picker-auto/package.json new file mode 100644 index 0000000000..888637231e --- /dev/null +++ b/packages/host/directory-picker-auto/package.json @@ -0,0 +1,47 @@ +{ + "name": "@deepseek-ai/dsh-host-directory-picker-auto", + "description": "Adaptive chooser of the directory-picker seam: resolves the host situation at boot and mounts the native or browse backend for the DeepSeek Harness web GUI host", + "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" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@cordisjs/plugin-loader": "^1.0.0-rc.5", + "@deepseek-ai/dsh-host-directory-picker-browse": "^0.0.1", + "@deepseek-ai/dsh-host-directory-picker-native": "^0.0.1", + "@deepseek-ai/dsh-host-webserver": "^0.0.1", + "@deepseek-ai/dsh-invariants": "^0.0.1", + "cordis": "^4.0.0-rc.7" + }, + "devDependencies": { + "@cordisjs/plugin-include": "workspace:^", + "@cordisjs/plugin-loader": "workspace:^", + "@deepseek-ai/dsh-host-directory-picker": "workspace:^", + "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^", + "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^", + "@deepseek-ai/dsh-host-webserver": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "cordis": "^4.0.0-rc.7" + } +} diff --git a/packages/host/directory-picker-auto/src/index.ts b/packages/host/directory-picker-auto/src/index.ts new file mode 100644 index 0000000000..12568d8f8b --- /dev/null +++ b/packages/host/directory-picker-auto/src/index.ts @@ -0,0 +1,52 @@ +/** + * Adaptive chooser of the directory-picker seam: resolves the host's + * situation once at boot (bind host, SSH launch, display session) and mounts + * the matching dual-face backend — `-native` or `-browse` — as a real Loader + * entry in the in-memory root tree. Because the backend arrives as an + * ordinary entry, its browser half is discovered exactly as a config-row's + * would be, so the seam's one-row-swaps-both-faces invariant holds for the + * resolved choice; pinning an interaction remains composing that backend row + * directly instead of this one. + * @module @deepseek-ai/dsh-host-directory-picker-auto + */ + +import type { Context } from 'cordis' +// Empty type imports carry the `loader` and `httpServer` Context merges for the reads below. +import type {} from '@cordisjs/plugin-loader' +import type {} from '@deepseek-ai/dsh-host-webserver' +import type { DirectoryPickerBackendKind } from './resolve.ts' +import { resolveDirectoryPickerBackend } from './resolve.ts' + +export type { DirectoryPickerBackendKind, DirectoryPickerEnv, DirectoryPickerHostFacts } from './resolve.ts' +export { resolveDirectoryPickerBackend } from './resolve.ts' + +/** Cordis plugin name. */ +export const name = 'directory-picker-auto' +/** Required services: the effective bind host (`httpServer`) and the entry tree the backend mounts into (`loader`). */ +export const inject = ['httpServer', 'loader'] + +/** Backend package per resolved kind — fixed composition vocabulary, not a tunable. */ +const BACKEND_PACKAGES: Record = { + native: '@deepseek-ai/dsh-host-directory-picker-native', + browse: '@deepseek-ai/dsh-host-directory-picker-browse', +} + +/** + * Resolve the backend from one boot-time sample and mount it as a Loader + * entry; the effect's disposer removes the entry, so unloading this plugin + * unloads both faces of the mounted backend with it. + * @param ctx - cordis context carrying the injected `httpServer` and `loader`. + */ +export async function apply(ctx: Context): Promise { + const backend = resolveDirectoryPickerBackend({ + bindHost: ctx.httpServer.host, + platform: process.platform, + env: process.env, + }) + await ctx.effect(async () => { + // Root-tree create: the Loader root is in-memory (write() is a no-op), so + // the mounted row can never be persisted back into a config file. + const id = await ctx.loader.create({ name: BACKEND_PACKAGES[backend] }) + return () => { ctx.loader.remove(id) } + }, 'directory-picker-auto: backend entry') +} diff --git a/packages/host/directory-picker-auto/src/invariant.ts b/packages/host/directory-picker-auto/src/invariant.ts new file mode 100644 index 0000000000..8b3f251447 --- /dev/null +++ b/packages/host/directory-picker-auto/src/invariant.ts @@ -0,0 +1,25 @@ +/** + * Package-owned invariant companion for the adaptive directory-picker chooser. + * @module @deepseek-ai/dsh-host-directory-picker-auto/invariant + */ + +import type { Context } from 'cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-host-directory-picker-auto' + +/** Cordis companion plugin name. */ +export const name = 'host-directory-picker-auto-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** No runtime invariant: the sole effect is one boot-time Loader-entry mount owned by the plugin fiber; the store is authoritative. */ +const install: InvariantInstaller = () => {} + +/** + * Register the adaptive directory-picker invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) diff --git a/packages/host/directory-picker-auto/src/resolve.ts b/packages/host/directory-picker-auto/src/resolve.ts new file mode 100644 index 0000000000..d2a22e2fa8 --- /dev/null +++ b/packages/host/directory-picker-auto/src/resolve.ts @@ -0,0 +1,46 @@ +/** + * Boot-time backend resolution for the adaptive directory-picker composition: + * one pure decision from sampled host facts to a concrete backend kind. The + * caller samples exactly once per boot, so the mounted capability stays + * stable for the service lifetime as the seam requires. + * @module @deepseek-ai/dsh-host-directory-picker-auto/resolve + */ + +/** Concrete interaction backend the resolver chooses between. */ +export type DirectoryPickerBackendKind = 'native' | 'browse' + +/** Environment keys the resolution reads (a `process.env` subset). */ +export type DirectoryPickerEnv = Readonly< + Partial> +> + +/** Host facts the backend choice is a pure function of, sampled once at boot. */ +export interface DirectoryPickerHostFacts { + /** Effective webserver bind host (`127.0.0.1` or `0.0.0.0`). */ + bindHost: string + /** Host process platform. */ + platform: NodeJS.Platform + /** Environment sample; SSH marks a remote operator, DISPLAY/WAYLAND_DISPLAY a Linux display. */ + env: DirectoryPickerEnv +} + +/** An env value counts only when set and non-blank (an empty export is "unset" by shell convention). */ +const present = (value: string | undefined): boolean => value !== undefined && value !== '' + +/** + * Resolve which backend serves this boot. `native` requires every signal that + * the operator can see the host display: a loopback-only bind (an + * all-interfaces bind admits remote browsers no OS chooser can reach), no SSH + * launch (under SSH port-forwarding the chooser would open on the unattended + * server), and a display session (assumed on darwin/win32, `DISPLAY`/ + * `WAYLAND_DISPLAY` elsewhere). Anything ambiguous resolves to `browse`, + * which works everywhere. + * @param facts - the sampled host facts. + * @returns the backend kind to mount. + */ +export function resolveDirectoryPickerBackend(facts: DirectoryPickerHostFacts): DirectoryPickerBackendKind { + if (facts.bindHost !== '127.0.0.1') return 'browse' + if (present(facts.env.SSH_CONNECTION) || present(facts.env.SSH_TTY)) return 'browse' + if (facts.platform === 'darwin' || facts.platform === 'win32') return 'native' + return present(facts.env.DISPLAY) || present(facts.env.WAYLAND_DISPLAY) ? 'native' : 'browse' +} diff --git a/packages/host/directory-picker-auto/tests/loader-composition.spec.ts b/packages/host/directory-picker-auto/tests/loader-composition.spec.ts new file mode 100644 index 0000000000..7e094035fb --- /dev/null +++ b/packages/host/directory-picker-auto/tests/loader-composition.spec.ts @@ -0,0 +1,139 @@ +/** + * REAL-composition coverage: a test-only cordis.yml booted through the + * vendored Loader mounts the webserver row plus the adaptive chooser, and the + * assertions observe the durable outcome — which backend entry the chooser + * mounted into the Loader store, the capability the seam then serves, and + * that disposing the chooser removes the mounted entry again (HMR safety). + */ + +import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import Loader from '@cordisjs/plugin-loader' +import Include from '@cordisjs/plugin-include' +import HttpServer from '@deepseek-ai/dsh-host-webserver' +import type { DirectoryPicker } from '@deepseek-ai/dsh-host-directory-picker' +import BrowseDirectoryPicker from '@deepseek-ai/dsh-host-directory-picker-browse' +import NativeDirectoryPicker from '@deepseek-ai/dsh-host-directory-picker-native' +import * as DirectoryPickerAuto from '../src/index.ts' + +const AUTO = '@deepseek-ai/dsh-host-directory-picker-auto' +const NATIVE = '@deepseek-ai/dsh-host-directory-picker-native' +const BROWSE = '@deepseek-ai/dsh-host-directory-picker-browse' + +let root: string | undefined +let context: Context | undefined + +afterEach(async () => { + vi.unstubAllEnvs() + await context?.fiber.dispose() + context = undefined + if (root !== undefined) await rm(root, { recursive: true, force: true }) + root = undefined +}) + +/** Write a dist fixture and a two-row cordis.yml (webserver + chooser), then boot it through the real Loader. */ +async function loadComposition(bindHost: '127.0.0.1' | '0.0.0.0'): Promise<{ ctx: Context; configPath: string }> { + root = await mkdtemp(join(tmpdir(), 'dsh-directory-picker-auto-')) + const dist = join(root, 'dist') + await mkdir(dist) + const distIndex = join(dist, 'index.html') + await writeFile(distIndex, 'shell') + const configPath = join(root, 'cordis.yml') + await writeFile(configPath, [ + "- name: '@deepseek-ai/dsh-host-webserver'", + ' config:', + ` host: '${bindHost}'`, + ' port: 0', + ` distIndex: '${distIndex}'`, + `- name: '${AUTO}'`, + '', + ].join('\n')) + + context = new Context() + context.baseUrl = pathToFileURL(root).href + '/' + await context.plugin(Loader) + context.loader.builtins.include = Include + const modules = new Map([ + ['@deepseek-ai/dsh-host-webserver', HttpServer], + [AUTO, DirectoryPickerAuto], + [NATIVE, NativeDirectoryPicker], + [BROWSE, BrowseDirectoryPicker], + ]) + context.loader.internal = { + version: 'v2', + async import(specifier: string) { + if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`) + return modules.get(specifier) + }, + } as unknown as NonNullable + await context.loader.create({ + name: 'cordis:include', + config: { path: pathToFileURL(configPath).href }, + }) + await context.loader.await() + return { ctx: context, configPath } +} + +/** Entry names currently present in the loader store (root tree plus subtrees). */ +function entryNames(ctx: Context): string[] { + return [...ctx.loader.entries()].map(entry => entry.options.name) +} + +/** Force every signal of an attended host: no SSH launch, a display on any platform. */ +function stubAttendedHost(): void { + vi.stubEnv('SSH_CONNECTION', '') + vi.stubEnv('SSH_TTY', '') + vi.stubEnv('DISPLAY', ':0') +} + +describe('real Loader composition', () => { + // Real-Loader composition resolves workspace packages through tsx at test + // time; first resolution after the host/client program split is slow enough + // to trip the default 5s budget on cold caches. + it('mounts the native backend for an attended loopback host and unmounts it on disposal', { timeout: 60_000 }, async () => { + stubAttendedHost() + const { ctx, configPath } = await loadComposition('127.0.0.1') + + const unloaded = [...ctx.loader.entries()] + .filter(entry => entry.fiber === undefined && !entry.disabled) + .map(entry => entry.options.name) + expect(unloaded).toEqual([]) + expect(entryNames(ctx)).toContain(NATIVE) + expect(entryNames(ctx)).not.toContain(BROWSE) + const picker = ctx.get('directoryPicker') as DirectoryPicker + expect(picker.capability().kind).toBe('native') + // The mounted row lives in the Loader's in-memory root tree only — the + // booted config file must never gain the resolved backend row. + expect(await readFile(configPath, 'utf8')).not.toContain(NATIVE) + + // HMR safety: disposing the chooser's fiber removes the entry it created. + const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)! + await autoEntry.fiber!.dispose() + await ctx.loader.await() + expect(entryNames(ctx)).not.toContain(NATIVE) + expect(ctx.get('directoryPicker')).toBeUndefined() + }) + + it('mounts the browse backend under an SSH launch', { timeout: 60_000 }, async () => { + stubAttendedHost() + vi.stubEnv('SSH_CONNECTION', '10.0.0.2 55 10.0.0.9 22') + const { ctx } = await loadComposition('127.0.0.1') + + expect(entryNames(ctx)).toContain(BROWSE) + expect(entryNames(ctx)).not.toContain(NATIVE) + const picker = ctx.get('directoryPicker') as DirectoryPicker + expect(picker.capability().kind).toBe('browse') + }) + + it('mounts the browse backend for an all-interfaces bind even on an attended host', { timeout: 60_000 }, async () => { + stubAttendedHost() + const { ctx } = await loadComposition('0.0.0.0') + + expect(entryNames(ctx)).toContain(BROWSE) + expect(entryNames(ctx)).not.toContain(NATIVE) + }) +}) diff --git a/packages/host/directory-picker-auto/tests/resolve.spec.ts b/packages/host/directory-picker-auto/tests/resolve.spec.ts new file mode 100644 index 0000000000..3beac44961 --- /dev/null +++ b/packages/host/directory-picker-auto/tests/resolve.spec.ts @@ -0,0 +1,37 @@ +import { describe, expect, it } from 'vitest' +import { resolveDirectoryPickerBackend } from '../src/resolve.ts' +import type { DirectoryPickerHostFacts } from '../src/resolve.ts' + +/** Baseline facts that resolve to `native`; each case overrides one signal. */ +const attended: DirectoryPickerHostFacts = { + bindHost: '127.0.0.1', + platform: 'darwin', + env: {}, +} + +describe('resolveDirectoryPickerBackend', () => { + it('resolves native for a loopback bind on a display platform', () => { + expect(resolveDirectoryPickerBackend(attended)).toBe('native') + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'win32' })).toBe('native') + }) + + it('resolves browse for an all-interfaces bind regardless of other signals', () => { + expect(resolveDirectoryPickerBackend({ ...attended, bindHost: '0.0.0.0' })).toBe('browse') + }) + + it('resolves browse under an SSH launch (either env marker)', () => { + expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_CONNECTION: '10.0.0.2 55 10.0.0.9 22' } })).toBe('browse') + expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_TTY: '/dev/pts/3' } })).toBe('browse') + }) + + it('requires a display session on platforms without an implied one', () => { + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux' })).toBe('browse') + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { DISPLAY: ':0' } })).toBe('native') + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('native') + }) + + it('treats blank env exports as unset', () => { + expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_CONNECTION: '', SSH_TTY: '' } })).toBe('native') + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { DISPLAY: '', WAYLAND_DISPLAY: '' } })).toBe('browse') + }) +}) diff --git a/packages/host/directory-picker-auto/tsconfig.json b/packages/host/directory-picker-auto/tsconfig.json new file mode 100644 index 0000000000..4e9a1955a7 --- /dev/null +++ b/packages/host/directory-picker-auto/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/loader" + }, + { + "path": "../webserver" + }, + { + "path": "../../support/invariants" + } + ] +} diff --git a/packages/host/directory-picker/README.i18n.yaml b/packages/host/directory-picker/README.i18n.yaml index 3e5bae41b5..8bb3c0afec 100644 --- a/packages/host/directory-picker/README.i18n.yaml +++ b/packages/host/directory-picker/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/directory-picker/README.md -README.md: 8ef8889c875f5b1d07c015ddef819591041c8d7f -README.zh.md: 8aefffa7b29a47205ea42d0d1df742d1e1b2502d +README.md: 3749b238b56578ec68610bc13550760aa084bad6 +README.zh.md: 488da5129ec211c2a064156c22a9d0abf04d99be diff --git a/packages/host/directory-picker/README.md b/packages/host/directory-picker/README.md index 8ef8889c87..3749b238b5 100644 --- a/packages/host/directory-picker/README.md +++ b/packages/host/directory-picker/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -The **workspace-directory picking seam** for the web-GUI host: an abstract `DirectoryPicker` service (`ctx.directoryPicker`) whose single contract method `capability()` returns a discriminated capability describing how an operator selects a directory. Backends differ in interaction shape, not just mechanism, so the seam models the shapes explicitly instead of one method set: `{ kind: 'native', pick(signal) }` opens one native OS chooser on the host display ([`-native`](../directory-picker-native/README.md)); `{ kind: 'browse', list(path?), createDirectory(path, name) }` serves listing/creation primitives an in-app browser drives, which works for remote clients no OS chooser can reach ([`-browse`](../directory-picker-browse/README.md)). Consumers switch on `capability().kind`; the union derives from the merge-extensible `DirectoryPickerCapabilities` map (a new backend declaration-merges its shape there), and the documented default for an unknown kind is to hide the picking affordance rather than fail. The capability object must be stable for the service lifetime. The client side mirrors the seam without a wire advertisement: each backend package is dual-face, its browser half registering the matching picking interaction into ui-workspace's directory-flow slots — so one composition row swaps both the host capability and the client flow together. +The **workspace-directory picking seam** for the web-GUI host: an abstract `DirectoryPicker` service (`ctx.directoryPicker`) whose single contract method `capability()` returns a discriminated capability describing how an operator selects a directory. Backends differ in interaction shape, not just mechanism, so the seam models the shapes explicitly instead of one method set: `{ kind: 'native', pick(signal) }` opens one native OS chooser on the host display ([`-native`](../directory-picker-native/README.md)); `{ kind: 'browse', list(path?), createDirectory(path, name) }` serves listing/creation primitives an in-app browser drives, which works for remote clients no OS chooser can reach ([`-browse`](../directory-picker-browse/README.md)). Consumers switch on `capability().kind`; the union derives from the merge-extensible `DirectoryPickerCapabilities` map (a new backend declaration-merges its shape there), and the documented default for an unknown kind is to hide the picking affordance rather than fail. The capability object must be stable for the service lifetime. The client side mirrors the seam without a wire advertisement: each backend package is dual-face, its browser half registering the matching picking interaction into ui-workspace's directory-flow slots — so one composition row swaps both the host capability and the client flow together. A composition that should not pin an interaction mounts the [`-auto`](../directory-picker-auto/README.md) chooser instead, which resolves the host's situation once at boot and mounts the matching backend row itself. Browse primitives fail with the typed `DirectoryPickerError` (`directory-unreadable` / `directory-exists` / `directory-create-failed`, each carrying the subject `path`), which the consuming gateway maps 1:1 onto wire error codes. `DirectoryEntry` rows carry a host-owned `hidden` flag (POSIX dot convention) so display policy stays client-side; `DirectoryListing.crumbs` is the ancestor chain from the filesystem root, every crumb a jump target. Design rationale, the `ctx.fs` separation, and the policy decisions live in [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md). diff --git a/packages/host/directory-picker/README.zh.md b/packages/host/directory-picker/README.zh.md index 8aefffa7b2..488da5129e 100644 --- a/packages/host/directory-picker/README.zh.md +++ b/packages/host/directory-picker/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一契约方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，可服务任何 OS 对话框都触及不到的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端在其中声明合并自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam 而不经 wire 广播：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一行组合同时切换宿主能力与 client 流程。 +web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一契约方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，可服务任何 OS 对话框都触及不到的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端在其中声明合并自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam 而不经 wire 广播：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一行组合同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。 浏览原语以带类型的 `DirectoryPickerError` 失败（`directory-unreadable`／`directory-exists`／`directory-create-failed`，各自携带主体 `path`），消费网关将其 1:1 映射为协议错误码。`DirectoryEntry` 行携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示策略留在客户端；`DirectoryListing.crumbs` 是从文件系统根开始的祖先链，每个 crumb 都是跳转目标。设计依据、与 `ctx.fs` 的切分、策略裁决见[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。 diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml index 40d5fcf9d3..0160db9f01 100644 --- a/packages/host/webserver/README.i18n.yaml +++ b/packages/host/webserver/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/webserver/README.md -README.md: e715e4452ddb808f36e6b097eee0fda7b8d0bfb0 -README.zh.md: 05e7e10d7815c8f26bb90597b38b7c6b83a86dbc +README.md: ace8c09e43dd8544a28d300f97b04610be78bc69 +README.zh.md: b9948e3d387a5da393ff62b9eeacfe310516f46a diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md index e715e4452d..ace8c09e43 100644 --- a/packages/host/webserver/README.md +++ b/packages/host/webserver/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Plain HTTP route-registration plugin (default-exported `HttpServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.httpServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics. +Plain HTTP route-registration plugin (default-exported `HttpServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.httpServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the locked semantics: traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405. Registration order carries no request-facing semantics. The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell. diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md index 05e7e10d78..b9948e3d38 100644 --- a/packages/host/webserver/README.zh.md +++ b/packages/host/webserver/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -朴素的 HTTP 路由注册插件（默认导出 `HttpServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。 +朴素的 HTTP 路由注册插件（默认导出 `HttpServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。 该包不了解任何 harness 概念：`/api` 桥接是 connection 插件的路由，插件 bundle 与 HMR（热模块替换）事件流则是 modules／hmr 插件的路由。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）；`distIndex` 是由组合应用解析并注入的组装事实，绝不会自行解析，因为 dist 位置属于应用的工作区知识。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。 diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts index 936dd4f5a1..37298cb178 100644 --- a/packages/host/webserver/src/index.ts +++ b/packages/host/webserver/src/index.ts @@ -78,6 +78,11 @@ export class HttpServerService extends Service { return this.listenedPort } + /** The configured bind host (the loopback or all-interfaces literal). */ + get host(): Config['host'] { + return this.config.host + } + /** * Register a named route. Duplicate (kind, path) throws — route patterns are * a composition-level contract, so a collision is a misconfiguration. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 66ea5bea26..d4813589a3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -230,6 +230,9 @@ importers: '@deepseek-ai/dsh-host-apiproxy': specifier: workspace:^ version: link:../../packages/host/apiproxy + '@deepseek-ai/dsh-host-directory-picker-auto': + specifier: workspace:^ + version: link:../../packages/host/directory-picker-auto '@deepseek-ai/dsh-host-directory-picker-browse': specifier: workspace:^ version: link:../../packages/host/directory-picker-browse @@ -2934,6 +2937,33 @@ importers: specifier: ^4.0.0-rc.7 version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + packages/host/directory-picker-auto: + devDependencies: + '@cordisjs/plugin-include': + specifier: workspace:^ + version: link:../../../vendor/include + '@cordisjs/plugin-loader': + specifier: workspace:^ + version: link:../../../vendor/loader + '@deepseek-ai/dsh-host-directory-picker': + specifier: workspace:^ + version: link:../directory-picker + '@deepseek-ai/dsh-host-directory-picker-browse': + specifier: workspace:^ + version: link:../directory-picker-browse + '@deepseek-ai/dsh-host-directory-picker-native': + specifier: workspace:^ + version: link:../directory-picker-native + '@deepseek-ai/dsh-host-webserver': + specifier: workspace:^ + version: link:../webserver + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../support/invariants + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader) + packages/host/directory-picker-browse: dependencies: '@deepseek-ai/dsh-host-directory-picker': diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index fd74c6d13e..0e48167920 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -78,6 +78,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' }, 'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' }, 'packages/host/directory-picker': { kind: 'none', reason: 'The GUI-host picking seam registers no model surface.' }, + 'packages/host/directory-picker-auto': { kind: 'none', reason: 'The GUI-host picking chooser only mounts a backend row; registers no model surface.' }, 'packages/host/directory-picker-browse': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' }, 'packages/host/directory-picker-native': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' }, 'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' }, diff --git a/tsconfig.host.json b/tsconfig.host.json index 2287d21a9a..69a7550593 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -172,6 +172,14 @@ { "path": "./packages/mcp/mcp-client" }, { "path": "./packages/host/apiproxy" }, { "path": "./packages/host/directory-picker" }, + { "path": "./packages/host/directory-picker-auto" }, + // Dual-face backend leaves stay client-registered (their tests and client + // halves are excluded above); these references only let the adaptive + // chooser's composition test import each backend's NODE entry, whose + // declarations carry no client-side Context merge — the mirror of the + // client aggregate's webserver reference. + { "path": "./packages/host/directory-picker-browse" }, + { "path": "./packages/host/directory-picker-native" }, { "path": "./packages/host/webserver" }, { "path": "./packages/sdk/sdk-client" }, { "path": "./packages/sdk/helper" }, From f0f897ef029a448172c48de4cf48e3c066a4ea35 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Wed, 29 Jul 2026 21:09:02 +0800 Subject: [PATCH 20/67] fix(host): address ds-review-bot v7 on the adaptive picker chooser - resolve.ts: gate the display branch on linux (the native backend drives exactly darwin/win32/linux) and require a zenity/kdialog binary on PATH, probed once at boot (new probe.ts, injected predicate for tests); type bindHost as the webserver schema's closed union. - index.ts: the disposer now joins the removed entry's fiber teardown so unloading the chooser settles only after the backend quiesced; export BACKEND_PACKAGES as the runtime-string source of truth. - verify-cordis-config: a composition mounting -auto must declare both backends as dependencies (negative-tested), since keyless Linux CI only ever resolves browse and would hide a dropped -native dep. - apps/web scaffold: pin -browse via disable+insert (goldens are interaction-specific); fix the stale workspace-flow comment. - docs/module-graph.md regenerated; README + Agent Note document the ssh -L shape, the PATH-only probe, and the new gate (zh pairs re-paired). - composition spec: assert teardown quiescence without a loader await, cover external entry removal, and await the loader's self-dispose disabled-persist so it cannot race temp-dir teardown. --- ...irectory-picker-adaptive-default.i18n.yaml | 4 +- ...07-29-directory-picker-adaptive-default.md | 5 +- ...29-directory-picker-adaptive-default.zh.md | 5 +- apps/web/tests/scaffold.ts | 8 +++ apps/web/tests/workspace-flow.snapshot.ts | 3 +- docs/module-graph.md | 6 ++ .../directory-picker-auto/README.i18n.yaml | 4 +- packages/host/directory-picker-auto/README.md | 5 +- .../host/directory-picker-auto/README.zh.md | 5 +- .../host/directory-picker-auto/src/index.ts | 43 ++++++++---- .../host/directory-picker-auto/src/probe.ts | 44 ++++++++++++ .../host/directory-picker-auto/src/resolve.ts | 23 ++++--- .../tests/loader-composition.spec.ts | 57 +++++++++++++--- .../tests/resolve.spec.ts | 68 +++++++++++++++++-- scripts/verify-cordis-config.ts | 26 ++++++- 15 files changed, 253 insertions(+), 53 deletions(-) create mode 100644 packages/host/directory-picker-auto/src/probe.ts diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml index cd921886f6..3ade5b93e1 100644 --- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md -2026-07-29-directory-picker-adaptive-default.md: ae5748259f162503300360d6cca43bec996afdb6 -2026-07-29-directory-picker-adaptive-default.zh.md: acabeb80604b473289fa441e6d9d913e4a8f87d0 +2026-07-29-directory-picker-adaptive-default.md: 7ff6529bb8e445f63343b1019ac520f56b19d5e4 +2026-07-29-directory-picker-adaptive-default.zh.md: a2a2d8ec4c91a347eedfc3aa3413b091ee847934 diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md index ae5748259f..7ff6529bb8 100644 --- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md @@ -10,7 +10,7 @@ The [directory-picker seam](../architecture/2026-07-28-directory-picker-capabili ## Decision -A third sibling package, **`dsh-host-directory-picker-auto`**: a node-half-only *chooser* that owns no picking code and no UI. Its `apply` samples the host facts exactly once at boot — bind host from the injected `httpServer` (a new `host` getter mirrors the existing `port`), `SSH_CONNECTION`/`SSH_TTY`, platform, `DISPLAY`/`WAYLAND_DISPLAY` — resolves them through one exported pure function, and mounts the chosen dual-face backend with `ctx.loader.create({name})` into the Loader's **in-memory root tree**; the effect's disposer removes the entry again. `native` requires every attended-host signal (loopback bind ∧ no SSH markers ∧ display session, assumed on darwin/win32); anything ambiguous resolves to `browse`, which works everywhere. `apps/cli` now mounts `-auto` as its `directory-picker` row; composing `-native` or `-browse` directly remains the pin. +A third sibling package, **`dsh-host-directory-picker-auto`**: a node-half-only *chooser* that owns no picking code and no UI. Its `apply` samples the host facts exactly once at boot — bind host from the injected `httpServer` (a new `host` getter mirrors the existing `port`), `SSH_CONNECTION`/`SSH_TTY`, platform, `DISPLAY`/`WAYLAND_DISPLAY`, and a `PATH` probe for a Linux chooser binary (zenity/kdialog) — resolves them through one exported pure function, and mounts the chosen dual-face backend with `ctx.loader.create({name})` into the Loader's **in-memory root tree**; the effect's disposer removes the entry and joins the backend fiber's teardown (`remove()` alone only starts it), so unloading the chooser settles only after the backend quiesced. `native` requires every attended-and-servable signal: loopback bind ∧ no SSH markers ∧ a display session the native backend can drive — assumed on darwin/win32, requiring `DISPLAY`/`WAYLAND_DISPLAY` plus a chooser binary on linux, and never true elsewhere (the native backend supports exactly darwin/win32/linux). Anything ambiguous resolves to `browse`, which works everywhere. `apps/cli` now mounts `-auto` as its `directory-picker` row; composing `-native` or `-browse` directly remains the pin. Why entry-level mounting is the load-bearing mechanism: the client module table (`dsh-client-modules`) reconciles **Loader entries** reactively over `internal/plugin`, so a backend mounted as a real entry gets its browser half discovered exactly as a config-row's would be — the seam's one-row-swaps-both-faces invariant survives adaptivity with zero duplicated client code. The dev HMR row (`AppCLIEntry`) is the mechanism precedent. Root-tree targeting matters: the root tree's `write()` is a no-op, so the resolved row can never be persisted back into `cordis.yml` (the Include subtree *does* write). @@ -23,7 +23,8 @@ Why entry-level mounting is the load-bearing mechanism: the client module table ## Consequences -- The shipped web GUI adapts out of the box: attended local host → OS chooser; SSH launch, all-interfaces bind, or headless host → in-app browser. Detection is a heuristic (a detached tmux session loses `SSH_*`; a non-Aqua darwin process still counts as displayed) — a wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` pins the safe interaction. +- The shipped web GUI adapts out of the box: attended local host → OS chooser; SSH launch, all-interfaces bind, headless host, unsupported platform, or Linux without a chooser binary → in-app browser. Detection infers operator location from launch context, which no launch-side signal can prove: a detached tmux session loses `SSH_*`; a non-Aqua darwin process still counts as displayed; and the `ssh -L` shape (a workstation-local launch later reached through a forwarded port, arriving from `127.0.0.1`) resolves `native` and opens the chooser on the unattended workstation — per-connection adaptivity could not fix that last case either. A wrong `native` choice degrades to the backend's existing retryable failure dialog; deployments in these shapes compose `-browse` directly. +- The chooser mounts backends by runtime string (`BACKEND_PACKAGES`, exported), which yml-row scanning cannot see; `verify-cordis-config` therefore requires every composition mounting `-auto` to declare both backends as dependencies, so keyless Linux CI (which only ever resolves `browse`) cannot hide a dropped `-native` dependency. The shipped-tree web e2e/snapshot lane (`apps/web/tests/scaffold.ts`) pins `-browse` by disable+insert patch — its goldens are interaction-specific and must not depend on the host running the suite. - One resolution per boot keeps the seam's capability-stability contract; per-connection shapes remain out of scope until a deployment demands them. - Mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service; duplicate flow in the `single` holes). - The host typecheck aggregate now references the two backend projects (declarations only, node entries carry no client merge) so the chooser's REAL-composition test can mount them — the mirror of the client aggregate's `webserver` reference. diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md index acabeb8060..a2a2d8ec4c 100644 --- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md @@ -10,7 +10,7 @@ ## 决策 -第三个同级包 **`dsh-host-directory-picker-auto`**：一个只有 node 半侧的*选择器*，不持有任何选取代码，也没有 UI。它的 `apply` 在启动时恰好采样一次宿主事实——从注入的 `httpServer` 读绑定宿主（新增的 `host` getter 与既有的 `port` 对称）、`SSH_CONNECTION`／`SSH_TTY`、平台、`DISPLAY`／`WAYLAND_DISPLAY`——经由一个导出的纯函数判定，再用 `ctx.loader.create({name})` 把选中的双面后端挂进 Loader 的**内存根树**；该 effect 的 disposer 会再次移除该条目。`native` 要求全部有人值守宿主信号（回环绑定 ∧ 无 SSH 标记 ∧ 显示会话，darwin／win32 上视为存在）；任何含糊情形都判定为处处可用的 `browse`。`apps/cli` 现在把 `-auto` 挂为它的 `directory-picker` 行；直接组合 `-native` 或 `-browse` 仍是固定交互的方式。 +第三个同级包 **`dsh-host-directory-picker-auto`**：一个只有 node 半侧的*选择器*，不持有任何选取代码，也没有 UI。它的 `apply` 在启动时恰好采样一次宿主事实——从注入的 `httpServer` 读绑定宿主（新增的 `host` getter 与既有的 `port` 对称）、`SSH_CONNECTION`／`SSH_TTY`、平台、`DISPLAY`／`WAYLAND_DISPLAY`、以及对 Linux 选择器二进制（zenity／kdialog）的一次 `PATH` 探查——经由一个导出的纯函数判定，再用 `ctx.loader.create({name})` 把选中的双面后端挂进 Loader 的**内存根树**；该 effect 的 disposer 会移除该条目并汇入后端 fiber 的拆卸（单靠 `remove()` 只是启动拆卸），因此卸载选择器要到后端静止之后才落定。`native` 要求全部“有人值守且可服务”信号：回环绑定 ∧ 无 SSH 标记 ∧ native 后端能驱动的显示会话——darwin／win32 上视为存在，linux 上要求 `DISPLAY`／`WAYLAND_DISPLAY` 外加一个选择器二进制，其余平台一律不成立（native 后端恰好支持 darwin／win32／linux）。任何含糊情形都判定为处处可用的 `browse`。`apps/cli` 现在把 `-auto` 挂为它的 `directory-picker` 行；直接组合 `-native` 或 `-browse` 仍是固定交互的方式。 条目级挂载之所以是承重机制：client 模块表（`dsh-client-modules`）基于 `internal/plugin` 对 **Loader 条目**做响应式协调，因此以真实条目挂载的后端，其 browser half 被发现的方式与配置行完全相同——seam 的“一行同时换两面”不变式在自适应下依然成立，且没有一行重复的 client 代码。开发环境的 HMR 行（`AppCLIEntry`）是该机制的先例。瞄准根树很关键：根树的 `write()` 是 no-op，因此判定出的行绝不会被持久化回 `cordis.yml`（Include 子树*会*写回）。 @@ -23,7 +23,8 @@ ## 后果 -- 随附的 web GUI 开箱即自适应：有人值守的本地宿主 → OS 选择器；SSH 启动、全网卡绑定或无头宿主 → 应用内浏览器。探测是启发式的（脱离的 tmux 会话会丢失 `SSH_*`；非 Aqua 的 darwin 进程仍被算作有显示）——错误的 `native` 选择会退化为后端既有的可重试失败对话框，组合 `-browse` 即固定住安全的交互。 +- 随附的 web GUI 开箱即自适应：有人值守的本地宿主 → OS 选择器；SSH 启动、全网卡绑定、无头宿主、不支持的平台，或没有选择器二进制的 Linux → 应用内浏览器。探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点：脱离的 tmux 会话会丢失 `SSH_*`；非 Aqua 的 darwin 进程仍被算作有显示；而 `ssh -L` 形态（在工作站本地启动、之后经转发端口访问，从 `127.0.0.1` 到达）会判定 `native`，把选择器弹在无人值守的工作站上——即便按连接自适应也修不了最后这一情形。错误的 `native` 选择会退化为后端既有的可重试失败对话框；处于这些形态的部署直接组合 `-browse`。 +- 选择器按运行时字符串（已导出的 `BACKEND_PACKAGES`）挂载后端，yml 行扫描看不到这一点；因此 `verify-cordis-config` 要求每个挂载 `-auto` 的组合把两个后端都声明为依赖，使无密钥的 Linux CI（它永远只会判定出 `browse`）无法掩盖被丢掉的 `-native` 依赖。随附树的 web e2e／快照通道（`apps/web/tests/scaffold.ts`）以 disable+insert 补丁固定 `-browse`——其 golden 是交互特定的，绝不能依赖运行该套件的宿主。 - 每次启动只判定一次，维持 seam 的能力稳定性契约；按连接的形态在有部署提出需求前仍不在范围内。 - 同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务；`single` 洞中的重复流程）。 - host 类型检查聚合现在引用两个后端项目（仅声明，node 入口不携带 client 合并），使选择器的 REAL-composition 测试能挂载它们——与 client 聚合对 `webserver` 的引用互为镜像。 diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index 753cdc2953..d7970036f9 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -175,6 +175,14 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise pkg_invariants pkg_code_runtime_worker --> pkg_session pkg_code_runtime_worker --> pkg_timeout + pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse + pkg_host_directory_picker_auto --> pkg_host_directory_picker_native + pkg_host_directory_picker_auto --> pkg_host_webserver + pkg_host_directory_picker_auto --> pkg_invariants pkg_lsp_local --> pkg_brand pkg_lsp_local --> pkg_invariants pkg_lsp_local --> pkg_llm @@ -1041,6 +1046,7 @@ flowchart TD | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) | | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) | | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | +| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) | | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | diff --git a/packages/host/directory-picker-auto/README.i18n.yaml b/packages/host/directory-picker-auto/README.i18n.yaml index fa4907698b..ea430abe70 100644 --- a/packages/host/directory-picker-auto/README.i18n.yaml +++ b/packages/host/directory-picker-auto/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/directory-picker-auto/README.md -README.md: 73692d1fb5af1e7b23b2a99d0a5cd48507f68ce5 -README.zh.md: 5bc9ced01f86d021db256df2c9e69e97ec6a7ab1 +README.md: 10d1784590b79fdfef3cf6683d389182cd8437b6 +README.zh.md: 86ec9f2c3a87557e86038ce7d3f89887c5bb3546 diff --git a/packages/host/directory-picker-auto/README.md b/packages/host/directory-picker-auto/README.md index 73692d1fb5..10d1784590 100644 --- a/packages/host/directory-picker-auto/README.md +++ b/packages/host/directory-picker-auto/README.md @@ -4,7 +4,7 @@ English | [中文](README.zh.md) The **adaptive chooser** of the [directory-picker seam](../directory-picker/README.md): a node-half-only plugin that resolves the host's situation once at boot and mounts the matching dual-face backend — [`-native`](../directory-picker-native/README.md) or [`-browse`](../directory-picker-browse/README.md) — as a real Loader entry in the in-memory root tree (never persisted to a config file; the root tree's `write()` is a no-op). Because the backend arrives as an ordinary entry, its browser half is discovered by the client module table exactly as a config-row's would be, so the seam's one-row-swaps-both-faces invariant holds for the resolved choice. Unloading the chooser removes the entry again, unloading both faces with it. -Resolution is one pure boot-time sample (`resolveDirectoryPickerBackend`), exported for reuse and tests. `native` requires every signal that the operator can see the host display: a loopback-only bind (read from the injected `httpServer`; an all-interfaces bind admits remote browsers no OS chooser can reach), no SSH launch (`SSH_CONNECTION`/`SSH_TTY` unset or blank — under SSH port-forwarding the chooser would open on the unattended server), and a display session (assumed on darwin/win32; `DISPLAY`/`WAYLAND_DISPLAY` elsewhere). Anything ambiguous resolves to `browse`, which works everywhere. The sample happens exactly once per boot so the mounted capability stays stable for the service lifetime, as the seam requires. Pinning an interaction is not a config field here — compose the `-native` or `-browse` row directly instead of this one, the seam's documented swap point; mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service, duplicate client flow in the `single` holes). +Resolution is one pure boot-time sample (`resolveDirectoryPickerBackend`), exported for reuse and tests. `native` requires every signal that the operator can see the host display and the native backend can serve it: a loopback-only bind (read from the injected `httpServer`; an all-interfaces bind admits remote browsers no OS chooser can reach), no SSH launch (`SSH_CONNECTION`/`SSH_TTY` unset or blank — under SSH port-forwarding the chooser would open on the unattended server), and a servable display session — assumed on darwin/win32; on linux `DISPLAY`/`WAYLAND_DISPLAY` plus a zenity or kdialog binary on `PATH` (the probe is one more boot-time fact); never on any other platform, since the native backend drives exactly darwin/win32/linux. Anything ambiguous resolves to `browse`, which works everywhere. The sample happens exactly once per boot so the mounted capability stays stable for the service lifetime, as the seam requires. Pinning an interaction is not a config field here — compose the `-native` or `-browse` row directly instead of this one, the seam's documented swap point; mounting the chooser **and** a backend row together fails loud (duplicate `directoryPicker` service, duplicate client flow in the `single` holes). ## Model Experience @@ -16,5 +16,6 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **Detection is a heuristic, not a proof** — a tmux session detached from its SSH launch loses the `SSH_*` markers, and a darwin process outside an Aqua session still counts as displayed; a wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` directly pins the safe interaction. +- **Detection infers operator location from launch context, which no launch-side signal can prove** — a tmux session detached from its SSH launch loses the `SSH_*` markers; a darwin process outside an Aqua session still counts as displayed; and the `ssh -L` shape (a workstation-local launch later reached through a forwarded port, which arrives from `127.0.0.1`) resolves `native` and opens the chooser on the unattended workstation. A wrong `native` choice degrades to the backend's existing retryable failure dialog, and composing `-browse` directly pins the safe interaction for such deployments. +- **The Linux chooser probe reads `PATH` only** — a zenity/kdialog reachable some other way (shell alias, non-PATH install) still resolves `browse`; installing either binary on `PATH` restores `native` eligibility at the next boot. - **Boot-time only** — one resolution serves every client of the boot; per-connection adaptivity (native for a local browser, browse for a remote one, same server) would need a per-client capability and the wire advertisement the seam deliberately deleted, and waits for a deployment that serves both at once. diff --git a/packages/host/directory-picker-auto/README.zh.md b/packages/host/directory-picker-auto/README.zh.md index 5bc9ced01f..86ec9f2c3a 100644 --- a/packages/host/directory-picker-auto/README.zh.md +++ b/packages/host/directory-picker-auto/README.zh.md @@ -4,7 +4,7 @@ [目录选择 seam](../directory-picker/README.md) 的**自适应选择器**：一个只有 node 半侧的插件，在启动时一次性判定宿主处境，并把匹配的双面后端——[`-native`](../directory-picker-native/README.md) 或 [`-browse`](../directory-picker-browse/README.md)——作为真实的 Loader 条目挂进内存根树（绝不持久化到配置文件；根树的 `write()` 是 no-op）。由于后端以普通条目的形式到达，其 browser half 被 client 模块表发现的方式与配置行完全相同，因此对判定出的选择，seam 的“一行同时换两面”不变式依然成立。卸载该选择器会再次移除该条目，连同两面一起卸载。 -判定是一次纯函数的启动时采样（`resolveDirectoryPickerBackend`），已导出供复用与测试。`native` 要求“操作者看得到宿主屏幕”的全部信号：仅回环的绑定（从注入的 `httpServer` 读取；全网卡绑定会接入任何 OS 选择器都触及不到的远程浏览器）；非 SSH 启动（`SSH_CONNECTION`／`SSH_TTY` 未设置或为空——SSH 端口转发下选择器会弹在无人值守的服务器上）；以及存在显示会话（darwin／win32 上视为存在，其余平台看 `DISPLAY`／`WAYLAND_DISPLAY`）。任何含糊情形都判定为处处可用的 `browse`。采样每次启动恰好发生一次，因此挂载的能力在服务生命周期内保持稳定，符合 seam 的要求。固定某种交互在这里不是配置字段——直接组合 `-native` 或 `-browse` 行来替代本行，那才是 seam 文档化的切换点；同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务、`single` 洞中的重复 client 流程）。 +判定是一次纯函数的启动时采样（`resolveDirectoryPickerBackend`），已导出供复用与测试。`native` 要求“操作者看得到宿主屏幕、且 native 后端能服务它”的全部信号：仅回环的绑定（从注入的 `httpServer` 读取；全网卡绑定会接入任何 OS 选择器都触及不到的远程浏览器）；非 SSH 启动（`SSH_CONNECTION`／`SSH_TTY` 未设置或为空——SSH 端口转发下选择器会弹在无人值守的服务器上）；以及可服务的显示会话——darwin／win32 上视为存在；linux 上要求 `DISPLAY`／`WAYLAND_DISPLAY`，外加 `PATH` 上有 zenity 或 kdialog 二进制（该探查是又一项启动时事实）；其余任何平台上都不成立，因为 native 后端驱动的平台恰为 darwin／win32／linux。任何含糊情形都判定为处处可用的 `browse`。采样每次启动恰好发生一次，因此挂载的能力在服务生命周期内保持稳定，符合 seam 的要求。固定某种交互在这里不是配置字段——直接组合 `-native` 或 `-browse` 行来替代本行，那才是 seam 文档化的切换点；同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务、`single` 洞中的重复 client 流程）。 ## 模型体验 @@ -16,5 +16,6 @@ ## 已知限制与延期工作 -- **探测是启发式，不是证明**——从 SSH 启动中脱离的 tmux 会话会丢失 `SSH_*` 标记，Aqua 会话之外的 darwin 进程也仍被算作有显示；错误的 `native` 选择会退化为后端既有的可重试失败对话框，而直接组合 `-browse` 即固定住安全的交互。 +- **探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点**——从 SSH 启动中脱离的 tmux 会话会丢失 `SSH_*` 标记；Aqua 会话之外的 darwin 进程仍被算作有显示；而 `ssh -L` 形态（在工作站本地启动、之后经转发端口访问，从 `127.0.0.1` 到达）会判定 `native`，把选择器弹在无人值守的工作站上。错误的 `native` 选择会退化为后端既有的可重试失败对话框，而对这类部署，直接组合 `-browse` 即固定住安全的交互。 +- **Linux 选择器探查只读 `PATH`**——以其他途径可用的 zenity／kdialog（shell 别名、未装在 PATH 上）仍判定为 `browse`；把任一二进制装到 `PATH` 上，下次启动即恢复 `native` 资格。 - **仅在启动时判定**——一次判定服务本次启动的所有客户端；按连接自适应（同一台服务器，本地浏览器用 native、远程浏览器用 browse）需要按客户端的能力对象以及 seam 有意删除的 wire 广播，等到出现同时服务两种形态的部署再做。 diff --git a/packages/host/directory-picker-auto/src/index.ts b/packages/host/directory-picker-auto/src/index.ts index 12568d8f8b..5766e36b98 100644 --- a/packages/host/directory-picker-auto/src/index.ts +++ b/packages/host/directory-picker-auto/src/index.ts @@ -1,12 +1,12 @@ /** * Adaptive chooser of the directory-picker seam: resolves the host's - * situation once at boot (bind host, SSH launch, display session) and mounts - * the matching dual-face backend — `-native` or `-browse` — as a real Loader - * entry in the in-memory root tree. Because the backend arrives as an - * ordinary entry, its browser half is discovered exactly as a config-row's - * would be, so the seam's one-row-swaps-both-faces invariant holds for the - * resolved choice; pinning an interaction remains composing that backend row - * directly instead of this one. + * situation once at boot (bind host, SSH launch, display session, Linux + * chooser binary) and mounts the matching dual-face backend — `-native` or + * `-browse` — as a real Loader entry in the in-memory root tree. Because the + * backend arrives as an ordinary entry, its browser half is discovered + * exactly as a config-row's would be, so the seam's one-row-swaps-both-faces + * invariant holds for the resolved choice; pinning an interaction remains + * composing that backend row directly instead of this one. * @module @deepseek-ai/dsh-host-directory-picker-auto */ @@ -14,9 +14,11 @@ import type { Context } from 'cordis' // Empty type imports carry the `loader` and `httpServer` Context merges for the reads below. import type {} from '@cordisjs/plugin-loader' import type {} from '@deepseek-ai/dsh-host-webserver' +import { canExecute, hasLinuxChooserBinary } from './probe.ts' import type { DirectoryPickerBackendKind } from './resolve.ts' import { resolveDirectoryPickerBackend } from './resolve.ts' +export { canExecute, hasLinuxChooserBinary } from './probe.ts' export type { DirectoryPickerBackendKind, DirectoryPickerEnv, DirectoryPickerHostFacts } from './resolve.ts' export { resolveDirectoryPickerBackend } from './resolve.ts' @@ -25,16 +27,22 @@ export const name = 'directory-picker-auto' /** Required services: the effective bind host (`httpServer`) and the entry tree the backend mounts into (`loader`). */ export const inject = ['httpServer', 'loader'] -/** Backend package per resolved kind — fixed composition vocabulary, not a tunable. */ -const BACKEND_PACKAGES: Record = { +/** + * Backend package per resolved kind — fixed composition vocabulary, not a + * tunable. Exported because the reference is a runtime string the static + * config gate cannot see in a yml row: `verify-cordis-config` requires every + * app composing this chooser to declare both values as dependencies. + */ +export const BACKEND_PACKAGES: Record = { native: '@deepseek-ai/dsh-host-directory-picker-native', browse: '@deepseek-ai/dsh-host-directory-picker-browse', } /** * Resolve the backend from one boot-time sample and mount it as a Loader - * entry; the effect's disposer removes the entry, so unloading this plugin - * unloads both faces of the mounted backend with it. + * entry; the effect's disposer removes the entry and joins the backend + * fiber's teardown, so unloading this plugin returns only after both faces + * of the mounted backend (and their dependents) quiesced. * @param ctx - cordis context carrying the injected `httpServer` and `loader`. */ export async function apply(ctx: Context): Promise { @@ -42,11 +50,22 @@ export async function apply(ctx: Context): Promise { bindHost: ctx.httpServer.host, platform: process.platform, env: process.env, + linuxChooser: hasLinuxChooserBinary(process.env.PATH, canExecute), }) await ctx.effect(async () => { // Root-tree create: the Loader root is in-memory (write() is a no-op), so // the mounted row can never be persisted back into a config file. const id = await ctx.loader.create({ name: BACKEND_PACKAGES[backend] }) - return () => { ctx.loader.remove(id) } + return async () => { + // Tree teardown (group.stop) can have removed the entry already; + // nothing is left to unmount or await then. + const entry = ctx.loader.store[id] + if (entry === undefined) return + const fiber = entry.fiber + ctx.loader.remove(id) + // remove() only starts the fiber's dispose; join it so the chooser's + // unload signals completion only after the backend quiesced. + await fiber?.dispose() + } }, 'directory-picker-auto: backend entry') } diff --git a/packages/host/directory-picker-auto/src/probe.ts b/packages/host/directory-picker-auto/src/probe.ts new file mode 100644 index 0000000000..17fd0c99f8 --- /dev/null +++ b/packages/host/directory-picker-auto/src/probe.ts @@ -0,0 +1,44 @@ +/** + * PATH probe for the native backend's Linux chooser binaries: one boot-time + * sampled fact for the resolver, so an attended Linux host without + * zenity/kdialog keeps the working `browse` interaction instead of a backend + * whose every pick fails. + * @module @deepseek-ai/dsh-host-directory-picker-auto/probe + */ + +import { accessSync, constants } from 'node:fs' +import { delimiter, join } from 'node:path' + +/** The chooser binaries the native backend can drive on Linux (zenity, KDialog fallback). */ +const LINUX_CHOOSER_BINARIES = ['zenity', 'kdialog'] as const + +/** + * Whether the current process may execute the candidate path. + * @param candidate - absolute or PATH-joined file path. + * @returns true only for an existing executable file. + */ +export function canExecute(candidate: string): boolean { + try { + accessSync(candidate, constants.X_OK) + } catch { + // Absent or non-executable candidate — the only signals accessSync(X_OK) emits. + return false + } + return true +} + +/** + * Scan a PATH value for one of the native backend's Linux chooser binaries. + * @param pathValue - the `PATH` environment value (absent or empty scans nothing). + * @param isExecutable - executability predicate ({@link canExecute} in production; injected for deterministic tests). + * @returns whether any PATH directory holds an executable chooser binary. + */ +export function hasLinuxChooserBinary(pathValue: string | undefined, isExecutable: (candidate: string) => boolean): boolean { + for (const dir of (pathValue ?? '').split(delimiter)) { + if (dir === '') continue + for (const name of LINUX_CHOOSER_BINARIES) { + if (isExecutable(join(dir, name))) return true + } + } + return false +} diff --git a/packages/host/directory-picker-auto/src/resolve.ts b/packages/host/directory-picker-auto/src/resolve.ts index d2a22e2fa8..395e2da55f 100644 --- a/packages/host/directory-picker-auto/src/resolve.ts +++ b/packages/host/directory-picker-auto/src/resolve.ts @@ -6,6 +6,8 @@ * @module @deepseek-ai/dsh-host-directory-picker-auto/resolve */ +import type { Config as HttpServerConfig } from '@deepseek-ai/dsh-host-webserver' + /** Concrete interaction backend the resolver chooses between. */ export type DirectoryPickerBackendKind = 'native' | 'browse' @@ -16,12 +18,14 @@ export type DirectoryPickerEnv = Readonly< /** Host facts the backend choice is a pure function of, sampled once at boot. */ export interface DirectoryPickerHostFacts { - /** Effective webserver bind host (`127.0.0.1` or `0.0.0.0`). */ - bindHost: string + /** Effective webserver bind host (the schema's closed loopback/all-interfaces union). */ + bindHost: HttpServerConfig['host'] /** Host process platform. */ platform: NodeJS.Platform /** Environment sample; SSH marks a remote operator, DISPLAY/WAYLAND_DISPLAY a Linux display. */ env: DirectoryPickerEnv + /** Whether a Linux chooser binary the native backend can drive (zenity/kdialog) is on PATH; consulted only when `platform` is linux. */ + linuxChooser: boolean } /** An env value counts only when set and non-blank (an empty export is "unset" by shell convention). */ @@ -29,12 +33,14 @@ const present = (value: string | undefined): boolean => value !== undefined && v /** * Resolve which backend serves this boot. `native` requires every signal that - * the operator can see the host display: a loopback-only bind (an - * all-interfaces bind admits remote browsers no OS chooser can reach), no SSH - * launch (under SSH port-forwarding the chooser would open on the unattended - * server), and a display session (assumed on darwin/win32, `DISPLAY`/ - * `WAYLAND_DISPLAY` elsewhere). Anything ambiguous resolves to `browse`, - * which works everywhere. + * the operator can see the host display and the native backend can serve it: + * a loopback-only bind (an all-interfaces bind admits remote browsers no OS + * chooser can reach), no SSH launch (under SSH port-forwarding the chooser + * would open on the unattended server), and a servable display session — + * assumed on darwin/win32, requiring `DISPLAY`/`WAYLAND_DISPLAY` plus a + * chooser binary on linux, and never true elsewhere (the native backend + * drives exactly darwin/win32/linux). Anything ambiguous resolves to + * `browse`, which works everywhere. * @param facts - the sampled host facts. * @returns the backend kind to mount. */ @@ -42,5 +48,6 @@ export function resolveDirectoryPickerBackend(facts: DirectoryPickerHostFacts): if (facts.bindHost !== '127.0.0.1') return 'browse' if (present(facts.env.SSH_CONNECTION) || present(facts.env.SSH_TTY)) return 'browse' if (facts.platform === 'darwin' || facts.platform === 'win32') return 'native' + if (facts.platform !== 'linux' || !facts.linuxChooser) return 'browse' return present(facts.env.DISPLAY) || present(facts.env.WAYLAND_DISPLAY) ? 'native' : 'browse' } diff --git a/packages/host/directory-picker-auto/tests/loader-composition.spec.ts b/packages/host/directory-picker-auto/tests/loader-composition.spec.ts index 7e094035fb..ce86a8d4ec 100644 --- a/packages/host/directory-picker-auto/tests/loader-composition.spec.ts +++ b/packages/host/directory-picker-auto/tests/loader-composition.spec.ts @@ -3,10 +3,12 @@ * vendored Loader mounts the webserver row plus the adaptive chooser, and the * assertions observe the durable outcome — which backend entry the chooser * mounted into the Loader store, the capability the seam then serves, and - * that disposing the chooser removes the mounted entry again (HMR safety). + * that disposing the chooser removes the mounted entry again (HMR safety), + * joining the backend's own teardown before the disposer settles. */ -import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { pathToFileURL } from 'node:url' @@ -25,21 +27,27 @@ const NATIVE = '@deepseek-ai/dsh-host-directory-picker-native' const BROWSE = '@deepseek-ai/dsh-host-directory-picker-browse' let root: string | undefined +let fakeBin: string | undefined let context: Context | undefined afterEach(async () => { vi.unstubAllEnvs() await context?.fiber.dispose() context = undefined - if (root !== undefined) await rm(root, { recursive: true, force: true }) + for (const dir of [root, fakeBin]) { + // maxRetries absorbs teardown stragglers (e.g. an unawaited fiber's late + // file handle) that can otherwise race the recursive scan into ENOTEMPTY. + if (dir !== undefined) await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 }) + } root = undefined + fakeBin = undefined }) /** Write a dist fixture and a two-row cordis.yml (webserver + chooser), then boot it through the real Loader. */ async function loadComposition(bindHost: '127.0.0.1' | '0.0.0.0'): Promise<{ ctx: Context; configPath: string }> { root = await mkdtemp(join(tmpdir(), 'dsh-directory-picker-auto-')) const dist = join(root, 'dist') - await mkdir(dist) + mkdirSync(dist) const distIndex = join(dist, 'index.html') await writeFile(distIndex, 'shell') const configPath = join(root, 'cordis.yml') @@ -83,17 +91,26 @@ function entryNames(ctx: Context): string[] { return [...ctx.loader.entries()].map(entry => entry.options.name) } -/** Force every signal of an attended host: no SSH launch, a display on any platform. */ +/** + * Force every signal of an attended host on any platform: no SSH launch, a + * display, and a PATH holding one executable chooser binary so the real + * probe resolves identically on hosts with and without zenity/kdialog. + */ function stubAttendedHost(): void { + fakeBin = mkdtempSync(join(tmpdir(), 'dsh-picker-bin-')) + const zenity = join(fakeBin, 'zenity') + writeFileSync(zenity, '#!/bin/sh\n') + chmodSync(zenity, 0o755) + vi.stubEnv('PATH', fakeBin) vi.stubEnv('SSH_CONNECTION', '') vi.stubEnv('SSH_TTY', '') vi.stubEnv('DISPLAY', ':0') } describe('real Loader composition', () => { - // Real-Loader composition resolves workspace packages through tsx at test - // time; first resolution after the host/client program split is slow enough - // to trip the default 5s budget on cold caches. + // The 60s budget covers this file's static imports (webserver plus both + // backend node halves through tsx), which dominate on cold caches; the + // Loader itself resolves nothing here — `loader.internal` is a module map. it('mounts the native backend for an attended loopback host and unmounts it on disposal', { timeout: 60_000 }, async () => { stubAttendedHost() const { ctx, configPath } = await loadComposition('127.0.0.1') @@ -110,12 +127,19 @@ describe('real Loader composition', () => { // booted config file must never gain the resolved backend row. expect(await readFile(configPath, 'utf8')).not.toContain(NATIVE) - // HMR safety: disposing the chooser's fiber removes the entry it created. + // HMR safety: disposing the chooser's fiber removes the entry it created, + // and the disposer joins the backend's teardown — the service is gone the + // moment dispose() settles, with no further loader await. const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)! await autoEntry.fiber!.dispose() - await ctx.loader.await() expect(entryNames(ctx)).not.toContain(NATIVE) expect(ctx.get('directoryPicker')).toBeUndefined() + // Self-disposing an include-tree entry persists `disabled: true` (loader + // behavior, not the chooser's); await that debounced write so it cannot + // race the temp-dir removal, and pin that the persisted row is the + // chooser itself — the resolved backend still never reaches the file. + await expect.poll(async () => await readFile(configPath, 'utf8')).toContain('disabled: true') + expect(await readFile(configPath, 'utf8')).not.toContain(NATIVE) }) it('mounts the browse backend under an SSH launch', { timeout: 60_000 }, async () => { @@ -136,4 +160,17 @@ describe('real Loader composition', () => { expect(entryNames(ctx)).toContain(BROWSE) expect(entryNames(ctx)).not.toContain(NATIVE) }) + + it('tolerates the mounted entry being removed by the tree before the chooser unloads', { timeout: 60_000 }, async () => { + stubAttendedHost() + const { ctx, configPath } = await loadComposition('127.0.0.1') + + const backendEntry = [...ctx.loader.entries()].find(entry => entry.options.name === NATIVE)! + ctx.loader.remove(backendEntry.id) + const autoEntry = [...ctx.loader.entries()].find(entry => entry.options.name === AUTO)! + await expect(autoEntry.fiber!.dispose()).resolves.not.toThrow() + expect(entryNames(ctx)).not.toContain(NATIVE) + // Same self-dispose persistence as above: let the write land before teardown. + await expect.poll(async () => await readFile(configPath, 'utf8')).toContain('disabled: true') + }) }) diff --git a/packages/host/directory-picker-auto/tests/resolve.spec.ts b/packages/host/directory-picker-auto/tests/resolve.spec.ts index 3beac44961..bf8792cfa9 100644 --- a/packages/host/directory-picker-auto/tests/resolve.spec.ts +++ b/packages/host/directory-picker-auto/tests/resolve.spec.ts @@ -1,12 +1,17 @@ -import { describe, expect, it } from 'vitest' +import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { delimiter, join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { canExecute, hasLinuxChooserBinary } from '../src/probe.ts' import { resolveDirectoryPickerBackend } from '../src/resolve.ts' import type { DirectoryPickerHostFacts } from '../src/resolve.ts' -/** Baseline facts that resolve to `native`; each case overrides one signal. */ +/** Baseline facts that resolve to `native`; each case overrides one signal (darwin never consults `linuxChooser`). */ const attended: DirectoryPickerHostFacts = { bindHost: '127.0.0.1', platform: 'darwin', env: {}, + linuxChooser: false, } describe('resolveDirectoryPickerBackend', () => { @@ -24,14 +29,63 @@ describe('resolveDirectoryPickerBackend', () => { expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_TTY: '/dev/pts/3' } })).toBe('browse') }) - it('requires a display session on platforms without an implied one', () => { - expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux' })).toBe('browse') - expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { DISPLAY: ':0' } })).toBe('native') - expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('native') + it('requires a display session and a chooser binary on linux', () => { + const linux: DirectoryPickerHostFacts = { ...attended, platform: 'linux', linuxChooser: true } + expect(resolveDirectoryPickerBackend(linux)).toBe('browse') + expect(resolveDirectoryPickerBackend({ ...linux, env: { DISPLAY: ':0' } })).toBe('native') + expect(resolveDirectoryPickerBackend({ ...linux, env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('native') + expect(resolveDirectoryPickerBackend({ ...linux, env: { DISPLAY: ':0' }, linuxChooser: false })).toBe('browse') + }) + + it('resolves browse on platforms the native backend cannot serve, display or not', () => { + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'freebsd', env: { DISPLAY: ':0' }, linuxChooser: true })).toBe('browse') + expect(resolveDirectoryPickerBackend({ ...attended, platform: 'openbsd', env: { WAYLAND_DISPLAY: 'wayland-1' } })).toBe('browse') }) it('treats blank env exports as unset', () => { expect(resolveDirectoryPickerBackend({ ...attended, env: { SSH_CONNECTION: '', SSH_TTY: '' } })).toBe('native') - expect(resolveDirectoryPickerBackend({ ...attended, platform: 'linux', env: { DISPLAY: '', WAYLAND_DISPLAY: '' } })).toBe('browse') + expect(resolveDirectoryPickerBackend({ + ...attended, platform: 'linux', linuxChooser: true, env: { DISPLAY: '', WAYLAND_DISPLAY: '' }, + })).toBe('browse') + }) +}) + +let probeRoot: string | undefined + +afterEach(() => { + if (probeRoot !== undefined) rmSync(probeRoot, { recursive: true, force: true }) + probeRoot = undefined +}) + +describe('hasLinuxChooserBinary', () => { + it('finds a chooser binary in any PATH segment, skipping empty segments', () => { + const seen: string[] = [] + const path = ['', '/opt/none', '/usr/local/bin'].join(delimiter) + const found = hasLinuxChooserBinary(path, (candidate) => { + seen.push(candidate) + return candidate === join('/usr/local/bin', 'kdialog') + }) + expect(found).toBe(true) + expect(seen).toEqual([ + join('/opt/none', 'zenity'), join('/opt/none', 'kdialog'), + join('/usr/local/bin', 'zenity'), join('/usr/local/bin', 'kdialog'), + ]) + }) + + it('reports absence when no segment holds a chooser binary', () => { + expect(hasLinuxChooserBinary(['/a', '/b'].join(delimiter), () => false)).toBe(false) + expect(hasLinuxChooserBinary('', () => true)).toBe(false) + expect(hasLinuxChooserBinary(undefined, () => true)).toBe(false) + }) +}) + +describe('canExecute', () => { + it('accepts an executable file and rejects an absent one', () => { + probeRoot = mkdtempSync(join(tmpdir(), 'dsh-picker-probe-')) + const binary = join(probeRoot, 'zenity') + writeFileSync(binary, '#!/bin/sh\n') + chmodSync(binary, 0o755) + expect(canExecute(binary)).toBe(true) + expect(canExecute(join(probeRoot, 'kdialog'))).toBe(false) }) }) diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts index 66d6e0f2a3..5ff429a2f4 100644 --- a/scripts/verify-cordis-config.ts +++ b/scripts/verify-cordis-config.ts @@ -30,6 +30,20 @@ interface PluginReference { const root = resolve(import.meta.dirname, '..') const metadataFields = ['id', 'name', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const + +/** The adaptive directory-picker chooser package (mounts a backend row at boot). */ +const CHOOSER_PACKAGE = '@deepseek-ai/dsh-host-directory-picker-auto' + +/** + * The backends the chooser mounts by runtime string (mirror of its exported + * `BACKEND_PACKAGES`), invisible to yml-row scanning: a composition mounting + * the chooser must resolve both, or keyless Linux CI (which only ever + * resolves `browse`) hides a dropped `-native` dependency until a macOS boot. + */ +const CHOOSER_BACKEND_PACKAGES = [ + '@deepseek-ai/dsh-host-directory-picker-native', + '@deepseek-ai/dsh-host-directory-picker-browse', +] const jsExprType = new yaml.Type('tag:yaml.org,2002:js', { kind: 'scalar', resolve: data => typeof data === 'string', @@ -134,12 +148,18 @@ function missingPluginDependencies( manifestPath: string, ): string[] { const requiredPackages = new Map>() + const require = (packageName: string, file: string): void => { + const locations = requiredPackages.get(packageName) ?? new Set() + locations.add(file) + requiredPackages.set(packageName, locations) + } for (const reference of references) { const packageName = packageNameFromSpecifier(reference.name) if (packageName === undefined) continue - const locations = requiredPackages.get(packageName) ?? new Set() - locations.add(reference.file) - requiredPackages.set(packageName, locations) + require(packageName, reference.file) + if (packageName === CHOOSER_PACKAGE) { + for (const backend of CHOOSER_BACKEND_PACKAGES) require(backend, reference.file) + } } return [...requiredPackages].flatMap(([packageName, locations]) => packageName in dependencies ? [] From 7b22a3b45483f29c3feb0e32cad3b200848ef387 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 11:50:16 +0800 Subject: [PATCH 21/67] =?UTF-8?q?feat(directory-picker-browse):=20quiet=20?= =?UTF-8?q?navigation=20=E2=80=94=20one-frame=20landings=20and=20a=20slow-?= =?UTF-8?q?scan=20loading=20pill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Navigations keep the previous view rendering while scanning: target and parent legs land as one two-pane frame when the parent leg settles within a 200ms wait bound (past it the target lands alone and the late leg upgrades in place; Escape inside the landing window withdraws the navigation). The loading indicator floats over the content on the card background and appears only once a scan outlives a 300ms silence window, so navigation never shifts the columns or flashes an intermediate frame. The truncated note now describes the on-screen panes instead of hiding during scans. --- ...directory-picker-capability-seam.i18n.yaml | 4 +- ...-07-28-directory-picker-capability-seam.md | 2 +- ...-28-directory-picker-capability-seam.zh.md | 2 +- .../directory-picker-browse/README.i18n.yaml | 4 +- .../host/directory-picker-browse/README.md | 2 +- .../host/directory-picker-browse/README.zh.md | 2 +- .../src/client/DirectoryBrowser.module.css | 15 ++ .../src/client/DirectoryBrowser.tsx | 116 ++++++++++++---- .../tests/directory-browser.spec.tsx | 128 +++++++++++++++++- 9 files changed, 235 insertions(+), 40 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index 900e1d01b6..edc0afb4c5 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: ad2aa904beddb2fe941883c3c1827702dbec9964 -2026-07-28-directory-picker-capability-seam.zh.md: 30e719ad9b4e8374496106b447e961a042c7d8b6 +2026-07-28-directory-picker-capability-seam.md: cfe0de43294439fadca2d7bc40a8c175d2cda372 +2026-07-28-directory-picker-capability-seam.zh.md: 7e2e16aa24bb4430667bdc1a5c12dfd1bd3a2e4f diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index ad2aa904be..cfe0de4329 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -20,7 +20,7 @@ Placement and policy rulings folded into this decision: - **Dependency survey (hand-roll vs adopt).** Node's stdlib *is* the maintained cross-platform OS layer (`readdir(withFileTypes)`, `homedir`, path semantics); surveyed alternatives fail the dependency bar — file-manager packages (`node-file-manager`, `files-and-folders`, Syncfusion's provider) are whole HTTP apps (fit), drive-letter helpers (`drivelist` native addon, `windows-drive-letters` ~7y stale) fail health/proportionality. The browse backend is a thin adapter over stdlib. - **Hidden entries: return-and-flag.** The host stamps `hidden` (POSIX dot convention) and returns everything; the client filters. Display policy stays client-side, and the show-hidden toggle shipped as exactly that client-only change: a fixed-label footer toggle whose state lives in the pressed presentation (`aria-pressed` + check glyph), a dot-led path-draft prefix reveals the hidden entries it names, and the current selection is exempt from both the hidden and the prefix filter (it anchors the two-pane view). Windows' `FILE_ATTRIBUTE_HIDDEN` is not exposed by dirents — documented limitation until a native probe pays for itself. - **Path-editor cancel scope: the dialog card.** The browse client's path editor cancels on Escape and on focus leaving the card, both observed at a card-scope wrapper rather than the input — after Tab parks focus on a filtered row the input is off the event path, yet Escape must collapse the editor (not the dialog) and a later focus departure must still cancel. Non-cancel exemptions: window/tab focus loss, in-card focus moves, and pointer paths (rows and the toggle suppress focus steal on mousedown while editing). Separators for seeding and draft-tail filtering are inferred from `listing.home`; the wire-field alternative below records the deferred authoritative form. Combobox semantics between the editor and the list it filters (`aria-expanded`/`aria-controls`/active-descendant, result announcements) are likewise deferred — today they read to assistive tech as separate widgets. -- **Navigation lands selection-anchored, progressively.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the browse client's navigate commits the target level the moment it arrives — the editor closes and loading ends on that first settlement, so an Enter-submitted navigation is never withdrawn waiting on more — and a parent leg then upgrades the landing in place: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent; a failed parent leg, or a truncated parent window lacking the target, leaves the committed single-pane landing — the upgrade must never orphan the selection it exists to anchor. +- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content (never a layout-shifting row) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. - **Symlinks: follow for enterability.** `stat` probes symlinks (broken/cyclic → skipped); crumbs keep the logical path the operator navigated, and `workspace.create` already canonicalizes via realpath at adoption. - **Listing levels are bounded, and streamed.** One `list` call returns at most `maxEntries` rows (config, default 1000 — GitHub's web-UI directory-listing bound). The level streams via `opendir` into a name-sorted window of `maxEntries + 1` candidates, so memory stays O(maxEntries) and enterability probing touches only windowed candidates; the wire `DirectoryListing` carries a required `truncated` flag so the client states incompleteness instead of silently missing tail entries. A windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated. Window insertion is binary with an O(1) full-window tail rejection (an oversized level must not pay a window scan per dirent), and `list(path, signal)` threads the carrier's request signal so a scan of a stalled network directory cannot outlive a disconnected caller — every await in the scan (open, each read, each symlink probe) races the signal, an aborted exit abandons rather than awaits the close (Node queues close behind in-flight reads), and abandoned settlements are swallowed so cleanup can never surface as an unhandled rejection. An unbounded level is a memory/responsiveness hole for large or adversarial directories. - **Whole-filesystem scope, no roots config.** `workspace.create` accepts arbitrary paths and the API serves bash-driving methods, so a browse root would be UX scoping, not a boundary; configurability without a consumer fails the evidence bar. Deferred until a deployment needs it. diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 30e719ad9b..7e2e16aa24 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -20,7 +20,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick - **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。 - **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。 - **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。 -- **导航以选中项为锚、渐进落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），browse 客户端的导航在目标层级到达的那一刻即提交它——这次首个落定即关闭编辑器并结束加载，因此 Enter 提交的导航绝不会为等待更多内容而被撤回——随后父层级这一程就地升级这次落地：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止；父层级这一程失败，或被截断的父窗口缺少目标时，都保留已提交的单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。 +- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容之上（绝不是会挪动布局的一行），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。 - **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。 - **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。 diff --git a/packages/host/directory-picker-browse/README.i18n.yaml b/packages/host/directory-picker-browse/README.i18n.yaml index d807bd737a..673d053e3a 100644 --- a/packages/host/directory-picker-browse/README.i18n.yaml +++ b/packages/host/directory-picker-browse/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/directory-picker-browse/README.md -README.md: 23153881b84dcb71dfb05d4f297a5818c410ca77 -README.zh.md: d7010e2941a801ba6358082824330eaae46e42b7 +README.md: 52b5fe7e89f915be3b50324628e9d5c48f1ef94c +README.zh.md: 742da39470083887a71ddba4a7c8012f0ce0ea1f diff --git a/packages/host/directory-picker-browse/README.md b/packages/host/directory-picker-browse/README.md index 23153881b8..52b5fe7e89 100644 --- a/packages/host/directory-picker-browse/README.md +++ b/packages/host/directory-picker-browse/README.md @@ -6,7 +6,7 @@ The **in-app browsing backend** of the [directory-picker seam](../directory-pick Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Both primitives reject an explicit path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`) that `isAbsolute` accepts — with `directory-unreadable`/`directory-create-failed`, instead of letting `resolve` rebase it under the host process cwd or current drive. One `list` call returns at most `maxEntries` rows (config, default 1000 — the bound GitHub's web UI applies to directory listings), and the level streams through a bounded window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, counts hidden rows against the bound, probes only windowed candidates, and reports `truncated: true` so the client can say the level is incomplete (a windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated); window insertion is binary with an O(1) full-window tail rejection, and `list` threads the caller's `AbortSignal` so a disconnect or timeout stops the scan instead of letting it outlive the caller. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md). -**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored: a crumb jump or a submitted path commits the target immediately, then re-selects its actual entry in its parent level once that level arrives — two panes, so stepping back never collapses (a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). +**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored and quiet: the previous view keeps rendering while a crumb jump or a submitted path is scanned (a "Loading…" pill floats over it only once the scan outlives a 300ms silence window, never shifting the columns), then target and parent legs land as one two-pane frame with the target re-selected as its actual parent-level entry — so stepping back never collapses and no intermediate frame flashes (a parent leg outliving its 200ms wait bound lands the target alone and upgrades in place; a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). ## Model Experience diff --git a/packages/host/directory-picker-browse/README.zh.md b/packages/host/directory-picker-browse/README.zh.md index d7010e2941..742da39470 100644 --- a/packages/host/directory-picker-browse/README.zh.md +++ b/packages/host/directory-picker-browse/README.zh.md @@ -6,7 +6,7 @@ 行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限），且层级以流式方式经过一个有界窗口，无论目录有多少子项内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`，供客户端提示层级不完整（窗口内的断链符号链接不会从窗口外回填——发生过驱逐本身已把层级标记为截断）；窗口插入为二分查找、满窗尾部单次比较即拒绝，且 `list` 透传调用方的 `AbortSignal`，断连或超时会停止扫描而不是让它在调用方离开后继续。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。 -**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚落地：crumb 跳转或提交的路径会立即提交目标，待父层级到达后再在其中重新选中目标的实际条目——双栏，因此后退绝不塌缩（父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 +**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚、安静落地：扫描 crumb 跳转或提交的路径期间，先前视图持续渲染（"Loading…" 胶囊仅在扫描超出 300ms 静默窗口后才浮于其上，绝不挪动各列），随后目标与父层级两程以单个双栏帧落地，目标被重新选中为其在父层级中的实际条目——因此后退绝不塌缩，也没有中间帧闪现（父层级这一程超出其 200ms 等待上限时，目标单独落地，随后就地升级；父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 ## 模型体验 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index 85349962e5..bfa50aa987 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -146,11 +146,26 @@ flex-direction: column; flex: 1 1 0; min-height: 0; + /* Anchors the floating loading pill (.loadingFloat). */ + position: relative; /* Right inset is slimmer than the left: the trailing column's own 8px * scrollbar clearance makes up the optical difference. */ padding: 16px 16px 16px 24px; } +/* The slow-scan indicator floats over the content's bottom-left on the card + * background instead of occupying a row: a scan must never shift the + * columns' height, and the stale view keeps rendering beneath it (it only + * appears at all once a scan outlives SLOW_SCAN_DELAY_MS). */ +.loadingFloat { + position: absolute; + left: 24px; + bottom: 8px; + padding: 2px 8px; + border-radius: 6px; + background: var(--dsw-alias-bg-layer-2); +} + /* Columns split the row evenly around the divider (a solo column takes the * whole row); 256px is the floor below which the row scrolls (scrollbar * hidden, the effect pins the child pane into view) instead of squeezing diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 859667d115..0610dbb8a6 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -5,10 +5,12 @@ * breadcrumb, and a click-to-edit path zone; below it a Miller view — one * full-width level until a row is selected, then two columns splitting the * row evenly (256px floor; level | selected folder's children) around a - * hairline divider. Navigations land selection-anchored: a crumb jump or a - * submitted path commits the target immediately, then re-selects it in its - * parent level once that level arrives, so stepping back keeps two panes - * away from the display root. Selecting in the + * hairline divider. Navigations land selection-anchored and quiet: the + * previous view keeps rendering while a crumb jump or a submitted path is + * scanned, then target and parent legs land as one two-pane frame (a slow + * parent leg falls back to landing the target alone and upgrading in + * place), so stepping back keeps two panes away from the display root and + * navigation never flashes an intermediate frame. Selecting in the * right column shifts the view one level deeper. "New folder" opens a nested * create dialog targeting the selected folder (or the level itself) and * selects the created folder. Open adopts the selected folder, falling back @@ -55,6 +57,24 @@ function failureText(error: unknown): string { return error instanceof Error ? error.message : String(error) } +/** + * How long a scan may stay visually silent before the floating "Loading…" + * pill appears. The stale view keeps rendering while a scan is in flight, so + * a listing that settles inside this window swaps the panes with no + * intermediate frame at all; only a genuinely slow host (a network mount, a + * cold disk) surfaces the indicator. + */ +const SLOW_SCAN_DELAY_MS = 300 + +/** + * How long a navigation landing waits for its parent leg before committing + * the target alone. Inside the window both legs land as ONE two-pane frame — + * no single-pane flash between them; past it the target commits single-pane + * at once (an Enter-submitted navigation is never held hostage by a stalled + * parent) and the late parent leg upgrades the landing in place. + */ +const PARENT_LEG_WAIT_MS = 200 + /** * Breadcrumb rows for display: inside the home subtree the chain starts at a * localized Home crumb; outside it the full ancestry shows, the root labeled @@ -166,6 +186,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const [selected, setSelected] = useState(null) const [child, setChild] = useState(null) const [loading, setLoading] = useState(false) + // Derived from `loading` by the slow-scan effect below: true only once a + // scan has been in flight for SLOW_SCAN_DELAY_MS, so fast listings never + // render the indicator at all. + const [slowScan, setSlowScan] = useState(false) const [error, setError] = useState(null) // Path-edit state: null = breadcrumb mode; a string = the draft being typed. const [pathDraft, setPathDraft] = useState(null) @@ -228,17 +252,20 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }, [listDirectory]) /** - * Replace the whole view with a freshly navigated level. The target level - * commits the moment it arrives (single wide level: the editor closes and - * loading ends on this first settlement, so an Enter-submitted navigation - * is never withdrawn waiting on anything further). Away from the display - * root — the same collapse the crumb header renders, so crumbs and pane - * shape never disagree — a parent leg then upgrades the landing in place: - * the target's ACTUAL parent-level entry re-selected (left pane = parent, - * right pane = the target), so a crumb jump reads as stepping back one - * pane. A failed parent leg, or a truncated parent window that lacks the - * target, leaves the committed single-pane landing — the upgrade must - * never orphan the selection it exists to anchor. + * Replace the whole view with a freshly navigated level. Away from the + * display root — the same collapse the crumb header renders, so crumbs and + * pane shape never disagree — the landing is two-pane: the target's ACTUAL + * parent-level entry re-selected (left pane = parent, right pane = the + * target), so a crumb jump reads as stepping back one pane. Both legs land + * as one frame when the parent leg settles within + * {@link PARENT_LEG_WAIT_MS}; past that bound (or at the display root) the + * target commits alone — single wide level, the editor closes, loading + * ends — and a late parent leg still upgrades the landing in place. A + * failed parent leg, or a truncated parent window that lacks the target, + * leaves the single-pane landing — the upgrade must never orphan the + * selection it exists to anchor. Until whichever commit comes first, the + * previous view keeps rendering: navigation swaps the panes, it never + * blanks them. */ const navigate = useCallback((path?: string) => { const { seq, scan } = launchListing(path) @@ -246,16 +273,23 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, setError(null) scan.then((target) => { if (seq !== requestSeq.current) return - setParent(target) - setSelected(null) - setChild(null) - setLoading(false) - setPathDraft(null) + // The single-pane landing; `landed` makes it first-commit-only, while + // the two-pane commit below may still upgrade an already-landed view. + let landed = false + const landSingle = (): void => { + if (landed || seq !== requestSeq.current) return + landed = true + setParent(target) + setSelected(null) + setChild(null) + setLoading(false) + setPathDraft(null) + } // Arity is label-independent: only the collapsed chain's depth decides. - if (displayCrumbs(target, '').length < 2) return + if (displayCrumbs(target, '').length < 2) { landSingle(); return } const parentCrumb = target.crumbs.at(-2) /* v8 ignore next -- narrowing: a two-deep display chain implies a parent crumb (root-to-target inclusive). */ - if (parentCrumb === undefined) return + if (parentCrumb === undefined) { landSingle(); return } continueScan(parentCrumb.path).then((parentLevel) => { if (seq !== requestSeq.current) return // Windows resolves a typed path preserving its case; anchor on the @@ -263,15 +297,23 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const sep = separatorOf(parentLevel) const fold = (value: string): string => (sep === '\\' ? value.toLowerCase() : value) const match = parentLevel.entries.find(entry => fold(entry.path) === fold(target.path)) - if (match === undefined) return + if (match === undefined) { landSingle(); return } + landed = true setParent(parentLevel) setSelected(match) setChild(target) + // Idempotent on a late upgrade of a timed-out landing: reopening the + // editor or starting a newer scan supersedes this seq, so reaching + // here means the draft is closed and the loading flag is this + // navigation's own. + setLoading(false) + setPathDraft(null) }, () => { - // Swallows the parent-leg failure (its abort included): the - // committed single-pane landing stands, and nobody asked to see - // the parent level. + // The parent-leg failure (its abort included) never surfaces: the + // target listed fine, and nobody asked to see the parent level. + landSingle() }) + window.setTimeout(landSingle, PARENT_LEG_WAIT_MS) }, (reason: unknown) => { if (seq !== requestSeq.current) return setLoading(false) @@ -415,6 +457,18 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }) } + // The slow-scan gate for the loading indicator: arm a timer when a scan + // starts, retire it (and the indicator) the moment loading ends. A settle + // inside the window means the swap happened with nothing shown. + useEffect(() => { + if (!loading) { + setSlowScan(false) + return + } + const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS) + return () => { window.clearTimeout(timer) } + }, [loading]) + // After the hooks: a closed dialog renders nothing and evaluates no copy. const crumbSource = child ?? parent const crumbs = crumbSource === null ? [] : displayCrumbs(crumbSource, t('browser.home')) @@ -649,11 +703,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, /> )} - {loading &&
{t('browser.loading')}
} + {loading && slowScan + &&
{t('browser.loading')}
} {/* The backend bounds a level at its complete-result limit; say so * whenever a visible pane was cut instead of letting the tail of a - * huge directory go silently missing. */} - {(parent?.truncated === true || child?.truncated === true) && !loading + * huge directory go silently missing. The note describes the panes + * on screen, so an in-flight scan leaves it alone — hiding it while + * the stale view still shows the cut level would shift the columns + * on every navigation away from it. */} + {(parent?.truncated === true || child?.truncated === true) &&
{t('browser.truncated')}
} {error !== null &&
{error}
} diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 6fa9bb999f..2528af4b46 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -235,7 +235,7 @@ describe('DirectoryBrowser', () => { expect(columns()).toHaveLength(1) }) - it('commits the target immediately, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { + it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { const signals: (AbortSignal | undefined)[] = [] const settlers: ((value: DirectoryListing) => void)[] = [] // Only the FIRST explicit HOME request (the parent leg) hangs; the later @@ -253,8 +253,8 @@ describe('DirectoryBrowser', () => { fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // The target leg commits at once: editor closed, single-pane DOCS level, - // while the parent leg (upgrade) is still in flight. + // The parent leg (upgrade) hangs past the landing wait bound: the target + // commits alone — editor closed, single-pane DOCS level. await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') }) expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() expect(columns()).toHaveLength(1) @@ -270,6 +270,128 @@ describe('DirectoryBrowser', () => { expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() }) + /** + * Listing fake whose explicit-path scans stay pending until the test + * settles them by path; the absent-path form (the initial home listing) + * resolves normally so mounting is a one-flush setup. + */ + function manualLister() { + const settlers = new Map void>() + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve(listingFor(path)) + return new Promise((resolve) => { settlers.set(path, resolve) }) + }) + return { settlers, listDirectory } + } + + it('lands a navigation as ONE two-pane frame: the stale view holds until both legs arrive', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target settles while the parent leg is still in flight: nothing + // commits yet — the editor stays open over the stale home level, and no + // single-pane DOCS frame ever renders. + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy() + expect(screen.queryByText('harness')).toBeNull() + // The parent leg settles inside the wait bound: one commit straight to + // the two-pane landing, editor closed. + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(columns()).toHaveLength(2) + expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true') + expect(within(columns()[0]!).getByText('Documents')).toBeTruthy() + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + // The wait-bound timer firing after the landing is a no-op. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(2) + } finally { + vi.useRealTimers() + } + }) + + it('a stalled parent leg lands the target alone at the wait bound, then upgrades in place', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // The parent leg outlives PARENT_LEG_WAIT_MS: the target lands alone. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(1) + expect(screen.getByRole('listitem').textContent).toBe('harness') + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + // The late parent leg still upgrades the landing in place, exactly as + // if it had made the bound. (Reopening the editor meanwhile would + // supersede the upgrade — the editor-open handler withdraws pending + // listings — so a late upgrade can never close a resumed draft.) + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(columns()).toHaveLength(2) + expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true') + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + } finally { + vi.useRealTimers() + } + }) + + it('Escape inside the landing window withdraws the submitted navigation', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + const input = screen.getByLabelText('browser.editPath') + fireEvent.change(input, { target: { value: DOCS } }) + fireEvent.keyDown(input, { key: 'Enter' }) + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // Nothing has committed yet; Escape supersedes the landing entirely. + fireEvent.keyDown(input, { key: 'Escape' }) + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(1) + expect(screen.queryByText('harness')).toBeNull() + expect(within(columns()[0]!).getByText('Documents')).toBeTruthy() + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + } finally { + vi.useRealTimers() + } + }) + + it('shows the loading indicator only once a scan outlives its silence window, floating over the stale view', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + expect(screen.queryByText('browser.loading')).toBeNull() + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // In flight but still inside the silence window: nothing shows. + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(300) }) + // Past it: the indicator floats while the stale level keeps rendering. + expect(screen.getByRole('status').textContent).toBe('browser.loading') + expect(screen.getByText('Documents')).toBeTruthy() + // Landing (both legs) retires the indicator with the scan. + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(screen.queryByText('browser.loading')).toBeNull() + expect(columns()).toHaveLength(2) + } finally { + vi.useRealTimers() + } + }) + it('keeps the single-pane landing when the truncated parent level lacks the target', async () => { const listDirectory = vi.fn(async (path?: string) => { // The parent leg names HOME explicitly; serve it a truncated window From 6ee2752ccaf7a3b9d933154ed45cdf251feff9eb Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 12:09:45 +0800 Subject: [PATCH 22/67] fix(directory-picker-browse): rebind the scrollbar elevation pair on the browser card The loading pill's layer-2 background made the sheet an elevated-surface painter, and the ui-theme scrollbar invariant rightly flagged what was already latent: the dialog's columns scroll on an l2 card while the thumbs rendered in the base-surface pair. Rebind the indirection on the card rule so it inherits to the scrolling columns. --- .../src/client/DirectoryBrowser.module.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index bfa50aa987..d440b94862 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -13,6 +13,12 @@ height: min(500px, calc(100dvh - 32px)); padding: 0; gap: 0; + /* The Modal card is an l2 surface and the columns below scroll on it: + * rebind the scrollbar indirection to the elevation pair here, on the + * surface, so it inherits down to whichever descendant scrolls (the + * rebinding contract in ui-theme styles/scrollbar.css). */ + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); } /* Card-scope wrapper hosting the path editor's Escape and focus-leave From 3ba25e25c0650dc443ba9eb7f7b10a82246ad143 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 12:53:07 +0800 Subject: [PATCH 23/67] =?UTF-8?q?fix(directory-picker-browse):=20bot=20rou?= =?UTF-8?q?nd=201=20=E2=80=94=20pill=20cascade+corner,=20slow-scan=20close?= =?UTF-8?q?=20reset,=20asymmetry+calibration=20recorded?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .loadingFloat moved after the .status/.error block (its padding was losing the same-specificity race) and re-anchored bottom-right: the truncated/error rows own the bottom left and keep rendering through a scan, so the pill can never cover them; confirmCreate's relist now clears the stale failure text like every other scan launch. - The close edge resets loading, so the slow-scan effect disarms while hidden and a reopened dialog waits out a fresh silence window (regression test added). - The truncated note's survival through a scan is now asserted in the slow-scan test; the wait-bound test moved to fake timers with the 200ms bound explicit. - select()'s exemption from the one-frame rule and the constants' local calibration premise are recorded in JSDoc and the capability-seam Agent Note; the themed-scrollbars note's rebinding enumeration is replaced by a pointer to the mechanical gate (it had drifted twice). Both pairs re-recorded. --- ...directory-picker-capability-seam.i18n.yaml | 4 +- ...-07-28-directory-picker-capability-seam.md | 2 +- ...-28-directory-picker-capability-seam.zh.md | 2 +- ...d-scrollbars-and-reserved-gutter.i18n.yaml | 4 +- ...8-themed-scrollbars-and-reserved-gutter.md | 2 +- ...hemed-scrollbars-and-reserved-gutter.zh.md | 2 +- .../src/client/DirectoryBrowser.module.css | 30 +++-- .../src/client/DirectoryBrowser.tsx | 19 ++- .../tests/directory-browser.spec.tsx | 127 +++++++++++++----- 9 files changed, 133 insertions(+), 59 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index edc0afb4c5..5b33f27a5c 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: cfe0de43294439fadca2d7bc40a8c175d2cda372 -2026-07-28-directory-picker-capability-seam.zh.md: 7e2e16aa24bb4430667bdc1a5c12dfd1bd3a2e4f +2026-07-28-directory-picker-capability-seam.md: 892bb4b2c4fe200df91866c4ec4cf8bb7c58e940 +2026-07-28-directory-picker-capability-seam.zh.md: d738773adc853dae7b3496f0dc2901eebd0f0a08 diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index cfe0de4329..892bb4b2c4 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -20,7 +20,7 @@ Placement and policy rulings folded into this decision: - **Dependency survey (hand-roll vs adopt).** Node's stdlib *is* the maintained cross-platform OS layer (`readdir(withFileTypes)`, `homedir`, path semantics); surveyed alternatives fail the dependency bar — file-manager packages (`node-file-manager`, `files-and-folders`, Syncfusion's provider) are whole HTTP apps (fit), drive-letter helpers (`drivelist` native addon, `windows-drive-letters` ~7y stale) fail health/proportionality. The browse backend is a thin adapter over stdlib. - **Hidden entries: return-and-flag.** The host stamps `hidden` (POSIX dot convention) and returns everything; the client filters. Display policy stays client-side, and the show-hidden toggle shipped as exactly that client-only change: a fixed-label footer toggle whose state lives in the pressed presentation (`aria-pressed` + check glyph), a dot-led path-draft prefix reveals the hidden entries it names, and the current selection is exempt from both the hidden and the prefix filter (it anchors the two-pane view). Windows' `FILE_ATTRIBUTE_HIDDEN` is not exposed by dirents — documented limitation until a native probe pays for itself. - **Path-editor cancel scope: the dialog card.** The browse client's path editor cancels on Escape and on focus leaving the card, both observed at a card-scope wrapper rather than the input — after Tab parks focus on a filtered row the input is off the event path, yet Escape must collapse the editor (not the dialog) and a later focus departure must still cancel. Non-cancel exemptions: window/tab focus loss, in-card focus moves, and pointer paths (rows and the toggle suppress focus steal on mousedown while editing). Separators for seeding and draft-tail filtering are inferred from `listing.home`; the wire-field alternative below records the deferred authoritative form. Combobox semantics between the editor and the list it filters (`aria-expanded`/`aria-controls`/active-descendant, result announcements) are likewise deferred — today they read to assistive tech as separate widgets. -- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content (never a layout-shifting row) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. +- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content's bottom-right corner (never a layout-shifting row; the truncated/error rows own the bottom left and keep rendering through a scan) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. Row picks are deliberately exempt from the one-frame rule: a pick's immediate pane split is its selected-state feedback (aria-current, crumbs following), while a navigation has nothing to acknowledge the click but the swap itself. Both timing constants are calibrated for local enumeration; a remote deployment (one RPC per level, commonly 100–400ms) would sit inside the silence window with no pressed state on the crumbs — revisit the window or add pressed feedback when a remote consumer lands. - **Symlinks: follow for enterability.** `stat` probes symlinks (broken/cyclic → skipped); crumbs keep the logical path the operator navigated, and `workspace.create` already canonicalizes via realpath at adoption. - **Listing levels are bounded, and streamed.** One `list` call returns at most `maxEntries` rows (config, default 1000 — GitHub's web-UI directory-listing bound). The level streams via `opendir` into a name-sorted window of `maxEntries + 1` candidates, so memory stays O(maxEntries) and enterability probing touches only windowed candidates; the wire `DirectoryListing` carries a required `truncated` flag so the client states incompleteness instead of silently missing tail entries. A windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated. Window insertion is binary with an O(1) full-window tail rejection (an oversized level must not pay a window scan per dirent), and `list(path, signal)` threads the carrier's request signal so a scan of a stalled network directory cannot outlive a disconnected caller — every await in the scan (open, each read, each symlink probe) races the signal, an aborted exit abandons rather than awaits the close (Node queues close behind in-flight reads), and abandoned settlements are swallowed so cleanup can never surface as an unhandled rejection. An unbounded level is a memory/responsiveness hole for large or adversarial directories. - **Whole-filesystem scope, no roots config.** `workspace.create` accepts arbitrary paths and the API serves bash-driving methods, so a browse root would be UX scoping, not a boundary; configurability without a consumer fails the evidence bar. Deferred until a deployment needs it. diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 7e2e16aa24..d738773adc 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -20,7 +20,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick - **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。 - **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。 - **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。 -- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容之上（绝不是会挪动布局的一行），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。 +- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。两个时序常量都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态——待远程消费方落地时，重新审视该窗口或补上按下反馈。 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。 - **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。 - **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml index a205f48f54..8099344ace 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md -2026-07-28-themed-scrollbars-and-reserved-gutter.md: 38228c868bb00210118e8110feb722fb81d0d56c -2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 9fafe1faa9303b5e2e23a1b3064904f71494026d +2026-07-28-themed-scrollbars-and-reserved-gutter.md: 76dcb6d9f3976faf3338a89f3ccab7182fe6d5ab +2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: ff12c6884bec706dbbd9974684010cbcd9fa03bf diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md index 38228c868b..76dcb6d9f3 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md @@ -20,7 +20,7 @@ The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-a The two renderings are mutually exclusive, and the exclusion is enforced rather than assumed. A non-`auto` `scrollbar-width` or `scrollbar-color` makes Chromium and Safari discard every `::-webkit-scrollbar*` rule for that element, `::-webkit-scrollbar-thumb:hover` included. Declaring both unconditionally therefore leaves the hover token rendering nowhere at all: the engines that implement the hover pseudo-element are exactly the ones the standard properties silence, and Firefox has no hover pseudo-element to fall back on. The standard properties consequently sit inside `@supports not selector(::-webkit-scrollbar)`, which is true only where the pseudo-element is unimplemented, so Firefox takes the standard path and WebKit-based engines take the pseudo-element path. The WebKit rules are not gated in turn: an engine without those pseudo-elements drops them as unknown selectors, so a gate would only restate what selector matching already does. An engine too old for the `selector()` function makes the condition invalid, which evaluates false and selects the pseudo-element path — the correct side for the pre-16.4 Safari that is the realistic case for that reading. -Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. Eight surfaces rebind today: the command popup, the slash menu, the model-select panel, the settings panel, the shared `ui-primitives` menu card, the composer input card, the question composer card, and the todo panel. Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. +Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The set of rebinding surfaces is owned by the mechanical gate (`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`): any sheet that scrolls and paints an elevated surface must rebind, so this note no longer enumerates them (an enumeration here drifted twice). Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. The last four were missed in the first implementation and found in review, which is why the rebinding contract is now checked mechanically rather than by inspection: a sheet that scrolls somewhere and paints an elevated surface somewhere must rebind. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md index 9fafe1faa9..ff12c6884b 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md @@ -20,7 +20,7 @@ Status: implemented 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。 -两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。目前有八处抬升表面做了重新绑定：命令浮层、斜杠菜单、模型选择面板、设置面板、`ui-primitives` 共用菜单卡片、输入条卡片、提问组件卡片与待办面板。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 +两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。重新绑定表面的集合归机械门禁（`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`）所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再枚举它们（这里的枚举已经漂移过两次）。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 后四处在最初的实现里被漏掉、由评审发现，因此重新绑定契约现在由机械检查把关，而不再依赖人工审阅：一张样式表只要在某处滚动、又在某处绘制抬升表面，就必须重新绑定。 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index d440b94862..594f450756 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -159,19 +159,6 @@ padding: 16px 16px 16px 24px; } -/* The slow-scan indicator floats over the content's bottom-left on the card - * background instead of occupying a row: a scan must never shift the - * columns' height, and the stale view keeps rendering beneath it (it only - * appears at all once a scan outlives SLOW_SCAN_DELAY_MS). */ -.loadingFloat { - position: absolute; - left: 24px; - bottom: 8px; - padding: 2px 8px; - border-radius: 6px; - background: var(--dsw-alias-bg-layer-2); -} - /* Columns split the row evenly around the divider (a solo column takes the * whole row); 256px is the floor below which the row scrolls (scrollbar * hidden, the effect pins the child pane into view) instead of squeezing @@ -267,6 +254,23 @@ color: var(--dsw-alias-state-error-primary); } +/* The slow-scan indicator floats over the content's bottom-RIGHT corner on + * the card background instead of occupying a row: a scan must never shift + * the columns' height, and the stale view keeps rendering beneath it (it + * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right, + * not left: the truncated/error status rows flow at the bottom LEFT and + * stay on screen through a scan, so the opposite corner keeps both + * legible. After .status in the cascade — the element carries both + * classes and this padding must win the same-specificity race. */ +.loadingFloat { + position: absolute; + right: 16px; + bottom: 8px; + padding: 2px 8px; + border-radius: 6px; + background: var(--dsw-alias-bg-layer-2); +} + /* Footer: l3 separator on top, symmetric padding so the row sits vertically * centered in the bar; New-folder and the show-hidden toggle pin left. */ .footerBar { diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 0610dbb8a6..023404f71d 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -331,7 +331,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const pathInputRef = useRef(null) const editZoneRef = useRef(null) - /** Select a row of the listed level and preview its children on the right. */ + /** + * Select a row of the listed level and preview its children on the right. + * Deliberately NOT one-frame like navigate(): a pick's first duty is the + * immediate selected state on the clicked row, and the pane split IS that + * feedback (aria-current pill, crumbs following the selection) — holding + * it back for the child listing would make clicks feel dropped. The quiet + * rule governs whole-view replacement, where nothing acknowledges the + * click but the swap itself. + */ const select = useCallback((entry: DirectoryEntry) => { const { seq, scan } = launchListing(entry.path) // A pick while the path editor is open adopts the (filtered) row and @@ -402,6 +410,11 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, return } supersede() + // Closing mid-scan leaves nothing to load: without this edge the + // slow-scan effect keeps arming while hidden and the reopened dialog + // would show the indicator on its first frame instead of waiting out a + // fresh silence window (reopen's navigate() produces no loading edge). + setLoading(false) setError(null) setPathDraft(null) setFolderDraft(null) @@ -438,6 +451,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, // create target becomes the listed level and the new folder its selection. const { seq, scan } = launchListing(targetPath) setLoading(true) + // Symmetric with navigate/select: a launched scan clears the stale + // failure text (and keeps the floating indicator's corner the only + // occupant of the content's right edge while it shows). + setError(null) scan.then((level) => { /* v8 ignore next -- same fence as navigate/select; the modal blocks superseding input */ if (seq !== requestSeq.current) return diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 2528af4b46..0fe1f91e00 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -236,38 +236,49 @@ describe('DirectoryBrowser', () => { }) it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { - const signals: (AbortSignal | undefined)[] = [] - const settlers: ((value: DirectoryListing) => void)[] = [] - // Only the FIRST explicit HOME request (the parent leg) hangs; the later - // home crumb jump lists normally. - let homeCalls = 0 - const listDirectory = vi.fn(async (path?: string, signal?: AbortSignal) => { - signals.push(signal) - if (path === HOME && ++homeCalls === 1) { - return new Promise((resolve) => { settlers.push(resolve) }) - } - return listingFor(path) - }) - mount({ listDirectory }) - await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) - fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) - fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) - fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // The parent leg (upgrade) hangs past the landing wait bound: the target - // commits alone — editor closed, single-pane DOCS level. - await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') }) - expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() - expect(columns()).toHaveLength(1) - await waitFor(() => { expect(settlers).toHaveLength(1) }) - // A newer jump aborts the pending parent leg ON THE WIRE, not merely - // dropping its settlement. - fireEvent.click(screen.getByRole('button', { name: 'browser.home' })) - expect(signals[2]?.aborted).toBe(true) - await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('Documents') }) - // Its late resolution changes nothing either. - await act(async () => { settlers[0]!(listingFor(HOME)) }) - expect(columns()).toHaveLength(1) - expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() + vi.useFakeTimers() + try { + const signals: (AbortSignal | undefined)[] = [] + const settlers: ((value: DirectoryListing) => void)[] = [] + // Only the FIRST explicit HOME request (the parent leg) hangs; the + // later home crumb jump lists normally. + let homeCalls = 0 + const listDirectory = vi.fn((path?: string, signal?: AbortSignal) => { + signals.push(signal) + if (path === HOME && ++homeCalls === 1) { + return new Promise((resolve) => { settlers.push(resolve) }) + } + return Promise.resolve(listingFor(path)) + }) + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target settled but the parent leg hangs: inside the wait bound + // nothing commits yet. + await act(async () => {}) + expect(settlers).toHaveLength(1) + expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy() + // The wait bound expires: the target commits alone — editor closed, + // single-pane DOCS level. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(screen.getByRole('listitem').textContent).toBe('harness') + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + expect(columns()).toHaveLength(1) + // A newer jump aborts the pending parent leg ON THE WIRE, not merely + // dropping its settlement. + fireEvent.click(screen.getByRole('button', { name: 'browser.home' })) + expect(signals[2]?.aborted).toBe(true) + await act(async () => {}) + expect(screen.getByRole('listitem').textContent).toBe('Documents') + // Its late resolution changes nothing either. + await act(async () => { settlers[0]!(listingFor(HOME)) }) + expect(columns()).toHaveLength(1) + expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() + } finally { + vi.useRealTimers() + } }) /** @@ -369,29 +380,71 @@ describe('DirectoryBrowser', () => { it('shows the loading indicator only once a scan outlives its silence window, floating over the stale view', async () => { vi.useFakeTimers() try { - const { settlers, listDirectory } = manualLister() + // The home level is truncated so its note is on screen when the slow + // scan starts: dropping the note's old !loading guard means it must + // keep rendering through the scan, coexisting with the indicator. + const settlers = new Map void>() + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve({ ...listingFor(path), truncated: true }) + return new Promise((resolve) => { settlers.set(path, resolve) }) + }) mount({ listDirectory }) await act(async () => {}) expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('browser.truncated')).toBeTruthy() fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // In flight but still inside the silence window: nothing shows. + // In flight but still inside the silence window: no indicator, and the + // stale level's truncated note stays put (no layout churn on launch). expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('browser.truncated')).toBeTruthy() await act(async () => { vi.advanceTimersByTime(300) }) - // Past it: the indicator floats while the stale level keeps rendering. - expect(screen.getByRole('status').textContent).toBe('browser.loading') + // Past it: the indicator floats while the stale level — truncated note + // included — keeps rendering beneath it. + expect(screen.getByText('browser.loading')).toBeTruthy() + expect(screen.getByText('browser.truncated')).toBeTruthy() expect(screen.getByText('Documents')).toBeTruthy() - // Landing (both legs) retires the indicator with the scan. + // Landing (both legs) retires the indicator with the scan, and the + // fresh listings' own truncated state replaces the stale note. await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.queryByText('browser.truncated')).toBeNull() expect(columns()).toHaveLength(2) } finally { vi.useRealTimers() } }) + it('a close mid-scan resets the slow-scan gate: reopening waits a fresh silence window', async () => { + vi.useFakeTimers() + try { + // Every home listing hangs: the initial open's scan is the one the + // close interrupts, and the reopen's scan proves the fresh window. + const settlers: ((value: DirectoryListing) => void)[] = [] + const listDirectory = vi.fn((_path?: string, _signal?: AbortSignal) => + new Promise((resolve) => { settlers.push(resolve) })) + const { view, props } = mount({ listDirectory }) + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // Close while the scan is in flight, then reopen: the first frame must + // wait out a fresh silence window, not inherit the armed indicator. + view.rerender() + view.rerender() + await act(async () => {}) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // The reopened scan settles normally. + await act(async () => { settlers.at(-1)!(listingFor(undefined)) }) + expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('Documents')).toBeTruthy() + } finally { + vi.useRealTimers() + } + }) + it('keeps the single-pane landing when the truncated parent level lacks the target', async () => { const listDirectory = vi.fn(async (path?: string) => { // The parent leg names HOME explicitly; serve it a truncated window From b6bb24bfa1da69abce3c17c1f1b9ffb0bef5cfe5 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 13:20:47 +0800 Subject: [PATCH 24/67] docs: raise AGENTS.md and packages/README.md budget ceilings after the master merge Both files fit their ceilings on each parent; the merge union of this branch's settings rows with master's typert row and source-launch rewrite overflows by 6 and 2 words. Every added row is a fixed-format layout or package-table entry with nothing to relocate, so the ceilings move to the union size. --- 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 0682f78640..537abeff00 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1755, + "AGENTS.md": 1765, "docs/AGENTS.md": 1150, "docs/architecture.md": 1920, "docs/cordis-primer.md": 600, @@ -7,5 +7,5 @@ "docs/testing.md": 1100, "examples/AGENTS.md": 310, "packages/AGENTS.md": 675, - "packages/README.md": 900 + "packages/README.md": 905 } From bdc6d95d561b400a08e34307520c4bdb0c838b57 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 13:29:52 +0800 Subject: [PATCH 25/67] fix(settings): close third-review watcher-lifecycle and write-boundary gaps Review round three found four seam defects: - A watch() disposer only removed the observer from the set; an invocation already chained onto the watcher tail still ran after disposal. Watchers now carry an active flag checked when a queued invocation would start, and the service dispose drain awaits started invocations (pendingTails) beside the write queues, so disposal is quiescent. - The settings/updated manual fan-out caught only synchronous throws; an async listener rejection escaped as an unhandled rejection. Thenable returns are now contained through the shared listener diagnostic, and the event contract documents that the INVARIANT rethrow serves synchronous listeners only. - structuredClone admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on reload (a Date lands as a timestamp string, a Map as a plain map, a BigInt as a number). The write snapshot is now a single-pass cloneJsonShaped walk that rejects non-JSON values with their path before anything persists. - mergeLayers' per-entry undefined guard became dead code once the clone strips undefined entries at the boundary; removed, with the sparse-patch contract restated at its enforcement point. --- packages/settings/settings/src/index.ts | 142 +++++++++++++++--- .../settings/settings/tests/settings.spec.ts | 105 ++++++++++++- 2 files changed, 222 insertions(+), 25 deletions(-) diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts index a7e9366048..27decc7db5 100644 --- a/packages/settings/settings/src/index.ts +++ b/packages/settings/settings/src/index.ts @@ -60,20 +60,24 @@ export interface SettingsScope { /** * Observe committed changes to this namespace's resolved value. Invocations * of one callback run asynchronously, one at a time, in commit order; a - * rejection is contained and logged like a sync throw. + * rejection is contained and logged like a sync throw. After the disposer + * returns, no further invocation starts — one already queued is skipped; + * one already started still settles, and service disposal waits for it. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ watch(callback: (next: T, prev: T) => void | Promise): () => void /** * Merge a partial patch into this namespace's user layer and persist it. - * @param patch - plain-object patch over the user section. + * @param patch - plain-object patch over the user section; JSON-shaped data + * only (non-JSON values reject with their path before anything persists). */ update(patch: object): Promise /** * Replace this namespace's user section wholesale; absent keys re-inherit * the composition `base` and schema defaults (`replace({})` resets all). - * @param section - the complete next user section. + * @param section - the complete next user section; JSON-shaped data only, + * as for {@link update}. */ replace(section: object): Promise } @@ -88,6 +92,11 @@ declare module 'cordis' { * Committed change to one registered namespace's resolved value. Emitted * after the provider persisted (for `update`) or published (`provider`) * the change; never emitted when the resolved value is deep-equal. + * Listener failures are contained and logged — a sync throw and an async + * rejection alike — except `INVARIANT`-coded failures, which rethrow + * after every listener ran; that rethrow reaches the emitter only from + * synchronous listeners, so invariant checks on this event must not be + * async functions. * @param ns - the namespace whose resolved value changed. * @param next - the new resolved value. * @param prev - the previous resolved value. @@ -127,17 +136,76 @@ function isPlainObject(value: unknown): value is Record { return proto === Object.prototype || proto === null } +/** Human label for a value rejected by the JSON-shape boundary (numbers reject inline). */ +function describeRejected(value: unknown): string { + if (value === undefined) return 'undefined' + if (typeof value === 'object' && value !== null) { + const proto = Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null + const name = proto?.constructor?.name + return name === undefined || name === 'Object' ? 'a non-plain object' : `a ${name}` + } + return `a ${typeof value}` +} + +/** + * Detach one write input in a single walk that doubles as the durable-boundary + * shape check: only JSON data (plain objects, arrays, strings, finite numbers, + * booleans, `null`) may reach a provider document. `structuredClone` alone + * would admit Dates, Maps, BigInts, and cycles that YAML/JSON storage then + * silently distorts on the reload round-trip. `undefined` entries in objects + * are skipped — the same sparse-patch semantics as {@link mergeLayers} — while + * an `undefined` array entry is rejected rather than coerced. + * @param root - plain-object write input (caller-checked). + * @param reject - builds the boundary error from a value label and its `$`-rooted path. + * @returns the detached JSON-shaped clone. + */ +function cloneJsonShaped( + root: Record, + reject: (label: string, path: string) => TypeError, +): Record { + const visiting = new WeakSet() + const clone = (value: unknown, path: string): unknown => { + if (value === null || typeof value === 'string' || typeof value === 'boolean') return value + if (typeof value === 'number') { + if (!Number.isFinite(value)) throw reject('a non-finite number', path) + return value + } + if (Array.isArray(value)) { + if (visiting.has(value)) throw reject('a circular reference', path) + visiting.add(value) + const entries = value.map((entry, index) => clone(entry, `${path}[${index}]`)) + // Un-mark on exit so one object referenced twice without a cycle passes. + visiting.delete(value) + return entries + } + if (isPlainObject(value)) { + if (visiting.has(value)) throw reject('a circular reference', path) + visiting.add(value) + const out: Record = {} + for (const [key, entry] of Object.entries(value)) { + if (entry === undefined) continue + out[key] = clone(entry, `${path}.${key}`) + } + visiting.delete(value) + return out + } + throw reject(describeRejected(value), path) + } + return clone(root, '$') as Record +} + /** * Layer `over` onto `under`: plain objects merge recursively, every other - * value (arrays included) replaces the lower layer wholesale, and `undefined` - * entries in `over` are ignored so a sparse patch cannot erase lower keys. + * value (arrays included) replaces the lower layer wholesale. `over` never + * carries `undefined` entries — sections come from parsed documents and write + * snapshots pass {@link cloneJsonShaped}, which strips them so a sparse patch + * cannot erase lower keys. */ function mergeLayers(under: unknown, over: unknown): unknown { if (over === undefined) return under if (!isPlainObject(under) || !isPlainObject(over)) return over const merged: Record = { ...under } for (const [key, value] of Object.entries(over)) { - if (value === undefined) continue merged[key] = key in merged ? mergeLayers(merged[key], value) : value } return merged @@ -155,6 +223,8 @@ interface SettingsWatcher { callback: (next: never, prev: never) => void | Promise /** Settled tail: invocations of this callback run one at a time, in commit order. */ tail: Promise + /** Cleared by the disposer: a queued invocation checks this before starting. */ + active: boolean } /** One live namespace registration owned by a registrant fiber. */ @@ -179,6 +249,8 @@ export abstract class Settings extends Service { private document: Record = {} /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */ private readonly writeQueues = new Map>() + /** In-flight watcher invocation segments, drained by the dispose teardown. */ + private readonly pendingTails = new Set>() /** Set at service dispose: refuse new writes while queued ones drain. */ private stopped = false @@ -199,10 +271,12 @@ export abstract class Settings extends Service { */ async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { yield async () => { - // Teardown: refuse new writes, then wait until every queued write chain - // settles so disposal completes only once storage is quiescent. + // Teardown: refuse new writes and new watcher starts, then wait until + // every queued write chain and every started watcher invocation settles + // so disposal completes only once storage and observers are quiescent. + // Invocations queued but not yet started skip via the stopped check. this.stopped = true - await Promise.allSettled([...this.writeQueues.values()]) + await Promise.allSettled([...this.writeQueues.values(), ...this.pendingTails]) } this.publish(await this.load()) } @@ -252,9 +326,12 @@ export abstract class Settings extends Service { return { get: () => registration.resolved as T, watch: (callback) => { - const watcher: SettingsWatcher = { callback: callback, tail: Promise.resolve() } + const watcher: SettingsWatcher = { callback: callback, tail: Promise.resolve(), active: true } registration.watchers.add(watcher) - return () => registration.watchers.delete(watcher) + return () => { + watcher.active = false + registration.watchers.delete(watcher) + } }, update: patch => this.update(ns, patch), replace: section => this.replace(ns, section), @@ -325,13 +402,10 @@ export abstract class Settings extends Service { throw new TypeError(`settings ${verb} for "${ns}" must be a plain object`) } // Snapshot at call time: the queue must never read a caller-owned object - // the caller may keep mutating while the write waits its turn. - let snapshot: Record - try { - snapshot = structuredClone(input) - } catch { - throw new TypeError(`settings ${verb} for "${ns}" must be JSON-shaped (structured-cloneable) data`) - } + // the caller may keep mutating while the write waits its turn. The same + // walk is the JSON-shape boundary check (see cloneJsonShaped). + const snapshot = cloneJsonShaped(input, (label, path) => + new TypeError(`settings ${verb} for "${ns}" must be JSON-shaped data (found ${label} at ${path})`)) const previous = this.writeQueues.get(ns) ?? Promise.resolve() // Chain past a failed predecessor: one rejected write must not poison the // namespace queue for every later caller. @@ -407,11 +481,20 @@ export abstract class Settings extends Service { // Serialize per watcher: invocations of one callback run one at a time // in commit order, so a slow stale invocation can never apply after a // newer one. Sync throws and async rejections land in the same handler. - watcher.tail = watcher.tail - .then(() => watcher.callback(next as never, prev as never)) + // The activity check runs when the queued invocation would start, so a + // disposer (or service stop) that ran while it waited prevents the + // start entirely; started invocations drain at service dispose. + const segment = watcher.tail + .then(() => { + if (!watcher.active || this.isStopped()) return + return watcher.callback(next as never, prev as never) + }) .then(() => undefined, (error: unknown) => { this.warnWatcherFailure(registration.ns, error) }) + watcher.tail = segment + this.pendingTails.add(segment) + void segment.then(() => this.pendingTails.delete(segment)) } // Fan the event out one listener at a time (the plain emit stops at the // first throwing listener, starving the rest). Invariant violations are @@ -422,14 +505,21 @@ export abstract class Settings extends Service { const args = ['settings/updated', registration.ns, next, prev, source] for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) { try { - listener(registration.ns, next, prev, source) + const returned = listener(registration.ns, next, prev, source) + if (returned != null && typeof (returned as PromiseLike).then === 'function') { + // An emit listener may still be an async function; its rejection + // cannot reach the synchronous INVARIANT rethrow below, so it is + // contained here instead of becoming an unhandled rejection. + void Promise.resolve(returned as PromiseLike).then(undefined, (error: unknown) => { + this.warnListenerFailure(registration.ns, error) + }) + } } catch (error) { if ((error as { code?: unknown } | null)?.code === 'INVARIANT') { invariantFailure ??= error continue } - this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', registration.ns) - this.ctx.logger.warn(error) + this.warnListenerFailure(registration.ns, error) } } if (invariantFailure !== undefined) throw invariantFailure as Error @@ -440,6 +530,12 @@ export abstract class Settings extends Service { this.ctx.logger.warn('settings: watcher for "%s" failed', ns) this.ctx.logger.warn(error) } + + /** Contained-listener diagnostic shared by the sync and async failure paths. */ + private warnListenerFailure(ns: SettingsNamespace, error: unknown): void { + this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', ns) + this.ctx.logger.warn(error) + } } export default Settings diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts index a989d9a5cc..cfd88b166f 100644 --- a/packages/settings/settings/tests/settings.spec.ts +++ b/packages/settings/settings/tests/settings.spec.ts @@ -228,6 +228,14 @@ describe('update', () => { expect(scope.get()).toEqual({ theme: 'light', fontSize: 18 }) }) + it('ignores an explicit undefined entry in the composition base layer', async () => { + const { ctx } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { + base: { theme: undefined, fontSize: 16 }, + }) + expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 }) + }) + it('rejects a non-object patch', async () => { const { ctx } = await boot() const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) @@ -433,11 +441,11 @@ describe('second review regressions', () => { expect(applied).toEqual([1, 2]) }) - it('rejects a plain object that is not structured-cloneable', async () => { + it('rejects a function value as not JSON-shaped', async () => { const { ctx } = await boot() const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) await expect(scope.update({ theme: () => 'dark' })) - .rejects.toThrow(/JSON-shaped/) + .rejects.toThrow(/JSON-shaped.*function at \$\.theme/) }) it('rejects a write still queued when the service disposes', async () => { @@ -532,6 +540,99 @@ describe('publish', () => { }) }) +describe('third review regressions', () => { + it('skips a queued watch invocation whose disposer ran before it started', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const watcher = vi.fn() + const dispose = scope.watch(watcher) + // The commit chains the invocation as a microtask; the disposer runs in + // the same synchronous frame, before that invocation could start. + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + dispose() + await new Promise(resolve => setTimeout(resolve, 10)) + expect(watcher).not.toHaveBeenCalled() + }) + + it('waits for an in-flight watch invocation at service dispose', async () => { + const { ctx, provider, fiber } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + let release: (() => void) | undefined + let finished = false + scope.watch(async () => { + await new Promise((resolve) => { release = resolve }) + finished = true + }) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + await vi.waitFor(() => { expect(release).toBeDefined() }) + let disposed = false + const disposal = fiber.dispose().then(() => { disposed = true }) + await new Promise(resolve => setTimeout(resolve, 15)) + expect(disposed).toBe(false) + release!() + await disposal + expect(finished).toBe(true) + }) + + it('rejects a Date at its path before anything persists', async () => { + const { ctx, provider } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() })) + await expect(scope.update({ value: { at: new Date(0) } })) + .rejects.toThrow(/JSON-shaped.*Date at \$\.value\.at/) + expect(provider.persisted).toEqual([]) + }) + + it.each([ + ['a Map', { value: new Map() }, /Map at \$\.value/], + ['a bigint', { value: [10n] }, /bigint at \$\.value\[0\]/], + ['a symbol', { value: Symbol('x') }, /symbol at \$\.value/], + ['a non-finite number', { value: Number.NaN }, /non-finite number at \$\.value/], + ['an undefined array entry', { value: [undefined] }, /undefined at \$\.value\[0\]/], + ['a class instance', { value: Object.create({ marker: true }) as object }, /non-plain object at \$\.value/], + ])('rejects %s that structuredClone would admit', async (_label, patch, message) => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() })) + await expect(scope.update(patch)).rejects.toThrow(message) + }) + + it('rejects a circular patch instead of storing an alias-looped document', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() })) + const cyclic: Record = {} + cyclic['self'] = cyclic + await expect(scope.update({ value: cyclic })).rejects.toThrow(/circular reference at \$\.value\.self/) + const loop: unknown[] = [] + loop.push(loop) + await expect(scope.update({ value: loop })).rejects.toThrow(/circular reference at \$\.value\[0\]/) + }) + + it('accepts one object referenced twice without a cycle', async () => { + const { ctx } = await boot() + const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() })) + const shared = { leaf: 1 } + await scope.update({ value: { left: shared, right: shared } }) + expect(scope.get()).toEqual({ value: { left: { leaf: 1 }, right: { leaf: 1 } } }) + }) + + it('contains an async settings/updated listener rejection and keeps other listeners running', async () => { + const { ctx, provider } = await boot() + // An async listener violates the event's synchronous signature (typed + // consumers get a lint error for it), but an unlinted JS plugin can still + // register one; the cast simulates exactly that caller. + ctx.on('settings/updated', async () => { + throw new Error('async listener boom') + }) + const second = vi.fn() + ctx.on('settings/updated', second) + ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + provider.pushExternal({ 'ui-theme': { theme: 'light' } }) + expect(second).toHaveBeenCalledTimes(1) + // Containment gives the rejection a handler; vitest observes no unhandled + // rejection out of this test. + await new Promise(resolve => setTimeout(resolve, 10)) + }) +}) + describe('watch', () => { it('stops after its disposer runs', async () => { const { ctx, provider } = await boot() From 85a3a158dde4e532e83a93c3889172518a950b6a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 13:39:22 +0800 Subject: [PATCH 26/67] fix(settings-local): one operation chain, read-modify-write under a writer lock, and diff-shaped YAML edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round three found the provider's write path could destroy state it never observed: - Watcher reloads and document writes ran on two independent promise chains, and a write rendered the whole next document from the cached text. An external edit still inside the debounce window (or missed outright) was overwritten, and the follow-up reload no-oped because the post-rename content matched the cache — the edit vanished without a trace. Reloads and writes now share one operation chain, and every write starts by reconciling the on-disk text into the seam before rendering, so unobserved sibling sections survive and publish first. An unparsable on-disk document fails the write loud instead of being overwritten. - The initial load raced the watcher's own setup: a change written between that read and the watcher becoming active never fired an event. The watcher's ready signal now queues one reconcile, closing the gap. - Two processes sharing a harness home rendered from independent caches, last writer winning. Writes now hold a wx-created .lock sibling around the read-render-rename cycle with bounded backoff, a crashed- holder stale takeover, and a deadline failure; readers stay lock-free because the rename commit is atomic. - renderYaml replaced the whole namespace node, dropping every comment inside the section. The next section now lands as a leaf-level diff (set changed values, delete removed keys), so comments, anchors, and formatting survive on every untouched node and on the key of every changed pair; arrays still replace wholesale when unequal. --- packages/settings/settings-local/src/index.ts | 247 ++++++++++++++---- .../settings-local/tests/concurrency.spec.ts | 103 ++++++++ .../settings-local/tests/local.spec.ts | 96 +++++++ .../settings-local/tests/lock-race.spec.ts | 100 +++++++ .../settings-local/tests/watcher.spec.ts | 55 +++- 5 files changed, 545 insertions(+), 56 deletions(-) create mode 100644 packages/settings/settings-local/tests/concurrency.spec.ts create mode 100644 packages/settings/settings-local/tests/lock-race.spec.ts diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts index b305f61fe7..b9df71f9e1 100644 --- a/packages/settings/settings-local/src/index.ts +++ b/packages/settings/settings-local/src/index.ts @@ -9,11 +9,11 @@ import { Context, Service } from 'cordis' import z from 'schemastery' import { watch as chokidarWatch } from 'chokidar' import { randomBytes } from 'node:crypto' -import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises' +import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises' import { dirname, extname, join, resolve } from 'node:path' import { Document, parseDocument } from 'yaml' import { resolveDshHome } from '@deepseek-ai/dsh-paths' -import { Settings, type SettingsNamespace } from '@deepseek-ai/dsh-settings' +import { Settings, deepEqualJson, type SettingsNamespace } from '@deepseek-ai/dsh-settings' /** Plugin config: file location and hot-reload behavior. */ export interface Config { @@ -64,11 +64,53 @@ export function resolveSpec(config: Config): ResolvedSpec { } } +/** Whether a parsed YAML value is a map for diffing purposes. */ +function isMapLike(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** + * Apply the difference between one node's stored and next value as minimal + * `setIn`/`deleteIn` edits, recursing through maps, so every untouched node — + * and the key node of every changed pair — keeps its comments, anchors, and + * formatting. Non-map values (arrays and scalars) replace wholesale when + * unequal, taking any comments inside them along. + */ +function patchNode(document: Document, path: readonly string[], current: unknown, next: unknown): void { + if (isMapLike(current) && isMapLike(next)) { + for (const key of Object.keys(current)) { + if (!(key in next)) document.deleteIn([...path, key]) + } + for (const [key, value] of Object.entries(next)) { + patchNode(document, [...path, key], current[key], value) + } + return + } + if (!deepEqualJson(current, next)) document.setIn([...path], next) +} + /** Whether a filesystem error means absence; every non-ENOENT failure must surface. */ function isENOENT(error: unknown): boolean { return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT' } +/** Whether an exclusive create failed because the path already exists. */ +function isEEXIST(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST' +} + +/** + * Writer-lock protocol constants. These are robustness invariants of the + * cross-process write protocol, not deployment tunables: a holder rewrites one + * small document in milliseconds, so contention resolves well inside the + * retry deadline, and a lock older than the stale age can only belong to a + * crashed holder. + */ +const LOCK_RETRY_INITIAL_MS = 20 +const LOCK_RETRY_MAX_MS = 200 +const LOCK_TIMEOUT_MS = 2_000 +const LOCK_STALE_MS = 5_000 + /** File-backed settings provider (`settings.yaml`/`.json`). */ export class SettingsLocal extends Settings { static Config: z = z.object({ @@ -85,10 +127,13 @@ export class SettingsLocal extends Settings { * this cache are no-ops, which is also the self-write suppression. */ private text: string | undefined - /** Serializes watcher-triggered reloads so reads never interleave. */ - private refreshTask: Promise = Promise.resolve() - /** Serializes whole-document writes across namespace queues; settled tail. */ - private persistChain: Promise = Promise.resolve() + /** + * Single exclusive operation chain: watcher reloads and document writes run + * one at a time in queue order (settled tail), so a write can never render + * from text a concurrent reload is busy replacing, and a reload can never + * read a half-committed write. + */ + private operations: Promise = Promise.resolve() /** Set at dispose: refuse new watcher events and let in-flight work no-op. */ private closed = false @@ -125,32 +170,107 @@ export class SettingsLocal extends Settings { protected persist(ns: SettingsNamespace, section: Record): Promise { // One document backs every namespace, so writes from different namespace - // queues must serialize here: each render must see the text the previous - // write committed, or the loser's section silently vanishes from disk. - // The stored tail is settled on both outcomes, so chaining needs no catch. - const task = this.persistChain.then(() => this.persistSection(ns, section)) - this.persistChain = task.then(() => undefined, () => undefined) + // queues serialize with each other and with watcher reloads on the one + // operation chain: each render must see the text the previous operation + // committed, or a sibling section silently vanishes from disk. + return this.enqueue(() => this.persistSection(ns, section)) + } + + /** Queue one exclusive document operation behind every earlier one. */ + private enqueue(operation: () => Promise): Promise { + const task = this.operations.then(operation) + this.operations = task.then(() => undefined, () => undefined) return task } + /** Queue a reload; only an invariant violation escaping a commit can reject it. */ + private queueRefresh(): void { + void this.enqueue(() => this.refresh()).catch((error: unknown) => { + // Only an invariant violation escaping the commit path can reject a + // refresh; keep the operation queue alive and surface it as an error so + // one poisoned commit cannot silently end hot reloading forever. + this.ctx.logger.error('settings-local: reload commit failed at %s', this.spec.filename) + this.ctx.logger.error(error) + }) + } + private async persistSection(ns: SettingsNamespace, section: Record): Promise { - const output = this.spec.format === 'yaml' - ? this.renderYaml(ns, section) - : this.renderJson(ns, section) await mkdir(dirname(this.spec.filename), { recursive: true }) - // Exclusive-create (`wx`) a random-suffix sibling: the open refuses to - // follow any planted symlink at a guessable temp path, and the fresh inode - // carries owner-only permissions that survive the rename — a document that - // may hold personal values is never world-readable and never a symlink. - const temp = `${this.spec.filename}.${randomBytes(6).toString('hex')}.tmp` - try { - await writeFile(temp, output, { mode: 0o600, flag: 'wx' }) - await rename(temp, this.spec.filename) - } catch (error) { - await rm(temp, { force: true }) - throw error + await this.withWriterLock(async () => { + // Read-modify-write: fold in any on-disk state this process has not + // observed yet — an external edit still inside the watcher debounce + // window, a change the watcher missed, or another process's write — so + // the render below can never resurrect a stale document. An unparsable + // on-disk document fails the write loud instead of silently overwriting + // a user's manual edit. + await this.reconcileFromDisk() + const output = this.spec.format === 'yaml' + ? this.renderYaml(ns, section) + : this.renderJson(ns, section) + // Exclusive-create (`wx`) a random-suffix sibling: the open refuses to + // follow any planted symlink at a guessable temp path, and the fresh inode + // carries owner-only permissions that survive the rename — a document that + // may hold personal values is never world-readable and never a symlink. + const temp = `${this.spec.filename}.${randomBytes(6).toString('hex')}.tmp` + try { + await writeFile(temp, output, { mode: 0o600, flag: 'wx' }) + await rename(temp, this.spec.filename) + } catch (error) { + await rm(temp, { force: true }) + throw error + } + this.text = output + }) + } + + /** + * Hold the cross-process writer lock around one read-render-rename cycle. + * The lock is a `wx`-created sibling (`.lock`); the rename-based + * commit keeps readers lock-free, so only writers contend. A lock older + * than {@link LOCK_STALE_MS} is a crashed holder and is broken with a + * warning; a live holder past {@link LOCK_TIMEOUT_MS} fails the write. + */ + private async withWriterLock(operation: () => Promise): Promise { + const lockPath = `${this.spec.filename}.lock` + const deadline = Date.now() + LOCK_TIMEOUT_MS + let delay = LOCK_RETRY_INITIAL_MS + for (;;) { + try { + await writeFile(lockPath, `${process.pid}\n`, { mode: 0o600, flag: 'wx' }) + break + } catch (error) { + if (!isEEXIST(error)) throw error + } + const ageMs = await this.lockAgeMs(lockPath) + // The holder released between the failed create and the stat: the lock + // is free right now, so retry without burning backoff or deadline. + if (ageMs === undefined) continue + if (ageMs > LOCK_STALE_MS) { + this.ctx.logger.warn('settings-local: breaking a stale writer lock at %s', lockPath) + await rm(lockPath, { force: true }) + continue + } + if (Date.now() >= deadline) { + throw new Error(`settings-local: timed out waiting for the writer lock at ${lockPath}`) + } + await new Promise(resolve => setTimeout(resolve, delay)) + delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS) + } + try { + return await operation() + } finally { + await rm(lockPath, { force: true }) + } + } + + /** Age of the writer lock, or `undefined` when it vanished after a failed create. */ + private async lockAgeMs(lockPath: string): Promise { + try { + return Date.now() - (await stat(lockPath)).mtimeMs + } catch (error) { + if (!isENOENT(error)) throw error + return undefined } - this.text = output } override async* [Service.init](): AsyncGenerator<() => Promise | void, void, void> { @@ -168,13 +288,14 @@ export class SettingsLocal extends Settings { }) watcher.on('all', () => { if (this.closed) return - this.refreshTask = this.refreshTask.then(() => this.refresh()).catch((error: unknown) => { - // Only an invariant violation escaping the commit path can reject a - // refresh; keep the reload queue alive and surface it as an error so - // one poisoned commit cannot silently end hot reloading forever. - this.ctx.logger.error('settings-local: reload commit failed at %s', this.spec.filename) - this.ctx.logger.error(error) - }) + this.queueRefresh() + }) + watcher.on('ready', () => { + // The base init's load raced the watcher's own setup: a change written + // between that read and the watcher becoming active never fires an + // event. One reconcile at ready closes the gap. + if (this.closed) return + this.queueRefresh() }) watcher.on('error', (error) => { this.ctx.logger.warn('settings-local: watcher error on %s', this.spec.filename) @@ -182,10 +303,10 @@ export class SettingsLocal extends Settings { }) yield async () => { // Quiesce: stop accepting events, close the watcher, then wait out any - // queued or in-flight refresh so nothing publishes after disposal. + // queued or in-flight operation so nothing publishes after disposal. this.closed = true await watcher.close() - await this.refreshTask + await this.operations } } @@ -212,46 +333,62 @@ export class SettingsLocal extends Settings { * Re-read the document after a watcher event. Unchanged content (including * this provider's own writes) is a no-op; an unreadable or unparsable * document keeps the last good sections and warns — a live hot-reload must - * never take the process down. + * never take the process down. An invariant violation escaping a commit is + * not a reload failure and propagates to the queue's error surface. */ private async refresh(): Promise { if (this.closed) return - let text: string + try { + await this.reconcileFromDisk() + } catch (error) { + if ((error as { code?: unknown } | null)?.code === 'INVARIANT') throw error + this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename) + this.ctx.logger.warn(error) + } + } + + /** + * Compare the on-disk text against the cache and publish any difference + * into the seam. Absence publishes the empty document; an unreadable or + * unparsable file throws, so each caller picks its policy — a reload warns + * and keeps the last good document, a write fails loud. + */ + private async reconcileFromDisk(): Promise { + let text: string | undefined try { text = await readFile(this.spec.filename, 'utf8') } catch (error) { - if (!isENOENT(error)) { - this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename) - this.ctx.logger.warn(error) - return - } - if (this.text === undefined || this.isClosed()) return + if (!isENOENT(error)) throw error + text = undefined + } + if (text === this.text || this.isClosed()) return + if (text === undefined) { this.text = undefined this.publish({}) return } - if (text === this.text || this.isClosed()) return - let doc: Record - try { - doc = this.parse(text) - } catch (error) { - this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename) - this.ctx.logger.warn(error) - return - } + const doc = this.parse(text) this.text = text this.publish(doc) } - /** Render the next YAML text by patching one namespace in the comment-preserving document. */ + /** + * Render the next YAML text by patching one namespace in the + * comment-preserving document. The next section lands as a leaf-level diff + * against the stored one — only changed values set, only removed keys + * delete — so comments inside the section survive edits to their siblings, + * not just comments outside it. + */ private renderYaml(ns: SettingsNamespace, section: Record): string { if (this.text === undefined) { return new Document({ [ns]: section }).toString() } // this.text only ever caches content that parsed successfully, so this - // re-parse (for the mutable comment-preserving tree) cannot fail. + // re-parse (for the mutable comment-preserving tree) cannot fail, and + // parse() already rejected any non-map root. const document = parseDocument(this.text) - document.set(ns, section) + const root: unknown = document.toJS() + patchNode(document, [ns], isMapLike(root) ? root[ns] : undefined, section) return document.toString() } diff --git a/packages/settings/settings-local/tests/concurrency.spec.ts b/packages/settings/settings-local/tests/concurrency.spec.ts new file mode 100644 index 0000000000..ab09866819 --- /dev/null +++ b/packages/settings/settings-local/tests/concurrency.spec.ts @@ -0,0 +1,103 @@ +// Cross-instance and writer-lock behavior: two providers on one document are +// the in-process equivalent of two dsh processes sharing a harness home — +// neither knows the other's cache, so only the read-modify-write cycle under +// the `.lock` sibling keeps both namespaces alive on disk. +import { afterEach, describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import { chmod, mkdtemp, readFile, rm, utimes, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { settingsNamespace } from '@deepseek-ai/dsh-settings' +import { SettingsLocal } from '../src/index.ts' + +const AlphaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) }) +const BetaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) }) + +const cleanups: Array<() => Promise> = [] + +afterEach(async () => { + while (cleanups.length > 0) await cleanups.pop()!() +}) + +async function tempDir(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-lock-')) + cleanups.push(() => rm(dir, { recursive: true, force: true })) + return dir +} + +async function boot(config: ConstructorParameters[1]): Promise { + const ctx = new Context() + const fiber = ctx.plugin(SettingsLocal, config) + cleanups.push(async () => { await fiber.dispose() }) + await fiber + return ctx +} + +describe('cross-instance writes', () => { + it('keeps both namespaces when two providers write the same document concurrently', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const first = await boot({ path, watch: false }) + const second = await boot({ path, watch: false }) + const alpha = first.settings.register(settingsNamespace('alpha'), AlphaSchema) + const beta = second.settings.register(settingsNamespace('beta'), BetaSchema) + const rounds = [1, 2, 3, 4, 5] + await Promise.all([ + (async () => { for (const value of rounds) await alpha.update({ value }) })(), + (async () => { for (const value of rounds) await beta.update({ value }) })(), + ]) + const text = await readFile(path, 'utf8') + expect(text).toContain('alpha:') + expect(text).toContain('beta:') + // A third instance resolves both final values from the shared document. + const third = await boot({ path, watch: false }) + expect(third.settings.register(settingsNamespace('alpha'), AlphaSchema).get()).toEqual({ value: 5 }) + expect(third.settings.register(settingsNamespace('beta'), BetaSchema).get()).toEqual({ value: 5 }) + }) +}) + +describe('writer lock', () => { + it('waits for a busy writer lock instead of failing', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + await writeFile(`${path}.lock`, 'holder\n') + const release = setTimeout(() => { void rm(`${path}.lock`, { force: true }) }, 120) + cleanups.push(async () => { clearTimeout(release) }) + await scope.update({ value: 7 }) + expect(await readFile(path, 'utf8')).toContain('value: 7') + }) + + it('breaks a stale writer lock with a warning and writes through', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + await writeFile(`${path}.lock`, 'crashed-holder\n') + const past = (Date.now() - 60_000) / 1000 + await utimes(`${path}.lock`, past, past) + await scope.update({ value: 9 }) + expect(await readFile(path, 'utf8')).toContain('value: 9') + }) + + it('times out on a lock a live holder never releases', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + await writeFile(`${path}.lock`, 'busy-holder\n') + await expect(scope.update({ value: 1 })).rejects.toThrow(/timed out waiting for the writer lock/) + }, 10_000) + + it('surfaces a non-contention lock failure as the write error', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + await chmod(dir, 0o500) + cleanups.push(() => chmod(dir, 0o700)) + await expect(scope.update({ value: 1 })).rejects.toThrow(/EACCES|permission/) + }) +}) diff --git a/packages/settings/settings-local/tests/local.spec.ts b/packages/settings/settings-local/tests/local.spec.ts index 4c3c24ccd9..0b753675f5 100644 --- a/packages/settings/settings-local/tests/local.spec.ts +++ b/packages/settings/settings-local/tests/local.spec.ts @@ -204,6 +204,102 @@ describe('persist', () => { expect(written).toContain('theme: light') }) + it('keeps comments inside the section when a sibling key changes', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, [ + 'ui-theme:', + ' # chosen during onboarding', + ' theme: light', + ' fontSize: 12', + '', + ].join('\n')) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ fontSize: 18 }) + const written = await readFile(path, 'utf8') + expect(written).toContain('# chosen during onboarding') + expect(written).toContain('theme: light') + expect(written).toContain('fontSize: 18') + }) + + it('keeps a changed key\'s own-line comment while replacing its value', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, [ + 'ui-theme:', + ' # chosen during onboarding', + ' theme: light', + '', + ].join('\n')) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'dark' }) + const written = await readFile(path, 'utf8') + expect(written).toContain('# chosen during onboarding') + expect(written).toContain('theme: dark') + }) + + it('deletes only the removed key on replace, keeping sibling comments', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, [ + 'ui-theme:', + ' # chosen during onboarding', + ' theme: light', + ' fontSize: 12', + '', + ].join('\n')) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.replace({ theme: 'light' }) + const written = await readFile(path, 'utf8') + expect(written).toContain('# chosen during onboarding') + expect(written).toContain('theme: light') + expect(written).not.toContain('fontSize') + }) + + it('keeps an unchanged array\'s comments and replaces a changed array wholesale', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const TagsSchema: z<{ tags: string[]; label: string }> = z.object({ + tags: z.array(z.string()).default([]), + label: z.string().default(''), + }) + await writeFile(path, [ + 'workspace:', + ' tags:', + ' # pinned by hand', + ' - alpha', + ' label: draft', + '', + ].join('\n')) + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('workspace'), TagsSchema) + await scope.update({ label: 'final' }) + const untouched = await readFile(path, 'utf8') + expect(untouched).toContain('# pinned by hand') + expect(untouched).toContain('label: final') + // A changed array replaces wholesale; comments inside it go with it. + await scope.update({ tags: ['beta'] }) + const replaced = await readFile(path, 'utf8') + expect(replaced).not.toContain('# pinned by hand') + expect(replaced).toContain('- beta') + }) + + it('keeps a comment-only document\'s comment when the first section lands', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + // Parses to a null root: the document exists but holds no sections yet. + await writeFile(path, '# reserved for future settings\n') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + await scope.update({ theme: 'light' }) + const written = await readFile(path, 'utf8') + expect(written).toContain('# reserved for future settings') + expect(written).toContain('theme: light') + }) + it('creates a json document from scratch', async () => { const dir = await tempDir() const path = join(dir, 'settings.json') diff --git a/packages/settings/settings-local/tests/lock-race.spec.ts b/packages/settings/settings-local/tests/lock-race.spec.ts new file mode 100644 index 0000000000..09eb025654 --- /dev/null +++ b/packages/settings/settings-local/tests/lock-race.spec.ts @@ -0,0 +1,100 @@ +// Writer-lock races that cannot be timed from outside: a contender whose lock +// vanishes between the failed exclusive create and the stat, a stat failing +// for a reason other than absence, and a temp-file write failing mid-cycle. +// The fs/promises seam is partially mocked to inject exactly one failure at a +// chosen path suffix; everything else passes through to the real filesystem. +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import z from 'schemastery' +import { access, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { settingsNamespace } from '@deepseek-ai/dsh-settings' +import { SettingsLocal } from '../src/index.ts' + +const state = vi.hoisted(() => ({ + /** One-shot failure injections keyed by operation, matched on a path suffix. */ + failures: [] as Array<{ op: 'writeFile' | 'stat'; suffix: string; code: string }>, +})) + +vi.mock('node:fs/promises', async (importOriginal) => { + const actual = await importOriginal() + const inject = (op: 'writeFile' | 'stat', path: unknown): void => { + const index = state.failures.findIndex(f => f.op === op && String(path).endsWith(f.suffix)) + if (index === -1) return + const [failure] = state.failures.splice(index, 1) + throw Object.assign(new Error(`${failure!.code}: injected ${op} failure`), { code: failure!.code }) + } + return { + ...actual, + writeFile: (async (path: unknown, ...rest: never[]) => { + inject('writeFile', path) + return (actual.writeFile as (path: unknown, ...args: never[]) => Promise)(path, ...rest) + }) as typeof actual.writeFile, + stat: (async (path: unknown, ...rest: never[]) => { + inject('stat', path) + return (actual.stat as (path: unknown, ...args: never[]) => Promise)(path, ...rest) + }) as typeof actual.stat, + } +}) + +const AlphaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) }) + +const cleanups: Array<() => Promise> = [] + +afterEach(async () => { + state.failures.length = 0 + while (cleanups.length > 0) await cleanups.pop()!() +}) + +async function tempDir(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-lockrace-')) + cleanups.push(() => rm(dir, { recursive: true, force: true })) + return dir +} + +async function boot(config: ConstructorParameters[1]): Promise { + const ctx = new Context() + const fiber = ctx.plugin(SettingsLocal, config) + cleanups.push(async () => { await fiber.dispose() }) + await fiber + return ctx +} + +describe('writer-lock races', () => { + it('retries immediately when the contending lock vanished before the stat', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + // The exclusive create loses to a holder that releases before the stat: + // no lock file actually exists, so the stat sees honest absence and the + // very next attempt takes the lock. + state.failures.push({ op: 'writeFile', suffix: '.lock', code: 'EEXIST' }) + await scope.update({ value: 3 }) + expect(await readFile(path, 'utf8')).toContain('value: 3') + }) + + it('propagates a stat failure that does not mean absence', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + state.failures.push({ op: 'writeFile', suffix: '.lock', code: 'EEXIST' }) + state.failures.push({ op: 'stat', suffix: '.lock', code: 'EACCES' }) + await expect(scope.update({ value: 3 })).rejects.toThrow(/EACCES/) + }) + + it('cleans up the temp file and releases the lock when the write fails mid-cycle', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'alpha:\n value: 1\n') + const ctx = await boot({ path, watch: false }) + const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema) + state.failures.push({ op: 'writeFile', suffix: '.tmp', code: 'ENOSPC' }) + await expect(scope.update({ value: 9 })).rejects.toThrow(/ENOSPC/) + // The document is untouched and the writer lock was released on the way out. + expect(await readFile(path, 'utf8')).toContain('value: 1') + await expect(access(`${path}.lock`)).rejects.toThrow() + }) +}) diff --git a/packages/settings/settings-local/tests/watcher.spec.ts b/packages/settings/settings-local/tests/watcher.spec.ts index 439f213473..7b289b22a3 100644 --- a/packages/settings/settings-local/tests/watcher.spec.ts +++ b/packages/settings/settings-local/tests/watcher.spec.ts @@ -1,7 +1,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' import z from 'schemastery' -import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises' +import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { settingsNamespace } from '@deepseek-ai/dsh-settings' @@ -155,6 +155,7 @@ describe('watcher pipeline', () => { await fiber.dispose() disposed = true instance!.watcher.emit('all', 'change', path) + instance!.watcher.emit('ready') await new Promise(resolve => setTimeout(resolve, 100)) expect(postDisposeCommits).toBe(0) }) @@ -169,4 +170,56 @@ describe('watcher pipeline', () => { await new Promise(resolve => setTimeout(resolve, 50)) expect(scope.get()).toEqual({ theme: 'dark' }) }) + + it('folds an unobserved external edit into a write instead of overwriting it', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 5 }) + const theme = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const editor = ctx.settings.register(settingsNamespace('editor'), z.object({ + tabWidth: z.number().default(2), + })) + // The external edit has landed on disk but its watcher event has not + // fired yet (a debounce window, or a missed event): the write must fold + // it in, not resurrect the stale document. + await writeFile(path, 'ui-theme:\n theme: light\neditor:\n tabWidth: 8\n') + await theme.update({ theme: 'darker' }) + const text = await readFile(path, 'utf8') + expect(text).toContain('tabWidth: 8') + expect(text).toContain('theme: darker') + // The fold published the unobserved section before the write committed. + expect(editor.get()).toEqual({ tabWidth: 8 }) + }) + + it('reconciles at watcher ready so a change during setup is not missed', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + // Written after the initial load but before the watcher became active: + // no 'all' event will ever fire for it. + await writeFile(path, 'ui-theme:\n theme: written-before-ready\n') + const [instance] = await fakeInstances() + instance!.watcher.emit('ready') + await vi.waitFor(() => { + expect(scope.get().theme).toBe('written-before-ready') + }) + }) + + it('fails a write loud when the on-disk document turned invalid unobserved', async () => { + const dir = await tempDir() + const path = join(dir, 'settings.yaml') + await writeFile(path, 'ui-theme:\n theme: light\n') + const ctx = await boot({ path, debounceMs: 5 }) + const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) + const broken = 'ui-theme: [unclosed\n flow: {\n' + await writeFile(path, broken) + await expect(scope.update({ theme: 'darker' })).rejects.toThrow(/invalid document/) + // The user's manual edit stays on disk untouched and the cache keeps the + // last good value. + expect(await readFile(path, 'utf8')).toBe(broken) + expect(scope.get()).toEqual({ theme: 'light' }) + }) }) From 3b1b9125180c23c70f8a090b215a7f1d3f05692d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 14:09:04 +0800 Subject: [PATCH 27/67] docs(settings): third-review contracts across READMEs, catalogs, and the write-path integrity note The seam README states the JSON-shaped write boundary, watch-disposer quiescence, async listener containment, and the drained teardown; the provider README rewrites Behavior around the operation chain, read-modify-write, writer lock, ready reconcile, and leaf-level YAML diffs, and updates Known Limitations to the residual guarantees. A new Agent Note records the round's decisions and supersedes the original note's deferred-lockfile alternative (cross-linked in place). Chinese counterparts updated pair-by-pair (three briefed minimal updates, one whole-document translation); type-equiv, config, cordis, and module-graph catalogs re-recorded. --- .../2026-07-28-user-settings-seam.i18n.yaml | 4 +- .../2026-07-28-user-settings-seam.md | 4 +- .../2026-07-28-user-settings-seam.zh.md | 4 +- ...30-settings-write-path-integrity.i18n.yaml | 6 +++ ...026-07-30-settings-write-path-integrity.md | 35 ++++++++++++++++ ...-07-30-settings-write-path-integrity.zh.md | 41 +++++++++++++++++++ docs/config-catalog.md | 2 +- docs/cordis-catalog/events.md | 9 +++- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/settings.i18n.yaml | 4 +- docs/core-data-structures/settings.md | 10 +++-- docs/core-data-structures/settings.zh.md | 10 +++-- docs/event-producer-consumer.md | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 2 +- .../settings/settings-local/README.i18n.yaml | 4 +- packages/settings/settings-local/README.md | 17 +++++--- packages/settings/settings-local/README.zh.md | 17 +++++--- packages/settings/settings-local/src/index.ts | 4 +- packages/settings/settings/README.i18n.yaml | 4 +- packages/settings/settings/README.md | 8 ++-- packages/settings/settings/README.zh.md | 8 ++-- 21 files changed, 152 insertions(+), 45 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md create mode 100644 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml index cc409d8403..736a372f27 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md -2026-07-28-user-settings-seam.md: f0f45d77c8f98fc15625b1a1bf116ec10b965676 -2026-07-28-user-settings-seam.zh.md: eb562099b1ff0b5b0a019e9956d6e36e71857236 +2026-07-28-user-settings-seam.md: bf93f95168b1b6d0dec5a9fc2c9aac5531f0564a +2026-07-28-user-settings-seam.zh.md: 8cd4dfcbb2facdd590b2c24d453ad79e9badda4d diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md index f0f45d77c8..bf93f95168 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md @@ -14,7 +14,7 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile **Two planes with a litmus test.** `cordis.yml` (+ Include patches) stays the composition plane: which plugins exist, wiring, deployment config, owned by the orchestrator and upgraded with the product. A settings namespace carries only the user-editable subset; the test is "should the personal config page edit it?" Values live in both planes without ambiguity because layering is the contract: schema defaults, then the registrant's composition `base` (its entry-config subset), then the user document section. -**Three-package seam mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `/settings.yaml`), chokidar watch, atomic `0600` tmp+rename writes, comment-preserving YAML patching of exactly one namespace key, and content-equality self-write suppression. +**Three-package seam mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `/settings.yaml`), chokidar watch, read-modify-write persists under a cross-process writer lock with atomic `0600` tmp+rename commits, leaf-level diff patching of the written namespace (comments survive untouched nodes), and content-equality self-write suppression ([write-path integrity note](2026-07-30-settings-write-path-integrity.md)). **Registrations are caller-fiber effects.** `register()` runs through the service proxy, so `this.ctx` is the registrant's context and the registration rides `ctx.effect`: disposing the registrant removes the namespace and its watchers (proven by the HMR disposal test), while the user's section keeps living in storage for the next owner. @@ -28,7 +28,7 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile - **Loader-reactive `fiber.update` as the propagation channel**: constructor-time reads observe nothing; the seam's explicit `watch()` makes hot-update a consumer contract instead of framework magic. - **A domain-aware settings service** (getters per product area): the coupling objection from design review stands; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema. - **Multi-layer precedence now** (system/managed/project tiers à la Codex/Claude Code): deferred until a real second layer exists; the resolve step is the single place layering would extend. -- **A cross-process lockfile now** (Pi's proper-lockfile): atomic replace plus watcher convergence (last write wins) is documented behavior until real contention shows up. +- **A cross-process lockfile now** (Pi's proper-lockfile): initially deferred as "atomic replace plus watcher convergence until real contention shows up" — review showed convergence loses unobserved sibling namespaces, so the deferral is superseded by the [write-path integrity note](2026-07-30-settings-write-path-integrity.md)'s hand-rolled writer lock. ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md index eb562099b1..8cd4dfcbb2 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md @@ -14,7 +14,7 @@ Status: implemented **两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是契约：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。 -**镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `/settings.yaml` 的 YAML/JSON、chokidar 监听、`0600` tmp+rename 原子写、只修补目标 namespace 键的保注释 YAML 写回、按内容相等抑制自写。 +**镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。 **注册是调用方 fiber 上的 effect。**`register()` 经服务代理调用，`this.ctx` 即注册方 context，注册挂在 `ctx.effect` 上：dispose 注册方即移除 namespace 及其观察者（HMR disposal 测试证明），而用户的分节继续留在存储中等待下一任 owner。 @@ -28,7 +28,7 @@ Status: implemented - **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者契约而非框架魔法。 - **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。 - **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。 -- **现在就上跨进程锁**（Pi 的 proper-lockfile）：原子替换加 watcher 收敛（后写胜出）是已记录的行为，真实冲突出现再说。 +- **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——评审发现收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。 ## 后果 diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml new file mode 100644 index 0000000000..fa54d657a9 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md +2026-07-30-settings-write-path-integrity.md: 07bd095162879c8e7866846cf562f6a13307e5fc +2026-07-30-settings-write-path-integrity.zh.md: 5d02177073d482b61750d7bdfbbd0866bc227a6a diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md new file mode 100644 index 0000000000..07bd095162 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md @@ -0,0 +1,35 @@ +# Agent Note: settings write-path integrity and observer lifecycle + +Status: implemented + +English | [中文](2026-07-30-settings-write-path-integrity.zh.md) + +> Scope: the third review round over `packages/settings/` — write-path data integrity in `dsh-settings-local` (operation chain, read-modify-write, cross-process writer lock, diff-shaped YAML edits) and observer lifecycle in `dsh-settings` (watch disposal, async listener containment, the JSON-shape write boundary). This note reverses one deferral recorded in the [user-settings seam note](2026-07-28-user-settings-seam.md): the cross-process lockfile now ships. + +## Problem + +Review found the provider's write path could destroy state it never observed, and the seam's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the seam side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep. + +## Decision + +**One operation chain, and every write is a read-modify-write.** Watcher refreshes and persists from every namespace queue share a single settled chain, and `persistSection` begins by reconciling the on-disk text into the seam — publishing any unobserved difference first — before rendering against that fresh text. A write can no longer resurrect a stale document, and an on-disk document that turned invalid fails the write loud rather than being overwritten (the reload path keeps its warn-and-keep-last-good policy; the shared `reconcileFromDisk` throws and each caller picks its policy). The watcher's `ready` signal queues one extra reconcile, closing the startup gap between the initial load and the watcher becoming active. + +**Writes hold a `wx`-created `.lock` sibling.** The read-render-rename cycle runs under a cross-process writer lock with exponential backoff, a 2 s acquisition deadline, and stale takeover after 5 s (a crashed holder, broken with a warning). Readers never lock — the rename commit is atomic — so contention is writer-only and resolves in milliseconds. The lock constants are protocol invariants, not config: a holder rewrites one small document, so the deadline and stale age derive from that bound, not from deployment taste. + +**Observer disposal is quiescent.** Watchers carry an `active` flag checked when a queued invocation would start, so a disposer that ran while the invocation waited prevents the start entirely; started invocations register in a service-level `pendingTails` set that the dispose drain awaits beside the write queues. The `settings/updated` fan-out contains a returned thenable's rejection through the same listener diagnostic as a sync throw, and the event contract now states that the `INVARIANT` rethrow serves synchronous listeners only — invariant companions must stay sync, which the shipped companion already is. + +**The write boundary admits JSON data only.** The call-time snapshot is a single `cloneJsonShaped` walk that detaches the patch and rejects any non-JSON value — Date, Map, BigInt, non-finite number, function, symbol, class instance, `undefined` array entry, circular reference — with its `$`-rooted path before anything persists. Object entries that are explicitly `undefined` still skip (the sparse-patch contract), now enforced at the boundary instead of inside `mergeLayers`. + +**YAML edits are leaf-level diffs.** `renderYaml` diffs the stored section against the next one and applies only `setIn` for changed values and `deleteIn` for removed keys, recursing through maps. Comments, anchors, and formatting survive on every untouched node and on the key node of every changed pair; arrays and other non-map values replace wholesale when unequal (`deepEqualJson` is the shared predicate), taking comments inside them along. + +## Alternatives considered + +- **`proper-lockfile` instead of a hand-rolled lock** — the dependency-over-hand-rolling policy was weighed: the library is barely maintained, its stale/retry policy is broader than this one-file protocol needs, and the shipped lock is ~40 lines with deterministic tests (including injected `EEXIST`/`stat` races). The policy favors dependencies that delete owned code; this one would replace 40 explained lines with an opaque peer. +- **Revision/CAS instead of a lock** — rename cannot express compare-and-swap, so a CAS needs a version sidecar or content re-hash and a retry loop in every writer; the lock achieves the same serialization with one primitive and keeps readers free. +- **Merging external edits into the in-flight write's own section** — the seam merges patches over the state visible at call time, so a same-namespace external edit racing a write still resolves last-write-wins; folding it in would need three-way merge semantics no consumer has asked for. The write publishes the external state first, so the loser is at least observed before being superseded. +- **Declaring async `settings/updated` listeners unsupported** — the typed signature is `void` and lint flags misused promises, but an unlinted JS plugin can still register an async listener; a contract note cannot un-throw an unhandled rejection, so containment is the only defense that holds at runtime. +- **Keeping `structuredClone` and validating in the provider** — the seam is the durable boundary's owner (every provider stores JSON-shaped documents), and rejecting at call time gives the caller the offending path; a provider-side check would reject after merge, blaming the merged section instead of the caller's value. + +## Consequences + +`update()` gained a documented failure mode (lock deadline, invalid on-disk document) and the rejection messages carry `$`-rooted paths. Remaining, documented in the provider README: same-namespace concurrent edits stay last-write-wins (no per-value merge or revision check), a watcher event the OS never delivers leaves the cache stale until the next signal or write, and comments inside replaced arrays or attached inline to changed scalar values go with the value they described. The [user-settings seam note](2026-07-28-user-settings-seam.md)'s deferred-lockfile alternative is superseded by this note. The same defect classes exist in `dsh-credentials-local` (two chains over one `.env`, cached whole-file write-back, post-persist emit) and in the `llm/adapters-updated` fan-out on the stacked branches; those fixes belong to the PRs that introduce the packages and follow this template on merge-up. diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md new file mode 100644 index 0000000000..5d02177073 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md @@ -0,0 +1,41 @@ +# Agent Note: settings 写路径完整性与观察者生命周期 + +Status: implemented + +[English](2026-07-30-settings-write-path-integrity.md) | 中文 + +> 范围：对 `packages/settings/` 的第三轮评审——`dsh-settings-local` 的写路径数据完整性（操作链、读-改-写、跨进程写锁、diff 形态的 YAML 编辑）与 `dsh-settings` 的观察者生命周期（watch 的 dispose（资源释放）、异步监听器收容、JSON 形态写入边界）。本 note 推翻了[用户设置 seam note](2026-07-28-user-settings-seam.md)所记录的一项延后决定：跨进程锁文件现已交付。 + +## 问题 + +评审发现，提供方的写路径可能销毁它从未观察到的状态，而 seam 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。 + +在 seam 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。 + +YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删掉——而这个保注释的提供方承诺过要保住它们。 + +## 决策 + +**单一操作链，且每次写入都是读-改-写。**watcher 的刷新与来自各 namespace 队列的持久化共享同一条结算链；`persistSection` 会先把磁盘上的文本对账进 seam——任何未被观察到的差异都先发布出去——然后才对照这份新鲜文本渲染。写入不再可能复活一份陈旧文档；磁盘上已变非法的文档会让写入响亮失败，而不是被覆盖（重载路径保持其“告警并保留最后可用值”策略；共享的 `reconcileFromDisk` 抛错，各调用方自选策略）。watcher 的 `ready` 信号会额外排入一次对账，弥合初始加载与 watcher 生效之间的启动缺口。 + +**写入持有以 `wx` 创建的同目录 `.lock`。**读-渲染-rename 循环在一把跨进程写锁下运行：指数退避、2 s 获取截止时间、5 s 后陈旧接管（持有者已崩溃；打破旧锁时给出告警）。读方从不加锁——rename 提交是原子的——因此竞争只发生在写方之间，毫秒级即可化解。锁的各项常量是协议不变式，不是配置：持有者只是重写一份小文档，截止时间与陈旧时限都从这一上界推得，而非出自部署偏好。 + +**观察者 dispose 达到完全停稳。**watcher 携带一个 `active` 标志，排队的调用即将启动时先检查它，因此在调用等待期间已经运行过的释放器能让这次启动彻底不发生；已启动的调用会登记进服务级的 `pendingTails` 集合，dispose 排空除了等待各写队列，还会等待该集合。`settings/updated` 扇出会把监听器返回的 thenable 的 rejection 收容进与同步抛错相同的监听器诊断；事件契约现已写明 `INVARIANT` 重抛只服务同步监听器——不变式配套插件必须保持同步，而已交付的那个配套插件本就是同步的。 + +**写入边界只放行 JSON 数据。**调用时刻的快照就是一次 `cloneJsonShaped` 遍历：它把 patch 从调用方分离出来，并在任何内容持久化之前拒绝一切非 JSON 值——Date、Map、BigInt、非有限数值、函数、symbol、类实例、值为 `undefined` 的数组元素、循环引用——拒绝时附带该值以 `$` 为根的路径。显式为 `undefined` 的对象条目仍会跳过（稀疏 patch 契约），这一契约如今在边界处强制执行，而不再放在 `mergeLayers` 内部。 + +**YAML 编辑是叶子级 diff。**`renderYaml` 对比已存储分节与下一份分节，只对变化的值应用 `setIn`、对移除的键应用 `deleteIn`，并沿 map 递归。注释、锚点与格式在每个未触碰节点上、以及每个被改键值对的键节点上全部保留；数组等非 map 值在不相等时整体替换（`deepEqualJson` 是共享的判定谓词），其内部注释随之一并被带走。 + +## 曾考虑的替代方案 + +- **用 `proper-lockfile` 取代手写锁**——按“依赖优先于手写”政策做过权衡：该库几乎无人维护，其陈旧／重试策略比这个单文件协议所需的更宽泛，而已交付的锁约 40 行并带确定性测试（含注入的 `EEXIST`/`stat` 竞态）。该政策偏向能删除自有代码的依赖；这个依赖只会把 40 行带解释的代码换成一个不透明的等价物。 +- **用修订号/CAS 取代锁**——rename 表达不了 compare-and-swap，因此 CAS 需要一个版本伴随文件或内容重哈希，外加每个写方里的一个重试循环；锁用一个原语实现同样的串行化，还让读方完全免锁。 +- **把外部编辑合并进正在进行的写入自身的分节**——seam 是在调用时刻可见的状态之上合并 patch 的，因此与写入竞态的同 namespace 外部编辑仍按后写胜出解决；要把外部编辑并进来，需要三方合并语义，而没有任何消费方提出过这种需求。写入会先发布外部状态，落败一方至少在被取代之前被观察到。 +- **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；契约里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。 +- **保留 `structuredClone`、在提供方里做校验**——seam 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。 + +## 后果 + +`update()` 有了成文的失败模式（锁截止时间到期、磁盘文档非法），rejection 消息携带以 `$` 为根的路径。仍然存在、且已记录在提供方 README 中的有：同 namespace 并发编辑仍是后写胜出（没有逐值合并，也没有修订号检查）；OS 从未投递的 watcher 事件会让缓存保持陈旧，直到下一个信号或下一次写入；被替换数组内部的注释、以及行内附着在被改标量值上的注释，会随其描述的值一起消失。 + +[用户设置 seam note](2026-07-28-user-settings-seam.md)里“延后锁文件”那条替代方案已被本 note 取代。同类缺陷还存在于 `dsh-credentials-local`（两条链共用一个 `.env`、按缓存整文件写回、持久化之后才发事件）与堆叠分支上的 `llm/adapters-updated` 扇出；这些修复归引入相应包（package）的那些 PR（Pull Request）所有，向上合并时按本模板处理。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 8a960f7c04..ce8fd03d49 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1247,7 +1247,7 @@ export interface Config { } ``` -Source: [`packages/settings/settings-local/src/index.ts:19`](../packages/settings/settings-local/src/index.ts) +Source: [`packages/settings/settings-local/src/index.ts:21`](../packages/settings/settings-local/src/index.ts) ## `@deepseek-ai/dsh-skill` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 6cd530e4fd..a1a7efadf4 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -663,13 +663,18 @@ Source: [`packages/core/session/src/index.ts:103`](../../packages/core/session/s ### `settings/updated` — emit -Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. +Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions. ```ts cordis-catalog /** * Committed change to one registered namespace's resolved value. Emitted * after the provider persisted (for `update`) or published (`provider`) * the change; never emitted when the resolved value is deep-equal. + * Listener failures are contained and logged — a sync throw and an async + * rejection alike — except `INVARIANT`-coded failures, which rethrow + * after every listener ran; that rethrow reaches the emitter only from + * synchronous listeners, so invariant checks on this event must not be + * async functions. * @param ns - the namespace whose resolved value changed. * @param next - the new resolved value. * @param prev - the previous resolved value. @@ -681,7 +686,7 @@ Committed change to one registered namespace's resolved value. Emitted after the Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:97`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:106`](../../packages/settings/settings/src/index.ts) ## `skills/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 3fe2e69334..e53d981d03 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1693,7 +1693,7 @@ async replace(ns: SettingsNamespace, section: object): Promise Types: [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:176`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:246`](../../packages/settings/settings/src/index.ts) ## `ctx.skills` — `SkillService` diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/core-data-structures/settings.i18n.yaml index cca43c251b..7a971156e7 100644 --- a/docs/core-data-structures/settings.i18n.yaml +++ b/docs/core-data-structures/settings.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/settings.md -settings.md: abbfecb35f67b27e16dffb9558a35cf368c90beb -settings.zh.md: c746e3cc181f8347cbe634b9231cfee1b3beecd3 +settings.md: 381b36b3ff2f45a2090a2a2eac0f700bd00270c4 +settings.zh.md: bc6547db3b05c5a78f112462ae205d848f93da60 diff --git a/docs/core-data-structures/settings.md b/docs/core-data-structures/settings.md index abbfecb35f..381b36b3ff 100644 --- a/docs/core-data-structures/settings.md +++ b/docs/core-data-structures/settings.md @@ -48,20 +48,24 @@ interface SettingsScope { /** * Observe committed changes to this namespace's resolved value. Invocations * of one callback run asynchronously, one at a time, in commit order; a - * rejection is contained and logged like a sync throw. + * rejection is contained and logged like a sync throw. After the disposer + * returns, no further invocation starts — one already queued is skipped; + * one already started still settles, and service disposal waits for it. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ watch(callback: (next: T, prev: T) => void | Promise): () => void /** * Merge a partial patch into this namespace's user layer and persist it. - * @param patch - plain-object patch over the user section. + * @param patch - plain-object patch over the user section; JSON-shaped data + * only (non-JSON values reject with their path before anything persists). */ update(patch: object): Promise /** * Replace this namespace's user section wholesale; absent keys re-inherit * the composition `base` and schema defaults (`replace({})` resets all). - * @param section - the complete next user section. + * @param section - the complete next user section; JSON-shaped data only, + * as for {@link update}. */ replace(section: object): Promise } diff --git a/docs/core-data-structures/settings.zh.md b/docs/core-data-structures/settings.zh.md index c746e3cc18..bc6547db3b 100644 --- a/docs/core-data-structures/settings.zh.md +++ b/docs/core-data-structures/settings.zh.md @@ -48,20 +48,24 @@ interface SettingsScope { /** * Observe committed changes to this namespace's resolved value. Invocations * of one callback run asynchronously, one at a time, in commit order; a - * rejection is contained and logged like a sync throw. + * rejection is contained and logged like a sync throw. After the disposer + * returns, no further invocation starts — one already queued is skipped; + * one already started still settles, and service disposal waits for it. * @param callback - invoked after each commit with the next and previous values. * @returns the disposer removing this observer. */ watch(callback: (next: T, prev: T) => void | Promise): () => void /** * Merge a partial patch into this namespace's user layer and persist it. - * @param patch - plain-object patch over the user section. + * @param patch - plain-object patch over the user section; JSON-shaped data + * only (non-JSON values reject with their path before anything persists). */ update(patch: object): Promise /** * Replace this namespace's user section wholesale; absent keys re-inherit * the composition `base` and schema defaults (`replace({})` resets all). - * @param section - the complete next user section. + * @param section - the complete next user section; JSON-shaped data only, + * as for {@link update}. */ replace(section: object): Promise } diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index c3a30a2ba7..9638ecfedf 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | -| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:97`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | +| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:106`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | [`tui`](../packages/ui/tui) | | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) | | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:114`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index e2e08d757f..811be436b7 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -1345,7 +1345,7 @@ export const EVENT_API: readonly EventApiEntry[] = [ name: 'settings/updated', mode: 'emit', signature: '\'settings/updated\'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void', - jsDoc: '/**\n * Committed change to one registered namespace\'s resolved value. Emitted\n * after the provider persisted (for `update`) or published (`provider`)\n * the change; never emitted when the resolved value is deep-equal.\n * @param ns - the namespace whose resolved value changed.\n * @param next - the new resolved value.\n * @param prev - the previous resolved value.\n * @param source - whether the change entered through `update()` or the provider.\n * @mode emit\n */', + jsDoc: '/**\n * Committed change to one registered namespace\'s resolved value. Emitted\n * after the provider persisted (for `update`) or published (`provider`)\n * the change; never emitted when the resolved value is deep-equal.\n * Listener failures are contained and logged — a sync throw and an async\n * rejection alike — except `INVARIANT`-coded failures, which rethrow\n * after every listener ran; that rethrow reaches the emitter only from\n * synchronous listeners, so invariant checks on this event must not be\n * async functions.\n * @param ns - the namespace whose resolved value changed.\n * @param next - the new resolved value.\n * @param prev - the previous resolved value.\n * @param source - whether the change entered through `update()` or the provider.\n * @mode emit\n */', summary: 'Committed change to one registered namespace\'s resolved value.', }, { diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml index 5d44f50f9d..9638a62f96 100644 --- a/packages/settings/settings-local/README.i18n.yaml +++ b/packages/settings/settings-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings-local/README.md -README.md: af8df7c030757b330e034a1c46507fbe75c9bab8 -README.zh.md: fc8943263b339baad1a92a1d0b0977b926e40f6e +README.md: 2c0817afd2f2fd35fda2d22cd7f7ef3772fe2257 +README.zh.md: 547abb035368f07d4478a5c3a1793cdaa6743c68 diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md index af8df7c030..2c0817afd2 100644 --- a/packages/settings/settings-local/README.md +++ b/packages/settings/settings-local/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -File-backed settings provider. One YAML or JSON document carries every namespace section; external edits hot-publish through `ctx.settings`, and `update()` writes back atomically while preserving the user's YAML comments and any section owned by a plugin that is not currently loaded. +File-backed settings provider. One YAML or JSON document carries every namespace section; external edits hot-publish through `ctx.settings`, and `update()` re-reads the document under a writer lock before writing back atomically, preserving the user's YAML comments, any section owned by a plugin that is not currently loaded, and any on-disk change this process has not observed yet. ## Config @@ -18,9 +18,13 @@ Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension ## Behavior - **Boot fails loud, reload keeps last-good.** An existing-but-invalid document fails plugin load; once live, an unreadable or unparsable edit warns and keeps the last good sections. A missing document resolves every namespace from defaults and `base`; deleting it publishes the same empty state. -- **Write-back is atomic, owner-only, and symlink-proof.** `persist` exclusive-creates a random-suffix temp sibling with mode `0600` (`wx` refuses to follow a planted symlink) and renames over the target, cleaning the temp up on failure. YAML writes patch one namespace in the comment-preserving document; JSON re-serializes. -- **Cross-namespace writes serialize on one document.** Every namespace shares the file, so persists from different namespace queues chain internally; each render sees the text the previous write committed. -- **Dispose quiesces.** Teardown stops accepting watcher events, closes the watcher, then waits out any queued or in-flight reload, so nothing publishes after disposal. +- **Every write is a read-modify-write.** A persist first re-reads the document and publishes any difference into the seam — an external edit still inside the watcher debounce window, a change the watcher missed, or another process's write — then renders against that fresh text, so a write can never resurrect a stale document or drop an unobserved sibling section. If the on-disk document turned invalid, the write rejects loud instead of overwriting the user's manual edit. +- **Writes hold a cross-process writer lock.** The read-render-rename cycle runs under a `wx`-created `.lock` sibling with exponential backoff, a 2 s acquisition deadline (the write rejects), and stale-lock takeover after 5 s (a crashed holder, broken with a warning). Readers never take the lock: the rename commit is atomic, so reloads are always consistent. +- **Write-back is atomic, owner-only, and symlink-proof.** The render exclusive-creates a random-suffix temp sibling with mode `0600` (`wx` refuses to follow a planted symlink) and renames over the target, cleaning the temp up on failure. +- **YAML edits are leaf-level diffs.** A write sets only the values that changed and deletes only the keys that were removed, so comments, anchors, and formatting survive on every untouched node and on the key of every changed pair; a changed array (or other non-map value) replaces wholesale, taking comments inside it along. JSON re-serializes without comments. +- **Reloads and writes share one operation chain.** Watcher refreshes and persists from every namespace queue run one at a time in queue order; each render sees the text the previous operation committed. +- **The watcher's ready signal reconciles once.** The initial load races the watcher's own setup, so a change written in between never fires an event; the reconcile at ready closes that startup gap. +- **Dispose quiesces.** Teardown stops accepting watcher events, closes the watcher, then waits out any queued or in-flight operation, so nothing publishes after disposal. - **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op. ## Model Experience @@ -33,6 +37,7 @@ No direct invalidation; the consuming plugin owns any request-prefix changes. ## Known Limitations and Deferred Work -- **No cross-process write lock** — concurrent writers (for example TUI and web on one home) converge by atomic replace plus watcher reload, last write wins; a lockfile is deferred until real contention shows up. -- **Comment preservation is YAML-only** — JSON documents re-serialize without comments (JSON has none) and lose hand formatting. +- **Same-namespace conflicts stay last-write-wins** — the writer lock and read-modify-write keep concurrent writers from dropping each other's namespaces, but two writers editing one namespace still resolve to the later write; there is no per-value merge or revision check. +- **A missed watcher event stays unseen until the next signal** — reads never re-stat the file, so a change the watcher fails to report is only folded in by the next event, the next write, or a restart. +- **Comment preservation is YAML-only and map-shaped** — JSON documents re-serialize without comments (JSON has none), and comments inside a changed array (or attached inline to a changed scalar value) go with the value they described. - **No value indirection** — sections hold literal values; `${env:VAR}`-style references for secrets are a deferred seam-level feature. diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md index fc8943263b..547abb0353 100644 --- a/packages/settings/settings-local/README.zh.md +++ b/packages/settings/settings-local/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 原子写回，并保留用户的 YAML 注释以及当前未加载插件所拥有的分节。 +文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。 ## 配置 @@ -18,9 +18,13 @@ ## 行为 - **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。 -- **写回原子、仅属主可读、抗符号链接。** `persist` 以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。YAML 写回在保留注释的文档里只修补目标 namespace；JSON 重新序列化。 -- **跨 namespace 写入在同一文档上串行。** 所有 namespace 共享一个文件，来自不同 namespace 队列的 persist 在内部串联；每次渲染都基于上一次写入提交后的文本。 -- **Dispose 保证静止。** 卸载先停止接收 watcher 事件、关闭 watcher，再等完排队与进行中的重载，之后不再有任何发布。 +- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入响亮拒绝，而不是覆盖用户的手工编辑。 +- **写入持有跨进程写锁。** 读-渲染-rename 流程在 `wx` 创建的 `.lock` 同级文件下运行，带指数退避、2 s 的获取期限（到期则写入拒绝）与 5 s 后的陈旧锁接管（持有者已崩溃，破锁并告警）。读取方从不取锁：rename 提交是原子的，重载因此始终一致。 +- **写回原子、仅属主可读、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。 +- **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。 +- **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。 +- **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。 +- **Dispose 保证静止。** 卸载先停止接收 watcher 事件、关闭 watcher，再等完排队与进行中的操作，之后不再有任何发布。 - **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。 ## Model Experience @@ -33,6 +37,7 @@ ## Known Limitations and Deferred Work -- **无跨进程写锁** — 并发写入者（例如同一 home 上的 TUI 与 web）靠原子替换加 watcher 重载收敛，后写胜出；lockfile 等真实冲突出现再做。 -- **注释保留仅限 YAML** — JSON 文档重新序列化，无注释（JSON 本身没有）且丢失手工排版。 +- **同 namespace 冲突仍是后写胜出** — 写锁加读-改-写让并发写入者不会丢掉彼此的 namespace，但两个写入者编辑同一个 namespace 时仍以较后的写入为准；没有按值合并，也没有修订检查。 +- **漏掉的 watcher 事件在下一个信号前保持不可见** — 读取从不重新 stat 文件，因此 watcher 漏报的变更只会在下一个事件、下一次写入或重启时被并入。 +- **注释保留仅限 YAML 且仅限 map 形状** — JSON 文档重新序列化，无注释（JSON 本身没有），且被改数组内部的注释（或行内附着在被改标量值上的注释）随其所描述的值一同被换掉。 - **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是 seam 层的延后特性。 diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts index b9df71f9e1..04ba6808a3 100644 --- a/packages/settings/settings-local/src/index.ts +++ b/packages/settings/settings-local/src/index.ts @@ -1,7 +1,9 @@ /** * File-backed settings provider. One YAML or JSON document under the user's * harness home carries every namespace section; external edits hot-publish - * through the seam and `update()` writes back preserving the user's comments. + * through the seam, and every write re-reads the document under a + * cross-process writer lock before patching it as a comment-preserving + * leaf-level diff. * @module @deepseek-ai/dsh-settings-local */ diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml index 63a274dd4d..4f03498b06 100644 --- a/packages/settings/settings/README.i18n.yaml +++ b/packages/settings/settings/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/settings/settings/README.md -README.md: ff6cdeb57a265dbaa9d5f50de1d558f1e3cb581f -README.zh.md: d820a5c1fa804455c439f1a155e7628f5118a49b +README.md: ec9f0e09c47015edd8495dac48beb610e0b5cdc5 +README.zh.md: 6d0a760f9b1bbef21881a03933d0fe5b9fc3cd0d diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md index ff6cdeb57a..ec9f0e09c4 100644 --- a/packages/settings/settings/README.md +++ b/packages/settings/settings/README.md @@ -9,10 +9,10 @@ Abstract user-settings seam (`ctx.settings`). One provider holds a raw document - `register(ns, schema, { base?, applies? })` — returns the owner `SettingsScope` (`get`/`watch`/`update`). The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. A stored section the schema rejects fails the registration itself; a duplicate namespace fails loud. - `describe()` — one descriptor per namespace (`schema.toJSON()` envelope, resolved value, `applies`) for configuration surfaces. - `get(ns)` — resolved value, `undefined` while unregistered. -- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every write. Writes to one namespace are serialized in call order. +- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Patches must be JSON-shaped data: a Date, Map, BigInt, non-finite number, or circular reference rejects with its `$`-rooted path before anything persists (YAML/JSON storage would silently distort such values on reload). Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every write. Writes to one namespace are serialized in call order. - `replace(ns, section)` — sets the user section wholesale: the removal/reset path a merge cannot express (`replace({})` re-inherits `base` and schema defaults). -- Resolved values are deep-frozen snapshots. Watchers receive `(next, prev)` after each commit: invocations of one callback run asynchronously, one at a time, in commit order (a slow stale invocation can never apply after a newer one), and failures — sync throws and async rejections alike — are contained. The `settings/updated` event fans out one listener at a time, so one throwing listener cannot starve the rest. -- Service teardown refuses new writes and drains every queued write before disposal completes; a write whose registrant fiber was disposed mid-flight still reaches storage but commits and notifies nobody. +- Resolved values are deep-frozen snapshots. Watchers receive `(next, prev)` after each commit: invocations of one callback run asynchronously, one at a time, in commit order (a slow stale invocation can never apply after a newer one), and failures — sync throws and async rejections alike — are contained. After a watch disposer returns, no further invocation starts (one already queued is skipped); an invocation already started still settles. The `settings/updated` event fans out one listener at a time, so one throwing listener cannot starve the rest; an async listener's rejection is contained and logged, which is why `INVARIANT`-coded failures rethrow only from synchronous listeners. +- Service teardown refuses new writes and watcher starts, then drains every queued write and every started watcher invocation before disposal completes; a write whose registrant fiber was disposed mid-flight still reaches storage but commits and notifies nobody. ## Provider contract @@ -33,5 +33,5 @@ No direct invalidation; a consumer that folds a settings value into the request ## Known Limitations and Deferred Work - **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet. -- **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider is last-write-wins). +- **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider read-modify-writes under a writer lock, so namespaces survive concurrent writers and same-namespace conflicts resolve last-write-wins). - **No secret-field redaction** — `describe()` returns resolved values verbatim; a wire surface (RPC/UI) must redact `role('secret')` fields before exposure. diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md index d820a5c1fa..6d0a760f9b 100644 --- a/packages/settings/settings/README.zh.md +++ b/packages/settings/settings/README.zh.md @@ -9,10 +9,10 @@ - `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。 - `describe()` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、`applies`），供配置界面使用。 - `get(ns)` — 解析值；未注册时为 `undefined`。 -- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。 +- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。 - `replace(ns, section)` — 整体替换用户分节：merge 表达不了的删除/重置路径（`replace({})` 重新继承 `base` 与 schema 默认值）。 -- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener。 -- 服务卸载先拒绝新写入并排干全部排队写入后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。 +- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。 +- 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。 ## Provider 契约 @@ -33,5 +33,5 @@ ## Known Limitations and Deferred Work - **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。 -- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 为后写胜出）。 +- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。 - **无 secret 字段脱敏** — `describe()` 原样返回解析值；wire 面（RPC/UI）在暴露前必须对 `role('secret')` 字段脱敏。 From 2b379799ba5e38b378e11c8ae2ad0c5b860a6969 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 30 Jul 2026 14:13:15 +0800 Subject: [PATCH 28/67] test(settings): make third-review specs conform to strict optional and misused-promise contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the explicit-undefined base fixture exactOptionalPropertyTypes forbids (the repository trusts TypeScript at typed same-process seams — no test for an input the static interface excludes; coverage holds), and reshape the async-listener containment fixture as an unknown-returning function: the earlier inline cast was silently stripped by the staged oxlint fixer, leaving a shape the next lint pass rejects. --- .../settings/settings/tests/settings.spec.ts | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts index cfd88b166f..379ce02d08 100644 --- a/packages/settings/settings/tests/settings.spec.ts +++ b/packages/settings/settings/tests/settings.spec.ts @@ -228,14 +228,6 @@ describe('update', () => { expect(scope.get()).toEqual({ theme: 'light', fontSize: 18 }) }) - it('ignores an explicit undefined entry in the composition base layer', async () => { - const { ctx } = await boot({ doc: { 'ui-theme': { theme: 'light' } } }) - const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { - base: { theme: undefined, fontSize: 16 }, - }) - expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 }) - }) - it('rejects a non-object patch', async () => { const { ctx } = await boot() const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) @@ -616,12 +608,13 @@ describe('third review regressions', () => { it('contains an async settings/updated listener rejection and keeps other listeners running', async () => { const { ctx, provider } = await boot() - // An async listener violates the event's synchronous signature (typed - // consumers get a lint error for it), but an unlinted JS plugin can still - // register one; the cast simulates exactly that caller. - ctx.on('settings/updated', async () => { - throw new Error('async listener boom') - }) + // An async listener violates the event's synchronous signature, but an + // unlinted JS plugin can still register one. Declaring the return as + // unknown keeps this file's typed surface legal (unknown-returning + // functions are assignable to void positions) while the runtime value is + // still the rejected promise the containment guard must handle. + const boom = (): unknown => Promise.reject(new Error('async listener boom')) + ctx.on('settings/updated', boom) const second = vi.fn() ctx.on('settings/updated', second) ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema) From e596d300d745d25c4cb0fb0dde0430e3cc2ea00c Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 15:22:28 +0800 Subject: [PATCH 29/67] fix(directory-picker-browse): resolve quiet-navigation review --- ...d-scrollbars-and-reserved-gutter.i18n.yaml | 4 +- ...8-themed-scrollbars-and-reserved-gutter.md | 6 +-- ...hemed-scrollbars-and-reserved-gutter.zh.md | 6 +-- .../src/client/DirectoryBrowser.module.css | 12 ++++-- .../src/client/DirectoryBrowser.tsx | 31 +++++++++---- .../tests/directory-browser.spec.tsx | 43 ++++++++++++++++++- 6 files changed, 80 insertions(+), 22 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml index 8099344ace..45e957b824 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md -2026-07-28-themed-scrollbars-and-reserved-gutter.md: 76dcb6d9f3976faf3338a89f3ccab7182fe6d5ab -2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: ff12c6884bec706dbbd9974684010cbcd9fa03bf +2026-07-28-themed-scrollbars-and-reserved-gutter.md: b45f70b126d083916c756afb88a8b646a4e9bb85 +2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 8afa36429ce7e6e061b014d63dcb20e5a642a84c diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md index 76dcb6d9f3..b45f70b126 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md @@ -20,13 +20,13 @@ The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-a The two renderings are mutually exclusive, and the exclusion is enforced rather than assumed. A non-`auto` `scrollbar-width` or `scrollbar-color` makes Chromium and Safari discard every `::-webkit-scrollbar*` rule for that element, `::-webkit-scrollbar-thumb:hover` included. Declaring both unconditionally therefore leaves the hover token rendering nowhere at all: the engines that implement the hover pseudo-element are exactly the ones the standard properties silence, and Firefox has no hover pseudo-element to fall back on. The standard properties consequently sit inside `@supports not selector(::-webkit-scrollbar)`, which is true only where the pseudo-element is unimplemented, so Firefox takes the standard path and WebKit-based engines take the pseudo-element path. The WebKit rules are not gated in turn: an engine without those pseudo-elements drops them as unknown selectors, so a gate would only restate what selector matching already does. An engine too old for the `selector()` function makes the condition invalid, which evaluates false and selects the pseudo-element path — the correct side for the pre-16.4 Safari that is the realistic case for that reading. -Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The set of rebinding surfaces is owned by the mechanical gate (`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`): any sheet that scrolls and paints an elevated surface must rebind, so this note no longer enumerates them (an enumeration here drifted twice). Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. +Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls. -The last four were missed in the first implementation and found in review, which is why the rebinding contract is now checked mechanically rather than by inspection: a sheet that scrolls somewhere and paints an elevated surface somewhere must rebind. +Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were missed in the first implementation and found in review, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection. The elevated set is resolved from the palette's own dark elevation ladder — the surface tokens whose dark value lands on `bg-layer-2` or `bg-layer-3`, which is the step the l1/l2 split encodes. Deriving it instead from the sheets that already rebind was the first attempt and is unsound: such a set can only confirm what someone already remembered, and a surface nobody has rebound yet — exactly the case the check exists for — defines itself as unelevated. `--dsw-specific-tip` proved it, resolving to the menu surface's rung while the todo panel scrolled on it unrebound and the derived check stayed green. -Scope is by token family, not by geometry: only `--dsw-alias-bg-*` and `--dsw-specific-*` name a surface. `--dsw-alias-button-*`, `--dsw-alias-interactive-*`, and `--dsw-alias-markdown-*` reach the same rungs while naming a control or an inline span that no scroll container renders its bar against. Shape cannot make that call, since a floating button legitimately carries a radius, a shadow, and a fixed size. The check is per sheet rather than per rule because the card and the descendant that scrolls are separate rules, and CSS text does not express which contains which. +Scope is by token family, not by geometry: only `--dsw-alias-bg-*` and `--dsw-specific-*` name a surface. `--dsw-alias-button-*`, `--dsw-alias-interactive-*`, and `--dsw-alias-markdown-*` reach the same rungs while naming a control or an inline span that no scroll container renders its bar against. Shape cannot make that call, since a floating button legitimately carries a radius, a shadow, and a fixed size. The check is per sheet rather than per rule because the card and the descendant that scrolls are separate rules. That approximation cannot detect a scrolling component embedded in an elevated card painted by another package's stylesheet, as `DirectoryBrowser` inside `Modal` demonstrated; cross-sheet composition remains a review and assembled-UI responsibility. The track and the corner stay transparent, so the thumb reads against whatever surface scrolls under it; only the thumb and its hover state carry a token color. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md index ff12c6884b..8afa36429c 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md @@ -20,13 +20,13 @@ Status: implemented 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。 -两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。重新绑定表面的集合归机械门禁（`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`）所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再枚举它们（这里的枚举已经漂移过两次）。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 +两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。 -后四处在最初的实现里被漏掉、由评审发现，因此重新绑定契约现在由机械检查把关，而不再依赖人工审阅：一张样式表只要在某处滚动、又在某处绘制抬升表面，就必须重新绑定。 +`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。 -判定范围依据 token 家族而非几何形状：只有 `--dsw-alias-bg-*` 与 `--dsw-specific-*` 表述的是表面。`--dsw-alias-button-*`、`--dsw-alias-interactive-*` 与 `--dsw-alias-markdown-*` 会落到相同档位，但它们表述的是控件或行内片段，没有任何滚动容器会把滚动条画在它们之上。形状无法做这个判断，因为悬浮按钮本来就会带圆角、阴影和固定尺寸。这项检查以样式表为粒度而非以规则为粒度，因为卡片与真正滚动的后代元素是两条不同的规则，而 CSS 文本无法表达谁包含谁。 +判定范围依据 token 家族而非几何形状：只有 `--dsw-alias-bg-*` 与 `--dsw-specific-*` 表述的是表面。`--dsw-alias-button-*`、`--dsw-alias-interactive-*` 与 `--dsw-alias-markdown-*` 会落到相同档位，但它们表述的是控件或行内片段，没有任何滚动容器会把滚动条画在它们之上。形状无法做这个判断，因为悬浮按钮本来就会带圆角、阴影和固定尺寸。这项检查以样式表为粒度而非以规则为粒度，因为卡片与真正滚动的后代元素是两条不同的规则。这种近似检查无法检测嵌在由另一个包的样式表绘制的抬升卡片中的滚动组件，`Modal` 内的 `DirectoryBrowser` 就证明了这一点；跨样式表的组合仍需在评审和组装后 UI 层面把关。 轨道与两条滚动条相交的角落保持透明，因此滑块是以其下滚动的任何表面为背景被看到；只有滑块及其 hover 状态带 token 颜色。 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index 594f450756..2f207e4195 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -242,6 +242,10 @@ .status, .error { padding: 4px; + /* The loading pill occupies the opposite corner while a stale status stays + * visible. Reserve its widest localized footprint so wrapped text cannot + * run underneath it on a narrow card. */ + padding-right: 120px; font-size: 12px; line-height: 18px; } @@ -259,15 +263,15 @@ * the columns' height, and the stale view keeps rendering beneath it (it * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right, * not left: the truncated/error status rows flow at the bottom LEFT and - * stay on screen through a scan, so the opposite corner keeps both - * legible. After .status in the cascade — the element carries both - * classes and this padding must win the same-specificity race. */ + * stay on screen through a scan, with their reserved right padding keeping + * both legible even on a narrow card. After .status in the cascade — the + * element carries both classes and this padding must win the + * same-specificity race. */ .loadingFloat { position: absolute; right: 16px; bottom: 8px; padding: 2px 8px; - border-radius: 6px; background: var(--dsw-alias-bg-layer-2); } diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 023404f71d..f5510fda7c 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -186,10 +186,14 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const [selected, setSelected] = useState(null) const [child, setChild] = useState(null) const [loading, setLoading] = useState(false) - // Derived from `loading` by the slow-scan effect below: true only once a - // scan has been in flight for SLOW_SCAN_DELAY_MS, so fast listings never - // render the indicator at all. + // Derived from `loading` and `scanWindow` by the slow-scan effect below: + // true only once the current listing call has been in flight for + // SLOW_SCAN_DELAY_MS, so fast listings never render the indicator at all. const [slowScan, setSlowScan] = useState(false) + // Every listing call owns a fresh silence window. `loading` may stay true + // across a superseding row pick or across a navigation's target and parent + // legs, so its boolean edge cannot identify the start of each scan. + const [scanWindow, setScanWindow] = useState(0) const [error, setError] = useState(null) // Path-edit state: null = breadcrumb mode; a string = the draft being typed. const [pathDraft, setPathDraft] = useState(null) @@ -233,13 +237,20 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, return ++requestSeq.current }, []) + /** Hide any prior indicator and start a fresh silence window for one listing call. */ + const restartSlowScanWindow = useCallback((): void => { + setSlowScan(false) + setScanWindow(value => value + 1) + }, []) + /** Launch one listing under a fresh controller so a later supersession can abort it. */ const launchListing = useCallback((path: string | undefined): { seq: number; scan: Promise } => { const seq = supersede() const controller = new AbortController() scanController.current = controller + restartSlowScanWindow() return { seq, scan: listDirectory(path, controller.signal) } - }, [supersede, listDirectory]) + }, [supersede, restartSlowScanWindow, listDirectory]) /** * Launch a follow-up listing under the CURRENT supersession seq: a newer @@ -248,8 +259,9 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const continueScan = useCallback((path: string): Promise => { const controller = new AbortController() scanController.current = controller + restartSlowScanWindow() return listDirectory(path, controller.signal) - }, [listDirectory]) + }, [restartSlowScanWindow, listDirectory]) /** * Replace the whole view with a freshly navigated level. Away from the @@ -474,9 +486,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }) } - // The slow-scan gate for the loading indicator: arm a timer when a scan - // starts, retire it (and the indicator) the moment loading ends. A settle - // inside the window means the swap happened with nothing shown. + // The slow-scan gate for the loading indicator: each listing call restarts + // the timer even when a superseding scan or a navigation's parent leg keeps + // `loading` continuously true. A settle inside its own window means the swap + // happened with nothing shown. useEffect(() => { if (!loading) { setSlowScan(false) @@ -484,7 +497,7 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, } const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS) return () => { window.clearTimeout(timer) } - }, [loading]) + }, [loading, scanWindow]) // After the hooks: a closed dialog renders nothing and evaluates no copy. const crumbSource = child ?? parent diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 0fe1f91e00..ce9f03fb0b 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -111,6 +111,12 @@ function rowButton(item: HTMLElement): HTMLButtonElement { } describe('DirectoryBrowser', () => { + it('renders nothing and launches no listing while initially closed', () => { + const b = mount({ open: false }) + expect(screen.queryByRole('dialog')).toBeNull() + expect(b.listDirectory).not.toHaveBeenCalled() + }) + it('opens at the Host home as one wide column, hides hidden entries, and roots the crumbs at Home', async () => { const b = mount() await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) @@ -335,9 +341,16 @@ describe('DirectoryBrowser', () => { fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target can consume most of the outer scan's silence window. + await act(async () => { vi.advanceTimersByTime(250) }) await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // Its parent leg gets a fresh silence window. Crossing the original + // scan's 300ms deadline therefore cannot flash the indicator during the + // bounded landing wait. + await act(async () => { vi.advanceTimersByTime(199) }) + expect(screen.queryByText('browser.loading')).toBeNull() // The parent leg outlives PARENT_LEG_WAIT_MS: the target lands alone. - await act(async () => { vi.advanceTimersByTime(200) }) + await act(async () => { vi.advanceTimersByTime(1) }) expect(columns()).toHaveLength(1) expect(screen.getByRole('listitem').textContent).toBe('harness') expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() @@ -417,6 +430,34 @@ describe('DirectoryBrowser', () => { } }) + it('restarts the silence window when a row pick supersedes a pending scan', async () => { + vi.useFakeTimers() + try { + const pending: ((value: DirectoryListing) => void)[] = [] + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve(listingFor(path)) + return new Promise((resolve) => { pending.push(resolve) }) + }) + mount({ listDirectory }) + await act(async () => {}) + const documents = rowButton(screen.getByRole('listitem')) + fireEvent.click(documents) + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // The same row remains actionable while its preview is pending. A second + // pick starts a new listing without a false `loading` edge. + fireEvent.click(documents) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(299) }) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(1) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + await act(async () => { pending.at(-1)!(listingFor(DOCS)) }) + } finally { + vi.useRealTimers() + } + }) + it('a close mid-scan resets the slow-scan gate: reopening waits a fresh silence window', async () => { vi.useFakeTimers() try { From 9ba6462d4207da3468ea794016da3074b30299a1 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Thu, 30 Jul 2026 15:50:02 +0800 Subject: [PATCH 30/67] chore: retrigger CI after master merge From 0a25c0d2371eb3ecc84545ae5241821e2f2961f1 Mon Sep 17 00:00:00 2001 From: kingwl Date: Thu, 30 Jul 2026 16:41:55 +0800 Subject: [PATCH 31/67] feat(web): add queue collapse control --- ...-29-addressable-queue-operations.i18n.yaml | 4 +- ...2026-07-29-addressable-queue-operations.md | 4 +- ...6-07-29-addressable-queue-operations.zh.md | 4 +- apps/web/tests/queue-actions.e2e.ts | 4 + .../queue-actions/editing.expected.md | 1 + .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 + packages/client/ui-conversation/README.zh.md | 2 + .../src/client/queue/QueueDock.module.css | 39 ++++ .../src/client/queue/QueueDock.tsx | 190 ++++++++++-------- .../ui-conversation/tests/queue-dock.spec.tsx | 33 ++- 11 files changed, 190 insertions(+), 97 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml index 85befa1383..3524737277 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md -2026-07-29-addressable-queue-operations.md: 78a7d346163bb7e5e76c989c6e93576b4a6cee64 -2026-07-29-addressable-queue-operations.zh.md: 050b9755ad4ebe70e2bdcafb711ef279331e27af +2026-07-29-addressable-queue-operations.md: 28570be7a2a520fd8293a73526302122740823ca +2026-07-29-addressable-queue-operations.zh.md: eb62d45c6572cd993fedf982d6c86e2ff19787a6 diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md index 78a7d34616..28570be7a2 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md @@ -18,7 +18,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M **Queue addresses require a live Agent.** `session.updateQueue` queries only the mounted Agent registry and never resumes a cold session: an `InboxItemId` is process-local and cannot name work after restart or disposal. A missing Agent and a driver-claimed occurrence both return `queue-item-not-found`. -**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock exposes edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. +**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `" Queued"` header that expands or collapses the complete list. The header exposes `aria-expanded`. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. ## Alternatives considered @@ -34,7 +34,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M ## Verification -AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios drive the exposed edit and delete actions through the built Web composition and real HTTP/SSE wire. +AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios expand the queue and drive its exposed edit and delete actions through the built Web composition and real HTTP/SSE wire. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md index 050b9755ad..eb62d45c65 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md @@ -18,7 +18,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 **Queue 寻址要求 Agent 存活。** `session.updateQueue` 只查询已挂载的 Agent 注册表，绝不恢复冷会话：`InboxItemId` 属于进程本地标识，无法在重启或资源释放后继续指向工作。Agent 缺失和单次入队项已被驱动器认领这两种情况都返回 `queue-item-not-found`。 -**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 暴露编辑和删除，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。 +**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `" Queued"` 表头。表头暴露 `aria-expanded`。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。 ## 考虑过的替代方案 @@ -34,7 +34,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 ## 验证 -AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会通过构建后的 Web 组合和真实 HTTP／SSE 协议操作公开的编辑和删除。 +AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会展开队列，并通过构建后的 Web 组合和真实 HTTP／SSE 协议操作其公开的编辑和删除。 ## 后果 diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts index 1df3ffc247..025747c37d 100644 --- a/apps/web/tests/queue-actions.e2e.ts +++ b/apps/web/tests/queue-actions.e2e.ts @@ -80,6 +80,10 @@ describe('web e2e: queue row actions', () => { await input.fill(text) await input.press('Enter') } + const queueHeader = page.getByRole('button', { name: '2 Queued' }) + await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 }) + .toBe('false') + await queueHeader.click() await expect.poll( () => page.getByRole('button', { name: '删除排队消息' }).count(), { timeout: 10_000 }, diff --git a/apps/web/tests/snapshots/queue-actions/editing.expected.md b/apps/web/tests/snapshots/queue-actions/editing.expected.md index 311c961450..0bb20cde47 100644 --- a/apps/web/tests/snapshots/queue-actions/editing.expected.md +++ b/apps/web/tests/snapshots/queue-actions/editing.expected.md @@ -12,6 +12,7 @@ - button "编辑": - img - paragraph: partial +- button "2 Queued" [expanded] - list: - listitem: - text: Queue item to remove diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 654722b589..5b9adf8b01 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 3973c14f2b8fe746549bb74af85a7a60a7d66aea -README.zh.md: a6bb15c4cdd53d05bf28147b97d9d64d1c59da2b +README.md: 6e48c127b18eb65008edd2debf9835e5beffdcca +README.zh.md: 632d2f9959ac496e6f4512ec30ca0f97c53a5abf diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 3973c14f2b..6e48c127b1 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -18,6 +18,8 @@ Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.to The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`/ 已完成 · ` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"/ tasks · in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. +`QueueDock` takes the same input-dock list at `order: 0`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `" Queued"` header whose button expands or collapses the complete list. The header exposes `aria-expanded`; each visible row remains a single-line preview with its exact-occurrence edit and delete actions. + Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks. The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `command.hint` locale namespace this package registers and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The resident no-session shell uses `DisabledInputBar` and therefore dispatches no session-scoped control seats. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index a6bb15c4cd..632d2f9959 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -18,6 +18,8 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: -1` 占用 `'conversation.input.dock'` 列表 slot（位于队列行之上），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。 +`QueueDock` 以 `order: 0` 占用同一个 input-dock 列表。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `" Queued"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded`；每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。 + 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。常驻无会话壳使用 `DisabledInputBar`，因此不会分发任何会话作用域的控件 seat。 diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css index 4c05c2cbca..ce4455509b 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css @@ -30,6 +30,45 @@ pointer-events: none; } +.header { + box-sizing: border-box; + display: flex; + align-items: center; + gap: 10px; + width: 100%; + height: 36px; + padding: 4px 16px 4px 12px; + border: none; + border-radius: 8px; + background: transparent; + color: var(--dsw-alias-label-primary); + text-align: left; + cursor: pointer; +} + +.header:focus-visible { + outline: 2px solid var(--dsw-alias-label-tertiary); + outline-offset: -2px; +} + +.count { + flex: 1 1 auto; + min-width: 0; + font-family: Inter, var(--dsw-font-family); + font-size: 14px; + font-weight: 500; + line-height: 24px; +} + +.chevron { + display: grid; + flex: none; + place-items: center; + width: 14px; + height: 14px; + color: var(--dsw-alias-label-tertiary); +} + .list { margin: 0; padding: 0; diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index 99b91f301d..b4f7da1cc5 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -8,7 +8,8 @@ import { useEffect, useState } from 'react' import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client' import { - IconCheckOutline16, IconCloseOutline16, IconEditOutline16, IconTrashOutline16, + IconCheckOutline16, IconChevronDownOutline14, IconChevronUpOutline14, + IconCloseOutline16, IconEditOutline16, IconTrashOutline16, } from '@deepseek-ai/dsh-client-ui-primitives' import type { QueueAction, QueueItemId } from '../contract/queue.ts' import css from './QueueDock.module.css' @@ -22,11 +23,15 @@ export interface QueueDockInjected { /** Full props of a dock entry: InputZone owner share + session standard kit + global seat. */ export type QueueDockProps = PropsRuntime<'conversation.input.dock'> & QueueDockInjected -/** Queue strip: one preview line per queued message; renders null when the queue is empty. */ +/** + * Queue strip: one item renders directly; multiple items default to a + * collapsible count header; an empty queue renders nothing. + */ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) { const queue = useSession(s => s.queue) const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null) const [busy, setBusy] = useState(null) + const [collapsed, setCollapsed] = useState(true) useEffect(() => { if (editing !== null && !queue.some(row => row.id === editing.id)) setEditing(null) @@ -63,92 +68,107 @@ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) { return (
-
    - {queue.map(row => ( -
  • - {editing?.id === row.id - ? ( - { setEditing({ id: row.id, text: event.currentTarget.value }) }} - onKeyDown={(event) => { - if (event.key === 'Escape') { - setEditing(null) - return - } - if (event.key === 'Enter' && !event.nativeEvent.isComposing) { - event.preventDefault() - void saveEdit() - } - }} - /> - ) - : {row.preview}} -
    + {queue.length > 1 && ( + + )} + {(queue.length === 1 || !collapsed) && ( +
      + {queue.map(row => ( +
    • {editing?.id === row.id ? ( - <> - - - + { setEditing({ id: row.id, text: event.currentTarget.value }) }} + onKeyDown={(event) => { + if (event.key === 'Escape') { + setEditing(null) + return + } + if (event.key === 'Enter' && !event.nativeEvent.isComposing) { + event.preventDefault() + void saveEdit() + } + }} + /> ) - : ( - <> - - - - )} -
    -
    • - ))} -
+ : {row.preview}} +
+ {editing?.id === row.id + ? ( + <> + + + + ) + : ( + <> + + + + )} +
+ + ))} + + )}
) diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx index 8d0614d2e9..67c6ce7c45 100644 --- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx @@ -1,7 +1,7 @@ // @vitest-environment jsdom /** * QueueDock rendering and operations: authoritative rows, inline editing, - * removal, failure notices, and live retirement. + * collapse state, removal, failure notices, and live retirement. */ import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react' @@ -78,16 +78,40 @@ describe('QueueDock', () => { expect(container.innerHTML).toBe('') }) + it('renders one row directly and defaults multiple rows to a collapsible count header', () => { + const single = snapshotWith([row('i-1', 'one')]) + const source = liveSession(single) + const view = render() + expect(view.queryByRole('button', { name: '1 Queued' })).toBeNull() + expect(view.getByText('one')).toBeTruthy() + + act(() => { source.push(snapshotWith([row('i-1', 'one'), row('i-2', 'two')])) }) + const header = view.getByRole('button', { name: '2 Queued' }) + expect(header.getAttribute('aria-expanded')).toBe('false') + expect(view.queryByText('one')).toBeNull() + expect(view.queryByText('two')).toBeNull() + + fireEvent.click(header) + expect(header.getAttribute('aria-expanded')).toBe('true') + expect(view.getByText('one')).toBeTruthy() + expect(view.getByText('two')).toBeTruthy() + + fireEvent.click(header) + expect(header.getAttribute('aria-expanded')).toBe('false') + expect(view.queryByText('one')).toBeNull() + }) + it('renders active actions and disables editing for mixed-content rows', () => { const snap = snapshotWith([ row('i-1', '第一条排队消息'), row('i-2', null, 'image [image]'), ]) const source = liveSession(snap) - const { container } = render() + const { container, getByRole } = render() + fireEvent.click(getByRole('button', { name: '2 Queued' })) expect([...container.querySelectorAll('li')].map(item => item.textContent)) .toEqual(['第一条排队消息', 'image [image]']) - expect(container.querySelectorAll('button')).toHaveLength(4) + expect(container.querySelectorAll('button')).toHaveLength(5) expect(container.querySelectorAll('[aria-label="编辑排队消息"]')).toHaveLength(2) expect(container.querySelectorAll('[aria-label="删除排队消息"]')).toHaveLength(2) expect(container.querySelectorAll('[aria-label="立即发送排队消息"]')).toHaveLength(0) @@ -162,10 +186,11 @@ describe('QueueDock', () => { const snap = snapshotWith([row('i-1', 'one'), row('i-2', 'two')]) const source = liveSession(snap) const updateQueue = vi.fn(() => Promise.resolve()) - const { getAllByLabelText } = render( + const { getAllByLabelText, getByRole } = render( , ) + fireEvent.click(getByRole('button', { name: '2 Queued' })) fireEvent.click(getAllByLabelText('删除排队消息')[0]!) await waitFor(() => { expect(updateQueue).toHaveBeenCalledWith(iid('i-1'), { kind: 'remove' }) From 07e3d15d4250d0c42ccae9ebefda61a7518a26b4 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 17:07:29 +0800 Subject: [PATCH 32/67] docs(settings): mark deferred review follow-ups --- packages/settings/settings-local/src/index.ts | 4 ++++ packages/settings/settings/src/index.ts | 8 ++++++++ 2 files changed, 12 insertions(+) diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts index 04ba6808a3..d0d1497b16 100644 --- a/packages/settings/settings-local/src/index.ts +++ b/packages/settings/settings-local/src/index.ts @@ -214,6 +214,8 @@ export class SettingsLocal extends Settings { // carries owner-only permissions that survive the rename — a document that // may hold personal values is never world-readable and never a symlink. const temp = `${this.spec.filename}.${randomBytes(6).toString('hex')}.tmp` + // TODO(settings-atomic-durability): Use a replacement that fsyncs the file + // and parent directory and preserves owner-only permissions on Windows. try { await writeFile(temp, output, { mode: 0o600, flag: 'wx' }) await rename(temp, this.spec.filename) @@ -248,6 +250,8 @@ export class SettingsLocal extends Settings { // is free right now, so retry without burning backoff or deadline. if (ageMs === undefined) continue if (ageMs > LOCK_STALE_MS) { + // TODO(settings-lock-ownership): Replace age-only takeover with ownership-safe + // acquisition and release so a slow writer cannot remove a successor's lock. this.ctx.logger.warn('settings-local: breaking a stale writer lock at %s', lockPath) await rm(lockPath, { force: true }) continue diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts index 27decc7db5..76c1082f3f 100644 --- a/packages/settings/settings/src/index.ts +++ b/packages/settings/settings/src/index.ts @@ -43,6 +43,8 @@ export interface SettingsRegisterOptions { /** One registered namespace as surfaced to configuration UIs. */ export interface SettingsDescriptor { + // TODO(settings-namespace-vocabulary): Rename `ns` to `namespace` across the + // public seam, provider contract, implementations, tests, and consumers. /** The registered namespace. */ ns: SettingsNamespace /** Serialized schemastery schema (`schema.toJSON()`). */ @@ -181,6 +183,8 @@ function cloneJsonShaped( if (isPlainObject(value)) { if (visiting.has(value)) throw reject('a circular reference', path) visiting.add(value) + // TODO(settings-json-properties): Use property-safe construction here and + // in mergeLayers so valid JSON keys such as "__proto__" remain own data. const out: Record = {} for (const [key, entry] of Object.entries(value)) { if (entry === undefined) continue @@ -321,6 +325,8 @@ export abstract class Settings extends Service { } this.ctx.effect(() => { this.registrations.set(ns, registration) + // TODO(settings-registration-quiescence): Deactivate every watcher and await + // its tail on disposal so callbacks cannot outlive the registrant fiber. return () => this.registrations.delete(ns) }, `settings.register(${JSON.stringify(String(ns))})`) return { @@ -425,6 +431,8 @@ export abstract class Settings extends Service { // only when this registration is still the namespace owner — a fiber // disposed (or replaced) mid-persist must not receive the notification. this.document[ns] = section + // TODO(settings-replacement-resync): Re-resolve any replacement registration + // from this persisted section so an old in-flight write cannot leave it stale. if (this.registrations.get(ns) === registration && !this.isStopped()) { this.commit(registration, next, 'update') } From 101c3908f37c6a190329293c8b536b5f12d405e2 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 11:50:16 +0800 Subject: [PATCH 33/67] =?UTF-8?q?feat(directory-picker-browse):=20quiet=20?= =?UTF-8?q?navigation=20=E2=80=94=20one-frame=20landings=20and=20a=20slow-?= =?UTF-8?q?scan=20loading=20pill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Navigations keep the previous view rendering while scanning: target and parent legs land as one two-pane frame when the parent leg settles within a 200ms wait bound (past it the target lands alone and the late leg upgrades in place; Escape inside the landing window withdraws the navigation). The loading indicator floats over the content on the card background and appears only once a scan outlives a 300ms silence window, so navigation never shifts the columns or flashes an intermediate frame. The truncated note now describes the on-screen panes instead of hiding during scans. --- ...directory-picker-capability-seam.i18n.yaml | 4 +- ...-07-28-directory-picker-capability-seam.md | 2 +- ...-28-directory-picker-capability-seam.zh.md | 2 +- .../directory-picker-browse/README.i18n.yaml | 4 +- .../host/directory-picker-browse/README.md | 2 +- .../host/directory-picker-browse/README.zh.md | 2 +- .../src/client/DirectoryBrowser.module.css | 15 ++ .../src/client/DirectoryBrowser.tsx | 116 ++++++++++++---- .../tests/directory-browser.spec.tsx | 128 +++++++++++++++++- 9 files changed, 235 insertions(+), 40 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index 900e1d01b6..edc0afb4c5 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: ad2aa904beddb2fe941883c3c1827702dbec9964 -2026-07-28-directory-picker-capability-seam.zh.md: 30e719ad9b4e8374496106b447e961a042c7d8b6 +2026-07-28-directory-picker-capability-seam.md: cfe0de43294439fadca2d7bc40a8c175d2cda372 +2026-07-28-directory-picker-capability-seam.zh.md: 7e2e16aa24bb4430667bdc1a5c12dfd1bd3a2e4f diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index ad2aa904be..cfe0de4329 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -20,7 +20,7 @@ Placement and policy rulings folded into this decision: - **Dependency survey (hand-roll vs adopt).** Node's stdlib *is* the maintained cross-platform OS layer (`readdir(withFileTypes)`, `homedir`, path semantics); surveyed alternatives fail the dependency bar — file-manager packages (`node-file-manager`, `files-and-folders`, Syncfusion's provider) are whole HTTP apps (fit), drive-letter helpers (`drivelist` native addon, `windows-drive-letters` ~7y stale) fail health/proportionality. The browse backend is a thin adapter over stdlib. - **Hidden entries: return-and-flag.** The host stamps `hidden` (POSIX dot convention) and returns everything; the client filters. Display policy stays client-side, and the show-hidden toggle shipped as exactly that client-only change: a fixed-label footer toggle whose state lives in the pressed presentation (`aria-pressed` + check glyph), a dot-led path-draft prefix reveals the hidden entries it names, and the current selection is exempt from both the hidden and the prefix filter (it anchors the two-pane view). Windows' `FILE_ATTRIBUTE_HIDDEN` is not exposed by dirents — documented limitation until a native probe pays for itself. - **Path-editor cancel scope: the dialog card.** The browse client's path editor cancels on Escape and on focus leaving the card, both observed at a card-scope wrapper rather than the input — after Tab parks focus on a filtered row the input is off the event path, yet Escape must collapse the editor (not the dialog) and a later focus departure must still cancel. Non-cancel exemptions: window/tab focus loss, in-card focus moves, and pointer paths (rows and the toggle suppress focus steal on mousedown while editing). Separators for seeding and draft-tail filtering are inferred from `listing.home`; the wire-field alternative below records the deferred authoritative form. Combobox semantics between the editor and the list it filters (`aria-expanded`/`aria-controls`/active-descendant, result announcements) are likewise deferred — today they read to assistive tech as separate widgets. -- **Navigation lands selection-anchored, progressively.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the browse client's navigate commits the target level the moment it arrives — the editor closes and loading ends on that first settlement, so an Enter-submitted navigation is never withdrawn waiting on more — and a parent leg then upgrades the landing in place: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent; a failed parent leg, or a truncated parent window lacking the target, leaves the committed single-pane landing — the upgrade must never orphan the selection it exists to anchor. +- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content (never a layout-shifting row) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. - **Symlinks: follow for enterability.** `stat` probes symlinks (broken/cyclic → skipped); crumbs keep the logical path the operator navigated, and `workspace.create` already canonicalizes via realpath at adoption. - **Listing levels are bounded, and streamed.** One `list` call returns at most `maxEntries` rows (config, default 1000 — GitHub's web-UI directory-listing bound). The level streams via `opendir` into a name-sorted window of `maxEntries + 1` candidates, so memory stays O(maxEntries) and enterability probing touches only windowed candidates; the wire `DirectoryListing` carries a required `truncated` flag so the client states incompleteness instead of silently missing tail entries. A windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated. Window insertion is binary with an O(1) full-window tail rejection (an oversized level must not pay a window scan per dirent), and `list(path, signal)` threads the carrier's request signal so a scan of a stalled network directory cannot outlive a disconnected caller — every await in the scan (open, each read, each symlink probe) races the signal, an aborted exit abandons rather than awaits the close (Node queues close behind in-flight reads), and abandoned settlements are swallowed so cleanup can never surface as an unhandled rejection. An unbounded level is a memory/responsiveness hole for large or adversarial directories. - **Whole-filesystem scope, no roots config.** `workspace.create` accepts arbitrary paths and the API serves bash-driving methods, so a browse root would be UX scoping, not a boundary; configurability without a consumer fails the evidence bar. Deferred until a deployment needs it. diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 30e719ad9b..7e2e16aa24 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -20,7 +20,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick - **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。 - **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。 - **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。 -- **导航以选中项为锚、渐进落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），browse 客户端的导航在目标层级到达的那一刻即提交它——这次首个落定即关闭编辑器并结束加载，因此 Enter 提交的导航绝不会为等待更多内容而被撤回——随后父层级这一程就地升级这次落地：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止；父层级这一程失败，或被截断的父窗口缺少目标时，都保留已提交的单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。 +- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容之上（绝不是会挪动布局的一行），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。 - **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。 - **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。 diff --git a/packages/host/directory-picker-browse/README.i18n.yaml b/packages/host/directory-picker-browse/README.i18n.yaml index d807bd737a..673d053e3a 100644 --- a/packages/host/directory-picker-browse/README.i18n.yaml +++ b/packages/host/directory-picker-browse/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/directory-picker-browse/README.md -README.md: 23153881b84dcb71dfb05d4f297a5818c410ca77 -README.zh.md: d7010e2941a801ba6358082824330eaae46e42b7 +README.md: 52b5fe7e89f915be3b50324628e9d5c48f1ef94c +README.zh.md: 742da39470083887a71ddba4a7c8012f0ce0ea1f diff --git a/packages/host/directory-picker-browse/README.md b/packages/host/directory-picker-browse/README.md index 23153881b8..52b5fe7e89 100644 --- a/packages/host/directory-picker-browse/README.md +++ b/packages/host/directory-picker-browse/README.md @@ -6,7 +6,7 @@ The **in-app browsing backend** of the [directory-picker seam](../directory-pick Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Both primitives reject an explicit path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`) that `isAbsolute` accepts — with `directory-unreadable`/`directory-create-failed`, instead of letting `resolve` rebase it under the host process cwd or current drive. One `list` call returns at most `maxEntries` rows (config, default 1000 — the bound GitHub's web UI applies to directory listings), and the level streams through a bounded window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, counts hidden rows against the bound, probes only windowed candidates, and reports `truncated: true` so the client can say the level is incomplete (a windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated); window insertion is binary with an O(1) full-window tail rejection, and `list` threads the caller's `AbortSignal` so a disconnect or timeout stops the scan instead of letting it outlive the caller. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md). -**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored: a crumb jump or a submitted path commits the target immediately, then re-selects its actual entry in its parent level once that level arrives — two panes, so stepping back never collapses (a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). +**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored and quiet: the previous view keeps rendering while a crumb jump or a submitted path is scanned (a "Loading…" pill floats over it only once the scan outlives a 300ms silence window, never shifting the columns), then target and parent legs land as one two-pane frame with the target re-selected as its actual parent-level entry — so stepping back never collapses and no intermediate frame flashes (a parent leg outliving its 200ms wait bound lands the target alone and upgrades in place; a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind). ## Model Experience diff --git a/packages/host/directory-picker-browse/README.zh.md b/packages/host/directory-picker-browse/README.zh.md index d7010e2941..742da39470 100644 --- a/packages/host/directory-picker-browse/README.zh.md +++ b/packages/host/directory-picker-browse/README.zh.md @@ -6,7 +6,7 @@ 行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限），且层级以流式方式经过一个有界窗口，无论目录有多少子项内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`，供客户端提示层级不完整（窗口内的断链符号链接不会从窗口外回填——发生过驱逐本身已把层级标记为截断）；窗口插入为二分查找、满窗尾部单次比较即拒绝，且 `list` 透传调用方的 `AbortSignal`，断连或超时会停止扫描而不是让它在调用方离开后继续。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。 -**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚落地：crumb 跳转或提交的路径会立即提交目标，待父层级到达后再在其中重新选中目标的实际条目——双栏，因此后退绝不塌缩（父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 +**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚、安静落地：扫描 crumb 跳转或提交的路径期间，先前视图持续渲染（"Loading…" 胶囊仅在扫描超出 300ms 静默窗口后才浮于其上，绝不挪动各列），随后目标与父层级两程以单个双栏帧落地，目标被重新选中为其在父层级中的实际条目——因此后退绝不塌缩，也没有中间帧闪现（父层级这一程超出其 200ms 等待上限时，目标单独落地，随后就地升级；父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。 ## 模型体验 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index 85349962e5..bfa50aa987 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -146,11 +146,26 @@ flex-direction: column; flex: 1 1 0; min-height: 0; + /* Anchors the floating loading pill (.loadingFloat). */ + position: relative; /* Right inset is slimmer than the left: the trailing column's own 8px * scrollbar clearance makes up the optical difference. */ padding: 16px 16px 16px 24px; } +/* The slow-scan indicator floats over the content's bottom-left on the card + * background instead of occupying a row: a scan must never shift the + * columns' height, and the stale view keeps rendering beneath it (it only + * appears at all once a scan outlives SLOW_SCAN_DELAY_MS). */ +.loadingFloat { + position: absolute; + left: 24px; + bottom: 8px; + padding: 2px 8px; + border-radius: 6px; + background: var(--dsw-alias-bg-layer-2); +} + /* Columns split the row evenly around the divider (a solo column takes the * whole row); 256px is the floor below which the row scrolls (scrollbar * hidden, the effect pins the child pane into view) instead of squeezing diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 859667d115..0610dbb8a6 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -5,10 +5,12 @@ * breadcrumb, and a click-to-edit path zone; below it a Miller view — one * full-width level until a row is selected, then two columns splitting the * row evenly (256px floor; level | selected folder's children) around a - * hairline divider. Navigations land selection-anchored: a crumb jump or a - * submitted path commits the target immediately, then re-selects it in its - * parent level once that level arrives, so stepping back keeps two panes - * away from the display root. Selecting in the + * hairline divider. Navigations land selection-anchored and quiet: the + * previous view keeps rendering while a crumb jump or a submitted path is + * scanned, then target and parent legs land as one two-pane frame (a slow + * parent leg falls back to landing the target alone and upgrading in + * place), so stepping back keeps two panes away from the display root and + * navigation never flashes an intermediate frame. Selecting in the * right column shifts the view one level deeper. "New folder" opens a nested * create dialog targeting the selected folder (or the level itself) and * selects the created folder. Open adopts the selected folder, falling back @@ -55,6 +57,24 @@ function failureText(error: unknown): string { return error instanceof Error ? error.message : String(error) } +/** + * How long a scan may stay visually silent before the floating "Loading…" + * pill appears. The stale view keeps rendering while a scan is in flight, so + * a listing that settles inside this window swaps the panes with no + * intermediate frame at all; only a genuinely slow host (a network mount, a + * cold disk) surfaces the indicator. + */ +const SLOW_SCAN_DELAY_MS = 300 + +/** + * How long a navigation landing waits for its parent leg before committing + * the target alone. Inside the window both legs land as ONE two-pane frame — + * no single-pane flash between them; past it the target commits single-pane + * at once (an Enter-submitted navigation is never held hostage by a stalled + * parent) and the late parent leg upgrades the landing in place. + */ +const PARENT_LEG_WAIT_MS = 200 + /** * Breadcrumb rows for display: inside the home subtree the chain starts at a * localized Home crumb; outside it the full ancestry shows, the root labeled @@ -166,6 +186,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const [selected, setSelected] = useState(null) const [child, setChild] = useState(null) const [loading, setLoading] = useState(false) + // Derived from `loading` by the slow-scan effect below: true only once a + // scan has been in flight for SLOW_SCAN_DELAY_MS, so fast listings never + // render the indicator at all. + const [slowScan, setSlowScan] = useState(false) const [error, setError] = useState(null) // Path-edit state: null = breadcrumb mode; a string = the draft being typed. const [pathDraft, setPathDraft] = useState(null) @@ -228,17 +252,20 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }, [listDirectory]) /** - * Replace the whole view with a freshly navigated level. The target level - * commits the moment it arrives (single wide level: the editor closes and - * loading ends on this first settlement, so an Enter-submitted navigation - * is never withdrawn waiting on anything further). Away from the display - * root — the same collapse the crumb header renders, so crumbs and pane - * shape never disagree — a parent leg then upgrades the landing in place: - * the target's ACTUAL parent-level entry re-selected (left pane = parent, - * right pane = the target), so a crumb jump reads as stepping back one - * pane. A failed parent leg, or a truncated parent window that lacks the - * target, leaves the committed single-pane landing — the upgrade must - * never orphan the selection it exists to anchor. + * Replace the whole view with a freshly navigated level. Away from the + * display root — the same collapse the crumb header renders, so crumbs and + * pane shape never disagree — the landing is two-pane: the target's ACTUAL + * parent-level entry re-selected (left pane = parent, right pane = the + * target), so a crumb jump reads as stepping back one pane. Both legs land + * as one frame when the parent leg settles within + * {@link PARENT_LEG_WAIT_MS}; past that bound (or at the display root) the + * target commits alone — single wide level, the editor closes, loading + * ends — and a late parent leg still upgrades the landing in place. A + * failed parent leg, or a truncated parent window that lacks the target, + * leaves the single-pane landing — the upgrade must never orphan the + * selection it exists to anchor. Until whichever commit comes first, the + * previous view keeps rendering: navigation swaps the panes, it never + * blanks them. */ const navigate = useCallback((path?: string) => { const { seq, scan } = launchListing(path) @@ -246,16 +273,23 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, setError(null) scan.then((target) => { if (seq !== requestSeq.current) return - setParent(target) - setSelected(null) - setChild(null) - setLoading(false) - setPathDraft(null) + // The single-pane landing; `landed` makes it first-commit-only, while + // the two-pane commit below may still upgrade an already-landed view. + let landed = false + const landSingle = (): void => { + if (landed || seq !== requestSeq.current) return + landed = true + setParent(target) + setSelected(null) + setChild(null) + setLoading(false) + setPathDraft(null) + } // Arity is label-independent: only the collapsed chain's depth decides. - if (displayCrumbs(target, '').length < 2) return + if (displayCrumbs(target, '').length < 2) { landSingle(); return } const parentCrumb = target.crumbs.at(-2) /* v8 ignore next -- narrowing: a two-deep display chain implies a parent crumb (root-to-target inclusive). */ - if (parentCrumb === undefined) return + if (parentCrumb === undefined) { landSingle(); return } continueScan(parentCrumb.path).then((parentLevel) => { if (seq !== requestSeq.current) return // Windows resolves a typed path preserving its case; anchor on the @@ -263,15 +297,23 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const sep = separatorOf(parentLevel) const fold = (value: string): string => (sep === '\\' ? value.toLowerCase() : value) const match = parentLevel.entries.find(entry => fold(entry.path) === fold(target.path)) - if (match === undefined) return + if (match === undefined) { landSingle(); return } + landed = true setParent(parentLevel) setSelected(match) setChild(target) + // Idempotent on a late upgrade of a timed-out landing: reopening the + // editor or starting a newer scan supersedes this seq, so reaching + // here means the draft is closed and the loading flag is this + // navigation's own. + setLoading(false) + setPathDraft(null) }, () => { - // Swallows the parent-leg failure (its abort included): the - // committed single-pane landing stands, and nobody asked to see - // the parent level. + // The parent-leg failure (its abort included) never surfaces: the + // target listed fine, and nobody asked to see the parent level. + landSingle() }) + window.setTimeout(landSingle, PARENT_LEG_WAIT_MS) }, (reason: unknown) => { if (seq !== requestSeq.current) return setLoading(false) @@ -415,6 +457,18 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }) } + // The slow-scan gate for the loading indicator: arm a timer when a scan + // starts, retire it (and the indicator) the moment loading ends. A settle + // inside the window means the swap happened with nothing shown. + useEffect(() => { + if (!loading) { + setSlowScan(false) + return + } + const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS) + return () => { window.clearTimeout(timer) } + }, [loading]) + // After the hooks: a closed dialog renders nothing and evaluates no copy. const crumbSource = child ?? parent const crumbs = crumbSource === null ? [] : displayCrumbs(crumbSource, t('browser.home')) @@ -649,11 +703,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, /> )} - {loading &&
{t('browser.loading')}
} + {loading && slowScan + &&
{t('browser.loading')}
} {/* The backend bounds a level at its complete-result limit; say so * whenever a visible pane was cut instead of letting the tail of a - * huge directory go silently missing. */} - {(parent?.truncated === true || child?.truncated === true) && !loading + * huge directory go silently missing. The note describes the panes + * on screen, so an in-flight scan leaves it alone — hiding it while + * the stale view still shows the cut level would shift the columns + * on every navigation away from it. */} + {(parent?.truncated === true || child?.truncated === true) &&
{t('browser.truncated')}
} {error !== null &&
{error}
} diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 6fa9bb999f..2528af4b46 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -235,7 +235,7 @@ describe('DirectoryBrowser', () => { expect(columns()).toHaveLength(1) }) - it('commits the target immediately, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { + it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { const signals: (AbortSignal | undefined)[] = [] const settlers: ((value: DirectoryListing) => void)[] = [] // Only the FIRST explicit HOME request (the parent leg) hangs; the later @@ -253,8 +253,8 @@ describe('DirectoryBrowser', () => { fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // The target leg commits at once: editor closed, single-pane DOCS level, - // while the parent leg (upgrade) is still in flight. + // The parent leg (upgrade) hangs past the landing wait bound: the target + // commits alone — editor closed, single-pane DOCS level. await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') }) expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() expect(columns()).toHaveLength(1) @@ -270,6 +270,128 @@ describe('DirectoryBrowser', () => { expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() }) + /** + * Listing fake whose explicit-path scans stay pending until the test + * settles them by path; the absent-path form (the initial home listing) + * resolves normally so mounting is a one-flush setup. + */ + function manualLister() { + const settlers = new Map void>() + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve(listingFor(path)) + return new Promise((resolve) => { settlers.set(path, resolve) }) + }) + return { settlers, listDirectory } + } + + it('lands a navigation as ONE two-pane frame: the stale view holds until both legs arrive', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target settles while the parent leg is still in flight: nothing + // commits yet — the editor stays open over the stale home level, and no + // single-pane DOCS frame ever renders. + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy() + expect(screen.queryByText('harness')).toBeNull() + // The parent leg settles inside the wait bound: one commit straight to + // the two-pane landing, editor closed. + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(columns()).toHaveLength(2) + expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true') + expect(within(columns()[0]!).getByText('Documents')).toBeTruthy() + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + // The wait-bound timer firing after the landing is a no-op. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(2) + } finally { + vi.useRealTimers() + } + }) + + it('a stalled parent leg lands the target alone at the wait bound, then upgrades in place', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // The parent leg outlives PARENT_LEG_WAIT_MS: the target lands alone. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(1) + expect(screen.getByRole('listitem').textContent).toBe('harness') + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + // The late parent leg still upgrades the landing in place, exactly as + // if it had made the bound. (Reopening the editor meanwhile would + // supersede the upgrade — the editor-open handler withdraws pending + // listings — so a late upgrade can never close a resumed draft.) + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(columns()).toHaveLength(2) + expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true') + expect(within(columns()[1]!).getByText('harness')).toBeTruthy() + } finally { + vi.useRealTimers() + } + }) + + it('Escape inside the landing window withdraws the submitted navigation', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + const input = screen.getByLabelText('browser.editPath') + fireEvent.change(input, { target: { value: DOCS } }) + fireEvent.keyDown(input, { key: 'Enter' }) + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // Nothing has committed yet; Escape supersedes the landing entirely. + fireEvent.keyDown(input, { key: 'Escape' }) + await act(async () => { vi.advanceTimersByTime(200) }) + expect(columns()).toHaveLength(1) + expect(screen.queryByText('harness')).toBeNull() + expect(within(columns()[0]!).getByText('Documents')).toBeTruthy() + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + } finally { + vi.useRealTimers() + } + }) + + it('shows the loading indicator only once a scan outlives its silence window, floating over the stale view', async () => { + vi.useFakeTimers() + try { + const { settlers, listDirectory } = manualLister() + mount({ listDirectory }) + await act(async () => {}) + expect(screen.queryByText('browser.loading')).toBeNull() + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // In flight but still inside the silence window: nothing shows. + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(300) }) + // Past it: the indicator floats while the stale level keeps rendering. + expect(screen.getByRole('status').textContent).toBe('browser.loading') + expect(screen.getByText('Documents')).toBeTruthy() + // Landing (both legs) retires the indicator with the scan. + await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) + expect(screen.queryByText('browser.loading')).toBeNull() + expect(columns()).toHaveLength(2) + } finally { + vi.useRealTimers() + } + }) + it('keeps the single-pane landing when the truncated parent level lacks the target', async () => { const listDirectory = vi.fn(async (path?: string) => { // The parent leg names HOME explicitly; serve it a truncated window From 7895754ae93765fa41b1c3ef4a8111d64abce3dd Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 12:09:45 +0800 Subject: [PATCH 34/67] fix(directory-picker-browse): rebind the scrollbar elevation pair on the browser card The loading pill's layer-2 background made the sheet an elevated-surface painter, and the ui-theme scrollbar invariant rightly flagged what was already latent: the dialog's columns scroll on an l2 card while the thumbs rendered in the base-surface pair. Rebind the indirection on the card rule so it inherits to the scrolling columns. --- .../src/client/DirectoryBrowser.module.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index bfa50aa987..d440b94862 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -13,6 +13,12 @@ height: min(500px, calc(100dvh - 32px)); padding: 0; gap: 0; + /* The Modal card is an l2 surface and the columns below scroll on it: + * rebind the scrollbar indirection to the elevation pair here, on the + * surface, so it inherits down to whichever descendant scrolls (the + * rebinding contract in ui-theme styles/scrollbar.css). */ + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); } /* Card-scope wrapper hosting the path editor's Escape and focus-leave From 3d26b8a6960abf8572faf99d17521ac82777fd4b Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 12:53:07 +0800 Subject: [PATCH 35/67] =?UTF-8?q?fix(directory-picker-browse):=20bot=20rou?= =?UTF-8?q?nd=201=20=E2=80=94=20pill=20cascade+corner,=20slow-scan=20close?= =?UTF-8?q?=20reset,=20asymmetry+calibration=20recorded?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .loadingFloat moved after the .status/.error block (its padding was losing the same-specificity race) and re-anchored bottom-right: the truncated/error rows own the bottom left and keep rendering through a scan, so the pill can never cover them; confirmCreate's relist now clears the stale failure text like every other scan launch. - The close edge resets loading, so the slow-scan effect disarms while hidden and a reopened dialog waits out a fresh silence window (regression test added). - The truncated note's survival through a scan is now asserted in the slow-scan test; the wait-bound test moved to fake timers with the 200ms bound explicit. - select()'s exemption from the one-frame rule and the constants' local calibration premise are recorded in JSDoc and the capability-seam Agent Note; the themed-scrollbars note's rebinding enumeration is replaced by a pointer to the mechanical gate (it had drifted twice). Both pairs re-recorded. --- ...directory-picker-capability-seam.i18n.yaml | 4 +- ...-07-28-directory-picker-capability-seam.md | 2 +- ...-28-directory-picker-capability-seam.zh.md | 2 +- ...d-scrollbars-and-reserved-gutter.i18n.yaml | 4 +- ...8-themed-scrollbars-and-reserved-gutter.md | 2 +- ...hemed-scrollbars-and-reserved-gutter.zh.md | 2 +- .../src/client/DirectoryBrowser.module.css | 30 +++-- .../src/client/DirectoryBrowser.tsx | 19 ++- .../tests/directory-browser.spec.tsx | 127 +++++++++++++----- 9 files changed, 133 insertions(+), 59 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml index edc0afb4c5..5b33f27a5c 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md -2026-07-28-directory-picker-capability-seam.md: cfe0de43294439fadca2d7bc40a8c175d2cda372 -2026-07-28-directory-picker-capability-seam.zh.md: 7e2e16aa24bb4430667bdc1a5c12dfd1bd3a2e4f +2026-07-28-directory-picker-capability-seam.md: 892bb4b2c4fe200df91866c4ec4cf8bb7c58e940 +2026-07-28-directory-picker-capability-seam.zh.md: d738773adc853dae7b3496f0dc2901eebd0f0a08 diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md index cfe0de4329..892bb4b2c4 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md @@ -20,7 +20,7 @@ Placement and policy rulings folded into this decision: - **Dependency survey (hand-roll vs adopt).** Node's stdlib *is* the maintained cross-platform OS layer (`readdir(withFileTypes)`, `homedir`, path semantics); surveyed alternatives fail the dependency bar — file-manager packages (`node-file-manager`, `files-and-folders`, Syncfusion's provider) are whole HTTP apps (fit), drive-letter helpers (`drivelist` native addon, `windows-drive-letters` ~7y stale) fail health/proportionality. The browse backend is a thin adapter over stdlib. - **Hidden entries: return-and-flag.** The host stamps `hidden` (POSIX dot convention) and returns everything; the client filters. Display policy stays client-side, and the show-hidden toggle shipped as exactly that client-only change: a fixed-label footer toggle whose state lives in the pressed presentation (`aria-pressed` + check glyph), a dot-led path-draft prefix reveals the hidden entries it names, and the current selection is exempt from both the hidden and the prefix filter (it anchors the two-pane view). Windows' `FILE_ATTRIBUTE_HIDDEN` is not exposed by dirents — documented limitation until a native probe pays for itself. - **Path-editor cancel scope: the dialog card.** The browse client's path editor cancels on Escape and on focus leaving the card, both observed at a card-scope wrapper rather than the input — after Tab parks focus on a filtered row the input is off the event path, yet Escape must collapse the editor (not the dialog) and a later focus departure must still cancel. Non-cancel exemptions: window/tab focus loss, in-card focus moves, and pointer paths (rows and the toggle suppress focus steal on mousedown while editing). Separators for seeding and draft-tail filtering are inferred from `listing.home`; the wire-field alternative below records the deferred authoritative form. Combobox semantics between the editor and the list it filters (`aria-expanded`/`aria-controls`/active-descendant, result announcements) are likewise deferred — today they read to assistive tech as separate widgets. -- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content (never a layout-shifting row) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. +- **Navigation lands selection-anchored, quiet, and bounded.** Away from the display root (the same collapse the crumb header renders, so crumbs and pane shape never disagree), the landing is two-pane: the target's actual parent-level entry re-selected (platform case folding on Windows), its children on the right, so a crumb jump reads as stepping back one pane rather than collapsing to a single column. Target and parent legs land as **one frame** when the parent leg settles within the 200ms wait bound — the stale view keeps rendering until then, so navigation swaps the panes without an intermediate single-pane flash — and past the bound the target commits alone at once (an Enter-submitted navigation is never held hostage by a stalled parent) with the late parent leg upgrading the landing in place. The parent leg runs under the landing's supersession scope and is aborted on the wire by any newer intent (Escape inside the landing window therefore withdraws the whole navigation); a failed parent leg, or a truncated parent window lacking the target, leaves the single-pane landing — the upgrade must never orphan the selection it exists to anchor. The loading indicator follows the same quiet rule: it floats over the content's bottom-right corner (never a layout-shifting row; the truncated/error rows own the bottom left and keep rendering through a scan) and only once a scan outlives a 300ms silence window, so a local listing swaps with nothing shown at all. Row picks are deliberately exempt from the one-frame rule: a pick's immediate pane split is its selected-state feedback (aria-current, crumbs following), while a navigation has nothing to acknowledge the click but the swap itself. Both timing constants are calibrated for local enumeration; a remote deployment (one RPC per level, commonly 100–400ms) would sit inside the silence window with no pressed state on the crumbs — revisit the window or add pressed feedback when a remote consumer lands. - **Symlinks: follow for enterability.** `stat` probes symlinks (broken/cyclic → skipped); crumbs keep the logical path the operator navigated, and `workspace.create` already canonicalizes via realpath at adoption. - **Listing levels are bounded, and streamed.** One `list` call returns at most `maxEntries` rows (config, default 1000 — GitHub's web-UI directory-listing bound). The level streams via `opendir` into a name-sorted window of `maxEntries + 1` candidates, so memory stays O(maxEntries) and enterability probing touches only windowed candidates; the wire `DirectoryListing` carries a required `truncated` flag so the client states incompleteness instead of silently missing tail entries. A windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated. Window insertion is binary with an O(1) full-window tail rejection (an oversized level must not pay a window scan per dirent), and `list(path, signal)` threads the carrier's request signal so a scan of a stalled network directory cannot outlive a disconnected caller — every await in the scan (open, each read, each symlink probe) races the signal, an aborted exit abandons rather than awaits the close (Node queues close behind in-flight reads), and abandoned settlements are swallowed so cleanup can never surface as an unhandled rejection. An unbounded level is a memory/responsiveness hole for large or adversarial directories. - **Whole-filesystem scope, no roots config.** `workspace.create` accepts arbitrary paths and the API serves bash-driving methods, so a browse root would be UX scoping, not a boundary; configurability without a consumer fails the evidence bar. Deferred until a deployment needs it. diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md index 7e2e16aa24..d738773adc 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md @@ -20,7 +20,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick - **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。 - **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。 - **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。 -- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容之上（绝不是会挪动布局的一行），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。 +- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。两个时序常量都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态——待远程消费方落地时，重新审视该窗口或补上按下反馈。 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。 - **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。 - **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml index a205f48f54..8099344ace 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md -2026-07-28-themed-scrollbars-and-reserved-gutter.md: 38228c868bb00210118e8110feb722fb81d0d56c -2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 9fafe1faa9303b5e2e23a1b3064904f71494026d +2026-07-28-themed-scrollbars-and-reserved-gutter.md: 76dcb6d9f3976faf3338a89f3ccab7182fe6d5ab +2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: ff12c6884bec706dbbd9974684010cbcd9fa03bf diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md index 38228c868b..76dcb6d9f3 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md @@ -20,7 +20,7 @@ The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-a The two renderings are mutually exclusive, and the exclusion is enforced rather than assumed. A non-`auto` `scrollbar-width` or `scrollbar-color` makes Chromium and Safari discard every `::-webkit-scrollbar*` rule for that element, `::-webkit-scrollbar-thumb:hover` included. Declaring both unconditionally therefore leaves the hover token rendering nowhere at all: the engines that implement the hover pseudo-element are exactly the ones the standard properties silence, and Firefox has no hover pseudo-element to fall back on. The standard properties consequently sit inside `@supports not selector(::-webkit-scrollbar)`, which is true only where the pseudo-element is unimplemented, so Firefox takes the standard path and WebKit-based engines take the pseudo-element path. The WebKit rules are not gated in turn: an engine without those pseudo-elements drops them as unknown selectors, so a gate would only restate what selector matching already does. An engine too old for the `selector()` function makes the condition invalid, which evaluates false and selects the pseudo-element path — the correct side for the pre-16.4 Safari that is the realistic case for that reading. -Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. Eight surfaces rebind today: the command popup, the slash menu, the model-select panel, the settings panel, the shared `ui-primitives` menu card, the composer input card, the question composer card, and the todo panel. Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. +Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The set of rebinding surfaces is owned by the mechanical gate (`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`): any sheet that scrolls and paints an elevated surface must rebind, so this note no longer enumerates them (an enumeration here drifted twice). Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. The last four were missed in the first implementation and found in review, which is why the rebinding contract is now checked mechanically rather than by inspection: a sheet that scrolls somewhere and paints an elevated surface somewhere must rebind. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md index 9fafe1faa9..ff12c6884b 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md @@ -20,7 +20,7 @@ Status: implemented 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。 -两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。目前有八处抬升表面做了重新绑定：命令浮层、斜杠菜单、模型选择面板、设置面板、`ui-primitives` 共用菜单卡片、输入条卡片、提问组件卡片与待办面板。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 +两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。重新绑定表面的集合归机械门禁（`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`）所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再枚举它们（这里的枚举已经漂移过两次）。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 后四处在最初的实现里被漏掉、由评审发现，因此重新绑定契约现在由机械检查把关，而不再依赖人工审阅：一张样式表只要在某处滚动、又在某处绘制抬升表面，就必须重新绑定。 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index d440b94862..594f450756 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -159,19 +159,6 @@ padding: 16px 16px 16px 24px; } -/* The slow-scan indicator floats over the content's bottom-left on the card - * background instead of occupying a row: a scan must never shift the - * columns' height, and the stale view keeps rendering beneath it (it only - * appears at all once a scan outlives SLOW_SCAN_DELAY_MS). */ -.loadingFloat { - position: absolute; - left: 24px; - bottom: 8px; - padding: 2px 8px; - border-radius: 6px; - background: var(--dsw-alias-bg-layer-2); -} - /* Columns split the row evenly around the divider (a solo column takes the * whole row); 256px is the floor below which the row scrolls (scrollbar * hidden, the effect pins the child pane into view) instead of squeezing @@ -267,6 +254,23 @@ color: var(--dsw-alias-state-error-primary); } +/* The slow-scan indicator floats over the content's bottom-RIGHT corner on + * the card background instead of occupying a row: a scan must never shift + * the columns' height, and the stale view keeps rendering beneath it (it + * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right, + * not left: the truncated/error status rows flow at the bottom LEFT and + * stay on screen through a scan, so the opposite corner keeps both + * legible. After .status in the cascade — the element carries both + * classes and this padding must win the same-specificity race. */ +.loadingFloat { + position: absolute; + right: 16px; + bottom: 8px; + padding: 2px 8px; + border-radius: 6px; + background: var(--dsw-alias-bg-layer-2); +} + /* Footer: l3 separator on top, symmetric padding so the row sits vertically * centered in the bar; New-folder and the show-hidden toggle pin left. */ .footerBar { diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 0610dbb8a6..023404f71d 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -331,7 +331,15 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const pathInputRef = useRef(null) const editZoneRef = useRef(null) - /** Select a row of the listed level and preview its children on the right. */ + /** + * Select a row of the listed level and preview its children on the right. + * Deliberately NOT one-frame like navigate(): a pick's first duty is the + * immediate selected state on the clicked row, and the pane split IS that + * feedback (aria-current pill, crumbs following the selection) — holding + * it back for the child listing would make clicks feel dropped. The quiet + * rule governs whole-view replacement, where nothing acknowledges the + * click but the swap itself. + */ const select = useCallback((entry: DirectoryEntry) => { const { seq, scan } = launchListing(entry.path) // A pick while the path editor is open adopts the (filtered) row and @@ -402,6 +410,11 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, return } supersede() + // Closing mid-scan leaves nothing to load: without this edge the + // slow-scan effect keeps arming while hidden and the reopened dialog + // would show the indicator on its first frame instead of waiting out a + // fresh silence window (reopen's navigate() produces no loading edge). + setLoading(false) setError(null) setPathDraft(null) setFolderDraft(null) @@ -438,6 +451,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, // create target becomes the listed level and the new folder its selection. const { seq, scan } = launchListing(targetPath) setLoading(true) + // Symmetric with navigate/select: a launched scan clears the stale + // failure text (and keeps the floating indicator's corner the only + // occupant of the content's right edge while it shows). + setError(null) scan.then((level) => { /* v8 ignore next -- same fence as navigate/select; the modal blocks superseding input */ if (seq !== requestSeq.current) return diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 2528af4b46..0fe1f91e00 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -236,38 +236,49 @@ describe('DirectoryBrowser', () => { }) it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => { - const signals: (AbortSignal | undefined)[] = [] - const settlers: ((value: DirectoryListing) => void)[] = [] - // Only the FIRST explicit HOME request (the parent leg) hangs; the later - // home crumb jump lists normally. - let homeCalls = 0 - const listDirectory = vi.fn(async (path?: string, signal?: AbortSignal) => { - signals.push(signal) - if (path === HOME && ++homeCalls === 1) { - return new Promise((resolve) => { settlers.push(resolve) }) - } - return listingFor(path) - }) - mount({ listDirectory }) - await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) - fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) - fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) - fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // The parent leg (upgrade) hangs past the landing wait bound: the target - // commits alone — editor closed, single-pane DOCS level. - await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') }) - expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() - expect(columns()).toHaveLength(1) - await waitFor(() => { expect(settlers).toHaveLength(1) }) - // A newer jump aborts the pending parent leg ON THE WIRE, not merely - // dropping its settlement. - fireEvent.click(screen.getByRole('button', { name: 'browser.home' })) - expect(signals[2]?.aborted).toBe(true) - await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('Documents') }) - // Its late resolution changes nothing either. - await act(async () => { settlers[0]!(listingFor(HOME)) }) - expect(columns()).toHaveLength(1) - expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() + vi.useFakeTimers() + try { + const signals: (AbortSignal | undefined)[] = [] + const settlers: ((value: DirectoryListing) => void)[] = [] + // Only the FIRST explicit HOME request (the parent leg) hangs; the + // later home crumb jump lists normally. + let homeCalls = 0 + const listDirectory = vi.fn((path?: string, signal?: AbortSignal) => { + signals.push(signal) + if (path === HOME && ++homeCalls === 1) { + return new Promise((resolve) => { settlers.push(resolve) }) + } + return Promise.resolve(listingFor(path)) + }) + mount({ listDirectory }) + await act(async () => {}) + fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) + fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) + fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target settled but the parent leg hangs: inside the wait bound + // nothing commits yet. + await act(async () => {}) + expect(settlers).toHaveLength(1) + expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy() + // The wait bound expires: the target commits alone — editor closed, + // single-pane DOCS level. + await act(async () => { vi.advanceTimersByTime(200) }) + expect(screen.getByRole('listitem').textContent).toBe('harness') + expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() + expect(columns()).toHaveLength(1) + // A newer jump aborts the pending parent leg ON THE WIRE, not merely + // dropping its settlement. + fireEvent.click(screen.getByRole('button', { name: 'browser.home' })) + expect(signals[2]?.aborted).toBe(true) + await act(async () => {}) + expect(screen.getByRole('listitem').textContent).toBe('Documents') + // Its late resolution changes nothing either. + await act(async () => { settlers[0]!(listingFor(HOME)) }) + expect(columns()).toHaveLength(1) + expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull() + } finally { + vi.useRealTimers() + } }) /** @@ -369,29 +380,71 @@ describe('DirectoryBrowser', () => { it('shows the loading indicator only once a scan outlives its silence window, floating over the stale view', async () => { vi.useFakeTimers() try { - const { settlers, listDirectory } = manualLister() + // The home level is truncated so its note is on screen when the slow + // scan starts: dropping the note's old !loading guard means it must + // keep rendering through the scan, coexisting with the indicator. + const settlers = new Map void>() + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve({ ...listingFor(path), truncated: true }) + return new Promise((resolve) => { settlers.set(path, resolve) }) + }) mount({ listDirectory }) await act(async () => {}) expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('browser.truncated')).toBeTruthy() fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) - // In flight but still inside the silence window: nothing shows. + // In flight but still inside the silence window: no indicator, and the + // stale level's truncated note stays put (no layout churn on launch). expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('browser.truncated')).toBeTruthy() await act(async () => { vi.advanceTimersByTime(300) }) - // Past it: the indicator floats while the stale level keeps rendering. - expect(screen.getByRole('status').textContent).toBe('browser.loading') + // Past it: the indicator floats while the stale level — truncated note + // included — keeps rendering beneath it. + expect(screen.getByText('browser.loading')).toBeTruthy() + expect(screen.getByText('browser.truncated')).toBeTruthy() expect(screen.getByText('Documents')).toBeTruthy() - // Landing (both legs) retires the indicator with the scan. + // Landing (both legs) retires the indicator with the scan, and the + // fresh listings' own truncated state replaces the stale note. await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) await act(async () => { settlers.get(HOME)!(listingFor(HOME)) }) expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.queryByText('browser.truncated')).toBeNull() expect(columns()).toHaveLength(2) } finally { vi.useRealTimers() } }) + it('a close mid-scan resets the slow-scan gate: reopening waits a fresh silence window', async () => { + vi.useFakeTimers() + try { + // Every home listing hangs: the initial open's scan is the one the + // close interrupts, and the reopen's scan proves the fresh window. + const settlers: ((value: DirectoryListing) => void)[] = [] + const listDirectory = vi.fn((_path?: string, _signal?: AbortSignal) => + new Promise((resolve) => { settlers.push(resolve) })) + const { view, props } = mount({ listDirectory }) + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // Close while the scan is in flight, then reopen: the first frame must + // wait out a fresh silence window, not inherit the armed indicator. + view.rerender() + view.rerender() + await act(async () => {}) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // The reopened scan settles normally. + await act(async () => { settlers.at(-1)!(listingFor(undefined)) }) + expect(screen.queryByText('browser.loading')).toBeNull() + expect(screen.getByText('Documents')).toBeTruthy() + } finally { + vi.useRealTimers() + } + }) + it('keeps the single-pane landing when the truncated parent level lacks the target', async () => { const listDirectory = vi.fn(async (path?: string) => { // The parent leg names HOME explicitly; serve it a truncated window From e080ff2c345aefd779b0a18ea4f95f9a1d37811a Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 15:22:28 +0800 Subject: [PATCH 36/67] fix(directory-picker-browse): resolve quiet-navigation review --- ...d-scrollbars-and-reserved-gutter.i18n.yaml | 4 +- ...8-themed-scrollbars-and-reserved-gutter.md | 6 +-- ...hemed-scrollbars-and-reserved-gutter.zh.md | 6 +-- .../src/client/DirectoryBrowser.module.css | 12 ++++-- .../src/client/DirectoryBrowser.tsx | 31 +++++++++---- .../tests/directory-browser.spec.tsx | 43 ++++++++++++++++++- 6 files changed, 80 insertions(+), 22 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml index 8099344ace..45e957b824 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md -2026-07-28-themed-scrollbars-and-reserved-gutter.md: 76dcb6d9f3976faf3338a89f3ccab7182fe6d5ab -2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: ff12c6884bec706dbbd9974684010cbcd9fa03bf +2026-07-28-themed-scrollbars-and-reserved-gutter.md: b45f70b126d083916c756afb88a8b646a4e9bb85 +2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 8afa36429ce7e6e061b014d63dcb20e5a642a84c diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md index 76dcb6d9f3..b45f70b126 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md @@ -20,13 +20,13 @@ The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-a The two renderings are mutually exclusive, and the exclusion is enforced rather than assumed. A non-`auto` `scrollbar-width` or `scrollbar-color` makes Chromium and Safari discard every `::-webkit-scrollbar*` rule for that element, `::-webkit-scrollbar-thumb:hover` included. Declaring both unconditionally therefore leaves the hover token rendering nowhere at all: the engines that implement the hover pseudo-element are exactly the ones the standard properties silence, and Firefox has no hover pseudo-element to fall back on. The standard properties consequently sit inside `@supports not selector(::-webkit-scrollbar)`, which is true only where the pseudo-element is unimplemented, so Firefox takes the standard path and WebKit-based engines take the pseudo-element path. The WebKit rules are not gated in turn: an engine without those pseudo-elements drops them as unknown selectors, so a gate would only restate what selector matching already does. An engine too old for the `selector()` function makes the condition invalid, which evaluates false and selects the pseudo-element path — the correct side for the pre-16.4 Safari that is the realistic case for that reading. -Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The set of rebinding surfaces is owned by the mechanical gate (`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`): any sheet that scrolls and paints an elevated surface must rebind, so this note no longer enumerates them (an enumeration here drifted twice). Most declare it on the elevated card rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls. +Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls. -The last four were missed in the first implementation and found in review, which is why the rebinding contract is now checked mechanically rather than by inspection: a sheet that scrolls somewhere and paints an elevated surface somewhere must rebind. +Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were missed in the first implementation and found in review, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection. The elevated set is resolved from the palette's own dark elevation ladder — the surface tokens whose dark value lands on `bg-layer-2` or `bg-layer-3`, which is the step the l1/l2 split encodes. Deriving it instead from the sheets that already rebind was the first attempt and is unsound: such a set can only confirm what someone already remembered, and a surface nobody has rebound yet — exactly the case the check exists for — defines itself as unelevated. `--dsw-specific-tip` proved it, resolving to the menu surface's rung while the todo panel scrolled on it unrebound and the derived check stayed green. -Scope is by token family, not by geometry: only `--dsw-alias-bg-*` and `--dsw-specific-*` name a surface. `--dsw-alias-button-*`, `--dsw-alias-interactive-*`, and `--dsw-alias-markdown-*` reach the same rungs while naming a control or an inline span that no scroll container renders its bar against. Shape cannot make that call, since a floating button legitimately carries a radius, a shadow, and a fixed size. The check is per sheet rather than per rule because the card and the descendant that scrolls are separate rules, and CSS text does not express which contains which. +Scope is by token family, not by geometry: only `--dsw-alias-bg-*` and `--dsw-specific-*` name a surface. `--dsw-alias-button-*`, `--dsw-alias-interactive-*`, and `--dsw-alias-markdown-*` reach the same rungs while naming a control or an inline span that no scroll container renders its bar against. Shape cannot make that call, since a floating button legitimately carries a radius, a shadow, and a fixed size. The check is per sheet rather than per rule because the card and the descendant that scrolls are separate rules. That approximation cannot detect a scrolling component embedded in an elevated card painted by another package's stylesheet, as `DirectoryBrowser` inside `Modal` demonstrated; cross-sheet composition remains a review and assembled-UI responsibility. The track and the corner stay transparent, so the thumb reads against whatever surface scrolls under it; only the thumb and its hover state carry a token color. diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md index ff12c6884b..8afa36429c 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md @@ -20,13 +20,13 @@ Status: implemented 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。 -两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。重新绑定表面的集合归机械门禁（`packages/client/ui-theme/tests/scrollbar-styles.spec.ts`）所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再枚举它们（这里的枚举已经漂移过两次）。多数把声明写在抬升卡片上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。 +两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。 -后四处在最初的实现里被漏掉、由评审发现，因此重新绑定契约现在由机械检查把关，而不再依赖人工审阅：一张样式表只要在某处滚动、又在某处绘制抬升表面，就必须重新绑定。 +`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。 -判定范围依据 token 家族而非几何形状：只有 `--dsw-alias-bg-*` 与 `--dsw-specific-*` 表述的是表面。`--dsw-alias-button-*`、`--dsw-alias-interactive-*` 与 `--dsw-alias-markdown-*` 会落到相同档位，但它们表述的是控件或行内片段，没有任何滚动容器会把滚动条画在它们之上。形状无法做这个判断，因为悬浮按钮本来就会带圆角、阴影和固定尺寸。这项检查以样式表为粒度而非以规则为粒度，因为卡片与真正滚动的后代元素是两条不同的规则，而 CSS 文本无法表达谁包含谁。 +判定范围依据 token 家族而非几何形状：只有 `--dsw-alias-bg-*` 与 `--dsw-specific-*` 表述的是表面。`--dsw-alias-button-*`、`--dsw-alias-interactive-*` 与 `--dsw-alias-markdown-*` 会落到相同档位，但它们表述的是控件或行内片段，没有任何滚动容器会把滚动条画在它们之上。形状无法做这个判断，因为悬浮按钮本来就会带圆角、阴影和固定尺寸。这项检查以样式表为粒度而非以规则为粒度，因为卡片与真正滚动的后代元素是两条不同的规则。这种近似检查无法检测嵌在由另一个包的样式表绘制的抬升卡片中的滚动组件，`Modal` 内的 `DirectoryBrowser` 就证明了这一点；跨样式表的组合仍需在评审和组装后 UI 层面把关。 轨道与两条滚动条相交的角落保持透明，因此滑块是以其下滚动的任何表面为背景被看到；只有滑块及其 hover 状态带 token 颜色。 diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css index 594f450756..2f207e4195 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css @@ -242,6 +242,10 @@ .status, .error { padding: 4px; + /* The loading pill occupies the opposite corner while a stale status stays + * visible. Reserve its widest localized footprint so wrapped text cannot + * run underneath it on a narrow card. */ + padding-right: 120px; font-size: 12px; line-height: 18px; } @@ -259,15 +263,15 @@ * the columns' height, and the stale view keeps rendering beneath it (it * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right, * not left: the truncated/error status rows flow at the bottom LEFT and - * stay on screen through a scan, so the opposite corner keeps both - * legible. After .status in the cascade — the element carries both - * classes and this padding must win the same-specificity race. */ + * stay on screen through a scan, with their reserved right padding keeping + * both legible even on a narrow card. After .status in the cascade — the + * element carries both classes and this padding must win the + * same-specificity race. */ .loadingFloat { position: absolute; right: 16px; bottom: 8px; padding: 2px 8px; - border-radius: 6px; background: var(--dsw-alias-bg-layer-2); } diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx index 023404f71d..f5510fda7c 100644 --- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx +++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx @@ -186,10 +186,14 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const [selected, setSelected] = useState(null) const [child, setChild] = useState(null) const [loading, setLoading] = useState(false) - // Derived from `loading` by the slow-scan effect below: true only once a - // scan has been in flight for SLOW_SCAN_DELAY_MS, so fast listings never - // render the indicator at all. + // Derived from `loading` and `scanWindow` by the slow-scan effect below: + // true only once the current listing call has been in flight for + // SLOW_SCAN_DELAY_MS, so fast listings never render the indicator at all. const [slowScan, setSlowScan] = useState(false) + // Every listing call owns a fresh silence window. `loading` may stay true + // across a superseding row pick or across a navigation's target and parent + // legs, so its boolean edge cannot identify the start of each scan. + const [scanWindow, setScanWindow] = useState(0) const [error, setError] = useState(null) // Path-edit state: null = breadcrumb mode; a string = the draft being typed. const [pathDraft, setPathDraft] = useState(null) @@ -233,13 +237,20 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, return ++requestSeq.current }, []) + /** Hide any prior indicator and start a fresh silence window for one listing call. */ + const restartSlowScanWindow = useCallback((): void => { + setSlowScan(false) + setScanWindow(value => value + 1) + }, []) + /** Launch one listing under a fresh controller so a later supersession can abort it. */ const launchListing = useCallback((path: string | undefined): { seq: number; scan: Promise } => { const seq = supersede() const controller = new AbortController() scanController.current = controller + restartSlowScanWindow() return { seq, scan: listDirectory(path, controller.signal) } - }, [supersede, listDirectory]) + }, [supersede, restartSlowScanWindow, listDirectory]) /** * Launch a follow-up listing under the CURRENT supersession seq: a newer @@ -248,8 +259,9 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, const continueScan = useCallback((path: string): Promise => { const controller = new AbortController() scanController.current = controller + restartSlowScanWindow() return listDirectory(path, controller.signal) - }, [listDirectory]) + }, [restartSlowScanWindow, listDirectory]) /** * Replace the whole view with a freshly navigated level. Away from the @@ -474,9 +486,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, }) } - // The slow-scan gate for the loading indicator: arm a timer when a scan - // starts, retire it (and the indicator) the moment loading ends. A settle - // inside the window means the swap happened with nothing shown. + // The slow-scan gate for the loading indicator: each listing call restarts + // the timer even when a superseding scan or a navigation's parent leg keeps + // `loading` continuously true. A settle inside its own window means the swap + // happened with nothing shown. useEffect(() => { if (!loading) { setSlowScan(false) @@ -484,7 +497,7 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen, } const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS) return () => { window.clearTimeout(timer) } - }, [loading]) + }, [loading, scanWindow]) // After the hooks: a closed dialog renders nothing and evaluates no copy. const crumbSource = child ?? parent diff --git a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx index 0fe1f91e00..ce9f03fb0b 100644 --- a/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx +++ b/packages/host/directory-picker-browse/tests/directory-browser.spec.tsx @@ -111,6 +111,12 @@ function rowButton(item: HTMLElement): HTMLButtonElement { } describe('DirectoryBrowser', () => { + it('renders nothing and launches no listing while initially closed', () => { + const b = mount({ open: false }) + expect(screen.queryByRole('dialog')).toBeNull() + expect(b.listDirectory).not.toHaveBeenCalled() + }) + it('opens at the Host home as one wide column, hides hidden entries, and roots the crumbs at Home', async () => { const b = mount() await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() }) @@ -335,9 +341,16 @@ describe('DirectoryBrowser', () => { fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' })) fireEvent.change(screen.getByLabelText('browser.editPath'), { target: { value: DOCS } }) fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' }) + // The target can consume most of the outer scan's silence window. + await act(async () => { vi.advanceTimersByTime(250) }) await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) }) + // Its parent leg gets a fresh silence window. Crossing the original + // scan's 300ms deadline therefore cannot flash the indicator during the + // bounded landing wait. + await act(async () => { vi.advanceTimersByTime(199) }) + expect(screen.queryByText('browser.loading')).toBeNull() // The parent leg outlives PARENT_LEG_WAIT_MS: the target lands alone. - await act(async () => { vi.advanceTimersByTime(200) }) + await act(async () => { vi.advanceTimersByTime(1) }) expect(columns()).toHaveLength(1) expect(screen.getByRole('listitem').textContent).toBe('harness') expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull() @@ -417,6 +430,34 @@ describe('DirectoryBrowser', () => { } }) + it('restarts the silence window when a row pick supersedes a pending scan', async () => { + vi.useFakeTimers() + try { + const pending: ((value: DirectoryListing) => void)[] = [] + const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => { + if (path === undefined) return Promise.resolve(listingFor(path)) + return new Promise((resolve) => { pending.push(resolve) }) + }) + mount({ listDirectory }) + await act(async () => {}) + const documents = rowButton(screen.getByRole('listitem')) + fireEvent.click(documents) + await act(async () => { vi.advanceTimersByTime(300) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + // The same row remains actionable while its preview is pending. A second + // pick starts a new listing without a false `loading` edge. + fireEvent.click(documents) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(299) }) + expect(screen.queryByText('browser.loading')).toBeNull() + await act(async () => { vi.advanceTimersByTime(1) }) + expect(screen.getByText('browser.loading')).toBeTruthy() + await act(async () => { pending.at(-1)!(listingFor(DOCS)) }) + } finally { + vi.useRealTimers() + } + }) + it('a close mid-scan resets the slow-scan gate: reopening waits a fresh silence window', async () => { vi.useFakeTimers() try { From 86ddef6c01ea56477152f656deb47bd9eadd9b2f Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 18:35:32 +0800 Subject: [PATCH 37/67] docs: refresh settings catalog locations --- docs/cordis-catalog/events.md | 2 +- docs/cordis-catalog/services.md | 2 +- docs/event-producer-consumer.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index f7383d1212..5e4521bd77 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -686,7 +686,7 @@ Committed change to one registered namespace's resolved value. Emitted after the Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:106`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:108`](../../packages/settings/settings/src/index.ts) ## `skills/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 5d8705f23d..9dc24cd8b5 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1693,7 +1693,7 @@ async replace(ns: SettingsNamespace, section: object): Promise Types: [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md) -Source: [`packages/settings/settings/src/index.ts:246`](../../packages/settings/settings/src/index.ts) +Source: [`packages/settings/settings/src/index.ts:250`](../../packages/settings/settings/src/index.ts) ## `ctx.skills` — `SkillService` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 0d88723d22..c82ffb5883 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) | | `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) | | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) | -| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:106`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | +| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:108`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) | | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | [`tui`](../packages/ui/tui) | | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) | | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:114`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) | From 6d6c146f8105f09ed0b8626729ed7fbe26654e17 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 19:02:10 +0800 Subject: [PATCH 38/67] ci: allocate consumer runner independently --- ...ence-based-larger-hosted-runners.i18n.yaml | 4 +- ...22-evidence-based-larger-hosted-runners.md | 8 +-- ...evidence-based-larger-hosted-runners.zh.md | 10 ++-- ...30-independent-ci-consumer-build.i18n.yaml | 6 +++ ...026-07-30-independent-ci-consumer-build.md | 35 +++++++++++++ ...-07-30-independent-ci-consumer-build.zh.md | 35 +++++++++++++ ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml | 4 +- .../2026-07-24-web-gui-browser-e2e-lane.md | 2 +- .../2026-07-24-web-gui-browser-e2e-lane.zh.md | 2 +- ...-30-web-browser-snapshot-ci-gate.i18n.yaml | 4 +- ...2026-07-30-web-browser-snapshot-ci-gate.md | 6 +-- ...6-07-30-web-browser-snapshot-ci-gate.zh.md | 6 +-- .github/workflows/ci.yml | 26 +--------- scripts/run-gates.spec.ts | 28 ++++++++--- scripts/run-gates.ts | 49 ++++++++++++------- 15 files changed, 152 insertions(+), 73 deletions(-) create mode 100644 .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml create mode 100644 .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md create mode 100644 .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml index ba77f5f044..88d32203c0 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md -2026-07-22-evidence-based-larger-hosted-runners.md: 983d5520bd73fc3cf82c37bf0d4a9ff1c6e6f51c -2026-07-22-evidence-based-larger-hosted-runners.zh.md: a86dcf2c60d7b950e7557e84ef6993e712a2ce09 +2026-07-22-evidence-based-larger-hosted-runners.md: d46b8291ec05e997728da76354354f9e36bd2fb4 +2026-07-22-evidence-based-larger-hosted-runners.zh.md: e05ad30a713258ed7bc3d8099f8d6fab3d7c0c5d diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md index 983d5520bd..d46b8291ec 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md @@ -18,9 +18,9 @@ The required primary path depends on those enterprise pools. Standard GitHub-hos The former gate-level and coarse primary shard jobs are absent from the workflow. Their static, lint, coverage, snapshot, and scenario shard selectors are also absent from the repository, so an unused diagnostic path cannot preserve a second CI architecture. -Linux primary work uses three independent 32-core jobs. Coverage runs alone with its own worker bound, and the static scheduler runs alone so its result has no post-build consumer tail. After static gates finish, that job publishes its emitted `apps/*/lib`, `packages/*/*/lib`, and `vendor/*/lib` tree as a run-scoped artifact. The third job restores that exact tree, then starts lint, Node 24 runtime compatibility, build-backed snapshots, and all artifact consumers without repeating the build. Generated NodeNext consumer directories are excluded from Oxlint discovery because the artifact check removes them while these processes overlap. The pnpm store is restored without putting cache uploads on the pull-request critical path; Oxlint has no repository-managed result cache. Performance reports use each job's `startedAt` to `completedAt` interval; runner queue delay is capacity evidence, not repository execution time. +Linux primary work uses three independent 32-core jobs. Coverage runs alone with its own worker bound, and the static scheduler owns source and documentation gates that do not consume emitted output. The third job owns the single Linux build, then starts lint, Node 24 runtime compatibility, build-backed snapshots, documentation typechecking, and all artifact consumers against that tree. This [independent consumer build](2026-07-30-independent-ci-consumer-build.md) lets all three jobs request runners immediately without duplicating compilation or transferring a run-scoped artifact. Generated NodeNext consumer directories are excluded from Oxlint discovery because the artifact check removes them while these processes overlap. The pnpm store is restored without putting cache uploads on the pull-request critical path; Oxlint has no repository-managed result cache. Performance reports use each job's `startedAt` to `completedAt` interval; runner queue delay is capacity evidence, not repository execution time. -The gate dependencies remain explicit. Coverage consumes source and does not wait for build. Documentation typechecking builds its complete project-reference graph once. Snapshot replay and publication consumers wait for emitted output, while Node-version compatibility jobs exercise runtime-sensitive source loading without repeating the primary source-graph typecheck. PTY and subprocess suites keep their bounded inner concurrency rather than inheriting the runner's core count. +The gate dependencies remain explicit. Coverage consumes source and does not wait for build. Documentation typechecking consumes the consumer lane's complete project-reference output. Snapshot replay and publication consumers wait for emitted output, while Node-version compatibility jobs exercise runtime-sensitive source loading without repeating the primary source-graph typecheck. PTY and subprocess suites keep their bounded inner concurrency rather than inheriting the runner's core count. The artifact boundary remains explicit. `scripts/publint-all.ts` calls publint's supported API against an in-memory publication view formed from each manifest's declared files plus npm's mandatory metadata, avoiding one package-manager pack process per package. `scripts/verify-built-package-invariants.mjs` stages the declared `lib/` files below the real package and imports its compiled self-reference through plain Node and Cordis Loader normalization; a runtime chunk omitted from the publication contract still fails. @@ -68,7 +68,7 @@ An additional serial Linux reference runs on the in-house self-hosted pool (`vm- **Keep build behind typecheck.** This orders independent compiler invocations and turns snapshot replay into a three-stage critical chain. Build output has its own success dependency, so only snapshot and publication consumers wait for it. -**Keep static gates and post-build consumers on one runner.** Reusing one workspace avoids a setup wave and artifact transfer, but build-duration variance delays every consumer and leaves their lint and snapshot tails after the static result. A run-scoped built tree preserves one exact build while independent jobs keep both complete paths within the observed target. +**Publish the static job's build to post-build consumers.** A run-scoped artifact preserves one exact build, but the workflow can only consume it by waiting for the entire static job and then requesting another runner. The [independent consumer build](2026-07-30-independent-ci-consumer-build.md) assigns the single Linux build to its actual consumers instead. **Keep the complete required path on standard GitHub-hosted capacity.** This avoids repository-external runner configuration, but exact-head standard-runner runs remain materially slower and can spend longer queued behind shared capacity. Standard-hosted compatibility and serial references preserve portable evidence without making that slower topology the ordinary primary path. @@ -80,7 +80,7 @@ An additional serial Linux reference runs on the in-house self-hosted pool (`vm- The required topology pays one setup wave per 32-core lane and retains no shard selectors. Every ordinary pull request consumes paid enterprise Linux and Windows minutes; manual benchmarks add other sizes only when remeasurement is useful. -GitHub rounds each larger-runner execution up to a whole minute, so complete-job measurement exposes both billed time and workflow complexity. Splitting Linux repeats setup twice and transfers one built tree, but isolates coverage, static gates, and post-build consumers from each other's critical paths without repeating the build; consolidating Windows avoids repeating its slower setup. +GitHub rounds each larger-runner execution up to a whole minute, so complete-job measurement exposes both billed time and workflow complexity. Splitting Linux repeats setup twice, but the consumer lane owns the only built tree and coverage, static gates, and post-build consumers enter runner allocation independently; consolidating Windows avoids repeating its slower setup. Performance targets are observations, not cancellation deadlines or correctness requirements. Manual all-size and serial suites remain available when image, dependency, scheduler, or pricing changes need remeasurement. diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md index a86dcf2c60..e05ad30a71 100644 --- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md +++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md @@ -18,11 +18,11 @@ Status: implemented 原有的门禁级和粗粒度主流程分片作业已从工作流中移除。相应的静态、lint、覆盖率、快照和场景分片选择器也已从仓库中移除，因此未使用的诊断路径无法继续维系第二套 CI 架构。 -Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行，并设有自己的工作线程上限；静态调度器也单独运行，因此构建后的消费方不会拖延其结果。静态门禁完成后，该作业将其生成的 `apps/*/lib`、`packages/*/*/lib` 和 `vendor/*/lib` 目录树作为仅供本次运行使用的产物发布。第三个作业恢复完全相同的目录树，再让 lint、Node 24 运行时兼容性、依赖构建产物的快照和所有产物消费方基于构建完成后的工作树启动，而不重复构建。生成的 NodeNext 消费方目录不会纳入 Oxlint 的文件发现范围，因为这些进程重叠执行时，产物检查会删除这些目录。pnpm store 会得到恢复，但缓存上传不会进入拉取请求关键路径；Oxlint 没有由仓库管理的结果缓存。性能报告采用每个作业从 `startedAt` 到 `completedAt` 的区间；运行器排队延迟是容量证据，而非仓库执行时间。 +Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行，并设有自己的工作线程上限；静态调度器负责不消费生成输出的源码和文档门禁。第三个作业负责唯一一次 Linux 构建，随后让 lint、Node 24 运行时兼容性、依赖构建产物的快照、文档类型检查和所有产物消费方基于该目录树启动。这种[消费方独立构建](2026-07-30-independent-ci-consumer-build.md)使 3 个作业都能立即请求运行器，而无需重复编译或传输仅供本次运行使用的产物。生成的 NodeNext 消费方目录不会纳入 Oxlint 的文件发现范围，因为这些进程重叠执行时，产物检查会删除这些目录。pnpm store 会得到恢复，但缓存上传不会进入拉取请求关键路径；Oxlint 没有由仓库管理的结果缓存。性能报告采用每个作业从 `startedAt` 到 `completedAt` 的区间；运行器排队延迟是容量证据，而非仓库执行时间。 -门禁依赖关系保持显式。覆盖率消费源码，不等待构建。文档类型检查只构建一次完整的 project-reference 图。快照回放和发布消费方等待生成的输出，而 Node 版本兼容性作业会验证对运行时敏感的源码加载，且不重复主源码项目图的类型检查。PTY 和子进程套件继续使用自身有界的内部并发，不继承运行器的核心数。 +门禁依赖关系保持显式。覆盖率消费源码，不等待构建。文档类型检查以消费方通道的完整 project-reference 输出为输入。快照回放和发布消费方等待生成的输出，而 Node 版本兼容性作业会验证对运行时敏感的源码加载，且不重复主源码项目图的类型检查。PTY 和子进程套件继续使用自身有界的内部并发，不继承运行器的核心数。 -产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布契约只要遗漏一个运行时分片，检查仍会失败。 +产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包（package）启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布契约只要遗漏一个运行时分片，检查仍会失败。 Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物契约。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台契约。 @@ -68,7 +68,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完 **让构建继续等待类型检查。** 此方案会给相互独立的编译器调用排定先后顺序，并把快照回放变成 3 阶段关键链。构建输出本身有独立的成功依赖关系，因此只有快照和发布消费方需要等待它。 -**将静态门禁和构建后消费方保留在同一台运行器上。** 复用同一个工作区可以省去一轮设置和一次产物传输，但构建耗时的波动会延迟每个消费方，并使消费方的 lint 和快照尾段延续到静态结果之后。仅供本次运行使用的已构建目录树可以保留同一份构建结果，而相互独立的作业能让两条完整路径都保持在实测目标内。 +**将静态作业的构建发布给构建后消费方。** 仅供本次运行使用的产物能保留同一份构建结果，但工作流要消费它，只能先等待整个静态作业完成，再请求另一台运行器。[消费方独立构建](2026-07-30-independent-ci-consumer-build.md)则转而让实际消费方负责唯一一次 Linux 构建。 **将完整必需路径保留在 GitHub 标准托管容量上。** 此方案可以避免依赖仓库外部的运行器配置，但标准运行器上的分支头精确运行仍明显更慢，也可能因共享容量而排队更久。标准托管兼容性作业和串行参考流程保留可移植证据，无需让这套较慢的拓扑成为普通主路径。 @@ -80,7 +80,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完 必需拓扑中的每个 32 核通道只承担 1 轮设置开销，且不保留分片选择器。每个普通拉取请求都会消耗付费的企业级 Linux 和 Windows 运行器分钟数；只有在重新测量有价值时，手动基准测试才会加入其他规格。 -GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此完整作业测量能同时呈现计费时长与工作流复杂度。拆分 Linux 会重复两轮设置并传输一份已构建目录树，但能使覆盖率、静态门禁与构建后消费方不再相互进入关键路径，且无需重复构建；合并 Windows 则避免重复其耗时更长的设置。 +GitHub 会把每次大型运行器执行向上取整到整分钟计费，因此完整作业测量能同时呈现计费时长与工作流复杂度。拆分 Linux 会重复两轮设置，但消费方通道拥有唯一一份已构建目录树，且覆盖率、静态门禁与构建后消费方分别进入运行器分配；合并 Windows 则避免重复其耗时更长的设置。 性能目标是观测结果，而非取消截止时间或正确性要求。当映像、依赖、调度器或定价发生变化而需要重新测量时，仍可使用手动全规格和串行套件。 diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml new file mode 100644 index 0000000000..663b074d59 --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md +2026-07-30-independent-ci-consumer-build.md: ea87d8051a30c282bdf57ddc3226072be8cb7f24 +2026-07-30-independent-ci-consumer-build.zh.md: 1b5faf73711bd522ddf0ae04f870e0401a481c0e diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md new file mode 100644 index 0000000000..ea87d8051a --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md @@ -0,0 +1,35 @@ +# Agent Note: Independent CI consumer build + +Status: implemented + +English | [中文](2026-07-30-independent-ci-consumer-build.zh.md) + +## Problem + +The [larger-runner topology](2026-07-22-evidence-based-larger-hosted-runners.md) gave the static and built-consumer inventories separate jobs, but the static job owned their shared build. It uploaded the emitted tree only after every static gate completed, and the consumer job declared a job-level dependency before restoring that tree. Compiled-output snapshots and publication checks genuinely require a complete build; they do not require runtime-closure checks, documentation generation, module-graph verification, or Knip. + +That wider dependency made runner availability part of the required critical chain. In one failover run, static waited 8 minutes 1 second for a runner and ran for 1 minute 41 seconds; only then could consumers enter the same shared pool, where they waited another 10 minutes 34 seconds before running for 1 minute 58 seconds. Reusing the static build saved repository work but serialized two independent runner allocations. + +## Decision + +The three required Linux jobs enter runner allocation independently. Coverage remains source-only. Static owns source and documentation checks that do not consume emitted output. The consumer job owns the single Linux build together with documentation typechecking, compiled-output snapshots, publication checks, NodeNext checks, and built-bin smokes. + +The consumer's internal gate graph preserves the real dependency. Build and source-only Node compatibility start first; publint waits for build, built-package invariants validate that publication view, and every compiled-output consumer waits for that validation. Example and Web snapshots therefore continue to exercise current `lib/` output under plain Node, while no GitHub job waits for an unrelated job or transfers a built-tree artifact. + +Windows and serial reference aggregates retain their own build ownership. The change is confined to the required pull-request Linux topology; `all checks passed` still aggregates the same named jobs and fails for any unsuccessful dependency. + +## Alternatives considered + +**Keep publishing the static job's build.** This preserves one build but cannot express the actual step-level dependency: GitHub makes the consumer wait for the whole static job before it can request a runner. The saved build time is smaller than the repeated queue delay during failover saturation. + +**Build independently in both jobs.** Removing the job dependency while leaving build in static would restore parallel allocation, but every pull request would compile the same tree twice. Moving documentation typechecking and build ownership to the consumer preserves one build. + +**Add a dedicated build job.** A narrow producer would make the dependency name accurate, but it would add a fourth setup and runner-allocation stage before consumers. The consumer already owns every long-lived use of emitted output, so a separate producer has no second independent consumer. + +**Combine static and consumers only during failover.** One long job would avoid the second allocation, but conditional job inventories and result aggregation would create a second CI topology. Independent jobs preserve the same graph on hosted and failover pools. + +## Consequences + +Static and consumer queue delays overlap instead of accumulating. The consumer's active time includes the build, while the static job becomes shorter and artifact upload, download, compression, and extraction disappear. Total Linux build count remains one. + +A static failure no longer prevents the consumer inventory from producing its own evidence; the final verdict still fails. Build and documentation-typecheck failures appear under `node 24 / snapshots and artifacts` rather than `node 24 / static`, matching the job that owns their output dependency. diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md new file mode 100644 index 0000000000..1b5faf7371 --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md @@ -0,0 +1,35 @@ +# Agent Note: 消费方独立构建 + +Status: implemented + +[English](2026-07-30-independent-ci-consumer-build.md) | 中文 + +## 问题 + +[大型运行器拓扑](2026-07-22-evidence-based-larger-hosted-runners.md)将静态门禁清单和构建后消费方清单分配给不同作业，但二者共用的构建由静态作业负责。静态作业要等所有静态门禁完成后才上传生成的目录树，消费方作业则在恢复该目录树前声明了作业级依赖。基于编译输出的快照与发布校验确实需要完整构建，但不依赖运行时依赖闭包检查、文档生成、模块图验证或 Knip。 + +这项过宽的依赖使运行器可用性成为必需关键链的一环。一次故障切换运行中，静态作业等待运行器 8 分 1 秒，随后运行 1 分 41 秒；直到此时，消费方作业才能进入同一个共享池，它又等待 10 分 34 秒，随后运行 1 分 58 秒。复用静态作业的构建省去了部分仓库工作，却让两次原本相互独立的运行器分配串行发生。 + +## 决策 + +3 个必需 Linux 作业分别进入运行器分配。覆盖率仍只消费源码。静态作业负责无需消费生成输出的源码检查与文档检查。消费方作业负责唯一一次 Linux 构建，以及文档类型检查、基于编译输出的快照、发布校验、NodeNext 检查和 built-bin 冒烟测试。 + +消费方内部的门禁图保留实际依赖关系。构建和只消费源码的 Node 兼容性检查率先启动；publint 等待构建完成，已构建包不变式检查会验证该发布视图，所有编译输出消费方都等待这项验证完成。因此，示例和 Web 快照仍会在普通 Node 下验证当前 `lib/` 输出；同时，没有任何 GitHub 作业需要等待无关作业或传输已构建目录树产物。 + +Windows 与串行参考聚合流程仍各自负责自身构建。本变更仅涉及拉取请求的必需 Linux 拓扑；`all checks passed` 仍聚合同一批具名作业，任一依赖未成功时都会失败。 + +## 曾考虑的替代方案 + +**继续发布静态作业的构建。** 此方案只需构建一次，却无法表达实际的步骤级依赖：GitHub 会让消费方等到整个静态作业结束后才可请求运行器。故障切换池饱和时，再次排队的延迟超过了省下的构建时间。 + +**在两个作业中分别独立构建。** 在静态作业中保留构建、同时移除作业依赖，可以恢复并行分配，但每个拉取请求都会对同一目录树编译两次。将文档类型检查和构建职责移给消费方，则仍只需构建一次。 + +**新增专用构建作业。** 职责单一的生产方能让依赖名称与实际关系相符，但会在消费方之前新增第 4 个需要设置和分配运行器的阶段。所有需要持续使用生成输出的任务都已由消费方作业负责，因此单独增设生产方也没有第二个相互独立的消费方。 + +**仅在故障切换期间合并静态作业与消费方作业。** 单个长作业可以避免第二次分配，但带条件分支的作业清单与结果聚合会形成第二套 CI 拓扑。独立作业能让托管池与故障切换池使用同一作业图。 + +## 后果 + +静态作业与消费方作业的排队延迟会相互重叠，不再累加。消费方的活动耗时包含构建；静态作业则变短，产物上传、下载、压缩和解压步骤全部消失。Linux 构建总次数仍为 1 次。 + +静态作业失败不再阻止消费方清单生成自身证据；最终判定仍会失败。构建与文档类型检查失败会归入 `node 24 / snapshots and artifacts` 而非 `node 24 / static`，这一归类与输出依赖的实际归属一致。 diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml index 14990e32c8..6b950f9fc8 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md -2026-07-24-web-gui-browser-e2e-lane.md: fb28b7013550a853b92e50810f5bc34f2c02d2e4 -2026-07-24-web-gui-browser-e2e-lane.zh.md: b9a7d050031c3d08269a3b971cd1a84f082efba7 +2026-07-24-web-gui-browser-e2e-lane.md: 898b8b5fe1b8d65b108b4afa95b782a1ce1e5c71 +2026-07-24-web-gui-browser-e2e-lane.zh.md: 966a9854aee8f3b63b2ae8f1362f91a40b9ba894 diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md index fb28b70135..898b8b5fe1 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md @@ -46,7 +46,7 @@ The lane covers three behavior families. Live-turn scenarios pin ordinary tool e ### CI stance -The lane is a required compare-only gate for Linux pull requests under the [browser snapshot CI decision](2026-07-30-web-browser-snapshot-ci-gate.md). The static job publishes `apps/web/dist` with the package build artifacts; the `node 24 / snapshots and artifacts` consumer job installs the lockfile-selected Chromium, restores its OS-and-lockfile-keyed cache, and runs the lane with `DSH_SNAPSHOT=replay`. This is an intentional plane split: the host and specs use the [tsx source-launch contract](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md), while the browser consumes `apps/web/dist` and package `lib/client.js` artifacts, so the gate depends on `built-package-invariants` for those client artifacts. The hosted and self-hosted default-branch Linux serial jobs run the same gate; the hosted job produces the browser cache consumed by pull requests, while the persistent self-hosted pool needs no hosted cache. CI never records or refreshes goldens. Scenarios remain POSIX-oriented and stay outside the Windows and macOS matrices. +The lane is a required compare-only gate for Linux pull requests under the [browser snapshot CI decision](2026-07-30-web-browser-snapshot-ci-gate.md). The `node 24 / snapshots and artifacts` consumer job owns the [single Linux build](../process/2026-07-30-independent-ci-consumer-build.md), installs the lockfile-selected Chromium, restores its OS-and-lockfile-keyed cache, and runs the lane with `DSH_SNAPSHOT=replay`. This is an intentional plane split: the host and specs use the [tsx source-launch contract](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md), while the browser consumes `apps/web/dist` and package `lib/client.js` artifacts, so the gate depends on `built-package-invariants` for those client artifacts. The hosted and self-hosted default-branch Linux serial jobs run the same gate; the hosted job produces the browser cache consumed by pull requests, while the persistent self-hosted pool needs no hosted cache. CI never records or refreshes goldens. Scenarios remain POSIX-oriented and stay outside the Windows and macOS matrices. ## Prior art diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md index b9a7d05003..966a9854ae 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md @@ -46,7 +46,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu ### CI 立场 -根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。static 任务会把 `apps/web/dist` 与包构建产物一同发布；`node 24 / snapshots and artifacts` 消费方任务安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。 +根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。 ## 业界先例 diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml index d16d412559..2e8e53fdd7 100644 --- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md -2026-07-30-web-browser-snapshot-ci-gate.md: 3f87bb0f3d936bcee7ba7c3d84ae808c6ede1a97 -2026-07-30-web-browser-snapshot-ci-gate.zh.md: af563f0e2a1c20f7b53d371e97e41b7ffa52a1d1 +2026-07-30-web-browser-snapshot-ci-gate.md: 14402485034cd85ec5781477ce67481165d47e62 +2026-07-30-web-browser-snapshot-ci-gate.zh.md: f214c524253d2ad8a43e8543dc65ddfcfd7c065c diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md index 3f87bb0f3d..1440248503 100644 --- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md +++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md @@ -12,7 +12,7 @@ The [keyless web browser e2e lane](2026-07-24-web-gui-browser-e2e-lane.md) runs For Linux PRs, the `node 24 / snapshots and artifacts` job must run the full web browser replay/compare suite. `scripts/run-gates.ts` registers `test:web:built` as a `ci-consumers` gate and explicitly injects `DSH_SNAPSHOT=replay`; CI never runs in `record` or `refresh` mode, so when the committed goldens disagree with the currently assembled application, the tests fail directly instead of silently rewriting them on the runner and then passing. -The static CI job already builds all publishable artifacts; it puts `apps/web/dist` and the package `lib/` directories in the built-tree artifact, which the consumer job reuses without rebuilding the entire repository. On hosted runners, CI installs Chromium and its system dependencies at the Playwright version in the lockfile. On the persistent failover VM, the image owns the Linux system packages and CI installs only Chromium, avoiding per-run `apt` mutation. The hosted default-branch Linux serial job runs the suite and produces the operating-system-and-lockfile-keyed browser cache; pull requests restore it without paying compression and upload on the required path, with an operating-system prefix fallback across lockfile changes. The self-hosted standby runs the same comparison without hosted cache actions. +The consumer job owns the [single Linux build](../process/2026-07-30-independent-ci-consumer-build.md), so `apps/web/dist` and the package `lib/` directories remain in its workspace for the browser suite. On hosted runners, CI installs Chromium and its system dependencies at the Playwright version in the lockfile. On the persistent failover VM, the image owns the Linux system packages and CI installs only Chromium, avoiding per-run `apt` mutation. The hosted default-branch Linux serial job runs the suite and produces the operating-system-and-lockfile-keyed browser cache; pull requests restore it without paying compression and upload on the required path, with an operating-system prefix fallback across lockfile changes. The self-hosted standby runs the same comparison without hosted cache actions. Local `pnpm run test:web` continues to build first and then run the full browser suite; `test:web:built` is the entry point for existing build artifacts. Developers explicitly run `DSH_SNAPSHOT=refresh pnpm run test:web` only after confirming that user-visible output changed intentionally, review every expected-output diff, and then verify again in replay mode that no files are written. @@ -26,10 +26,10 @@ An observed self-hosted consumer run measured `web-snapshot` at 112.15 seconds a **Run CI in `refresh` mode and then check the working tree.** Rejected: checking after writing turns the assertion mechanism into a generator; if the working-tree check is wired incorrectly, it can turn a regression into a passing expected-output update. Replay compares the existing goldens directly and has a smaller failure surface. -**Create a standalone browser job and rebuild the entire repository.** Rejected: it would duplicate dependency installation and the publishable build. The existing Linux consumer job already consumes the same built-tree artifact and is part of the unified required verdict. +**Create a standalone browser job and rebuild the entire repository.** Rejected: it would duplicate dependency installation and the publishable build. The existing Linux consumer job already owns that build and is part of the unified required verdict. **Replace real Chromium with jsdom snapshots.** Rejected: jsdom does not cover the browser, HTTP/SSE carriage, or the composition of real client plugin bundles. It remains useful for fast lower-layer feedback, but cannot replace the assembled browser chain. ## Consequences -Before merge, every PR proves that the current web assembly matches all committed browser expected outputs, turning a missed refresh from an “unrelated change in a later PR” into a failure in the PR that introduced it. The cost is Chromium provisioning and one serial pass through the browser scenarios in the consumer job; built-artifact reuse and the browser cache avoid duplicate builds and downloads on reruns. The gate still makes no claim of cross-platform browser consistency, and if a Playwright/Chromium upgrade changes the ARIA format, the upgrade PR must explicitly refresh the expected outputs and review the churn. +Before merge, every PR proves that the current web assembly matches all committed browser expected outputs, turning a missed refresh from an “unrelated change in a later PR” into a failure in the PR that introduced it. The cost is Chromium provisioning and one serial pass through the browser scenarios in the consumer job; the consumer-owned build and browser cache avoid duplicate builds and downloads on reruns. The gate still makes no claim of cross-platform browser consistency, and if a Playwright/Chromium upgrade changes the ARIA format, the upgrade PR must explicitly refresh the expected outputs and review the churn. diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md index af563f0e2a..f214c52425 100644 --- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md +++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md @@ -12,7 +12,7 @@ Status: implemented Linux PR 的 `node 24 / snapshots and artifacts` 必须运行完整 Web 浏览器 replay/compare。`scripts/run-gates.ts` 把 `test:web:built` 作为 `ci-consumers` 的一个 gate，并显式注入 `DSH_SNAPSHOT=replay`；CI 永不以 `record` 或 `refresh` 模式运行，因此提交的 golden 与当前组装应用不一致时测试直接失败，不会在 runner 内静默改写后通过。 -静态 CI job 已经构建全部发布产物；它把 `apps/web/dist` 和包的 `lib/` 目录放进 built-tree 产物，消费方 job 复用该产物而不重复全仓构建。在托管运行器上，CI 按锁文件中的 Playwright 版本安装 Chromium 及其系统依赖。在持久化故障切换 VM 上，镜像负责预装 Linux 系统软件包，CI 只安装 Chromium，避免每次运行都通过 `apt` 改动系统。托管的默认分支 Linux 串行 job 运行该套件，并生成以操作系统和锁文件为键的浏览器缓存；PR 恢复该缓存，使必需路径无需承担压缩和上传开销，并可在锁文件变化时按操作系统前缀回退。自托管热备运行相同的比较，但不执行托管缓存操作。 +消费方 job 在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，因此 `apps/web/dist` 和包的 `lib/` 目录会保留在其工作区中，供浏览器套件使用。在托管运行器上，CI 按锁文件中的 Playwright 版本安装 Chromium 及其系统依赖。在持久化故障切换 VM 上，镜像负责预装 Linux 系统软件包，CI 只安装 Chromium，避免每次运行都通过 `apt` 改动系统。托管的默认分支 Linux 串行 job 运行该套件，并生成以操作系统和锁文件为键的浏览器缓存；PR 恢复该缓存，使必需路径无需承担压缩和上传开销，并可在锁文件变化时按操作系统前缀回退。自托管热备运行相同的比较，但不执行托管缓存操作。 本地 `pnpm run test:web` 仍先构建再运行浏览器全集；`test:web:built` 是已有构建产物的执行入口。开发者只在确认用户可见输出有意变化后显式运行 `DSH_SNAPSHOT=refresh pnpm run test:web`，评审每一处 expected diff，再以 replay 模式复验不再写文件。 @@ -26,10 +26,10 @@ Linux PR 的 `node 24 / snapshots and artifacts` 必须运行完整 Web 浏览 **让 CI 以 `refresh` 模式运行后检查工作树。** 已否决：写后比较把断言机制变成生成器，若工作树检查接线失效就会把回归更新成绿色；replay 直接比较已有 golden，失败面更小。 -**新建独立 browser job 并重新构建全仓。** 已否决：它会重复依赖安装和发布构建。现有 Linux consumer job 已消费同一 built-tree artifact，并已被统一的 required verdict 聚合。 +**新建独立 browser job 并重新构建全仓。** 已否决：它会重复依赖安装和发布构建。现有 Linux 消费方 job 已负责该构建，并已被统一的 required verdict 聚合。 **用 jsdom 快照代替真实 Chromium。** 已否决：jsdom 不覆盖浏览器、HTTP/SSE 承载及真实 client plugin bundle 组合；它保留为快速的下层反馈，不能替代 assembled browser chain。 ## 后果 -每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器 expected 一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要供给 Chromium，并串行运行一轮浏览器场景；built artifact 复用与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 aria 格式，升级 PR 必须显式 refresh 并评审 churn。 +每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器 expected 一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要供给 Chromium，并串行运行一轮浏览器场景；消费方独立构建与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 aria 格式，升级 PR 必须显式 refresh 并评审 churn。 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c9800a0d62..c6a9aa04f3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,8 +28,8 @@ env: jobs: # Three enterprise jobs isolate coverage, static analysis, and the - # build-backed consumer tail. The static job publishes its exact build so - # consumers do not repeat the longest part of their critical path. + # build-backed consumer tail. The consumer job owns the only Linux build so + # all three jobs enter runner allocation independently. # # FAILOVER: each Linux enterprise job resolves its pool through the # DSH_CI_FAILOVER repository variable. Unset (normal), the expressions @@ -93,19 +93,6 @@ jobs: DSH_ARCHIVE_BASE_REF: ${{ github.event.pull_request.base.sha }} run: pnpm run check:ci:static - - name: Pack built tree - run: >- - tar -czf "$RUNNER_TEMP/node-24-built-tree.tar.gz" - apps/*/lib apps/web/dist packages/*/*/lib vendor/*/lib - - - uses: actions/upload-artifact@v7 - with: - name: node-24-built-tree - path: ${{ runner.temp }}/node-24-built-tree.tar.gz - if-no-files-found: error - retention-days: 1 - compression-level: 0 - node-24-coverage: if: github.event_name == 'pull_request' runs-on: >- @@ -171,7 +158,6 @@ jobs: run: pnpm run check:ci:coverage node-24-consumers: - needs: node-24 if: github.event_name == 'pull_request' runs-on: >- ${{ vars.DSH_CI_FAILOVER == 'selfhosted' @@ -191,14 +177,6 @@ jobs: with: persist-credentials: false - - uses: actions/download-artifact@v8 - with: - name: node-24-built-tree - path: ${{ runner.temp }} - - - name: Restore built tree - run: tar -xzf "$RUNNER_TEMP/node-24-built-tree.tar.gz" - - uses: pnpm/action-setup@v4 with: dest: ${{ runner.temp }}/setup-pnpm diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts index 9a67e64929..a4ea97ce31 100644 --- a/scripts/run-gates.spec.ts +++ b/scripts/run-gates.spec.ts @@ -135,31 +135,43 @@ describe('Oxlint gate', () => { }) }) -describe('Node 24 consumer graph', () => { - it('owns the eight-command pool and orders restored-artifact consumers', () => { +describe('Node 24 lane ownership', () => { + it('keeps the static lane source-only', () => { + const subject = withPnpmEntrypoint(() => gatesForMode('ci-static')) + + expect(subject.map(item => item.id)).not.toContain('build') + expect(subject.map(item => item.id)).not.toContain('doc-typecheck') + }) + + it('owns the build and orders its artifact consumers', () => { const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers')) expect(defaultConcurrency('ci-consumers', subject.length, 4)).toEqual({ - workers: 8, + workers: 10, source: 'ci-consumers gate count', }) expect(subject.map(item => item.id)).toEqual([ - 'lint-and-duplication', + 'build', 'node-compat', + 'publint', + 'built-package-invariants', + 'lint-and-duplication', 'snapshot', 'web-snapshot', - 'publint', + 'doc-typecheck', 'node-next-types', - 'built-package-invariants', 'built-bin-smoke', ]) - expect(subject.find(item => item.id === 'publint')?.needs).toBeUndefined() + expect(subject.find(item => item.id === 'publint')?.needs).toEqual(['build']) expect(subject.find(item => item.id === 'built-package-invariants')?.needs).toEqual(['publint']) expect(subject.find(item => item.id === 'lint-and-duplication')?.needs).toEqual(['built-package-invariants']) - for (const id of ['snapshot', 'web-snapshot', 'node-next-types', 'built-bin-smoke']) { + for (const id of ['snapshot', 'web-snapshot', 'doc-typecheck', 'node-next-types', 'built-bin-smoke']) { expect(subject.find(item => item.id === id)?.needs).toEqual(['built-package-invariants']) } expect(subject.find(item => item.id === 'snapshot')?.env).toEqual({ DSH_EXAMPLE_MODE: 'lib' }) + expect(subject.find(item => item.id === 'doc-typecheck')?.env).toEqual({ + DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1', + }) expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({ displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built', env: { DSH_SNAPSHOT: 'replay' }, diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 167d226ff8..46bc72c833 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -195,7 +195,7 @@ export function gatesForMode(selected: Mode): Gate[] { case 'ci-linux-primary': return [...ciPrimaryGates(), webSnapshotGate(['built-package-invariants'])] case 'ci-static': - return ciStaticGates() + return ciStaticGates({ ownsBuild: false }) case 'ci-lint': return [ lintGate(), @@ -295,16 +295,21 @@ function nodeCompatSmokeGates(): Gate[] { ] } -function ciStaticGates(): Gate[] { +function ciStaticGates(options: { ownsBuild: boolean }): Gate[] { return [ pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }), pnpmScript('constraints', 'constraints'), pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }), pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }), - pnpmScript('build', 'build'), + ...options.ownsBuild ? [pnpmScript('build', 'build')] : [], ...docSyncLeafGates({ - docTypecheckNeeds: ['build'], - docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' }, + includeDocTypecheck: options.ownsBuild, + ...options.ownsBuild + ? { + docTypecheckNeeds: ['build'], + docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' }, + } + : {}, docsBuildScript: 'docs:build:mpa', }), pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), @@ -326,23 +331,28 @@ function ciArtifactGates(): Gate[] { } function ciConsumerGates(): Gate[] { - const publicArtifacts = ['publint'] - const restoredBuild = ['built-package-invariants'] + const builtTree = ['build'] + const validatedBuild = ['built-package-invariants'] return [ + pnpmScript('build', 'build'), + pnpmScript('node-compat', 'check:node-compat', { label: 'Node compatibility' }), + pnpmScript('publint', 'publint', { needs: builtTree }), + builtPackageInvariantsGate(['publint']), pnpmScript('lint-and-duplication', 'check:ci:lint', { label: 'lint and duplication', - needs: restoredBuild, + needs: validatedBuild, + }), + snapshotGate(validatedBuild), + webSnapshotGate(validatedBuild), + pnpmScript('doc-typecheck', 'doc-typecheck', { + needs: validatedBuild, + env: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' }, }), - pnpmScript('node-compat', 'check:node-compat', { label: 'Node compatibility' }), - snapshotGate(restoredBuild), - webSnapshotGate(restoredBuild), - pnpmScript('publint', 'publint'), pnpmScript('node-next-types', 'verify-node-next-types', { label: 'node-next types', - needs: restoredBuild, + needs: validatedBuild, }), - builtPackageInvariantsGate(publicArtifacts), - builtBinSmokeGate(restoredBuild), + builtBinSmokeGate(validatedBuild), ] } @@ -377,7 +387,7 @@ function ciWindowsCompleteGates(): Gate[] { function ciWindowsObservationalGates(): Gate[] { return [ - ...ciStaticGates(), + ...ciStaticGates({ ownsBuild: true }), // Linux owns required lint, coverage, and snapshots; Windows omits those duplicates. pnpmScript('duplication', 'duplication'), pnpmScript('publint', 'publint', { needs: ['build'] }), @@ -410,7 +420,7 @@ function coverageGate(): Gate { // Example and package snapshots boot their bins in `lib` mode (built artifacts under plain Node, // plugins via real exports); repository-script snapshots execute their real source entry path. -// Build-owning modes wait on `build`; a restored-artifact mode passes its validation dependency. +// Callers wait either on `build` or on a validation gate that transitively owns that build. function snapshotGate(needs: string[] = ['build']): Gate { return pnpmScript('snapshot', 'test:snapshot', { env: { DSH_EXAMPLE_MODE: 'lib' }, @@ -458,6 +468,7 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] { } function docSyncLeafGates(options: { + includeDocTypecheck?: boolean docTypecheckNeeds?: string[] docTypecheckEnv?: Record docsBuildScript?: 'docs:build' | 'docs:build:mpa' @@ -466,7 +477,9 @@ function docSyncLeafGates(options: { if (options.docTypecheckNeeds !== undefined) docTypecheckOptions.needs = options.docTypecheckNeeds if (options.docTypecheckEnv !== undefined) docTypecheckOptions.env = options.docTypecheckEnv return [ - pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions), + ...options.includeDocTypecheck === false + ? [] + : [pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions)], pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }), pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }), pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }), From 89d30b0ef71320a562ab41f99c68548be41d2d50 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 19:09:19 +0800 Subject: [PATCH 39/67] feat(user-interaction): declare a plan-review presentation intent on questions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A question may now carry `intent`, a tagged declaration that it IS a decision of a known shape, so a UI that recognises the tag can present it as such instead of as a generic option list. The one member is `{ kind: 'plan-review', approve }`, which plan-mode sets on the exit_plan_mode review. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, so the tool reads one answer shape either way, and a UI that does not know the tag renders the generic flow. `approve` names the affirmative option rather than relying on option order; since no type can tie that label to the question's own option list, `ask()` rejects a mismatch as BAD_INTENT, and the wire schema rejects an unknown tag outright rather than silently rendering generic. plan-mode also stops reporting a dismissed review as "the user cancelled ask_user_question" — a tool it never called. A dismissal now tells the model the user took the turn back to speak, and to stay in plan mode and wait; every other ask failure keeps its own message. --- docs/cordis-catalog/services.md | 4 +- .../user-interaction.i18n.yaml | 6 +-- docs/core-data-structures/user-interaction.md | 26 ++++++++++++ .../user-interaction.zh.md | 26 ++++++++++++ .../cordis/tool-cordis/src/api-catalog.ts | 6 ++- .../host/apiproxy/src/api/events.schema.ts | 5 +++ .../host/apiproxy/tests/rpc-schemas.spec.ts | 11 +++++ packages/plan/plan-mode/README.i18n.yaml | 4 +- packages/plan/plan-mode/README.md | 7 +++- packages/plan/plan-mode/README.zh.md | 7 +++- packages/plan/plan-mode/src/index.ts | 24 +++++++++-- .../plan/plan-mode/tests/plan-mode.spec.ts | 38 ++++++++++++++++- packages/ui/user-interaction/README.i18n.yaml | 4 +- packages/ui/user-interaction/README.md | 9 +++- packages/ui/user-interaction/README.zh.md | 9 +++- packages/ui/user-interaction/src/index.ts | 17 +++++++- packages/ui/user-interaction/src/types.ts | 20 +++++++++ .../tests/user-interaction.spec.ts | 41 +++++++++++++++++++ scripts/type-equiv.manifest.json | 5 +++ 19 files changed, 246 insertions(+), 23 deletions(-) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 8e4030c2fe..6ab505b3fb 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -908,7 +908,7 @@ set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop Types: [Agent](../core-data-structures/core.md) -Source: [`packages/plan/plan-mode/src/index.ts:179`](../../packages/plan/plan-mode/src/index.ts) +Source: [`packages/plan/plan-mode/src/index.ts:182`](../../packages/plan/plan-mode/src/index.ts) ## `ctx.pty` — `PtyService` @@ -2284,7 +2284,7 @@ async ask(request: AskUserQuestionRequest): Promise Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md) -Source: [`packages/ui/user-interaction/src/index.ts:50`](../../packages/ui/user-interaction/src/index.ts) +Source: [`packages/ui/user-interaction/src/index.ts:51`](../../packages/ui/user-interaction/src/index.ts) ## `ctx.web` — `WebService` diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml index 66cb12815e..ee739a59d3 100644 --- a/docs/core-data-structures/user-interaction.i18n.yaml +++ b/docs/core-data-structures/user-interaction.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write -user-interaction.md: 798a9790f424683775284a98421be08e6e1399e3 -user-interaction.zh.md: 12bfcffe4fe4caaacb54e90126eac55e333d64a5 +# pnpm run verify-translation-pairing --write docs/core-data-structures/user-interaction.md +user-interaction.md: 4ebaf66131b3ab7a7c205bef1ba533e9321d4f0b +user-interaction.zh.md: 8e5542b995bbf061b097d650ab79505e93151fa8 diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md index 798a9790f4..4ebaf66131 100644 --- a/docs/core-data-structures/user-interaction.md +++ b/docs/core-data-structures/user-interaction.md @@ -20,6 +20,30 @@ interface AskUserQuestionOption { } ``` +## Presentation intent + +`AskUserQuestionIntent` is the optional declaration that a question IS a decision of a known shape. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent shapes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads one answer shape either way. `approve` names the affirmative option instead of relying on option order, and `ask()` rejects an `approve` naming none of its own question's options. + +```ts type-equiv +/** + * A caller-declared presentation intent: the question IS a decision of this + * shape, so a UI that recognises the tag may present it as such instead of as a + * generic option list. Tagged so further intents can be added; a UI that does + * not know a tag renders the generic flow, and the answer encoding is identical + * either way — an intent shapes presentation only, never the protocol. + */ +type AskUserQuestionIntent = { + /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + kind: 'plan-review' + /** + * The option label that approves the plan; every other option declines it. + * Named rather than positional so no UI infers the verdict from option order. + * An `approve` naming no option of its own question is rejected at `ask()`. + */ + approve: string +} +``` + ## Question item `AskUserQuestionItem` is one question in a request. The caller supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. Optional `detail` carries supporting text that providers render with the question but keep out of selectable option labels. @@ -39,6 +63,8 @@ interface AskUserQuestionItem { options?: AskUserQuestionOption[] /** Whether more than one option may be selected. Defaults to single-select. */ multiSelect?: boolean + /** Optional presentation intent for capable UIs; absent asks for the generic option list. */ + intent?: AskUserQuestionIntent } ``` diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md index 12bfcffe4f..8e5542b995 100644 --- a/docs/core-data-structures/user-interaction.zh.md +++ b/docs/core-data-structures/user-interaction.zh.md @@ -20,6 +20,30 @@ interface AskUserQuestionOption { } ``` +## 呈现意图 + +`AskUserQuestionIntent` 是一项可选声明：某个问题本身就是一次已知形状的决定。它按 `kind` 打标签，因此意图可以扩充；不认识某个标签的 UI 渲染通用选项列表。意图只塑造呈现 —— 遵循它的 UI 回答的仍是通用 UI 会发送的那些 option label，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名肯定选项，而不依赖选项顺序；`ask()` 会拒绝未命中该问题自身任一选项的 `approve`。 + +```ts type-equiv +/** + * A caller-declared presentation intent: the question IS a decision of this + * shape, so a UI that recognises the tag may present it as such instead of as a + * generic option list. Tagged so further intents can be added; a UI that does + * not know a tag renders the generic flow, and the answer encoding is identical + * either way — an intent shapes presentation only, never the protocol. + */ +type AskUserQuestionIntent = { + /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + kind: 'plan-review' + /** + * The option label that approves the plan; every other option declines it. + * Named rather than positional so no UI infers the verdict from option order. + * An `approve` naming no option of its own question is rejected at `ask()`. + */ + approve: string +} +``` + ## 问题条目 `AskUserQuestionItem` 是请求中的一个问题。调用方提供稳定的 `id`，它会随答案原样返回，使批量问题仍可路由。可选的 `detail` 携带辅助文本；提供方会将其随问题渲染，但不会放入可选 option label。 @@ -39,6 +63,8 @@ interface AskUserQuestionItem { options?: AskUserQuestionOption[] /** Whether more than one option may be selected. Defaults to single-select. */ multiSelect?: boolean + /** Optional presentation intent for capable UIs; absent asks for the generic option list. */ + intent?: AskUserQuestionIntent } ``` diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index d7cdc4e253..74d66a5631 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -1503,9 +1503,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'AskUserQuestionAnswerItem', declaration: 'export interface AskUserQuestionAnswerItem {\n id: string;\n selected: string[];\n custom?: string;\n}', }, + { + name: 'AskUserQuestionIntent', + declaration: 'export type AskUserQuestionIntent = {\n kind: \'plan-review\';\n approve: string;\n};', + }, { name: 'AskUserQuestionItem', - declaration: 'export interface AskUserQuestionItem {\n id: string;\n question: string;\n detail?: string;\n header?: string;\n options?: AskUserQuestionOption[];\n multiSelect?: boolean;\n}', + declaration: 'export interface AskUserQuestionItem {\n id: string;\n question: string;\n detail?: string;\n header?: string;\n options?: AskUserQuestionOption[];\n multiSelect?: boolean;\n intent?: AskUserQuestionIntent;\n}', }, { name: 'AskUserQuestionOption', diff --git a/packages/host/apiproxy/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts index 4e17b1f403..43b7a147e4 100644 --- a/packages/host/apiproxy/src/api/events.schema.ts +++ b/packages/host/apiproxy/src/api/events.schema.ts @@ -23,6 +23,11 @@ export const askUserQuestionItemSchema = z.object({ detail: z.string().optional(), options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(), multiSelect: z.boolean().optional(), + // Presentation intent: a tagged union on the wire, so an unknown tag is a + // rejected frame rather than a silently generic render. + intent: z.discriminatedUnion('kind', [ + z.object({ kind: z.literal('plan-review'), approve: z.string() }), + ]).optional(), }) satisfies z.ZodType> /** Unified message envelope carried by transient queue frames. */ diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts index 80cd0baf4c..0b4d0b78ee 100644 --- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts +++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts @@ -399,6 +399,17 @@ describe('events frame schemas', () => { expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow() }) + it('carries a question presentation intent through, and rejects an unknown one', () => { + const intent = { kind: 'plan-review', approve: 'Approve' } + expect(askUserQuestionItemSchema.parse({ + id: 'plan-review', question: 'Approve?', detail: '# Plan', options: [{ label: 'Approve' }], intent, + }).intent).toEqual(intent) + // An unrecognised tag is a rejected frame, not a silently generic render. + for (const invalid of [{ kind: 'plan-review' }, { kind: 'poll', approve: 'Approve' }, { approve: 'Approve' }]) { + expect(() => askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?', intent: invalid })).toThrow() + } + }) + it('rejects a queue snapshot with malformed items', () => { expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: 'x' })).toThrow() expect(() => muxFrameSchema.parse({ type: 'session/queue', sessionId: 's', items: [{ id: '', message: {} }] })).toThrow() diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml index c5a13bee7e..a4b6723b98 100644 --- a/packages/plan/plan-mode/README.i18n.yaml +++ b/packages/plan/plan-mode/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/plan/plan-mode/README.md -README.md: d3c2c14fe616e1c9b4e33b716570b084db6474cf -README.zh.md: 6d6878c4b0300a716ad16be60fd86bc79f1514ba +README.md: 6f0a9ac477b49b96ddfc2ce667e3556dec727569 +README.zh.md: 922b153aa1b08e1a6003f63736ea402787bff1dd diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md index d3c2c14fe6..6f0a9ac477 100644 --- a/packages/plan/plan-mode/README.md +++ b/packages/plan/plan-mode/README.md @@ -14,6 +14,8 @@ Logged, per-agent plan collaboration state with deployment-owned guidance, direc While active, `plan:policy` renders the configured `section`. The plugin always registers `exit_plan_mode`, keeping tool schemas stable across the transition; its execute path accepts only active plan mode and leaves it only after an exact user approval through `ctx.userInteraction`. +The review question declares the `plan-review` presentation intent, naming `Approve` as the label that approves it, so a capable UI presents the plan as a decision instead of a generic question; the answer the tool reads is the same either way. A dismissed review — the user closing the request to speak instead — is reported to the model as such, telling it to stay in plan mode and wait for the message; every other review failure keeps the seam's own message. + When `ctx.commands` is composed, the package registers `/plan [message]` and reserves the exact argument `off` for direct exit. Bare `/plan` selects plan mode; any other non-empty argument selects it first and is then submitted through `agent.steer()`, so it becomes the next step's ordinary logged user message under plan guidance. `/plan off` selects inactive without sending model input; it also cancels a pending entry before plan mode reaches a request. The TUI consumes the plugin-owned `/plan` command; other front doors may drive the same service directly without defining a second mode vocabulary. @@ -77,7 +79,7 @@ The user block is append-only conversation growth. Entering or leaving plan mode #### What the model sees -The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback. +The [`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) remains available in both states; execution outside plan mode fails, while an approved in-mode review returns the canonical `{ approved: true }` value and renders the existing confirmation text. Rejection remains a failed call carrying review feedback, and a dismissed review a failed call naming the user's takeover. #### Token effect @@ -92,4 +94,5 @@ Mode transitions do not change the tool catalog; plan arguments and review resul - Plan mode guides rather than enforces; deployments needing a hard boundary must combine independent sandbox and approval controls. - A pending selection made while idle is lost if the process exits before the next boundary, so the UI must reapply it. - Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option. -- The `exit_plan_mode` review arc (submit → human review → approved flip or rejected feedback) is covered by package tests only; its assembled-application snapshot left with the retired ACP UI scenarios ([automation-only ACP](../../../.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md)) and the TUI keyless scenarios exercise only `/plan` entry and `/plan off` exit. +- The `exit_plan_mode` review arc has one assembled-application snapshot, the Web `plan-review` e2e lane (submit → decision card → approved flip). The rejected-feedback and dismissed branches are covered by package tests only, and the TUI keyless scenarios exercise only `/plan` entry and `/plan off` exit. +- Only the Web UI renders the `plan-review` intent; the TUI presents the review through its generic question flow, which is answerable but does not read as a plan gate. diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md index 6d6878c4b0..922b153aa1 100644 --- a/packages/plan/plan-mode/README.zh.md +++ b/packages/plan/plan-mode/README.zh.md @@ -14,6 +14,8 @@ 激活时，`plan:policy` 会渲染已配置的 `section`。插件始终注册 `exit_plan_mode`，使工具 schema 在转换期间保持稳定；其 execute 路径只接受已激活的 plan mode，且只有通过 `ctx.userInteraction` 获得精确用户批准后才退出。 +评审问题声明 `plan-review` 呈现意图，并指名 `Approve` 为表示批准的标签，因此有能力的 UI 会把计划呈现为一次决定而非通用问题；两种情况下该工具读到的回答完全相同。放弃审阅 —— 用户关掉请求改用说话 —— 会如实报告给模型，要求它留在 plan mode 中等待那条消息；其余每一种评审失败都保留 seam 自身的消息。 + 组合 `ctx.commands` 时，该包（package）会注册 `/plan [message]`，并保留精确参数 `off` 用于直接退出。不带参数的 `/plan` 选择 plan mode；任何其他非空参数都会先选择 plan mode，再通过 `agent.steer()` 提交，因此它会在 plan 引导下成为下一步骤的常规已记录用户消息。`/plan off` 选择未激活状态，不发送模型输入；它还可以在 plan mode 进入选择到达请求之前取消该待生效选择。 TUI 消费插件拥有的 `/plan` 命令；其他入口可以直接驱动同一服务，无需定义第二套 mode 词汇。 @@ -77,7 +79,7 @@ You are in plan mode. Explore and design before presenting the complete plan thr #### 模型所见内容 -[`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) 在两种状态下均可用；在 plan mode 外执行会失败，而 plan mode 内经批准的评审会返回规范 `{ approved: true }` 值，并渲染现有确认文本。拒绝仍是携带评审反馈的失败调用。 +[`exit_plan_mode` schema](../../../docs/tool-catalog.md#deepseek-aidsh-plan-mode) 在两种状态下均可用；在 plan mode 外执行会失败，而 plan mode 内经批准的评审会返回规范 `{ approved: true }` 值，并渲染现有确认文本。拒绝仍是携带评审反馈的失败调用，放弃审阅则是一次指明用户接手的失败调用。 #### Token 影响 @@ -92,4 +94,5 @@ Mode 转换不改变工具目录；plan 参数与评审结果按常规方式扩 - Plan mode 只进行引导，而不强制执行；需要硬边界的部署必须组合独立的沙箱与批准控制。 - 如果进程在下一个边界之前退出，空闲时作出的待生效选择会丢失，因此 UI 必须重新应用它。 - Fork 的 agent 会继承已记录的 plan 状态，新 spawn 的 agent 则从未激活状态开始；不存在创建时 plan 选项。 -- `exit_plan_mode` 评审弧（提交 → 人类评审 → 已批准切换或已拒绝反馈）仅由包测试覆盖；其组装应用快照随已退役 ACP UI 场景一起离开（[仅面向自动化的 ACP](../../../.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md)），TUI 无密钥场景只演练 `/plan` 进入和 `/plan off` 退出。 +- `exit_plan_mode` 评审弧有一个组装应用快照，即 Web `plan-review` e2e 通道（提交 → 决定卡片 → 已批准切换）。已拒绝反馈与放弃审阅两个分支仅由包测试覆盖，TUI 无密钥场景只演练 `/plan` 进入和 `/plan off` 退出。 +- 只有 Web UI 渲染 `plan-review` 意图；TUI 通过其通用问题流程呈现该评审，可以回答，但读起来不像一个计划关口。 diff --git a/packages/plan/plan-mode/src/index.ts b/packages/plan/plan-mode/src/index.ts index dc6b788825..b2a5f6076d 100644 --- a/packages/plan/plan-mode/src/index.ts +++ b/packages/plan/plan-mode/src/index.ts @@ -29,7 +29,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm' import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' import { defineTool } from '@deepseek-ai/dsh-tools' import type {} from '@deepseek-ai/dsh-system-prompt' -import type {} from '@deepseek-ai/dsh-user-interaction' +import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction' // Type-only edge: resolves `ctx.commands` for the optional command child. import type {} from '@deepseek-ai/dsh-commands' // Type-only: resolves ctx.sessionProjections for the optional unit child. @@ -70,6 +70,9 @@ export interface PlanModeConfig { section: string } +/** The review question's id, echoed in the answer this tool reads. */ +const REVIEW_ID = 'plan-review' + /** The review question's approve option label. */ const APPROVE_LABEL = 'Approve' @@ -317,7 +320,7 @@ export class PlanModeService extends Service { } const answer = await interaction.ask({ questions: [{ - id: 'plan-review', + id: REVIEW_ID, header: 'Plan review', question: 'Approve this plan and leave plan mode?', detail: args.plan, @@ -325,16 +328,31 @@ export class PlanModeService extends Service { { label: APPROVE_LABEL, description: 'Leave plan mode; the plan is carried out from the next step.' }, { label: KEEP_PLANNING_LABEL, description: 'Stay in plan mode; feedback goes back to the model.' }, ], + // Presentation only: a capable UI renders the plan as a review + // decision instead of a generic question, and answers with one of + // the labels above either way. + intent: { kind: 'plan-review', approve: APPROVE_LABEL }, }], agent, signal: exec.signal, + }).catch((cause: unknown) => { + // A dismissed review is not a failed one: the user took the turn back + // to say something the two options do not cover. Say so, because the + // generic channel message names ask_user_question, which the model + // never called. An abort (turn cancel, provider teardown) keeps its + // own message — there is no user to wait for. + if (cause instanceof UserInteractionError && cause.code === 'ASK_CANCELLED') { + throw new Error('The user dismissed the plan review to speak instead; ' + + 'stay in plan mode, stop here, and wait for their message.') + } + throw cause }) // A review may outlive this plugin fiber. Without boundary listeners, // an approved result could never land, so fail and keep planning. if (disposed) { throw new Error('the plan-mode service was reloaded while the plan was under review; present the plan again') } - const reviewItems = answer.answers.filter(entry => entry.id === 'plan-review') + const reviewItems = answer.answers.filter(entry => entry.id === REVIEW_ID) const item = reviewItems.length === 1 ? reviewItems[0] : undefined if (item?.selected.length !== 1 || item.selected[0] !== APPROVE_LABEL || item.custom !== undefined) { const feedback = item?.custom ?? '' diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts index 72d273d20f..6fa165cbb0 100644 --- a/packages/plan/plan-mode/tests/plan-mode.spec.ts +++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts @@ -6,7 +6,9 @@ import ToolRegistry, { RUN_CODE_NAME, defineContentToolFixture } from '@deepseek import { Session, SessionId } from '@deepseek-ai/dsh-session' import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent' import { createScope } from '@deepseek-ai/dsh-scope' -import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction' +import UserInteractionService, { + UserInteractionError, type AskUserQuestionRequest, +} from '@deepseek-ai/dsh-user-interaction' import CommandService from '@deepseek-ai/dsh-commands' import { CodeRuntime, type CodeRunRequest, type CodeRunResult } from '@deepseek-ai/dsh-code-runtime' import PlanModeService, { EXIT_PLAN_MODE, foldPlanMode, resolveConfig } from '../src/index.ts' @@ -894,6 +896,40 @@ describe('exit_plan_mode', () => { expect(result.content).toEqual([{ type: 'text', text: 'Error: The user chose to keep planning; revise the plan and present it again.' }]) }) + it('declares the plan-review presentation intent naming its approve option', async () => { + const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] }) + await callExit(ctx, agent) + const question = asked[0]?.questions[0] + expect(question?.intent).toEqual({ kind: 'plan-review', approve: 'Approve' }) + // The named label is one this same question offers, so a UI honouring the + // intent answers a choice this tool accepts. + expect(question?.options?.map(option => option.label)).toContain(question?.intent?.approve) + }) + + it('reads a dismissed review as the user taking the turn back, not as a failure', async () => { + const { ctx, agent } = await setupWithReview() + ctx.userInteraction.registerProvider({ + ask: () => Promise.reject(new UserInteractionError( + 'the user cancelled ask_user_question', 'ASK_CANCELLED')), + }) + const result = await callExit(ctx, agent) + expect(result.isError).toBe(true) + expect(result.content).toEqual([{ type: 'text', text: 'Error: The user dismissed the plan review to speak instead; stay in plan mode, stop here, and wait for their message.' }]) + expect(foldPlanMode(agent.session.events)).toBe(true) + }) + + it('leaves every other review failure its own message', async () => { + const { ctx, agent } = await setupWithReview() + ctx.userInteraction.registerProvider({ + ask: () => Promise.reject(new UserInteractionError( + 'ask_user_question was aborted before the user answered', 'ASK_ABORTED')), + }) + const result = await callExit(ctx, agent) + expect(result.isError).toBe(true) + expect(result.content).toEqual([{ type: 'text', text: 'Error: ask_user_question was aborted before the user answered' }]) + expect(foldPlanMode(agent.session.events)).toBe(true) + }) + it('forwards the execution abort signal to the review question', async () => { const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] }) const controller = new AbortController() diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml index 98e40aa0d3..96973400df 100644 --- a/packages/ui/user-interaction/README.i18n.yaml +++ b/packages/ui/user-interaction/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/ui/user-interaction/README.md -README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32 -README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79 +README.md: f134e912149190efb81ea9f64c5d63632ce8c626 +README.zh.md: ab6432dcbddc36d3ef9ca957b3901cb76257539a diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md index d234d6677b..f134e91214 100644 --- a/packages/ui/user-interaction/README.md +++ b/packages/ui/user-interaction/README.md @@ -13,14 +13,19 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod ### Key Types -- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label. +- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label. - `AskUserQuestionOption` — `{ label, description? }`. +- `AskUserQuestionIntent` — `{ kind: 'plan-review', approve }`; the tagged presentation intent below. - `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`. - `UserInteractionProvider` — UI implementation with `ask(request)`. -- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`. +- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `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. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch. +### Presentation intent + +`intent` declares that a question IS a decision of a known shape, so a UI that recognises the tag may present it as such — `plan-review` says `detail` is a plan under review, and `dsh-plan-mode` sets it on the `exit_plan_mode` question. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, and a UI that does not know the tag renders the generic option list, so callers read one answer shape either way. `approve` names the label that approves rather than relying on option order; `ask()` rejects an intent whose `approve` names none of that question's own options with `BAD_INTENT`, since no type can tie the two together. + ## Role This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; `dsh-tui` and the host runtime provide interactive implementations. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop. diff --git a/packages/ui/user-interaction/README.zh.md b/packages/ui/user-interaction/README.zh.md index c89210b695..ab6432dcbd 100644 --- a/packages/ui/user-interaction/README.zh.md +++ b/packages/ui/user-interaction/README.zh.md @@ -13,14 +13,19 @@ ### 关键类型 -- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。 +- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。 - `AskUserQuestionOption`：`{ label, description? }`。 +- `AskUserQuestionIntent`：`{ kind: 'plan-review', approve }`；即下文的带标签呈现意图。 - `AskUserQuestionAnswer`：`{ answers: [{ id, selected, custom? }] }`。 - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。 -- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。 +- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。 当回答包含 `custom` 时，`selected` 为空；自定义文本是所选选项的替代，而不是补充。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。 +### 呈现意图 + +`intent` 声明某个问题本身就是一次已知形状的决定，因此认识该标签的 UI 可以照此呈现 —— `plan-review` 表示 `detail` 是一份待审阅的计划，`dsh-plan-mode` 会在 `exit_plan_mode` 的问题上设置它。意图只塑造呈现：遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，不认识该标签的 UI 渲染通用选项列表，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名表示批准的标签，而不依赖选项顺序；由于没有类型能把两者绑定起来，`ask()` 会以 `BAD_INTENT` 拒绝 `approve` 未命中该问题自身任一选项的意图。 + ## 职责 这是接口包（package）。`@deepseek-ai/dsh-tool-ask-user` 等面向模型的消费方依赖此 seam；`dsh-tui` 和宿主运行时提供交互式实现。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。 diff --git a/packages/ui/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts index 4b5caf6a55..af0aa40e7b 100644 --- a/packages/ui/user-interaction/src/index.ts +++ b/packages/ui/user-interaction/src/index.ts @@ -20,7 +20,8 @@ declare module 'cordis' { import type { AskUserQuestionAnswer, AskUserQuestionItem } from './types.ts' export type { - AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionOption, + AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionIntent, AskUserQuestionItem, + AskUserQuestionOption, } from './types.ts' /** Request for a human answer. */ @@ -86,6 +87,20 @@ export class UserInteractionService extends Service { if (request.questions.length === 0) { throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS') } + // A presentation intent names an option label the types cannot pin to its + // own question's option list. A UI honouring the intent answers with that + // label, so a name matching nothing would answer a choice the asker never + // offered — caught here, at the asker, rather than in a UI. + for (const question of request.questions) { + const intent = question.intent + if (intent === undefined) continue + if (!(question.options ?? []).some(option => option.label === intent.approve)) { + throw new UserInteractionError( + `question ${question.id} declares intent ${intent.kind} whose approve label ` + + `${JSON.stringify(intent.approve)} names none of its options`, + 'BAD_INTENT') + } + } if (this.provider === undefined) { throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER') } diff --git a/packages/ui/user-interaction/src/types.ts b/packages/ui/user-interaction/src/types.ts index ddf3e43489..15747e371c 100644 --- a/packages/ui/user-interaction/src/types.ts +++ b/packages/ui/user-interaction/src/types.ts @@ -13,6 +13,24 @@ export interface AskUserQuestionOption { description?: string } +/** + * A caller-declared presentation intent: the question IS a decision of this + * shape, so a UI that recognises the tag may present it as such instead of as a + * generic option list. Tagged so further intents can be added; a UI that does + * not know a tag renders the generic flow, and the answer encoding is identical + * either way — an intent shapes presentation only, never the protocol. + */ +export type AskUserQuestionIntent = { + /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + kind: 'plan-review' + /** + * The option label that approves the plan; every other option declines it. + * Named rather than positional so no UI infers the verdict from option order. + * An `approve` naming no option of its own question is rejected at `ask()`. + */ + approve: string +} + /** One question in a user-interaction request. */ export interface AskUserQuestionItem { /** Stable caller-provided question id, echoed in the answer. */ @@ -27,6 +45,8 @@ export interface AskUserQuestionItem { options?: AskUserQuestionOption[] /** Whether more than one option may be selected. Defaults to single-select. */ multiSelect?: boolean + /** Optional presentation intent for capable UIs; absent asks for the generic option list. */ + intent?: AskUserQuestionIntent } /** Answer to one question. */ diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/ui/user-interaction/tests/user-interaction.spec.ts index adfbc9d4bb..e9fca39761 100644 --- a/packages/ui/user-interaction/tests/user-interaction.spec.ts +++ b/packages/ui/user-interaction/tests/user-interaction.spec.ts @@ -83,4 +83,45 @@ describe('UserInteractionService', () => { .rejects.toMatchObject({ name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' }) expect(p.ask).not.toHaveBeenCalled() }) + + it('rejects an intent whose approve label names none of its own options', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = { ask: vi.fn(async () => ({ answers: [] })) } + ctx.userInteraction.registerProvider(p) + const question = { id: 'plan-review', question: 'Approve?', detail: '# Plan' } + + // A wrong label among offered options, and no options offered at all. + for (const options of [[{ label: 'Approve' }], undefined]) { + await expect(ctx.userInteraction.ask({ + questions: [{ + ...question, + ...(options === undefined ? {} : { options }), + intent: { kind: 'plan-review', approve: 'Ship it' }, + }], + })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'BAD_INTENT' }) + } + expect(p.ask).not.toHaveBeenCalled() + }) + + it('passes an intent through once its approve label names an offered option', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = provider('Approve') + ctx.userInteraction.registerProvider(p) + const intent = { kind: 'plan-review', approve: 'Approve' } as const + + const result = await ctx.userInteraction.ask({ + questions: [ + { id: 'plain', question: 'Proceed?' }, + { + id: 'plan-review', question: 'Approve?', detail: '# Plan', + options: [{ label: 'Approve' }, { label: 'Keep planning' }], intent, + }, + ], + }) + + expect(result.answers).toEqual([{ id: 'plain', selected: ['Approve'] }]) + expect(p.seen[0]?.questions[1]?.intent).toEqual(intent) + }) }) diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index d886b33df2..8a5eebdd7d 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -694,6 +694,11 @@ "symbol": "AskUserQuestionOption", "source": "packages/ui/user-interaction/src/types.ts" }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionIntent", + "source": "packages/ui/user-interaction/src/types.ts" + }, { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", From 2363ef01eb14560ecce3cdede09b48a3280122e5 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 19:09:35 +0800 Subject: [PATCH 40/67] feat(web): render a plan review as a decision card, not a quiz MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Web composer now renders a request that declares the `plan-review` intent as its own surface: the waiting-approval card language — amber "Plan review" strip, the plan as the scrolling markdown body, the question as the card's accessible name — over one decision row of Chat about it / Refuse / Approve. Gone from that surface are the 1/1 pager, the numbered radio rows, the custom answer row, and Skip/Submit, which made approving a plan read as sitting an exam. Approve and Refuse answer with the asker's own option labels and keep its descriptions as tooltips; Chat about it cancels the request so the composer returns and the user can simply say what they want. Copy is bilingual under the existing `question` namespace. The shape choice lives inside the single composer entry rather than a second chain registration, so the two surfaces cannot race the same carrier, and `planReviewOf` falls back to the generic flow for any request it cannot render as a card — the client sits downstream of a wire boundary and every request must stay answerable. --- ...-plan-review-presentation-intent.i18n.yaml | 6 + ...6-07-30-plan-review-presentation-intent.md | 55 +++++ ...7-30-plan-review-presentation-intent.zh.md | 55 +++++ apps/web/tests/plan-review.e2e.ts | 113 +++++++++ .../plan-review/approved.expected.md | 51 ++++ .../snapshots/plan-review/review.expected.md | 44 ++++ .../tests/snapshots/plan-review/session.jsonl | 39 ++++ packages/client/ui-question/README.i18n.yaml | 4 +- packages/client/ui-question/README.md | 2 + packages/client/ui-question/README.zh.md | 2 + .../src/client/PlanReviewPanel.module.css | 113 +++++++++ .../src/client/PlanReviewPanel.tsx | 100 ++++++++ .../src/client/QuestionComposer.tsx | 17 +- .../ui-question/src/client/contract/slots.ts | 59 +++++ .../client/ui-question/src/client/index.ts | 12 +- .../client/ui-question/src/client/locales.ts | 8 + .../tests/plan-review-panel.spec.tsx | 221 ++++++++++++++++++ 17 files changed, 894 insertions(+), 7 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md create mode 100644 .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md create mode 100644 apps/web/tests/plan-review.e2e.ts create mode 100644 apps/web/tests/snapshots/plan-review/approved.expected.md create mode 100644 apps/web/tests/snapshots/plan-review/review.expected.md create mode 100644 apps/web/tests/snapshots/plan-review/session.jsonl create mode 100644 packages/client/ui-question/src/client/PlanReviewPanel.module.css create mode 100644 packages/client/ui-question/src/client/PlanReviewPanel.tsx create mode 100644 packages/client/ui-question/tests/plan-review-panel.spec.tsx diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml new file mode 100644 index 0000000000..3de0b88f5c --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md +2026-07-30-plan-review-presentation-intent.md: aa85156d87a35d049f3cfab465fc668a63781a73 +2026-07-30-plan-review-presentation-intent.zh.md: fffee3de6341d45b26b88e1cc67a3895e747afac diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md new file mode 100644 index 0000000000..aa85156d87 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md @@ -0,0 +1,55 @@ +# Agent Note: Plan review as a decision, not a question + +Status: implemented + +English | [中文](2026-07-30-plan-review-presentation-intent.zh.md) + +## Problem + +`exit_plan_mode` presents a finished plan for review through `ctx.userInteraction.ask()`, the same seam `ask_user_question` uses. On the Web GUI that made a plan review render as the generic question flow of [the ask-question Web presentation](2026-07-29-ask-question-web-presentation.md): a `1 / 1` pager, the plan as a question's supporting detail, the two verdicts as numbered radio rows with descriptions, an "Other — enter a custom answer" row, and `Skip this question` / `Submit` in the footer. + +Every one of those affordances is wrong for the surface. Reviewing a plan is one decision over one document, and the quiz chrome told the user they were being examined rather than asked to approve work — reported as "让人很困惑以为在做题". The paging controls page a set of one. Skipping is not an outcome the tool accepts (it folds into keep-planning). Worst, the surface gave no hint that this was the plan gate at all, while the adjacent waiting-approval takeover already had exactly the right shape for a decision: a tinted strip naming what is being decided, the subject as the body, and a right-aligned action row. + +## Decision + +A question may declare a **presentation intent**, and the Web composer renders a declared intent as its own surface. `AskUserQuestionItem` gains `intent?: AskUserQuestionIntent`, a tagged shape whose one member is `{ kind: 'plan-review', approve: string }`; `plan-mode` sets it on the review question, naming `Approve` as the label that approves. + +An intent shapes presentation only. The answer protocol is untouched: a UI honouring the intent answers with the same option labels a generic UI would send, so `exit_plan_mode` reads one answer shape regardless of which surface collected it, and a UI that does not know a tag renders the generic flow with nothing lost but the layout. + +`approve` names the affirmative option instead of relying on option order, so no UI infers a verdict from a position. Because the types cannot tie that label to the question's own option list, `UserInteractionService.ask()` rejects an intent whose `approve` names none of its options (`BAD_INTENT`) — at the asker, before any UI can answer a choice that was never offered. On the wire the intent is a discriminated union, so an unrecognised tag is a rejected frame rather than a silently generic render. + +`ui-question` renders the intent as `PlanReviewPanel`, in the waiting-approval card language: the amber strip carries `Plan review`, the plan is the scrolling markdown body, and the decision row holds three actions — `Chat about it`, `Refuse`, `Approve`. The question text becomes the card's accessible name rather than a headline, because the buttons already say what the decision is. Approve and Refuse answer with the asker's own option labels and keep the asker's descriptions as tooltips; `Chat about it` cancels the request, which returns the composer so the user can simply say what they want. All copy is bilingual under the existing `question` namespace. + +Routing lives inside the single composer entry (`QuestionComposer` chooses the shape) rather than in a second chain registration, and `planReviewOf` claims a request only when the batch is one question that declares the intent, carries the plan as its `detail`, and offers the named approve label. Anything else stays a generic question — the client is downstream of a wire boundary, so a request it cannot render as a card must still be answerable. + +Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reached the model as "the user cancelled ask_user_question", naming a tool it never called; `exit_plan_mode` now reports that the user dismissed the review to speak instead and to stay in plan mode and wait. Every other ask failure — an abort from turn cancel or provider teardown, where no user is coming — keeps its own message. + +## Alternatives considered + +**Make plan review its own pending kind (`plan-review/requested`).** Rejected as the wrong size for a presentation problem. It buys an honest response shape (approve / decline / discuss instead of an answer batch) at the cost of a third `PendingKind`, new requested/resolved frames and schemas, an api-proxy registry and respond branch, client session and baseline-replay handling, and a new three-package capability seam for a decision the question protocol already expresses. Worth revisiting only if plan review grows outcomes the answer shape cannot carry. + +**Route the card on the question's `id` or `header` (`plan-review` / `Plan review`).** Rejected: string-sniffing a foreign package's copy across a wire boundary, which any wording change silently breaks. The intent is the declaration that makes the routing legible. + +**Order the options and let the card read position 0 as approve.** Rejected: a positional contract at a package seam, invisible in both the type and the wire frame, and unenforceable — a producer that reorders its options would invert a user's verdict. Naming the label costs one string. + +**Register a second composer-chain entry for the plan card.** Rejected: two entries would select over the same pending question carrier, making the surface depend on chain priority and on whether the plan package's client half is composed at all. One entry that picks its own shape cannot race itself, and the generic flow is the built-in fallback. + +**Put the panel in `ui-plan` beside the plan chip.** Rejected: the panel's whole behavior is the question carrier's answer encoding (`PendingQuestion`), which `ui-question` owns; the intent is a question-protocol field, not plan-mode's private channel. Rendering declared intents belongs to the package that owns question rendering, as tool render intents belong to the tool renderer. + +**Extract a shared takeover card with `ui-conversation`'s `ApprovalPanel`.** Not done: the two takeovers agree on tokens and geometry but not on content — this body is scrolling markdown, that one a headline plus a command line — and the shared shell would be two elements wide. They are kept in step by token, not by component. + +**Give `Chat about it` its own protocol outcome.** Rejected: dismissing a request is a verb the generic flow already has (the `×` that cancels the batch). Promoting it to a labelled button is presentation; inventing a fourth wire outcome for it is not. + +## Consequences + +The question protocol now carries a presentation axis. Adding a second intent is a tag on the union, a producer that sets it, a schema member, and a panel — no new frame, service, or answer shape. The cost is that the question seam knows presentation exists at all, and that `ui-question` knows the word "plan"; both are the price of one entry owning every question surface. + +The plan gate reads as a plan gate: the plan is the card's content, the verdict is two labelled buttons, and taking the turn back is a third. The generic flow is untouched for every other question, and its committed goldens did not move. + +A deployment whose client half predates this change still shows the quiz layout — correct, answerable, and merely unstyled — because the intent is additive and the fallback is the generic flow. + +## Testing + +`ui-question` tests pin the narrowing (single-question batch, intent present, plan as detail, named approve label offered, decline absent when only approve is offered) and the panel (strip, markdown plan, accessible name, absence of pager/radio/skip/custom, approve and decline answering with the asker's labels, dismissal cancelling, one-shot latch with re-arm and message on a rejected receipt, tooltips present and absent, both locales). `user-interaction` tests pin `BAD_INTENT` and intent pass-through; `plan-mode` tests pin the declared intent against its own option list and both failure messages; the apiproxy schema test pins wire acceptance and an unknown tag's rejection. + +The `plan-review` Web e2e lane records `/plan` entering plan mode for real, the model calling `exit_plan_mode`, the decision card taking the composer (asserting the generic flow did **not** claim the request), and the card's own Approve completing the turn — two keyless goldens, the waiting card and the approved transcript. diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md new file mode 100644 index 0000000000..fffee3de63 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md @@ -0,0 +1,55 @@ +# Agent Note：计划审阅是一次决定，不是一道题 + +Status: implemented + +[English](2026-07-30-plan-review-presentation-intent.md) | 中文 + +## 问题 + +`exit_plan_mode` 通过 `ctx.userInteraction.ask()` 把写好的计划交给用户审阅，而这正是 `ask_user_question` 使用的同一个 seam。在 Web GUI 上，这导致计划审阅渲染为[ask-question Web 呈现](2026-07-29-ask-question-web-presentation.md)里的通用问题流程：一个 `1 / 1` 分页器、计划作为问题的补充说明、两个裁决作为带描述的编号单选行、一行"其他，请填写自定义答案"，以及底部的 `跳过本题` / `提交`。 + +这些可交互元素对这个界面而言无一正确。审阅一份计划是对一份文档做一次决定，而做题式的界面告诉用户他正在被考试，而不是被请求批准一份工作 —— 实际反馈是"让人很困惑以为在做题"。分页控件在给只有一项的集合分页。跳过并不是该工具接受的结果（它会折叠成继续规划）。最糟的是，这个界面完全没有暗示这就是计划关口，而旁边的等待审批接管早就具备了一次决定该有的形状：一条带色条带说明正在决定什么、主体是决定的对象、右对齐的操作行。 + +## 决定 + +一个问题可以声明**呈现意图（presentation intent）**，Web 输入区把已声明的意图渲染为它自己的界面。`AskUserQuestionItem` 新增 `intent?: AskUserQuestionIntent`，一个带标签的形状，目前唯一成员是 `{ kind: 'plan-review', approve: string }`；`plan-mode` 在审阅问题上设置它，并指明 `Approve` 是表示批准的标签。 + +意图只塑造呈现。回答协议不变：遵循意图的 UI 回答的仍是通用 UI 会发送的那些选项标签，因此无论由哪个界面收集，`exit_plan_mode` 读到的都是同一种回答形状；而不认识某个标签的 UI 渲染通用流程，除布局之外一无所失。 + +`approve` 指名肯定选项，而不依赖选项顺序，因此没有任何 UI 会从位置推断裁决。由于类型无法把该标签绑定到问题自身的选项列表，`UserInteractionService.ask()` 会拒绝 `approve` 未命中任一选项的意图（`BAD_INTENT`）—— 拦在提问方一侧，早于任何 UI 回答一个从未被提供过的选择。在协议格式（wire format）上意图是可辨识联合，因此无法识别的标签是被拒绝的帧，而不是静默退回通用渲染。 + +`ui-question` 把该意图渲染为 `PlanReviewPanel`，沿用等待审批卡片的语言：琥珀色条带写着 `Plan review`，计划是可滚动的 markdown 主体，决定行放三个操作 —— `Chat about it`、`Refuse`、`Approve`。问题文本成为卡片的无障碍名称而非标题，因为按钮已经说明了这次决定是什么。Approve 与 Refuse 用提问方自己的选项标签回答，并把提问方的描述保留为 tooltip；`Chat about it` 取消该请求，从而让输入区归位，用户直接说他想说的话即可。所有文案在既有 `question` 命名空间下双语。 + +路由住在单一输入区条目内部（由 `QuestionComposer` 选择形状），而不是第二个链式注册；`planReviewOf` 仅在这一批只有一个问题、该问题声明了意图、以 `detail` 承载计划、并提供了被指名的批准标签时才接管请求。其他情形一律保持通用问题 —— 客户端位于协议边界的下游，它无法渲染成卡片的请求仍必须可回答。 + +放弃审阅成为面向模型的独立结果。`ASK_CANCELLED` 以前传到模型的是"the user cancelled ask_user_question"，指名了一个它从未调用的工具；现在 `exit_plan_mode` 报告用户放弃审阅是为了改用说话，并要求留在 plan mode 中等待。其余每一种 ask 失败 —— 轮次取消或提供方拆卸导致的中止，那里并没有用户会来 —— 保留它们自己的消息。 + +## 备选方案 + +**让计划审阅成为自己的待处理种类（`plan-review/requested`）。** 否决：对一个呈现问题来说尺寸不对。它换来的是诚实的响应形状（approve / decline / discuss 而非一批回答），代价是第三个 `PendingKind`、新的 requested/resolved 帧与 schema、一个 api-proxy 注册表与响应分支、客户端会话与基线重放处理，以及为一个问题协议已能表达的决定新增一个三包能力 seam。只有当计划审阅长出回答形状承载不了的结果时才值得重新考虑。 + +**按问题的 `id` 或 `header`（`plan-review` / `Plan review`）路由卡片。** 否决：这是跨协议边界嗅探另一个包的文案字符串，任何措辞改动都会静默破坏它。意图才是让路由可读的那个声明。 + +**约定选项顺序，让卡片把第 0 个位置读作批准。** 否决：这是包边界上的位置约定，在类型和协议帧里都看不见，也无法强制 —— 生产方一旦重排选项，就会颠倒用户的裁决。指名标签只花一个字符串。 + +**为计划卡片注册第二个输入区链条目。** 否决：两个条目会对同一个待回答问题载体做选择，使界面取决于链优先级、以及计划包的客户端半边是否被组合。一个自己挑形状的条目不会和自己抢，而通用流程正是内建的回退。 + +**把面板放在 `ui-plan` 里、紧挨计划状态标签。** 否决：面板的全部行为就是问题载体的回答编码（`PendingQuestion`），那是 `ui-question` 拥有的；意图是问题协议的字段，不是 plan-mode 的私有通道。渲染已声明的意图属于拥有问题渲染的那个包，正如工具渲染意图属于工具渲染方。 + +**与 `ui-conversation` 的 `ApprovalPanel` 抽出共享的接管卡片。** 未做：两个接管在 token 和几何上一致，但内容不一致 —— 这边的主体是可滚动 markdown，那边是一行标题加一行命令 —— 共享外壳只会剩两个元素宽。它们靠 token 保持一致，而不是靠组件。 + +**给 `Chat about it` 自己的协议结果。** 否决：放弃一个请求是通用流程已有的动词（取消整批的 `×`）。把它提升为带标签的按钮属于呈现；为它发明第四种协议结果不属于。 + +## 结果 + +问题协议从此带有一个呈现轴。新增第二个意图 = 联合上的一个标签、一个设置它的生产方、一个 schema 成员、一个面板 —— 不需要新的帧、服务或回答形状。代价是问题 seam 从此知道"呈现"这件事存在，且 `ui-question` 知道"plan"这个词；两者都是由单一条目拥有全部问题界面所要付的价钱。 + +计划关口读起来就像计划关口：计划是卡片的内容，裁决是两个带标签的按钮，把轮次拿回来是第三个。通用流程对其他每个问题都未受影响，其已提交的 golden 也没有变动。 + +客户端半边早于本次改动的部署仍然显示做题式布局 —— 正确、可回答、只是没有专门样式 —— 因为意图是增量的，而回退就是通用流程。 + +## 测试 + +`ui-question` 测试钉住收窄（单问题批、意图存在、计划作为 detail、被指名的批准标签确实被提供、只提供批准时 decline 缺席）与面板（条带、markdown 计划、无障碍名称、无分页/单选/跳过/自定义、批准与拒绝用提问方的标签回答、放弃触发取消、一次性闭锁在回执被拒时重新武装并给出消息、tooltip 有与无、两种语言）。`user-interaction` 测试钉住 `BAD_INTENT` 与意图透传；`plan-mode` 测试钉住已声明的意图与其自身选项列表的一致、以及两条失败消息；apiproxy schema 测试钉住协议接受与未知标签的拒绝。 + +`plan-review` Web e2e 通道录制了 `/plan` 真实进入 plan mode、模型调用 `exit_plan_mode`、决定卡片接管输入区（并断言通用流程**没有**接管该请求）、以及卡片自身的 Approve 完成该轮 —— 两份无密钥 golden：等待中的卡片与批准后的会话记录。 diff --git a/apps/web/tests/plan-review.e2e.ts b/apps/web/tests/plan-review.e2e.ts new file mode 100644 index 0000000000..28272777fb --- /dev/null +++ b/apps/web/tests/plan-review.e2e.ts @@ -0,0 +1,113 @@ +// Web e2e scenario: the plan-review takeover. The shipped composition mounts +// plan mode and its client seat, so `/plan ` enters plan mode for real +// and the recorded turn ends on exit_plan_mode blocking against the live +// userInteraction seam. The composer is then occupied by the plan decision +// card — not the generic question flow — and approving it through the card +// completes the turn with the approval in the log. +// Replay is deterministic: the plan content arrives from replayed chunks, the +// review wait is real, and the approve click is the test's own gesture (the +// turn cannot complete without it, in record and replay alike). +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' +import { join } from 'node:path' +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { + assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, + launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/plan-review', import.meta.url)) +const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl') +// The waiting golden owns the decision card; the approved golden owns the +// transcript the approval leaves behind — the state the card cannot see. +const REVIEW_EXPECTED = join(SNAPSHOT_DIR, 'review.expected.md') +const APPROVED_EXPECTED = join(SNAPSHOT_DIR, 'approved.expected.md') +const MODE = webSnapshotMode() + +// One command line: /plan enters plan mode and submits the rest as the turn's +// message. The task is deliberately self-contained (nothing to explore in a +// fresh workspace) so the recorded turn is a plan and its review, and the +// approved continuation is one word. +const TASK = 'Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. ' + + 'Call exit_plan_mode with a short plan of at most five bullet points. ' + + 'Once the plan is approved, reply with the single word DONE and stop.' +const LINE = `/plan ${TASK}` + +describe('web e2e: plan review takeover round trip', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + const sessionEvents: SessionEvent[] = [] + + beforeAll(async () => { + scaffold = await launchWebScaffold(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 15 }) + scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) }) + browser = await chromium.launch() + // English page: the decision copy is the surface under test, and the + // golden pins one language. + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.baseUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + await connectFreshWorkspace(page) + }, 120_000) + + afterAll(async () => { + await browser?.close() + await scaffold?.close() + }) + + it('reviews the plan on a decision card and approves through it', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-plan-review')) + if (MODE !== 'record') { + expect(fixtureUserPrompts(await readFile(FIXTURE, 'utf8'))).toEqual([TASK]) + } + const input = page.locator('textarea').first() + await input.waitFor({ timeout: 10_000 }) + const settled = scaffold.whenTurnSettled(MODE === 'record' ? 180_000 : 30_000) + await input.fill(LINE) + await input.press('Enter') + + // The card takes over the input area while exit_plan_mode blocks. Its + // presence is a STABLE waiting state (it stays until answered), so a plain + // waitFor is race-free. + const card = page.locator('[data-plan-review-key]') + await card.waitFor({ timeout: MODE === 'record' ? 120_000 : 30_000 }) + // The plan-review request must NOT land on the generic question flow. + expect(await page.locator('[data-question-key]').count()).toBe(0) + await expect.poll(() => card.getByText('Plan review').count(), { timeout: 10_000 }).toBeGreaterThan(0) + + if (MODE !== 'record') { + const snapshot = await captureStableAria(page, '[data-plan-review-key]', scaffold.workspaceCwd) + await compareOrRefreshGolden(REVIEW_EXPECTED, snapshot, MODE) + } + + await card.getByRole('button', { name: 'Approve' }).click() + + const sessionId = await settled + if (MODE === 'record') { + await recordFixture(scaffold, sessionId, FIXTURE) + return + } + // World state: the approval reached the tool, and plan mode is left behind. + const results = sessionEvents.filter(e => e.type === 'tool/result') + expect(JSON.stringify(results.at(-1))).toContain('Plan approved') + await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1) + // Card gone; regular input restored. + expect(await page.locator('[data-plan-review-key]').count()).toBe(0) + await expect.poll(() => page.locator('textarea').first().isEnabled(), { timeout: 10_000 }).toBe(true) + const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(APPROVED_EXPECTED, snapshot, MODE) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 200_000) + + it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { + await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl', 'review.expected.md', 'approved.expected.md']) + }) +}) diff --git a/apps/web/tests/snapshots/plan-review/approved.expected.md b/apps/web/tests/snapshots/plan-review/approved.expected.md new file mode 100644 index 0000000000..aca0bc31bb --- /dev/null +++ b/apps/web/tests/snapshots/plan-review/approved.expected.md @@ -0,0 +1,51 @@ +- banner: + - navigation "Session hierarchy": + - 'button "Plan a small change: add" [disabled]' + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- img +- text: "/plan Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. Plan mode on. Use /plan off to leave. Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. {{clock}}" +- button "复制": + - img +- button "在新对话中分支": + - img +- button "编辑": + - img +- 'button "Think The user wants me to plan a small change to add a `--greeting` flag to a CLI. They explicitly told me not to read or write any files, and to call exit_plan_mode with a short plan. Let me do that directly."': + - img + - img + - text: "Think The user wants me to plan a small change to add a `--greeting` flag to a CLI. They explicitly told me not to read or write any files, and to call exit_plan_mode with a short plan. Let me do that directly." +- paragraph: + - text: Since the user has explicitly asked me not to read or write any files and to go straight to planning, I'll proceed with + - code: exit_plan_mode + - text: . +- button "复制": + - img +- button "在新对话中分支": + - img +- text: {{clock}} +- button: + - img + - img +- text: "Tool call exit_plan_mode · # Add `--greeting` flag to CLI" +- 'button "Think The plan was approved. The user''s last instruction says: \"Once the plan is approved, reply with the single word DONE and stop.\" So I should just reply with DONE and stop."': + - img + - img + - text: "Think The plan was approved. The user's last instruction says: \"Once the plan is approved, reply with the single word DONE and stop.\" So I should just reply with DONE and stop." +- paragraph: DONE +- button "复制": + - img +- button "在新对话中分支": + - img +- text: {{clock}} +- textbox "Message the agent" +- button "Add attachment": + - img +- 'button "Access mode, current: Danger Full Access"': Danger Full Access +- button "Plan mode off, press to turn on": Plan off +- button "Select model, current DeepSeek-V4-Flash": + - text: DeepSeek-V4-Flash + - img +- button "Send message" [disabled] +- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 51% Input 10.2K tok · Output 346 tok diff --git a/apps/web/tests/snapshots/plan-review/review.expected.md b/apps/web/tests/snapshots/plan-review/review.expected.md new file mode 100644 index 0000000000..81d3af911c --- /dev/null +++ b/apps/web/tests/snapshots/plan-review/review.expected.md @@ -0,0 +1,44 @@ +- region "Approve this plan and leave plan mode?": + - text: Plan review + - heading "Add --greeting flag to CLI" [level=1]: + - text: Add + - code: "--greeting" + - text: flag to CLI + - list: + - listitem: + - strong: Locate the CLI entry point + - text: (e.g., + - code: cli.py + - text: "," + - code: main.go + - text: "," + - code: index.js + - text: etc.) and find the argument parser definition (argparse, click, cobra, yargs, or similar). + - listitem: + - strong: Register a new optional string argument + - text: named + - code: "--greeting" + - text: with a short alias ( + - code: "-g" + - text: if available) and a sensible default value (e.g., + - code: "\"Hello\"" + - text: ). + - listitem: + - strong: Thread the parsed value + - text: through the main handler function so it is passed where the greeting string is used (e.g., the welcome/response message). + - listitem: + - strong: Update the help text + - text: so + - code: "--help" + - text: or + - code: "-h" + - text: shows the new flag with its description. + - listitem: + - strong: No tests or config changes + - text: unless they already exist and directly validate the flag's presence. + - status + - button "Chat about it": + - img + - text: Chat about it + - button "Refuse" + - button "Approve" diff --git a/apps/web/tests/snapshots/plan-review/session.jsonl b/apps/web/tests/snapshots/plan-review/session.jsonl new file mode 100644 index 0000000000..960c05393f --- /dev/null +++ b/apps/web/tests/snapshots/plan-review/session.jsonl @@ -0,0 +1,39 @@ +{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785406804293,"cwd":"{{cwd}}/workspace"} +{"type":"command/run","seq":0,"time":1785406804350,"data":{"commandId":"cmd-228a60ef-1","name":"plan","args":" Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop.","source":{"kind":"user"}}} +{"type":"plan/mode","seq":1,"time":1785406804350,"data":{"active":true}} +{"type":"command/done","seq":2,"time":1785406804352,"data":{"commandId":"cmd-228a60ef-1","kind":"success","text":"Plan mode on. Use /plan off to leave."}} +{"type":"turn/start","seq":3,"time":1785406804353,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":4,"time":1785406804353,"data":{"content":[{"type":"text","text":"Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"a22bd0d2-15dc-4bfb-b978-0d5961459e57"},"surfaceOp":"append"} +{"type":"session/title","seq":5,"time":1785406804354,"data":{"title":"Plan a small change: add","messageSeqs":[4],"source":{"kind":"fallback"}}} +{"type":"step/start","seq":6,"time":1785406804355,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":7,"time":1785406804356,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash","reasoningEffort":"high"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":8,"time":1785406805697,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":9,"time0":1785406805698,"data":{"turn":1,"step":1,"index":0,"dt":[151,31,0,0,0,0,18,1,0,0,0,31,1,0,0,0,1,23,0,0,0,19,0,0,37,1,0,0,0,0,12,1,0,0,28,0,1,0,24,1,0,0,0,0,26,1,0,0,26,1,22],"texts":["The"," user"," wants"," me"," to"," plan"," a"," small"," change"," to"," add"," a"," `","--","gre","eting","`"," flag"," to"," a"," CLI","."," They"," explicitly"," told"," me"," not"," to"," read"," or"," write"," any"," files",","," and"," to"," call"," exit","_","plan","_mode"," with"," a"," short"," plan","."," Let"," me"," do"," that"," directly","."]}} +{"type":"assistant/chunk","seq":61,"time":1785406806155,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"text-chunks","seq0":62,"time0":1785406806156,"data":{"turn":1,"step":1,"index":1,"dt":[0,20,0,34,23,26,0,1,0,0,28,0,0,0,32,0,15,1,0,30,1,0,0,23,1,0,24,0,0,0],"texts":["Since"," the"," user"," has"," explicitly"," asked"," me"," not"," to"," read"," or"," write"," any"," files"," and"," to"," go"," straight"," to"," planning",","," I","'ll"," proceed"," with"," `","exit","_","plan","_mode","`."]}} +{"type":"assistant/chunk","seq":93,"time":1785406806493,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":2,"blockType":"tool-call"}}} +{"type":"tool-call-chunks","seq0":94,"time0":1785406806493,"data":{"turn":1,"step":1,"index":2,"dt":[27,1,0,0,0,24,0,0,29,1,0,0,0,1,20,0,27,1,0,21,28,0,0,31,1,23,0,0,1,23,0,0,0,23,1,0,28,20,26,28,1,0,29,1,0,0,21,28,0,0,25,1,26,1,0,0,24,1,0,26,0,0,0,1,23,1,0,0,22,29,0,31,1,1,0,21,1,0,0,0,0,20,0,32,25,0,0,22,0,0,27,0,1,0,31,0,1,0,0,20,1,0,0,0,0,24,0,1,0,26,1,29,1,26,1,0,25,30,1,18,0,30,0,0,30,21,1,28,0,21,1,0,0,23,1,23,36,0,0,1,0,13,1,28,27,0,0,25,1,45,1,11,0,21,0,0,0,0,23,0,0,32,1,0,0,0,16,28,0,27,1,0,22,31,1,24,1,21,32,1,0,24,1,0,24],"id":"call_00_TPh5fH8x5kRezK115kgx8155","name":"exit_plan_mode","args":["","{","\"","plan","\"",": ","\"","#"," Add"," `","--","gre","eting","`"," flag"," to"," CLI","\\n\\n","-"," **","Loc","ate"," the"," CLI"," entry"," point","**"," (","e",".g",".,"," `","cli",".py","`,"," `","main",".go","`,"," `","index",".js","`"," etc",".)"," and"," find"," the"," argument"," parser"," definition"," (","arg","parse",","," click",","," cob","ra",","," y","args",","," or"," similar",").\\n","-"," **","Register"," a"," new"," optional"," string"," argument","**"," named"," `","--","gre","eting","`"," with"," a"," short"," alias"," (`","-","g","`"," if"," available",")"," and"," a"," sensible"," default"," value"," (","e",".g",".,"," `","\\\"","Hello","\\\"","`",").\\n","-"," **","Thread"," the"," parsed"," value","**"," through"," the"," main"," handler"," function"," so"," it"," is"," passed"," where"," the"," greeting"," string"," is"," used"," (","e",".g",".,"," the"," welcome","/","response"," message",").\\n","-"," **","Update"," the"," help"," text","**"," so"," `","--","help","`"," or"," `","-","h","`"," shows"," the"," new"," flag"," with"," its"," description",".\\n","-"," **","No"," tests"," or"," config"," changes","**"," unless"," they"," already"," exist"," and"," directly"," validate"," the"," flag","'s"," presence",".","\"","}"]}} +{"type":"assistant/chunk","seq":280,"time":1785406808318,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to plan a small change to add a `--greeting` flag to a CLI. They explicitly told me not to read or write any files, and to call exit_plan_mode with a short plan. Let me do that directly."}}}} +{"type":"assistant/chunk","seq":281,"time":1785406808318,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"Since the user has explicitly asked me not to read or write any files and to go straight to planning, I'll proceed with `exit_plan_mode`."}}}} +{"type":"assistant/chunk","seq":282,"time":1785406808318,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":2,"block":{"type":"tool-call","id":"call_00_TPh5fH8x5kRezK115kgx8155","name":"exit_plan_mode","arguments":"{\"plan\": \"# Add `--greeting` flag to CLI\\n\\n- **Locate the CLI entry point** (e.g., `cli.py`, `main.go`, `index.js` etc.) and find the argument parser definition (argparse, click, cobra, yargs, or similar).\\n- **Register a new optional string argument** named `--greeting` with a short alias (`-g` if available) and a sensible default value (e.g., `\\\"Hello\\\"`).\\n- **Thread the parsed value** through the main handler function so it is passed where the greeting string is used (e.g., the welcome/response message).\\n- **Update the help text** so `--help` or `-h` shows the new flag with its description.\\n- **No tests or config changes** unless they already exist and directly validate the flag's presence.\"}"}}}} +{"type":"assistant/chunk","seq":283,"time":1785406808319,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":4529,"outputTokens":303,"cacheReadTokens":640,"reasoningTokens":52}}}} +{"type":"assistant/chunk","seq":284,"time":1785406808319,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":285,"time":1785406808324,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to plan a small change to add a `--greeting` flag to a CLI. They explicitly told me not to read or write any files, and to call exit_plan_mode with a short plan. Let me do that directly."},{"type":"text","text":"Since the user has explicitly asked me not to read or write any files and to go straight to planning, I'll proceed with `exit_plan_mode`."},{"type":"tool-call","id":"call_00_TPh5fH8x5kRezK115kgx8155","name":"exit_plan_mode","arguments":"{\"plan\": \"# Add `--greeting` flag to CLI\\n\\n- **Locate the CLI entry point** (e.g., `cli.py`, `main.go`, `index.js` etc.) and find the argument parser definition (argparse, click, cobra, yargs, or similar).\\n- **Register a new optional string argument** named `--greeting` with a short alias (`-g` if available) and a sensible default value (e.g., `\\\"Hello\\\"`).\\n- **Thread the parsed value** through the main handler function so it is passed where the greeting string is used (e.g., the welcome/response message).\\n- **Update the help text** so `--help` or `-h` shows the new flag with its description.\\n- **No tests or config changes** unless they already exist and directly validate the flag's presence.\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"b9e18116-68f6-4442-b5a5-a33277ef526c"},"usage":{"inputTokens":4529,"outputTokens":303,"cacheReadTokens":640,"reasoningTokens":52}},"sourceEventSeqs":[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,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,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284],"surfaceOp":"append"} +{"type":"tool/call","seq":286,"time":1785406808325,"data":{"turn":1,"step":1,"callId":"call_00_TPh5fH8x5kRezK115kgx8155","name":"exit_plan_mode","arguments":"{\"plan\": \"# Add `--greeting` flag to CLI\\n\\n- **Locate the CLI entry point** (e.g., `cli.py`, `main.go`, `index.js` etc.) and find the argument parser definition (argparse, click, cobra, yargs, or similar).\\n- **Register a new optional string argument** named `--greeting` with a short alias (`-g` if available) and a sensible default value (e.g., `\\\"Hello\\\"`).\\n- **Thread the parsed value** through the main handler function so it is passed where the greeting string is used (e.g., the welcome/response message).\\n- **Update the help text** so `--help` or `-h` shows the new flag with its description.\\n- **No tests or config changes** unless they already exist and directly validate the flag's presence.\"}"}} +{"type":"tool/result","seq":287,"time":1785406808720,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_TPh5fH8x5kRezK115kgx8155"},"content":[{"type":"tool-result","toolCallId":"call_00_TPh5fH8x5kRezK115kgx8155","content":[{"type":"text","text":"Plan approved — plan mode exited; carry out the plan starting with your next step."}],"isError":false}],"role":"user","id":"e7cf1f9f-e143-48df-b975-440a9d61a538"}},"sourceEventSeqs":[286],"surfaceOp":"append"} +{"type":"step/end","seq":288,"time":1785406808721,"data":{"turn":1,"step":1}} +{"type":"plan/mode","seq":289,"time":1785406808721,"data":{"active":false}} +{"type":"step/start","seq":290,"time":1785406808723,"data":{"turn":1,"step":2}} +{"type":"request/header","seq":291,"time":1785406808723,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash","reasoningEffort":"high"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}} +{"type":"assistant/chunk","seq":292,"time":1785406809855,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} +{"type":"reasoning-chunks","seq0":293,"time0":1785406809855,"data":{"turn":1,"step":2,"index":0,"dt":[133,28,1,0,0,17,0,28,1,0,0,29,0,0,0,0,0,21,0,0,0,35,0,0,0,0,0,14,1,37,1,0,1,17,0,0,0,0,1],"texts":["The"," plan"," was"," approved","."," The"," user","'s"," last"," instruction"," says",":"," \"","Once"," the"," plan"," is"," approved",","," reply"," with"," the"," single"," word"," D","ONE"," and"," stop",".\""," So"," I"," should"," just"," reply"," with"," D","ONE"," and"," stop","."]}} +{"type":"assistant/chunk","seq":333,"time":1785406810252,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}} +{"type":"assistant/chunk","seq":334,"time":1785406810253,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}} +{"type":"assistant/chunk","seq":335,"time":1785406810253,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}} +{"type":"assistant/chunk","seq":336,"time":1785406810256,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The plan was approved. The user's last instruction says: \"Once the plan is approved, reply with the single word DONE and stop.\" So I should just reply with DONE and stop."}}}} +{"type":"assistant/chunk","seq":337,"time":1785406810256,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":338,"time":1785406810256,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":441,"outputTokens":43,"cacheReadTokens":4608,"reasoningTokens":40}}}} +{"type":"assistant/chunk","seq":339,"time":1785406810256,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":340,"time":1785406810257,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The plan was approved. The user's last instruction says: \"Once the plan is approved, reply with the single word DONE and stop.\" So I should just reply with DONE and stop."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"2d9da552-d236-4166-9d06-dffa9bace4cd"},"usage":{"inputTokens":441,"outputTokens":43,"cacheReadTokens":4608,"reasoningTokens":40}},"sourceEventSeqs":[292,293,294,295,296,297,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339],"surfaceOp":"append"} +{"type":"step/end","seq":341,"time":1785406810258,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":342,"time":1785406810258,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/packages/client/ui-question/README.i18n.yaml b/packages/client/ui-question/README.i18n.yaml index 26f790b296..cd2f0556a4 100644 --- a/packages/client/ui-question/README.i18n.yaml +++ b/packages/client/ui-question/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-question/README.md -README.md: 0700375758774610fcd897b9a3e16484206a871d -README.zh.md: d9e5eb22cef13e16ab1ce2cebba9e563bd9d08d9 +README.md: 6b40c503be61c2458cefceabbb35e16a3befbe66 +README.zh.md: 7c0c4ee67d1ef8b4507f3899bdb1ae2f76408032 diff --git a/packages/client/ui-question/README.md b/packages/client/ui-question/README.md index 0700375758..6b40c503be 100644 --- a/packages/client/ui-question/README.md +++ b/packages/client/ui-question/README.md @@ -6,6 +6,8 @@ Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`. +A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. A request that declares no intent, batches more than one question, or fails to offer the named approve label stays on the generic flow — the layout is all an intent changes, never the answer. + Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally. Composer chrome copy (pager, buttons, placeholders, validation feedback) is bilingual: the plugin registers zh/en dictionaries under the `question` namespace of `dsh-client-locale` and hands the entry its bound translator plus the locale snapshot source through the inject face, so a locale switch re-renders a mounted composer. Question and option text arrives from the model and renders verbatim; carrier failure messages also display untranslated. diff --git a/packages/client/ui-question/README.zh.md b/packages/client/ui-question/README.zh.md index d9e5eb22ce..7c0c4ee67d 100644 --- a/packages/client/ui-question/README.zh.md +++ b/packages/client/ui-question/README.zh.md @@ -6,6 +6,8 @@ Web `ask_user_question` 功能插件。只有选择 Web 功能时，其主机侧 组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信内容策略。封顶卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。 +若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review` —— 由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置 —— 采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。未声明意图、一批含多个问题、或未提供被指名的批准标签的请求，一律留在通用流程上 —— 意图改变的只是布局，从不改变答案。 + 选择状态只存在于以请求 rpcId 为 key 的组件本地。使用相同 id 回放时，只要组件仍挂载，就会保留草稿；主机发出的 `question/resolved` 则会移除编辑器。主机仍具有最终决定权：HTTP 交付成功不会在本地移除待处理状态。 编辑器外框文案（翻页器、按钮、占位符、校验提示）是双语的：插件在 `dsh-client-locale` 的 `question` 命名空间下注册 zh/en 词典，并通过 inject face 把绑定的翻译函数和 locale 快照源交给该配置项，因此切换语言会重新渲染已挂载的编辑器。问题与选项文本来自模型并原样渲染；载体失败消息也不经翻译直接显示。 diff --git a/packages/client/ui-question/src/client/PlanReviewPanel.module.css b/packages/client/ui-question/src/client/PlanReviewPanel.module.css new file mode 100644 index 0000000000..428effab2b --- /dev/null +++ b/packages/client/ui-question/src/client/PlanReviewPanel.module.css @@ -0,0 +1,113 @@ +/* Plan-review takeover: the waiting-approval card language (amber strip on a + floating capsule, right-aligned actions) applied to a reviewed plan. Kept as + its own module rather than shared with ui-conversation's ApprovalPanel: the + two takeovers agree on tokens and geometry, not on content — this one's body + is scrollable markdown, that one's is a headline plus a command line. Warn + semantics ride the alias state tokens; no hardcoded colors. */ + +/* Mirrors the question card's frame so the takeover is a content swap. */ +.frame { + display: flex; + justify-content: center; + padding: 6px 24px 10px; +} + +.card { + display: flex; + overflow: hidden; + flex-direction: column; + width: 100%; + max-width: 776px; + /* Composer seat sits in a fixed-height conversation column (overflow + hidden): cap the card against the viewport and scroll the plan, so the + strip and the decision row stay reachable on a long plan. */ + max-height: min(60vh, 520px); + border: 1px solid var(--dsw-alias-state-warn-secondary); + border-radius: 20px; + background: var(--dsw-specific-input-major); + box-shadow: var(--dsw-shadow-lv2); + color: var(--dsw-alias-label-primary); + /* Elevated surface in dark: the plan body inside scrolls once the card hits + the cap above, so the thumb takes the l2 pair (see ui-theme + styles/scrollbar.css for the rebinding contract). */ + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); +} + +.card, +.card * { + box-sizing: border-box; +} + +/* Tinted full-width header band, as on the approval takeover. */ +.strip { + display: flex; + align-items: center; + flex-shrink: 0; + gap: 8px; + padding: 10px 16px; + background: var(--dsw-alias-state-warn-tertiary); + color: var(--dsw-alias-state-warn-primary); + font-size: 13px; + line-height: 18px; +} + +.dot { + width: 8px; + height: 8px; + border-radius: 50%; + background: var(--dsw-alias-state-warn-primary); +} + +/* The plan is the panel's message: it takes the whole body and the scroll. */ +.body { + flex: 1 1 auto; + min-height: 0; + overflow-y: auto; + overscroll-behavior: contain; + padding: 12px 16px 4px; + font-size: 14px; + line-height: 22px; +} + +.footer { + display: flex; + align-items: center; + justify-content: space-between; + flex-shrink: 0; + gap: 12px; + padding: 8px 16px 12px; +} + +.feedback { + min-height: 16px; + color: var(--dsw-alias-state-error-primary); + font-size: 11px; + line-height: 16px; +} + +.actions { + display: flex; + align-items: center; + flex-shrink: 0; + gap: 8px; +} + +@media (max-width: 720px) { + .frame { + padding: 6px 10px 10px; + } + + .card { + border-radius: 16px; + } + + .body { + padding: 10px 12px 4px; + } + + .footer { + align-items: flex-end; + padding: 8px 12px 10px; + } +} diff --git a/packages/client/ui-question/src/client/PlanReviewPanel.tsx b/packages/client/ui-question/src/client/PlanReviewPanel.tsx new file mode 100644 index 0000000000..020df9c82c --- /dev/null +++ b/packages/client/ui-question/src/client/PlanReviewPanel.tsx @@ -0,0 +1,100 @@ +// PlanReviewPanel: the composer takeover for a question carrying the +// `plan-review` presentation intent. A plan under review is one decision over +// one body of markdown, so it takes the waiting-approval card shape — tinted +// strip, content, right-aligned action row — instead of the generic question +// flow's pager, numbered options, skip and custom-answer affordances, which +// read as a quiz the user is being graded on. +// +// The three actions are the whole decision surface: approve and decline answer +// the question with the option labels the asker offered (localised copy on the +// buttons, the asker's descriptions as their tooltips), while "discuss" +// dismisses the request so the composer returns and the user can simply say +// what they want. Dismissal is the generic flow's own cancel verb, promoted to +// a labelled button because in a two-outcome decision it is the third real +// answer, not an escape hatch. + +import { useState } from 'react' +import { Button, IconEditOutline16, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives' +import type { PendingQuestion, PlanReview, QuestionComposerProps } from './contract/slots.ts' +import css from './PlanReviewPanel.module.css' + +/** The panel's own props: the question domain face, the narrowed review, and the locale seat. */ +export type PlanReviewPanelProps = + { pending: PendingQuestion; review: PlanReview } & Pick + +/** + * Optional-prop spread for a decision button's tooltip: `title` is optional on + * the DOM props, and exactOptionalPropertyTypes rejects an explicit undefined. + * + * @param description - the asker's option description, when it carries one. + * @returns The `title` prop to spread, or nothing. + */ +function tooltip(description: string | undefined): { title?: string } { + return description === undefined ? {} : { title: description } +} + +/** + * Render a plan review as a decision card. + * + * @param props - the question domain face, the narrowed plan review, and `t`. + * @returns The plan-review takeover for this request. + */ +export function PlanReviewPanel({ pending, review, t }: PlanReviewPanelProps) { + // One-shot latch shaped like the approval takeover's: the panel leaves only + // when the host's resolved frame lands, so until then a second click must + // not re-fire. A failed send (rejected receipt / transport) re-arms it and + // shows why, since nothing else would tell the user the click was lost. + const [busy, setBusy] = useState(false) + const [error, setError] = useState(null) + const settle = (send: () => Promise): void => { + setBusy(true) + setError(null) + void send().catch((cause: unknown) => { + setBusy(false) + setError(cause instanceof Error ? cause.message : String(cause)) + }) + } + const decide = (label: string): void => { + settle(() => pending.answer({ answers: [{ id: review.id, selected: [label] }] })) + } + const decline = review.decline + + return ( +
+
+
+ + {t('plan.header')} +
+
+ +
+
+
{error}
+
+ + {decline !== undefined && ( + + )} + +
+
+
+
+ ) +} diff --git a/packages/client/ui-question/src/client/QuestionComposer.tsx b/packages/client/ui-question/src/client/QuestionComposer.tsx index 30caf7f98e..abe87f567e 100644 --- a/packages/client/ui-question/src/client/QuestionComposer.tsx +++ b/packages/client/ui-question/src/client/QuestionComposer.tsx @@ -5,9 +5,10 @@ import { IconCloseOutline16, IconEditOutline16, MarkdownText, } from '@deepseek-ai/dsh-client-ui-primitives' import { - PendingQuestion, + PendingQuestion, planReviewOf, type QuestionAnswer, type QuestionComposerProps, } from './contract/slots.ts' +import { PlanReviewPanel } from './PlanReviewPanel.tsx' import css from './QuestionComposer.module.css' interface DraftAnswer { @@ -46,14 +47,24 @@ function isComposing(event: KeyboardEvent new PendingQuestion(props.matched), [props.matched]) - return + const review = useMemo(() => planReviewOf(question.questions), [question]) + return review === undefined + ? + : } function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick) { diff --git a/packages/client/ui-question/src/client/contract/slots.ts b/packages/client/ui-question/src/client/contract/slots.ts index 54e87c016d..f92eb33f52 100644 --- a/packages/client/ui-question/src/client/contract/slots.ts +++ b/packages/client/ui-question/src/client/contract/slots.ts @@ -19,6 +19,65 @@ export type QuestionWait = PendingWait<'question'> /** One structured answer batch covering every question of the request. */ export type QuestionAnswer = QuestionResponsePayload['answer'] +/** One question of the request, as the carrier payload carries it. */ +type QuestionItem = QuestionWait['payload']['questions'][number] + +/** One option the asker offered on a question. */ +type QuestionOption = NonNullable[number] + +/** + * A request narrowed to the `plan-review` presentation intent: everything the + * decision card renders and answers with, so the panel never re-reads the + * request shape. `approve` and `decline` are the asker's own options — an + * answer must carry one of those labels verbatim — and `plan` is the markdown + * body under review. + */ +export interface PlanReview { + /** The reviewed question's id, echoed in the answer. */ + id: string + /** The question text, kept as the card's accessible name. */ + question: string + /** The plan markdown under review. */ + plan: string + /** The option that approves the plan. */ + approve: QuestionOption + /** The option that declines it; absent when the asker offered no other option. */ + decline?: QuestionOption +} + +/** + * Narrow a request to a renderable plan review, or return undefined to leave it + * to the generic question flow. + * + * The card is one decision over one plan, so it claims a request only when the + * batch is a single question that declares the intent, carries the plan as its + * detail, and offers the approve label the intent names. The asker's own + * service validates that label, but this is a wire boundary: a request failing + * any part of it still renders and stays answerable as a generic question + * rather than reaching a card that cannot express it. + * + * @param questions - the request's whole question batch. + * @returns The narrowed review, or undefined when the generic flow owns it. + */ +export function planReviewOf(questions: readonly QuestionItem[]): PlanReview | undefined { + if (questions.length !== 1) return undefined + // Length-checked above; the index read is the narrowing tax, not a guess. + const question = questions[0] as QuestionItem + const intent = question.intent + if (intent?.kind !== 'plan-review' || question.detail === undefined) return undefined + const options = question.options ?? [] + const approve = options.find(option => option.label === intent.approve) + if (approve === undefined) return undefined + const decline = options.find(option => option.label !== intent.approve) + return { + id: question.id, + question: question.question, + plan: question.detail, + approve, + ...(decline === undefined ? {} : { decline }), + } +} + /** * Question domain face over the carrier: render identity and questions * transparently forwarded; answer/cancel own the wire encoding (the ok value diff --git a/packages/client/ui-question/src/client/index.ts b/packages/client/ui-question/src/client/index.ts index 63f7517c3a..9c6893fd18 100644 --- a/packages/client/ui-question/src/client/index.ts +++ b/packages/client/ui-question/src/client/index.ts @@ -5,6 +5,12 @@ * question carrier (matched prop), and the whole behavior surface rides the * carrier (domain encoding in contract/slots.ts PendingQuestion); copy rides * the standard locale seat. Export discipline: packages/client/AGENTS.md. + * + * One entry, two shapes: the composer renders a request that declares a + * presentation intent as that intent's own surface (`plan-review` → the plan + * decision card) and every other request as the generic question flow. A + * separate chain entry per shape would race the same carrier, so the shape + * choice lives inside this entry — see QuestionComposer. */ import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client' @@ -14,8 +20,10 @@ import type { QuestionWait } from './contract/slots.ts' import { QuestionComposer } from './QuestionComposer.tsx' import { en, zh, type QuestionKey } from './locales.ts' -export { PendingQuestion } from './contract/slots.ts' -export type { QuestionAnswer, QuestionComposerProps, QuestionWait } from './contract/slots.ts' +export { PendingQuestion, planReviewOf } from './contract/slots.ts' +export type { + PlanReview, QuestionAnswer, QuestionComposerProps, QuestionWait, +} from './contract/slots.ts' export type { QuestionKey } from './locales.ts' declare module '@deepseek-ai/dsh-client-ui-slots' { diff --git a/packages/client/ui-question/src/client/locales.ts b/packages/client/ui-question/src/client/locales.ts index f124b34da2..bd5ee515ae 100644 --- a/packages/client/ui-question/src/client/locales.ts +++ b/packages/client/ui-question/src/client/locales.ts @@ -11,6 +11,10 @@ export const zh = { 'custom.placeholder': '输入你的答案', 'action.skip': '跳过本题', 'action.next': '下一题', + 'plan.header': '计划待审', + 'plan.approve': '确认执行', + 'plan.decline': '拒绝', + 'plan.discuss': '去聊天里说', } satisfies Record /** The question namespace key union. */ @@ -27,4 +31,8 @@ export const en = { 'custom.placeholder': 'Type your answer', 'action.skip': 'Skip this question', 'action.next': 'Next', + 'plan.header': 'Plan review', + 'plan.approve': 'Approve', + 'plan.decline': 'Refuse', + 'plan.discuss': 'Chat about it', } satisfies Record diff --git a/packages/client/ui-question/tests/plan-review-panel.spec.tsx b/packages/client/ui-question/tests/plan-review-panel.spec.tsx new file mode 100644 index 0000000000..3c2c456c57 --- /dev/null +++ b/packages/client/ui-question/tests/plan-review-panel.spec.tsx @@ -0,0 +1,221 @@ +// @vitest-environment jsdom +// The plan-review takeover, driven through the composer entry that routes to +// it: a request carrying the intent must reach the decision card and answer +// with the asker's own option labels, and a request that does not (or cannot) +// must keep the generic question flow. +import { afterEach, describe, expect, it, vi } from 'vitest' +import { cleanup, fireEvent, render, screen } from '@testing-library/react' +import type { + ConversationSnapshot, SessionId, SessionListState, WorkspaceListState, +} from '@deepseek-ai/dsh-client-runtime/client' +import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client' +import type { RpcReceipt } from '@deepseek-ai/dsh-client-connection/client' +import { RpcId } from '@deepseek-ai/dsh-client-connection/client' +import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots' +import { planReviewOf, type QuestionComposerProps, type QuestionWait } from '../src/client/contract/slots.ts' +import { QuestionComposer } from '../src/client/QuestionComposer.tsx' +import { en, zh } from '../src/client/locales.ts' +import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts' +import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' + +afterEach(cleanup) + +const SID = 's1' as SessionId + +/** Seat stub over a dictionary pair mirroring the real lookup chain: package dictionary, then common vocabulary, then the key. */ +const seatOver = (dict: Record, common: Record): QuestionComposerProps['t'] => + (key => dict[key] ?? common[key] ?? key) + +/** Framework standard-kit stubs: the panel consumes only the locale seat. */ +const kit = { + sessionId: SID, + useSession: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook, + useSessions: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook, + useWorkspaces: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook, + useProjection: (() => undefined) as never, + useInput: (() => { throw new Error('unused') }) as never, + inputActions: { setDraft: () => { throw new Error('unused') }, submit: () => { throw new Error('unused') } } as never, + t: seatOver(zh, commonZh), +} + +const PLAN = '# Ship the picker\n\n- read the store\n- render the rows\n' + +/** The plan-mode request shape: one question, the plan as detail, approve named. */ +const questions = (): QuestionWait['payload']['questions'] => [{ + id: 'plan-review', + header: 'Plan review', + question: 'Approve this plan and leave plan mode?', + detail: PLAN, + options: [ + { label: 'Approve', description: 'Leave plan mode; the plan is carried out from the next step.' }, + { label: 'Keep planning', description: 'Stay in plan mode; feedback goes back to the model.' }, + ], + intent: { kind: 'plan-review', approve: 'Approve' }, +}] + +/** Carrier fixture over a scripted respond carrier. */ +function wait( + payload: QuestionWait['payload'] = { questions: questions() }, + respond = vi.fn(() => Promise.resolve({ accepted: true })), +) { + return { carrier: new PendingWait('question', RpcId('q-1'), SID, payload, respond), respond } +} + +/** The client-response envelope respond must have received for a decision. */ +function decidedEnvelope(label: string) { + return { + type: 'client-response', rpcId: RpcId('q-1'), + result: { ok: true, value: { sessionId: SID, answer: { answers: [{ id: 'plan-review', selected: [label] }] } } }, + } +} + +describe('planReviewOf', () => { + it('narrows a plan-review request to its decision, options included', () => { + expect(planReviewOf(questions())).toEqual({ + id: 'plan-review', + question: 'Approve this plan and leave plan mode?', + plan: PLAN, + approve: { label: 'Approve', description: 'Leave plan mode; the plan is carried out from the next step.' }, + decline: { label: 'Keep planning', description: 'Stay in plan mode; feedback goes back to the model.' }, + }) + }) + + it('leaves the decline absent when the asker offered approve alone', () => { + const [question] = questions() + const review = planReviewOf([{ ...question as object, options: [{ label: 'Approve' }] } as never]) + expect(review?.approve).toEqual({ label: 'Approve' }) + expect(review === undefined ? true : 'decline' in review).toBe(false) + }) + + it.each([ + ['a batch of more than one question', () => [...questions(), ...questions()]], + ['no intent at all', () => [{ ...questions()[0] as object, intent: undefined }]], + ['an intent without the plan as detail', () => [{ ...questions()[0] as object, detail: undefined }]], + ['an intent whose approve names no option', () => [{ + ...questions()[0] as object, intent: { kind: 'plan-review', approve: 'Ship it' }, + }]], + ['an intent with no options at all', () => [{ ...questions()[0] as object, options: undefined }]], + ])('declines %s, leaving the request to the generic flow', (_case, build) => { + expect(planReviewOf(build() as never)).toBeUndefined() + }) + + it('declines an empty batch, which the generic flow reports as such', () => { + expect(planReviewOf([])).toBeUndefined() + }) +}) + +describe('PlanReviewPanel', () => { + it('renders the plan under a review strip, with none of the quiz affordances', () => { + const { carrier } = wait() + render() + + expect(document.querySelector('[data-plan-review-key="q:q-1"]')).toBeTruthy() + expect(screen.getByText(zh['plan.header'])).toBeTruthy() + // The plan renders as markdown, so its heading is a heading. + expect(screen.getByRole('heading', { name: 'Ship the picker' })).toBeTruthy() + expect(screen.getByText('render the rows')).toBeTruthy() + // The question text stays as the card's accessible name rather than a title + // that reads like a test item. + expect(screen.getByLabelText('Approve this plan and leave plan mode?')).toBeTruthy() + // No pager, no numbered options, no skip, no custom answer. + expect(screen.queryByText('1 / 1')).toBeNull() + expect(screen.queryByRole('radio')).toBeNull() + expect(screen.queryByText(zh['action.skip'])).toBeNull() + expect(screen.queryByRole('textbox')).toBeNull() + }) + + it('answers with the asker\'s approve label and keeps its description as the tooltip', () => { + const { carrier, respond } = wait() + render() + + const approve = screen.getByRole('button', { name: zh['plan.approve'] }) + expect(approve.getAttribute('title')).toBe('Leave plan mode; the plan is carried out from the next step.') + fireEvent.click(approve) + expect(respond).toHaveBeenCalledWith(decidedEnvelope('Approve')) + // One-shot: every action locks until the host's resolved frame lands. + expect(approve.hasAttribute('disabled')).toBe(true) + expect(screen.getByRole('button', { name: zh['plan.decline'] }).hasAttribute('disabled')).toBe(true) + fireEvent.click(approve) + expect(respond).toHaveBeenCalledTimes(1) + }) + + it('answers with the asker\'s decline label', () => { + const { carrier, respond } = wait() + render() + + fireEvent.click(screen.getByRole('button', { name: zh['plan.decline'] })) + expect(respond).toHaveBeenCalledWith(decidedEnvelope('Keep planning')) + }) + + it('dismisses the request so the composer returns for a plain message', () => { + const { carrier, respond } = wait() + render() + + fireEvent.click(screen.getByRole('button', { name: zh['plan.discuss'] })) + expect(respond).toHaveBeenCalledWith({ + type: 'client-response', rpcId: RpcId('q-1'), + result: { + ok: false, + error: { code: 'cancelled', message: 'the user closed this question request', details: {} }, + }, + }) + }) + + it('omits the tooltip for an option carrying no description', () => { + const { carrier } = wait({ questions: [{ + ...questions()[0] as object, + options: [{ label: 'Approve' }, { label: 'Keep planning' }], + }] as never }) + render() + + expect(screen.getByRole('button', { name: zh['plan.approve'] }).hasAttribute('title')).toBe(false) + expect(screen.getByRole('button', { name: zh['plan.decline'] }).hasAttribute('title')).toBe(false) + }) + + it('hides the decline action when the asker offered approve alone', () => { + const { carrier } = wait({ questions: [{ + ...questions()[0] as object, options: [{ label: 'Approve' }], + }] as never }) + render() + + expect(screen.queryByRole('button', { name: zh['plan.decline'] })).toBeNull() + expect(screen.getByRole('button', { name: zh['plan.approve'] })).toBeTruthy() + }) + + it('re-arms the actions and says why when the decision does not land', async () => { + const { carrier, respond } = wait( + { questions: questions() }, + vi.fn(() => Promise.resolve({ accepted: false, reason: 'not-pending' })), + ) + render() + + fireEvent.click(screen.getByRole('button', { name: zh['plan.approve'] })) + const failure = await screen.findByText('question response rejected: not-pending') + expect(failure.getAttribute('role')).toBe('status') + // Re-armed for the retry: a lost click must not leave a dead card. + expect(screen.getByRole('button', { name: zh['plan.approve'] }).hasAttribute('disabled')).toBe(false) + fireEvent.click(screen.getByRole('button', { name: zh['plan.approve'] })) + expect(respond).toHaveBeenCalledTimes(2) + }) + + it('reports a non-Error transport failure as its stringified value', async () => { + // A non-Error rejection is the case under test: a carrier can reject with + // anything, and the panel must still show the user something. + // oxlint-disable-next-line typescript/prefer-promise-reject-errors + const { carrier } = wait({ questions: questions() }, vi.fn(() => Promise.reject('socket gone'))) + render() + + fireEvent.click(screen.getByRole('button', { name: zh['plan.discuss'] })) + expect(await screen.findByText('socket gone')).toBeTruthy() + }) + + it('carries the same decision surface in English', () => { + const { carrier } = wait() + render() + + expect(screen.getByText('Plan review')).toBeTruthy() + expect(screen.getByRole('button', { name: 'Approve' })).toBeTruthy() + expect(screen.getByRole('button', { name: 'Refuse' })).toBeTruthy() + expect(screen.getByRole('button', { name: 'Chat about it' })).toBeTruthy() + }) +}) From 132294fe8d5b61cc9aac174cb4ff2ad57a94bed2 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 30 Jul 2026 19:12:02 +0800 Subject: [PATCH 41/67] fix(web): register the plan-review e2e lane in the host-plane program MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The lane boots the host spine through the shared scaffold, so it belongs to tsconfig.host.json and must stay out of the client-registered apps/web project — one program cannot hold both sides of the cordis Context merges. --- apps/web/tsconfig.json | 1 + tsconfig.host.json | 1 + 2 files changed, 2 insertions(+) diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 7a7f228fb0..5f903b79b5 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -25,6 +25,7 @@ "tests/scaffold.ts", "tests/live-interactions.e2e.ts", "tests/question-composer.e2e.ts", + "tests/plan-review.e2e.ts", "tests/steering.e2e.ts", "tests/navigation-panes.e2e.ts", "tests/lifecycle-chrome.e2e.ts", diff --git a/tsconfig.host.json b/tsconfig.host.json index f55010712e..80579d7943 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -12,6 +12,7 @@ "apps/web/tests/support.ts", "apps/web/tests/live-interactions.e2e.ts", "apps/web/tests/question-composer.e2e.ts", + "apps/web/tests/plan-review.e2e.ts", "apps/web/tests/steering.e2e.ts", "apps/web/tests/navigation-panes.e2e.ts", "apps/web/tests/lifecycle-chrome.e2e.ts", From 5f87c7a89c75de19e852302e1202f7ea8c72274c Mon Sep 17 00:00:00 2001 From: kingwl Date: Thu, 30 Jul 2026 19:20:13 +0800 Subject: [PATCH 42/67] fix(web): close queue collapse review gaps --- ...-29-addressable-queue-operations.i18n.yaml | 4 +- ...2026-07-29-addressable-queue-operations.md | 4 +- ...6-07-29-addressable-queue-operations.zh.md | 4 +- apps/web/tests/queue-actions.e2e.ts | 14 +- .../queue-actions/collapsed.expected.md | 24 +++ .../queue-actions/editing.expected.md | 2 +- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../src/client/queue/QueueDock.module.css | 8 + .../src/client/queue/QueueDock.tsx | 186 +++++++++--------- .../ui-conversation/tests/queue-dock.spec.tsx | 77 +++++++- 12 files changed, 224 insertions(+), 107 deletions(-) create mode 100644 apps/web/tests/snapshots/queue-actions/collapsed.expected.md diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml index 3524737277..d9b4a04671 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md -2026-07-29-addressable-queue-operations.md: 28570be7a2a520fd8293a73526302122740823ca -2026-07-29-addressable-queue-operations.zh.md: eb62d45c6572cd993fedf982d6c86e2ff19787a6 +2026-07-29-addressable-queue-operations.md: 7a08b889c958e583dc430d33a1855fe3725f3d48 +2026-07-29-addressable-queue-operations.zh.md: 701b028c7494fd7cb608d05a5d170c9075b155d7 diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md index 28570be7a2..7a08b889c9 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md @@ -18,7 +18,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M **Queue addresses require a live Agent.** `session.updateQueue` queries only the mounted Agent registry and never resumes a cold session: an `InboxItemId` is process-local and cannot name work after restart or disposal. A missing Agent and a driver-claimed occurrence both return `queue-item-not-found`. -**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `" Queued"` header that expands or collapses the complete list. The header exposes `aria-expanded`. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. +**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `" 条排队消息"` header that expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. ## Alternatives considered @@ -34,7 +34,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M ## Verification -AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios expand the queue and drive its exposed edit and delete actions through the built Web composition and real HTTP/SSE wire. +AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, interaction-forced visibility, reset after emptying, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios capture the default collapsed header before expanding the queue and driving its exposed edit and delete actions through the built Web composition and real HTTP/SSE wire. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md index eb62d45c65..701b028c74 100644 --- a/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.zh.md @@ -18,7 +18,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 **Queue 寻址要求 Agent 存活。** `session.updateQueue` 只查询已挂载的 Agent 注册表，绝不恢复冷会话：`InboxItemId` 属于进程本地标识，无法在重启或资源释放后继续指向工作。Agent 缺失和单次入队项已被驱动器认领这两种情况都返回 `queue-item-not-found`。 -**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `" Queued"` 表头。表头暴露 `aria-expanded`。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。 +**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `" 条排队消息"` 表头。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。 ## 考虑过的替代方案 @@ -34,7 +34,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行 ## 验证 -AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会展开队列，并通过构建后的 Web 组合和真实 HTTP／SSE 协议操作其公开的编辑和删除。 +AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、交互期间强制保持可见、清空后重置、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会先捕获默认收起的表头，再展开队列，并通过构建后的 Web 组合和真实 HTTP／SSE 协议操作其公开的编辑和删除。 ## 后果 diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts index 025747c37d..1c2ca271aa 100644 --- a/apps/web/tests/queue-actions.e2e.ts +++ b/apps/web/tests/queue-actions.e2e.ts @@ -20,6 +20,7 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/queue-actions', import.meta.url)) const FIXTURE = fileURLToPath(new URL('./snapshots/live-interactions/session.jsonl', import.meta.url)) +const COLLAPSED_EXPECTED = join(SNAPSHOT_DIR, 'collapsed.expected.md') const EDITING_EXPECTED = join(SNAPSHOT_DIR, 'editing.expected.md') const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md') const MODE = webSnapshotMode() @@ -80,9 +81,15 @@ describe('web e2e: queue row actions', () => { await input.fill(text) await input.press('Enter') } - const queueHeader = page.getByRole('button', { name: '2 Queued' }) + const queueHeader = page.getByRole('button', { name: '2 条排队消息' }) await expect.poll(() => queueHeader.getAttribute('aria-expanded'), { timeout: 10_000 }) .toBe('false') + const collapsedSnapshot = await captureStableAria( + page, + '[class*="centerCol"]', + scaffold.workspaceCwd, + ) + await compareOrRefreshGolden(COLLAPSED_EXPECTED, collapsedSnapshot, MODE) await queueHeader.click() await expect.poll( () => page.getByRole('button', { name: '删除排队消息' }).count(), @@ -116,6 +123,9 @@ describe('web e2e: queue row actions', () => { }, 120_000) it.skipIf(MODE === 'record')('keeps its snapshot inventory closed', async () => { - await assertFixtureInventory(SNAPSHOT_DIR, ['editing.expected.md', 'ui.expected.md']) + await assertFixtureInventory( + SNAPSHOT_DIR, + ['collapsed.expected.md', 'editing.expected.md', 'ui.expected.md'], + ) }) }) diff --git a/apps/web/tests/snapshots/queue-actions/collapsed.expected.md b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md new file mode 100644 index 0000000000..cdbf6fc64b --- /dev/null +++ b/apps/web/tests/snapshots/queue-actions/collapsed.expected.md @@ -0,0 +1,24 @@ +- banner: + - navigation "Session hierarchy": + - button "Reply with a one-sentence description" [disabled] + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- text: Reply with a one-sentence description of event sourcing, then stop. {{clock}} +- button "复制": + - img +- button "在新对话中分支": + - img +- button "编辑": + - img +- paragraph: partial +- button "2 条排队消息" +- textbox "Message the agent" +- button "Add attachment": + - img +- 'button "Access mode, current: Danger Full Access"': Danger Full Access +- button "Plan mode off, press to turn on": Plan off +- button "Select model, current DeepSeek-V4-Flash": + - text: DeepSeek-V4-Flash + - img +- button "Stop generating" diff --git a/apps/web/tests/snapshots/queue-actions/editing.expected.md b/apps/web/tests/snapshots/queue-actions/editing.expected.md index 0bd0f3f472..cf287b5006 100644 --- a/apps/web/tests/snapshots/queue-actions/editing.expected.md +++ b/apps/web/tests/snapshots/queue-actions/editing.expected.md @@ -12,7 +12,7 @@ - button "编辑": - img - paragraph: partial -- button "2 Queued" [expanded] +- button "2 条排队消息" [disabled] [expanded] - list: - listitem: - text: Queue item to remove diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index ff60af0eed..157999ceef 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 18c8d86cb8dc375815afab8cc5275691bfdd3d86 -README.zh.md: 5b69be13980ecc25302e28b9ecda32d57f11b782 +README.md: 602befcc7b0ff49701b4b447fd80da0237034fdc +README.zh.md: fa24deaa9638d4397ebce4cca072814257fa2bc3 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 18c8d86cb8..602befcc7b 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -18,7 +18,7 @@ Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.to The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`/ 已完成 · ` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 10` — between Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"/ tasks · in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. -`QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `" Queued"` header whose button expands or collapses the complete list. The header exposes `aria-expanded`; each visible row remains a single-line preview with its exact-occurrence edit and delete actions. +`QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `" 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible row remains a single-line preview with its exact-occurrence edit and delete actions. Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 5b69be1398..fa24deaa96 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -18,7 +18,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: 10` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 和 Queue 之间），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。 -`QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `" Queued"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded`；每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。 +`QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `" 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。 diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css index a45c8c02c2..46cc018179 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css @@ -20,6 +20,8 @@ padding-top: 2px; border-radius: 14px 14px 0 0; background: var(--dsw-specific-tip); + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); } .panel::after { @@ -53,6 +55,10 @@ outline-offset: -2px; } +.header:disabled { + cursor: default; +} + .count { flex: 1 1 auto; min-width: 0; @@ -72,6 +78,8 @@ } .list { + max-height: 180px; + overflow-y: auto; margin: 0; padding: 0; list-style: none; diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index d20e25d8d2..67de5d0796 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -4,7 +4,7 @@ // The 'conversation.input.dock' SlotMap declaration lives in // ../contract/slots.ts beside the other input-region slots. import type { Context } from 'cordis' -import { useEffect, useState } from 'react' +import { useEffect, useId, useState } from 'react' import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client' import { @@ -32,13 +32,19 @@ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) { const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null) const [busy, setBusy] = useState(null) const [collapsed, setCollapsed] = useState(true) + const listId = useId() useEffect(() => { + if (queue.length === 0 && !collapsed) setCollapsed(true) if (editing !== null && !queue.some(row => row.id === editing.id)) setEditing(null) - }, [editing, queue]) + }, [collapsed, editing, queue]) if (queue.length === 0) return null + const interactionActive = editing !== null || busy !== null + const expanded = !collapsed || interactionActive + const listVisible = queue.length === 1 || expanded + const applyAction = async ( itemId: QueueItemId, action: QueueAction, @@ -72,103 +78,103 @@ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) { )} - {(queue.length === 1 || !collapsed) && ( -
    - {queue.map(row => ( -
  • + - )} + : ( + <> + + + + )} + +
    • + ))} +
) diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx index 42749ec329..8a8e01cc91 100644 --- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx @@ -82,12 +82,13 @@ describe('QueueDock', () => { const single = snapshotWith([row('i-1', 'one')]) const source = liveSession(single) const view = render() - expect(view.queryByRole('button', { name: '1 Queued' })).toBeNull() + expect(view.queryByRole('button', { name: '1 条排队消息' })).toBeNull() expect(view.getByText('one')).toBeTruthy() act(() => { source.push(snapshotWith([row('i-1', 'one'), row('i-2', 'two')])) }) - const header = view.getByRole('button', { name: '2 Queued' }) + const header = view.getByRole('button', { name: '2 条排队消息' }) expect(header.getAttribute('aria-expanded')).toBe('false') + expect(document.getElementById(header.getAttribute('aria-controls')!)).toBeTruthy() expect(view.queryByText('one')).toBeNull() expect(view.queryByText('two')).toBeNull() @@ -101,6 +102,74 @@ describe('QueueDock', () => { expect(view.queryByText('one')).toBeNull() }) + it('keeps an active single-row editor visible when another item arrives', () => { + const single = snapshotWith([row('i-edit', 'before')]) + const source = liveSession(single) + const view = render() + + fireEvent.click(view.getByLabelText('编辑排队消息')) + fireEvent.change(view.getByLabelText('编辑排队消息'), { target: { value: 'draft' } }) + act(() => { + source.push(snapshotWith([row('i-edit', 'before'), row('i-2', 'second')])) + }) + + const header = view.getByRole('button', { name: '2 条排队消息' }) + expect(header).toHaveProperty('disabled', true) + expect(header.getAttribute('aria-expanded')).toBe('true') + expect(view.getByRole('textbox', { name: '编辑排队消息' })).toHaveProperty('value', 'draft') + expect(view.getByText('second')).toBeTruthy() + + fireEvent.click(view.getByLabelText('取消编辑')) + expect(header).toHaveProperty('disabled', false) + expect(header.getAttribute('aria-expanded')).toBe('false') + expect(view.queryByText('second')).toBeNull() + }) + + it('keeps an in-flight row action visible when another item arrives', async () => { + const single = snapshotWith([row('i-remove', 'remove me')]) + const source = liveSession(single) + let finishUpdate: (() => void) | undefined + const updateQueue = vi.fn(() => new Promise((resolve) => { finishUpdate = resolve })) + const view = render( + , + ) + + fireEvent.click(view.getByLabelText('删除排队消息')) + act(() => { + source.push(snapshotWith([row('i-remove', 'remove me'), row('i-2', 'second')])) + }) + + const header = view.getByRole('button', { name: '2 条排队消息' }) + expect(header).toHaveProperty('disabled', true) + expect(header.getAttribute('aria-expanded')).toBe('true') + expect(view.getByText('remove me')).toBeTruthy() + expect(view.getByText('second')).toBeTruthy() + + act(() => { finishUpdate?.() }) + await waitFor(() => { + expect(header).toHaveProperty('disabled', false) + expect(header.getAttribute('aria-expanded')).toBe('false') + }) + }) + + it('defaults a new multi-row queue to collapsed after the prior queue empties', () => { + const first = snapshotWith([row('i-1', 'one'), row('i-2', 'two')]) + const source = liveSession(first) + const view = render() + fireEvent.click(view.getByRole('button', { name: '2 条排队消息' })) + expect(view.getByText('one')).toBeTruthy() + + act(() => { source.push(snapshotWith([])) }) + expect(view.container.innerHTML).toBe('') + act(() => { + source.push(snapshotWith([row('i-3', 'three'), row('i-4', 'four')])) + }) + + const header = view.getByRole('button', { name: '2 条排队消息' }) + expect(header.getAttribute('aria-expanded')).toBe('false') + expect(view.queryByText('three')).toBeNull() + }) + it('renders active actions and disables editing for mixed-content rows', () => { const snap = snapshotWith([ row('i-1', '第一条排队消息'), @@ -108,7 +177,7 @@ describe('QueueDock', () => { ]) const source = liveSession(snap) const { container, getByRole } = render() - fireEvent.click(getByRole('button', { name: '2 Queued' })) + fireEvent.click(getByRole('button', { name: '2 条排队消息' })) expect([...container.querySelectorAll('li')].map(item => item.textContent)) .toEqual(['第一条排队消息', 'image [image]']) expect(container.querySelectorAll('button')).toHaveLength(5) @@ -190,7 +259,7 @@ describe('QueueDock', () => { , ) - fireEvent.click(getByRole('button', { name: '2 Queued' })) + fireEvent.click(getByRole('button', { name: '2 条排队消息' })) fireEvent.click(getAllByLabelText('删除排队消息')[0]!) await waitFor(() => { expect(updateQueue).toHaveBeenCalledWith(iid('i-1'), { kind: 'remove' }) From fb3018716176955531c521a00626feee63b7be32 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 19:27:44 +0800 Subject: [PATCH 43/67] fix(web): isolate replay skill discovery --- ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml | 4 +- .../2026-07-24-web-gui-browser-e2e-lane.md | 4 +- .../2026-07-24-web-gui-browser-e2e-lane.zh.md | 4 +- apps/web/tests/scaffold-hermetic.e2e.ts | 57 +++++++++++++++++++ apps/web/tests/scaffold.ts | 26 +++++++-- apps/web/tsconfig.json | 1 + tsconfig.host.json | 1 + 7 files changed, 85 insertions(+), 12 deletions(-) create mode 100644 apps/web/tests/scaffold-hermetic.e2e.ts diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml index 14990e32c8..7b59000f1e 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md -2026-07-24-web-gui-browser-e2e-lane.md: fb28b7013550a853b92e50810f5bc34f2c02d2e4 -2026-07-24-web-gui-browser-e2e-lane.zh.md: b9a7d050031c3d08269a3b971cd1a84f082efba7 +2026-07-24-web-gui-browser-e2e-lane.md: e47509378a8df25e5adac89a0f70c7ac1a8314c4 +2026-07-24-web-gui-browser-e2e-lane.zh.md: 1b2ea038b9a2c5ffd20442dcdf6986ce4e55af5f diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md index fb28b70135..e47509378a 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md @@ -16,7 +16,7 @@ The web GUI ships as a real assembled chain — chromium page → client plugin A plain shared-fixture module (the [testing-policy sanctioned shape](../../../../docs/testing.md)), not a package: the gate-worthy logic — replay derivation, session parsing, log scrubbing, persistence — lives in the gated packages `dsh-llm-replay`, `dsh-acp-snapshot`, and `dsh-session-persistence-jsonl`; what remains is boot wiring and browser glue, and chromium-driving code cannot hold per-file 100% coverage on the browserless coverage runners. -`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`, `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md), `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor), the webserver row pinned to port 0 with the built dist, and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure. +`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`; every host-level `skill-local` root (`dshHome`, `agentsHome`, and `bundledSkillDir`) pinned beneath the temp workspace with watching disabled, because ambient skill catalogs are model-visible input; `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md); `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor); the webserver row pinned to port 0 with the built dist; and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure. Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the open seam on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the seam empty, so a stray stream fails loud with NO_ADAPTER. @@ -76,7 +76,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot ## Testing -`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position. +`pnpm run test:web` builds and runs the lane keylessly; `test:web:built` runs it against existing build artifacts. `DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` records a prompting scenario against the live model, and `DSH_SNAPSHOT=refresh pnpm run test:web` rewrites aria goldens keylessly. CI explicitly selects replay mode. The scaffold hermeticity scenario populates distinct entries in all three ambient skill roots and requires none to enter the assembled catalog. `dsh-llm-replay` unit coverage pins pacing, cancellation, consumption diagnostics, sidecar validation, indexed replacement, and the single append position. ## Deferred diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md index b9a7d05003..1b2ea038b9 100644 --- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md +++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md @@ -16,7 +16,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu 一个普通的共享 fixture 模块（[测试政策认可的形态](../../../../docs/testing.md)），不是包：值得门禁把守的逻辑——回放推导、会话解析、日志脱敏、持久化——都在已受门禁的包 `dsh-llm-replay`、`dsh-acp-snapshot`、`dsh-session-persistence-jsonl` 中；剩下的只是启动接线和浏览器胶水，而驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100% 覆盖率。 -`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。 +`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。 无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。 @@ -76,7 +76,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu ## Testing -`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。 +`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。 ## 暂缓 diff --git a/apps/web/tests/scaffold-hermetic.e2e.ts b/apps/web/tests/scaffold-hermetic.e2e.ts new file mode 100644 index 0000000000..6e14eebfa5 --- /dev/null +++ b/apps/web/tests/scaffold-hermetic.e2e.ts @@ -0,0 +1,57 @@ +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it } from 'vitest' +import type {} from '@deepseek-ai/dsh-skill' +import { launchWebScaffold, type WebScaffold } from './scaffold.ts' + +async function writeSkill(root: string, name: string): Promise { + const bundle = join(root, name) + await mkdir(bundle, { recursive: true }) + await writeFile(join(bundle, 'SKILL.md'), `--- +name: ${name} +description: Must not enter the Web replay scaffold +--- + +Ambient host state. +`) +} + +it('isolates replay skill discovery from every ambient host root', async () => { + const ambient = await mkdtemp(join(tmpdir(), 'dsh-web-ambient-skills-')) + const dshHome = join(ambient, 'dsh-home') + const agentsHome = join(ambient, 'agents-home') + const bundled = join(ambient, 'bundled') + await Promise.all([ + writeSkill(join(dshHome, 'skills'), 'ambient-dsh'), + writeSkill(join(agentsHome, 'skills'), 'ambient-agents'), + writeSkill(bundled, 'ambient-bundled'), + ]) + + const originalDshHome = process.env.DSH_HOME + const originalAgentsHome = process.env.DSH_AGENTS_HOME + const originalBundled = process.env.DSH_BUNDLED_SKILL_DIR + process.env.DSH_HOME = dshHome + process.env.DSH_AGENTS_HOME = agentsHome + process.env.DSH_BUNDLED_SKILL_DIR = bundled + let scaffold: WebScaffold | undefined + try { + scaffold = await launchWebScaffold() + const names = (await scaffold.ctx.skills.list({ cwd: scaffold.workspaceCwd })).map(skill => skill.name) + expect(names).not.toContain('ambient-dsh') + expect(names).not.toContain('ambient-agents') + expect(names).not.toContain('ambient-bundled') + } finally { + try { + await scaffold?.close() + } finally { + if (originalDshHome === undefined) delete process.env.DSH_HOME + else process.env.DSH_HOME = originalDshHome + if (originalAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME + else process.env.DSH_AGENTS_HOME = originalAgentsHome + if (originalBundled === undefined) delete process.env.DSH_BUNDLED_SKILL_DIR + else process.env.DSH_BUNDLED_SKILL_DIR = originalBundled + await rm(ambient, { recursive: true, force: true }) + } + } +}) diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index 1c030b4097..cfa0374c77 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -9,12 +9,13 @@ // from live session memory), refresh (keyless replay that rewrites goldens). // // Composition divergences from `dsh web`, all deliberate, all via include -// patches after the shipped surface overlay: temp persistenceRoot; -// workspace-context disabled (recorded fixtures must not embed this repo's -// AGENTS.md); session-title-llm disabled (its fire-and-forget title call -// would race the loop for the session's replay cursor); webserver pinned to -// port 0 with the built dist; keyless modes disable llm-deepseek and fill -// the open llm seam post-boot with installLlmReplay on the settled root ctx +// patches after the shipped surface overlay: temp persistenceRoot; local skill +// roots confined to the temp workspace; workspace-context disabled (recorded +// fixtures must not embed this repo's AGENTS.md); session-title-llm disabled +// (its fire-and-forget title call would race the loop for the session's replay +// cursor); webserver pinned to port 0 with the built dist; keyless modes +// disable llm-deepseek and fill the open llm seam post-boot with +// installLlmReplay on the settled root ctx // (the plugin-row path discards the ReplayHandle; the direct install keeps // assertConsumed for the teardown fixture-consumption check). import { existsSync } from 'node:fs' @@ -172,6 +173,19 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise Date: Thu, 30 Jul 2026 19:38:18 +0800 Subject: [PATCH 44/67] fix(web): keep the plan card to decisions it can actually answer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups on the presentation intent. The card claimed any single-question request declaring the intent, then sent one of two labels — so a producer offering a third option, or a multi-select batch, lost answers the generic flow would have shown. That contradicts the intent's own contract, so `planReviewOf` now claims only a binary single choice and leaves everything else to the flow that can express it. `ask()` also rejects a plan-review intent on a question with no `detail`: the intent declares detail IS the plan, and without one a honouring UI asks the user to approve something invisible. The client keeps its own fallback — it sits downstream of a wire boundary — but the misconfiguration now fails at the asker. `planReviewOf` stops being a value export of the client contract face (client export discipline: pure helpers stay internal; the tests already import it relatively), and the ui-question README fallback list, both languages, now states every condition the code enforces. --- ...0-plan-review-presentation-intent.i18n.yaml | 4 ++-- ...26-07-30-plan-review-presentation-intent.md | 6 +++--- ...07-30-plan-review-presentation-intent.zh.md | 6 +++--- .../user-interaction.i18n.yaml | 4 ++-- docs/core-data-structures/user-interaction.md | 4 ++-- .../user-interaction.zh.md | 4 ++-- packages/client/ui-question/README.i18n.yaml | 4 ++-- packages/client/ui-question/README.md | 2 +- packages/client/ui-question/README.zh.md | 2 +- .../ui-question/src/client/contract/slots.ts | 18 ++++++++++++------ .../client/ui-question/src/client/index.ts | 2 +- .../tests/plan-review-panel.spec.tsx | 7 +++++++ packages/ui/user-interaction/README.i18n.yaml | 4 ++-- packages/ui/user-interaction/README.md | 2 +- packages/ui/user-interaction/README.zh.md | 2 +- packages/ui/user-interaction/src/index.ts | 16 ++++++++++++---- packages/ui/user-interaction/src/types.ts | 2 +- .../tests/user-interaction.spec.ts | 18 ++++++++++++++++++ 18 files changed, 73 insertions(+), 34 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml index 3de0b88f5c..d6f77e3e14 100644 --- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md -2026-07-30-plan-review-presentation-intent.md: aa85156d87a35d049f3cfab465fc668a63781a73 -2026-07-30-plan-review-presentation-intent.zh.md: fffee3de6341d45b26b88e1cc67a3895e747afac +2026-07-30-plan-review-presentation-intent.md: aeab12aac308c24aa5c4b5953a60ae0f2cf6c5b5 +2026-07-30-plan-review-presentation-intent.zh.md: 4096018e374212c821675ce6ed3a2355df20edc9 diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md index aa85156d87..aeab12aac3 100644 --- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md @@ -16,11 +16,11 @@ A question may declare a **presentation intent**, and the Web composer renders a An intent shapes presentation only. The answer protocol is untouched: a UI honouring the intent answers with the same option labels a generic UI would send, so `exit_plan_mode` reads one answer shape regardless of which surface collected it, and a UI that does not know a tag renders the generic flow with nothing lost but the layout. -`approve` names the affirmative option instead of relying on option order, so no UI infers a verdict from a position. Because the types cannot tie that label to the question's own option list, `UserInteractionService.ask()` rejects an intent whose `approve` names none of its options (`BAD_INTENT`) — at the asker, before any UI can answer a choice that was never offered. On the wire the intent is a discriminated union, so an unrecognised tag is a rejected frame rather than a silently generic render. +`approve` names the affirmative option instead of relying on option order, so no UI infers a verdict from a position. Two assertions an intent makes are beyond the types, and `UserInteractionService.ask()` rejects both as `BAD_INTENT` at the asker: an `approve` naming none of that question's own options — before any UI can answer a choice never offered — and an intent on a question with no `detail`, the thing it declares itself a review of, which would ask the user to approve something invisible. On the wire the intent is a discriminated union, so an unrecognised tag is a rejected frame rather than a silently generic render. `ui-question` renders the intent as `PlanReviewPanel`, in the waiting-approval card language: the amber strip carries `Plan review`, the plan is the scrolling markdown body, and the decision row holds three actions — `Chat about it`, `Refuse`, `Approve`. The question text becomes the card's accessible name rather than a headline, because the buttons already say what the decision is. Approve and Refuse answer with the asker's own option labels and keep the asker's descriptions as tooltips; `Chat about it` cancels the request, which returns the composer so the user can simply say what they want. All copy is bilingual under the existing `question` namespace. -Routing lives inside the single composer entry (`QuestionComposer` chooses the shape) rather than in a second chain registration, and `planReviewOf` claims a request only when the batch is one question that declares the intent, carries the plan as its `detail`, and offers the named approve label. Anything else stays a generic question — the client is downstream of a wire boundary, so a request it cannot render as a card must still be answerable. +Routing lives inside the single composer entry (`QuestionComposer` chooses the shape) rather than in a second chain registration, and `planReviewOf` claims a request only when the card can send every answer that request allows: one question declaring the intent, the plan as its `detail`, the named approve label offered, and a binary single choice — at most one option besides approve, and not multi-select. A third option or a multi-select batch has answers two buttons cannot express, so the generic flow keeps it, and keeps anything else the card cannot render. "Presentation only" is therefore literal: an intent never costs the user a reachable answer, and the client — downstream of a wire boundary — leaves every request answerable. Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reached the model as "the user cancelled ask_user_question", naming a tool it never called; `exit_plan_mode` now reports that the user dismissed the review to speak instead and to stay in plan mode and wait. Every other ask failure — an abort from turn cancel or provider teardown, where no user is coming — keeps its own message. @@ -50,6 +50,6 @@ A deployment whose client half predates this change still shows the quiz layout ## Testing -`ui-question` tests pin the narrowing (single-question batch, intent present, plan as detail, named approve label offered, decline absent when only approve is offered) and the panel (strip, markdown plan, accessible name, absence of pager/radio/skip/custom, approve and decline answering with the asker's labels, dismissal cancelling, one-shot latch with re-arm and message on a rejected receipt, tooltips present and absent, both locales). `user-interaction` tests pin `BAD_INTENT` and intent pass-through; `plan-mode` tests pin the declared intent against its own option list and both failure messages; the apiproxy schema test pins wire acceptance and an unknown tag's rejection. +`ui-question` tests pin the narrowing (single-question batch, intent present, plan as detail, named approve label offered, binary single choice, decline absent when only approve is offered) and the panel (strip, markdown plan, accessible name, absence of pager/radio/skip/custom, approve and decline answering with the asker's labels, dismissal cancelling, one-shot latch with re-arm and message on a rejected receipt, tooltips present and absent, both locales). `user-interaction` tests pin both `BAD_INTENT` rejections and intent pass-through; `plan-mode` tests pin the declared intent against its own option list and both failure messages; the apiproxy schema test pins wire acceptance and an unknown tag's rejection. The `plan-review` Web e2e lane records `/plan` entering plan mode for real, the model calling `exit_plan_mode`, the decision card taking the composer (asserting the generic flow did **not** claim the request), and the card's own Approve completing the turn — two keyless goldens, the waiting card and the approved transcript. diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md index fffee3de63..4096018e37 100644 --- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md +++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md @@ -16,11 +16,11 @@ Status: implemented 意图只塑造呈现。回答协议不变：遵循意图的 UI 回答的仍是通用 UI 会发送的那些选项标签，因此无论由哪个界面收集，`exit_plan_mode` 读到的都是同一种回答形状；而不认识某个标签的 UI 渲染通用流程，除布局之外一无所失。 -`approve` 指名肯定选项，而不依赖选项顺序，因此没有任何 UI 会从位置推断裁决。由于类型无法把该标签绑定到问题自身的选项列表，`UserInteractionService.ask()` 会拒绝 `approve` 未命中任一选项的意图（`BAD_INTENT`）—— 拦在提问方一侧，早于任何 UI 回答一个从未被提供过的选择。在协议格式（wire format）上意图是可辨识联合，因此无法识别的标签是被拒绝的帧，而不是静默退回通用渲染。 +`approve` 指名肯定选项，而不依赖选项顺序，因此没有任何 UI 会从位置推断裁决。意图作出的两项断言超出类型的表达能力，`UserInteractionService.ask()` 都以 `BAD_INTENT` 在提问方一侧拒绝：`approve` 未命中该问题自身的任一选项 —— 早于任何 UI 回答一个从未被提供过的选择；以及意图落在没有 `detail` 的问题上，而 `detail` 正是它自称在审阅的东西，那会让用户去批准一件看不见的事。在协议格式（wire format）上意图是可辨识联合，因此无法识别的标签是被拒绝的帧，而不是静默退回通用渲染。 `ui-question` 把该意图渲染为 `PlanReviewPanel`，沿用等待审批卡片的语言：琥珀色条带写着 `Plan review`，计划是可滚动的 markdown 主体，决定行放三个操作 —— `Chat about it`、`Refuse`、`Approve`。问题文本成为卡片的无障碍名称而非标题，因为按钮已经说明了这次决定是什么。Approve 与 Refuse 用提问方自己的选项标签回答，并把提问方的描述保留为 tooltip；`Chat about it` 取消该请求，从而让输入区归位，用户直接说他想说的话即可。所有文案在既有 `question` 命名空间下双语。 -路由住在单一输入区条目内部（由 `QuestionComposer` 选择形状），而不是第二个链式注册；`planReviewOf` 仅在这一批只有一个问题、该问题声明了意图、以 `detail` 承载计划、并提供了被指名的批准标签时才接管请求。其他情形一律保持通用问题 —— 客户端位于协议边界的下游，它无法渲染成卡片的请求仍必须可回答。 +路由住在单一输入区条目内部（由 `QuestionComposer` 选择形状），而不是第二个链式注册；`planReviewOf` 仅在卡片能够发出该请求允许的每一个答案时才接管：只有一个问题且声明了意图、以 `detail` 承载计划、提供了被指名的批准标签，且是二元单选 —— 除批准外最多一个选项，且非多选。出现第三个选项或多选批次时，其答案是两个按钮无法表达的，通用流程保留它，也保留其他任何卡片渲染不了的请求。因此"只塑造呈现"是字面意义上的：意图绝不让用户失去一个可达的答案，而位于协议边界下游的客户端让每个请求都保持可回答。 放弃审阅成为面向模型的独立结果。`ASK_CANCELLED` 以前传到模型的是"the user cancelled ask_user_question"，指名了一个它从未调用的工具；现在 `exit_plan_mode` 报告用户放弃审阅是为了改用说话，并要求留在 plan mode 中等待。其余每一种 ask 失败 —— 轮次取消或提供方拆卸导致的中止，那里并没有用户会来 —— 保留它们自己的消息。 @@ -50,6 +50,6 @@ Status: implemented ## 测试 -`ui-question` 测试钉住收窄（单问题批、意图存在、计划作为 detail、被指名的批准标签确实被提供、只提供批准时 decline 缺席）与面板（条带、markdown 计划、无障碍名称、无分页/单选/跳过/自定义、批准与拒绝用提问方的标签回答、放弃触发取消、一次性闭锁在回执被拒时重新武装并给出消息、tooltip 有与无、两种语言）。`user-interaction` 测试钉住 `BAD_INTENT` 与意图透传；`plan-mode` 测试钉住已声明的意图与其自身选项列表的一致、以及两条失败消息；apiproxy schema 测试钉住协议接受与未知标签的拒绝。 +`ui-question` 测试钉住收窄（单问题批、意图存在、计划作为 detail、被指名的批准标签确实被提供、二元单选、只提供批准时 decline 缺席）与面板（条带、markdown 计划、无障碍名称、无分页/单选/跳过/自定义、批准与拒绝用提问方的标签回答、放弃触发取消、一次性闭锁在回执被拒时重新武装并给出消息、tooltip 有与无、两种语言）。`user-interaction` 测试钉住两种 `BAD_INTENT` 拒绝与意图透传；`plan-mode` 测试钉住已声明的意图与其自身选项列表的一致、以及两条失败消息；apiproxy schema 测试钉住协议接受与未知标签的拒绝。 `plan-review` Web e2e 通道录制了 `/plan` 真实进入 plan mode、模型调用 `exit_plan_mode`、决定卡片接管输入区（并断言通用流程**没有**接管该请求）、以及卡片自身的 Approve 完成该轮 —— 两份无密钥 golden：等待中的卡片与批准后的会话记录。 diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml index ee739a59d3..bc281d9bb7 100644 --- a/docs/core-data-structures/user-interaction.i18n.yaml +++ b/docs/core-data-structures/user-interaction.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/user-interaction.md -user-interaction.md: 4ebaf66131b3ab7a7c205bef1ba533e9321d4f0b -user-interaction.zh.md: 8e5542b995bbf061b097d650ab79505e93151fa8 +user-interaction.md: 2483382eee07d379b13d456149096c8afab70e4b +user-interaction.zh.md: 57f57277975597fff712705cc741ae8e78643642 diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md index 4ebaf66131..2483382eee 100644 --- a/docs/core-data-structures/user-interaction.md +++ b/docs/core-data-structures/user-interaction.md @@ -22,7 +22,7 @@ interface AskUserQuestionOption { ## Presentation intent -`AskUserQuestionIntent` is the optional declaration that a question IS a decision of a known shape. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent shapes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads one answer shape either way. `approve` names the affirmative option instead of relying on option order, and `ask()` rejects an `approve` naming none of its own question's options. +`AskUserQuestionIntent` is the optional declaration that a question IS a decision of a known shape. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent shapes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads one answer shape either way. `approve` names the affirmative option instead of relying on option order. `ask()` rejects the two assertions no type can carry: an `approve` naming none of its own question's options, and an intent on a question with no `detail`. ```ts type-equiv /** @@ -33,7 +33,7 @@ interface AskUserQuestionOption { * either way — an intent shapes presentation only, never the protocol. */ type AskUserQuestionIntent = { - /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */ kind: 'plan-review' /** * The option label that approves the plan; every other option declines it. diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md index 8e5542b995..57f5727797 100644 --- a/docs/core-data-structures/user-interaction.zh.md +++ b/docs/core-data-structures/user-interaction.zh.md @@ -22,7 +22,7 @@ interface AskUserQuestionOption { ## 呈现意图 -`AskUserQuestionIntent` 是一项可选声明：某个问题本身就是一次已知形状的决定。它按 `kind` 打标签，因此意图可以扩充；不认识某个标签的 UI 渲染通用选项列表。意图只塑造呈现 —— 遵循它的 UI 回答的仍是通用 UI 会发送的那些 option label，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名肯定选项，而不依赖选项顺序；`ask()` 会拒绝未命中该问题自身任一选项的 `approve`。 +`AskUserQuestionIntent` 是一项可选声明：某个问题本身就是一次已知形状的决定。它按 `kind` 打标签，因此意图可以扩充；不认识某个标签的 UI 渲染通用选项列表。意图只塑造呈现 —— 遵循它的 UI 回答的仍是通用 UI 会发送的那些 option label，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名肯定选项，而不依赖选项顺序。有两项断言是任何类型都承载不了的，`ask()` 会拒绝它们：`approve` 未命中该问题自身的任一选项，以及意图落在没有 `detail` 的问题上。 ```ts type-equiv /** @@ -33,7 +33,7 @@ interface AskUserQuestionOption { * either way — an intent shapes presentation only, never the protocol. */ type AskUserQuestionIntent = { - /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */ kind: 'plan-review' /** * The option label that approves the plan; every other option declines it. diff --git a/packages/client/ui-question/README.i18n.yaml b/packages/client/ui-question/README.i18n.yaml index cd2f0556a4..914485fbbb 100644 --- a/packages/client/ui-question/README.i18n.yaml +++ b/packages/client/ui-question/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-question/README.md -README.md: 6b40c503be61c2458cefceabbb35e16a3befbe66 -README.zh.md: 7c0c4ee67d1ef8b4507f3899bdb1ae2f76408032 +README.md: 5ebba2a1da6e6108b82e9deb235b84f987600345 +README.zh.md: 0aa6428a9b6472fc5b525c11b4716ebc50c378c3 diff --git a/packages/client/ui-question/README.md b/packages/client/ui-question/README.md index 6b40c503be..5ebba2a1da 100644 --- a/packages/client/ui-question/README.md +++ b/packages/client/ui-question/README.md @@ -6,7 +6,7 @@ Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user` The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`. -A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. A request that declares no intent, batches more than one question, or fails to offer the named approve label stays on the generic flow — the layout is all an intent changes, never the answer. +A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. The card claims a request only when it can send every answer that request allows: one question, the intent declared, the plan present as `detail`, the named approve label offered, and a binary single choice (at most one option besides approve, not multi-select). Anything else — no intent, a batch of several questions, a missing plan, an approve label naming no option, a third option, a multi-select decision — stays on the generic flow, which can express it. An intent changes the layout, never which answers are reachable. Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally. diff --git a/packages/client/ui-question/README.zh.md b/packages/client/ui-question/README.zh.md index 7c0c4ee67d..0aa6428a9b 100644 --- a/packages/client/ui-question/README.zh.md +++ b/packages/client/ui-question/README.zh.md @@ -6,7 +6,7 @@ Web `ask_user_question` 功能插件。只有选择 Web 功能时，其主机侧 组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信内容策略。封顶卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。 -若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review` —— 由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置 —— 采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。未声明意图、一批含多个问题、或未提供被指名的批准标签的请求，一律留在通用流程上 —— 意图改变的只是布局，从不改变答案。 +若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review` —— 由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置 —— 采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。卡片只在能够发出该请求允许的每一个答案时才接管：只有一个问题、声明了意图、计划以 `detail` 存在、提供了被指名的批准标签，且是二元单选（除批准外最多一个选项，且非多选）。其他任何情形 —— 没有意图、一批含多个问题、缺少计划、批准标签未命中任何选项、出现第三个选项、多选决定 —— 都留在能够表达它的通用流程上。意图改变的只是布局，从不改变可达的答案。 选择状态只存在于以请求 rpcId 为 key 的组件本地。使用相同 id 回放时，只要组件仍挂载，就会保留草稿；主机发出的 `question/resolved` 则会移除编辑器。主机仍具有最终决定权：HTTP 交付成功不会在本地移除待处理状态。 diff --git a/packages/client/ui-question/src/client/contract/slots.ts b/packages/client/ui-question/src/client/contract/slots.ts index f92eb33f52..8f9d9f8c75 100644 --- a/packages/client/ui-question/src/client/contract/slots.ts +++ b/packages/client/ui-question/src/client/contract/slots.ts @@ -49,12 +49,16 @@ export interface PlanReview { * Narrow a request to a renderable plan review, or return undefined to leave it * to the generic question flow. * - * The card is one decision over one plan, so it claims a request only when the - * batch is a single question that declares the intent, carries the plan as its - * detail, and offers the approve label the intent names. The asker's own - * service validates that label, but this is a wire boundary: a request failing - * any part of it still renders and stays answerable as a generic question - * rather than reaching a card that cannot express it. + * The card is one decision over one plan, and it claims a request only when it + * can send every answer that request allows — an intent changes the layout, + * never which answers are reachable. So the batch must be a single question + * that declares the intent, carries the plan as its detail, offers the approve + * label the intent names, and is a binary single choice: at most one option + * besides approve, and not multi-select. A third option or a multi-select batch + * has answers two buttons cannot express, so the generic flow keeps it — as it + * keeps any request whose intent the asker's own service would have rejected, + * because the client sits downstream of a wire boundary and every request must + * stay answerable. * * @param questions - the request's whole question batch. * @returns The narrowed review, or undefined when the generic flow owns it. @@ -65,7 +69,9 @@ export function planReviewOf(questions: readonly QuestionItem[]): PlanReview | u const question = questions[0] as QuestionItem const intent = question.intent if (intent?.kind !== 'plan-review' || question.detail === undefined) return undefined + if (question.multiSelect === true) return undefined const options = question.options ?? [] + if (options.length > 2) return undefined const approve = options.find(option => option.label === intent.approve) if (approve === undefined) return undefined const decline = options.find(option => option.label !== intent.approve) diff --git a/packages/client/ui-question/src/client/index.ts b/packages/client/ui-question/src/client/index.ts index 9c6893fd18..8cc25aeb88 100644 --- a/packages/client/ui-question/src/client/index.ts +++ b/packages/client/ui-question/src/client/index.ts @@ -20,7 +20,7 @@ import type { QuestionWait } from './contract/slots.ts' import { QuestionComposer } from './QuestionComposer.tsx' import { en, zh, type QuestionKey } from './locales.ts' -export { PendingQuestion, planReviewOf } from './contract/slots.ts' +export { PendingQuestion } from './contract/slots.ts' export type { PlanReview, QuestionAnswer, QuestionComposerProps, QuestionWait, } from './contract/slots.ts' diff --git a/packages/client/ui-question/tests/plan-review-panel.spec.tsx b/packages/client/ui-question/tests/plan-review-panel.spec.tsx index 3c2c456c57..069445415f 100644 --- a/packages/client/ui-question/tests/plan-review-panel.spec.tsx +++ b/packages/client/ui-question/tests/plan-review-panel.spec.tsx @@ -95,6 +95,13 @@ describe('planReviewOf', () => { ...questions()[0] as object, intent: { kind: 'plan-review', approve: 'Ship it' }, }]], ['an intent with no options at all', () => [{ ...questions()[0] as object, options: undefined }]], + // Two buttons cannot send a third label or a combination, and the generic + // flow can: an intent never costs the user a reachable answer. + ['a third option the card could not offer', () => [{ + ...questions()[0] as object, + options: [{ label: 'Approve' }, { label: 'Keep planning' }, { label: 'Start over' }], + }]], + ['a multi-select decision', () => [{ ...questions()[0] as object, multiSelect: true }]], ])('declines %s, leaving the request to the generic flow', (_case, build) => { expect(planReviewOf(build() as never)).toBeUndefined() }) diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml index 96973400df..a74e6ec71b 100644 --- a/packages/ui/user-interaction/README.i18n.yaml +++ b/packages/ui/user-interaction/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/ui/user-interaction/README.md -README.md: f134e912149190efb81ea9f64c5d63632ce8c626 -README.zh.md: ab6432dcbddc36d3ef9ca957b3901cb76257539a +README.md: d62e75d110b8be339c5f9449b0834320f695ac99 +README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816 diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md index f134e91214..d62e75d110 100644 --- a/packages/ui/user-interaction/README.md +++ b/packages/ui/user-interaction/README.md @@ -24,7 +24,7 @@ When an answer includes `custom`, `selected` is empty; custom text is an overrid ### Presentation intent -`intent` declares that a question IS a decision of a known shape, so a UI that recognises the tag may present it as such — `plan-review` says `detail` is a plan under review, and `dsh-plan-mode` sets it on the `exit_plan_mode` question. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, and a UI that does not know the tag renders the generic option list, so callers read one answer shape either way. `approve` names the label that approves rather than relying on option order; `ask()` rejects an intent whose `approve` names none of that question's own options with `BAD_INTENT`, since no type can tie the two together. +`intent` declares that a question IS a decision of a known shape, so a UI that recognises the tag may present it as such — `plan-review` says `detail` is a plan under review, and `dsh-plan-mode` sets it on the `exit_plan_mode` question. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, and a UI that does not know the tag renders the generic option list, so callers read one answer shape either way. `approve` names the label that approves rather than relying on option order. `ask()` rejects with `BAD_INTENT` the two assertions no type can carry: an `approve` naming none of that question's own options, and an intent on a question with no `detail` — the thing it declares itself a review of. ## Role diff --git a/packages/ui/user-interaction/README.zh.md b/packages/ui/user-interaction/README.zh.md index ab6432dcbd..55258e85e5 100644 --- a/packages/ui/user-interaction/README.zh.md +++ b/packages/ui/user-interaction/README.zh.md @@ -24,7 +24,7 @@ ### 呈现意图 -`intent` 声明某个问题本身就是一次已知形状的决定，因此认识该标签的 UI 可以照此呈现 —— `plan-review` 表示 `detail` 是一份待审阅的计划，`dsh-plan-mode` 会在 `exit_plan_mode` 的问题上设置它。意图只塑造呈现：遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，不认识该标签的 UI 渲染通用选项列表，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名表示批准的标签，而不依赖选项顺序；由于没有类型能把两者绑定起来，`ask()` 会以 `BAD_INTENT` 拒绝 `approve` 未命中该问题自身任一选项的意图。 +`intent` 声明某个问题本身就是一次已知形状的决定，因此认识该标签的 UI 可以照此呈现 —— `plan-review` 表示 `detail` 是一份待审阅的计划，`dsh-plan-mode` 会在 `exit_plan_mode` 的问题上设置它。意图只塑造呈现：遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，不认识该标签的 UI 渲染通用选项列表，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名表示批准的标签，而不依赖选项顺序。有两项断言是任何类型都承载不了的，`ask()` 会以 `BAD_INTENT` 拒绝它们：`approve` 未命中该问题自身的任一选项，以及意图落在没有 `detail` 的问题上 —— 而 `detail` 正是它自称在审阅的东西。 ## 职责 diff --git a/packages/ui/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts index af0aa40e7b..506b3c6bfe 100644 --- a/packages/ui/user-interaction/src/index.ts +++ b/packages/ui/user-interaction/src/index.ts @@ -87,10 +87,13 @@ export class UserInteractionService extends Service { if (request.questions.length === 0) { throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS') } - // A presentation intent names an option label the types cannot pin to its - // own question's option list. A UI honouring the intent answers with that - // label, so a name matching nothing would answer a choice the asker never - // offered — caught here, at the asker, rather than in a UI. + // A presentation intent asserts two things the types cannot: that the + // named approve label is one of this question's own options, and that a + // plan-review carries the plan it is a review of. A UI honouring the + // intent answers with that label, and shows that detail as the plan, so + // either gap would put a choice the asker never offered — or an approval of + // something invisible — in front of the user. Caught at the asker, where + // the mistake is, rather than in each UI. for (const question of request.questions) { const intent = question.intent if (intent === undefined) continue @@ -100,6 +103,11 @@ export class UserInteractionService extends Service { + `${JSON.stringify(intent.approve)} names none of its options`, 'BAD_INTENT') } + if (question.detail === undefined) { + throw new UserInteractionError( + `question ${question.id} declares intent ${intent.kind} without the detail it reviews`, + 'BAD_INTENT') + } } if (this.provider === undefined) { throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER') diff --git a/packages/ui/user-interaction/src/types.ts b/packages/ui/user-interaction/src/types.ts index 15747e371c..63949e81a1 100644 --- a/packages/ui/user-interaction/src/types.ts +++ b/packages/ui/user-interaction/src/types.ts @@ -21,7 +21,7 @@ export interface AskUserQuestionOption { * either way — an intent shapes presentation only, never the protocol. */ export type AskUserQuestionIntent = { - /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */ + /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */ kind: 'plan-review' /** * The option label that approves the plan; every other option declines it. diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/ui/user-interaction/tests/user-interaction.spec.ts index e9fca39761..df6b878cbd 100644 --- a/packages/ui/user-interaction/tests/user-interaction.spec.ts +++ b/packages/ui/user-interaction/tests/user-interaction.spec.ts @@ -104,6 +104,24 @@ describe('UserInteractionService', () => { expect(p.ask).not.toHaveBeenCalled() }) + it('rejects a plan-review intent on a question carrying no plan to review', async () => { + const ctx = new Context() + await ctx.plugin(UserInteractionService) + const p = { ask: vi.fn(async () => ({ answers: [] })) } + ctx.userInteraction.registerProvider(p) + + // Detail IS the plan for this intent, so a UI honouring it would ask the + // user to approve something they cannot see. + await expect(ctx.userInteraction.ask({ + questions: [{ + id: 'plan-review', question: 'Approve?', + options: [{ label: 'Approve' }, { label: 'Keep planning' }], + intent: { kind: 'plan-review', approve: 'Approve' }, + }], + })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'BAD_INTENT' }) + expect(p.ask).not.toHaveBeenCalled() + }) + it('passes an intent through once its approve label names an offered option', async () => { const ctx = new Context() await ctx.plugin(UserInteractionService) From 49678f38aedf3314182c6a1ddd4321ecd5e759e0 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 18:59:06 +0800 Subject: [PATCH 45/67] test(typert): allow catalog analysis under coverage --- .../typert/generator/tests/cordis-catalog-contract.spec.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts index 4092ac7e63..1bfe0f5e46 100644 --- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts +++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts @@ -125,7 +125,7 @@ afterEach(() => { while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true }) }) -describe('gen-cordis-catalog collectEvents', () => { +describe('gen-cordis-catalog collectEvents', { timeout: 30_000 }, () => { it('extracts a well-formed event with its @mode and JSDoc', () => { const events = collectEvents(make( ' /**\n * A thing happened.\n * @param id - which thing.\n * @mode emit\n */\n \'fix/happened\'(id: string): void', @@ -239,7 +239,7 @@ describe('gen-cordis-catalog collectEvents', () => { }) }) -describe('gen-cordis-catalog collectServices', () => { +describe('gen-cordis-catalog collectServices', { timeout: 30_000 }, () => { const WELL_FORMED = `/** Fixture service. */ export class FixService { /** From 6777e4fab97315c398f676eb37b9416c933c435d Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:14:03 +0800 Subject: [PATCH 46/67] fix(fs-search): make glob sampling an explicit choice --- .../2026-07-27-glob-sampling.i18n.yaml | 4 +- .../bug-fix/2026-07-27-glob-sampling.md | 16 ++++---- .../bug-fix/2026-07-27-glob-sampling.zh.md | 16 ++++---- apps/cli/config/base.cordis.yml | 2 + docs/config-catalog.md | 4 +- docs/tool-catalog.md | 4 +- .../tests/fs-search.cordis.snapshot.yml | 1 + examples/acp-agent/tests/fs-search.cordis.yml | 1 + packages/fs/tool-fs-search/README.i18n.yaml | 4 +- packages/fs/tool-fs-search/README.md | 31 ++++++++------ packages/fs/tool-fs-search/README.zh.md | 31 ++++++++------ packages/fs/tool-fs-search/src/glob.ts | 41 +++++++++++++------ packages/fs/tool-fs-search/src/index.ts | 6 ++- .../tool-fs-search/tests/integration.spec.ts | 2 +- .../fs/tool-fs-search/tests/load-path.spec.ts | 2 +- .../fs/tool-fs-search/tests/tools.spec.ts | 38 +++++++++++++++-- scripts/gen-tool-catalog.ts | 4 +- 17 files changed, 140 insertions(+), 67 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml index 7c11db5207..6a898fa0a4 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md -2026-07-27-glob-sampling.md: b9dfc7fc89ff61824094ccd5297f766c665f4edb -2026-07-27-glob-sampling.zh.md: 4f022467e461247c746e906b32f5ecffcb885d56 +2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d +2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300 diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md index b9dfc7fc89..67912cf290 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.md @@ -12,15 +12,17 @@ Three individually valid behaviors composed into the false impression. A glob wi ## Decision -A result that fits within `globMaxResults` remains complete and byte-for-byte modification-time ordered. An over-cap result is sampled round-robin across the complete result's top-level entries: every entry receives one slot before any receives a second, exhausted groups drop out, and relative order remains stable within each group. Grouping is relative to the actual search root, including an explicit `path`. +A result that fits within `globMaxResults` remains complete and byte-for-byte modification-time ordered. The required `sampleOverCapGlobResults` config has no fallback: `false` retains the modification-time head for an over-cap result, while `true` samples round-robin across the complete result's top-level entries. In sampling mode, every entry receives one slot before any receives a second, exhausted groups drop out, relative order remains stable within each group, and grouping is relative to the actual search root, including an explicit `path`. -The footer states that the page is a cross-entry sample rather than the modification-time head, reports how many top-level entries it reaches when that fact adds information, and preserves the complete sorted list in the spill artifact. When more top-level entries exist than inline slots, it tells the model to narrow `path`. +In sampling mode, the footer states that the page is a cross-entry sample rather than the modification-time head and reports how many top-level entries it reaches when that fact adds information. When more top-level entries exist than inline slots, it tells the model to narrow `path`. Head mode keeps the ordinary capped-result footer. When spill succeeds, both modes preserve the complete sorted list in the artifact. -The prompt and schema also state that a pattern without `/` matches at any depth and that glob returns files, never directory entries. Directory orientation remains ordinary shell work in deployments that expose the model-facing bash tool: use `ls` for one directory, and glob for a named file-path pattern across the tree. `ctx.fs.listDir` remains an internal provider primitive used by skill discovery; this decision adds no model-facing `list` tool. +The prompt and schema state the configured over-cap ordering, that a pattern without `/` matches at any depth, and that glob returns files, never directory entries. The shipped CLI composition explicitly selects head mode; deployments that want representative capped pages select sampling mode. Directory orientation remains ordinary shell work in deployments that expose the model-facing bash tool: use `ls` for one directory, and glob for a named file-path pattern across the tree. `ctx.fs.listDir` remains an internal provider primitive used by skill discovery; this decision adds no model-facing `list` tool. ## Alternatives considered -**Keep the modification-time head and only warn about concentration.** Rejected after measuring the failure shape. A warning asks the model to distrust the only paths it received; representative data fixes the answer directly. +**Keep the modification-time head as the only behavior.** Rejected after measuring the failure shape. Some deployments need the stable ordering, but a deployment that values workspace orientation can explicitly select representative data instead of asking the model to distrust the only paths it received. + +**Give the sampling choice a default.** Rejected. No product-wide evidence establishes either ordering as the implicit contract, so every composition selects one and misconfiguration fails at load. **Sample every result.** Rejected. A complete result loses nothing to truncation, so modification-time order remains useful for age-oriented questions. Sampling begins only when the head stops describing the whole. @@ -36,10 +38,10 @@ The prompt and schema also state that a pattern without `/` matches at any depth ## Consequences -An over-cap glob page no longer answers age-order questions from its inline paths; its footer says so, and the spill artifact retains the complete sorted view. Sampling balances only the first segment beneath the search root, so a deeper hot subtree can still dominate within one top-level entry. +A sampling-mode over-cap page no longer answers age-order questions from its inline paths; its footer says so, and the spill artifact retains the complete sorted view. Sampling balances only the first segment beneath the search root, so a deeper hot subtree can still dominate within one top-level entry. Head mode retains the concentration risk as an explicit deployment trade-off. -The tool surface does not grow. The fix changes glob's prompt, schema description, canonical output (`root` records the sampling basis), and over-cap Native rendering while leaving fitting results unchanged. +The tool surface does not grow. Every composition must set `sampleOverCapGlobResults`; changing it alters glob's prompt, schema description, and over-cap Native rendering. The canonical output keeps `root` so sampling mode can recover its grouping basis, while fitting results remain unchanged. ## Testing -Package tests pin concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario boots a minimal real Loader/app/local-bash composition and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head. +Package tests pin the required config, both over-cap modes, their prompt and schema descriptions, concentrated and flat results, explicit roots, more groups than the JavaScript argument limit, exhausted groups, fewer slots than groups, and paths outside the workdir. The `fs-glob-sampling` ACP scenario explicitly enables sampling, boots a minimal real Loader/app/local-bash composition, and executes the real search plugin against a deterministic `rg` process fixture; its result spans four top-level entries instead of returning one subtree's head. diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md index 4f022467e4..e339a5f87b 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md @@ -12,15 +12,17 @@ Status: implemented ## 决策 -未超过 `globMaxResults` 的结果仍保持完整，且按修改时间排序的内容逐字节不变。超过上限时，系统会在完整结果的顶层条目之间按轮转方式采样：每个条目都先获得一个位置，之后才有条目获得第二个位置；已经用尽的分组会退出轮转；各组内部的相对顺序保持稳定。分组始终以实际搜索根为基准，显式指定 `path` 时也如此。 +未超过 `globMaxResults` 的结果仍保持完整，且按修改时间排序的内容逐字节不变。必填的 `sampleOverCapGlobResults` 配置没有回退值：`false` 会为超过上限的结果保留按修改时间排序的前部，`true` 则会在完整结果的顶层条目之间按轮转方式采样。采样模式下，每个条目都先获得一个位置，之后才有条目获得第二个位置；已经用尽的分组会退出轮转；各组内部的相对顺序保持稳定；分组以实际搜索根为基准，显式指定 `path` 时也如此。 -footer 会说明当前页面是跨条目的样本，而不是按修改时间排序的前部；当顶层条目覆盖数能提供额外信息时，还会报告该数量；完整排序列表仍保存在 spill 产物中。若顶层条目数量超过内联位置数，footer 会要求模型缩小 `path`。 +采样模式下，footer 会说明当前页面是跨条目的样本，而不是按修改时间排序的前部；当触达的顶层条目数能提供额外信息时，还会报告该数量。若顶层条目数量超过内联位置数，footer 会要求模型缩小 `path`。保留前部的模式沿用达到上限时的普通 footer。spill 成功时，两种模式都会在该产物中保留完整排序列表。 -提示词与 schema 还会说明：不含 `/` 的模式会匹配任意深度，glob 只返回文件，绝不返回目录条目。在向模型暴露 bash 工具的部署中，目录定位仍由普通 shell 操作完成：查看一个目录使用 `ls`，跨目录树按指定文件路径模式查找则使用 glob。skill（技能）发现流程仍将 `ctx.fs.listDir` 作为内部提供方原语使用；本决策不会新增面向模型的 `list` 工具。 +提示词与 schema 会说明配置所指定的超限结果排序方式、不含 `/` 的模式会匹配任意深度，以及 glob 只返回文件而绝不返回目录条目。随产品交付的 CLI（命令行界面）组合显式选择保留前部的模式；希望达到上限的页面具有代表性的部署则选择采样模式。在向模型暴露 bash 工具的部署中，目录定位仍由普通 shell 操作完成：查看一个目录使用 `ls`，跨目录树按指定文件路径模式查找则使用 glob。skill（技能）发现流程仍将 `ctx.fs.listDir` 作为内部提供方原语使用；本决策不会新增面向模型的 `list` 工具。 ## 考虑过的替代方案 -**保留按修改时间排序的前部，只警告结果过于集中。** 测量实际故障形态后否决。警告只会要求模型怀疑自己拿到的唯一一批路径；具有代表性的数据能直接修正答案。 +**只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。 + +**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。 **对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。 @@ -36,10 +38,10 @@ footer 会说明当前页面是跨条目的样本，而不是按修改时间排 ## 影响 -超过上限的 glob 页面无法再根据内联路径回答按时间判断新旧的问题；footer 会明确说明这一点，spill 产物仍保留完整的排序视图。采样只平衡搜索根下的第一路径段，因此某个顶层条目内部较深处、结果密集的子树仍可能占据主导。 +采样模式下，超过上限的 glob 页面无法再根据内联路径回答按时间判断新旧的问题；footer 会明确说明这一点，spill 产物仍保留完整的排序视图。采样只平衡搜索根下的第一路径段，因此某个顶层条目内部较深处、结果密集的子树仍可能占据主导。保留前部的模式则把集中风险作为显式部署取舍保留下来。 -工具接口不会扩大。此修复会更改 glob 的提示词、schema 描述、规范输出（`root` 记录采样基准）以及超过上限时的 Native 渲染，未超过上限的结果保持不变。 +工具接口不会扩大。每个组合都必须设置 `sampleOverCapGlobResults`；更改该值会改变 glob 的提示词、schema 描述以及超过上限时的 Native 渲染。规范输出保留 `root`，以便采样模式恢复其分组基准；未超过上限的结果保持不变。 ## 测试 -包测试锁定了结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会启动最小化的真实 Loader/app/local-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。 +包测试锁定了必填配置、两种超过上限模式及其提示词和 schema 描述、结果集中与扁平两种情况、显式根目录、分组数超过 JavaScript 参数个数上限、分组耗尽、位置数少于分组数，以及工作目录以外的路径。`fs-glob-sampling` ACP（Agent Client Protocol）场景会显式启用采样，启动最小化的真实 Loader/app/local-bash 组合，并让真实搜索插件对接确定性的 `rg` 进程 fixture（测试前置数据）；其结果覆盖 4 个顶层条目，而不是只返回某棵子树的前部。 diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml index 67c2b3b551..bc8c3434de 100644 --- a/apps/cli/config/base.cordis.yml +++ b/apps/cli/config/base.cordis.yml @@ -102,6 +102,8 @@ - id: tool-fs-search name: '@deepseek-ai/dsh-tool-fs-search' + config: + sampleOverCapGlobResults: false - id: workspace-context name: '@deepseek-ai/dsh-workspace-context' diff --git a/docs/config-catalog.md b/docs/config-catalog.md index dde2d6f65b..98b798b9b7 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1664,8 +1664,10 @@ Source: [`packages/fs/tool-fs/src/index.ts:24`](../packages/fs/tool-fs/src/index Requires: `tools` · `systemPrompt` · `bash` ```ts config-catalog -/** Plugin config (all optional — `Config` supplies the defaults). */ +/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */ export interface Config { + /** Whether an over-cap `glob` page is sampled across top-level entries instead of taking the modification-time head. */ + sampleOverCapGlobResults: boolean /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */ globMaxResults?: number /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */ diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index bac13da635..7d6fa79dea 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -23,7 +23,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. | | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after successful file operations`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. | | `@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-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. | +| `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. | | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. | | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `user/message goal snapshot for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. | | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. | @@ -524,7 +524,7 @@ Search file contents with a ripgrep regular expression. Returns matching lines w Source: [`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts) -glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. +glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. ## `@deepseek-ai/dsh-tool-pty` diff --git a/examples/acp-agent/tests/fs-search.cordis.snapshot.yml b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml index e1755ec9d4..141691a087 100644 --- a/examples/acp-agent/tests/fs-search.cordis.snapshot.yml +++ b/examples/acp-agent/tests/fs-search.cordis.snapshot.yml @@ -31,4 +31,5 @@ - id: tool-fs-search name: '@deepseek-ai/dsh-tool-fs-search' config: + sampleOverCapGlobResults: true globMaxResults: 4 diff --git a/examples/acp-agent/tests/fs-search.cordis.yml b/examples/acp-agent/tests/fs-search.cordis.yml index 171ab88980..153128f914 100644 --- a/examples/acp-agent/tests/fs-search.cordis.yml +++ b/examples/acp-agent/tests/fs-search.cordis.yml @@ -29,4 +29,5 @@ - id: tool-fs-search name: '@deepseek-ai/dsh-tool-fs-search' config: + sampleOverCapGlobResults: true globMaxResults: 4 diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml index 2d11c1356a..bedb8289c1 100644 --- a/packages/fs/tool-fs-search/README.i18n.yaml +++ b/packages/fs/tool-fs-search/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md -README.md: 51b3fa5385330cdaba0b36dd71a6efe4fd3d0db5 -README.zh.md: de9e50c90724cbc40f6de5880e7000ae0552b52d +README.md: b12ffda9869c7d6bef5ea5b54594781ecf555ff4 +README.zh.md: 7dd6cdf9a209f2fe357b4ffe48d20d574266ce60 diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md index 51b3fa5385..b12ffda986 100644 --- a/packages/fs/tool-fs-search/README.md +++ b/packages/fs/tool-fs-search/README.md @@ -5,9 +5,9 @@ English | [中文](README.zh.md) The **model-facing filesystem discovery tools**—`glob`, `grep`—are backed by the **bash executor seam**, not by `ctx.fs` provider methods. At load, the package probes `command -v rg` through `ctx.bash`; if the executor cannot find ripgrep on its `PATH`, it logs a warning and registers no tools or prompt sections. Each call assembles a fixed ripgrep command (every model-controlled value through one package-private shell-quoting helper), runs it via `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` as an ordinary foreground tool call, parses the raw `rg` output, and returns a workdir-relative canonical value. The package injects `tools`, `systemPrompt`, and `bash`—deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional. ```ts ignore-check -// Default deployment: a bash executor whose PATH includes rg, then the discovery tools. +// A deployment chooses how over-cap glob pages are selected. await ctx.plugin(LocalBashExecutor, { cwd: process.cwd() }) // @deepseek-ai/dsh-bash-local -await ctx.plugin(ToolFsSearch) // this package — conditionally registers glob/grep +await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: false }) // Optional: a spill backend makes capped results fully recoverable. await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-spill-local ``` @@ -20,11 +20,12 @@ The mounted bash executor must be able to resolve `rg` from its `PATH` at plugin ## Config -All keys are optional; the defaults are the shipped search caps. +`sampleOverCapGlobResults` is required and has no fallback; deployments choose the over-cap ordering contract explicitly. The remaining keys are optional search caps with the defaults below. | Key | Default | Meaning | |---|---|---| -| `globMaxResults` | `100` | Max paths one `glob` call shows inline (matches Claude Code's `GlobTool` limit). Within it the result is shown whole in modification-time order; beyond it the inline page is sampled across top-level entries and the complete sorted list goes to the formatted spill artifact. | +| `sampleOverCapGlobResults` | none (required) | `true` samples an over-cap `glob` page across top-level entries; `false` keeps the modification-time-ordered head. When formatted spill succeeds, both modes preserve the complete sorted list in that artifact. | +| `globMaxResults` | `100` | Max paths one `glob` call shows inline (matches Claude Code's `GlobTool` limit). A result within the cap remains complete and modification-time ordered. | | `grepMaxMatches` | `250` | Max flat matches one `grep` call retains inline (matches Claude Code's `GrepTool` `head_limit`); later matches go to the formatted spill artifact. | | `grepMaxLineBytes` | `2000` | Byte cap per matched-line preview; the cut preserves UTF-8 boundaries and is marked `(line truncated)`. | | `rawOutputMaxBytes` | `20000000` | Max complete raw `rg` stdout a search will parse (matches Claude Code's ripgrep raw buffer); larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. | @@ -34,14 +35,14 @@ All keys are optional; the defaults are the shipped search caps. | Tool | Arguments | Behavior | |---|---|---| -| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line, modification-time ordered; `rg --files` never emits directory entries. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. | +| `glob` | `pattern`, `path?` | `rg --files --glob --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one FILE path per line; `rg --files` never emits directory entries. The pattern keeps ripgrep semantics: without a `/` it matches the basename at any depth, so `*` matches the whole tree. Complete results stay modification-time ordered; over-cap presentation follows `sampleOverCapGlobResults`. | | `grep` | `pattern`, `path?`, `include?` | Line-oriented `rg --json` parse (no colon-splitting ambiguity). `pattern` is a ripgrep regex; `path` is an optional **file or directory** target; `include` is ONE positive glob filter — a comma-separated list or a negated (`!…`) value is rejected up front (brace alternation like `*.{ts,tsx}` is fine). Returns matches grouped by file as `Line N: `. | Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`case_insensitive`/output modes): a model that needs surrounding context reads the matched file with `read`; one that needs later results follows the returned spill locator's retrieval hint. ## Two budgets, two artifacts -Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps the displayed search root and every acquired path in `{ root, paths }`; `root` lets the Native renderer group an explicit relative or absolute search path by entries beneath that root rather than by its workdir prefix. `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with a head page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`. +Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. A successful `glob` keeps the displayed search root and every acquired path in `{ root, paths }`; when sampling is enabled, `root` lets the Native renderer group an explicit relative or absolute search path by entries beneath that root rather than by its workdir prefix. `grep` keeps every acquired `{ path, lineNumber, line }` in `{ matches }`. Inline item and per-line preview caps apply only in the Native renderer. For a direct surface call with more logical results than the inline cap, post-policy best-effort saves the complete formatted preview through `ctx.spillStore.saveText()` and replaces only presentation with the configured page plus locator. Nested Code dispatches skip that spill because their full canonical value does not enter model context. Missing/failed spill keeps the inline page and reports that the complete result could not be saved—never an `isError`. ## Errors @@ -55,12 +56,18 @@ Search failures carry the package-owned `SearchError` (a `HarnessError` subclass After the load-time `rg` probe succeeds, every request in this plugin's registration scope contains the independently registered glob and grep guidance below. Agent-scoped tool restrictions can hide either schema without removing its prompt section. -##### Glob guidance +##### Glob guidance with `sampleOverCapGlobResults: true` ```markdown Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. ``` +##### Glob guidance with `sampleOverCapGlobResults: false` + +```markdown +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one keeps the modification-time-ordered head. +``` + ##### Grep guidance ```markdown @@ -69,17 +76,17 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read #### Token effect -Fixed guidance cost per request while the tools are registered. +Fixed guidance cost per request while the tools are registered; the required sampling choice selects one glob variant. #### KV Cache effect -Prefix-stable while the plugin scope and guidance text are unchanged. Activation or disposal may invalidate reuse from this prompt section. +Prefix-stable while the plugin scope, sampling choice, and guidance text are unchanged. Activation, disposal, or changing the choice may invalidate reuse from this prompt section. ### Tool schemas #### What the model sees -The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) after the load-time `rg` probe succeeds and while this surface is visible. +The glob description states the configured over-cap ordering. The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) use `sampleOverCapGlobResults: true`; schemas are visible only after the load-time `rg` probe succeeds. #### Token effect @@ -93,7 +100,7 @@ Prefix-stable while tool visibility and definitions are unchanged. Registration #### What the model sees -`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. An over-cap `glob` result does not show the head of the sorted list: its inline page takes paths round-robin across entries immediately beneath the actual search root, so one old-timestamped subtree cannot own every slot, and the footer states the sampled basis and how many top-level entries it reached. When it cannot reach them all, the footer tells the model to narrow `path`. A result that fits inline is untouched, and a flat result — every path its own top-level entry — keeps the plain footer, because there the sample is the modification-time-ordered head. The spill artifact always holds the complete list in modification-time order. +`glob` returns one path per line; `grep` groups `Line : ` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved. With `sampleOverCapGlobResults: true`, an over-cap `glob` page takes paths round-robin across entries immediately beneath the actual search root, and the footer states the sampled basis and how many top-level entries it reached; when it cannot reach them all, the footer tells the model to narrow `path`. With `false`, the page is the modification-time-ordered head and keeps the plain capped-result footer. A result that fits inline is untouched, and a flat sampled result also keeps the plain footer because its sample equals the modification-time head. The spill artifact always holds the complete list in modification-time order. #### Token effect @@ -122,4 +129,4 @@ Append-only; newly visible content follows the reusable request prefix and does - **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation. - **Ripgrep is a deployment dependency** — a missing `rg` executable makes the package register no tools or guidance; an incompatible executable or one that disappears after registration fails calls with `SEARCH_FAILED`. Remote or virtual filesystems need a co-located executor or another search consumer. - **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend. -- **Sampling groups by first path segment beneath the search root only** — an over-cap `glob` page balances across those top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred. +- **Sampling, when enabled, groups by first path segment beneath the search root only** — an over-cap `glob` page balances across those top-level entries, so a result concentrated deeper (one busy directory inside an otherwise even tree) is still shown unevenly below that level; recursive balancing is deferred. diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md index de9e50c907..7dd6cdf9a2 100644 --- a/packages/fs/tool-fs-search/README.zh.md +++ b/packages/fs/tool-fs-search/README.zh.md @@ -5,9 +5,9 @@ **面向模型的文件系统发现工具**（`glob`、`grep`）由 **bash 执行器 seam** 支持，而不是由 `ctx.fs` 提供方方法支持。加载时，本包（package）探测 `command -v rg`，探测通过 `ctx.bash` 进行；如果执行器无法在其 `PATH` 上找到 ripgrep，就记录警告，并且不注册工具或提示词段。每次调用都会组装固定的 ripgrep 命令（所有模型控制的值都经过同一个包私有 shell 引用辅助函数），通过 `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` 作为普通前台工具调用运行，解析原始 `rg` 输出，并返回相对于工作目录的规范值。本包注入 `tools`、`systemPrompt` 和 `bash`，有意**不**注入 `fs`；格式化结果 spill 为可选功能，因此机会性读取 `ctx.spillStore`，调用方式为 `ctx.get()`。 ```ts ignore-check -// Default deployment: a bash executor whose PATH includes rg, then the discovery tools. +// A deployment chooses how over-cap glob pages are selected. await ctx.plugin(LocalBashExecutor, { cwd: process.cwd() }) // @deepseek-ai/dsh-bash-local -await ctx.plugin(ToolFsSearch) // this package — conditionally registers glob/grep +await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: false }) // Optional: a spill backend makes capped results fully recoverable. await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-spill-local ``` @@ -20,11 +20,12 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- ## 配置 -所有键均为可选；默认值是随产品交付的搜索上限。 +`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序契约。其余键是可选的搜索上限，默认值如下。 | 键 | 默认值 | 含义 | |---|---|---| -| `globMaxResults` | `100` | 一次 `glob` 调用内联展示的最大路径数（与 Claude Code 的 `GlobTool` 上限相同）。未超过时结果整体按修改时间展示；超过时内联页面改为跨顶层条目取样，完整的排序列表写入格式化 spill 产物。 | +| `sampleOverCapGlobResults` | 无（必填） | `true` 会在顶层条目之间对超过上限的 `glob` 页面采样；`false` 保留按修改时间排序的前部。格式化 spill 成功时，两种模式都会在该产物中保留完整排序列表。 | +| `globMaxResults` | `100` | 一次 `glob` 调用内联展示的最大路径数（与 Claude Code 的 `GlobTool` 上限相同）。未超过上限的结果保持完整，并按修改时间排序。 | | `grepMaxMatches` | `250` | 一次 `grep` 调用内联保留的最大平铺匹配数（与 Claude Code 的 `GrepTool` `head_limit` 相同）；后续匹配写入格式化 spill 产物。 | | `grepMaxLineBytes` | `2000` | 每条匹配行预览的字节上限；截断会保留 UTF-8 边界，并标记为 `(line truncated)`。 | | `rawOutputMaxBytes` | `20000000` | 搜索将解析的完整原始 `rg` stdout 上限（与 Claude Code 的 ripgrep 原始 buffer 相同）；更大的原始输出以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败。 | @@ -34,14 +35,14 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- | 工具 | 参数 | 行为 | |---|---|---| -| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录**搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件**路径；`rg --files` 从不输出目录条目。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。未超过 `globMaxResults` 的结果按修改时间排序；超过时内联页面改为跨顶层条目取样（见下）。 | +| `glob` | `pattern`、`path?` | 运行 `rg --files --glob --sort=modified --no-ignore --hidden`，并排除 VCS 元数据（`.git`、`.svn`、`.hg`、`.bzr`、`.jj`、`.sl`）。`path` 是可选的**目录**搜索根；省略时使用解析后的 bash 工作目录。每行返回一个**文件**路径；`rg --files` 从不输出目录条目。pattern 保留 ripgrep 语义：不含 `/` 时匹配任意深度的基名，因此 `*` 匹配整棵树。完整结果保持按修改时间排序；超过上限时的呈现方式遵循 `sampleOverCapGlobResults`。 | | `grep` | `pattern`、`path?`、`include?` | 按行解析 `rg --json`，避免按冒号拆分的歧义。`pattern` 是 ripgrep 正则表达式；`path` 是可选的**文件或目录**目标；`include` 是一个正向 glob 过滤器，前置拒绝逗号分隔列表或否定值（`!…`），但允许 `*.{ts,tsx}` 等花括号交替。返回按文件分组、形如 `Line N: ` 的匹配。 | 常规预算不进入面向模型的 schema（没有 `head_limit`/`offset`/`case_insensitive`/输出模式）：模型需要周边上下文时，用 `read` 读取匹配文件；需要后续结果时，遵循返回的 spill locator 检索提示。 ## 两类预算、两类产物 -原始 `rg` stdout 是内部传输细节。每次搜索从 bash seam 请求 `stdoutMaxBytes: rawOutputMaxBytes`，且只解析完整保留的 stdout；如果执行器仍返回 `stdout.truncated`，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询。成功的 `glob` 在 `{ root, paths }` 中保留所显示的搜索根及所有已取得路径；借助 `root`，原生渲染器能以显式的相对或绝对搜索路径为根，按该根下的条目分组，而不是按其工作目录前缀分组。`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于原生渲染器。直接接口调用的逻辑结果超过内联上限时，后置策略会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为头部页面加 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。 +原始 `rg` stdout 是内部传输细节。每次搜索从 bash seam 请求 `stdoutMaxBytes: rawOutputMaxBytes`，且只解析完整保留的 stdout；如果执行器仍返回 `stdout.truncated`，搜索会以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败，并要求模型缩小查询。成功的 `glob` 在 `{ root, paths }` 中保留所显示的搜索根及所有已取得路径；启用采样时，借助 `root`，原生渲染器能以显式的相对或绝对搜索路径为根，按该根下的条目分组，而不是按其工作目录前缀分组。`grep` 保留所有已取得的 `{ path, lineNumber, line }`，并将其存入 `{ matches }`。内联条目和每行预览上限只应用于原生渲染器。直接接口调用的逻辑结果超过内联上限时，后置策略会尽力通过 `ctx.spillStore.saveText()` 保存完整格式化预览，并只把呈现替换为配置指定的页面与 locator。嵌套 Code 分派会跳过 spill，因为其完整规范值不会进入模型上下文。spill 缺失/失败时保留内联页面，并报告完整结果无法保存，绝不会成为 `isError`。 ## 错误 @@ -55,12 +56,18 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh- 加载时 `rg` 探测成功后，该插件注册作用域内的每个请求都包含下方独立注册的 glob 与 grep 指导。agent 作用域的工具限制可以隐藏任一 schema，而不移除其提示词段。 -##### Glob 指导 +##### 启用 `sampleOverCapGlobResults: true` 时的 Glob 指导 ```markdown Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree. ``` +##### 启用 `sampleOverCapGlobResults: false` 时的 Glob 指导 + +```markdown +Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one keeps the modification-time-ordered head. +``` + ##### Grep 指导 ```markdown @@ -69,17 +76,17 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read #### Token 影响 -工具注册期间，每个请求支付固定指导成本。 +工具注册期间，每个请求支付固定指导成本；必填的采样选项决定采用哪个 glob 变体。 #### KV Cache 影响 -只要插件作用域和指导文本不变，前缀就保持稳定。启用或 dispose（资源释放）可能从该提示词段开始使复用失效。 +只要插件作用域、采样选项和指导文本不变，前缀就保持稳定。启用、dispose（资源释放）或更改该选项，可能从该提示词段开始使复用失效。 ### 工具 schema #### 模型看到的内容 -当前接口可见时，公开已生成的 [`glob` 和 `grep` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search)；前提是加载时 `rg` 探测成功。 +glob 描述会说明配置所指定的超限结果排序方式。已生成的 [`glob` 和 `grep` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) 使用 `sampleOverCapGlobResults: true`；只有加载时 `rg` 探测成功后，这些 schema 才可见。 #### Token 影响 @@ -93,7 +100,7 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read #### 模型看到的内容 -`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。超过上限的 `glob` 结果不再展示排序列表的头部：其内联页面按轮转方式跨实际搜索根正下方的条目取样，因此单个时间戳较旧的子树无法占满所有位置；footer 会说明取样依据及其触达的顶层条目数。无法触达全部时，footer 会要求模型缩小 `path`。未超过上限的结果原样不动；扁平结果（每个路径各自构成一个顶层条目）保留朴素 footer，因为此时取样结果就是按修改时间排序的头部。spill 产物始终保存按修改时间排序的完整列表。 +`glob` 每行返回一个路径；`grep` 在每个路径下对 `Line : ` 匹配分组。空搜索返回 `No files found` 或 `No matches found`。达到上限的结果末尾会附加省略数量、spill locator 和后端检索提示，或说明完整结果无法保存。`sampleOverCapGlobResults: true` 时，超过上限的 `glob` 页面会在实际搜索根正下方的条目之间按轮转方式取路径，footer 会说明采样依据和触达的顶层条目数；若无法触达全部条目，footer 会要求模型缩小 `path`。设为 `false` 时，页面保留按修改时间排序的前部，并沿用通常用于达到上限结果的 footer。未超过上限的结果原样不动；扁平的采样结果也沿用普通 footer，因为其样本等同于按修改时间排序的前部。spill 产物始终保存按修改时间排序的完整列表。 #### Token 影响 @@ -122,4 +129,4 @@ Use the grep tool — not shell grep or rg — to search file contents. Use read - **搜索和文件访问没有共享工作区证明**：只有 bash 工作目录和文件系统根目录表示同一工作区时，返回路径才能继续读取；本包不执行运行时跨服务校验。 - **Ripgrep 是部署依赖**：缺失 `rg` 可执行文件时，本包不注册工具或指导；可执行文件不兼容或注册后消失时，调用以 `SEARCH_FAILED` 失败。远程或虚拟文件系统需要共置执行器或其他搜索消费方。 - **schema 只公开一个有界页面**：offset 分页、大小写模式开关、其他输出模式和提供方支持的发现均不在本包内；达到上限的完整输出需要 spill 后端。 -- **取样只按搜索根下的路径首段分组**：超过上限的 `glob` 页面在这些顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。 +- **启用采样时，只按搜索根下的路径首段分组**：超过上限的 `glob` 页面在这些顶层条目之间做均衡，因此集中在更深层的结果（一棵总体均匀的树里某个特别庞大的子目录）在该层级以下仍然分布不均；递归均衡已延期。 diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index 12af97a24b..c9806b7bd8 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -38,6 +38,8 @@ export const GLOB_VCS_EXCLUDES: readonly string[] = ['.git', '.svn', '.hg', '.bz /** Resolved glob-tool caps — plugin config after defaulting (see `Config` in index.ts). */ export interface GlobToolCaps { + /** Whether over-cap pages are sampled across top-level entries instead of taking the modification-time head. */ + sampleOverCapGlobResults: boolean /** Max paths retained inline; later paths go to the formatted spill file. */ maxResults: number /** Cap on the complete raw `rg` stdout the tool will parse. */ @@ -183,24 +185,32 @@ export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number, * @returns the model-facing text. */ export function formatGlobOutput(sample: GlobSample, seen: number, spillRef: SpillRef | undefined): string { - const body = sample.items.join('\n') - const recovery = spillRef !== undefined - ? `Full sorted result stored at: ${spillRef.locator}. ${spillRef.retrievalHint}` - : 'The complete result could not be saved; narrow pattern or path to see more.' const basis = sample.total === seen ? '.' : `, sampled across ${sample.shown} of the ${sample.total} top-level entries this pattern matched instead of taken in modification-time order.` + (sample.shown < sample.total ? ' Narrow path to inspect a specific subtree.' : '') - return `${body}\n\n(Showing ${sample.items.length} of ${seen} paths${basis} ${recovery})` + return formatGlobPage(sample.items, seen, spillRef, basis) +} + +/** Format one bounded page and the recovery path for its complete sorted result. */ +function formatGlobPage(items: readonly string[], seen: number, spillRef: SpillRef | undefined, basis: string): string { + const body = items.join('\n') + const recovery = spillRef !== undefined + ? `Full sorted result stored at: ${spillRef.locator}. ${spillRef.retrievalHint}` + : 'The complete result could not be saved; narrow pattern or path to see more.' + return `${body}\n\n(Showing ${items.length} of ${seen} paths${basis} ${recovery})` } /** Bound and format one canonical path list for the Native surface relative to its search root. */ -function renderGlobPaths(paths: string[], maxResults: number, root: string, spillRef?: SpillRef): string { +function renderGlobPaths(paths: string[], caps: GlobToolCaps, root: string, spillRef?: SpillRef): string { if (paths.length === 0) return 'No files found' // A result that fits is shown whole, untouched: modification-time order is the // tool's contract, and over a complete result it is what answers age questions. - if (paths.length <= maxResults) return paths.join('\n') - return formatGlobOutput(sampleAcrossTopLevel(paths, maxResults, root), paths.length, spillRef) + if (paths.length <= caps.maxResults) return paths.join('\n') + if (!caps.sampleOverCapGlobResults) { + return formatGlobPage(paths.slice(0, caps.maxResults), paths.length, spillRef, '.') + } + return formatGlobOutput(sampleAcrossTopLevel(paths, caps.maxResults, root), paths.length, spillRef) } /** @@ -222,19 +232,24 @@ export function presentGlobCall(args: { pattern: string; path?: string }): Gener * @param caps - the deployment's resolved glob caps (plugin config after defaulting). */ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { + const overCapGuidance = caps.sampleOverCapGlobResults + ? 'while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree.' + : 'while a larger one keeps the modification-time-ordered head.' ctx.systemPrompt.section({ name: 'tool:glob', order: 103, text: 'Use the glob tool — not shell find — to discover files by path pattern. A pattern with no "/" matches basenames at any depth, so "*" matches every file in the tree rather than its top level. ' - + 'Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, while a larger one is sampled across top-level entries, ' - + 'so it spans the tree instead of one subtree.', + + `Results are files only, never directories, and include hidden and ignored files: a result that fits comes back in modification-time order, ${overCapGuidance}`, }) + const overCapDescription = caps.sampleOverCapGlobResults + ? `a larger result instead returns ${caps.maxResults} paths sampled across top-level entries` + : `a larger result returns the first ${caps.maxResults} paths in modification-time order` const tool = defineTool({ name: 'glob', description: 'Find files whose paths match a glob pattern. Returns matching file paths — never directories — ' + 'including hidden and ignored files (VCS metadata directories are excluded). ' - + `Up to ${caps.maxResults} paths come back in modification-time order; a larger result instead returns ${caps.maxResults} paths sampled across top-level entries, ` + + `Up to ${caps.maxResults} paths come back in modification-time order; ${overCapDescription}, ` + 'says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries.', parameters: { pattern: { @@ -255,7 +270,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { paths: { type: 'array', required: true, items: { type: 'string' } }, }, }, - render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps.maxResults, value.root) }], + render: (_args, value) => [{ type: 'text', text: renderGlobPaths(value.paths, caps, value.root) }], }, async execute(args, exec) { const input = parseGlobArgs(args) @@ -284,7 +299,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void { const spillRef = await trySaveFormattedResult(ctx, exec, 'glob-results.txt', paths.join('\n')) return { kind: 'accept', - content: [{ type: 'text', text: renderGlobPaths(paths, caps.maxResults, value.root, spillRef) }], + content: [{ type: 'text', text: renderGlobPaths(paths, caps, value.root, spillRef) }], ...decision.additionalContexts !== undefined ? { additionalContexts: decision.additionalContexts } : {}, } }) diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts index b6ae6ebbad..eea213a938 100644 --- a/packages/fs/tool-fs-search/src/index.ts +++ b/packages/fs/tool-fs-search/src/index.ts @@ -58,8 +58,10 @@ export const name = 'tool-fs-search' /** Services required by the search tool suite (`spillStore` is optional, read via `ctx.get()`). */ export const inject = ['tools', 'systemPrompt', 'bash'] -/** Plugin config (all optional — `Config` supplies the defaults). */ +/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */ export interface Config { + /** Whether an over-cap `glob` page is sampled across top-level entries instead of taking the modification-time head. */ + sampleOverCapGlobResults: boolean /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */ globMaxResults?: number /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */ @@ -73,6 +75,7 @@ export interface Config { } export const Config: z = z.object({ + sampleOverCapGlobResults: z.boolean().required(), globMaxResults: z.number().default(GLOB_MAX_RESULTS), grepMaxMatches: z.number().default(GREP_MAX_MATCHES), grepMaxLineBytes: z.number().default(GREP_MAX_LINE_BYTES), @@ -137,6 +140,7 @@ export async function apply(ctx: Context, config: Config): Promise { return } applyGlobTool(ctx, { + sampleOverCapGlobResults: resolved.sampleOverCapGlobResults, maxResults: resolved.globMaxResults, rawOutputMaxBytes: resolved.rawOutputMaxBytes, timeoutMs: resolved.timeoutMs, diff --git a/packages/fs/tool-fs-search/tests/integration.spec.ts b/packages/fs/tool-fs-search/tests/integration.spec.ts index 6be9629460..8cb96e7e66 100644 --- a/packages/fs/tool-fs-search/tests/integration.spec.ts +++ b/packages/fs/tool-fs-search/tests/integration.spec.ts @@ -64,7 +64,7 @@ describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', () await ctx.plugin(ToolRegistry) await ctx.plugin(LocalSubprocessService) await ctx.plugin(LocalBashExecutor, { cwd: dir, timeoutMs: 20_000 }) - await ctx.plugin(ToolFsSearch) + await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: true }) }) afterEach(async () => { diff --git a/packages/fs/tool-fs-search/tests/load-path.spec.ts b/packages/fs/tool-fs-search/tests/load-path.spec.ts index 0f72529567..71022720fc 100644 --- a/packages/fs/tool-fs-search/tests/load-path.spec.ts +++ b/packages/fs/tool-fs-search/tests/load-path.spec.ts @@ -82,7 +82,7 @@ describe('dsh-tool-fs-search real-load-path guard', () => { const loader = Object.create(Loader.prototype) as Loader const unwrapped = loader.unwrapExports(toolFsSearch) as Parameters[0] // A collapsed export shape (dropped inject) would throw "without inject" here. - const fiber = await ctx.plugin(unwrapped) + const fiber = await ctx.plugin(unwrapped, { sampleOverCapGlobResults: true }) expect(ctx.tools.schemas().map(s => s.name)).toEqual(expect.arrayContaining(['glob', 'grep'])) await fiber.dispose() }) diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index ccb3af5b80..da273ec2a2 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -111,12 +111,14 @@ class FakeSpill extends SpillStore { } interface SetupOptions { - config?: ToolFsSearch.Config + config?: Partial spill?: boolean probeError?: Error probeResult?: BashRunResult } +const DEFAULT_CONFIG = { sampleOverCapGlobResults: true } satisfies ToolFsSearch.Config + async function setup(options: SetupOptions = {}) { const ctx = new Context() const warnings: string[] = [] @@ -128,7 +130,7 @@ async function setup(options: SetupOptions = {}) { if (options.probeResult) bash.probeResult = options.probeResult if (options.probeError) bash.probeError = options.probeError if (options.spill === true) await ctx.plugin(FakeSpill) - const fiber = await ctx.plugin(ToolFsSearch, options.config) + const fiber = await ctx.plugin(ToolFsSearch, { ...DEFAULT_CONFIG, ...options.config }) const spill = options.spill === true ? ctx.get('spillStore') as FakeSpill : undefined return { ctx, bash, spill, fiber, warnings } } @@ -216,7 +218,7 @@ describe('registration', () => { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) - await ctx.plugin(ToolFsSearch) // no bash executor + await ctx.plugin(ToolFsSearch, DEFAULT_CONFIG) // no bash executor expect(ctx.tools.schemas()).toHaveLength(0) }) @@ -241,9 +243,27 @@ describe('registration', () => { expect(ctx.tools.get('glob')?.timeoutMs).toBe(30_000) expect(ctx.tools.get('grep')?.timeoutMs).toBe(30_000) }) + + it('describes the modification-time head when over-cap sampling is disabled', async () => { + const { ctx } = await setup({ config: { sampleOverCapGlobResults: false } }) + const prompt = renderPrompt(await ctx.systemPrompt.assemble()) + expect(prompt).toContain('a larger one keeps the modification-time-ordered head') + expect(prompt).not.toContain('sampled across top-level entries') + const glob = ctx.tools.schemas().find(schema => schema.name === 'glob') + expect(glob?.description).toContain('a larger result returns the first 100 paths in modification-time order') + expect(glob?.description).not.toContain('sampled across top-level entries') + }) }) describe('config validation', () => { + it('requires an explicit over-cap glob sampling choice', () => { + expect(() => new ToolFsSearch.Config()).toThrow(/sampleOverCapGlobResults/) + expect(new ToolFsSearch.Config({ sampleOverCapGlobResults: false })).toMatchObject({ + sampleOverCapGlobResults: false, + globMaxResults: 100, + }) + }) + it.each([ ['globMaxResults', { globMaxResults: 0 }], ['grepMaxMatches', { grepMaxMatches: -1 }], @@ -255,7 +275,7 @@ describe('config validation', () => { await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRegistry) await ctx.plugin(FakeBash) - await expect(ctx.plugin(ToolFsSearch, config)).rejects.toThrow(new RegExp(`tool-fs-search: ${name} must be a positive integer`)) + await expect(ctx.plugin(ToolFsSearch, { ...DEFAULT_CONFIG, ...config })).rejects.toThrow(new RegExp(`tool-fs-search: ${name} must be a positive integer`)) }) }) @@ -625,6 +645,16 @@ describe('glob results', () => { + 'The complete result could not be saved; narrow pattern or path to see more.)') }) + it('keeps the modification-time head when over-cap sampling is disabled', async () => { + const { ctx, bash } = await setup({ + config: { globMaxResults: 3, sampleOverCapGlobResults: false }, + }) + bash.handler = () => runResult(['vendor/a.ts', 'vendor/b.ts', 'vendor/c.ts', 'src/d.ts', 'guide/e.md'].join('\n')) + expect(text(await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') }))) + .toBe('vendor/a.ts\nvendor/b.ts\nvendor/c.ts\n\n' + + '(Showing 3 of 5 paths. The complete result could not be saved; narrow pattern or path to see more.)') + }) + it('samples relative to the explicit search root instead of its workdir prefix', async () => { const { ctx, bash } = await setup({ config: { globMaxResults: 3 } }) bash.handler = () => runResult([ diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index b092154b21..a77bdb6d95 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -273,10 +273,10 @@ const TOOL_PACKAGES: ToolPackage[] = [ // never depends on the host PATH. `ctx.spillStore` is optional (read via // ctx.get) and does not affect the schemas, so no spill backend is mounted. await ctx.plugin(CatalogSearchBashExecutor) - await ctx.plugin(ToolFsSearch) + await ctx.plugin(ToolFsSearch, { sampleOverCapGlobResults: true }) }, note: - 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.', + 'glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.', }, { pkg: '@deepseek-ai/dsh-tool-pty', From 57fb5b488e4bd5cbf4f543330ce8894bdbd82de8 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 29 Jul 2026 03:03:43 +0800 Subject: [PATCH 47/67] feat: fork --- .../client/connection/src/client/fixture.ts | 45 ++++++++++++++ packages/client/connection/tests/fake-api.ts | 2 + .../runtime/src/client/contract/sessions.ts | 8 +++ .../runtime/src/client/sessions/manager.ts | 30 ++++++++++ .../runtime/src/client/sessions/service.ts | 32 ++++++++++ packages/client/runtime/tests/fake-api.ts | 2 + packages/client/test-runtime/src/sessions.ts | 13 +++- .../ui-conversation/src/client/apply.ts | 7 +++ .../src/client/chat/ChatView.tsx | 4 +- .../src/client/chat/MessageIconActions.tsx | 13 ++-- .../src/client/chat/MessageItem.tsx | 5 +- .../src/client/contract/slots.ts | 2 + .../ui-conversation/tests/chat-view.spec.tsx | 4 +- .../src/client/WorkspaceBrowser.tsx | 34 +++++++++-- .../ui-workspace/src/client/contract/slots.ts | 2 + .../client/ui-workspace/src/client/index.ts | 7 +++ .../ui-workspace/src/client/rows/Rows.tsx | 16 +++-- .../client/ui-workspace/tests/rows.spec.tsx | 54 ++++++++--------- .../tests/workspace-browser.spec.tsx | 1 + packages/host/apiproxy/src/api-proxy.ts | 60 +++++++++++++++++++ packages/host/apiproxy/src/api/rpc-map.ts | 1 + packages/host/apiproxy/src/api/rpc.schema.ts | 1 + packages/host/apiproxy/src/api/rpc.ts | 1 + .../host/apiproxy/src/api/sessions.schema.ts | 11 ++++ packages/host/apiproxy/src/api/sessions.ts | 14 +++++ packages/host/apiproxy/src/fetch/client.ts | 4 ++ packages/host/apiproxy/src/fetch/handler.ts | 2 + .../apiproxy/tests/client-handler.spec.ts | 1 + .../host/apiproxy/tests/fetch-carrier.spec.ts | 3 + 29 files changed, 330 insertions(+), 49 deletions(-) diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts index cb79a6b9a2..282dfbee56 100644 --- a/packages/client/connection/src/client/fixture.ts +++ b/packages/client/connection/src/client/fixture.ts @@ -1042,6 +1042,50 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy { const appended = logOf(sessionId).at(-1) as SessionEvent return ok(request, { title: normalized, seq: appended.seq }) }, + fork: (request) => { + const { sessionId, atSeq } = request.payload + const source = summaryOf(sessionId) + if (source === undefined) { + return err(request, { + code: 'session-not-found', + message: `no session ${sessionId}`, + details: { sessionId }, + }) + } + const log = logs.get(sessionId) ?? [] + // Host-parallel boundary: first turn/end at or after atSeq, falling + // back to the last completed turn; no completed turn = fork-unavailable. + const boundary = (atSeq === undefined ? undefined : log.find(e => e.type === 'turn/end' && e.seq >= atSeq)) + ?? log.findLast(e => e.type === 'turn/end') + if (boundary === undefined) { + return err(request, { + code: 'fork-unavailable', + message: `session ${sessionId} has no completed turn`, + details: { sessionId }, + }) + } + let cut = boundary.seq + 1 + while (cut < log.length && log[cut]?.type !== 'turn/start') cut++ + const child: SessionSummary = { + sessionId: sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: false, + parentSessionId: sessionId, + ...source.cwd === undefined ? {} : { cwd: source.cwd }, + } + logs.set(child.sessionId, log.slice(0, cut)) + sessions.push(child) + emitHost({ + type: 'host/session-added', sessionId: child.sessionId, blank: false, + parentSessionId: sessionId, + ...source.cwd === undefined ? {} : { cwd: source.cwd }, + }) + const workspace = workspaces.find(w => w.sessionIds.includes(sessionId)) + if (workspace !== undefined) { + workspace.sessionIds = [child.sessionId, ...workspace.sessionIds] + workspace.updatedAt = new Date().toISOString() + emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } }) + } + return ok(request, { sessionId: child.sessionId }) + }, history: async (request) => { const log = logs.get(request.payload.sessionId) ?? [] // Snapshot at request time, deliver after the transit delay (mirrors a real host under latency). @@ -1591,6 +1635,7 @@ export class FixtureApiClient extends AbstractApiClient { case 'session.models': return this.api.sessions.models(request) case 'session.selectModel': return this.api.sessions.selectModel(request) case 'session.rename': return this.api.sessions.rename(request) + case 'session.fork': return this.api.sessions.fork(request) case 'session.prompt': return this.api.sessions.prompt(request) case 'session.updateQueue': return this.api.sessions.updateQueue(request) case 'session.cancel': return this.api.sessions.cancel(request) diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts index 89bcb9301d..8e99d9f9bb 100644 --- a/packages/client/connection/tests/fake-api.ts +++ b/packages/client/connection/tests/fake-api.ts @@ -46,6 +46,7 @@ export class FakeApiClient implements IApiClient { onList: (payload: unknown) => Promise> = () => Promise.resolve(ok({ items: [] })) onCreate: (payload: unknown) => Promise> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId })) onRename: (payload: unknown) => Promise> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 })) + onFork: (payload: unknown) => Promise> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId })) onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) => Promise> = () => Promise.resolve(ok({ @@ -99,6 +100,7 @@ export class FakeApiClient implements IApiClient { selectModel: (payload: ModelTarget & { sessionId: SessionId }) => this.record('session.selectModel', payload, this.onSelectModel(payload)), rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)), + fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)), prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)), updateQueue: (payload: unknown) => this.record('session.updateQueue', payload, this.onUpdateQueue(payload)), cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)), diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts index d26b392072..7c147df80c 100644 --- a/packages/client/runtime/src/client/contract/sessions.ts +++ b/packages/client/runtime/src/client/contract/sessions.ts @@ -29,6 +29,14 @@ export interface ISessions { open(id: SessionId): void /** Clear the current selection into the no-session view state. */ clear(): void + /** + * Fork a session from a completed-turn prefix of the source; on resolution + * the child is in the list store and `open()` can target it. + * @param opts - source session id and the optional event seq anchoring the + * cut (the boundary is the first turn/end at or after it). + * @returns the child session id. + */ + fork(opts: { sessionId: SessionId; atSeq?: number }): Promise /** * Register a per-session standard-props provider (hooks become `use` * selector hooks on the render side; props spread verbatim). diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts index ff68e21921..f60d7b51e8 100644 --- a/packages/client/runtime/src/client/sessions/manager.ts +++ b/packages/client/runtime/src/client/sessions/manager.ts @@ -289,6 +289,36 @@ export class SessionManager { } } + /** + * Contract session.fork; on success merge the child into summaries + * immediately (same synchronous-addressability guarantee as create). The + * child carries the source's history, so it is never blank; lineage rides + * parentSessionId so the list nests it under its source. + * @param opts - source session and the optional seq anchoring the cut. + * @returns the fork result (the child session id). + */ + async fork( + opts: { sessionId: SessionId; atSeq?: number }, + ): Promise> { + try { + const source = this.summaries.find(s => s.sessionId === opts.sessionId) + const { result } = await this.api.sessions.fork({ + sessionId: opts.sessionId, + ...opts.atSeq === undefined ? {} : { atSeq: opts.atSeq }, + }) + if (result.ok) { + this.recordMutation({ kind: 'upsert', summary: { + sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, blank: false, + parentSessionId: opts.sessionId, + ...(source?.cwd !== undefined ? { cwd: source.cwd } : {}), + } }) + } + return result + } catch (error) { + return transportError(error) + } + } + /** * Insert-or-enrich a locally synthesized summary: a new id prepends; an * existing entry only gains fields it lacks (the session-added frame and the diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts index 71067d6330..b5bf951605 100644 --- a/packages/client/runtime/src/client/sessions/service.ts +++ b/packages/client/runtime/src/client/sessions/service.ts @@ -81,6 +81,22 @@ export class SessionCreateError extends Error { } } +/** Structured session-fork failure. */ +export class SessionForkError extends Error { + override readonly name = 'SessionForkError' + + /** + * @param rpcError - Host business or folded transport error. + * @param sourceSessionId - the session the fork was cut from. + */ + constructor( + readonly rpcError: RpcError, + readonly sourceSessionId: SessionId, + ) { + super(`session fork failed: ${rpcError.code}: ${rpcError.message}`) + } +} + /** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */ export interface SessionBinding { readonly sessionId: SessionId @@ -317,6 +333,22 @@ export class SessionsService implements ISessions { return result.value.sessionId } + /** + * Fork a session from a completed-turn prefix of the source (same + * synchronous-addressability guarantee as {@link SessionsService.create}: + * on resolution the child is in the list store and open() can target it). + * @param opts - source session id and the optional event seq anchoring the + * cut (the boundary is the first turn/end at or after it). + * @returns the child session id. + * @throws {SessionForkError} with the source id. + */ + async fork(opts: { sessionId: SessionId; atSeq?: number }): Promise { + const result = await this.manager.fork(opts) + if (!result.ok) throw new SessionForkError(result.error, opts.sessionId) + this.projectList() + return result.value.sessionId + } + /** * Resolve an Agent-scoped context view (use-and-discard). * @param id - session id (the agent identity — 1:1 same axis). diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts index eb2a06294e..85dd4c5a55 100644 --- a/packages/client/runtime/tests/fake-api.ts +++ b/packages/client/runtime/tests/fake-api.ts @@ -64,6 +64,7 @@ export class FakeApiClient implements IApiClient { onCreate: (payload: unknown) => Promise> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId })) readonly defaultModel: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' } onRename: (payload: unknown) => Promise> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 })) + onFork: (payload: unknown) => Promise> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId })) onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) => Promise> = () => Promise.resolve(ok({ events: [], hasMore: false })) @@ -118,6 +119,7 @@ export class FakeApiClient implements IApiClient { selectModel: (payload: { provider: string; model: string }) => this.record('session.selectModel', payload, this.onSelectModel(payload)), rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)), + fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)), prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)), updateQueue: (payload: unknown) => this.record('session.updateQueue', payload, this.onUpdateQueue(payload)), cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)), diff --git a/packages/client/test-runtime/src/sessions.ts b/packages/client/test-runtime/src/sessions.ts index 4fdfb32cc0..f585772b38 100644 --- a/packages/client/test-runtime/src/sessions.ts +++ b/packages/client/test-runtime/src/sessions.ts @@ -169,7 +169,7 @@ export class TestSessions implements ISessions { private readonly channel: SessionProvideChannel /** Calls observed on the service-level face (open/clear), newest last. */ - readonly calls: { method: 'open' | 'clear'; args: unknown[] }[] = [] + readonly calls: { method: 'open' | 'clear' | 'fork'; args: unknown[] }[] = [] /** * @param stabilize - the owning runtime's act wrapper. @@ -392,6 +392,17 @@ export class TestSessions implements ISessions { this.list.update((draft) => { draft.current = undefined }) } + /** + * Recorded fork stub: no child materializes (benches asserting the full + * fork flow drive the production service; this face only proves the call). + * @param opts - source session id and optional cut anchor. + * @returns the source id (no child record is created). + */ + fork(opts: { sessionId: SessionId; atSeq?: number }): Promise { + this.calls.push({ method: 'fork', args: [opts] }) + return Promise.resolve(opts.sessionId) + } + /** * The session face of a fixture (typed view for assertions; fixture * behavior methods are grafted onto it). diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts index c6b597ae79..ca0159ce3d 100644 --- a/packages/client/ui-conversation/src/client/apply.ts +++ b/packages/client/ui-conversation/src/client/apply.ts @@ -262,6 +262,13 @@ export function apply(ctx: Context): void { }) }, loadOlder: () => { void scoped.loadOlder() }, + forkAt: (seq) => { + sessions.fork({ sessionId, atSeq: seq }) + .then((childId) => { sessions.open(childId) }) + .catch(() => { + // Fork failure keeps the source view untouched (composer-stop posture). + }) + }, } }, }, ChatView) diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx index b9e1e3351f..68b9b71cb8 100644 --- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx +++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx @@ -230,7 +230,7 @@ function StreamingTail({ useSession, onGrow }: { * The chat view slot entry: pure component over the composed props (tool rows * render through the declared keyed hole's renderSlot share). */ -export function ChatView({ useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder }: ChatViewSlotProps) { +export function ChatView({ useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, forkAt }: ChatViewSlotProps) { const nodes = useSession(s => s.nodes) // Workspace root off the session list row: path summaries display relative to it. const cwd = useSessions(s => s.byId[sessionId]?.cwd) @@ -385,7 +385,7 @@ export function ChatView({ useSession, useSessions, useStore, renderSlot, sessio } /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */ if (node.kind === 'tool-result') return null - return + return } return ( diff --git a/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx b/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx index fc76cfb753..124371f2da 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx +++ b/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx @@ -1,5 +1,6 @@ -// Shared IconActions chrome for user and assistant messages: copy / branch -// live (branch still a stub), date-aware clock, optional edit stub. +// Shared IconActions chrome for user and assistant messages: copy live, +// branch wired through onBranch (stub without it), date-aware clock, +// optional edit stub. import { useCallback } from 'react' import { @@ -18,17 +19,19 @@ export interface MessageIconActionsProps { clock: 'start' | 'end' /** When true, append the stub edit control (user bubble). */ edit?: boolean | undefined + /** Fork the session at this message; absent leaves the branch control a stub. */ + onBranch?: (() => void) | undefined /** Parent layout class composed onto the actions row. */ className?: string | undefined } /** * Copy / branch (/ clock) IconActions row shared by user and assistant chrome. - * @param props - Copy text, event time, clock side, optional edit, className. + * @param props - Copy text, event time, clock side, optional edit, branch callback, className. * @returns The actions row element. */ export function MessageIconActions({ - text, time, clock, edit, className, + text, time, clock, edit, onBranch, className, }: MessageIconActionsProps) { const day = useCalendarDay() const onCopy = useCallback(() => { @@ -48,7 +51,7 @@ export function MessageIconActions({ - diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx index aa56d35270..2eb8e313ae 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx @@ -16,6 +16,8 @@ import css from './MessageItem.module.css' export interface MessageItemProps { node: UserMessageNode | SteeringMessageNode | ContextMessageNode | UnknownSurfaceNode + /** Fork the session through the turn containing this message (user-bubble branch action). */ + onFork?: (seq: number) => void } function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } { @@ -61,7 +63,7 @@ function projectUserText(text: string): ReactNode { return <>{parts} } -export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) { +export const MessageItem = memo(function MessageItem({ node, onFork }: MessageItemProps) { switch (node.kind) { case 'user': { const { text, rest } = contentText(node.content) @@ -76,6 +78,7 @@ export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) time={node.time} clock="start" edit + onBranch={onFork === undefined ? undefined : () => { onFork(node.seq) }} className={css.actions} /> diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts index 1684e616b2..dca8cbc567 100644 --- a/packages/client/ui-conversation/src/client/contract/slots.ts +++ b/packages/client/ui-conversation/src/client/contract/slots.ts @@ -419,6 +419,8 @@ export interface ChatViewInjected { */ openFile: (path: string) => void loadOlder: () => void + /** Fork the session through the turn containing the message at `seq`, then open the child. */ + forkAt: (seq: number) => void } /** Full chat-view component props: runtime share & the declared toolview/commandview holes' render share & store share & injected share. */ diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx index c0cb4dcb78..960f954d61 100644 --- a/packages/client/ui-conversation/tests/chat-view.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx @@ -94,6 +94,7 @@ function makeHarness(init?: Partial) { const openDetails = vi.fn<(t: SelectionTarget) => void>() const openFile = vi.fn<(path: string) => void>() const loadOlder = vi.fn() + const forkAt = vi.fn() // Selection rides the REAL chat store (same construction path as // production; the view reads it through the PropsStore useStore share). // renderSlot stub renders the render-site fallback (an empty keyed ledger: @@ -120,9 +121,10 @@ function makeHarness(init?: Partial) { openDetails, openFile, loadOlder, + forkAt, } const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) } - return { set, ChatView, props, openDetails, openFile, loadOlder, setSelection } + return { set, ChatView, props, openDetails, openFile, loadOlder, forkAt, setSelection } } describe('chat-flow derivation', () => { diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx index a1fa0683ac..035bfe06a7 100644 --- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx +++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx @@ -83,7 +83,7 @@ interface DragState { type SessionTreeProps = Pick< WorkspaceBrowserProps, - 'useSessions' | 'startSession' | 'open' | 'insertSessionBefore' + 'useSessions' | 'startSession' | 'open' | 'forkSession' | 'insertSessionBefore' > & { workspaces: readonly WorkspaceView[] /** Live search filter owned by the browser root (the query outlives the tree). */ @@ -98,7 +98,7 @@ type SessionTreeProps = Pick< /** The scrolling session tree; unmounting at collapse settle drops the sessions subscription and expansion state. */ function SessionTree({ - useSessions, startSession, open, workspaces, query, + useSessions, startSession, open, forkSession, workspaces, query, onRenameRequest, onDeleteRequest, onSessionRename, insertSessionBefore, }: SessionTreeProps) { const list = useSessions(s => s) @@ -115,6 +115,24 @@ function SessionTree({ if (current === undefined || currentGroup === undefined) return setExpandedProjects(l => (l.includes(currentGroup) ? l : [...l, currentGroup])) }, [current, currentGroup]) + // The selected session must be visible: unfold its ancestor chain (fork + // lands the child under a possibly folded parent row). + const currentAncestors = useMemo(() => { + const chain: string[] = [] + let cursor = current === undefined ? undefined : list.byId[current]?.parentId + while (cursor !== undefined && !chain.includes(cursor)) { + chain.push(cursor) + cursor = list.byId[cursor]?.parentId + } + return chain + }, [current, list]) + useEffect(() => { + if (currentAncestors.length === 0) return + setExpandedSessions((l) => { + const missing = currentAncestors.filter(id => !l.includes(id)) + return missing.length === 0 ? l : [...l, ...missing] + }) + }, [currentAncestors]) const groups = useMemo( () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions, query }), [list, workspaces, expandedProjects, expandedSessions, query], @@ -195,6 +213,7 @@ function SessionTree({ now={now} onOpen={open} onRename={onSessionRename} + onFork={forkSession} onToggle={(id) => { setExpandedSessions(l => toggled(l, id)) }} drag={dragProps} /> @@ -209,7 +228,7 @@ function SessionTree({ } /** The flat "In one list" body: every session a top-level row, newest-first. */ -function FlatList({ useSessions, open, onSessionRename, query }: Pick) { +function FlatList({ useSessions, open, forkSession, onSessionRename, query }: Pick) { const list = useSessions(s => s) const rows = useMemo(() => deriveFlat(list, { query }), [list, query]) const now = Date.now() @@ -228,6 +247,7 @@ function FlatList({ useSessions, open, onSessionRename, query }: Pick {}} flat @@ -254,6 +274,7 @@ export function WorkspaceBrowser({ startSession, open, renameSession, + forkSession, renameWorkspace, deleteWorkspace, insertSessionBefore, @@ -460,13 +481,14 @@ export function WorkspaceBrowser({ {/* Always-mounted seat keeps the region's flex slot while the list itself is wide-only. */} -
- {wide && (groupBy === 'flat' - ? +
+ {wide && (groupBy === 'flat' + ? : ( void /** Rename a Session (explicit user title; resolves on host acceptance). */ renameSession: (sessionId: SessionId, title: string) => Promise + /** Fork a Session at its last completed turn and open the child. */ + forkSession: (sessionId: SessionId) => void /** Rename a Host Workspace (rejects on name conflict; resolves on durability). */ renameWorkspace: (workspaceId: WorkspaceId, title: string) => Promise /** Delete only a Host Workspace registration; directory and Session logs remain. */ diff --git a/packages/client/ui-workspace/src/client/index.ts b/packages/client/ui-workspace/src/client/index.ts index c1f5e61ba4..f7ced8016a 100644 --- a/packages/client/ui-workspace/src/client/index.ts +++ b/packages/client/ui-workspace/src/client/index.ts @@ -59,6 +59,13 @@ export function apply(ctx: ClientContext): void { const result = await session.rename(title) if (!result.ok) throw new Error(result.error.message) }, + forkSession: (sessionId) => { + ctx.sessions.fork({ sessionId }) + .then((childId) => { ctx.sessions.open(childId) }) + .catch(() => { + // Fork failure keeps the list untouched (composer-stop posture). + }) + }, renameWorkspace: async (workspaceId, title) => { await ctx.workspaces.rename(workspaceId, title) }, deleteWorkspace: async (workspaceId) => { await ctx.workspaces.delete(workspaceId) }, insertSessionBefore: async (workspaceId, sessionId, beforeSessionId) => { diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index a507ac2991..c4b9752690 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -2,8 +2,8 @@ * Workspace browser tree row components (figma Cell set 14:3080): pure presentational — * all data and callbacks arrive via props. Hover swaps (folder->chevron, * time->ellipsis, action buttons) are CSS-only. Row ... menus are visual-only - * except workspace Rename/Delete and session Rename; the session and workspace - * hover cards are suppressed while a menu is open. + * except workspace Rename/Delete and session Rename/Fork; the session and + * workspace hover cards are suppressed while a menu is open. */ import { useState } from 'react' import clsx from 'clsx' @@ -184,7 +184,7 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' | return e.clientY < rect.top + rect.height / 2 ? 'before' : 'after' } -export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onToggle, drag, flat = false }: { +export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onFork, onToggle, drag, flat = false }: { node: SessionNode depth: number currentId: string | undefined @@ -192,6 +192,8 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onOpen: (id: SessionNode['id']) => void /** Open the browser-owned session rename dialog (row menu action). */ onRename: (id: SessionNode['id'], currentTitle: string) => void + /** Fork a session at its last completed turn (row menu action). */ + onFork: (id: SessionNode['id']) => void onToggle: (id: SessionNode['id']) => void /** Present only on draggable rows (workspace-group roots outside search). */ drag?: RowDragProps | undefined @@ -259,9 +261,10 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, open={menuOpen} onClose={() => { setMenuOpen(false) }} items={SESSION_MENU_ITEMS} - onSelect={(id) => { - setMenuOpen(false) - if (id === 'rename') onRename(node.id, row.title) // fork/delete stay visual-only. + onSelect={(id) => { + setMenuOpen(false) + if (id === 'rename') onRename(node.id, row.title) + if (id === 'fork') onFork(node.id) // delete stays visual-only. }} portal closeOnPointerLeave @@ -295,6 +298,7 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, now={now} onOpen={onOpen} onRename={onRename} + onFork={onFork} onToggle={onToggle} /> ))} diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx index c4b440578a..dc8e9379dc 100644 --- a/packages/client/ui-workspace/tests/rows.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.spec.tsx @@ -67,9 +67,9 @@ describe('workspace browser rows', () => { } const onOpen = vi.fn() const onToggle = vi.fn() - const view = render( - , + const view = render( + , ) const parentRow = screen.getByText('Parent').closest('[role="treeitem"]')! @@ -88,9 +88,9 @@ describe('workspace browser rows', () => { view.rerender( , ) expect(screen.getByRole('button', { name: 'Expand' })).toBeTruthy() @@ -162,9 +162,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('s1'), title: 'One', children: [], hasChildren: false, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' })) expect(onOpen).not.toHaveBeenCalled() expect(screen.getByRole('menuitem', { name: 'Delete session' }).className).toMatch(/danger/) @@ -189,9 +189,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('p'), title: 'Parent', children: [], hasChildren: true, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull() }) @@ -201,9 +201,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('s1'), title: 'Hovered', children: [], hasChildren: false, expanded: false, running: true, updatedAt: 0, - } - render() + } + render() const wrapper = screen.getByRole('treeitem').parentElement as HTMLElement fireEvent.pointerEnter(wrapper) act(() => { vi.advanceTimersByTime(500) }) @@ -228,9 +228,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('s1'), title: 'Quiet', children: [], hasChildren: false, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement) act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('Idle')).toBeTruthy() @@ -246,9 +246,9 @@ describe('workspace browser rows', () => { expanded: false, running: false, updatedAt: 0, } const inactive = dragProps() - const { rerender } = render( - , + const { rerender } = render( + , ) const row = screen.getByRole('treeitem') stubRect(row) @@ -264,9 +264,9 @@ describe('workspace browser rows', () => { expect(inactive.end).toHaveBeenCalledOnce() const active = dragProps({ active: true, marker: 'before' }) - rerender( - , + rerender( + , ) stubRect(screen.getByRole('treeitem')) // Top half hovers/drops 'before'; bottom half 'after' (row mid = 117). @@ -278,9 +278,9 @@ describe('workspace browser rows', () => { expect(active.drop).toHaveBeenCalledWith('after') const after = dragProps({ active: true, marker: 'after' }) - rerender( - , + rerender( + , ) expect(screen.getByRole('treeitem').className).toMatch(/dropAfter/) }) diff --git a/packages/client/ui-workspace/tests/workspace-browser.spec.tsx b/packages/client/ui-workspace/tests/workspace-browser.spec.tsx index abe896dffe..d0535ecdfa 100644 --- a/packages/client/ui-workspace/tests/workspace-browser.spec.tsx +++ b/packages/client/ui-workspace/tests/workspace-browser.spec.tsx @@ -56,6 +56,7 @@ function mount(overrides: Partial = {}) { startSession: vi.fn(), open: vi.fn(), renameSession: vi.fn(async () => {}), + forkSession: vi.fn(), renameWorkspace: vi.fn(async () => {}), deleteWorkspace: vi.fn(async () => {}), insertSessionBefore: vi.fn(async () => {}), diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index cab5747963..e3c73746a9 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -1148,6 +1148,66 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro } }, + async fork(request) { + const { sessionId, atSeq } = request.payload + const found = await agentFor(sessionId) + if ('error' in found) return err(request, found.error) + const source = found.agent.session + const events = source.events + // Boundary: the first turn/end at or after atSeq (fork includes that + // whole turn); an overshooting atSeq or an omitted one falls back to + // the last completed turn. + const boundary = (atSeq === undefined ? undefined : events.find(e => e.type === 'turn/end' && e.seq >= atSeq)) + ?? events.findLast(e => e.type === 'turn/end') + if (boundary === undefined) { + return err(request, { + code: 'fork-unavailable', + message: `session "${sessionId}" has no completed turn to fork from`, + details: { sessionId }, + }) + } + // Extend the cut through trailing out-of-band appends (session/title, + // injections) up to the next turn/start: they are standalone events, so + // the seed stays balanced, and the child inherits a title generated + // right after the boundary turn. + let cut = boundary.seq + 1 + while (cut < events.length && events[cut]?.type !== 'turn/start') cut++ + const childId = `session-${randomUUID()}` as SessionId + try { + await ctx.agents.create({ + sessionId: childId, + seed: events.slice(0, cut), + meta: { + ...source.header.cwd === undefined ? {} : { cwd: source.header.cwd }, + parentSession: source.id, + seedLength: cut, + }, + agentOptions, + }) + } catch (error: unknown) { + return err(request, { + code: 'internal', + message: `failed to fork session "${sessionId}": ${String(error)}`, + details: {}, + }) + } + // Keep the child in the source's Workspace so the list nests it under + // its parent; the child is already published if the attach fails. + const workspace = ctx.workspace.list().find(w => w.sessionIds.includes(source.id)) + if (workspace !== undefined) { + try { + await workspace.attachSession(childId) + } catch (error: unknown) { + return err(request, { + code: 'workspace-attach-failed', + message: `session "${childId}" was forked but could not attach to workspace "${workspace.id}": ${String(error)}`, + details: { sessionId: childId, workspaceId: workspace.id }, + }) + } + } + return ok(request, { sessionId: childId }) + }, + async prompt(request) { const { sessionId, mode, content } = request.payload const found = await agentFor(sessionId) diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts index bc197be3c5..54c68e9c1c 100644 --- a/packages/host/apiproxy/src/api/rpc-map.ts +++ b/packages/host/apiproxy/src/api/rpc-map.ts @@ -24,6 +24,7 @@ export interface RpcMethodMap { 'session.models': SessionsApi['models'] 'session.selectModel': SessionsApi['selectModel'] 'session.rename': SessionsApi['rename'] + 'session.fork': SessionsApi['fork'] 'session.prompt': SessionsApi['prompt'] 'session.updateQueue': SessionsApi['updateQueue'] 'session.cancel': SessionsApi['cancel'] diff --git a/packages/host/apiproxy/src/api/rpc.schema.ts b/packages/host/apiproxy/src/api/rpc.schema.ts index cbd793ebd0..95701f6deb 100644 --- a/packages/host/apiproxy/src/api/rpc.schema.ts +++ b/packages/host/apiproxy/src/api/rpc.schema.ts @@ -51,6 +51,7 @@ export const rpcErrorSchema: z.ZodType = z.discriminatedUnion('code', z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }), z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }), z.object({ code: z.literal('title-invalid'), message: z.string(), details: z.object({ sessionId: z.string() }) }), + z.object({ code: z.literal('fork-unavailable'), message: z.string(), details: z.object({ sessionId: z.string() }) }), z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }), ]) as unknown as z.ZodType diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts index c1fa4e1611..720db149c1 100644 --- a/packages/host/apiproxy/src/api/rpc.ts +++ b/packages/host/apiproxy/src/api/rpc.ts @@ -51,6 +51,7 @@ export interface RpcErrorDetailsMap { /** A leading-/ prompt named no registered command; the message names the token. */ 'unknown-command': {} 'title-invalid': { sessionId: SessionId } + 'fork-unavailable': { sessionId: SessionId } 'internal': {} } diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts index e3744ec37a..12bc273d98 100644 --- a/packages/host/apiproxy/src/api/sessions.schema.ts +++ b/packages/host/apiproxy/src/api/sessions.schema.ts @@ -89,6 +89,17 @@ export const sessionRenameValueSchema = z.object({ seq: z.number().int().nonnegative(), }) satisfies z.ZodType>> +/** session.fork request payload (atSeq anchors the completed-turn cut). */ +export const sessionForkRequestSchema = z.object({ + sessionId: sessionIdSchema, + atSeq: z.number().int().nonnegative().optional(), +}) satisfies z.ZodType>> + +/** session.fork response value (the child session id). */ +export const sessionForkValueSchema = z.object({ + sessionId: sessionIdSchema, +}) satisfies z.ZodType>> + /** session.history request payload (beforeSeq/maxMessages page backwards from the window tail). */ export const sessionHistoryRequestSchema = z.object({ sessionId: sessionIdSchema, diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index 077087a0de..70a4003a1a 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -238,6 +238,20 @@ export interface SessionsApi { * one — carried for future rendering; the state change is the feedback). A usage/state error is an * RPC error with code command-error; an unrecognized name is an RPC error with code unknown-command. */ + /** + * Forks a new session from a completed-turn prefix of the source. `atSeq` + * anchors the cut: the boundary is the first `turn/end` at or after it + * (a message's fork button passes the message seq, so the fork includes + * that whole turn); a boundary past the log end, or an omitted `atSeq`, + * falls back to the source's last completed turn. A source with no + * completed turn fails with `fork-unavailable`. The child inherits the + * source cwd (and its workspace attachment) and records + * `parentSessionId` lineage; the seed prefix carries the source title. + */ + fork(request: RpcRequest<{ sessionId: SessionId; atSeq?: number }>): + Promise> + + /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */ prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>): Promise> diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts index 38e684fa20..b1dc1e4a1e 100644 --- a/packages/host/apiproxy/src/fetch/client.ts +++ b/packages/host/apiproxy/src/fetch/client.ts @@ -20,6 +20,7 @@ import { import { sessionCancelValueSchema, sessionCreateValueSchema, + sessionForkValueSchema, sessionHistoryValueSchema, sessionListValueSchema, sessionModelsValueSchema, @@ -69,6 +70,7 @@ export interface IApiClient { models(payload: RequestPayload<'session.models'>, signal?: AbortSignal): Promise>> selectModel(payload: RequestPayload<'session.selectModel'>, signal?: AbortSignal): Promise>> rename(payload: RequestPayload<'session.rename'>, signal?: AbortSignal): Promise>> + fork(payload: RequestPayload<'session.fork'>, signal?: AbortSignal): Promise>> prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise>> updateQueue(payload: RequestPayload<'session.updateQueue'>, signal?: AbortSignal): Promise>> cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise>> @@ -121,6 +123,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType this.callUnary('session.models', payload, signal), selectModel: (payload, signal) => this.callUnary('session.selectModel', payload, signal), rename: (payload, signal) => this.callUnary('session.rename', payload, signal), + fork: (payload, signal) => this.callUnary('session.fork', payload, signal), prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal), updateQueue: (payload, signal) => this.callUnary('session.updateQueue', payload, signal), cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal), diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts index 98dac06b9f..785ce7431b 100644 --- a/packages/host/apiproxy/src/fetch/handler.ts +++ b/packages/host/apiproxy/src/fetch/handler.ts @@ -17,6 +17,7 @@ import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts' import { sessionCancelRequestSchema, sessionCreateRequestSchema, + sessionForkRequestSchema, sessionHistoryRequestSchema, sessionListRequestSchema, sessionModelsRequestSchema, @@ -71,6 +72,7 @@ const UNARY_ROUTES: UnaryRoutes = { 'session.models': { schema: sessionModelsRequestSchema, invoke: (api, r) => api.sessions.models(r) }, 'session.selectModel': { schema: sessionSelectModelRequestSchema, invoke: (api, r) => api.sessions.selectModel(r) }, 'session.rename': { schema: sessionRenameRequestSchema, invoke: (api, r) => api.sessions.rename(r) }, + 'session.fork': { schema: sessionForkRequestSchema, invoke: (api, r) => api.sessions.fork(r) }, 'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) }, 'session.updateQueue': { schema: sessionUpdateQueueRequestSchema, invoke: (api, r) => api.sessions.updateQueue(r) }, 'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) }, diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts index 4751e3357b..2981c9ddea 100644 --- a/packages/host/apiproxy/tests/client-handler.spec.ts +++ b/packages/host/apiproxy/tests/client-handler.spec.ts @@ -47,6 +47,7 @@ function scriptedApi(overrides: { selected: { provider: r.payload.provider, model: r.payload.model }, }), rename: r => ok(r, { title: 'renamed', seq: 0 }), + fork: r => ok(r, { sessionId: sid('s-fork') }), prompt: r => ok(r, { accepted: true as const }), updateQueue: r => ok(r, { accepted: true as const }), cancel: r => ok(r, { accepted: true as const }), diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts index f356beac0d..bc76b7242f 100644 --- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts +++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts @@ -70,6 +70,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra async rename(request) { return { rpcId: request.rpcId, result: { ok: true, value: { title: request.payload.title, seq: 0 } } } }, + async fork(request) { + return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-fork' as never } } } + }, async prompt(request) { return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } } }, From 36f148939894b019803f7230066ea951cf7668d9 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 12:55:10 +0800 Subject: [PATCH 48/67] fix(web): address session fork review findings --- ...026-06-30-session-store-fork-api.i18n.yaml | 4 +- .../2026-06-30-session-store-fork-api.md | 8 +- .../2026-06-30-session-store-fork-api.zh.md | 8 +- apps/web/tests/message-actions.e2e.ts | 23 ++- .../message-actions/fork.expected.md | 9 ++ .../snapshots/message-actions/ui.expected.md | 3 +- .../client/connection/src/client/fixture.ts | 16 +- packages/client/runtime/README.i18n.yaml | 4 +- packages/client/runtime/README.md | 4 + packages/client/runtime/README.zh.md | 4 + .../runtime/src/client/contract/sessions.ts | 3 +- .../runtime/src/client/sessions/manager.ts | 10 +- .../runtime/src/client/sessions/service.ts | 3 +- packages/client/runtime/tests/manager.spec.ts | 17 ++ .../test-runtime/tests/runtime.spec.tsx | 4 +- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 4 +- packages/client/ui-workspace/README.i18n.yaml | 4 +- packages/client/ui-workspace/README.md | 4 +- packages/client/ui-workspace/README.zh.md | 4 +- .../src/client/WorkspaceBrowser.tsx | 4 +- .../ui-workspace/src/client/rows/Rows.tsx | 8 +- .../client/ui-workspace/tests/rows.spec.tsx | 60 +++---- packages/host/apiproxy/README.i18n.yaml | 4 +- packages/host/apiproxy/README.md | 4 +- packages/host/apiproxy/README.zh.md | 8 +- packages/host/apiproxy/src/api-proxy.ts | 21 ++- packages/host/apiproxy/src/api/sessions.ts | 9 +- .../apiproxy/tests/api-proxy-fork.spec.ts | 151 ++++++++++++++++++ .../apiproxy/tests/client-handler.spec.ts | 15 ++ 31 files changed, 346 insertions(+), 80 deletions(-) create mode 100644 apps/web/tests/snapshots/message-actions/fork.expected.md create mode 100644 packages/host/apiproxy/tests/api-proxy-fork.spec.ts diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml index 437bd200dc..5669911951 100644 --- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md -2026-06-30-session-store-fork-api.md: 5342deba8ca879026d32ee1420cb3c0fdf67c500 -2026-06-30-session-store-fork-api.zh.md: 51a3e0ce50aff10a9812c91d24dc6e78a56c43ba +2026-06-30-session-store-fork-api.md: 69ff85e1f137f4f263bf951af0a3f655411c606a +2026-06-30-session-store-fork-api.zh.md: 3304a6f384c9004b3572c95881f832a4aa21b77c diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md index 5342deba8c..69ff85e1f1 100644 --- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md +++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md @@ -28,6 +28,12 @@ class SessionStore extends Service { An empty prefix is forkable; any non-empty boundary must be a safe existing sequence outside an open turn. Typed errors distinguish missing sources, stale objects, duplicate child ids, invalid boundaries, and prefixes ending during execution. Broader log validation and crash repair remain with their existing owners. +### Host and browser adaptation + +The Host `session.fork` RPC accepts `atSeq` as an anchor within the desired turn rather than as the store's inclusive safe boundary. It selects the first `turn/end` at or after that anchor; an omitted or past-end anchor selects the last completed turn. An anchor already in the log but not followed by a matching `turn/end` returns `fork-unavailable` and never falls back to an earlier turn, so a message action cannot silently omit the clicked message. + +The Host creates the child through the agent registry with the selected seed and lineage, and pre-publication setup installs the latest logged provider, model, and reasoning target before the child can run. It then attaches the child to the source Workspace. An attachment failure returns `workspace-attach-failed` with the already-published child id; the client reconciles that child into its summary list before surfacing the error. The Session-row action uses the last completed turn, while a message action supplies its event seq; both open the child after success, and lineage expansion makes it visible beneath the source. + ## Alternatives considered **Separate `ctx.sessionFork` service.** This was the first implementation, but review showed it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive. @@ -40,4 +46,4 @@ An empty prefix is forkable; any non-empty boundary must be a safe existing sequ The public surface stays small and discoverable: live session branching is part of `ctx.sessions`, next to `create({ seed })`, rather than a standalone service or a two-step helper pair. Persistence continues to work through existing `session/created` and `session/flush` behavior: a forked child starts life with seeded events, so existing backends persist that seed once and preserve `parentSession` / `seedLength` in the header. -The v1 scope still excludes ACP `session/fork`, unloaded persisted-session forking, model-facing tools, and subagent refactors. If a future ACP method is added, it should advertise the capability only after it has protocol and snapshot coverage; this Agent Note adds no ACP wire behavior, so no ACP snapshot is required. Fork-child replay remains covered by the existing [seed-boundary testing Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md), while this API gets focused `dsh-session` unit tests plus JSONL persistence coverage. +The v1 scope still excludes ACP `session/fork`, unloaded persisted-session forking, model-facing tools, and subagent refactors. If a future ACP method is added, it should advertise the capability only after it has protocol and snapshot coverage; this Agent Note adds no ACP wire behavior, so no ACP snapshot is required. Fork-child replay remains covered by the existing [seed-boundary testing Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md); focused store, Host, carrier, and client tests pin the boundary and reconciliation contracts, while the real Chromium scenario pins the assembled message action and lineage tree. diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md index 51a3e0ce50..3304a6f384 100644 --- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md +++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md @@ -28,6 +28,12 @@ class SessionStore extends Service { 空前缀可以被 fork；任何非空边界都必须是位于开放轮次之外且安全、已存在的序号。类型化的错误区分源缺失、对象陈旧、子 id 重复、边界无效和前缀结束于执行过程中等情况。更广泛的日志校验与崩溃恢复仍由其现有的负责方处理。 +### Host 与浏览器适配 + +Host 的 `session.fork` RPC 接受 `atSeq`，并将其视为所需轮次内的锚点，而非 store 中包含该序号的安全边界。它选择该锚点处或其后的首个 `turn/end`；锚点省略或超过末尾时，选择最后一个已完成轮次。若锚点已在日志中，但从该锚点起找不到匹配的 `turn/end`，则返回 `fork-unavailable`，绝不回退到更早的轮次，因此消息操作不会静默遗漏所点击的消息。 + +Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子会话；发布前 setup 会先安装日志中最新的提供方、模型和推理（reasoning）目标，子会话才能运行。随后，Host 将子会话附加到源 Workspace。若附加失败，则返回 `workspace-attach-failed` 及已发布的子会话 id；客户端先将该子会话对账到摘要列表，再向调用方报告错误。Session 行操作使用最后一个已完成轮次，消息操作则提供其事件 seq；两者都会在成功后打开子会话，展开谱系后可在源会话下看到它。 + ## 曾考虑的替代方案 **独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了 capability-seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。 @@ -40,4 +46,4 @@ class SessionStore extends Service { 公开接口保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话以种子事件开始生命，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。 -v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才广播该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖，而本 API 则获得专门的 `dsh-session` 单元测试加 JSONL 持久化覆盖。 +v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才广播该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖；store、Host、载体与客户端的专项测试固定边界和对账契约，真实 Chromium 场景则固定组装后的消息操作与谱系树。 diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts index aa14308d43..d3c4f45fd7 100644 --- a/apps/web/tests/message-actions.e2e.ts +++ b/apps/web/tests/message-actions.e2e.ts @@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import { SessionId } from '@deepseek-ai/dsh-session' import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold, @@ -19,6 +20,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/message-actions', import // a new recording (workspace-management / sidebar-scrollbar pattern). const SEED = fileURLToPath(new URL('./snapshots/seeded-history/seed.jsonl', import.meta.url)) const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md') +const FORK_EXPECTED = join(SNAPSHOT_DIR, 'fork.expected.md') const MODE = webSnapshotMode() const SEED_ID = 'message-actions-web-e2e' @@ -85,9 +87,28 @@ describe('web e2e: message IconActions and clocks on settled history', () => { await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE) }) + it.skipIf(MODE === 'record')('forks the session through the settled user-message action', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-message-fork')) + await page.getByRole('button', { name: '在新对话中分支' }).first().click() + await expect.poll( + () => scaffold.ctx.agents.list().find(agent => agent.session.header.parentSession === SessionId(SEED_ID)), + { timeout: 15_000 }, + ).toBeDefined() + await expect.poll( + () => page.locator('[role="treeitem"][aria-selected="true"]').count(), + { timeout: 10_000 }, + ).toBe(1) + const tree = await captureStableAria( + page, + '[role="tree"][aria-label="Sessions"]', + scaffold.workspaceCwd, + ) + await compareOrRefreshGolden(FORK_EXPECTED, tree, MODE) + }) + it.skipIf(MODE === 'record')('issued zero model calls and kept a closed inventory', async () => { expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md']) + await assertFixtureInventory(SNAPSHOT_DIR, ['fork.expected.md', 'ui.expected.md']) }) }) diff --git a/apps/web/tests/snapshots/message-actions/fork.expected.md b/apps/web/tests/snapshots/message-actions/fork.expected.md new file mode 100644 index 0000000000..2afb7d4d23 --- /dev/null +++ b/apps/web/tests/snapshots/message-actions/fork.expected.md @@ -0,0 +1,9 @@ +- tree "Sessions": + - treeitem "Ungrouped 2 sessions" [expanded]: + - img + - text: Ungrouped 2 sessions + - treeitem "Collapse Use the read tool twice 1min" [expanded]: + - button "Collapse": + - img + - text: Use the read tool twice 1min + - treeitem "Use the read tool twice now" [selected] diff --git a/apps/web/tests/snapshots/message-actions/ui.expected.md b/apps/web/tests/snapshots/message-actions/ui.expected.md index 19ba02d99d..e21b3782a8 100644 --- a/apps/web/tests/snapshots/message-actions/ui.expected.md +++ b/apps/web/tests/snapshots/message-actions/ui.expected.md @@ -31,7 +31,7 @@ - img - button "在新对话中分支": - img -- text: {{clock}} +- text: {{clock}} cache hit 98% · 15,962 tokens · 1 turns · 2 steps - textbox "Message the agent" - button "Add attachment": - img @@ -41,4 +41,3 @@ - text: deepseek-v4-flash - img - button "Send message" [disabled] -- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts index 282dfbee56..916125ff6f 100644 --- a/packages/client/connection/src/client/fixture.ts +++ b/packages/client/connection/src/client/fixture.ts @@ -1053,14 +1053,20 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy { }) } const log = logs.get(sessionId) ?? [] - // Host-parallel boundary: first turn/end at or after atSeq, falling - // back to the last completed turn; no completed turn = fork-unavailable. - const boundary = (atSeq === undefined ? undefined : log.find(e => e.type === 'turn/end' && e.seq >= atSeq)) - ?? log.findLast(e => e.type === 'turn/end') + const lastSeq = log.at(-1)?.seq ?? -1 + const anchoredBoundary = atSeq === undefined + ? undefined + : log.find(e => e.type === 'turn/end' && e.seq >= atSeq) + const boundary = anchoredBoundary + ?? (atSeq === undefined || atSeq > lastSeq + ? log.findLast(e => e.type === 'turn/end') + : undefined) if (boundary === undefined) { return err(request, { code: 'fork-unavailable', - message: `session ${sessionId} has no completed turn`, + message: atSeq !== undefined && atSeq <= lastSeq + ? `session ${sessionId} has not completed the turn containing event ${String(atSeq)}` + : `session ${sessionId} has no completed turn`, details: { sessionId }, }) } diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index fa4c87adb2..4ef6fd488c 100644 --- a/packages/client/runtime/README.i18n.yaml +++ b/packages/client/runtime/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/runtime/README.md -README.md: 766d8516225cd46cb1a3a80c832d1cf55e816140 -README.zh.md: 9b514afca91f604b3e895187de3b5532bf22a692 +README.md: db6388dccee6e065066cc70e141073d99822ce0f +README.zh.md: e1b6902d0d30972bd613553081e0f0e8d5da2a05 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index 766d851622..db6388dcce 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -28,6 +28,10 @@ SlotsService gives the renderer separate bare observables for `useSessions` and `SessionManager` retains the latest validated `session/title` control snapshot independently of list and session-instance arrival. Newer event seqs replace older snapshots, title timestamps contribute to list recency, and a subscription baseline discards any retained title beyond its `lastSeq` before the optional folded title arrives. Explicit session removal also clears the retained title. The client-facing `SessionSummary.title` is therefore only the actual durable title; `displayTitle` is always present and falls back through the cwd basename and session id. A cold persisted session keeps that fallback until opening or resuming it causes the host to fold and project its log-backed title. `ISession.rename` settles the `title` projection cell directly from the unary response's `{title, seq}` under the same higher-seq-wins rule — the list row and every `useProjection('title')` reader update ahead of the push frame, whose later replay of the same seq is a no-op. +## Session forking + +`ISessions.fork({sessionId, atSeq?})` resolves only after the child summary is locally addressable, carrying source lineage and cwd with `blank: false`; callers choose whether to open it. A `workspace-attach-failed` response still identifies a child already published by the Host, so `SessionManager` reconciles that partial success before `SessionForkError` reaches the caller instead of making a retry create a duplicate child. + ## Session model selection Each resident `Session` owns a `modelSelection` snapshot containing the current provider/model target, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current target, opening a selector refreshes the directory, and selection failures preserve the last target and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the target reported by the Host without replacing unchanged selection substructure. diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index 9b514afca9..e1b6902d0d 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -28,6 +28,10 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 `SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更高的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含实际的持久化标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷态持久化会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影由日志支撑的标题。`ISession.rename` 用 unary 响应中的 `{title, seq}` 直接结算 `title` 投影格，遵循同一 seq 高者胜规则——列表行和所有 `useProjection('title')` 读者在推送帧到达前即更新；推送帧随后重放同一 seq 时为无操作。 +## 会话 fork + +`ISessions.fork({sessionId, atSeq?})` 只在子会话摘要已能在本地寻址后才完成；该摘要携带源会话的谱系和 cwd，且 `blank: false`，由调用方决定是否打开。即使响应为 `workspace-attach-failed`，其中仍会标识 Host 已发布的子会话，因此 `SessionManager` 会先将这一部分成功对账，再让 `SessionForkError` 到达调用方，避免重试创建重复的子会话。 + ## 会话模型选择 每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。 diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts index 7c147df80c..1b59c3c27c 100644 --- a/packages/client/runtime/src/client/contract/sessions.ts +++ b/packages/client/runtime/src/client/contract/sessions.ts @@ -33,7 +33,8 @@ export interface ISessions { * Fork a session from a completed-turn prefix of the source; on resolution * the child is in the list store and `open()` can target it. * @param opts - source session id and the optional event seq anchoring the - * cut (the boundary is the first turn/end at or after it). + * cut (the boundary is the first turn/end at or after it; an in-log + * anchor in an open turn is unavailable rather than clipped backward). * @returns the child session id. */ fork(opts: { sessionId: SessionId; atSeq?: number }): Promise diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts index f60d7b51e8..4ba134b321 100644 --- a/packages/client/runtime/src/client/sessions/manager.ts +++ b/packages/client/runtime/src/client/sessions/manager.ts @@ -293,7 +293,8 @@ export class SessionManager { * Contract session.fork; on success merge the child into summaries * immediately (same synchronous-addressability guarantee as create). The * child carries the source's history, so it is never blank; lineage rides - * parentSessionId so the list nests it under its source. + * parentSessionId so the list nests it under its source. A child published + * before Workspace attachment fails is also reconciled into the list. * @param opts - source session and the optional seq anchoring the cut. * @returns the fork result (the child session id). */ @@ -306,9 +307,12 @@ export class SessionManager { sessionId: opts.sessionId, ...opts.atSeq === undefined ? {} : { atSeq: opts.atSeq }, }) - if (result.ok) { + const childId = result.ok + ? result.value.sessionId + : workspaceAttachSessionId(result.error) + if (childId !== undefined) { this.recordMutation({ kind: 'upsert', summary: { - sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, blank: false, + sessionId: childId, updatedAt: Date.now(), running: false, blank: false, parentSessionId: opts.sessionId, ...(source?.cwd !== undefined ? { cwd: source.cwd } : {}), } }) diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts index b5bf951605..741aba4c24 100644 --- a/packages/client/runtime/src/client/sessions/service.ts +++ b/packages/client/runtime/src/client/sessions/service.ts @@ -338,7 +338,8 @@ export class SessionsService implements ISessions { * synchronous-addressability guarantee as {@link SessionsService.create}: * on resolution the child is in the list store and open() can target it). * @param opts - source session id and the optional event seq anchoring the - * cut (the boundary is the first turn/end at or after it). + * cut (the boundary is the first turn/end at or after it; an in-log + * anchor in an open turn is unavailable rather than clipped backward). * @returns the child session id. * @throws {SessionForkError} with the source id. */ diff --git a/packages/client/runtime/tests/manager.spec.ts b/packages/client/runtime/tests/manager.spec.ts index 33b46538d9..afe6308249 100644 --- a/packages/client/runtime/tests/manager.spec.ts +++ b/packages/client/runtime/tests/manager.spec.ts @@ -277,6 +277,23 @@ describe('remaining branches', () => { expect(manager.getListSnapshot().items[0]).not.toHaveProperty('cwd') }) + it('reconciles a fork child published before workspace attachment fails', async () => { + const api = new FakeApiClient() + api.onFork = () => Promise.resolve(err({ + code: 'workspace-attach-failed', + message: 'forked but unattached', + details: { sessionId: S2, workspaceId: 'w1' }, + } as never)) + const manager = new SessionManager(api) + const result = await manager.fork({ sessionId: S1 }) + expect(result).toMatchObject({ ok: false, error: { code: 'workspace-attach-failed' } }) + expect(manager.getListSnapshot().items).toEqual([expect.objectContaining({ + sessionId: S2, + parentSessionId: S1, + blank: false, + })]) + }) + it('reconciles a preallocated id after an ordinary transport failure', async () => { const api = new FakeApiClient() api.onCreate = () => Promise.reject(new Error('response lost')) diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx index c5084112eb..eddc6efe76 100644 --- a/packages/client/test-runtime/tests/runtime.spec.tsx +++ b/packages/client/test-runtime/tests/runtime.spec.tsx @@ -201,7 +201,7 @@ describe('sessions', () => { await runtime.dispose() }) - it('records service-face calls; open() moves the selection and clear() empties it', async () => { + it('records service-face calls; open() moves selection, clear() empties it, and fork() echoes the source', async () => { const runtime = await runtimeWithFrame() await runtime.sessions.add({ id: 's1' }) await runtime.sessions.add({ id: 's2' }) @@ -211,9 +211,11 @@ describe('sessions', () => { runtime.sessions.clear() await runtime.flush() expect(runtime.sessions.list.getSnapshot().current).toBeUndefined() + await expect(runtime.sessions.fork({ sessionId: 's1' as SessionId, atSeq: 7 })).resolves.toBe('s1') expect(runtime.sessions.calls).toEqual([ { method: 'open', args: ['s1'] }, { method: 'clear', args: [] }, + { method: 'fork', args: [{ sessionId: 's1', atSeq: 7 }] }, ]) await runtime.dispose() }) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 1588367646..d5d1dcfbfb 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: fc466190a744a1c13094ca6ebf62755d5bf49c98 -README.zh.md: f6fbff9c1e5d005b64e928680bbf401d94e4ce79 +README.md: 02834be207e45bb1ff65b75a0c75a884db3be315 +README.zh.md: 84f9d79660207a68305d75ac0e7deaecdedf00d6 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index fc466190a7..02834be207 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -38,7 +38,7 @@ None; this package neither assembles nor sends a provider request. - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted. - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly. -- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch remains a chrome stub. +- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch forks through the turn containing that message and opens the child, while a fork failure leaves the source selected. - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export. - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today. - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index f6fbff9c1e..84f9d79660 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -36,9 +36,9 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插 ## 已知限制与暂缓事项 -- **统计行的耗时只覆盖窗口内消息流**：LLM 与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 +- **统计行的耗时只覆盖窗口内消息流**：LLM（大语言模型）与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。 -- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支仍是 chrome stub。 +- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支会 fork 到包含该消息的轮次末尾并打开子会话，而 fork 失败时源会话保持选中。 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。 diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index 536911a16a..a8f5d98981 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md -README.md: a1b58f4abe0925be3b426d10344777e46caa9ba0 -README.zh.md: a472507bc45549c8feb55a75d294cbd7b3138cc5 +README.md: f0dbd3de4ac5b7934b4077b2986f5def5be329c8 +README.zh.md: b9f068c6d1709f0a01d22c3fb1cdc391764d666b diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index a1b58f4abe..f0dbd3de4a 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,6 +6,8 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. +The Session row's Fork action forks at the source's last completed turn and opens the child; the lineage-aware tree nests it beneath the source. A failure leaves the current selection unchanged. + Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. ## Model Experience @@ -18,5 +20,5 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work -- **No Session deletion or fork control** — the Session menu's Fork and Delete rows remain visual-only (Rename is wired); Workspace registration deletion does not delete Sessions. +- **No Session deletion control** — the Session menu's Delete row remains visual-only; Workspace registration deletion does not delete Sessions. - **Native folder selection depends on the local Host carrier** — under the `-native` composition, fixture-only or remote browser deployments cannot open a local operating-system dialog; platform failures are shown in a retryable modal. Remote-capable picking is the `-browse` composition's in-app flow. diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index a472507bc4..b9f068c6d1 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,6 +6,8 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 +Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork 并打开子会话；感知谱系的树会将子会话嵌套在源会话下。失败不会改变当前选中项。 + 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 ## 模型体验 @@ -18,5 +20,5 @@ ## 已知限制与暂缓事项 -- **没有 Session 删除与 fork 控件**：Session 菜单的 Fork 与 Delete 行仍仅提供视觉效果（Rename 已接线）；删除 Workspace 注册记录不会删除 Session。 +- **没有 Session 删除控件**：Session 菜单的 Delete 行仍仅提供视觉效果；删除 Workspace 注册记录不会删除 Session。 - **原生文件夹选择依赖本地 Host 载体**：在 `-native` 组合下，仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。可远程的选取是 `-browse` 组合的应用内流程。 diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx index 035bfe06a7..933b49bdf0 100644 --- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx +++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx @@ -481,8 +481,8 @@ export function WorkspaceBrowser({ {/* Always-mounted seat keeps the region's flex slot while the list itself is wide-only. */} -
- {wide && (groupBy === 'flat' +
+ {wide && (groupBy === 'flat' ? : ( { setMenuOpen(false) }} items={SESSION_MENU_ITEMS} - onSelect={(id) => { - setMenuOpen(false) - if (id === 'rename') onRename(node.id, row.title) - if (id === 'fork') onFork(node.id) // delete stays visual-only. + onSelect={(id) => { + setMenuOpen(false) + if (id === 'rename') onRename(node.id, row.title) + if (id === 'fork') onFork(node.id) // delete stays visual-only. }} portal closeOnPointerLeave diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx index dc8e9379dc..44a311d6d3 100644 --- a/packages/client/ui-workspace/tests/rows.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.spec.tsx @@ -67,9 +67,9 @@ describe('workspace browser rows', () => { } const onOpen = vi.fn() const onToggle = vi.fn() - const view = render( - , + const view = render( + , ) const parentRow = screen.getByText('Parent').closest('[role="treeitem"]')! @@ -88,9 +88,9 @@ describe('workspace browser rows', () => { view.rerender( , ) expect(screen.getByRole('button', { name: 'Expand' })).toBeTruthy() @@ -156,15 +156,16 @@ describe('workspace browser rows', () => { expect(screen.queryByRole('button', { name: /Workspace actions/ })).toBeNull() }) - it('session row menu opens without opening the session and dispatches rename', () => { + it('session row menu opens without opening the session and dispatches rename and fork', () => { const onOpen = vi.fn() const onRename = vi.fn() + const onFork = vi.fn() const node: SessionNode = { id: sid('s1'), title: 'One', children: [], hasChildren: false, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' })) expect(onOpen).not.toHaveBeenCalled() expect(screen.getByRole('menuitem', { name: 'Delete session' }).className).toMatch(/danger/) @@ -173,9 +174,10 @@ describe('workspace browser rows', () => { expect(screen.queryByRole('menu')).toBeNull() expect(onRename).toHaveBeenCalledWith(node.id, 'One') expect(onOpen).not.toHaveBeenCalled() - // Fork and Delete stay visual-only. fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' })) fireEvent.click(screen.getByRole('menuitem', { name: 'Fork session' })) + expect(onFork).toHaveBeenCalledWith(node.id) + // Delete stays visual-only. fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' })) fireEvent.click(screen.getByRole('menuitem', { name: 'Delete session' })) expect(onRename).toHaveBeenCalledOnce() @@ -189,9 +191,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('p'), title: 'Parent', children: [], hasChildren: true, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull() }) @@ -201,9 +203,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('s1'), title: 'Hovered', children: [], hasChildren: false, expanded: false, running: true, updatedAt: 0, - } - render() + } + render() const wrapper = screen.getByRole('treeitem').parentElement as HTMLElement fireEvent.pointerEnter(wrapper) act(() => { vi.advanceTimersByTime(500) }) @@ -228,9 +230,9 @@ describe('workspace browser rows', () => { const node: SessionNode = { id: sid('s1'), title: 'Quiet', children: [], hasChildren: false, expanded: false, running: false, updatedAt: 0, - } - render() + } + render() fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement) act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('Idle')).toBeTruthy() @@ -246,9 +248,9 @@ describe('workspace browser rows', () => { expanded: false, running: false, updatedAt: 0, } const inactive = dragProps() - const { rerender } = render( - , + const { rerender } = render( + , ) const row = screen.getByRole('treeitem') stubRect(row) @@ -264,9 +266,9 @@ describe('workspace browser rows', () => { expect(inactive.end).toHaveBeenCalledOnce() const active = dragProps({ active: true, marker: 'before' }) - rerender( - , + rerender( + , ) stubRect(screen.getByRole('treeitem')) // Top half hovers/drops 'before'; bottom half 'after' (row mid = 117). @@ -278,9 +280,9 @@ describe('workspace browser rows', () => { expect(active.drop).toHaveBeenCalledWith('after') const after = dragProps({ active: true, marker: 'after' }) - rerender( - , + rerender( + , ) expect(screen.getByRole('treeitem').className).toMatch(/dropAfter/) }) diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml index 236cc5968f..95c3643886 100644 --- a/packages/host/apiproxy/README.i18n.yaml +++ b/packages/host/apiproxy/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md -README.md: 8f9deb6add7d30bf1609cc7febcb1febafe392c1 -README.zh.md: 399d45208b6d3f4152c27556523b6944432bec66 +README.md: 3ec21f90a495fe42e40c4407e0a81faa34a1e427 +README.zh.md: 5bcd310c23c35b851216176d69b13965dd2e1c3e diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md index 8f9deb6add..3ec21f90a4 100644 --- a/packages/host/apiproxy/README.md +++ b/packages/host/apiproxy/README.md @@ -16,6 +16,8 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`. +`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale. + Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. Pending queued input is a live control-plane contract, not session history. The gateway mirrors queued `InboxItem` occurrences from `agent/inbox/*` and broadcasts authoritative `session/queue` snapshots on every queued change and reconnect; pending steering stays outside this Web projection. `session.updateQueue` addresses one `InboxItemId`: edit replaces pending content and remove discards it. A driver claim wins races by retiring the address before admission; a later operation returns `queue-item-not-found`. The operation queries only an attached Agent and never resumes a cold session because process-local inbox identities do not survive restart or disposal. The client never infers retirement from turn or status events. @@ -43,7 +45,7 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work - **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `src/api-proxy.ts` and is still minimal (questions only, no approvals). -- **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code. +- **Reserved seams stay out of `RpcMethodMap`** — `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code. - **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists. - **Linux native picker requires desktop tooling** — under the `native` capability, `host.pickDirectory` reports an actionable error when neither Zenity nor KDialog is installed; the browse backend is the composition-level fallback (see the [native backend README](../directory-picker-native/README.md)). - **A cold session's `updatedAt` counts a mere pickup as a write (per-file backends only)** — the attached projection excludes the `session/end-seed` boundary, because picking a session up is not activity, but a cold session's `updatedAt` is its log file's mtime and every durable write refreshes that, the boundary included. `agentFor()` resumes a cold session on first touch, so merely opening one in a client writes it. This applies only where `locate()` resolves a per-session artifact, i.e. JSONL; SQLite returns `undefined`, so its cold sessions fall back to `createdAt` and are skewed the other way — too old rather than too new — independently of this boundary. A session touched without being worked in therefore sorts newer than its last real activity until it attaches. Separating the two needs a log read, which is exactly what the mtime path exists to avoid; a stored last-activity field in the index would fix it at the source, scoped in the [last-activity-index Agent Note](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md). diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md index 399d45208b..5bcd310c23 100644 --- a/packages/host/apiproxy/README.zh.md +++ b/packages/host/apiproxy/README.zh.md @@ -16,7 +16,9 @@ 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。 -会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理（reasoning）目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。 +`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。 + +会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。 待处理的 queued 输入属于实时控制平面契约，而非会话历史。网关镜像来自 `agent/inbox/*` 的 queued `InboxItem` 入队项，并在每次 queued 变更和重连时广播权威的 `session/queue` 快照；待处理 steering（中途引导）不进入此 Web 投影。`session.updateQueue` 通过 `InboxItemId` 寻址单个项：编辑会替换待处理内容，移除会将其丢弃。驱动器在接纳前退役寻址标识，因此认领会赢得竞态；之后的操作返回 `queue-item-not-found`。该操作只查询当前已挂载的 Agent，绝不恢复冷会话，因为进程本地 inbox 标识无法在重启或资源释放后存活。客户端绝不根据轮次或状态事件推断项已退役。 @@ -43,7 +45,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr ## 已知限制与延期工作 - **`respond` 路由已经发布，但待处理交互状态仍属宿主侧工作**：协议形状（POST `/api/respond`、`RpcReceipt`）已经定型；使延迟或重复回答具有明确语义的待处理表位于 `src/api-proxy.ts`，目前仍很精简（只支持问题，不支持审批）。 -- **预留 seam 不进入 `RpcMethodMap`**：`session.fork`、`prompt.mode: 'inject'`、`task.list`、`host.listModels` 和描述字段 `hostInstanceId` 都是已记录的预留项；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。 +- **预留 seam 不进入 `RpcMethodMap`**：`prompt.mode: 'inject'`、`task.list`、`host.listModels` 和描述字段 `hostInstanceId` 都是已记录的预留项；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。 - **Linux 原生选择器依赖桌面工具**：在 `native` 能力下，Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；组合层面的回退是 browse 后端（见 [native 后端 README](../directory-picker-native/README.md)）。 -- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会排在它最后一次真实活动之后。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。 +- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。 diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts index e3c73746a9..bcd9873263 100644 --- a/packages/host/apiproxy/src/api-proxy.ts +++ b/packages/host/apiproxy/src/api-proxy.ts @@ -1154,15 +1154,23 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro if ('error' in found) return err(request, found.error) const source = found.agent.session const events = source.events - // Boundary: the first turn/end at or after atSeq (fork includes that - // whole turn); an overshooting atSeq or an omitted one falls back to - // the last completed turn. - const boundary = (atSeq === undefined ? undefined : events.find(e => e.type === 'turn/end' && e.seq >= atSeq)) - ?? events.findLast(e => e.type === 'turn/end') + // An in-log anchor belongs to the turn containing it and must never + // clip backward to an earlier completed turn. Omitted and past-end + // anchors retain the last-completed-turn shortcut. + const lastSeq = events.at(-1)?.seq ?? -1 + const anchoredBoundary = atSeq === undefined + ? undefined + : events.find(e => e.type === 'turn/end' && e.seq >= atSeq) + const boundary = anchoredBoundary + ?? (atSeq === undefined || atSeq > lastSeq + ? events.findLast(e => e.type === 'turn/end') + : undefined) if (boundary === undefined) { return err(request, { code: 'fork-unavailable', - message: `session "${sessionId}" has no completed turn to fork from`, + message: atSeq !== undefined && atSeq <= lastSeq + ? `session "${sessionId}" has not completed the turn containing event ${String(atSeq)}` + : `session "${sessionId}" has no completed turn to fork from`, details: { sessionId }, }) } @@ -1183,6 +1191,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro seedLength: cut, }, agentOptions, + setup: installTarget, }) } catch (error: unknown) { return err(request, { diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts index 70a4003a1a..d386241bf1 100644 --- a/packages/host/apiproxy/src/api/sessions.ts +++ b/packages/host/apiproxy/src/api/sessions.ts @@ -243,10 +243,11 @@ export interface SessionsApi { * anchors the cut: the boundary is the first `turn/end` at or after it * (a message's fork button passes the message seq, so the fork includes * that whole turn); a boundary past the log end, or an omitted `atSeq`, - * falls back to the source's last completed turn. A source with no - * completed turn fails with `fork-unavailable`. The child inherits the - * source cwd (and its workspace attachment) and records - * `parentSessionId` lineage; the seed prefix carries the source title. + * falls back to the source's last completed turn. An in-log anchor whose + * turn is still open fails with `fork-unavailable` instead of clipping to + * an earlier turn. The child inherits the source cwd, latest logged model + * target, workspace attachment, and `parentSessionId` lineage; the seed + * prefix carries the source title. */ fork(request: RpcRequest<{ sessionId: SessionId; atSeq?: number }>): Promise> diff --git a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts new file mode 100644 index 0000000000..64cb1188f5 --- /dev/null +++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts @@ -0,0 +1,151 @@ +/** Session-fork boundaries, lineage, and inherited model routing. */ + +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent' +import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent' +import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm' +import type { LlmCallConfig } from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import type { Session, SessionId } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import UserInteractionService from '@deepseek-ai/dsh-user-interaction' +import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc' +import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc' +import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy' + +const sid = (id: string): SessionId => id as SessionId + +let nextRpc = 1 +function request

(payload: P): RpcRequest

{ + return { rpcId: RpcId(`fork-${String(nextRpc++)}`), payload } +} + +async function composed(): Promise { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(AgentRegistry) + await ctx.plugin(UserInteractionService) + ctx.provide('workspace', { list: () => [] } as never) + ctx.agents.setFactory({ + createAgent: async (ownerCtx: Context, options: CreateAgentOptions): Promise => { + const session = ctx.sessions.create(options.sessionId, { + ...options.seed === undefined ? {} : { seed: [...options.seed] }, + ...options.meta === undefined ? {} : { meta: options.meta }, + }) + const agent = {} as Agent + const agentCtx = ownerCtx.extend({ agent }) + Object.assign(agent, { id: session.id, session, status: 'idle', ctx: agentCtx }) + await options.setup?.(agentCtx) + ctx.agents.register(agent) + return { agent, dispose: () => Promise.resolve() } + }, + resume: () => Promise.reject(new Error('fork test sources are live')), + }) + return ctx +} + +function liveAgent(ctx: Context, id: string, turns: number, openTail = false): Session { + const session = ctx.sessions.create(sid(id), { meta: { cwd: '/proj' } }) + for (let turn = 1; turn <= turns; turn++) { + session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: `prompt ${String(turn)}` }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + session.append('turn/end', { turn, reason: { kind: 'completed' } }) + } + if (openTail) { + session.append('turn/start', { turn: turns + 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('user/message', createUserMessage({ + content: [{ type: 'text', text: 'open prompt' }], + source: { kind: 'user' }, + }), { surfaceOp: 'append' }) + } + ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent) + return session +} + +const api = (ctx: Context) => createApiProxy(ctx, { + provider: 'default-provider', + model: 'default-model', + cwd: '/tmp', + workspaceRoot: '/tmp', +}) + +describe('sessions.fork', () => { + it('cuts at the anchored completed turn and records lineage and cwd', async () => { + const ctx = await composed() + const source = liveAgent(ctx, 'session-source', 2) + const response = await api(ctx).sessions.fork(request({ sessionId: source.id, atSeq: 1 })) + expect(response.result.ok).toBe(true) + if (!response.result.ok) return + const child = ctx.sessions.get(response.result.value.sessionId) + expect(child?.events.length).toBe(3) + expect(child?.header.parentSession).toBe(source.id) + expect(child?.header.cwd).toBe('/proj') + await ctx.fiber.dispose() + }) + + it('uses the last completed turn only for omitted and past-end anchors', async () => { + const ctx = await composed() + const source = liveAgent(ctx, 'session-tail', 2, true) + const proxy = api(ctx) + const omitted = await proxy.sessions.fork(request({ sessionId: source.id })) + expect(omitted.result.ok).toBe(true) + if (omitted.result.ok) { + expect(ctx.sessions.get(omitted.result.value.sessionId)?.events.length).toBe(6) + } + const pastEnd = await proxy.sessions.fork(request({ sessionId: source.id, atSeq: 999 })) + expect(pastEnd.result.ok).toBe(true) + await ctx.fiber.dispose() + }) + + it('rejects an in-log anchor whose turn is still open', async () => { + const ctx = await composed() + const source = liveAgent(ctx, 'session-open', 1, true) + const anchor = source.events.at(-1)?.seq ?? 0 + const response = await api(ctx).sessions.fork(request({ sessionId: source.id, atSeq: anchor })) + expect(response.result).toMatchObject({ + ok: false, + error: { code: 'fork-unavailable', details: { sessionId: source.id } }, + }) + if (!response.result.ok) expect(response.result.error.message).toMatch(/has not completed/) + await ctx.fiber.dispose() + }) + + it('installs the latest logged model target before the child can run', async () => { + const ctx = await composed() + const source = liveAgent(ctx, 'session-routed', 1) + source.append('request/header', { + header: { + config: { + provider: 'inherited-provider', + model: 'inherited-model', + reasoningEffort: ReasoningEffortId('high'), + }, + }, + reason: 'initial', + }) + const response = await api(ctx).sessions.fork(request({ sessionId: source.id })) + expect(response.result.ok).toBe(true) + if (!response.result.ok) return + const child = ctx.agents.get(response.result.value.sessionId) + if (child === undefined) throw new Error('fork did not publish the child agent') + const assembly = await child.ctx.systemPrompt.assemble() + expect(assembly.variables).toMatchObject({ + provider: 'inherited-provider', + model: 'inherited-model', + }) + const fallback: LlmCallConfig = { provider: 'default-provider', model: 'default-model' } + await expect(agentEvents(child.ctx, child).waterfall( + 'agent/request', 1, 0, new AbortController().signal, () => Promise.resolve(fallback), + )).resolves.toMatchObject({ + provider: 'inherited-provider', + model: 'inherited-model', + reasoningEffort: 'high', + }) + await ctx.fiber.dispose() + }) +}) diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts index 2981c9ddea..b7ace8f832 100644 --- a/packages/host/apiproxy/tests/client-handler.spec.ts +++ b/packages/host/apiproxy/tests/client-handler.spec.ts @@ -111,6 +111,21 @@ describe('unary round trip', () => { expect(response.result).toEqual({ ok: true, value: { items: [{ sessionId: 's1', updatedAt: 7, running: false, blank: false }] } }) }) + it('routes session fork with its optional cut anchor through the wire', async () => { + let seen: RpcRequest<{ sessionId: SessionId; atSeq?: number }> | undefined + const api = scriptedApi({ + sessions: { + fork: (request) => { + seen = request + return ok(request, { sessionId: sid('s-child') }) + }, + }, + }) + const response = await client(api).sessions.fork({ sessionId: sid('s-parent'), atSeq: 7 }) + expect(seen?.payload).toEqual({ sessionId: 's-parent', atSeq: 7 }) + expect(response.result).toEqual({ ok: true, value: { sessionId: 's-child' } }) + }) + it('routes workspace rename, delete, and insertSessionBefore through the wire', async () => { const api = scriptedApi() const c = client(api) From 7d27c928515b755a7acec908f1337ec0c2a07d2c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:27:02 +0800 Subject: [PATCH 49/67] test(web): cover row fork in the real app --- apps/web/tests/message-actions.e2e.ts | 30 ++++++++++++++++++- .../message-actions/fork.expected.md | 5 ++-- .../snapshots/message-actions/ui.expected.md | 3 +- .../apiproxy/tests/api-proxy-fork.spec.ts | 16 ++++++++-- 4 files changed, 48 insertions(+), 6 deletions(-) diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts index d3c4f45fd7..679fdfbc65 100644 --- a/apps/web/tests/message-actions.e2e.ts +++ b/apps/web/tests/message-actions.e2e.ts @@ -87,13 +87,41 @@ describe('web e2e: message IconActions and clocks on settled history', () => { await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE) }) - it.skipIf(MODE === 'record')('forks the session through the settled user-message action', async () => { + it.skipIf(MODE === 'record')('forks through the settled-message and session-row actions', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-message-fork')) await page.getByRole('button', { name: '在新对话中分支' }).first().click() await expect.poll( () => scaffold.ctx.agents.list().find(agent => agent.session.header.parentSession === SessionId(SEED_ID)), { timeout: 15_000 }, ).toBeDefined() + await expect.poll( + () => page.locator('[role="treeitem"]').count(), + { timeout: 10_000 }, + ).toBe(3) + await expect.poll( + () => page.locator('[role="treeitem"][aria-selected="true"]').count(), + { timeout: 10_000 }, + ).toBe(1) + // The row action owns a distinct ui-workspace injection from the message + // action above, so exercise both through the loaded app before capture. + const sourceRow = page.locator('[role="treeitem"][aria-expanded="true"]').last() + const rowBox = await sourceRow.boundingBox() + if (rowBox === null) throw new Error('fork source row has no layout box') + const actionButton = sourceRow.locator('button[aria-label^="Session actions for "]') + await sourceRow.hover({ position: { x: rowBox.width - 16, y: rowBox.height / 2 } }) + await expect.poll(() => actionButton.isVisible(), { timeout: 2_000 }).toBe(true) + const buttonBox = await actionButton.boundingBox() + if (buttonBox === null) throw new Error('fork source row action has no layout box') + await page.mouse.click(buttonBox.x + buttonBox.width / 2, buttonBox.y + buttonBox.height / 2) + await page.getByRole('menuitem', { name: 'Fork session' }).click() + await expect.poll( + () => scaffold.ctx.agents.list().filter(agent => agent.session.header.parentSession !== undefined).length, + { timeout: 15_000 }, + ).toBe(2) + await expect.poll( + () => page.locator('[role="treeitem"]').count(), + { timeout: 10_000 }, + ).toBe(4) await expect.poll( () => page.locator('[role="treeitem"][aria-selected="true"]').count(), { timeout: 10_000 }, diff --git a/apps/web/tests/snapshots/message-actions/fork.expected.md b/apps/web/tests/snapshots/message-actions/fork.expected.md index 2afb7d4d23..5255632c3a 100644 --- a/apps/web/tests/snapshots/message-actions/fork.expected.md +++ b/apps/web/tests/snapshots/message-actions/fork.expected.md @@ -1,9 +1,10 @@ - tree "Sessions": - - treeitem "Ungrouped 2 sessions" [expanded]: + - treeitem "Ungrouped 3 sessions" [expanded]: - img - - text: Ungrouped 2 sessions + - text: Ungrouped 3 sessions - treeitem "Collapse Use the read tool twice 1min" [expanded]: - button "Collapse": - img - text: Use the read tool twice 1min - treeitem "Use the read tool twice now" [selected] + - treeitem "Use the read tool twice now" diff --git a/apps/web/tests/snapshots/message-actions/ui.expected.md b/apps/web/tests/snapshots/message-actions/ui.expected.md index e21b3782a8..19ba02d99d 100644 --- a/apps/web/tests/snapshots/message-actions/ui.expected.md +++ b/apps/web/tests/snapshots/message-actions/ui.expected.md @@ -31,7 +31,7 @@ - img - button "在新对话中分支": - img -- text: {{clock}} cache hit 98% · 15,962 tokens · 1 turns · 2 steps +- text: {{clock}} - textbox "Message the agent" - button "Add attachment": - img @@ -41,3 +41,4 @@ - text: deepseek-v4-flash - img - button "Send message" [disabled] +- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok diff --git a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts index 64cb1188f5..797bca29f2 100644 --- a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts +++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts @@ -82,7 +82,9 @@ describe('sessions.fork', () => { expect(response.result.ok).toBe(true) if (!response.result.ok) return const child = ctx.sessions.get(response.result.value.sessionId) - expect(child?.events.length).toBe(3) + expect(child?.events.map(event => event.type)).toEqual([ + 'turn/start', 'user/message', 'turn/end', 'session/end-seed', + ]) expect(child?.header.parentSession).toBe(source.id) expect(child?.header.cwd).toBe('/proj') await ctx.fiber.dispose() @@ -92,13 +94,23 @@ describe('sessions.fork', () => { const ctx = await composed() const source = liveAgent(ctx, 'session-tail', 2, true) const proxy = api(ctx) + const expectedTypes = [ + 'turn/start', 'user/message', 'turn/end', + 'turn/start', 'user/message', 'turn/end', + 'session/end-seed', + ] const omitted = await proxy.sessions.fork(request({ sessionId: source.id })) expect(omitted.result.ok).toBe(true) if (omitted.result.ok) { - expect(ctx.sessions.get(omitted.result.value.sessionId)?.events.length).toBe(6) + expect(ctx.sessions.get(omitted.result.value.sessionId)?.events.map(event => event.type)) + .toEqual(expectedTypes) } const pastEnd = await proxy.sessions.fork(request({ sessionId: source.id, atSeq: 999 })) expect(pastEnd.result.ok).toBe(true) + if (pastEnd.result.ok) { + expect(ctx.sessions.get(pastEnd.result.value.sessionId)?.events.map(event => event.type)) + .toEqual(expectedTypes) + } await ctx.fiber.dispose() }) From 2f8f47e50048d4998686000124e7a08d974a8b45 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 20:29:29 +0800 Subject: [PATCH 50/67] feat(ui-workspace): flatten session fork rows --- ...n-list-browsing-and-manual-order.i18n.yaml | 6 +- ...-session-list-browsing-and-manual-order.md | 14 +- ...ssion-list-browsing-and-manual-order.zh.md | 14 +- packages/client/ui-workspace/README.i18n.yaml | 4 +- packages/client/ui-workspace/README.md | 2 +- packages/client/ui-workspace/README.zh.md | 2 +- .../src/client/WorkspaceBrowser.tsx | 41 +---- .../src/client/rows/Rows.module.css | 36 +--- .../ui-workspace/src/client/rows/Rows.tsx | 64 ++------ .../client/ui-workspace/src/client/tree.ts | 155 +++--------------- .../client/ui-workspace/tests/rows.spec.tsx | 94 ++++------- .../client/ui-workspace/tests/tree.spec.ts | 18 +- .../tests/workspace-browser.spec.tsx | 8 +- 13 files changed, 110 insertions(+), 348 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml index 590d9227b8..ebc2df795a 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write -2026-07-25-session-list-browsing-and-manual-order.md: 586995bf459aeaee88672863977f7acf2a7061a3 -2026-07-25-session-list-browsing-and-manual-order.zh.md: 432d5167a57d30bc04a0b4faf213e4341f07bd2f +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md +2026-07-25-session-list-browsing-and-manual-order.md: 831aa53e532a75392690c330837482bb0f9c32b1 +2026-07-25-session-list-browsing-and-manual-order.zh.md: 9ad074d59c13585aa4fca46ae4d40e2deb15cde6 diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md index 586995bf45..831aa53e53 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md @@ -12,14 +12,14 @@ Two existing mechanisms stood in the way. First, the host durably promoted the a ## Decision -### Flat view and viewing state +### Flat rows and viewing state -The group-by menu offers two modes, WorkSpace / In one list. Flat mode renders every session (fork children included) as a top-level row, strictly newest-first by `updatedAt`, with no parent/child adjacency; the Intent placeholder renders as the first row. The mode choice persists in the browser (`dsh.workspace.view`) across reloads. +The group-by menu offers two modes, WorkSpace / In one list. WorkSpace mode renders peer session rows within each group in the manual order from `WorkspaceView.sessionIds`; In one list combines every session and sorts them strictly newest-first by `updatedAt`. Neither mode projects `parentId` into a list hierarchy; fork lineage remains session data only. [Web session fork actions](2026-07-27-web-session-fork-actions.md) define the complete fork behavior. The mode choice persists in the browser (`dsh.workspace.view`) across reloads. ### Row interactions - Session rows show a detail card after a 500ms hover dwell (full title / relative time / status line; the status line has only running/idle until the wire grows a status field). The card and the row menu are mutually exclusive: no card while a menu is open or a drag is in flight. -- Session-row … menu: Rename / Fork session / Delete session, visual-only this iteration; workspace-header … menu: Rename (wired) / Delete workspace (visual-only). Menus close when the pointer leaves them. +- Session-row … menu: Rename / Fork session / Delete session; Rename and Fork are wired, while Delete remains visual-only. The workspace-header … menu's Rename / Delete workspace actions are both wired. Menus close when the pointer leaves them. - Supporting primitives: `Menu` gains label entries, danger rows, and `closeOnPointerLeave`; a new `HoverCard` (portaled placement, open delay, disabled guard). ### workspace.rename @@ -30,7 +30,7 @@ The group-by menu offers two modes, WorkSpace / In one list. Flat mode renders e The `session/event` → `touchSession` activity-pinning chain is deleted wholesale; the workspace account order is now manually owned — new sessions prepend at attach, and explicit reordering goes through `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })` (DOM insertBefore semantics: with an anchor it inserts before it, omitted appends to the end). The entity throws a typed `WorkspaceMoveInvalidError` only for unaccounted session/anchor ids; the handler maps exactly that to the business code `workspace-move-invalid`, while storage failures stay internal. -The UI is HTML5 drag on root rows inside a group (workspace grouping only, outside search; fork children ride with their parent and are not draggable). Order authority stays entirely host-side: drop only sends the RPC, the client performs zero local reordering, and the view refreshes from the response upsert and the changed frame; a failed move changes nothing. The client's upsert rejects snapshots older (`updatedAt`) than the installed projection so a late unary response cannot roll back a newer frame. +The UI is HTML5 drag on session rows inside a group (workspace grouping only, outside search; fork children and their source sessions are ordered independently). Order authority stays entirely host-side: drop only sends the RPC, the client performs zero local reordering, and the view refreshes from the response upsert and the changed frame; a failed move changes nothing. The client's upsert rejects snapshots older (`updatedAt`) than the installed projection so a late unary response cannot roll back a newer frame. ### Shell/region split @@ -46,15 +46,15 @@ ui-sidebar shrinks to the column-geometry shell: brand row, fold state machine, **Keep the rename dialog in ui-sidebar (smallest change)** — that is the problem itself: workspace-domain dialogs scattered in a borrowed slot, with each addition (the Delete confirmation is coming) repeating the cross-package wiring. Review first considered moving only the rename modal; the ruling was to give the whole browsing region to ui-workspace and leave the shell geometry-only. -**Keep parent/child adjacency in flat mode** — contradicts strict recency (a child newer than its parent's sibling cannot slot adjacently), and the flat view's purpose is dropping the hierarchy; flattening fully and disabling drag in flat mode (no persistence carrier) is more consistent. +**Nest sessions by fork lineage in WorkSpace mode** — nesting makes the current child visible only while its ancestors are expanded and limits in-group manual ordering to root nodes; `parentId` is lineage data, not a list-navigation structure. Flattening all sessions into peer rows lets each row be opened, searched, and ordered independently; In one list still disables drag because it has no workspace persistence carrier. ## Consequences - Manual order is the sole authority over the workspace account: an order the user arranges is never scrambled by activity; the cost is losing float-to-top-on-activity, whose signal now rides the row status dot and time label. The `WorkspaceView.sessionIds` wire contract is reworded to the manual-order semantics. - The two-fact shell/region contract funnels every future workspace-domain feature (Delete confirmation, cross-group moves, Ungrouped adoption) into the single ui-workspace package; ui-sidebar no longer evolves with session-list features. - Flat mode supports neither reordering nor a create-in-workspace entry point (switching back to grouped view is required) — an accepted scope reduction. -- Wiring the three session-menu items and workspace Delete, and growing the wire status enum, remain future iterations. +- Wiring session Delete and growing the wire status enum remain future iterations. ## Testing -Package-level suites cover the derivations (deriveGroups/deriveFlat), row components, both apply registrations and passthroughs, host entity move semantics, and the rename/insertSessionBefore RPC implementations with their fixture stubs; the `apps/web` keyless snapshots regress the assembled application; delivery acceptance additionally runs a 12-item playwright (chromium headless) checklist (grouped default, flat switch and persistence, hover-card appearance and suppression, both menus, the full rename chain, drag persistence) and drives the real host over the wire for rename success / duplicate rejection / `workspace-move-invalid`. +Package-level suites cover the derivations (deriveGroups/deriveFlat), peer session rows, both apply registrations and passthroughs, host entity move semantics, and the rename/insertSessionBefore RPC implementations with their fixture stubs; the `apps/web` keyless snapshots regress the assembled application and pin that a fork does not introduce session expansion controls. diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md index 432d5167a5..9ad074d59c 100644 --- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md +++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md @@ -12,14 +12,14 @@ Status: implemented ## Decision -### 平铺视图与浏览态 +### 平铺行与浏览态 -group-by 菜单提供 WorkSpace / In one list 两种模式。平铺模式把所有 session(含 fork 子)一律作为顶层行,严格按 `updatedAt` 新→旧排序,不保持父子相邻;Intent 占位行渲染在列表首行。模式选择持久化在浏览器(`dsh.workspace.view`),刷新保持。 +group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序在各组内展示同级 session 行；In one list 把所有 session 合并后严格按 `updatedAt` 新→旧排序。两种模式都不把 `parentId` 投影成列表层级，fork 谱系只保留为 session 数据；完整 fork 行为由 [Web session fork 操作](2026-07-27-web-session-fork-actions.md)定义。模式选择持久化在浏览器(`dsh.workspace.view`),刷新保持。 ### 行交互 - session 行悬停 500ms 出详情卡(全名/相对时间/状态行;状态本期只有 running/idle 两态,枚举扩展待 wire 增补 status 字段)。卡片与行菜单互斥:菜单开启或拖拽进行中不出卡。 -- session 行 … 菜单:Rename / Fork session / Delete session,本期纯视觉;workspace 组头 … 菜单:Rename(已接线)/ Delete workspace(纯视觉)。菜单鼠标移出即关。 +- session 行 … 菜单:Rename / Fork session / Delete session，其中 Rename 与 Fork 已接线，Delete 仍为纯视觉；workspace 组头 … 菜单的 Rename / Delete workspace 均已接线。菜单鼠标移出即关。 - 支撑件:`Menu` 新增 label 条目、danger 行、`closeOnPointerLeave`;新增 `HoverCard`(portal 定位、开启延时、disabled 守卫)。 ### workspace.rename @@ -30,7 +30,7 @@ group-by 菜单提供 WorkSpace / In one list 两种模式。平铺模式把所 `session/event` → `touchSession` 活动置顶链整体删除;workspace 账本序改为纯手动拥有——新 session attach 时前插,显式重排走 `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })`(DOM insertBefore 语义:锚给了插锚前,缺省 append 到末尾)。实体只对不在账的 session/锚抛类型化的 `WorkspaceMoveInvalidError`,handler 仅把它映射为业务码 `workspace-move-invalid`,存储故障保持 internal。 -UI 为组内 root 行的 HTML5 拖拽(仅 workspace 分组、非搜索态;fork 子随父不单独拖)。顺序权威完全在 host:drop 只发 RPC,client 零本地重排,视图靠响应体 upsert 与 changed 帧刷新;失败即无事发生。client 的 upsert 拒绝比已装载投影更旧(`updatedAt`)的快照,防迟到的一元响应回滚更新的帧。 +UI 为组内 session 行的 HTML5 拖拽(仅 workspace 分组、非搜索态；fork 子与源会话一样独立排序)。顺序权威完全在 host:drop 只发 RPC,client 零本地重排,视图靠响应体 upsert 与 changed 帧刷新;失败即无事发生。client 的 upsert 拒绝比已装载投影更旧(`updatedAt`)的快照,防迟到的一元响应回滚更新的帧。 ### 壳/区域切分 @@ -46,15 +46,15 @@ ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settin **rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态,最终裁定整个浏览区域归 ui-workspace,壳只留几何。 -**平铺模式保持父子相邻成组** —— 与「严格按时间」矛盾(子新于兄则插不进相邻位),且平铺本意就是取消层级;拉平并禁用平铺下的拖拽(无持久化载体)更一致。 +**WorkSpace 模式按 fork 谱系嵌套 session** —— 嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有 session 拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。 ## Consequences - 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 契约随之改为手动序措辞。 - 壳/区域两事实契约把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。 - 平铺模式不支持排序与分组入口(建到指定 workspace 需切回分组视图),是拍板接受的范围收窄。 -- session 菜单三项与 workspace Delete 的功能接线、状态枚举扩 wire,留待后续迭代。 +- session Delete 的功能接线与状态枚举扩 wire,留待后续迭代。 ## Testing -包级用例覆盖派生(deriveGroups/deriveFlat)、行组件、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture 桩;`apps/web` keyless snapshot 回归覆盖装配后的应用;交付验收另以 playwright(chromium headless)过 12 项清单(分组默认、平铺切换与持久化、hover 卡出现与抑制、双菜单、rename 全链、拖拽落盘),并对真 host 直打 wire 验证 rename 成功/重名拒绝/`workspace-move-invalid` 三径。 +包级用例覆盖派生(deriveGroups/deriveFlat)、同级 session 行、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture 桩；`apps/web` keyless snapshot 回归覆盖装配后的应用，并钉住 fork 后没有 session 展开控件。 diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index a8f5d98981..1223fcc0f9 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md -README.md: f0dbd3de4ac5b7934b4077b2986f5def5be329c8 -README.zh.md: b9f068c6d1709f0a01d22c3fb1cdc391764d666b +README.md: 2a4e544250756db50b19bc101c19ac79505a3d6c +README.zh.md: 7ae2b0e196a98d1375e9073146bb8119ea8cbe90 diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index f0dbd3de4a..2a4e544250 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,7 +6,7 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. -The Session row's Fork action forks at the source's last completed turn and opens the child; the lineage-aware tree nests it beneath the source. A failure leaves the current selection unchanged. +The Session row's Fork action forks at the source's last completed turn and opens the child; the source and child always appear as peer rows within a workspace group, with lineage retained only as session data. A failure leaves the current selection unchanged. Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index b9f068c6d1..7ae2b0e196 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,7 +6,7 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 -Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork 并打开子会话；感知谱系的树会将子会话嵌套在源会话下。失败不会改变当前选中项。 +Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork 并打开子会话；源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。失败不会改变当前选中项。 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx index 933b49bdf0..60b57e0b06 100644 --- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx +++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx @@ -104,7 +104,6 @@ function SessionTree({ const list = useSessions(s => s) const current = list.current const [expandedProjects, setExpandedProjects] = useState([]) - const [expandedSessions, setExpandedSessions] = useState([]) // Transient drag viewing state (never store-bound; order truth stays Host-side). const [drag, setDrag] = useState(null) const currentGroup = current === undefined @@ -115,27 +114,9 @@ function SessionTree({ if (current === undefined || currentGroup === undefined) return setExpandedProjects(l => (l.includes(currentGroup) ? l : [...l, currentGroup])) }, [current, currentGroup]) - // The selected session must be visible: unfold its ancestor chain (fork - // lands the child under a possibly folded parent row). - const currentAncestors = useMemo(() => { - const chain: string[] = [] - let cursor = current === undefined ? undefined : list.byId[current]?.parentId - while (cursor !== undefined && !chain.includes(cursor)) { - chain.push(cursor) - cursor = list.byId[cursor]?.parentId - } - return chain - }, [current, list]) - useEffect(() => { - if (currentAncestors.length === 0) return - setExpandedSessions((l) => { - const missing = currentAncestors.filter(id => !l.includes(id)) - return missing.length === 0 ? l : [...l, ...missing] - }) - }, [currentAncestors]) const groups = useMemo( - () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions, query }), - [list, workspaces, expandedProjects, expandedSessions, query], + () => deriveGroups(list, workspaces, { expandedProjects, query }), + [list, workspaces, expandedProjects, query], ) const now = Date.now() @@ -146,7 +127,7 @@ function SessionTree({

{query === '' ? 'No sessions yet' : 'No matches'}
)} {groups.map(group => ( - // Group section: header row + expanded session subtree. The + // Group section: header row + expanded top-level session rows. The // inter-group breathing room (former flat-list batch separator) // is the section's own margin (WorkspaceBrowser.module.css).
@@ -170,7 +151,7 @@ function SessionTree({ }} /> {group.sessions.map((node, index) => { - // Draggable: real-workspace group roots outside search. The drag + // Draggable: real-workspace session rows outside search. The drag // never leaves its group — rows of other groups show no markers // and reject drops (visual movement confined to this section). const draggable = group.workspaceId !== undefined && query === '' @@ -188,15 +169,15 @@ function SessionTree({ drop: (half: 'before' | 'after') => { /* v8 ignore next -- narrowing guard: Rows gates drop on `active`, which is false while the drag state is null. */ if (drag === null) return - const roots = group.sessions + const sessions = group.sessions // Anchor = the row the insert line points at ('after' means // the next root; end-of-list omits the anchor → append). - const anchor = half === 'before' ? node.id : roots[index + 1]?.id + const anchor = half === 'before' ? node.id : sessions[index + 1]?.id setDrag(null) if (anchor === drag.sessionId) return // No-op when the drop lands back on the source position. - const sourceIndex = roots.findIndex(r => r.id === drag.sessionId) - const anchorIndex = anchor === undefined ? roots.length : roots.findIndex(r => r.id === anchor) + const sourceIndex = sessions.findIndex(r => r.id === drag.sessionId) + const anchorIndex = anchor === undefined ? sessions.length : sessions.findIndex(r => r.id === anchor) if (sourceIndex !== -1 && (anchorIndex === sourceIndex || anchorIndex === sourceIndex + 1)) return insertSessionBefore(drag.workspaceId, drag.sessionId, anchor).catch((reason: unknown) => { console.warn('session reorder rejected:', reason) @@ -208,13 +189,11 @@ function SessionTree({ { setExpandedSessions(l => toggled(l, id)) }} drag={dragProps} /> ) @@ -242,15 +221,11 @@ function FlatList({ useSessions, open, forkSession, onSessionRename, query }: Pi {}} - flat /> ))}
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css index 5a5cac914e..f64849e1c5 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.module.css +++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css @@ -39,9 +39,7 @@ height: 20px; } -/* Session cell (figma): pad 8, adjacent 16px twist + status slots, then a 4px - gap to the title — the slots butt together, so the row gap is zeroed and - the title carries its own margins. */ +/* Session cell (figma): pad 8, a 16px status slot, then a 4px title gap. */ .sessionRow { height: 34px; gap: 0; @@ -168,7 +166,7 @@ background: var(--dsw-alias-interactive-bg-hover); } -/* Drag reorder insert line (workspace-group roots): 2px accent above or +/* Drag reorder insert line (workspace-group session rows): 2px accent above or below the hovered row, drawn with box-shadow so no layout shift. */ .sessionRow.dropBefore { box-shadow: 0 -2px 0 0 var(--dsw-alias-state-business-primary); @@ -233,33 +231,9 @@ color: var(--dsw-alias-label-primary); } -/* Session expand twist occupies the leading 16px slot; keep a spacer when absent - so titles align across sibling rows. Duplicates the .iconButton reset instead - of `composes:` — the tsdown CSS-modules pipeline drops composes mappings, which - left the raw UA button box showing. */ -.twist { - flex: none; - display: inline-flex; - align-items: center; - justify-content: center; - width: 16px; - height: 20px; - border: none; - border-radius: 4px; - padding: 0; - background: transparent; - cursor: pointer; -} - -.twist:hover { - color: var(--dsw-alias-label-primary); -} - -/* Chevrons and tree twists ride the caption grey (#ADB2B8); the folder glyph - stays one step darker (tertiary, #81858C) per the cell spec. Declared last - to win over the composed .iconButton color. */ -.chevron, -.twist { +/* Chevrons ride the caption grey (#ADB2B8); the folder glyph stays one step + darker (tertiary, #81858C) per the cell spec. */ +.chevron { color: var(--dsw-alias-label-caption); } diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index 657585f075..6dceec4ef6 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -16,9 +16,6 @@ import type { GroupNode, SessionNode } from '../tree.ts' import { formatRelativeTime } from '../tree.ts' import css from './Rows.module.css' -/** Indent step per tree level: one 16px slot (figma session cell). */ -const INDENT_STEP = 16 - const SESSION_MENU_ITEMS = [ { id: 'rename', label: 'Rename', icon: }, { id: 'fork', label: 'Fork session', icon: }, @@ -135,16 +132,12 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions }: { } /** - * One session subtree: the node's own 34px row (indent by depth, expand - * twist when it has children, running dot, relative time) plus its visible - * children, recursively — the component tree mirrors the derived tree. + * One top-level 34px session row with running dot and relative time. * @param props.node - derived session node. - * @param props.depth - 0 = directly under the group header. * @param props.currentId - selected session id (row highlight). * @param props.now - epoch ms for relative-time formatting. * @param props.onOpen - open a session by id. - * @param props.onToggle - unfold/fold a subtree by id. - * @returns the node's row followed by its children. + * @returns the session row. */ /** Hover-card body: full title, relative time, and the status line (running/idle until wire status lands). */ function SessionHoverContent({ node, now }: { node: SessionNode; now: number }) { @@ -161,7 +154,7 @@ function SessionHoverContent({ node, now }: { node: SessionNode; now: number }) } /** - * Root-row drag wiring supplied by the group owner (workspace groups only). + * Session-row drag wiring supplied by the group owner (workspace groups only). * `drop` reports the half of the row the pointer released on: 'before' * inserts above this row, 'after' below it (the owner resolves the anchor). */ @@ -184,9 +177,8 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' | return e.clientY < rect.top + rect.height / 2 ? 'before' : 'after' } -export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onFork, onToggle, drag, flat = false }: { +export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork, drag }: { node: SessionNode - depth: number currentId: string | undefined now: number onOpen: (id: SessionNode['id']) => void @@ -194,18 +186,13 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onRename: (id: SessionNode['id'], currentTitle: string) => void /** Fork a session at its last completed turn (row menu action). */ onFork: (id: SessionNode['id']) => void - onToggle: (id: SessionNode['id']) => void - /** Present only on draggable rows (workspace-group roots outside search). */ + /** Present only on draggable rows (workspace-group sessions outside search). */ drag?: RowDragProps | undefined - /** Flat-list variant: no twist slot (figma flat cell) — titles align on the status slot. */ - flat?: boolean }) { const row = node const selected = node.id === currentId const [menuOpen, setMenuOpen] = useState(false) - // Rail (figma session cell: pad 8, twist slot 16, status slot 16, gap 4 to - // the title): both slots are always reserved so titles align whether or not - // the twist/dot is lit. Extra depth rides the left padding. + // Figma session cell: pad 8, status slot 16, then a 4px title gap. const ownRow = (
{ onOpen(node.id) }} draggable={drag !== undefined} onDragStart={drag === undefined @@ -241,18 +226,6 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, drag.drop(rowHalf(e)) }} > - {row.hasChildren && !flat - ? ( - - ) - : null} {row.running && } {row.title} {formatRelativeTime(row.updatedAt, now)} @@ -283,25 +256,10 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename,
) return ( - <> - } - disabled={menuOpen || drag?.active === true} - /> - {node.children.map(child => ( - - ))} - + } + disabled={menuOpen || drag?.active === true} + /> ) } diff --git a/packages/client/ui-workspace/src/client/tree.ts b/packages/client/ui-workspace/src/client/tree.ts index de47454d84..3f30064269 100644 --- a/packages/client/ui-workspace/src/client/tree.ts +++ b/packages/client/ui-workspace/src/client/tree.ts @@ -11,20 +11,15 @@ export const UNGROUPED_KEY = '' /** Display label for the ungrouped bucket row. */ export const UNGROUPED_LABEL = 'Ungrouped' -/** One session node of a group's visible tree (34px row; children render indented one step). */ +/** One top-level session row in a group or the flat list. */ export interface SessionNode { id: SessionId title: string - /** Visible children, already expansion/search-filtered (empty when folded). */ - children: readonly SessionNode[] - /** The session HAS children in the data (the twist renders even while folded). */ - hasChildren: boolean - expanded: boolean running: boolean updatedAt: number } -/** One workspace group section: header row facts + the visible session tree. */ +/** One workspace group section: header row facts + visible top-level session rows. */ export interface GroupNode { /** Group key: the workspace id or {@link UNGROUPED_KEY}. */ key: string @@ -39,14 +34,13 @@ export interface GroupNode { expanded: boolean /** The group contains the selected session (active folder tint; supplied here so the renderer never scans). */ containsCurrent: boolean - /** Visible roots (empty while the group is folded). */ + /** Visible session rows (empty while the group is folded). */ sessions: readonly SessionNode[] } -/** Viewing state consumed by the derivation — the component's local useState arrays, taken as-is. */ +/** Viewing state consumed by the derivation. */ export interface TreeView { expandedProjects: readonly string[] - expandedSessions: readonly string[] query: string } @@ -56,9 +50,7 @@ interface Group { cwd: string | undefined createdAt: number | undefined label: string - summaries: Map - roots: SessionId[] - children: Map + sessions: SessionSummary[] } /** @@ -89,7 +81,7 @@ function sessionTitle(session: SessionSummary): string { return session.blank ? 'New Session' : session.displayTitle } -/** Build one group's parent/child tree from an ordered member list. */ +/** Build one group without projecting session lineage into presentation. */ function buildGroup( key: string, workspaceId: WorkspaceId | undefined, @@ -99,54 +91,11 @@ function buildGroup( members: readonly SessionSummary[], order: 'account' | 'recency', ): Group { - const summaries = new Map(members.map(m => [m.id, m])) - const children = new Map() - const roots: SessionSummary[] = [] - for (const m of members) { - // A session is a tree child only when its parent lives in the same - // group; cross-group or unknown parents degrade to group roots. - if (m.parentId !== undefined && m.parentId !== m.id && summaries.has(m.parentId)) { - const kids = children.get(m.parentId) - if (kids === undefined) children.set(m.parentId, [m.id]) - else kids.push(m.id) - } else { - roots.push(m) - } - } - // Workspace order is the member iteration order (workspace.sessionIds), so - // attached groups keep insertion order; Ungrouped sorts by recency. - if (order === 'recency') { - roots.sort(byRecency) - for (const kids of children.values()) { - kids.sort((a, b) => { - const sa = summaries.get(a) - const sb = summaries.get(b) - /* v8 ignore next -- unreachable: kid ids are inserted alongside their summaries. */ - if (sa === undefined || sb === undefined) return 0 - return byRecency(sa, sb) - }) - } - } - const rootIds = roots.map(r => r.id) - // parentId cycles (host bug) leave members unreachable from any root; - // surface them as extra roots — the flatten walk's visited set stops - // loops. Each node sits in at most one kids list and roots have no - // in-group parent, so the scan pushes every reachable node exactly once. - const reachable = new Set(rootIds) - const stack = [...rootIds] - while (stack.length > 0) { - const top = stack.pop() - /* v8 ignore next -- unreachable: the loop condition guarantees a non-empty stack. */ - if (top === undefined) break - for (const kid of children.get(top) ?? []) { - reachable.add(kid) - stack.push(kid) - } - } - for (const m of members) { - if (!reachable.has(m.id)) rootIds.push(m.id) - } - return { key, workspaceId, cwd, createdAt, label, summaries, roots: rootIds, children } + const sessions = [...members] + // Workspace order is workspace.sessionIds; only Ungrouped lacks an account + // order and therefore falls back to recency. + if (order === 'recency') sessions.sort(byRecency) + return { key, workspaceId, cwd, createdAt, label, sessions } } /** @@ -181,72 +130,24 @@ function groupByWorkspace(list: SessionListState, workspaces: readonly Workspace return groups } -function sessionNode(s: SessionSummary, children: readonly SessionNode[], hasChildren: boolean, expanded: boolean): SessionNode { +function sessionNode(s: SessionSummary): SessionNode { return { id: s.id, title: sessionTitle(s), - children, - hasChildren, - expanded, running: s.running, updatedAt: s.updatedAt, } } -function buildVisible(g: Group, expandedSessions: ReadonlySet): SessionNode[] { - const visited = new Set() - const walk = (id: SessionId): SessionNode | null => { - if (visited.has(id)) return null - visited.add(id) - const s = g.summaries.get(id) - /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */ - if (s === undefined) return null - const kids = g.children.get(id) ?? [] - const expanded = expandedSessions.has(id) - const children = expanded ? kids.map(walk).filter((n): n is SessionNode => n !== null) : [] - return sessionNode(s, children, kids.length > 0, expanded) - } - return g.roots.map(walk).filter((n): n is SessionNode => n !== null) -} - -/** Matched sessions plus their ancestor chains (forced visible under search). */ -function searchVisible(g: Group, q: string): Set { - const visible = new Set() - for (const m of g.summaries.values()) { - if (!sessionTitle(m).toLowerCase().includes(q)) continue - let cur: SessionSummary | undefined = m - while (cur !== undefined && !visible.has(cur.id)) { - visible.add(cur.id) - cur = cur.parentId !== undefined && cur.parentId !== cur.id ? g.summaries.get(cur.parentId) : undefined - } - } - return visible -} - -function buildSearch(g: Group, visible: ReadonlySet): SessionNode[] { - const visited = new Set() - const walk = (id: SessionId): SessionNode | null => { - if (visited.has(id) || !visible.has(id)) return null - visited.add(id) - const s = g.summaries.get(id) - /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */ - if (s === undefined) return null - const kids = (g.children.get(id) ?? []).filter(kid => visible.has(kid)) - const children = kids.map(walk).filter((n): n is SessionNode => n !== null) - return sessionNode(s, children, kids.length > 0, kids.length > 0) - } - return g.roots.map(walk).filter((n): n is SessionNode => n !== null) -} - /** - * Derive the nested workspace browser group structure. + * Derive the workspace browser groups with every session as a top-level row. * * Normal mode: every group shows; sessions populate under expanded groups, - * descending only into expanded sessions. Search mode (non-blank query, + * preserving Host account order. Search mode (non-blank query, * case-insensitive display-title substring): expansion state is ignored — - * matched sessions and their ancestor chains are forced visible, groups - * without a display-title or label hit are dropped, and a label-only hit - * keeps the bare group header. Blank sessions are excluded everywhere. + * matching sessions are forced visible, groups without a display-title or + * label hit are dropped, and a label-only hit + * keeps the bare group header. Non-current blank sessions are excluded. * @param list - sessions list snapshot (`current` feeds containsCurrent). * @param workspaces - real workspaces in stable Host order. * @param view - local expansion arrays and search query. @@ -259,7 +160,6 @@ export function deriveGroups( ): GroupNode[] { const q = view.query.trim().toLowerCase() const expandedProjects = new Set(view.expandedProjects) - const expandedSessions = new Set(view.expandedSessions) const currentGroup = list.current === undefined ? undefined : (workspaces.find(w => w.sessionIds.includes(list.current as SessionId))?.workspaceId as string | undefined) @@ -274,24 +174,24 @@ export function deriveGroups( cwd: g.cwd, createdAt: g.createdAt, label: g.label, - sessionCount: g.summaries.size, + sessionCount: g.sessions.length, expanded, containsCurrent: g.key === currentGroup, - sessions: expanded ? buildVisible(g, expandedSessions) : [], + sessions: expanded ? g.sessions.map(sessionNode) : [], }) } else { - const visible = searchVisible(g, q) - if (visible.size === 0 && !g.label.toLowerCase().includes(q)) continue + const matches = g.sessions.filter(session => sessionTitle(session).toLowerCase().includes(q)) + if (matches.length === 0 && !g.label.toLowerCase().includes(q)) continue groups.push({ key: g.key, workspaceId: g.workspaceId, cwd: g.cwd, createdAt: g.createdAt, label: g.label, - sessionCount: g.summaries.size, - expanded: visible.size > 0, + sessionCount: g.sessions.length, + expanded: matches.length > 0, containsCurrent: g.key === currentGroup, - sessions: buildSearch(g, visible), + sessions: matches.map(sessionNode), }) } } @@ -301,9 +201,8 @@ export function deriveGroups( /** * Derive the flat session list ("In one list" mode): every session — fork * children included — as a top-level row, strictly newest-first. No grouping, - * no parent/child adjacency; rows reuse SessionNode with children always - * empty so the renderer stays branch-free. Search mode filters by - * case-insensitive display-title substring. + * no parent/child adjacency. Search mode filters by case-insensitive + * display-title substring. * @param list - sessions list snapshot. * @param view - the search query (expansion state does not apply). * @returns flat rows in render order. @@ -318,7 +217,7 @@ export function deriveFlat(list: SessionListState, view: Pick rows.push(s) } rows.sort(byRecency) - return rows.map(s => sessionNode(s, [], false, false)) + return rows.map(sessionNode) } /** diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx index 44a311d6d3..3be85a7646 100644 --- a/packages/client/ui-workspace/tests/rows.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.spec.tsx @@ -56,46 +56,22 @@ describe('workspace browser rows', () => { expect(onToggle).toHaveBeenCalledOnce() }) - it('renders and operates selected, running, recursive Session nodes', () => { - const child: SessionNode = { - id: sid('child'), title: 'Child', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, - } - const parent: SessionNode = { - id: sid('parent'), title: 'Parent', children: [child], hasChildren: true, - expanded: true, running: true, updatedAt: 0, + it('renders and opens a selected running Session row', () => { + const node: SessionNode = { + id: sid('session'), title: 'Session', running: true, updatedAt: 0, } const onOpen = vi.fn() - const onToggle = vi.fn() - const view = render( - , + render( + , ) - const parentRow = screen.getByText('Parent').closest('[role="treeitem"]')! - const childRow = screen.getByText('Child').closest('[role="treeitem"]')! - expect(parentRow.getAttribute('aria-selected')).toBe('true') - expect(parentRow.getAttribute('aria-expanded')).toBe('true') - expect(childRow.getAttribute('aria-selected')).toBe('false') - expect(childRow.hasAttribute('aria-expanded')).toBe(false) - - fireEvent.click(screen.getByRole('button', { name: 'Collapse' })) - expect(onToggle).toHaveBeenCalledWith(parent.id) - expect(onOpen).not.toHaveBeenCalled() - fireEvent.click(parentRow) - fireEvent.click(childRow) - expect(onOpen.mock.calls).toEqual([[parent.id], [child.id]]) - - view.rerender( - , - ) - expect(screen.getByRole('button', { name: 'Expand' })).toBeTruthy() - expect(screen.getByRole('treeitem').getAttribute('aria-selected')).toBe('false') - expect(screen.getByRole('treeitem').style.paddingLeft).toBe('24px') + const row = screen.getByRole('treeitem') + expect(row.getAttribute('aria-selected')).toBe('true') + expect(row.hasAttribute('aria-expanded')).toBe(false) + expect(screen.queryByRole('button', { name: /Expand|Collapse/ })).toBeNull() + fireEvent.click(row) + expect(onOpen).toHaveBeenCalledWith(node.id) }) it('workspace row menu opens on the ellipsis, renames, and shows the danger delete row', () => { @@ -161,11 +137,10 @@ describe('workspace browser rows', () => { const onRename = vi.fn() const onFork = vi.fn() const node: SessionNode = { - id: sid('s1'), title: 'One', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + id: sid('s1'), title: 'One', running: false, updatedAt: 0, } - render() + render() fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' })) expect(onOpen).not.toHaveBeenCalled() expect(screen.getByRole('menuitem', { name: 'Delete session' }).className).toMatch(/danger/) @@ -187,25 +162,14 @@ describe('workspace browser rows', () => { expect(screen.queryByRole('menu')).toBeNull() }) - it('flat variant renders no twist even for a parent and ignores toggling', () => { - const node: SessionNode = { - id: sid('p'), title: 'Parent', children: [], hasChildren: true, - expanded: false, running: false, updatedAt: 0, - } - render() - expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull() - }) - it('shows the hover card after the dwell and suppresses it while the row menu is open', () => { vi.useFakeTimers() try { const node: SessionNode = { - id: sid('s1'), title: 'Hovered', children: [], hasChildren: false, - expanded: false, running: true, updatedAt: 0, + id: sid('s1'), title: 'Hovered', running: true, updatedAt: 0, } - render() + render() const wrapper = screen.getByRole('treeitem').parentElement as HTMLElement fireEvent.pointerEnter(wrapper) act(() => { vi.advanceTimersByTime(500) }) @@ -228,11 +192,10 @@ describe('workspace browser rows', () => { vi.useFakeTimers() try { const node: SessionNode = { - id: sid('s1'), title: 'Quiet', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + id: sid('s1'), title: 'Quiet', running: false, updatedAt: 0, } - render() + render() fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement) act(() => { vi.advanceTimersByTime(500) }) expect(screen.getByText('Idle')).toBeTruthy() @@ -244,13 +207,12 @@ describe('workspace browser rows', () => { it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => { const node: SessionNode = { - id: sid('s1'), title: 'Drag me', children: [], hasChildren: false, - expanded: false, running: false, updatedAt: 0, + id: sid('s1'), title: 'Drag me', running: false, updatedAt: 0, } const inactive = dragProps() const { rerender } = render( - , + , ) const row = screen.getByRole('treeitem') stubRect(row) @@ -267,8 +229,8 @@ describe('workspace browser rows', () => { const active = dragProps({ active: true, marker: 'before' }) rerender( - , + , ) stubRect(screen.getByRole('treeitem')) // Top half hovers/drops 'before'; bottom half 'after' (row mid = 117). @@ -281,8 +243,8 @@ describe('workspace browser rows', () => { const after = dragProps({ active: true, marker: 'after' }) rerender( - , + , ) expect(screen.getByRole('treeitem').className).toMatch(/dropAfter/) }) diff --git a/packages/client/ui-workspace/tests/tree.spec.ts b/packages/client/ui-workspace/tests/tree.spec.ts index eb34f633d8..aa5828e8ac 100644 --- a/packages/client/ui-workspace/tests/tree.spec.ts +++ b/packages/client/ui-workspace/tests/tree.spec.ts @@ -21,7 +21,7 @@ const workspace = (id: string, sessionIds: string[]): WorkspaceView => ({ sessionIds: sessionIds.map(sid), createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z', }) const view = (expandedProjects: readonly string[] = [], query = '') => ({ - expandedProjects, expandedSessions: [] as string[], query, + expandedProjects, query, }) describe('deriveGroups', () => { @@ -74,7 +74,7 @@ describe('deriveGroups', () => { expect(groups[0]!.sessionCount).toBe(1) }) - it('builds, sorts, expands, and cycle-guards an ungrouped session tree', () => { + it('ignores fork lineage and sorts every ungrouped session as a top-level row', () => { const parent = summary('parent', 1) const oldChild = { ...summary('old-child', 10), parentId: parent.id } const newChild = { ...summary('new-child', 20), parentId: parent.id } @@ -87,15 +87,13 @@ describe('deriveGroups', () => { const groups = deriveGroups( list(parent, oldChild, newChild, tieB, tieA, self, orphan, cycleA, cycleB), [], - { expandedProjects: [UNGROUPED_KEY], expandedSessions: [parent.id, cycleA.id, cycleB.id], query: '' }, + { expandedProjects: [UNGROUPED_KEY], query: '' }, ) expect(groups).toHaveLength(1) expect(groups[0]!.sessions.map(node => node.id)).toEqual([ - sid('orphan'), sid('self'), parent.id, sid('cycle-a'), - ]) - expect(groups[0]!.sessions[2]!.children.map(node => node.id)).toEqual([ newChild.id, tieA.id, tieB.id, oldChild.id, + cycleB.id, cycleA.id, orphan.id, self.id, parent.id, ]) // Equal timestamps use ids as a deterministic tiebreak in either input order. @@ -113,7 +111,7 @@ describe('deriveGroups', () => { expect(groups[0]!.sessions.map(node => node.id)).toEqual([sid('present')]) }) - it('searches descendants with ancestors and handles cycles, self parents, and label-only hits', () => { + it('searches rows independently of lineage and keeps label-only hits', () => { const root = { ...summary('root', 1), displayTitle: 'Ancestor' } const match = { ...summary('match', 2), displayTitle: 'Needle child', parentId: root.id } const sibling = { ...summary('sibling', 3), displayTitle: 'Other child', parentId: root.id } @@ -124,8 +122,8 @@ describe('deriveGroups', () => { const sessions = list(root, match, sibling, self, orphan, cycleA, cycleB) const groups = deriveGroups(sessions, [workspace('project', sessions.ids)], view([], 'needle')) - expect(groups[0]!.sessions.flatMap(node => [node.id, ...node.children.map(child => child.id)])).toEqual([ - root.id, match.id, self.id, orphan.id, cycleA.id, cycleB.id, + expect(groups[0]!.sessions.map(node => node.id)).toEqual([ + match.id, self.id, orphan.id, cycleA.id, cycleB.id, ]) const labelOnly = deriveGroups( @@ -157,8 +155,6 @@ describe('deriveFlat', () => { const tieA = summary('tie-a', 20) const rows = deriveFlat(list(parent, child, tieB, tieA), { query: '' }) expect(rows.map(row => row.id)).toEqual([sid('child'), sid('tie-a'), sid('tie-b'), sid('parent')]) - // Rows are branch-free: no children, no expansion. - expect(rows.every(row => row.children.length === 0 && !row.hasChildren && !row.expanded)).toBe(true) }) it('search filters by case-insensitive display-title substring', () => { diff --git a/packages/client/ui-workspace/tests/workspace-browser.spec.tsx b/packages/client/ui-workspace/tests/workspace-browser.spec.tsx index d0535ecdfa..a6603593cc 100644 --- a/packages/client/ui-workspace/tests/workspace-browser.spec.tsx +++ b/packages/client/ui-workspace/tests/workspace-browser.spec.tsx @@ -125,7 +125,7 @@ describe('WorkspaceBrowser', () => { expect(screen.queryByText('alpha-s')).toBeNull() }) - it('unfolds a session subtree through the row twist', () => { + it('renders a fork child as a top-level row without a session twist', () => { const parent = summary('parent-s', 2) const child = { ...summary('child-s', 1), parentId: parent.id } mount({ @@ -133,11 +133,9 @@ describe('WorkspaceBrowser', () => { useWorkspaces: hook(workspaceState([workspace('alpha', ['parent-s', 'child-s'])])), }) fireEvent.click(screen.getByText('alpha')) - expect(screen.queryByText('child-s')).toBeNull() - fireEvent.click(screen.getByRole('button', { name: 'Expand' })) expect(screen.getByText('child-s')).toBeTruthy() - fireEvent.click(screen.getByRole('button', { name: 'Collapse' })) - expect(screen.queryByText('child-s')).toBeNull() + expect(screen.queryByRole('button', { name: /Expand|Collapse/ })).toBeNull() + expect(screen.getByText('child-s').closest('[role="treeitem"]')?.getAttribute('draggable')).toBe('true') }) it('auto-expands the selected session group and starts a session from the group ＋', () => { From 213de9a7373529f45e7969b903c96f8dbe82d86c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 20:30:02 +0800 Subject: [PATCH 51/67] feat(ui-conversation): wire assistant session forks --- ...6-07-27-web-session-fork-actions.i18n.yaml | 6 ++++ .../2026-07-27-web-session-fork-actions.md | 33 +++++++++++++++++++ .../2026-07-27-web-session-fork-actions.zh.md | 33 +++++++++++++++++++ ...b-message-icon-actions-and-clock.i18n.yaml | 4 +-- ...7-29-web-message-icon-actions-and-clock.md | 6 ++-- ...9-web-message-icon-actions-and-clock.zh.md | 6 ++-- apps/web/tests/message-actions.e2e.ts | 8 +++-- .../message-actions/fork.expected.md | 5 +-- .../src/client/chat/AssistantMarkdown.tsx | 7 +++- .../src/client/chat/ChatView.tsx | 2 ++ .../src/client/chat/MessageIconActions.tsx | 4 +-- .../ui-conversation/tests/chat-view.spec.tsx | 10 ++++++ 12 files changed, 107 insertions(+), 17 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md create mode 100644 .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml new file mode 100644 index 0000000000..976dcc1d1d --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md +2026-07-27-web-session-fork-actions.md: 90d2f9a8085cf1f1d2656bb442eee1e4116bb91a +2026-07-27-web-session-fork-actions.zh.md: f0642d17fdb6030dea16ff1440c730c605fec13d diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md new file mode 100644 index 0000000000..90d2f9a808 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md @@ -0,0 +1,33 @@ +# Agent Note: Web session fork actions + +Status: implemented + +English | [中文](2026-07-27-web-session-fork-actions.zh.md) + +## Problem + +The Session store already provides a fork primitive that creates a child session from a completed-turn prefix, but the Web client has no unified interaction contract. The Session-row menu can express only “branch from the latest completed turn,” while message IconActions need to express “branch from the turn containing this message”; if the two entry points independently interpret the boundary, switching, and failure behavior, the same user action acquires two sets of semantics. Nesting a fork child beneath its source session also makes the newly selected child visible only while its ancestors are expanded and weakens the workspace manual-order model. + +## Decision + +The Web Session-row menu and message IconActions share the client runtime's `sessions.fork` action. A Session row passes `{ sessionId }`, so it forks at the source session's last completed turn; a user message or settled assistant content message passes `{ sessionId, atSeq: node.seq }`, so it forks at the turn containing that event. On success, the client first adds the child session to its local list and then opens it; on failure, it leaves the source session and current selection unchanged. + +`forkAt(seq)` touches the session service only in ui-conversation's apply injection layer; message components report only the event `seq`. Session rows likewise initiate the operation only through ui-workspace's injected callback. Neither presentation package owns session mutation state or duplicates the host's boundary evaluation. + +Session lineage is not projected into a list hierarchy. WorkSpace mode displays source sessions and all fork children as peer rows in the manual order from `WorkspaceView.sessionIds`; every row can be opened, searched, and dragged independently. In one list mode continues to sort strictly by `updatedAt`; the Ungrouped group also sorts by recency when no workspace ledger is available. `parentId` remains available for lineage, tool presentation, and later queries, but does not control session-list visibility. + +## Alternatives considered + +**Wire only the Session-row menu.** Rejected: at a message, the user has already selected more precise context; forcing them back to the list can only degrade the boundary to the latest completed turn, while the visible message branch icon would remain non-responsive. + +**Allow branching only from user messages.** Rejected: settled assistant content also has a stable event `seq`, and the host places it in its containing completed turn; making only one of two visually identical branch buttons work would create an invisible behavioral difference. + +**Nest fork children beneath their source by `parentId`.** Rejected: lineage is not navigation ownership; nesting requires automatic ancestor expansion to reveal the current item and prevents children from participating in the workspace's peer manual order. + +**Call the session service directly from message components.** Rejected: client components must not touch `ctx` or business services; injected callbacks keep mutation in the apply world and leave components driven purely by props. + +## Consequences + +Users can create forks from Session rows, user messages, or settled assistant content messages; all three entry points ultimately use the same runtime/host operation. Message entry points preserve the exact event boundary, while the list entry point preserves the “latest completed turn” shortcut. Every fork child immediately appears as an ordinary peer row, so the list no longer needs session expansion state, recursive nodes, or twist controls. + +Fork failures stay silent and preserve the source selection, preventing a derivation action from disrupting the current reading position; this tradeoff also means the UI does not yet expose a failure reason or retry entry point. Package tests separately pin the two message `seq` paths and the peer-list derivation; `apps/web/tests/message-actions.e2e.ts` exercises assistant-message branching and Session-row menu branching through the assembled application. diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md new file mode 100644 index 0000000000..f0642d17fd --- /dev/null +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md @@ -0,0 +1,33 @@ +# Agent Note: Web session fork 操作 + +Status: implemented + +[English](2026-07-27-web-session-fork-actions.md) | 中文 + +## Problem + +Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互契约。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。 + +## Decision + +Web 的 session 行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。Session 行传 `{ sessionId }`，因此在源会话最后一个已完成轮次处分支；用户消息与已定稿 assistant 内容消息传 `{ sessionId, atSeq: node.seq }`，因此在包含该事件的轮次处分支。成功后 client 先把子会话纳入本地列表，再打开子会话；失败时保持源会话与当前选择不变。 + +`forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触 session 服务，消息组件只回传事件 `seq`。Session 行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。 + +Session lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序把源会话与所有 fork 子会话显示为同级行，每行都可独立打开、搜索和拖拽；In one list 模式继续按 `updatedAt` 严格排序；Ungrouped 组在没有 workspace 账本时也按 recency 排序。`parentId` 仍用于 lineage、工具呈现和后续查询，但不控制 session 列表可见性。 + +## Alternatives considered + +**只接 session 行菜单。** 否决：用户在消息处已经选择了更精确的上下文，强迫其回到列表只能退化为最新完成轮，且已展示的消息分支图标会成为无响应控件。 + +**只允许用户消息分支。** 否决：已定稿 assistant 内容同样有稳定事件 `seq`，host 会把它归入所属完成轮；让两个外观相同的分支按钮只有一个可用会制造不可见的行为差异。 + +**按 `parentId` 把 fork 子会话嵌套在源会话下。** 否决：lineage 不是导航所有权；嵌套要求自动展开祖先才能看见当前项，并让子会话无法参与 workspace 的同级手动排序。 + +**由消息组件直接调用 session 服务。** 否决：client 组件不得接触 `ctx` 或业务服务；注入回调让 mutation 留在 apply 世界，组件保持纯 props。 + +## Consequences + +用户可从 session 行、用户消息或已定稿 assistant 内容消息创建分支，三处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新完成轮」快捷语义。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。 + +Fork 失败保持静默并保留源选择，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。Package tests 分别钉住两种消息 `seq` 与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。 diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml index de8869a96a..f2e1183fe5 100644 --- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md -2026-07-29-web-message-icon-actions-and-clock.md: e79662056792c3ab413468ad038dec40455be767 -2026-07-29-web-message-icon-actions-and-clock.zh.md: 72d3b4e0cda19438f2f46fd402b3b76de3726ae5 +2026-07-29-web-message-icon-actions-and-clock.md: ccc9b127d2fcf276fa415ec0ede8b062e45f3df5 +2026-07-29-web-message-icon-actions-and-clock.zh.md: fb4b82a22478b2de38755368ec48a5dca420e79d diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md index e796620567..ccc9b127d2 100644 --- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md +++ b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md @@ -12,7 +12,7 @@ The web chat user bubble already had copy / branch / edit IconActions but no clo **User bubbles prepend a date-aware local clock to the existing IconActions row; finalized assistant *content* nodes (non-empty text blocks) append a copy / branch / clock row with `margin-top: 16px`; both seats stay visible whenever mounted and re-format at the next local midnight.** -Both seats format `node.time` through `formatMessageClock`: same calendar day → `HH:mm`, earlier this year → `M月D日 HH:mm`, other years → `YYYY年M月D日 HH:mm`. `useCalendarDay` is a component-local day tick (timeout to the next local midnight) so memoized rows re-render when the calendar day changes without a new framework hook. `MessageItem` places the label before copy (figma `388:20051`). `AssistantMarkdown` places it after branch (figma `43:32997`) only when `streaming` is false, the event time is known, and the node has non-empty text content; Think-only nodes and the streaming tail omit the row. Copy writes joined text blocks. Branch stays a chrome stub. Clipboard write and the clock helpers live in `message-chrome.ts`. The assembled surface is pinned by `apps/web/tests/message-actions.e2e.ts` (cold-seeded history + aria golden); aria normalization collapses every clock shape to `{{clock}}`. +Both seats format `node.time` through `formatMessageClock`: same calendar day → `HH:mm`, earlier this year → `M月D日 HH:mm`, other years → `YYYY年M月D日 HH:mm`. `useCalendarDay` is a component-local day tick (timeout to the next local midnight) so memoized rows re-render when the calendar day changes without a new framework hook. `MessageItem` places the label before copy (figma `388:20051`). `AssistantMarkdown` places it after branch (figma `43:32997`) only when `streaming` is false, the event time is known, and the node has non-empty text content; Think-only nodes and the streaming tail omit the row. Copy writes joined text blocks. Both message rows pass their event's `seq` to the same fork callback; [Web session fork actions](2026-07-27-web-session-fork-actions.md) define the real mutation contract. Clipboard write and the clock helpers live in `message-chrome.ts`. The assembled surface is pinned by `apps/web/tests/message-actions.e2e.ts` (cold-seeded history + aria golden); aria normalization collapses every clock shape to `{{clock}}`. ## Alternatives considered @@ -22,10 +22,10 @@ Both seats format `node.time` through `formatMessageClock`: same calendar day **Hover-reveal the action row on hover-capable pointers.** Rejected: once the row exists it should stay discoverable; opacity hiding made the chrome easy to miss and required parent hover selectors that duplicated the mount gate. -**Wire branch to a real session fork.** Rejected for this change: same rationale as the archived [user IconActions note](../../archived/feature/2026-07-27-user-message-icon-actions.md) — the mutation path is unspecified; the button reserves the design seat. +**Let the IconActions decision also define session fork semantics.** Rejected: this note owns only message chrome, clocks, and mount gating; boundary selection, failure behavior, and switching semantics belong to the separate [Web session fork actions](2026-07-27-web-session-fork-actions.md), keeping presentation components from becoming a second home for session mutation. **Publish the calendar day through a chat store or inject hook.** Rejected: the day tick is presentation-only local state with no cross-entry consumers; a component-local timeout matches the client rule that behavioral hooks may own state that does not subscribe to an external source. ## Consequences -Settled assistant content answers expose copy and the event clock as soon as the row mounts; Think-only nodes stay chrome-free; branch stays a stub. User and assistant clocks share the same day/year widening rules and refresh after midnight without a message mutation. Per-message paging remains a deferred footer seat in the package README. Package tests pin the three clock shapes, the midnight widen, and the content-only assistant gate; the web e2e scenario pins the assembled IconActions chrome. +Settled assistant content answers expose copy, branch, and the event clock as soon as the row mounts; Think-only nodes stay chrome-free. User and assistant clocks share the same day/year widening rules and refresh after midnight without a message mutation. Per-message paging remains a deferred footer seat in the package README. Package tests pin the three clock shapes, the midnight widen, the content-only assistant gate, and the respective event `seq` values passed by the user and assistant branch buttons; the web e2e scenario pins the assembled IconActions chrome. diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md index 72d3b4e0cd..fb4b82a224 100644 --- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md +++ b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md @@ -12,7 +12,7 @@ Web 聊天的用户气泡已有复制／分支／编辑 IconActions，但没有 **用户气泡在既有 IconActions 行前追加感知日期的本地时钟；已定稿的 assistant *内容*节点（非空 text 块）在正文下追加带 `margin-top: 16px` 的复制／分支／时钟；两边只要挂载就保持可见，并在下一个本地午夜重新格式化。** -两边都通过 `formatMessageClock` 格式化 `node.time`：同一日历日 → `HH:mm`，同年更早 → `M月D日 HH:mm`，跨年 → `YYYY年M月D日 HH:mm`。`useCalendarDay` 是组件本地的日刻度（定时到下一个本地午夜），因此 memo 行在日历日变化时会重渲染，且不新增框架 hook。`MessageItem` 把标签放在复制之前（figma `388:20051`）。`AssistantMarkdown` 把它放在分支之后（figma `43:32997`），且仅在 `streaming` 为 false、已知事件时间、且节点含非空 text 内容时渲染；纯 Think 节点与流式尾部省略该行。复制写入拼接后的 text 块。分支仍是 chrome stub。剪贴板写入与时钟辅助函数放在 `message-chrome.ts`。组装面由 `apps/web/tests/message-actions.e2e.ts`（冷 seed 历史 + aria golden）钉住；aria 归一化把每种时钟形态折叠为 `{{clock}}`。 +两边都通过 `formatMessageClock` 格式化 `node.time`：同一日历日 → `HH:mm`，同年更早 → `M月D日 HH:mm`，跨年 → `YYYY年M月D日 HH:mm`。`useCalendarDay` 是组件本地的日刻度（定时到下一个本地午夜），因此 memo 行在日历日变化时会重渲染，且不新增框架 hook。`MessageItem` 把标签放在复制之前（figma `388:20051`）。`AssistantMarkdown` 把它放在分支之后（figma `43:32997`），且仅在 `streaming` 为 false、已知事件时间、且节点含非空 text 内容时渲染；纯 Think 节点与流式尾部省略该行。复制写入拼接后的 text 块。两种消息行都把自己的事件 `seq` 交给同一个 fork 回调；真实 mutation 契约由 [Web session fork 操作](2026-07-27-web-session-fork-actions.md)定义。剪贴板写入与时钟辅助函数放在 `message-chrome.ts`。组装面由 `apps/web/tests/message-actions.e2e.ts`（冷 seed 历史 + aria golden）钉住；aria 归一化把每种时钟形态折叠为 `{{clock}}`。 ## 曾考虑的方案 @@ -22,10 +22,10 @@ Web 聊天的用户气泡已有复制／分支／编辑 IconActions，但没有 **在具备 hover 能力的指针上用 hover 才揭示操作行。** 否决：行一旦存在就应保持可发现；用 opacity 隐藏容易漏看，且需要父级 hover 选择器重复挂载门控。 -**把分支接到真实的会话 fork。** 本次否决：与已归档的[用户 IconActions 笔记](../../archived/feature/2026-07-27-user-message-icon-actions.md)同一理由——变更路径尚未规定；按钮只预留设计座位。 +**由 IconActions 决策同时定义 session fork 语义。** 否决：本笔记只拥有消息 chrome、时钟与挂载门控；边界选择、失败行为和切换语义属于独立的 [Web session fork 操作](2026-07-27-web-session-fork-actions.md)，避免展示组件成为 session mutation 的第二正家。 **通过 chat store 或 inject hook 发布日历日。** 否决：日刻度只是展示层本地状态，没有跨入口消费者；组件本地 timeout 符合「行为 hook 可拥有不订阅外部源的状态」这一客户端规则。 ## 后果 -已定稿的 assistant 内容回答在行挂载后立刻暴露复制与事件时钟；纯 Think 节点不带 chrome；分支仍为 stub。用户与 assistant 时钟共用同一套跨天／跨年加宽规则，并在午夜后无需消息变更即可刷新。逐消息分页仍是包 README 中的暂缓 footer 座位。包级测试钉住三种时钟形态、午夜加宽与 assistant 仅内容门控；Web e2e 场景钉住组装后的 IconActions chrome。 +已定稿的 assistant 内容回答在行挂载后立刻暴露复制、分支与事件时钟；纯 Think 节点不带 chrome。用户与 assistant 时钟共用同一套跨天／跨年加宽规则，并在午夜后无需消息变更即可刷新。逐消息分页仍是包 README 中的暂缓 footer 座位。包级测试钉住三种时钟形态、午夜加宽、assistant 仅内容门控，以及 user/assistant 分支按钮各自传递的事件 `seq`；Web e2e 场景钉住组装后的 IconActions chrome。 diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts index 679fdfbc65..9b02c5bc73 100644 --- a/apps/web/tests/message-actions.e2e.ts +++ b/apps/web/tests/message-actions.e2e.ts @@ -89,7 +89,9 @@ describe('web e2e: message IconActions and clocks on settled history', () => { it.skipIf(MODE === 'record')('forks through the settled-message and session-row actions', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-message-fork')) - await page.getByRole('button', { name: '在新对话中分支' }).first().click() + // Exercise the assistant action specifically; package coverage pins the + // user action separately at its own event seq. + await page.getByRole('button', { name: '在新对话中分支' }).last().click() await expect.poll( () => scaffold.ctx.agents.list().find(agent => agent.session.header.parentSession === SessionId(SEED_ID)), { timeout: 15_000 }, @@ -104,7 +106,9 @@ describe('web e2e: message IconActions and clocks on settled history', () => { ).toBe(1) // The row action owns a distinct ui-workspace injection from the message // action above, so exercise both through the loaded app before capture. - const sourceRow = page.locator('[role="treeitem"][aria-expanded="true"]').last() + const sourceRow = page.locator('[role="treeitem"]') + .filter({ has: page.locator('button[aria-label^="Session actions for "]') }) + .last() const rowBox = await sourceRow.boundingBox() if (rowBox === null) throw new Error('fork source row has no layout box') const actionButton = sourceRow.locator('button[aria-label^="Session actions for "]') diff --git a/apps/web/tests/snapshots/message-actions/fork.expected.md b/apps/web/tests/snapshots/message-actions/fork.expected.md index 5255632c3a..8e07129bfd 100644 --- a/apps/web/tests/snapshots/message-actions/fork.expected.md +++ b/apps/web/tests/snapshots/message-actions/fork.expected.md @@ -2,9 +2,6 @@ - treeitem "Ungrouped 3 sessions" [expanded]: - img - text: Ungrouped 3 sessions - - treeitem "Collapse Use the read tool twice 1min" [expanded]: - - button "Collapse": - - img - - text: Use the read tool twice 1min - treeitem "Use the read tool twice now" [selected] - treeitem "Use the read tool twice now" + - treeitem "Use the read tool twice 1min" diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx index 904aeee0d8..7de69083ac 100644 --- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx +++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx @@ -23,6 +23,10 @@ export interface AssistantMarkdownProps { interrupted?: boolean | undefined /** Unix epoch ms for the finalized IconActions clock; omitted while streaming. */ time?: number | undefined + /** Event sequence used as the fork boundary; omitted while streaming. */ + seq?: number | undefined + /** Fork the session through the turn containing this finalized message. */ + onFork?: ((seq: number) => void) | undefined } function firstLine(text: string): string { @@ -60,7 +64,7 @@ function ThinkRow({ text, running }: { text: string; running: boolean }) { } export const AssistantMarkdown = memo(function AssistantMarkdown({ - blocks, streaming, interrupted, time, + blocks, streaming, interrupted, time, seq, onFork, }: AssistantMarkdownProps) { const last = blocks.length - 1 // Tool-call heads render as tool rows in the chat view's grouping pass, so @@ -91,6 +95,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({ text={copyText(blocks)} time={time} clock="end" + onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }} className={css.actions} /> )} diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx index 68b9b71cb8..2941348eb1 100644 --- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx +++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx @@ -377,6 +377,8 @@ export function ChatView({ useSession, useSessions, useStore, renderSlot, sessio streaming={false} interrupted={node.interrupted} time={node.time} + seq={node.seq} + onFork={forkAt} /> ) } diff --git a/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx b/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx index 124371f2da..3075c258a6 100644 --- a/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx +++ b/packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx @@ -1,5 +1,5 @@ // Shared IconActions chrome for user and assistant messages: copy live, -// branch wired through onBranch (stub without it), date-aware clock, +// branch wired through onBranch, date-aware clock, // optional edit stub. import { useCallback } from 'react' @@ -19,7 +19,7 @@ export interface MessageIconActionsProps { clock: 'start' | 'end' /** When true, append the stub edit control (user bubble). */ edit?: boolean | undefined - /** Fork the session at this message; absent leaves the branch control a stub. */ + /** Fork the session at this message. */ onBranch?: (() => void) | undefined /** Parent layout class composed onto the actions row. */ className?: string | undefined diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx index 960f954d61..59025b6b21 100644 --- a/packages/client/ui-conversation/tests/chat-view.spec.tsx +++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx @@ -196,6 +196,16 @@ describe('ChatView', () => { expect(view.getByText('run a')).toBeTruthy() }) + it('forks from both user and finalized assistant message actions at their event seq', () => { + const h = makeHarness({ nodes: [user(1, 'question'), assistant(2, 'answer')] }) + const view = render() + const buttons = view.getAllByRole('button', { name: '在新对话中分支' }) + expect(buttons).toHaveLength(2) + fireEvent.click(buttons[0]!) + fireEvent.click(buttons[1]!) + expect(h.forkAt.mock.calls).toEqual([[1], [2]]) + }) + it('renders assistant Markdown across history, streaming, final, and interrupted states while user text stays literal', () => { const markdown = '# Rendered\n\n- **one**\n- `two`' const h = makeHarness({ nodes: [user(1, markdown), assistant(2, markdown)] }) From 3b370549a1a5d526cdf65a969c45120cb0f7f473 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:16:02 +0800 Subject: [PATCH 52/67] feat(client): increment forked session titles --- ...6-07-27-web-session-fork-actions.i18n.yaml | 4 +- .../2026-07-27-web-session-fork-actions.md | 6 +- .../2026-07-27-web-session-fork-actions.zh.md | 6 +- apps/web/tests/message-actions.e2e.ts | 4 +- .../message-actions/fork.expected.md | 4 +- packages/client/runtime/README.i18n.yaml | 4 +- packages/client/runtime/README.md | 2 +- packages/client/runtime/README.zh.md | 2 +- .../runtime/src/client/contract/sessions.ts | 8 ++- .../runtime/src/client/sessions/service.ts | 47 ++++++++++++-- .../runtime/tests/sessions-service.spec.ts | 65 ++++++++++++++++++- packages/client/test-runtime/src/sessions.ts | 4 +- .../test-runtime/tests/runtime.spec.tsx | 6 +- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../ui-conversation/src/client/apply.ts | 4 +- .../tests/apply-inject.spec.tsx | 7 ++ packages/client/ui-workspace/README.i18n.yaml | 4 +- packages/client/ui-workspace/README.md | 2 +- packages/client/ui-workspace/README.zh.md | 2 +- .../client/ui-workspace/src/client/index.ts | 4 +- .../client/ui-workspace/tests/apply.spec.ts | 18 ++++- 23 files changed, 167 insertions(+), 44 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml index 976dcc1d1d..e4b5cd7778 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md -2026-07-27-web-session-fork-actions.md: 90d2f9a8085cf1f1d2656bb442eee1e4116bb91a -2026-07-27-web-session-fork-actions.zh.md: f0642d17fdb6030dea16ff1440c730c605fec13d +2026-07-27-web-session-fork-actions.md: b5dc7e820de069a68b38ed87c7d29ffbdb4867bc +2026-07-27-web-session-fork-actions.zh.md: 774cd74d69eb02d43ca01c8ec7ba1cf94c24b1dc diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md index 90d2f9a808..b5dc7e820d 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.md @@ -10,7 +10,7 @@ The Session store already provides a fork primitive that creates a child session ## Decision -The Web Session-row menu and message IconActions share the client runtime's `sessions.fork` action. A Session row passes `{ sessionId }`, so it forks at the source session's last completed turn; a user message or settled assistant content message passes `{ sessionId, atSeq: node.seq }`, so it forks at the turn containing that event. On success, the client first adds the child session to its local list and then opens it; on failure, it leaves the source session and current selection unchanged. +The Web Session-row menu and message IconActions share the client runtime's `sessions.fork` action. A Session row passes `{ sessionId, increaseTitle: true }`, so it forks at the source session's last completed turn; a user message or settled assistant content message passes `{ sessionId, atSeq: node.seq, increaseTitle: true }`, so it forks at the turn containing that event. Only the client consumes `increaseTitle`: after adding the child session to its local list, the client increments a trailing `(N)` or `（N）` in the source session's persisted title without changing bracket style, appends ` (1)` to an unnumbered title, and skips the rename when no persisted title exists; the Host fork request still contains only `sessionId` and the optional `atSeq`. The caller opens the child only after the rename succeeds; a fork or rename failure leaves the source session and current selection unchanged, while a child created before a rename failure remains in the list. `forkAt(seq)` touches the session service only in ui-conversation's apply injection layer; message components report only the event `seq`. Session rows likewise initiate the operation only through ui-workspace's injected callback. Neither presentation package owns session mutation state or duplicates the host's boundary evaluation. @@ -28,6 +28,6 @@ Session lineage is not projected into a list hierarchy. WorkSpace mode displays ## Consequences -Users can create forks from Session rows, user messages, or settled assistant content messages; all three entry points ultimately use the same runtime/host operation. Message entry points preserve the exact event boundary, while the list entry point preserves the “latest completed turn” shortcut. Every fork child immediately appears as an ordinary peer row, so the list no longer needs session expansion state, recursive nodes, or twist controls. +Users can create forks from Session rows, user messages, or settled assistant content messages; all three entry points ultimately use the same runtime/host operation. Message entry points preserve the exact event boundary, while the list entry point preserves the “latest completed turn” shortcut. Successive fork titles increment through `(1)`, `(2)`, and so on instead of repeatedly appending `(1)`; titles with fullwidth parentheses retain that style. Every fork child immediately appears as an ordinary peer row, so the list no longer needs session expansion state, recursive nodes, or twist controls. -Fork failures stay silent and preserve the source selection, preventing a derivation action from disrupting the current reading position; this tradeoff also means the UI does not yet expose a failure reason or retry entry point. Package tests separately pin the two message `seq` paths and the peer-list derivation; `apps/web/tests/message-actions.e2e.ts` exercises assistant-message branching and Session-row menu branching through the assembled application. +Fork and child-rename failures stay silent and preserve the source selection, preventing a derivation action from disrupting the current reading position; this tradeoff also means the UI does not yet expose a failure reason or retry entry point. Package tests separately pin the two message `seq` paths, title increments, and the peer-list derivation; `apps/web/tests/message-actions.e2e.ts` exercises assistant-message branching and Session-row menu branching through the assembled application. diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md index f0642d17fd..774cd74d69 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md @@ -10,7 +10,7 @@ Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 We ## Decision -Web 的 session 行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。Session 行传 `{ sessionId }`，因此在源会话最后一个已完成轮次处分支；用户消息与已定稿 assistant 内容消息传 `{ sessionId, atSeq: node.seq }`，因此在包含该事件的轮次处分支。成功后 client 先把子会话纳入本地列表，再打开子会话；失败时保持源会话与当前选择不变。 +Web 的 session 行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。Session 行传 `{ sessionId, increaseTitle: true }`，因此在源会话最后一个已完成轮次处分支；用户消息与已定稿 assistant 内容消息传 `{ sessionId, atSeq: node.seq, increaseTitle: true }`，因此在包含该事件的轮次处分支。`increaseTitle` 只由 client 消费：子会话进入本地列表后，client 把源会话持久化标题尾部的 `(N)` 或 `（N）` 递增并保留括号样式，无编号时追加 ` (1)`，没有持久化标题时不改名；Host fork 请求仍只有 `sessionId` 与可选的 `atSeq`。改名成功后调用方才打开子会话；fork 或改名失败时保持源会话与当前选择不变，改名失败时已创建的子会话仍留在列表中。 `forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触 session 服务，消息组件只回传事件 `seq`。Session 行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。 @@ -28,6 +28,6 @@ Session lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.se ## Consequences -用户可从 session 行、用户消息或已定稿 assistant 内容消息创建分支，三处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新完成轮」快捷语义。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。 +用户可从 session 行、用户消息或已定稿 assistant 内容消息创建分支，三处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新完成轮」快捷语义。连续 fork 的标题按 `(1)`、`(2)` 递增，而不是重复追加 `(1)`；全角括号标题保持全角样式。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。 -Fork 失败保持静默并保留源选择，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。Package tests 分别钉住两种消息 `seq` 与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。 +Fork 与子会话改名失败都保持静默并保留源选择，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。Package tests 分别钉住两种消息 `seq`、标题递增与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。 diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts index 9b02c5bc73..650c089d32 100644 --- a/apps/web/tests/message-actions.e2e.ts +++ b/apps/web/tests/message-actions.e2e.ts @@ -106,9 +106,7 @@ describe('web e2e: message IconActions and clocks on settled history', () => { ).toBe(1) // The row action owns a distinct ui-workspace injection from the message // action above, so exercise both through the loaded app before capture. - const sourceRow = page.locator('[role="treeitem"]') - .filter({ has: page.locator('button[aria-label^="Session actions for "]') }) - .last() + const sourceRow = page.locator('[role="treeitem"][aria-selected="true"]') const rowBox = await sourceRow.boundingBox() if (rowBox === null) throw new Error('fork source row has no layout box') const actionButton = sourceRow.locator('button[aria-label^="Session actions for "]') diff --git a/apps/web/tests/snapshots/message-actions/fork.expected.md b/apps/web/tests/snapshots/message-actions/fork.expected.md index 8e07129bfd..d20754711d 100644 --- a/apps/web/tests/snapshots/message-actions/fork.expected.md +++ b/apps/web/tests/snapshots/message-actions/fork.expected.md @@ -2,6 +2,6 @@ - treeitem "Ungrouped 3 sessions" [expanded]: - img - text: Ungrouped 3 sessions - - treeitem "Use the read tool twice now" [selected] - - treeitem "Use the read tool twice now" + - treeitem "Use the read tool twice (2) now" [selected] + - treeitem "Use the read tool twice (1) now" - treeitem "Use the read tool twice 1min" diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml index 4ef6fd488c..e82da5cc62 100644 --- a/packages/client/runtime/README.i18n.yaml +++ b/packages/client/runtime/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/runtime/README.md -README.md: db6388dccee6e065066cc70e141073d99822ce0f -README.zh.md: e1b6902d0d30972bd613553081e0f0e8d5da2a05 +README.md: b85deeec92fd4da1f342b5536757692f594853a5 +README.zh.md: 2dbb66c56ad5687fb299fe030d0abfe451004a62 diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md index db6388dcce..b85deeec92 100644 --- a/packages/client/runtime/README.md +++ b/packages/client/runtime/README.md @@ -30,7 +30,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and ## Session forking -`ISessions.fork({sessionId, atSeq?})` resolves only after the child summary is locally addressable, carrying source lineage and cwd with `blank: false`; callers choose whether to open it. A `workspace-attach-failed` response still identifies a child already published by the Host, so `SessionManager` reconciles that partial success before `SessionForkError` reaches the caller instead of making a retry create a duplicate child. +`ISessions.fork({sessionId, atSeq?, increaseTitle?})` resolves only after the child summary is locally addressable, carrying source lineage and cwd with `blank: false`; callers choose whether to open it. With `increaseTitle: true`, the client renames the child from the source session's persisted title: a trailing `(N)` or `（N）` is incremented without changing bracket style, while any other title gets ` (1)` appended; the rename is skipped when the source has no persisted title, and a rename failure rejects the promise but leaves the created child in place. This option is not sent in the Host fork request. A `workspace-attach-failed` response still identifies a child already published by the Host, so `SessionManager` reconciles that partial success before `SessionForkError` reaches the caller instead of making a retry create a duplicate child. ## Session model selection diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md index e1b6902d0d..2dbb66c56a 100644 --- a/packages/client/runtime/README.zh.md +++ b/packages/client/runtime/README.zh.md @@ -30,7 +30,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 ## 会话 fork -`ISessions.fork({sessionId, atSeq?})` 只在子会话摘要已能在本地寻址后才完成；该摘要携带源会话的谱系和 cwd，且 `blank: false`，由调用方决定是否打开。即使响应为 `workspace-attach-failed`，其中仍会标识 Host 已发布的子会话，因此 `SessionManager` 会先将这一部分成功对账，再让 `SessionForkError` 到达调用方，避免重试创建重复的子会话。 +`ISessions.fork({sessionId, atSeq?, increaseTitle?})` 只在子会话摘要已能在本地寻址后才完成；该摘要携带源会话的谱系和 cwd，且 `blank: false`，由调用方决定是否打开。`increaseTitle: true` 会在 client 端把源会话的持久化标题改名到子会话：尾部 `(N)` 或 `（N）` 递增并保留括号样式，其余标题追加 ` (1)`；源会话没有持久化标题时跳过改名，改名失败时拒绝 promise 但保留已创建的子会话。该选项不会进入 Host fork 请求。即使响应为 `workspace-attach-failed`，其中仍会标识 Host 已发布的子会话，因此 `SessionManager` 会先将这一部分成功对账，再让 `SessionForkError` 到达调用方，避免重试创建重复的子会话。 ## 会话模型选择 diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts index 1b59c3c27c..280bc602eb 100644 --- a/packages/client/runtime/src/client/contract/sessions.ts +++ b/packages/client/runtime/src/client/contract/sessions.ts @@ -32,12 +32,14 @@ export interface ISessions { /** * Fork a session from a completed-turn prefix of the source; on resolution * the child is in the list store and `open()` can target it. - * @param opts - source session id and the optional event seq anchoring the + * @param opts - source session id, the optional event seq anchoring the * cut (the boundary is the first turn/end at or after it; an in-log - * anchor in an open turn is unavailable rather than clipped backward). + * anchor in an open turn is unavailable rather than clipped backward), + * and whether to increment an inherited durable title before resolving. * @returns the child session id. + * @throws when the fork fails, or when a requested child-title rename fails after creation. */ - fork(opts: { sessionId: SessionId; atSeq?: number }): Promise + fork(opts: { sessionId: SessionId; atSeq?: number; increaseTitle?: boolean }): Promise /** * Register a per-session standard-props provider (hooks become `use` * selector hooks on the render side; props spread verbatim). diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts index 741aba4c24..342fc3b62e 100644 --- a/packages/client/runtime/src/client/sessions/service.ts +++ b/packages/client/runtime/src/client/sessions/service.ts @@ -137,6 +137,24 @@ function displayTitleOf(title: string | undefined, cwd: string | undefined, id: return id } +/** + * Increment a trailing fork number while preserving its half-width or + * full-width parentheses; an unnumbered title starts with ` (1)`. + * @param title - source session's durable title. + * @returns the title assigned to the fork child. + */ +function increasedForkTitle(title: string): string { + const ascii = /^(.*?)\((\d+)\)$/u.exec(title) + if (ascii?.[1] !== undefined && ascii[2] !== undefined) { + return `${ascii[1]}(${BigInt(ascii[2]) + 1n})` + } + const fullWidth = /^(.*?)（(\d+)）$/u.exec(title) + if (fullWidth?.[1] !== undefined && fullWidth[2] !== undefined) { + return `${fullWidth[1]}（${BigInt(fullWidth[2]) + 1n}）` + } + return `${title} (1)` +} + interface ScopeRecord { fiber: Fiber ctx: Context @@ -337,17 +355,36 @@ export class SessionsService implements ISessions { * Fork a session from a completed-turn prefix of the source (same * synchronous-addressability guarantee as {@link SessionsService.create}: * on resolution the child is in the list store and open() can target it). - * @param opts - source session id and the optional event seq anchoring the + * @param opts - source session id, the optional event seq anchoring the * cut (the boundary is the first turn/end at or after it; an in-log - * anchor in an open turn is unavailable rather than clipped backward). + * anchor in an open turn is unavailable rather than clipped backward), + * and whether to increment an inherited durable title before resolving. * @returns the child session id. * @throws {SessionForkError} with the source id. + * @throws {Error} when a requested child-title rename fails after creation. */ - async fork(opts: { sessionId: SessionId; atSeq?: number }): Promise { - const result = await this.manager.fork(opts) + async fork(opts: { + sessionId: SessionId + atSeq?: number + increaseTitle?: boolean + }): Promise { + const sourceTitle = opts.increaseTitle + ? this.list.getSnapshot().byId[opts.sessionId]?.title + : undefined + const result = await this.manager.fork({ + sessionId: opts.sessionId, + ...(opts.atSeq === undefined ? {} : { atSeq: opts.atSeq }), + }) if (!result.ok) throw new SessionForkError(result.error, opts.sessionId) this.projectList() - return result.value.sessionId + const childId = result.value.sessionId + if (sourceTitle !== undefined) { + const child = this.binding(childId)?.session + if (child === undefined) throw new Error(`fork child "${childId}" is not locally addressable`) + const renamed = await child.rename(increasedForkTitle(sourceTitle)) + if (!renamed.ok) throw new Error(`fork child rename failed: ${renamed.error.code}: ${renamed.error.message}`) + } + return childId } /** diff --git a/packages/client/runtime/tests/sessions-service.spec.ts b/packages/client/runtime/tests/sessions-service.spec.ts index 09076bace7..8687f208f0 100644 --- a/packages/client/runtime/tests/sessions-service.spec.ts +++ b/packages/client/runtime/tests/sessions-service.spec.ts @@ -10,7 +10,7 @@ import { Context } from 'cordis' import { afterEach, describe, expect, it, vi } from 'vitest' import type { SessionId } from '@deepseek-ai/dsh-client-connection/client' import { SessionCreateError, SessionsService, scopeOf } from '../src/client/sessions/service.ts' -import { FakeApiClient, deferred, ok } from './fake-api.ts' +import { FakeApiClient, deferred, err, ok } from './fake-api.ts' const sid = (s: string): SessionId => s as SessionId @@ -399,6 +399,69 @@ describe('create', () => { }) }) +describe('fork', () => { + it.each([ + ['Roadmap', 'Roadmap (1)'], + ['Roadmap (1)', 'Roadmap (2)'], + ['计划（1）', '计划（2）'], + ['计划 （9）', '计划 （10）'], + ])('increments the durable title %j after the child is published', async (sourceTitle, childTitle) => { + const b = bench() + b.svc.handleMuxEnvelope({ + rpcId: 'source-title' as never, + payload: { type: 'session/projection', sessionId: sid('source'), key: 'title', value: sourceTitle, seq: 2 } as never, + }) + await feedList(b, [{ id: 'source', cwd: '/work' }]) + b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') })) + b.api.onRename = (payload) => { + const { title } = payload as { title: string } + return Promise.resolve(ok({ title, seq: 3 })) + } + + await expect(b.svc.fork({ + sessionId: sid('source'), atSeq: 7, increaseTitle: true, + })).resolves.toBe('child') + + expect(b.api.callsOf('session.fork')).toEqual([{ sessionId: 'source', atSeq: 7 }]) + expect(b.api.callsOf('session.rename')).toEqual([{ sessionId: 'child', title: childTitle }]) + await Promise.resolve() + expect(b.svc.list.getSnapshot().byId[sid('child')]).toMatchObject({ + title: childTitle, + displayTitle: childTitle, + parentId: 'source', + }) + }) + + it('does not rename without the title policy or a durable source title', async () => { + const b = bench() + await feedList(b, [{ id: 'source', cwd: '/work' }]) + b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') })) + await expect(b.svc.fork({ sessionId: sid('source'), increaseTitle: true })).resolves.toBe('child') + expect(b.api.callsOf('session.rename')).toEqual([]) + + b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child-2') })) + await expect(b.svc.fork({ sessionId: sid('source') })).resolves.toBe('child-2') + expect(b.api.callsOf('session.rename')).toEqual([]) + }) + + it('rejects when child rename fails while keeping the published child addressable', async () => { + const b = bench() + b.svc.handleMuxEnvelope({ + rpcId: 'source-title' as never, + payload: { type: 'session/projection', sessionId: sid('source'), key: 'title', value: 'Roadmap', seq: 2 } as never, + }) + await feedList(b, [{ id: 'source' }]) + b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') })) + b.api.onRename = () => Promise.resolve(err({ + code: 'title-invalid', message: 'rejected', details: { sessionId: sid('child') }, + })) + + await expect(b.svc.fork({ sessionId: sid('source'), increaseTitle: true })) + .rejects.toThrow('fork child rename failed: title-invalid: rejected') + expect(b.svc.binding(sid('child'))).toBeDefined() + }) +}) + describe('scope lifecycle rides the list mirror (entity parity: no client-side pre-birth)', () => { it('a session-added frame births the row (blank) and makes the scope resolvable; removal prunes it', async () => { const b = bench() diff --git a/packages/client/test-runtime/src/sessions.ts b/packages/client/test-runtime/src/sessions.ts index f585772b38..f40f9a14a5 100644 --- a/packages/client/test-runtime/src/sessions.ts +++ b/packages/client/test-runtime/src/sessions.ts @@ -395,10 +395,10 @@ export class TestSessions implements ISessions { /** * Recorded fork stub: no child materializes (benches asserting the full * fork flow drive the production service; this face only proves the call). - * @param opts - source session id and optional cut anchor. + * @param opts - source session id, optional cut anchor, and client title policy. * @returns the source id (no child record is created). */ - fork(opts: { sessionId: SessionId; atSeq?: number }): Promise { + fork(opts: { sessionId: SessionId; atSeq?: number; increaseTitle?: boolean }): Promise { this.calls.push({ method: 'fork', args: [opts] }) return Promise.resolve(opts.sessionId) } diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx index eddc6efe76..62bab2845a 100644 --- a/packages/client/test-runtime/tests/runtime.spec.tsx +++ b/packages/client/test-runtime/tests/runtime.spec.tsx @@ -211,11 +211,13 @@ describe('sessions', () => { runtime.sessions.clear() await runtime.flush() expect(runtime.sessions.list.getSnapshot().current).toBeUndefined() - await expect(runtime.sessions.fork({ sessionId: 's1' as SessionId, atSeq: 7 })).resolves.toBe('s1') + await expect(runtime.sessions.fork({ + sessionId: 's1' as SessionId, atSeq: 7, increaseTitle: true, + })).resolves.toBe('s1') expect(runtime.sessions.calls).toEqual([ { method: 'open', args: ['s1'] }, { method: 'clear', args: [] }, - { method: 'fork', args: [{ sessionId: 's1', atSeq: 7 }] }, + { method: 'fork', args: [{ sessionId: 's1', atSeq: 7, increaseTitle: true }] }, ]) await runtime.dispose() }) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index d5d1dcfbfb..086c63f2ad 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 02834be207e45bb1ff65b75a0c75a884db3be315 -README.zh.md: 84f9d79660207a68305d75ac0e7deaecdedf00d6 +README.md: 95f336b9bce82cbf6daf0fdb016f52de9b13c8d5 +README.zh.md: 948da361400a1207fcc582b3d874ab7fb98f27de diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 02834be207..95f336b9bc 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -38,7 +38,7 @@ None; this package neither assembles nor sends a provider request. - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted. - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly. -- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch forks through the turn containing that message and opens the child, while a fork failure leaves the source selected. +- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under text output only; branch forks through the turn containing that message, increments the inherited title on the client, and then opens the child, while a fork or rename failure leaves the source selected. - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export. - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today. - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 84f9d79660..948da36140 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -38,7 +38,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插 - **统计行的耗时只覆盖窗口内消息流**：LLM（大语言模型）与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。 -- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支会 fork 到包含该消息的轮次末尾并打开子会话，而 fork 失败时源会话保持选中。 +- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在 text 输出下；分支会 fork 到包含该消息的轮次末尾，在 client 端递增继承标题后打开子会话，而 fork 或改名失败时源会话保持选中。 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。 diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts index ca0159ce3d..9c2008f092 100644 --- a/packages/client/ui-conversation/src/client/apply.ts +++ b/packages/client/ui-conversation/src/client/apply.ts @@ -263,10 +263,10 @@ export function apply(ctx: Context): void { }, loadOlder: () => { void scoped.loadOlder() }, forkAt: (seq) => { - sessions.fork({ sessionId, atSeq: seq }) + sessions.fork({ sessionId, atSeq: seq, increaseTitle: true }) .then((childId) => { sessions.open(childId) }) .catch(() => { - // Fork failure keeps the source view untouched (composer-stop posture). + // Fork or child-rename failure keeps the source view untouched. }) }, } diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx index 87ec0dfde7..c9dd4c37f9 100644 --- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx +++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx @@ -122,6 +122,13 @@ describe('conversation slot inject surface', () => { const chatView = b.chatViewSurface(ROOT) chatView.injected.loadOlder() expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1) + chatView.injected.forkAt(17) + await vi.waitFor(() => { + expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] }) + }) + expect(b.runtime.sessions.calls).toContainEqual({ + method: 'fork', args: [{ sessionId: ROOT, atSeq: 17, increaseTitle: true }], + }) await b.runtime.dispose() }) diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml index 1223fcc0f9..a50419efb6 100644 --- a/packages/client/ui-workspace/README.i18n.yaml +++ b/packages/client/ui-workspace/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md -README.md: 2a4e544250756db50b19bc101c19ac79505a3d6c -README.zh.md: 7ae2b0e196a98d1375e9073146bb8119ea8cbe90 +README.md: 860c24b8a25a1e9968261f586c16163579131a1c +README.zh.md: 5a8e88051fc6f4fd46c5f2f6dcdc185eb4559ac6 diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md index 2a4e544250..860c24b8a2 100644 --- a/packages/client/ui-workspace/README.md +++ b/packages/client/ui-workspace/README.md @@ -6,7 +6,7 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration. -The Session row's Fork action forks at the source's last completed turn and opens the child; the source and child always appear as peer rows within a workspace group, with lineage retained only as session data. A failure leaves the current selection unchanged. +The Session row's Fork action forks at the source's last completed turn, increments the inherited persisted title on the client, and then opens the child; a trailing ASCII or fullwidth parenthesized number is incremented in the same style, while an unnumbered title gets ` (1)` appended. The source and child always appear as peer rows within a workspace group, with lineage retained only as session data. A fork or rename failure leaves the current selection unchanged; after a rename failure, the created child remains in the list. Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored. diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md index 7ae2b0e196..5a8e88051f 100644 --- a/packages/client/ui-workspace/README.zh.md +++ b/packages/client/ui-workspace/README.zh.md @@ -6,7 +6,7 @@ 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。 -Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork 并打开子会话；源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。失败不会改变当前选中项。 +Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork，在 client 端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。 diff --git a/packages/client/ui-workspace/src/client/index.ts b/packages/client/ui-workspace/src/client/index.ts index f7ced8016a..79a275eafa 100644 --- a/packages/client/ui-workspace/src/client/index.ts +++ b/packages/client/ui-workspace/src/client/index.ts @@ -60,10 +60,10 @@ export function apply(ctx: ClientContext): void { if (!result.ok) throw new Error(result.error.message) }, forkSession: (sessionId) => { - ctx.sessions.fork({ sessionId }) + ctx.sessions.fork({ sessionId, increaseTitle: true }) .then((childId) => { ctx.sessions.open(childId) }) .catch(() => { - // Fork failure keeps the list untouched (composer-stop posture). + // Fork or child-rename failure keeps the current selection. }) }, renameWorkspace: async (workspaceId, title) => { await ctx.workspaces.rename(workspaceId, title) }, diff --git a/packages/client/ui-workspace/tests/apply.spec.ts b/packages/client/ui-workspace/tests/apply.spec.ts index 817416663e..257f98a1d6 100644 --- a/packages/client/ui-workspace/tests/apply.spec.ts +++ b/packages/client/ui-workspace/tests/apply.spec.ts @@ -19,11 +19,17 @@ async function bench() { const insertSessionBefore = vi.fn(async () => ({})) const open = vi.fn() const clear = vi.fn() + const renameSession = vi.fn(async (title: string) => ({ ok: true, value: { title, seq: 1 } })) + const binding = vi.fn(() => ({ session: { rename: renameSession } })) + const fork = vi.fn(async () => 'forked' as never) ctx.provide('workspaces', { create, startSession, rename, insertSessionBefore, } as never) - ctx.provide('sessions', { open, clear } as never) - return { ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename, insertSessionBefore, open, clear } + ctx.provide('sessions', { open, clear, binding, fork } as never) + return { + ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename, + insertSessionBefore, open, clear, renameSession, binding, fork, + } } type HoleName = 'sidebar.workspaces' | 'conversation.hero.workspace' | 'conversation.empty.workspace' @@ -66,6 +72,14 @@ describe('ui-workspace apply', () => { expect(b.startSession).toHaveBeenLastCalledWith(undefined) browser.open('session' as never) expect(b.open).toHaveBeenCalledWith('session') + await browser.renameSession('session' as never, 'renamed session') + expect(b.binding).toHaveBeenCalledWith('session') + expect(b.renameSession).toHaveBeenCalledWith('renamed session') + browser.forkSession('session' as never) + await vi.waitFor(() => { + expect(b.open).toHaveBeenCalledWith('forked') + }) + expect(b.fork).toHaveBeenCalledWith({ sessionId: 'session', increaseTitle: true }) await browser.renameWorkspace('ws' as never, 'renamed') expect(b.rename).toHaveBeenCalledWith('ws', 'renamed') await browser.insertSessionBefore('ws' as never, 's1' as never, 's2' as never) From 30cda487eafd17ee5ee1d77b294f3e3fd7642e59 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 21:34:15 +0800 Subject: [PATCH 53/67] fix(cli): map @deepseek-ai/dsh-tui/prompt to source in tsconfig paths The tui.cordis.yml entry for @deepseek-ai/dsh-tui/prompt had no tsconfig paths mapping: the @deepseek-ai/dsh-* wildcard substitutes tui/prompt whole into nonexistent candidates, so the tsx source launch fell back to package exports and required built lib/prompt.js. pnpm dsh failed at startup on every clean tree (fresh worktrees) with 'plugin(s) failed to load'. --- tsconfig.base.json | 1 + 1 file changed, 1 insertion(+) diff --git a/tsconfig.base.json b/tsconfig.base.json index 527dc44758..801ed2dc66 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -58,6 +58,7 @@ "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"], "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"], "@deepseek-ai/dsh-commands/brand": ["./packages/ui/commands/src/brand.ts"], + "@deepseek-ai/dsh-tui/prompt": ["./packages/ui/tui/src/prompt.ts"], "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"], "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"], "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"], From 7dff9c3ad093c398f7f918abe866f51579dd79d3 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:38:04 +0800 Subject: [PATCH 54/67] ci: temporarily disable serial reference runners --- .github/workflows/ci.yml | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9ffe59ead9..04d4a54131 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,6 +27,9 @@ env: jobs: + # TEMPORARY: the four serial reference jobs remain defined but cannot run. + # Restore their master-push conditions to re-enable them. + # Three enterprise jobs isolate coverage, static analysis, and the # build-backed consumer tail. The static job publishes its exact build so # consumers do not repeat the longest part of their critical path. @@ -39,8 +42,8 @@ jobs: # three onto the in-house # vm-backup pool and re-running the failed jobs is the entire switch — # see .agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md. The - # in-house pool's readiness is re-proven on every master push by the - # serial-linux-selfhosted standby lane below. + # Normally, the in-house pool's readiness is re-proven on every master push + # by the serial-linux-selfhosted standby lane below. node-24: if: github.event_name == 'pull_request' runs-on: >- @@ -225,8 +228,8 @@ jobs: restore-keys: | ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm- - # Pull requests restore the cache produced by serial-linux on master; - # they do not pay compression and upload on the required path. + # Pull requests restore the cache normally produced by serial-linux on + # master; they do not pay compression and upload on the required path. - uses: actions/cache/restore@v4 if: vars.DSH_CI_FAILOVER != 'selfhosted' || github.event.pull_request.user.login == 'dependabot[bot]' with: @@ -321,8 +324,9 @@ jobs: # The required pull-request Windows signal: the two blocking win32 surfaces # (workspace build, production site) execute with real, checksum-verified # Windows Node under Wine on standard hosted Linux. The master - # serial-windows job below keeps the complete native-kernel inventory — - # including the observational portability gates this lane does not run — + # serial-windows job below normally keeps the complete native-kernel + # inventory — including the observational portability gates this lane does + # not run — # on real windows-2025. This job only provisions runner state (caches, # apt); scripts/wine-windows-gates.sh owns the gate logic and is the same # script the optional local gate `pnpm run check:windows-wine` runs. @@ -427,12 +431,12 @@ jobs: cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" du -sh "$HOME/wine-debs" - # Master pushes run only the serial reference jobs below. - # Each host executes the complete, unsharded primary Node aggregate with one - # gate worker, giving reviewers a simple cross-platform oracle for completeness - # and timing. + # The disabled definitions below normally run on master pushes. When + # enabled, each host executes the complete, unsharded primary Node aggregate + # with one gate worker, giving reviewers a simple cross-platform oracle for + # completeness and timing. serial-linux: - if: github.event_name == 'push' && github.ref == 'refs/heads/master' + if: false name: serial / linux runs-on: ubuntu-latest steps: @@ -511,7 +515,7 @@ jobs: # tool caches make them redundant (and saving here would poison the hosted # cache namespace with self-hosted paths). serial-linux-selfhosted: - if: github.event_name == 'push' && github.ref == 'refs/heads/master' + if: false name: serial / linux (self-hosted standby) runs-on: [self-hosted, linux, x64, vm-backup] steps: @@ -557,7 +561,7 @@ jobs: run: pnpm run check:ci:linux-primary serial-macos: - if: github.event_name == 'push' && github.ref == 'refs/heads/master' + if: false name: serial / macos runs-on: macos-latest steps: @@ -584,7 +588,7 @@ jobs: run: pnpm run check:ci serial-windows: - if: github.event_name == 'push' && github.ref == 'refs/heads/master' + if: false name: serial / windows runs-on: windows-2025 steps: From 85d721458a5ffc847c152dc1dfb9c542a2d26e25 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:45:43 +0800 Subject: [PATCH 55/67] ci: keep self-hosted serial standby enabled --- .github/workflows/ci.yml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 04d4a54131..7cf55653f2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,8 +27,8 @@ env: jobs: - # TEMPORARY: the four serial reference jobs remain defined but cannot run. - # Restore their master-push conditions to re-enable them. + # FIXME: Re-enable the three hosted serial reference jobs before cutting a release. + # The self-hosted standby remains active on every master push. # Three enterprise jobs isolate coverage, static analysis, and the # build-backed consumer tail. The static job publishes its exact build so @@ -42,8 +42,8 @@ jobs: # three onto the in-house # vm-backup pool and re-running the failed jobs is the entire switch — # see .agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md. The - # Normally, the in-house pool's readiness is re-proven on every master push - # by the serial-linux-selfhosted standby lane below. + # in-house pool's readiness is re-proven on every master push by the + # serial-linux-selfhosted standby lane below. node-24: if: github.event_name == 'pull_request' runs-on: >- @@ -431,10 +431,10 @@ jobs: cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" du -sh "$HOME/wine-debs" - # The disabled definitions below normally run on master pushes. When - # enabled, each host executes the complete, unsharded primary Node aggregate - # with one gate worker, giving reviewers a simple cross-platform oracle for - # completeness and timing. + # The hosted reference jobs below are temporarily disabled; the self-hosted + # standby remains active. Each enabled host executes the complete, unsharded + # primary Node aggregate with one gate worker, giving reviewers a simple + # cross-platform oracle for completeness and timing. serial-linux: if: false name: serial / linux @@ -515,7 +515,7 @@ jobs: # tool caches make them redundant (and saving here would poison the hosted # cache namespace with self-hosted paths). serial-linux-selfhosted: - if: false + if: github.event_name == 'push' && github.ref == 'refs/heads/master' name: serial / linux (self-hosted standby) runs-on: [self-hosted, linux, x64, vm-backup] steps: From 37116d0b0adae58e7e6a5b279e8004e9eb7d81a5 Mon Sep 17 00:00:00 2001 From: Turtle Date: Thu, 30 Jul 2026 21:34:23 +0800 Subject: [PATCH 56/67] test(scripts): gate source-plane resolution of configured plugins verify-cordis-config now requires every configured specifier of a local workspace package to resolve through the tsconfig.base.json paths facade to a .ts/.tsx source file. A failed resolution or a .d.ts hit (the exports fallback into built lib/types) fails the gate, so a missing paths mapping is a red gate instead of a clean-tree-only startup crash masked by built trees in CI. Removing the dsh-tui/prompt mapping reproduces the failure. Agent Note records the decision and alternatives. --- ...fig-source-plane-resolution-gate.i18n.yaml | 6 +++ ...dis-config-source-plane-resolution-gate.md | 27 ++++++++++ ...-config-source-plane-resolution-gate.zh.md | 27 ++++++++++ scripts/verify-cordis-config.ts | 52 +++++++++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 .agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.i18n.yaml create mode 100644 .agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.md create mode 100644 .agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.zh.md diff --git a/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.i18n.yaml new file mode 100644 index 0000000000..9b7308098b --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.md +2026-07-30-cordis-config-source-plane-resolution-gate.md: f9070d39559948ef27f96df5afccd7c4e076f131 +2026-07-30-cordis-config-source-plane-resolution-gate.zh.md: fac6c4047d334d7dd0685aa270234fee3d15dba8 diff --git a/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.md b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.md new file mode 100644 index 0000000000..f9070d3955 --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.md @@ -0,0 +1,27 @@ +# Agent Note: verify-cordis-config gates source-plane resolution of configured plugins + +Status: implemented + +English | [中文](2026-07-30-cordis-config-source-plane-resolution-gate.zh.md) + +## Problem + +`apps/cli/config/tui.cordis.yml` gained the `@deepseek-ai/dsh-tui/prompt` entry without a matching tsconfig `paths` mapping. The generic `@deepseek-ai/dsh-*` wildcard substitutes `tui/prompt` whole into its `/*/src` candidates, none of which exist, so the [tsx source launch](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md) fell back to package `exports` and resolved `lib/prompt.js` — an artifact-plane file. Every environment with a built `lib/` (developer trees after `pnpm build`) booted fine, and the e2e workflow runs the keyless TUI PTY smoke in `lib` mode (`DSH_EXAMPLE_MODE=lib`, built bin under plain Node) so CI never exercises the source vector at all — while every clean checkout failed `pnpm dsh` at startup with `plugin(s) failed to load: @deepseek-ai/dsh-tui/prompt`. No gate checked the source plane, so the breakage shipped silently and surfaced only in fresh worktrees. + +## Decision + +`scripts/verify-cordis-config.ts` (`validateSourcePlaneResolution`) requires every configured specifier of a local workspace package — harness packages and vendored Cordis alike — to resolve through the `tsconfig.base.json` `paths` facade to a `.ts`/`.tsx` source file, using `ts.resolveModuleName` from the repository root. A failed resolution or a `.d.ts` hit (the `exports` fallback into built `lib/types`) fails `verify-cordis-config`, naming the config files and the specifier. The missing `@deepseek-ai/dsh-tui/prompt` mapping is added next to the other explicit subpath entries; removing it reproduces the gate failure. + +## Alternatives considered + +**Rely on the keyless TUI PTY smoke.** In default source mode it boots the real tree through the source vector and does catch the failure — but only on a clean tree. CI's e2e workflow runs it exclusively in `lib` mode (the built bin resolving real package `exports`), so no CI line runs the source vector, and developer trees with a stale `lib/` stay masked locally. Adding a source-mode CI smoke proves one composition per run; the static gate covers every shipped and example config. + +**Broaden the `dsh-source-launch-smoke` compat test to full boot.** The node-compat smoke asserts only the TTY refusal, which happens before plugin loading. A full keyless boot per matrix line duplicates the PTY smoke at higher cost and, like it, proves one composition rather than every shipped and example config. + +**A `@deepseek-ai/dsh-*/prompt`-style wildcard mapping.** Fixes this one subpath but not the class; the next single-file subpath export (`/surface`, `/message`, …) regresses identically. The static gate covers all current and future configured specifiers. + +## Consequences + +- A configured workspace specifier that resolves only through built `lib/` is now a red `verify-cordis-config` (in `hygiene` and CI) instead of a clean-tree-only startup crash. +- New single-file subpath exports referenced from a cordis.yml need an explicit `tsconfig.base.json` `paths` entry at introduction time; the gate message says so. +- The gate resolves with `tsconfig.base.json` options only; a specifier needing client-only compiler options to resolve would fail it, which matches the facade's role as the single resolution surface for tsx and vitest. diff --git a/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.zh.md b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.zh.md new file mode 100644 index 0000000000..fac6c4047d --- /dev/null +++ b/.agents/notes/implemented/process/2026-07-30-cordis-config-source-plane-resolution-gate.zh.md @@ -0,0 +1,27 @@ +# Agent Note: verify-cordis-config 对配置中插件的源码面解析实施门禁 + +Status: implemented + +[English](2026-07-30-cordis-config-source-plane-resolution-gate.md) | 中文 + +## 问题 + +`apps/cli/config/tui.cordis.yml` 新增了 `@deepseek-ai/dsh-tui/prompt` 配置项，却没有对应的 tsconfig `paths` 映射。通用的 `@deepseek-ai/dsh-*` 通配符会把 `tui/prompt` 整体代入其 `/*/src` 候选路径，而这些路径全都不存在，因此 [tsx 源码启动](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)会回退到包（package）的 `exports`，解析出产物面文件 `lib/prompt.js`。任何带有已构建 `lib/` 的环境（开发者目录树运行 `pnpm build` 后）都能正常启动，而 e2e 工作流以 `lib` 模式（`DSH_EXAMPLE_MODE=lib`，构建产物 bin 在普通 Node 下运行）执行无密钥 TUI PTY 冒烟测试，因此 CI 根本不会经过源码启动向量——与此同时，所有干净检出环境中的 `pnpm dsh` 都会在启动时失败，并报错 `plugin(s) failed to load: @deepseek-ai/dsh-tui/prompt`。当时没有门禁检查源码面，因此该故障未被发现便进入发布版本，仅在新的 worktree 中暴露。 + +## 决策 + +`scripts/verify-cordis-config.ts`（`validateSourcePlaneResolution`）要求配置中凡是引用本地 workspace 包的模块说明符（包括 harness 包与纳入 vendor 的 Cordis）都必须通过 `tsconfig.base.json` 的 `paths` 外观层（facade）解析到 `.ts`/`.tsx` 源文件；解析以仓库根目录为起点，调用 `ts.resolveModuleName` 完成。解析失败或命中 `.d.ts`（即经 `exports` 回退到构建出的 `lib/types`）都会使 `verify-cordis-config` 失败，并列出配置文件与模块说明符。缺失的 `@deepseek-ai/dsh-tui/prompt` 映射已添加在其他显式子路径条目旁；删除该映射即可复现门禁失败。 + +## 备选方案 + +**依赖无密钥 TUI PTY 冒烟测试。** 在默认源码模式下，该测试通过源码向量启动真实目录树，确实能捕获这个故障，但仅限干净目录树。CI 的 e2e 工作流只以 `lib` 模式运行它（构建产物 bin 通过真实的包 `exports` 解析），因此没有任何 CI 环节执行源码向量，而带有过期 `lib/` 的开发者目录树在本地也仍被掩盖。为 CI 增加一个源码模式冒烟测试，每次也只能证明一种组合；静态门禁则覆盖所有随产品发布的配置与示例配置。 + +**将 `dsh-source-launch-smoke` 兼容性测试扩展为完整启动。** node-compat 冒烟测试只断言 TTY 拒绝，而该拒绝发生在插件加载之前。每条矩阵版本线都执行一次完整的无密钥启动，会以更高成本重复 PTY 冒烟测试，而且同样只能验证一种组合，无法覆盖所有随产品发布的配置与示例配置。 + +**使用类似 `@deepseek-ai/dsh-*/prompt` 的通配符映射。** 这能修复当前子路径，却不能杜绝这一类问题；下一个单文件子路径导出（`/surface`、`/message` 等）仍会以同样方式复发。静态门禁覆盖当前及未来配置中引用的所有模块说明符。 + +## 结果 + +- 配置中的 workspace 模块说明符若只能通过构建后的 `lib/` 解析，现在会导致 `verify-cordis-config` 门禁失败（在 `hygiene` 和 CI 中执行），而不再成为只在干净目录树中出现的启动崩溃。 +- cordis.yml 中引用新的单文件子路径导出时，必须同步为 `tsconfig.base.json` 添加显式 `paths` 条目；门禁消息会明确提示这一要求。 +- 门禁只使用 `tsconfig.base.json` 的选项执行解析；如果某个模块说明符需要仅客户端可用的编译器选项才能解析，门禁就会失败。这符合该外观层作为 tsx 与 vitest 唯一解析入口的定位。 diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts index 1e0127a826..bda0d5ecfc 100644 --- a/scripts/verify-cordis-config.ts +++ b/scripts/verify-cordis-config.ts @@ -60,6 +60,7 @@ for (const file of files) { errors.push(...validateExampleResolution()) errors.push(...validateAppResolution()) +errors.push(...validateSourcePlaneResolution()) if (errors.length > 0) { console.error('verify-cordis-config: invalid Loader metadata or plugin package resolution:') @@ -138,6 +139,57 @@ function validateAppResolution(): string[] { return missingPluginDependencies(references, dependencies, 'apps/cli/package.json') } +/** + * Every configured specifier of a local workspace package must resolve through + * the tsconfig `paths` facade to a `.ts`/`.tsx` source file. The `dsh` source + * launch (tsx) and vitest resolve in the source plane; without a `paths` match + * they fall back to package `exports`, which reach built `lib/` — present on a + * built dev tree, absent on a clean one — so a missing mapping boots locally + * yet breaks every clean checkout. Anything but a `.ts`/`.tsx` hit (a `.d.ts` + * or `.js` under built `lib/`) is that artifact-plane fallback, not source. + */ +function validateSourcePlaneResolution(): string[] { + const violations: string[] = [] + const localPackages = localPackageDirectories() + const config = ts.readConfigFile(resolve(root, 'tsconfig.base.json'), path => ts.sys.readFile(path)) + if (config.error !== undefined) { + throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n')) + } + const { options, errors: optionErrors } = ts.convertCompilerOptionsFromJson( + (config.config as { compilerOptions?: unknown }).compilerOptions, + root, + 'tsconfig.base.json', + ) + if (optionErrors.length > 0) { + throw new Error(optionErrors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n')) + } + // convertCompilerOptionsFromJson leaves `pathsBasePath` unset, so relative + // `paths` targets resolve against the host's current directory; anchor it to + // the repository root to keep the gate cwd-independent. + const host: ts.ModuleResolutionHost = { + fileExists: path => ts.sys.fileExists(path), + readFile: path => ts.sys.readFile(path), + directoryExists: path => ts.sys.directoryExists(path), + getCurrentDirectory: () => root, + } + const sourceExtensions = new Set([ts.Extension.Ts, ts.Extension.Tsx]) + const containingFile = resolve(root, 'scripts/verify-cordis-config.ts') + const locationsBySpecifier = new Map>() + for (const reference of pluginReferences) { + const packageName = packageNameFromSpecifier(reference.name) + if (packageName === undefined || !localPackages.has(packageName)) continue + const locations = locationsBySpecifier.get(reference.name) ?? new Set() + locations.add(reference.file) + locationsBySpecifier.set(reference.name, locations) + } + for (const [specifier, locations] of locationsBySpecifier) { + const resolved = ts.resolveModuleName(specifier, containingFile, options, host).resolvedModule + if (resolved !== undefined && sourceExtensions.has(resolved.extension)) continue + violations.push(`${[...locations].join(', ')}: ${specifier} does not resolve to workspace source through tsconfig.base.json paths (add a mapping so the tsx source launch does not depend on built lib/)`) + } + return violations +} + function missingPluginDependencies( references: readonly PluginReference[], dependencies: Readonly>, From 98f6552e219b32125e27b9c7683c049340693c69 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 20:24:58 +0800 Subject: [PATCH 57/67] Revert "ci: reduce coverage cocurrency" This reverts commit ab30aca5cb859aea4bd0fffc88414270d1761f7d. --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d6a94d11f..d1440bd88b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,8 +110,8 @@ jobs: # across six always-on runner instances, and the timing-sensitive # process suites have documented aggregate-contention failures. # 8 × 6 instances = 48 workers worst case on 64 cores. - DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '8' }} - DSH_GATE_CONCURRENCY: '3' + DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '24' }} + DSH_GATE_CONCURRENCY: '8' NODE_OPTIONS: '--max-old-space-size=8192' steps: - uses: actions/checkout@v6 From e35e2a9f3ead2cc3b9e3aa2fcd1a15e8c668dad2 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:07:22 +0800 Subject: [PATCH 58/67] perf: tsc --- packages/typert/generator/src/analyzer.ts | 27 +++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts index 1f545d9673..e0e04a4fa1 100644 --- a/packages/typert/generator/src/analyzer.ts +++ b/packages/typert/generator/src/analyzer.ts @@ -131,6 +131,26 @@ interface FaceProgramHost { readonly files: Map } +/** + * Process-wide parse cache for the bundled TypeScript default libraries. + * `typescript/lib/lib.*.d.ts` content is immutable for the process lifetime, + * so parses are shared across every {@link WorkspaceCaches} instance; the key + * carries the parse-affecting settings, keeping reuse exact. + */ +const defaultLibraryParses = new Map() + +function defaultLibraryKey(fileName: string, languageVersionOrOptions: ts.ScriptTarget | ts.CreateSourceFileOptions): string { + const options = typeof languageVersionOrOptions === 'object' + ? languageVersionOrOptions + : { languageVersion: languageVersionOrOptions } + return [ + fileName, + String(options.languageVersion), + String(options.impliedNodeFormat ?? ''), + String(options.jsDocParsingMode ?? ''), + ].join('\0') +} + /** * Shared memo over one immutable workspace snapshot. Passing one instance to * several analyzers (the batched and write-mode children reuse their parent's @@ -185,6 +205,13 @@ export class WorkspaceCaches { // only fires under oldProgram reuse, which these fresh programs never // request, and invalidate() is the one supported re-read path. host.getSourceFile = (fileName, languageVersionOrOptions, onError) => { + if (isStandardLibraryFile(fileName)) { + const key = defaultLibraryKey(fileName, languageVersionOrOptions) + if (!defaultLibraryParses.has(key)) { + defaultLibraryParses.set(key, base(fileName, languageVersionOrOptions, onError)) + } + return defaultLibraryParses.get(key) + } if (!files.has(fileName)) files.set(fileName, base(fileName, languageVersionOrOptions, onError)) return files.get(fileName) } From be0216102a145729543b872e6da91c5bbfab7d69 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:17:11 +0800 Subject: [PATCH 59/67] Reapply "ci: reduce coverage cocurrency" This reverts commit a471ba79e30e6148e8c433b83fe0d7ee14a8312b. --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d1440bd88b..6d6a94d11f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,8 +110,8 @@ jobs: # across six always-on runner instances, and the timing-sensitive # process suites have documented aggregate-contention failures. # 8 × 6 instances = 48 workers worst case on 64 cores. - DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '24' }} - DSH_GATE_CONCURRENCY: '8' + DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '8' }} + DSH_GATE_CONCURRENCY: '3' NODE_OPTIONS: '--max-old-space-size=8192' steps: - uses: actions/checkout@v6 From 56a8db2777ce002ead70f6f35d80cde9ccdbe60a Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:31:27 +0800 Subject: [PATCH 60/67] ci: use 16c 16c --- .github/workflows/ci.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d6a94d11f..1e999becdc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,7 +50,7 @@ jobs: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && fromJSON('["self-hosted", "linux", "x64", "vm-backup"]') - || 'dsh-enterprise-ubuntu-latest-32core-test' }} + || 'dsh-ubuntu-24-04-16core' }} name: node 24 / static env: DSH_GATE_CONCURRENCY: '8' @@ -102,7 +102,7 @@ jobs: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && fromJSON('["self-hosted", "linux", "x64", "vm-backup"]') - || 'dsh-enterprise-ubuntu-24-04-32core-test' }} + || 'dsh-ubuntu-24-04-16core' }} name: node 24 / coverage env: # Failover shrinks the worker bound: the hosted 32-core runner is @@ -167,7 +167,7 @@ jobs: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && fromJSON('["self-hosted", "linux", "x64", "vm-backup"]') - || 'dsh-enterprise-ubuntu-latest-32core-test' }} + || 'dsh-ubuntu-24-04-16core' }} name: node 24 / snapshots and artifacts env: DSH_GATE_CONCURRENCY: '8' From 9e2f6859f7c40b1be7014d7ae881e38d4d81fe9b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:36:46 +0800 Subject: [PATCH 61/67] ci: reduce invariant import --- scripts/test-invariants.spec.ts | 3 +- scripts/test-invariants.ts | 66 ++++++++++++++++++--------------- 2 files changed, 38 insertions(+), 31 deletions(-) diff --git a/scripts/test-invariants.spec.ts b/scripts/test-invariants.spec.ts index 7a4f678be8..0fb6aeb201 100644 --- a/scripts/test-invariants.spec.ts +++ b/scripts/test-invariants.spec.ts @@ -61,7 +61,8 @@ describe('global test invariant host', () => { return () => {} }) const fakeContext = { invariants: { register } } as unknown as Context - for (const [rawPath, companion] of Object.entries(testInvariantCompanions)) { + for (const [rawPath, load] of Object.entries(testInvariantCompanions)) { + const companion = await load() const path = rawPath.replace(/^\.\.\//, '') expect(companion.default, path).toBeUndefined() const unwrapped = loader.unwrapExports(companion) as typeof companion diff --git a/scripts/test-invariants.ts b/scripts/test-invariants.ts index ce9ede2dff..62c0102588 100644 --- a/scripts/test-invariants.ts +++ b/scripts/test-invariants.ts @@ -12,8 +12,8 @@ import InvariantService from '@deepseek-ai/dsh-invariants' declare global { interface ImportMeta { - /** Eager Vite module-glob expansion used by the Vitest setup file. */ - glob(pattern: string, options: { eager: true }): Record + /** Lazy Vite module-glob expansion used by the Vitest setup file. */ + glob(pattern: string): Record Promise> } } @@ -25,9 +25,15 @@ export interface TestInvariantCompanion { apply(ctx: Context): Promise<() => void> } -/** Every package companion, discovered eagerly so coverage observes each registration. */ -export const testInvariantCompanions: Readonly> = - import.meta.glob('../packages/*/*/src/invariant.ts', { eager: true }) +/** + * Every package companion as a lazy loader keyed by glob path. Ordinary tests + * load only their owner's module; the exhaustive topology test loads and + * executes all of them, so aggregated coverage still observes every + * registration while per-file setup stops importing 168 companions and their + * transitive package sources. + */ +export const testInvariantCompanions: Readonly Promise>> = + import.meta.glob('../packages/*/*/src/invariant.ts') /** Manual-topology suites whose names cannot follow the focused invariant convention. */ const MANUAL_INVARIANT_TEST_EXCEPTIONS = [ @@ -36,7 +42,6 @@ const MANUAL_INVARIANT_TEST_EXCEPTIONS = [ ] as const interface InvariantHost { - readonly fibers: readonly PluginFiber[] readonly byCallback: ReadonlyMap readonly ready: Promise } @@ -102,39 +107,40 @@ export function testInvariantCompanionPaths(testPath: string): string[] { } function startInvariantHost(root: Context): InvariantHost { - const fibers: PluginFiber[] = [] const byCallback = new Map() - const mount = (plugin: Plugin, config?: unknown): void => { + const mount = (plugin: Plugin, config?: unknown): PluginFiber => { const fiber = originalPlugin.call(root.registry, plugin, config) const callback = root.registry.resolve(plugin) if (callback === undefined) throw new Error('test invariants: companion is not a valid Cordis plugin') - fibers.push(fiber) byCallback.set(callback, fiber) + return fiber } - mount(InvariantService, { enabled: true }) + // The service mounts synchronously so the intercepted registration that + // started this host immediately finds its own fiber in byCallback. + // Companions load and mount inside the ready chain (after the service is + // active, so their startup is directly joinable); every joined root plugin + // awaits ready, so none starts ahead of its package checks. Tests plugging + // a companion directly must await an earlier root plugin first — the + // duplicate-mount failure otherwise is loud (owner name already reserved). + const serviceFiber = mount(InvariantService, { enabled: true }) const testPath = expect.getState().testPath ?? '' const companionPaths = testInvariantCompanionPaths(testPath) - for (const path of companionPaths) { - const companion = testInvariantCompanions[path] - if (companion === undefined) { - throw new Error(`test invariants: selected companion vanished at ${path}`) - } - if (!companion.inject.includes('invariants')) { - throw new Error(`test invariants: ${path} must inject the invariant service`) - } - mount(companion) - } - - const [serviceFiber, ...companionFibers] = fibers - if (serviceFiber === undefined) throw new Error('test invariants: service fiber was not mounted') - // A companion is initially PENDING on the invariant service, and Cordis - // Fiber.await() only joins work already in flight. Wait for the service to - // activate its dependants before joining their startup and failures. - const ready = serviceFiber.await() - .then(() => Promise.all(companionFibers.map(fiber => fiber.await()))) - .then(() => undefined) - const host = { fibers, byCallback, ready } + const ready = serviceFiber.await().then(async () => { + const companionFibers = await Promise.all(companionPaths.map(async (path) => { + const load = testInvariantCompanions[path] + if (load === undefined) { + throw new Error(`test invariants: selected companion vanished at ${path}`) + } + const companion = await load() + if (!companion.inject.includes('invariants')) { + throw new Error(`test invariants: ${path} must inject the invariant service`) + } + return mount(companion) + })) + await Promise.all(companionFibers.map(fiber => fiber.await())) + }) + const host = { byCallback, ready } hosts.set(root, host) return host } From 1a75d60174e474e613baf2fcb49715262518cf1f Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:59:07 +0800 Subject: [PATCH 62/67] ci: vitest forks --- vitest.config.ts | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/vitest.config.ts b/vitest.config.ts index 750bb6ddf2..a0d8b6d58a 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -62,10 +62,12 @@ export default defineConfig({ plugins: [pathsPlugin()], test: { name: 'thread-safe', - // Node 24 has aborted in its CJS lexer from a macOS arm64 worker - // thread. A fork contains that external runtime failure to the test - // process; other hosts retain the lower-overhead thread pool. - pool: process.platform === 'darwin' ? 'forks' : 'threads', + // Node 24 has aborted in its CJS lexer (v8::ToLocalChecked Empty + // MaybeLocal in cjs_lexer::Parse) from worker threads on macOS + // arm64 and later on Linux. A fork contains that external runtime + // failure to the test process; Windows keeps the thread pool, where + // the abort has not reproduced and process spawn is costlier. + pool: process.platform === 'win32' ? 'threads' : 'forks', setupFiles: ['./scripts/test-invariants.ts'], include: testIncludes, exclude: [ From 8cc31127c4c7989e1954b33b7c7433e8fd717d62 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 22:10:43 +0800 Subject: [PATCH 63/67] ci: concurrency 3/6 --- .github/workflows/ci.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1e999becdc..1f6ec52f0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,9 +110,8 @@ jobs: # across six always-on runner instances, and the timing-sensitive # process suites have documented aggregate-contention failures. # 8 × 6 instances = 48 workers worst case on 64 cores. - DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '8' }} + DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '6' }} DSH_GATE_CONCURRENCY: '3' - NODE_OPTIONS: '--max-old-space-size=8192' steps: - uses: actions/checkout@v6 with: From 72220dd821f690bb1d5d1ff4204711a04bf638e5 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 22:17:42 +0800 Subject: [PATCH 64/67] fix(fs-search): drop exhausted glob sample groups Keep only groups with another path in the active round. This bounds skewed sampling by paths visited instead of rescanning every singleton for every late-group item. --- packages/fs/tool-fs-search/src/glob.ts | 28 ++++++++++++------- .../fs/tool-fs-search/tests/tools.spec.ts | 13 +++++++++ 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index c9806b7bd8..97d0d904bb 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -150,27 +150,35 @@ function topLevelSegment(path: string): string { * @returns the page grouped by top-level entry, with the shown/total top-level spread. */ export function sampleAcrossTopLevel(paths: readonly string[], maxItems: number, root = '.'): GlobSample { + type ActiveGroup = { key: string; items: string[]; index: number; current: string } const groups = new Map() + let active: ActiveGroup[] = [] for (const path of paths) { const key = topLevelSegment(relativeToSearchRoot(path, root)) const group = groups.get(key) - if (group === undefined) groups.set(key, [path]) - else group.push(path) + if (group === undefined) { + const items = [path] + groups.set(key, items) + active.push({ key, items, index: 0, current: path }) + } else { + group.push(path) + } } - let rounds = 0 - for (const group of groups.values()) rounds = Math.max(rounds, group.length) const taken = new Map() let count = 0 - for (let round = 0; round < rounds && count < maxItems; round += 1) { - for (const [key, group] of groups) { + while (active.length > 0 && count < maxItems) { + const nextActive: ActiveGroup[] = [] + for (const { key, items, index, current } of active) { if (count >= maxItems) break - const path = group[round] - if (path === undefined) continue count += 1 const bucket = taken.get(key) - if (bucket === undefined) taken.set(key, [path]) - else bucket.push(path) + if (bucket === undefined) taken.set(key, [current]) + else bucket.push(current) + const nextIndex = index + 1 + const nextPath = items[nextIndex] + if (nextPath !== undefined) nextActive.push({ key, items, index: nextIndex, current: nextPath }) } + active = nextActive } return { items: [...taken.values()].flat(), shown: taken.size, total: groups.size } } diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index da273ec2a2..5055db7c9c 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -538,6 +538,19 @@ describe('cross-directory sampling', () => { expect(sampleAcrossTopLevel(paths, 3)).toEqual({ items: ['solo/a', 'many/b', 'many/c'], shown: 2, total: 2 }) }) + it('does not rescan exhausted entries while filling a skewed page', () => { + const singletonCount = 12_500 + const paths = [ + ...Array.from({ length: singletonCount }, (_, index) => `group-${index}/only`), + ...Array.from({ length: singletonCount }, (_, index) => `late/${index}`), + ] + expect(sampleAcrossTopLevel(paths, paths.length - 1)).toMatchObject({ + shown: singletonCount + 1, + total: singletonCount + 1, + items: { length: paths.length - 1 }, + }) + }, 500) + it('reports the entries it could not reach when the page is smaller than the top level', () => { const paths = ['a/1', 'b/1', 'c/1', 'd/1'] expect(sampleAcrossTopLevel(paths, 2)).toEqual({ items: ['a/1', 'b/1'], shown: 2, total: 4 }) From 48b0cb25fd1ad02bcfa63c6246d2b7924c228493 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 22:20:15 +0800 Subject: [PATCH 65/67] fix(fs-search): respect platform path separators Group paths using node:path.sep so POSIX backslashes remain filename characters while Windows continues to treat them as separators. --- .../acp-agent/tests/fixtures/fs-search-bin/rg | 2 ++ .../snapshots/fs-glob-sampling/session.jsonl | 2 +- packages/fs/tool-fs-search/src/glob.ts | 22 ++++++++++++++----- .../fs/tool-fs-search/tests/tools.spec.ts | 20 ++++++++++++++--- 4 files changed, 36 insertions(+), 10 deletions(-) diff --git a/examples/acp-agent/tests/fixtures/fs-search-bin/rg b/examples/acp-agent/tests/fixtures/fs-search-bin/rg index cd5703bbf7..181ad68837 100755 --- a/examples/acp-agent/tests/fixtures/fs-search-bin/rg +++ b/examples/acp-agent/tests/fixtures/fs-search-bin/rg @@ -3,6 +3,8 @@ printf '%s\n' \ 'archive/a.ts' \ 'archive/b.ts' \ 'archive/c.ts' \ + 'old\one' \ + 'old\two' \ 'src/index.ts' \ 'docs/guide.md' \ 'test/spec.ts' diff --git a/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl index 85ef5dfe1a..8579543459 100644 --- a/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl +++ b/examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl @@ -11,7 +11,7 @@ {"type":"assistant/chunk","seq":9,"time":1785218400010,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":10,"time":1785218400011,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"d8c174b5-2f08-49b3-80d5-a69aabefbd7a"},"usage":{"inputTokens":1,"outputTokens":1}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"} {"type":"tool/call","seq":11,"time":1785218400012,"data":{"turn":1,"step":1,"callId":"glob-sampling-call","name":"glob","arguments":"{\"pattern\":\"*\"}"}} -{"type":"tool/result","seq":12,"time":1785218400013,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"glob-sampling-call"},"content":[{"type":"tool-result","toolCallId":"glob-sampling-call","content":[{"type":"text","text":"archive/a.ts\nsrc/index.ts\ndocs/guide.md\ntest/spec.ts\n\n(Showing 4 of 6 paths, sampled across 4 of the 4 top-level entries this pattern matched instead of taken in modification-time order. The complete result could not be saved; narrow pattern or path to see more.)"}],"isError":false}],"role":"user","id":"e9711775-0ea5-4383-a562-76a6b49a4742"}},"sourceEventSeqs":[11],"surfaceOp":"append"} +{"type":"tool/result","seq":12,"time":1785218400013,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"glob-sampling-call"},"content":[{"type":"tool-result","toolCallId":"glob-sampling-call","content":[{"type":"text","text":"archive/a.ts\nold\\one\nold\\two\nsrc/index.ts\n\n(Showing 4 of 8 paths, sampled across 4 of the 6 top-level entries this pattern matched instead of taken in modification-time order. Narrow path to inspect a specific subtree. The complete result could not be saved; narrow pattern or path to see more.)"}],"isError":false}],"role":"user","id":"e9711775-0ea5-4383-a562-76a6b49a4742"}},"sourceEventSeqs":[11],"surfaceOp":"append"} {"type":"step/end","seq":13,"time":1785218400014,"data":{"turn":1,"step":1}} {"type":"step/start","seq":14,"time":1785218400015,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":15,"time":1785218400016,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} diff --git a/packages/fs/tool-fs-search/src/glob.ts b/packages/fs/tool-fs-search/src/glob.ts index 97d0d904bb..d934e76d21 100644 --- a/packages/fs/tool-fs-search/src/glob.ts +++ b/packages/fs/tool-fs-search/src/glob.ts @@ -9,6 +9,7 @@ */ import type { Context } from 'cordis' +import { sep } from 'node:path' import { defineTool } from '@deepseek-ai/dsh-tools' import type { GenericCallView } from '@deepseek-ai/dsh-tools' import type { SpillRef } from '@deepseek-ai/dsh-spill' @@ -112,16 +113,25 @@ export interface GlobSample { /** Remove the displayed search-root prefix before choosing a top-level group. */ function relativeToSearchRoot(path: string, root: string): string { - if (root === '.') return path.replace(/^\.[\\/]/, '') - const trimmedRoot = root.replace(/[\\/]+$/, '') - if (trimmedRoot.length === 0) return path.replace(/^[\\/]+/, '') + if (root === '.') return path.startsWith(`.${sep}`) ? path.slice(2) : path + let rootEnd = root.length + while (rootEnd > 0 && root[rootEnd - 1] === sep) rootEnd -= 1 + const trimmedRoot = root.slice(0, rootEnd) + if (trimmedRoot.length === 0) return stripLeadingSeparators(path) if (path === trimmedRoot) return '' - if (path.startsWith(`${trimmedRoot}/`) || path.startsWith(`${trimmedRoot}\\`)) { + if (path.startsWith(`${trimmedRoot}${sep}`)) { return path.slice(trimmedRoot.length + 1) } return path } +/** Strip only separators recognized by the execution platform. */ +function stripLeadingSeparators(path: string): string { + let start = 0 + while (path[start] === sep) start += 1 + return path.slice(start) +} + /** * The leading path segment of one display path — the top-level entry, relative * to the search root, that the path sits under. A path with no separator is its @@ -131,8 +141,8 @@ function relativeToSearchRoot(path: string, root: string): string { * empty group. */ function topLevelSegment(path: string): string { - const trimmed = path.replace(/^[\\/]+/, '') - const cut = trimmed.search(/[\\/]/) + const trimmed = stripLeadingSeparators(path) + const cut = trimmed.indexOf(sep) return cut === -1 ? trimmed : trimmed.slice(0, cut) } diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 5055db7c9c..a0d3cdf38c 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -12,7 +12,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' -import { join } from 'node:path' +import { join, sep } from 'node:path' import { createUserMessage, CallId } from '@deepseek-ai/dsh-llm' import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecutionToken } from '@deepseek-ai/dsh-tools' @@ -582,14 +582,28 @@ describe('cross-directory sampling', () => { .toEqual({ items: ['./vendor/a.ts', './src/b.ts'], shown: 2, total: 2 }) expect(sampleAcrossTopLevel(['/vendor/a.ts', '/src/b.ts'], 2, '/')) .toEqual({ items: ['/vendor/a.ts', '/src/b.ts'], shown: 2, total: 2 }) - expect(sampleAcrossTopLevel(['C:\\root\\a\\one', 'C:\\root\\b\\two'], 2, 'C:\\root')) - .toEqual({ items: ['C:\\root\\a\\one', 'C:\\root\\b\\two'], shown: 2, total: 2 }) + const rooted = [ + ['root', 'a', 'one'].join(sep), + ['root', 'a', 'two'].join(sep), + ['root', 'b', 'three'].join(sep), + ] + expect(sampleAcrossTopLevel(rooted, 2, 'root')) + .toEqual({ items: [rooted[0], rooted[2]], shown: 2, total: 2 }) expect(sampleAcrossTopLevel(['other/a.ts'], 1, 'src')) .toEqual({ items: ['other/a.ts'], shown: 1, total: 1 }) expect(sampleAcrossTopLevel(['src'], 1, 'src')) .toEqual({ items: ['src'], shown: 1, total: 1 }) }) + it.skipIf(process.platform === 'win32')('treats POSIX backslashes as filename characters', () => { + const paths = ['old\\one', 'old\\two', 'src/a'] + expect(sampleAcrossTopLevel(paths, 2)).toEqual({ + items: ['old\\one', 'old\\two'], + shown: 2, + total: 3, + }) + }) + it('handles more top-level groups than the JavaScript argument limit', () => { const paths = Array.from({ length: 125_000 }, (_, index) => `dir-${index}/file.txt`) expect(sampleAcrossTopLevel(paths, 100)).toMatchObject({ shown: 100, total: 125_000 }) From 78adace0314528f16def3fd4346d89ecb364ded2 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 30 Jul 2026 22:34:37 +0800 Subject: [PATCH 66/67] ci: exclude typert generator from coverage thresholds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Generator correctness stays pinned by its fixture suites and the byte-for-byte catalog reproduction test; per-file coverage put whole-workspace compiler analysis under v8 instrumentation — the coverage lane's longest tail. Widen the existing three-file exclude to the package's src. --- vitest.config.ts | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/vitest.config.ts b/vitest.config.ts index a0d8b6d58a..aa3e2b441b 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -156,9 +156,11 @@ export default defineConfig({ 'packages/client/ui-sidebar/src/client/index.ts', 'packages/client/ui-skill/src/client/index.ts', 'packages/client/ui-workspace/src/client/index.ts', - 'packages/typert/generator/src/analyzer.ts', - 'packages/typert/generator/src/renderer.ts', - 'packages/typert/generator/src/cordis-catalog.ts', + // Typert generator: correctness is pinned by its fixture suites and + // the byte-for-byte catalog reproduction test; per-file coverage + // would put whole-workspace compiler analysis under v8 + // instrumentation — the coverage lane's longest tail. + 'packages/typert/generator/src/*.ts', 'packages/host/apiproxy/src/index.ts', 'packages/host/apiproxy/src/invariant.ts', 'packages/host/apiproxy/src/api-proxy.ts', From 58513ee12665e166af1eeed6ab3f3ea1c46a7b68 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 30 Jul 2026 23:42:54 +0800 Subject: [PATCH 67/67] fix(config): map directory picker auto to source --- tsconfig.base.json | 1 + 1 file changed, 1 insertion(+) diff --git a/tsconfig.base.json b/tsconfig.base.json index f5f5c0a3ba..5a69af958d 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -121,6 +121,7 @@ "@deepseek-ai/dsh-host-apiproxy": ["./packages/host/apiproxy/src"], "@deepseek-ai/dsh-host-directory-picker": ["./packages/host/directory-picker/src"], "@deepseek-ai/dsh-host-directory-picker/*": ["./packages/host/directory-picker/src/*"], + "@deepseek-ai/dsh-host-directory-picker-auto": ["./packages/host/directory-picker-auto/src"], "@deepseek-ai/dsh-host-directory-picker-browse": ["./packages/host/directory-picker-browse/src"], "@deepseek-ai/dsh-host-directory-picker-browse/*": ["./packages/host/directory-picker-browse/src/*"], "@deepseek-ai/dsh-host-directory-picker-native": ["./packages/host/directory-picker-native/src"],