Merge remote-tracking branch 'origin/feat/directory-picker-quiet-navigation' into feat/dir-selector-adaptive-default
# Conflicts: # .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
This commit is contained in:
creatixchu
@@ -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/system-prompt/README.md
|
||||
README.md: 79badba0b84b27c01f25e9c31b5df78c556411ea
|
||||
README.zh.md: fb3ed08bc9ea546033acac3b577980f500ce243d
|
||||
README.md: 23bc0e8177ad2a778df9522e254bfd5e03a9871f
|
||||
README.zh.md: 1fd4febc1c15acda19e7abfca94079b9585c1972
|
||||
|
||||
@@ -8,6 +8,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `includeHarnessIdentity` | `true` | Include the fixed `You are an AI agent powered by the DeepSeek Harness SDK.` order-−100 opener. Set false only when a compatibility deployment owns the complete system prompt. |
|
||||
| `persona` | `''` | The global deployment-persona default: the ONE config-authored prompt fragment, rendered as the order-0 `deployment:persona` section unless an agent-scoped contribution shadows it. A template — complete `{{…}}` groups are interpreted strictly against the registered variables (the shipped loop registers `{{model}}`/`{{cwd}}`), with no escape syntax for literal braces yet. Empty ⇒ the section is dropped at render. |
|
||||
| `toolOrder` | — | Explicit model-facing tool order, as a list of `ToolSchema.name`s with one `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`): listed tools take their listed position, unlisted tools land at the rest entry in lexicographic name order. Absent ⇒ plain lexicographic name order. Applied to the collected tools BEFORE the `system-prompt/assemble` waterfall — like the sections' `order` sort, it canonicalizes what the registry contributed (registration order is a plugin-load artifact), and a waterfall listener that mutates the list owns the determinism of what it emits. Misconfiguration fails loud: a list without exactly one rest entry, or with duplicates, throws at load; a listed name with no registered tool rejects every `assemble()`; a tool provider returning the reserved rest-entry name also rejects. Under the shipped loop the turn fails before any model request. Why a central list and not per-plugin weights: [Explicit model-facing tool order](../../../.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md). |
|
||||
|
||||
@@ -48,7 +49,7 @@ Design rationale: [the prompt-variables Agent Note](../../../.agents/notes/imple
|
||||
|
||||
#### What the model sees
|
||||
|
||||
Every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The final `system-prompt/assemble` waterfall result is authoritative, so an expert listener's changes determine the delivered prompt and tool schemas.
|
||||
By default every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. `includeHarnessIdentity: false` omits only that fixed opener for a deployment that owns the complete compatibility persona. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The final `system-prompt/assemble` waterfall result is authoritative, so an expert listener's changes determine the delivered prompt and tool schemas.
|
||||
|
||||
##### Harness identity
|
||||
|
||||
@@ -58,7 +59,7 @@ You are an AI agent powered by the DeepSeek Harness SDK.
|
||||
|
||||
#### Token effect
|
||||
|
||||
Identity is a fixed per-request cost. Persona and plugin text are repeated per request and scale with their rendered content.
|
||||
Identity is a fixed per-request cost when enabled. Persona and plugin text are repeated per request and scale with their rendered content.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
|
||||
| 键 | 默认值 | 含义 |
|
||||
|---|---|---|
|
||||
| `includeHarnessIdentity` | `true` | 是否包含固定的 `You are an AI agent powered by the DeepSeek Harness SDK.`、顺序为 −100 的开场白。仅当兼容部署拥有完整系统提示词时设为 false。 |
|
||||
| `persona` | `''` | 全局部署 persona 默认值：唯一由配置创作的提示词片段，渲染为顺序为 0 的 `deployment:persona` 段，除非 agent 作用域的贡献将其遮蔽。它是模板，完整的 `{{…}}` 组会严格按已注册变量解释（随附循环注册 `{{model}}`/`{{cwd}}`），目前没有表达字面量花括号的转义语法。为空 ⇒ 渲染时删除该段。 |
|
||||
| `toolOrder` | 无 | 显式的面向模型工具顺序：一个 `ToolSchema.name` 列表，包含一个 `'<unlisted-tools>'` 其余项（`TOOL_ORDER_REST`）。已列工具占据列出的位置；未列工具按名称字典序落在其余项位置。缺席 ⇒ 直接按名称字典序排列。在 `system-prompt/assemble` waterfall（瀑布式事件）之前应用于已收集工具；与段的 `order` 排序一样，它会规范化注册表贡献的内容（注册顺序是插件加载产物），而修改列表的 waterfall 监听器拥有其输出的确定性。配置错误会明确失败：列表没有恰好一个其余项或存在重复项，会在加载时抛出；已列名称没有对应已注册工具，会使每次 `assemble()` 被拒绝；工具提供方返回保留的其余项名称也会被拒绝。在随附循环下，轮次会在任何模型请求前失败。为何采用中心列表而非每插件权重，见[显式面向模型工具顺序](../../../.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md)。 |
|
||||
|
||||
@@ -48,7 +49,7 @@
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
每次组装都从下方 harness 身份开始，然后在严格变量插值后追加已配置 persona 与有序插件段。空段会消失；带作用域的段和变量可以为一个 agent 遮蔽全局项。最终 `system-prompt/assemble` waterfall 结果是权威来源，因此专家监听器的变更决定交付的提示词与工具 schema。
|
||||
默认情况下，每次组装都从下方 harness 身份开始，然后在严格变量插值后追加已配置 persona 与有序插件段。`includeHarnessIdentity: false` 仅为拥有完整兼容 persona 的部署省略这个固定开场白。空段会消失；带作用域的段和变量可以为一个 agent 遮蔽全局项。最终 `system-prompt/assemble` waterfall 结果是权威来源，因此专家监听器的变更决定交付的提示词与工具 schema。
|
||||
|
||||
##### Harness 身份
|
||||
|
||||
@@ -58,7 +59,7 @@ You are an AI agent powered by the DeepSeek Harness SDK.
|
||||
|
||||
#### Token 影响
|
||||
|
||||
身份是每次请求的固定成本。Persona 与插件文本在每次请求中重复，成本随渲染内容增长。
|
||||
启用时，身份是每次请求的固定成本。Persona 与插件文本在每次请求中重复，成本随渲染内容增长。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
|
||||
@@ -145,6 +145,8 @@ function compareToolNames(a: ToolSchema, b: ToolSchema): number {
|
||||
|
||||
/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */
|
||||
export interface Config {
|
||||
/** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
|
||||
includeHarnessIdentity?: boolean
|
||||
/**
|
||||
* Deployment-wide order-0 persona template. A scoped section named
|
||||
* `deployment:persona` shadows it; `{{variable}}` references are strict.
|
||||
@@ -245,6 +247,7 @@ class PromptLayer implements ScopeLayer {
|
||||
/** Registry service for the prompt inputs assembled before each model step. */
|
||||
export class SystemPrompt extends Service {
|
||||
static Config: z<Config> = z.object({
|
||||
includeHarnessIdentity: z.boolean().default(true),
|
||||
persona: z.string().default(''),
|
||||
// Preserve omission because an explicit empty order lacks the rest marker.
|
||||
toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
|
||||
@@ -260,11 +263,13 @@ export class SystemPrompt extends Service {
|
||||
super(ctx, 'systemPrompt')
|
||||
this.toolOrder = validateToolOrder(config.toolOrder)
|
||||
// Keep harness-owned openers independent of the selected loop plugin.
|
||||
this.section({
|
||||
name: 'harness:identity',
|
||||
order: -100,
|
||||
text: 'You are an AI agent powered by the DeepSeek Harness SDK.',
|
||||
})
|
||||
if (config.includeHarnessIdentity ?? true) {
|
||||
this.section({
|
||||
name: 'harness:identity',
|
||||
order: -100,
|
||||
text: 'You are an AI agent powered by the DeepSeek Harness SDK.',
|
||||
})
|
||||
}
|
||||
this.section({
|
||||
name: 'deployment:persona',
|
||||
order: 0,
|
||||
|
||||
@@ -37,6 +37,18 @@ describe('SystemPrompt', () => {
|
||||
expect(renderPrompt(await ctx.systemPrompt.assemble())).toBe(IDENTITY)
|
||||
})
|
||||
|
||||
it('can omit the harness identity for a deployment that owns the complete persona', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SystemPrompt, {
|
||||
includeHarnessIdentity: false,
|
||||
persona: 'You are a helpful software engineer assistant.',
|
||||
})
|
||||
|
||||
const assembly = await ctx.systemPrompt.assemble()
|
||||
expect(assembly.sections.map(section => section.name)).toEqual(['deployment:persona'])
|
||||
expect(renderPrompt(assembly)).toBe('You are a helpful software engineer assistant.')
|
||||
})
|
||||
|
||||
it('tolerates a schema-bypassing direct construction (persona omitted)', async () => {
|
||||
// ctx.plugin validates + defaults the config first; a direct construction
|
||||
// skips the schema, so the ctor's `?? ''` narrowing is what fires.
|
||||
|
||||
@@ -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', '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', 'str_replace_editor', '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) {
|
||||
|
||||
@@ -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/examples/agent-spine-demo/README.md
|
||||
README.md: 359e7153be2f480ba3fea4b06782acdc9f89ebb9
|
||||
README.zh.md: acd8c06940b03e90e368314cd725846a2b92b656
|
||||
README.md: 6bbd99217bcdce0e8a0e8fd22a8d39d0c64224b9
|
||||
README.zh.md: 4a7e7a1b7eced9317f94eeddf2442ded9a3e0e13
|
||||
|
||||
@@ -31,7 +31,7 @@ Read this package for the whole plugin tree and its composition order.
|
||||
@deepseek-ai/dsh-scope/invariant
|
||||
@deepseek-ai/dsh-agent-loop/invariant
|
||||
package-owned relational checks
|
||||
@deepseek-ai/dsh-tool-bash the model-facing bash schema
|
||||
@deepseek-ai/dsh-tool-bash the model-facing bash schema (unless toolBash=false)
|
||||
@deepseek-ai/dsh-workspace-context AGENTS.md/CLAUDE.md workspace context loader
|
||||
@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema
|
||||
@deepseek-ai/dsh-tool-tasks task_output/task_list/task_kill schemas + completion notices
|
||||
@@ -55,11 +55,11 @@ This is the [interface/implementation/consumer seam](../../../.agents/notes/impl
|
||||
|
||||
```ts
|
||||
import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
|
||||
// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
|
||||
// { agents?, maxParallelToolCalls?, includeHarnessIdentity?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
|
||||
// workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
|
||||
```
|
||||
|
||||
The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It always mounts `dsh-llm-retry`, while each leaf adapter owns its nested `retryPolicy`. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
|
||||
The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `includeHarnessIdentity`, `persona`, and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It always mounts `dsh-llm-retry`, while each leaf adapter owns its nested `retryPolicy`. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, set `toolBash: false` when another plugin owns the `bash` tool name, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bundled bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
|
||||
|
||||
For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` keeps the package-owned companions mounted but suppresses the blocked owner. Blocklist matches override allowlist matches; see [`dsh-invariants`](../../support/invariants/README.md) for regex and lifecycle rules.
|
||||
|
||||
@@ -79,5 +79,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **Most of the spine set is fixed in code** — `apply()` always mounts the core services and `tool-bash`; config can omit bundled goals, skills, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
|
||||
- **Most of the spine set is fixed in code** — `apply()` always mounts the core services; config can omit bundled goals, skills, bash, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
|
||||
- **The invariant seam and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
@deepseek-ai/dsh-scope/invariant
|
||||
@deepseek-ai/dsh-agent-loop/invariant
|
||||
package-owned relational checks
|
||||
@deepseek-ai/dsh-tool-bash the model-facing bash schema
|
||||
@deepseek-ai/dsh-tool-bash the model-facing bash schema (unless toolBash=false)
|
||||
@deepseek-ai/dsh-workspace-context AGENTS.md/CLAUDE.md workspace context loader
|
||||
@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema
|
||||
@deepseek-ai/dsh-tool-tasks task_output/task_list/task_kill schemas + completion notices
|
||||
@@ -55,11 +55,11 @@
|
||||
|
||||
```ts
|
||||
import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
|
||||
// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
|
||||
// { agents?, maxParallelToolCalls?, includeHarnessIdentity?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
|
||||
// workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
|
||||
```
|
||||
|
||||
组合包将每个字段转发给拥有它的子节点：`agents` 与 `maxParallelToolCalls` 交给 `agent-loop`（`agents` 默认为 `[]`，上限在该处默认），因此每个应用提供自己的预创建 agent；TUI 和无头应用预创建 `main`，ACP 应用则在 `session/new` 按需创建 agent；`persona` 与 `toolOrder` 交给 `dsh-system-prompt`；`tools` 交给工具注册表以配置呈现模式；`sessionTitle` 交给后备标题服务；`skills.registry`、`skills.local` 与 `skills.tool` 分别交给 skill 注册表、本地提供方和面向模型的消费方；必填的 `workspaceContext` 选择交给 `dsh-workspace-context`（`{ maxBytes }` 启用加载，`false` 禁用）；`invariants` 交给不变式服务；`toolBash`/`toolTasks` 交给组合包拥有的两个面向模型工具插件。组合包始终挂载 `dsh-llm-retry`，而每个叶节点适配器拥有自己的嵌套 `retryPolicy`。省略 `sessionTitle` 时采用显式示例策略：5 个词、40 个后备字节、80 个可接受标题字节。`goals` 对象会选用持久化领域、模型工具和同会话 Goal Round 驱动器，并将 `goals.domain` 与 `goals.tool` 转发给各自拥有者；省略或设为 `false` 会让整个栈缺席，使无头调用方继续以单轮次结算。设置 `skills.enabled: false` 会同时省略本地提供方和面向模型的 skill 工具；设置 `toolTasks: false` 会保留供前台生产方使用的任务服务，但不公开 `task_output`/`task_list`/`task_kill`。它对 `dshHome` 只解析一次，解析通过 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 完成，并将所得绝对值转发给 tool-bash 的托管环境和已启用的本地 skill 发现。顶层 `dshHome` 缺席时采用 `skills.local.dshHome`；两者同时提供但解析后的路径不同会明确失败。`toolBash.enableRunInBackground` 只控制 bash 生产方；独立加载的生产方保留各自配置。工作区指令先于 skill 目录注册，因此其会话前缀消息先渲染。应用包使用 `pickSpineConfig()`，只复制这些由组合包拥有的字段。
|
||||
组合包将每个字段转发给拥有它的子节点：`agents` 与 `maxParallelToolCalls` 交给 `agent-loop`（`agents` 默认为 `[]`，上限在该处默认），因此每个应用提供自己的预创建 agent；TUI 和无头应用预创建 `main`，ACP 应用则在 `session/new` 按需创建 agent；`includeHarnessIdentity`、`persona` 与 `toolOrder` 交给 `dsh-system-prompt`；`tools` 交给工具注册表以配置呈现模式；`sessionTitle` 交给后备标题服务；`skills.registry`、`skills.local` 与 `skills.tool` 分别交给 skill 注册表、本地提供方和面向模型的消费方；必填的 `workspaceContext` 选择交给 `dsh-workspace-context`（`{ maxBytes }` 启用加载，`false` 禁用）；`invariants` 交给不变式服务；`toolBash`/`toolTasks` 交给组合包拥有的两个面向模型工具插件。组合包始终挂载 `dsh-llm-retry`，而每个叶节点适配器拥有自己的嵌套 `retryPolicy`。省略 `sessionTitle` 时采用显式示例策略：5 个词、40 个后备字节、80 个可接受标题字节。`goals` 对象会选用持久化领域、模型工具和同会话 Goal Round 驱动器，并将 `goals.domain` 与 `goals.tool` 转发给各自拥有者；省略或设为 `false` 会让整个栈缺席，使无头调用方继续以单轮次结算。设置 `skills.enabled: false` 会同时省略本地提供方和面向模型的 skill 工具；当另一个插件拥有 `bash` 工具名时设置 `toolBash: false`；设置 `toolTasks: false` 会保留供前台生产方使用的任务服务，但不公开 `task_output`/`task_list`/`task_kill`。它对 `dshHome` 只解析一次，解析通过 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 完成，并将所得绝对值转发给 tool-bash 的托管环境和已启用的本地 skill 发现。顶层 `dshHome` 缺席时采用 `skills.local.dshHome`；两者同时提供但解析后的路径不同会明确失败。`toolBash.enableRunInBackground` 只控制内置 bash 生产方；独立加载的生产方保留各自配置。工作区指令先于 skill 目录注册，因此其会话前缀消息先渲染。应用包使用 `pickSpineConfig()`，只复制这些由组合包拥有的字段。
|
||||
|
||||
例如，`{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` 会让包拥有的配套插件保持挂载，但抑制被阻止的拥有者。Blocklist 匹配优先于 allowlist 匹配；正则表达式与生命周期规则见 [`dsh-invariants`](../../support/invariants/README.md)。
|
||||
|
||||
@@ -79,5 +79,5 @@ YAML include 可以去重配置，却无法拥有 bin 或提供前端入口默
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务与 `tool-bash`；配置可以省略组合包内的目标、skill 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
|
||||
- **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务；配置可以省略组合包内的目标、skill、bash 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
|
||||
- **不变式 seam 与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
|
||||
|
||||
@@ -68,9 +68,9 @@ export interface GoalConfig {
|
||||
/**
|
||||
* Bundle config: each field forwarded verbatim to the child that owns it —
|
||||
* `agents` to the agent loop (an app that pre-creates no agents, like the ACP
|
||||
* bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
|
||||
* plugin (the deployment's persona section and the explicit model-facing tool
|
||||
* order), the `tools` object to the tool registry (its presentation `mode`),
|
||||
* bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
|
||||
* to the system-prompt plugin (the fixed opener, deployment persona, and explicit
|
||||
* model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
|
||||
* `dshHome` to bash environment and local skill discovery, `sessionTitle` to
|
||||
* the fallback title service, `skills` to the
|
||||
* skill registry/local provider/tool consumer, `workspaceContext` to the
|
||||
@@ -83,13 +83,16 @@ export interface GoalConfig {
|
||||
* workspace context instead requires an explicit byte budget or `false` because
|
||||
* it changes model-visible input. Producer opt-in stays producer-local:
|
||||
* `toolBash` configures bash only; independently composed producers keep their
|
||||
* own config.
|
||||
* own config. Set `toolBash: false` when another plugin owns the model-facing
|
||||
* `bash` name.
|
||||
*/
|
||||
export interface Config {
|
||||
/** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
|
||||
agents?: AgentLoopConfig['agents']
|
||||
/** Agent-loop concurrency cap; `1` is serial. */
|
||||
maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
|
||||
/** Whether the system prompt includes the fixed Harness identity (default true). */
|
||||
includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
|
||||
/** The deployment persona (see dsh-system-prompt's `Config`). */
|
||||
persona?: SystemPromptConfig['persona']
|
||||
/** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
|
||||
@@ -102,10 +105,14 @@ export interface Config {
|
||||
sessionTitle?: SessionTitleConfig
|
||||
/** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
|
||||
workspaceContext: workspaceContext.Config | false
|
||||
/** Skill registry, local provider, and model-facing consumer config. */
|
||||
/**
|
||||
* Skill registry, local provider, and model-facing consumer config.
|
||||
* Skills use `enabled` because one nested config controls a provider stack;
|
||||
* single model-tool plugins use `Config | false` to disable that one consumer.
|
||||
*/
|
||||
skills?: SkillConfig
|
||||
/** Model-facing bash tool config, including this producer's background opt-in. */
|
||||
toolBash?: toolBash.Config
|
||||
/** Model-facing bash tool config, or false when another plugin owns `bash`. */
|
||||
toolBash?: toolBash.Config | false
|
||||
/** Generic background-task controls; set false to keep the task service without model-facing task tools. */
|
||||
toolTasks?: toolTasks.Config | false
|
||||
/** Global enablement and package-name filters for invariant companions. */
|
||||
@@ -127,7 +134,8 @@ export const SessionTitleConfigSchema: z<SessionTitleConfig> = SessionTitleServi
|
||||
.default(EXAMPLE_SESSION_TITLE_CONFIG)
|
||||
|
||||
/** The bash-tool config schema exported for app packages that forward `toolBash`. */
|
||||
export const ToolBashConfigSchema: z<toolBash.Config> = toolBash.Config
|
||||
export const ToolBashConfigSchema: z<toolBash.Config | false> =
|
||||
z.union([z.const(false), toolBash.Config])
|
||||
|
||||
/** The task-control-tool config schema exported for app packages that forward `toolTasks`. */
|
||||
export const ToolTasksConfigSchema: z<toolTasks.Config> = toolTasks.Config
|
||||
@@ -163,6 +171,7 @@ export const Config = z.intersect([
|
||||
export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'agents'> {
|
||||
return {
|
||||
...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {},
|
||||
...config.includeHarnessIdentity !== undefined ? { includeHarnessIdentity: config.includeHarnessIdentity } : {},
|
||||
...config.persona !== undefined ? { persona: config.persona } : {},
|
||||
...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
|
||||
...config.tools !== undefined ? { tools: config.tools } : {},
|
||||
@@ -201,6 +210,7 @@ export function apply(ctx: Context, config: Config): void {
|
||||
ctx.plugin(SessionTitleService, config.sessionTitle ?? EXAMPLE_SESSION_TITLE_CONFIG)
|
||||
// Owner schemas resolve defaults; forward toolOrder only when explicitly set.
|
||||
ctx.plugin(SystemPrompt, {
|
||||
includeHarnessIdentity: config.includeHarnessIdentity ?? true,
|
||||
persona: config.persona ?? '',
|
||||
...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
|
||||
})
|
||||
@@ -223,7 +233,9 @@ export function apply(ctx: Context, config: Config): void {
|
||||
ctx.plugin(agentInvariant)
|
||||
ctx.plugin(scopeInvariant)
|
||||
ctx.plugin(agentLoopInvariant)
|
||||
ctx.plugin(toolBash, Object.assign({}, config.toolBash, { dshHome }))
|
||||
if (config.toolBash !== false) {
|
||||
ctx.plugin(toolBash, Object.assign({}, config.toolBash, { dshHome }))
|
||||
}
|
||||
if (config.workspaceContext !== false) {
|
||||
ctx.plugin(workspaceContext, config.workspaceContext)
|
||||
}
|
||||
|
||||
@@ -4,7 +4,7 @@ import { join } from 'node:path'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { Context } from 'cordis'
|
||||
import Loader from '@cordisjs/plugin-loader'
|
||||
import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
|
||||
import { renderPrompt, TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
|
||||
import * as agentCore from '../src/index.ts'
|
||||
import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
|
||||
import { SessionId } from '@deepseek-ai/dsh-session'
|
||||
@@ -654,9 +654,27 @@ describe('dsh-agent-spine-demo bundle', () => {
|
||||
await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
it('can omit the bundled bash tool and Harness identity for a compatibility deployment', async () => {
|
||||
const ctx = await mount({
|
||||
includeHarnessIdentity: false,
|
||||
persona: 'You are a helpful software engineer assistant.',
|
||||
workspaceContext: false,
|
||||
skills: { enabled: false },
|
||||
toolBash: false,
|
||||
toolTasks: false,
|
||||
}, true)
|
||||
|
||||
expect(ctx.tools.schemas()).toEqual([])
|
||||
expect(renderPrompt(await ctx.systemPrompt.assemble()))
|
||||
.toBe('You are a helpful software engineer assistant.')
|
||||
|
||||
await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
it('picks shared spine config without leaking front-door fields', () => {
|
||||
const appConfig = {
|
||||
model: 'front-door-only',
|
||||
includeHarnessIdentity: false,
|
||||
persona: 'You are merged.',
|
||||
toolOrder: ['zulu'],
|
||||
tools: { mode: 'native' as const },
|
||||
@@ -670,6 +688,7 @@ describe('dsh-agent-spine-demo bundle', () => {
|
||||
}
|
||||
|
||||
expect(agentCore.pickSpineConfig(appConfig)).toEqual({
|
||||
includeHarnessIdentity: appConfig.includeHarnessIdentity,
|
||||
persona: appConfig.persona,
|
||||
toolOrder: appConfig.toolOrder,
|
||||
tools: appConfig.tools,
|
||||
|
||||
@@ -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/README.md
|
||||
README.md: 4d954455ea920be4882530bcfe90b48a364c29b5
|
||||
README.zh.md: ed154cbbaf7c7f45c42c17799957254fee918153
|
||||
README.md: b5e0ac9d1c0c550eb372b8a66fc6358711fddc07
|
||||
README.zh.md: ee64a617aa0d9549bcaf00b20821a6d59c6673c8
|
||||
|
||||
@@ -12,6 +12,7 @@ The filesystem stack: a provider seam (text IO + atomic mutation with an optiona
|
||||
| `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
|
||||
| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
|
||||
| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
|
||||
| `tool-str-replace-editor/` | Model-facing `str_replace_editor` with view/create/unique literal replace/line insert operations over `ctx.fs` | (registers on `ctx.tools`) |
|
||||
|
||||
The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
|
||||
|
||||
|
||||
@@ -12,6 +12,7 @@
|
||||
| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
|
||||
| `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升权字段 | （注册到 `ctx.tools`） |
|
||||
| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
|
||||
| `tool-str-replace-editor/` | 基于 `ctx.fs` 提供查看／创建／唯一字面量替换／按行插入的模型可见 `str_replace_editor` | （注册到 `ctx.tools`） |
|
||||
|
||||
接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema；`fs-sandbox` 是第一个这样的替代实现（基于共享沙箱模式的进程内路径围栏；见[跨能力族 fs 沙箱 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它只会使策略失效，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、基于进程的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，其结果便可供后续读取，这也是其 README 所述的共置部署。
|
||||
|
||||
|
||||
6
packages/fs/tool-str-replace-editor/README.i18n.yaml
Normal file
6
packages/fs/tool-str-replace-editor/README.i18n.yaml
Normal file
@@ -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/fs/tool-str-replace-editor/README.md
|
||||
README.md: 97e9e0ab9ade7c7241c1aac3e2489e055d01ff8f
|
||||
README.zh.md: 48358eb3c9d81ddad6a83c4ff3ef0cf6542096b1
|
||||
52
packages/fs/tool-str-replace-editor/README.md
Normal file
52
packages/fs/tool-str-replace-editor/README.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# @deepseek-ai/dsh-tool-str-replace-editor
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Standalone model-facing `str_replace_editor` over `ctx.fs`. It can be composed with persistent Bash, one-shot Bash, sandboxed Bash, or another terminal surface.
|
||||
|
||||
## Config
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---:|---|
|
||||
| `maxOutputChars` | `16000` | Prefix characters retained for file and directory views. |
|
||||
| `description` | Editor command guide | Model-facing tool description. |
|
||||
|
||||
## Tool
|
||||
|
||||
The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
|
||||
|
||||
## Model Experience
|
||||
|
||||
### Tool schema
|
||||
|
||||
#### What the model sees
|
||||
|
||||
The generated [`str_replace_editor` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-str-replace-editor), including the configured `description`. The plugin contributes no standalone system-prompt section.
|
||||
|
||||
#### Token effect
|
||||
|
||||
Fixed schema cost while `str_replace_editor` is visible.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
Prefix-stable while the configured description and schema remain unchanged.
|
||||
|
||||
### Tool results
|
||||
|
||||
#### What the model sees
|
||||
|
||||
Views return numbered text or a shallow directory listing. Calls expose file locations, and create/replace calls expose diff cards to presentation surfaces. Mutations return concise confirmations. Long views keep their prefix and append a clipping notice.
|
||||
|
||||
#### Token effect
|
||||
|
||||
Data-dependent and bounded by `maxOutputChars` plus the fixed clipping notice.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
Append-only tool results follow the reusable request prefix.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- Operations target UTF-8 text; binary files are unsupported.
|
||||
- `str_replace` intentionally rejects zero or multiple matches and has no `replace_all` argument.
|
||||
- Every mutation goes through `fs/write-intent` or `fs/edit-intent`, resolves the current session sandbox policy, and delegates enforcement to the mounted filesystem and policy plugins.
|
||||
52
packages/fs/tool-str-replace-editor/README.zh.md
Normal file
52
packages/fs/tool-str-replace-editor/README.zh.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# @deepseek-ai/dsh-tool-str-replace-editor
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
基于 `ctx.fs` 的独立模型可见 `str_replace_editor`。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端表面组合。
|
||||
|
||||
## 配置
|
||||
|
||||
| 键 | 默认值 | 含义 |
|
||||
|---|---:|---|
|
||||
| `maxOutputChars` | `16000` | 文件和目录查看结果保留的前缀字符数。 |
|
||||
| `description` | 编辑器命令指南 | 面向模型的工具描述。 |
|
||||
|
||||
## 工具
|
||||
|
||||
Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从一开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
|
||||
|
||||
## 模型体验
|
||||
|
||||
### 工具 schema
|
||||
|
||||
#### 模型所见
|
||||
|
||||
生成的 [`str_replace_editor` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-str-replace-editor)，其中包含配置的 `description`。本插件不贡献独立系统提示词段。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
`str_replace_editor` 可见时产生固定的 schema 成本。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
配置的描述与 schema 不变时前缀稳定。
|
||||
|
||||
### 工具结果
|
||||
|
||||
#### 模型所见
|
||||
|
||||
查看操作返回带行号文本或浅层目录列表。调用会向展示层提供文件位置，创建/替换还会提供 diff 卡片。修改操作返回简洁确认。长查看结果保留前缀并追加截断提示。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
随数据变化，并受 `maxOutputChars` 与固定截断提示约束。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
工具结果以追加方式位于可复用请求前缀之后。
|
||||
|
||||
## 已知限制与延后工作
|
||||
|
||||
- 操作面向 UTF-8 文本，不支持二进制文件。
|
||||
- `str_replace` 刻意拒绝零匹配或多匹配，且没有 `replace_all` 参数。
|
||||
- 每个修改操作都会经过 `fs/write-intent` 或 `fs/edit-intent`，解析当前 session 的沙箱策略，并交由挂载的文件系统与策略插件执行。
|
||||
54
packages/fs/tool-str-replace-editor/package.json
Normal file
54
packages/fs/tool-str-replace-editor/package.json
Normal file
@@ -0,0 +1,54 @@
|
||||
{
|
||||
"name": "@deepseek-ai/dsh-tool-str-replace-editor",
|
||||
"description": "Model-facing view, create, literal replace, and line insert tool over the Harness filesystem service",
|
||||
"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"
|
||||
},
|
||||
"./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-fs": "^0.0.1",
|
||||
"@deepseek-ai/dsh-invariants": "^0.0.1",
|
||||
"@deepseek-ai/dsh-sandbox": "^0.0.1",
|
||||
"@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
|
||||
"@deepseek-ai/dsh-tools": "^0.0.1",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
},
|
||||
"dependencies": {
|
||||
"schemastery": "^3.18.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@deepseek-ai/dsh-agent": "workspace:^",
|
||||
"@deepseek-ai/dsh-fs": "workspace:^",
|
||||
"@deepseek-ai/dsh-fs-local": "workspace:^",
|
||||
"@deepseek-ai/dsh-fs-policy": "workspace:^",
|
||||
"@deepseek-ai/dsh-fs-sandbox": "workspace:^",
|
||||
"@deepseek-ai/dsh-invariants": "workspace:^",
|
||||
"@deepseek-ai/dsh-llm": "workspace:^",
|
||||
"@deepseek-ai/dsh-sandbox": "workspace:^",
|
||||
"@deepseek-ai/dsh-sandbox-policy": "workspace:^",
|
||||
"@deepseek-ai/dsh-session": "workspace:^",
|
||||
"@deepseek-ai/dsh-system-prompt": "workspace:^",
|
||||
"@deepseek-ai/dsh-tools": "workspace:^",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
}
|
||||
}
|
||||
522
packages/fs/tool-str-replace-editor/src/index.ts
Normal file
522
packages/fs/tool-str-replace-editor/src/index.ts
Normal file
@@ -0,0 +1,522 @@
|
||||
/**
|
||||
* Model-facing `str_replace_editor` over the Harness filesystem seam.
|
||||
* @module @deepseek-ai/dsh-tool-str-replace-editor
|
||||
*/
|
||||
|
||||
import { isAbsolute } from 'node:path'
|
||||
import type { Context } from 'cordis'
|
||||
import z from 'schemastery'
|
||||
import { FsError } from '@deepseek-ai/dsh-fs'
|
||||
import type { FsInfo, FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs'
|
||||
import { sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
|
||||
import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
|
||||
import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
import type { ToolCallView, ToolRunContext } from '@deepseek-ai/dsh-tools'
|
||||
|
||||
const TRUNCATED_MESSAGE = '<response clipped><NOTE>To save on context only part of this file has been shown to you. You should retry this tool after you have searched inside the file with `grep -n` in order to find the line numbers of what you are looking for.</NOTE>'
|
||||
|
||||
const DEFAULT_DESCRIPTION = `
|
||||
Custom editing tool for viewing, creating and editing files
|
||||
* State is persistent across command calls and discussions with the user
|
||||
* If \`path\` is a file, \`view\` displays the result of applying \`cat -n\`. If \`path\` is a directory, \`view\` lists non-hidden files and directories up to 2 levels deep
|
||||
* The \`create\` command cannot be used if the specified \`path\` already exists as a file
|
||||
* If a \`command\` generates a long output, it will be truncated and marked with \`<response clipped>\`
|
||||
|
||||
Notes for using the \`str_replace\` command:
|
||||
* The \`old_str\` parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!
|
||||
* If the \`old_str\` parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in \`old_str\` to make it unique
|
||||
* The \`new_str\` parameter should contain the edited lines that should replace the \`old_str\`
|
||||
`.trim()
|
||||
|
||||
function maybeTruncate(content: string, maxOutputChars: number): string {
|
||||
return content.length <= maxOutputChars
|
||||
? content
|
||||
: content.slice(0, maxOutputChars) + TRUNCATED_MESSAGE
|
||||
}
|
||||
|
||||
function codepointCompare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0
|
||||
}
|
||||
|
||||
function matchOffsets(content: string, search: string): number[] {
|
||||
const offsets: number[] = []
|
||||
let offset = 0
|
||||
while (true) {
|
||||
const match = content.indexOf(search, offset)
|
||||
if (match < 0) return offsets
|
||||
offsets.push(match)
|
||||
offset = match + search.length
|
||||
}
|
||||
}
|
||||
|
||||
function lineNumbersAt(content: string, offsets: readonly number[]): number[] {
|
||||
let line = 1
|
||||
let cursor = 0
|
||||
return offsets.map((offset) => {
|
||||
while (cursor < offset) {
|
||||
if (content[cursor] === '\n') line += 1
|
||||
cursor += 1
|
||||
}
|
||||
return line
|
||||
})
|
||||
}
|
||||
|
||||
class MutationPolicy {
|
||||
private readonly policy: SandboxPolicyService | undefined
|
||||
|
||||
constructor(ctx: Context) {
|
||||
this.policy = ctx.fs.sandboxMode === undefined ? undefined : ctx.get('sandboxPolicy')
|
||||
if (ctx.fs.sandboxMode !== undefined && this.policy === undefined) {
|
||||
throw new Error('tool-str-replace-editor: the mounted filesystem confines but ctx.sandboxPolicy is missing')
|
||||
}
|
||||
}
|
||||
|
||||
resolve(exec: ToolRunContext): SandboxExecutionPolicy | undefined {
|
||||
return this.policy?.resolve({
|
||||
...exec.agent === undefined ? {} : { session: exec.agent.session },
|
||||
})
|
||||
}
|
||||
|
||||
mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown {
|
||||
if (!(error instanceof FsError) || error.code !== 'FS_SANDBOX_DENIED') return error
|
||||
const mode = (policy as SandboxExecutionPolicy).mode
|
||||
return new FsError(sandboxDenialMarker(mode), 'FS_SANDBOX_DENIED', { cause: error })
|
||||
}
|
||||
}
|
||||
|
||||
async function resolveTarget(
|
||||
ctx: Context,
|
||||
path: string,
|
||||
signal: AbortSignal,
|
||||
): Promise<FsTarget> {
|
||||
if (path.trim().length === 0) throw new Error('path must be a non-empty string')
|
||||
if (!isAbsolute(path)) {
|
||||
throw new Error(`The path ${path} is not an absolute path, it should start with \`/\`. Maybe you meant /${path}?`)
|
||||
}
|
||||
return ctx.fs.resolve(path, { signal })
|
||||
}
|
||||
|
||||
async function statExisting(
|
||||
ctx: Context,
|
||||
target: FsTarget,
|
||||
command: 'view' | 'str_replace' | 'insert',
|
||||
exec: ToolRunContext,
|
||||
): Promise<FsInfo> {
|
||||
const info = await ctx.fs.stat(target, exec.signal)
|
||||
if (info === undefined) {
|
||||
throw new FsError(
|
||||
`The path ${target.displayPath} does not exist. Please provide a valid path.`,
|
||||
'FS_NOT_FOUND',
|
||||
)
|
||||
}
|
||||
if (info.type === 'directory' && command !== 'view') {
|
||||
throw new FsError(
|
||||
`The path ${target.displayPath} is a directory and only the \`view\` command can be used on directories`,
|
||||
'FS_NOT_REGULAR_FILE',
|
||||
)
|
||||
}
|
||||
return info
|
||||
}
|
||||
|
||||
function requiredForCommand(
|
||||
value: string | undefined,
|
||||
parameter: string,
|
||||
command: string,
|
||||
allowEmpty = true,
|
||||
): string {
|
||||
if (value === undefined) throw new Error(`Parameter \`${parameter}\` is required for command: ${command}`)
|
||||
if (!allowEmpty && value.length === 0) {
|
||||
throw new Error(`Parameter \`${parameter}\` is empty for command: ${command}`)
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
function formatFileView(
|
||||
path: string,
|
||||
content: string,
|
||||
maxOutputChars: number,
|
||||
viewRange?: number[],
|
||||
): string {
|
||||
const allLines = content.split('\n')
|
||||
let lines = allLines
|
||||
let initialLine = 1
|
||||
let finalLine: number | undefined
|
||||
let prompt = `Here's the content of ${path} with line numbers (which has a total of ${allLines.length} lines)`
|
||||
if (viewRange !== undefined) {
|
||||
const [requestedInitialLine, requestedFinalLine] = viewRange
|
||||
if (
|
||||
viewRange.length !== 2
|
||||
|| requestedInitialLine === undefined
|
||||
|| requestedFinalLine === undefined
|
||||
|| !viewRange.every(Number.isInteger)
|
||||
) {
|
||||
throw new Error('Invalid `view_range`. It should be a list of two integers.')
|
||||
}
|
||||
initialLine = requestedInitialLine
|
||||
finalLine = requestedFinalLine
|
||||
if (initialLine < 1 || initialLine > allLines.length) {
|
||||
throw new Error(
|
||||
`Invalid \`view_range\`: [${viewRange.join(', ')}]. Its first element \`${initialLine}\` should be within the range of lines of the file: [1, ${allLines.length}]`,
|
||||
)
|
||||
}
|
||||
if (finalLine > allLines.length) {
|
||||
throw new Error(
|
||||
`Invalid \`view_range\`: [${viewRange.join(', ')}]. Its second element \`${finalLine}\` should be smaller than the number of lines in the file: \`${allLines.length}\``,
|
||||
)
|
||||
}
|
||||
if (finalLine !== -1 && finalLine < initialLine) {
|
||||
throw new Error(
|
||||
`Invalid \`view_range\`: [${viewRange.join(', ')}]. Its second element \`${finalLine}\` should be larger or equal than its first \`${initialLine}\``,
|
||||
)
|
||||
}
|
||||
lines = finalLine === -1
|
||||
? allLines.slice(initialLine - 1)
|
||||
: allLines.slice(initialLine - 1, finalLine)
|
||||
prompt += ` with view_range=[${initialLine}, ${finalLine}]`
|
||||
}
|
||||
const numbered = lines
|
||||
.map((line, index) => `${String(initialLine + index).padStart(6, ' ')} ${line}`)
|
||||
.join('\n')
|
||||
return maybeTruncate(`${prompt}:\n${numbered}\n`, maxOutputChars)
|
||||
}
|
||||
|
||||
async function listDirectory(
|
||||
ctx: Context,
|
||||
target: FsTarget,
|
||||
maxOutputChars: number,
|
||||
exec: ToolRunContext,
|
||||
): Promise<string> {
|
||||
async function visit(dir: FsTarget, depth: number): Promise<string[]> {
|
||||
const entries = await ctx.fs.listDir(dir, exec.signal)
|
||||
const rows: string[] = []
|
||||
for (const entry of entries.filter(candidate =>
|
||||
!candidate.name.startsWith('.')
|
||||
&& candidate.name !== 'node_modules'
|
||||
&& candidate.name !== '__pycache__')) {
|
||||
const type = entry.type === 'directory' ? 'd' : entry.type === 'file' ? 'f' : '?'
|
||||
rows.push(`${type}\t${entry.target.displayPath}`)
|
||||
if (entry.type === 'directory' && depth < 2) {
|
||||
rows.push(...await visit(entry.target, depth + 1))
|
||||
}
|
||||
}
|
||||
return rows
|
||||
}
|
||||
const rows = [`d\t${target.displayPath}`, ...await visit(target, 1)]
|
||||
rows.sort((left, right) => {
|
||||
const leftPath = left.slice(left.indexOf('\t') + 1)
|
||||
const rightPath = right.slice(right.indexOf('\t') + 1)
|
||||
return codepointCompare(leftPath, rightPath)
|
||||
})
|
||||
const listing = maybeTruncate(rows.join('\n') + '\n', maxOutputChars)
|
||||
return `Here're the files and directories up to 2 levels deep in ${target.displayPath}, excluding hidden items, node_modules, and Python cache directories:\n${listing}\n`
|
||||
}
|
||||
|
||||
async function viewPath(
|
||||
ctx: Context,
|
||||
path: string,
|
||||
viewRange: number[] | undefined,
|
||||
maxOutputChars: number,
|
||||
exec: ToolRunContext,
|
||||
): Promise<string> {
|
||||
const target = await resolveTarget(ctx, path, exec.signal)
|
||||
const info = await statExisting(ctx, target, 'view', exec)
|
||||
if (info.type === 'directory') {
|
||||
if (viewRange !== undefined) {
|
||||
throw new Error('The `view_range` parameter is not allowed when `path` points to a directory.')
|
||||
}
|
||||
return listDirectory(ctx, target, maxOutputChars, exec)
|
||||
}
|
||||
if (info.type !== 'file') {
|
||||
throw new FsError(`cannot view "${target.displayPath}": not a regular file or directory`, 'FS_NOT_REGULAR_FILE')
|
||||
}
|
||||
const content = await ctx.fs.readText(target, exec.signal)
|
||||
ctx.emit('fs/observed', target, info.version, exec)
|
||||
return formatFileView(target.displayPath, content, maxOutputChars, viewRange)
|
||||
}
|
||||
|
||||
async function createFile(
|
||||
ctx: Context,
|
||||
policy: MutationPolicy,
|
||||
path: string,
|
||||
fileText: string | undefined,
|
||||
exec: ToolRunContext,
|
||||
): Promise<string> {
|
||||
const content = requiredForCommand(fileText, 'file_text', 'create')
|
||||
const sandboxPolicy = policy.resolve(exec)
|
||||
const target = await resolveTarget(ctx, path, exec.signal)
|
||||
if (await ctx.fs.stat(target, exec.signal) !== undefined) {
|
||||
throw new Error(`File already exists at: ${target.displayPath}. Cannot overwrite files using command \`create\`.`)
|
||||
}
|
||||
const intent = await ctx.waterfall(
|
||||
'fs/write-intent',
|
||||
target,
|
||||
exec,
|
||||
() => ({ kind: 'createIfAbsent' } as const),
|
||||
)
|
||||
let outcome
|
||||
try {
|
||||
outcome = await ctx.fs.writeText(
|
||||
target,
|
||||
content,
|
||||
intent,
|
||||
exec.signal,
|
||||
sandboxPolicy,
|
||||
)
|
||||
} catch (error: unknown) {
|
||||
throw policy.mapError(error, sandboxPolicy)
|
||||
}
|
||||
ctx.emit('fs/observed', target, outcome.version, exec)
|
||||
return `New file created successfully at: ${target.displayPath}`
|
||||
}
|
||||
|
||||
async function replaceInFile(
|
||||
ctx: Context,
|
||||
policy: MutationPolicy,
|
||||
path: string,
|
||||
oldStr: string | undefined,
|
||||
newStr: string | undefined,
|
||||
exec: ToolRunContext,
|
||||
): Promise<string> {
|
||||
const sandboxPolicy = policy.resolve(exec)
|
||||
const target = await resolveTarget(ctx, path, exec.signal)
|
||||
const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)
|
||||
const oldValue = requiredForCommand(oldStr, 'old_str', 'str_replace', false)
|
||||
const newValue = newStr ?? ''
|
||||
const info = await statExisting(ctx, target, 'str_replace', exec)
|
||||
if (info.type !== 'file') {
|
||||
throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
|
||||
}
|
||||
const before = await ctx.fs.readText(target, exec.signal)
|
||||
const offsets = matchOffsets(before, oldValue)
|
||||
const offset = offsets[0]
|
||||
if (offset === undefined) {
|
||||
throw new FsError(
|
||||
`No replacement was performed, old_str \`${oldValue}\` did not appear verbatim in ${target.displayPath}.`,
|
||||
'FS_EDIT_NOT_FOUND',
|
||||
)
|
||||
}
|
||||
if (offsets.length > 1) {
|
||||
const lines = lineNumbersAt(before, offsets)
|
||||
throw new FsError(
|
||||
`No replacement was performed. Multiple occurrences of old_str \`${oldValue}\` in lines [${lines.join(', ')}]. Please ensure it is unique`,
|
||||
'FS_AMBIGUOUS_EDIT',
|
||||
)
|
||||
}
|
||||
let outcome
|
||||
try {
|
||||
outcome = await ctx.fs.writeText(
|
||||
target,
|
||||
before.slice(0, offset) + newValue + before.slice(offset + oldValue.length),
|
||||
intent === undefined
|
||||
? { kind: 'replaceIfVersion', version: info.version }
|
||||
: { kind: 'replaceIfVersion', version: intent.version },
|
||||
exec.signal,
|
||||
sandboxPolicy,
|
||||
)
|
||||
} catch (error: unknown) {
|
||||
throw policy.mapError(error, sandboxPolicy)
|
||||
}
|
||||
ctx.emit('fs/observed', target, outcome.version, exec)
|
||||
return `The file ${target.displayPath} has been edited successfully.`
|
||||
}
|
||||
|
||||
async function insertInFile(
|
||||
ctx: Context,
|
||||
policy: MutationPolicy,
|
||||
path: string,
|
||||
insertLine: number | undefined,
|
||||
newStr: string | undefined,
|
||||
exec: ToolRunContext,
|
||||
): Promise<string> {
|
||||
if (insertLine === undefined) throw new Error('Parameter `insert_line` is required for command: insert')
|
||||
const value = requiredForCommand(newStr, 'new_str', 'insert')
|
||||
const sandboxPolicy = policy.resolve(exec)
|
||||
const target = await resolveTarget(ctx, path, exec.signal)
|
||||
const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)
|
||||
const info = await statExisting(ctx, target, 'insert', exec)
|
||||
if (info.type !== 'file') {
|
||||
throw new FsError(`cannot insert into "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
|
||||
}
|
||||
const before = await ctx.fs.readText(target, exec.signal)
|
||||
const lines = before.split('\n')
|
||||
if (!Number.isInteger(insertLine) || insertLine < 0 || insertLine > lines.length) {
|
||||
throw new Error(
|
||||
`Invalid \`insert_line\` parameter: ${insertLine}. It should be within the range of lines of the file: [0, ${lines.length}]`,
|
||||
)
|
||||
}
|
||||
const after = [
|
||||
...lines.slice(0, insertLine),
|
||||
...value.split('\n'),
|
||||
...lines.slice(insertLine),
|
||||
].join('\n')
|
||||
const expected: FsWriteIntent = intent === undefined
|
||||
? { kind: 'replaceIfVersion', version: info.version }
|
||||
: { kind: 'replaceIfVersion', version: intent.version }
|
||||
let outcome
|
||||
try {
|
||||
outcome = await ctx.fs.writeText(target, after, expected, exec.signal, sandboxPolicy)
|
||||
} catch (error: unknown) {
|
||||
throw policy.mapError(error, sandboxPolicy)
|
||||
}
|
||||
ctx.emit('fs/observed', target, outcome.version, exec)
|
||||
return `The file ${target.displayPath} has been edited successfully.`
|
||||
}
|
||||
|
||||
interface ResolvedConfig {
|
||||
maxOutputChars: number
|
||||
description: string
|
||||
}
|
||||
|
||||
function presentEditorCall(args: {
|
||||
command: 'view' | 'create' | 'str_replace' | 'insert'
|
||||
path: string
|
||||
file_text?: string
|
||||
insert_line?: number
|
||||
new_str?: string
|
||||
old_str?: string
|
||||
}): ToolCallView {
|
||||
switch (args.command) {
|
||||
case 'view':
|
||||
return {
|
||||
card: 'generic',
|
||||
title: `view ${args.path}`,
|
||||
kind: 'read',
|
||||
locations: [{ path: args.path }],
|
||||
}
|
||||
case 'create':
|
||||
return {
|
||||
card: 'diff',
|
||||
title: `create ${args.path}`,
|
||||
diffs: [{ path: args.path, oldText: null, newText: args.file_text ?? '' }],
|
||||
locations: [{ path: args.path }],
|
||||
}
|
||||
case 'str_replace':
|
||||
return {
|
||||
card: 'diff',
|
||||
title: `str_replace ${args.path}`,
|
||||
diffs: [{
|
||||
path: args.path,
|
||||
oldText: args.old_str ?? null,
|
||||
newText: args.new_str ?? '',
|
||||
}],
|
||||
locations: [{ path: args.path }],
|
||||
}
|
||||
case 'insert':
|
||||
return {
|
||||
card: 'generic',
|
||||
title: `insert ${args.path}`,
|
||||
kind: 'edit',
|
||||
locations: [{
|
||||
path: args.path,
|
||||
...args.insert_line === undefined ? {} : { line: Math.max(1, args.insert_line + 1) },
|
||||
}],
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Register the model-facing `str_replace_editor` tool. */
|
||||
function registerStrReplaceEditor(ctx: Context, config: ResolvedConfig): void {
|
||||
const policy = new MutationPolicy(ctx)
|
||||
ctx.tools.register(defineTool({
|
||||
name: 'str_replace_editor',
|
||||
description: config.description,
|
||||
parameters: {
|
||||
command: {
|
||||
type: 'string',
|
||||
required: true,
|
||||
enum: ['view', 'create', 'str_replace', 'insert'],
|
||||
description: 'The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`.',
|
||||
},
|
||||
path: {
|
||||
type: 'string',
|
||||
required: true,
|
||||
description: 'Absolute path to file or directory, e.g. `/repo/file.py` or `/repo`.',
|
||||
},
|
||||
file_text: {
|
||||
type: 'string',
|
||||
description: 'Required parameter of `create` command, with the content of the file to be created.',
|
||||
},
|
||||
insert_line: {
|
||||
type: 'integer',
|
||||
description: 'Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`.',
|
||||
},
|
||||
new_str: {
|
||||
type: 'string',
|
||||
description: 'Optional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert.',
|
||||
},
|
||||
old_str: {
|
||||
type: 'string',
|
||||
description: 'Required parameter of `str_replace` command containing the string in `path` to replace.',
|
||||
},
|
||||
view_range: {
|
||||
type: 'array',
|
||||
items: { type: 'integer' },
|
||||
description: 'Optional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file.',
|
||||
},
|
||||
},
|
||||
output: {
|
||||
schema: { type: 'string' },
|
||||
render: (_args, value) => [{ type: 'text', text: value }],
|
||||
},
|
||||
async execute(args, exec) {
|
||||
switch (args.command) {
|
||||
case 'view':
|
||||
return viewPath(ctx, args.path, args.view_range, config.maxOutputChars, exec)
|
||||
case 'create':
|
||||
return createFile(ctx, policy, args.path, args.file_text, exec)
|
||||
case 'str_replace':
|
||||
return replaceInFile(
|
||||
ctx,
|
||||
policy,
|
||||
args.path,
|
||||
args.old_str,
|
||||
args.new_str,
|
||||
exec,
|
||||
)
|
||||
case 'insert':
|
||||
return insertInFile(
|
||||
ctx,
|
||||
policy,
|
||||
args.path,
|
||||
args.insert_line,
|
||||
args.new_str,
|
||||
exec,
|
||||
)
|
||||
}
|
||||
},
|
||||
presentCall: presentEditorCall,
|
||||
}))
|
||||
}
|
||||
|
||||
export const name = 'tool-str-replace-editor'
|
||||
export const inject = ['tools', 'fs']
|
||||
|
||||
/** Configuration for the string-replacement editor tool. */
|
||||
export interface Config {
|
||||
/** Maximum returned view characters before clipping (default 16000). */
|
||||
maxOutputChars?: number
|
||||
/** Model-facing tool description. */
|
||||
description?: string
|
||||
}
|
||||
|
||||
/** Runtime configuration schema for the string-replacement editor tool. */
|
||||
export const Config: z<Config> = z.object({
|
||||
maxOutputChars: z.number().default(16_000),
|
||||
description: z.string().default(DEFAULT_DESCRIPTION),
|
||||
})
|
||||
|
||||
/** Register one `str_replace_editor` tool over `ctx.fs`. */
|
||||
export function apply(ctx: Context, config: Config): void {
|
||||
const resolved: ResolvedConfig = {
|
||||
maxOutputChars: config.maxOutputChars ?? 16_000,
|
||||
description: config.description ?? DEFAULT_DESCRIPTION,
|
||||
}
|
||||
if (!Number.isSafeInteger(resolved.maxOutputChars) || resolved.maxOutputChars <= 0) {
|
||||
throw new Error('tool-str-replace-editor: maxOutputChars must be a positive safe integer')
|
||||
}
|
||||
if (resolved.description.trim().length === 0) {
|
||||
throw new Error('tool-str-replace-editor: description must be non-empty')
|
||||
}
|
||||
registerStrReplaceEditor(ctx, resolved)
|
||||
}
|
||||
30
packages/fs/tool-str-replace-editor/src/invariant.ts
Normal file
30
packages/fs/tool-str-replace-editor/src/invariant.ts
Normal file
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* Package-owned invariant companion for `@deepseek-ai/dsh-tool-str-replace-editor`.
|
||||
* @module @deepseek-ai/dsh-tool-str-replace-editor/invariant
|
||||
*/
|
||||
|
||||
/* jscpd:ignore-start */
|
||||
import type { Context } from 'cordis'
|
||||
import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
|
||||
|
||||
const PACKAGE_NAME = '@deepseek-ai/dsh-tool-str-replace-editor'
|
||||
|
||||
/** Cordis companion plugin name. */
|
||||
export const name = 'tool-str-replace-editor-invariant'
|
||||
/** Service required before the companion can reserve package ownership. */
|
||||
export const inject = ['invariants']
|
||||
|
||||
/**
|
||||
* No runtime invariant: the tool adapter owns no independent durable state;
|
||||
* filesystem mutation relations stay with the provider and policy plugins.
|
||||
*/
|
||||
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 */
|
||||
547
packages/fs/tool-str-replace-editor/tests/tools.spec.ts
Normal file
547
packages/fs/tool-str-replace-editor/tests/tools.spec.ts
Normal file
@@ -0,0 +1,547 @@
|
||||
import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { Context } from 'cordis'
|
||||
import { FsVersion } from '@deepseek-ai/dsh-fs'
|
||||
import { CallId } from '@deepseek-ai/dsh-llm'
|
||||
import { Session, SessionId } from '@deepseek-ai/dsh-session'
|
||||
import AgentRegistry from '@deepseek-ai/dsh-agent'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
|
||||
import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
|
||||
import SandboxedFileSystem from '@deepseek-ai/dsh-fs-sandbox'
|
||||
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
|
||||
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
|
||||
import ToolRegistry from '@deepseek-ai/dsh-tools'
|
||||
import * as ToolStrReplaceEditor from '@deepseek-ai/dsh-tool-str-replace-editor'
|
||||
|
||||
const contexts: Context[] = []
|
||||
const roots: string[] = []
|
||||
let callNumber = 0
|
||||
|
||||
afterEach(async () => {
|
||||
for (const ctx of contexts.splice(0)) await ctx.fiber.dispose()
|
||||
for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
function agent(ctx: Context, cwd: string): Agent {
|
||||
const id = SessionId(`str-replace-editor-owner-${callNumber}`)
|
||||
const scope = ctx.plugin(() => {})
|
||||
const value: Agent = {
|
||||
id,
|
||||
options: {},
|
||||
session: new Session(id, [], { version: 0, id, createdAt: 0, cwd }),
|
||||
status: 'idle',
|
||||
acceptsNextStep: false,
|
||||
ctx: scope.ctx,
|
||||
followup: () => {},
|
||||
steer: () => {},
|
||||
inject: () => {},
|
||||
send: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
ctx.agents.register(value)
|
||||
return value
|
||||
}
|
||||
|
||||
function text(result: { content: { type: string; text?: string }[] }): string {
|
||||
return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
|
||||
}
|
||||
|
||||
function call(ctx: Context, owner: Agent | undefined, args: unknown) {
|
||||
return ctx.tools.execute({
|
||||
signal: new AbortController().signal,
|
||||
callId: CallId(`str-replace-editor-${++callNumber}`),
|
||||
name: 'str_replace_editor',
|
||||
arguments: args,
|
||||
...owner === undefined ? {} : { agent: owner },
|
||||
})
|
||||
}
|
||||
|
||||
async function setup(
|
||||
config: ToolStrReplaceEditor.Config = {},
|
||||
options: { fsPolicy?: boolean; sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access' } = {},
|
||||
) {
|
||||
const root = await mkdtemp(join(tmpdir(), 'dsh-tool-str-replace-editor-'))
|
||||
roots.push(root)
|
||||
const ctx = new Context()
|
||||
contexts.push(ctx)
|
||||
await ctx.plugin(SystemPrompt)
|
||||
await ctx.plugin(ToolRegistry)
|
||||
await ctx.plugin(AgentRegistry)
|
||||
if (options.sandboxMode === undefined) {
|
||||
await ctx.plugin(LocalFileSystem, { cwd: root })
|
||||
} else {
|
||||
await ctx.plugin(SandboxPolicy, { mode: options.sandboxMode, workspaceRoot: root })
|
||||
await ctx.plugin(SandboxedFileSystem, { cwd: root })
|
||||
}
|
||||
if (options.fsPolicy === true) await ctx.plugin(FsPolicy)
|
||||
const fiber = await ctx.plugin(ToolStrReplaceEditor, config)
|
||||
return { ctx, root, fiber, owner: agent(ctx, root) }
|
||||
}
|
||||
|
||||
describe('tool-str-replace-editor', () => {
|
||||
it('registers the standalone schema and configurable description', async () => {
|
||||
const { ctx, fiber } = await setup({ description: 'custom editor description' })
|
||||
const schema = ctx.tools.schemas()[0]
|
||||
expect(ctx.tools.schemas().map(item => item.name)).toEqual(['str_replace_editor'])
|
||||
expect(schema?.description).toBe('custom editor description')
|
||||
const properties = (schema?.parameters as {
|
||||
properties: Record<string, { type?: string; items?: { type?: string } }>
|
||||
}).properties
|
||||
expect(properties).not.toHaveProperty('replace_all')
|
||||
expect(properties.insert_line?.type).toBe('integer')
|
||||
expect(properties.view_range?.items?.type).toBe('integer')
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'view',
|
||||
path: '/workspace/a.txt',
|
||||
})).toMatchObject({
|
||||
card: 'generic',
|
||||
kind: 'read',
|
||||
locations: [{ path: '/workspace/a.txt' }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'create',
|
||||
path: '/workspace/a.txt',
|
||||
file_text: 'hello',
|
||||
})).toMatchObject({
|
||||
card: 'diff',
|
||||
diffs: [{ path: '/workspace/a.txt', oldText: null, newText: 'hello' }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'str_replace',
|
||||
path: '/workspace/a.txt',
|
||||
old_str: 'old',
|
||||
new_str: 'new',
|
||||
})).toMatchObject({
|
||||
card: 'diff',
|
||||
diffs: [{ path: '/workspace/a.txt', oldText: 'old', newText: 'new' }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'insert',
|
||||
path: '/workspace/a.txt',
|
||||
insert_line: 0,
|
||||
new_str: 'x',
|
||||
})).toMatchObject({
|
||||
card: 'generic',
|
||||
kind: 'edit',
|
||||
locations: [{ path: '/workspace/a.txt', line: 1 }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'create',
|
||||
path: '/workspace/empty.txt',
|
||||
})).toMatchObject({
|
||||
diffs: [{ path: '/workspace/empty.txt', oldText: null, newText: '' }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'str_replace',
|
||||
path: '/workspace/a.txt',
|
||||
})).toMatchObject({
|
||||
diffs: [{ path: '/workspace/a.txt', oldText: null, newText: '' }],
|
||||
})
|
||||
expect(ctx.tools.get('str_replace_editor')?.presentCall?.({
|
||||
command: 'insert',
|
||||
path: '/workspace/a.txt',
|
||||
})).toMatchObject({
|
||||
locations: [{ path: '/workspace/a.txt' }],
|
||||
})
|
||||
|
||||
await fiber.dispose()
|
||||
expect(ctx.tools.schemas()).toEqual([])
|
||||
expect(ctx.tools.get('str_replace_editor')).toBeUndefined()
|
||||
})
|
||||
|
||||
it('creates, views, replaces, and inserts with the canonical model-facing output', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const sample = join(root, 'sample.txt')
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'create',
|
||||
path: sample,
|
||||
file_text: 'one\ntwo\nthree\n',
|
||||
}))).toBe(`New file created successfully at: ${sample}`)
|
||||
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'view',
|
||||
path: sample,
|
||||
view_range: [2, -1],
|
||||
}))).toBe([
|
||||
`Here's the content of ${sample} with line numbers (which has a total of 4 lines) with view_range=[2, -1]:`,
|
||||
' 2 two',
|
||||
' 3 three',
|
||||
' 4 ',
|
||||
'',
|
||||
].join('\n'))
|
||||
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: sample,
|
||||
old_str: 'two',
|
||||
new_str: 'TWO',
|
||||
}))).toBe(`The file ${sample} has been edited successfully.`)
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: sample,
|
||||
old_str: 'TWO',
|
||||
}))).toBe(`The file ${sample} has been edited successfully.`)
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path: sample,
|
||||
insert_line: 1,
|
||||
new_str: 'between',
|
||||
}))).toBe(`The file ${sample} has been edited successfully.`)
|
||||
expect(await readFile(sample, 'utf8')).toBe('one\nbetween\n\nthree\n')
|
||||
})
|
||||
|
||||
it('writes replacement text literally', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const sample = join(root, 'literal.txt')
|
||||
const replacement = "$&|$`|$'|$$"
|
||||
await writeFile(sample, 'before OLD after')
|
||||
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: sample,
|
||||
old_str: 'OLD',
|
||||
new_str: replacement,
|
||||
})).isError).toBe(false)
|
||||
expect(await readFile(sample, 'utf8')).toBe(`before ${replacement} after`)
|
||||
})
|
||||
|
||||
it('lists visible entries to depth two and clips at the configured view limit', async () => {
|
||||
const { ctx, root, owner } = await setup({ maxOutputChars: 10_000 })
|
||||
await mkdir(join(root, 'dir', 'nested', 'third'), { recursive: true })
|
||||
await mkdir(join(root, 'dir', 'node_modules', 'pkg'), { recursive: true })
|
||||
await mkdir(join(root, 'dir', 'node_modules_old'), { recursive: true })
|
||||
await mkdir(join(root, 'dir', '__pycache__'), { recursive: true })
|
||||
await mkdir(join(root, 'dir', '__pycache__backup'), { recursive: true })
|
||||
await writeFile(join(root, 'dir', 'visible.txt'), 'ok')
|
||||
await writeFile(join(root, 'dir', '.hidden'), 'hidden')
|
||||
await writeFile(join(root, 'dir', 'nested', 'child.txt'), 'child')
|
||||
await writeFile(join(root, 'dir', 'nested', 'third', 'too-deep.txt'), 'deep')
|
||||
await writeFile(join(root, 'dir', 'node_modules', 'pkg', 'index.js'), 'hidden dependency')
|
||||
await writeFile(join(root, 'dir', 'node_modules_old', 'kept.js'), 'visible source')
|
||||
await writeFile(join(root, 'dir', '__pycache__', 'module.pyc'), 'cache')
|
||||
await writeFile(join(root, 'dir', '__pycache__backup', 'kept.py'), 'visible source')
|
||||
const listDir = ctx.fs.listDir.bind(ctx.fs)
|
||||
const otherTarget = await ctx.fs.resolve(join(root, 'dir', 'other'))
|
||||
ctx.fs.listDir = async (target, signal) => {
|
||||
const entries = await listDir(target, signal)
|
||||
return target.displayPath === join(root, 'dir')
|
||||
? [
|
||||
{ name: 'same-target', type: 'other', target: otherTarget },
|
||||
{ name: 'other', type: 'other', target: otherTarget },
|
||||
...entries.toReversed(),
|
||||
]
|
||||
: entries
|
||||
}
|
||||
|
||||
const listing = text(await call(ctx, owner, { command: 'view', path: join(root, 'dir') }))
|
||||
expect(listing).not.toContain('.hidden')
|
||||
expect(listing).not.toContain('too-deep.txt')
|
||||
expect(listing).not.toContain('index.js')
|
||||
expect(listing).not.toContain('module.pyc')
|
||||
expect(listing).toContain('node_modules_old/kept.js')
|
||||
expect(listing).toContain('__pycache__backup/kept.py')
|
||||
|
||||
const clipped = await setup({ maxOutputChars: 10 })
|
||||
await writeFile(join(clipped.root, 'large.txt'), 'x'.repeat(100))
|
||||
expect(text(await call(clipped.ctx, clipped.owner, {
|
||||
command: 'view',
|
||||
path: join(clipped.root, 'large.txt'),
|
||||
})))
|
||||
.toContain('<response clipped>')
|
||||
})
|
||||
|
||||
it('matches canonical empty-line, range, and end-insert behavior', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const empty = join(root, 'empty.txt')
|
||||
const newline = join(root, 'newline.txt')
|
||||
const plain = join(root, 'plain.txt')
|
||||
await writeFile(empty, '')
|
||||
await writeFile(newline, '\n')
|
||||
await writeFile(plain, 'one\ntwo')
|
||||
|
||||
expect(text(await call(ctx, owner, { command: 'view', path: empty })))
|
||||
.toContain('(which has a total of 1 lines):\n 1 \n')
|
||||
expect(text(await call(ctx, owner, { command: 'view', path: newline })))
|
||||
.toContain('(which has a total of 2 lines):\n 1 \n 2 \n')
|
||||
expect(text(await call(ctx, owner, {
|
||||
command: 'view',
|
||||
path: plain,
|
||||
view_range: [1, 2],
|
||||
}))).toContain(' 2 two')
|
||||
expect(text(await call(ctx, undefined, {
|
||||
command: 'view',
|
||||
path: plain,
|
||||
}))).toContain(' 1 one')
|
||||
expect((await call(ctx, undefined, {
|
||||
command: 'create',
|
||||
path: join(root, 'ownerless.txt'),
|
||||
file_text: 'ownerless',
|
||||
})).isError).toBe(false)
|
||||
|
||||
await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path: plain,
|
||||
insert_line: 2,
|
||||
new_str: 'three',
|
||||
})
|
||||
expect(await readFile(plain, 'utf8')).toBe('one\ntwo\nthree')
|
||||
|
||||
await writeFile(newline, 'one\n')
|
||||
await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path: newline,
|
||||
insert_line: 2,
|
||||
new_str: 'three',
|
||||
})
|
||||
expect(await readFile(newline, 'utf8')).toBe('one\n\nthree')
|
||||
})
|
||||
|
||||
it('uses old_str-only replacement failures and rejects relative paths', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const ambiguous = join(root, 'ambiguous.txt')
|
||||
await writeFile(ambiguous, 'same\nother\nsame')
|
||||
|
||||
const missing = await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: ambiguous,
|
||||
old_str: 'absent',
|
||||
new_str: 'x',
|
||||
})
|
||||
expect(missing.isError).toBe(true)
|
||||
expect(text(missing)).toContain(`old_str \`absent\` did not appear verbatim in ${ambiguous}`)
|
||||
expect(text(missing)).not.toContain('old_string')
|
||||
|
||||
const repeated = await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: ambiguous,
|
||||
old_str: 'same',
|
||||
new_str: 'x',
|
||||
})
|
||||
expect(repeated.isError).toBe(true)
|
||||
expect(text(repeated)).toContain('Multiple occurrences of old_str `same` in lines [1, 3]')
|
||||
expect(text(repeated)).not.toContain('replace_all')
|
||||
|
||||
await writeFile(ambiguous, 'alpha\nbeta\nmiddle\nalpha\nbeta')
|
||||
const repeatedMultiline = await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: ambiguous,
|
||||
old_str: 'alpha\nbeta',
|
||||
new_str: 'x',
|
||||
})
|
||||
expect(text(repeatedMultiline))
|
||||
.toContain('Multiple occurrences of old_str `alpha\nbeta` in lines [1, 4]')
|
||||
|
||||
const mixedEol = join(root, 'mixed-eol.txt')
|
||||
await writeFile(mixedEol, 'alpha\r\nbeta\nmiddle\nalpha\nbeta')
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: mixedEol,
|
||||
old_str: 'alpha\r\nbeta',
|
||||
new_str: 'replaced',
|
||||
})).isError).toBe(false)
|
||||
expect(await readFile(mixedEol, 'utf8')).toBe('replaced\nmiddle\nalpha\nbeta')
|
||||
|
||||
const relative = await call(ctx, owner, { command: 'view', path: 'ambiguous.txt' })
|
||||
expect(relative.isError).toBe(true)
|
||||
expect(text(relative)).toContain('is not an absolute path')
|
||||
expect(await readFile(ambiguous, 'utf8')).toBe('alpha\nbeta\nmiddle\nalpha\nbeta')
|
||||
})
|
||||
|
||||
it('reports invalid commands or arguments without mutating files', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const ambiguous = join(root, 'ambiguous.txt')
|
||||
const empty = join(root, 'empty.txt')
|
||||
const trailingNewline = join(root, 'trailing-newline.txt')
|
||||
const threeLines = join(root, 'three-lines.txt')
|
||||
const directory = join(root, 'directory')
|
||||
await writeFile(ambiguous, 'same same')
|
||||
await writeFile(empty, '')
|
||||
await writeFile(trailingNewline, 'one\n')
|
||||
await writeFile(threeLines, 'one\ntwo\nthree')
|
||||
await mkdir(directory)
|
||||
|
||||
const cases = [
|
||||
{ command: 'view', path: '' },
|
||||
{ command: 'view', path: join(root, 'missing.txt') },
|
||||
{ command: 'view', path: ambiguous, view_range: [1] },
|
||||
{ command: 'view', path: ambiguous, view_range: [0, 1] },
|
||||
{ command: 'view', path: ambiguous, view_range: [1.5, 2] },
|
||||
{ command: 'view', path: threeLines, view_range: [1, 99] },
|
||||
{ command: 'view', path: threeLines, view_range: [2, 1] },
|
||||
{ command: 'view', path: directory, view_range: [1, 1] },
|
||||
{ command: 'create', path: join(root, 'new.txt') },
|
||||
{ command: 'create', path: ambiguous, file_text: 'overwrite' },
|
||||
{ command: 'str_replace', path: ambiguous, new_str: 'x' },
|
||||
{ command: 'str_replace', path: ambiguous, old_str: '', new_str: 'x' },
|
||||
{ command: 'insert', path: ambiguous, new_str: 'x' },
|
||||
{ command: 'insert', path: ambiguous, insert_line: -1, new_str: 'x' },
|
||||
{ command: 'insert', path: ambiguous, insert_line: 1.5, new_str: 'x' },
|
||||
{ command: 'insert', path: ambiguous, insert_line: 99, new_str: 'x' },
|
||||
{ command: 'insert', path: empty, insert_line: 2, new_str: 'x' },
|
||||
{ command: 'insert', path: directory, insert_line: 0, new_str: 'x' },
|
||||
]
|
||||
for (const args of cases) {
|
||||
expect((await call(ctx, owner, args)).isError).toBe(true)
|
||||
}
|
||||
expect(await readFile(ambiguous, 'utf8')).toBe('same same')
|
||||
|
||||
ctx.fs.stat = async () => ({ version: FsVersion('special'), type: 'other' })
|
||||
const special = await call(ctx, owner, { command: 'view', path: join(root, 'special') })
|
||||
expect(special.isError).toBe(true)
|
||||
expect(special.error).toMatchObject({ info: { code: 'FS_NOT_REGULAR_FILE' } })
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: join(root, 'special'),
|
||||
old_str: 'x',
|
||||
new_str: 'y',
|
||||
})).error).toMatchObject({ info: { code: 'FS_NOT_REGULAR_FILE' } })
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path: join(root, 'special'),
|
||||
insert_line: 0,
|
||||
new_str: 'x',
|
||||
})).error).toMatchObject({ info: { code: 'FS_NOT_REGULAR_FILE' } })
|
||||
})
|
||||
|
||||
it('delegates read-before-edit decisions to fs-policy', async () => {
|
||||
const { ctx, root, owner } = await setup({}, { fsPolicy: true })
|
||||
const existing = join(root, 'existing.txt')
|
||||
const created = join(root, 'created.txt')
|
||||
await writeFile(existing, 'before')
|
||||
|
||||
const blindEdit = await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: existing,
|
||||
old_str: 'before',
|
||||
new_str: 'after',
|
||||
})
|
||||
expect(blindEdit.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
|
||||
expect(await readFile(existing, 'utf8')).toBe('before')
|
||||
|
||||
await call(ctx, owner, { command: 'view', path: existing })
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path: existing,
|
||||
old_str: 'before',
|
||||
new_str: 'after',
|
||||
})).isError).toBe(false)
|
||||
expect(await readFile(existing, 'utf8')).toBe('after')
|
||||
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path: existing,
|
||||
insert_line: 1,
|
||||
new_str: 'tail',
|
||||
})).isError).toBe(false)
|
||||
expect(await readFile(existing, 'utf8')).toBe('after\ntail')
|
||||
|
||||
expect((await call(ctx, owner, {
|
||||
command: 'create',
|
||||
path: created,
|
||||
file_text: 'new',
|
||||
})).isError).toBe(false)
|
||||
expect(await readFile(created, 'utf8')).toBe('new')
|
||||
})
|
||||
|
||||
it('passes the session sandbox policy to every mutation', async () => {
|
||||
const { ctx, root, owner } = await setup({}, { sandboxMode: 'read-only' })
|
||||
const path = join(root, 'blocked.txt')
|
||||
const result = await call(ctx, owner, {
|
||||
command: 'create',
|
||||
path,
|
||||
file_text: 'blocked',
|
||||
})
|
||||
expect(result.error).toMatchObject({ info: { code: 'FS_SANDBOX_DENIED' } })
|
||||
expect(text(result)).toContain('[sandbox: file access denied under read-only mode]')
|
||||
|
||||
const ownerless = await call(ctx, undefined, {
|
||||
command: 'create',
|
||||
path: join(root, 'ownerless-blocked.txt'),
|
||||
file_text: 'blocked',
|
||||
})
|
||||
expect(ownerless.error).toMatchObject({ info: { code: 'FS_SANDBOX_DENIED' } })
|
||||
})
|
||||
|
||||
it('preserves tabs outside the edited region', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const path = join(root, 'Makefile')
|
||||
await writeFile(path, 'target:\n\told\nremove\n')
|
||||
expect(text(await call(ctx, owner, { command: 'view', path })))
|
||||
.toContain(' 2 \told')
|
||||
await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path,
|
||||
old_str: '\told',
|
||||
new_str: '\tnew',
|
||||
})
|
||||
await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path,
|
||||
old_str: 'remove\n',
|
||||
})
|
||||
await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path,
|
||||
insert_line: 1,
|
||||
new_str: '\tkept',
|
||||
})
|
||||
expect(await readFile(path, 'utf8')).toBe('target:\n\tkept\n\tnew\n')
|
||||
})
|
||||
|
||||
it('reports missing sandbox-policy composition during plugin startup', async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), 'dsh-tool-str-replace-editor-missing-policy-'))
|
||||
roots.push(root)
|
||||
const ctx = new Context()
|
||||
contexts.push(ctx)
|
||||
await ctx.plugin(SystemPrompt)
|
||||
await ctx.plugin(ToolRegistry)
|
||||
await ctx.plugin(AgentRegistry)
|
||||
await ctx.plugin(LocalFileSystem, { cwd: root })
|
||||
Object.defineProperty(ctx.fs, 'sandboxMode', { value: 'read-only' })
|
||||
|
||||
await expect(ctx.plugin(ToolStrReplaceEditor))
|
||||
.rejects.toThrow('the mounted filesystem confines but ctx.sandboxPolicy is missing')
|
||||
})
|
||||
|
||||
it('maps unexpected backend write failures for replace and insert', async () => {
|
||||
const { ctx, root, owner } = await setup()
|
||||
const path = join(root, 'backend-error.txt')
|
||||
await writeFile(path, 'old\n')
|
||||
const failWrite = async (): Promise<never> => {
|
||||
throw new Error('backend write failed')
|
||||
}
|
||||
ctx.fs.writeText = failWrite
|
||||
|
||||
const replace = await call(ctx, owner, {
|
||||
command: 'str_replace',
|
||||
path,
|
||||
old_str: 'old',
|
||||
new_str: 'new',
|
||||
})
|
||||
expect(replace.isError).toBe(true)
|
||||
expect(text(replace)).toContain('backend write failed')
|
||||
|
||||
const insert = await call(ctx, owner, {
|
||||
command: 'insert',
|
||||
path,
|
||||
insert_line: 1,
|
||||
new_str: 'new',
|
||||
})
|
||||
expect(insert.isError).toBe(true)
|
||||
expect(text(insert)).toContain('backend write failed')
|
||||
})
|
||||
|
||||
it('rejects invalid plugin config', () => {
|
||||
expect(() => {
|
||||
ToolStrReplaceEditor.apply(new Context(), { maxOutputChars: 0 })
|
||||
}).toThrow('maxOutputChars must be a positive safe integer')
|
||||
expect(() => {
|
||||
ToolStrReplaceEditor.apply(new Context(), { description: ' ' })
|
||||
}).toThrow('description must be non-empty')
|
||||
})
|
||||
})
|
||||
16
packages/fs/tool-str-replace-editor/tsconfig.json
Normal file
16
packages/fs/tool-str-replace-editor/tsconfig.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"extends": "../../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "src",
|
||||
"outDir": "lib/types"
|
||||
},
|
||||
"include": ["src"],
|
||||
"references": [
|
||||
{ "path": "../../../vendor/cordis" },
|
||||
{ "path": "../../core/tools" },
|
||||
{ "path": "../fs" },
|
||||
{ "path": "../../sandbox/sandbox" },
|
||||
{ "path": "../../sandbox/sandbox-policy" },
|
||||
{ "path": "../../support/invariants" }
|
||||
]
|
||||
}
|
||||
@@ -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: 318380405214d5f25ad77e348c4e134a8981ffb3
|
||||
README.zh.md: 2f88f64cc2974b8535e34eb9798f512ea109b754
|
||||
README.md: 52b5fe7e89f915be3b50324628e9d5c48f1ef94c
|
||||
README.zh.md: 742da39470083887a71ddba4a7c8012f0ce0ea1f
|
||||
|
||||
@@ -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, breadcrumb with a click-to-edit path zone, 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
|
||||
|
||||
|
||||
@@ -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 双列视图、带点击即编辑路径区的面包屑、嵌套新建文件夹对话框）填入 [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）。
|
||||
|
||||
## 模型体验
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
/* Directory-browser dialog (figma 813-23126 family). The shared Modal renders
|
||||
* headless here — mask, card, Escape only — and this module owns the figma
|
||||
* frame: 600×420 card (viewport-clamped), header (title + crumbs, l3 separator),
|
||||
* frame: 680×500 card (viewport-clamped; upsized from the figma 600×420),
|
||||
* header (title + crumbs, l3 separator),
|
||||
* the one-or-two-column Miller content, and the bordered footer. */
|
||||
|
||||
/* Doubled class beats Modal's own .dialog regardless of stylesheet order. */
|
||||
@@ -8,19 +9,32 @@
|
||||
* columns scroll, so shrinking the height keeps Open/Cancel reachable
|
||||
* instead of clipping them below a fixed overlay. */
|
||||
.dialog.dialog {
|
||||
width: min(600px, 100%);
|
||||
height: min(420px, calc(100dvh - 32px));
|
||||
width: min(680px, 100%);
|
||||
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);
|
||||
}
|
||||
|
||||
/* Header block: pl24 pr14 pt22 pb12, 8px between title row and crumb row. */
|
||||
/* Card-scope wrapper hosting the path editor's Escape and focus-leave
|
||||
* observers; display:contents keeps header/content/footer as direct flex
|
||||
* children of the Modal card. */
|
||||
.editorScope {
|
||||
display: contents;
|
||||
}
|
||||
|
||||
/* Header block: pl24 pr14 pt16 pb8, 8px between title row and crumb row. */
|
||||
.header {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 8px;
|
||||
flex: none;
|
||||
padding: 22px 14px 12px 24px;
|
||||
padding: 16px 14px 8px 24px;
|
||||
border-bottom: 1px solid var(--dsw-alias-border-l3);
|
||||
}
|
||||
|
||||
@@ -54,8 +68,12 @@
|
||||
align-items: stretch;
|
||||
flex: 1 1 0;
|
||||
min-height: 0;
|
||||
gap: 20px;
|
||||
/* 12px of row gap on each side of the divider; the left side reads wider
|
||||
* by the column's trailing 8px scrollbar clearance, which is deliberate —
|
||||
* the thumb needs that room, the right pane's rows do not. */
|
||||
gap: 12px;
|
||||
overflow-x: auto;
|
||||
scrollbar-width: none;
|
||||
}
|
||||
|
||||
.crumbTrail {
|
||||
@@ -126,28 +144,36 @@
|
||||
color: var(--dsw-alias-label-primary);
|
||||
}
|
||||
|
||||
/* Miller content: pt16 px24; columns are 256 wide (or full width solo) with
|
||||
* the hairline divider centered between them; each column scrolls alone. */
|
||||
/* Miller content: symmetric 16px vertical padding so the divider clears the
|
||||
* header and footer rules evenly; each column scrolls alone (column widths
|
||||
* live at .column). */
|
||||
.content {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
flex: 1 1 0;
|
||||
min-height: 0;
|
||||
padding: 16px 24px 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;
|
||||
}
|
||||
|
||||
/* 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
|
||||
* the panes. */
|
||||
.column {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 2px;
|
||||
width: 256px;
|
||||
flex: none;
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
.columnWide {
|
||||
width: 100%;
|
||||
flex: 1 1 0;
|
||||
min-width: 256px;
|
||||
overflow-y: auto;
|
||||
/* The themed scrollbar occupies the column's edge (styled scrollbars are
|
||||
* classic, gutter-taking ones); the extra clearance keeps the row pills
|
||||
* clear of the thumb. */
|
||||
padding-right: 8px;
|
||||
}
|
||||
|
||||
.divider {
|
||||
@@ -216,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;
|
||||
}
|
||||
@@ -228,8 +258,25 @@
|
||||
color: var(--dsw-alias-state-error-primary);
|
||||
}
|
||||
|
||||
/* Footer: l3 separator on top, pt12 px24, New-folder pinned left; the fixed
|
||||
* card leaves the figma 28px below the 36px buttons. */
|
||||
/* 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, 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;
|
||||
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 {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
@@ -238,10 +285,42 @@
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
flex: none;
|
||||
padding: 12px 24px 28px;
|
||||
padding: 16px 24px;
|
||||
border-top: 1px solid var(--dsw-alias-border-l3);
|
||||
}
|
||||
|
||||
/* Show-hidden toggle: a subtle fixed-label text button left of the gap;
|
||||
* the pressed state seats a check glyph after the label (Menu's selected
|
||||
* vocabulary; trailing so the label never shifts) instead of flipping the
|
||||
* wording. */
|
||||
.showHiddenToggle {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 4px;
|
||||
border: none;
|
||||
background: transparent;
|
||||
padding: 0;
|
||||
font-size: 13px;
|
||||
line-height: 20px;
|
||||
font-weight: 500;
|
||||
color: var(--dsw-alias-label-secondary);
|
||||
cursor: pointer;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.showHiddenToggle:hover {
|
||||
color: var(--dsw-alias-label-primary);
|
||||
}
|
||||
|
||||
.showHiddenToggle:disabled {
|
||||
color: var(--dsw-alias-label-caption);
|
||||
cursor: default;
|
||||
}
|
||||
|
||||
.showHiddenToggleActive {
|
||||
color: var(--dsw-alias-label-primary);
|
||||
}
|
||||
|
||||
.footerGap {
|
||||
flex: 1 1 0;
|
||||
}
|
||||
|
||||
@@ -1,22 +1,32 @@
|
||||
/**
|
||||
* The in-app workspace-directory browser (figma Harness 813-23126 family): a
|
||||
* 600×420 dialog (clamped to short/narrow viewports — the Miller row scrolls
|
||||
* 680×500 dialog (clamped to short/narrow viewports — the Miller row scrolls
|
||||
* sideways, the columns scroll down) whose header carries the title, the selection-path
|
||||
* breadcrumb, and a click-to-edit path zone; below it a Miller view — one
|
||||
* full-width level until a row is selected, then two 256px columns (level |
|
||||
* selected folder's children) around a hairline divider. Selecting in the
|
||||
* 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 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
|
||||
* to the listed level. Pure consumer of the injected browse calls — the
|
||||
* owning flow decides what "Open" means and owns the workspace-creation
|
||||
* error surface. Hidden entries are host-flagged and filtered here (a
|
||||
* show-hidden toggle is deferred work, client-side only).
|
||||
* error surface. Hidden entries are host-flagged and hidden by default; the
|
||||
* footer's fixed-label "Show hidden files" toggle (aria-pressed, check when
|
||||
* on) reveals them (client-side only). The path editor opens seeded with a
|
||||
* trailing separator, and while the draft's directory part names a listed
|
||||
* level, its final segment prefix-filters that level's rows (a dot-led
|
||||
* prefix also reveals the hidden entries it names).
|
||||
*/
|
||||
import { useCallback, useEffect, useRef, useState } from 'react'
|
||||
import clsx from 'clsx'
|
||||
import {
|
||||
Button, IconChevronRightOutline14, IconFolderClose16, IconFolderOpen16, IconPlusOutline16, Modal,
|
||||
Button, IconCheckOutline16, IconChevronRightOutline14, IconFolderClose16, IconFolderOpen16, IconPlusOutline16, Modal,
|
||||
} from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
import type { DirectoryEntry, DirectoryListing } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import { DirectoryBrowseError } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
@@ -47,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
|
||||
@@ -59,17 +87,59 @@ function displayCrumbs(listing: DirectoryListing, homeLabel: string): DirectoryE
|
||||
return [{ name: homeLabel, path: listing.home, hidden: false }, ...tail]
|
||||
}
|
||||
|
||||
/**
|
||||
* The listing's platform separator, inferred from the home path the host
|
||||
* stamped — never from typed text or entry paths, where a backslash is a
|
||||
* legal POSIX name character. Still a heuristic at the last step: a POSIX
|
||||
* home directory whose own name contains a backslash would misread.
|
||||
* TODO: replace with a host-stamped `separator` field on the wire
|
||||
* DirectoryListing so the platform fact travels verbatim (the trade-off is
|
||||
* recorded in the directory-picker capability seam Agent Note).
|
||||
*/
|
||||
function separatorOf(listing: DirectoryListing): '\\' | '/' {
|
||||
return listing.home.includes('\\') ? '\\' : '/'
|
||||
}
|
||||
|
||||
/**
|
||||
* The path draft's final segment, when its directory part is exactly the
|
||||
* level `listing` lists — the segment the level prefix-filters on while the
|
||||
* user types. Any other draft (no separator yet, or naming some other
|
||||
* directory) leaves the level unfiltered. The directory part compares
|
||||
* exactly (it is the host's own path text, reached by seeding or erasing);
|
||||
* only the name filter downstream is case-insensitive.
|
||||
*/
|
||||
function draftPrefixFor(listing: DirectoryListing, draft: string | null): string | null {
|
||||
if (draft === null) return null
|
||||
const sep = separatorOf(listing)
|
||||
const cut = draft.lastIndexOf(sep)
|
||||
if (cut === -1) return null
|
||||
const level = listing.path.endsWith(sep) ? listing.path : `${listing.path}${sep}`
|
||||
return draft.slice(0, cut + 1) === level ? draft.slice(cut + 1) : null
|
||||
}
|
||||
|
||||
/** One column of folder rows (the Miller view renders one or two of these). */
|
||||
function LevelColumn({ entries, selectedPath, busy, onPick, wide }: {
|
||||
function LevelColumn({ entries, selectedPath, busy, onPick, showHidden, filterPrefix, pathEditing }: {
|
||||
entries: readonly DirectoryEntry[]
|
||||
selectedPath: string | null
|
||||
busy: boolean
|
||||
onPick: (entry: DirectoryEntry) => void
|
||||
wide: boolean
|
||||
showHidden: boolean
|
||||
filterPrefix: string | null
|
||||
pathEditing: boolean
|
||||
}) {
|
||||
const visible = entries.filter((entry) => {
|
||||
// The selection is exempt from both filters: it anchors the two-pane
|
||||
// view (crumbs and the child pane point at it), so neither the hidden
|
||||
// filter after a dot-reveal pick nor a prefix miss may orphan it.
|
||||
if (entry.path === selectedPath) return true
|
||||
if (filterPrefix !== null && !entry.name.toLowerCase().startsWith(filterPrefix.toLowerCase())) return false
|
||||
// A dot-led prefix names hidden entries explicitly, so matching ones
|
||||
// surface even while the toggle keeps the rest hidden.
|
||||
return showHidden || !entry.hidden || filterPrefix?.startsWith('.') === true
|
||||
})
|
||||
return (
|
||||
<div className={clsx(css.column, wide && css.columnWide)} role="list">
|
||||
{entries.filter(entry => !entry.hidden).map((entry) => {
|
||||
<div className={css.column} role="list">
|
||||
{visible.map((entry) => {
|
||||
const selected = entry.path === selectedPath
|
||||
return (
|
||||
// The wrapper carries the list semantics; the row keeps its NATIVE
|
||||
@@ -80,6 +150,15 @@ function LevelColumn({ entries, selectedPath, busy, onPick, wide }: {
|
||||
aria-current={selected || undefined}
|
||||
className={clsx(css.row, selected && css.rowSelected)}
|
||||
disabled={busy}
|
||||
// While the path editor is open, keep focus in it: a focus
|
||||
// steal on mousedown would blur the editor and (in engines
|
||||
// where the blur lands before our guards) drop this click.
|
||||
// Outside editing, rows keep native focus behavior.
|
||||
onMouseDown={pathEditing ? (event) => { event.preventDefault() } : undefined}
|
||||
// Editing-time focus parking happens after commit (the
|
||||
// DirectoryBrowser refocus effect): a right-pane pick replaces
|
||||
// this very column, so focusing the clicked node here would
|
||||
// still fall to body.
|
||||
onClick={() => { onPick(entry) }}
|
||||
>
|
||||
{selected
|
||||
@@ -107,9 +186,19 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
const [selected, setSelected] = useState<DirectoryEntry | null>(null)
|
||||
const [child, setChild] = useState<DirectoryListing | null>(null)
|
||||
const [loading, setLoading] = useState(false)
|
||||
// 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<string | null>(null)
|
||||
// Path-edit state: null = breadcrumb mode; a string = the draft being typed.
|
||||
const [pathDraft, setPathDraft] = useState<string | null>(null)
|
||||
// Show-hidden toggle state (pure client-side filter, reset on each open).
|
||||
const [showHidden, setShowHidden] = useState(false)
|
||||
// Create-folder state: null = closed; a string = the nested dialog's draft.
|
||||
const [folderDraft, setFolderDraft] = useState<string | null>(null)
|
||||
const [creatingFolder, setCreatingFolder] = useState(false)
|
||||
@@ -148,36 +237,128 @@ 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<DirectoryListing> } => {
|
||||
const seq = supersede()
|
||||
const controller = new AbortController()
|
||||
scanController.current = controller
|
||||
restartSlowScanWindow()
|
||||
return { seq, scan: listDirectory(path, controller.signal) }
|
||||
}, [supersede, listDirectory])
|
||||
}, [supersede, restartSlowScanWindow, listDirectory])
|
||||
|
||||
/** Replace the whole view with one freshly listed level (no selection). */
|
||||
/**
|
||||
* Launch a follow-up listing under the CURRENT supersession seq: a newer
|
||||
* intent aborts it like the leg it continues, and it supersedes nothing.
|
||||
*/
|
||||
const continueScan = useCallback((path: string): Promise<DirectoryListing> => {
|
||||
const controller = new AbortController()
|
||||
scanController.current = controller
|
||||
restartSlowScanWindow()
|
||||
return listDirectory(path, controller.signal)
|
||||
}, [restartSlowScanWindow, listDirectory])
|
||||
|
||||
/**
|
||||
* 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)
|
||||
setLoading(true)
|
||||
setError(null)
|
||||
scan.then((next) => {
|
||||
scan.then((target) => {
|
||||
if (seq !== requestSeq.current) return
|
||||
setParent(next)
|
||||
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) { 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) { landSingle(); return }
|
||||
continueScan(parentCrumb.path).then((parentLevel) => {
|
||||
if (seq !== requestSeq.current) return
|
||||
// Windows resolves a typed path preserving its case; anchor on the
|
||||
// parent level's actual entry so selection comparisons hold.
|
||||
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) { 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)
|
||||
}, () => {
|
||||
// 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)
|
||||
setError(failureText(reason))
|
||||
})
|
||||
}, [launchListing])
|
||||
}, [launchListing, continueScan])
|
||||
|
||||
/** Select a row of the listed level and preview its children on the right. */
|
||||
// Editor-close focus parking (consumed by the refocus effect below the
|
||||
// miller-row ref): a pick parks on the selection's row, Enter and an
|
||||
// input-focused Escape park on the crumb edit zone that replaces the
|
||||
// input. Pointer-out cancels never set (or clear) these — yanking focus
|
||||
// back from wherever the user clicked would be worse than the fall.
|
||||
const refocusPick = useRef(false)
|
||||
const refocusEditZone = useRef(false)
|
||||
const pathInputRef = useRef<HTMLInputElement | null>(null)
|
||||
const editZoneRef = useRef<HTMLButtonElement | null>(null)
|
||||
|
||||
/**
|
||||
* 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
|
||||
// closes the editor — the draft served its purpose. Focus re-parks on
|
||||
// the selection after commit (see the refocus effect below).
|
||||
if (pathDraft !== null) refocusPick.current = true
|
||||
setPathDraft(null)
|
||||
setSelected(entry)
|
||||
setChild(null)
|
||||
setLoading(true)
|
||||
@@ -193,8 +374,31 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
// An unreadable selection cannot be the committing target while the
|
||||
// breadcrumb still names the level: fall back to the single pane.
|
||||
setSelected(null)
|
||||
// Clearing the selection can unmount the very row the pick parked
|
||||
// focus on (a dot-revealed hidden row re-hides); the refocus effect
|
||||
// re-parks on the edit zone only if focus actually fell to body.
|
||||
refocusEditZone.current = true
|
||||
})
|
||||
}, [launchListing])
|
||||
}, [launchListing, pathDraft])
|
||||
|
||||
/** Abandon path editing (Escape or clicking away) and restore the crumb view. */
|
||||
const cancelPathEdit = useCallback(() => {
|
||||
// Cancel also withdraws a navigation the editor already launched: its
|
||||
// late success must not jump to the cancelled path, so the pending
|
||||
// request is superseded and the view leaves the loading state.
|
||||
supersede()
|
||||
setLoading(false)
|
||||
setPathDraft(null)
|
||||
setError(null)
|
||||
// Editing may have superseded the selection's preview request; a
|
||||
// selection with no preview would render a half-empty two-pane view, so
|
||||
// cancel falls back to the single-pane level.
|
||||
if (child === null) setSelected(null)
|
||||
// With no level listed yet (the editor superseded the initial home
|
||||
// listing), plain cancellation would leave a permanently blank picker:
|
||||
// restart the home listing.
|
||||
if (parent === null) navigate()
|
||||
}, [supersede, child, parent, navigate])
|
||||
|
||||
/** A right-column pick advances the view one level: child becomes the level. */
|
||||
const advance = useCallback((entry: DirectoryEntry) => {
|
||||
@@ -213,14 +417,24 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
setSelected(null)
|
||||
setChild(null)
|
||||
setCreatingFolder(false)
|
||||
setShowHidden(false)
|
||||
navigate()
|
||||
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)
|
||||
setCreateError(null)
|
||||
// A close mid-flight (failed Enter, then Cancel) may leave refocus
|
||||
// flags armed; retire them so a later render cannot consume them.
|
||||
refocusPick.current = false
|
||||
refocusEditZone.current = false
|
||||
}, [open, navigate, supersede])
|
||||
|
||||
/** The folder a create or Open acts on: the selection, else the listed level. */
|
||||
@@ -249,6 +463,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
|
||||
@@ -268,6 +486,19 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
})
|
||||
}
|
||||
|
||||
// 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)
|
||||
return
|
||||
}
|
||||
const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS)
|
||||
return () => { window.clearTimeout(timer) }
|
||||
}, [loading, scanWindow])
|
||||
|
||||
// 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'))
|
||||
@@ -285,6 +516,37 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
const row = millerRowRef.current
|
||||
if (row !== null && childPath !== undefined) row.scrollLeft = row.scrollWidth
|
||||
}, [childPath])
|
||||
// Every editor exit that would drop focus to body re-parks it after
|
||||
// commit, so keyboard traversal stays inside the dialog (the Modal has no
|
||||
// focus trap): a pick lands on the selection's row — aria-current in the
|
||||
// freshly rendered left pane, which survives even a right-pane advance
|
||||
// replacing the picked button's column — while Enter and an input-focused
|
||||
// Escape land on the crumb edit zone that replaces the input.
|
||||
useEffect(() => {
|
||||
if (pathDraft !== null) return
|
||||
if (refocusPick.current) {
|
||||
refocusPick.current = false
|
||||
refocusEditZone.current = false
|
||||
const rowHost = millerRowRef.current
|
||||
/* v8 ignore next -- narrowing guard: the miller row is mounted whenever a pick just committed. */
|
||||
if (rowHost === null) return
|
||||
const row = rowHost.querySelector<HTMLButtonElement>('button[aria-current="true"]')
|
||||
/* v8 ignore next -- narrowing guard: the pick that set the flag just rendered its aria-current row. */
|
||||
if (row === null) return
|
||||
row.focus()
|
||||
return
|
||||
}
|
||||
if (refocusEditZone.current) {
|
||||
refocusEditZone.current = false
|
||||
// Re-park only when the close actually dropped focus to body; focus
|
||||
// the user parked elsewhere (a surviving row) stays theirs.
|
||||
if (document.activeElement !== document.body) return
|
||||
const zone = editZoneRef.current
|
||||
/* v8 ignore next -- narrowing guard: crumb mode renders the edit zone whenever the editor just closed. */
|
||||
if (zone === null) return
|
||||
zone.focus()
|
||||
}
|
||||
})
|
||||
|
||||
if (!open) return null
|
||||
const twoPane = selected !== null
|
||||
@@ -310,149 +572,220 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
|
||||
className={clsx(css.dialog)}
|
||||
headless
|
||||
>
|
||||
<div className={css.header}>
|
||||
<h2 className={css.title}>{t('browser.title')}</h2>
|
||||
<div className={css.crumbBar}>
|
||||
{pathDraft === null
|
||||
? (
|
||||
<>
|
||||
<span className={css.crumbTrail} role="navigation" ref={crumbTrailRef}>
|
||||
{crumbs.map((crumb, index) => (
|
||||
<span key={crumb.path} className={css.crumbSeat}>
|
||||
{index > 0 && <IconChevronRightOutline14 size={12} className={css.crumbChevron} />}
|
||||
<button
|
||||
type="button"
|
||||
className={css.crumb}
|
||||
disabled={parentInert}
|
||||
onClick={() => { navigate(crumb.path) }}
|
||||
>
|
||||
{crumb.name}
|
||||
</button>
|
||||
</span>
|
||||
))}
|
||||
</span>
|
||||
{/* The empty zone right of the crumbs is the path-edit affordance. */}
|
||||
<button
|
||||
type="button"
|
||||
className={css.crumbEditZone}
|
||||
aria-label={t('browser.editPath')}
|
||||
// Stays available with no listed level: when the home
|
||||
// listing itself fails, typing an absolute path is the one
|
||||
// remaining way forward.
|
||||
disabled={parentInert}
|
||||
onClick={() => {
|
||||
{/* Path-edit cancellation is observed at the card scope, not the
|
||||
* input: once Tab parks focus on a filtered row the input is off the
|
||||
* event path, yet Escape must still collapse the editor (not the
|
||||
* dialog) and a further focus move out of the card must still
|
||||
* cancel. display:contents keeps header/content/footer as direct
|
||||
* flex children of the Modal card. */}
|
||||
<div
|
||||
className={css.editorScope}
|
||||
onKeyDown={(event) => {
|
||||
if (event.key !== 'Escape' || pathDraft === null) return
|
||||
// stopPropagation keeps the card-scope Escape from the Modal's
|
||||
// document listener — the same containment the input previously
|
||||
// provided for itself.
|
||||
event.stopPropagation()
|
||||
// Escape while the input holds focus is about to unmount it; with
|
||||
// focus already parked on a row, that row survives the cancel and
|
||||
// keeps focus naturally. Assignment (not a conditional set) also
|
||||
// retires a stale flag a failed or still-upgrading Enter left.
|
||||
refocusEditZone.current = document.activeElement === pathInputRef.current
|
||||
cancelPathEdit()
|
||||
}}
|
||||
// Focus leaving THIS dialog card while editing cancels like Escape.
|
||||
// Guarded non-cancel paths: window/tab focus loss (document no
|
||||
// longer focused); a focus move that stays inside the card (Tab
|
||||
// onto the filtered rows or the footer toggle); and pointer paths,
|
||||
// where rows and the toggle suppress focus steal on mousedown while
|
||||
// editing so their click lands first. Enter keeps focus in the
|
||||
// input while its navigation is in flight, so a submitted path is
|
||||
// never withdrawn here. Anchored to this card via closest, not any
|
||||
// [role="dialog"], so focus escaping into a sibling overlay cancels.
|
||||
onBlur={(event) => {
|
||||
if (pathDraft === null) return
|
||||
if (!document.hasFocus()) return
|
||||
const card = event.currentTarget.closest('[role="dialog"]')
|
||||
/* v8 ignore next -- narrowing guard: this scope always renders inside the Modal card. */
|
||||
if (card === null) return
|
||||
if (event.relatedTarget instanceof Node && card.contains(event.relatedTarget)) return
|
||||
// The user moved focus out of the card themselves: cancel without
|
||||
// re-parking (a lingering Enter-failure flag must not yank focus
|
||||
// back either).
|
||||
refocusEditZone.current = false
|
||||
cancelPathEdit()
|
||||
}}
|
||||
>
|
||||
<div className={css.header}>
|
||||
<h2 className={css.title}>{t('browser.title')}</h2>
|
||||
<div className={css.crumbBar}>
|
||||
{pathDraft === null
|
||||
? (
|
||||
<>
|
||||
<span className={css.crumbTrail} role="navigation" ref={crumbTrailRef}>
|
||||
{crumbs.map((crumb, index) => (
|
||||
<span key={crumb.path} className={css.crumbSeat}>
|
||||
{index > 0 && <IconChevronRightOutline14 size={12} className={css.crumbChevron} />}
|
||||
<button
|
||||
type="button"
|
||||
className={css.crumb}
|
||||
disabled={parentInert}
|
||||
onClick={() => { navigate(crumb.path) }}
|
||||
>
|
||||
{crumb.name}
|
||||
</button>
|
||||
</span>
|
||||
))}
|
||||
</span>
|
||||
{/* The empty zone right of the crumbs is the path-edit affordance. */}
|
||||
<button
|
||||
type="button"
|
||||
className={css.crumbEditZone}
|
||||
aria-label={t('browser.editPath')}
|
||||
// Stays available with no listed level: when the home
|
||||
// listing itself fails, typing an absolute path is the one
|
||||
// remaining way forward.
|
||||
disabled={parentInert}
|
||||
ref={editZoneRef}
|
||||
onClick={() => {
|
||||
// Opening the editor supersedes any pending listing: a
|
||||
// settlement landing before the first keystroke would
|
||||
// otherwise close the editor via navigate's draft reset.
|
||||
supersede()
|
||||
setLoading(false)
|
||||
setPathDraft(selected?.path ?? parent?.path ?? '')
|
||||
}}
|
||||
/>
|
||||
</>
|
||||
)
|
||||
: (
|
||||
<input
|
||||
className={css.pathInput}
|
||||
value={pathDraft}
|
||||
aria-label={t('browser.editPath')}
|
||||
autoFocus
|
||||
disabled={parentInert}
|
||||
onChange={(event) => {
|
||||
supersede()
|
||||
setLoading(false)
|
||||
// Seed with a trailing separator so typing immediately
|
||||
// continues into child names (and prefix-filters below).
|
||||
// No listed level means nothing to seed from (the editor
|
||||
// is the recovery path for a failed home listing).
|
||||
if (parent === null) {
|
||||
setPathDraft('')
|
||||
return
|
||||
}
|
||||
const base = selected?.path ?? parent.path
|
||||
const sep = separatorOf(parent)
|
||||
setPathDraft(base.endsWith(sep) ? base : `${base}${sep}`)
|
||||
}}
|
||||
/>
|
||||
</>
|
||||
)
|
||||
: (
|
||||
<input
|
||||
className={css.pathInput}
|
||||
value={pathDraft}
|
||||
aria-label={t('browser.editPath')}
|
||||
autoFocus
|
||||
ref={pathInputRef}
|
||||
disabled={parentInert}
|
||||
onChange={(event) => {
|
||||
// Editing the draft supersedes any in-flight navigation:
|
||||
// its completion must neither clear the newer text nor
|
||||
// repopulate the view with the older path.
|
||||
supersede()
|
||||
setLoading(false)
|
||||
setPathDraft(event.target.value)
|
||||
}}
|
||||
{...compositionGuard}
|
||||
onKeyDown={(event) => {
|
||||
if (event.key === 'Enter' && !composingRef.current) {
|
||||
event.preventDefault()
|
||||
// Trim only detects a blank draft; the Host gets the
|
||||
// original text — a real directory name may end in
|
||||
// whitespace, and trimming would list its sibling.
|
||||
if (pathDraft.trim() !== '') navigate(pathDraft)
|
||||
}
|
||||
if (event.key === 'Escape') {
|
||||
event.stopPropagation()
|
||||
// Cancel also withdraws a navigation the editor already
|
||||
// launched: its late success must not jump to the
|
||||
// cancelled path, so the pending request is superseded
|
||||
// and the view leaves the loading state.
|
||||
supersede()
|
||||
setLoading(false)
|
||||
setPathDraft(null)
|
||||
setError(null)
|
||||
// Editing may have superseded the selection's preview
|
||||
// request; a selection with no preview would render a
|
||||
// half-empty two-pane view, so cancel falls back to the
|
||||
// single-pane level.
|
||||
if (child === null) setSelected(null)
|
||||
// With no level listed yet (the editor superseded the
|
||||
// initial home listing), plain cancellation would leave a
|
||||
// permanently blank picker: restart the home listing.
|
||||
if (parent === null) navigate()
|
||||
}
|
||||
}}
|
||||
setPathDraft(event.target.value)
|
||||
}}
|
||||
{...compositionGuard}
|
||||
// Escape and focus-leave cancellation live on the card-scope
|
||||
// wrapper above (they must work after focus Tabs onto the
|
||||
// rows); this handler owns only submission.
|
||||
onKeyDown={(event) => {
|
||||
if (event.key === 'Enter' && !composingRef.current) {
|
||||
event.preventDefault()
|
||||
// Trim only detects a blank draft; the Host gets the
|
||||
// original text — a real directory name may end in
|
||||
// whitespace, and trimming would list its sibling.
|
||||
if (pathDraft.trim() !== '') {
|
||||
// Success will unmount the still-focused input; park
|
||||
// focus on the returning crumb edit zone (a failure
|
||||
// keeps the editor, so the flag waits until close).
|
||||
refocusEditZone.current = true
|
||||
navigate(pathDraft)
|
||||
}
|
||||
}
|
||||
}}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
<div className={css.content}>
|
||||
<div className={css.millerRow} ref={millerRowRef}>
|
||||
{parent !== null && (
|
||||
<LevelColumn
|
||||
entries={parent.entries}
|
||||
selectedPath={selected?.path ?? null}
|
||||
busy={parentInert}
|
||||
onPick={select}
|
||||
showHidden={showHidden}
|
||||
filterPrefix={draftPrefixFor(parent, pathDraft)}
|
||||
pathEditing={draftPending}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
<div className={css.content}>
|
||||
<div className={css.millerRow} ref={millerRowRef}>
|
||||
{parent !== null && (
|
||||
<LevelColumn
|
||||
entries={parent.entries}
|
||||
selectedPath={selected?.path ?? null}
|
||||
busy={parentInert}
|
||||
onPick={select}
|
||||
wide={!twoPane}
|
||||
/>
|
||||
)}
|
||||
{twoPane && <span className={css.divider} />}
|
||||
{twoPane && child !== null && (
|
||||
<LevelColumn
|
||||
entries={child.entries}
|
||||
selectedPath={null}
|
||||
busy={parentInert}
|
||||
onPick={advance}
|
||||
wide={false}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
{loading && <div className={css.status} role="status">{t('browser.loading')}</div>}
|
||||
{/* The backend bounds a level at its complete-result limit; say so
|
||||
{twoPane && <span className={css.divider} />}
|
||||
{twoPane && child !== null && (
|
||||
<LevelColumn
|
||||
entries={child.entries}
|
||||
selectedPath={null}
|
||||
busy={parentInert}
|
||||
onPick={advance}
|
||||
showHidden={showHidden}
|
||||
filterPrefix={draftPrefixFor(child, pathDraft)}
|
||||
pathEditing={draftPending}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
{loading && slowScan
|
||||
&& <div className={clsx(css.status, css.loadingFloat)} role="status">{t('browser.loading')}</div>}
|
||||
{/* 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)
|
||||
&& <div className={css.status} role="status">{t('browser.truncated')}</div>}
|
||||
{error !== null && <div className={css.error} role="alert">{error}</div>}
|
||||
</div>
|
||||
<div className={css.footerBar}>
|
||||
<Button
|
||||
variant="outline"
|
||||
icon={<IconPlusOutline16 size={14} />}
|
||||
disabled={parent === null || loading || parentInert || draftPending}
|
||||
onClick={() => {
|
||||
setFolderDraft('')
|
||||
setCreateError(null)
|
||||
}}
|
||||
>
|
||||
{t('browser.newFolder')}
|
||||
</Button>
|
||||
<span className={css.footerGap} />
|
||||
<Button variant="outline" className={clsx(css.footerAction)} disabled={parentInert} onClick={onClose}>{t('browser.cancel')}</Button>
|
||||
<Button
|
||||
variant="primary"
|
||||
className={clsx(css.footerAction)}
|
||||
disabled={targetPath === null || loading || parentInert || draftPending}
|
||||
/* v8 ignore next -- narrowing guard: Open disables while no target exists. */
|
||||
onClick={() => { if (targetPath !== null) onOpen(targetPath) }}
|
||||
>
|
||||
{t('browser.open')}
|
||||
</Button>
|
||||
{error !== null && <div className={css.error} role="alert">{error}</div>}
|
||||
</div>
|
||||
<div className={css.footerBar}>
|
||||
<Button
|
||||
variant="outline"
|
||||
icon={<IconPlusOutline16 size={14} />}
|
||||
disabled={parent === null || loading || parentInert || draftPending}
|
||||
onClick={() => {
|
||||
setFolderDraft('')
|
||||
setCreateError(null)
|
||||
}}
|
||||
>
|
||||
{t('browser.newFolder')}
|
||||
</Button>
|
||||
<button
|
||||
type="button"
|
||||
className={clsx(css.showHiddenToggle, showHidden && css.showHiddenToggleActive)}
|
||||
aria-pressed={showHidden}
|
||||
disabled={parentInert}
|
||||
// The toggle composes with the path editor (dot-led prefixes and
|
||||
// this filter interleave): while editing, don't steal focus, so
|
||||
// toggling never blur-cancels a draft mid-thought. Outside editing
|
||||
// it keeps native focus behavior.
|
||||
onMouseDown={draftPending ? (event) => { event.preventDefault() } : undefined}
|
||||
onClick={() => { setShowHidden(prev => !prev) }}
|
||||
>
|
||||
{t('browser.showHidden')}
|
||||
{/* Trailing check (Menu's selected vocabulary): the label never
|
||||
* shifts when the pressed state toggles. */}
|
||||
{showHidden && <IconCheckOutline16 size={14} />}
|
||||
</button>
|
||||
<span className={css.footerGap} />
|
||||
<Button variant="outline" className={clsx(css.footerAction)} disabled={parentInert} onClick={onClose}>{t('browser.cancel')}</Button>
|
||||
<Button
|
||||
variant="primary"
|
||||
className={clsx(css.footerAction)}
|
||||
disabled={targetPath === null || loading || parentInert || draftPending}
|
||||
/* v8 ignore next -- narrowing guard: Open disables while no target exists. */
|
||||
onClick={() => { if (targetPath !== null) onOpen(targetPath) }}
|
||||
>
|
||||
{t('browser.open')}
|
||||
</Button>
|
||||
</div>
|
||||
</div>
|
||||
{/* Nested create dialog (figma 813:23278): names one folder inside the target. */}
|
||||
<Modal
|
||||
|
||||
@@ -46,6 +46,7 @@ export function apply(ctx: ClientContext): void {
|
||||
'browser.editPath': '编辑路径',
|
||||
'browser.loading': '加载中…',
|
||||
'browser.truncated': '文件夹过多，仅显示开头部分。',
|
||||
'browser.showHidden': '显示隐藏文件',
|
||||
}],
|
||||
['en', {
|
||||
'browser.title': 'Select Workspace Directory',
|
||||
@@ -60,6 +61,7 @@ export function apply(ctx: ClientContext): void {
|
||||
'browser.editPath': 'Edit path',
|
||||
'browser.loading': 'Loading…',
|
||||
'browser.truncated': 'Too many folders to list; only the beginning is shown.',
|
||||
'browser.showHidden': 'Show hidden files',
|
||||
}],
|
||||
]
|
||||
try {
|
||||
|
||||
@@ -162,6 +162,7 @@ describe('directory-picker-browse client half', () => {
|
||||
// zh is the shipped default locale.
|
||||
expect(injected.t('browser.title')).toBe('选择工作区目录')
|
||||
expect(injected.t('browser.newFolder')).toBe('新建文件夹')
|
||||
expect(injected.t('browser.showHidden')).toBe('显示隐藏文件')
|
||||
})
|
||||
|
||||
it('drives the injected browse calls through the hole entry', async () => {
|
||||
|
||||
@@ -29,6 +29,25 @@ function listingFor(path?: string): DirectoryListing {
|
||||
],
|
||||
truncated: false,
|
||||
},
|
||||
'/': {
|
||||
path: '/',
|
||||
home: HOME,
|
||||
crumbs: [{ name: '/', path: '/', hidden: false }],
|
||||
entries: [{ name: 'home', path: '/home', hidden: false }],
|
||||
truncated: false,
|
||||
},
|
||||
[`${HOME}/.config`]: {
|
||||
path: `${HOME}/.config`,
|
||||
home: HOME,
|
||||
crumbs: [
|
||||
{ name: '/', path: '/', hidden: false },
|
||||
{ name: 'home', path: '/home', hidden: false },
|
||||
{ name: 'u', path: HOME, hidden: false },
|
||||
{ name: '.config', path: `${HOME}/.config`, hidden: true },
|
||||
],
|
||||
entries: [],
|
||||
truncated: false,
|
||||
},
|
||||
[DOCS]: {
|
||||
path: DOCS,
|
||||
home: HOME,
|
||||
@@ -92,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() })
|
||||
@@ -103,6 +128,28 @@ describe('DirectoryBrowser', () => {
|
||||
expect(screen.queryByRole('button', { name: '/' })).toBeNull()
|
||||
})
|
||||
|
||||
it('shows hidden entries when the toggle is on and hides them again on close', async () => {
|
||||
const b = mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
expect(screen.queryByText('.config')).toBeNull()
|
||||
// The fixed-label toggle reports its state through aria-pressed. Its
|
||||
// mousedown never steals focus (so it composes with the path editor).
|
||||
const toggle = screen.getByRole('button', { name: 'browser.showHidden' })
|
||||
expect(toggle.getAttribute('aria-pressed')).toBe('false')
|
||||
fireEvent.mouseDown(toggle)
|
||||
fireEvent.click(toggle)
|
||||
expect(toggle.getAttribute('aria-pressed')).toBe('true')
|
||||
expect(screen.getByText('.config')).toBeTruthy()
|
||||
fireEvent.click(toggle)
|
||||
expect(toggle.getAttribute('aria-pressed')).toBe('false')
|
||||
expect(screen.queryByText('.config')).toBeNull()
|
||||
// Close resets the toggle.
|
||||
b.view.rerender(<DirectoryBrowser {...b.props} open={false} />)
|
||||
b.view.rerender(<DirectoryBrowser {...b.props} open />)
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
expect(screen.queryByText('.config')).toBeNull()
|
||||
})
|
||||
|
||||
it('selects a row into the two-pane view: children preview right, crumbs follow the selection', async () => {
|
||||
const b = mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
@@ -153,7 +200,7 @@ describe('DirectoryBrowser', () => {
|
||||
expect(signals[2]?.aborted).toBe(true)
|
||||
})
|
||||
|
||||
it('jumps back through a crumb into a fresh single-column level', async () => {
|
||||
it('a crumb jump to the display root (home) lands the single wide level', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(rowButton(screen.getByRole('listitem')))
|
||||
@@ -164,6 +211,393 @@ describe('DirectoryBrowser', () => {
|
||||
expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull()
|
||||
})
|
||||
|
||||
it('a crumb jump away from the root lands two-pane with the target selected', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(rowButton(screen.getByRole('listitem')))
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
fireEvent.click(rowButton(within(columns()[1]!).getByRole('listitem')))
|
||||
await waitFor(() => { expect(screen.getByRole('button', { name: 'harness' })).toBeTruthy() })
|
||||
// Jumping to the Documents crumb is a step BACK one pane, not a
|
||||
// collapse: Documents stays selected in the home level, its children
|
||||
// stay on the right.
|
||||
fireEvent.click(screen.getByRole('button', { name: 'Documents' }))
|
||||
await waitFor(() => {
|
||||
expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
|
||||
})
|
||||
expect(columns()).toHaveLength(2)
|
||||
expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
|
||||
expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
|
||||
})
|
||||
|
||||
it('a navigation to the filesystem root keeps the single wide level', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: '/' } })
|
||||
fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
|
||||
// A one-crumb chain has no parent level to show on the left.
|
||||
await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('home') })
|
||||
expect(columns()).toHaveLength(1)
|
||||
})
|
||||
|
||||
it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => {
|
||||
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<DirectoryListing>((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<HTMLInputElement>('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()
|
||||
}
|
||||
})
|
||||
|
||||
/**
|
||||
* 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<string, (value: DirectoryListing) => void>()
|
||||
const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => {
|
||||
if (path === undefined) return Promise.resolve(listingFor(path))
|
||||
return new Promise<DirectoryListing>((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<HTMLInputElement>('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<HTMLInputElement>('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(1) })
|
||||
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<HTMLInputElement>('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 {
|
||||
// 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<string, (value: DirectoryListing) => void>()
|
||||
const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => {
|
||||
if (path === undefined) return Promise.resolve({ ...listingFor(path), truncated: true })
|
||||
return new Promise<DirectoryListing>((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<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
|
||||
fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
|
||||
// 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 — 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, 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('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<DirectoryListing>((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 {
|
||||
// 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<DirectoryListing>((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(<DirectoryBrowser {...props} open={false} />)
|
||||
view.rerender(<DirectoryBrowser {...props} open />)
|
||||
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
|
||||
// that misses Documents (the initial open uses the absent-path form).
|
||||
if (path === HOME) return { ...listingFor(HOME), entries: [], truncated: true }
|
||||
return listingFor(path)
|
||||
})
|
||||
mount({ listDirectory })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
|
||||
fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
|
||||
// The upgrade would orphan the selection (no source row): it stays off.
|
||||
await act(async () => {})
|
||||
expect(columns()).toHaveLength(1)
|
||||
expect(screen.queryByText('browser.truncated')).toBeNull()
|
||||
})
|
||||
|
||||
it('anchors the upgrade on the parent level actual entry under Windows case folding', async () => {
|
||||
const ROOT = 'C:\\'
|
||||
const TYPED = 'c:\\users'
|
||||
const winRoot: DirectoryListing = {
|
||||
path: ROOT,
|
||||
home: ROOT,
|
||||
crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }],
|
||||
entries: [{ name: 'Users', path: 'C:\\Users', hidden: false }],
|
||||
truncated: false,
|
||||
}
|
||||
const winUsers: DirectoryListing = {
|
||||
path: TYPED,
|
||||
home: ROOT,
|
||||
crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }, { name: 'users', path: TYPED, hidden: false }],
|
||||
entries: [],
|
||||
truncated: false,
|
||||
}
|
||||
mount({ listDirectory: vi.fn(async (path?: string) => (path === TYPED ? winUsers : winRoot)) })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: TYPED } })
|
||||
fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
|
||||
// The typed case differs from the real entry; the upgrade selects the
|
||||
// parent level's ACTUAL entry so aria-current and exemptions hold.
|
||||
await waitFor(() => {
|
||||
expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
|
||||
})
|
||||
expect(within(columns()[0]!).getByText('Users')).toBeTruthy()
|
||||
})
|
||||
|
||||
it('re-parks focus on the edit zone when a failed pick unmounts a dot-revealed row', async () => {
|
||||
const listDirectory = vi.fn(async (path?: string) => {
|
||||
if (path === `${HOME}/.config`) {
|
||||
throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'denied', details: { path } })
|
||||
}
|
||||
return listingFor(path)
|
||||
})
|
||||
mount({ listDirectory })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: `${HOME}/.co` } })
|
||||
const row = rowButton(screen.getByRole('listitem'))
|
||||
fireEvent.mouseDown(row)
|
||||
fireEvent.click(row)
|
||||
// The failed selection re-hides the picked row; focus fell to body and
|
||||
// re-parks on the crumb edit zone.
|
||||
await screen.findByRole('alert')
|
||||
expect(screen.queryByText('.config')).toBeNull()
|
||||
expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
})
|
||||
|
||||
it('leaves focus on a surviving row when its pick fails', async () => {
|
||||
const listDirectory = vi.fn(async (path?: string) => {
|
||||
if (path === DOCS) {
|
||||
throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'denied', details: { path } })
|
||||
}
|
||||
return listingFor(path)
|
||||
})
|
||||
mount({ listDirectory })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: `${HOME}/do` } })
|
||||
const row = rowButton(screen.getByRole('listitem'))
|
||||
row.focus()
|
||||
fireEvent.mouseDown(row)
|
||||
fireEvent.click(row)
|
||||
// Documents survives the cleared selection (it is not hidden): the
|
||||
// user's focus on it is not yanked to the edit zone.
|
||||
await screen.findByRole('alert')
|
||||
expect(document.activeElement).toBe(row)
|
||||
})
|
||||
|
||||
it('falls back to the single-pane landing when the parent leg of a navigation fails', async () => {
|
||||
const listDirectory = vi.fn(async (path?: string) => {
|
||||
// The initial open lists home through the absent-path form; only the
|
||||
// parent leg names HOME explicitly.
|
||||
if (path === HOME) {
|
||||
throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'parent gone', details: { path } })
|
||||
}
|
||||
return listingFor(path)
|
||||
})
|
||||
mount({ listDirectory })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
|
||||
fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
|
||||
// The target listed fine; the failed parent leg neither blocks the
|
||||
// landing nor surfaces an error for a level nobody asked to see.
|
||||
await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
|
||||
expect(columns()).toHaveLength(1)
|
||||
expect(screen.queryByRole('alert')).toBeNull()
|
||||
})
|
||||
|
||||
it('opens the selection, else the listed level; Cancel closes; busy freezes Open', async () => {
|
||||
const b = mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
@@ -186,18 +620,221 @@ describe('DirectoryBrowser', () => {
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
expect(input.value).toBe(HOME)
|
||||
// The editor seeds with a trailing separator so typing continues into
|
||||
// child names.
|
||||
expect(input.value).toBe(`${HOME}/`)
|
||||
fireEvent.change(input, { target: { value: DOCS } })
|
||||
fireEvent.keyDown(input, { key: 'Enter' })
|
||||
await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
|
||||
expect(columns()).toHaveLength(1)
|
||||
// Away from the root a navigation lands two-pane: the target selected
|
||||
// in its parent level, its own children on the right.
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
|
||||
expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
|
||||
// The submitted navigation unmounted the focused input; focus parks on
|
||||
// the crumb edit zone that replaced it.
|
||||
expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const again = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(again, { target: { value: ' ' } })
|
||||
fireEvent.keyDown(again, { key: 'Enter' })
|
||||
expect(b.listDirectory).toHaveBeenCalledTimes(2)
|
||||
// Initial home + the DOCS target leg + its parent leg; the blank draft
|
||||
// added none.
|
||||
expect(b.listDirectory).toHaveBeenCalledTimes(3)
|
||||
fireEvent.keyDown(again, { key: 'Escape' })
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
// Escape with focus in the input parks focus on the returning edit zone.
|
||||
expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
})
|
||||
|
||||
it('prefix-filters the listed level from the draft tail, dot revealing hidden matches', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
// The seeded empty segment leaves the level as-is: hidden stays hidden.
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
// Case-insensitive prefix narrows the rows.
|
||||
fireEvent.change(input, { target: { value: `${HOME}/do` } })
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
// A dot-led prefix names hidden entries, so it reveals the match.
|
||||
fireEvent.change(input, { target: { value: `${HOME}/.co` } })
|
||||
expect(screen.getByRole('listitem').textContent).toBe('.config')
|
||||
// A prefix matching nothing empties the level (no stale rows linger).
|
||||
fireEvent.change(input, { target: { value: `${HOME}/zzz` } })
|
||||
expect(screen.queryByRole('listitem')).toBeNull()
|
||||
// A draft naming some other directory (or none) leaves the level whole.
|
||||
fireEvent.change(input, { target: { value: 'no-separator' } })
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
})
|
||||
|
||||
it('filters the child pane in two-pane mode and follows the draft back up a level', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(rowButton(screen.getByRole('listitem')))
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
// The seed comes from the selection, so the draft tail addresses the
|
||||
// RIGHT pane (the selection's children).
|
||||
expect(input.value).toBe(`${DOCS}/`)
|
||||
fireEvent.change(input, { target: { value: `${DOCS}/h` } })
|
||||
expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
|
||||
fireEvent.change(input, { target: { value: `${DOCS}/zzz` } })
|
||||
expect(within(columns()[1]!).queryAllByRole('listitem')).toHaveLength(0)
|
||||
expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
|
||||
// Erasing back into the parent's own path moves the filter to the LEFT
|
||||
// pane and releases the right one. The selected row is exempt (it
|
||||
// anchors the two-pane view), so it alone survives the miss.
|
||||
fireEvent.change(input, { target: { value: `${HOME}/zz` } })
|
||||
expect(within(columns()[0]!).getAllByRole('listitem').map(item => item.textContent)).toEqual(['Documents'])
|
||||
expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
|
||||
})
|
||||
|
||||
it('keeps the draft and filter through window focus loss and in-dialog focus moves', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: `${HOME}/do` } })
|
||||
// A blur while the document itself lost focus (window switch, dev-tools
|
||||
// focus) must not discard the draft: value and filter both survive.
|
||||
const hasFocus = vi.spyOn(document, 'hasFocus').mockReturnValue(false)
|
||||
fireEvent.focusOut(input)
|
||||
hasFocus.mockRestore()
|
||||
expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
// A keyboard focus move that stays inside the dialog (Tab onto the
|
||||
// filtered row) keeps the draft too — the results stay reachable.
|
||||
fireEvent.focusOut(input, { relatedTarget: rowButton(screen.getByRole('listitem')) })
|
||||
expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
|
||||
// Toggling show-hidden mid-edit suppresses focus steal: the draft and
|
||||
// its filter survive the toggle in both directions.
|
||||
const toggle = screen.getByRole('button', { name: 'browser.showHidden' })
|
||||
fireEvent.mouseDown(toggle)
|
||||
fireEvent.click(toggle)
|
||||
expect(toggle.getAttribute('aria-pressed')).toBe('true')
|
||||
expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
// Focus landing outside the dialog cancels like Escape — even when the
|
||||
// departure happens from a row the user had Tabbed onto, not the input
|
||||
// (the observer lives on the card scope, not the input).
|
||||
fireEvent.focusOut(rowButton(screen.getByRole('listitem')), { relatedTarget: document.body })
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
// Outside editing the card-scope observer is inert.
|
||||
fireEvent.focusOut(screen.getByRole('button', { name: 'browser.showHidden' }))
|
||||
expect(screen.getByRole('button', { name: 'browser.editPath' })).toBeTruthy()
|
||||
})
|
||||
|
||||
it('Escape with focus on a filtered row collapses the editor, not the dialog', async () => {
|
||||
const b = mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: `${HOME}/do` } })
|
||||
// Tab parked focus on the result row; Escape must still mean "leave
|
||||
// path editing", not "close the whole dialog".
|
||||
const row = rowButton(screen.getByRole('listitem'))
|
||||
row.focus()
|
||||
fireEvent.keyDown(row, { key: 'Escape' })
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
expect(b.onClose).not.toHaveBeenCalled()
|
||||
// Focus was already on a surviving row, so nothing re-parks it.
|
||||
expect(document.activeElement).toBe(row)
|
||||
// With no draft left, Escape falls through to the Modal and closes.
|
||||
fireEvent.keyDown(row, { key: 'Escape' })
|
||||
expect(b.onClose).toHaveBeenCalledTimes(1)
|
||||
})
|
||||
|
||||
it('a picked dot-revealed hidden row stays visible as the selection', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: `${HOME}/.co` } })
|
||||
const row = rowButton(screen.getByRole('listitem'))
|
||||
expect(row.textContent).toBe('.config')
|
||||
fireEvent.mouseDown(row)
|
||||
fireEvent.click(row)
|
||||
// The pick cleared the draft (and with it the dot-reveal), but the
|
||||
// selection is exempt from the hidden filter: the anchor row survives.
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
expect(within(columns()[0]!).getByText('.config')).toBeTruthy()
|
||||
})
|
||||
|
||||
it('picking a filtered row adopts it and closes the path editor', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: `${HOME}/do` } })
|
||||
// The row suppresses focus steal on mousedown (no blur-cancel unmounts
|
||||
// the filtered rows mid-gesture), then the click both selects the row
|
||||
// and closes the editor.
|
||||
const row = rowButton(screen.getByRole('listitem'))
|
||||
fireEvent.mouseDown(row)
|
||||
fireEvent.click(row)
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
// Focus parks on the picked row (the editor's input just unmounted and
|
||||
// the Modal has no focus trap to catch a fall to body).
|
||||
expect(document.activeElement).toBe(row)
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
expect(screen.getByRole('button', { name: 'browser.home' })).toBeTruthy()
|
||||
})
|
||||
|
||||
it('a right-pane pick while editing parks focus on the advanced selection', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(rowButton(screen.getByRole('listitem')))
|
||||
await waitFor(() => { expect(columns()).toHaveLength(2) })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: `${DOCS}/h` } })
|
||||
// The advance replaces BOTH panes (the picked button's own column
|
||||
// unmounts), so focus is re-parked on the selection's aria-current row
|
||||
// in the freshly rendered left pane rather than the clicked node.
|
||||
const row = rowButton(within(columns()[1]!).getByRole('listitem'))
|
||||
fireEvent.mouseDown(row)
|
||||
fireEvent.click(row)
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
await waitFor(() => { expect(document.activeElement?.textContent).toBe('harness') })
|
||||
expect(document.activeElement?.getAttribute('aria-current')).toBe('true')
|
||||
})
|
||||
|
||||
it('seeds and filters with backslashes on a Windows-rooted listing', async () => {
|
||||
const ROOT = 'C:\\'
|
||||
const windowsListing: DirectoryListing = {
|
||||
path: ROOT,
|
||||
home: ROOT,
|
||||
crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }],
|
||||
entries: [
|
||||
{ name: 'Program Files', path: `${ROOT}Program Files`, hidden: false },
|
||||
{ name: 'Users', path: `${ROOT}Users`, hidden: false },
|
||||
],
|
||||
truncated: false,
|
||||
}
|
||||
mount({ listDirectory: vi.fn(async () => windowsListing) })
|
||||
await waitFor(() => { expect(screen.getAllByRole('listitem')).toHaveLength(2) })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
// The root already ends in its separator: no doubled backslash.
|
||||
expect(input.value).toBe(ROOT)
|
||||
fireEvent.change(input, { target: { value: `${ROOT}u` } })
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Users')
|
||||
})
|
||||
|
||||
it('clicking away from the path editor cancels it back to the crumb view', async () => {
|
||||
mount()
|
||||
await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
|
||||
const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
|
||||
fireEvent.change(input, { target: { value: '/somewhere/else' } })
|
||||
// Focus moving anywhere outside the editor abandons the draft like Escape.
|
||||
fireEvent.focusOut(input)
|
||||
expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
|
||||
// The crumb view is back and the abandoned draft was never navigated to.
|
||||
expect(screen.getByRole('button', { name: 'browser.editPath' })).toBeTruthy()
|
||||
expect(screen.getByRole('listitem').textContent).toBe('Documents')
|
||||
})
|
||||
|
||||
it('restarts the home listing when Escape cancels an edit opened before any level listed', async () => {
|
||||
@@ -713,11 +1350,13 @@ describe('DirectoryBrowser', () => {
|
||||
b.listDirectory.mockReturnValueOnce(slow)
|
||||
fireEvent.click(screen.getByRole('button', { name: 'browser.home' }))
|
||||
fireEvent.click(within(screen.getByRole('navigation')).getByRole('button', { name: 'Documents' }))
|
||||
await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
|
||||
// The newer jump lands two-pane: Documents selected at home, children right.
|
||||
await waitFor(() => { expect(within(columns()[1]!).getByText('harness')).toBeTruthy() })
|
||||
resolveSlow(listingFor(undefined))
|
||||
await new Promise(settle => setTimeout(settle, 0))
|
||||
// The stale home listing did not replace the newer Documents level.
|
||||
expect(screen.getByRole('listitem').textContent).toBe('harness')
|
||||
// The stale home listing did not replace the newer Documents landing.
|
||||
expect(columns()).toHaveLength(2)
|
||||
expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
|
||||
})
|
||||
|
||||
it('names the create target by its path when the level reports no crumbs', async () => {
|
||||
|
||||
@@ -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/pty/README.md
|
||||
README.md: a9121455519a5f83a63a005cb857fec0f0e06b92
|
||||
README.zh.md: 4e36ef934d31861d72748b9b9585695f86749171
|
||||
README.md: e54dcf64db083665f37b7dc19a7a92e21494442b
|
||||
README.zh.md: 0bb7e565a5799002ffb8b74dce12e129a7b2665e
|
||||
|
||||
@@ -9,5 +9,6 @@ English | [中文](README.zh.md)
|
||||
| [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
|
||||
| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
|
||||
| `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
|
||||
| `tool-bash-persistent` (`@deepseek-ai/dsh-tool-bash-persistent`) | One model-facing `bash` backed by an owner-scoped reusable PTY shell | consumes `ctx.pty`, registers on `ctx.tools` |
|
||||
|
||||
The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
|
||||
|
||||
@@ -9,5 +9,6 @@
|
||||
| [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确到 agent（智能体）的所有权、会话操作与等待清理完成的机制 | `ctx.pty` |
|
||||
| `pty-local`（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
|
||||
| `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，以及用于后台发送的通用任务集成 | 注册到 `ctx.tools` |
|
||||
| `tool-bash-persistent`（`@deepseek-ai/dsh-tool-bash-persistent`） | 一个由所有者隔离可复用 PTY shell 支撑的模型可见 `bash` | 消费 `ctx.pty`，注册到 `ctx.tools` |
|
||||
|
||||
设计与暂缓边界记录在[持久 PTY Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
|
||||
|
||||
6
packages/pty/tool-bash-persistent/README.i18n.yaml
Normal file
6
packages/pty/tool-bash-persistent/README.i18n.yaml
Normal file
@@ -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/pty/tool-bash-persistent/README.md
|
||||
README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
|
||||
README.zh.md: a525485933344a8f9bc218456c099efdef572902
|
||||
50
packages/pty/tool-bash-persistent/README.md
Normal file
50
packages/pty/tool-bash-persistent/README.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# @deepseek-ai/dsh-tool-bash-persistent
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Model-facing `bash(command)` backed by one owner-scoped `ctx.pty` shell. The package owns the tool contract and shell reuse; deployments select the PTY backend and sandbox policy.
|
||||
|
||||
## Config
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---:|---|
|
||||
| `backendType` | `shell` | Registered PTY backend used for each Agent shell. |
|
||||
| `timeoutMs` | `300000` | Wall-clock limit for one command; timeout closes the shell. |
|
||||
| `maxOutputChars` | `16000` | Maximum retained command-output characters; fixed diagnostics are added afterward. |
|
||||
| `description` | Persistent-shell description | Model-facing environment contract. |
|
||||
|
||||
## Model Experience
|
||||
|
||||
### Tool schema
|
||||
|
||||
#### What the model sees
|
||||
|
||||
The generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent), including the configured `description`. The plugin contributes no standalone system-prompt section; the deployment owns persona and environment guidance.
|
||||
|
||||
#### Token effect
|
||||
|
||||
Fixed schema cost while `bash` is visible.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
Prefix-stable while the configured description and schema remain unchanged.
|
||||
|
||||
### Tool results
|
||||
|
||||
#### What the model sees
|
||||
|
||||
Commands share one shell per Agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers and the shell prompt. A nonzero wrapped command appends `[exit code: N]`; a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither, then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
|
||||
|
||||
#### Token effect
|
||||
|
||||
Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
Append-only tool results follow the reusable request prefix.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- The tool requires an owning Agent and a real PTY backend.
|
||||
- Explicit `exit` and timeout discard shell state. Cancellation also resets and discards the result, even when a complete status marker is already observable; the next call starts a fresh shell.
|
||||
- Environment facts such as network access and package mirrors belong in the configured `description`, not this package's default.
|
||||
50
packages/pty/tool-bash-persistent/README.zh.md
Normal file
50
packages/pty/tool-bash-persistent/README.zh.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# @deepseek-ai/dsh-tool-bash-persistent
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
|
||||
|
||||
## 配置
|
||||
|
||||
| 键 | 默认值 | 含义 |
|
||||
|---|---:|---|
|
||||
| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
|
||||
| `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
|
||||
| `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
|
||||
| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
|
||||
|
||||
## 模型体验
|
||||
|
||||
### 工具 schema
|
||||
|
||||
#### 模型所见
|
||||
|
||||
生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；persona 与环境指导由部署负责。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
`bash` 可见时产生固定的 schema 成本。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
配置的描述与 schema 不变时前缀稳定。
|
||||
|
||||
### 工具结果
|
||||
|
||||
#### 模型所见
|
||||
|
||||
每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
随数据变化。`maxOutputChars` 限制保留的命令输出；固定的截断、前缀丢失、状态、超时与重置诊断可能使结果更长。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
工具结果以追加方式位于可复用请求前缀之后。
|
||||
|
||||
## 已知限制与延后工作
|
||||
|
||||
- 工具需要拥有它的 Agent 和真实 PTY 后端。
|
||||
- 显式 `exit` 与超时会丢弃 shell 状态。取消同样会重置 shell 并丢弃结果，即使已经能观察到完整状态标记也是如此；下次调用创建新 shell。
|
||||
- 网络访问、软件包镜像等环境事实应写入配置的 `description`，而非包默认描述。
|
||||
55
packages/pty/tool-bash-persistent/package.json
Normal file
55
packages/pty/tool-bash-persistent/package.json
Normal file
@@ -0,0 +1,55 @@
|
||||
{
|
||||
"name": "@deepseek-ai/dsh-tool-bash-persistent",
|
||||
"description": "Model-facing owner-scoped persistent Bash tool backed by the Harness PTY service",
|
||||
"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"
|
||||
},
|
||||
"./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-agent": "^0.0.1",
|
||||
"@deepseek-ai/dsh-invariants": "^0.0.1",
|
||||
"@deepseek-ai/dsh-pty": "^0.0.1",
|
||||
"@deepseek-ai/dsh-timeout": "^0.0.1",
|
||||
"@deepseek-ai/dsh-tools": "^0.0.1",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
},
|
||||
"dependencies": {
|
||||
"schemastery": "^3.18.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@cordisjs/plugin-include": "workspace:^",
|
||||
"@cordisjs/plugin-loader": "workspace:^",
|
||||
"@deepseek-ai/dsh-agent": "workspace:^",
|
||||
"@deepseek-ai/dsh-invariants": "workspace:^",
|
||||
"@deepseek-ai/dsh-llm": "workspace:^",
|
||||
"@deepseek-ai/dsh-pty": "workspace:^",
|
||||
"@deepseek-ai/dsh-pty-local": "workspace:^",
|
||||
"@deepseek-ai/dsh-sandbox": "workspace:^",
|
||||
"@deepseek-ai/dsh-sandbox-policy": "workspace:^",
|
||||
"@deepseek-ai/dsh-session": "workspace:^",
|
||||
"@deepseek-ai/dsh-system-prompt": "workspace:^",
|
||||
"@deepseek-ai/dsh-timeout": "workspace:^",
|
||||
"@deepseek-ai/dsh-tools": "workspace:^",
|
||||
"cordis": "^4.0.0-rc.7"
|
||||
}
|
||||
}
|
||||
445
packages/pty/tool-bash-persistent/src/index.ts
Normal file
445
packages/pty/tool-bash-persistent/src/index.ts
Normal file
@@ -0,0 +1,445 @@
|
||||
/**
|
||||
* Model-facing persistent `bash` tool over the owner-scoped PTY seam.
|
||||
* @module @deepseek-ai/dsh-tool-bash-persistent
|
||||
*/
|
||||
|
||||
import { randomUUID } from 'node:crypto'
|
||||
import type { Context } from 'cordis'
|
||||
import z from 'schemastery'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import type { PtyReadResult, PtySendResult, PtySessionId } from '@deepseek-ai/dsh-pty'
|
||||
import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
|
||||
// TODO: Replace the file-search advice; arbitrary command output need not come from a searchable file.
|
||||
const TRUNCATED_MESSAGE = '<response clipped><NOTE>To save on context only part of this file has been shown to you. You should retry this tool after you have searched inside the file with `grep -n` in order to find the line numbers of what you are looking for.</NOTE>'
|
||||
const LOST_PREFIX_MESSAGE = '<response clipped><NOTE>The beginning of this command output was dropped by the terminal scrollback limit. The following text is the earliest retained output.</NOTE>\n'
|
||||
const SHELL_RESET_MESSAGE = 'The persistent bash shell was reset; the next bash call starts from the workspace with a fresh current directory and environment.'
|
||||
const SHELL_PROMPT = '__DSH_PERSISTENT_BASH_PROMPT__ '
|
||||
const TIMEOUT_CODE = 'PERSISTENT_BASH_TIMEOUT'
|
||||
// One page is enough to find a just-emitted completion marker; the full
|
||||
// scrollback is assembled only when a command settles or needs partial output.
|
||||
const SCROLLBACK_PAGE_LINES = 1_000
|
||||
const POLL_INTERVAL_MS = 25
|
||||
|
||||
const DEFAULT_DESCRIPTION = 'Run commands in a persistent bash shell. State, including the current directory and exported environment variables, persists across calls for this agent.'
|
||||
|
||||
interface ResolvedConfig {
|
||||
backendType: string
|
||||
timeoutMs: number
|
||||
maxOutputChars: number
|
||||
description: string
|
||||
}
|
||||
|
||||
interface CommandMarkers {
|
||||
start: string
|
||||
end: string
|
||||
}
|
||||
|
||||
interface RetainedOutput {
|
||||
text: string
|
||||
truncated: boolean
|
||||
}
|
||||
|
||||
interface CapturedOutput {
|
||||
text: string
|
||||
incomplete: boolean
|
||||
exitCode?: number
|
||||
}
|
||||
|
||||
interface PersistentShells {
|
||||
get(owner: Agent, signal: AbortSignal): Promise<PtySessionId>
|
||||
reset(owner: Agent, reason: string): Promise<void>
|
||||
}
|
||||
|
||||
function maybeTruncate(content: string, maxOutputChars: number, incomplete = false): string {
|
||||
if (content.length <= maxOutputChars && !incomplete) return content
|
||||
return content.length <= maxOutputChars
|
||||
? content + TRUNCATED_MESSAGE
|
||||
: content.slice(0, maxOutputChars) + TRUNCATED_MESSAGE
|
||||
}
|
||||
|
||||
function markers(): CommandMarkers {
|
||||
const nonce = randomUUID()
|
||||
return {
|
||||
start: `__DSH_PERSISTENT_BASH_START_${nonce}__`,
|
||||
end: `__DSH_PERSISTENT_BASH_END_${nonce}:`,
|
||||
}
|
||||
}
|
||||
|
||||
function quoteForBash(value: string): string {
|
||||
return `$'${value
|
||||
.replaceAll('\\', '\\\\')
|
||||
.replaceAll("'", "\\'")
|
||||
.replaceAll('\r', '\\r')
|
||||
.replaceAll('\n', '\\n')}'`
|
||||
}
|
||||
|
||||
function wrapCommand(command: string, marker: CommandMarkers): string {
|
||||
// Keep the wrapper on one physical line. An interactive bash prints PS2 for
|
||||
// embedded newlines before executing the buffer, which would leak terminal
|
||||
// prompts and marker source text into the model-facing result.
|
||||
return `printf '%s\\n' ${quoteForBash(marker.start)}; eval -- ${quoteForBash(command)}; __dsh_persistent_bash_status=$?; printf '%s%s\\n' ${quoteForBash(marker.end)} "$__dsh_persistent_bash_status"`
|
||||
}
|
||||
|
||||
function stripPrompt(text: string): string {
|
||||
let result = text.replace(/\r?\n$/, '')
|
||||
while (result.endsWith(SHELL_PROMPT)) {
|
||||
result = result.slice(0, -SHELL_PROMPT.length)
|
||||
}
|
||||
return result.endsWith('\n') ? result.slice(0, -1) : result
|
||||
}
|
||||
|
||||
function commandOutput(
|
||||
snapshot: RetainedOutput,
|
||||
marker: CommandMarkers,
|
||||
): CapturedOutput | undefined {
|
||||
const text = snapshot.text
|
||||
const end = text.lastIndexOf(marker.end)
|
||||
const status = /^(\d+)\r?\n/.exec(text.slice(end + marker.end.length))?.[1]
|
||||
if (status === undefined) return undefined
|
||||
const startMarker = text.lastIndexOf(marker.start, end)
|
||||
const start = startMarker < 0 ? 0 : startMarker + marker.start.length
|
||||
return {
|
||||
text: stripPrompt(text.slice(start, end).replace(/^\r?\n/, '')),
|
||||
incomplete: startMarker < 0,
|
||||
exitCode: Number(status),
|
||||
}
|
||||
}
|
||||
|
||||
function promptCompleted(result: PtySendResult): boolean {
|
||||
return result.viewport.endsWith(SHELL_PROMPT)
|
||||
|| result.viewport.endsWith(`${SHELL_PROMPT}\r\n`)
|
||||
|| result.viewport.endsWith(`${SHELL_PROMPT}\n`)
|
||||
}
|
||||
|
||||
function partialOutput(
|
||||
snapshot: RetainedOutput,
|
||||
marker: CommandMarkers,
|
||||
fallback: string,
|
||||
fallbackTruncated = false,
|
||||
): CapturedOutput {
|
||||
const startMarker = snapshot.text.lastIndexOf(marker.start)
|
||||
if (startMarker >= 0) {
|
||||
return {
|
||||
text: stripPrompt(snapshot.text.slice(startMarker + marker.start.length).replace(/^\r?\n/, '')),
|
||||
incomplete: false,
|
||||
}
|
||||
}
|
||||
const fallbackStart = fallback.lastIndexOf(marker.start)
|
||||
const afterStart = fallbackStart < 0
|
||||
? fallback
|
||||
: fallback.slice(fallbackStart + marker.start.length).replace(/^\r?\n/, '')
|
||||
const fallbackEnd = afterStart.lastIndexOf(marker.end)
|
||||
const beforeEnd = fallbackEnd < 0 ? afterStart : afterStart.slice(0, fallbackEnd)
|
||||
return {
|
||||
text: stripPrompt(beforeEnd.replaceAll(SHELL_PROMPT, '')),
|
||||
incomplete: fallbackTruncated || fallbackStart < 0,
|
||||
}
|
||||
}
|
||||
|
||||
async function pause(): Promise<void> {
|
||||
await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
|
||||
}
|
||||
|
||||
function nextScrollbackOffset(page: PtyReadResult, offset: number): number | undefined {
|
||||
if (page.text.length === 0 || page.lineEnd <= offset) return undefined
|
||||
return page.lineEnd
|
||||
}
|
||||
|
||||
function retainedScrollback(
|
||||
ctx: Context,
|
||||
owner: Agent,
|
||||
id: PtySessionId,
|
||||
latest = ctx.pty.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES }),
|
||||
): RetainedOutput {
|
||||
const pages: string[] = latest.text.length === 0 ? [] : [latest.text]
|
||||
let offset = latest.lineEnd
|
||||
let truncated = latest.truncated
|
||||
while (true) {
|
||||
if (offset >= latest.totalLines) break
|
||||
const page = ctx.pty.read(owner, id, { offset, count: SCROLLBACK_PAGE_LINES })
|
||||
truncated ||= page.truncated
|
||||
if (page.text.length > 0) pages.unshift(page.text)
|
||||
const next = nextScrollbackOffset(page, offset)
|
||||
if (next === undefined || next >= page.totalLines) break
|
||||
offset = next
|
||||
}
|
||||
return { text: pages.join('\n'), truncated }
|
||||
}
|
||||
|
||||
function renderCaptured(output: CapturedOutput, maxOutputChars: number): string {
|
||||
const rendered = maybeTruncate(output.text, maxOutputChars, output.incomplete)
|
||||
const withPrefix = output.incomplete && output.text.length > 0
|
||||
? LOST_PREFIX_MESSAGE + rendered
|
||||
: rendered
|
||||
const marker = output.exitCode !== undefined && output.exitCode !== 0
|
||||
? `[exit code: ${output.exitCode}]`
|
||||
: undefined
|
||||
return appendStatusMarker(withPrefix, marker)
|
||||
}
|
||||
|
||||
function appendStatusMarker(content: string, marker: string | undefined): string {
|
||||
if (marker === undefined) return content
|
||||
return content.length === 0 ? marker : `${content}\n${marker}`
|
||||
}
|
||||
|
||||
function renderShellExitStatus(
|
||||
content: string,
|
||||
exitCode: number | null,
|
||||
signal: NodeJS.Signals | null,
|
||||
): string {
|
||||
const marker = signal !== null
|
||||
? `[shell killed by signal: ${signal}]`
|
||||
: exitCode !== null
|
||||
? `[shell exited: code ${exitCode}]`
|
||||
: '[shell exited]'
|
||||
return appendStatusMarker(content, marker)
|
||||
}
|
||||
|
||||
function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShells {
|
||||
const pending = new WeakMap<Agent, Promise<PtySessionId>>()
|
||||
const live = new Map<Agent, PtySessionId>()
|
||||
const creating = new Set<Promise<PtySessionId>>()
|
||||
const ownerCleanupInstalled = new WeakSet<Agent>()
|
||||
const lifecycle = new AbortController()
|
||||
|
||||
const close = async (owner: Agent, id: PtySessionId, reason: string): Promise<void> => {
|
||||
if (!ctx.pty.list(owner).some(snapshot => snapshot.sessionId === id)) return
|
||||
await ctx.pty.kill(owner, id, reason)
|
||||
}
|
||||
|
||||
ctx.effect(() => async () => {
|
||||
lifecycle.abort(new Error('tool-bash-persistent disposed during shell creation'))
|
||||
await Promise.allSettled([...creating])
|
||||
const closing = [...live].map(async ([owner, id]) => { await close(owner, id, 'tool-bash-persistent disposed') })
|
||||
await Promise.all(closing)
|
||||
live.clear()
|
||||
}, 'tool-bash-persistent shell cleanup')
|
||||
|
||||
const reset = async (owner: Agent, reason: string): Promise<void> => {
|
||||
pending.delete(owner)
|
||||
const id = live.get(owner)
|
||||
live.delete(owner)
|
||||
if (id !== undefined) await close(owner, id, reason)
|
||||
}
|
||||
|
||||
const get = (owner: Agent, signal: AbortSignal): Promise<PtySessionId> => {
|
||||
const existing = pending.get(owner)
|
||||
if (existing !== undefined) return existing
|
||||
const combinedSignal = AbortSignal.any([signal, lifecycle.signal])
|
||||
const creation = (async () => {
|
||||
try {
|
||||
const cwd = owner.session.header.cwd
|
||||
const spawned = await ctx.pty.spawn(owner, {
|
||||
type: config.backendType,
|
||||
...cwd === undefined ? {} : { cwd },
|
||||
}, combinedSignal)
|
||||
live.set(owner, spawned.sessionId)
|
||||
if (!ownerCleanupInstalled.has(owner)) {
|
||||
ownerCleanupInstalled.add(owner)
|
||||
owner.ctx.effect(() => () => {
|
||||
pending.delete(owner)
|
||||
live.delete(owner)
|
||||
}, 'tool-bash-persistent owner cache cleanup')
|
||||
}
|
||||
const setup = ctx.pty.startSend(owner, spawned.sessionId, {
|
||||
text: `stty -echo; PS1=${quoteForBash(SHELL_PROMPT)}`,
|
||||
submit: true,
|
||||
signal: combinedSignal,
|
||||
})
|
||||
const result = await setup.done
|
||||
if (result.sessionStatus.kind === 'exited' || result.waitReason === 'timeout') {
|
||||
throw new Error('persistent bash shell did not accept initialization')
|
||||
}
|
||||
return spawned.sessionId
|
||||
} catch (error: unknown) {
|
||||
await reset(owner, 'persistent bash initialization failed')
|
||||
throw error
|
||||
}
|
||||
})()
|
||||
const tracked = creation.finally(() => {
|
||||
creating.delete(tracked)
|
||||
})
|
||||
creating.add(tracked)
|
||||
pending.set(owner, tracked)
|
||||
return tracked
|
||||
}
|
||||
|
||||
return { get, reset }
|
||||
}
|
||||
|
||||
async function executeCommand(
|
||||
ctx: Context,
|
||||
shells: PersistentShells,
|
||||
owner: Agent,
|
||||
command: string,
|
||||
config: ResolvedConfig,
|
||||
upstream: AbortSignal,
|
||||
): Promise<string> {
|
||||
using commandDeadline = deadline(upstream, config.timeoutMs, TIMEOUT_CODE)
|
||||
const id = await shells.get(owner, commandDeadline.signal)
|
||||
const marker = markers()
|
||||
const wrapped = wrapCommand(command, marker)
|
||||
let first = true
|
||||
let fallback = ''
|
||||
let fallbackTruncated = false
|
||||
|
||||
while (true) {
|
||||
let operation
|
||||
let result
|
||||
try {
|
||||
operation = ctx.pty.startSend(owner, id, {
|
||||
text: first ? wrapped : '',
|
||||
submit: first,
|
||||
signal: commandDeadline.signal,
|
||||
})
|
||||
first = false
|
||||
result = await operation.done
|
||||
} catch (error: unknown) {
|
||||
await shells.reset(owner, 'persistent bash send failed')
|
||||
throw error
|
||||
}
|
||||
const incremental = operation.readOutput()
|
||||
fallback = incremental.delta.length > 0 ? fallback + incremental.delta : result.viewport
|
||||
fallbackTruncated ||= incremental.truncated || result.truncated
|
||||
const latest = ctx.pty.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES })
|
||||
const timedOut = timeoutOf(commandDeadline.signal, TIMEOUT_CODE)
|
||||
if (timedOut !== undefined) {
|
||||
const snapshot = retainedScrollback(ctx, owner, id, latest)
|
||||
const partial = renderCaptured(
|
||||
partialOutput(snapshot, marker, fallback, fallbackTruncated),
|
||||
config.maxOutputChars,
|
||||
)
|
||||
await shells.reset(owner, 'persistent bash command timed out')
|
||||
return [
|
||||
// TODO: Report a timeout only; this signal does not establish an OOM.
|
||||
`Your command timed out after ${Math.round(timedOut.timeoutMs / 1000)} seconds or experienced an OOM error. Below is partial output:`,
|
||||
partial,
|
||||
SHELL_RESET_MESSAGE,
|
||||
].join('\n')
|
||||
}
|
||||
if (commandDeadline.signal.aborted) {
|
||||
await shells.reset(owner, 'persistent bash command aborted')
|
||||
commandDeadline.signal.throwIfAborted()
|
||||
}
|
||||
if (latest.text.includes(marker.end)) {
|
||||
const complete = commandOutput(retainedScrollback(ctx, owner, id, latest), marker)
|
||||
if (complete !== undefined) return renderCaptured(complete, config.maxOutputChars)
|
||||
}
|
||||
if (result.sessionStatus.kind === 'exited') {
|
||||
const snapshot = retainedScrollback(ctx, owner, id, latest)
|
||||
await shells.reset(owner, 'persistent bash shell exited')
|
||||
return [
|
||||
renderShellExitStatus(
|
||||
renderCaptured(partialOutput(snapshot, marker, fallback, fallbackTruncated), config.maxOutputChars),
|
||||
result.sessionStatus.exitCode,
|
||||
result.sessionStatus.signal,
|
||||
),
|
||||
SHELL_RESET_MESSAGE,
|
||||
].filter(part => part.length > 0).join('\n')
|
||||
}
|
||||
if (promptCompleted(result)) {
|
||||
const snapshot = retainedScrollback(ctx, owner, id, latest)
|
||||
return renderCaptured(
|
||||
partialOutput(snapshot, marker, fallback, fallbackTruncated),
|
||||
config.maxOutputChars,
|
||||
)
|
||||
}
|
||||
await pause()
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Register the model-facing persistent `bash` tool.
|
||||
* @param ctx - plugin context carrying tools and the owner-scoped PTY service.
|
||||
* @param config - selected PTY backend and command deadline.
|
||||
*/
|
||||
function registerPersistentBash(ctx: Context, config: ResolvedConfig): void {
|
||||
const shells = persistentShells(ctx, config)
|
||||
const queues = new WeakMap<Agent, Promise<void>>()
|
||||
|
||||
const serialized = async <T>(owner: Agent, operation: () => Promise<T>): Promise<T> => {
|
||||
const prior = queues.get(owner) ?? Promise.resolve()
|
||||
const run = prior.then(operation, operation)
|
||||
const tail = run.then(() => undefined, () => undefined)
|
||||
queues.set(owner, tail)
|
||||
try {
|
||||
return await run
|
||||
} finally {
|
||||
if (queues.get(owner) === tail) queues.delete(owner)
|
||||
}
|
||||
}
|
||||
|
||||
ctx.tools.register(defineTool({
|
||||
name: 'bash',
|
||||
description: config.description,
|
||||
parameters: {
|
||||
command: {
|
||||
type: 'string',
|
||||
required: true,
|
||||
description: 'The bash command to run. Relative path is preferred in the command.',
|
||||
},
|
||||
},
|
||||
output: {
|
||||
schema: { type: 'string' },
|
||||
render: (_args, value) => [{ type: 'text', text: value }],
|
||||
},
|
||||
async execute(args, exec) {
|
||||
if (args.command.trim().length === 0) throw new Error('command must be a non-empty string')
|
||||
const owner = exec.agent
|
||||
if (owner === undefined) throw new Error('bash requires an owning agent session')
|
||||
return serialized(owner, async () => {
|
||||
exec.signal.throwIfAborted()
|
||||
return executeCommand(ctx, shells, owner, args.command, config, exec.signal)
|
||||
})
|
||||
},
|
||||
presentCall: args => ({ card: 'terminal', title: args.command }),
|
||||
}))
|
||||
}
|
||||
|
||||
export const name = 'tool-bash-persistent'
|
||||
export const inject = ['tools', 'pty']
|
||||
|
||||
/** Configuration for the persistent Bash tool. */
|
||||
export interface Config {
|
||||
/** PTY backend used for each owner-isolated persistent shell (default `shell`). */
|
||||
backendType?: string
|
||||
/** Wall-clock limit for one command (default 300000). */
|
||||
timeoutMs?: number
|
||||
/** Maximum returned command-output characters before clipping (default 16000). */
|
||||
maxOutputChars?: number
|
||||
/** Model-facing tool description; deployments may describe their environment. */
|
||||
description?: string
|
||||
}
|
||||
|
||||
/** Runtime configuration schema for the persistent Bash tool. */
|
||||
export const Config: z<Config> = z.object({
|
||||
backendType: z.string().default('shell'),
|
||||
timeoutMs: z.number().default(300_000),
|
||||
maxOutputChars: z.number().default(16_000),
|
||||
description: z.string().default(DEFAULT_DESCRIPTION),
|
||||
})
|
||||
|
||||
/** Register one owner-scoped persistent `bash` tool. */
|
||||
export function apply(ctx: Context, config: Config): void {
|
||||
const resolved: ResolvedConfig = {
|
||||
backendType: config.backendType ?? 'shell',
|
||||
timeoutMs: config.timeoutMs ?? 300_000,
|
||||
maxOutputChars: config.maxOutputChars ?? 16_000,
|
||||
description: config.description ?? DEFAULT_DESCRIPTION,
|
||||
}
|
||||
if (resolved.backendType.trim().length === 0) {
|
||||
throw new Error('tool-bash-persistent: backendType must be non-empty')
|
||||
}
|
||||
if (!Number.isSafeInteger(resolved.timeoutMs) || resolved.timeoutMs <= 0) {
|
||||
throw new Error('tool-bash-persistent: timeoutMs must be a positive safe integer')
|
||||
}
|
||||
if (!Number.isSafeInteger(resolved.maxOutputChars) || resolved.maxOutputChars <= 0) {
|
||||
throw new Error('tool-bash-persistent: maxOutputChars must be a positive safe integer')
|
||||
}
|
||||
if (resolved.description.trim().length === 0) {
|
||||
throw new Error('tool-bash-persistent: description must be non-empty')
|
||||
}
|
||||
registerPersistentBash(ctx, resolved)
|
||||
}
|
||||
31
packages/pty/tool-bash-persistent/src/invariant.ts
Normal file
31
packages/pty/tool-bash-persistent/src/invariant.ts
Normal file
@@ -0,0 +1,31 @@
|
||||
/**
|
||||
* Package-owned invariant companion for `@deepseek-ai/dsh-tool-bash-persistent`.
|
||||
* @module @deepseek-ai/dsh-tool-bash-persistent/invariant
|
||||
*/
|
||||
|
||||
/* jscpd:ignore-start */
|
||||
import type { Context } from 'cordis'
|
||||
import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
|
||||
|
||||
const PACKAGE_NAME = '@deepseek-ai/dsh-tool-bash-persistent'
|
||||
|
||||
/** Cordis companion plugin name. */
|
||||
export const name = 'tool-bash-persistent-invariant'
|
||||
/** Service required before the companion can reserve package ownership. */
|
||||
export const inject = ['invariants']
|
||||
|
||||
/**
|
||||
* No runtime invariant: the adapter's private owner-to-shell cache has no
|
||||
* observable event or data relation. Lifecycle tests prove its cleanup without
|
||||
* adding a public surface solely for an invariant.
|
||||
*/
|
||||
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 */
|
||||
@@ -0,0 +1,157 @@
|
||||
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 } from 'vitest'
|
||||
import { Context } from 'cordis'
|
||||
import Loader from '@cordisjs/plugin-loader'
|
||||
import Include from '@cordisjs/plugin-include'
|
||||
import { CallId } from '@deepseek-ai/dsh-llm'
|
||||
import { Session, SessionId } from '@deepseek-ai/dsh-session'
|
||||
import AgentRegistry from '@deepseek-ai/dsh-agent'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import PtyService from '@deepseek-ai/dsh-pty'
|
||||
import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
|
||||
import SandboxProvider from '@deepseek-ai/dsh-sandbox'
|
||||
import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
|
||||
import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
|
||||
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
|
||||
import ToolRegistry from '@deepseek-ai/dsh-tools'
|
||||
import * as ToolBashPersistent from '@deepseek-ai/dsh-tool-bash-persistent'
|
||||
|
||||
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
|
||||
})
|
||||
|
||||
class PassthroughSandbox extends SandboxProvider {
|
||||
confine(argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
|
||||
return { argv: [...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
|
||||
}
|
||||
}
|
||||
|
||||
function agent(ctx: Context, cwd: string): Agent {
|
||||
const id = SessionId('persistent-bash-loader-agent')
|
||||
const scope = ctx.plugin(() => {})
|
||||
const value: Agent = {
|
||||
id,
|
||||
options: {},
|
||||
session: new Session(id, [], { version: 0, id, createdAt: 0, cwd }),
|
||||
status: 'idle',
|
||||
acceptsNextStep: false,
|
||||
ctx: scope.ctx,
|
||||
followup: () => {},
|
||||
steer: () => {},
|
||||
inject: () => {},
|
||||
send: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
ctx.agents.register(value)
|
||||
return value
|
||||
}
|
||||
|
||||
function text(result: { content: { type: string; text?: string }[] }): string {
|
||||
return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
|
||||
}
|
||||
|
||||
const suite = process.platform === 'linux' || process.platform === 'darwin' ? describe : describe.skip
|
||||
|
||||
suite('persistent Bash through a real cordis.yml Loader composition', () => {
|
||||
it('preserves cwd and environment across calls', async () => {
|
||||
root = await mkdtemp(join(tmpdir(), 'dsh-persistent-bash-loader-'))
|
||||
const configPath = join(root, 'cordis.yml')
|
||||
await writeFile(configPath, [
|
||||
"- name: '@deepseek-ai/dsh-agent'",
|
||||
"- name: '@deepseek-ai/dsh-system-prompt'",
|
||||
"- name: '@deepseek-ai/dsh-tools'",
|
||||
"- name: '@deepseek-ai/dsh-pty'",
|
||||
"- name: '@deepseek-ai/dsh-test-sandbox'",
|
||||
"- name: '@deepseek-ai/dsh-sandbox-policy'",
|
||||
' config:',
|
||||
' mode: danger-full-access',
|
||||
` workspaceRoot: ${JSON.stringify(root)}`,
|
||||
"- name: '@deepseek-ai/dsh-pty-local'",
|
||||
' config:',
|
||||
' pollIntervalMs: 10',
|
||||
' exactProbeAfterMs: 20',
|
||||
' idleSilenceMs: 100',
|
||||
' handoffGraceMs: 100',
|
||||
' scrollbackLines: 20000',
|
||||
' timeoutMs: 2000',
|
||||
' disposeGraceMs: 500',
|
||||
"- name: '@deepseek-ai/dsh-tool-bash-persistent'",
|
||||
' config:',
|
||||
' timeoutMs: 5000',
|
||||
'',
|
||||
].join('\n'))
|
||||
|
||||
context = new Context()
|
||||
context.baseUrl = pathToFileURL(root).href + '/'
|
||||
await context.plugin(Loader)
|
||||
context.loader.builtins.include = Include
|
||||
const modules = new Map<string, unknown>([
|
||||
['@deepseek-ai/dsh-agent', AgentRegistry],
|
||||
['@deepseek-ai/dsh-system-prompt', SystemPrompt],
|
||||
['@deepseek-ai/dsh-tools', ToolRegistry],
|
||||
['@deepseek-ai/dsh-pty', PtyService],
|
||||
['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
|
||||
['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
|
||||
['@deepseek-ai/dsh-pty-local', PtyLocal],
|
||||
['@deepseek-ai/dsh-tool-bash-persistent', ToolBashPersistent],
|
||||
])
|
||||
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<typeof context.loader.internal>
|
||||
await context.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(configPath).href } })
|
||||
await context.loader.await()
|
||||
|
||||
const owner = agent(context, root)
|
||||
const signal = new AbortController().signal
|
||||
const execute = (id: string, command: string) => context!.tools.execute({
|
||||
signal,
|
||||
callId: CallId(id),
|
||||
name: 'bash',
|
||||
arguments: { command },
|
||||
agent: owner,
|
||||
})
|
||||
|
||||
expect(context.tools.schemas().map(schema => schema.name)).toEqual(['bash'])
|
||||
await execute('state', 'export KEEP=loader; mkdir -p nested; cd nested')
|
||||
const observed = text(await execute('observe', 'printf "cwd=%s keep=%s\\n" "$PWD" "$KEEP"'))
|
||||
expect(observed).toContain(`cwd=${join(root, 'nested')} keep=loader`)
|
||||
expect(observed).not.toContain('DSH_PERSISTENT_BASH')
|
||||
|
||||
const multiline = text(await execute(
|
||||
'multiline',
|
||||
'value="line one"\nprintf "%s:%s\\n" "$value" "it\'s fine"',
|
||||
))
|
||||
expect(multiline).toBe("line one:it's fine")
|
||||
expect(multiline).not.toContain('DSH_PERSISTENT_BASH')
|
||||
|
||||
const heredoc = text(await execute(
|
||||
'heredoc',
|
||||
"cat <<'EOF'\nalpha\nbeta\nEOF",
|
||||
))
|
||||
expect(heredoc).toBe('alpha\nbeta')
|
||||
|
||||
const large = text(await execute('large-output', 'seq 1 12050'))
|
||||
expect(large.startsWith('1\n2\n3\n')).toBe(true)
|
||||
expect(large).toContain('<response clipped>')
|
||||
expect(large).not.toContain('beginning of this command output was dropped')
|
||||
|
||||
const exited = text(await execute('exit', 'exit'))
|
||||
expect(exited).toContain('next bash call starts from the workspace')
|
||||
expect(text(await execute('after-exit', 'printf "%s\\n" "$PWD"'))).toBe(root)
|
||||
}, 20_000)
|
||||
})
|
||||
538
packages/pty/tool-bash-persistent/tests/tools.spec.ts
Normal file
538
packages/pty/tool-bash-persistent/tests/tools.spec.ts
Normal file
@@ -0,0 +1,538 @@
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { Context } from 'cordis'
|
||||
import { CallId } from '@deepseek-ai/dsh-llm'
|
||||
import { Session, SessionId } from '@deepseek-ai/dsh-session'
|
||||
import AgentRegistry from '@deepseek-ai/dsh-agent'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import PtyService from '@deepseek-ai/dsh-pty'
|
||||
import type {
|
||||
PtyBackend,
|
||||
PtyBackendSession,
|
||||
PtyReadRequest,
|
||||
PtySendOperation,
|
||||
PtySendRequest,
|
||||
PtySessionStatus,
|
||||
PtySignal,
|
||||
PtyWaitReason,
|
||||
} from '@deepseek-ai/dsh-pty'
|
||||
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
|
||||
import ToolRegistry from '@deepseek-ai/dsh-tools'
|
||||
import * as ToolBashPersistent from '@deepseek-ai/dsh-tool-bash-persistent'
|
||||
|
||||
const contexts: Context[] = []
|
||||
let callNumber = 0
|
||||
|
||||
afterEach(async () => {
|
||||
for (const ctx of contexts.splice(0)) await ctx.fiber.dispose()
|
||||
})
|
||||
|
||||
function agent(ctx: Context, cwd: string | undefined): Agent {
|
||||
const id = SessionId(`persistent-bash-owner-${callNumber}`)
|
||||
const scope = ctx.plugin(() => {})
|
||||
const value: Agent = {
|
||||
id,
|
||||
options: {},
|
||||
session: new Session(id, [], {
|
||||
version: 0,
|
||||
id,
|
||||
createdAt: 0,
|
||||
...cwd === undefined ? {} : { cwd },
|
||||
}),
|
||||
status: 'idle',
|
||||
acceptsNextStep: false,
|
||||
ctx: scope.ctx,
|
||||
followup: () => {},
|
||||
steer: () => {},
|
||||
inject: () => {},
|
||||
send: () => {},
|
||||
updateInbox: () => 'not-found',
|
||||
cancel() {},
|
||||
whenIdle: () => Promise.resolve(),
|
||||
}
|
||||
ctx.agents.register(value)
|
||||
return value
|
||||
}
|
||||
|
||||
function text(result: { content: { type: string; text?: string }[] }): string {
|
||||
return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
|
||||
}
|
||||
|
||||
function call(
|
||||
ctx: Context,
|
||||
owner: Agent | undefined,
|
||||
command: string,
|
||||
signal = new AbortController().signal,
|
||||
) {
|
||||
return ctx.tools.execute({
|
||||
signal,
|
||||
callId: CallId(`persistent-bash-${++callNumber}`),
|
||||
name: 'bash',
|
||||
arguments: { command },
|
||||
...owner === undefined ? {} : { agent: owner },
|
||||
})
|
||||
}
|
||||
|
||||
type StubMode =
|
||||
| 'normal'
|
||||
| 'prompt-only'
|
||||
| 'prompt-crlf'
|
||||
| 'empty-read'
|
||||
| 'stalled-read'
|
||||
| 'exit'
|
||||
| 'signal-exit'
|
||||
| 'unknown-exit'
|
||||
| 'wait-for-abort'
|
||||
| 'end-on-abort'
|
||||
| 'idle-then-normal'
|
||||
| 'large'
|
||||
| 'nonzero'
|
||||
| 'torn-status'
|
||||
| 'finish-torn-status'
|
||||
| 'end-only'
|
||||
| 'init-exit'
|
||||
| 'init-timeout'
|
||||
| 'spawn-error'
|
||||
| 'send-error'
|
||||
| 'prompt-after-idle'
|
||||
| 'empty-page-after-latest'
|
||||
|
||||
class StubPtySession implements PtyBackendSession {
|
||||
readonly motd = '__DSH_PERSISTENT_BASH_PROMPT__ '
|
||||
readonly pid = 123
|
||||
statusValue: PtySessionStatus = { kind: 'running' }
|
||||
scrollback = this.motd
|
||||
closed: string[] = []
|
||||
mode: StubMode
|
||||
sends = 0
|
||||
pendingText = ''
|
||||
historyTruncated = false
|
||||
|
||||
constructor(mode: StubMode) {
|
||||
this.mode = mode
|
||||
}
|
||||
|
||||
startSend(request: PtySendRequest): PtySendOperation {
|
||||
this.sends += 1
|
||||
if (request.text.startsWith('stty -echo')) {
|
||||
if (this.mode === 'init-exit') {
|
||||
this.statusValue = { kind: 'exited', exitCode: 1, signal: null }
|
||||
return this.operation(Promise.resolve(this.result('', 'session_exit')))
|
||||
}
|
||||
if (this.mode === 'init-timeout') {
|
||||
return this.operation(Promise.resolve(this.result('', 'timeout')))
|
||||
}
|
||||
return this.operation(Promise.resolve(this.result(this.motd, 'stdin_read')))
|
||||
}
|
||||
if (this.mode === 'send-error') throw new Error('stub send failed')
|
||||
if (this.mode === 'wait-for-abort' || this.mode === 'end-on-abort') {
|
||||
const done = new Promise<ReturnType<StubPtySession['result']>>((resolve) => {
|
||||
request.signal?.addEventListener('abort', () => {
|
||||
const start = /__DSH_PERSISTENT_BASH_START_[^_]+(?:-[^_]+)*__/.exec(request.text)?.[0]
|
||||
const end = /__DSH_PERSISTENT_BASH_END_[^:]+:/.exec(request.text)?.[0]
|
||||
const output = this.mode === 'end-on-abort'
|
||||
? `${start ?? ''}\ninterrupted\n${end ?? ''}130\n${this.motd}`
|
||||
: 'partial output'
|
||||
this.scrollback += output
|
||||
resolve(this.result(output, 'stdin_read'))
|
||||
}, { once: true })
|
||||
})
|
||||
return this.operation(done)
|
||||
}
|
||||
if (this.mode === 'idle-then-normal') {
|
||||
this.mode = 'normal'
|
||||
this.pendingText = request.text
|
||||
return this.operation(Promise.resolve(this.result('', 'inferred_idle')))
|
||||
}
|
||||
if (this.mode === 'prompt-after-idle') {
|
||||
if (request.text.length > 0) {
|
||||
const start = /__DSH_PERSISTENT_BASH_START_[^_]+(?:-[^_]+)*__/.exec(request.text)?.[0]
|
||||
const output = `${start ?? ''}\npartial syntax output\n`
|
||||
this.scrollback += output
|
||||
return this.operation(Promise.resolve(this.result(output, 'inferred_idle')))
|
||||
}
|
||||
const output = `bash: syntax error\n${this.motd}`
|
||||
this.scrollback += output
|
||||
return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
|
||||
}
|
||||
if (this.mode === 'prompt-only' || this.mode === 'prompt-crlf') {
|
||||
const newline = this.mode === 'prompt-crlf' ? '\r\n' : '\n'
|
||||
const output = `bash: syntax error${newline}${this.motd}${newline}`
|
||||
this.scrollback += output
|
||||
return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
|
||||
}
|
||||
const sent = request.text.length > 0 ? request.text : this.pendingText
|
||||
this.pendingText = ''
|
||||
const start = /__DSH_PERSISTENT_BASH_START_[^_]+(?:-[^_]+)*__/.exec(sent)?.[0]
|
||||
const end = /__DSH_PERSISTENT_BASH_END_[^:]+:/.exec(sent)?.[0]
|
||||
if (this.mode === 'torn-status') {
|
||||
const output = `${start ?? ''}\nhello from stub\n${end ?? ''}`
|
||||
this.scrollback += output
|
||||
this.mode = 'finish-torn-status'
|
||||
return this.operation(Promise.resolve(this.result(output, 'inferred_idle')))
|
||||
}
|
||||
if (this.mode === 'finish-torn-status') {
|
||||
const output = `7\n${this.motd}`
|
||||
this.scrollback += output
|
||||
return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
|
||||
}
|
||||
if (this.mode === 'end-only') {
|
||||
const output = `recovered output\n${end ?? ''}0\n${this.motd}`
|
||||
this.scrollback += output
|
||||
return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
|
||||
}
|
||||
const commandOutput = this.mode === 'large'
|
||||
? 'x'.repeat(100)
|
||||
: this.mode === 'nonzero' ? '' : 'hello from stub'
|
||||
const exitCode = this.mode === 'nonzero' ? 7 : 0
|
||||
const output = `${start ?? ''}\n${commandOutput}\n${end ?? ''}${exitCode}\n${this.motd}`
|
||||
this.scrollback += output
|
||||
if (this.mode === 'exit' || this.mode === 'signal-exit' || this.mode === 'unknown-exit') {
|
||||
const exitedOutput = `${start ?? ''}\nhello from stub\n`
|
||||
this.scrollback = this.scrollback.slice(0, -output.length) + exitedOutput
|
||||
this.statusValue = this.mode === 'signal-exit'
|
||||
? { kind: 'exited', exitCode: null, signal: 'SIGTERM' }
|
||||
: this.mode === 'exit'
|
||||
? { kind: 'exited', exitCode: 9, signal: null }
|
||||
: { kind: 'exited', exitCode: null, signal: null }
|
||||
return this.operation(Promise.resolve(this.result(exitedOutput, 'session_exit')))
|
||||
}
|
||||
return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
|
||||
}
|
||||
|
||||
read(request: PtyReadRequest) {
|
||||
if (this.mode === 'empty-read') {
|
||||
return { text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: false }
|
||||
}
|
||||
if (this.mode === 'stalled-read') {
|
||||
return { text: 'stalled', totalLines: 1, lineBegin: 0, lineEnd: 0, truncated: false }
|
||||
}
|
||||
if (this.mode === 'empty-page-after-latest' && (request.offset ?? 0) > 0) {
|
||||
return { text: '', totalLines: 2, lineBegin: 1, lineEnd: 1, truncated: false }
|
||||
}
|
||||
const lines = this.scrollback.split('\n')
|
||||
return {
|
||||
text: this.scrollback,
|
||||
totalLines: this.mode === 'empty-page-after-latest' ? lines.length + 1 : lines.length,
|
||||
lineBegin: 0,
|
||||
lineEnd: this.mode === 'empty-page-after-latest' ? 1 : lines.length,
|
||||
truncated: this.historyTruncated,
|
||||
}
|
||||
}
|
||||
|
||||
signal(_signal: PtySignal) {
|
||||
return Promise.resolve({ delivered: true as const, targetPgid: 123 })
|
||||
}
|
||||
|
||||
status() {
|
||||
return this.statusValue
|
||||
}
|
||||
|
||||
async close(reason: string) {
|
||||
this.closed.push(reason)
|
||||
this.statusValue = { kind: 'exited', exitCode: 0, signal: null }
|
||||
}
|
||||
|
||||
private result(viewport: string, waitReason: PtyWaitReason) {
|
||||
return { viewport, waitReason, sessionStatus: this.statusValue, truncated: false }
|
||||
}
|
||||
|
||||
private operation(done: Promise<ReturnType<StubPtySession['result']>>): PtySendOperation {
|
||||
return {
|
||||
done,
|
||||
readOutput: () => ({ delta: '', truncated: false }),
|
||||
cancel: () => false,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function stubBackend(initialMode: StubMode = 'normal') {
|
||||
const sessions: StubPtySession[] = []
|
||||
const backend: PtyBackend = {
|
||||
type: 'stub',
|
||||
async spawn() {
|
||||
if (initialMode === 'spawn-error') throw new Error('stub spawn failed')
|
||||
const session = new StubPtySession(initialMode)
|
||||
sessions.push(session)
|
||||
return session
|
||||
},
|
||||
}
|
||||
return { backend, sessions }
|
||||
}
|
||||
|
||||
async function setup(
|
||||
config: ToolBashPersistent.Config = { backendType: 'stub' },
|
||||
initialMode: StubMode = 'normal',
|
||||
) {
|
||||
const ctx = new Context()
|
||||
contexts.push(ctx)
|
||||
await ctx.plugin(SystemPrompt)
|
||||
await ctx.plugin(ToolRegistry)
|
||||
await ctx.plugin(AgentRegistry)
|
||||
await ctx.plugin(PtyService)
|
||||
const stub = stubBackend(initialMode)
|
||||
ctx.pty.registerBackend(stub.backend)
|
||||
const fiber = await ctx.plugin(ToolBashPersistent, config)
|
||||
return { ctx, stub, fiber, owner: agent(ctx, '/workspace') }
|
||||
}
|
||||
|
||||
describe('tool-bash-persistent', () => {
|
||||
it('registers a configurable schema and reuses one owner shell', async () => {
|
||||
const { ctx, owner, stub, fiber } = await setup({
|
||||
backendType: 'stub',
|
||||
description: 'deployment-specific persistent shell',
|
||||
})
|
||||
const schema = ctx.tools.schemas()[0]
|
||||
expect(ctx.tools.schemas().map(item => item.name)).toEqual(['bash'])
|
||||
expect(schema?.description).toBe('deployment-specific persistent shell')
|
||||
expect(schema?.parameters).toMatchObject({
|
||||
required: ['command'],
|
||||
properties: { command: { type: 'string' } },
|
||||
})
|
||||
expect(ctx.tools.get('bash')?.presentCall?.({ command: 'pwd' }))
|
||||
.toEqual({ card: 'terminal', title: 'pwd' })
|
||||
|
||||
expect(text(await call(ctx, owner, 'echo one'))).toBe('hello from stub')
|
||||
expect(text(await call(ctx, owner, 'echo two'))).toBe('hello from stub')
|
||||
expect(stub.sessions).toHaveLength(1)
|
||||
expect(stub.sessions[0]?.sends).toBe(3)
|
||||
|
||||
const ownerWithoutCwd = agent(ctx, undefined)
|
||||
expect(text(await call(ctx, ownerWithoutCwd, 'pwd'))).toBe('hello from stub')
|
||||
expect(stub.sessions).toHaveLength(2)
|
||||
|
||||
await fiber.dispose()
|
||||
expect(ctx.tools.schemas()).toEqual([])
|
||||
expect(ctx.tools.get('bash')).toBeUndefined()
|
||||
})
|
||||
|
||||
it('handles inferred idle, prompt fallback, shell exit, clipping, and cleanup', async () => {
|
||||
const { ctx, owner, stub, fiber } = await setup({
|
||||
backendType: 'stub',
|
||||
maxOutputChars: 10,
|
||||
})
|
||||
await call(ctx, owner, 'warm up')
|
||||
const session = stub.sessions[0]!
|
||||
|
||||
session.mode = 'idle-then-normal'
|
||||
expect(text(await call(ctx, owner, 'silent then complete'))).toContain('hello from')
|
||||
|
||||
session.mode = 'prompt-only'
|
||||
const promptFallback = text(await call(ctx, owner, 'bad {'))
|
||||
expect(promptFallback).toContain('bash: synt')
|
||||
expect(promptFallback).not.toContain('DSH_PERSISTENT_BASH_PROMPT')
|
||||
|
||||
session.mode = 'prompt-crlf'
|
||||
session.scrollback = ''
|
||||
const crlfPromptFallback = text(await call(ctx, owner, 'bad {'))
|
||||
expect(crlfPromptFallback).toContain('bash: synt')
|
||||
expect(crlfPromptFallback).not.toContain('DSH_PERSISTENT_BASH_PROMPT')
|
||||
|
||||
session.mode = 'end-only'
|
||||
session.scrollback = ''
|
||||
const missingStart = text(await call(ctx, owner, 'recover marker'))
|
||||
expect(missingStart).toContain('recovered')
|
||||
expect(missingStart).toContain('beginning of this command output was dropped')
|
||||
expect(missingStart).toContain('<response clipped>')
|
||||
|
||||
session.mode = 'large'
|
||||
expect(text(await call(ctx, owner, 'large'))).toContain('<response clipped>')
|
||||
|
||||
session.mode = 'nonzero'
|
||||
expect(text(await call(ctx, owner, 'false'))).toBe('[exit code: 7]')
|
||||
|
||||
session.mode = 'exit'
|
||||
const exited = text(await call(ctx, owner, 'exit'))
|
||||
expect(exited).toContain('hello from')
|
||||
expect(exited).toContain('[shell exited: code 9]')
|
||||
expect(exited).not.toContain('[exit code: 9]')
|
||||
expect(exited).toContain('next bash call starts from the workspace')
|
||||
expect(session.closed).toContain('persistent bash shell exited')
|
||||
|
||||
await call(ctx, owner, 'new shell')
|
||||
expect(stub.sessions).toHaveLength(2)
|
||||
const replacement = stub.sessions[1]!
|
||||
replacement.mode = 'signal-exit'
|
||||
expect(text(await call(ctx, owner, 'kill shell')))
|
||||
.toContain('[shell killed by signal: SIGTERM]')
|
||||
|
||||
await call(ctx, owner, 'another shell')
|
||||
expect(stub.sessions).toHaveLength(3)
|
||||
const externallyClosed = ctx.pty.list(owner)[0]?.sessionId
|
||||
expect(externallyClosed).toBeDefined()
|
||||
await ctx.pty.kill(owner, externallyClosed!, 'external cleanup')
|
||||
await fiber.dispose()
|
||||
expect(stub.sessions[2]?.closed).toEqual(['external cleanup'])
|
||||
})
|
||||
|
||||
it('waits for status digits after a torn completion marker', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.mode = 'torn-status'
|
||||
stub.sessions[0]!.scrollback = ''
|
||||
|
||||
expect(text(await call(ctx, owner, 'torn status'))).toBe('hello from stub\n[exit code: 7]')
|
||||
})
|
||||
|
||||
it('reports a shell exit when the backend has no code or signal', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub' })
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.mode = 'unknown-exit'
|
||||
|
||||
expect(text(await call(ctx, owner, 'exit without status'))).toContain('[shell exited]')
|
||||
})
|
||||
|
||||
it('marks a short missing-prefix result and tolerates exhausted scrollback pages', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
const session = stub.sessions[0]!
|
||||
|
||||
session.mode = 'end-only'
|
||||
session.scrollback = ''
|
||||
expect(text(await call(ctx, owner, 'missing start')))
|
||||
.toContain('beginning of this command output was dropped')
|
||||
|
||||
session.mode = 'empty-read'
|
||||
expect(text(await call(ctx, owner, 'empty page'))).toContain('hello from stub')
|
||||
|
||||
session.mode = 'stalled-read'
|
||||
expect(text(await call(ctx, owner, 'stalled page'))).toContain('hello from stub')
|
||||
|
||||
session.mode = 'empty-page-after-latest'
|
||||
expect(text(await call(ctx, owner, 'empty continuation page'))).toContain('hello from stub')
|
||||
})
|
||||
|
||||
it('sanitizes a prompt fallback reached after multiple polling rounds', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
const session = stub.sessions[0]!
|
||||
session.mode = 'prompt-after-idle'
|
||||
session.scrollback = ''
|
||||
const result = text(await call(ctx, owner, 'bad {'))
|
||||
expect(result).toContain('partial syntax output')
|
||||
expect(result).toContain('bash: syntax error')
|
||||
expect(result).not.toContain('DSH_PERSISTENT_BASH_PROMPT')
|
||||
expect(result).not.toContain('DSH_PERSISTENT_BASH_START')
|
||||
})
|
||||
|
||||
it('does not attribute old scrollback truncation to a complete current command', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.historyTruncated = true
|
||||
const result = text(await call(ctx, owner, 'short command'))
|
||||
expect(result).toBe('hello from stub')
|
||||
expect(result).not.toContain('<response clipped>')
|
||||
expect(result).not.toContain('beginning of this command output was dropped')
|
||||
})
|
||||
|
||||
it('closes a timed-out shell and reports bounded partial output', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', timeoutMs: 10 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.mode = 'wait-for-abort'
|
||||
const result = await call(ctx, owner, 'hang')
|
||||
expect(text(result)).toContain('timed out after 0 seconds or experienced an OOM error')
|
||||
expect(text(result)).toContain('partial output')
|
||||
expect(text(result)).toContain('next bash call starts from the workspace')
|
||||
expect(stub.sessions[0]?.closed).toContain('persistent bash command timed out')
|
||||
})
|
||||
|
||||
it.each(['wait-for-abort', 'end-on-abort'] as const)(
|
||||
'cancels %s work, resets the shell, and releases a queued call',
|
||||
async (mode) => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub', timeoutMs: 5_000 })
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.mode = mode
|
||||
const controller = new AbortController()
|
||||
const cancelled = call(ctx, owner, 'hang', controller.signal)
|
||||
const queued = call(ctx, owner, 'after cancellation')
|
||||
setTimeout(() => {
|
||||
controller.abort(new Error('caller stopped'))
|
||||
}, 5)
|
||||
|
||||
expect((await cancelled).isError).toBe(true)
|
||||
expect(text(await queued)).toBe('hello from stub')
|
||||
expect(stub.sessions[0]?.closed).toContain('persistent bash command aborted')
|
||||
expect(stub.sessions).toHaveLength(2)
|
||||
},
|
||||
)
|
||||
|
||||
it.each(['init-exit', 'init-timeout'] as const)(
|
||||
'fails initialization and closes the unusable shell for %s',
|
||||
async (mode) => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub' }, mode)
|
||||
expect((await call(ctx, owner, 'pwd')).isError).toBe(true)
|
||||
expect(stub.sessions[0]?.closed).toContain('persistent bash initialization failed')
|
||||
},
|
||||
)
|
||||
|
||||
it('clears a failed spawn without trying to close an unpublished shell', async () => {
|
||||
const { ctx, owner, stub } = await setup({ backendType: 'stub' }, 'spawn-error')
|
||||
expect((await call(ctx, owner, 'pwd')).isError).toBe(true)
|
||||
expect(stub.sessions).toHaveLength(0)
|
||||
})
|
||||
|
||||
it('resets a cached shell after startSend fails', async () => {
|
||||
const { ctx, owner, stub } = await setup()
|
||||
await call(ctx, owner, 'warm up')
|
||||
stub.sessions[0]!.mode = 'send-error'
|
||||
expect((await call(ctx, owner, 'fails')).isError).toBe(true)
|
||||
expect(stub.sessions[0]?.closed).toContain('persistent bash send failed')
|
||||
expect(text(await call(ctx, owner, 'recovers'))).toBe('hello from stub')
|
||||
expect(stub.sessions).toHaveLength(2)
|
||||
})
|
||||
|
||||
it('cancels and awaits a pending shell spawn when the plugin is disposed', async () => {
|
||||
const ctx = new Context()
|
||||
contexts.push(ctx)
|
||||
await ctx.plugin(SystemPrompt)
|
||||
await ctx.plugin(ToolRegistry)
|
||||
await ctx.plugin(AgentRegistry)
|
||||
await ctx.plugin(PtyService)
|
||||
const spawnStarted = Promise.withResolvers<undefined>()
|
||||
const spawnAborted = Promise.withResolvers<undefined>()
|
||||
ctx.pty.registerBackend({
|
||||
type: 'slow',
|
||||
spawn: spec => new Promise((_resolve, reject) => {
|
||||
spawnStarted.resolve(undefined)
|
||||
spec.signal?.addEventListener('abort', () => {
|
||||
spawnAborted.resolve(undefined)
|
||||
const reason: unknown = spec.signal?.reason
|
||||
reject(reason instanceof Error
|
||||
? reason
|
||||
: new Error('slow PTY spawn aborted', { cause: reason }))
|
||||
}, { once: true })
|
||||
}),
|
||||
})
|
||||
const fiber = await ctx.plugin(ToolBashPersistent, { backendType: 'slow' })
|
||||
const owner = agent(ctx, '/workspace')
|
||||
const running = call(ctx, owner, 'pwd')
|
||||
await spawnStarted.promise
|
||||
await fiber.dispose()
|
||||
await spawnAborted.promise
|
||||
expect((await running).isError).toBe(true)
|
||||
expect(ctx.pty.list(owner)).toEqual([])
|
||||
})
|
||||
|
||||
it('rejects invalid config and invalid calls', async () => {
|
||||
const { ctx, owner, stub } = await setup()
|
||||
expect((await call(ctx, undefined, 'pwd')).isError).toBe(true)
|
||||
expect(text(await call(ctx, owner, ' '))).toContain('command must be a non-empty string')
|
||||
|
||||
const controller = new AbortController()
|
||||
controller.abort(new Error('caller stopped'))
|
||||
expect((await call(ctx, owner, 'pwd', controller.signal)).isError).toBe(true)
|
||||
expect(stub.sessions).toHaveLength(0)
|
||||
|
||||
expect(() => {
|
||||
ToolBashPersistent.apply(new Context(), { backendType: '' })
|
||||
}).toThrow('backendType must be non-empty')
|
||||
expect(() => {
|
||||
ToolBashPersistent.apply(new Context(), { timeoutMs: 0 })
|
||||
}).toThrow('timeoutMs must be a positive safe integer')
|
||||
expect(() => {
|
||||
ToolBashPersistent.apply(new Context(), { maxOutputChars: 0 })
|
||||
}).toThrow('maxOutputChars must be a positive safe integer')
|
||||
expect(() => {
|
||||
ToolBashPersistent.apply(new Context(), { description: ' ' })
|
||||
}).toThrow('description must be non-empty')
|
||||
})
|
||||
})
|
||||
16
packages/pty/tool-bash-persistent/tsconfig.json
Normal file
16
packages/pty/tool-bash-persistent/tsconfig.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"extends": "../../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "src",
|
||||
"outDir": "lib/types"
|
||||
},
|
||||
"include": ["src"],
|
||||
"references": [
|
||||
{ "path": "../../../vendor/cordis" },
|
||||
{ "path": "../../core/agent" },
|
||||
{ "path": "../../core/tools" },
|
||||
{ "path": "../pty" },
|
||||
{ "path": "../../support/invariants" },
|
||||
{ "path": "../../util/timeout" }
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user