diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml index 1c4eadabc1..a54457715b 100644 --- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-capability-seams.md -2026-06-13-capability-seams.md: 46a2c39e927e859c7eb95956d8586f3bf04c7b1c -2026-06-13-capability-seams.zh.md: f44e3e68d2153149435b0fd0aaa5fd121cf3ecad +2026-06-13-capability-seams.md: 3c552c474b499b9f1c9f60242f4773750faadafb +2026-06-13-capability-seams.zh.md: 4e6100a2ce557d91fa18b5630c267f37f1bc0f00 diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md index 46a2c39e92..3c552c474b 100644 --- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md +++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md @@ -15,7 +15,7 @@ This is distinct from "who provides vs. needs a capability at runtime", which Co A swappable capability has **three roles**: 1. **Service Definition** — the Cordis `Service` and vocabulary types owning `ctx.` and depending only on the vocabulary the contract needs (e.g. `dsh-shell`: `ShellExecutor`, `ShellRunResult`, `ShellProcess`). A definition may be an abstract class or a concrete registry service; it is never a TypeScript `interface`. -2. **Service Provider** — a plugin that supplies or registers an implementation (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed and remote providers are sibling packages implementing or registering against the same Service Definition. +2. **Service Provider** — a plugin that supplies or registers an implementation (e.g. `dsh-bash-local`: subprocesses, provider-managed range termination, spill-file truncation). The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns the local provider's OS-specific range mechanics. Sandboxed and remote providers are sibling packages implementing or registering against the same Service Definition. 3. **Consumer** — what the model and plugins program against (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic job runtime). Consumers inject the service key and never import provider-specific types. The role names use title case: **Service Definition**, **Service Provider**, and **Consumer**. Generic uses of `provider` and `consumer` remain lowercase. diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md index f44e3e68d2..4e6100a2ce 100644 --- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md @@ -15,7 +15,7 @@ harness 具有可替换的能力，包括 shell 执行和模型提供方。一 一项可替换的能力包含**三个角色**： 1. **Service Definition**——拥有 `ctx.` 的 Cordis `Service` 和词汇类型，仅依赖约定所需的词汇（例如 `dsh-shell`：`ShellExecutor`、`ShellRunResult`、`ShellProcess`）。Service Definition 可以是抽象类，也可以是具体的注册表服务；绝不是 TypeScript `interface`。 -2. **Service Provider**——提供或注册实现的插件（例如 `dsh-bash-local`：子进程、进程组 kill、spill 文件截断）。沙箱化和远程 Service Provider 是依据同一 Service Definition 实现或注册的兄弟包。 +2. **Service Provider**——提供或注册实现的插件（例如 `dsh-bash-local`：子进程、由提供方管理的范围终止、spill 文件截断）。[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责本地提供方的 OS 特有范围机制。沙箱化和远程 Service Provider 是依据同一 Service Definition 实现或注册的兄弟包。 3. **Consumer**——模型和插件编程所面向的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。Consumer 注入服务键，从不导入 Service Provider 特有的类型。 角色名使用标题式大小写：**Service Definition**、**Service Provider** 和 **Consumer**。泛指的 `provider` 和 `consumer` 仍使用小写。 diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml index aaa3f9f1d1..b2ebf2057f 100644 --- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md -2026-07-06-timeout-deadline-library.md: 24dcabfd039e553af28fd3cc1d2c7f717ee66509 -2026-07-06-timeout-deadline-library.zh.md: 5f31cf21606345bb323ce3f839b5cb939def5a48 +2026-07-06-timeout-deadline-library.md: 6f726938731f18386105ff1180c79fef981c95bf +2026-07-06-timeout-deadline-library.zh.md: 48bd7b4b91efd0045c03e3e1e1e9e37656b4dcf6 diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md index 24dcabfd03..6f72693873 100644 --- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md +++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md @@ -8,11 +8,11 @@ English | [中文](2026-07-06-timeout-deadline-library.zh.md) Timeout handling was drifting apart across the tool-bearing capabilities, and the divergence was not superficial — it was the same logic re-implemented three ways, each with its own subtle correctness burden. -- **bash** (then in the bash-local implementation's `run.ts`) had a full, correct timeout inside the process plumbing: a config-clamped `timeoutMs`, two independent triggers — a `killTimer` for the timeout and an `onAbort` listener for upstream cancellation — each calling one `kill()` closure that escalates SIGTERM→grace→SIGKILL on the process group, and two orthogonal outcome booleans (`timedOut`, `aborted`) latched independently. After this consolidation, the plumbing — [packages/subprocess/subprocess-local/src/spawn.ts](../../../../packages/subprocess/subprocess-local/src/spawn.ts) — only reacts to aborts; [packages/shell/bash-local/src/index.ts](../../../../packages/shell/bash-local/src/index.ts) owns the fused deadline and the `timedOut`/`aborted` classification. +- **bash** (then in the bash-local implementation's `run.ts`) had a full, correct timeout inside the process plumbing: a config-clamped `timeoutMs`, two independent triggers — a `killTimer` for the timeout and an `onAbort` listener for upstream cancellation — each calling one `kill()` closure that drove the subprocess termination path, and two orthogonal outcome booleans (`timedOut`, `aborted`) latched independently. After this consolidation, the plumbing — [packages/subprocess/subprocess-local/src/spawn.ts](../../../../packages/subprocess/subprocess-local/src/spawn.ts) — only reacts to aborts; [packages/shell/bash-local/src/index.ts](../../../../packages/shell/bash-local/src/index.ts) owns the fused deadline and the `timedOut`/`aborted` classification. - **web_fetch** ([packages/web/web-fetch-http/src/provider.ts](../../../../packages/web/web-fetch-http/src/provider.ts)) had a correct but *hand-rolled* timeout: it constructed an `AbortController`, wired `setTimeout(() => controller.abort(new WebError(…, 'WEB_FETCH_TIMEOUT')))`, manually added and removed the upstream-signal listener, cleared the timer in a `finally`, and recovered the timeout reason from `signal.reason` in a `translateAbortOrNetwork` helper because the reader surfaces a bare `AbortError`. - **web_search** ([packages/web/tool-web/src/search.ts](../../../../packages/web/tool-web/src/search.ts)) had **no timeout at all**: `WebSearchRequest` ([packages/web/web/src/types.ts](../../../../packages/web/web/src/types.ts)) carries no `timeoutMs` field, and each provider's `search()` only forwards `exec.signal`. (web_search stays untimed here — see Consequences.) -Each new external-process or network tool re-derived the same four things — clamp the requested value, start a timer, fuse the timeout with upstream cancellation, and distinguish "timed out" from "cancelled" on the way out — and the fusion and reason-recovery are exactly the parts that are easy to get subtly wrong (web_fetch's `signal.reason` dance is evidence). At the same time, the *termination* each performs is irreducibly different: bash kills an OS process group (work runs in a child process, outside this runtime, reachable only by signal), while web aborts an in-process `fetch` (undici tears down the socket). There is no single mechanism that can stop all of them. +Each new external-process or network tool re-derived the same four things — clamp the requested value, start a timer, fuse the timeout with upstream cancellation, and distinguish "timed out" from "cancelled" on the way out — and the fusion and reason-recovery are exactly the parts that are easy to get subtly wrong (web_fetch's `signal.reason` dance is evidence). At the same time, the *termination* each performs is irreducibly different: bash asks its subprocess provider to terminate an OS-owned range, while web aborts an in-process `fetch` and lets undici tear down the socket. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns the local scope, Job, and fallback mechanisms; there is no single mechanism that can stop every capability's work. ## Decision @@ -87,17 +87,17 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): | The default/max *values* | the capability's config | | The timeout `code` string | the capability (`WEB_FETCH_TIMEOUT` ≠ `BASH_TIMEOUT`) | -The signal only *notifies*; termination is always the listener's job, and the listener differs by capability. bash writes its own `addEventListener('abort', kill)` because the OS process lives outside this runtime and nothing else will kill it; web hands `d.signal` to `fetch` and undici tears down the socket. This is why file read/write/edit take **no** `timeoutMs`: a local syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. Both reference agents leave file I/O untimed for the same reason. +The signal only *notifies*; termination is always the listener's job, and the listener differs by capability. bash writes its own `addEventListener('abort', kill)` because the OS process lives outside this runtime and its subprocess provider must drive the owned range to settlement; web hands `d.signal` to `fetch` and undici tears down the socket. This is why file read/write/edit take **no** `timeoutMs`: a local syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. Both reference agents leave file I/O untimed for the same reason. ### How each capability consumes it - **web_fetch** — the tool stays validate-and-forward; the provider's hand-rolled controller + `setTimeout` + manual listener + `finally` + `signal.reason` recovery is replaced by provider-owned `deadline`/`timeoutOf`. A pre-aborted upstream signal still throws `WEB_ABORTED` up front; otherwise `fetch` runs against the fused `d.signal`, and `translateAbortOrNetwork` classifies a thrown error by the signal (`timeoutOf` → `WEB_FETCH_TIMEOUT`, else aborted → `WEB_ABORTED`, else network → `WEB_PROVIDER_ERROR`). The public error-code contract is unchanged, and `TimeoutReason` never crosses the web seam as the public error. -- **bash** — `resolve()` clamps the request into an explicit spec. Foreground `run()` creates the deadline and passes its signal to process execution, whose existing abort listener performs the process-group kill. The executor classifies the first abort as timeout or cancellation. Background starts remain timeout-free and forward only upstream cancellation. +- **bash** — `resolve()` clamps the request into an explicit spec. Foreground `run()` creates the deadline and passes its signal to process execution, whose abort listener calls `SubprocessHandle.terminate()` and awaits the same provider-managed range. The executor classifies the first abort as timeout or cancellation. Background starts remain timeout-free and forward only upstream cancellation. - **LLM adapters** — `dsh-llm-deepseek` and `dsh-llm-pi-ai` wrap actual transport iteration with `idleWatchdog`. The five-minute configured interval covers only outstanding provider demand, not time the downstream consumer spends between chunks. The direct DeepSeek adapter also pulses that outstanding demand when its SSE parser observes a comment, without yielding the comment as a `StreamChunk` or writing it to the session log. The pi-ai SDK does not expose comment activity to its adapter, so that path can rearm only when the SDK yields. The stable signal reaches `fetch` or the SDK for the whole call, so timeout closes the underlying request and maps to `TIMEOUT`, while an earlier caller abort maps to `ABORTED`. ## Consequences -- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the Service Definition type `ShellRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched. +- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. Timeout classification does not alter provider-owned termination: local POSIX ranges use TERM→grace→KILL, while Windows ordinary ranges terminate immediately. The Service Definition type `ShellRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched. - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. An always-0 field read by nothing is dead weight under the per-file coverage gate. - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`. - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met). @@ -107,10 +107,10 @@ Out of scope, named to mark the boundary: `web_search` can gain an optional mode ## Alternatives considered -**A unified timeout *plugin* / `ctx.timeout` service.** Rejected on microkernel grounds. A service that could stop any tool's work would have to understand every capability's termination mechanism (process-group SIGKILL, socket teardown, syscall-boundary checks) — the "kernel knows too much" the architecture forbids. Codex's `ExecExpiration` is scoped to the exec family precisely because the kill it drives (`killpg`) is process-family-specific; MCP and model-stream keep their own. There is no coherent middle layer that owns termination for everything, so the shared piece can only be the pure timing/classification half — a library, not a service. +**A unified timeout *plugin* / `ctx.timeout` service.** Rejected on microkernel grounds. A service that could stop any tool's work would have to understand every capability's termination mechanism (native scope or Job termination, fallback process-group signalling, socket teardown, syscall-boundary checks) — the "kernel knows too much" the architecture forbids. Codex's `ExecExpiration` is scoped to the exec family precisely because the kill it drives (`killpg`) is process-family-specific; MCP and model-stream keep their own. There is no coherent middle layer that owns termination for everything, so the shared piece can only be the pure timing/classification half — a library, not a service. **Per-tool ad-hoc timeout, no shared code (the prior status quo, and Claude Code's choice).** Rejected because it was already producing divergence and duplicated correctness burden: web_fetch hand-rolled the exact controller/reason logic that future network/process-backed tools would each have to re-derive, and the fusion + `signal.reason` recovery are the error-prone parts. Claude Code tolerates full duplication; this repo has a single shared abort channel (`exec.signal` on every `execute`) that makes a small shared primitive strictly cleaner, so the cost/benefit differs. **A `withTimeout(promise, ms)` wrapper instead of a signal factory.** Rejected because racing a promise against a timer resolves the *tool-call* promise on deadline without stopping the underlying work — the child process or fetch socket leaks on. Handing out a signal and requiring the capability to listen is what forces a real termination path to exist. This mirrors the "dispose must reach quiescence, not just request it" defensive rule. -**Keep separate bash timeout and cancellation triggers.** Rejected because one deadline signal removes the bespoke timer and standardizes classification. Racing causes report whichever abort arrived first, while the existing SIGTERM-to-SIGKILL termination path remains unchanged. +**Keep separate bash timeout and cancellation triggers.** Rejected because one deadline signal removes the bespoke timer and standardizes classification. Racing causes report whichever abort arrived first, while the provider-owned termination path is independent of which cause won. diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md index 5f31cf2160..48bd7b4b91 100644 --- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md @@ -8,11 +8,11 @@ Status: implemented 超时处理在各个承载工具的能力之间逐渐分化，而且这种分化并非表面的：同一套逻辑被以三种方式重新实现，各自带有微妙的正确性负担。 -- **bash**（当时位于 bash-local 实现的 `run.ts`）在进程管道内部有一套完整、正确的超时实现：一个经配置钳位的 `timeoutMs`，两个独立触发器（用于超时的 `killTimer` 和用于上游取消的 `onAbort` 监听器），各自调用同一个 `kill()` 闭包对进程组执行 SIGTERM→宽限期→SIGKILL 升级，以及两个正交的结果布尔值（`timedOut`、`aborted`）独立锁存。经此次整合之后，这套管道——位于 [packages/subprocess/subprocess-local/src/spawn.ts](../../../../packages/subprocess/subprocess-local/src/spawn.ts)——只响应中止；[packages/shell/bash-local/src/index.ts](../../../../packages/shell/bash-local/src/index.ts) 拥有融合的 deadline 以及 `timedOut`/`aborted` 分类。 +- **bash**（当时位于 bash-local 实现的 `run.ts`）在进程管道内部有一套完整、正确的超时实现：一个经配置钳位的 `timeoutMs`，两个独立触发器（用于超时的 `killTimer` 和用于上游取消的 `onAbort` 监听器），各自调用同一个 `kill()` 闭包驱动子进程终止路径，以及两个正交的结果布尔值（`timedOut`、`aborted`）独立锁存。经此次整合之后，这套管道——位于 [packages/subprocess/subprocess-local/src/spawn.ts](../../../../packages/subprocess/subprocess-local/src/spawn.ts)——只响应中止；[packages/shell/bash-local/src/index.ts](../../../../packages/shell/bash-local/src/index.ts) 拥有融合的 deadline 以及 `timedOut`/`aborted` 分类。 - **web_fetch**（[packages/web/web-fetch-http/src/provider.ts](../../../../packages/web/web-fetch-http/src/provider.ts)）有一套正确但*手写*的超时：构造一个 `AbortController`，连接 `setTimeout(() => controller.abort(new WebError(…, 'WEB_FETCH_TIMEOUT')))`，手动添加和移除上游信号监听器，在 `finally` 中清除定时器，并在 `translateAbortOrNetwork` 辅助函数中从 `signal.reason` 恢复超时原因（因为 reader 只抛出裸 `AbortError`）。 - **web_search**（[packages/web/tool-web/src/search.ts](../../../../packages/web/tool-web/src/search.ts)）**完全没有超时**：`WebSearchRequest`（[packages/web/web/src/types.ts](../../../../packages/web/web/src/types.ts)）不携带 `timeoutMs` 字段，各提供方的 `search()` 只转发 `exec.signal`。（web_search 在本次设计中保持无超时——见「后果」。） -每个新的外部进程或网络工具都要重新推导同样四件事：钳位请求值、启动定时器、将超时与上游取消融合、在出口处区分「超时」与「已取消」。而融合与原因恢复恰恰是最容易出微妙错误的部分（web_fetch 的 `signal.reason` 处理就是证据）。与此同时，各能力执行的*终止*操作不可归约地不同：bash 杀死一个 OS 进程组（工作运行在子进程中，在本运行时之外，只能通过信号触达），而 web 中止一个进程内的 `fetch`（undici 拆除 socket）。不存在一个能停止所有能力工作的单一机制。 +每个新的外部进程或网络工具都要重新推导同样四件事：钳位请求值、启动定时器、将超时与上游取消融合、在出口处区分「超时」与「已取消」。而融合与原因恢复恰恰是最容易出微妙错误的部分（web_fetch 的 `signal.reason` 处理就是证据）。与此同时，各能力执行的*终止*操作不可归约地不同：bash 请求其子进程提供方终止由 OS 拥有的范围，而 web 中止一个进程内的 `fetch`，由 undici 拆除 socket。[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责本地 scope、Job 与 fallback 机制；不存在一个能停止所有能力工作的单一机制。 ## 决策 @@ -87,17 +87,17 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): | 默认值/最大值*数值* | 各能力的配置 | | 超时 `code` 字符串 | 各能力（`WEB_FETCH_TIMEOUT` ≠ `BASH_TIMEOUT`） | -信号只*通知*；终止始终是监听方的职责，而监听方因能力而异。bash 自行编写 `addEventListener('abort', kill)`，因为 OS 进程存在于本运行时之外，没有别的东西会杀死它；web 将 `d.signal` 交给 `fetch`，由 undici 拆除 socket。这也是文件读/写/编辑**不接受** `timeoutMs` 的原因：本地系统调用最多只能尽力中止，超时无法强制 `fsync`/`rename` 停止，添加超时将是一个违反「显式优于隐式」的隐式默认值。两个参考 agent（智能体）出于同样的原因对文件 I/O 不设超时。 +信号只*通知*；终止始终是监听方的职责，而监听方因能力而异。bash 自行编写 `addEventListener('abort', kill)`，因为 OS 进程存在于本运行时之外，必须由子进程提供方驱动其拥有的范围达到完全停稳；web 将 `d.signal` 交给 `fetch`，由 undici 拆除 socket。这也是文件读/写/编辑**不接受** `timeoutMs` 的原因：本地系统调用最多只能尽力中止，超时无法强制 `fsync`/`rename` 停止，添加超时将是一个违反「显式优于隐式」的隐式默认值。两个参考 agent（智能体）出于同样的原因对文件 I/O 不设超时。 ### 各能力如何消费该库 - **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码约定不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。 -- **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者既有的 abort 监听器执行进程组 kill。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。 +- **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者的 abort 监听器调用 `SubprocessHandle.terminate()`，并等待同一个由提供方管理的范围。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。 - **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。DeepSeek 直连适配器还会在其 SSE（Server-Sent Events）解析器观察到注释时，对该项尚未结算的 demand 调用 `pulse()`；该注释既不会作为 `StreamChunk` 产出，也不会写入会话日志。pi-ai SDK 不会向其适配器暴露注释活动，因此该路径只能在 SDK 产出值时重新启动定时器。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。 ## 后果 -- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，Service Definition 类型 `ShellRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。 +- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。超时分类不改变由提供方管理的终止：本地 POSIX 范围使用 TERM→宽限期→KILL，Windows 普通范围则立即终止。Service Definition 类型 `ShellRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。 @@ -107,10 +107,10 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): ## 曾考虑的替代方案 -**统一的超时*插件* / `ctx.timeout` 服务。** 基于微内核原则否决。一个能停止任何工具工作的服务必须理解每个能力的终止机制（进程组 SIGKILL、socket 拆除、系统调用边界检查），这正是架构所禁止的「内核知道太多」。Codex 的 `ExecExpiration` 被限定于 exec 族，正是因为它驱动的 kill（`killpg`）是进程族特有的；MCP 和模型流各自保有自己的。不存在一个连贯的中间层能为所有东西拥有终止权，因此共享部分只能是纯计时/分类那一半——一个库，而非服务。 +**统一的超时*插件* / `ctx.timeout` 服务。** 基于微内核原则否决。一个能停止任何工具工作的服务必须理解每个能力的终止机制（原生 scope 或 Job 终止、fallback 进程组信号、socket 拆除、系统调用边界检查），这正是架构所禁止的「内核知道太多」。Codex 的 `ExecExpiration` 被限定于 exec 族，正是因为它驱动的 kill（`killpg`）是进程族特有的；MCP 和模型流各自保有自己的。不存在一个连贯的中间层能为所有东西拥有终止权，因此共享部分只能是纯计时/分类那一半——一个库，而非服务。 **每个工具各自实现超时，不共享代码（先前的现状，也是 Claude Code 的选择）。** 否决，因为它已经在产生分化和重复的正确性负担：web_fetch 手写了与未来网络/进程类工具各自需要重新推导的完全相同的 controller/reason 逻辑，而融合 + `signal.reason` 恢复正是容易出错的部分。Claude Code 容忍完全重复；本仓库有一个统一的共享 abort 通道（每次 `execute` 上的 `exec.signal`），使得采用一个小型共享原语明显更简洁，因此成本/收益不同。 **用 `withTimeout(promise, ms)` 包装器代替信号工厂。** 否决，因为让 promise 与定时器竞争只是在截止时间到达时 resolve *工具调用*的 promise，而不会停止底层工作——子进程或 fetch socket 会泄漏。分发信号并要求能力监听，才能强制一条真实的终止路径存在。这与「dispose 必须达到完全停稳，而非仅仅请求它」的防御性规则一致。 -**保留 bash 独立的超时和取消触发器。** 否决，因为一个 deadline 信号移除了定制定时器并标准化了分类。发生竞争时，报告先到达的那个 abort 作为原因，而既有的 SIGTERM→SIGKILL 终止路径保持不变。 +**保留 bash 独立的超时和取消触发器。** 否决，因为一个 deadline 信号移除了定制定时器并标准化了分类。发生竞争时，报告先到达的那个 abort 作为原因，由提供方管理的终止路径不受哪个原因先胜出的影响。 diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml index 712a1af3cb..3c883f7d6c 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md -2026-07-10-single-file-executable-sdk-runtime-distribution.md: 756cf419df2dff70973eee9c1598950158dbfc1d -2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: aa9c1c1b93b19a8310fff65bdfafa54f237c0e3c +2026-07-10-single-file-executable-sdk-runtime-distribution.md: 5533c38d635d04c8799658fc1f6bcec8543d1dab +2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 05800082034f0d1bd5034fc5bb17f09356d84dd9 diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md index 756cf419df..5533c38d63 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md @@ -44,7 +44,7 @@ The deploy root includes `@deepseek-ai/dsh-mcp-client` as an explicitly supporte ### Build pipeline and artifacts -[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → inject pkg configuration whose bin is `node_modules/@deepseek-ai/dsh/lib/bin.js` and whose assets cover dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime--` under `dist-exe/` and copy it into the runtime directory. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. +[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime--` under `dist-exe/` and copy it into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment decision](2026-08-28-subprocess-native-containment.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) runs [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) on Linux/Windows x64 for pull requests and Linux ARM64 plus both macOS architectures for master pushes. The [public publication workflow](../../archived/process/2026-08-11-python-publication-workflow.md) calls it for all five targets; `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / macos-x64 (`macos-15-intel`) / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, proves their package and executable provenance, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests and master pushes additionally run a real DeepSeek two-turn tool smoke on their selected targets; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS checks the runtime, ripgrep, and PTY helper architectures and verifies that all three deployment targets fit the wheel tag. A full five-target run retains six artifacts, each containing one release file: the platform-independent SDK wheel and five native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and five native runtime wheels, then a single serialized job checks and publishes all six to the project PyPI registry. The [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows target and the explicit exclusion of Windows arm64. diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md index aa9c1c1b93..0580008203 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md @@ -44,7 +44,7 @@ exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真 ### 构建流水线与产物 -[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 注入 pkg 配置，其中 bin 为 `node_modules/@deepseek-ai/dsh/lib/bin.js`，assets 覆盖动态读取的 profile、bundle、前端、preset、原生库与配置文件 → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime--` 写入 `dist-exe/` 并拷回运行时目录。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 为 pkg 提供稳定的单实例布局，再由显式物化步骤消除符号链接；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 +[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`，其中包含作为载体根目录 `runtime-bootstrap.mjs` 的 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) → 恢复 legacy deploy 遗漏的直接工作区包，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 验证已部署的 bootstrap，并注入以该文件为 bin 的 pkg 配置及覆盖动态读取 profile、bundle、前端、preset、原生库与配置文件的 assets → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime--` 写入 `dist-exe/` 并拷回运行时目录。该 bootstrap 由 Python runtime 拥有；普通启动时它调用公开 CLI export，而提供方私有选择会分派到同一个 `@deepseek-ai/dsh-subprocess-local/runner` 核心，不改变 CLI 语法，也不增加另一个可执行文件；[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责这条私有路径。Linux CI 会在匹配的 manylinux 2.28 容器中重新构建 `pty.node`，因为 legacy deploy 会遗漏这一安装副作用。每个目标都会把对应的原生 `@vscode/ripgrep` 二进制复制到可执行文件旁，作为必需的 `-rg` 伴随文件；pkg 运行时通过 `process.pkg` 选择该伴随文件，普通 Node 执行则直接使用 `@vscode/ripgrep`。macOS 使用对应目标的预构建产物，并额外生成所需的 `-spawn-helper`。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 为 pkg 提供稳定的单实例布局，再由显式物化步骤消除符号链接；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。 CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)：[安装后 wheel 包验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)在拉取请求上运行 Linux/Windows x64，在 master 推送上运行 Linux ARM64 与两种 macOS 架构。[公开发布工作流](../../archived/process/2026-08-11-python-publication-workflow.md)调用它构建全部五个目标；`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64（`ubuntu-24.04-arm`）、macos-arm64、macos-x64（`macos-15-intel`）与 win-x64（`windows-2025`）分别进行原生构建，并在适用平台缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv，证明包与可执行文件来源，再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景。可信拉取请求与 master 推送还会在各自选定的目标上运行真实 DeepSeek 双轮工具冒烟测试；fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖，并额外运行 manylinux 2.28 冒烟测试；macOS 则检查 runtime、ripgrep 与 PTY helper 的架构，并验证三个载荷的部署目标都符合 wheel 包标签。完整构建五个目标时保留 6 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 5 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v` 标签流水线，构建一个 SDK wheel 包和 5 个原生运行时 wheel 包，再由单个串行任务校验并将这 6 个文件发布到项目的 PyPI 注册表。[`python/sdk-runtime` README](../../../../python/sdk-runtime/README.zh.md)负责 Windows 目标及对 Windows arm64 的明确排除。 diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml index e23ba3b605..16ecfcc400 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md -2026-07-16-explicit-turn-cancellation.md: ee4253ba607d3468c05b61d6fb0fbc5efcf9f9d7 -2026-07-16-explicit-turn-cancellation.zh.md: d98d2c114056c44f131a2fe989f0b1f544127976 +2026-07-16-explicit-turn-cancellation.md: 09631349226837d7f93112fe5e9c517f2fee099c +2026-07-16-explicit-turn-cancellation.zh.md: baf039d49578895d53ffae4c6b88d29b3d1563b6 diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md index ee4253ba60..0963134922 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md @@ -20,7 +20,7 @@ AgentLoop privately owns one `TurnCancellation` per prospective turn. It install The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer is latched and runs when the aborted activity converges to idle — a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work. -The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn. +The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's provider-managed termination and join boundary; the [native-containment decision](2026-08-28-subprocess-native-containment.md) owns the supported local scope, Job, and fallback mechanics. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn. `ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam. diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md index d98d2c1140..baf039d495 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md @@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。 -显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 API 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)）。进入 pre-step 时、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。 +显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 API 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)）。进入 pre-step 时、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器由提供方管理的终止与等待边界；[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责受支持本地路径上的 scope、Job 与 fallback 机制。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。 diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml index 40454e9a56..441e67f823 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md -2026-07-28-portable-execution-world-consumers.md: 760005f1460890222c5af1ea0ec4eaf9cb29f360 -2026-07-28-portable-execution-world-consumers.zh.md: d78b04a5af785be0707d06e519819f95c524d92d +2026-07-28-portable-execution-world-consumers.md: 787fe341e58cc212c99e0f35f07eea8e83daf000 +2026-07-28-portable-execution-world-consumers.zh.md: a558a5af64437b8743e741ace4ccf27079501721 diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md index 760005f146..787fe341e5 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md +++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md @@ -18,13 +18,13 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream. -The subprocess interface owns executable lookup and process primitives: ordinary raw or collected process spawning and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer. +The subprocess interface owns executable lookup and process primitives: ordinary raw or collected process spawning and `spawnTerminal()`. An ordinary handle keeps target identity private: `.done` reports the direct target, while `terminate()` and `waitForExit()` control and observe the same provider-managed range. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns local Linux scopes, Windows Jobs, and their disclosed fallbacks. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every member of its provider-owned range; an observational fallback limits that range to identities it can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer. Generic consumers use that execution world: - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`. - `dsh-lsp-stdio` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged. -- `dsh-terminal-bash` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation. +- `dsh-terminal-bash` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-managed session quiescence to the handle's awaited termination operation. ## E2B POC boundary @@ -68,6 +68,6 @@ A remote execution provider implements only its shared sandbox owner plus filesy The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers. -The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer. +The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. On supported Linux hosts, the user-systemd scope retains descendants that call `setsid` or reparent, while process inspection continues to own foreground attribution and synchronous fallback evidence. Other hosts use the observational teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer. The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, and adapter artifacts remain until sandbox deletion. These are provider constraints, not justification for compatibility shims or more E2B packages. diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md index d78b04a5af..a558a5af64 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md @@ -18,13 +18,13 @@ Status: implemented 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。 -进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。 +进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。普通句柄把 target identity 保持为私有事实：`.done` 报告 direct target，`terminate()` 与 `waitForExit()` 则控制并观察同一个由提供方管理的范围。[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责本地 Linux scope、Windows Job 及其已声明的 fallback。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方拥有的范围中每个成员完全停稳；观察型 fallback 只能把该范围限制为它仍可观察到的 identity。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。 通用消费方使用该执行世界： - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。 - `dsh-lsp-stdio` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。 -- `dsh-terminal-bash` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。 +- `dsh-terminal-bash` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把由提供方管理的会话完全停稳委托给句柄上须等待的终止操作。 ## E2B POC 边界 @@ -68,6 +68,6 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。 -本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。 +本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。在受支持的 Linux 宿主上，user-systemd scope 会保留调用 `setsid` 或发生 reparent 的后代，进程检查则继续负责前台归属与同步 fallback 证据。其他宿主使用观察型拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。 E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；适配器产物会一直保留到沙箱删除。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。 diff --git a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.i18n.yaml index e28fbd3024..e846f8f186 100644 --- a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md -2026-08-22-single-dsh-application-launcher.md: 21fc99790c506f4e3f6e8b3ab572121e1cf1a882 -2026-08-22-single-dsh-application-launcher.zh.md: 4175bd675889ec01db46ebca157aff35c9ef9cab +2026-08-22-single-dsh-application-launcher.md: 630040c75c4c20c57b5e26288663265174331ca5 +2026-08-22-single-dsh-application-launcher.zh.md: 9bd51e6c4e8b7ab60cbabc384431bc4e22a6b522 diff --git a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md index 21fc99790c..630040c75c 100644 --- a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md +++ b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md @@ -46,7 +46,7 @@ Direct SDK use follows normal Harness-home resolution: explicit `dshHome`, inher ### Python runtime -The Python runtime wheel packages the ordinary `@deepseek-ai/dsh` CLI from `node_modules/@deepseek-ai/dsh/lib/bin.js` through the private `dsh-python-runtime-closure` deploy manifest. The Python client selects `dsh --profile sdk` by default, ordered patch files, and an explicit Harness home; the runnable example under `python/sdk/examples` selects `sdk-minimal`. The installed `dsh` console command exposes the same profile grammar and the separately packaged `web` application. +The Python runtime wheel stages [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the `dsh-python-runtime-closure` entry. Its ordinary branch calls the public CLI export; a provider-private selector dispatches to the internal subprocess runner before CLI parsing and is not an application entry point. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns that private dispatch. The Python client selects `dsh --profile sdk` by default, ordered patch files, and an explicit Harness home; the runnable example under `python/sdk/examples` selects `sdk-minimal`. The installed `dsh` console command exposes the same profile grammar and the separately packaged `web` application. The executable family is `deepseek-harness-sdk-runtime--`. The SDK wire, wheel and import distribution names, sidecar names, and wire identity `deepseek-harness-sdk-runtime` remain stable. The SDK package family is `@deepseek-ai/dsh-sdk-client`, `@deepseek-ai/dsh-sdk-protocol`, and `@deepseek-ai/dsh-sdk-jsonrpc-server`; `@deepseek-ai/dsh-acp` remains the ACP protocol plugin. There is no Python-specific Node application, checked-in complete config, compatibility package, forwarding executable, fallback parser, or SDK/ACP launcher alias. [docs/architecture.md](../../../../docs/architecture.md) owns this launch, and the [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows carrier. diff --git a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.zh.md b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.zh.md index 4175bd6758..9bd51e6c4e 100644 --- a/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.zh.md @@ -46,7 +46,7 @@ SDK 用户通过 profile 自定义插件。`dsh plugin --profile ...` 管 ### Python 运行时 -Python 运行时 wheel 通过私有 `dsh-python-runtime-closure` 部署 manifest，打包来自 `node_modules/@deepseek-ai/dsh/lib/bin.js` 的普通 `@deepseek-ai/dsh` CLI。Python 客户端默认选择 `dsh --profile sdk`、有序 patch 文件与显式 Harness home；`python/sdk/examples` 下的可运行示例选择 `sdk-minimal`。安装的 `dsh` 控制台命令暴露相同 profile 语法与单独打包的 `web` 应用。 +Python 运行时 wheel 将 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) 暂存为 `dsh-python-runtime-closure` 入口。其普通分支调用公开 CLI export；提供方私有选择会在 CLI 解析前分派到内部子进程 runner，而不是应用入口。[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责该私有分派。Python 客户端默认选择 `dsh --profile sdk`、有序 patch 文件与显式 Harness home；`python/sdk/examples` 下的可运行示例选择 `sdk-minimal`。安装的 `dsh` 控制台命令暴露相同 profile 语法与单独打包的 `web` 应用。 可执行文件族是 `deepseek-harness-sdk-runtime--`。SDK 协议格式、wheel 与 import 分发名称、伴随文件名称，以及协议 identity `deepseek-harness-sdk-runtime` 保持稳定。SDK 包族是 `@deepseek-ai/dsh-sdk-client`、`@deepseek-ai/dsh-sdk-protocol` 与 `@deepseek-ai/dsh-sdk-jsonrpc-server`；`@deepseek-ai/dsh-acp` 继续作为 ACP 协议插件。仓库不保留 Python 专用 Node 应用、检入的完整配置、兼容包、转发可执行文件、后备解析器或 SDK／ACP 启动别名。[docs/architecture.md](../../../../docs/architecture.zh.md)负责该启动方式，[`python/sdk-runtime` README](../../../../python/sdk-runtime/README.zh.md)负责 Windows 载体。 diff --git a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml new file mode 100644 index 0000000000..805b1f08c0 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md +2026-08-28-subprocess-native-containment.md: 0c03884bba67dab6e2e38f96ce2e874ed62ba00f +2026-08-28-subprocess-native-containment.zh.md: b7850e1c4fee06dfeb1a05c968d132de5994686f diff --git a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md new file mode 100644 index 0000000000..0c03884bba --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md @@ -0,0 +1,83 @@ +# Agent Note: Native owners contain escaped subprocess descendants + +Status: implemented + +English | [中文](2026-08-28-subprocess-native-containment.zh.md) + +## Problem + +Detached POSIX process groups, Windows direct-parent traversal, and PTY descendant scans describe only members that remain observable through one process relationship. A child can call `setsid`, reparent, or outlive its direct parent and leave those ranges, so terminating the apparent tree can return while work, ports, or files remain active. A direct target result also does not prove that every descendant has stopped. + +The ordinary subprocess handle cannot solve this gap by publishing a PID. Linux scope setup and the Windows Job runner establish target identity asynchronously, a PID does not name the complete managed range, and consumers would be forced to infer whether startup committed. The public result, range ownership, private startup protocol, and packaged entry therefore need separate owners. + +## Decision + +`LocalSubprocessRuntime` selects one provider-private managed-range owner before a target can execute. Eligible Linux ordinary and PTY launches enter a transient user-systemd scope; eligible Windows ordinary launches enter an unnamed kill-on-close Job owned by a private runner. Unsupported hosts use the existing weaker fallback with one provider-lifetime warning. The provider never replays a target after a selected native path may have executed it. + +An ordinary `SubprocessHandle` has no PID or public startup state. `.done` reports the direct target result or startup/provider failure, `terminate()` signals the selected range, and `waitForExit()` succeeds only after that same range is proven empty. `SubprocessTerminalHandle.pid` remains part of the terminal contract because PTY identity and foreground inspection require it. + +### Linux scope and one-shot bootstrap + +The first eligible Linux ordinary or PTY call in one runtime deeply checks the exact runner entry, the libc `execve` and `fcntl` bindings, the readable user manager, and literal-argv transient-scope support. Failed deep probes are retried, while the first success is cached. Each later eligible call still performs a lightweight user-manager reachability probe before target execution. Once selected, a scope, protocol, state-query, or pre-exec failure is reported through that launch and never switches to fallback. + +The parent creates one 0700 directory with a complete 0600 `launch-request.json` containing the final target cwd and environment. The private `DSH_SUBPROCESS_RUNNER` value locates that request while the runner starts from the provider cwd and a bootstrap-safe environment. `systemd-run --user --scope --quiet --collect --expand-environment=no` registers its process in the scope, then the one-shot bootstrap removes and validates the request, changes to the target cwd, restores the complete target environment, resolves a bare executable with the target PATH rules, clears `FD_CLOEXEC` on fd 0 through fd 2, and calls libc `execve()` with the original argv. The bootstrap becomes the target in place and preserves its inherited stdio; it does not remain as a supervisor. + +Request consumption or a manager observation of a loaded unit establishes scope ownership. Unit absence before either fact remains unresolved while the direct launcher is running. If that launcher exits while the request remains unconsumed, the direct result rejects with the startup failure while range observation records that the scope never existed and resolves the empty-range wait. The parent checks this unresolved interval every 50 milliseconds; after establishment, state queries back off exponentially to the existing 5-second systemctl bound. Each query reads both `LoadState` and `ActiveState`: loaded `inactive` or `failed`, or an established unit becoming `not-found`/`inactive` or otherwise collected away, proves the range empty. `active`, `activating`, `reloading`, and `deactivating` remain nonterminal. Unknown or malformed combinations and unreadable manager results reject `waitForExit()` instead of claiming quiescence. `terminate()` wakes a sleeping observer for an immediate recheck, and settlement cancels the losing backoff sleep. A strict sibling `startup-error.json` carries only request/bootstrap or target pre-exec failure, and the parent removes this spawn's private paths at observable lifecycle completion. + +The ordinary target result still comes from the same child process. The PTY path uses the same request and bootstrap without a resident runner, so the `node-pty` PID, process group, session leader, controlling terminal, foreground `inputWaiting`, `/dev/tty`, readiness, and direct terminal outcome retain their existing meanings while scope membership covers `setsid` and reparented descendants. + +### Windows runner and Job + +The Windows parent starts the provider runner from a bootstrap cwd and environment, gives it the original target argv after a private `--` delimiter, and waits for Node's runner `spawn` event before sending exactly one start request. A pre-spawn runner error preserves that direct launch failure while proving that no Job range existed, so the empty-range wait succeeds; post-spawn infrastructure failure remains uncertain and rejects range settlement. Node IPC otherwise carries idempotent terminate control and exactly one result. Runner fd 0 through fd 2 are isolated, fd 3 carries IPC, and fd 4 through fd 6 carry target stdin, stdout, and stderr. Fd 4 inherits the platform null-device descriptor when stdin is ignored and uses a pipe otherwise. The shared Win32 layer maps fds 4 through 6 to OS handles through Node's exported `uv_get_osfhandle()`, rejects null plus the unsigned `UV_INVALID_OS_FILE_HANDLE` and `UV_INVALID_FILE_DESCRIPTOR` sentinels exposed by Koffi, temporarily enables inheritance on valid handles, and passes them through `STARTF_USESTDHANDLES`. `spawnCurrentTokenJobProcess` requires a separately resolved `applicationName` and a complete target environment, which it sends as a sorted, double-NUL-terminated UTF-16LE block with `CREATE_UNICODE_ENVIRONMENT`, including `=X:` drive entries, without mutating the runner environment. After the suspended target enters the Job and resumes, the runner closes only fd 4 through fd 6; it never mutates or destroys Node's standard streams. The parent returns the pipe carriers as the ordinary handle's stdio, and user bytes never pass through IPC. + +The runner is the sole owner of the target process handle and unnamed Job handle. `spawnCurrentTokenJobProcess` creates the target suspended, assigns it to a kill-on-close Job that disallows active breakaway, and resumes it only after assignment. The runner polls the direct process for the target exit code and the Job for active-process count. It exits successfully only after the direct result has been delivered through the IPC send callback and the Job has reported zero active processes; the parent maps only that clean exit to successful `waitForExit()`. + +The parent permanently latches a validated numeric `target-exit` as soon as it arrives, before the existing stdout/stderr close or bounded-drain barrier settles. `.done` waits only for that stdio barrier and then returns the latched result. A later Job query, range-settlement failure, IPC loss, or abnormal runner exit rejects only `waitForExit()` and cannot replace the direct result. Infrastructure failure before a valid target result rejects `.done`, but that rejection does not reveal whether target execution began. On disconnect or result-send failure, the runner stops protocol work, terminates and closes its only Job handle, and exits nonzero. Closing the last Job handle kills remaining members but does not convert the disconnected path into a successful quiescence proof. + +### Private dispatch and protocol + +Source launches execute the package runner entry through the TypeScript source launcher, built launches resolve the `@deepseek-ai/dsh-subprocess-local/runner` export, and the Python SDK single-file executable enters through [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs). The Python runtime owns that bootstrap. It calls the public CLI export when the private selector is absent; otherwise it removes the selector and dispatches to the same subprocess runner core. The public `dsh` argument parser has no hidden runner mode, `apps/cli` builds only its public entry, and packaging ships no second Node executable. + +The selector is a per-spawn locator or sentinel, not a credential or persistent format. Linux uses one strict request plus one optional strict startup-error file. Windows uses one IPC channel with closed `start` and `terminate` requests and exactly two result branches: `target-exit` with a numeric `exitCode`, and `error` with required `name` and `message` plus only optional `code`, `syscall`, and `path`; the parent derives `signal: null`. Pre-commit cancellation uses the same ordinary `error` record. The cancellation reason never crosses the wire, so a parent cancellation latch restores its first local reason exactly, including `null` or `undefined`. Missing, extra, mistyped, or unknown fields fail closed. Target environments may contain the selector name, including Windows case variants, because the provider transmits target state separately and restores it only after private selection is consumed. + +### Fallback and cleanup + +Linux falls back before target execution when the exact bootstrap, modern readable user-systemd manager, or literal-argv scope is unavailable. Windows ordinary launch falls back when the runner entry, Win32 bindings, or current-token Job probe is unavailable. macOS ordinary launch, Windows ConPTY, and other unsupported hosts retain their existing PGID, `taskkill /T`, or identity-fenced PTY observation. The warning states that descendants escaping those observable relationships are not guaranteed to terminate or delay `waitForExit()`. + +Normal Cordis disposal starts direct-result and range observation independently, requests termination, and waits for every owned range. Consumer teardown does not inspect an ordinary PID; it retains the original operation or startup error while attempting terminate and final wait, and preserves cleanup failures in the consumer's existing error order. A confirmed empty range permanently disables later signalling against stale identities. + +During a JavaScript-observable host exit, `LocalSubprocessRuntime` synchronously force-terminates every still-live handle without promises or timers. Linux sends the existing direct fallback kill and the exact scope kill; Windows kills the runner so its only Job handle closes; PTY fallback scans remain best effort. Per-handle failures are contained and do not change the host's exit result. Termination modes in which JavaScript cannot run remain outside this listener's guarantee. + +## Existing decisions and supersession + +This note owns the current native-containment mechanism. It partially updates the provider and no-PID facts in the [subprocess seam](../../archived/architecture/2026-07-26-subprocess-seam.md), the Linux teardown facts in [persistent PTY sessions](../feature/2026-07-16-persistent-pty-sessions.md), the native targets used by [synchronous host-exit cleanup](../../archived/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md), the ordinary consumer of [shared Win32 process primitives](../../archived/architecture/2026-08-19-shared-win32-process-primitives.md), and the private entry selected by the [Python SDK profile runtime](../../archived/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md). Each note retains its other decision and remains active. + +## Verification + +- Provider and Linux protocol suites pin synchronous NUL rejection before launch side effects, strict request/error decoding, target cwd and complete environment restoration, private-variable collision, symlink-sensitive PATH traversal with preserved argv, close-on-exec removal for inherited stdio, pre-exec error ownership, failed-deep-probe retry plus successful-deep-probe caching with per-call manager checks, the three scope-establishment states including an exited launcher with an unconsumed request, `LoadState`/`ActiveState` parsing, `reloading`, terminate wake-up with losing-delay cancellation, bounded established-scope backoff, and exactly-once PTY managed-owner cleanup. +- Windows protocol and Win32 suites pin exactly two result branches, numeric-only target exits, ordinary-error start cancellation with raw parent-local reasons, the reduced `name`/`message`/`code`/`syscall`/`path` error record, the fixed `2`/`3`/`267` to `ENOENT`, `740` to `EACCES`, `5` to `EPERM`, `193` to `EFTYPE`, and remaining-code to `UNKNOWN` mapping, start delivery after runner spawn, empty-range settlement after pre-spawn failure, explicit ordinally sorted target environment blocks with `=C:` preservation and double-NUL termination, `uv_get_osfhandle()` carrier mapping and unsigned invalid-sentinel rejection, the null-device ignored-stdin carrier and piped non-ignored stdin, result-send and IPC-disconnect failures, direct-result latching before stdio settlement, active-process quiescence, and unique handle cleanup. +- Real Linux user-systemd tests run one ordinary and one `node-pty` `setsid`/reparent scenario through the production entry. They prove scope signalling and collection, bare executable lookup, escaped-descendant termination, range settlement, and unchanged PTY PID, session, controlling-terminal, foreground-input, `/dev/tty`, readiness, and startup-failure semantics. +- Native Windows tests prove suspended creation, Job assignment before resume, inherited stdio, default descendant inheritance, direct result, termination, active-process zero, abnormal/disconnected runner cleanup, kill-on-close, and synchronous host-exit termination. Source, built, and Python packaged smokes enter the same runner core. +- Public seam types, local and E2B providers, LSP and subagent consumers, shell fixtures, READMEs, the Cordis catalog, and the keyless subprocess API snapshot contain no ordinary PID; terminal PID remains. + +## Alternatives considered + +**Keep PID, make it optional, or add a public `started` promise.** Rejected because each representation exposes an asynchronous provider identity that does not name the managed range and invites consumers to infer startup or quiescence from the wrong fact. + +**Extend process-group, session, parent-tree, or PID scanning.** Rejected because a process can leave each observed relationship; broader SID signalling can also reach unrelated processes when a PTY helper shares a launcher session. Native OS membership is persistent and independently queryable. + +**Let the parent own or reopen the Windows Job.** Rejected because copied handles, named Jobs, `OpenJobObject`, process-handle handoff, and completion ports create multiple lifecycle owners without improving the direct-result contract. One runner can own target creation, Job membership, result production, and final handle closure. + +**Carry control or results through target stdio or files on Windows.** Rejected because user bytes and EOF must remain authoritative to existing Node streams, while result files or polling introduce a second result owner. One IPC channel separates control from target stdio. + +**Parse a hidden runner argument in the public CLI or ship another Node executable.** Rejected because either choice expands the public application grammar or distribution surface. A packaging-only bootstrap keeps one physical executable and two private logical entries. + +**Cache the complete Linux native decision without another reachability check.** Rejected because user-manager availability can change between spawns. The runtime caches only the first successful deep bootstrap/scope probe and lightly rechecks manager reachability for every later eligible call. + +**Recover a failed native launch by replaying the command.** Rejected because an ambiguous failure may occur after target execution and replay can therefore execute the command twice. + +## Consequences + +Supported Linux ordinary and PTY launches and Windows ordinary launches retain descendants through process-group escape and direct-parent exit, while direct target results remain independent from range quiescence. The cost is a per-spawn Linux manager check and scope/request or Windows runner/IPC/Job lifecycle, plus explicit failure when the selected owner cannot prove settlement. + +Fallback hosts continue to run commands but carry a visible weaker guarantee. Windows ConPTY, macOS native containment, active breakaway descendants, old or absent user-systemd environments, target replay, persistent runner recovery, and termination paths where JavaScript cannot execute remain outside this decision. diff --git a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md new file mode 100644 index 0000000000..b7850e1c4f --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.zh.md @@ -0,0 +1,83 @@ +# Agent Note: 原生 owner 收容逃逸的 subprocess 后代 + +Status: implemented + +[English](2026-08-28-subprocess-native-containment.md) | 中文 + +## Problem + +detached POSIX 进程组、Windows direct-parent 遍历与 PTY 后代扫描只能描述仍可通过某种进程关系观察到的成员。子进程可以调用 `setsid`、发生 reparent，或比 direct parent 存活更久并离开这些 range，因此终止表面进程树后，工作、端口或文件仍可能保持活跃。direct target result 也不能证明全部后代已经停止。 + +普通 subprocess 句柄无法通过发布 PID 解决这个缺口。Linux scope setup 与 Windows Job runner 会异步建立 target identity，PID 不表示完整 managed range，消费方也会被迫推断 startup 是否已经提交。因此，公共结果、range ownership、私有启动协议与打包入口需要各自明确的 owner。 + +## Decision + +`LocalSubprocessRuntime` 会在 target 执行前选择一个 provider 私有的 managed-range owner。符合条件的 Linux 普通命令与 PTY 进入临时 user-systemd scope；符合条件的 Windows 普通命令进入由私有 runner 拥有的 unnamed kill-on-close Job。不支持的宿主使用既有较弱 fallback，并在 provider 生命周期内只警告一次。选定的 native 路径一旦可能已经执行 target，provider 绝不重放 target。 + +普通 `SubprocessHandle` 没有 PID 或公共 startup 状态。`.done` 报告 direct target result 或 startup／provider failure，`terminate()` 向所选 range 发送信号，`waitForExit()` 只有在同一 range 被证明为空后才成功。`SubprocessTerminalHandle.pid` 继续属于终端约定，因为 PTY identity 与前台检查需要它。 + +### Linux scope 与 one-shot bootstrap + +同一 runtime 第一次符合条件的 Linux 普通或 PTY 调用会深入检查准确 runner 入口、libc `execve` 与 `fcntl` bindings、可读的 user manager 与保留 literal argv 的 transient-scope 支持。失败的深度 probe 会重试，第一次成功则会缓存。之后每次符合条件的调用仍会在 target 执行前轻量检查 user manager 是否可达。native 路径一旦选定，scope、协议、状态查询或 pre-exec failure 都由本次启动报告，绝不切换到 fallback。 + +parent 创建一个 0700 目录，其中的完整 0600 `launch-request.json` 保存最终 target cwd 与环境。私有 `DSH_SUBPROCESS_RUNNER` 值负责定位该 request，runner 则从 provider cwd 与 bootstrap-safe 环境启动。`systemd-run --user --scope --quiet --collect --expand-environment=no` 先把自身进程注册到 scope，再由 one-shot bootstrap 删除并校验 request、切换到 target cwd、恢复完整 target 环境、按 target PATH 规则解析裸可执行文件、清除 fd 0 至 fd 2 的 `FD_CLOEXEC`，并使用原始 argv 调用 libc `execve()`。bootstrap 会原地成为 target 并保留继承的 stdio，不作为常驻 supervisor。 + +request 被消费或 manager 已观察到 loaded unit 都能建立 scope ownership。在这两项事实出现前，只要 direct launcher 仍在运行，unit absence 就保持未决。如果 launcher 退出时 request 仍未消费，direct result 会以 startup failure reject，而 range observation 会记录 scope 从未存在，并成功结算 empty-range wait。parent 每 50 毫秒检查一次这段未决区间；建立后，状态查询按指数增长间隔退避，最多达到既有的 5 秒 systemctl 上限。每次查询同时读取 `LoadState` 与 `ActiveState`：loaded `inactive` 或 `failed`，以及已经建立的 unit 变为 `not-found`/`inactive` 或被 collect 卸载，都能证明 range 为空。`active`、`activating`、`reloading` 与 `deactivating` 仍是非终态。未知或 malformed 组合以及不可读的 manager 结果会使 `waitForExit()` reject，而不是宣称完全停稳。`terminate()` 会唤醒正在休眠的 observer 立即复查，结算时会取消未胜出的退避 sleep。严格的同目录 `startup-error.json` 只承载 request／bootstrap 或 target pre-exec failure，parent 会在可观察生命周期完成时移除本次 spawn 的私有路径。 + +普通 target result 仍来自同一个 child process。PTY 路径复用同一 request 与 bootstrap，但不增加常驻 runner，因此 `node-pty` PID、进程组、session leader、控制终端、前台 `inputWaiting`、`/dev/tty`、readiness 与 direct terminal outcome 保留既有含义，同时 scope membership 覆盖 `setsid` 与 reparent 后代。 + +### Windows runner 与 Job + +Windows parent 从 bootstrap cwd 与环境启动 provider runner，把原始 target argv 放在私有 `--` 分隔符之后，并等待 Node 的 runner `spawn` 事件后才发送恰好一条 start request。runner 在 spawn 前报错时，direct launch failure 会原样保留，同时证明 Job range 从未存在，因此 empty-range wait 成功；spawn 后的 infrastructure failure 仍是不确定状态，会使 range settlement reject。除此之外，Node IPC 还承载幂等 terminate control 与恰好一个 result。runner 的 fd 0 至 fd 2 相互隔离，fd 3 承载 IPC，fd 4 至 fd 6 承载 target stdin、stdout 与 stderr。忽略 stdin 时，fd 4 继承平台 null-device descriptor；其他模式使用 pipe。共享 Win32 层通过 Node 导出的 `uv_get_osfhandle()` 把 fd 4 至 fd 6 映射为 OS handle，拒绝 null 以及 Koffi 暴露的 unsigned `UV_INVALID_OS_FILE_HANDLE` 与 `UV_INVALID_FILE_DESCRIPTOR` sentinel，临时启用有效 handle 的继承，并通过 `STARTF_USESTDHANDLES` 传入。`spawnCurrentTokenJobProcess` 要求单独解析的 `applicationName` 与完整 target 环境，并使用 `CREATE_UNICODE_ENVIRONMENT` 传入排序、双 NUL 结尾的 UTF-16LE 块，其中包括 `=X:` 驱动器条目，而不修改 runner 环境。suspended target 进入 Job 并恢复后，runner 只关闭 fd 4 至 fd 6；它绝不改写或销毁 Node 标准流。parent 把 pipe carrier stream 作为普通句柄的 stdio 返回，用户字节绝不经过 IPC。 + +runner 是 target process handle 与 unnamed Job handle 的唯一 owner。`spawnCurrentTokenJobProcess` 以 suspended 状态创建 target，把它分配给不允许 active breakaway 的 kill-on-close Job，并只在分配后恢复。runner 轮询 direct process 获取 target exit code，并轮询 Job 获取 active-process count。只有 direct result 已通过 IPC send callback 交付且 Job 已报告零 active process 后，runner 才成功退出；parent 只把这次 clean exit 映射成成功的 `waitForExit()`。 + +parent 会在收到经过校验、只含数字的 `target-exit` 时立即永久锁存它，此时既有 stdout／stderr close 或有界 drain barrier 可能尚未完成。`.done` 只继续等待该 stdio barrier，随后返回已锁存的结果。后续 Job query、range settlement failure、IPC loss 或 runner 异常退出只会使 `waitForExit()` reject，不能替换 direct result。在有效 target result 到达前发生 infrastructure failure 才会使 `.done` reject，但该 rejection 不会说明 target 是否已经开始执行。disconnect 或 result-send failure 会让 runner 停止协议工作、终止并关闭自己唯一的 Job handle，然后以非零状态退出。最后一个 Job handle 关闭会终止剩余成员，但不会把 disconnected 路径改写成成功的完全停稳证明。 + +### 私有分派与协议 + +source 启动通过 TypeScript source launcher 执行包内 runner 入口，built 启动解析 `@deepseek-ai/dsh-subprocess-local/runner` export，Python SDK 单文件可执行程序则从 [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) 进入。该 bootstrap 由 Python runtime 拥有；私有 selector 不存在时，它调用公共 CLI export；否则会删除 selector，并分派到同一 subprocess runner core。公共 `dsh` 参数解析器没有隐藏 runner mode，`apps/cli` 只构建公共入口，打包也不提供第二个 Node 可执行程序。 + +selector 是 per-spawn locator 或 sentinel，不是凭据或持久格式。Linux 使用一个严格 request 与一个可选严格 startup-error 文件。Windows 使用一条 IPC channel，承载闭集的 `start` 与 `terminate` request，以及恰好两个 result 分支：只含数字 `exitCode` 的 `target-exit`，以及必含 `name`、`message` 且只允许可选 `code`、`syscall`、`path` 的 `error`；parent 会派生 `signal: null`。提交前取消使用同一种普通 `error` record。取消 reason 不跨 wire 传递，因此 parent cancellation latch 会原样恢复第一个本地 reason，包括 `null` 或 `undefined`。缺失、额外、类型错误或未知字段都会 fail closed。target 环境可以包含 selector 名称及其 Windows 大小写变体，因为 provider 会单独传递 target 状态，并且只在私有选择值消费后才恢复该状态。 + +### Fallback 与 cleanup + +准确 bootstrap、现代且可读的 user-systemd manager，或保留 literal argv 的 scope 不可用时，Linux 会在 target 执行前进入 fallback。runner 入口、Win32 bindings 或 current-token Job probe 不可用时，Windows 普通启动会进入 fallback。macOS 普通启动、Windows ConPTY 与其他不受支持的宿主保留既有 PGID、`taskkill /T` 或带身份围栏的 PTY 观察机制。warning 会明确说明：逃离这些可观察关系的后代不保证被终止，也不保证延迟 `waitForExit()`。 + +正常 Cordis dispose 会独立启动 direct-result 与 range observation、请求终止，并等待每个自有 range。消费方 teardown 不检查普通 PID；它会保留原始 operation 或 startup error，同时尝试 terminate 与 final wait，并按消费方既有错误顺序保留 cleanup failure。range 一旦被确认为空，就会永久禁止后续向陈旧 identity 发送信号。 + +在 JavaScript 可观察的 host exit 期间，`LocalSubprocessRuntime` 会同步强制终止每个仍存活的句柄，不使用 Promise 或 timer。Linux 会发送既有 direct fallback kill 与准确 scope kill；Windows 会终止 runner，使其唯一 Job handle 关闭；PTY fallback 扫描仍是 best effort。每个句柄的失败相互隔离，也不改变宿主退出结果。JavaScript 无法运行的终止形态不属于该 listener 的保证。 + +## Existing decisions and supersession + +本 Note 拥有当前 native containment 机制。它局部更新了[subprocess seam](../../archived/architecture/2026-07-26-subprocess-seam.md)中的 provider 与 no-PID 事实、[持久化 PTY 会话](../feature/2026-07-16-persistent-pty-sessions.zh.md)中的 Linux teardown 事实、[宿主退出同步清理](../../archived/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md)使用的 native target、[共享 Win32 process primitives](../../archived/architecture/2026-08-19-shared-win32-process-primitives.md)的 ordinary 消费方，以及[Python SDK profile 运行时](../../archived/architecture/2026-08-23-python-sdk-dsh-profile-runtime.md)选择的私有入口。每份 Note 都保留其余决策并继续处于 active 状态。 + +## Verification + +- provider 与 Linux 协议测试套件固定同步 NUL 拒绝发生在启动副作用之前、严格 request／error 解码、target cwd 与完整环境恢复、私有变量碰撞、保留 argv 且对 symlink 敏感的 PATH 遍历、为继承 stdio 清除 close-on-exec、pre-exec error ownership、失败深度 probe 重试与成功深度 probe 缓存及逐调用 manager 检查、三种 scope 建立状态（包括 launcher 退出且 request 未消费）、`LoadState`／`ActiveState` 解析、`reloading`、带未胜出 delay 取消的 terminate wake-up、建立后有上限的退避，以及 PTY managed-owner 恰好一次 cleanup。 +- Windows 协议与 Win32 测试套件固定恰好两个 result 分支、只含数字的 target exit、使用普通 error 的 start cancellation 与 parent 原样保留的本地 reason、缩减到 `name`／`message`／`code`／`syscall`／`path` 的 error record、固定的 `2`／`3`／`267` 到 `ENOENT`、`740` 到 `EACCES`、`5` 到 `EPERM`、`193` 到 `EFTYPE` 及其余 code 到 `UNKNOWN` 的映射、runner spawn 后才发送 start、spawn 前 failure 的 empty-range settlement、按序数显式排序的 target 环境块及 `=C:` 保留和双 NUL 结尾、`uv_get_osfhandle()` carrier 映射与 unsigned invalid sentinel 拒绝、null-device ignored-stdin carrier 与非 ignore stdin pipe、result-send 与 IPC-disconnect failure、stdio settlement 前的 direct-result 锁存、active-process 完全停稳，以及唯一 handle cleanup。 +- 真实 Linux user-systemd 测试会分别通过生产入口运行一条普通命令与一条 `node-pty` `setsid`／reparent 场景。它们证明 scope signalling 与 collection、裸可执行文件查找、逃逸后代终止、range settlement，以及不变的 PTY PID、session、控制终端、前台输入、`/dev/tty`、readiness 与 startup-failure 语义。 +- native Windows 测试证明 suspended creation、resume 前 Job assignment、继承 stdio、默认后代继承、direct result、termination、active-process zero、异常／disconnected runner cleanup、kill-on-close 与同步 host-exit termination。source、built 与 Python packaged 冒烟测试进入同一 runner core。 +- 公共 seam 类型、local 与 E2B provider、LSP 与 subagent 消费方、shell fixture、README、Cordis catalog 与 keyless subprocess API snapshot 都不包含普通 PID；terminal PID 保留。 + +## Alternatives considered + +**保留 PID、把它改成可选值，或增加公共 `started` Promise。**不予采用，因为这些表示都会暴露不表示 managed range 的异步 provider identity，并诱导消费方从错误事实推断 startup 或完全停稳。 + +**扩展进程组、session、parent tree 或 PID 扫描。**不予采用，因为进程可以离开每一种观察关系；当 PTY helper 与 launcher 共用 session 时，更宽的 SID signalling 还可能命中无关进程。native OS membership 会持续存在，并且可以独立查询。 + +**让 parent 拥有或重新打开 Windows Job。**不予采用，因为复制 handle、named Job、`OpenJobObject`、process-handle handoff 与 completion port 会制造多个 lifecycle owner，却不能改善 direct-result 约定。一个 runner 可以统一拥有 target creation、Job membership、result production 与最终 handle closure。 + +**在 Windows 上通过 target stdio 或文件传递 control／result。**不予采用，因为用户字节与 EOF 必须继续以既有 Node stream 为权威，而 result file 或 polling 会制造第二个 result owner。一条 IPC channel 可以把 control 与 target stdio 分开。 + +**在公共 CLI 中解析隐藏 runner 参数，或发布另一个 Node 可执行程序。**不予采用，因为前者扩张公共应用语法，后者扩张分发面。packaging-only bootstrap 保留一个物理可执行程序与两个私有逻辑入口。 + +**缓存完整的 Linux native 选择结果且不再检查可达性。**不予采用，因为 user-manager availability 可以在两次 spawn 之间变化。runtime 只缓存第一次成功的 bootstrap／scope 深度 probe，并在之后每次符合条件的调用中轻量复查 manager reachability。 + +**在 native launch 失败后重放命令。**不予采用，因为含糊 failure 可能发生在 target 已经执行之后，重放因此可能把命令执行两次。 + +## Consequences + +受支持的 Linux 普通与 PTY 启动、Windows 普通启动会在后代逃离进程组或 direct parent 退出后继续拥有它们，同时 direct target result 与 range 完全停稳保持独立。代价是每次 spawn 都需要一次 Linux manager 检查与 scope／request，或一套 Windows runner／IPC／Job 生命周期，而且所选 owner 无法证明 settlement 时会显式失败。 + +fallback 宿主继续运行命令，但携带可见的较弱保证。Windows ConPTY、macOS native containment、active breakaway 后代、旧版或缺失的 user-systemd 环境、target replay、持久 runner recovery，以及 JavaScript 无法执行的终止路径均不属于本决策。 diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml index 081433eb42..5db7ce1ba0 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md -2026-07-06-sandbox.md: ceffb260163bc21e2ed13275dde38ea0843aac7d -2026-07-06-sandbox.zh.md: 2b6753585b2778bc0dc898661d9f21779dc37f18 +2026-07-06-sandbox.md: a6e5639e21ca7140cb0314c9918319e99b1495f6 +2026-07-06-sandbox.zh.md: 5144b3fa719465707d7fb2870d45094b8c07661a diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md index ceffb26016..a6e5639e21 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md @@ -38,7 +38,7 @@ Four `cordis.yml` entries turn an unconfined coding agent into the sandboxed pro The swap is invisible to every consumer of `ctx.shell`: the bash tools, hook commands, and background jobs run exactly as before by directly spawning the wrapped argv the provider returns. Deleting the `sandbox` and `permission` entries and replacing `bash` with `@deepseek-ai/dsh-bash-local` is the opt-out — execution is unconfined again and the escalation fields vanish from the tool schema, because they are capability-gated on the mounted executor, not on configuration. Omitting only `approval` keeps confinement but fails every escalation closed with its own error text; `permission` also requires the approval seam and a confining executor, so a partially composed preset layer fails loud at load. -Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. If the selected runner rejects with attributable `ENOENT` or `EACCES`, the consumer reports the same infrastructure error from the spawn channel before any command starts; other spawn errors retain local command-start semantics while still running nothing. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner hook for keyless tests. +Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. An attributable `ENOENT` or `EACCES` that names the selected runner proves that executable did not start, so the consumer reports the same infrastructure error; other synchronous creation errors propagate unchanged. An asynchronous subprocess-provider rejection exposes no public target stage and retains stage-neutral local semantics. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner hook for keyless tests. Denied file effects return a `[sandbox: file access denied under mode]` marker and instructions not to work around the denial. A confining executor adds paired `sandbox_permissions` and `justification` fields for one approved retry that must be strictly wider than the session's effective mode. A grant widens only that retry; rejection executes nothing, returns `the user rejected escalating this command to ""`, and permits no re-ask. The owner-derived pending policy context states the current file policy without replacing those enforcement boundaries. When `dsh-permission-presets` is composed with a UI adapter, one preset selects both knob values; unmatched values fold to `custom`. The [ACP application bundle](../../../../packages/bundle/acp-app/README.md) does not mount that UI service and selects its deployment mode explicitly. @@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La #### The bash consumer -`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection counts as a runner failure only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn '`; a present path also requires `syscall: 'spawn'` or the exact `spawn `. Other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner failures to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessRuntime` that synchronously throws the same runner-identifying shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code check and a remaining fatal line after informational exclusions. A match takes priority over denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `ShellProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `job_output`. +`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. An asynchronous rejection counts as a runner failure only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn '`; a present path also requires `syscall: 'spawn'` or the exact `spawn `. Other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain stage-neutral provider-failure semantics. Foreground execution converts attributable runner failures to `SANDBOX_UNAVAILABLE` with the original detail; an attributable asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessRuntime` that synchronously throws the same runner-identifying shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a direct outcome exists, foreground and background use one runner-failure classifier that requires the rule's exit-code check and a remaining fatal line after informational exclusions. A match takes priority over denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `ShellProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `job_output`. The model sees the current effective file policy in the owner-derived `sandbox:policy` context, while the static tool description explains the denial marker (`[sandbox: file access denied under mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](../../archived/feature/2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries. @@ -184,7 +184,7 @@ Costs and accepted limits: ## FAQ - **A command came back with `[sandbox: file access denied under read-only mode]` — did it fail?** It RAN, and the kernel refused a file effect: the denial is a result fact orthogonal to exit code. The teaching forbids retrying around it; the one sanctioned move is the same command retried once with an escalation request. -- **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background job stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessRuntime` that synchronously throws the same `ENOENT`/`EACCES` shape with the runner path makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result. +- **How is a BROKEN sandbox told apart from a failing command?** An asynchronous subprocess-provider rejection exposes no public execution stage. It identifies a broken confinement runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]; a bare `syscall: 'spawn'` without an exact error path and all other rejections remain stage-neutral provider failures. After a direct outcome exists, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground runner failures throw structured `SANDBOX_UNAVAILABLE` with executable or matched-line detail; an attributable asynchronous background rejection or a matched settled failure stamps `sandbox.runnerFailed`, while every asynchronous rejection renders the local executor's provider-failure note. A `SubprocessRuntime` that synchronously throws the same `ENOENT`/`EACCES` shape with the runner path makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result. - **What happens on a platform with no backend?** `confine()` throws the fail-closed `SANDBOX_UNAVAILABLE`, and the command never spawns. - **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the packaged Landlock launcher, and the verdict is cached for the provider's lifetime. - **Does the sandbox restrict network or process visibility?** `SandboxMode` claims FILE effects only, and no backend claims network. Process visibility is backend-specific: bwrap unshares PID and mounts matching procfs because host `/proc/` magic links otherwise bypass file confinement, while Landlock and Seatbelt leave process visibility unchanged ([decision](../bug-fix/2026-08-06-bwrap-private-pid-namespace.md)). Whether network restriction becomes its own knob is left open in § The seam. diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md index 2b6753585b..5144b3fa71 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md @@ -38,7 +38,7 @@ harness 是一个 SDK，因此约束必须是开发者可组合的能力：是 这一替换对 `ctx.shell` 的所有消费方透明：bash 工具、钩子命令和后台任务照常运行，直接使用提供方返回的已包装 argv 启动。删除 `sandbox` 和 `permission` 条目、将 `bash` 替换为 `@deepseek-ai/dsh-bash-local` 即为退出——执行恢复为无约束，升级字段从工具 schema 中消失，因为它们是基于已挂载执行器的能力门控，而非基于配置。仅省略 `approval` 则保留约束但以自身错误文本关闭每次升级；`permission` 还要求 approval seam 和约束执行器同时存在，因此组合不完整的 preset 层会在加载时明确报错。 -配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。如果所选 runner 以可归因的 `ENOENT` 或 `EACCES` 拒绝，消费方会在任何命令开始前通过 spawn 通道报告同一基础设施错误；其他 spawn 错误仍保留本地命令启动语义，同时也不会运行任何内容。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner 钩子。 +配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。若可归因的 `ENOENT` 或 `EACCES` 指明所选 runner，就能证明该 executable 未启动，因此消费方会报告同一基础设施错误；其他同步创建错误原样传播。异步 subprocess-provider rejection 不公开 target 阶段，保留本地不声明阶段的语义。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner 钩子。 被拒绝的文件操作返回 `[sandbox: file access denied under mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to ""`，且不允许再次请求。由归属方派生的待处理策略上下文会说明当前文件策略，但不会取代这些强制执行边界。当 `dsh-permission-presets` 与某个 UI 适配器一起组合时，一个 preset 同时选定两个旋钮值；不匹配的组合折叠为 `custom`。[ACP（Agent Client Protocol）应用组合包](../../../../packages/bundle/acp-app/README.zh.md)不挂载该 UI 服务，而是显式选定其部署模式。 @@ -70,7 +70,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness #### bash 消费方 -`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，Node 报告 `ENOENT` 或 `EACCES`，并且错误符合以下一种形态时，才判定为 runner 失败：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn '`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn '`。其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将 runner 失败转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessRuntime` 同步抛出同样能指明 runner 的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码检查与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `ShellProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `job_output` 渲染它。 +`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。异步 rejection 只有在调用方拥有的 workdir 经独立验证可用，Node 报告 `ENOENT` 或 `EACCES`，并且错误符合以下一种形态时，才判定为 runner 失败：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn '`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn '`。其他错误码、无效 workdir、资源失败、无关 syscall 与无结构 rejection 保留不声明阶段的 provider-failure 语义。前台执行会将可归因的 runner failure 转为 `SANDBOX_UNAVAILABLE` 并附上原始详情；可归因的异步后台 rejection 则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessRuntime` 同步抛出同样能指明 runner 的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。direct outcome 已存在后，前台与后台共用一个 runner failure 分类器：先排除信息性行，再要求规则的退出码检查与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详情；结算后的 `ShellProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `job_output` 渲染它。 模型会在归属方派生的 `sandbox:policy` 上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](../../archived/feature/2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。 @@ -184,7 +184,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自能力边 ## FAQ - **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？** 它运行了，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。相关指令禁止通过绕过限制来重试；唯一被认可的动作是以升级请求重试同一命令一次。 -- **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessRuntime` 同步抛出同样带有 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。 +- **如何区分损坏的沙箱与失败的命令？** 异步 subprocess-provider rejection 不公开执行阶段。只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 confinement runner 损坏；没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有 rejection 都保持不声明阶段的 provider failure。direct outcome 已存在后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台 runner failure 会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 executable 或匹配行详情；可归因的异步后台 rejection 或匹配到的已结算失败会盖章 `sandbox.runnerFailed`，而所有异步 rejection 都会渲染本地执行器的 provider-failure 提示。如果 `SubprocessRuntime` 同步抛出同样带有 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。 - **在没有后端的平台上会发生什么？** `confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn。 - **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？** 链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到已打包的 Landlock launcher，结论在提供方生命周期内缓存。 - **沙箱限制网络或进程可见性吗？** `SandboxMode` 仅声称文件操作，没有后端声称网络。进程可见性取决于后端：bwrap 会 unshare PID 并挂载匹配的 procfs，因为宿主 `/proc/` 魔法链接会绕过文件约束；Landlock 与 Seatbelt 则保持进程可见性不变（[决策](../bug-fix/2026-08-06-bwrap-private-pid-namespace.zh.md)）。网络限制是否成为自己的旋钮留在 § seam 中开放。 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml index 17bec079b4..b1b7365597 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md -2026-07-16-persistent-pty-sessions.md: d0bbb230bdb1cf7ab723a3451f0524cc86996209 -2026-07-16-persistent-pty-sessions.zh.md: 359d8e2b6c7f0ea857d0e73349421fc673d5cc3b +2026-07-16-persistent-pty-sessions.md: d62587ced78be75de121fe907ca258d07a2830a1 +2026-07-16-persistent-pty-sessions.zh.md: a26c3ed852b3a18842585e19ecb2a6994f8d9117 diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md index d0bbb230bd..d62587ced7 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md @@ -45,7 +45,7 @@ A registered `shell` backend constrains how a terminal starts; it does not const Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary. -The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors below that primitive derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split. +The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. On supported Linux hosts the [native-containment owner](../architecture/2026-08-28-subprocess-native-containment.md) starts that same PTY command inside a user-systemd scope without changing its PID, session, controlling terminal, foreground-group, or readiness semantics. Platform process inspectors below the primitive still derive foreground process groups and fallback parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split. ### Six model-facing tools @@ -92,7 +92,9 @@ Background sends use the existing task completion notice and `job_output` result ### Process-tree teardown -The subprocess terminal handle owns the top-level terminal process and its session. On close it snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation. +On supported Linux hosts, the subprocess terminal handle binds the top-level PTY process to its transient user-systemd scope. Before establishment, close sends `SIGTERM` through the direct PTY fallback so the bootstrap cannot continue; after establishment, it signals the scope alone and uses the direct fallback only if scope signalling fails. It waits for the manager to prove that range empty and escalates to `SIGKILL` after the configured grace. Scope membership continues to include descendants that call `setsid` or reparent, while the PTY's direct exit notification remains the terminal outcome. + +Fallback hosts retain observational process-session cleanup. The handle snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation. Teardown reports top-level exit and survivor cleanup independently. The PTY session does not claim success merely because the shell exited: it calls `SubprocessTerminalHandle.terminate()` and awaits whole-session quiescence, propagating a cleanup failure that names survivors. A failed close is not cached forever: the registry and local session clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails. @@ -158,7 +160,7 @@ The package ships concise tool guidance explaining persistent state, owner isola - Per-file coverage pins owner fencing, concurrent reservations, cancellation during pre-write inspection, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits and delayed earlier prompts, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents. - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, thread-local fd tables, the `/dev/tty` alias, supported kernel ABIs under user-mode emulation, rejection of fd 0 backed by a pipe, zombie quiescence, unreadable process state, unsupported architectures, and other false-positive rejection; macOS inspector logic is injected into the same unit suite. -- Real `node-pty` and PTY-consumer tests jointly exercise shell state, controlling-terminal input through `/dev/tty`, the exact attribution when process syscalls are readable, its bounded idle fallback when host policy denies them, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts. +- Real `node-pty` and PTY-consumer tests jointly exercise shell state, controlling-terminal input through `/dev/tty`, the exact attribution when process syscalls are readable, its bounded idle fallback when host policy denies them, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence. The Linux native smoke keeps the PTY PID, session leader, controlling terminal, foreground `inputWaiting`, and readiness while a reparented `setsid` descendant remains owned by the scope; fallback suites retain identity-fenced observational cleanup coverage. - A Loader-driven `cordis.yml` test mounts the real three-package composition and verifies that delayed pipeline output returns with the completed command instead of being classified as terminal-input readiness. The SDK minimal snapshot pins that output through the persistent Bash tool; ACP and headless snapshots pin the six terminal schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation. - Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface. @@ -172,7 +174,7 @@ The package ships concise tool guidance explaining persistent state, owner isola **Persistent state can drift from the model's belief.** The model may forget its cwd or active REPL. Session summaries and retained output help recovery, but no prompt can make state persistence deterministic. -**A daemonized descendant can leave the local provider's captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The local terminal primitive accepts that cleanup gap instead of risking SID-wide signals to unrelated processes. +**Native Linux ownership closes the process-tree observation gap; fallback ownership does not.** A supported user-systemd scope retains a daemonized or reparented descendant as a member until the scope becomes empty. On macOS, Windows ConPTY, and Linux hosts that cannot establish the scope, a process that escapes before observational teardown can still evade the captured tree; the fallback accepts that gap instead of risking SID-wide signals to unrelated processes. **A shell can cause external side effects.** Session sandboxing and environment scrubbing reduce local exposure but do not undo pushes, API calls, or messages. Deployments that cannot tolerate those effects must omit PTY or add network policy. diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md index 359d8e2b6c..a26c3ed852 100644 --- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md +++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md @@ -45,7 +45,7 @@ agent scope dispose（资源释放）时先撤销注册，再等待全部所属 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。 -本地子进程终端原语只使用 `node-pty` 的公开能力：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。该原语下的平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.zh.md)负责定义这种进程／消费方拆分。 +本地子进程终端原语只使用 `node-pty` 的公开能力：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。在受支持的 Linux 宿主上，[原生收容 owner](../architecture/2026-08-28-subprocess-native-containment.zh.md)会在 user-systemd scope 内启动同一条 PTY 命令，同时保持 PID、session、控制终端、前台进程组与就绪语义。该原语下的平台进程检查器仍在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和 fallback 父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.zh.md)负责定义这种进程／消费方拆分。 ### 6 个面向模型的工具 @@ -92,7 +92,9 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 ### 进程树 teardown -子进程终端句柄拥有顶层终端进程及其会话。关闭时，它按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。 +在受支持的 Linux 宿主上，subprocess 终端句柄会把顶层 PTY 进程绑定到临时 user-systemd scope。建立前，close 通过 direct PTY fallback 发送 `SIGTERM`，阻止 bootstrap 继续；建立后只向 scope 发送信号，并且仅在 scope signalling 失败时使用 direct fallback。随后它等待 manager 证明该 range 为空，并在配置的宽限期后升级到 `SIGKILL`。调用 `setsid` 或发生 reparent 的后代仍属于 scope，而 PTY 的 direct exit 通知继续作为终端结果。 + +fallback 宿主保留观察式进程 session 清理。句柄会按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。 teardown 独立报告顶层进程退出与存活进程清理。PTY 会话不会只因 shell 退出就声称成功：它会调用 `SubprocessTerminalHandle.terminate()` 并等待整个会话完全停稳，若清理失败则向外传播并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。 @@ -158,7 +160,7 @@ plugins: - 逐文件覆盖测试锁定了 owner 隔离、并发预留、写入前检查期间的取消、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待与延迟到达的先前 prompt 的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。 - 子进程 fixture（测试前置数据）覆盖非 leader 与非主线程的 stdin 等待、线程本地 fd 表、`/dev/tty` 别名、用户态模拟下受支持的内核 ABI、拒绝把指向管道的 fd 0 当作终端输入、僵尸进程完全停稳、不可读进程状态、不支持的架构和其他误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。 -- 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、通过 `/dev/tty` 读取控制终端输入、进程 syscall 可读时的精确归因、宿主策略拒绝读取时的有界 idle fallback、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。 +- 真实 `node-pty` 与 PTY 消费方测试共同覆盖 shell 状态、通过 `/dev/tty` 读取控制终端输入、进程 syscall 可读时的精确归因、宿主策略拒绝读取时的有界 idle fallback、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。Linux native 冒烟测试会在一个 reparent 的 `setsid` 后代仍由 scope 拥有时，保持 PTY PID、session leader、控制终端、前台 `inputWaiting` 与 readiness；fallback 测试套件继续覆盖带身份围栏的观察式清理。 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合，并验证延迟到达的流水线输出随已完成命令返回，而不会被归类为终端输入就绪。SDK minimal 快照通过持久 Bash 工具固定该输出；ACP 与 headless 快照通过 opt-in overlay 固定 6 个终端 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。 - 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。 @@ -172,7 +174,7 @@ plugins: **持久状态可能偏离模型认知。**模型可能忘记 cwd 或活跃 REPL。会话摘要和保留输出有助恢复，但任何提示词都无法让状态持久化变成确定行为。 -**daemonized 后代进程可能离开本地提供方捕获的进程树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。本地终端原语接受这个清理缺口，不冒险按 SID 向无关进程发送信号。 +**Linux native ownership 消除了进程树观察缺口，fallback ownership 没有。**受支持的 user-systemd scope 会持续保有 daemonized 或 reparent 后代，直到 scope 为空。在 macOS、Windows ConPTY，以及无法建立 scope 的 Linux 宿主上，观察式 teardown 开始前已经逃逸的进程仍可能避开捕获树；fallback 接受这个缺口，不冒险按 SID 向无关进程发送信号。 **Shell 可以造成外部副作用。**会话沙箱和环境清洗降低本地暴露，但无法撤销 push、API 调用或消息发送。无法容忍这些副作用的部署必须省略 PTY 或增加网络策略。 diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts index 321849f2d9..20038abb5b 100644 --- a/apps/cli/src/bin.ts +++ b/apps/cli/src/bin.ts @@ -21,30 +21,40 @@ function readVersion(): string { return typeof manifest.version === 'string' ? manifest.version : '0.0.0' } -const invocation = parseDshArgs(process.argv.slice(2), readVersion()) +/** + * Run the public dsh command-line interface. + * @returns a promise that settles when the selected command mode finishes. + */ +export async function runCli(): Promise { + const invocation = parseDshArgs(process.argv.slice(2), readVersion()) -switch (invocation.mode) { - case 'profile': { - const { runProfile } = await import('./profile-boot.ts') - await runProfile({ - environment: loadLayeredEnv('dsh'), - profile: invocation.profile, - patchFiles: invocation.patches, - args: invocation.args, - }) - break + switch (invocation.mode) { + case 'profile': { + const { runProfile } = await import('./profile-boot.ts') + await runProfile({ + environment: loadLayeredEnv('dsh'), + profile: invocation.profile, + patchFiles: invocation.patches, + args: invocation.args, + }) + break + } + case 'plugin': { + const { runPlugin } = await import('./plugin.ts') + process.exit(runPlugin(invocation.profile, invocation.args)) + break + } + case 'dump-config': { + const { runDumpConfig } = await import('./dump-config.ts') + runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches) + break + } + default: + invocation satisfies never + throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`) } - case 'plugin': { - const { runPlugin } = await import('./plugin.ts') - process.exit(runPlugin(invocation.profile, invocation.args)) - break - } - case 'dump-config': { - const { runDumpConfig } = await import('./dump-config.ts') - runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches) - break - } - default: - invocation satisfies never - throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`) +} + +if (import.meta.main) { + await runCli() } diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts index 98fd96fddf..178ddadd92 100644 --- a/apps/cli/tests/built-bin.e2e.ts +++ b/apps/cli/tests/built-bin.e2e.ts @@ -1,4 +1,4 @@ -import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' import { createInterface } from 'node:readline' @@ -617,6 +617,25 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', } }) + it.skipIf(process.platform === 'win32')('runs through an installed-style symlink', async () => { + const installation = mkdtempSync(join(tmpdir(), 'dsh-bin-link-')) + const installedBin = join(installation, 'dsh') + symlinkSync(dshBin, installedBin) + try { + const result = await execa(process.execPath, [installedBin, '--version'], { + input: '', + timeout: SPAWN_TIMEOUT_MS, + killSignal: 'SIGKILL', + reject: false, + }) + expect(result.exitCode).toBe(0) + expect(result.stdout).toBe(cliVersion) + expect(result.stderr).toBe('') + } finally { + rmSync(installation, { recursive: true, force: true }) + } + }) + it('fails loud on a nonexistent profile with the plugin-command hint', async () => { const home = mkdtempSync(join(tmpdir(), 'dsh-missing-profile-')) try { diff --git a/apps/cli/tsdown.config.ts b/apps/cli/tsdown.config.ts index 51dec0dc6c..cfb50e6af4 100644 --- a/apps/cli/tsdown.config.ts +++ b/apps/cli/tsdown.config.ts @@ -14,5 +14,5 @@ export default defineConfig({ target: 'es2024', fixedExtension: false, dts: false, - clean: false, + clean: ['lib/*.js'], }) diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts index 27ac026b7d..174bc48d7f 100644 --- a/apps/web/tests/hmr-live.e2e.ts +++ b/apps/web/tests/hmr-live.e2e.ts @@ -78,7 +78,7 @@ function waitForOutput(child: SubprocessHandle, pattern: RegExp, label: string): async function stopTree(child: SubprocessHandle): Promise { child.terminate() const stopped = await child.waitForExit(AbortSignal.timeout(15_000)) - if (!stopped) throw new Error(`process tree ${String(child.pid)} did not stop after termination escalation`) + if (!stopped) throw new Error('managed process range did not stop after termination escalation') await child.done } diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 208b1e910f..0e75402353 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/config-catalog.md -config-catalog.md: f7bb896ffd2613da1ccd253957f36381d0d678f8 -config-catalog.zh.md: cabf36d32aa4755edff8850ecae5d627c0f9518a +config-catalog.md: 88fb3875567947dfe32b61bb65287a5d8551df4e +config-catalog.zh.md: 1e5f2347ab05d4979fe49b2e5bb06d742ee9621d diff --git a/docs/config-catalog.md b/docs/config-catalog.md index f7bb896ffd..88fb387556 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -309,7 +309,7 @@ export type Config = LocalConfig Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) -Source: [`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-sandbox/src/index.ts) +Source: [`packages/shell/bash-sandbox/src/index.ts:36`](../packages/shell/bash-sandbox/src/index.ts) @@ -2394,7 +2394,7 @@ export interface Config { * `bypassPermissions` explicitly skips permission checks. */ permissionMode?: ClaudeCodePermissionMode - /** Grace in milliseconds for Claude Code process-tree termination. */ + /** Grace in milliseconds between Claude Code managed-range termination tiers. */ disposeGraceMs?: number } @@ -2424,7 +2424,7 @@ export interface Config { env?: Record /** Native non-interactive permission mode fixed for this Provider instance. */ permissionMode?: CodexPermissionMode - /** Grace in milliseconds for app-server process-tree termination. */ + /** Grace in milliseconds between app-server managed-range termination tiers. */ disposeGraceMs?: number } @@ -2539,7 +2539,7 @@ export interface Config { } ``` -Source: [`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts) +Source: [`packages/e2b/subprocess-e2b/src/index.ts:26`](../packages/e2b/subprocess-e2b/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index cabf36d32a..1e5f2347ab 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -311,7 +311,7 @@ export type Config = LocalConfig 依赖：[`LocalConfig`](#deepseek-aidsh-bash-local) -来源：[`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-sandbox/src/index.ts) +来源：[`packages/shell/bash-sandbox/src/index.ts:36`](../packages/shell/bash-sandbox/src/index.ts) @@ -2396,7 +2396,7 @@ export interface Config { * `bypassPermissions` explicitly skips permission checks. */ permissionMode?: ClaudeCodePermissionMode - /** Grace in milliseconds for Claude Code process-tree termination. */ + /** Grace in milliseconds between Claude Code managed-range termination tiers. */ disposeGraceMs?: number } @@ -2426,7 +2426,7 @@ export interface Config { env?: Record /** Native non-interactive permission mode fixed for this Provider instance. */ permissionMode?: CodexPermissionMode - /** Grace in milliseconds for app-server process-tree termination. */ + /** Grace in milliseconds between app-server managed-range termination tiers. */ disposeGraceMs?: number } @@ -2541,7 +2541,7 @@ export interface Config { } ``` -来源：[`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts) +来源：[`packages/e2b/subprocess-e2b/src/index.ts:26`](../packages/e2b/subprocess-e2b/src/index.ts) diff --git a/docs/subsystems/shell.i18n.yaml b/docs/subsystems/shell.i18n.yaml index c77b3a0313..3253bbdd17 100644 --- a/docs/subsystems/shell.i18n.yaml +++ b/docs/subsystems/shell.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/shell.md -shell.md: 9d5f0431924499716c38d4d155e8993d942788ab -shell.zh.md: 5874ca44f82d54e9ae4b505a22c7a97a9a0b45d6 +shell.md: 298544569906ddf62ad0703e25beab19204855d7 +shell.zh.md: d4f25e333d57142115af67cdee4f4eb4c7c460ab diff --git a/docs/subsystems/shell.md b/docs/subsystems/shell.md index 9d5f043192..2985445699 100644 --- a/docs/subsystems/shell.md +++ b/docs/subsystems/shell.md @@ -2,7 +2,7 @@ English | [中文](shell.zh.md) -The bash execution seam is split across a Service Definition ([dsh-shell](../../packages/shell/shell), `ctx.shell`), Service Providers ([dsh-bash-local](../../packages/shell/bash-local) and [dsh-bash-sandbox](../../packages/shell/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/shell/tool-bash), the `bash` schema). Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md). +The bash execution seam is split across a Service Definition ([dsh-shell](../../packages/shell/shell), `ctx.shell`), Service Providers ([dsh-bash-local](../../packages/shell/bash-local) and [dsh-bash-sandbox](../../packages/shell/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/shell/tool-bash), the `bash` schema). Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a task-free process handle. Managed-range mechanics live behind the [subprocess seam](subprocess.md). Source: [`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts) @@ -166,7 +166,7 @@ The `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) i ## Background processes: `ShellProcess` -`start()` returns a handle with no id or owner. `dsh-tool-bash` adapts it into `ctx.jobs.start()` hooks; the generic runtime then owns job identity and lifecycle. `done` resolves when the process closes and never rejects, reads remain valid after settlement, and sandbox facts are stamped before `done` resolves. +`start()` returns a handle with no id or owner. `dsh-tool-bash` adapts it into `ctx.jobs.start()` hooks; the generic runtime then owns job identity and lifecycle. `done` resolves when the underlying process settles and never rejects; a subprocess provider rejection becomes a `killed` process with a stage-neutral error on stderr. Reads remain valid after settlement, and sandbox facts are stamped before `done` resolves. ```ts type-equiv /** @@ -182,7 +182,10 @@ interface ShellProcess { exitCode: number | null /** Terminating signal name, when signal-killed. */ signal: NodeJS.Signals | null - /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */ + /** + * Resolves when the underlying process settles (never rejects — provider + * rejection settles as `killed` with a stage-neutral error on stderr). + */ readonly done: Promise /** Sandbox facts, stamped once a confined process settles. */ sandbox?: ShellSandboxInfo @@ -193,7 +196,7 @@ interface ShellProcess { */ readOutput(): ShellProcessRead /** - * Kill the process group. Returns false when it had already finished + * Terminate the provider-managed range. Returns false when it had already finished * (no-op); idempotent. */ kill(): boolean @@ -218,7 +221,7 @@ interface ShellProcessRead { ## The service -`ShellExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; process groups, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic job runtime](jobs.md). `dsh-shell` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill. +`ShellExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; managed-range termination, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic job runtime](jobs.md). `dsh-shell` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill. diff --git a/docs/subsystems/shell.zh.md b/docs/subsystems/shell.zh.md index 5874ca44f8..d4f25e333d 100644 --- a/docs/subsystems/shell.zh.md +++ b/docs/subsystems/shell.zh.md @@ -2,7 +2,7 @@ [English](shell.md) | 中文 -bash 执行 seam 分为 Service Definition（[dsh-shell](../../packages/shell/shell)，`ctx.shell`）、Service Provider（[dsh-bash-local](../../packages/shell/bash-local) 与 [dsh-bash-sandbox](../../packages/shell/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/shell/tool-bash)，即 `bash` schema）。通用后台任务的 job id、所有权与控制位于 [jobs.md](jobs.zh.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制封装在[子进程 seam](subprocess.zh.md)之后。 +bash 执行 seam 分为 Service Definition（[dsh-shell](../../packages/shell/shell)，`ctx.shell`）、Service Provider（[dsh-bash-local](../../packages/shell/bash-local) 与 [dsh-bash-sandbox](../../packages/shell/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/shell/tool-bash)，即 `bash` schema）。通用后台任务的 job id、所有权与控制位于 [jobs.md](jobs.zh.md)；本 seam 返回一个不含任务概念的进程句柄。managed-range 机制封装在[子进程 seam](subprocess.zh.md)之后。 源码：[`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts) @@ -166,7 +166,7 @@ interface ShellSandboxInfo { ## 后台进程：`ShellProcess` -`start()` 返回不含 id 或所有者的句柄。`dsh-tool-bash` 将它适配为 `ctx.jobs.start()` 钩子；随后由通用运行时拥有任务标识与生命周期。`done` 在进程关闭时完成且绝不被拒绝；进程结束后仍可读取，并且沙箱事实会在 `done` 完成前写入。 +`start()` 返回不含 id 或所有者的句柄。`dsh-tool-bash` 将它适配为 `ctx.jobs.start()` 钩子；随后由通用运行时拥有任务标识与生命周期。`done` 会在底层进程结算时完成且绝不 reject；subprocess 提供方的 rejection 会生成状态为 `killed` 的进程，并把不声明阶段的错误写入 stderr。进程结算后仍可读取，并且沙箱事实会在 `done` 完成前写入。 ```ts type-equiv /** @@ -182,7 +182,10 @@ interface ShellProcess { exitCode: number | null /** Terminating signal name, when signal-killed. */ signal: NodeJS.Signals | null - /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */ + /** + * Resolves when the underlying process settles (never rejects — provider + * rejection settles as `killed` with a stage-neutral error on stderr). + */ readonly done: Promise /** Sandbox facts, stamped once a confined process settles. */ sandbox?: ShellSandboxInfo @@ -193,7 +196,7 @@ interface ShellProcess { */ readOutput(): ShellProcessRead /** - * Kill the process group. Returns false when it had already finished + * Terminate the provider-managed range. Returns false when it had already finished * (no-op); idempotent. */ kill(): boolean @@ -218,7 +221,7 @@ interface ShellProcessRead { ## 服务 -`ShellExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[子进程服务](subprocess.zh.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](jobs.zh.md)。`dsh-shell` 拥有 shell 工具共享的退出状态约定：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。 +`ShellExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；managed-range 终止、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[子进程服务](subprocess.zh.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](jobs.zh.md)。`dsh-shell` 拥有 shell 工具共享的退出状态约定：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。 diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml index bb087de82e..90672cfb7f 100644 --- a/docs/subsystems/subprocess.i18n.yaml +++ b/docs/subsystems/subprocess.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md -subprocess.md: b5d5c61da9d153d9a0d24dab650e310ece154c49 -subprocess.zh.md: 81f0d1aa979c7930d0fa9de9dd56b768b6e3e62d +subprocess.md: 782623760e70648a108ac51252b610e27bffbe45 +subprocess.zh.md: 7b8e590a843899b5f00a309a913e1dcb152c5c1b diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md index b5d5c61da9..782623760e 100644 --- a/docs/subsystems/subprocess.md +++ b/docs/subsystems/subprocess.md @@ -106,14 +106,15 @@ interface SubprocessSpawnSpec { stdio: SubprocessStdio /** * Positive finite grace period in milliseconds, no greater than - * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation - * and for draining still-open collected pipes after the process exits (an - * inherited descriptor held by a surviving descendant cannot hold the - * outcome open indefinitely). + * `MAX_TIMER_DELAY_MS`, available to the provider's termination procedure + * and used for draining still-open collected pipes after the process exits + * (an inherited descriptor held by a survivor cannot hold the outcome open + * indefinitely). Providers document whether range termination is staged or + * immediate. */ graceMs: number /** - * Abort signal — starts the terminate escalation on the process tree when + * Abort signal — starts the terminate escalation on the managed range when * it fires. The caller owns deadlines and cause classification; this seam * only reacts to the abort. */ @@ -129,23 +130,20 @@ interface SubprocessSpawnSpec { } ``` -## Handles: streams, readers, and tree-scoped termination +## Handles: streams, readers, and managed-range termination -A spawn returns a live handle immediately. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. Termination is tree-scoped on every platform: `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL, and `waitForExit()` observes the whole tree — enough for a consumer to build its own teardown ladder (the ACP backend's stdin-EOF-first `disposeAcpChild` is the template). +A spawn returns a live handle synchronously while target and managed-range identities remain provider-private. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. `terminate()` starts the provider's documented procedure, and `waitForExit()` observes the same provider-managed range; staged providers may use `graceMs`, while immediate providers do not delay. Consumers can build their own teardown ladders over those two operations (the ACP backend's stdin-EOF-first `disposeAcpChild` is the template). ```ts type-equiv /** - * A live child process rooted in its own process tree. Collected output + * A live subprocess and its provider-managed process range. Collected output * remains readable after exit; piped streams belong to the caller. * - * Termination is tree-scoped everywhere: POSIX signals the detached process - * group (falling back to the direct child when the group is gone), Windows - * terminates the tree via `taskkill /T`, so helper processes cannot outlive - * the handle unnoticed. + * Termination and {@link SubprocessHandle.waitForExit} use the same managed + * range. Each provider documents the range it can observe and its signalling + * and observation limits. */ interface SubprocessHandle { - /** Process id (tree root); -1 when the spawn itself failed. */ - readonly pid: number /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */ readonly stdin: Writable | undefined /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */ @@ -154,20 +152,20 @@ interface SubprocessHandle { readonly stderr: Readable | undefined /** Offset-based readers for collect-mode streams (also readable after exit). */ readonly collected: SubprocessCollectedOutputs - /** Resolves at process close with exit facts; rejects only for spawn-level failures. */ + /** Resolves with spawned-command exit facts; rejects for spawn or provider failures. */ readonly done: Promise /** - * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree - * (Windows force-terminates immediately) — the seam's only termination - * verb. Idempotent, a no-op once the tree is gone (the pid may be reused), - * and also triggered by the spec's abort signal. + * Begin the provider's documented termination procedure on the managed range + * — the seam's only termination verb. Idempotent, a no-op once that range is + * gone, and also triggered by the spec's abort signal. */ terminate(): void /** - * Wait until the process tree has exited — the tree, not just the direct - * child, so a still-running helper is observable before teardown returns. + * Wait until the same managed range is empty — not just until the spawned + * command reports its outcome, so surviving work remains observable. * @param signal - optional bound for the wait. - * @returns `true` when the tree exited, `false` when the signal aborted first. + * @returns `true` when the managed range is empty, `false` when the signal aborted first. + * @throws when the selected provider can no longer observe its managed range. */ waitForExit(signal?: AbortSignal): Promise } @@ -246,7 +244,7 @@ The terminal spec fully specifies argv, cwd, environment overrides, dimensions, ## Service behavior -The abstract [`SubprocessRuntime`](../../packages/subprocess/subprocess/src/index.ts) Service Definition specifies execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessRuntime`](../../packages/subprocess/subprocess-local/src/index.ts) provides them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the Service Definition contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics. +The abstract [`SubprocessRuntime`](../../packages/subprocess/subprocess/src/index.ts) Service Definition specifies execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessRuntime`](../../packages/subprocess/subprocess-local/src/index.ts) provides them with platform-selected managed ranges, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the Service Definition contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics. @@ -282,9 +280,9 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as Implementations must honor these semantics: - Executable paths belong to one execution world shared with the mounted filesystem provider. -- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures. +- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here. -- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence. +- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits. - Disposal of the service terminates all still-running managed processes and awaits their exit. - spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits. @@ -307,13 +305,14 @@ abstract resolveExecutable( command: string, env?: Readonly /** - * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree - * (Windows force-terminates immediately) — the seam's only termination - * verb. Idempotent, a no-op once the tree is gone (the pid may be reused), - * and also triggered by the spec's abort signal. + * Begin the provider's documented termination procedure on the managed range + * — the seam's only termination verb. Idempotent, a no-op once that range is + * gone, and also triggered by the spec's abort signal. */ terminate(): void /** - * Wait until the process tree has exited — the tree, not just the direct - * child, so a still-running helper is observable before teardown returns. + * Wait until the same managed range is empty — not just until the spawned + * command reports its outcome, so surviving work remains observable. * @param signal - optional bound for the wait. - * @returns `true` when the tree exited, `false` when the signal aborted first. + * @returns `true` when the managed range is empty, `false` when the signal aborted first. + * @throws when the selected provider can no longer observe its managed range. */ waitForExit(signal?: AbortSignal): Promise } @@ -246,7 +244,7 @@ interface SubprocessOutcome { ## 服务行为 -抽象的 [`SubprocessRuntime`](../../packages/subprocess/subprocess/src/index.ts) Service Definition 规定执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessRuntime`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放提供这些能力。Service Definition 约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.zh.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.zh.md)。 +抽象的 [`SubprocessRuntime`](../../packages/subprocess/subprocess/src/index.ts) Service Definition 规定执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessRuntime`](../../packages/subprocess/subprocess-local/src/index.ts) 以平台选择的 managed range、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放提供这些能力。Service Definition 约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.zh.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.zh.md)。 @@ -282,9 +280,9 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as Implementations must honor these semantics: - Executable paths belong to one execution world shared with the mounted filesystem provider. -- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures. +- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures. - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here. -- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence. +- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits. - Disposal of the service terminates all still-running managed processes and awaits their exit. - spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits. @@ -307,13 +305,14 @@ abstract resolveExecutable( command: string, env?: Readonly { + validateNoNullByte(index === 0 ? "The argument 'file'" : `The argument 'args[${String(index - 1)}]'`, value) + }) + validateNoNullByte("The property 'options.cwd'", spec.cwd) + for (const [key, value] of Object.entries(spec.env ?? {})) { + if (value === undefined) continue + validateNoNullByte(`The property 'options.env['${key}']'`, key) + validateNoNullByte(`The property 'options.env['${key}']'`, value) } const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID()) const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir, this.pollMs) diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts index e3dd047e38..ce4e91c268 100644 --- a/packages/e2b/subprocess-e2b/src/process.ts +++ b/packages/e2b/subprocess-e2b/src/process.ts @@ -155,7 +155,7 @@ function waitWithSignal(promise: Promise, signal: AbortSignal | undefined) }) } -/** E2B-backed subprocess handle with deferred remote PID acquisition. */ +/** E2B-backed subprocess handle with private remote process-group tracking. */ export class E2BSubprocessHandle implements SubprocessHandle { readonly stdin: Writable | undefined readonly stdout: PassThrough | undefined @@ -174,7 +174,7 @@ export class E2BSubprocessHandle implements SubprocessHandle { private readonly stderrReader: E2BOutputReader | undefined private readonly paths: RemotePaths private controlEnvs: Record = {} - private remotePid = -1 + private remoteProcessGroupId: number | undefined private outputTransportError: Error | undefined private outputDrainExpired = false private stateDirectoryCreated = false @@ -225,11 +225,6 @@ export class E2BSubprocessHandle implements SubprocessHandle { if (spec.signal?.aborted === true) this.terminate() } - /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */ - get pid(): number { - return this.remotePid - } - /** @inheritdoc */ terminate(): void { if (this.quiescenceProven || this.terminationAttempt !== undefined) return @@ -260,7 +255,7 @@ export class E2BSubprocessHandle implements SubprocessHandle { this.markQuiescent() return true } - if (this.remotePid <= 0) { + if (this.remoteProcessGroupId === undefined) { const attempt = this.terminationAttempt if (attempt !== undefined && await waitWithSignal(attempt.catch(() => undefined), signal) === WAIT_ABORTED) { return false @@ -293,7 +288,7 @@ export class E2BSubprocessHandle implements SubprocessHandle { } throw error } - const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid + const processGroupId = this.remoteProcessGroupId ?? handle.pid while (await this.groupAlive(sandbox, processGroupId, signal)) { this.throwTerminationFailure() if (!await waitTick(this.pollMs, signal)) return false @@ -349,7 +344,7 @@ export class E2BSubprocessHandle implements SubprocessHandle { } this.commandState.resolve(handle) try { - this.remotePid = await this.waitForProcessGroupId(sandbox, completion) + this.remoteProcessGroupId = await this.waitForProcessGroupId(sandbox, completion) } catch (error: unknown) { try { await this.rollbackUnpublishedGroup(sandbox, handle) @@ -559,7 +554,7 @@ export class E2BSubprocessHandle implements SubprocessHandle { } private async rollbackPublishedFailure(error: unknown): Promise { - if (this.remotePid <= 0 || this.quiescenceProven) return error + if (this.remoteProcessGroupId === undefined || this.quiescenceProven) return error this.terminate() try { await this.waitForExit() @@ -599,13 +594,13 @@ export class E2BSubprocessHandle implements SubprocessHandle { this.markQuiescent() return } - if (!isValidProcessId(handle.pid) && this.remotePid <= 0) { + if (!isValidProcessId(handle.pid) && this.remoteProcessGroupId === undefined) { await handle.kill() this.markQuiescent() return } const sandbox = await this.runtime.getSandbox() - const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid + const processGroupId = this.remoteProcessGroupId ?? handle.pid await this.terminateGroup(sandbox, handle, processGroupId) } diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts index fe79c60720..c1f1a3e4d7 100644 --- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts +++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts @@ -400,12 +400,10 @@ describe('E2BSubprocessHandle', () => { KEEP: undefined, }, }), '/workspace/.dsh-e2b/processes/one') - expect(handle.pid).toBe(-1) handle.stdin!.write('hello') handle.stdin!.end() fake.releaseStart() await flush() - expect(handle.pid).toBe(4343) expect(fake.handle.sent.map(value => String(value))).toEqual(['hello']) expect(fake.handle.closes).toBe(1) const controlEnvs = fake.startOptions?.envs @@ -1164,7 +1162,6 @@ describe('E2BSubprocessHandle', () => { fake.backgroundError = new Error('start failed') const handle = testHandle(runtime(fake), spec(), '/runtime/fail') await expect(handle.done).rejects.toThrow('start failed') - expect(handle.pid).toBe(-1) expect(fake.removed).toContain('/runtime/fail/environment') expect(fake.removed).toContain('/runtime/fail') await expect(handle.waitForExit()).resolves.toBe(true) @@ -1405,6 +1402,17 @@ describe('E2BSubprocessHandle', () => { await expect(absent.waitForExit()).resolves.toBe(true) }) + it('keeps polling while a running command has not published its process group yet', async () => { + const fake = new FakeSandbox() + fake.processGroupReads.push('', '4242\n') + const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group-publication', 1) + + await vi.waitFor(() => { expect(fake.processGroupReads).toEqual([]) }) + fake.finish() + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + }) + it('preserves publication failure and reports cleanup that cannot be verified', async () => { const fake = new FakeSandbox() fake.processGroupId = 'not-a-pid\n' @@ -1447,15 +1455,6 @@ describe('E2BSubprocessHandle', () => { await expect(observed.waitForExit()).resolves.toBe(true) }) - it('waits for delayed process-group publication', async () => { - const fake = new FakeSandbox() - fake.processGroupReads.push('', '4242\n') - const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group') - await vi.waitFor(() => { expect(handle.pid).toBe(4242) }) - fake.finish() - await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) - }) - it('handles output backpressure and contains a stderr sink failure', async () => { const fake = new FakeSandbox() const handle = testHandle(runtime(fake), spec({ @@ -1775,9 +1774,37 @@ describe('E2BSubprocessRuntime', () => { await expect(handle.done).rejects.toThrow('start failed during disposal') }) - it('validates synchronous spawn preconditions', async () => { - const { ctx } = await service() + it('validates synchronous spawn preconditions before handle or remote work', async () => { + const fake = new FakeSandbox() + const getSandbox = vi.fn(async () => fake.sandbox) + const { ctx } = await service(fake, runtime(fake, getSandbox)) + const live = (ctx.subprocess as unknown as { live: Set }).live expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/) - expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/) + expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))) + .toThrow(new Error('aborted before spawn: stop')) + expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort(null) }))) + .toThrow(new Error('aborted before spawn: aborted')) + const throwingReason = { toString: () => { throw new Error('caller reason escaped') } } + expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort(throwingReason) }))) + .toThrow(new Error('aborted before spawn: aborted')) + + for (const invalid of [ + spec({ argv: ['bash\0'] }), + spec({ argv: ['bash', 'bad\0arg'] }), + spec({ cwd: 'bad\0cwd' }), + spec({ env: { REMOVED: undefined, 'BAD\0KEY': 'value' } }), + spec({ env: { BAD: 'bad\0value' } }), + ]) { + let thrown: unknown + try { + ctx.subprocess.spawn(invalid) + } catch (error) { + thrown = error + } + expect(thrown).toMatchObject({ name: 'TypeError', code: 'ERR_INVALID_ARG_VALUE' }) + } + expect(getSandbox).not.toHaveBeenCalled() + expect(live).toEqual(new Set()) + expect(fake.directories).toEqual([]) }) }) diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 0951aea6b1..e2c8bbef24 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -2348,7 +2348,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { key: 'subprocess', summary: 'Abstract subprocess service.', - description: 'Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\n- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another\'s output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\n- SubprocessHandle.terminate (and the spec\'s abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.', + description: 'Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\n- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command\'s exit facts and may reject for spawn or provider failures.\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another\'s output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\n- SubprocessHandle.terminate (and the spec\'s abort signal) starts the provider\'s documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.', methods: [ { signature: 'abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise', @@ -2361,10 +2361,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ description: 'Start one managed child process from a fully-specified spec; this seam applies no defaults.', parameters: [{ name: 'spec', description: 'argv, directory, stdio dispositions, grace, cancellation, and environment.' }], returns: 'the live process handle (streams/readers, signalling, outcome promise).', + throws: ['synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation.'], }, { signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise', - description: 'Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and complete session-tree cleanup.', + description: 'Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and whole-session quiescence.', parameters: [{ name: 'spec', description: 'fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.' }], returns: 'the live terminal handle after allocation succeeds.', }, @@ -5691,7 +5692,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SubprocessHandle', - declaration: 'export interface SubprocessHandle {\n readonly pid: number;\n readonly stdin: Writable | undefined;\n readonly stdout: Readable | undefined;\n readonly stderr: Readable | undefined;\n readonly collected: SubprocessCollectedOutputs;\n readonly done: Promise;\n terminate(): void;\n waitForExit(signal?: AbortSignal): Promise;\n}', + declaration: 'export interface SubprocessHandle {\n readonly stdin: Writable | undefined;\n readonly stdout: Readable | undefined;\n readonly stderr: Readable | undefined;\n readonly collected: SubprocessCollectedOutputs;\n readonly done: Promise;\n terminate(): void;\n waitForExit(signal?: AbortSignal): Promise;\n}', }, { name: 'SubprocessOutcome', diff --git a/packages/fs/tool-fs-search/src/search-core.ts b/packages/fs/tool-fs-search/src/search-core.ts index 542ca4553e..acdca37c00 100644 --- a/packages/fs/tool-fs-search/src/search-core.ts +++ b/packages/fs/tool-fs-search/src/search-core.ts @@ -201,9 +201,10 @@ export function resolveRgPath(): Promise { * `SEARCH_INVALID_PATTERN`, the rest → `SEARCH_FAILED` / * `SEARCH_RAW_OUTPUT_OVERFLOW`). Both launch-time failure domains are * classified: a synchronous throw at spawn CREATION (a NUL in argv, an abort - * racing the pre-check, a rejected `@vscode/ripgrep` resolution) and a - * rejection of `handle.done` (the seam's infrastructure failures) both become - * `SEARCH_FAILED` with the original as `cause` — an abort already observed by + * racing the pre-check, a rejected `@vscode/ripgrep` resolution) reports that + * the command could not start, while a rejection of `handle.done` reports a + * provider failure without claiming whether execution began. Both become + * `SEARCH_FAILED` with the original as `cause`; an abort already observed by * creation time becomes `SEARCH_ABORTED` instead. * * @param ctx - the plugin context; execution uses its `subprocess` service. @@ -258,7 +259,7 @@ export async function runRipgrep( try { outcome = await handle.done } catch (error: unknown) { - throw new SearchError(`${toolName} could not start its search command (ripgrep launch failed)`, 'SEARCH_FAILED', { cause: error }) + throw new SearchError(`${toolName} subprocess failed before reporting an outcome (ripgrep provider failure)`, 'SEARCH_FAILED', { cause: error }) } const stdout = handle.collected.stdout?.readFrom(0) const stderr = handle.collected.stderr?.readFrom(0) diff --git a/packages/fs/tool-fs-search/tests/integration.spec.ts b/packages/fs/tool-fs-search/tests/integration.spec.ts index 94be0e1088..77ed0c8c1a 100644 --- a/packages/fs/tool-fs-search/tests/integration.spec.ts +++ b/packages/fs/tool-fs-search/tests/integration.spec.ts @@ -189,12 +189,13 @@ describe('search tools over the real subprocess service + the packaged rg', () = expect(result.error).toMatchObject({ info: { name: 'AbortError', code: TOOL_ABORTED_BEFORE_DISPATCH } }) }) - it('an unusable session cwd (spawn failure) is SEARCH_FAILED', async () => { + it('an unusable session cwd provider rejection is SEARCH_FAILED', async () => { const gone = join(dir, 'deleted-session-dir') const result = await call('glob', { pattern: '*' }, { session: { header: { id: 'session-int', cwd: gone } } }) expect(result.isError).toBe(true) expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } }) - expect(text(result)).toContain('could not start') + expect(text(result)).toContain('subprocess failed before reporting an outcome') + expect(text(result)).not.toContain('could not start') }) }) }) diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 12efe3b220..3ecfd86a5b 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -96,7 +96,6 @@ class FakeReader implements SubprocessOutputReader { * abort→terminate escalation. */ class FakeHandle implements SubprocessHandle { - readonly pid = 4242 readonly stdin = undefined readonly stdout = undefined readonly stderr = undefined @@ -472,10 +471,9 @@ describe('workdir derivation and signal forwarding', () => { .toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' }) }) - it('translates a spawn rejection into SEARCH_FAILED even when the signal aborts concurrently', async () => { - // The seam rejects only for infrastructure failures (unusable workdir, - // missing binary); the abort happened after dispatch, so the launch - // failure is the reportable cause with the original error chained. + it('translates a provider rejection without claiming the search command never started', async () => { + // The public seam does not expose whether a done rejection happened before + // or after target execution; the original provider error remains chained. const { ctx, subprocess } = await setup() const controller = new AbortController() subprocess.handler = () => { @@ -487,7 +485,8 @@ describe('workdir derivation and signal forwarding', () => { expect(result.isError).toBe(true) expect(result.error).toMatchObject({ info: { name: 'SearchError', code: 'SEARCH_FAILED' } }) - expect(text(result)).toContain('could not start') + expect(text(result)).toContain('subprocess failed before reporting an outcome') + expect(text(result)).not.toContain('could not start') }) it('classifies a synchronous spawn-creation throw as SEARCH_FAILED', async () => { diff --git a/packages/lsp/lsp-stdio/README.i18n.yaml b/packages/lsp/lsp-stdio/README.i18n.yaml index 56f4a4295b..ccddf79ad6 100644 --- a/packages/lsp/lsp-stdio/README.i18n.yaml +++ b/packages/lsp/lsp-stdio/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/lsp/lsp-stdio/README.md -README.md: c19c3892d77680899f00c52582a7cfdce1cca9b5 -README.zh.md: 696f4758f94cc765c5149da7d8e615284f6a5d19 +README.md: 61137e544ea7c9ba0d2458fc99a43eaa1c03aafb +README.zh.md: 39c327346c90d7efeee895035e35a76b17354cf5 diff --git a/packages/lsp/lsp-stdio/README.md b/packages/lsp/lsp-stdio/README.md index c19c3892d7..61137e544e 100644 --- a/packages/lsp/lsp-stdio/README.md +++ b/packages/lsp/lsp-stdio/README.md @@ -91,7 +91,7 @@ This section explains the design decisions behind the provider and where the cod - **Read before spawn.** The source is resolved, contained, and byte-bounded inside the workspace queue before any process is created, so a queued query sees current bytes when its turn starts and an invalid source cannot leave an idle process pooled. - **One pooled process per canonical workspace.** Instances are single-flighted per `(server id, canonical workspace target)`; a transport failure retries the read-only query once on a fresh process after awaiting disposal. - **Per-workspace serialization.** One abortable queue per workspace serializes source-read/open/query/close lifecycles; distinct workspaces run in parallel, and a cancellation that fails to stop a server terminates only that instance. -- **Bounded teardown.** Graceful `shutdown`/`exit` escalates through tree termination (process-group signaling on POSIX, `taskkill /T /F` on Windows); quiescence is confirmed by awaiting process-tree exit, not by the kill outcome. +- **Bounded teardown.** Graceful `shutdown`/`exit` escalates through the subprocess provider's managed-range termination procedure; quiescence is confirmed by awaiting that whole range, not by the termination request's outcome. - **Execution-world pairing.** Servers launch through `ctx.subprocess` with `processId: null` (another machine or PID namespace must not monitor the harness), sources read through `ctx.fs`, and no `fs/observed` event is emitted — only the LSP result is model-visible. ### Source map diff --git a/packages/lsp/lsp-stdio/README.zh.md b/packages/lsp/lsp-stdio/README.zh.md index 696f4758f9..39c327346c 100644 --- a/packages/lsp/lsp-stdio/README.zh.md +++ b/packages/lsp/lsp-stdio/README.zh.md @@ -91,7 +91,7 @@ kind: "package-reference" - **先读后启动。** 源文件在工作区队列内先完成解析、包含关系检查与字节限制，然后才创建任何进程，因此排队查询只会在轮到自身时读取当前字节，无效源文件也不会留下空闲的池化进程。 - **每个规范工作区一个池化进程。** 实例按 `(server id, canonical workspace target)` 进行 single-flight；传输故障会在等待释放完成后于新进程上重试一次该只读查询。 - **逐工作区串行化。** 每个工作区一条可中止队列，串行执行源读取／打开／查询／关闭生命周期；不同工作区并行运行，无法停止服务器的取消只会终止该实例。 -- **有边界的释放。** 优雅 `shutdown`／`exit` 升级为进程树终止（POSIX 进程组信号，Windows `taskkill /T /F`）；是否完全停稳由等待进程树退出确认，而非由终止操作自身的结果确认。 +- **有边界的释放。** 优雅 `shutdown`／`exit` 会升级到 subprocess 提供方的 managed-range 终止流程；是否完全停稳由等待整个 range 确认，而非由终止请求自身的结果确认。 - **执行世界配对。** 服务器通过 `ctx.subprocess` 启动，`processId: null`（另一台机器或 PID namespace 不得监视 harness）；源文件通过 `ctx.fs` 读取；不发出 `fs/observed` 事件——只有 LSP 结果对模型可见。 ### 源码地图 diff --git a/packages/lsp/lsp-stdio/src/connection.ts b/packages/lsp/lsp-stdio/src/connection.ts index 5cfcf10b0c..bdc4b3fb11 100644 --- a/packages/lsp/lsp-stdio/src/connection.ts +++ b/packages/lsp/lsp-stdio/src/connection.ts @@ -4,8 +4,8 @@ * server→client requests: it answers `workspace/configuration` from static * config, and rejects `workspace/applyEdit` (this host never applies edits or * runs commands). It caps stderr, surfaces framing/decoder failures as a - * fatal close, and exposes tree-scoped termination through the handle so the - * instance owns teardown; group/tree mechanics live in the subprocess + * fatal close, and exposes managed-range termination through the handle so the + * instance owns teardown; platform mechanics live in the subprocess * Service Provider. * @module @deepseek-ai/dsh-lsp-stdio/connection */ @@ -88,7 +88,7 @@ export class LspConnection { this.decoder = new MessageDecoder(spec.maxMessageBytes) // stdin/stdout are piped protocol streams this endpoint frames itself; // stderr is a collected diagnostic tail (no spill — the bounded tail IS - // the contract). The seam owns detachment and tree-scoped signalling. + // the contract). The seam owns managed-range signalling and observation. this.handle = spawner({ argv: [spec.command, ...spec.args], cwd: spec.cwd, @@ -131,11 +131,6 @@ export class LspConnection { this.handle.stdout.on('data', (chunk: Buffer) => { this.onStdout(chunk) }) } - /** The child's pid, or `-1` when the spawn produced no pid (so signalling is a no-op). */ - get pid(): number { - return this.handle.pid - } - /** The retained stderr tail, for diagnostics on a failed server. */ get stderrTail(): string { /* v8 ignore next -- the collect disposition always exposes a stderr reader; defensive. */ @@ -209,17 +204,17 @@ export class LspConnection { return this.nextId } - /** Terminate the server's process tree (the seam's SIGTERM→grace→SIGKILL escalation; idempotent). */ + /** Terminate the server's provider-managed range (idempotent). */ terminate(): void { this.handle.terminate() } /** - * Wait until the owned process tree has exited. + * Wait until the owned managed range is empty. * @param signal - optional bound for the wait. - * @returns `true` when the tree exited, or `false` when the signal aborted first. + * @returns `true` when the range is empty, or `false` when the signal aborted first. */ - async waitForProcessTreeExit(signal?: AbortSignal): Promise { + async waitForManagedRangeExit(signal?: AbortSignal): Promise { return await this.handle.waitForExit(signal) } @@ -229,8 +224,7 @@ export class LspConnection { messages = this.decoder.push(chunk) } catch (error) { // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance and - // terminate the whole group so helper processes don't outlive the leader (SIGTERM first, then - // the kill grace's SIGKILL — a misbehaving server still gets its bounded flush window). + // terminate the managed range so helper processes do not outlive the leader. this.fail(asError(error)) this.handle.terminate() return diff --git a/packages/lsp/lsp-stdio/src/index.ts b/packages/lsp/lsp-stdio/src/index.ts index ebc54702da..bfe1974e38 100644 --- a/packages/lsp/lsp-stdio/src/index.ts +++ b/packages/lsp/lsp-stdio/src/index.ts @@ -281,23 +281,35 @@ class LocalLspProvider implements LspProvider { // synchronous get-or-create so every spawned process remains owned by teardown. this.assertActive(querySignal) let instance = this.instanceFor(workspaceKey, workspace) - try { - return await instance.query(request, source, querySignal) - } catch (error) { - // A selected child can have died while idle or fail during the next write. Queries are - // read-only, so replace that transport once and retry transparently. - if (!instance.isTransportFailure(error)) throw error - await instance.dispose() - this.evictIfCurrent(workspaceKey, instance) - this.assertActive(querySignal) - instance = this.instanceFor(workspaceKey, workspace) - return await instance.query(request, source, querySignal) - } finally { - // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check. + let canRetryTransport = true + for (;;) { + const [queryOutcome] = await Promise.allSettled([ + instance.query(request, source, querySignal), + ]) + let teardownOutcome: PromiseSettledResult | undefined if (instance.dead) { - await instance.dispose() + ;[teardownOutcome] = await Promise.allSettled([instance.dispose()]) + // A dead instance is never reusable, even when its final quiescence observation fails. this.evictIfCurrent(workspaceKey, instance) } + if (teardownOutcome?.status === 'rejected') { + if (queryOutcome.status === 'rejected') { + throw new AggregateError( + [queryOutcome.reason, teardownOutcome.reason], + 'LSP operation and teardown failed', + ) + } + throw teardownOutcome.reason + } + if (queryOutcome.status === 'fulfilled') return queryOutcome.value + // A selected child can have died while idle or fail during the next write. Queries are + // read-only, so replace that transport once and retry transparently after clean disposal. + if (!canRetryTransport || !instance.isTransportFailure(queryOutcome.reason)) { + throw queryOutcome.reason + } + canRetryTransport = false + this.assertActive(querySignal) + instance = this.instanceFor(workspaceKey, workspace) } }) } diff --git a/packages/lsp/lsp-stdio/src/instance.ts b/packages/lsp/lsp-stdio/src/instance.ts index 2028129de7..d86d484571 100644 --- a/packages/lsp/lsp-stdio/src/instance.ts +++ b/packages/lsp/lsp-stdio/src/instance.ts @@ -97,7 +97,7 @@ export class LspInstance { const run = abortable(this.queue, signal) .then(() => this.runQuery(request, source, signal)) .catch(async (error: unknown) => { - if (this.isTransportFailure(error)) await this.startTeardown() + if (this.isTransportFailure(error)) await this.awaitTeardownAttempt() throw error }) // Keep the tail alive regardless of this query's outcome so the next caller still serializes. The @@ -136,7 +136,7 @@ export class LspInstance { await abortable(this.ready, signal) } catch (error) { if (!this.dead) { - await this.startTeardown() + await this.awaitTeardownAttempt() } throw error } @@ -162,7 +162,7 @@ export class LspInstance { } catch (error) { // A canceled backpressured write or failed stdin leaves the protocol stream unusable before // `opened` can arm the didClose cleanup. Teardown here makes the pool evict the instance. - await this.startTeardown() + await this.awaitTeardownAttempt() throw error } opened = true @@ -175,15 +175,10 @@ export class LspInstance { if (opened && !this.dead) { try { await this.connection.notify('textDocument/didClose', { textDocument: { uri } }) - } catch { + } catch (_closeFailure: unknown) { // A close-write failure does not replace the settled result/error, but the instance can no - // longer be trusted: invalidate it and await bounded process termination. - try { - await this.startTeardown() - } catch { - /* v8 ignore next -- teardown owns all expected process races; this only preserves the - already-settled query outcome if an unexpected cleanup primitive itself rejects. */ - } + // longer be trusted. The provider re-awaits this teardown and owns failure reporting. + await this.awaitTeardownAttempt() } } } @@ -232,7 +227,7 @@ export class LspInstance { grace.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) }), ]) - if (!settled) await this.startTeardown() + if (!settled) await this.awaitTeardownAttempt() } finally { grace[Symbol.dispose]() } @@ -283,12 +278,21 @@ export class LspInstance { return this.teardownPromise } + /** Await teardown while leaving its memoized failure for provider-level finalization. */ + private async awaitTeardownAttempt(): Promise { + try { + await this.startTeardown() + } catch (_teardownFailure: unknown) { + // LocalLspProvider re-awaits the same teardown and combines it with the query outcome. + } + } + private async tearDown(): Promise { const shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN') try { await this.gracefulShutdown(shutdownDeadline.signal) } catch { - // Graceful shutdown failed or timed out; process-tree cleanup below remains authoritative. + // Graceful shutdown failed or timed out; managed-range cleanup below remains authoritative. } finally { shutdownDeadline[Symbol.dispose]() } @@ -303,16 +307,15 @@ export class LspInstance { } /** - * Terminate the tree (the seam escalates SIGTERM→`killGraceMs`→SIGKILL), - * then await leader and helper exit. The awaits are unbounded on purpose: - * the seam's escalation already committed to SIGKILL, so quiescence — not - * another timer — is the postcondition disposal owes its callers. + * Terminate the provider-managed range, then await the direct server result + * and whole-range quiescence. The awaits are unbounded on purpose because + * quiescence, not another timer, is the postcondition disposal owes callers. */ private async forceTerminate(): Promise { this.connection.terminate() await Promise.all([ this.connection.closed, - this.connection.waitForProcessTreeExit(), + this.connection.waitForManagedRangeExit(), ]) } } diff --git a/packages/lsp/lsp-stdio/tests/connection.spec.ts b/packages/lsp/lsp-stdio/tests/connection.spec.ts index 3785e677e7..37a9ef84e6 100644 --- a/packages/lsp/lsp-stdio/tests/connection.spec.ts +++ b/packages/lsp/lsp-stdio/tests/connection.spec.ts @@ -44,11 +44,10 @@ function connect( } describe('LspConnection', () => { - it('completes an initialize request/response round-trip and exposes a pid', async () => { + it('completes an initialize request/response round-trip', async () => { const conn = connect({}) const result = await conn.request('initialize', { capabilities: {} }) expect(result).toMatchObject({ capabilities: { hoverProvider: true } }) - expect(conn.pid).toBeGreaterThan(0) }) it('forwards explicit DSH_* env entries to the child', async () => { diff --git a/packages/lsp/lsp-stdio/tests/instance.spec.ts b/packages/lsp/lsp-stdio/tests/instance.spec.ts index 9efc091919..7e7ee17696 100644 --- a/packages/lsp/lsp-stdio/tests/instance.spec.ts +++ b/packages/lsp/lsp-stdio/tests/instance.spec.ts @@ -233,15 +233,13 @@ describe('LspInstance query and abort', () => { expect(instance.dead).toBe(true) }) - it('awaits process exit before rejecting a request write failure', async () => { + it('finishes teardown before rejecting a request write failure', async () => { const instance = makeInstance({}, { shutdownTimeoutMs: 100, killGraceMs: 100, }, failingWriter('textDocument/definition')) - // The pid is observed only to prove the owned subprocess reached quiescence before rejection. - const pid = (instance as unknown as { connection: { pid: number } }).connection.pid await expect(run(instance, 'goToDefinition')).rejects.toThrow(/fixture textDocument\/definition failure/) - expect(processAlive(pid)).toBe(false) + expect(instance.dead).toBe(true) }) it('rejects when the server lacks the operation capability', async () => { @@ -268,6 +266,7 @@ describe('LspInstance query and abort', () => { }) expect(instance.dead).toBe(true) }) + }) describe('LspInstance disposal', () => { @@ -312,7 +311,7 @@ describe('LspInstance disposal', () => { await expect(instance.dispose()).resolves.toBeUndefined() }) - it('awaits a surviving process-tree helper on every concurrent dispose', async () => { + it('awaits a surviving managed-range helper on every concurrent dispose', async () => { const marker = join(root, 'helper.pid') const helper = 'process.on("SIGTERM",()=>{});setInterval(()=>{},1000);' const script = 'const{spawn}=require("node:child_process");const{writeFileSync}=require("node:fs");' @@ -372,10 +371,10 @@ async function waitForProcessExit(pid: number, timeoutMs = 3_000): Promise } /** Write normally except for one method whose callback receives a deterministic transport error. */ -function failingWriter(method: string): ConnectionWriter { +function failingWriter(method: string, failure = new Error(`fixture ${method} failure`)): ConnectionWriter { return (stdin, message, done) => { if ((message as { method?: unknown }).method === method) { - queueMicrotask(() => { done(new Error(`fixture ${method} failure`)) }) + queueMicrotask(() => { done(failure) }) return } stdin.write(encodeMessage(message), done) diff --git a/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts b/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts index 55725022f4..e368e2d952 100644 --- a/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts +++ b/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts @@ -11,6 +11,7 @@ import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import LocalFileSystem from '@deepseek-ai/dsh-fs-local' import * as LspLocal from '@deepseek-ai/dsh-lsp-stdio' import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-stdio' +import { LspConnection } from '../src/connection.ts' const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) @@ -44,10 +45,12 @@ async function mount( fakeEnv: Record = {}, overrides: Partial = {}, captureProvider?: (provider: LspProvider) => void, + configureSubprocess?: (ctx: Context) => void, ): Promise { const ctx = new Context() await ctx.plugin(Lsp) await ctx.plugin(LocalSubprocessRuntime) + configureSubprocess?.(ctx) await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) const register = ctx.lsp.registerProvider.bind(ctx.lsp) const registrationSpy = captureProvider === undefined @@ -165,6 +168,98 @@ describe('lsp-stdio end to end over a fake server', () => { await ctx.fiber.dispose() }) + it('preserves a query failure with final disposal failure and evicts the instance', async () => { + const teardownFailure = new Error('managed range observation failed') + let provider: LspProvider | undefined + let firstSpawn = true + let restoreFirstWait: (() => void) | undefined + const ctx = await mount( + { LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' }, + { shutdownTimeoutMs: 100, killGraceMs: 100 }, + (registered) => { provider = registered }, + (mounted) => { + const spawn = mounted.subprocess.spawn.bind(mounted.subprocess) + vi.spyOn(mounted.subprocess, 'spawn').mockImplementation((spec) => { + const handle = spawn(spec) + if (!firstSpawn) return handle + firstSpawn = false + const waitForExit = handle.waitForExit.bind(handle) + const waitSpy = vi.spyOn(handle, 'waitForExit') + .mockImplementation(async (signal) => { + await waitForExit(signal) + throw teardownFailure + }) + restoreFirstWait = () => { waitSpy.mockRestore() } + return handle + }) + }, + ) + const failure = await ctx.lsp.query(query('goToDefinition')).then( + () => undefined, + (error: unknown) => error, + ) + expect(failure).toBeInstanceOf(AggregateError) + const errors = (failure as AggregateError).errors as unknown[] + expect(errors).toHaveLength(2) + expect(errors[0]).toBeInstanceOf(Error) + expect((errors[0] as Error).message).toContain('unsupported position encoding') + expect(errors[1]).toBe(teardownFailure) + expect((failure as AggregateError).message).toBe('LSP operation and teardown failed') + restoreFirstWait?.() + if (provider === undefined) throw new Error('expected lsp-stdio to register a provider') + const instances = (provider as unknown as { readonly instances: ReadonlyMap }).instances + expect(instances.size).toBe(0) + await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/unsupported position encoding/) + expect(instances.size).toBe(0) + await ctx.fiber.dispose() + }) + + it('reports final disposal failure after a settled query and evicts the instance', async () => { + const closeFailure = new Error('fixture textDocument/didClose failure') + const teardownFailure = new Error('managed range observation failed') + const notify = Object.getOwnPropertyDescriptor(LspConnection.prototype, 'notify')?.value as LspConnection['notify'] + const notifySpy = vi.spyOn(LspConnection.prototype, 'notify').mockImplementation(function (this: LspConnection, method, params) { + if (method === 'textDocument/didClose') return Promise.reject(closeFailure) + return notify.call(this, method, params) + }) + let provider: LspProvider | undefined + let restoreFirstWait: (() => void) | undefined + const ctx = await mount( + { LSP_FAKE_DEF: 'null' }, + { shutdownTimeoutMs: 100, killGraceMs: 100 }, + (registered) => { provider = registered }, + (mounted) => { + const spawn = mounted.subprocess.spawn.bind(mounted.subprocess) + let firstSpawn = true + vi.spyOn(mounted.subprocess, 'spawn').mockImplementation((spec) => { + const handle = spawn(spec) + if (!firstSpawn) return handle + firstSpawn = false + const waitForExit = handle.waitForExit.bind(handle) + const waitSpy = vi.spyOn(handle, 'waitForExit').mockImplementation(async (signal) => { + await waitForExit(signal) + throw teardownFailure + }) + restoreFirstWait = () => { waitSpy.mockRestore() } + return handle + }) + }, + ) + try { + await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toBe(teardownFailure) + if (provider === undefined) throw new Error('expected lsp-stdio to register a provider') + const instances = (provider as unknown as { readonly instances: ReadonlyMap }).instances + expect(instances.size).toBe(0) + restoreFirstWait?.() + notifySpy.mockRestore() + await expect(ctx.lsp.query(query('goToDefinition'))).resolves.toMatchObject({ kind: 'locations' }) + } finally { + restoreFirstWait?.() + notifySpy.mockRestore() + await ctx.fiber.dispose() + } + }) + it('rejects a server without transient-open sync (None)', async () => { const ctx = await mount({ LSP_FAKE_SYNC: '0', LSP_FAKE_DEF: 'null' }) await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/transient textDocument\/didOpen/) diff --git a/packages/shell/bash-local/README.i18n.yaml b/packages/shell/bash-local/README.i18n.yaml index 806aa7549c..2c2e783ba3 100644 --- a/packages/shell/bash-local/README.i18n.yaml +++ b/packages/shell/bash-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/bash-local/README.md -README.md: df9248651c94b26df3a16a19a360056a5a9199e1 -README.zh.md: ad5ba2143f0b0eff46264de2be48bd1bb1067edf +README.md: 462054d435433067355a91103aa0d606cea6521b +README.zh.md: 6127c6265079d522b5a58d8b1fd019c1bd909262 diff --git a/packages/shell/bash-local/README.md b/packages/shell/bash-local/README.md index df9248651c..462054d435 100644 --- a/packages/shell/bash-local/README.md +++ b/packages/shell/bash-local/README.md @@ -61,7 +61,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### Background processes -Call `start` to run a command in the background; it returns a handle immediately and no timeout applies. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` stops the process group; `done` settles when the process closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with. +Call `start` to run a command in the background; it returns a handle immediately and no timeout applies. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` terminates the provider-managed range; `done` settles when the direct command closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with. ### Adjusting budgets at runtime @@ -80,7 +80,7 @@ This section explains the design of the executor and points at the code that rea ### Design concept -The executor is a Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything bash-shaped — command defaulting and caps, deadline fusion and cause classification, the model-friendly terminal environment, and the background read merge — while process-group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) belong to the subprocess service. Every call spawns a fresh non-login `bash -c` with no rc files, so commands are deterministic and shell state never leaks between calls. +The executor is a Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything bash-shaped — command defaulting and caps, deadline fusion and cause classification, the model-friendly terminal environment, and the background read merge — while managed-range mechanics (bounded spill-backed output, credential scrub, termination escalation, quiescence, and disposal) belong to the subprocess service. Every call spawns a fresh non-login `bash -c` with no rc files, so commands are deterministic and shell state never leaks between calls. ### Source map @@ -114,7 +114,7 @@ Read these pages when the executor contract is not enough. They move from the se - [bash-sandbox](../bash-sandbox/README.md) — the confining executor to compose instead when commands need the sandbox capability. - [tool-bash](../tool-bash/README.md) — the model-facing `bash` tool over this executor. - [Bash executor subsystem](../../../docs/subsystems/shell.md) — request/spec vocabulary, results, and the service contract in full. -- [subprocess-local](../../subprocess/subprocess-local/README.md) — the process-group mechanics behind this executor. +- [subprocess-local](../../subprocess/subprocess-local/README.md) — the managed-range mechanics behind this executor. ----- @@ -137,7 +137,7 @@ These limits define when this executor is a poor fit. They are current package c - **Unconfined by itself** — commands run with the harness process's authority; deployments needing confinement compose `dsh-bash-sandbox`, while per-call allow/deny/ask policy belongs on the tools' `pre-execute` waterfall. - **No persistent shell or PTY** — every call starts a fresh non-login `bash -c`; cwd-only persistence and interactive terminal sessions remain deferred until a real workflow requires them. - **POSIX-only** — the `bash` binary is hardcoded and the underlying service's group semantics are POSIX; Windows is unsupported. -- **A background spawn-failure note is single-delivery** — the subprocess service buffers no output for a process that never ran, so the executor injects `spawn failed: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it. +- **A background provider-failure note is single-delivery** — `SubprocessHandle.done` can reject before or after target execution begins, so the executor injects the stage-neutral `subprocess failed before reporting an outcome: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it. ### Dev Note diff --git a/packages/shell/bash-local/README.zh.md b/packages/shell/bash-local/README.zh.md index ad5ba2143f..6127c62650 100644 --- a/packages/shell/bash-local/README.zh.md +++ b/packages/shell/bash-local/README.zh.md @@ -61,7 +61,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### 后台进程 -调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 停止进程组；`done` 在进程关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 +调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止提供方管理的 range；`done` 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 ### 运行时调整预算 @@ -80,7 +80,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### 设计概念 -本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 Service Provider：它负责所有 bash 层职责——命令默认化与上限、deadline 融合与原因分类、面向模型的终端环境，以及后台读取合并——而进程组机制（有界 spill 输出、凭据清除、终止升级、dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非登录 `bash -c`，不读取 rc 文件，因此命令是确定性的，shell 状态绝不会在调用之间泄漏。 +本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 Service Provider：它负责所有 bash 层职责——命令默认化与上限、deadline 融合与原因分类、面向模型的终端环境，以及后台读取合并——而 managed-range 机制（有界 spill 输出、凭据清除、终止升级、完全停稳与 dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非登录 `bash -c`，不读取 rc 文件，因此命令是确定性的，shell 状态绝不会在调用之间泄漏。 ### 源码地图 @@ -114,7 +114,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) - [bash-sandbox](../bash-sandbox/README.zh.md) —— 需要沙箱能力时替换组合的受限执行器。 - [tool-bash](../tool-bash/README.zh.md) —— 基于本执行器的面向模型 `bash` 工具。 - [Bash 执行器子系统](../../../docs/subsystems/shell.zh.md) —— 请求/spec 词汇、结果与完整的服务约定。 -- [subprocess-local](../../subprocess/subprocess-local/README.zh.md) —— 本执行器背后的进程组机制。 +- [subprocess-local](../../subprocess/subprocess-local/README.zh.md) —— 本执行器背后的 managed-range 机制。 ----- @@ -137,7 +137,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合 `dsh-bash-sandbox`，每次调用的 allow/deny/ask 策略则属于工具的 `pre-execute` waterfall。 - **没有持久 shell 或 PTY**——每次调用都启动全新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续延期，直到真实工作流需要它们。 - **仅支持 POSIX**——`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。 -- **后台 spawn 失败提示只交付一次**——subprocess 服务不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。 +- **后台 provider failure 提示只交付一次**——`SubprocessHandle.done` 可能在 target 开始执行前或后 reject，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。 ### 开发备注 diff --git a/packages/shell/bash-local/src/index.ts b/packages/shell/bash-local/src/index.ts index 064f124a00..0ab4c03964 100644 --- a/packages/shell/bash-local/src/index.ts +++ b/packages/shell/bash-local/src/index.ts @@ -1,6 +1,6 @@ /** * Local Service Provider for the bash capability seam over the subprocess - * capability seam. Public commands run as `bash -c` in a managed process group spawned + * capability seam. Public commands run as `bash -c` in a provider-managed range * through `ctx.subprocess`; subclasses may reuse the same mechanics with an * explicit argv. This executor owns command defaulting, deadlines and cause * classification, the model-friendly terminal environment, and the model-facing @@ -93,9 +93,9 @@ export function assertServiceableBashConfig(config: Config): void { } /** - * Local bash executor over `ctx.subprocess`. Bounded output, spill files, and - * process-group SIGTERM→SIGKILL escalation are the subprocess service's - * mechanics; this executor supplies their configured budgets per spawn, so a + * Local bash executor over `ctx.subprocess`. Bounded output, spill files, + * managed-range SIGTERM→SIGKILL escalation, and quiescence are the subprocess + * service's mechanics; this executor supplies their configured budgets per spawn, so a * still-running background process stays managed (killed and joined at * composition teardown) even across an executor reload. */ @@ -247,24 +247,24 @@ export class LocalBashExecutor extends ShellExecutor { /** * Start an explicit argv with the background lifecycle, environment, output, - * cancellation, and process-tree ownership semantics of this executor. + * cancellation, and managed-range ownership semantics of this executor. * Subclasses use this after replacing the public command's shell argv at an * execution boundary. * @param spec - resolved execution settings and caller-owned command metadata. * @param argv - exact executable and arguments to hand to `ctx.subprocess`. - * @returns the live background handle; spawn rejection settles it as killed. + * @returns the live background handle; provider rejection settles it as killed. */ protected startArgv(spec: ShellExecSpec, argv: readonly string[]): ShellProcess { // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal. const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, this.config.maxOutputBytes, spec.signal)) const collected = LocalBashExecutor.collected(running) - // A spawn failure produces no process output, so the subprocess service has nothing - // to buffer; the note is delivered exactly once through the read path. - let spawnFailureNote: string | undefined - const consumeSpawnFailure = (): string => { - const note = spawnFailureNote ?? '' - spawnFailureNote = undefined + // A provider rejection has no direct outcome to display; its stage is not + // public, so a neutral note is delivered once through the read path. + let providerFailureNote: string | undefined + const consumeProviderFailure = (): string => { + const note = providerFailureNote ?? '' + providerFailureNote = undefined return note } @@ -283,10 +283,16 @@ export class LocalBashExecutor extends ShellExecutor { proc.signal = outcome.signal this.onProcessDone(proc, collected.stderr.readFrom(0).text, false) }, (error: unknown) => { - // Background spawn failures settle as killed and surface through the read path. + // Background provider failures settle as killed and surface through the read path. proc.status = 'killed' - spawnFailureNote = `spawn failed: ${String(error)}` - this.onProcessDone(proc, spawnFailureNote, true, error) + let detail = 'unprintable provider failure' + try { + detail = String(error) + } catch { + // Provider-owned rejection values cannot make ShellProcess.done reject. + } + providerFailureNote = `subprocess failed before reporting an outcome: ${detail}` + this.onProcessDone(proc, providerFailureNote, true, error) }), readOutput: (): ShellProcessRead => { const out = collected.stdout.readFrom(stdoutOffset) @@ -294,9 +300,10 @@ export class LocalBashExecutor extends ShellExecutor { stdoutOffset = out.nextOffset stderrOffset = err.nextOffset - // A failed spawn never produced process output, so the note and real - // stderr text are mutually exclusive. - const errText = err.text.length > 0 ? err.text : consumeSpawnFailure() + const providerFailure = consumeProviderFailure() + const failureSeparator = err.text.length > 0 && !err.text.endsWith('\n') ? '\n' : '' + const errText = err.text + + (providerFailure.length > 0 ? `${failureSeparator}${providerFailure}` : '') // Single newline between sections: stdout chunks usually end with one // already; add it only when missing. const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : '' @@ -321,15 +328,15 @@ export class LocalBashExecutor extends ShellExecutor { /** * Settlement hook for subclasses that attach execution facts to a process. - * Called after exit facts or spawn-failure output are stamped and before + * Called after exit facts or provider-failure output are stamped and before * {@link ShellProcess.done} resolves. The base implementation is intentionally * empty. * @param _proc - the settled process handle. * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification. - * @param _spawnFailed - whether the subprocess promise rejected before a process started. - * @param _spawnError - the original spawn rejection reason, which may itself be undefined. + * @param _providerRejected - whether the subprocess promise rejected without a direct outcome. + * @param _providerError - the provider rejection reason, which may itself be undefined. */ - protected onProcessDone(_proc: ShellProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void {} + protected onProcessDone(_proc: ShellProcess, _stderr: string, _providerRejected: boolean, _providerError?: unknown): void {} } export default LocalBashExecutor diff --git a/packages/shell/bash-local/tests/executor.spec.ts b/packages/shell/bash-local/tests/executor.spec.ts index 0f5b7992f3..7a690b3984 100644 --- a/packages/shell/bash-local/tests/executor.spec.ts +++ b/packages/shell/bash-local/tests/executor.spec.ts @@ -1,10 +1,11 @@ import { mkdtempSync, rmSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { afterAll, describe, expect, it } from 'vitest' +import { afterAll, describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' +import type { SubprocessHandle, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' import type { ShellProcess } from '@deepseek-ai/dsh-shell' @@ -242,7 +243,7 @@ describe('LocalBashExecutor.start (background process handles)', () => { expect(read.delta).toContain('[stderr]') }) - it('kill() terminates the process group: true once, false after settlement', async () => { + it('kill() requests managed-range termination: true once, false after settlement', async () => { const { bash } = await setup() const proc = bash.start(bash.resolve({ command: 'sleep 60' })) expect(proc.kill()).toBe(true) @@ -292,13 +293,72 @@ describe('LocalBashExecutor.start (background process handles)', () => { expect(proc.signal).toBe('SIGTERM') }) - it('a background spawn failure settles as killed with the error readable on stderr', async () => { + it('reports both unread stderr and an asynchronous provider rejection exactly once', async () => { + const { ctx, bash } = await setup() + const emptyReader: SubprocessOutputReader = { + readFrom: () => ({ text: '', nextOffset: 0, lossy: false }), + } + const stderrText = 'target stderr' + const stderrReader: SubprocessOutputReader = { + readFrom: offset => ({ + text: stderrText.slice(offset), + nextOffset: stderrText.length, + lossy: false, + }), + } + vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue({ + stdin: undefined, + stdout: undefined, + stderr: undefined, + collected: { stdout: emptyReader, stderr: stderrReader }, + done: Promise.reject(new Error('provider lost the direct outcome')), + terminate: vi.fn(), + waitForExit: async () => true, + } satisfies SubprocessHandle) + + const proc = bash.start(bash.resolve({ command: 'true' })) + await expect(proc.done).resolves.toBeUndefined() + expect(proc.status).toBe('killed') + const output = proc.readOutput().delta + expect(output).toContain('target stderr') + expect(output).toContain('subprocess failed before reporting an outcome:') + expect(output).not.toContain('spawn failed:') + expect(proc.readOutput().delta).toBe('') + }) + + it('settles an unprintable provider rejection instead of rejecting done', async () => { + const { ctx, bash } = await setup() + const emptyReader: SubprocessOutputReader = { + readFrom: () => ({ text: '', nextOffset: 0, lossy: false }), + } + const providerError = new Error('unprintable provider error') + Object.defineProperty(providerError, Symbol.toPrimitive, { + value: () => { throw new Error('provider formatting must not escape') }, + }) + vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue({ + stdin: undefined, + stdout: undefined, + stderr: undefined, + collected: { stdout: emptyReader, stderr: emptyReader }, + done: Promise.reject(providerError), + terminate: vi.fn(), + waitForExit: async () => true, + } satisfies SubprocessHandle) + + const proc = bash.start(bash.resolve({ command: 'true' })) + await expect(proc.done).resolves.toBeUndefined() + expect(proc.status).toBe('killed') + expect(proc.readOutput().delta).toContain('unprintable provider failure') + expect(proc.readOutput().delta).toBe('') + }) + + it('an asynchronous creation failure settles as killed with a stage-neutral note', async () => { const { bash } = await setup() const proc = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' })) // done resolves (never rejects) even though the process never ran. await expect(proc.done).resolves.toBeUndefined() expect(proc.status).toBe('killed') - expect(proc.readOutput().delta).toContain('spawn failed:') + expect(proc.readOutput().delta).toContain('subprocess failed before reporting an outcome:') }) }) diff --git a/packages/shell/bash-sandbox/README.i18n.yaml b/packages/shell/bash-sandbox/README.i18n.yaml index 9965d94905..4433dad796 100644 --- a/packages/shell/bash-sandbox/README.i18n.yaml +++ b/packages/shell/bash-sandbox/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/bash-sandbox/README.md -README.md: db0b280c595458873537479700a69120f2865994 -README.zh.md: db5019c9dc5b4e8f99caaad4374f6b83a7b4288f +README.md: 6d0e6aab3cd501c42be83e6da7a15ba0984fc114 +README.zh.md: 086fee202bdea39d3d80b6322ff1c0484b5d1ab9 diff --git a/packages/shell/bash-sandbox/README.md b/packages/shell/bash-sandbox/README.md index db0b280c59..6d0e6aab3c 100644 --- a/packages/shell/bash-sandbox/README.md +++ b/packages/shell/bash-sandbox/README.md @@ -61,7 +61,7 @@ A denied command is reported, not retried silently: the result carries `sandbox: ### Failures and recovery -If no runner can enforce a confined mode, the foreground call fails with `SANDBOX_UNAVAILABLE` and a background process records a runner-failure fact — never a silent unconfined run. A runner-attributable spawn failure carries the original spawn error as detail; other spawn rejections keep the local executor's ordinary command-start semantics. +If no runner can enforce a confined mode, the foreground call fails with `SANDBOX_UNAVAILABLE` and a background process records a runner-failure fact — never a silent unconfined run. A provider rejection is attributed to the confinement runner only when its `ENOENT`/`EACCES` path or syscall independently names `argv[0]`; otherwise it keeps the local executor's stage-neutral provider-failure semantics. ----- @@ -151,7 +151,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -If no runner can enforce a confined mode, the foreground call propagates the `SANDBOX_UNAVAILABLE` error from the sandbox seam. A runner-attributable spawn failure supplies the original spawn error as detail; a rejection without `ENOENT`/`EACCES` path or syscall evidence that names `argv[0]` remains an ordinary command-start error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection; the appended `Runner failure: ` is the authoritative diagnosis over the generic `SANDBOX_UNAVAILABLE` prefix. +If no runner can enforce a confined mode, the foreground call propagates the `SANDBOX_UNAVAILABLE` error from the sandbox seam. A provider rejection with `ENOENT`/`EACCES` path or syscall evidence that names `argv[0]` supplies the original error as runner-failure detail; another rejection remains a stage-neutral provider error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection; the appended `Runner failure: ` is the authoritative diagnosis over the generic `SANDBOX_UNAVAILABLE` prefix. #### Token effect diff --git a/packages/shell/bash-sandbox/README.zh.md b/packages/shell/bash-sandbox/README.zh.md index db5019c9dc..086fee202b 100644 --- a/packages/shell/bash-sandbox/README.zh.md +++ b/packages/shell/bash-sandbox/README.zh.md @@ -61,7 +61,7 @@ kind: "package-reference" ### 失败与恢复 -如果没有 runner 能强制执行受限模式，前台调用以 `SANDBOX_UNAVAILABLE` 失败，后台进程则记录 runner 失败事实——绝不会静默无隔离运行。可归因于 runner 的 spawn 失败以原始 spawn 错误作为详情；其他 spawn 拒绝保持本地执行器普通的命令启动语义。 +如果没有 runner 能强制执行受限模式，前台调用以 `SANDBOX_UNAVAILABLE` 失败，后台进程则记录 runner 失败事实——绝不会静默无隔离运行。只有当 provider rejection 的 `ENOENT`/`EACCES` 路径或 syscall 独立指向 `argv[0]` 时，才把它归因于 confinement runner；其他 rejection 保持本地执行器不声明阶段的 provider-failure 语义。 ----- @@ -151,7 +151,7 @@ kind: "package-reference" #### 模型看到的内容 -如果没有 runner 能强制执行受限模式，前台调用会传播来自 sandbox seam 的 `SANDBOX_UNAVAILABLE` 错误。可归因于 runner 的 spawn 失败以原始 spawn 错误作为详情；没有 `ENOENT`/`EACCES` 的 `path` 或 `syscall` 证据指明 `argv[0]` 的拒绝仍是普通的命令启动错误。已结算的 runner 失败以匹配到的致命 stderr 行作为详情，并保留原始 stderr 收集结果；追加的 `Runner failure: ` 是权威诊断，优先于通用的 `SANDBOX_UNAVAILABLE` 前缀。 +如果没有 runner 能强制执行受限模式，前台调用会传播来自 sandbox seam 的 `SANDBOX_UNAVAILABLE` 错误。带有 `ENOENT`/`EACCES` 路径或 syscall 证据并指向 `argv[0]` 的 provider rejection 会把原始错误作为 runner-failure 详情；其他 rejection 保持不声明阶段的 provider error。已结算的 runner 失败以匹配到的致命 stderr 行作为详情，并保留原始 stderr 收集结果；追加的 `Runner failure: ` 是权威诊断，优先于通用的 `SANDBOX_UNAVAILABLE` 前缀。 #### Token 影响 diff --git a/packages/shell/bash-sandbox/src/index.ts b/packages/shell/bash-sandbox/src/index.ts index be9c6647ec..de3d4368bc 100644 --- a/packages/shell/bash-sandbox/src/index.ts +++ b/packages/shell/bash-sandbox/src/index.ts @@ -1,10 +1,11 @@ /** * Sandbox-consuming bash executor. It wraps the exact local bash argv through * `ctx.sandbox`, inherits local process mechanics, and reports the selected - * mode, enforcement, and denial facts. Positive runner-launch evidence means - * the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while - * background processes carry `runnerFailed`; other spawn rejections retain - * local-executor semantics. The tool owns approval and passes a complete per-call policy. + * mode, enforcement, and denial facts. Positive runner-executable evidence + * identifies a broken confinement runner: foreground calls throw + * `SANDBOX_UNAVAILABLE`, while background processes carry `runnerFailed`; + * other provider rejections retain stage-neutral local-executor semantics. The + * tool owns approval and passes a complete per-call policy. * @module @deepseek-ai/dsh-bash-sandbox */ @@ -147,14 +148,15 @@ export class SandboxBashExecutor extends LocalBashExecutor { * Stamp per-process sandbox facts before `done` settles. Full-access processes * have no facts; signal deaths are not denials. */ - protected override onProcessDone(proc: ShellProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void { + protected override onProcessDone(proc: ShellProcess, stderr: string, providerRejected: boolean, providerError?: unknown): void { const facts = this.processFacts.get(proc) if (facts !== undefined) { this.processFacts.delete(proc) - // A rejected spawn never started the confined launch. Otherwise runner - // failure outranks denial because its diagnostics may contain denial terms. - const runnerFailed = spawnFailed - ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir) + // A provider rejection exposes no public failure stage. Attribute it to + // the confinement runner only when the error independently names argv[0]. + // Otherwise settled runner failure outranks denial-like diagnostics. + const runnerFailed = providerRejected + ? isRunnerSpawnFailure(providerError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== undefined proc.sandbox = { mode: facts.mode, @@ -163,7 +165,7 @@ export class SandboxBashExecutor extends LocalBashExecutor { ...(runnerFailed ? { runnerFailed } : {}), } } - super.onProcessDone(proc, stderr, spawnFailed, spawnError) + super.onProcessDone(proc, stderr, providerRejected, providerError) } /** diff --git a/packages/shell/bash-sandbox/tests/partial-landlock.spec.ts b/packages/shell/bash-sandbox/tests/partial-landlock.spec.ts index d665bb4eb5..d2355c7dad 100644 --- a/packages/shell/bash-sandbox/tests/partial-landlock.spec.ts +++ b/packages/shell/bash-sandbox/tests/partial-landlock.spec.ts @@ -100,7 +100,7 @@ describe('partial Landlock runner-failure classification', () => { const task = bash.start(bash.resolve({ command: 'true' })) await task.done expect(task.status).toBe('killed') - expect(task.readOutput().delta).toContain(`spawn failed: Error: spawn ${runner}`) + expect(task.readOutput().delta).toContain(`subprocess failed before reporting an outcome: Error: spawn ${runner}`) expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, @@ -134,7 +134,7 @@ describe('partial Landlock runner-failure classification', () => { const task = bash.start(bash.resolve(request)) await task.done expect(task.status).toBe('killed') - expect(task.readOutput().delta).toContain(`spawn failed: Error: spawn ${runner} ENOENT`) + expect(task.readOutput().delta).toContain(`subprocess failed before reporting an outcome: Error: spawn ${runner} ENOENT`) expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, @@ -188,7 +188,7 @@ describe('partial Landlock runner-failure classification', () => { const output = background.readOutput().delta expect(output.startsWith('[stderr]\n')).toBe(true) expect(output.length).toBeGreaterThan('[stderr]\n'.length) - expect(output).not.toContain('spawn failed:') + expect(output).not.toContain('subprocess failed before reporting an outcome:') } const accounting = (bash as unknown as { processFacts: Map }).processFacts diff --git a/packages/shell/bash-sandbox/tests/sandbox.spec.ts b/packages/shell/bash-sandbox/tests/sandbox.spec.ts index 21d2dfceaa..f6a57b541c 100644 --- a/packages/shell/bash-sandbox/tests/sandbox.spec.ts +++ b/packages/shell/bash-sandbox/tests/sandbox.spec.ts @@ -556,7 +556,7 @@ describe('background sandbox facts', () => { await task.done expect(task.status).toBe('killed') - expect(task.readOutput().delta).toContain('spawn failed:') + expect(task.readOutput().delta).toContain('subprocess failed before reporting an outcome:') expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, @@ -569,18 +569,17 @@ describe('background sandbox facts', () => { } }) - it('does not invent runner evidence when a spawn rejection has no structured reason', async () => { + it('does not invent runner evidence when a provider rejection has no structured reason', async () => { const { ctx, bash } = await setup() const emptyReader: SubprocessOutputReader = { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }), } vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue({ - pid: -1, stdin: undefined, stdout: undefined, stderr: undefined, collected: { stdout: emptyReader, stderr: emptyReader }, - // Arbitrary subprocess providers can reject without a value; that edge is the point of this test. + // Arbitrary subprocess providers can reject without a value or public stage. // oxlint-disable-next-line typescript/prefer-promise-reject-errors done: Promise.reject(undefined), terminate: vi.fn(), @@ -590,7 +589,7 @@ describe('background sandbox facts', () => { const task = bash.start(bash.resolve({ command: 'true' })) await task.done - expect(task.readOutput().delta).toContain('spawn failed: undefined') + expect(task.readOutput().delta).toContain('subprocess failed before reporting an outcome: undefined') expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, diff --git a/packages/shell/pwsh-local/README.i18n.yaml b/packages/shell/pwsh-local/README.i18n.yaml index 39ed34f989..2737493806 100644 --- a/packages/shell/pwsh-local/README.i18n.yaml +++ b/packages/shell/pwsh-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/pwsh-local/README.md -README.md: d9ad46b84f78a2a8ed373420039646e710b79710 -README.zh.md: ef4f7e376dbad2ad1878b45dae156b6afb312783 +README.md: 1d6872ec6b342f415b1632f87be5a485c4dfa270 +README.zh.md: 2594ecc1623fec9ea8022f92d1c38941f643d979 diff --git a/packages/shell/pwsh-local/README.md b/packages/shell/pwsh-local/README.md index d9ad46b84f..1d6872ec6b 100644 --- a/packages/shell/pwsh-local/README.md +++ b/packages/shell/pwsh-local/README.md @@ -66,7 +66,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### Background processes -Call `start` to run a command in the background; it returns a handle immediately and no timeout applies. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` stops the process tree; `done` settles when the process closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with. +Call `start` to run a command in the background; it returns a handle immediately and no timeout applies. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` terminates the provider-managed range; `done` settles when the direct command closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with. ### Adjusting budgets at runtime @@ -85,7 +85,7 @@ This section explains the design of the executor and points at the code that rea ### Design concept -The executor is the PowerShell Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything pwsh-shaped — executable resolution, command defaulting and caps, deadline fusion and cause classification, UTF-8 output pinning, the model-friendly terminal environment, and the background read merge — while process-tree mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) belong to the subprocess service. Every call spawns a fresh non-interactive `pwsh -Command` with `-NoLogo -NoProfile -NonInteractive`, so commands are deterministic and profile state never leaks between calls. +The executor is the PowerShell Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything pwsh-shaped — executable resolution, command defaulting and caps, deadline fusion and cause classification, UTF-8 output pinning, the model-friendly terminal environment, and the background read merge — while managed-range mechanics (bounded spill-backed output, credential scrub, termination escalation, quiescence, and disposal) belong to the subprocess service. Every call spawns a fresh non-interactive `pwsh -Command` with `-NoLogo -NoProfile -NonInteractive`, so commands are deterministic and profile state never leaks between calls. ### Source map @@ -143,7 +143,7 @@ These limits define when this executor is a poor fit. They are current package c - **Unconfined by itself** — commands run with the harness process's authority; deployments needing confinement compose a sandboxing executor or policy instead. - **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`. - **The command string is PowerShell text** — the `-Command` domain has no shell-quoting layer, but a model-facing command is parsed by PowerShell itself, so PowerShell syntax errors are command failures, not launch failures. -- **A background spawn-failure note is single-delivery** — the subprocess service buffers no output for a process that never ran, so the executor injects `spawn failed: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it. +- **A background provider-failure note is single-delivery** — `SubprocessHandle.done` can reject before or after target execution begins, so the executor injects the stage-neutral `subprocess failed before reporting an outcome: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it. - **Windows termination reports no signal** — a force-killed process settles as exit 1 with `signal: null`, so signal-based status classification does not apply on Windows; `kill()`-initiated stops still stamp `killed` directly. - **The encoding preamble precedes the command** — PowerShell requires `param(...)`, `#requires`, and `using` statements at the very top of a script, so a command whose first statement is one of those cannot run under the UTF-8 output preamble; wrap a `param(...)` script in `& { … }`, and run `using`/`#requires` scripts from a file instead. - **Non-ASCII stdin under Windows PowerShell 5.1 may be mis-decoded** — the preamble pins output encoding only; `[Console]::InputEncoding` stays at the host default because setting it under redirected stdin throws; pwsh 7 defaults to UTF-8 and is unaffected. diff --git a/packages/shell/pwsh-local/README.zh.md b/packages/shell/pwsh-local/README.zh.md index ef4f7e376d..2594ecc162 100644 --- a/packages/shell/pwsh-local/README.zh.md +++ b/packages/shell/pwsh-local/README.zh.md @@ -66,7 +66,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### 后台进程 -调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 停止进程树；`done` 在进程关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 +调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止由提供方管理的 range；`done` 在 direct command 关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 ### 运行时调整预算 @@ -85,7 +85,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) ### 设计概念 -本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 PowerShell Service Provider：它负责所有 pwsh 层职责——可执行文件解析、命令默认化与上限、deadline 融合与原因分类、UTF-8 输出固定、面向模型的终端环境，以及后台读取合并——而进程树机制（有界 spill 输出、凭据清除、终止升级、dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非交互 `pwsh -Command`，并带 `-NoLogo -NoProfile -NonInteractive`，因此命令是确定性的，profile 状态绝不会在调用之间泄漏。 +本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 PowerShell Service Provider：它负责所有 pwsh 层职责——可执行文件解析、命令默认化与上限、deadline 融合与原因分类、UTF-8 输出固定、面向模型的终端环境，以及后台读取合并——而 managed-range 机制（有界 spill 输出、凭据清除、终止升级、完全停稳与 dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非交互 `pwsh -Command`，并带 `-NoLogo -NoProfile -NonInteractive`，因此命令是确定性的，profile 状态绝不会在调用之间泄漏。 ### 源码地图 @@ -143,7 +143,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs) - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合沙箱执行器或策略。 - **没有持久 shell 或 PTY**——每次调用都启动全新的 `pwsh -Command`。 - **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。 -- **后台 spawn 失败提示只交付一次**——subprocess 服务不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。 +- **后台 provider failure 提示只交付一次**——`SubprocessHandle.done` 可能在 target 开始执行前或后 reject，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。 - **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结算，因此基于信号的状态分类在 Windows 上不适用；`kill()` 发起的停止仍会直接标记为 `killed`。 - **编码 preamble 位于命令之前**——PowerShell 要求 `param(...)`、`#requires` 与 `using` 语句位于脚本最顶部，因此以其中一种开头的命令无法在 UTF-8 输出 preamble 下运行；`param(...)` 脚本请包进 `& { … }`，`using`/`#requires` 脚本请改从文件运行。 - **Windows PowerShell 5.1 下的非 ASCII stdin 可能被错误解码**——preamble 只固定输出编码；`[Console]::InputEncoding` 保持主机默认，因为在重定向 stdin 下设置它会抛出异常；pwsh 7 默认 UTF-8，不受影响。 diff --git a/packages/shell/pwsh-local/src/index.ts b/packages/shell/pwsh-local/src/index.ts index 93133b37af..99d7d1564b 100644 --- a/packages/shell/pwsh-local/src/index.ts +++ b/packages/shell/pwsh-local/src/index.ts @@ -122,7 +122,7 @@ export function assertServiceablePwshConfig(config: Config): void { /** * Local PowerShell executor over `ctx.subprocess`. Bounded output, spill - * files, and process-tree termination are the subprocess service's mechanics; + * files, and managed-range termination are the subprocess service's mechanics; * this executor supplies their configured budgets per spawn. */ export class PwshLocalExecutor extends ShellExecutor { @@ -288,12 +288,12 @@ export class PwshLocalExecutor extends ShellExecutor { const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal, argv)) const collected = PwshLocalExecutor.collected(running) - // A spawn failure produces no process output, so the subprocess service has nothing - // to buffer; the note is delivered exactly once through the read path. - let spawnFailureNote: string | undefined - const consumeSpawnFailure = (): string => { - const note = spawnFailureNote ?? '' - spawnFailureNote = undefined + // A provider rejection has no direct outcome to display; its stage is not + // public, so a neutral note is delivered once through the read path. + let providerFailureNote: string | undefined + const consumeProviderFailure = (): string => { + const note = providerFailureNote ?? '' + providerFailureNote = undefined return note } @@ -312,10 +312,16 @@ export class PwshLocalExecutor extends ShellExecutor { proc.signal = outcome.signal this.onProcessDone(proc, collected.stderr.readFrom(0).text, false) }, (error: unknown) => { - // Background spawn failures settle as killed and surface through the read path. + // Background provider failures settle as killed and surface through the read path. proc.status = 'killed' - spawnFailureNote = `spawn failed: ${String(error)}` - this.onProcessDone(proc, spawnFailureNote, true, error) + let detail = 'unprintable provider failure' + try { + detail = String(error) + } catch { + // Provider-owned rejection values cannot make ShellProcess.done reject. + } + providerFailureNote = `subprocess failed before reporting an outcome: ${detail}` + this.onProcessDone(proc, providerFailureNote, true, error) }), readOutput: (): ShellProcessRead => { const out = collected.stdout.readFrom(stdoutOffset) @@ -323,9 +329,10 @@ export class PwshLocalExecutor extends ShellExecutor { stdoutOffset = out.nextOffset stderrOffset = err.nextOffset - // A failed spawn never produced process output, so the note and real - // stderr text are mutually exclusive. - const errText = err.text.length > 0 ? err.text : consumeSpawnFailure() + const providerFailure = consumeProviderFailure() + const failureSeparator = err.text.length > 0 && !err.text.endsWith('\n') ? '\n' : '' + const errText = err.text + + (providerFailure.length > 0 ? `${failureSeparator}${providerFailure}` : '') // Single newline between sections: stdout chunks usually end with one // already; add it only when missing. const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : '' @@ -355,10 +362,10 @@ export class PwshLocalExecutor extends ShellExecutor { * pwsh-confining consumer is `@deepseek-ai/dsh-pwsh-sandbox`. * @param _proc - the settled process handle. * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification. - * @param _spawnFailed - whether the spawn rejected before any process existed. - * @param _spawnError - the spawn rejection, when `_spawnFailed`. + * @param _providerRejected - whether the subprocess promise rejected without a direct outcome. + * @param _providerError - the provider rejection reason, which may itself be undefined. */ - protected onProcessDone(_proc: ShellProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void {} + protected onProcessDone(_proc: ShellProcess, _stderr: string, _providerRejected: boolean, _providerError?: unknown): void {} } /* jscpd:ignore-end */ diff --git a/packages/shell/pwsh-local/tests/executor.spec.ts b/packages/shell/pwsh-local/tests/executor.spec.ts index 319c588ac5..f46fd1f4a2 100644 --- a/packages/shell/pwsh-local/tests/executor.spec.ts +++ b/packages/shell/pwsh-local/tests/executor.spec.ts @@ -18,7 +18,7 @@ import { Context } from '@deepseek-ai/cordis' import { PwshLocalExecutor, ENCODING_PREAMBLE, candidatePwshPaths, resolvePwshPath } from '@deepseek-ai/dsh-pwsh-local' import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import SubprocessRuntime from '@deepseek-ai/dsh-subprocess' -import type { SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import type { SubprocessHandle, SubprocessOutcome, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' import type { ShellProcess } from '@deepseek-ai/dsh-shell' @@ -168,20 +168,28 @@ describe('spawn construction (pure, every platform)', () => { /** A subprocess service that records spawn specs and settles instantly. */ class CapturingSubprocessRuntime extends SubprocessRuntime { specs: SubprocessSpawnSpec[] = [] + done: Promise = Promise.resolve({ exitCode: 0, signal: null }) + stderrText = '' override async resolveExecutable(command: string): Promise { return command } override spawnTerminal(): Promise { throw new Error('pwsh spawns pipes, never terminals') } - private readonly reader: SubprocessOutputReader = { + private readonly stdoutReader: SubprocessOutputReader = { readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }), } + private readonly stderrReader: SubprocessOutputReader = { + readFrom: offset => ({ + text: this.stderrText.slice(offset), + lossy: false, + nextOffset: this.stderrText.length, + }), + } override spawn(spec: SubprocessSpawnSpec): SubprocessHandle { this.specs.push(spec) return { - pid: -1, stdin: undefined, stdout: undefined, stderr: undefined, - collected: { stdout: this.reader, stderr: this.reader }, - done: Promise.resolve({ exitCode: 0, signal: null }), + collected: { stdout: this.stdoutReader, stderr: this.stderrReader }, + done: this.done, terminate: () => {}, waitForExit: async () => true, } @@ -200,6 +208,67 @@ describe('spawn construction (pure, every platform)', () => { expect(ENCODING_PREAMBLE).toContain('[Console]::OutputEncoding') expect(ENCODING_PREAMBLE).toContain('$OutputEncoding') }) + + it('reports both unread stderr and an asynchronous provider rejection exactly once', async () => { + const ctx = new Context() + const subprocess = new CapturingSubprocessRuntime(ctx) + await ctx.plugin(PwshLocalExecutor) + subprocess.stderrText = 'target stderr' + subprocess.done = Promise.reject(new Error('provider lost the direct outcome')) + + const proc = ctx.shell.start(ctx.shell.resolve({ command: 'Write-Output maybe-ran' })) + await expect(proc.done).resolves.toBeUndefined() + expect(proc.status).toBe('killed') + const output = proc.readOutput().delta + expect(output).toContain('target stderr') + expect(output).toContain('subprocess failed before reporting an outcome:') + expect(output).not.toContain('spawn failed:') + expect(proc.readOutput().delta).toBe('') + }) + + it('settles an unprintable provider rejection instead of rejecting done', async () => { + const ctx = new Context() + const subprocess = new CapturingSubprocessRuntime(ctx) + await ctx.plugin(PwshLocalExecutor) + const providerError = new Error('unprintable provider error') + Object.defineProperty(providerError, Symbol.toPrimitive, { + value: () => { throw new Error('provider formatting must not escape') }, + }) + subprocess.done = Promise.reject(providerError) + + const proc = ctx.shell.start(ctx.shell.resolve({ command: 'Write-Output maybe-ran' })) + await expect(proc.done).resolves.toBeUndefined() + expect(proc.status).toBe('killed') + expect(proc.readOutput().delta).toContain('unprintable provider failure') + expect(proc.readOutput().delta).toBe('') + }) + + it('preserves an explicit kill stamp and maps an aborted direct outcome to killed', async () => { + const ctx = new Context() + const subprocess = new CapturingSubprocessRuntime(ctx) + await ctx.plugin(PwshLocalExecutor) + + const killedOutcome = Promise.withResolvers() + subprocess.done = killedOutcome.promise + const killed = ctx.shell.start(ctx.shell.resolve({ command: 'Write-Output maybe-ran' })) + expect(killed.kill()).toBe(true) + killedOutcome.resolve({ exitCode: 0, signal: null }) + await killed.done + expect(killed.status).toBe('killed') + expect(killed.exitCode).toBe(0) + + const abortedOutcome = Promise.withResolvers() + subprocess.done = abortedOutcome.promise + const controller = new AbortController() + const aborted = ctx.shell.start(ctx.shell.resolve({ + command: 'Write-Output maybe-ran', + signal: controller.signal, + })) + controller.abort() + abortedOutcome.resolve({ exitCode: 0, signal: null }) + await aborted.done + expect(aborted.status).toBe('killed') + }) }) describe.skipIf(!hasPwsh)('PwshLocalExecutor.run', () => { @@ -414,7 +483,7 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)' expect(lf(read.delta)).toContain('[stderr]') }) - it('kill() terminates the process tree: true once, false after settlement', async () => { + it('kill() requests managed-range termination: true once, false after settlement', async () => { const { bash } = await setup() const proc = bash.start(bash.resolve({ command: 'Start-Sleep -Seconds 60' })) expect(proc.kill()).toBe(true) @@ -450,13 +519,13 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)' expect(['SIGTERM', 'SIGKILL']).toContain(proc.signal) }) - it('a background spawn failure settles as killed with the error readable on stderr', async () => { + it('an asynchronous creation failure settles as killed with a stage-neutral note', async () => { const { bash } = await setup() const proc = bash.start(bash.resolve({ command: 'Write-Output ok', workdir: '/nonexistent-dsh' })) // done resolves (never rejects) even though the process never ran. await expect(proc.done).resolves.toBeUndefined() expect(proc.status).toBe('killed') - expect(proc.readOutput().delta).toContain('spawn failed:') + expect(proc.readOutput().delta).toContain('subprocess failed before reporting an outcome:') }) }) diff --git a/packages/shell/pwsh-sandbox/README.i18n.yaml b/packages/shell/pwsh-sandbox/README.i18n.yaml index 02b5593e61..ad6cac6d5c 100644 --- a/packages/shell/pwsh-sandbox/README.i18n.yaml +++ b/packages/shell/pwsh-sandbox/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/pwsh-sandbox/README.md -README.md: 18b4a8bcbd48523fcac29c1eacaea6cf8aee7b82 -README.zh.md: 0755dd96b1bb756b6e860463cd5641b4874c8052 +README.md: 101560e34f1205cdddd0a3177616ca3526be1e44 +README.zh.md: d672878ef015989568a807a65aac382b77eafb3c diff --git a/packages/shell/pwsh-sandbox/README.md b/packages/shell/pwsh-sandbox/README.md index 18b4a8bcbd..101560e34f 100644 --- a/packages/shell/pwsh-sandbox/README.md +++ b/packages/shell/pwsh-sandbox/README.md @@ -61,7 +61,7 @@ A denied command is reported as a fact: the result carries `sandbox: { mode, den ### Failures and recovery -If no runner can enforce a confined mode, the foreground call fails with `SANDBOX_UNAVAILABLE` and a background process records a runner-failure fact — never a silent unconfined run. A runner-attributable spawn failure carries the original spawn error as detail; other spawn rejections keep the local executor's ordinary command-start semantics. +If no runner can enforce a confined mode, the foreground call fails with `SANDBOX_UNAVAILABLE` and a background process records a runner-failure fact — never a silent unconfined run. A provider rejection is attributed to the confinement runner only when its `ENOENT`/`EACCES` path or syscall independently names `argv[0]`; otherwise it keeps the local executor's stage-neutral provider-failure semantics. ----- diff --git a/packages/shell/pwsh-sandbox/README.zh.md b/packages/shell/pwsh-sandbox/README.zh.md index 0755dd96b1..d672878ef0 100644 --- a/packages/shell/pwsh-sandbox/README.zh.md +++ b/packages/shell/pwsh-sandbox/README.zh.md @@ -61,7 +61,7 @@ kind: "package-reference" ### 失败与恢复 -如果没有 runner 能强制执行受限模式，前台调用以 `SANDBOX_UNAVAILABLE` 失败，后台进程则记录 runner 失败事实——绝不会静默无隔离运行。可归因于 runner 的 spawn 失败以原始 spawn 错误作为详情；其他 spawn 拒绝保持本地执行器普通的命令启动语义。 +如果没有 runner 能强制执行受限模式，前台调用以 `SANDBOX_UNAVAILABLE` 失败，后台进程则记录 runner 失败事实——绝不会静默无隔离运行。只有当 provider rejection 的 `ENOENT`/`EACCES` 路径或 syscall 独立指向 `argv[0]` 时，才把它归因于 confinement runner；其他 rejection 保持本地执行器不声明阶段的 provider-failure 语义。 ----- diff --git a/packages/shell/pwsh-sandbox/src/index.ts b/packages/shell/pwsh-sandbox/src/index.ts index 66bc73bcf0..2e9a03557a 100644 --- a/packages/shell/pwsh-sandbox/src/index.ts +++ b/packages/shell/pwsh-sandbox/src/index.ts @@ -3,12 +3,12 @@ * `@deepseek-ai/dsh-bash-sandbox`. It wraps the exact local pwsh argv through * `ctx.sandbox` (which on Windows resolves to the ACL restricted-token runner * chain), inherits local process mechanics, and reports the selected mode, - * enforcement, and denial facts. Positive runner-launch evidence means the - * command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while - * background processes carry `runnerFailed`; other spawn rejections retain - * local-executor semantics. The tool layer owns the escalation approval flow - * through `ctx.approval`; this executor reports the sandbox facts the tool - * renders. + * enforcement, and denial facts. Positive runner-executable evidence + * identifies a broken confinement runner: foreground calls throw + * `SANDBOX_UNAVAILABLE`, while background processes carry `runnerFailed`; + * other provider rejections retain stage-neutral local-executor semantics. The + * tool layer owns the escalation approval flow through `ctx.approval`; this + * executor reports the sandbox facts the tool renders. * @module @deepseek-ai/dsh-pwsh-sandbox */ @@ -153,14 +153,15 @@ export class SandboxPwshExecutor extends PwshLocalExecutor { * Stamp per-process sandbox facts before `done` settles. Full-access * processes have no facts; signal deaths are not denials. */ - protected override onProcessDone(proc: ShellProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void { + protected override onProcessDone(proc: ShellProcess, stderr: string, providerRejected: boolean, providerError?: unknown): void { const facts = this.processFacts.get(proc) if (facts !== undefined) { this.processFacts.delete(proc) - // A rejected spawn never started the confined launch. Otherwise runner - // failure outranks denial because its diagnostics may contain denial terms. - const runnerFailed = spawnFailed - ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir) + // A provider rejection exposes no public failure stage. Attribute it to + // the confinement runner only when the error independently names argv[0]. + // Otherwise settled runner failure outranks denial-like diagnostics. + const runnerFailed = providerRejected + ? isRunnerSpawnFailure(providerError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== undefined proc.sandbox = { mode: facts.mode, @@ -169,7 +170,7 @@ export class SandboxPwshExecutor extends PwshLocalExecutor { ...(runnerFailed ? { runnerFailed } : {}), } } - super.onProcessDone(proc, stderr, spawnFailed, spawnError) + super.onProcessDone(proc, stderr, providerRejected, providerError) } /** diff --git a/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts b/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts index 258e3d950f..166e5ed042 100644 --- a/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts +++ b/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts @@ -300,7 +300,7 @@ describe.skipIf(!pwshAvailable())('SandboxPwshExecutor', () => { expect(denied.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) }, 30_000) - it('background spawn rejections settle as runnerFailed facts', async () => { + it('background provider rejections with runner provenance settle as runnerFailed facts', async () => { const { executor } = await setup(() => ({ argv: ['definitely-not-a-real-runner', '--', 'pwsh'], enforcement: 'full', @@ -312,7 +312,7 @@ describe.skipIf(!pwshAvailable())('SandboxPwshExecutor', () => { expect(proc.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true }) // The failure note surfaces through the read path. const read = proc.readOutput() - expect(read.delta).toContain('spawn failed') + expect(read.delta).toContain('subprocess failed before reporting an outcome') }, 30_000) it('danger-full-access background runs bypass confine and carry no facts', async () => { diff --git a/packages/shell/shell/README.i18n.yaml b/packages/shell/shell/README.i18n.yaml index 68001f5d8e..8889ff0357 100644 --- a/packages/shell/shell/README.i18n.yaml +++ b/packages/shell/shell/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/shell/README.md -README.md: dd3eeb45af432e6fdbb9a0aa688d8a5c3c58bbb1 -README.zh.md: 8767aad9795494c6a996c7063778b1a816362e16 +README.md: a606050c30d07024ff972652b87a223f91767f58 +README.zh.md: 9ae7cd5f858d6e7deaed5bf08c873c6e1aecdaae diff --git a/packages/shell/shell/README.md b/packages/shell/shell/README.md index dd3eeb45af..a606050c30 100644 --- a/packages/shell/shell/README.md +++ b/packages/shell/shell/README.md @@ -38,7 +38,7 @@ console.log(result.exitCode, result.stdout.text) ### Background processes -Call `start` with a resolved spec to launch a background process; it returns a handle immediately and no timeout applies. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Kill the process group with `kill()` (returns `false` once it has finished) and await `done` for settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle. +Call `start` with a resolved spec to launch a background process; it returns a handle immediately and no timeout applies. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Terminate the provider-managed range with `kill()` (returns `false` once the direct command has finished) and await `done` for direct-command settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle. ### Requests and resolved specs @@ -91,7 +91,7 @@ The package is one role of a standard capability seam: the Service Definition th ### Background lifecycle and ownership -A background process belongs to the subprocess service, not to the executor: it survives an executor-only reload and is killed and joined when the composition tears down. Implementations must honor the seam's semantics — `run` rejects only for infrastructure failures; `start` returns immediately with no timeout and its `done` never rejects (spawn failures settle as `killed` with the error on stderr); `readOutput` is consuming and lossy reads report spill files. +A background process belongs to the subprocess service, not to the executor: it survives an executor-only reload and is killed and joined when the composition tears down. Implementations must honor the seam's semantics — `run` rejects only for infrastructure failures; `start` returns immediately with no timeout and its `done` never rejects (a subprocess provider rejection settles as `killed` with a stage-neutral error on stderr); `readOutput` is consuming and lossy reads report spill files. diff --git a/packages/shell/shell/README.zh.md b/packages/shell/shell/README.zh.md index 8767aad979..9ae7cd5f85 100644 --- a/packages/shell/shell/README.zh.md +++ b/packages/shell/shell/README.zh.md @@ -38,7 +38,7 @@ console.log(result.exitCode, result.stdout.text) ### 后台进程 -用已解析的 spec 调用 `start` 即可启动后台进程；它会立即返回句柄，且不应用任何超时。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止进程组（进程结束后返回 `false`），并等待 `done` 结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 +用已解析的 spec 调用 `start` 即可启动后台进程；它会立即返回句柄，且不应用任何超时。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止提供方管理的 range（直接命令结束后返回 `false`），并等待 `done` 完成直接命令结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。 ### 请求与已解析 spec @@ -91,7 +91,7 @@ seam 本身不是执行器：每个组合只挂载一个提供方，工具即可 ### 后台生命周期与归属 -后台进程属于 subprocess 服务而非执行器：它能在仅重载执行器后存活，并在组合拆解时被终止并 join。实现必须遵守 seam 的语义——`run` 只在基础设施失败时 reject；`start` 立即返回且不设超时，其 `done` 绝不 reject（spawn 失败以 `killed` 结算，错误进入 stderr）；`readOutput` 是消费式的，有损读取会报告 spill 文件。 +后台进程属于 subprocess 服务而非执行器：它能在仅重载执行器后存活，并在组合拆解时被终止并 join。实现必须遵守 seam 的语义——`run` 只在基础设施失败时 reject；`start` 立即返回且不设超时，其 `done` 绝不 reject（subprocess provider rejection 以 `killed` 结算，并把不声明阶段的错误写入 stderr）；`readOutput` 是消费式的，有损读取会报告 spill 文件。 diff --git a/packages/shell/shell/src/types.ts b/packages/shell/shell/src/types.ts index 21fea2d791..8a17c3880b 100644 --- a/packages/shell/shell/src/types.ts +++ b/packages/shell/shell/src/types.ts @@ -165,7 +165,10 @@ export interface ShellProcess { exitCode: number | null /** Terminating signal name, when signal-killed. */ signal: NodeJS.Signals | null - /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */ + /** + * Resolves when the underlying process settles (never rejects — provider + * rejection settles as `killed` with a stage-neutral error on stderr). + */ readonly done: Promise /** Sandbox facts, stamped once a confined process settles. */ sandbox?: ShellSandboxInfo @@ -176,7 +179,7 @@ export interface ShellProcess { */ readOutput(): ShellProcessRead /** - * Kill the process group. Returns false when it had already finished + * Terminate the provider-managed range. Returns false when it had already finished * (no-op); idempotent. */ kill(): boolean diff --git a/packages/subagent/subagent-acp/README.i18n.yaml b/packages/subagent/subagent-acp/README.i18n.yaml index 7237db63df..4a42e3e391 100644 --- a/packages/subagent/subagent-acp/README.i18n.yaml +++ b/packages/subagent/subagent-acp/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subagent/subagent-acp/README.md -README.md: 2d929738de2f761cbc597fae6cb52f7d44d83536 -README.zh.md: d67e174a44497148d08ef54d13f17df934db2018 +README.md: 62b20bd1b35a80682dbacbe1e9ff4c0b1b7c3d63 +README.zh.md: fa1b1c8897cee115de25240fa543ac0d496d8f22 diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md index 2d929738de..62b20bd1b3 100644 --- a/packages/subagent/subagent-acp/README.md +++ b/packages/subagent/subagent-acp/README.md @@ -67,7 +67,7 @@ A successful run returns the child's final streamed assistant text as the result ### Failure and recovery -A spawn, initialization, or new-session failure rejects before publication, ordinarily after the child process is reaped. If cleanup also fails, the rejection preserves ordered safe startup and teardown facts without claiming whole-tree quiescence. Non-cancellation errors expose only fixed provider, stage, and category facts; the original failure stays on the internal cause chain and in Host diagnostics. After publication, a prompt, transport, or early-process failure resolves as `error` with a safe diagnostic, while local cancellation resolves as `aborted` without failure detail. +A spawn, initialization, or new-session failure rejects before publication, ordinarily after the managed range is proven quiescent. If cleanup also fails, the rejection preserves ordered safe startup and teardown facts without claiming whole-range quiescence. Non-cancellation errors expose only fixed provider, stage, and category facts; the original failure stays on the internal cause chain and in Host diagnostics. After publication, a prompt, transport, or early-process failure resolves as `error` with a safe diagnostic, while local cancellation resolves as `aborted` without failure detail. ### Safe diagnostics @@ -91,7 +91,7 @@ This section explains how the backend drives a child over ACP and where the obse ### Start and ownership flow -A start resolves the child's working directory (the configured `cwd` override, else the parent session's cwd), spawns the command through the subprocess seam, performs the ACP `initialize` and `newSession` handshake, and only then publishes the run. Fulfillment means a remote session is ready and ownership has transferred to the caller. Disposal is idempotent: it closes stdin and waits a configured grace for cooperative quiescence, then escalates through SIGTERM to SIGKILL and awaits whole-tree exit. Cleanup failures remain observable as ordered safe facts and never claim quiescence. +A start resolves the child's working directory (the configured `cwd` override, else the parent session's cwd), spawns the command through the subprocess seam, performs the ACP `initialize` and `newSession` handshake, and only then publishes the run. Fulfillment means a remote session is ready and ownership has transferred to the caller. Disposal is idempotent: it closes stdin and waits a configured grace for cooperative quiescence, then escalates through SIGTERM to SIGKILL and awaits whole-range exit. Cleanup failures remain observable as ordered safe facts and never claim quiescence. ### Stop-reason mapping diff --git a/packages/subagent/subagent-acp/README.zh.md b/packages/subagent/subagent-acp/README.zh.md index d67e174a44..fa1b1c8897 100644 --- a/packages/subagent/subagent-acp/README.zh.md +++ b/packages/subagent/subagent-acp/README.zh.md @@ -67,7 +67,7 @@ DeepSeek Harness 子进程使用产品启动器和一个显式的绝对路径 `D ### 失败与恢复 -spawn、初始化或新建会话失败会在发布前拒绝，通常先等待子进程被回收。如果清理也失败，拒绝会保留有序、安全的启动与拆卸事实，但不会声称整棵进程树已经停稳。非取消错误只暴露固定的提供方、阶段与类别事实；原始失败保留在内部 cause 链与 Host 诊断中。发布后，提示词、传输或进程提前退出会以携带安全诊断的 `error` 结算；本地取消则以不带失败详情的 `aborted` 结算。 +spawn、初始化或新建会话失败会在发布前拒绝，通常先证明 managed range 已经完全停稳。如果清理也失败，拒绝会保留有序、安全的启动与拆卸事实，但不会声称整个 range 已经停稳。非取消错误只暴露固定的提供方、阶段与类别事实；原始失败保留在内部 cause 链与 Host 诊断中。发布后，提示词、传输或进程提前退出会以携带安全诊断的 `error` 结算；本地取消则以不带失败详情的 `aborted` 结算。 ### 安全诊断 @@ -91,7 +91,7 @@ spawn、初始化或新建会话失败会在发布前拒绝，通常先等待子 ### 启动与所有权流程 -一次启动先解析子 agent 的工作目录（配置的 `cwd` 覆盖值，否则取父会话 cwd），经子进程 seam spawn 命令，完成 ACP `initialize` 与 `newSession` 握手，然后才发布运行。兑现意味着远程会话已就绪、所有权已转移给调用方。dispose（资源释放）是幂等的：先关闭 stdin 并按配置的宽限等待协作式完全停稳，再经 SIGTERM 升级到 SIGKILL，并等待整棵进程树退出。清理失败会作为有序的安全事实保持可观察，且绝不声称已经完全停稳。 +一次启动先解析子 agent 的工作目录（配置的 `cwd` 覆盖值，否则取父会话 cwd），经子进程 seam spawn 命令，完成 ACP `initialize` 与 `newSession` 握手，然后才发布运行。兑现意味着远程会话已就绪、所有权已转移给调用方。dispose（资源释放）是幂等的：先关闭 stdin 并按配置的宽限等待协作式完全停稳，再经 SIGTERM 升级到 SIGKILL，并等待整个 managed range 退出。清理失败会作为有序的安全事实保持可观察，且绝不声称已经完全停稳。 ### 停止原因映射 diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts index 015504000e..3164c5d634 100644 --- a/packages/subagent/subagent-acp/src/run.ts +++ b/packages/subagent/subagent-acp/src/run.ts @@ -67,7 +67,7 @@ export interface AcpRunSpec { disposeGraceMs: number /** * Spawn function from the subprocess seam (`ctx.subprocess.spawn`), so the - * child rides the shared scrub, tree-scoped teardown, and service-owned + * child rides the shared scrub, managed-range teardown, and service-owned * lifetime instead of a package-local child_process path. */ spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle @@ -170,8 +170,8 @@ function permissionRequestKind(kind: ToolKind | null | undefined): ToolKind | 'u : 'unknown' } -/** Bounded whole-tree exit wait: polls the handle's tree liveness until it exits or `ms` elapses. */ -async function treeExitsWithin(child: SubprocessHandle, ms: number): Promise { +/** Bounded managed-range exit wait: observes the handle's range until it is empty or `ms` elapses. */ +async function rangeExitsWithin(child: SubprocessHandle, ms: number): Promise { const controller = new AbortController() const timer = setTimeout(() => { controller.abort() }, ms) try { @@ -183,26 +183,33 @@ async function treeExitsWithin(child: SubprocessHandle, ms: number): Promise { - // A spawn failure has no process to tear down; observe the rejection so - // disposal in a finally block cannot surface it as unhandled. - if (child.pid <= 0) { - await child.done.catch(() => {}) - return - } + const failures: Error[] = [] child.stdin?.end() - if (await treeExitsWithin(child, eofGraceMs)) return + let exited = false + try { + exited = await rangeExitsWithin(child, eofGraceMs) + } catch (error: unknown) { + failures.push(toError(error)) + } + if (exited) return // terminate() owns the bounded SIGTERM→SIGKILL timer. Its unbounded wait is // the process owner's exit proof, not a second derived grace that can overflow. child.terminate() - await child.waitForExit() + try { + await child.waitForExit() + } catch (error: unknown) { + failures.push(toError(error)) + } + if (failures.length === 1) throw failures[0] as Error + if (failures.length > 1) throw new AggregateError(failures, 'ACP subprocess teardown failed') } /** @@ -279,12 +286,8 @@ function reportFailure(spec: AcpRunSpec, error: unknown): void { function startupFailure( error: unknown, stage: Extract, - child: SubprocessHandle, outcome: SubprocessOutcome | undefined, ): AcpRunFailure { - if (child.pid <= 0) { - return new AcpRunFailure({ stage: 'process', category: 'process-start' }, error) - } return new AcpRunFailure( /* v8 ignore next -- Windows anonymous pipes cannot expose a live-child protocol close during startup. */ outcome === undefined @@ -322,10 +325,10 @@ function terminalFailure( /** * Start and publish one ACP child after initialization and session creation. * Child failures resolve through the run result. Startup rejects with fixed - * safe facts after provider-owned cleanup; successful cleanup proves process - * reap. Cleanup failure preserves startup plus teardown facts for an ordinary + * safe facts after provider-owned cleanup; successful cleanup proves managed + * range quiescence. Cleanup failure preserves startup plus teardown facts for an ordinary * failure, or teardown alone after cancellation, without claiming quiescence. - * Disposal cancels, kills, and reaps the child. + * Disposal cancels, terminates, and settles the child's managed range. * @param request - the start request; its signal is the cancellation channel. * @param spec - the resolved spawn spec: command/args/cwd, env, permission * policy, dispose graces, and the optional error sink. @@ -360,24 +363,31 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe } /* v8 ignore stop */ let processOutcome: SubprocessOutcome | undefined - const processDone = child.done.then((outcome) => { - processOutcome = outcome - return outcome - }) + let processFailure: Error | undefined + const processDone = child.done.then( + (outcome) => { + processOutcome = outcome + return outcome + }, + (error: unknown) => { + processFailure = toError(error) + throw processFailure + }, + ) - // Spawn-level failure surfaces as `done` rejecting into the startup race; a - // clean exit must never win it, so the success arm parks forever. (The ACP - // connection observing its streams closing bounds a child that exits - // without speaking the protocol.) - const spawnFailed: Promise = processDone.then( + // A rejected direct result surfaces into the startup race; a clean exit must + // never win it, so the success arm parks forever. (The ACP connection + // observing its streams closing bounds a child that exits without speaking + // the protocol.) + const processRejected: Promise = processDone.then( /* v8 ignore next -- the success arm's never-settling executor is intentionally empty. */ () => new Promise(() => {}), (err: unknown) => Promise.reject(toError(err)), ) - spawnFailed.catch(() => { /* observed by the startup race; never unhandled */ }) + processRejected.catch(() => { /* observed by the startup race; never unhandled */ }) const observeProcessOutcome = async (signal?: AbortSignal): Promise => { - if (processOutcome !== undefined || child.pid <= 0) return processOutcome + if (processOutcome !== undefined) return processOutcome const timeout = AbortSignal.timeout(Math.ceil(spec.disposeGraceMs)) const bound = signal === undefined ? timeout : AbortSignal.any([signal, timeout]) const aborted = Promise.withResolvers() @@ -389,8 +399,8 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe try { return await Promise.race([processDone, aborted.promise]) } catch { - // The active protocol failure remains authoritative when exit observation fails. - /* v8 ignore next -- a published child.done cannot reject; spawn rejection is consumed before publication. */ + // A provider rejection after handle publication leaves no direct outcome; + // the active protocol failure remains authoritative. return processOutcome } finally { bound.removeEventListener('abort', onObservationAbort) @@ -492,22 +502,25 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe /* v8 ignore next -- cancelSettled wins the startup race before this post-response guard can settle it. */ if (flags.cancelled) throw new Error('subagent cancelled before the ACP session started') })(), - spawnFailed, + processRejected, cancelSettled.then((): never => { throw new Error('subagent cancelled before the ACP session started') }), ]) } catch (error: unknown) { request.signal.removeEventListener('abort', onAbort) const cancelledBeforeCleanup = flags.cancelled - // A child closing its protocol stream can precede whole-tree exit + // A child closing its protocol stream can precede whole-range exit // observation. Local cancellation does not need the discarded startup // classification; other failures use the configured process grace. + const observedOutcome = !cancelledBeforeCleanup && !(error instanceof AcpRunFailure) + ? await observeProcessOutcome() + : undefined const startup = cancelledBeforeCleanup ? { kind: 'cancelled' } as const : { kind: 'failed', failure: error instanceof AcpRunFailure ? error - : startupFailure(error, startupStage, child, await observeProcessOutcome()), + : startupFailure(error, startupStage, observedOutcome), } as const if (startup.kind === 'cancelled') { // Local cancellation owns the startup outcome; only cleanup failure is @@ -515,7 +528,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe } else { reportFailure(spec, error instanceof AcpRunFailure ? error.cause - : error) + : processFailure ?? error) } try { await disposeProcess() @@ -566,13 +579,12 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe } catch (error: unknown) { if (!flags.cancelled) { const outcome = await observeProcessOutcome(request.signal) - /* v8 ignore next -- Windows anonymous pipes cannot expose a live-child prompt transport failure. */ const facts = outcome === undefined ? { stage: 'prompt', category: 'transport' } as const : { stage: 'process', category: 'process-exit', outcome } as const diagnostic = diagnosticText(facts, latestPermission) } - throw error + throw processFailure ?? error } }, collectOutput, diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index c1085a6ff8..caf75f0308 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -86,7 +86,6 @@ async function waitForFile(file: string, timeoutMs = 5000): Promise { function rejectFinalExitWait(child: SubprocessHandle, message: string): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -110,7 +109,6 @@ function rejectFinalExitWaitAfterExit(child: SubprocessHandle, message: string): function tapBoundedExitWait(child: SubprocessHandle, onWait: () => void): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -132,7 +130,6 @@ function replaceProtocolStreams( if (child.stdin === undefined) throw new Error('expected piped child stdin') stdin.pipe(child.stdin) return { - pid: child.pid, stdin, stdout, stderr: child.stderr, @@ -170,7 +167,6 @@ function closeProtocolOnPrompt(child: SubprocessHandle, onClose: () => void = () function replaceProcessOutcome(child: SubprocessHandle, outcome: SubprocessOutcome): SubprocessHandle { return { - pid: child.pid, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, @@ -300,7 +296,6 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', const stdin = new PassThrough() const calls: string[] = [] const child: SubprocessHandle = { - pid: 123, stdin, stdout: undefined, stderr: undefined, @@ -355,6 +350,98 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)', await expect(disposeAcpChild(child, 1_000)).resolves.toBeUndefined() await expect(child.done).rejects.toThrow() }) + + it('still terminates and performs the final wait when the EOF wait rejects', async () => { + const initialFailure = new Error('initial range observation failed') + const waitForExit = vi.fn() + .mockRejectedValueOnce(initialFailure) + .mockResolvedValueOnce(true) + const terminate = vi.fn() + const child: SubprocessHandle = { + stdin: new PassThrough(), + stdout: undefined, + stderr: undefined, + collected: {}, + done: new Promise(() => {}), + terminate, + waitForExit, + } + + await expect(disposeAcpChild(child, 1_000)).rejects.toBe(initialFailure) + expect(terminate).toHaveBeenCalledOnce() + expect(waitForExit).toHaveBeenCalledTimes(2) + }) + + it('preserves both wait failures in observation order', async () => { + const initialFailure = new Error('initial range observation failed') + const finalFailure = new Error('final range observation failed') + const waitForExit = vi.fn() + .mockRejectedValueOnce(initialFailure) + .mockRejectedValueOnce(finalFailure) + const child: SubprocessHandle = { + stdin: new PassThrough(), + stdout: undefined, + stderr: undefined, + collected: {}, + done: new Promise(() => {}), + terminate: vi.fn(), + waitForExit, + } + + let failure: unknown + try { + await disposeAcpChild(child, 1_000) + } catch (error: unknown) { + failure = error + } + expect(failure).toBeInstanceOf(AggregateError) + expect((failure as AggregateError).errors).toEqual([initialFailure, finalFailure]) + }) + + it('keeps an initialize transport failure before its rollback failure', async () => { + const startupFailure = new Error('target startup failed') + const cleanupFailure = new Error('range cleanup failed') + const direct = Promise.withResolvers() + const stdin = new PassThrough() + const stdout = new PassThrough() + const child: SubprocessHandle = { + stdin, + stdout, + stderr: undefined, + collected: {}, + done: direct.promise, + terminate: vi.fn(), + waitForExit: vi.fn() + .mockResolvedValueOnce(false) + .mockRejectedValueOnce(cleanupFailure), + } + const starting = startAcpRun(request(), { + command: 'fake-acp', + args: [], + cwd: process.cwd(), + permission: 'reject', + env: {}, + disposeEofGraceMs: 1_000, + disposeGraceMs: 1_000, + spawn: () => child, + }) + direct.reject(startupFailure) + + let failure: unknown + try { + await starting + } catch (error: unknown) { + failure = error + } + expect(failure).toBeInstanceOf(AggregateError) + const failures = (failure as AggregateError).errors as Error[] + expect(failures.map(error => error.message)).toEqual([ + `subagent-acp: ${expectedFailure('stage: initialize; category: transport')}`, + `subagent-acp: ${expectedFailure('stage: teardown; category: unknown')}`, + ]) + expect(failures[0]?.cause).toBe(startupFailure) + expect(failures[1]?.cause).toBe(cleanupFailure) + }) }) describe('cwd resolution', () => { @@ -699,7 +786,7 @@ describe('dsh-subagent-acp', () => { env: { MOCK_CRASH_ON_INITIALIZE: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, - spawn: spawnSubprocess, + spawn: spec => spawnSubprocess(spec), }).catch((cause: unknown) => cause) expect(error).toBeInstanceOf(Error) expect((error as Error).message).toBe( @@ -724,6 +811,36 @@ describe('dsh-subagent-acp', () => { ) }) + it('reuses a direct outcome already observed before the startup transport closes', async () => { + const outcome = { exitCode: 19, signal: null } as const + const stdin = new PassThrough() + const stdout = new PassThrough() + const starting = startAcpRun(request(), { + command: 'fake-acp', + args: [], + cwd: process.cwd(), + permission: 'reject', + env: {}, + disposeEofGraceMs: 50, + disposeGraceMs: 50, + spawn: () => ({ + stdin, + stdout, + stderr: undefined, + collected: {}, + done: Promise.resolve(outcome), + terminate: vi.fn(), + waitForExit: vi.fn().mockResolvedValue(true), + }), + }) + await Promise.resolve() + stdout.end() + + await expect(starting).rejects.toThrow( + `subagent-acp: ${expectedFailure('stage: initialize; category: process-exit; exit code: 19')}`, + ) + }) + it('reaps a child whose session/new response omits the session id', async () => { const tmp = mkdtempSync(join(tmpdir(), 'acp-malformed-session-')) const flushed = join(tmp, 'flushed') @@ -1125,8 +1242,16 @@ describe('dsh-subagent-acp', () => { }) it('preserves partial output and structured process facts when the child exits', async () => { - const ctx = await setup({ MOCK_TEXT: 'partial answer', MOCK_CRASH_AFTER_CHUNK: '1' }) - const run = await ctx.subagents.start('acp', request()) + const run = await startAcpRun(request(), { + command: process.execPath, + args: [mockServer], + cwd: process.cwd(), + permission: 'reject', + env: { MOCK_TEXT: 'partial answer', MOCK_CRASH_AFTER_CHUNK: '1' }, + disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, + disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, + spawn: spec => spawnSubprocess(spec), + }) const result = await run.result expect(result).toEqual({ output: [{ type: 'text', text: 'partial answer' }], @@ -1136,6 +1261,44 @@ describe('dsh-subagent-acp', () => { await run.dispose() }) + it('classifies a rejected direct result as the active prompt transport failure', async () => { + const processFailure = new Error('remote provider failed after returning a handle') + const direct = Promise.withResolvers() + let realChild: SubprocessHandle | undefined + const errors: Error[] = [] + const run = await startAcpRun(request(), { + command: process.execPath, + args: [mockServer], + cwd: process.cwd(), + permission: 'reject', + env: { MOCK_HANG: '1' }, + disposeEofGraceMs: 100, + disposeGraceMs: 100, + spawn: (spec) => { + const child = spawnSubprocess(spec) + realChild = child + return closeProtocolOnPrompt({ + stdin: child.stdin, + stdout: child.stdout, + stderr: child.stderr, + collected: child.collected, + done: direct.promise, + terminate: () => { child.terminate() }, + waitForExit: (signal?: AbortSignal) => child.waitForExit(signal), + }, () => { direct.reject(processFailure) }) + }, + onError: (error) => { errors.push(error) }, + }) + await expect(run.result).resolves.toEqual({ + output: [], + diagnostic: expectedFailure('stage: prompt; category: transport'), + stopReason: 'error', + }) + expect(errors).toContain(processFailure) + await run.dispose() + await realChild?.done + }) + it('reports a signal-only process outcome', async () => { const run = await startAcpRun(request(), { command: process.execPath, @@ -1159,7 +1322,7 @@ describe('dsh-subagent-acp', () => { await run.dispose() }) - it('rejects a spawn failure after provider-owned cleanup', async () => { + it('rejects a returned-handle startup failure after provider-owned cleanup', async () => { const privateCommand = '/nonexistent/private/SECRET_TOKEN/acp-agent' const error = await startAcpRun( request(), @@ -1167,7 +1330,7 @@ describe('dsh-subagent-acp', () => { ).catch((cause: unknown) => cause) expect(error).toBeInstanceOf(Error) expect((error as Error).message).toBe( - `subagent-acp: ${expectedFailure('stage: process; category: process-start')}`, + `subagent-acp: ${expectedFailure('stage: initialize; category: transport')}`, ) expect((error as Error).message).not.toContain(privateCommand) }) @@ -1246,7 +1409,7 @@ describe('dsh-subagent-acp', () => { } }) - it('rejects a startup failure via the provider load path', async () => { + it('classifies a returned-handle startup failure through the provider load path', async () => { const ctx = new Context() await ctx.plugin(SessionProjectionRegistry) await ctx.plugin(SubagentRuntime) @@ -1259,7 +1422,7 @@ describe('dsh-subagent-acp', () => { env: {}, }) await expect(ctx.subagents.start('acp', request())).rejects.toThrow( - `subagent-acp: ${expectedFailure('stage: process; category: process-start')}`, + `subagent-acp: ${expectedFailure('stage: initialize; category: transport')}`, ) }) @@ -1390,9 +1553,11 @@ describe('dsh-subagent-acp', () => { expect(result.diagnostic).toBe( expectedFailure('stage: process; category: process-exit; exit code: 1'), ) - expect(warnings).toEqual([ + // Unsupported hosts can emit the subprocess provider's one-time fallback + // warning before this provider-specific failure reaches the same logger. + expect(warnings).toContainEqual( expect.stringContaining('subagent-acp "acp": child run failed (error):'), - ]) + ) await run.dispose() }) diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml index 2ed36236ee..c0e1344a60 100644 --- a/packages/subagent/subagent-claude-code/README.i18n.yaml +++ b/packages/subagent/subagent-claude-code/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subagent/subagent-claude-code/README.md -README.md: 7ec86fc2092f22fc82665d9660edb42a01a3d99c -README.zh.md: 2ef2e957b19f56b664f79e429b067a59557373f8 +README.md: 6f63a0338ba0e7f6223ca12c8b0739b21d8a44fa +README.zh.md: f097d14427bb28deaca9bbc3c259ac7d83755fe9 diff --git a/packages/subagent/subagent-claude-code/README.md b/packages/subagent/subagent-claude-code/README.md index 7ec86fc209..6f63a0338b 100644 --- a/packages/subagent/subagent-claude-code/README.md +++ b/packages/subagent/subagent-claude-code/README.md @@ -47,7 +47,7 @@ Removing the package withdraws the provider and its private runtime closure on t | `model` | native Claude settings | Optional non-empty model name fixed for every run from this provider instance; omission sends no SDK override | | `env` | `{}` | Explicit SDK/CLI environment layered over the credential-scrubbed parent environment | | `permissionMode` | `dontAsk` | Native non-interactive permission policy fixed for every run from this provider instance | -| `disposeGraceMs` | `3000` | Grace between the shared process-tree owner's termination tiers | +| `disposeGraceMs` | `3000` | Grace between the shared managed-range owner's termination tiers | | `permissionMode` value | Native behavior | |---|---| @@ -109,7 +109,7 @@ This section explains how the provider drives a real Claude Code CLI and where t |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: config schema, provider registration | | [`src/run.ts`](src/run.ts) | The SDK query lifecycle, result acceptance, and permission handling | -| [`src/process.ts`](src/process.ts) | Process-tree termination escalation on disposal | +| [`src/process.ts`](src/process.ts) | Managed-range termination escalation on disposal | | [`cordis.patch.yml`](cordis.patch.yml) | The Profile patch layer that registers the dormant provider | ### Run flow @@ -194,4 +194,4 @@ This Dev Note is working context for maintainers: open questions and undecided d -**Runtime invariant:** No companion is published. Lifecycle pairing belongs to the shared subagent service and process-tree ownership belongs to the subprocess service. +**Runtime invariant:** No companion is published. Lifecycle pairing belongs to the shared subagent service, and managed-range ownership belongs to the subprocess service. diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md index 2ef2e957b1..f097d14427 100644 --- a/packages/subagent/subagent-claude-code/README.zh.md +++ b/packages/subagent/subagent-claude-code/README.zh.md @@ -47,7 +47,7 @@ dsh --profile | `model` | Claude 原生设置 | 为本提供方实例的每次运行固定的可选非空模型名称；省略时不发送 SDK 覆盖 | | `env` | `{}` | 叠加在已清理凭据的父环境之上的显式 SDK/CLI 环境 | | `permissionMode` | `dontAsk` | 为本提供方实例的每次运行固定的原生非交互权限策略 | -| `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限 | +| `disposeGraceMs` | `3000` | 共享 managed-range owner 各终止层级之间的宽限 | | `permissionMode` 值 | 原生行为 | |---|---| @@ -109,7 +109,7 @@ dsh --profile |---|---| | [`src/index.ts`](src/index.ts) | 插件入口：config schema、提供方注册 | | [`src/run.ts`](src/run.ts) | SDK query 生命周期、结果接受与权限处理 | -| [`src/process.ts`](src/process.ts) | dispose 时的进程树逐级终止 | +| [`src/process.ts`](src/process.ts) | dispose 时的 managed-range 逐级终止 | | [`cordis.patch.yml`](cordis.patch.yml) | 注册休眠提供方的 Profile patch 层 | ### 运行流程 @@ -194,4 +194,4 @@ Claude Code 子级会在一个全新的 SDK query 中接收独立文本任务。 -**运行时不变式：** 不发布伴生入口。生命周期配对属于共享 subagent service，process-tree 所有权属于 subprocess service。 +**运行时不变式：** 不发布伴生入口。生命周期配对属于共享 subagent service，受管范围的所有权属于 subprocess service。 diff --git a/packages/subagent/subagent-claude-code/src/index.ts b/packages/subagent/subagent-claude-code/src/index.ts index c853fc6154..9b9abce5db 100644 --- a/packages/subagent/subagent-claude-code/src/index.ts +++ b/packages/subagent/subagent-claude-code/src/index.ts @@ -52,7 +52,7 @@ export interface Config { * `bypassPermissions` explicitly skips permission checks. */ permissionMode?: ClaudeCodePermissionMode - /** Grace in milliseconds for Claude Code process-tree termination. */ + /** Grace in milliseconds between Claude Code managed-range termination tiers. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-claude-code/src/process.ts b/packages/subagent/subagent-claude-code/src/process.ts index e9c3d81156..b610c5bb7b 100644 --- a/packages/subagent/subagent-claude-code/src/process.ts +++ b/packages/subagent/subagent-claude-code/src/process.ts @@ -40,7 +40,7 @@ export function sdkEnvironmentOverlay( /** * Translate one official SDK spawn request to the shared process owner. * @param options - command, arguments, workspace, environment, and forwarded signal from the SDK. - * @param graceMs - process-tree termination grace. + * @param graceMs - managed-range termination grace. * @returns the fully explicit shared subprocess request. */ export function claudeSpawnSpec( @@ -73,7 +73,7 @@ export class ManagedClaudeCodeProcess implements SpawnedProcess { /** * Project a managed process with piped stdin and stdout. - * @param child - shared handle that remains the process-tree authority. + * @param child - shared handle that remains the managed-range authority. */ constructor(private readonly child: SubprocessHandle) { this.stdin = child.stdin as NonNullable @@ -93,7 +93,7 @@ export class ManagedClaudeCodeProcess implements SpawnedProcess { ) } - /** Whether the SDK has requested managed tree termination. */ + /** Whether the SDK has requested managed-range termination. */ get killed(): boolean { return this.killRequested } @@ -114,7 +114,7 @@ export class ManagedClaudeCodeProcess implements SpawnedProcess { } /** - * Route the SDK's termination request to the tree-scoped process owner. + * Route the SDK's termination request to the managed-range process owner. * @param _signal - SDK-selected signal; the shared seam owns its escalation ladder. * @returns false only after exit or a previous termination request. */ diff --git a/packages/subagent/subagent-claude-code/src/run.ts b/packages/subagent/subagent-claude-code/src/run.ts index 1db2180d70..dfe6c5fee7 100644 --- a/packages/subagent/subagent-claude-code/src/run.ts +++ b/packages/subagent/subagent-claude-code/src/run.ts @@ -1,7 +1,7 @@ /** * One-shot Claude Code lifecycle: invoke the official Agent SDK, place its * real CLI process under the shared subprocess owner, map only strict SDK - * success to completion, and dispose to whole-tree quiescence. + * success to completion, and dispose to whole-range quiescence. * * @module @deepseek-ai/dsh-subagent-claude-code/run */ @@ -156,7 +156,7 @@ export interface ClaudeCodeRunSpec { readonly permissionMode: ClaudeCodePermissionMode /** Explicit deployment/test environment layered after shared scrubbing. */ readonly env: Record - /** Subprocess termination grace passed to the shared process-tree owner. */ + /** Subprocess termination grace passed to the shared managed-range owner. */ readonly disposeGraceMs: number /** Shared subprocess service spawn operation. */ readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle @@ -261,17 +261,22 @@ export async function consumeClaudeQuery( } /** - * Close the official query, terminate the managed process tree, and wait for - * the subprocess owner to prove it is gone. + * Close the official query, terminate the managed range, and wait for the + * subprocess owner to prove it is quiescent. * @param query - official SDK query, when creation reached that point. - * @param child - live shared-service handle that owns the CLI process tree; - * spawn-failed handles settle at the startup boundary instead. + * @param child - shared-service handle that owns the CLI managed range, including + * a published handle whose direct result later rejects. */ export async function disposeClaudeCodeChild( query: Pick | undefined, child: SubprocessHandle, ): Promise { const failures: Error[] = [] + let outcome: SubprocessOutcome | undefined + void child.done.then( + (value) => { outcome = value }, + () => {}, + ) try { query?.close() } catch (error: unknown) { @@ -284,7 +289,6 @@ export async function disposeClaudeCodeChild( } catch (error: unknown) { failures.push(thrown(error)) } - const outcome = await child.done const firstFailure = failures[0] if (firstFailure !== undefined) { @@ -298,6 +302,7 @@ export async function disposeClaudeCodeChild( : new AggregateError(failures, 'Claude Code teardown failures') throw new ClaudeCodeFailure(facts, cause) } + await child.done.catch(() => {}) } /** @@ -375,7 +380,7 @@ export function claudeQueryOptions( * Start one official Claude Agent SDK query and publish its one-shot run. * @param request - resolved shared subagent request. * @param spec - Workspace, environment, process service, and diagnostic policy. - * @returns the published run after both Query and real CLI handle exist. + * @returns the published run after both Query and the real CLI handle exist. */ export async function startClaudeCodeRun( request: SubagentStartRequest, @@ -403,6 +408,8 @@ export async function startClaudeCodeRun( } let child: SubprocessHandle | undefined + let childFailure: Error | undefined + let childProcessFailure: Promise | undefined let query: Query | undefined let managedProcess: ManagedClaudeCodeProcess | undefined let diagnostic: string | undefined @@ -421,6 +428,14 @@ export async function startClaudeCodeRun( ): void => { child = captured managedProcess = process + childProcessFailure = captured.done.then( + () => new Promise(() => {}), + (error: unknown) => { + childFailure = thrown(error) + throw childFailure + }, + ) + void childProcessFailure.catch(() => {}) } try { query = officialQuery({ @@ -432,12 +447,12 @@ export async function startClaudeCodeRun( capturePermissionDiagnostic, ), }) - if (child === undefined || child.pid <= 0) { + if (child === undefined || childProcessFailure === undefined) { throw new Error( 'subagent-claude-code: official SDK did not publish a controllable Claude Code process', ) } - if (controller.signal.aborted) { + if (isAborted(controller.signal)) { throw new Error('subagent-claude-code: request was aborted before SDK startup') } } catch (error: unknown) { @@ -451,46 +466,11 @@ export async function startClaudeCodeRun( category: 'unknown', outcome: startupOutcome, } as const - const startupFailure = (cause: unknown = error): ClaudeCodeFailure => new ClaudeCodeFailure( + const startupFailure = (cause: unknown = childFailure ?? error): ClaudeCodeFailure => new ClaudeCodeFailure( startupFacts, thrown(cause), ) requestCancel() - if (child !== undefined && child.pid <= 0) { - let closeError: Error | undefined - try { - query?.close() - } catch (disposeError: unknown) { - closeError = thrown(disposeError) - } - - let spawnError = thrown(error) - try { - await child.done - } catch (childError: unknown) { - spawnError = thrown(childError) - } - - if (closeError !== undefined) { - const failure = startupFailure(spawnError) - const cleanupFailure = new ClaudeCodeFailure({ - stage: 'teardown', - category: 'unknown', - }, closeError) - const aggregate = new AggregateError( - [failure, cleanupFailure], - `${failure.message}; ${cleanupFailure.message}`, - ) - reportFailure(aggregate) - throw aggregate - } - if (cancelledBeforeCleanup || isAborted(request.signal)) { - throw new Error('subagent-claude-code: request was aborted before SDK startup') - } - const failure = startupFailure(spawnError) - reportFailure(failure) - throw failure - } if (child !== undefined) { try { await disposeClaudeCodeChild(query, child) @@ -504,6 +484,12 @@ export async function startClaudeCodeRun( reportFailure(aggregate) throw aggregate } + if (cancelledBeforeCleanup || isAborted(request.signal)) { + throw new Error('subagent-claude-code: request was aborted before SDK startup') + } + const failure = startupFailure() + reportFailure(failure) + throw failure } else if (query !== undefined) { try { query.close() @@ -531,20 +517,24 @@ export async function startClaudeCodeRun( const publishedQuery = query const publishedChild = child + const publishedProcessFailure = childProcessFailure let receivedResult = false const result = settleRunResult({ attempt: async () => { try { - return await consumeClaudeQuery(publishedQuery, () => { - capturePermissionDiagnostic(unattendedDiagnostic( - spec.permissionMode, - 'tool permission', - 'denied', - 'Claude Code denied the request before an interactive prompt', - )) - }, () => { - receivedResult = true - }) + return await Promise.race([ + consumeClaudeQuery(publishedQuery, () => { + capturePermissionDiagnostic(unattendedDiagnostic( + spec.permissionMode, + 'tool permission', + 'denied', + 'Claude Code denied the request before an interactive prompt', + )) + }, () => { + receivedResult = true + }), + publishedProcessFailure, + ]) } catch (error: unknown) { const processOutcome = managedProcess?.outcome let facts: ClaudeCodeFailureFacts diff --git a/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts index 04e1eadcb8..750929d405 100644 --- a/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts +++ b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts @@ -99,7 +99,6 @@ function errorCause(value: unknown): Error | undefined { } interface FakeChildOptions { - readonly pid?: number readonly exitOnTerminate?: boolean readonly waitForExitError?: Error readonly doneError?: Error @@ -168,7 +167,6 @@ function fakeChild(options: FakeChildOptions = {}): FakeChild { }) }) const handle: SubprocessHandle = { - pid: options.pid ?? 1234, stdin, stdout, stderr: undefined, @@ -261,6 +259,7 @@ function queryFrom( function waitingQuery(signal: AbortSignal, close = vi.fn()): Query { async function* stream(): AsyncGenerator { + yield { type: 'system', subtype: 'init' } as SDKMessage await new Promise((_resolve, reject) => { const fail = (): void => { reject(signal.reason instanceof Error @@ -329,7 +328,7 @@ beforeEach(() => { env: options.env!, signal: options.abortController!.signal, })) - return queryFrom([]) + return queryFrom([{ type: 'system', subtype: 'init' } as SDKMessage]) }) }) @@ -813,7 +812,7 @@ describe('official spawn projection', () => { }) it('emits spawn errors', async () => { - const child = fakeChild({ pid: -1 }) + const child = fakeChild() const process = new ManagedClaudeCodeProcess(child.handle) const errorListener = vi.fn() const removed = vi.fn() @@ -1201,6 +1200,7 @@ describe('run publication, cancellation, and settlement', () => { for (const outcome of outcomes) { const child = fakeChild() async function* stream(): AsyncGenerator { + yield { type: 'system', subtype: 'init' } as SDKMessage child.settle(outcome) await Promise.resolve() throw new Error('SECRET_TOKEN from process transport') @@ -1303,7 +1303,7 @@ describe('run publication, cancellation, and settlement', () => { await run.dispose() }) - it('rejects pre-abort and every incomplete startup transaction', async () => { + it('rejects pre-abort and incomplete Query or child acquisition', async () => { const preAborted = new AbortController() preAborted.abort() const unused = fakeRun() @@ -1313,6 +1313,16 @@ describe('run publication, cancellation, and settlement', () => { )).rejects.toThrow('aborted before SDK startup') expect(unused.options).toEqual([]) + const thrownAbort = new AbortController() + queryMock.mockImplementationOnce(() => { + thrownAbort.abort(new Error('startup cancelled before resource publication')) + throw new Error('query failed before resource publication') + }) + await expect(startClaudeCodeRun( + request(undefined, thrownAbort.signal), + unused.spec, + )).rejects.toThrow('aborted before SDK startup') + const noChildClose = vi.fn() queryMock.mockImplementationOnce( () => queryFrom([], undefined, noChildClose), @@ -1452,23 +1462,8 @@ describe('run publication, cancellation, and settlement', () => { new Error('spawn /sdk/claude EACCES'), { code: 'EACCES', path: '/sdk/claude' }, ) - const failedSpawn = fakeChild({ - pid: -1, - doneError: spawnError, - }) - const failed = fakeRun([], undefined, failedSpawn) - const failedStartup = startClaudeCodeRun(request(), failed.spec) - await expect(failedStartup) - .rejects.toThrow(expectedFailureDiagnostic('query-start', 'unknown')) - await expect(failedStartup).rejects.not.toThrow('spawn /sdk/claude EACCES') - await expect(failedStartup).rejects.toMatchObject({ cause: spawnError }) - expect(failed.close).toHaveBeenCalledOnce() - expect(failedSpawn.terminate).not.toHaveBeenCalled() - expect(failedSpawn.waitForExit).not.toHaveBeenCalled() - const failedSpawnAbort = new AbortController() const cancelledFailedSpawn = fakeChild({ - pid: -1, doneError: spawnError, }) const cancelledFailedClose = vi.fn() @@ -1488,7 +1483,6 @@ describe('run publication, cancellation, and settlement', () => { throw cancelledFailedSpawnCloseError }) const cancelledFailedSpawnWithCloseFailure = fakeChild({ - pid: -1, doneError: spawnError, }) const failedSpawnAbortWithCloseFailure = new AbortController() @@ -1518,32 +1512,6 @@ describe('run publication, cancellation, and settlement', () => { .rejects.not.toThrow('spawn /sdk/claude EACCES') expect(cancelledFailedSpawnClose).toHaveBeenCalledOnce() - const failedSpawnCloseError = new Error('query close failed') - const failedSpawnClose = vi.fn(() => { throw failedSpawnCloseError }) - const failedSpawnWithCloseFailure = fakeChild({ - pid: -1, - doneError: spawnError, - }) - queryMock.mockImplementationOnce(({ options }) => { - options.spawnClaudeCodeProcess!(sdkSpawnOptions()) - return queryFrom([], undefined, failedSpawnClose) - }) - const failedWithCloseFailure = startClaudeCodeRun(request(), { - ...unused.spec, - spawn: () => failedSpawnWithCloseFailure.handle, - }) - await expect(failedWithCloseFailure) - .rejects.toThrow(expectedFailureDiagnostic('query-start', 'unknown')) - await expect(failedWithCloseFailure) - .rejects.not.toThrow('spawn /sdk/claude EACCES') - await expect(failedWithCloseFailure).rejects.toMatchObject({ - message: `subagent-claude-code: ${expectedFailureDiagnostic('query-start', 'unknown')}; subagent-claude-code: ${expectedFailureDiagnostic('teardown', 'unknown')}`, - errors: [ - expect.objectContaining({ cause: spawnError }), - expect.objectContaining({ cause: failedSpawnCloseError }), - ], - }) - const cleanupError = new Error('live child cleanup failed') const constructionError = new Error( 'query construction failed with a live child', @@ -1569,6 +1537,135 @@ describe('run publication, cancellation, and settlement', () => { await expect(liveCleanupFailure) .rejects.not.toThrow('live child cleanup failed') }) + + it('publishes before the first SDK message and settles a delayed provider rejection through result', async () => { + const spawnError = Object.assign( + new Error('spawn /sdk/claude ENOENT'), + { code: 'ENOENT', path: '/sdk/claude' }, + ) + const child = fakeChild() + const close = vi.fn() + const onError = vi.fn>() + queryMock.mockImplementationOnce(({ options }) => { + options.spawnClaudeCodeProcess!(sdkSpawnOptions()) + async function* stream(): AsyncGenerator { + await new Promise(() => {}) + } + return Object.assign(stream(), { close }) as unknown as Query + }) + + const run = await startClaudeCodeRun(request(), { + cwd: '/workspace', + permissionMode: DEFAULT_CLAUDE_CODE_PERMISSION_MODE, + env: {}, + disposeGraceMs: 5, + spawn: () => child.handle, + onError, + }) + expect(close).not.toHaveBeenCalled() + expect(child.terminate).not.toHaveBeenCalled() + child.fail(spawnError) + await expect(run.result).resolves.toEqual({ + output: [], + diagnostic: expectedFailureDiagnostic('query-run', 'unknown'), + stopReason: 'error', + }) + expect(onError).toHaveBeenCalledWith(expect.any(Error), 'error') + expect(errorCause(onError.mock.calls[0]?.[0])?.message).toBe(spawnError.message) + await run.dispose() + expect(close).toHaveBeenCalledOnce() + expect(child.terminate).toHaveBeenCalledOnce() + expect(child.waitForExit).toHaveBeenCalledOnce() + }) + + it('keeps local cancellation authoritative when it arrives with the first SDK message', async () => { + const controller = new AbortController() + const child = fakeChild() + const close = vi.fn() + queryMock.mockImplementationOnce(({ options }) => { + options.spawnClaudeCodeProcess!(sdkSpawnOptions()) + async function* stream(): AsyncGenerator { + controller.abort(new Error('cancelled while the first message arrived')) + yield { type: 'system', subtype: 'init' } as SDKMessage + } + return Object.assign(stream(), { close }) as unknown as Query + }) + + const run = await startClaudeCodeRun( + request(undefined, controller.signal), + { + cwd: '/workspace', + permissionMode: DEFAULT_CLAUDE_CODE_PERMISSION_MODE, + env: {}, + disposeGraceMs: 5, + spawn: () => child.handle, + }, + ) + await expect(run.result).resolves.toEqual({ + output: [], + stopReason: 'aborted', + }) + await run.dispose() + expect(close).toHaveBeenCalledOnce() + expect(child.terminate).toHaveBeenCalledOnce() + }) + + it('settles an SDK stream that ends before its first message through result', async () => { + const child = fakeChild() + const close = vi.fn() + queryMock.mockImplementationOnce(({ options }) => { + options.spawnClaudeCodeProcess!(sdkSpawnOptions()) + return queryFrom([], undefined, close) + }) + + const run = await startClaudeCodeRun(request(), { + cwd: '/workspace', + permissionMode: DEFAULT_CLAUDE_CODE_PERMISSION_MODE, + env: {}, + disposeGraceMs: 5, + spawn: () => child.handle, + }) + await expect(run.result).resolves.toEqual({ + output: [], + diagnostic: expectedFailureDiagnostic('query-run', 'invalid-result'), + stopReason: 'error', + }) + await run.dispose() + expect(close).toHaveBeenCalledOnce() + expect(child.terminate).toHaveBeenCalledOnce() + expect(child.waitForExit).toHaveBeenCalledOnce() + }) + + it('settles a first-read SDK failure through the published result', async () => { + const child = fakeChild() + const close = vi.fn() + const firstReadFailure = new Error('first SDK read failed with SECRET_TOKEN') + const onError = vi.fn>() + queryMock.mockImplementationOnce(({ options }) => { + options.spawnClaudeCodeProcess!(sdkSpawnOptions()) + return queryFrom([], firstReadFailure, close) + }) + + const run = await startClaudeCodeRun(request(), { + cwd: '/workspace', + permissionMode: DEFAULT_CLAUDE_CODE_PERMISSION_MODE, + env: {}, + disposeGraceMs: 5, + spawn: () => child.handle, + onError, + }) + await expect(run.result).resolves.toEqual({ + output: [], + diagnostic: expectedFailureDiagnostic('query-run', 'unknown'), + stopReason: 'error', + }) + expect(onError).toHaveBeenCalledWith(expect.any(Error), 'error') + expect(errorCause(onError.mock.calls[0]?.[0])?.message).toBe(firstReadFailure.message) + await run.dispose() + expect(close).toHaveBeenCalledOnce() + expect(child.terminate).toHaveBeenCalledOnce() + expect(child.waitForExit).toHaveBeenCalledOnce() + }) }) describe('query and process disposal', () => { @@ -1608,7 +1705,7 @@ describe('query and process disposal', () => { .toBe('SECRET_TOKEN close failure') }) - it('does not finish disposal before the managed tree exits', async () => { + it('does not finish disposal before the managed range is empty', async () => { const child = fakeChild({ exitOnTerminate: false }) let disposed = false const disposal = disposeClaudeCodeChild( @@ -1624,7 +1721,7 @@ describe('query and process disposal', () => { expect(disposed).toBe(true) }) - it('reports close and tree-wait failures without skipping cleanup', async () => { + it('reports close and range-wait failures without skipping cleanup', async () => { const waitFailure = fakeChild({ waitForExitError: new Error('wait boom'), }) @@ -1650,4 +1747,23 @@ describe('query and process disposal', () => { ]) expect(waitFailure.terminate).toHaveBeenCalledOnce() }) + + it('reports a range-wait failure without waiting for a pending direct outcome', async () => { + const waitFailure = new Error('managed range observation failed') + const child = fakeChild({ + exitOnTerminate: false, + waitForExitError: waitFailure, + }) + const result = await Promise.race([ + disposeClaudeCodeChild({ close: vi.fn() }, child.handle).then( + () => undefined, + (error: unknown) => error, + ), + new Promise<'timeout'>(resolve => setTimeout(() => { resolve('timeout') }, 100)), + ]) + + expect(result).not.toBe('timeout') + expect(errorCause(result)).toBe(waitFailure) + expect(child.terminate).toHaveBeenCalledOnce() + }) }) diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml index 5a113e66ef..ebd80688f9 100644 --- a/packages/subagent/subagent-codex/README.i18n.yaml +++ b/packages/subagent/subagent-codex/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subagent/subagent-codex/README.md -README.md: 399f01bd057c3278356a17c04137be6596274866 -README.zh.md: f2ac1287cc0678822e655b6d06f0b414ebee2b81 +README.md: 5563dd420aa0fc7cae625d62bc4009625357b646 +README.zh.md: 65231ccab2a25f89ce8a9cf94875a19bfe3da1ec diff --git a/packages/subagent/subagent-codex/README.md b/packages/subagent/subagent-codex/README.md index 399f01bd05..5563dd420a 100644 --- a/packages/subagent/subagent-codex/README.md +++ b/packages/subagent/subagent-codex/README.md @@ -47,7 +47,7 @@ Removing the package withdraws the provider and its private runtime closure on t | `model` | native Codex settings | Optional non-empty model name fixed for every thread from this provider instance; omission sends no app-server override | | `env` | `{}` | Explicit child environment layered over the credential-scrubbed parent environment | | `permissionMode` | `never` | Native non-interactive approval and sandbox mode fixed for every thread from this provider instance | -| `disposeGraceMs` | `3000` | Grace between the shared process-tree owner's termination tiers | +| `disposeGraceMs` | `3000` | Grace between the shared managed-range owner's termination tiers | | `permissionMode` value | `thread/start` fields | Native behavior | |---|---|---| @@ -192,4 +192,4 @@ This Dev Note is working context for maintainers: open questions and undecided d -**Runtime invariant:** No companion is published. Lifecycle pairing belongs to the shared subagent service and process-tree ownership belongs to the subprocess service. +**Runtime invariant:** No companion is published. Lifecycle pairing belongs to the shared subagent service, and managed-range ownership belongs to the subprocess service. diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md index f2ac1287cc..65231ccab2 100644 --- a/packages/subagent/subagent-codex/README.zh.md +++ b/packages/subagent/subagent-codex/README.zh.md @@ -47,7 +47,7 @@ dsh --profile | `model` | Codex 原生设置 | 为本提供方实例的每个线程固定的可选非空模型名称；省略时不发送 app-server 覆盖 | | `env` | `{}` | 叠加在已清理凭据的父环境之上的显式子进程环境 | | `permissionMode` | `never` | 为本提供方实例的每个线程固定的原生非交互审批与沙箱模式 | -| `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限 | +| `disposeGraceMs` | `3000` | 共享 managed-range owner 各终止层级之间的宽限 | | `permissionMode` 值 | `thread/start` 字段 | 原生行为 | |---|---|---| @@ -192,4 +192,4 @@ Codex 子级会在一个全新的临时线程中，以单个轮次接收这些 -**运行时不变式：** 不发布伴生入口。生命周期配对属于共享 subagent service，process-tree 所有权属于 subprocess service。 +**运行时不变式：** 不发布伴生入口。生命周期配对属于共享 subagent service，受管范围的所有权属于 subprocess service。 diff --git a/packages/subagent/subagent-codex/src/index.ts b/packages/subagent/subagent-codex/src/index.ts index 84005ac866..9fcc73ebff 100644 --- a/packages/subagent/subagent-codex/src/index.ts +++ b/packages/subagent/subagent-codex/src/index.ts @@ -45,7 +45,7 @@ export interface Config { env?: Record /** Native non-interactive permission mode fixed for this Provider instance. */ permissionMode?: CodexPermissionMode - /** Grace in milliseconds for app-server process-tree termination. */ + /** Grace in milliseconds between app-server managed-range termination tiers. */ disposeGraceMs?: number } diff --git a/packages/subagent/subagent-codex/src/run.ts b/packages/subagent/subagent-codex/src/run.ts index 36b978dd23..12abd405e3 100644 --- a/packages/subagent/subagent-codex/src/run.ts +++ b/packages/subagent/subagent-codex/src/run.ts @@ -1,7 +1,7 @@ /** * One-shot Codex child lifecycle: spawn the real app-server through the * subprocess seam, publish only after initialization and ephemeral thread - * creation, flatten post-publication failures, and dispose to whole-tree + * creation, flatten post-publication failures, and dispose to whole-range * quiescence. * * @module @deepseek-ai/dsh-subagent-codex/run @@ -146,7 +146,7 @@ export interface CodexRunSpec { readonly permissionMode: CodexPermissionMode /** Explicit deployment/test environment layered after the shared scrub. */ readonly env: Record - /** Subprocess termination grace passed to the shared process-tree owner. */ + /** Subprocess termination grace passed to the shared managed-range owner. */ readonly disposeGraceMs: number /** Shared subprocess service spawn operation. */ readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle @@ -182,10 +182,10 @@ export function textTask(prompt: readonly ContentBlock[]): string[] { } /** - * Close the private wire, terminate the managed process tree, and wait for the - * subprocess owner to prove it is gone. + * Close the private wire, terminate the managed range, and wait for the + * subprocess owner to prove it is quiescent. * @param wire - private app-server protocol connection. - * @param child - shared-service handle that owns the process tree. + * @param child - shared-service handle that owns the managed range. */ export async function disposeCodexChild( wire: CodexAppServerWire, @@ -193,32 +193,27 @@ export async function disposeCodexChild( ): Promise { wire.close() - if (child.pid > 0) { - let outcome: SubprocessOutcome | undefined - void child.done.then( - (value) => { outcome = value }, - /* v8 ignore next -- a positive pid excludes spawn-level done rejection. */ - () => {}, - ) - try { - child.stdin?.end() - } catch { - // A concurrently closed stdin does not change tree ownership below. - } - child.terminate() - try { - await child.waitForExit() - } catch (error: unknown) { - throw new CodexRunFailure({ - stage: 'teardown', - category: 'unknown', - outcome, - }, thrown(error)) - } - await child.done - } else { - await child.done.catch(() => {}) + let outcome: SubprocessOutcome | undefined + void child.done.then( + (value) => { outcome = value }, + () => {}, + ) + try { + child.stdin?.end() + } catch { + // A concurrently closed stdin does not change range ownership below. } + child.terminate() + try { + await child.waitForExit() + } catch (error: unknown) { + throw new CodexRunFailure({ + stage: 'teardown', + category: 'unknown', + outcome, + }, thrown(error)) + } + await child.done.catch(() => {}) } /** diff --git a/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts index a203c42c82..32347c4784 100644 --- a/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts +++ b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts @@ -139,7 +139,6 @@ class ProtocolPeer { } interface FakeChildOptions { - readonly pid?: number readonly exitOnTerminate?: boolean readonly doneError?: Error readonly waitForExitError?: Error @@ -211,7 +210,6 @@ function fakeChild(options: FakeChildOptions = {}): FakeChild { }) }) const handle: SubprocessHandle = { - pid: options.pid ?? 1234, stdin: toChild, stdout: fromChild, stderr, @@ -1879,7 +1877,6 @@ describe('run lifecycle and quiescence', () => { await expect(spawnFailure).rejects.not.toThrow('SECRET_TOKEN') const asyncSpawnFailureChild = fakeChild({ - pid: -1, doneError: new Error('SECRET_TOKEN async spawn failure'), }) const asyncSpawnFailure = startCodexRun( @@ -1889,7 +1886,8 @@ describe('run lifecycle and quiescence', () => { await expect(asyncSpawnFailure) .rejects.toThrow(expectedFailureDiagnostic('initialize', 'unknown')) await expect(asyncSpawnFailure).rejects.not.toThrow('SECRET_TOKEN') - expect(asyncSpawnFailureChild.terminate).not.toHaveBeenCalled() + expect(asyncSpawnFailureChild.terminate).toHaveBeenCalledOnce() + expect(asyncSpawnFailureChild.waitForExit).toHaveBeenCalledOnce() const child = fakeChild() const starting = startCodexRun(request(), runSpec(child)) @@ -2230,7 +2228,7 @@ describe('run lifecycle and quiescence', () => { }) describe('disposeCodexChild', () => { - it('closes stdin, terminates, and waits for the managed tree', async () => { + it('closes stdin, terminates, and waits for the managed range', async () => { const child = fakeChild() const wire = defaultWire(child) const end = vi.spyOn(child.toChild, 'end') @@ -2241,7 +2239,7 @@ describe('disposeCodexChild', () => { expect(child.waitForExit).toHaveBeenCalledWith() }) - it('does not finish disposal before the managed tree exits', async () => { + it('does not finish disposal before the managed range is empty', async () => { const child = fakeChild({ exitOnTerminate: false }) const wire = defaultWire(child) let disposed = false @@ -2265,19 +2263,18 @@ describe('disposeCodexChild', () => { .resolves.toBeUndefined() }) - it('handles a spawn-level failure with no process tree', async () => { + it('still runs idempotent cleanup when target startup rejects', async () => { const child = fakeChild({ - pid: -1, doneError: new Error('spawn failed'), }) const wire = defaultWire(child) await expect(disposeCodexChild(wire, child.handle)) .resolves.toBeUndefined() - expect(child.terminate).not.toHaveBeenCalled() - expect(child.waitForExit).not.toHaveBeenCalled() + expect(child.terminate).toHaveBeenCalledOnce() + expect(child.waitForExit).toHaveBeenCalledOnce() }) - it('reports tree-wait failure with safe teardown facts', async () => { + it('reports range-wait failure with safe teardown facts', async () => { const child = fakeChild({ waitForExitError: new Error('SECRET_TOKEN wait failure'), }) diff --git a/packages/subagent/subagent/src/out-of-process.ts b/packages/subagent/subagent/src/out-of-process.ts index c4aed68628..4dc158a240 100644 --- a/packages/subagent/subagent/src/out-of-process.ts +++ b/packages/subagent/subagent/src/out-of-process.ts @@ -5,7 +5,7 @@ * working-directory resolution (config override, else the delegating parent * session's workspace), the never-reject result settlement, and the standard * run-handle publication. Backends compose these with their own wire drivers; - * the process machinery itself (spawn, env scrub, tree-scoped teardown) + * the process machinery itself (spawn, env scrub, managed-range teardown) * belongs to the `dsh-subprocess` seam. * * @module @deepseek-ai/dsh-subagent/out-of-process diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml index b03b4693a7..a56b86fb74 100644 --- a/packages/subprocess/README.i18n.yaml +++ b/packages/subprocess/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subprocess/README.md -README.md: bed6310ff70492474ceae38b685dee4cb9474ebf -README.zh.md: de2a287f6094d52c84ad25d86c34e45aa7c7e0c1 +README.md: 38f212bf8ddbe37c293f633f4411b07411e94eac +README.zh.md: 7bc3b16d9bb1c4ab770ea81ca226bd9e012e14fd diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md index bed6310ff7..38f212bf8d 100644 --- a/packages/subprocess/README.md +++ b/packages/subprocess/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Every child process and terminal session the harness runs — bash commands, language servers, persistent shells, and out-of-process subagent backends — starts, observes, and terminates through one shared service (`ctx.subprocess`), with a local provider running them on the host machine. It is not a standalone product feature: the consuming capability seams decide what each process means, and command semantics, deadlines, and model-facing presentation stay with them. The group provides executable lookup, bounded output capture with spill recovery, whole-tree termination, and a scrubbed starting environment for every child. +Every child process and terminal session the harness runs — bash commands, language servers, persistent shells, and out-of-process subagent backends — starts, observes, and terminates through one shared service (`ctx.subprocess`), with a local provider running them on the host machine. It is not a standalone product feature: the consuming capability seams decide what each process means, and command semantics, deadlines, and model-facing presentation stay with them. The group provides executable lookup, bounded output capture with spill recovery, provider-managed process ranges with disclosed weaker fallbacks, and a scrubbed starting environment for every child. ## Table of Contents @@ -25,8 +25,8 @@ Every child process and terminal session the harness runs — bash commands, lan | Package | Role | ctx key | |---|---|---| | [`subprocess`](subprocess/README.md) | Defines the child-process service: executable lookup, managed process spawns, and real terminal sessions | `ctx.subprocess` | -| [`subprocess-local`](subprocess-local/README.md) | Runs those process and terminal spawns on the host machine | registers on `ctx.subprocess` | -| [`win32-process`](win32-process/README.md) | Owns the shared Win32 bindings for restricted process creation, stdio, Job assignment, waits, and handle cleanup | library — no ctx key | +| [`subprocess-local`](subprocess-local/README.md) | Runs host processes and terminals with native managed ranges where supported and explicit weaker fallbacks elsewhere | registers on `ctx.subprocess` | +| [`win32-process`](win32-process/README.md) | Owns shared Win32 bindings for sandbox and ordinary process creation, stdio, Job assignment, polling, waits, and handle cleanup | library — no ctx key | The service keeps process lifetime across consumer reloads; consumers own what a process means (a bash command, a language server) and every default that shapes one. diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md index de2a287f60..7bc3b16d9b 100644 --- a/packages/subprocess/README.zh.md +++ b/packages/subprocess/README.zh.md @@ -9,7 +9,7 @@ kind: "package-group" ## 概述 -harness 运行的每个子进程与终端会话——bash 命令、语言服务器、持久 shell 与进程外 subagent 后端——都经由一个共享服务（`ctx.subprocess`）启动、观察与终止，并由一个本地提供方在宿主机器上执行。它不是独立的产品功能：消费方能力 seam 决定每个进程的含义，命令语义、时限与面向模型的呈现仍归它们所有。本组提供可执行文件查找、带 spill 恢复的有界输出捕获、整棵进程树的终止，以及每个子进程起步时所用的清理后环境。 +harness 运行的每个子进程与终端会话——bash 命令、语言服务器、持久 shell 与进程外 subagent 后端——都经由一个共享服务（`ctx.subprocess`）启动、观察与终止，并由一个本地提供方在宿主机器上执行。它不是独立的产品功能：消费方能力 seam 决定每个进程的含义，命令语义、时限与面向模型的呈现仍归它们所有。本组提供可执行文件查找、带 spill 恢复的有界输出捕获、由提供方管理且明确披露较弱 fallback 的进程范围，以及每个子进程起步时所用的清理后环境。 ## 目录 @@ -25,8 +25,8 @@ harness 运行的每个子进程与终端会话——bash 命令、语言服务 | 包 | 职责 | ctx 键 | |---|---|---| | [`subprocess`](subprocess/README.zh.md) | 定义子进程服务：可执行文件查找、受管进程 spawn 与真实终端会话 | `ctx.subprocess` | -| [`subprocess-local`](subprocess-local/README.zh.md) | 在宿主机器上运行这些进程与终端 spawn | 注册到 `ctx.subprocess` | -| [`win32-process`](win32-process/README.zh.md) | 归属受限进程创建、stdio、Job 分配、等待与句柄清理所用的共享 Win32 绑定 | 库，不使用 ctx key | +| [`subprocess-local`](subprocess-local/README.zh.md) | 在支持的平台上以原生受管范围运行宿主进程与终端，其他平台使用明确披露的较弱 fallback | 注册到 `ctx.subprocess` | +| [`win32-process`](win32-process/README.zh.md) | 归属 sandbox 与普通进程创建、stdio、Job 分配、轮询、等待与句柄清理所用的共享 Win32 绑定 | 库，不使用 ctx key | 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、一个语言服务器），以及决定塑造该进程的每一项默认值。 diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml index cfea9f923c..7979b68d4d 100644 --- a/packages/subprocess/subprocess-local/README.i18n.yaml +++ b/packages/subprocess/subprocess-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subprocess/subprocess-local/README.md -README.md: 17009a3576baa4e47b4e929b8125e8cd774d6545 -README.zh.md: 88ab221bbeeec60035d2d5f61d3f5b321fce8491 +README.md: 63d4d5d403d3559778dcad76a8c96cf677f1a977 +README.zh.md: f0a8b629b2ed17b6a6e9385a6eb565443c21ab26 diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md index 17009a3576..63d4d5d403 100644 --- a/packages/subprocess/subprocess-local/README.md +++ b/packages/subprocess/subprocess-local/README.md @@ -1,5 +1,5 @@ --- -description: "The local host provider for the subprocess service: run managed process trees and real terminal sessions on the host machine." +description: "The local host provider for the subprocess service: run OS-owned managed ranges and real terminal sessions on the host machine, with explicit weaker fallbacks." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Mount `dsh-subprocess-local` in any composition that runs child processes on the host: it resolves local executables, spawns detached process trees with explicit stdio, and provides real terminal sessions through `node-pty`. It has no configuration, so every disposition, limit, terminal size, and grace arrives on the spawn request from the calling capability seam. Output collection keeps a bounded in-memory tail with optional spill files for full-stream recovery, children start from a scrubbed environment, and disposal terminates and joins every running tree. +Mount `dsh-subprocess-local` in any composition that runs child processes on the host. It resolves local executables, gives ordinary Linux and Windows commands plus supported Linux terminal sessions an OS-owned managed range, and provides real terminal sessions through `node-pty`; unsupported hosts use an explicit weaker fallback. It has no configuration, so every disposition, limit, terminal size, and grace arrives on the spawn request from the calling capability seam. Output collection keeps a bounded in-memory tail with optional spill files for full-stream recovery, children start from a scrubbed environment, and disposal terminates and joins every selected range or session. ## Table of Contents @@ -46,15 +46,15 @@ Collect mode keeps the last `maxBytes` of a stream in memory — errors and fina ### Running terminal sessions -`spawnTerminal` allocates a real PTY and bridges UTF-8 text; you can inspect and signal the current foreground process group and await a `terminate()` that settles every session member the provider can still observe. On Linux, an exact input wait requires a foreground thread whose fd 0 identifies the shell's controlling terminal and whose current syscall waits on that fd. If the kernel denies the syscall probe, the provider reports no exact wait and leaves the higher PTY backend to its idle inference; process sleep state is not evidence. On Windows, SIGINT is delivered as a Ctrl-C input write, SIGTSTP and SIGHUP are unsupported, and teardown verifies the shell's termination through the process table because an externally killed shell may never fire the PTY exit notification. +`spawnTerminal` allocates a real PTY and bridges UTF-8 text; you can inspect and signal the current foreground process group and await one `terminate()` operation. On supported Linux hosts, the original terminal argv runs directly inside a user-systemd scope, preserving the node-pty PID, session leader, controlling terminal, foreground `inputWaiting`, and readiness while the scope owns reparented or `setsid` descendants. On fallback hosts, cleanup retains exact identities from the rooted tree and observable session but cannot recover every escaped descendant. An exact Linux input wait requires a foreground thread whose fd 0 identifies the shell's controlling terminal and whose current syscall waits on that fd; if the kernel denies the syscall probe, the higher PTY backend uses its idle inference instead. On Windows, SIGINT is delivered as a Ctrl-C input write, SIGTSTP and SIGHUP are unsupported, and teardown verifies the shell's termination through the process table because an externally killed shell may never fire the PTY exit notification. ### Shutdown behavior -Normal disposal terminates every running tree and terminal and awaits their exit. During a JavaScript-observable host exit — direct `process.exit()`, default uncaught exceptions, default unhandled rejections — a synchronous finalization force-terminates everything still owned (SIGKILL to the group, `taskkill /T /F` on Windows) without creating promises or timers. The same exit removes the private per-process spill directory when it holds no completed spill file (completed spill files are retained as full-output recovery artifacts until an external cleanup). Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor. +Normal disposal terminates every running managed range and terminal session and awaits quiescence. During a JavaScript-observable host exit — direct `process.exit()`, default uncaught exceptions, default unhandled rejections — synchronous finalization asks a Linux scope to kill its members, kills each Windows runner so its sole Job handle closes, and uses the existing PGID, `taskkill`, or captured-identity operation for fallbacks. It creates no promises or timers and does not claim quiescence. The same exit removes the private per-process spill directory when it holds no completed spill file; completed spill files remain as full-output recovery artifacts until an external cleanup. Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor. ### What can go wrong -An executable that cannot be resolved fails loud with a stable error; a spawn that never starts rejects `done`. A read past the retained tail is `lossy` and points at the spill file when one exists. A daemonized descendant that leaves the tree or terminal session can outlive cleanup — see the limitations below. +An executable that cannot be resolved fails loud with a stable error. `done` rejects when spawn or provider failure prevents a direct outcome, and that rejection does not prove whether target execution began. `waitForExit()` rejects if the selected owner can no longer prove its range empty, and cleanup still attempts termination. A read past the retained tail is `lossy` and points at the spill file when one exists. A fallback process group or observed terminal session can miss a descendant that escapes before observation — see the limitations below. ----- @@ -68,26 +68,33 @@ This section explains the design decisions behind the provider and points at the ### Design concept -The provider treats the process tree as the unit of lifetime. POSIX children spawn detached (their own process group) so the whole tree is signalled by negative group id with a direct-child fallback; Windows terminates by root pid through `taskkill /T`. Signalling, escalation, and teardown guard on tree liveness rather than direct-child settlement, so a TERM-trapping helper cannot outlive the handle unnoticed. +Each spawn selects one owner for both signalling and quiescence. Supported Linux ordinary and terminal launches use transient user-systemd scopes, while supported Windows ordinary launches use a helper-owned kill-on-close Job. macOS, older or unavailable user-systemd, and unavailable Windows native support use the existing detached process-group, `taskkill`, or terminal-session observations with one warning. The provider never replays a command through fallback after a native path may have started it. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Service wiring: live-handle sets, disposal, host-exit finalization, executable lookup | -| [`src/spawn.ts`](src/spawn.ts) | Process plumbing: detached spawn, tail-keep collection, spill files, escalation, tree-exit observer | -| [`src/terminal.ts`](src/terminal.ts) | `node-pty` terminal handle: foreground inspection, session cleanup, Windows teardown | +| [`src/spawn.ts`](src/spawn.ts) | Shared process plumbing: direct outcomes, tail-keep collection, spill files, and fallback spawning | +| [`src/managed-owner.ts`](src/managed-owner.ts) | Private signal-and-wait owner used by each ordinary handle | +| [`src/linux-scope.ts`](src/linux-scope.ts) | Linux user-systemd capability checks, scope launch, signalling, and quiescence | +| [`src/linux-execve.ts`](src/linux-execve.ts) | Linux libc image replacement and inherited-standard-descriptor preservation | +| [`src/windows-job.ts`](src/windows-job.ts) | Windows Job capability checks and helper launch | +| [`src/runner-launch.ts`](src/runner-launch.ts) | Source, built, and packaged private-runner selection | +| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux one-shot exec bootstrap and Windows Job runner | +| [`src/runner-protocol.ts`](src/runner-protocol.ts) | Strict Linux launch/startup files and Windows IPC messages | +| [`src/terminal.ts`](src/terminal.ts) | `node-pty` handle: Linux scope attachment, foreground inspection, and fallback cleanup | | [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX process-tree and session inspection | | [`src/windows-inspector.ts`](src/windows-inspector.ts) | Windows Toolhelp32 process-table inspection via koffi | | — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. | ### Main flow -A spawn builds the scrubbed child environment, starts the detached process, attaches collectors to the collected streams, and returns a handle. `done` settles at process close after a bounded pipe-drain grace, so a surviving descendant that inherited a pipe cannot hold the outcome open indefinitely; the escalation timer survives direct-child settlement so SIGKILL still reaches tree survivors. Terminal cleanup sweeps descendants by exact identity, stops the shell, re-sweeps, and verifies absence through the process table. +A spawn synchronously validates the final argv, cwd, and environment, selects containment before the user command can run, and returns a handle while target identity remains private. Linux ordinary and terminal launches use a private one-shot request whose scoped bootstrap restores the target cwd and environment, resolves the executable, clears close-on-exec on fd 0 through fd 2, and enters libc `execve()` with the original argv. Windows ordinary launches isolate runner fd 0 through fd 2, reserve fd 3 for IPC, and carry target stdio on fd 4 through fd 6; the runner resolves those CRT descriptors to OS handles, creates the target suspended, assigns it to the Job, resumes it, and closes only the carrier descriptors. `done` settles the direct command after its stdio barrier, while `waitForExit()` separately waits for the selected scope, Job, process group, or observed session to become empty. ### Safety invariants -Spill files are opened `0600` with `O_EXCL` and random names under a `0700` per-process directory, defeating symlink planting in shared temp dirs; a failed final close withholds the spill path. Process identities carry start times, so cleanup never follows PID reuse. Host-exit finalization creates no promises or timers, preserves the host exit code and diagnostic, contains each target's failure, and does not claim quiescence. +Spill files are opened `0600` with `O_EXCL` and random names under a `0700` per-process directory, defeating symlink planting in shared temp dirs; a failed final close withholds the spill path. Fallback process identities carry start times, so cleanup never follows PID reuse. A selected native failure is reported instead of replaying argv through fallback, and a range is removed from the live set only after cleanup completes or the failure remains observable. Host-exit finalization creates no promises or timers, preserves the host exit code and diagnostic, contains each target's failure, and does not claim quiescence. @@ -122,10 +129,12 @@ No direct invalidation; the named consumers own any request-prefix changes. These limits define when the provider is a poor fit or needs special operational care. They are current package constraints, not a general platform comparison or a task backlog. -- **Windows tree support is best-effort** — termination routes through `taskkill /PID /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary. -- **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a `taskkill` without `/F` does not terminate console processes, so the teardown TERM tier is a grace wait before the `/F` escalation. -- **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the PTY root; on Linux, a `setsid` child leaves both the tree and the owned terminal session; the provider adds no continuous process-table monitor. -- **In-process cleanup requires a JavaScript-observable exit** — direct `process.exit()`, default uncaught exceptions, and default unhandled rejections emit Node's synchronous `exit` event; an unhandled `SIGTERM`, `SIGINT`, or `SIGHUP`, `SIGKILL`, fatal OOM, `process.abort()`, native crashes, and power loss require an external supervisor, container init, or equivalent OS owner. +- **Native ownership has explicit host requirements** — Linux needs a readable user manager and `systemd-run --expand-environment=no`; older systemd versions use the warned PGID fallback. macOS always uses that fallback because no supported public persistent owner exists. +- **Native selection has bounded per-spawn costs** — Linux repeats the bootstrap entry, libc `execve`/`fcntl` bindings, live user manager, and literal-argv scope probe until it first succeeds; later eligible ordinary or terminal spawns recheck only the live user manager. Windows rechecks the runner entry, bindings, and current Job support before every ordinary spawn. Successful Linux deep-probe state and fallback-warning de-duplication persist for the provider lifetime. All probes finish before the user command can run, and child-process probes have a 5-second timeout. Each Linux launch creates a private request directory, checks unresolved scope establishment every 50 milliseconds, then exponentially backs off an established active scope to at most 5 seconds between queries; a Windows ordinary launch keeps one runner and IPC channel until the Job reports zero active processes. Target standard handles are inherited directly, with no named-pipe stdio or result files. +- **Windows Job inheritance has defined exclusions** — ordinary descendants inherit the Job by default, but breakaway processes are outside the guarantee. The target starts only after Job assignment; external termination of the runner in the narrow create-to-assignment interval can leave a suspended target behind. +- **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a `taskkill` without `/F` does not terminate console processes, so the teardown TERM tier is a grace wait before the `/F` escalation. Windows readiness has no exact stdin-wait tier: the prompt-marker fast path compares the shell pid as the pseudo foreground group, and silence/timing tiers cover the rest. +- **Fallback terminal ownership remains observational** — on macOS or Linux without usable user-systemd, a child that reparents before any foreground-inspection snapshot or leaves the owned terminal session can escape the process-table scan. The local provider does not add a continuous process-table monitor; supported Linux native mode instead retains these descendants through scope membership. +- **In-process cleanup requires a JavaScript-observable exit** — direct `process.exit()`, default uncaught exceptions, and default unhandled rejections emit Node's synchronous `exit` event. The default OS disposition for an unhandled `SIGTERM`, `SIGINT`, or `SIGHUP` bypasses that event; an application covers those signals only by installing a handler that performs normal disposal or calls `process.exit()`. `SIGKILL`, fatal OOM, `process.abort()`, native crashes, power loss, and any failure that cannot run JavaScript require an external supervisor, container init, or equivalent OS owner. - **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently named secrets (for example `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed variables is noted future work. - **Completed spill files are not deleted** — bounded full-output recovery files accumulate under the OS tmpdir until something external cleans them; the private per-process spill directory is removed at a JavaScript-observable exit only when it holds no completed spill file. diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md index 88ab221bbe..f0a8b629b2 100644 --- a/packages/subprocess/subprocess-local/README.zh.md +++ b/packages/subprocess/subprocess-local/README.zh.md @@ -1,5 +1,5 @@ --- -description: "面向部署方与维护者的子进程服务本地宿主提供方说明：在宿主机器上运行受管进程树与真实终端会话。" +description: "子进程服务的本地宿主提供方：在宿主机器上运行由 OS 所有的受管范围与真实终端会话，并明确披露较弱的 fallback。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -在需要于宿主机上运行子进程的组合中挂载 `dsh-subprocess-local`：它解析本地可执行文件、以显式 stdio 运行 detached 进程树，并通过 `node-pty` 提供真实终端会话。它没有任何配置，因此每项处置方式、限制、终端尺寸与宽限期都随 spawn 请求来自调用方能力 seam。输出收集在内存中保留一段有界尾部，并可选地用 spill 文件恢复完整流；子进程从清理后的环境起步；dispose（资源释放）会终止并等待每棵仍在运行的进程树退出。 +在任何于宿主机上运行子进程的组合中挂载 `dsh-subprocess-local`。它解析本地可执行文件，为普通 Linux 与 Windows 命令以及受支持的 Linux 终端会话提供由 OS 所有的受管范围，并通过 `node-pty` 提供真实终端会话；不受支持的宿主使用明确披露的较弱 fallback。它没有任何配置，因此每项处置方式、限制、终端尺寸与宽限期都随 spawn 请求来自调用方能力 seam。输出收集在内存中保留一段有界尾部，并可选地用 spill 文件恢复完整流；子进程从清理后的环境起步；dispose（资源释放）会终止并等待每个选定范围或会话完全停稳。 ## 目录 @@ -46,15 +46,15 @@ kind: "package-reference" ### 运行终端会话 -`spawnTerminal` 分配真实 PTY 并桥接 UTF-8 文本；你可以检查当前前台进程组并向其发送信号，还可以等待一次 `terminate()`，让提供方仍可观察到的每个会话成员完全停稳。在 Linux 上，精确输入等待要求前台线程的 fd 0 标识 shell 的控制终端，且线程当前的 syscall 正在等待该 fd。如果内核拒绝 syscall 探测，提供方不会报告精确等待，而由上层 PTY 后端使用空闲推断；进程睡眠状态不能作为证据。在 Windows 上，SIGINT 以 Ctrl-C 输入写入投递，SIGTSTP 与 SIGHUP 不受支持，拆卸会通过进程表验证 shell 已终止，因为被外部终止的 shell 可能永远不会触发 PTY 退出通知。 +`spawnTerminal` 分配真实 PTY 并桥接 UTF-8 文本；你可以检查当前前台进程组并向其发送信号，还可以等待一次 `terminate()` 操作。在受支持的 Linux 宿主上，原始终端 argv 直接在 user-systemd scope 内运行；node-pty PID、session leader、控制终端、前台 `inputWaiting` 与就绪状态保持不变，而 scope 会拥有已重新设定父进程或调用 `setsid` 的后代。在 fallback 宿主上，清理会保留根进程树和可观察 session 中的精确身份，但无法重新发现每个已经逃逸的后代。Linux 的精确输入等待要求前台线程的 fd 0 标识 shell 的控制终端，且线程当前的 syscall 正在等待该 fd；如果内核拒绝 syscall 探测，上层 PTY 后端会改用空闲推断。在 Windows 上，SIGINT 以 Ctrl-C 输入写入投递，SIGTSTP 与 SIGHUP 不受支持，拆卸会通过进程表验证 shell 已终止，因为被外部终止的 shell 可能永远不会触发 PTY 退出通知。 ### 关闭行为 -正常 dispose 会终止每棵仍在运行的进程树与终端并等待其退出。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会强制终止所有仍归本包所有的对象（对进程组发送 SIGKILL，Windows 上运行 `taskkill /T /F`），且不创建任何 Promise 或定时器。同一退出阶段会删除每进程私有 spill 目录（仅当其未持有任何已完成的 spill 文件时；已完成的 spill 文件作为完整输出恢复产物保留，直到外部机制清理）。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电则需要外部 supervisor。 +正常 dispose 会终止每个仍在运行的受管范围与终端会话并等待其完全停稳。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会请求 Linux scope 终止其成员，同步终止每个 Windows runner 以关闭其唯一 Job handle，并为 fallback 使用既有 PGID、`taskkill` 或已捕获身份操作。它不创建 Promise 或定时器，也不声称已经完全停稳。同一退出阶段会删除未持有任何已完成 spill 文件的每进程私有 spill 目录；已完成的 spill 文件作为完整输出恢复产物保留，直到外部机制清理。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电需要外部 supervisor。 ### 可能出错的地方 -无法解析的可执行文件会以稳定的错误快速失败；从未启动成功的 spawn 会让 `done` reject。越过保留尾部的读取是 `lossy` 的，并在 spill 文件存在时指向它。脱离进程树或终端会话的 daemon 化后代可能比清理更长寿——见下文限制。 +无法解析的可执行文件会以稳定错误快速失败。当 spawn 或 provider failure 使 direct outcome 无法产生时，`done` 会 reject；该 rejection 不能证明 target 是否已经开始执行。若所选 owner 无法再证明其范围为空，`waitForExit()` 会 reject，清理仍会尝试终止。越过保留尾部的读取是 `lossy` 的，并在 spill 文件存在时指向它。fallback 进程组或已观察终端 session 可能遗漏在观察前逃逸的后代——见下文限制。 ----- @@ -68,26 +68,33 @@ kind: "package-reference" ### 设计理念 -本提供方把进程树视为生命周期单元。POSIX 子进程以 detached 方式 spawn（拥有独立进程组），因此整棵进程树以负进程组 id 发送信号，并以直接子进程作为回退；Windows 通过 `taskkill /T` 按根 pid 终止。信号发送、升级与拆卸都以进程树存活状态为守卫，而非以直接子进程结算为准，因此拦截 TERM 的辅助进程无法在无人察觉的情况下比句柄更长寿。 +每次 spawn 都为信号发送与完全停稳选择同一个 owner。受支持的 Linux 普通命令与终端启动使用临时 user-systemd scope，受支持的 Windows 普通命令使用由 helper 持有、关闭时终止成员的 Job。macOS、旧版或不可用的 user-systemd，以及不可用的 Windows 原生支持使用既有 detached 进程组、`taskkill` 或终端 session 观察，并只告警一次。native 路径可能已经启动命令后，本提供方绝不会通过 fallback 重放该命令。 ### 源码地图 | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 服务接线：存活句柄集合、dispose、宿主退出最终清理、可执行文件查找 | -| [`src/spawn.ts`](src/spawn.ts) | 进程管道：detached spawn、保尾收集、spill 文件、升级、进程树退出观察器 | -| [`src/terminal.ts`](src/terminal.ts) | `node-pty` 终端句柄：前台检查、会话清理、Windows 拆卸 | +| [`src/spawn.ts`](src/spawn.ts) | 共享进程管道：直接结果、保尾收集、spill 文件与 fallback spawn | +| [`src/managed-owner.ts`](src/managed-owner.ts) | 每个普通句柄使用的私有信号与等待 owner | +| [`src/linux-scope.ts`](src/linux-scope.ts) | Linux user-systemd 能力检查、scope 启动、信号发送与完全停稳 | +| [`src/linux-execve.ts`](src/linux-execve.ts) | Linux libc 进程映像替换与继承标准文件描述符保留 | +| [`src/windows-job.ts`](src/windows-job.ts) | Windows Job 能力检查与 helper 启动 | +| [`src/runner-launch.ts`](src/runner-launch.ts) | source、built 与 packaged 私有 runner 选择 | +| [`src/spawn-runner.ts`](src/spawn-runner.ts) | Linux 一次性 exec bootstrap 与 Windows Job runner | +| [`src/runner-protocol.ts`](src/runner-protocol.ts) | 严格的 Linux 启动／错误文件与 Windows IPC 消息 | +| [`src/terminal.ts`](src/terminal.ts) | `node-pty` 终端句柄：Linux scope 绑定、前台检查与 fallback 清理 | | [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX 进程树与会话检查 | | [`src/windows-inspector.ts`](src/windows-inspector.ts) | 经 koffi 的 Windows Toolhelp32 进程表检查 | | — | 不发布运行时不变式伴生入口；约定归 seam 所有。 | ### 主流程 -一次 spawn 会构建清理后的子进程环境、启动 detached 进程、把收集器挂到收集模式的流上，然后返回句柄。`done` 在进程关闭后、经过一段有界管道排空宽限期才结算，因此继承了管道的存活后代无法无限期拖住结果；升级定时器在直接子进程结算后依然存活，使 SIGKILL 仍能到达进程树幸存者。终端清理按精确身份清扫后代、停止 shell、再次清扫，并通过进程表验证其已不存在。 +一次 spawn 会同步校验最终 argv、cwd 与环境，在用户命令可能运行前选择 containment，并在目标身份保持私有的情况下返回句柄。Linux 普通命令与终端启动使用私有的一次性请求；scope 内的 bootstrap 会恢复目标 cwd 与环境、解析可执行文件、清除 fd 0 至 fd 2 的 close-on-exec 标记，再以原始 argv 进入 libc `execve()`。Windows 普通命令会隔离 runner 的 fd 0 至 fd 2、把 fd 3 留给 IPC，并用 fd 4 至 fd 6 承载 target stdio；runner 把这些 CRT 描述符解析成 OS handle，以 suspended 状态创建 target，将其加入 Job、恢复运行，再只关闭 carrier 描述符。`done` 会在 direct command 及其 stdio 屏障结算后完成，`waitForExit()` 则分别等待所选 scope、Job、进程组或已观察 session 变空。 ### 安全不变式 -spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目录下创建，可抵御共享临时目录中的符号链接植入；最终关闭失败时不公布 spill 路径。进程身份携带启动时间，因此清理绝不会跟随 PID 复用。宿主退出最终清理不创建 Promise 或定时器，保留宿主退出码与诊断，分别包含每个目标的失败，也不会声称已经完全停稳。 +spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目录下创建，可抵御共享临时目录中的符号链接植入；最终关闭失败时不公布 spill 路径。fallback 进程身份携带启动时间，因此清理绝不会跟随 PID 复用。选定的 native 路径失败时会报告错误，而不会通过 fallback 重放 argv；受管范围只有在清理完成后才从存活集合移除，否则失败仍保持可观察。宿主退出最终清理不创建 Promise 或定时器，保留宿主退出码与诊断，分别包含每个目标的失败，也不会声称已经完全停稳。 @@ -122,11 +129,13 @@ spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目 这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用平台对比或任务积压。 -- **Windows 进程树支持仅为尽力而为**——终止经由 `taskkill /PID /T /F` 完成，所有结果都被就地吸收（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。 -- **Windows 终端信号是控制台级的**——SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 因不可用而被拒绝；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。 -- **守护化的终端后代仍可能逃出可观察边界**——在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 PTY 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话；本提供方不新增持续进程表监视器。 -- **进程内清理要求退出阶段仍能执行 JavaScript**——直接 `process.exit()`、默认未捕获异常和默认未处理 rejection 会发出 Node 同步 `exit` 事件；未处理的 `SIGTERM`、`SIGINT` 或 `SIGHUP`、`SIGKILL`、fatal OOM、`process.abort()`、native crash 与断电，都需要外部 supervisor、容器 init 或等价的 OS 所有者负责。 -- **凭据清除依赖名称启发式规则**——只匹配 `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。 +- **native ownership 有明确宿主要求**——Linux 需要可读的 user manager 与 `systemd-run --expand-environment=no`；旧版 systemd 使用带告警的 PGID fallback。macOS 因没有受支持的公开 persistent owner，始终使用该 fallback。 +- **native 选择具有有界的每次 spawn 成本**——Linux 会重复检查 bootstrap 入口、libc `execve`/`fcntl` bindings、存活的 user manager 与 literal-argv scope 支持，直到这套完整探测首次成功；后续符合条件的普通命令或终端 spawn 只重新检查存活的 user manager。Windows 会在每次普通 spawn 前重新检查 runner 入口、bindings 与当前 Job 支持。Linux 深度探测的成功状态与 fallback 告警去重会在 provider 生命周期内持续保留。所有探测都会在用户命令可能运行前完成，子进程探测的超时为 5 秒。每次 Linux 启动都会创建私有请求目录，以 50 毫秒间隔检查尚未确定的 scope 建立状态；scope 已建立且仍 active 后，查询间隔按指数增长，最多为 5 秒。Windows 普通命令会保留一个 runner 与一条 IPC 通道，直到 Job 报告活动进程数为零。目标会直接继承标准句柄，不使用 named-pipe stdio 或结果文件。 +- **Windows Job inheritance 有明确排除项**——普通后代默认继承 Job，但 breakaway 进程不在保证范围。目标只在 Job 分配后启动；runner 若在 create-to-assignment 极窄区间遭外力终止，可能留下 suspended target。 +- **Windows 终端信号是控制台级的**——SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 被拒绝（不可用）；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。Windows 就绪没有精确的 stdin-wait 档：prompt-marker 快路径把 shell pid 作为伪前台进程组比较，其余由静默与计时档覆盖。 +- **fallback 终端 ownership 仍依赖观察**——在 macOS 或缺少可用 user-systemd 的 Linux 上，子进程如果在任何前台检查快照之前重新设定父进程，或离开自有终端 session，就可能逃出进程表扫描。本地提供方不会新增持续进程表监视器；受支持的 Linux native 模式改由 scope membership 持有这些后代。 +- **进程内清理要求退出阶段仍能执行 JavaScript**——直接 `process.exit()`、默认未捕获异常和默认未处理 rejection 会发出 Node 同步 `exit` 事件。未安装 handler 时，`SIGTERM`、`SIGINT` 或 `SIGHUP` 的默认 OS 处置不会发出该事件；应用只有安装执行正常 dispose 或调用 `process.exit()` 的 handler 才能覆盖这些信号。`SIGKILL`、fatal OOM、`process.abort()`、native crash、断电，以及任何无法运行 JavaScript 的故障，都需要外部 supervisor、容器 init 或等价的 OS owner 负责。 +- **凭据清除依赖名称启发式规则**——只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。 - **不会删除已完成的 spill 文件**——有界的完整输出恢复文件会在 OS tmpdir 下累积，直到外部机制进行清理；每进程私有 spill 目录仅在未持有任何已完成 spill 文件时于 JavaScript 可观察的退出阶段删除。 diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json index f3b56fb873..e8797463c1 100644 --- a/packages/subprocess/subprocess-local/package.json +++ b/packages/subprocess/subprocess-local/package.json @@ -18,11 +18,17 @@ "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, + "./runner": { + "types": "./lib/types/bin.d.ts", + "default": "./lib/runner.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, "files": [ "lib/index.js", + "lib/runner.js", + "lib/runner-*.js", "scripts/ensure-spawn-helper.mjs", "lib/types/**/*.d.ts" ], @@ -36,6 +42,7 @@ "@deepseek-ai/cordis": "workspace:^" }, "dependencies": { + "@deepseek-ai/dsh-win32-process": "workspace:^", "koffi": "^3.1.0", "node-pty": "1.2.0-beta.15" }, diff --git a/packages/subprocess/subprocess-local/src/bin.ts b/packages/subprocess/subprocess-local/src/bin.ts new file mode 100644 index 0000000000..2ea28d6df1 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/bin.ts @@ -0,0 +1,25 @@ +/** Thin executable/importable entry for the provider-private runner core. */ + +import { consumeRunnerSelection } from './runner-launch.ts' +import { reportSpawnRunnerFailure, runSpawnRunner } from './spawn-runner.ts' + +/** + * Run a selector already removed by a packaging bootstrap. + * @param selection - private runner selector or Linux launch-request locator. + */ +export async function runSelectedSubprocessRunner(selection: string): Promise { + try { + await runSpawnRunner(selection, process.argv.slice(2)) + } catch (error) { + await reportSpawnRunnerFailure(selection, error) + } +} + +if (import.meta.main) { + const selection = consumeRunnerSelection() + if (selection === undefined) { + process.exitCode = 127 + } else { + void runSelectedSubprocessRunner(selection) + } +} diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts index d5289682f5..beaeef58ba 100644 --- a/packages/subprocess/subprocess-local/src/index.ts +++ b/packages/subprocess/subprocess-local/src/index.ts @@ -1,10 +1,10 @@ /** - * Local Service Provider for the subprocess capability seam. Each spawn is a detached - * process tree with the spec's per-stream stdio dispositions. Normal disposal - * terminates and joins live trees; Node's synchronous exit phase force-stops - * any trees the service still owns. It has no config: every disposition and - * limit arrives on the spec, so the deployment-varying choices stay with the - * caller's config (the bash executor's, the LSP host's, …). + * Local Service Provider for the subprocess capability seam. Each spawn owns a + * platform-selected managed range with the spec's per-stream stdio dispositions. + * Normal disposal terminates and joins live ranges; Node's synchronous exit + * phase force-stops any ranges the service still owns. It has no config: every + * disposition and limit arrives on the spec, so deployment-varying choices + * stay with the caller's config (the bash executor's, the LSP host's, …). * @module @deepseek-ai/dsh-subprocess-local */ @@ -21,18 +21,32 @@ import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec, } from '@deepseek-ai/dsh-subprocess' -import { childEnv, spawnSubprocess } from './spawn.ts' +import { + bindManagedProcess, + childEnv, + prepareManagedProcessBinding, + spawnSubprocess, + validateSubprocessSpec, +} from './spawn.ts' import type { LocalSubprocessHandle, SpawnInternals } from './spawn.ts' +import { + launchLinuxScope, + prepareLinuxTerminalScope, + probeLinuxManager, + probeLinuxNative, +} from './linux-scope.ts' +import { launchWindowsJob, probeWindowsJob } from './windows-job.ts' +import { targetEnvironment } from './runner-launch.ts' import { createProcessInspector } from './process-inspector.ts' import type { ProcessInspector } from './process-inspector.ts' import { LocalTerminalHandle } from './terminal.ts' /** - * Local subprocess service: detached process trees, Node-shaped stdio + * Local subprocess service: platform-selected managed ranges, Node-shaped stdio * dispositions (raw pipes, inherit, bounded tail-keep collection with spill - * files), credential-scrubbed environment, and tree-scoped signalling with - * SIGTERM→grace→SIGKILL escalation, plus synchronous final termination during - * JavaScript-observable host exit. + * files), credential-scrubbed environment, and provider-owned range signalling. + * POSIX paths stage TERM before KILL; Windows paths terminate immediately. + * JavaScript-observable host exit also performs synchronous final termination. */ export class LocalSubprocessRuntime extends SubprocessRuntime { /** Live handles retained for normal disposal and synchronous host-exit finalization. */ @@ -41,6 +55,10 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { private terminals = new Set() /** Test hook: process, spill, and platform operations forwarded to spawnSubprocess. */ internals: SpawnInternals = {} + /** Provider-lifetime latch suppressing repeated weaker-containment warnings. */ + private fallbackWarningIssued = false + /** Positive-only cache for the expensive Linux bootstrap and scope probe. */ + private linuxDeepProbePassed = false /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */ terminalInspector: ProcessInspector | undefined @@ -50,11 +68,8 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { const onHostExit = (): void => { this.terminateForHostExit() } process.prependListener('exit', onHostExit) return async () => { - try { - await this.disposeManagedProcesses() - } finally { - process.off('exit', onHostExit) - } + await this.disposeManagedProcesses() + process.off('exit', onHostExit) } }, 'local subprocess teardown') } @@ -63,7 +78,7 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { for (const handle of this.live) { try { handle.terminateForHostExit() - } catch (_ordinaryTreeTerminationFailed) { + } catch (_ordinaryRangeTerminationFailed) { // Host exit cannot await or report one target; continue with the rest. } } @@ -77,26 +92,29 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { } private async disposeManagedProcesses(): Promise { - // Terminate (escalating), then await WHOLE-TREE exit — not just the - // direct child's settlement — so even a TERM-trapping descendant cannot + // Request termination, then await MANAGED-RANGE exit — not just the + // direct command's settlement — so even a surviving descendant cannot // outlive the fiber. Keep both sets authoritative while these waits are // pending so a shorter process-level exit bound can still force-kill them. const pending: Promise[] = [] for (const handle of this.live) { handle.terminate() - // Spawn-failure rejections already settled and left the live set. - pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit())) + // Direct result and range observation are independent. Start both so an + // unreadable owner cannot hide behind a result that never settles. + pending.push(Promise.all([ + handle.done.catch(() => {}), + handle.waitForExit(), + ]).then(() => { this.live.delete(handle) })) } for (const terminal of this.terminals) { - pending.push(terminal.terminate()) + pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) })) } const outcomes = await Promise.allSettled(pending) - const failures = outcomes.flatMap(outcome => outcome.status === 'rejected' - ? [outcome.reason as unknown] - : []) + const failures: unknown[] = [] + for (const outcome of outcomes) { + if (outcome.status === 'rejected') failures.push(outcome.reason) + } if (failures.length > 0) this.terminateForHostExit() - this.live.clear() - this.terminals.clear() if (failures.length === 1) throw failures[0] if (failures.length > 1) throw new AggregateError(failures, 'local subprocess teardown failed') } @@ -144,18 +162,70 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { } spawn(spec: SubprocessSpawnSpec): SubprocessHandle { - const handle = spawnSubprocess(spec, this.internals) + validateSubprocessSpec(spec) + const env = targetEnvironment(spec) + const containmentMode = this.selectContainmentMode('ordinary') + let handle: LocalSubprocessHandle + if (containmentMode === 'fallback') { + handle = spawnSubprocess(spec, this.internals) + } else { + const binding = prepareManagedProcessBinding(this.internals) + const launch = containmentMode === 'linux-scope' + ? launchLinuxScope(spec, env) + : launchWindowsJob(spec, env) + handle = bindManagedProcess(spec, launch, binding) + } this.live.add(handle) - // Release ownership only once the whole TREE is gone, not at direct-child + // Release ownership only once the whole managed range is gone, not at direct-child // settlement — a TERM-trapping helper that outlives the leader must stay // owned so teardown can still escalate it. For the common no-survivor // case waitForExit resolves immediately after settlement. const release = (): Promise => handle.waitForExit().then(() => { this.live.delete(handle) }) - handle.done.then(release, release) + void handle.done.then(release, release).catch(() => {}) return handle } + private selectContainmentMode( + kind: 'ordinary' | 'terminal', + ): 'linux-scope' | 'windows-job' | 'fallback' { + const platform = this.internals.platform ?? process.platform + let fallbackReason: string | undefined + if (platform === 'linux') { + const available = this.linuxDeepProbePassed + ? probeLinuxManager() + : probeLinuxNative() + if (available) this.linuxDeepProbePassed = true + if (available) return 'linux-scope' + fallbackReason = 'the current user-systemd scope or private bootstrap is unavailable' + } + if (kind === 'ordinary' && platform === 'win32') { + const available = probeWindowsJob() + if (available) return 'windows-job' + } + this.warnFallback(platform, kind, fallbackReason) + return 'fallback' + } + + private warnFallback( + platform: NodeJS.Platform, + kind: 'ordinary' | 'terminal', + selectedReason?: string, + ): void { + if (this.fallbackWarningIssued) return + this.fallbackWarningIssued = true + const reason = selectedReason ?? (platform === 'darwin' + ? 'macOS has no supported persistent process-range owner' + : platform === 'win32' + ? kind === 'terminal' + ? 'Windows ConPTY remains outside Job containment' + : 'the Win32 Job runner is unavailable' + : `platform ${platform} has no native managed range`) + this.ctx.logger.warn( + `subprocess-local is using weaker process-tree containment because ${reason}; descendants that escape the process group or direct-parent tree are not guaranteed to terminate or delay waitForExit()`, + ) + } + // Local PTY allocation is synchronous, but the provider contract permits remote asynchronous allocation. // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract. async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise { @@ -164,16 +234,54 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { throw new Error('subprocess-local: terminal argv must contain a program') } spec.signal?.throwIfAborted() + const env = targetEnvironment(spec) const options: IPtyForkOptions = { name: 'dumb', rows: spec.rows, cols: spec.cols, cwd: spec.cwd, - env: childEnv(spec.env), + env, } const inspector = this.terminalInspector ?? createProcessInspector() - const terminal = nodePty.spawn(file, [...spec.argv.slice(1)], options) - const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs) + const containmentMode = this.selectContainmentMode('terminal') + const scope = containmentMode === 'linux-scope' + ? prepareLinuxTerminalScope(spec, { + ...env, + PWD: spec.cwd, + TERM: 'dumb', + }) + : undefined + if (scope !== undefined) { + options.cwd = scope.cwd + options.env = scope.env + } + let terminal: nodePty.IPty + try { + terminal = nodePty.spawn( + scope?.command ?? file, + scope?.args ?? [...spec.argv.slice(1)], + options, + ) + } catch (error) { + scope?.cleanup() + throw error + } + // oxlint-disable-next-line eslint/prefer-const -- The owner can query readiness before the handle is published. + let handle: LocalTerminalHandle | undefined + const owner = scope?.bindOwner({ + running: () => handle?.running ?? true, + signal: (signal) => { + try { terminal.kill(signal) } catch { /* Direct process already exited. */ } + }, + }) + handle = new LocalTerminalHandle( + terminal, + inspector, + spec.graceMs, + this.internals.platform ?? process.platform, + owner, + scope?.resolveOutcome, + ) this.terminals.add(handle) const release = async (): Promise => { await handle.terminate() diff --git a/packages/subprocess/subprocess-local/src/linux-execve.ts b/packages/subprocess/subprocess-local/src/linux-execve.ts new file mode 100644 index 0000000000..a5bed81059 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/linux-execve.ts @@ -0,0 +1,71 @@ +/** Lazy libc execve and descriptor bindings used by the one-shot Linux bootstrap. */ + +import { getSystemErrorMessage, getSystemErrorName } from 'node:util' +import koffi from 'koffi' + +/** Replace the current process image while preserving the supplied argv and environment. */ +export type LinuxExecve = ( + file: string, + argv: string[], + env: Record, +) => never + +type NativeExecve = ( + file: string, + argv: Array, + envp: Array, +) => number + +type NativeFcntl = (fd: number, command: number, argument: number) => number + +const STANDARD_FILE_DESCRIPTORS = [0, 1, 2] as const +const F_GETFD = 1 +const F_SETFD = 2 +const FD_CLOEXEC = 1 + +let cachedExecve: LinuxExecve | undefined + +function systemError(errno: number, syscall: string, path?: string): Error { + const uvError = -errno + const code = getSystemErrorName(uvError) + const detail = getSystemErrorMessage(uvError) + const subject = path === undefined ? syscall : `${syscall} '${path}'` + const error = Object.assign(new Error(`${code}: ${detail}, ${subject}`), { + code, + errno: uvError, + syscall, + }) + return path === undefined ? error : Object.assign(error, { path }) +} + +/** + * Load libc's execve and fcntl symbols on first use and retain the native bindings. + * @returns a process-replacing execve operation that throws Node-style errors on failure. + */ +export function loadLinuxExecve(): LinuxExecve { + if (cachedExecve !== undefined) return cachedExecve + const libc = koffi.load(null) + const nativeExecve = libc.func( + 'int execve(const char *pathname, const char **argv, const char **envp)', + ) as NativeExecve + const nativeFcntl = libc.func( + 'int fcntl(int fd, int cmd, int arg)', + ) as NativeFcntl + cachedExecve = (file, argv, env) => { + for (const fd of STANDARD_FILE_DESCRIPTORS) { + const flags = nativeFcntl(fd, F_GETFD, 0) + if (flags === -1) throw systemError(koffi.errno(), 'fcntl') + if ((flags & FD_CLOEXEC) === 0) continue + if (nativeFcntl(fd, F_SETFD, flags & ~FD_CLOEXEC) === -1) { + throw systemError(koffi.errno(), 'fcntl') + } + } + nativeExecve( + file, + [...argv, null], + [...Object.entries(env).map(([key, value]) => `${key}=${value}`), null], + ) + throw systemError(koffi.errno(), 'execve', file) + } + return cachedExecve +} diff --git a/packages/subprocess/subprocess-local/src/linux-scope.ts b/packages/subprocess/subprocess-local/src/linux-scope.ts new file mode 100644 index 0000000000..98b6847db8 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/linux-scope.ts @@ -0,0 +1,503 @@ +/** Linux user-systemd scope launch and managed-range ownership. */ + +import { execFile, spawn, spawnSync } from 'node:child_process' +import { randomBytes } from 'node:crypto' +import { existsSync } from 'node:fs' +import { setTimeout as sleepMs } from 'node:timers/promises' +import type { + SubprocessOutcome, + SubprocessSpawnSpec, + SubprocessTerminalSpawnSpec, +} from '@deepseek-ai/dsh-subprocess' +import { loadLinuxExecve } from './linux-execve.ts' +import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' +import { + cleanupLinuxLaunchFiles, + createLinuxLaunchFiles, + deserializeRunnerError, + readLinuxStartupError, +} from './runner-protocol.ts' +import type { LinuxLaunchFiles } from './runner-protocol.ts' +import { + runnerEnvironment, + runnerInvocationAvailable, + runnerStdio, + spawnRunnerInvocation, +} from './runner-launch.ts' +import type { RunnerInvocation } from './runner-launch.ts' +import { childEnv } from './spawn.ts' + +/** Test seams for systemd command execution. */ +export interface LinuxScopeInternals { + spawn?: typeof spawn + spawnSync?: typeof spawnSync + systemctlQuery?: (command: string, args: readonly string[]) => Promise + systemdRun?: string + systemctl?: string + runnerInvocation?: RunnerInvocation + resolveRunnerInvocation?: () => RunnerInvocation + runnerAvailable?: (invocation: RunnerInvocation) => boolean + loadLinuxExecve?: typeof loadLinuxExecve + sleep?: (delayMs: number, signal?: AbortSignal) => Promise +} + +interface SystemctlResult { + status: number | null + stdout: string + stderr: string + error?: Error +} + +const SYSTEMCTL_TIMEOUT_MS = 5_000 +const SCOPE_INITIAL_POLL_INTERVAL_MS = 50 +const MISSING_UNIT = /\bunit\b[^\r\n]*(?:could not be found|not found|not loaded)/iu + +function managerEnvironment(): NodeJS.ProcessEnv { + const environment = childEnv({ LC_ALL: 'C' }) + delete environment.SYSTEMD_LOG_TARGET + return environment +} + +function quietSystemdEnvironment(): NodeJS.ProcessEnv { + return childEnv({ LC_ALL: 'C', SYSTEMD_LOG_TARGET: 'null' }) +} + +function querySystemctl(command: string, args: readonly string[]): Promise { + return new Promise((resolveResult) => { + execFile(command, [...args], { + encoding: 'utf8', + env: managerEnvironment(), + timeout: SYSTEMCTL_TIMEOUT_MS, + }, (error, stdout, stderr) => { + const code = error === null ? 0 : (error as Error & { code?: string | number }).code + resolveResult({ + status: typeof code === 'number' ? code : null, + stdout, + stderr, + ...error === null ? {} : { error }, + }) + }) + }) +} + +function unitStem(prefix: string): string { + return `${prefix}-${String(process.pid)}-${randomBytes(6).toString('hex')}` +} + +function sleepWithAbort(delayMs: number, signal?: AbortSignal): Promise { + return sleepMs(delayMs, undefined, { signal }) +} + +/** + * Confirm this exact runner entry and libc execve binding without a probe mode. + * @param internals - optional runner and libc-binding seams used by tests. + * @returns whether the bootstrap can enter the final target. + */ +export function probeLinuxBootstrap(internals: LinuxScopeInternals = {}): boolean { + try { + ;(internals.loadLinuxExecve ?? loadLinuxExecve)() + const invocation = internals.runnerInvocation + ?? (internals.resolveRunnerInvocation ?? spawnRunnerInvocation)() + return (internals.runnerAvailable ?? runnerInvocationAvailable)(invocation) + } catch { + return false + } +} + +/** + * Confirm current literal-argv transient-scope support before selecting native launch. + * @param internals - optional systemd command seams used by tests. + * @returns whether the current user manager supports the required scope invocation. + */ +export function probeLinuxScope(internals: LinuxScopeInternals = {}): boolean { + const unitBase = unitStem('dsh-subprocess-probe') + const result = (internals.spawnSync ?? spawnSync)(internals.systemdRun ?? 'systemd-run', [ + '--user', + '--scope', + '--quiet', + '--collect', + '--expand-environment=no', + `--unit=${unitBase}`, + '--', + internals.systemctl ?? 'systemctl', + '--user', + 'show', + `${unitBase}.scope`, + '--property=ActiveState', + '--value', + ], { env: quietSystemdEnvironment(), stdio: 'ignore', timeout: SYSTEMCTL_TIMEOUT_MS }) + return result.error === undefined && result.status === 0 +} + +/** + * Confirm that the current user manager remains reachable after a positive deep probe. + * @param internals - optional systemctl seam used by tests. + * @returns whether one lightweight manager query succeeds. + */ +export function probeLinuxManager(internals: LinuxScopeInternals = {}): boolean { + const result = (internals.spawnSync ?? spawnSync)(internals.systemctl ?? 'systemctl', [ + '--user', + 'show', + '--property=Version', + '--value', + ], { env: managerEnvironment(), stdio: 'ignore', timeout: SYSTEMCTL_TIMEOUT_MS }) + return result.error === undefined && result.status === 0 +} + +/** + * Re-check every Linux native prerequisite for one eligible spawn. + * @param internals - optional native capability seams used by tests. + * @returns whether the Linux native containment path is currently available. + */ +export function probeLinuxNative(internals: LinuxScopeInternals = {}): boolean { + return probeLinuxBootstrap(internals) + && probeLinuxScope(internals) +} + +interface DirectRange { + running(): boolean + signal(signal: 'SIGTERM' | 'SIGKILL'): void +} + +class SystemdScopeOwner implements BoundProcessOwner { + private establishment: 'pending' | 'established' = 'pending' + private stopped = false + private observation: Promise | undefined + private killFailure: Error | undefined + private wakeGeneration = 0 + private wakeWaiter: { generation: number; resolve: () => void } | undefined + + constructor( + private readonly unit: string, + private readonly files: LinuxLaunchFiles, + private readonly direct: DirectRange, + private readonly systemctl: string, + private readonly runSync: typeof spawnSync, + private readonly query: (command: string, args: readonly string[]) => Promise, + private readonly sleep: (delayMs: number, signal?: AbortSignal) => Promise, + ) {} + + signal(signal: 'SIGTERM' | 'SIGKILL'): void { + if (this.stopped) return + this.observeRequestConsumption() + const directFallbackRequired = this.establishment === 'pending' + if (directFallbackRequired && this.direct.running()) this.direct.signal(signal) + const result = this.runSync(this.systemctl, [ + '--user', + 'kill', + '--kill-whom=all', + `--signal=${signal}`, + this.unit, + ], { encoding: 'utf8', env: managerEnvironment(), timeout: SYSTEMCTL_TIMEOUT_MS }) + this.wakeObservation() + if (result.error === undefined && result.status === 0) { + if (signal === 'SIGKILL') this.killFailure = undefined + return + } + if (!directFallbackRequired && this.direct.running()) this.direct.signal(signal) + if (signal === 'SIGKILL') { + const output = `${result.stdout}\n${result.stderr}` + if (!MISSING_UNIT.test(output)) { + this.killFailure = result.error ?? new Error( + `systemctl could not signal ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`, + ) + } + } + } + + terminateForHostExit(): void { + if (this.stopped) return + try { + if (this.direct.running()) this.direct.signal('SIGKILL') + } catch { /* Continue with the native owner. */ } + try { + this.runSync(this.systemctl, [ + '--user', + 'kill', + '--kill-whom=all', + '--signal=SIGKILL', + this.unit, + ], { env: managerEnvironment(), stdio: 'ignore', timeout: SYSTEMCTL_TIMEOUT_MS }) + } catch { + // Host exit cannot report one range; the runtime continues with the rest. + } + } + + private observeRequestConsumption(): void { + if (this.establishment === 'pending' && !existsSync(this.files.requestPath)) { + this.establishment = 'established' + } + } + + private absentUnit(): boolean { + this.observeRequestConsumption() + if (this.establishment === 'established') return false + if (!this.direct.running() && existsSync(this.files.requestPath)) { + return false + } + if (this.killFailure !== undefined) throw this.killFailure + return true + } + + private parseUnitState(stdout: string): { loadState: string; activeState: string } { + const values = new Map() + for (const line of stdout.split(/\r?\n/u)) { + if (line === '') continue + const separator = line.indexOf('=') + if (separator <= 0) { + throw new Error(`systemctl returned malformed state for ${this.unit}: ${JSON.stringify(stdout.trim())}`) + } + const name = line.slice(0, separator) + if (values.has(name)) { + throw new Error(`systemctl returned duplicate ${name} for ${this.unit}`) + } + values.set(name, line.slice(separator + 1)) + } + const loadState = values.get('LoadState') + const activeState = values.get('ActiveState') + if (values.size !== 2 || loadState === undefined || activeState === undefined) { + throw new Error(`systemctl returned incomplete state for ${this.unit}: ${JSON.stringify(stdout.trim())}`) + } + return { loadState, activeState } + } + + private async rangeActive(): Promise { + this.observeRequestConsumption() + const result = await this.query(this.systemctl, [ + '--user', + 'show', + this.unit, + '--property=LoadState', + '--property=ActiveState', + ]) + const output = `${result.stdout}\n${result.stderr}` + if (result.status === 0) { + const { loadState, activeState } = this.parseUnitState(result.stdout) + if (loadState === 'not-found' && activeState === 'inactive') return this.absentUnit() + if (loadState !== 'loaded') { + throw new Error( + `systemctl returned unknown state for ${this.unit}: ${JSON.stringify({ loadState, activeState })}`, + ) + } + this.establishment = 'established' + if (activeState === 'inactive' || activeState === 'failed') return false + if (!['active', 'activating', 'reloading', 'deactivating'].includes(activeState)) { + throw new Error(`systemctl returned unknown ActiveState for ${this.unit}: ${JSON.stringify(activeState)}`) + } + if (this.killFailure !== undefined) throw this.killFailure + return true + } + if (!MISSING_UNIT.test(output)) { + if (result.error !== undefined) throw result.error + throw new Error(`systemctl could not read ${this.unit}: ${output.trim() || `exit ${String(result.status)}`}`) + } + return this.absentUnit() + } + + private wakeObservation(): void { + this.wakeGeneration += 1 + this.wakeWaiter?.resolve() + this.wakeWaiter = undefined + } + + private async waitForPoll(delayMs: number, generation: number): Promise { + if (generation !== this.wakeGeneration) return + const wake = Promise.withResolvers() + const waiter = { generation, resolve: wake.resolve } + const sleepController = new AbortController() + this.wakeWaiter = waiter + try { + await Promise.race([this.sleep(delayMs, sleepController.signal), wake.promise]) + } finally { + sleepController.abort() + if (this.wakeWaiter === waiter) this.wakeWaiter = undefined + } + } + + async waitForExit(): Promise { + if (this.stopped) return + this.observation ??= (async () => { + let pollIntervalMs = SCOPE_INITIAL_POLL_INTERVAL_MS + let generation = this.wakeGeneration + while (await this.rangeActive()) { + await this.waitForPoll(pollIntervalMs, generation) + generation = this.wakeGeneration + // Keep establishment responsive, then reduce systemctl process churn + // while systemd remains the authoritative owner of an active range. + if (this.establishment === 'established') { + pollIntervalMs = Math.min(pollIntervalMs * 2, SYSTEMCTL_TIMEOUT_MS) + } + } + this.stopped = true + })().catch((error: unknown) => { + this.observation = undefined + throw error + }) + await this.observation + } + + cleanup(): void { + cleanupLinuxLaunchFiles(this.files) + } +} + +function scopeArgs(unitBase: string, invocation: RunnerInvocation, argv: readonly string[]): string[] { + return [ + '--user', + '--scope', + '--quiet', + '--collect', + '--expand-environment=no', + `--unit=${unitBase}`, + '--', + ...invocation, + '--', + ...argv, + ] +} + +function directOutcome( + child: ReturnType, + files: LinuxLaunchFiles, +): Promise { + return new Promise((resolveOutcome, rejectOutcome) => { + let settled = false + child.once('error', (error) => { + if (settled) return + settled = true + rejectOutcome(error) + }) + child.once('exit', (exitCode, signal) => { + if (settled) return + settled = true + try { + const startup = readLinuxStartupError(files.startupErrorPath) + if (startup !== undefined) { + rejectOutcome(deserializeRunnerError(startup.error)) + return + } + if (existsSync(files.requestPath)) { + rejectOutcome(new Error('subprocess scope exited before its bootstrap consumed the launch request')) + return + } + resolveOutcome({ exitCode, signal }) + } catch (error) { + /* v8 ignore next -- Node filesystem operations throw Error instances. */ + const failure = error instanceof Error ? error : new Error(String(error)) + rejectOutcome(failure) + } + }) + }) +} + +function signalChildGroup(child: ReturnType, signal: 'SIGTERM' | 'SIGKILL'): void { + try { + process.kill(-(child.pid as number), signal) + } catch { + try { child.kill(signal) } catch { /* The direct process already exited. */ } + } +} + +/** Linux PTY invocation and owner for the exact one-shot scope/bootstrap. */ +export interface LinuxTerminalScopeLaunch { + command: string + args: string[] + cwd: string + env: NodeJS.ProcessEnv + bindOwner: (direct: DirectRange) => BoundProcessOwner + resolveOutcome: (outcome: SubprocessOutcome) => SubprocessOutcome + cleanup: () => void +} + +/** + * Prepare one Linux PTY scope using the same launch request and bootstrap core. + * @param spec - terminal target request. + * @param targetEnv - validated complete target environment. + * @param internals - optional runner and systemd seams used by tests. + * @returns invocation facts and ownership callbacks for node-pty. + */ +export function prepareLinuxTerminalScope( + spec: SubprocessTerminalSpawnSpec, + targetEnv: Record, + internals: LinuxScopeInternals = {}, +): LinuxTerminalScopeLaunch { + const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() + const files = createLinuxLaunchFiles({ cwd: spec.cwd, env: targetEnv }) + const unitBase = unitStem('dsh-terminal') + return { + command: internals.systemdRun ?? 'systemd-run', + args: scopeArgs(unitBase, invocation, spec.argv), + cwd: process.cwd(), + env: runnerEnvironment(files.requestPath, invocation), + bindOwner: direct => new SystemdScopeOwner( + `${unitBase}.scope`, + files, + direct, + internals.systemctl ?? 'systemctl', + internals.spawnSync ?? spawnSync, + internals.systemctlQuery ?? querySystemctl, + internals.sleep ?? sleepWithAbort, + ), + resolveOutcome: (outcome) => { + const startup = readLinuxStartupError(files.startupErrorPath) + if (startup !== undefined) throw deserializeRunnerError(startup.error) + if (existsSync(files.requestPath)) { + throw new Error('terminal scope exited before its bootstrap consumed the launch request') + } + return outcome + }, + cleanup: () => { cleanupLinuxLaunchFiles(files) }, + } +} + +/** + * Launch one ordinary target inside a transient user scope. + * @param spec - ordinary target request. + * @param targetEnv - validated complete target environment. + * @param internals - optional runner and systemd seams used by tests. + * @returns direct streams, result, and managed-scope owner. + */ +export function launchLinuxScope( + spec: SubprocessSpawnSpec, + targetEnv: Record, + internals: LinuxScopeInternals = {}, +): ManagedProcessLaunch { + const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() + const files = createLinuxLaunchFiles({ cwd: spec.cwd, env: targetEnv }) + const unitBase = unitStem('dsh-subprocess') + let child: ReturnType + try { + child = (internals.spawn ?? spawn)(internals.systemdRun ?? 'systemd-run', scopeArgs( + unitBase, + invocation, + spec.argv, + ), { + cwd: process.cwd(), + env: runnerEnvironment(files.requestPath, invocation), + stdio: runnerStdio(spec, false), + detached: true, + }) + } catch (error) { + cleanupLinuxLaunchFiles(files) + throw error + } + const owner = new SystemdScopeOwner( + `${unitBase}.scope`, + files, + { + running: () => child.pid !== undefined && child.exitCode === null && child.signalCode === null, + signal: (signal) => { signalChildGroup(child, signal) }, + }, + internals.systemctl ?? 'systemctl', + internals.spawnSync ?? spawnSync, + internals.systemctlQuery ?? querySystemctl, + internals.sleep ?? sleepWithAbort, + ) + return { + stdin: child.stdin, + stdout: child.stdout, + stderr: child.stderr, + direct: directOutcome(child, files), + owner, + } +} diff --git a/packages/subprocess/subprocess-local/src/managed-owner.ts b/packages/subprocess/subprocess-local/src/managed-owner.ts new file mode 100644 index 0000000000..def20470b1 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/managed-owner.ts @@ -0,0 +1,50 @@ +/** Minimal managed-range ownership bound to one ordinary subprocess handle. */ + +import type { Readable, Writable } from 'node:stream' +import type { SubprocessOutcome } from '@deepseek-ai/dsh-subprocess' + +/** Platform owner used by termination and whole-range settlement. */ +export interface BoundProcessOwner { + /** Signal the managed range; `cancellationReason` is used only before Windows target commit. */ + signal(signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void + /** Wait for the same managed range to become empty; reject when it cannot be observed. */ + waitForExit(): Promise + /** Synchronously force final termination during JavaScript-observable host exit. */ + terminateForHostExit(): void + /** Release provider-private protocol artifacts after outcome and range settlement. */ + cleanup?(): void +} + +/** Platform launch facts consumed by the common stdio and result lifecycle. */ +export interface ManagedProcessLaunch { + stdin: Writable | null + stdout: Readable | null + stderr: Readable | null + direct: Promise + owner: BoundProcessOwner +} + +/** + * Apply an optional abort bound to one shared wait promise. + * @param pending - managed-range wait shared by all callers. + * @param signal - optional caller cancellation signal. + * @returns whether the managed-range wait completed before cancellation. + */ +export async function waitWithAbort(pending: Promise, signal?: AbortSignal): Promise { + if (signal?.aborted) { + void pending.catch(() => {}) + return false + } + if (signal === undefined) { + await pending + return true + } + const aborted = Promise.withResolvers() + const onAbort = (): void => { aborted.resolve(false) } + signal.addEventListener('abort', onAbort, { once: true }) + try { + return await Promise.race([pending.then(() => true), aborted.promise]) + } finally { + signal.removeEventListener('abort', onAbort) + } +} diff --git a/packages/subprocess/subprocess-local/src/runner-launch.ts b/packages/subprocess/subprocess-local/src/runner-launch.ts new file mode 100644 index 0000000000..0da6b95813 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/runner-launch.ts @@ -0,0 +1,305 @@ +/** Parent-side invocation and bootstrap state for the private native runner. */ + +import type { StdioOptions } from 'node:child_process' +import { accessSync, constants as fsConstants, lstatSync, statSync } from 'node:fs' +import { extname, isAbsolute } from 'node:path' +import { inspect } from 'node:util' +import { fileURLToPath } from 'node:url' +import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { childEnv } from './spawn.ts' + +/** The one private environment variable consumed before target state is restored. */ +export const SUBPROCESS_RUNNER_ENV = 'DSH_SUBPROCESS_RUNNER' as const + +/** Sentinel used by the packaged bootstrap for the Windows IPC runner. */ +export const WINDOWS_RUNNER_SELECTION = 'windows' as const + +/** Non-empty command tuple used to launch the private runner entry. */ +export type RunnerInvocation = [string, ...string[]] + +const SOURCE_TSCONFIG_PATH = fileURLToPath(new URL('../../../../tsconfig.base.json', import.meta.url)) +const RUNNER_CONTROL_ENV_PREFIXES = ['NODE_', 'TSX_'] as const + +/** + * Resolve the source, built, or packaged entry that calls the same runner core. + * @returns executable and arguments for the active runtime form. + */ +export function spawnRunnerInvocation(): RunnerInvocation { + if ('pkg' in process) return [process.execPath] + /* v8 ignore next -- built-artifact smoke imports the emitted JavaScript runner entry; + * source-unit coverage cannot change import.meta.url. */ + if (extname(fileURLToPath(import.meta.url)) !== '.ts') { + return [process.execPath, fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-subprocess-local/runner'))] + } + return [ + process.execPath, + '--import', + import.meta.resolve('tsx/esm'), + fileURLToPath(new URL('./bin.ts', import.meta.url)), + ] +} + +/** + * Check the concrete runner executable and entry paths without executing a probe mode. + * @param invocation - resolved executable and runner-entry arguments. + * @returns whether every concrete executable or entry path is accessible. + */ +export function runnerInvocationAvailable(invocation: RunnerInvocation = spawnRunnerInvocation()): boolean { + try { + if (isAbsolute(invocation[0])) accessSync(invocation[0], fsConstants.X_OK) + const entry = invocation.at(-1) + if (entry !== undefined && entry !== invocation[0] && isAbsolute(entry)) { + accessSync(entry, fsConstants.R_OK) + } + return true + } catch { + return false + } +} + +/** + * Build the bootstrap-safe environment; target overrides arrive through request/IPC. + * @param selection - private runner selector or Linux launch-request locator. + * @param invocation - resolved runner invocation whose source form needs the workspace paths map. + * @returns environment for the runner before target state is restored. + */ +export function runnerEnvironment( + selection: string, + invocation?: RunnerInvocation, +): NodeJS.ProcessEnv { + const entry = invocation?.at(-1) + const env = childEnv() + for (const name of Object.keys(env)) { + const normalized = name.toUpperCase() + if (RUNNER_CONTROL_ENV_PREFIXES.some(prefix => normalized.startsWith(prefix))) { + Reflect.deleteProperty(env, name) + } + } + return { + ...env, + [SUBPROCESS_RUNNER_ENV]: selection, + SYSTEMD_LOG_TARGET: 'null', + ...entry?.endsWith('.ts') === true ? { TSX_TSCONFIG_PATH: SOURCE_TSCONFIG_PATH } : {}, + } +} + +/** + * Read and delete the private selector before importing or restoring target state. + * @param env - mutable environment containing the private selector. + * @returns the consumed selector, or undefined when no runner was requested. + */ +export function consumeRunnerSelection(env: NodeJS.ProcessEnv = process.env): string | undefined { + const selection = env[SUBPROCESS_RUNNER_ENV] + Reflect.deleteProperty(env, SUBPROCESS_RUNNER_ENV) + return selection +} + +/** + * Require the private argv delimiter and at least one target argv entry. + * @param argv - private runner arguments. + * @returns copied target argv after the private delimiter. + */ +export function parseRunnerTargetArgv(argv: readonly string[]): string[] { + if (argv[0] !== '--' || argv.length < 2) { + throw new Error('subprocess runner requires target argv after a private -- delimiter') + } + return [...argv.slice(1)] +} + +/** + * Build direct Linux target stdio, or isolated Windows runner stdio with IPC + * on fd 3 and target carriers on fd 4 through fd 6. + * @param spec - ordinary subprocess request whose stdio modes are preserved. + * @param ipc - whether to isolate the runner and add its private Node IPC descriptor. + * @param stdinCarrier - runner fd 4 carrier; Windows ignore passes an opened null-device fd. + * @returns child-process stdio options for the runner. + */ +export function runnerStdio( + spec: SubprocessSpawnSpec, + ipc: boolean, + stdinCarrier: 'pipe' | number = 'pipe', +): StdioOptions { + const targetStdio: StdioOptions = [ + spec.stdio.stdin === 'ignore' ? 'ignore' : 'pipe', + spec.stdio.stdout === 'inherit' ? 'inherit' : 'pipe', + spec.stdio.stderr === 'inherit' ? 'inherit' : 'pipe', + ] + if (!ipc) return targetStdio + return [ + 'ignore', + 'ignore', + 'ignore', + 'ipc', + stdinCarrier, + spec.stdio.stdout === 'inherit' ? 1 : 'pipe', + spec.stdio.stderr === 'inherit' ? 2 : 'pipe', + ] +} + +function windowsEnvironmentValue( + env: Readonly>, + name: 'PATH' | 'NODEFAULTCURRENTDIRECTORYINEXEPATH', +): string | undefined { + for (const key of Object.keys(env).sort()) { + if (key.toUpperCase() === name) return env[key] + } + return undefined +} + +function executableCandidateExists(candidate: string): boolean { + try { + return !statSync(candidate).isDirectory() + } catch { + try { + const entry = lstatSync(candidate) + return entry.isFile() || entry.isSymbolicLink() + } catch { + return false + } + } +} + +function windowsPathDirectories(path: string): string[] { + const directories: string[] = [] + let start = 0 + while (start < path.length) { + if (path.charAt(start) === ';') { + start += 1 + continue + } + const quote = path.charAt(start) + const quoted = quote === '"' || quote === "'" + const quoteEnd = quoted + ? path.indexOf(quote, start + 1) + : -1 + const separator = path.indexOf(';', quoted ? quoteEnd < 0 ? path.length : quoteEnd : start) + const end = separator < 0 ? path.length : separator + let directory = path.slice(start, end) + if (directory.startsWith('"') || directory.startsWith("'")) directory = directory.slice(1) + if (directory.endsWith('"') || directory.endsWith("'")) directory = directory.slice(0, -1) + if (directory.length > 0) directories.push(directory) + start = end + 1 + } + return directories +} + +function windowsFileNameStart(command: string): number { + let start = command.length + while (start > 0 && !/[\\/:]/u.test(command.charAt(start - 1))) start -= 1 + return start +} + +function windowsSearchPathJoin(directory: string, name: string, cwd: string): string { + let prefix = cwd + let adjustedDirectory = directory + const slash = (value: string): boolean => value === '\\' || value === '/' + if (directory.length > 2 && slash(directory.charAt(0)) && slash(directory.charAt(1))) { + prefix = '' + } else if (directory.length >= 1 && slash(directory.charAt(0))) { + prefix = cwd.slice(0, 2) + } else if ( + directory.length >= 2 + && directory.charAt(1) === ':' + && (directory.length < 3 || !slash(directory.charAt(2))) + ) { + if (cwd.length < 2 || cwd.slice(0, 2).toLowerCase() !== directory.slice(0, 2).toLowerCase()) { + prefix = '' + } else { + adjustedDirectory = directory.slice(2) + } + } else if (directory.length > 2 && directory.charAt(1) === ':') { + prefix = '' + } + + const append = (base: string, part: string): string => { + if (base.length === 0 || part.length === 0) return base + part + return /[\\/:]$/u.test(base) ? base + part : `${base}\\${part}` + } + return append(append(prefix, adjustedDirectory), name) +} + +function windowsExecutableNames(command: string, name: string): string[] { + const dot = name.indexOf('.') + const hasExtension = dot >= 0 && dot < name.length - 1 + const separator = name.endsWith('.') ? '' : '.' + return [ + ...hasExtension ? [command] : [], + `${command}${separator}com`, + `${command}${separator}exe`, + ] +} + +/** + * Resolve the executable path with libuv/Node Windows spawn search order while + * preserving the caller's original command-line argv entry separately. + * @param command - original target argv[0]. + * @param cwd - final target working directory used for relative search roots. + * @param env - final target environment containing the child PATH. + * @param exists - injectable non-directory candidate probe used by tests. + * @param currentEnv - runner environment supplying PATH fallback and cwd-search policy. + * @returns a resolved application name suitable for `CreateProcessW`, or undefined when no candidate exists. + */ +export function resolveWindowsExecutable( + command: string, + cwd: string, + env: Readonly>, + exists: (candidate: string) => boolean = executableCandidateExists, + currentEnv: Readonly> = process.env, +): string | undefined { + const nameStart = windowsFileNameStart(command) + const directory = command.slice(0, nameStart) + const name = command.slice(nameStart) + const hasPath = nameStart !== 0 + const roots: string[] = [] + if (hasPath) { + roots.push(directory) + } else { + if (windowsEnvironmentValue(currentEnv, 'NODEFAULTCURRENTDIRECTORYINEXEPATH') === undefined) { + roots.push('') + } + const path = windowsEnvironmentValue(env, 'PATH') ?? windowsEnvironmentValue(currentEnv, 'PATH') ?? '' + roots.push(...windowsPathDirectories(path)) + } + + for (const root of roots) { + const base = windowsSearchPathJoin(root, name, cwd) + for (const candidate of windowsExecutableNames(base, name)) { + if (exists(candidate)) return candidate + } + } + + return undefined +} + +function throwNullByteError(property: string, value: string, argument: boolean): never { + const subject = argument ? `The argument '${property}'` : `The property '${property}'` + const error = new TypeError(`${subject} must be a string without null bytes. Received ${inspect(value)}`) + Object.assign(error, { code: 'ERR_INVALID_ARG_VALUE' }) + throw error +} + +function validateNoNullByte(property: string, value: string, argument = false): void { + if (value.includes('\0')) throwNullByteError(property, value, argument) +} + +/** + * Materialize and synchronously validate the final target environment. + * @param spec - final target argv, cwd, and environment overrides. + * @returns complete target environment after Node-equivalent validation. + */ +export function targetEnvironment( + spec: Pick, +): Record { + spec.argv.forEach((value, index) => { + validateNoNullByte(index === 0 ? 'file' : `args[${String(index - 1)}]`, value, true) + }) + validateNoNullByte('options.cwd', spec.cwd) + const env = Object.fromEntries( + Object.entries(childEnv(spec.env)).filter((entry): entry is [string, string] => entry[1] !== undefined), + ) + for (const [key, value] of Object.entries(env)) { + validateNoNullByte(`options.env['${key}']`, key) + validateNoNullByte(`options.env['${key}']`, value) + } + return env +} diff --git a/packages/subprocess/subprocess-local/src/runner-protocol.ts b/packages/subprocess/subprocess-local/src/runner-protocol.ts new file mode 100644 index 0000000000..90d09add3e --- /dev/null +++ b/packages/subprocess/subprocess-local/src/runner-protocol.ts @@ -0,0 +1,269 @@ +/** Closed private transports shared by the native subprocess runner. */ + +import { + chmodSync, + existsSync, + lstatSync, + mkdtempSync, + readFileSync, + rmdirSync, + unlinkSync, + writeFileSync, +} from 'node:fs' +import { tmpdir } from 'node:os' +import { basename, dirname, isAbsolute, join } from 'node:path' + +/** Target state restored by the Linux bootstrap after systemd establishes the scope. */ +export interface LinuxLaunchRequest { + cwd: string + env: Record +} + +/** Bounded Node-shaped error fields allowed across a private runner boundary. */ +export interface SerializedRunnerError { + name: string + message: string + code?: string + syscall?: string + path?: string +} + +/** A Linux pre-exec failure published beside its consumed request. */ +export type LinuxStartupError = + { type: 'error'; error: SerializedRunnerError } + +/** The only parent-to-runner start message on Windows. */ +export interface WindowsStartRequest { + type: 'start' + cwd: string + env: Record +} + +/** The only parent-to-runner control message on Windows. */ +export interface WindowsTerminateRequest { + type: 'terminate' +} + +/** Exactly one direct-result branch is sent by a connected Windows runner. */ +export type WindowsRunnerResult = + | { type: 'target-exit'; exitCode: number } + | { type: 'error'; error: SerializedRunnerError } + +/** Private paths owned by one Linux ordinary or PTY spawn. */ +export interface LinuxLaunchFiles { + directory: string + requestPath: string + startupErrorPath: string +} + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === 'object' && !Array.isArray(value) +} + +function hasExactKeys(value: Record, required: readonly string[], optional: readonly string[] = []): boolean { + const allowed = new Set([...required, ...optional]) + return required.every(key => Object.hasOwn(value, key)) + && Object.keys(value).every(key => allowed.has(key)) +} + +function isStringRecord(value: unknown): value is Record { + return isRecord(value) && Object.values(value).every(entry => typeof entry === 'string') +} + +function isSerializedRunnerError(value: unknown): value is SerializedRunnerError { + if (!isRecord(value) || !hasExactKeys( + value, + ['name', 'message'], + ['code', 'syscall', 'path'], + )) return false + return typeof value.name === 'string' + && typeof value.message === 'string' + && (value.code === undefined || typeof value.code === 'string') + && (value.syscall === undefined || typeof value.syscall === 'string') + && (value.path === undefined || typeof value.path === 'string') +} + +function parseErrorResult(value: Record): LinuxStartupError { + if (!hasExactKeys(value, ['type', 'error']) || !isSerializedRunnerError(value.error)) { + throw new Error('subprocess runner emitted an invalid error result') + } + if (value.type !== 'error') { + throw new Error('subprocess runner emitted an unknown error result') + } + return { type: 'error', error: value.error } +} + +/** + * Create a private 0700 directory and one complete 0600 launch request. + * @param request - target cwd and complete environment for the bootstrap. + * @returns private paths owned by this launch. + */ +export function createLinuxLaunchFiles(request: LinuxLaunchRequest): LinuxLaunchFiles { + const directory = mkdtempSync(join(tmpdir(), 'dsh-subprocess-launch-')) + const files = { + directory, + requestPath: join(directory, 'launch-request.json'), + startupErrorPath: join(directory, 'startup-error.json'), + } + try { + chmodSync(directory, 0o700) + writeFileSync(files.requestPath, JSON.stringify(request), { flag: 'wx', mode: 0o600 }) + return files + } catch (error) { + cleanupLinuxLaunchFiles(files) + throw error + } +} + +/** + * Derive the only permitted startup-error path from an absolute request locator. + * @param requestPath - absolute path to the private launch-request file. + * @returns validated sibling paths for this launch. + */ +export function linuxLaunchFilesFromLocator(requestPath: string): LinuxLaunchFiles { + if (!isAbsolute(requestPath) || basename(requestPath) !== 'launch-request.json') { + throw new Error('subprocess runner received an invalid Linux launch-request locator') + } + const directory = dirname(requestPath) + return { directory, requestPath, startupErrorPath: join(directory, 'startup-error.json') } +} + +/** + * Strictly read and remove a one-shot Linux launch request. + * @param requestPath - private launch-request path to consume. + * @returns validated target cwd and environment. + */ +export function consumeLinuxLaunchRequest(requestPath: string): LinuxLaunchRequest { + const text = readFileSync(requestPath, 'utf8') + unlinkSync(requestPath) + const value: unknown = JSON.parse(text) + if (!isRecord(value) || !hasExactKeys(value, ['cwd', 'env']) + || typeof value.cwd !== 'string' || !isStringRecord(value.env)) { + throw new Error('subprocess runner received an invalid Linux launch request') + } + return { cwd: value.cwd, env: value.env } +} + +/** + * Publish one strict 0600 Linux pre-exec error. + * @param files - private paths for this launch. + * @param error - bounded spawn or runner failure to publish. + */ +export function writeLinuxStartupError(files: LinuxLaunchFiles, error: LinuxStartupError): void { + writeFileSync(files.startupErrorPath, JSON.stringify(error), { flag: 'wx', mode: 0o600 }) +} + +/** + * Read the Linux pre-exec error, if the bootstrap published one. + * @param path - expected startup-error path. + * @returns the validated failure, or undefined when none was published. + */ +export function readLinuxStartupError(path: string): LinuxStartupError | undefined { + if (!existsSync(path)) return undefined + const value: unknown = JSON.parse(readFileSync(path, 'utf8')) + if (!isRecord(value)) throw new Error('subprocess runner emitted an invalid startup error') + return parseErrorResult(value) +} + +/** + * Strictly parse the single Windows start message. + * @param value - untrusted IPC payload. + * @returns validated target start request. + */ +export function parseWindowsStartRequest(value: unknown): WindowsStartRequest { + if (!isRecord(value) || !hasExactKeys(value, ['type', 'cwd', 'env']) + || value.type !== 'start' || typeof value.cwd !== 'string' || !isStringRecord(value.env)) { + throw new Error('subprocess runner received an invalid Windows start request') + } + return { type: 'start', cwd: value.cwd, env: value.env } +} + +/** + * Return true only for the exact, payload-free Windows terminate control. + * @param value - untrusted IPC payload. + * @returns whether the payload is the exact terminate request. + */ +export function isWindowsTerminateRequest(value: unknown): value is WindowsTerminateRequest { + return isRecord(value) && hasExactKeys(value, ['type']) && value.type === 'terminate' +} + +/** + * Strictly parse one of the two Windows direct-result branches. + * @param value - untrusted IPC payload. + * @returns validated direct-result message. + */ +export function parseWindowsRunnerResult(value: unknown): WindowsRunnerResult { + if (!isRecord(value) || typeof value.type !== 'string') { + throw new Error('subprocess runner emitted an invalid Windows result') + } + if (value.type === 'error') return parseErrorResult(value) + if (value.type === 'target-exit') { + const validExitCode = typeof value.exitCode === 'number' + && Number.isSafeInteger(value.exitCode) + && value.exitCode >= 0 + if (!hasExactKeys(value, ['type', 'exitCode']) || !validExitCode) { + throw new Error('subprocess runner emitted an invalid target-exit result') + } + return { + type: 'target-exit', + exitCode: value.exitCode as number, + } + } + throw new Error(`subprocess runner emitted an unknown Windows result: ${value.type}`) +} + +/** + * Convert an unknown failure into the bounded cross-process error record. + * @param error - failure caught at the process boundary. + * @returns bounded serializable error fields. + */ +export function serializeRunnerError(error: unknown): SerializedRunnerError { + const source = error instanceof Error ? error : new Error(String(error)) + const node = source as NodeJS.ErrnoException & { path?: string } + return { + name: source.name, + message: source.message, + ...typeof node.code === 'string' ? { code: node.code } : {}, + ...typeof node.syscall === 'string' ? { syscall: node.syscall } : {}, + ...typeof node.path === 'string' ? { path: node.path } : {}, + } +} + +/** + * Rebuild a Node-shaped Error from a strict runner record. + * @param serialized - validated bounded error fields. + * @returns reconstructed Error with supported Node fields. + */ +export function deserializeRunnerError(serialized: SerializedRunnerError): Error { + const error = new Error(serialized.message) + error.name = serialized.name + return Object.assign(error, { + ...serialized.code === undefined ? {} : { code: serialized.code }, + ...serialized.syscall === undefined ? {} : { syscall: serialized.syscall }, + ...serialized.path === undefined ? {} : { path: serialized.path }, + }) +} + +/** + * Best-effort removal of only the private paths created for this Linux spawn. + * @param files - exact private paths owned by this launch. + */ +export function cleanupLinuxLaunchFiles(files: LinuxLaunchFiles): void { + try { + if (lstatSync(files.directory).isSymbolicLink()) { + unlinkSync(files.directory) + return + } + for (const path of [ + files.requestPath, + files.startupErrorPath, + ]) { + try { unlinkSync(path) } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + } + } + rmdirSync(files.directory) + } catch { + // Crash residue remains private and no later spawn reuses this directory. + } +} diff --git a/packages/subprocess/subprocess-local/src/spawn-runner.ts b/packages/subprocess/subprocess-local/src/spawn-runner.ts new file mode 100644 index 0000000000..cc332ae8a5 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/spawn-runner.ts @@ -0,0 +1,486 @@ +/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */ + +import { closeSync } from 'node:fs' +import { + closeHandleChecked, + isJobEmpty, + loadWin32ProcessBindings, + pollProcessExit, + spawnCurrentTokenJobProcess, + terminateJob, + Win32Error, +} from '@deepseek-ai/dsh-win32-process' +import type { + CurrentTokenProcessBindings, + NativePtr, +} from '@deepseek-ai/dsh-win32-process' +import { loadLinuxExecve } from './linux-execve.ts' +import { + consumeLinuxLaunchRequest, + isWindowsTerminateRequest, + linuxLaunchFilesFromLocator, + parseWindowsStartRequest, + serializeRunnerError, + writeLinuxStartupError, +} from './runner-protocol.ts' +import type { + LinuxLaunchFiles, + SerializedRunnerError, + WindowsRunnerResult, + WindowsStartRequest, +} from './runner-protocol.ts' +import { + parseRunnerTargetArgv, + resolveWindowsExecutable, + SUBPROCESS_RUNNER_ENV, + WINDOWS_RUNNER_SELECTION, +} from './runner-launch.ts' + +type RunnerHost = Pick & { + send?: NodeJS.Process['send'] +} + +/** Injectable operations used by the protocol-owner tests. */ +export interface SpawnRunnerInternals { + execve(file: string, argv: string[], env: Record): never + loadWin32ProcessBindings(): CurrentTokenProcessBindings + spawnCurrentTokenJobProcess: typeof spawnCurrentTokenJobProcess + closeFileDescriptor(fileDescriptor: number): void + resolveWindowsExecutable: typeof resolveWindowsExecutable + pollProcessExit: typeof pollProcessExit + isJobEmpty: typeof isJobEmpty + terminateJob: typeof terminateJob + closeHandleChecked: typeof closeHandleChecked +} + +const defaultInternals: SpawnRunnerInternals = { + /* v8 ignore next -- source/built/packaged subprocess smoke executes this only in a replaceable child process. */ + execve: (file, argv, env) => loadLinuxExecve()(file, argv, env), + loadWin32ProcessBindings, + spawnCurrentTokenJobProcess, + closeFileDescriptor: closeSync, + resolveWindowsExecutable, + pollProcessExit, + isJobEmpty, + terminateJob, + closeHandleChecked, +} + +const NODE_SPAWN_DETAIL_CODES = new Set(['EACCES', 'ENOENT']) +const WINDOWS_SPAWN_ERROR_CODES = new Map([ + [2, 'ENOENT'], + [3, 'ENOENT'], + [267, 'ENOENT'], + [5, 'EPERM'], + [193, 'EFTYPE'], + [740, 'EACCES'], +]) + +function nodeSpawnError( + syscall: string, + code: string, + path?: string, +): SerializedRunnerError { + const message = `${syscall} ${code}` + return { + name: 'Error', + message, + code, + syscall, + ...path === undefined ? {} : { path }, + } +} + +function asSpawnError( + error: unknown, + program: string, +): SerializedRunnerError { + const serialized = serializeRunnerError(error) + if (!(error instanceof Win32Error)) { + return serialized.code === undefined + ? serialized + : nodeSpawnError(`spawn ${program}`, serialized.code, program) + } + const code = WINDOWS_SPAWN_ERROR_CODES.get(error.win32Code) ?? 'UNKNOWN' + if (NODE_SPAWN_DETAIL_CODES.has(code)) { + return nodeSpawnError(`spawn ${program}`, code, program) + } + return nodeSpawnError('spawn', code) +} + +function windowsPathNotFoundError(program: string): SerializedRunnerError { + return nodeSpawnError(`spawn ${program}`, 'ENOENT', program) +} + +function windowsStartCancelledError(): SerializedRunnerError { + return { + name: 'Error', + message: 'subprocess target start was cancelled', + } +} + +function linuxPathNotFoundError(program: string): NodeJS.ErrnoException { + return Object.assign(new Error(`spawn ${program} ENOENT`), { + code: 'ENOENT', + errno: -2, + syscall: `spawn ${program}`, + path: program, + spawnargs: [] as string[], + }) +} + +function execLinuxFile( + file: string, + argv: string[], + env: Record, + internals: SpawnRunnerInternals, +): never { + try { + return internals.execve(file, argv, env) + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOEXEC') throw error + return internals.execve('/bin/sh', ['/bin/sh', file, ...argv.slice(1)], env) + } +} + +function execLinuxTarget( + request: { cwd: string; env: Record }, + argv: string[], + internals: SpawnRunnerInternals, +): never { + const program = argv[0] as string + if (program.includes('/')) return execLinuxFile(program, argv, request.env, internals) + const path = request.env.PATH ?? '/usr/bin:/bin' + let permissionFailure: Error | undefined + for (const directory of path.split(':')) { + const root = directory.startsWith('/') + ? directory + : `${request.cwd}${request.cwd.endsWith('/') ? '' : '/'}${directory}` + const candidate = `${root}${root.endsWith('/') ? '' : '/'}${program}` + try { + return execLinuxFile(candidate, argv, request.env, internals) + } catch (error) { + const code = (error as NodeJS.ErrnoException).code + if (code === 'EACCES') { + permissionFailure ??= error as Error + continue + } + if (code === 'ENOENT' || code === 'ENOTDIR') continue + throw error + } + } + throw permissionFailure ?? linuxPathNotFoundError(program) +} + +function runLinux( + locator: string, + argv: string[], + host: RunnerHost, + internals: SpawnRunnerInternals, +): void { + const files = linuxLaunchFilesFromLocator(locator) + let request: ReturnType + try { + request = consumeLinuxLaunchRequest(files.requestPath) + } catch (error) { + writeLinuxStartupError(files, { type: 'error', error: serializeRunnerError(error) }) + host.exitCode = 127 + return + } + try { + host.chdir(request.cwd) + execLinuxTarget({ ...request, cwd: host.cwd() }, argv, internals) + } catch (error) { + writeLinuxStartupError(files, { + type: 'error', + error: asSpawnError(error, argv[0] as string), + }) + host.exitCode = 127 + } +} + +function sendMessage(host: RunnerHost, result: WindowsRunnerResult): Promise { + return new Promise((resolve, reject) => { + if (!host.connected || host.send === undefined) { + reject(new Error('subprocess runner IPC is not connected')) + return + } + try { + host.send(result, (error) => { + if (error === null) resolve() + else reject(error) + }) + } catch (error) { + /* v8 ignore next -- process.send throws Error instances. */ + const failure = error instanceof Error ? error : new Error(String(error)) + reject(failure) + } + }) +} + +class WindowsJobRunner { + private api: CurrentTokenProcessBindings | undefined + private processHandle: NativePtr | undefined + private jobHandle: NativePtr | undefined + private pollTimer: ReturnType | undefined + private startSeen = false + private terminateRequested = false + private resultStarted = false + private resultDelivered = false + private finished = false + private readonly completion = Promise.withResolvers() + + constructor( + private readonly argv: string[], + private readonly host: RunnerHost, + private readonly internals: SpawnRunnerInternals, + ) {} + + run(): Promise { + if (!this.host.connected || this.host.send === undefined) { + this.finish(127) + return this.completion.promise + } + this.host.on('message', this.onMessage) + this.host.once('disconnect', this.onDisconnect) + return this.completion.promise + } + + private readonly onMessage = (value: unknown): void => { + if (this.finished) return + if (isWindowsTerminateRequest(value)) { + this.requestTermination() + return + } + if (this.startSeen) { + void this.runnerFailure(new Error('subprocess runner received more than one Windows start request')) + return + } + let request: WindowsStartRequest + try { + request = parseWindowsStartRequest(value) + } catch (error) { + void this.runnerFailure(error) + return + } + this.startSeen = true + void this.start(request) + } + + private readonly onDisconnect = (): void => { + if (this.finished) return + this.releaseOwnedJob() + this.finish(127, false) + } + + private async start(request: WindowsStartRequest): Promise { + if (this.terminateRequested) { + await this.publishTerminalResult({ type: 'error', error: windowsStartCancelledError() }, 0) + return + } + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + if (this.finished) return + // IPC may set this field while start() is suspended above. + // oxlint-disable-next-line typescript/no-unnecessary-condition + if (this.terminateRequested) { + await this.publishTerminalResult({ type: 'error', error: windowsStartCancelledError() }, 0) + return + } + try { + const [command, ...args] = this.argv + const applicationName = this.internals.resolveWindowsExecutable( + command as string, + request.cwd, + request.env, + undefined, + { ...this.host.env }, + ) + if (applicationName === undefined) { + await this.publishTerminalResult({ + type: 'error', + error: windowsPathNotFoundError(command as string), + }, 0) + return + } + this.api = this.internals.loadWin32ProcessBindings() + const spawned = this.internals.spawnCurrentTokenJobProcess(this.api, { + command: command as string, + applicationName, + args, + cwd: request.cwd, + env: request.env, + stdio: { stdin: 4, stdout: 5, stderr: 6 }, + }) + this.processHandle = spawned.process + this.jobHandle = spawned.job + for (const fileDescriptor of [4, 5, 6]) { + this.internals.closeFileDescriptor(fileDescriptor) + } + this.pollTimer = setInterval(() => { this.poll() }, 10) + } catch (error) { + if (this.jobHandle === undefined && error instanceof Win32Error && error.api === 'CreateProcessW') { + await this.publishTerminalResult({ + type: 'error', + error: asSpawnError(error, this.argv[0] as string), + }, 0) + return + } + await this.runnerFailure(error) + } + } + + private requestTermination(): void { + if (this.terminateRequested) return + this.terminateRequested = true + try { + this.terminateOwnedJob() + } catch (error) { + void this.runnerFailure(error) + } + } + + private terminateOwnedJob(): void { + const job = this.jobHandle + if (job === undefined) return + /* v8 ignore next -- a Job handle is assigned only after the bindings are loaded; + * the guard above is the only reachable empty-owner state. */ + if (this.api === undefined) return + this.internals.terminateJob(this.api, job, 1) + } + + private poll(): void { + if (this.finished) return + /* v8 ignore next -- poll is installed only after start() stores the bindings; retained as a defensive invariant guard. */ + if (this.api === undefined) return + try { + if (this.processHandle !== undefined) { + const exitCode = this.internals.pollProcessExit(this.api, this.processHandle) + if (exitCode !== undefined) { + this.internals.closeHandleChecked(this.api, this.processHandle, 'ordinary direct process') + this.processHandle = undefined + void this.publishTerminalResult({ type: 'target-exit', exitCode }) + } + } + if (this.jobHandle !== undefined && this.internals.isJobEmpty(this.api, this.jobHandle)) { + this.internals.closeHandleChecked(this.api, this.jobHandle, 'ordinary process Job') + this.jobHandle = undefined + if (this.resultDelivered) this.finish(0) + } + } catch (error) { + void this.runnerFailure(error) + } + } + + private async publishTerminalResult(result: WindowsRunnerResult, exitCode?: number): Promise { + /* v8 ignore next -- each state transition has a single result call site; the guard contains only re-entrant internal defects. */ + if (this.finished || this.resultStarted) return + this.resultStarted = true + try { + await sendMessage(this.host, result) + this.resultDelivered = true + } catch { + this.releaseOwnedJob() + this.finish(127, false) + return + } + if (exitCode !== undefined) { + this.finish(exitCode) + return + } + if (this.jobHandle === undefined) this.finish(0) + } + + private async runnerFailure(error: unknown): Promise { + /* v8 ignore next -- callers stop/detach on finish; this guard contains only an already-queued internal callback. */ + if (this.finished) return + if (!this.resultStarted) { + this.resultStarted = true + try { + await sendMessage(this.host, { type: 'error', error: serializeRunnerError(error) }) + this.resultDelivered = true + } catch { + // The disconnected parent observes runner infrastructure failure. + } + } + this.releaseOwnedJob() + this.finish(127) + } + + private releaseOwnedJob(): void { + if (this.pollTimer !== undefined) clearInterval(this.pollTimer) + this.pollTimer = undefined + const api = this.api + if (api === undefined) return + if (this.jobHandle !== undefined) { + try { this.internals.terminateJob(api, this.jobHandle, 1) } catch { /* Continue to kill-on-close. */ } + try { this.internals.closeHandleChecked(api, this.jobHandle, 'ordinary process Job cleanup') } catch { /* Best effort after failure. */ } + this.jobHandle = undefined + } + if (this.processHandle !== undefined) { + try { this.internals.closeHandleChecked(api, this.processHandle, 'ordinary direct process cleanup') } catch { /* Best effort after failure. */ } + this.processHandle = undefined + } + } + + private finish(exitCode: number, disconnect = true): void { + if (this.finished) return + this.finished = true + if (this.pollTimer !== undefined) clearInterval(this.pollTimer) + this.pollTimer = undefined + this.host.off('message', this.onMessage) + this.host.off('disconnect', this.onDisconnect) + this.host.exitCode = exitCode + if (disconnect && this.host.connected) this.host.disconnect() + this.completion.resolve() + } +} + +/** + * Execute the selected Linux bootstrap or Windows Job runner. + * @param selection - Windows sentinel or Linux launch-request locator. + * @param argv - private runner arguments beginning with the target delimiter. + * @param host - process transport and lifecycle host. + * @param internals - native and filesystem operations used by the runner. + */ +export async function runSpawnRunner( + selection: string, + argv: readonly string[], + host: RunnerHost = process, + internals: SpawnRunnerInternals = defaultInternals, +): Promise { + Reflect.deleteProperty(host.env, SUBPROCESS_RUNNER_ENV) + const targetArgv = parseRunnerTargetArgv(argv) + if (selection === WINDOWS_RUNNER_SELECTION) { + await new WindowsJobRunner(targetArgv, host, internals).run() + return + } + runLinux(selection, targetArgv, host, internals) +} + +/** + * Best-effort reporting for failures before the selected runner established its owner. + * @param selection - Windows sentinel, Linux launch-request locator, or no selection. + * @param error - failure raised before normal runner settlement. + * @param host - process transport and lifecycle host. + */ +export async function reportSpawnRunnerFailure( + selection: string | undefined, + error: unknown, + host: RunnerHost = process, +): Promise { + if (selection === WINDOWS_RUNNER_SELECTION) { + try { await sendMessage(host, { type: 'error', error: serializeRunnerError(error) }) } catch { /* No transport remains. */ } + host.exitCode = 127 + if (host.connected) host.disconnect() + return + } + if (selection !== undefined) { + try { + const files: LinuxLaunchFiles = linuxLaunchFilesFromLocator(selection) + writeLinuxStartupError(files, { type: 'error', error: serializeRunnerError(error) }) + } catch { + // The parent will report an unconsumed request or missing runner result. + } + } + host.exitCode = 127 +} diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts index 03f1451c64..9079716c71 100644 --- a/packages/subprocess/subprocess-local/src/spawn.ts +++ b/packages/subprocess/subprocess-local/src/spawn.ts @@ -1,9 +1,10 @@ /** - * Process plumbing for the local subprocess service: detached process-tree - * spawn with per-stream stdio dispositions, tail-keep collection with spill - * files, tree-scoped signalling (POSIX groups; Windows taskkill), and the - * SIGTERM→SIGKILL escalation. This layer reacts to an abort signal; callers - * own deadlines, teardown ladders, and cause classification. + * Process plumbing for the local subprocess service: ordinary process launch + * with per-stream stdio dispositions, tail-keep collection with spill + * files, provider-owned range signalling, and common termination scheduling. + * POSIX owners stage TERM before KILL; Windows owners terminate immediately. + * This layer reacts to an abort signal; callers own deadlines, teardown + * ladders, and cause classification. * @module dsh-subprocess-local/spawn */ @@ -24,6 +25,8 @@ import type { SubprocessOutputMode, SubprocessSpawnSpec, } from '@deepseek-ai/dsh-subprocess' +import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' +import { waitWithAbort } from './managed-owner.ts' import { linuxProcessGroupHasLiveMembers } from './process-inspector.ts' type SpawnProcess = ( @@ -113,6 +116,17 @@ process.once('exit', () => { try { rmdirSync(defaultSpillDir) } catch { /* best-effort: ENOENT/ENOTEMPTY/EBUSY/EPERM must not change the exit code. */ } }) +/** + * Prepare fallible output storage before starting a managed native process. + * @param internals - optional caller-owned spill directory. + * @returns binding inputs whose spill directory is ready for use. + */ +export function prepareManagedProcessBinding( + internals: Pick = {}, +): { spillDir: string } { + return { spillDir: internals.spillDir ?? privateSpillDir() } +} + /** * Collects one stream with a bounded in-memory tail. With a spill cap, on * first overflow a spill file is created and every chunk (including those @@ -275,12 +289,12 @@ export class OutputCollector { /** * Send `sig` to a detached POSIX process group. Never throws: delivery races * process exit and may run in a timer callback, so failures are contained and - * a non-positive pid is a no-op. - * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op. + * a missing pid is a no-op. + * @param pid - the group leader's pid, when the spawn published one. * @param sig - the signal to deliver to the whole group. */ -export function killGroup(pid: number, sig: NodeJS.Signals): void { - if (pid <= 0) return +export function killGroup(pid: number | undefined, sig: NodeJS.Signals): void { + if (pid === undefined) return try { process.kill(-pid, sig) } catch { @@ -293,10 +307,10 @@ export function killGroup(pid: number, sig: NodeJS.Signals): void { * POSIX group signalling — delivery races tree exit, so an absent tree, a * nonzero status, or a missing taskkill binary must not break idempotent * teardown. - * @param pid - root process id; non-positive is a no-op. + * @param pid - root process id, when the spawn published one. */ -export function taskkillProcessTree(pid: number): void { - if (pid <= 0) return +export function taskkillProcessTree(pid: number | undefined): void { + if (pid === undefined || pid <= 0) return // Outcome deliberately unchecked: an already-absent tree (status 128), exit // races, and a missing taskkill binary (spawnSync reports, never throws) are // as tolerable here as ESRCH is for a POSIX group signal. @@ -314,17 +328,17 @@ export function taskkillProcessTree(pid: number): void { */ function signalTree( platform: NodeJS.Platform, - pid: number, + pid: number | undefined, sig: NodeJS.Signals, child: ChildProcess, taskkill: (pid: number) => void, ): void { + /* v8 ignore next -- kill/terminate gate on treeAlive(), which is false without a pid; this guard protects direct callers only. */ + if (pid === undefined) return if (platform === 'win32') { taskkill(pid) return } - /* v8 ignore next -- kill/terminate gate on treeAlive(), which is false for pid -1; this guard protects direct callers only. */ - if (pid <= 0) return try { process.kill(-pid, sig) } catch { @@ -340,31 +354,120 @@ function signalTree( } /** - * Spawn one isolated detached process tree with the spec's per-stream stdio - * dispositions. Runtime exits resolve `done` as {@link SubprocessOutcome}; - * only spawn failures reject. - * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment. - * @param internals - test-only spill-directory, platform, and taskkill overrides. - * @returns live subprocess handle. - * @throws when `graceMs` cannot be represented by one Node timer. + * Validate the synchronous portion of one ordinary spawn request. + * @param spec - exact target request. + * @throws when grace, cancellation, or argv is invalid before launch. */ -export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): LocalSubprocessHandle { +export function validateSubprocessSpec(spec: SubprocessSpawnSpec): void { if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) { throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`) } - const spillDir = internals.spillDir ?? privateSpillDir() - const platform = internals.platform ?? process.platform - const spawnProcess = internals.spawn ?? spawn - const taskkill = internals.taskkill ?? taskkillProcessTree - const linuxGroupHasLiveMembers = internals.linuxProcessGroupHasLiveMembers ?? linuxProcessGroupHasLiveMembers - if (spec.signal?.aborted) { - throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`) + let reason = 'aborted' + try { + reason = String(spec.signal.reason ?? reason) + } catch { + // Arbitrary caller-owned reasons cannot escape the stable Error boundary. + } + throw new Error(`aborted before spawn: ${reason}`) } - const [program, ...args] = spec.argv + const [program] = spec.argv if (program === undefined || program.length === 0) { throw new Error('invalid argv: expected a non-empty program name at argv[0]') } +} + +function directChildResult(child: ChildProcess): Promise { + return new Promise((resolve, reject) => { + let completed = false + child.once('error', (error) => { + /* v8 ignore next -- ChildProcess may report a later operational error after its + terminal exit event; the first terminal event owns the result. */ + if (completed) return + completed = true + reject(error) + }) + child.once('exit', (exitCode, signal) => { + /* v8 ignore next -- a spawn/kill error may be followed by exit; a Promise can publish only the first terminal event. */ + if (completed) return + completed = true + resolve({ exitCode, signal }) + }) + }) +} + +function fallbackOwner( + platform: NodeJS.Platform, + pid: number | undefined, + child: ChildProcess, + taskkill: (pid: number) => void, + linuxGroupHasLiveMembers: (processGroupId: number) => boolean | undefined, + direct: Promise, +): BoundProcessOwner { + let stopped = false + let directSettled = false + let observation: Promise | undefined + void direct.then( + () => { directSettled = true }, + () => { directSettled = true }, + ) + + const alive = (): boolean => { + if (stopped || pid === undefined) return false + if (platform === 'win32') return child.exitCode === null && child.signalCode === null + try { + process.kill(-pid, 0) + if (directSettled && platform === 'linux' && linuxGroupHasLiveMembers(pid) === false) return false + return true + } catch (error) { + const code = (error as NodeJS.ErrnoException).code + if (code === 'ESRCH') return false + /* v8 ignore start -- EPERM and non-POSIX negative-pid failures are platform defenses. */ + if (code === 'EPERM') return true + return child.exitCode === null && child.signalCode === null + /* v8 ignore stop */ + } + } + + return { + signal: (signal) => { + if (!alive()) { + stopped = true + return + } + signalTree(platform, pid, signal, child, taskkill) + }, + waitForExit: async () => { + /* v8 ignore next -- bindManagedProcess memoizes this owner wait; the guard only + protects direct internal re-entry after signal() observed absence. */ + if (stopped) return + observation ??= (async () => { + while (alive()) await sleepTick() + stopped = true + })() + await observation + }, + terminateForHostExit: () => { + if (stopped) return + signalTree(platform, pid, 'SIGKILL', child, taskkill) + }, + } +} + +/** + * Bind platform launch facts to the existing stdio, outcome, abort, and termination lifecycle. + * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment. + * @param launch - platform streams, direct outcome, and managed-range owner. + * @param internals - test-only spill-directory override. + * @returns live subprocess handle. + */ +export function bindManagedProcess( + spec: SubprocessSpawnSpec, + launch: ManagedProcessLaunch, + internals: Pick = {}, +): LocalSubprocessHandle { + const { spillDir } = prepareManagedProcessBinding(internals) + const { stdin, stdout, stderr } = launch const isCollect = (mode: SubprocessOutputMode): mode is SubprocessCollect => mode !== 'pipe' && mode !== 'inherit' @@ -372,191 +475,156 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter const errMode = spec.stdio.stderr const stdinMode = spec.stdio.stdin - const env = childEnv(spec.env) - const child = spawnProcess(program, args, { - cwd: spec.cwd, - env, - stdio: [ - stdinMode === 'ignore' ? 'ignore' : 'pipe', - outMode === 'inherit' ? 'inherit' : 'pipe', - errMode === 'inherit' ? 'inherit' : 'pipe', - ], - // `detached` gives teardown a tree root on POSIX (its own process group); - // Windows terminates by root pid through taskkill /T instead. - detached: platform !== 'win32', - windowsHide: platform === 'win32', - }) - const collectStream = (mode: SubprocessOutputMode, stream: Readable | null, label: string): OutputCollector | undefined => { if (!isCollect(mode) || stream === null) return undefined const collector = new OutputCollector(mode.maxBytes, mode.spill?.maxBytes, label, spillDir) stream.on('data', (chunk: Buffer) => { collector.push(chunk) }) return collector } - const stdoutCollector = collectStream(outMode, child.stdout, 'stdout') - const stderrCollector = collectStream(errMode, child.stderr, 'stderr') + const stdoutCollector = collectStream(outMode, stdout, 'stdout') + const stderrCollector = collectStream(errMode, stderr, 'stderr') + const observeOutputStream = (mode: SubprocessOutputMode, stream: Readable | null): Promise | undefined => { + if (mode === 'inherit' || stream === null || stream.readableEnded || stream.destroyed) return undefined + return new Promise((resolve) => { + const settle = (): void => { + stream.off('end', settle) + stream.off('close', settle) + stream.off('error', settle) + resolve() + } + stream.once('end', settle) + stream.once('close', settle) + stream.once('error', settle) + }) + } + const stdoutClosed = observeOutputStream(outMode, stdout) + const stderrClosed = observeOutputStream(errMode, stderr) + const outputStreamsClosed = Promise.all([stdoutClosed, stderrClosed]) + const stopCollectors = (): void => { + if (stdoutCollector !== undefined) stdout?.destroy() + if (stderrCollector !== undefined) stderr?.destroy() + stdoutCollector?.seal() + stderrCollector?.seal() + } let graceTimer: ReturnType | undefined - let treeExitObserved = false - let treeExitObservation: Promise | undefined + let terminationStarted = false + let rangeExitObserved = false + let rangeExitObservation: Promise | undefined let settled = false - // Failed spawns use pid -1 so signalling remains a no-op. - const pid = child.pid ?? -1 - - /** Whether the detached tree's root (or POSIX group) is still alive. */ - const treeAlive = (): boolean => { - /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here; - the guard is the final defense against probing an id after its tree was confirmed absent. */ - if (treeExitObserved) return false - if (pid <= 0) return false - if (platform === 'win32') { - // Windows has no group-liveness probe; the direct child's exit is the - // observable boundary (taskkill /T already took the tree with it). - return child.exitCode === null && child.signalCode === null - } - try { - process.kill(-pid, 0) - // A group containing only unreaped zombies still answers kill(0), but - // it can execute no work and cannot be signalled into quiescence. Only - // inspect after direct-child settlement so live-process polls remain a - // syscall rather than repeated process-table scans. - if (settled && platform === 'linux' && linuxGroupHasLiveMembers(pid) === false) return false - return true - } catch (error) { - const code = (error as NodeJS.ErrnoException).code - /* v8 ignore next 2 -- POSIX reports an absent group as ESRCH; child-reaping timing - makes observing the other arm platform-dependent. */ - if (code === 'ESRCH') return false - /* v8 ignore start -- EPERM and non-POSIX negative-pid failures are platform defenses; CI runs - tree-lifecycle tests on POSIX hosts where absence reports ESRCH. */ - if (code === 'EPERM') return true - return child.exitCode === null && child.signalCode === null - /* v8 ignore stop */ - } + const scheduleOwnerCleanup = (): boolean => { + if (launch.owner.cleanup === undefined) return false + queueMicrotask(() => { void done.finally(() => { launch.owner.cleanup?.() }).catch(() => {}) }) + return true } /** - * Start or reuse the handle's single whole-tree exit observer. The first - * confirmed absence is a permanent no-more-signals boundary: it cancels a - * pending escalation before this process-group id can be reused. + * Start or reuse the handle's managed-range exit observer. A failed read + * before direct settlement can be retried. Once direct settlement permits + * cleanup, retain a failed observation because removing its private evidence + * must not turn a later wait into a false success. The first confirmed + * absence is the permanent no-more-signals boundary and cancels pending + * escalation before stale identity can be used. */ - const observeTreeExit = (): Promise => { - treeExitObservation ??= (async () => { - while (treeAlive()) await sleepTick() - treeExitObserved = true + const observeRangeExit = (): Promise => { + rangeExitObservation ??= (async () => { + await launch.owner.waitForExit() + rangeExitObserved = true if (graceTimer !== undefined) clearTimeout(graceTimer) graceTimer = undefined - })() - return treeExitObservation + spec.signal?.removeEventListener('abort', onAbort) + scheduleOwnerCleanup() + })().catch((error: unknown) => { + if (!settled || !scheduleOwnerCleanup()) rangeExitObservation = undefined + throw error + }) + return rangeExitObservation } - // The escalation's tier primitive (not on the handle — terminate() is the - // only consumer-facing termination verb). Guards on TREE liveness, not - // outcome settlement: a TERM-trapping helper can outlive the settled direct - // child and must stay signalable, while a fully-dead tree (possible pid - // reuse) must not be re-signalled by a later tier. - const kill = (sig: NodeJS.Signals): void => { - /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer; - this remains the timer/death race guard and cannot be staged deterministically. */ - if (!treeAlive()) return - signalTree(platform, pid, sig, child, taskkill) + const kill = (sig: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void => { + if (rangeExitObserved) return + launch.owner.signal(sig, cancellationReason) + } + + const terminateWithReason = (cancellationReason: unknown): void => { + if (rangeExitObserved || terminationStarted) return + terminationStarted = true + // Keep the shared observation rejection available to waitForExit() without + // leaking an unhandled rejection when a caller only invokes terminate(). + void observeRangeExit().catch(() => {}) + kill('SIGTERM', cancellationReason) + graceTimer = setTimeout(() => { + graceTimer = undefined + kill('SIGKILL') + }, spec.graceMs) } const terminate = (): void => { - if (treeExitObserved || graceTimer !== undefined) return - // Observe from the first termination tier onward, even when inherited - // pipes delay `done` and no consumer has begun its own teardown wait. - void observeTreeExit() - // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await. - if (treeExitObserved) return - kill('SIGTERM') - // The escalation must survive direct-child settlement — the leader dying - // does not mean the tree died — so settle does not clear this timer, and - // kill() re-probes tree liveness before force-killing. It stays ref'd: - // the pending SIGKILL is a commitment, and a parent exiting before it - // fires would orphan a trapped survivor. Self-bounds at graceMs. - graceTimer = setTimeout(() => { kill('SIGKILL') }, spec.graceMs) + terminateWithReason(new Error('subprocess terminated before target start')) } const terminateForHostExit = (): void => { - kill('SIGKILL') + launch.owner.terminateForHostExit() } // The caller owns timeout classification; this layer only reacts to abort. - const onAbort = (): void => { terminate() } + const onAbort = (): void => { terminateWithReason(spec.signal?.reason) } spec.signal?.addEventListener('abort', onAbort, { once: true }) // Batch stdin is written and closed up front; process exit and captured // output remain authoritative, so write errors (EPIPE) are best-effort. - if (typeof stdinMode === 'object' && child.stdin !== null) { - child.stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ }) - child.stdin.end(stdinMode.data) + if (typeof stdinMode === 'object' && stdin !== null) { + stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ }) + stdin.end(stdinMode.data) } const done = new Promise((resolve, reject) => { let pipeDrainTimer: ReturnType | undefined - const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => { + const settle = (outcome: SubprocessOutcome): void => { if (settled) return settled = true // Only harness-collected pipes are force-closed at the drain boundary; // a 'pipe'-mode stream belongs to the caller and closes with the child. - if (stdoutCollector !== undefined) child.stdout?.destroy() - if (stderrCollector !== undefined) child.stderr?.destroy() - stdoutCollector?.seal() - stderrCollector?.seal() + stopCollectors() cleanup() - resolve({ exitCode, signal }) + resolve(outcome) } - child.on('error', (error) => { - // No meaningful close outcome follows a spawn failure. + const fail = (error: unknown): void => { settled = true + terminate() + stopCollectors() cleanup() + // Preserve the exact parent-local AbortSignal reason, including null or undefined. + // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- Exact cancellation reason is the contract. reject(error) - }) - child.on('exit', (exitCode, signal) => { - // A surviving descendant that inherited a pipe must not hold the - // outcome open indefinitely: after exit, the same bounded grace that - // governs kills also bounds the close wait. - pipeDrainTimer = setTimeout(() => { - settle(exitCode, signal) - }, spec.graceMs) - }) - child.on('close', settle) + } + launch.direct.then((outcome) => { + if (stdoutClosed === undefined && stderrClosed === undefined) { + settle(outcome) + return + } + pipeDrainTimer = setTimeout(() => { settle(outcome) }, spec.graceMs) + void outputStreamsClosed.then(() => { settle(outcome) }) + }, fail) function cleanup(): void { - // graceTimer deliberately NOT cleared: the SIGKILL escalation must be - // able to reach tree survivors after the direct child settles. + // graceTimer deliberately NOT cleared: forced termination must still + // reach range survivors after the spawned command settles. if (pipeDrainTimer !== undefined) clearTimeout(pipeDrainTimer) - spec.signal?.removeEventListener('abort', onAbort) } }) const waitForExit = async (signal?: AbortSignal): Promise => { - const observed = observeTreeExit() - if (treeExitObserved) return true - if (signal?.aborted) return false - if (signal === undefined) { - await observed - return true - } - const aborted = Promise.withResolvers() - const onAbort = (): void => { aborted.resolve(false) } - signal.addEventListener('abort', onAbort, { once: true }) - /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */ - if (signal.aborted) onAbort() - try { - return await Promise.race([observed.then(() => true), aborted.promise]) - } finally { - signal.removeEventListener('abort', onAbort) - } + if (rangeExitObserved) return true + return waitWithAbort(observeRangeExit(), signal) } return { - pid, - /* v8 ignore start -- pipe-mode fds exist on every spawn Node returns; the null-coalesces guard a nonconforming ChildProcess only. */ - stdin: stdinMode === 'pipe' ? child.stdin ?? undefined : undefined, - stdout: outMode === 'pipe' ? child.stdout ?? undefined : undefined, - stderr: errMode === 'pipe' ? child.stderr ?? undefined : undefined, + /* v8 ignore start -- pipe-mode streams exist on every conforming launch; + the null-coalesces guard an internal adapter defect only. */ + stdin: stdinMode === 'pipe' ? stdin ?? undefined : undefined, + stdout: outMode === 'pipe' ? stdout ?? undefined : undefined, + stderr: errMode === 'pipe' ? stderr ?? undefined : undefined, /* v8 ignore stop */ collected: { ...stdoutCollector !== undefined ? { stdout: stdoutCollector } : {}, @@ -568,3 +636,43 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter waitForExit, } } + +/** + * Spawn one detached PGID/taskkill fallback and bind the common lifecycle. + * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment. + * @param internals - test-only spill-directory, platform, and taskkill overrides. + * @returns live subprocess handle. + */ +export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): LocalSubprocessHandle { + const binding = prepareManagedProcessBinding(internals) + const platform = internals.platform ?? process.platform + const [program, ...args] = spec.argv + const child = (internals.spawn ?? spawn)(program as string, args, { + cwd: spec.cwd, + env: childEnv(spec.env), + stdio: [ + spec.stdio.stdin === 'ignore' ? 'ignore' : 'pipe', + spec.stdio.stdout === 'inherit' ? 'inherit' : 'pipe', + spec.stdio.stderr === 'inherit' ? 'inherit' : 'pipe', + ], + detached: platform !== 'win32', + windowsHide: platform === 'win32', + }) + const direct = directChildResult(child) + const pid = child.pid + const owner = fallbackOwner( + platform, + pid, + child, + internals.taskkill ?? taskkillProcessTree, + internals.linuxProcessGroupHasLiveMembers ?? linuxProcessGroupHasLiveMembers, + direct, + ) + return bindManagedProcess(spec, { + stdin: child.stdin, + stdout: child.stdout, + stderr: child.stderr, + direct, + owner, + }, binding) +} diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts index 624de54984..8d165dbd20 100644 --- a/packages/subprocess/subprocess-local/src/terminal.ts +++ b/packages/subprocess/subprocess-local/src/terminal.ts @@ -10,10 +10,31 @@ import type { SubprocessTerminalHandle, SubprocessTerminalSignal, } from '@deepseek-ai/dsh-subprocess' +import type { BoundProcessOwner } from './managed-owner.ts' import type { ProcessIdentity, ProcessInspector, ProcessSnapshot } from './process-inspector.ts' -function delay(ms: number): Promise { - return new Promise(resolve => setTimeout(resolve, ms)) +function delay(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve) => { + const finish = (): void => { + clearTimeout(timer) + signal?.removeEventListener('abort', finish) + resolve() + } + const timer = setTimeout(finish, ms) + signal?.addEventListener('abort', finish, { once: true }) + }) +} + +async function raceWithDelay(operation: Promise, ms: number, timeout: U): Promise { + const controller = new AbortController() + try { + return await Promise.race([ + operation, + delay(ms, controller.signal).then(() => timeout), + ]) + } finally { + controller.abort() + } } function signalName(number: number | undefined): NodeJS.Signals | null { @@ -25,7 +46,8 @@ function signalName(number: number | undefined): NodeJS.Signals | null { } /** - * A local terminal whose process-session ownership stays below the PTY backend. + * A local terminal whose native managed range or fallback process-session + * ownership stays below the PTY backend. * The seam's terminate() promise — no write, inspection, or signal in flight * after settlement — holds here without operation tracking only because every * handle call completes synchronously under the hood (node-pty write, ps-based @@ -41,6 +63,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { private readonly dataDisposable: IDisposable private readonly exitDisposable: IDisposable private cleanup: Promise | undefined + private managedOwnerCleaned = false private exited = false private trackedDescendants: ProcessIdentity[] = [] /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */ @@ -57,6 +80,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { private readonly inspector: ProcessInspector, private readonly graceMs: number, private readonly platform: NodeJS.Platform = process.platform, + private readonly managedOwner?: BoundProcessOwner, + private readonly resolveManagedOutcome?: (outcome: SubprocessOutcome) => SubprocessOutcome, ) { this.pid = terminal.pid this.rootIdentity = inspector.snapshot().tree(this.pid).find(member => member.pid === this.pid) @@ -66,13 +91,23 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { if (this.exited) return this.exited = true this.output.end() - this.outcome.resolve({ + const outcome = { exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null, signal: signalName(exitSignal), - }) + } + try { + this.outcome.resolve(this.resolveManagedOutcome?.(outcome) ?? outcome) + } catch (error) { + this.outcome.reject(error) + } }) } + /** Whether node-pty has not yet published the top-level exit event. */ + get running(): boolean { + return !this.exited + } + // node-pty writes synchronously; the seam returns a promise for remote transports. // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract. async write(data: string): Promise { @@ -133,6 +168,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { this.forceStopDescendants() this.forceStopShell() this.forceStopDescendants() + this.managedOwner?.terminateForHostExit() } private forceStopShell(): void { @@ -295,6 +331,16 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { } private async closeOnce(): Promise { + if (this.managedOwner !== undefined) { + try { + await this.closeManagedRange(this.managedOwner) + this.dataDisposable.dispose() + this.exitDisposable.dispose() + } finally { + void this.done.finally(() => { this.cleanupManagedOwner(this.managedOwner as BoundProcessOwner) }).catch(() => {}) + } + return + } let survivors = await this.stopDescendants() if (survivors.length > 0) { throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`) @@ -309,6 +355,39 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { this.exitDisposable.dispose() } + private cleanupManagedOwner(owner: BoundProcessOwner): void { + if (this.managedOwnerCleaned) return + this.managedOwnerCleaned = true + owner.cleanup?.() + } + + private async closeManagedRange(owner: BoundProcessOwner): Promise { + owner.signal('SIGTERM') + const observation = owner.waitForExit() + const first = await raceWithDelay(observation.then( + () => ({ kind: 'stopped' as const }), + (error: unknown) => ({ kind: 'failed' as const, error }), + ), this.graceMs, { kind: 'timeout' as const }) + if (first.kind !== 'stopped') { + owner.signal('SIGKILL') + if (first.kind === 'failed') { + // The observation failure is still authoritative, but force cleanup + // and a fresh final observation must be attempted before exposing it. + try { + await owner.waitForExit() + } catch (finalError: unknown) { + throw new AggregateError([first.error, finalError], 'terminal managed-range cleanup failed') + } + throw first.error + } + await observation + } + if (!this.exited) { + await raceWithDelay(this.done.then(() => undefined), this.graceMs, undefined) + } + if (!this.exited) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`) + } + private settleExitIfGone(): void { // An externally taskkilled Windows shell may never fire node-pty's exit // notification (its console-list agent fails without a parent console), diff --git a/packages/subprocess/subprocess-local/src/windows-job.ts b/packages/subprocess/subprocess-local/src/windows-job.ts new file mode 100644 index 0000000000..56dac99519 --- /dev/null +++ b/packages/subprocess/subprocess-local/src/windows-job.ts @@ -0,0 +1,232 @@ +/** Windows parent-side launch and ownership for the private Job runner. */ + +import { spawn } from 'node:child_process' +import { closeSync, openSync } from 'node:fs' +import { devNull } from 'node:os' +import type { Readable, Writable } from 'node:stream' +import type { SubprocessOutcome, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { + loadWin32ProcessBindings, + probeCurrentTokenJobSupport, +} from '@deepseek-ai/dsh-win32-process' +import type { BoundProcessOwner, ManagedProcessLaunch } from './managed-owner.ts' +import { + type SerializedRunnerError, + type WindowsRunnerResult, + deserializeRunnerError, + parseWindowsRunnerResult, +} from './runner-protocol.ts' +import { + runnerEnvironment, + runnerInvocationAvailable, + runnerStdio, + spawnRunnerInvocation, + WINDOWS_RUNNER_SELECTION, +} from './runner-launch.ts' +import type { RunnerInvocation } from './runner-launch.ts' + +/** Test seams for runner launch and dynamic capability checks. */ +export interface WindowsJobInternals { + spawn?: typeof spawn + runnerInvocation?: RunnerInvocation + resolveRunnerInvocation?: () => RunnerInvocation + runnerAvailable?: (invocation: RunnerInvocation) => boolean + loadWin32ProcessBindings?: typeof loadWin32ProcessBindings + probeCurrentTokenJobSupport?: typeof probeCurrentTokenJobSupport +} + +type RunnerProcess = Omit, 'send' | 'stdio'> & { + send?: ReturnType['send'] + stdio: Array +} + +function isWindowsStartCancellationError(error: SerializedRunnerError): boolean { + return error.name === 'Error' + && error.message === 'subprocess target start was cancelled' + && error.code === undefined + && error.syscall === undefined + && error.path === undefined +} + +/** + * Re-check the runner entry, bindings, and current Job capability for every spawn. + * @param internals - optional runner and Win32 capability seams used by tests. + * @returns whether the Windows native containment path is currently available. + */ +export function probeWindowsJob(internals: WindowsJobInternals = {}): boolean { + try { + const invocation = internals.runnerInvocation + ?? (internals.resolveRunnerInvocation ?? spawnRunnerInvocation)() + if (!(internals.runnerAvailable ?? runnerInvocationAvailable)(invocation)) return false + const api = (internals.loadWin32ProcessBindings ?? loadWin32ProcessBindings)() + ;(internals.probeCurrentTokenJobSupport ?? probeCurrentTokenJobSupport)(api) + return true + } catch { + return false + } +} + +class WindowsJobOwner implements BoundProcessOwner { + private cancellationReason: unknown + private cancellationReasonSet = false + private terminationSent = false + + constructor( + private readonly runner: RunnerProcess, + private readonly exited: Promise, + private readonly directResultType: () => WindowsRunnerResult['type'] | undefined, + private readonly failInfrastructure: (error: unknown) => void, + ) { + void this.exited.catch(() => {}) + } + + signal(_signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void { + if (!this.cancellationReasonSet) { + this.cancellationReason = cancellationReason + this.cancellationReasonSet = true + } + if (this.terminationSent || !this.runner.connected) return + this.terminationSent = true + try { + this.runner.send?.({ type: 'terminate' }, (error) => { + if (error === null || this.directResultType() !== undefined) return + this.failInfrastructure(error) + this.terminateForHostExit() + }) + } catch (error) { + this.failInfrastructure(error) + this.terminateForHostExit() + } + } + + mapStartFailure(failure: unknown, serialized: SerializedRunnerError): unknown { + return this.cancellationReasonSet && isWindowsStartCancellationError(serialized) + ? this.cancellationReason + : failure + } + + async waitForExit(): Promise { + await this.exited + } + + terminateForHostExit(): void { + try { this.runner.kill('SIGKILL') } catch { /* Host exit continues with other live runners. */ } + } +} + +/** + * Launch one target through a runner that uniquely owns its Job handle. + * @param spec - ordinary target request. + * @param targetEnv - validated complete target environment. + * @param internals - optional runner launch seams used by tests. + * @returns direct streams, result, and runner-owned managed range. + */ +export function launchWindowsJob( + spec: SubprocessSpawnSpec, + targetEnv: Record, + internals: WindowsJobInternals = {}, +): ManagedProcessLaunch { + const invocation = internals.runnerInvocation ?? spawnRunnerInvocation() + const [command, ...prefix] = invocation + const ignoredStdinFd = spec.stdio.stdin === 'ignore' ? openSync(devNull, 'r') : undefined + let child: RunnerProcess + try { + child = (internals.spawn ?? spawn)(command, [ + ...prefix, + '--', + ...spec.argv, + ], { + cwd: process.cwd(), + env: runnerEnvironment(WINDOWS_RUNNER_SELECTION, invocation), + stdio: runnerStdio(spec, true, ignoredStdinFd ?? 'pipe'), + }) as RunnerProcess + } finally { + if (ignoredStdinFd !== undefined) closeSync(ignoredStdinFd) + } + const targetStdin = child.stdio[4] as Writable | null + + const direct = Promise.withResolvers() + const rangeExit = Promise.withResolvers() + let directResultType: WindowsRunnerResult['type'] | undefined + let runnerSpawned = false + const failInfrastructure = (error: unknown): void => { + direct.reject(error) + rangeExit.reject(error) + } + + const owner = new WindowsJobOwner( + child, + rangeExit.promise, + () => directResultType, + failInfrastructure, + ) + child.on('message', (value: unknown) => { + if (directResultType !== undefined) { + const error = new Error('subprocess-local: Windows runner emitted more than one direct result') + failInfrastructure(error) + owner.terminateForHostExit() + return + } + let result: ReturnType + try { + result = parseWindowsRunnerResult(value) + } catch (error) { + failInfrastructure(error) + owner.terminateForHostExit() + return + } + directResultType = result.type + if (result.type === 'target-exit') { + direct.resolve({ exitCode: result.exitCode, signal: null }) + } else { + direct.reject(owner.mapStartFailure(deserializeRunnerError(result.error), result.error)) + } + }) + child.once('spawn', () => { + runnerSpawned = true + try { + if (child.send === undefined) throw new Error('subprocess-local: Windows runner has no IPC channel') + child.send({ type: 'start', cwd: spec.cwd, env: targetEnv }, (error) => { + if (error === null) return + failInfrastructure(error) + owner.terminateForHostExit() + }) + } catch (error) { + failInfrastructure(error) + owner.terminateForHostExit() + } + }) + child.once('error', (error) => { + if (!runnerSpawned) { + direct.reject(error) + rangeExit.resolve() + return + } + failInfrastructure(error) + }) + child.once('close', (exitCode, signal) => { + if (!runnerSpawned) return + const clean = exitCode === 0 && signal === null && directResultType !== undefined + if (clean) { + rangeExit.resolve() + return + } + const status = signal !== null + ? `signal ${signal}` + : exitCode === null + ? 'without an exit status' + : `exit code ${String(exitCode)}` + const error = new Error( + `subprocess-local: Windows Job runner exited with ${status} before proving its managed range empty`, + ) + failInfrastructure(error) + }) + + return { + stdin: spec.stdio.stdin === 'ignore' ? null : targetStdin, + stdout: child.stdio[5] as Readable | null, + stderr: child.stdio[6] as Readable | null, + direct: direct.promise, + owner, + } +} diff --git a/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts b/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts new file mode 100644 index 0000000000..5f4904366b --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts @@ -0,0 +1,104 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' + +afterEach(() => { + vi.doUnmock('koffi') + vi.resetModules() +}) + +describe.skipIf(process.platform !== 'linux')('Linux libc execve binding', () => { + it('preserves inherited stdio, null-terminates argv and envp, and reports execve errno', async () => { + const nativeExecve = vi.fn(() => -1) + const nativeFcntl = vi.fn((fd: number, command: number) => { + if (command === 2) return 0 + return [1, 0, 5][fd] + }) + const func = vi.fn((declaration: string) => declaration.includes('execve') + ? nativeExecve + : nativeFcntl) + const load = vi.fn(() => ({ func })) + const errno = vi.fn(() => 2) + vi.doMock('koffi', () => ({ default: { errno, load } })) + + const { loadLinuxExecve } = await import('../src/linux-execve.ts') + const execve = loadLinuxExecve() + expect(loadLinuxExecve()).toBe(execve) + expect(load).toHaveBeenCalledExactlyOnceWith(null) + expect(func.mock.calls).toEqual([ + ['int execve(const char *pathname, const char **argv, const char **envp)'], + ['int fcntl(int fd, int cmd, int arg)'], + ]) + + let failure: unknown + try { + execve('/missing/tool', ['tool', 'literal arg'], { A: '1', EMPTY: '' }) + } catch (error) { + failure = error + } + expect(nativeFcntl.mock.calls).toEqual([ + [0, 1, 0], + [0, 2, 0], + [1, 1, 0], + [2, 1, 0], + [2, 2, 4], + ]) + expect(nativeExecve).toHaveBeenCalledExactlyOnceWith( + '/missing/tool', + ['tool', 'literal arg', null], + ['A=1', 'EMPTY=', null], + ) + expect(errno).toHaveBeenCalledOnce() + expect(failure).toMatchObject({ + code: 'ENOENT', + errno: -2, + syscall: 'execve', + path: '/missing/tool', + }) + expect(failure).toBeInstanceOf(Error) + expect((failure as Error).message).toContain("ENOENT: no such file or directory, execve '/missing/tool'") + }) + + it('reports failure to read descriptor flags before replacing the process', async () => { + const nativeExecve = vi.fn() + const nativeFcntl = vi.fn(() => -1) + const func = vi.fn((declaration: string) => declaration.includes('execve') + ? nativeExecve + : nativeFcntl) + const errno = vi.fn(() => 9) + vi.doMock('koffi', () => ({ default: { errno, load: () => ({ func }) } })) + + const { loadLinuxExecve } = await import('../src/linux-execve.ts') + expect(() => loadLinuxExecve()('/bin/tool', ['tool'], {})).toThrow(expect.objectContaining({ + code: 'EBADF', + errno: -9, + syscall: 'fcntl', + })) + expect(nativeFcntl).toHaveBeenCalledExactlyOnceWith(0, 1, 0) + expect(nativeExecve).not.toHaveBeenCalled() + expect(errno).toHaveBeenCalledOnce() + }) + + it('reports failure to clear close-on-exec before replacing the process', async () => { + const nativeExecve = vi.fn() + const nativeFcntl = vi.fn() + .mockReturnValueOnce(1) + .mockReturnValueOnce(-1) + const func = vi.fn((declaration: string) => declaration.includes('execve') + ? nativeExecve + : nativeFcntl) + const errno = vi.fn(() => 5) + vi.doMock('koffi', () => ({ default: { errno, load: () => ({ func }) } })) + + const { loadLinuxExecve } = await import('../src/linux-execve.ts') + expect(() => loadLinuxExecve()('/bin/tool', ['tool'], {})).toThrow(expect.objectContaining({ + code: 'EIO', + errno: -5, + syscall: 'fcntl', + })) + expect(nativeFcntl.mock.calls).toEqual([ + [0, 1, 0], + [0, 2, 0], + ]) + expect(nativeExecve).not.toHaveBeenCalled() + expect(errno).toHaveBeenCalledOnce() + }) +}) diff --git a/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts new file mode 100644 index 0000000000..a392d35d08 --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts @@ -0,0 +1,618 @@ +import { EventEmitter } from 'node:events' +import { existsSync, rmSync, unlinkSync, writeFileSync } from 'node:fs' +import { PassThrough } from 'node:stream' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { + launchLinuxScope, + prepareLinuxTerminalScope, + probeLinuxBootstrap, + probeLinuxManager, + probeLinuxNative, + probeLinuxScope, +} from '../src/linux-scope.ts' +import type { LinuxScopeInternals } from '../src/linux-scope.ts' +import { + consumeLinuxLaunchRequest, + linuxLaunchFilesFromLocator, + writeLinuxStartupError, +} from '../src/runner-protocol.ts' +import { SUBPROCESS_RUNNER_ENV } from '../src/runner-launch.ts' + +const childProcessMocks = vi.hoisted(() => ({ + execFile: vi.fn(), + spawn: vi.fn(), + spawnSync: vi.fn(), +})) + +vi.mock('node:child_process', async (importOriginal) => { + const actual = await importOriginal() + return { + ...actual, + execFile: childProcessMocks.execFile as unknown as typeof actual.execFile, + spawn: childProcessMocks.spawn as typeof actual.spawn, + spawnSync: childProcessMocks.spawnSync as typeof actual.spawnSync, + } +}) + +class FakeChild extends EventEmitter { + pid: number | undefined = 321 + exitCode: number | null = null + signalCode: NodeJS.Signals | null = null + stdin = new PassThrough() + stdout = new PassThrough() + stderr = new PassThrough() + kills: NodeJS.Signals[] = [] + + kill(signal: NodeJS.Signals): boolean { + this.kills.push(signal) + return true + } + + exit(exitCode: number | null, signal: NodeJS.Signals | null): void { + this.exitCode = exitCode + this.signalCode = signal + this.emit('exit', exitCode, signal) + } +} + +const directories: string[] = [] + +afterEach(() => { + for (const directory of directories.splice(0)) { + rmSync(directory, { recursive: true, force: true }) + } + vi.restoreAllMocks() + childProcessMocks.execFile.mockReset() + childProcessMocks.spawn.mockReset() + childProcessMocks.spawnSync.mockReset() +}) + +function missingUnit() { + return { status: 1, stdout: '', stderr: 'Unit dsh.scope could not be found.' } +} + +function activeUnit(state = 'active') { + return { status: 0, stdout: `LoadState=loaded\nActiveState=${state}\n`, stderr: '' } +} + +function unloadedUnit() { + return { status: 0, stdout: 'LoadState=not-found\nActiveState=inactive\n', stderr: '' } +} + +function unitState(loadState: string, activeState: string) { + return { status: 0, stdout: `LoadState=${loadState}\nActiveState=${activeState}\n`, stderr: '' } +} + +function spec() { + return { + argv: ['tool', 'literal arg'], + cwd: '/target', + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' }, + graceMs: 100, + env: { TARGET: 'yes' }, + } as const +} + +function launch( + query: LinuxScopeInternals['systemctlQuery'], + overrides: LinuxScopeInternals = {}, +) { + const child = new FakeChild() + let options: { env?: NodeJS.ProcessEnv; cwd?: string; detached?: boolean } | undefined + const spawn = vi.fn((_command: string, _args: readonly string[], received: typeof options) => { + options = received + return child + }) + const spawnSync = vi.fn(() => ({ status: 0, stdout: '', stderr: '' })) + const systemctlQuery = overrides.systemctlQuery ?? query + const result = launchLinuxScope(spec(), { TARGET: 'yes' }, { + spawn: overrides.spawn ?? spawn as never, + spawnSync: overrides.spawnSync ?? spawnSync as never, + ...systemctlQuery === undefined ? {} : { systemctlQuery }, + systemdRun: overrides.systemdRun ?? '/bin/systemd-run', + systemctl: overrides.systemctl ?? '/bin/systemctl', + runnerInvocation: overrides.runnerInvocation ?? ['/usr/bin/node', '/runner.js'], + ...overrides.runnerAvailable === undefined ? {} : { runnerAvailable: overrides.runnerAvailable }, + ...overrides.loadLinuxExecve === undefined ? {} : { loadLinuxExecve: overrides.loadLinuxExecve }, + ...overrides.sleep === undefined ? {} : { sleep: overrides.sleep }, + }) + const requestPath = options?.env?.[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('launch did not publish a request locator') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + return { child, result, requestPath, spawn, spawnSync, options } +} + +describe('Linux native capability selection', () => { + it('rechecks bootstrap and literal transient-scope support', () => { + const spawnSync = vi.fn(() => ({ status: 0, error: undefined })) + const runnerAvailable = vi.fn(() => true) + const loadLinuxExecve = vi.fn(() => vi.fn() as never) + const inputs = { + spawnSync: spawnSync as never, + runnerAvailable, + runnerInvocation: ['/usr/bin/node', '/runner.js'] as [string, ...string[]], + loadLinuxExecve, + systemdRun: '/bin/systemd-run', + systemctl: '/bin/systemctl', + } + expect(probeLinuxNative(inputs)).toBe(true) + expect(probeLinuxNative(inputs)).toBe(true) + expect(runnerAvailable).toHaveBeenCalledTimes(2) + expect(loadLinuxExecve).toHaveBeenCalledTimes(2) + expect(spawnSync).toHaveBeenCalledTimes(2) + expect(probeLinuxBootstrap({ + ...inputs, + loadLinuxExecve: () => { throw new Error('libc execve missing') }, + })).toBe(false) + }) + + it('reports each failed dynamic prerequisite without executing a target', () => { + expect(probeLinuxScope({ + spawnSync: vi.fn(() => ({ status: null, error: new Error('missing') })) as never, + })).toBe(false) + expect(probeLinuxBootstrap({ + loadLinuxExecve: () => vi.fn() as never, + runnerInvocation: ['/missing'], + runnerAvailable: () => false, + })).toBe(false) + expect(probeLinuxBootstrap({ + loadLinuxExecve: () => vi.fn() as never, + resolveRunnerInvocation: () => { throw new Error('runner resolution failed') }, + })).toBe(false) + }) + + it('uses the default command adapters and runner resolution', () => { + childProcessMocks.spawnSync.mockReturnValue({ status: 0, error: undefined }) + expect(probeLinuxScope()).toBe(true) + expect(probeLinuxManager()).toBe(true) + expect(childProcessMocks.spawnSync).toHaveBeenCalledTimes(2) + expect(probeLinuxBootstrap({ loadLinuxExecve: () => vi.fn() as never })).toBe(true) + expect(probeLinuxBootstrap({ + runnerInvocation: [process.execPath], + runnerAvailable: () => true, + })).toBe(process.platform !== 'win32') + }) + + it('keeps quieting on the transient-scope probe but preserves manager diagnostics', () => { + const spawnSync = vi.fn(( + _command: string, + _args: readonly string[], + _options: unknown, + ) => ({ status: 0, error: undefined })) + expect(probeLinuxScope({ spawnSync: spawnSync as never })).toBe(true) + expect(probeLinuxManager({ spawnSync: spawnSync as never })).toBe(true) + const scopeOptions = spawnSync.mock.calls[0]?.[2] as { env: NodeJS.ProcessEnv } + const managerOptions = spawnSync.mock.calls[1]?.[2] as { env: NodeJS.ProcessEnv } + expect(scopeOptions.env).toMatchObject({ LC_ALL: 'C', SYSTEMD_LOG_TARGET: 'null' }) + expect(managerOptions.env).toMatchObject({ LC_ALL: 'C' }) + expect(managerOptions.env).not.toHaveProperty('SYSTEMD_LOG_TARGET') + + expect(probeLinuxManager({ + spawnSync: vi.fn(() => ({ status: 1, error: undefined })) as never, + })).toBe(false) + expect(probeLinuxManager({ + spawnSync: vi.fn(() => ({ status: null, error: new Error('missing') })) as never, + })).toBe(false) + }) +}) + +describe('Linux scope establishment and quiescence', () => { + it('does not mistake pre-establishment unit absence for quiescence and settles an empty range after cancellation', async () => { + const { child, result, requestPath, spawnSync } = launch(async () => missingUnit()) + const waiting = result.owner.waitForExit() + result.owner.signal('SIGTERM') + expect(child.kills).toEqual(['SIGTERM']) + expect(spawnSync).toHaveBeenCalledWith('/bin/systemctl', expect.arrayContaining([ + 'kill', '--kill-whom=all', '--signal=SIGTERM', + ]), expect.anything()) + const direct = expect(result.direct).rejects.toThrow('before its bootstrap consumed') + child.exit(null, 'SIGTERM') + await direct + await expect(waiting).resolves.toBeUndefined() + expect(existsSync(requestPath)).toBe(true) + result.owner.cleanup?.() + }) + + it('accepts request consumption followed by rapid --collect unload as stopped', async () => { + const states = [activeUnit(), unloadedUnit()] + const { child, result, requestPath } = launch(async () => states.shift() ?? missingUnit()) + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + const waiting = result.owner.waitForExit() + child.exit(0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(waiting).resolves.toBeUndefined() + result.owner.signal('SIGKILL') + result.owner.cleanup?.() + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) + }) + + it('uses the scope alone after establishment and the direct range only when scope signalling fails', async () => { + const spawnSync = vi.fn() + .mockReturnValueOnce({ status: 0, stdout: '', stderr: '' }) + .mockReturnValueOnce({ status: 1, stdout: '', stderr: 'scope signal failed' }) + const { child, result, requestPath } = launch(async () => activeUnit(), { + spawnSync: spawnSync as never, + }) + consumeLinuxLaunchRequest(requestPath) + const processKill = vi.spyOn(process, 'kill').mockReturnValue(true) + + result.owner.signal('SIGTERM') + expect(processKill).not.toHaveBeenCalled() + + result.owner.signal('SIGKILL') + expect(processKill).toHaveBeenCalledExactlyOnceWith(-321, 'SIGKILL') + expect(spawnSync).toHaveBeenCalledTimes(2) + + child.exit(null, 'SIGKILL') + await expect(result.direct).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' }) + result.owner.cleanup?.() + }) + + it('uses manager-observed unit existence as establishment proof', async () => { + const { child, result } = launch(async () => activeUnit('inactive')) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + child.exit(1, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + result.owner.cleanup?.() + }) + + it('keeps waiting while the unit is absent and the direct launcher is still running', async () => { + const states = [missingUnit(), activeUnit('inactive')] + const { child, result } = launch(async () => states.shift() ?? activeUnit('inactive')) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + child.exit(1, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + result.owner.cleanup?.() + }) + + it('treats status-zero not-found as pending until the direct launcher proves the range was never created', async () => { + const state: { child?: FakeChild } = {} + const launched = launch(async () => unloadedUnit(), { + sleep: async () => { state.child?.exit(127, null) }, + }) + state.child = launched.child + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + await expect(launched.result.direct).rejects.toThrow('before its bootstrap consumed') + launched.result.owner.cleanup?.() + }) + + it('polls promptly before establishment and backs off established active scopes', async () => { + const delays: number[] = [] + const states = [ + missingUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit(), + activeUnit('inactive'), + ] + const launched = launch( + async () => states.shift() ?? activeUnit('inactive'), + { sleep: async (delayMs) => { delays.push(delayMs) } }, + ) + + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + expect(delays).toEqual([50, 50, 100, 200, 400, 800, 1_600, 3_200, 5_000]) + launched.result.owner.cleanup?.() + }) + + it('keeps reloading scopes active and lets terminate wake a backed-off observation', async () => { + const states = [activeUnit('reloading'), activeUnit('inactive')] + const sleeping = Promise.withResolvers() + const sleep = vi.fn(async (_delayMs: number, signal?: AbortSignal) => { + sleeping.resolve(undefined) + if (signal === undefined) throw new Error('missing sleep cancellation signal') + await new Promise((resolve) => { signal.addEventListener('abort', () => { resolve() }, { once: true }) }) + }) + const launched = launch(async () => states.shift() ?? activeUnit('inactive'), { sleep }) + consumeLinuxLaunchRequest(launched.requestPath) + const waiting = launched.result.owner.waitForExit() + await sleeping.promise + launched.result.owner.signal('SIGTERM') + await expect(waiting).resolves.toBeUndefined() + expect(sleep).toHaveBeenCalledOnce() + expect(sleep.mock.calls[0]?.[0]).toBe(50) + expect(sleep.mock.calls[0]?.[1]?.aborted).toBe(true) + expect(launched.spawnSync).toHaveBeenCalledOnce() + launched.result.owner.cleanup?.() + }) + + it('skips the next poll delay when terminate arrives during a manager query', async () => { + const firstQuery = Promise.withResolvers>() + const query = vi.fn() + .mockImplementationOnce(async () => await firstQuery.promise) + .mockResolvedValueOnce(activeUnit('inactive')) + const sleep = vi.fn(async () => {}) + const launched = launch(query, { sleep }) + consumeLinuxLaunchRequest(launched.requestPath) + const waiting = launched.result.owner.waitForExit() + launched.result.owner.signal('SIGTERM') + firstQuery.resolve(activeUnit()) + await expect(waiting).resolves.toBeUndefined() + expect(sleep).not.toHaveBeenCalled() + launched.result.owner.cleanup?.() + }) + + it('reports child termination before request consumption to the direct result and settles the empty range', async () => { + const { child, result } = launch(async () => missingUnit()) + child.exit(127, null) + await expect(result.direct).rejects.toThrow('before its bootstrap consumed') + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + result.owner.cleanup?.() + }) + + it('reconstructs a pre-exec startup error instead of exposing bootstrap exit 127', async () => { + const { child, result, requestPath } = launch(async () => missingUnit()) + const files = linuxLaunchFilesFromLocator(requestPath) + unlinkSync(requestPath) + writeLinuxStartupError(files, { + type: 'error', + error: { name: 'Error', message: 'spawn tool ENOENT', code: 'ENOENT' }, + }) + child.exit(127, null) + await expect(result.direct).rejects.toMatchObject({ code: 'ENOENT' }) + result.owner.cleanup?.() + }) + + it('retries a failed state query and rejects unknown states or failed final kills', async () => { + const query = vi.fn() + .mockResolvedValueOnce({ status: null, stdout: '', stderr: '', error: new Error('query failed') }) + .mockResolvedValueOnce(missingUnit()) + const { result, requestPath } = launch(query) + unlinkSync(requestPath) + await expect(result.owner.waitForExit()).rejects.toThrow('query failed') + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + result.owner.cleanup?.() + + const unknown = launch(async () => activeUnit('mystery')) + await expect(unknown.result.owner.waitForExit()).rejects.toThrow('unknown ActiveState') + unknown.result.owner.cleanup?.() + + const unknownLoad = launch(async () => unitState('masked', 'inactive')) + await expect(unknownLoad.result.owner.waitForExit()).rejects.toThrow('unknown state') + unknownLoad.result.owner.cleanup?.() + + const killFailed = launch(async () => activeUnit(), { + spawnSync: vi.fn(() => ({ status: 1, stdout: '', stderr: 'permission denied' })) as never, + }) + killFailed.result.owner.signal('SIGKILL') + await expect(killFailed.result.owner.waitForExit()).rejects.toThrow('could not signal') + killFailed.result.owner.cleanup?.() + }) + + it('reports command-query failures from the default systemctl adapter', async () => { + childProcessMocks.execFile.mockImplementationOnce((...args: unknown[]) => { + const callback = args.at(-1) as (error: Error | null, stdout: string, stderr: string) => void + const options = args[2] as { env: NodeJS.ProcessEnv } + expect(options.env).toMatchObject({ LC_ALL: 'C' }) + expect(options.env).not.toHaveProperty('SYSTEMD_LOG_TARGET') + callback(null, 'LoadState=loaded\nActiveState=inactive\n', 'manager diagnostic remains readable') + return new EventEmitter() + }) + const stopped = launch(undefined) + await expect(stopped.result.owner.waitForExit()).resolves.toBeUndefined() + stopped.result.owner.cleanup?.() + + const queryError = Object.assign(new Error('systemctl execution failed'), { code: 'ENOENT' }) + childProcessMocks.execFile.mockImplementationOnce((...args: unknown[]) => { + const callback = args.at(-1) as (error: Error | null, stdout: string, stderr: string) => void + callback(queryError, '', '') + return new EventEmitter() + }) + const failed = launch(undefined) + await expect(failed.result.owner.waitForExit()).rejects.toBe(queryError) + failed.result.owner.cleanup?.() + }) + + it('rejects malformed, duplicate, incomplete, and extra manager state fields', async () => { + for (const [stdout, message] of [ + ['loaded\nActiveState=active\n', 'malformed state'], + ['LoadState=loaded\nLoadState=loaded\nActiveState=active\n', 'duplicate LoadState'], + ['LoadState=loaded\n', 'incomplete state'], + ['LoadState=loaded\nActiveState=inactive\nOther=value\n', 'incomplete state'], + ] as const) { + const launched = launch(async () => ({ status: 0, stdout, stderr: '' })) + await expect(launched.result.owner.waitForExit()).rejects.toThrow(message) + launched.result.owner.cleanup?.() + } + }) + + it('keeps signal failures scoped to final kill proof and stays idempotent after stop', async () => { + const spawnSync = vi.fn() + .mockReturnValueOnce({ status: 1, stdout: '', stderr: '' }) + .mockReturnValueOnce({ status: 1, stderr: 'Unit dsh.scope could not be found.' }) + .mockReturnValueOnce({ status: 1, stdout: '', stderr: '' }) + .mockReturnValueOnce({ status: 0, stdout: '', stderr: '' }) + const states = [activeUnit(), activeUnit('failed')] + const launched = launch(async () => states.shift() ?? missingUnit(), { + spawnSync: spawnSync as never, + }) + launched.child.pid = undefined + unlinkSync(launched.requestPath) + launched.result.owner.signal('SIGTERM') + launched.result.owner.signal('SIGKILL') + launched.result.owner.signal('SIGKILL') + launched.result.owner.signal('SIGKILL') + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + await expect(launched.result.owner.waitForExit()).resolves.toBeUndefined() + launched.result.owner.terminateForHostExit() + expect(spawnSync).toHaveBeenCalledTimes(4) + launched.result.owner.cleanup?.() + }) + + it('reports unreadable manager output and a failed kill before establishment', async () => { + const withOutput = launch(async () => ({ + status: 5, stdout: '', stderr: 'permission denied', + })) + await expect(withOutput.result.owner.waitForExit()).rejects.toThrow('permission denied') + withOutput.result.owner.cleanup?.() + + const withoutOutput = launch(async () => ({ status: null, stdout: '', stderr: '' })) + await expect(withoutOutput.result.owner.waitForExit()).rejects.toThrow('exit null') + withoutOutput.result.owner.cleanup?.() + + const killFailed = launch(async () => missingUnit(), { + spawnSync: vi.fn(() => ({ status: 1, stdout: '', stderr: 'kill denied' })) as never, + }) + vi.spyOn(process, 'kill').mockImplementation(() => { throw new Error('missing process group') }) + killFailed.result.owner.signal('SIGKILL') + await expect(killFailed.result.owner.waitForExit()).rejects.toThrow('kill denied') + killFailed.result.owner.cleanup?.() + }) + + it('settles direct outcomes once and reports malformed startup errors', async () => { + const childError = launch(async () => missingUnit()) + const spawnError = new Error('systemd-run failed') + childError.child.emit('error', spawnError) + childError.child.exit(1, null) + await expect(childError.result.direct).rejects.toBe(spawnError) + childError.result.owner.cleanup?.() + + const lateError = launch(async () => missingUnit()) + consumeLinuxLaunchRequest(lateError.requestPath) + lateError.child.exit(0, null) + lateError.child.emit('error', new Error('late child error')) + await expect(lateError.result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + lateError.result.owner.cleanup?.() + + const malformed = launch(async () => missingUnit()) + const files = linuxLaunchFilesFromLocator(malformed.requestPath) + unlinkSync(malformed.requestPath) + writeFileSync(files.startupErrorPath, '{', { mode: 0o600 }) + malformed.child.exit(127, null) + await expect(malformed.result.direct).rejects.toBeInstanceOf(SyntaxError) + malformed.result.owner.cleanup?.() + }) + + it('does not signal a direct group before the launcher publishes a pid', async () => { + const launched = launch(async () => activeUnit('inactive')) + launched.child.pid = undefined + const processKill = vi.spyOn(process, 'kill') + launched.result.owner.signal('SIGTERM') + expect(processKill).not.toHaveBeenCalled() + expect(launched.child.kills).toEqual([]) + consumeLinuxLaunchRequest(launched.requestPath) + launched.child.exit(0, null) + await expect(launched.result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + launched.result.owner.cleanup?.() + }) + + it('does not signal the direct group after the launcher exits', async () => { + const { child, result, requestPath, spawnSync } = launch(async () => activeUnit()) + consumeLinuxLaunchRequest(requestPath) + child.exit(0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + const processKill = vi.spyOn(process, 'kill') + + result.owner.signal('SIGTERM') + result.owner.terminateForHostExit() + + expect(processKill).not.toHaveBeenCalled() + expect(child.kills).toEqual([]) + expect(spawnSync).toHaveBeenCalledTimes(2) + result.owner.cleanup?.() + }) + + it('runs direct fallback before the exact synchronous scope kill on host exit', () => { + const events: string[] = [] + const { child, result } = launch(async () => missingUnit(), { + spawnSync: vi.fn(() => { events.push('scope'); return { status: 0 } }) as never, + }) + child.kill = vi.fn(() => { events.push('direct'); return true }) + vi.spyOn(process, 'kill').mockImplementation(() => { events.push('direct'); return true }) + result.owner.terminateForHostExit() + expect(events).toEqual(['direct', 'scope']) + result.owner.cleanup?.() + }) +}) + +describe('Linux PTY bootstrap reuse', () => { + const terminalSpec = { + argv: ['bash', '--noprofile'], + cwd: '/target', + env: { TARGET: 'yes' }, + rows: 24, + cols: 80, + graceMs: 100, + } as const + + it('uses the same request/bootstrap, preserves argv, and cleans after owner settlement', async () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }, { + systemdRun: '/bin/systemd-run', + systemctl: '/bin/systemctl', + runnerInvocation: ['/usr/bin/node', '/runner.js'], + spawnSync: vi.fn(() => ({ status: 0 })) as never, + systemctlQuery: async () => missingUnit(), + }) + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + expect(scope.args.slice(-3)).toEqual(['--', 'bash', '--noprofile']) + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + const owner = scope.bindOwner({ running: () => false, signal: vi.fn() }) + await expect(owner.waitForExit()).resolves.toBeUndefined() + expect(scope.resolveOutcome({ exitCode: 0, signal: null })).toEqual({ exitCode: 0, signal: null }) + scope.cleanup() + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) + }) + + it('surfaces PTY pre-exec errors instead of launcher outcomes', () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }) + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + const files = linuxLaunchFilesFromLocator(requestPath) + unlinkSync(requestPath) + writeLinuxStartupError(files, { + type: 'error', error: { name: 'Error', message: 'bad cwd', code: 'ENOENT' }, + }) + expect(() => scope.resolveOutcome({ exitCode: 127, signal: null })).toThrow('bad cwd') + scope.cleanup() + }) + + it('uses default owner dependencies and rejects an unconsumed request', () => { + const scope = prepareLinuxTerminalScope(terminalSpec, { TARGET: 'yes' }) + const requestPath = scope.env[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('missing PTY request') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + scope.bindOwner({ running: () => true, signal: vi.fn() }) + expect(() => scope.resolveOutcome({ exitCode: 1, signal: null })).toThrow( + 'before its bootstrap consumed', + ) + scope.cleanup() + }) +}) + +describe('Linux ordinary launch adapters', () => { + it('uses the default launch dependencies without changing the target request', async () => { + const child = new FakeChild() + childProcessMocks.spawn.mockReturnValue(child) + const result = launchLinuxScope(spec(), { TARGET: 'yes' }) + const call = childProcessMocks.spawn.mock.calls[0] + const options = call?.[2] as { env?: NodeJS.ProcessEnv } | undefined + const requestPath = options?.env?.[SUBPROCESS_RUNNER_ENV] + if (requestPath === undefined) throw new Error('launch did not publish a request locator') + directories.push(linuxLaunchFilesFromLocator(requestPath).directory) + expect(call?.[0]).toBe('systemd-run') + expect(consumeLinuxLaunchRequest(requestPath)).toEqual({ cwd: '/target', env: { TARGET: 'yes' } }) + child.exit(0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + result.owner.cleanup?.() + }) + + it('removes the private launch directory when spawn throws synchronously', () => { + const spawnError = new Error('synchronous spawn failure') + let requestPath: string | undefined + expect(() => launchLinuxScope(spec(), { TARGET: 'yes' }, { + runnerInvocation: ['/usr/bin/node', '/runner.js'], + spawn: vi.fn((_command: string, _args: readonly string[], options: { env?: NodeJS.ProcessEnv }) => { + requestPath = options.env?.[SUBPROCESS_RUNNER_ENV] + throw spawnError + }) as never, + })).toThrow(spawnError) + if (requestPath === undefined) throw new Error('spawn did not receive a request locator') + expect(existsSync(linuxLaunchFilesFromLocator(requestPath).directory)).toBe(false) + }) +}) diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts index 9e4925bdb2..4ca9f64439 100644 --- a/packages/subprocess/subprocess-local/tests/local.spec.ts +++ b/packages/subprocess/subprocess-local/tests/local.spec.ts @@ -6,6 +6,17 @@ import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess' import { childEnv } from '../src/spawn.ts' +function mockWin32ForIsolatedRuntime(): void { + vi.doMock('@deepseek-ai/dsh-win32-process', () => ({ + loadWin32ProcessBindings: vi.fn(), + probeCurrentTokenJobSupport: vi.fn(), + })) +} + +function unmockWin32ForIsolatedRuntime(): void { + vi.doUnmock('@deepseek-ai/dsh-win32-process') +} + function spec(command: string, overrides: Partial = {}): SubprocessSpawnSpec { // Windows has no bash; the suite's simple commands translate to node one-liners. const argv = process.platform === 'win32' @@ -87,6 +98,45 @@ describe('LocalSubprocessRuntime', () => { expect(process.listeners('exit')).not.toContain(listener) }) + it('observes range failure without waiting for a stuck direct result', async () => { + const before = new Set(process.listeners('exit')) + const ctx = new Context() + const disposalErrors: unknown[] = [] + ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error + const fiber = await ctx.plugin(LocalSubprocessRuntime) + const listener = process.listeners('exit').find(candidate => !before.has(candidate)) + const rangeFailure = new Error('managed range became unreadable') + const terminate = vi.fn() + const terminateForHostExit = vi.fn() + const live = (ctx.subprocess as unknown as { + live: Set<{ + done: Promise + terminate(): void + terminateForHostExit(): void + waitForExit(): Promise + }> + }).live + live.add({ + done: new Promise(() => {}), + terminate, + terminateForHostExit, + waitForExit: async () => { throw rangeFailure }, + }) + + await expect(Promise.race([ + fiber.dispose().then(() => 'disposed'), + new Promise(resolve => setTimeout(() => { resolve('timeout') }, 100)), + ])).resolves.toBe('disposed') + expect(terminate).toHaveBeenCalledOnce() + expect(terminateForHostExit).toHaveBeenCalledOnce() + expect(disposalErrors).toEqual([rangeFailure]) + expect(live.size).toBe(1) + expect(process.listeners('exit')).toContain(listener) + listener?.(0) + expect(terminateForHostExit).toHaveBeenCalledTimes(2) + if (listener !== undefined) process.off('exit', listener) + }) + it('contains each host-exit termination failure and continues with the other targets', async () => { const before = new Set(process.listeners('exit')) const ctx = new Context() @@ -202,8 +252,11 @@ describe('LocalSubprocessRuntime', () => { }) it('waits for every terminal cleanup and aggregates teardown failures', async () => { + const before = new Set(process.listeners('exit')) const ctx = new Context() const fiber = await ctx.plugin(LocalSubprocessRuntime) + const listener = process.listeners('exit').find(candidate => !before.has(candidate)) + expect(listener).toBeTypeOf('function') const service = ctx.subprocess const firstFailure = new Error('first cleanup failure') const secondFailure = new Error('second cleanup failure') @@ -241,20 +294,25 @@ describe('LocalSubprocessRuntime', () => { expect(disposed).toBe(false) finishCleanup() await disposing - expect(terminals.size).toBe(0) + expect(terminals).toEqual(new Set([failedTerminal, secondFailedTerminal])) expect(disposalErrors).toHaveLength(1) expect(disposalErrors[0]).toMatchObject({ errors: [firstFailure, secondFailure], message: 'local subprocess teardown failed', }) + expect(process.listeners('exit')).toContain(listener) + if (listener !== undefined) process.off('exit', listener) }) it('reports one cleanup failure without wrapping it', async () => { + const before = new Set(process.listeners('exit')) const ctx = new Context() const failure = new Error('single cleanup failure') const disposalErrors: unknown[] = [] ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error const fiber = await ctx.plugin(LocalSubprocessRuntime) + const listener = process.listeners('exit').find(candidate => !before.has(candidate)) + expect(listener).toBeTypeOf('function') const service = ctx.subprocess const terminal: SubprocessTerminalHandle = { pid: 1, @@ -271,9 +329,12 @@ describe('LocalSubprocessRuntime', () => { await fiber.dispose() expect(disposalErrors).toEqual([failure]) + expect(terminals.has(terminal)).toBe(true) + expect(process.listeners('exit')).toContain(listener) + if (listener !== undefined) process.off('exit', listener) }) - it('force-terminates remaining targets before releasing a failed disposal', async () => { + it('force-terminates and retains failed disposal targets for host exit', async () => { const before = new Set(process.listeners('exit')) const ctx = new Context() const fiber = await ctx.plugin(LocalSubprocessRuntime) @@ -293,8 +354,11 @@ describe('LocalSubprocessRuntime', () => { await fiber.dispose() expect(terminateForHostExit).toHaveBeenCalledOnce() - expect(terminals.size).toBe(0) - expect(process.listeners('exit')).not.toContain(listener) + expect(terminals.size).toBe(1) + expect(process.listeners('exit')).toContain(listener) + listener?.(0) + expect(terminateForHostExit).toHaveBeenCalledTimes(2) + if (listener !== undefined) process.off('exit', listener) }) it('releases a terminal after top-level exit reaches quiescence', async () => { @@ -318,6 +382,7 @@ describe('LocalSubprocessRuntime', () => { kill: () => {}, } vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('node-pty', () => ({ spawn: () => terminal })) vi.doMock('../src/process-inspector.ts', async importOriginal => ({ ...await importOriginal(), @@ -340,6 +405,175 @@ describe('LocalSubprocessRuntime', () => { } finally { vi.doUnmock('node-pty') vi.doUnmock('../src/process-inspector.ts') + unmockWin32ForIsolatedRuntime() + vi.resetModules() + } + }) + + it('wraps Linux terminals in the selected scope and binds owner liveness', async () => { + let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined + let launcherRunning: (() => boolean) | undefined + let launcherSignal: ((signal: 'SIGTERM' | 'SIGKILL') => void) | undefined + const terminalKill = vi.fn(() => { throw new Error('terminal already exited') }) + const terminal = { + pid: 123, + onData: () => ({ dispose: () => {} }), + onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => { + exitListener = listener + return { dispose: () => {} } + }, + write: () => {}, + kill: terminalKill, + } + const nodePtySpawn = vi.fn(() => terminal) + const owner = { + signal: vi.fn(), + waitForExit: vi.fn(async () => {}), + terminateForHostExit: vi.fn(), + } + const launcherStates: boolean[] = [] + const bindOwner = vi.fn((direct: { running(): boolean; signal(signal: 'SIGTERM' | 'SIGKILL'): void }) => { + launcherRunning = () => direct.running() + launcherSignal = (signal) => { direct.signal(signal) } + launcherStates.push(direct.running()) + return owner + }) + const prepareLinuxTerminalScope = vi.fn(() => ({ + command: '/usr/bin/systemd-run', + args: ['--user', '--scope', '--quiet', '--collect', '--', '/usr/bin/node', '/runner.js', '--', 'shell', '--literal'], + cwd: '/bootstrap', + env: { BOOTSTRAP: 'yes' }, + bindOwner, + resolveOutcome: (outcome: unknown) => outcome, + cleanup: vi.fn(), + })) + const probeLinuxNative = vi.fn(() => true) + const probeLinuxManager = vi.fn(() => true) + const inspector = { + foregroundPgid: () => undefined, + isStdinWaiting: () => false, + snapshot: () => ({ + tree: () => [{ pid: 123, started: 'shell' }], + session: () => [], + alive: () => false, + }), + isAlive: () => false, + signalGroup: () => {}, + signalProcess: () => {}, + } + + vi.resetModules() + mockWin32ForIsolatedRuntime() + vi.doMock('node-pty', () => ({ spawn: nodePtySpawn })) + vi.doMock('../src/linux-scope.ts', () => ({ + launchLinuxScope: vi.fn(), + prepareLinuxTerminalScope, + probeLinuxManager, + probeLinuxNative, + })) + let fiber: { dispose(): Promise } | undefined + try { + const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') + const ctx = new Context() + fiber = await ctx.plugin(IsolatedLocalSubprocessRuntime) + const runtime = ctx.subprocess as InstanceType + runtime.internals = { platform: 'linux' } + runtime.terminalInspector = inspector + + const targetCwd = process.cwd() + const handle = await runtime.spawnTerminal({ + argv: ['shell', '--literal'], + cwd: targetCwd, + rows: 24, + cols: 80, + graceMs: 10, + env: { PWD: '/stale-parent-cwd', TERM: 'xterm-256color', TARGET_VALUE: 'preserved' }, + }) + + expect(probeLinuxNative).toHaveBeenCalledOnce() + expect(prepareLinuxTerminalScope).toHaveBeenCalledWith( + expect.objectContaining({ argv: ['shell', '--literal'] }), + expect.objectContaining({ PWD: targetCwd, TERM: 'dumb', TARGET_VALUE: 'preserved' }), + ) + expect(nodePtySpawn).toHaveBeenCalledWith( + '/usr/bin/systemd-run', + ['--user', '--scope', '--quiet', '--collect', '--', '/usr/bin/node', '/runner.js', '--', 'shell', '--literal'], + expect.objectContaining({ rows: 24, cols: 80, cwd: '/bootstrap', env: { BOOTSTRAP: 'yes' } }), + ) + expect(bindOwner).toHaveBeenCalledOnce() + expect(launcherStates).toEqual([true]) + expect(launcherRunning?.()).toBe(true) + expect(() => { launcherSignal?.('SIGTERM') }).not.toThrow() + expect(terminalKill).toHaveBeenCalledExactlyOnceWith('SIGTERM') + + exitListener?.({ exitCode: 0 }) + expect(launcherRunning?.()).toBe(false) + await handle.done + await new Promise(resolve => setImmediate(resolve)) + expect(owner.signal).toHaveBeenCalledExactlyOnceWith('SIGTERM') + expect(owner.waitForExit).toHaveBeenCalledOnce() + } finally { + await fiber?.dispose() + vi.doUnmock('node-pty') + vi.doUnmock('../src/linux-scope.ts') + unmockWin32ForIsolatedRuntime() + vi.resetModules() + } + }) + + it('cleans the Linux terminal launch protocol when node-pty throws synchronously', async () => { + const launchFailure = new Error('node-pty launch failed') + const cleanup = vi.fn() + const nodePtySpawn = vi.fn(() => { throw launchFailure }) + const prepareLinuxTerminalScope = vi.fn(() => ({ + command: '/usr/bin/systemd-run', + args: ['--user', '--scope', '--', 'shell'], + cwd: '/bootstrap', + env: { BOOTSTRAP: 'yes' }, + bindOwner: vi.fn(), + resolveOutcome: (outcome: unknown) => outcome, + cleanup, + })) + const inspector = { + foregroundPgid: () => undefined, + isStdinWaiting: () => false, + snapshot: () => ({ + tree: () => [{ pid: 123, started: 'shell' }], + session: () => [], + alive: () => false, + }), + isAlive: () => false, + signalGroup: () => {}, + signalProcess: () => {}, + } + + vi.resetModules() + mockWin32ForIsolatedRuntime() + vi.doMock('node-pty', () => ({ spawn: nodePtySpawn })) + vi.doMock('../src/linux-scope.ts', () => ({ + launchLinuxScope: vi.fn(), + prepareLinuxTerminalScope, + probeLinuxManager: () => true, + probeLinuxNative: () => true, + })) + let fiber: { dispose(): Promise } | undefined + try { + const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') + const ctx = new Context() + fiber = await ctx.plugin(IsolatedLocalSubprocessRuntime) + const runtime = ctx.subprocess as InstanceType + runtime.internals = { platform: 'linux' } + runtime.terminalInspector = inspector + + await expect(runtime.spawnTerminal({ + argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 10, + })).rejects.toBe(launchFailure) + expect(cleanup).toHaveBeenCalledOnce() + } finally { + await fiber?.dispose() + vi.doUnmock('node-pty') + vi.doUnmock('../src/linux-scope.ts') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) @@ -357,6 +591,7 @@ describe('LocalSubprocessRuntime', () => { kill: () => {}, } vi.resetModules() + mockWin32ForIsolatedRuntime() vi.doMock('node-pty', () => ({ spawn: () => terminal })) try { const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') @@ -388,6 +623,7 @@ describe('LocalSubprocessRuntime', () => { expect(disposalErrors).toHaveLength(1) } finally { vi.doUnmock('node-pty') + unmockWin32ForIsolatedRuntime() vi.resetModules() } }) @@ -396,12 +632,218 @@ describe('LocalSubprocessRuntime', () => { const ctx = new Context() const fiber = await ctx.plugin(LocalSubprocessRuntime) const handle = ctx.subprocess.spawn(spec('echo managed')) + expect(handle).not.toHaveProperty('pid') const result = await handle.done expect(result.exitCode).toBe(0) expect(handle.collected.stdout!.readFrom(0).text).toBe('managed\n') await fiber.dispose() }) + it('warns once when ordinary spawns use the weaker macOS fallback', async () => { + const ctx = new Context() + const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) + const fiber = await ctx.plugin(LocalSubprocessRuntime) + const runtime = ctx.subprocess as LocalSubprocessRuntime + runtime.internals = { platform: 'darwin' } + try { + const first = runtime.spawn(spec('true')) + const second = runtime.spawn(spec('true')) + await Promise.all([first.done, second.done]) + expect(warning).toHaveBeenCalledOnce() + expect(warning).toHaveBeenCalledWith( + expect.stringContaining('descendants that escape the process group'), + ) + } finally { + warning.mockRestore() + await fiber.dispose() + } + }) + + it('reports the platform-specific reason for every fallback mode', async () => { + for (const [platform, kind, reason, selectedReason] of [ + ['darwin', 'ordinary', 'macOS has no supported persistent process-range owner', undefined], + ['linux', 'ordinary', 'the private Linux subprocess runner is unavailable', 'the private Linux subprocess runner is unavailable'], + ['win32', 'ordinary', 'the Win32 Job runner is unavailable', undefined], + ['win32', 'terminal', 'Windows ConPTY remains outside Job containment', undefined], + ['freebsd', 'ordinary', 'platform freebsd has no native managed range', undefined], + ] as const) { + const ctx = new Context() + const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) + const fiber = await ctx.plugin(LocalSubprocessRuntime) + const runtime = ctx.subprocess as unknown as { + warnFallback(platform: NodeJS.Platform, kind: 'ordinary' | 'terminal', selectedReason?: string): void + } + try { + runtime.warnFallback(platform, kind, selectedReason) + expect(warning).toHaveBeenLastCalledWith( + expect.stringContaining(reason), + ) + } finally { + warning.mockRestore() + await fiber.dispose() + } + } + }) + + it('rechecks native prerequisites for every eligible spawn and prepares storage before launch', async () => { + const linuxLaunch = { kind: 'linux' } + const windowsLaunch = { kind: 'windows' } + const launchLinuxScope = vi.fn(() => linuxLaunch) + const launchWindowsJob = vi.fn(() => windowsLaunch) + const probeLinuxNative = vi.fn(() => true) + const probeLinuxManager = vi.fn(() => true) + const probeWindowsJob = vi.fn(() => true) + const prepareManagedProcessBinding = vi.fn(() => ({ spillDir: '/tmp/dsh-test-spill' })) + const handles = [true, false, false].map((failFirstWait) => { + let waits = 0 + return { + collected: {}, + done: Promise.resolve({ exitCode: 0, signal: null }), + terminate: vi.fn(), + terminateForHostExit: vi.fn(), + waitForExit: vi.fn(async () => { + waits += 1 + if (failFirstWait && waits === 1) throw new Error('release observation failed') + return true + }), + } + }) + const bindManagedProcess = vi.fn((_spec: unknown, _launch: unknown, _binding: unknown) => { + const handle = handles.shift() + if (handle === undefined) throw new Error('missing fake handle') + return handle + }) + const spawnSubprocess = vi.fn() + + vi.resetModules() + mockWin32ForIsolatedRuntime() + vi.doMock('../src/linux-scope.ts', () => ({ + launchLinuxScope, + prepareLinuxTerminalScope: vi.fn(), + probeLinuxManager, + probeLinuxNative, + })) + vi.doMock('../src/windows-job.ts', () => ({ launchWindowsJob, probeWindowsJob })) + vi.doMock('../src/spawn.ts', async importOriginal => ({ + ...await importOriginal(), + bindManagedProcess, + prepareManagedProcessBinding, + spawnSubprocess, + })) + const fibers: Array<{ dispose(): Promise }> = [] + try { + const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') + const linuxContext = new Context() + const linuxFiber = await linuxContext.plugin(IsolatedLocalSubprocessRuntime) + fibers.push(linuxFiber) + const linuxRuntime = linuxContext.subprocess as InstanceType + linuxRuntime.internals = { platform: 'linux' } + const preparationFailure = new Error('spill directory unavailable') + prepareManagedProcessBinding.mockImplementationOnce(() => { throw preparationFailure }) + expect(() => linuxRuntime.spawn(spec('true'))).toThrow(preparationFailure) + expect(launchLinuxScope).not.toHaveBeenCalled() + await linuxRuntime.spawn(spec('true')).done + await new Promise(resolve => setImmediate(resolve)) + await linuxRuntime.spawn(spec('true')).done + await new Promise(resolve => setImmediate(resolve)) + expect(probeLinuxNative).toHaveBeenCalledOnce() + expect(probeLinuxManager).toHaveBeenCalledTimes(2) + expect(launchLinuxScope).toHaveBeenCalledTimes(2) + + const windowsContext = new Context() + const windowsFiber = await windowsContext.plugin(IsolatedLocalSubprocessRuntime) + fibers.push(windowsFiber) + const windowsRuntime = windowsContext.subprocess as InstanceType + windowsRuntime.internals = { platform: 'win32' } + await windowsRuntime.spawn(spec('true')).done + await new Promise(resolve => setImmediate(resolve)) + expect(probeWindowsJob).toHaveBeenCalledOnce() + expect(launchWindowsJob).toHaveBeenCalledOnce() + expect(bindManagedProcess.mock.calls.map(([, launch]) => launch)).toEqual([ + linuxLaunch, + linuxLaunch, + windowsLaunch, + ]) + expect(prepareManagedProcessBinding).toHaveBeenCalledTimes(4) + expect(spawnSubprocess).not.toHaveBeenCalled() + } finally { + for (const fiber of fibers.reverse()) await fiber.dispose() + vi.doUnmock('../src/linux-scope.ts') + vi.doUnmock('../src/windows-job.ts') + vi.doUnmock('../src/spawn.ts') + unmockWin32ForIsolatedRuntime() + vi.resetModules() + } + }) + + it('retries failed Linux deep probes, caches the first success, and rechecks the manager', async () => { + const probeLinuxNative = vi.fn() + .mockReturnValueOnce(false) + .mockReturnValueOnce(false) + .mockReturnValueOnce(false) + .mockReturnValueOnce(true) + const probeLinuxManager = vi.fn() + .mockReturnValueOnce(false) + .mockReturnValueOnce(true) + const probeWindowsJob = vi.fn() + .mockReturnValueOnce(false) + .mockReturnValueOnce(true) + .mockReturnValueOnce(true) + + vi.resetModules() + mockWin32ForIsolatedRuntime() + vi.doMock('../src/linux-scope.ts', () => ({ + launchLinuxScope: vi.fn(), + prepareLinuxTerminalScope: vi.fn(), + probeLinuxManager, + probeLinuxNative, + })) + vi.doMock('../src/windows-job.ts', () => ({ launchWindowsJob: vi.fn(), probeWindowsJob })) + const fibers: Array<{ dispose(): Promise }> = [] + try { + const { default: IsolatedLocalSubprocessRuntime } = await import('../src/index.ts') + const linuxContext = new Context() + vi.spyOn(linuxContext.logger, 'warn').mockImplementation(() => {}) + const linuxFiber = await linuxContext.plugin(IsolatedLocalSubprocessRuntime) + fibers.push(linuxFiber) + const linuxRuntime = linuxContext.subprocess as InstanceType + linuxRuntime.internals = { platform: 'linux' } + const linuxSelect = (linuxRuntime as unknown as { + selectContainmentMode(kind: 'ordinary' | 'terminal'): 'linux-scope' | 'windows-job' | 'fallback' + }).selectContainmentMode.bind(linuxRuntime) + + expect(linuxSelect('ordinary')).toBe('fallback') + expect(linuxSelect('ordinary')).toBe('fallback') + expect(linuxSelect('ordinary')).toBe('fallback') + expect(linuxSelect('ordinary')).toBe('linux-scope') + expect(linuxSelect('ordinary')).toBe('fallback') + expect(linuxSelect('ordinary')).toBe('linux-scope') + expect(probeLinuxNative).toHaveBeenCalledTimes(4) + expect(probeLinuxManager).toHaveBeenCalledTimes(2) + + const windowsContext = new Context() + vi.spyOn(windowsContext.logger, 'warn').mockImplementation(() => {}) + const windowsFiber = await windowsContext.plugin(IsolatedLocalSubprocessRuntime) + fibers.push(windowsFiber) + const windowsRuntime = windowsContext.subprocess as InstanceType + windowsRuntime.internals = { platform: 'win32' } + const windowsSelect = (windowsRuntime as unknown as { + selectContainmentMode(kind: 'ordinary' | 'terminal'): 'linux-scope' | 'windows-job' | 'fallback' + }).selectContainmentMode.bind(windowsRuntime) + + expect(windowsSelect('ordinary')).toBe('fallback') + expect(windowsSelect('ordinary')).toBe('windows-job') + expect(windowsSelect('ordinary')).toBe('windows-job') + expect(probeWindowsJob).toHaveBeenCalledTimes(3) + } finally { + for (const fiber of fibers.reverse()) await fiber.dispose() + vi.doUnmock('../src/linux-scope.ts') + vi.doUnmock('../src/windows-job.ts') + unmockWin32ForIsolatedRuntime() + vi.resetModules() + } + }) + it('disposal kills still-running processes and awaits their exit', async () => { const ctx = new Context() const fiber = await ctx.plugin(LocalSubprocessRuntime) diff --git a/packages/subprocess/subprocess-local/tests/native-containment.spec.ts b/packages/subprocess/subprocess-local/tests/native-containment.spec.ts new file mode 100644 index 0000000000..67bc46ecff --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/native-containment.spec.ts @@ -0,0 +1,270 @@ +import { spawn } from 'node:child_process' +import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterAll, describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import type { SubprocessSpawnSpec, SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess' +import LocalSubprocessRuntime from '../src/index.ts' +import { launchLinuxScope, probeLinuxScope } from '../src/linux-scope.ts' +import { targetEnvironment } from '../src/runner-launch.ts' +import { bindManagedProcess } from '../src/spawn.ts' + +const scratch = mkdtempSync(join(tmpdir(), 'dsh-native-containment-')) +afterAll(() => { rmSync(scratch, { recursive: true, force: true }) }) + +function spec(argv: string[], graceMs = 100): SubprocessSpawnSpec { + return { + argv, + cwd: scratch, + stdio: { + stdin: 'ignore', + stdout: { maxBytes: 64_000 }, + stderr: { maxBytes: 64_000 }, + }, + graceMs, + } +} + +type SpawnFailure = NodeJS.ErrnoException & { path?: string } + +function directSpawnFailure(argv: readonly string[]): Promise { + return new Promise((resolve, reject) => { + const child = spawn(argv[0] as string, argv.slice(1), { cwd: scratch, stdio: 'ignore' }) + child.once('error', resolve) + child.once('spawn', () => { reject(new Error(`expected ${argv[0]} to fail before spawn`)) }) + }) +} + +async function waitForPid(path: string): Promise { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + try { + const pid = Number(readFileSync(path, 'utf8').trim()) + if (Number.isSafeInteger(pid) && pid > 0) return pid + } catch { + // The target has not written the file yet. + } + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid file ${path} was not written`) +} + +async function waitGone(pid: number): Promise { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + try { + process.kill(pid, 0) + try { + const stat = readFileSync(`/proc/${pid}/stat`, 'utf8') + const state = stat.slice(stat.lastIndexOf(')') + 2, stat.lastIndexOf(')') + 3) + if (state === 'Z' || state === 'X') return + } catch { + return + } + } catch { + return + } + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid ${pid} remained alive`) +} + +interface LinuxProcessState { + parentPid: number + processGroupId: number + sessionId: number + ttyNumber: number + foregroundProcessGroupId: number +} + +function readLinuxProcessState(pid: number): LinuxProcessState { + const stat = readFileSync(`/proc/${pid}/stat`, 'utf8') + const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/) + const [parentPid, processGroupId, sessionId, ttyNumber, foregroundProcessGroupId] = fields + .slice(1, 6) + .map(Number) + if ([parentPid, processGroupId, sessionId, ttyNumber, foregroundProcessGroupId] + .some(value => !Number.isSafeInteger(value))) { + throw new Error(`invalid /proc state for pid ${String(pid)}`) + } + return { + parentPid: parentPid as number, + processGroupId: processGroupId as number, + sessionId: sessionId as number, + ttyNumber: ttyNumber as number, + foregroundProcessGroupId: foregroundProcessGroupId as number, + } +} + +async function waitReparented(pid: number, originalParentPid: number): Promise { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + const state = readLinuxProcessState(pid) + if (state.parentPid !== originalParentPid) return state + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid ${String(pid)} remained parented to ${String(originalParentPid)}`) +} + +function captureTerminalOutput(handle: SubprocessTerminalHandle): { + text(): string + waitFor(marker: string): Promise +} { + let output = '' + handle.output.on('data', (chunk: Buffer) => { output += chunk.toString() }) + return { + text: () => output, + waitFor: async (marker) => { + const deadline = Date.now() + 5_000 + while (!output.includes(marker) && Date.now() < deadline) { + await new Promise(resolve => setTimeout(resolve, 20)) + } + if (!output.includes(marker)) { + throw new Error(`terminal did not emit ${JSON.stringify(marker)}; output: ${JSON.stringify(output)}`) + } + return output + }, + } +} + +async function waitForInputReadiness(handle: SubprocessTerminalHandle): Promise<{ + processGroupId: number + inputWaiting: boolean +}> { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + const foreground = await handle.inspectForeground() + if (foreground?.inputWaiting === true) return foreground + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`terminal ${String(handle.pid)} never became input-ready`) +} + +const linuxNative = process.platform === 'linux' && probeLinuxScope() + +describe.skipIf(!linuxNative)('Linux user-systemd native containment', () => { + it('terminates a setsid descendant and waits for the scope to become empty', async () => { + const pidFile = join(scratch, `setsid-${Date.now()}.pid`) + const command = `setsid sh -c 'echo $$ > "$1"; trap "" TERM; while :; do sleep 60; done' sh ${JSON.stringify(pidFile)} & wait` + const request = spec(['bash', '-c', command], 80) + const handle = bindManagedProcess(request, launchLinuxScope(request, targetEnvironment(request))) + let descendant: number | undefined + try { + descendant = await waitForPid(pidFile) + handle.terminate() + await handle.done + await expect(handle.waitForExit()).resolves.toBe(true) + await waitGone(descendant) + } finally { + handle.terminate() + await Promise.allSettled([handle.done, handle.waitForExit()]) + if (descendant !== undefined) { + try { process.kill(descendant, 'SIGKILL') } catch { /* already contained */ } + } + } + }) + + it('preserves Node-shaped ENOENT and EACCES spawn failures without replay', async () => { + const missingArgv = [`missing-native-target-${Date.now()}`, 'literal arg'] + const expectedMissing = await directSpawnFailure(missingArgv) + const missing = spec(missingArgv) + const missingHandle = bindManagedProcess(missing, launchLinuxScope(missing, targetEnvironment(missing))) + await expect(missingHandle.done).rejects.toMatchObject({ + name: expectedMissing.name, + message: expectedMissing.message, + code: expectedMissing.code, + syscall: expectedMissing.syscall, + path: expectedMissing.path, + }) + + const deniedPath = join(scratch, `not-executable-${Date.now()}`) + writeFileSync(deniedPath, '#!/bin/sh\nexit 0\n', { mode: 0o600 }) + chmodSync(deniedPath, 0o600) + const deniedArgv = [deniedPath, 'literal arg'] + const expectedDenied = await directSpawnFailure(deniedArgv) + const denied = spec(deniedArgv) + const deniedHandle = bindManagedProcess(denied, launchLinuxScope(denied, targetEnvironment(denied))) + await expect(deniedHandle.done).rejects.toMatchObject({ + name: expectedDenied.name, + message: expectedDenied.message, + code: expectedDenied.code, + syscall: expectedDenied.syscall, + path: expectedDenied.path, + }) + }) + + it('keeps PTY identity and readiness while containing a reparented setsid descendant', async () => { + const escapedPath = join(scratch, `escaped-terminal-${Date.now()}.sh`) + const terminalPath = join(scratch, `terminal-${Date.now()}.sh`) + const launcherPidFile = join(scratch, `terminal-launcher-${Date.now()}.pid`) + const descendantPidFile = join(scratch, `terminal-descendant-${Date.now()}.pid`) + writeFileSync(escapedPath, `#!/bin/sh +printf '%s\\n' "$$" > "$1" +trap '' TERM +while :; do sleep 60; done +`, { mode: 0o700 }) + writeFileSync(terminalPath, `#!/bin/bash +set -eu +launcher_pid_file=$1 +descendant_pid_file=$2 +escaped_path=$3 +sh -c 'printf "%s\\n" "$$" > "$1"; setsid "$2" "$3" /dev/null 2>&1 &' sh "$launcher_pid_file" "$escaped_path" "$descendant_pid_file" +while [ ! -s "$descendant_pid_file" ]; do sleep 0.01; done +if [ -r /dev/tty ] && [ -w /dev/tty ]; then tty_ready=yes; else tty_ready=no; fi +printf 'PTY_READY pid=%s tty=%s\\n' "$$" "$tty_ready" > /dev/tty +IFS= read -r value < /dev/tty +printf 'PTY_INPUT=%s\\n' "$value" > /dev/tty +while :; do sleep 60; done +`, { mode: 0o700 }) + + const ctx = new Context() + const fiber = await ctx.plugin(LocalSubprocessRuntime) + let descendant: number | undefined + let handle: SubprocessTerminalHandle | undefined + try { + handle = await ctx.subprocess.spawnTerminal({ + argv: [terminalPath, launcherPidFile, descendantPidFile, escapedPath], + cwd: scratch, + rows: 24, + cols: 80, + graceMs: 100, + }) + const output = captureTerminalOutput(handle) + const readyOutput = await output.waitFor('PTY_READY') + const reportedPid = Number(/PTY_READY pid=(\d+) tty=yes/.exec(readyOutput)?.[1]) + expect(reportedPid, readyOutput).toBe(handle.pid) + + const top = readLinuxProcessState(handle.pid) + expect(top).toMatchObject({ + processGroupId: handle.pid, + sessionId: handle.pid, + foregroundProcessGroupId: handle.pid, + }) + expect(top.ttyNumber).not.toBe(0) + + const foreground = await waitForInputReadiness(handle) + expect(foreground).toEqual({ processGroupId: handle.pid, inputWaiting: true }) + await handle.write('continue\n') + await output.waitFor('PTY_INPUT=continue') + + const launcher = await waitForPid(launcherPidFile) + descendant = await waitForPid(descendantPidFile) + const escaped = await waitReparented(descendant, launcher) + expect(escaped.parentPid).not.toBe(launcher) + expect(escaped.processGroupId).toBe(descendant) + expect(escaped.sessionId).toBe(descendant) + expect(escaped.sessionId).not.toBe(handle.pid) + + await handle.terminate() + await handle.done + await waitGone(descendant) + } finally { + if (handle !== undefined) await handle.terminate().catch(() => {}) + if (descendant !== undefined) { + try { process.kill(descendant, 'SIGKILL') } catch { /* already contained */ } + } + await fiber.dispose() + } + }, 15_000) +}) diff --git a/packages/subprocess/subprocess-local/tests/native-windows.spec.ts b/packages/subprocess/subprocess-local/tests/native-windows.spec.ts new file mode 100644 index 0000000000..2d14ca026d --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/native-windows.spec.ts @@ -0,0 +1,233 @@ +import { spawn, spawnSync } from 'node:child_process' +import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterAll, describe, expect, it } from 'vitest' +import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { targetEnvironment } from '../src/runner-launch.ts' +import { bindManagedProcess } from '../src/spawn.ts' +import { launchWindowsJob, probeWindowsJob } from '../src/windows-job.ts' + +const scratch = mkdtempSync(join(tmpdir(), 'dsh-native-windows-')) +afterAll(() => { rmSync(scratch, { recursive: true, force: true }) }) + +function spec(argv: string[], graceMs = 100, env?: NodeJS.ProcessEnv): SubprocessSpawnSpec { + return { + argv, + cwd: scratch, + stdio: { + stdin: 'ignore', + stdout: { maxBytes: 64_000 }, + stderr: { maxBytes: 64_000 }, + }, + graceMs, + env, + } +} + +async function waitForPid(path: string): Promise { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + try { + const pid = Number(readFileSync(path, 'utf8').trim()) + if (Number.isSafeInteger(pid) && pid > 0) return pid + } catch { + // Target has not written its descendant pid yet. + } + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid file ${path} was not written`) +} + +async function waitGone(pid: number): Promise { + const deadline = Date.now() + 5_000 + while (Date.now() < deadline) { + try { + process.kill(pid, 0) + } catch { + return + } + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error(`pid ${pid} remained alive`) +} + +function cleanup(pid: number): void { + spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' }) +} + +type SpawnFailure = NodeJS.ErrnoException & { path?: string } + +function expectedSpawnFailure(error: SpawnFailure): Record { + const expected: Record = { + name: error.name, + message: error.message, + code: error.code, + syscall: error.syscall, + } + if (Object.hasOwn(error, 'path')) expected.path = error.path + return expected +} + +function directSpawnFailure(argv: readonly string[], cwd = scratch): Promise { + return new Promise((resolve, reject) => { + try { + const child = spawn(argv[0] as string, argv.slice(1), { cwd, stdio: 'ignore' }) + child.once('error', resolve) + child.once('spawn', () => { reject(new Error(`expected ${argv[0]} to fail before spawn`)) }) + } catch (error) { + resolve(error as SpawnFailure) + } + }) +} + +const windowsNative = process.platform === 'win32' && probeWindowsJob() + +describe.skipIf(!windowsNative)('Windows Job native containment', () => { + it('keeps raw stdin writable while the runner starts the target', async () => { + const output = join(scratch, `stdin-${Date.now()}.txt`) + const script = ` + const { writeFileSync } = require('node:fs') + let input = '' + process.stdin.setEncoding('utf8') + process.stdin.on('data', chunk => { input += chunk }) + process.stdin.on('end', () => { writeFileSync(${JSON.stringify(output)}, input) }) + ` + const request = { + ...spec([process.execPath, '-e', script]), + stdio: { stdin: 'pipe', stdout: 'inherit', stderr: 'inherit' } as const, + } + const handle = bindManagedProcess(request, launchWindowsJob(request, targetEnvironment(request))) + if (handle.stdin === undefined) throw new Error('expected piped stdin') + await new Promise((resolve, reject) => { + handle.stdin?.once('error', reject) + handle.stdin?.end('immediate-stdin', resolve) + }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + expect(readFileSync(output, 'utf8')).toBe('immediate-stdin') + }) + + it('preserves direct Node null-device semantics for ignored stdin', async () => { + const script = ` + const stat = require('node:fs').fstatSync(0) + process.stdout.write(JSON.stringify({ + file: stat.isFile(), + directory: stat.isDirectory(), + block: stat.isBlockDevice(), + character: stat.isCharacterDevice(), + fifo: stat.isFIFO(), + socket: stat.isSocket(), + })) + ` + const direct = spawnSync(process.execPath, ['-e', script], { + cwd: scratch, + stdio: ['ignore', 'pipe', 'inherit'], + encoding: 'utf8', + }) + expect(direct.status).toBe(0) + + const request = spec([process.execPath, '-e', script]) + const handle = bindManagedProcess(request, launchWindowsJob(request, targetEnvironment(request))) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + expect(handle.collected.stdout?.readFrom(0).text).toBe(direct.stdout) + }) + + it('reports direct exit before terminating its default-inheritance descendant', async () => { + const pidFile = join(scratch, `job-survivor-${Date.now()}.pid`) + const factsFile = join(scratch, `job-facts-${Date.now()}.json`) + const targetCwd = join(scratch, `target-cwd-${Date.now()}`) + mkdirSync(targetCwd) + const script = ` + const { spawn } = require('node:child_process') + const { writeFileSync } = require('node:fs') + const { dirname } = require('node:path') + const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { cwd: dirname(process.execPath), stdio: 'ignore', detached: true }) + writeFileSync(${JSON.stringify(pidFile)}, String(child.pid)) + writeFileSync(${JSON.stringify(factsFile)}, JSON.stringify({ cwd: process.cwd(), value: process.env.TARGET_VALUE, arg: process.argv[1] })) + child.unref() + process.stdout.end() + process.stderr.end() + process.exitCode = 42 + ` + const request = { + ...spec([process.execPath, '-e', script, 'literal $HOME ${UNCHANGED}'], 100, { TARGET_VALUE: 'explicit' }), + cwd: targetCwd, + stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' } as const, + } + const handle = bindManagedProcess(request, launchWindowsJob(request, targetEnvironment(request))) + let descendant: number | undefined + try { + if (handle.stdout === undefined) throw new Error('expected piped stdout') + if (handle.stderr === undefined) throw new Error('expected piped stderr') + handle.stdout.resume() + handle.stderr.resume() + const stdoutEnded = new Promise((resolve, reject) => { + handle.stdout?.once('end', resolve) + handle.stdout?.once('error', reject) + }) + const stderrEnded = new Promise((resolve, reject) => { + handle.stderr?.once('end', resolve) + handle.stderr?.once('error', reject) + }) + descendant = await waitForPid(pidFile) + await expect(handle.done).resolves.toEqual({ exitCode: 42, signal: null }) + await expect(Promise.race([ + Promise.all([stdoutEnded, stderrEnded]).then(() => true), + new Promise(resolve => setTimeout(() => { resolve(false) }, 5_000)), + ])).resolves.toBe(true) + expect(readFileSync(factsFile, 'utf8')).toBe(JSON.stringify({ + cwd: targetCwd, + value: 'explicit', + arg: 'literal $HOME ${UNCHANGED}', + })) + await expect(handle.waitForExit(AbortSignal.timeout(30))).resolves.toBe(false) + handle.terminate() + await expect(handle.waitForExit()).resolves.toBe(true) + await waitGone(descendant) + } finally { + handle.terminate() + await Promise.allSettled([handle.done, handle.waitForExit()]) + if (descendant !== undefined) cleanup(descendant) + rmSync(targetCwd, { recursive: true, force: true }) + } + }) + + it('preserves missing-target and invalid-executable rejection errors', async () => { + const relativeExecutable = `relative-node-${String(Date.now())}.exe` + copyFileSync(process.execPath, join(scratch, relativeExecutable)) + const relative = spec([relativeExecutable, '-e', 'process.exit(17)']) + const relativeHandle = bindManagedProcess(relative, launchWindowsJob(relative, targetEnvironment(relative))) + await expect(relativeHandle.done).resolves.toEqual({ exitCode: 17, signal: null }) + await expect(relativeHandle.waitForExit()).resolves.toBe(true) + + const missing = spec([`missing-native-target-${Date.now()}.exe`]) + const expectedMissing = await directSpawnFailure(missing.argv) + const missingHandle = bindManagedProcess(missing, launchWindowsJob(missing, targetEnvironment(missing))) + await expect(missingHandle.done).rejects.toMatchObject(expectedSpawnFailure(expectedMissing)) + await expect(missingHandle.waitForExit()).resolves.toBe(true) + + const expectedAccessDenied = await directSpawnFailure([scratch]) + const accessDenied = spec([scratch]) + const accessDeniedHandle = bindManagedProcess(accessDenied, launchWindowsJob(accessDenied, targetEnvironment(accessDenied))) + await expect(accessDeniedHandle.done).rejects.toMatchObject(expectedSpawnFailure(expectedAccessDenied)) + await expect(accessDeniedHandle.waitForExit()).resolves.toBe(true) + + const missingCwd = join(scratch, `missing-cwd-${Date.now()}`) + const cwdArgv = [process.execPath, '-e', 'process.exit(0)'] + const expectedCwd = await directSpawnFailure(cwdArgv, missingCwd) + const invalidCwd = { ...spec(cwdArgv), cwd: missingCwd } + const invalidCwdHandle = bindManagedProcess(invalidCwd, launchWindowsJob(invalidCwd, targetEnvironment(invalidCwd))) + await expect(invalidCwdHandle.done).rejects.toMatchObject(expectedSpawnFailure(expectedCwd)) + await expect(invalidCwdHandle.waitForExit()).resolves.toBe(true) + + const invalidExecutable = join(scratch, `direct-${Date.now()}.exe`) + writeFileSync(invalidExecutable, 'not a Windows executable\r\n') + const directError = await directSpawnFailure([invalidExecutable]) + const invalid = spec([invalidExecutable]) + const invalidHandle = bindManagedProcess(invalid, launchWindowsJob(invalid, targetEnvironment(invalid))) + await expect(invalidHandle.done).rejects.toMatchObject(expectedSpawnFailure(directError)) + await expect(invalidHandle.waitForExit()).resolves.toBe(true) + }) +}) diff --git a/packages/subprocess/subprocess-local/tests/process-exit.spec.ts b/packages/subprocess/subprocess-local/tests/process-exit.spec.ts index 1fc952a869..107d032da5 100644 --- a/packages/subprocess/subprocess-local/tests/process-exit.spec.ts +++ b/packages/subprocess/subprocess-local/tests/process-exit.spec.ts @@ -15,7 +15,8 @@ interface TreeState { root: number; descendant: number } const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url)) const hostScript = fileURLToPath(new URL('./fixtures/process-exit-host.ts', import.meta.url)) -const scenarioTimeoutMs = 30_000 +const scenarioTimeoutMs = process.platform === 'win32' ? 60_000 : 30_000 +const testTimeoutMs = scenarioTimeoutMs + 15_000 function processExists(pid: number): boolean { try { @@ -141,7 +142,7 @@ describe('synchronous cleanup on host exit', () => { { trigger: 'direct' as const, expectedCode: 23, diagnostic: undefined }, { trigger: 'uncaught-exception' as const, expectedCode: 1, diagnostic: 'host-exit-uncaught-exception' }, { trigger: 'unhandled-rejection' as const, expectedCode: 1, diagnostic: 'host-exit-unhandled-rejection' }, - ])('removes an ordinary managed tree after $trigger', { timeout: 45_000 }, async ({ + ])('removes an ordinary managed tree after $trigger', { timeout: testTimeoutMs }, async ({ trigger, expectedCode, diagnostic, @@ -154,7 +155,7 @@ describe('synchronous cleanup on host exit', () => { it.skipIf(process.platform === 'win32')( 'removes a terminal root and descendant after direct exit', - { timeout: 45_000 }, + { timeout: testTimeoutMs }, async () => { const { outcome } = await runScenario('terminal', 'direct') expect(outcome.exitCode).toBe(23) @@ -162,7 +163,7 @@ describe('synchronous cleanup on host exit', () => { }, ) - it('preserves normal terminate-and-join disposal and removes the exit listener', { timeout: 45_000 }, async () => { + it('preserves normal terminate-and-join disposal and removes the exit listener', { timeout: testTimeoutMs }, async () => { const { outcome, disposeCounts } = await runScenario('ordinary', 'dispose') expect(outcome.exitCode).toBe(0) expect(disposeCounts?.listenersAfterLoad).toBe((disposeCounts?.listenersBefore ?? 0) + 1) diff --git a/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts b/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts new file mode 100644 index 0000000000..f6602c8a61 --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts @@ -0,0 +1,116 @@ +import { spawn } from 'node:child_process' +import type { Buffer } from 'node:buffer' +import { existsSync } from 'node:fs' +import { resolve } from 'node:path' +import { fileURLToPath } from 'node:url' +import { describe, expect, it } from 'vitest' +import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess' +import { + cleanupLinuxLaunchFiles, + createLinuxLaunchFiles, +} from '../src/runner-protocol.ts' +import { + runnerEnvironment, + runnerInvocationAvailable, + SUBPROCESS_RUNNER_ENV, + targetEnvironment, +} from '../src/runner-launch.ts' +import type { RunnerInvocation } from '../src/runner-launch.ts' +import { bindManagedProcess } from '../src/spawn.ts' +import { launchWindowsJob } from '../src/windows-job.ts' + +const repoRoot = resolve(import.meta.dirname, '../../../..') +const sourceRunner = resolve(repoRoot, 'packages/subprocess/subprocess-local/src/bin.ts') +const builtRunner = fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-subprocess-local/runner')) + +function targetEnv(): Record { + return { + ...Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined)), + [SUBPROCESS_RUNNER_ENV]: 'target-collision-restored', + } +} + +async function executePosix(invocation: RunnerInvocation): Promise<{ status: number | null; stdout: string; stderr: string }> { + const files = createLinuxLaunchFiles({ cwd: repoRoot, env: targetEnv() }) + try { + const child = spawn(invocation[0], [ + ...invocation.slice(1), + '--', + process.execPath, + '--input-type=module', + '--eval', + `process.stdout.write(process.argv[0]+'|'+process.cwd()+'|'+process.env.${SUBPROCESS_RUNNER_ENV})`, + ], { + env: runnerEnvironment(files.requestPath, invocation), + stdio: ['ignore', 'pipe', 'pipe'], + }) + let stdout = '' + let stderr = '' + child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() }) + child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() }) + const status = await new Promise((resolveExit, rejectExit) => { + child.once('error', rejectExit) + child.once('exit', resolveExit) + }) + return { status, stdout, stderr } + } finally { + cleanupLinuxLaunchFiles(files) + } +} + +async function executeWindows(invocation: RunnerInvocation): Promise<{ status: number | null; stdout: string; stderr: string }> { + const request: SubprocessSpawnSpec = { + argv: [ + process.execPath, + '--input-type=module', + '--eval', + `process.stdout.write(process.argv[0]+'|'+process.cwd()+'|'+process.env.${SUBPROCESS_RUNNER_ENV})`, + ], + cwd: repoRoot, + env: targetEnv(), + stdio: { + stdin: 'ignore', + stdout: { maxBytes: 64_000 }, + stderr: { maxBytes: 64_000 }, + }, + graceMs: 3_000, + } + const handle = bindManagedProcess(request, launchWindowsJob( + request, + targetEnvironment(request), + { runnerInvocation: invocation }, + )) + const outcome = await handle.done + await handle.waitForExit() + const stdout = handle.collected.stdout?.readFrom(0).text ?? '' + const stderr = handle.collected.stderr?.readFrom(0).text ?? '' + return { status: outcome.exitCode, stdout, stderr } +} + +async function execute(invocation: RunnerInvocation): Promise<{ status: number | null; stdout: string; stderr: string }> { + return process.platform === 'win32' + ? executeWindows(invocation) + : executePosix(invocation) +} + +describe('subprocess-local runner artifacts', () => { + it('executes the source entry through the provider-owned core', async () => { + const result = await execute([process.execPath, '--import', 'tsx/esm', sourceRunner]) + expect(result).toEqual({ + status: 0, + stdout: `${process.execPath}|${repoRoot}|target-collision-restored`, + stderr: '', + }) + }, 30_000) + + it.skipIf(!existsSync(builtRunner))('executes the built ./runner subpath through the same core', async () => { + const invocation: RunnerInvocation = [process.execPath, builtRunner] + expect(runnerInvocationAvailable(invocation)).toBe(true) + const result = await execute(invocation) + expect(result).toEqual({ + status: 0, + stdout: `${process.execPath}|${repoRoot}|target-collision-restored`, + stderr: '', + }) + }, 30_000) +}) diff --git a/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts new file mode 100644 index 0000000000..bbaeb07745 --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts @@ -0,0 +1,979 @@ +import { EventEmitter } from 'node:events' +import { spawnSync } from 'node:child_process' +import { + existsSync, + mkdtempSync, + mkdirSync, + readdirSync, + rmSync, + statSync, + symlinkSync, + unlinkSync, + writeFileSync, +} from 'node:fs' +import { tmpdir } from 'node:os' +import { join, posix, resolve } from 'node:path' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Win32Error } from '@deepseek-ai/dsh-win32-process' +import type { + CurrentTokenProcessBindings, + NativePtr, +} from '@deepseek-ai/dsh-win32-process' +import { + cleanupLinuxLaunchFiles, + consumeLinuxLaunchRequest, + createLinuxLaunchFiles, + deserializeRunnerError, + isWindowsTerminateRequest, + linuxLaunchFilesFromLocator, + parseWindowsRunnerResult, + parseWindowsStartRequest, + readLinuxStartupError, + serializeRunnerError, + writeLinuxStartupError, +} from '../src/runner-protocol.ts' +import { + consumeRunnerSelection, + parseRunnerTargetArgv, + runnerEnvironment, + runnerInvocationAvailable, + runnerStdio, + resolveWindowsExecutable, + spawnRunnerInvocation, + SUBPROCESS_RUNNER_ENV, + targetEnvironment, + WINDOWS_RUNNER_SELECTION, +} from '../src/runner-launch.ts' +import { + reportSpawnRunnerFailure, + runSpawnRunner, +} from '../src/spawn-runner.ts' +import type { SpawnRunnerInternals } from '../src/spawn-runner.ts' + +const scratch: string[] = [] + +afterEach(() => { + for (const path of scratch.splice(0)) rmSync(path, { recursive: true, force: true }) + vi.restoreAllMocks() +}) + +function track(files: T): T { + scratch.push(files.directory) + return files +} + +class FakeRunnerHost extends EventEmitter { + env: NodeJS.ProcessEnv = { [SUBPROCESS_RUNNER_ENV]: 'stale', SAFE: 'bootstrap' } + exitCode: number | undefined + connected = true + directory = process.cwd() + sent: unknown[] = [] + sendFailure: Error | undefined + sendThrown: unknown + + cwd(): string { return this.directory } + chdir(path: string): void { this.directory = posix.resolve(this.directory, path) } + disconnect(): void { + if (!this.connected) return + this.connected = false + this.emit('disconnect') + } + send(message: unknown, callback?: (error: Error | null) => void): boolean { + if (this.sendThrown !== undefined) throw this.sendThrown + this.sent.push(message) + queueMicrotask(() => { callback?.(this.sendFailure ?? null) }) + return true + } +} + +function hostArgument(host: FakeRunnerHost): Parameters[2] { + return host as unknown as Parameters[2] +} + +function internals(overrides: Partial = {}): SpawnRunnerInternals { + return { + execve: vi.fn(() => { throw Object.assign(new Error('missing'), { code: 'ENOENT' }) }), + loadWin32ProcessBindings: vi.fn(() => ({} as CurrentTokenProcessBindings)), + spawnCurrentTokenJobProcess: vi.fn(() => ({ + pid: 123, + process: 10n as NativePtr, + job: 20n as NativePtr, + })), + closeFileDescriptor: vi.fn(), + resolveWindowsExecutable: vi.fn(() => 'C:\\resolved\\tool.exe'), + pollProcessExit: vi.fn(() => 0), + isJobEmpty: vi.fn(() => true), + terminateJob: vi.fn(), + closeHandleChecked: vi.fn(), + ...overrides, + } +} + +async function runWindows( + host: FakeRunnerHost, + native: SpawnRunnerInternals, + start: unknown = { type: 'start', cwd: 'C:\\target', env: { TARGET: 'yes', dsh_subprocess_runner: 'restored' } }, + targetArgv: string[] = ['tool.exe', 'literal arg'], +): Promise { + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', ...targetArgv], + hostArgument(host), + native, + ) + host.emit('message', start) + await running +} + +describe('closed runner protocol', () => { + it('creates, consumes, reports through, and cleans one private Linux exchange', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/target', env: { A: '1' } })) + if (process.platform !== 'win32') { + expect(statSync(files.directory).mode & 0o777).toBe(0o700) + expect(statSync(files.requestPath).mode & 0o777).toBe(0o600) + } + expect(linuxLaunchFilesFromLocator(files.requestPath)).toEqual(files) + expect(consumeLinuxLaunchRequest(files.requestPath)).toEqual({ cwd: '/target', env: { A: '1' } }) + expect(existsSync(files.requestPath)).toBe(false) + + const failure = Object.assign(new Error('spawn missing'), { + name: 'SpawnError', code: 'ENOENT', errno: -2, syscall: 'spawn tool', path: 'tool', spawnargs: ['x'], + }) + writeLinuxStartupError(files, { type: 'error', error: serializeRunnerError(failure) }) + if (process.platform !== 'win32') { + expect(statSync(files.startupErrorPath).mode & 0o777).toBe(0o600) + } + const result = readLinuxStartupError(files.startupErrorPath) + expect(result).toEqual({ + type: 'error', + error: { + name: 'SpawnError', message: 'spawn missing', code: 'ENOENT', syscall: 'spawn tool', path: 'tool', + }, + }) + expect(deserializeRunnerError(result!.error)).toMatchObject({ + name: 'SpawnError', message: 'spawn missing', code: 'ENOENT', syscall: 'spawn tool', path: 'tool', + }) + cleanupLinuxLaunchFiles(files) + expect(existsSync(files.directory)).toBe(false) + }) + + it('removes the private directory when request creation fails partway through', () => { + const isolatedTmp = mkdtempSync(join(tmpdir(), 'dsh-launch-failure-spec-')) + vi.stubEnv('TMPDIR', isolatedTmp) + vi.stubEnv('TMP', isolatedTmp) + vi.stubEnv('TEMP', isolatedTmp) + try { + const stringify = vi.spyOn(JSON, 'stringify').mockImplementationOnce(() => { + throw new Error('request serialization failed') + }) + expect(() => createLinuxLaunchFiles({ cwd: '/target', env: {} })).toThrow('request serialization failed') + stringify.mockRestore() + expect(readdirSync(isolatedTmp)).toEqual([]) + } finally { + vi.unstubAllEnvs() + rmSync(isolatedTmp, { recursive: true, force: true }) + } + }) + + it('strictly rejects malformed Linux and Windows messages', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + writeFileSync(files.requestPath, JSON.stringify({ cwd: '/ok', env: {}, extra: true })) + expect(() => consumeLinuxLaunchRequest(files.requestPath)).toThrow('invalid Linux launch request') + expect(() => linuxLaunchFilesFromLocator('relative.json')).toThrow('invalid Linux launch-request locator') + expect(readLinuxStartupError(files.startupErrorPath)).toBeUndefined() + writeFileSync(files.startupErrorPath, 'null') + expect(() => readLinuxStartupError(files.startupErrorPath)).toThrow('invalid startup error') + writeFileSync(files.startupErrorPath, JSON.stringify({ + type: 'unknown', error: { name: 'Error', message: 'bad' }, + })) + expect(() => readLinuxStartupError(files.startupErrorPath)).toThrow('unknown error result') + + expect(parseWindowsStartRequest({ type: 'start', cwd: 'C:\\x', env: { A: '1' } })).toEqual({ + type: 'start', cwd: 'C:\\x', env: { A: '1' }, + }) + expect(() => parseWindowsStartRequest({ type: 'start', cwd: 'C:\\x', env: {}, extra: 1 })).toThrow() + expect(isWindowsTerminateRequest({ type: 'terminate' })).toBe(true) + expect(isWindowsTerminateRequest({ type: 'terminate', reason: 'no' })).toBe(false) + expect(parseWindowsRunnerResult({ type: 'target-exit', exitCode: 7 })).toEqual({ + type: 'target-exit', exitCode: 7, + }) + expect(parseWindowsRunnerResult({ type: 'error', error: { name: 'Error', message: 'bad' } })).toEqual({ + type: 'error', error: { name: 'Error', message: 'bad' }, + }) + for (const invalid of [ + null, + { type: 'unknown' }, + { type: 'start-cancelled' }, + { type: 'start-cancelled', payload: 1 }, + { type: 'target-exit', exitCode: -1 }, + { type: 'target-exit', exitCode: 0, signal: null }, + { type: 'spawn-error', error: { name: 'Error', message: 'bad' } }, + { type: 'runner-error', error: { name: 'Error', message: 'bad' } }, + { type: 'error', error: { name: 'Error', message: 'bad', cause: {} } }, + ]) expect(() => parseWindowsRunnerResult(invalid)).toThrow() + }) + + it('contains cleanup failures and removes a substituted symlink only', () => { + const files = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + cleanupLinuxLaunchFiles(files) + cleanupLinuxLaunchFiles(files) + + const target = join(tmpdir(), `dsh-runner-cleanup-target-${String(process.pid)}`) + const link = join(tmpdir(), `dsh-runner-cleanup-link-${String(process.pid)}`) + scratch.push(target, link) + mkdirSync(target, { recursive: true }) + symlinkSync(target, link) + cleanupLinuxLaunchFiles({ + directory: link, + requestPath: join(link, 'launch-request.json'), + startupErrorPath: join(link, 'startup-error.json'), + }) + expect(existsSync(link)).toBe(false) + expect(existsSync(target)).toBe(true) + + const blocked = track(createLinuxLaunchFiles({ cwd: '/ok', env: {} })) + unlinkSync(blocked.requestPath) + mkdirSync(blocked.requestPath) + cleanupLinuxLaunchFiles(blocked) + expect(existsSync(blocked.directory)).toBe(true) + }) +}) + +describe('runner launch inputs', () => { + const spec = { + argv: ['node', 'a'], + cwd: process.cwd(), + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' }, + graceMs: 100, + env: { EXPLICIT: 'yes' }, + } as const + + it('keeps target state out of the bootstrap environment and consumes its selector', () => { + const env = runnerEnvironment('/tmp/request') + const sourceEnv = runnerEnvironment('/tmp/request', [process.execPath, '/repo/bin.ts']) + const builtEnv = runnerEnvironment('/tmp/request', [process.execPath, '/repo/runner.js']) + expect(env[SUBPROCESS_RUNNER_ENV]).toBe('/tmp/request') + expect(env.SYSTEMD_LOG_TARGET).toBe('null') + expect(env.EXPLICIT).toBeUndefined() + expect(sourceEnv.TSX_TSCONFIG_PATH).toBe(resolve(import.meta.dirname, '../../../..', 'tsconfig.base.json')) + expect(builtEnv.TSX_TSCONFIG_PATH).toBe(env.TSX_TSCONFIG_PATH) + expect(consumeRunnerSelection(env)).toBe('/tmp/request') + expect(env[SUBPROCESS_RUNNER_ENV]).toBeUndefined() + expect(consumeRunnerSelection({})).toBeUndefined() + expect(parseRunnerTargetArgv(['--', 'node', 'a'])).toEqual(['node', 'a']) + expect(() => parseRunnerTargetArgv(['node'])).toThrow('private -- delimiter') + expect(runnerStdio(spec, false)).toEqual(['pipe', 'pipe', 'inherit']) + expect(runnerStdio(spec, true)).toEqual([ + 'ignore', 'ignore', 'ignore', 'ipc', 'pipe', 'pipe', 2, + ]) + expect(runnerStdio({ + ...spec, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'pipe' }, + }, false)).toEqual(['ignore', 'inherit', 'pipe']) + expect(runnerStdio({ + ...spec, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'pipe' }, + }, true, 17)).toEqual(['ignore', 'ignore', 'ignore', 'ipc', 17, 1, 'pipe']) + }) + + it('removes ambient Node and tsx controls from the bootstrap environment only', () => { + vi.stubEnv('NODE_OPTIONS', '--require /tmp/runner-bootstrap-control.cjs') + vi.stubEnv('NODE_DEBUG', 'esm') + vi.stubEnv('TSX_DISABLE_CACHE', '1') + vi.stubEnv('TSX_TSCONFIG_PATH', '/ambient/tsconfig.json') + try { + const sourceEnv = runnerEnvironment('/tmp/request', [process.execPath, '/repo/bin.ts']) + const builtEnv = runnerEnvironment('/tmp/request', [process.execPath, '/repo/runner.js']) + expect(sourceEnv.NODE_OPTIONS).toBeUndefined() + expect(sourceEnv.NODE_DEBUG).toBeUndefined() + expect(sourceEnv.TSX_DISABLE_CACHE).toBeUndefined() + expect(sourceEnv.TSX_TSCONFIG_PATH) + .toBe(resolve(import.meta.dirname, '../../../..', 'tsconfig.base.json')) + expect(builtEnv.NODE_OPTIONS).toBeUndefined() + expect(builtEnv.NODE_DEBUG).toBeUndefined() + expect(builtEnv.TSX_DISABLE_CACHE).toBeUndefined() + expect(builtEnv.TSX_TSCONFIG_PATH).toBeUndefined() + expect(targetEnvironment(spec)).toMatchObject({ + NODE_OPTIONS: '--require /tmp/runner-bootstrap-control.cjs', + NODE_DEBUG: 'esm', + TSX_DISABLE_CACHE: '1', + TSX_TSCONFIG_PATH: '/ambient/tsconfig.json', + }) + } finally { + vi.unstubAllEnvs() + } + }) + + it('validates every Node-baseline NUL location before launch', () => { + expect(targetEnvironment(spec)).toMatchObject({ EXPLICIT: 'yes' }) + expect(targetEnvironment({ ...spec, env: { '=C:': 'C:\\target' } })) + .toMatchObject({ '=C:': 'C:\\target' }) + for (const invalid of [ + { ...spec, argv: ['node\0'] }, + { ...spec, argv: ['node', 'a\0'] }, + { ...spec, cwd: 'bad\0cwd' }, + { ...spec, env: { 'BAD\0KEY': 'x' } }, + { ...spec, env: { BAD: 'x\0' } }, + ]) { + try { + targetEnvironment(invalid) + throw new Error('expected targetEnvironment to reject') + } catch (error) { + expect(error).toMatchObject({ name: 'TypeError', code: 'ERR_INVALID_ARG_VALUE' }) + } + } + }) + + it('resolves the source runner entry and checks concrete paths without executing it', () => { + const invocation = spawnRunnerInvocation() + expect(invocation[0]).toBe(process.execPath) + expect(invocation).toContain(import.meta.resolve('tsx/esm')) + expect(runnerInvocationAvailable(invocation)).toBe(true) + expect(runnerInvocationAvailable(['/definitely/missing-dsh-runner'])).toBe(false) + expect(runnerInvocationAvailable(['node'])).toBe(true) + expect(runnerInvocationAvailable(['node', 'runner.js'])).toBe(true) + + Object.defineProperty(process, 'pkg', { configurable: true, value: {} }) + try { + expect(spawnRunnerInvocation()).toEqual([process.execPath]) + } finally { + Reflect.deleteProperty(process, 'pkg') + } + }) + + it('loads the source runner from an isolated application cwd', () => { + const directory = mkdtempSync(join(tmpdir(), 'dsh-runner-cwd-')) + scratch.push(directory) + const invocation = spawnRunnerInvocation() + const env = runnerEnvironment('unused', invocation) + Reflect.deleteProperty(env, SUBPROCESS_RUNNER_ENV) + const launched = spawnSync(invocation[0], invocation.slice(1), { + cwd: directory, + env, + encoding: 'utf8', + }) + expect(launched.status).toBe(127) + expect(launched.stderr).not.toContain('ERR_MODULE_NOT_FOUND') + }) + + it('serializes only the private protocol diagnostic fields', () => { + expect(serializeRunnerError('plain failure')).toMatchObject({ + name: 'Error', message: 'plain failure', + }) + const detailed = Object.assign(new Error('detailed'), { + code: 'ENOENT', errno: -2, syscall: 'spawn tool', path: 'tool', spawnargs: ['arg'], + }) + expect(serializeRunnerError(detailed)).toEqual({ + name: 'Error', message: 'detailed', code: 'ENOENT', syscall: 'spawn tool', path: 'tool', + }) + const minimal = deserializeRunnerError({ name: 'Error', message: 'minimal' }) + expect(minimal).toMatchObject({ name: 'Error', message: 'minimal' }) + expect(minimal).not.toHaveProperty('code') + expect(minimal).not.toHaveProperty('syscall') + expect(minimal).not.toHaveProperty('path') + }) + + it('resolves Windows executables with target-cwd and PATH search semantics', () => { + const probed: string[] = [] + const exists = (candidate: string): boolean => { + probed.push(candidate) + return candidate === 'C:\\tools\\git\\bin\\bash.exe' + } + expect(resolveWindowsExecutable('bash', 'C:\\target', { + Path: 'relative;"C:\\semi;colon";"C:\\tools\\git\\bin";C:\\later', + }, exists)).toBe('C:\\tools\\git\\bin\\bash.exe') + expect(probed).toEqual([ + 'C:\\target\\bash.com', + 'C:\\target\\bash.exe', + 'C:\\target\\relative\\bash.com', + 'C:\\target\\relative\\bash.exe', + 'C:\\semi;colon\\bash.com', + 'C:\\semi;colon\\bash.exe', + 'C:\\tools\\git\\bin\\bash.com', + 'C:\\tools\\git\\bin\\bash.exe', + ]) + + expect(resolveWindowsExecutable('local.exe', 'C:\\target', {}, candidate => + candidate === 'C:\\target\\local.exe')).toBe('C:\\target\\local.exe') + expect(resolveWindowsExecutable('tool', 'C:\\target', { + PATH: 'C:\\bin', + }, candidate => candidate === 'C:\\bin\\tool.com', { + NoDefaultCurrentDirectoryInExePath: '1', + })).toBe('C:\\bin\\tool.com') + expect(resolveWindowsExecutable('tool', 'C:\\target', { + PATH: 'D:relative', + }, candidate => candidate === 'D:relative\\tool.exe')).toBe('D:relative\\tool.exe') + expect(resolveWindowsExecutable('tool.', 'C:\\target', {}, candidate => + candidate === 'C:\\target\\tool.exe')).toBe('C:\\target\\tool.exe') + expect(resolveWindowsExecutable('.\\missing', 'C:\\target', {}, () => false)) + .toBeUndefined() + + expect(resolveWindowsExecutable('tool', 'C:\\target', { + PATH: ';;C:\\bin', + }, candidate => candidate === 'C:\\bin\\tool.exe')).toBe('C:\\bin\\tool.exe') + expect(resolveWindowsExecutable('tool', 'C:\\target', { + PATH: '"";C:\\bin', + }, candidate => candidate === 'C:\\bin\\tool.exe')).toBe('C:\\bin\\tool.exe') + expect(resolveWindowsExecutable('tool', 'C:\\target', { + PATH: '"unterminated', + }, candidate => candidate === 'C:\\target\\unterminated\\tool.exe')) + .toBe('C:\\target\\unterminated\\tool.exe') + expect(resolveWindowsExecutable('\\\\server\\share\\tool', 'C:\\target', {}, candidate => + candidate === '\\\\server\\share\\tool.exe')).toBe('\\\\server\\share\\tool.exe') + expect(resolveWindowsExecutable('\\tools\\tool', 'C:\\target', {}, candidate => + candidate === 'C:\\tools\\tool.exe')).toBe('C:\\tools\\tool.exe') + expect(resolveWindowsExecutable('C:tools\\tool', 'C:\\target', {}, candidate => + candidate === 'C:\\target\\tools\\tool.exe')).toBe('C:\\target\\tools\\tool.exe') + + const noSearchEnvironment = { NoDefaultCurrentDirectoryInExePath: '1' } + expect(resolveWindowsExecutable('missing', 'C:\\target', {}, () => false, noSearchEnvironment)) + .toBeUndefined() + expect(resolveWindowsExecutable('missing.cmd', 'C:\\target', {}, () => false, noSearchEnvironment)) + .toBeUndefined() + + const directory = mkdtempSync(join(tmpdir(), 'dsh-windows-resolver-')) + scratch.push(directory) + const executable = join(directory, 'direct.exe') + const directoryCandidate = join(directory, 'directory') + const missingExecutable = join(directory, 'missing.exe') + const danglingAlias = join(directory, 'alias.exe') + writeFileSync(executable, '') + mkdirSync(`${directoryCandidate}.com`) + writeFileSync(`${directoryCandidate}.exe`, '') + symlinkSync(missingExecutable, danglingAlias, 'file') + expect(resolveWindowsExecutable(executable, '', {})).toBe(executable) + expect(resolveWindowsExecutable(directoryCandidate, '', {})).toBe(`${directoryCandidate}.exe`) + expect(resolveWindowsExecutable(danglingAlias, '', {})).toBe(danglingAlias) + expect(resolveWindowsExecutable(missingExecutable, '', {})).toBeUndefined() + }) +}) + +describe('Linux one-shot exec bootstrap', () => { + it('uses final cwd/env PATH while preserving the original argv', async () => { + const files = track(createLinuxLaunchFiles({ + cwd: '/final/work', + env: { PATH: 'relative::/absolute', [SUBPROCESS_RUNNER_ENV]: 'target-value' }, + })) + const host = new FakeRunnerHost() + const execve = vi.fn((_file: string, _argv: string[], _env: Record) => { + throw Object.assign(new Error('not found'), { code: 'ENOENT' }) + }) + await runSpawnRunner(files.requestPath, ['--', 'tool', 'literal arg'], hostArgument(host), internals({ execve })) + expect(host.directory).toBe('/final/work') + expect(host.env[SUBPROCESS_RUNNER_ENV]).toBeUndefined() + expect(execve.mock.calls.map(call => call[0])).toEqual([ + '/final/work/relative/tool', + '/final/work/tool', + '/absolute/tool', + ]) + expect(execve.mock.calls[0]?.[1]).toEqual(['tool', 'literal arg']) + expect(execve.mock.calls[0]?.[2]).toMatchObject({ [SUBPROCESS_RUNNER_ENV]: 'target-value' }) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ + type: 'error', + error: { + name: 'Error', + message: 'spawn tool ENOENT', + code: 'ENOENT', + syscall: 'spawn tool', + path: 'tool', + }, + }) + }) + + it('resolves relative PATH entries from the cwd after chdir', async () => { + const files = track(createLinuxLaunchFiles({ cwd: 'work', env: { PATH: 'bin:' } })) + const host = new FakeRunnerHost() + host.directory = '/base' + const execve = vi.fn((_file: string, _argv: string[], _env: Record): never => { + throw Object.assign(new Error('not found'), { code: 'ENOENT' }) + }) + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(host), internals({ execve })) + expect(host.directory).toBe('/base/work') + expect(execve.mock.calls.map(call => call[0])).toEqual([ + '/base/work/bin/tool', + '/base/work/tool', + ]) + + const rootFiles = track(createLinuxLaunchFiles({ cwd: '/', env: { PATH: '' } })) + const rootExecve = vi.fn((): never => { + throw Object.assign(new Error('not found'), { code: 'ENOENT' }) + }) + await runSpawnRunner( + rootFiles.requestPath, + ['--', 'tool'], + hostArgument(new FakeRunnerHost()), + internals({ execve: rootExecve }), + ) + expect(rootExecve).toHaveBeenCalledWith('/tool', ['tool'], { PATH: '' }) + }) + + it.skipIf(process.platform === 'win32')('preserves symlink-sensitive parent traversal in PATH candidates', async () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-linux-path-symlink-')) + scratch.push(root) + const cwd = join(root, 'cwd') + const target = join(root, 'target') + mkdirSync(cwd) + mkdirSync(join(target, 'child'), { recursive: true }) + writeFileSync(join(target, 'tool'), '') + symlinkSync(join(target, 'child'), join(cwd, 'link'), 'dir') + const files = track(createLinuxLaunchFiles({ cwd, env: { PATH: 'link/..' } })) + const execve = vi.fn((file: string): never => { + throw Object.assign(new Error(existsSync(file) ? 'selected' : 'not found'), { + code: existsSync(file) ? 'EIO' : 'ENOENT', + }) + }) + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals({ execve })) + expect(execve).toHaveBeenCalledWith(`${cwd}/link/../tool`, ['tool'], { PATH: 'link/..' }) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ + type: 'error', error: { code: 'EIO' }, + }) + }) + + it('retries ENOEXEC through /bin/sh with the resolved file and original arguments', async () => { + const files = track(createLinuxLaunchFiles({ cwd: '/work', env: { PATH: 'bin' } })) + const execve = vi.fn() + .mockImplementationOnce(() => { throw Object.assign(new Error('exec format'), { code: 'ENOEXEC' }) }) + .mockImplementationOnce(() => { throw Object.assign(new Error('shell failed'), { code: 'EIO' }) }) + await runSpawnRunner( + files.requestPath, + ['--', 'tool', 'literal arg'], + hostArgument(new FakeRunnerHost()), + internals({ execve: execve as never }), + ) + expect(execve.mock.calls).toEqual([ + ['/work/bin/tool', ['tool', 'literal arg'], { PATH: 'bin' }], + ['/bin/sh', ['/bin/sh', '/work/bin/tool', 'literal arg'], { PATH: 'bin' }], + ]) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ + type: 'error', error: { code: 'EIO', path: 'tool' }, + }) + }) + + it('uses the default PATH and stops on a non-search error', async () => { + const files = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const execve = vi.fn((_file: string) => { + throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES', errno: -13 }) + }) + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals({ execve })) + expect(execve.mock.calls.map(call => call[0])).toEqual(['/usr/bin/tool', '/bin/tool']) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ + type: 'error', + error: { + name: 'Error', + message: 'spawn tool EACCES', + code: 'EACCES', + syscall: 'spawn tool', + path: 'tool', + }, + }) + + const explicit = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const fatal = vi.fn(() => { throw Object.assign(new Error('bad executable'), { code: 'EIO' }) }) + await runSpawnRunner(explicit.requestPath, ['--', './tool'], hostArgument(new FakeRunnerHost()), internals({ execve: fatal })) + expect(fatal).toHaveBeenCalledOnce() + + const stackless = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + await runSpawnRunner(stackless.requestPath, ['--', './tool'], hostArgument(new FakeRunnerHost()), internals({ + execve: vi.fn(() => { throw new Error('unclassified failure') }), + })) + expect(readLinuxStartupError(stackless.startupErrorPath)).toMatchObject({ + type: 'error', error: { message: 'unclassified failure' }, + }) + + const searched = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + const searchedExecve = vi.fn() + .mockImplementationOnce(() => { throw Object.assign(new Error('not a directory'), { code: 'ENOTDIR' }) }) + .mockImplementationOnce(() => { throw Object.assign(new Error('I/O failure'), { code: 'EIO' }) }) + await runSpawnRunner(searched.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals({ + execve: searchedExecve as never, + })) + expect(readLinuxStartupError(searched.startupErrorPath)).toMatchObject({ + type: 'error', error: { code: 'EIO' }, + }) + }) + + it('publishes request and early protocol failures through the single error branch', async () => { + const files = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + writeFileSync(files.requestPath, '{') + await runSpawnRunner(files.requestPath, ['--', 'tool'], hostArgument(new FakeRunnerHost()), internals()) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ type: 'error' }) + + const early = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) + await reportSpawnRunnerFailure(early.requestPath, new Error('delimiter failed'), hostArgument(new FakeRunnerHost())) + expect(readLinuxStartupError(early.startupErrorPath)).toMatchObject({ + type: 'error', error: { message: 'delimiter failed' }, + }) + }) +}) + +describe('Windows Job runner protocol owner', () => { + it('publishes a Node-shaped path-search miss before loading Win32 bindings', async () => { + const host = new FakeRunnerHost() + const loadWin32ProcessBindings = vi.fn(() => ({} as CurrentTokenProcessBindings)) + const native = internals({ + loadWin32ProcessBindings, + resolveWindowsExecutable: vi.fn(() => undefined), + }) + await runWindows(host, native) + expect(loadWin32ProcessBindings).not.toHaveBeenCalled() + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + expect(host.sent).toEqual([{ + type: 'error', + error: { + name: 'Error', + message: 'spawn tool.exe ENOENT', + code: 'ENOENT', + syscall: 'spawn tool.exe', + path: 'tool.exe', + }, + }]) + expect(host.exitCode).toBe(0) + }) + + it('maps only the promised Win32 process-creation error subset', async () => { + for (const [win32Code, code, enriched, program] of [ + [2, 'ENOENT', true, 'tool.exe'], + [3, 'ENOENT', true, 'tool.exe'], + [267, 'ENOENT', true, 'tool.exe'], + [740, 'EACCES', true, '$&.exe'], + [5, 'EPERM', false, 'tool.exe'], + [193, 'EFTYPE', false, 'tool.exe'], + [4, 'UNKNOWN', false, 'tool.exe'], + ] as const) { + const host = new FakeRunnerHost() + await runWindows(host, internals({ + spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', win32Code) }), + }), undefined, [program, 'literal arg']) + const syscall = enriched ? `spawn ${program}` : 'spawn' + expect(host.sent).toMatchObject([{ + type: 'error', + error: { + name: 'Error', + message: `${syscall} ${code}`, + code, + syscall, + }, + }]) + const result = parseWindowsRunnerResult(host.sent[0]) + if (result.type !== 'error') throw new Error('expected runner error') + if (enriched) { + expect(result.error).toMatchObject({ path: program }) + } else { + expect(result.error).not.toHaveProperty('path') + } + } + }) + + it('rejects a Windows runner without an initial IPC channel', async () => { + const disconnected = new FakeRunnerHost() + disconnected.connected = false + await runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(disconnected), + internals(), + ) + expect(disconnected.exitCode).toBe(127) + + const missingSend = new FakeRunnerHost() + Object.defineProperty(missingSend, 'send', { value: undefined }) + await runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(missingSend), + internals(), + ) + expect(missingSend.exitCode).toBe(127) + }) + + it('sends target-exit only after suspended Job launch and closes runner stdio', async () => { + const host = new FakeRunnerHost() + const closeFileDescriptor = vi.fn() + const native = internals({ closeFileDescriptor }) + await runWindows(host, native) + expect(native.resolveWindowsExecutable).toHaveBeenCalledWith( + 'tool.exe', + 'C:\\target', + { TARGET: 'yes', dsh_subprocess_runner: 'restored' }, + undefined, + { SAFE: 'bootstrap' }, + ) + expect(native.spawnCurrentTokenJobProcess).toHaveBeenCalledWith(expect.anything(), { + command: 'tool.exe', applicationName: 'C:\\resolved\\tool.exe', args: ['literal arg'], cwd: 'C:\\target', + env: { TARGET: 'yes', dsh_subprocess_runner: 'restored' }, + stdio: { stdin: 4, stdout: 5, stderr: 6 }, + }) + expect(closeFileDescriptor).toHaveBeenCalledTimes(3) + expect(closeFileDescriptor).toHaveBeenNthCalledWith(1, 4) + expect(closeFileDescriptor).toHaveBeenNthCalledWith(2, 5) + expect(closeFileDescriptor).toHaveBeenNthCalledWith(3, 6) + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 10n, 'ordinary direct process') + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 20n, 'ordinary process Job') + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) + expect(host.exitCode).toBe(0) + expect(host.env).toEqual({ SAFE: 'bootstrap' }) + }) + + it('closes every target carrier before the first Windows poll', async () => { + const events: string[] = [] + const interval = vi.spyOn(globalThis, 'setInterval').mockImplementation((callback: () => void) => { + events.push('interval') + queueMicrotask(callback) + return 1 as unknown as ReturnType + }) + try { + const host = new FakeRunnerHost() + const native = internals({ + closeFileDescriptor: vi.fn((fileDescriptor) => { events.push(`close:${String(fileDescriptor)}`) }), + pollProcessExit: vi.fn(() => { + events.push('poll') + return 0 + }), + }) + await runWindows(host, native) + expect(events).toEqual(['close:4', 'close:5', 'close:6', 'interval', 'poll']) + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) + expect(host.exitCode).toBe(0) + } finally { + interval.mockRestore() + } + }) + + it('exhausts target-exit and strict error results, including start cancellation', async () => { + const spawnHost = new FakeRunnerHost() + await runWindows(spawnHost, internals({ + spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', 2) }), + })) + expect(spawnHost.sent).toMatchObject([{ type: 'error', error: { code: 'ENOENT', path: 'tool.exe' } }]) + expect(spawnHost.exitCode).toBe(0) + + const runnerHost = new FakeRunnerHost() + await runWindows(runnerHost, internals({ + loadWin32ProcessBindings: vi.fn(() => { throw new Error('binding failed') }), + })) + expect(runnerHost.sent).toMatchObject([{ type: 'error', error: { message: 'binding failed' } }]) + expect(runnerHost.exitCode).toBe(127) + + const cancelledHost = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(cancelledHost), native) + cancelledHost.emit('message', { type: 'terminate' }) + cancelledHost.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await running + expect(cancelledHost.sent).toEqual([{ + type: 'error', + error: { + name: 'Error', + message: 'subprocess target start was cancelled', + }, + }]) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + }) + + it('cancels after accepting start but before target commit', async () => { + const host = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + host.emit('message', { type: 'terminate' }) + await running + expect(host.sent).toEqual([{ + type: 'error', + error: { + name: 'Error', + message: 'subprocess target start was cancelled', + }, + }]) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + }) + + it('does not create a target after pre-commit IPC disconnect', async () => { + const host = new FakeRunnerHost() + const native = internals() + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + host.disconnect() + await running + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + expect(native.spawnCurrentTokenJobProcess).not.toHaveBeenCalled() + expect(native.terminateJob).not.toHaveBeenCalled() + expect(host.exitCode).toBe(127) + }) + + it('terminates and closes the unique Job immediately when IPC disconnects', async () => { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + host.disconnect() + await running + expect(native.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + expect(native.closeHandleChecked).toHaveBeenCalledWith(expect.anything(), 20n, 'ordinary process Job cleanup') + expect(host.exitCode).toBe(127) + }) + + it('honors terminate after commit and treats result-send failure as infrastructure failure', async () => { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(host), native) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + host.emit('message', { type: 'terminate' }) + host.emit('message', { type: 'terminate' }) + expect(native.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + host.disconnect() + await running + + const sendFailureHost = new FakeRunnerHost() + sendFailureHost.sendFailure = new Error('send failed') + const sendFailureNative = internals({ isJobEmpty: vi.fn(() => false) }) + await runWindows(sendFailureHost, sendFailureNative) + expect(sendFailureNative.terminateJob).toHaveBeenCalledWith(expect.anything(), 20n, 1) + expect(sendFailureNative.closeHandleChecked).toHaveBeenCalledWith( + expect.anything(), + 20n, + 'ordinary process Job cleanup', + ) + expect(sendFailureHost.exitCode).toBe(127) + }) + + it('reports a post-commit termination failure', async () => { + const failedHost = new FakeRunnerHost() + const failed = internals({ + pollProcessExit: vi.fn(() => undefined), + isJobEmpty: vi.fn(() => false), + terminateJob: vi.fn(() => { throw new Error('terminate Job failed') }), + }) + const failedRun = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(failedHost), + failed, + ) + failedHost.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + failedHost.emit('message', { type: 'terminate' }) + await failedRun + expect(failedHost.sent).toMatchObject([{ type: 'error', error: { message: 'terminate Job failed' } }]) + }) + + it('finishes when a later poll observes Job emptiness after result delivery', async () => { + const host = new FakeRunnerHost() + const native = internals({ + pollProcessExit: vi.fn().mockReturnValueOnce(0).mockReturnValue(undefined), + isJobEmpty: vi.fn().mockReturnValueOnce(false).mockReturnValue(true), + }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await running + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) + expect(native.isJobEmpty).toHaveBeenCalledTimes(2) + }) + + it('contains poll failures and queued ticks after disconnect', async () => { + const failedHost = new FakeRunnerHost() + await runWindows(failedHost, internals({ + pollProcessExit: vi.fn(() => { throw new Error('poll failed') }), + })) + expect(failedHost.sent).toMatchObject([{ type: 'error', error: { message: 'poll failed' } }]) + + let tick: (() => void) | undefined + const interval = vi.spyOn(globalThis, 'setInterval').mockImplementation((callback: () => void) => { + tick = callback + return 1 as unknown as ReturnType + }) + try { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + tick?.() + host.disconnect() + await running + tick?.() + } finally { + interval.mockRestore() + } + }) + + it('cleans a direct handle after the Job identity was already cleared', async () => { + let tick: (() => void) | undefined + const interval = vi.spyOn(globalThis, 'setInterval').mockImplementation((callback: () => void) => { + tick = callback + return 1 as unknown as ReturnType + }) + try { + const host = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => true) }) + const running = runSpawnRunner( + WINDOWS_RUNNER_SELECTION, + ['--', 'tool.exe'], + hostArgument(host), + native, + ) + host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) + await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) + tick?.() + host.emit('message', { type: 'terminate' }) + host.disconnect() + await running + expect(native.closeHandleChecked).toHaveBeenCalledWith( + expect.anything(), 10n, 'ordinary direct process cleanup', + ) + } finally { + interval.mockRestore() + } + }) + + it('fails closed for malformed or duplicate start messages and disconnected reporting', async () => { + const malformed = new FakeRunnerHost() + await runWindows(malformed, internals(), { type: 'start', cwd: 'C:\\x', env: {}, extra: true }) + expect(malformed.sent).toMatchObject([{ type: 'error' }]) + + const duplicate = new FakeRunnerHost() + const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) + const running = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(duplicate), native) + duplicate.emit('message', { type: 'start', cwd: 'C:\\x', env: {} }) + duplicate.emit('message', { type: 'start', cwd: 'C:\\x', env: {} }) + await running + expect(duplicate.sent).toMatchObject([{ type: 'error' }]) + + const raced = new FakeRunnerHost() + const racedRun = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(raced), internals()) + const lateMessage = raced.listeners('message')[0] as ((value: unknown) => void) | undefined + const lateDisconnect = raced.listeners('disconnect')[0] as (() => void) | undefined + raced.emit('message', { type: 'bad' }) + raced.emit('message', { type: 'bad' }) + await racedRun + await Promise.resolve() + lateMessage?.({ type: 'bad' }) + lateDisconnect?.() + + const disconnected = new FakeRunnerHost() + disconnected.connected = false + await reportSpawnRunnerFailure(WINDOWS_RUNNER_SELECTION, new Error('early'), hostArgument(disconnected)) + expect(disconnected.exitCode).toBe(127) + + const connected = new FakeRunnerHost() + connected.sendThrown = new Error('synchronous send failure') + await reportSpawnRunnerFailure(WINDOWS_RUNNER_SELECTION, new Error('early'), hostArgument(connected)) + expect(connected.exitCode).toBe(127) + expect(connected.connected).toBe(false) + + const noSelection = new FakeRunnerHost() + await reportSpawnRunnerFailure(undefined, new Error('no selector'), hostArgument(noSelection)) + expect(noSelection.exitCode).toBe(127) + }) +}) diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts index 262a6ea56a..67cdd88d5a 100644 --- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts +++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts @@ -4,14 +4,17 @@ import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import { afterAll, describe, expect, it, vi } from 'vitest' import { + bindManagedProcess, childEnv, killGroup, OutputCollector, spawnSubprocess, taskkillProcessTree, + validateSubprocessSpec, } from '../src/spawn.ts' import type { SubprocessHandle, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' +import { waitWithAbort } from '../src/managed-owner.ts' vi.mock('node:child_process', async (importOriginal) => { const actual = await importOriginal() @@ -179,7 +182,7 @@ describe('spawnSubprocess', () => { it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY, MAX_TIMER_DELAY_MS + 1])( 'rejects an invalid grace before spawning: %s', (graceMs) => { - expect(() => spawnSubprocess(spec('true', { graceMs }))) + expect(() => { validateSubprocessSpec(spec('true', { graceMs })) }) .toThrow(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`) }, ) @@ -267,10 +270,13 @@ describe('spawnSubprocess', () => { }) const helper = await waitForPidFile(pidFile) const realKill: typeof process.kill = process.kill.bind(process) + let rootPid: number | undefined let termAt = 0 let forceSignals = 0 const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { - if (target !== -running.pid) return realKill(target, signal) + if (typeof target !== 'number' || target >= 0) return realKill(target, signal) + rootPid ??= -target + if (target !== -rootPid) return realKill(target, signal) if (signal === 'SIGTERM') { termAt = Date.now() return realKill(target, signal) @@ -321,11 +327,25 @@ describe('spawnSubprocess', () => { expect(result.signal).toBe(process.platform === 'win32' ? null : 'SIGTERM') }) - it('throws when the signal is already aborted before spawn', () => { + it('throws a stable Error when already aborted before spawn', () => { + for (const [reason, message] of [ + ['too late', 'aborted before spawn: too late'], + [null, 'aborted before spawn: aborted'], + ] as const) { + const controller = new AbortController() + controller.abort(reason) + expect(() => { validateSubprocessSpec(spec('echo hi', { signal: controller.signal })) }) + .toThrow(new Error(message)) + } + const controller = new AbortController() - controller.abort('too late') - expect(() => spawnSubprocess(spec('echo hi', { signal: controller.signal }))) - .toThrow(/aborted before spawn: too late/) + controller.abort({ + [Symbol.toPrimitive]() { + throw new Error('reason formatting must not escape') + }, + }) + expect(() => { validateSubprocessSpec(spec('echo hi', { signal: controller.signal })) }) + .toThrow(new Error('aborted before spawn: aborted')) }) it('rejects with a spawn error for a nonexistent cwd', async () => { @@ -595,15 +615,12 @@ describe('OutputCollector', () => { }) describe('killGroup', () => { - it('ignores non-positive pids', () => { - expect(() => { killGroup(-1, 'SIGTERM') }).not.toThrow() - expect(() => { killGroup(0, 'SIGTERM') }).not.toThrow() + it('ignores an unpublished pid', () => { + expect(() => { killGroup(undefined, 'SIGTERM') }).not.toThrow() }) it('swallows ESRCH for vanished groups', async () => { - const running = spawnSubprocess(spec('true')) - await running.done - expect(() => { killGroup(running.pid, 'SIGTERM') }).not.toThrow() + expect(() => { killGroup(2 ** 30, 'SIGTERM') }).not.toThrow() }) }) @@ -685,7 +702,8 @@ describe('windows tree semantics (injected platform)', () => { }) running.terminateForHostExit() await running.done - expect(killed).toEqual([running.pid]) + expect(killed).toHaveLength(1) + expect(killed[0]).toBeGreaterThan(0) }) it('terminate routes through taskkill by root pid', async () => { @@ -705,7 +723,8 @@ describe('windows tree semantics (injected platform)', () => { }) running.terminate() const outcome = await running.done - expect(killed).toContain(running.pid) + expect(killed).toHaveLength(1) + expect(killed[0]).toBeGreaterThan(0) expect(outcome.signal).toBe(process.platform === 'win32' ? null : 'SIGKILL') }) @@ -811,6 +830,173 @@ describe.skipIf(process.platform === 'win32')('tree-survivor escalation (termina }) describe('coverage seams', () => { + it('preserves a non-Error managed direct rejection', async () => { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const handle = bindManagedProcess(spec('true', { + graceMs: 1, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal: vi.fn(), + waitForExit: async () => { throw new Error('range unavailable') }, + terminateForHostExit: vi.fn(), + }, + }) + + direct.reject(null) + await expect(handle.done).rejects.toBeNull() + await Promise.resolve() + }) + + it('contains a managed-owner cleanup failure after direct and range settlement', async () => { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const stopped = Promise.withResolvers() + const cleanup = vi.fn(() => { throw new Error('protocol cleanup failed') }) + const handle = bindManagedProcess(spec('true', { + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal: vi.fn(), + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + cleanup, + }, + }) + + const waiting = handle.waitForExit() + stopped.resolve(undefined) + await expect(waiting).resolves.toBe(true) + expect(cleanup).not.toHaveBeenCalled() + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() }) + }) + + it('retries an early range read but cleans and retains a terminal range failure', async () => { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const earlyFailure = new Error('temporary range read failure') + const terminalFailure = new Error('scope ended before launch request consumption') + const waitForExit = vi.fn() + .mockRejectedValueOnce(earlyFailure) + .mockRejectedValueOnce(terminalFailure) + const cleanup = vi.fn() + const handle = bindManagedProcess(spec('true', { + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal: vi.fn(), + waitForExit, + terminateForHostExit: vi.fn(), + cleanup, + }, + }) + + await expect(handle.waitForExit()).rejects.toBe(earlyFailure) + expect(cleanup).not.toHaveBeenCalled() + + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(handle.waitForExit()).rejects.toBe(terminalFailure) + await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() }) + + await expect(handle.waitForExit()).rejects.toBe(terminalFailure) + expect(waitForExit).toHaveBeenCalledTimes(2) + }) + + it('does not deliver a stale escalation after range exit wins the timer race', async () => { + vi.useFakeTimers() + const clearTimer = vi.spyOn(globalThis, 'clearTimeout').mockImplementation(() => {}) + try { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const stopped = Promise.withResolvers() + const signal = vi.fn() + const handle = bindManagedProcess(spec('true', { + graceMs: 10, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + }, + }) + + handle.terminate() + expect(signal).toHaveBeenCalledExactlyOnceWith('SIGTERM', expect.any(Error)) + stopped.resolve(undefined) + await expect(handle.waitForExit()).resolves.toBe(true) + await vi.advanceTimersByTimeAsync(10) + expect(signal).toHaveBeenCalledTimes(1) + + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + } finally { + clearTimer.mockRestore() + vi.useRealTimers() + } + }) + + it('does not restart managed termination after the escalation timer fires', async () => { + vi.useFakeTimers() + try { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const stopped = Promise.withResolvers() + const signal = vi.fn() + const handle = bindManagedProcess(spec('true', { + graceMs: 10, + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + owner: { + signal, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + }, + }) + + handle.terminate() + await vi.advanceTimersByTimeAsync(10) + handle.terminate() + await vi.advanceTimersByTimeAsync(10) + expect(signal).toHaveBeenCalledTimes(2) + expect(signal).toHaveBeenNthCalledWith(1, 'SIGTERM', expect.any(Error)) + expect(signal).toHaveBeenNthCalledWith(2, 'SIGKILL', undefined) + + stopped.resolve(undefined) + await expect(handle.waitForExit()).resolves.toBe(true) + direct.resolve({ exitCode: 0, signal: null }) + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + } finally { + vi.useRealTimers() + } + }) + + it('contains a late wait rejection after an already-aborted observation', async () => { + const pending = Promise.withResolvers() + await expect(waitWithAbort(pending.promise, AbortSignal.abort())).resolves.toBe(false) + pending.reject(new Error('late observation failure')) + await Promise.resolve() + }) + it('hides the taskkill helper window', () => { const taskkill = vi.mocked(nodeSpawnSync) taskkill.mockReturnValueOnce({} as never) @@ -822,7 +1008,8 @@ describe('coverage seams', () => { ) }) - it('taskkillProcessTree ignores non-positive pids and contains a missing binary', () => { + it('taskkillProcessTree ignores unpublished or non-positive pids and contains a missing binary', () => { + expect(() => { taskkillProcessTree(undefined) }).not.toThrow() expect(() => { taskkillProcessTree(-1) }).not.toThrow() expect(() => { taskkillProcessTree(0) }).not.toThrow() // On POSIX there is no taskkill; spawnSync reports the failure in its @@ -841,10 +1028,12 @@ describe('coverage seams', () => { linuxProcessGroupHasLiveMembers: () => false, }) const realKill = process.kill.bind(process) + let rootPid: number | undefined const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { if (typeof target === 'number' && target < 0) { + rootPid ??= -target if (signal === 0) return true - if (signal === 'SIGKILL') realKill(running.pid, 'SIGKILL') + if (signal === 'SIGKILL') realKill(-target, 'SIGKILL') return true } return realKill(target, signal) @@ -861,8 +1050,10 @@ describe('coverage seams', () => { it('treats a vanished group probe as quiescent without signalling', async () => { const running = spawnSubprocess(spec('sleep 60'), { platform: 'linux' }) const realKill = process.kill.bind(process) + let rootPid: number | undefined const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { if (typeof target === 'number' && target < 0) { + rootPid ??= -target throw Object.assign(new Error('simulated absent group'), { code: 'ESRCH' }) } return realKill(target, signal) @@ -870,7 +1061,8 @@ describe('coverage seams', () => { try { running.terminate() await new Promise(resolve => setTimeout(resolve, 20)) - realKill(running.pid, 'SIGKILL') + if (rootPid === undefined) throw new Error('fallback owner did not probe its private process group') + realKill(rootPid, 'SIGKILL') await running.done await expect(running.waitForExit()).resolves.toBe(true) } finally { @@ -878,6 +1070,27 @@ describe('coverage seams', () => { } }) + it('treats an EPERM group probe as still alive', async () => { + const running = spawnSubprocess(spec('sleep 60'), { platform: 'linux' }) + const realKill = process.kill.bind(process) + let rootPid: number | undefined + const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => { + if (typeof target === 'number' && target < 0 && signal === 0) { + rootPid ??= -target + throw Object.assign(new Error('simulated permission denial'), { code: 'EPERM' }) + } + return realKill(target, signal) + }) + try { + await expect(running.waitForExit(AbortSignal.timeout(20))).resolves.toBe(false) + } finally { + killSpy.mockRestore() + if (rootPid === undefined) throw new Error('fallback owner did not probe its private process group') + realKill(-rootPid, 'SIGKILL') + await running.done + } + }) + it('childEnv keeps the POSIX spread on non-Windows hosts', () => { const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('linux') try { @@ -966,6 +1179,15 @@ describe('coverage seams', () => { await running.waitForExit() }) + it('host-exit finalization synchronously terminates until range absence is observed', async () => { + const taskkill = vi.fn() + const running = spawnSubprocess(spec('true'), { platform: 'win32', taskkill }) + await running.done + running.terminateForHostExit() + await expect(running.waitForExit()).resolves.toBe(true) + expect(taskkill).toHaveBeenCalledOnce() + }) + it('repeated terminate after exit never probes or signals a reused process group', async () => { const running = spawnSubprocess(spec('sleep 60')) running.terminate() @@ -1014,14 +1236,19 @@ describe('coverage seams 2', () => { await expect(running.waitForExit(aborted.signal)).resolves.toBe(false) // alive branch running.terminate() await running.done - expect(killedPid).toBe(running.pid) + expect(killedPid).toBeGreaterThan(0) await expect(running.waitForExit()).resolves.toBe(true) }) it('an inert win32 taskkill leaves the tree alive for a bounded wait to report', async () => { // An inert taskkill simulates a tree that never reports exit: terminate() // delivers nothing, so a bounded consumer wait must come back false. - const running = spawnSubprocess(spec('sleep 60'), { spillDir, platform: 'win32', taskkill: () => {} }) + let rootPid: number | undefined + const running = spawnSubprocess(spec('sleep 60'), { + spillDir, + platform: 'win32', + taskkill: (pid) => { rootPid = pid }, + }) running.terminate() const bound = new AbortController() const timer = setTimeout(() => { bound.abort() }, 60) @@ -1029,7 +1256,8 @@ describe('coverage seams 2', () => { clearTimeout(timer) // Real cleanup: the injected platform spawned without detachment, so the // child is a plain (group-less) POSIX process — kill it directly. - process.kill(running.pid, 'SIGKILL') + if (rootPid === undefined) throw new Error('fallback owner did not call its private taskkill adapter') + process.kill(rootPid, 'SIGKILL') await running.done }) @@ -1051,11 +1279,11 @@ describe('coverage seams 2', () => { describe('argv validation', () => { it('rejects an empty argv before spawning', () => { - expect(() => spawnSubprocess({ ...spec('true'), argv: [] })).toThrow(/non-empty program name/) + expect(() => { validateSubprocessSpec({ ...spec('true'), argv: [] }) }).toThrow(/non-empty program name/) }) it('rejects an empty program name before spawning', () => { - expect(() => spawnSubprocess({ ...spec('true'), argv: [''] })).toThrow(/non-empty program name/) + expect(() => { validateSubprocessSpec({ ...spec('true'), argv: [''] }) }).toThrow(/non-empty program name/) }) it.skipIf(process.platform === 'win32')('spawns argv verbatim without shell interpretation', async () => { @@ -1065,17 +1293,15 @@ describe('argv validation', () => { }) describe('abort edge cases', () => { - it('reports a fallback reason for reason-less pre-aborted signals', () => { - // Real AbortControllers always set a DOMException reason; signal-like - // objects from other libraries may not — the fallback covers them. + it('uses a stable fallback for a reason-less pre-aborted signal', () => { const bare = { aborted: true, reason: undefined, addEventListener() {}, removeEventListener() {}, } as unknown as AbortSignal - expect(() => spawnSubprocess(spec('echo hi', { signal: bare }))) - .toThrow(/aborted before spawn: aborted/) + expect(() => { validateSubprocessSpec(spec('echo hi', { signal: bare })) }) + .toThrow(new Error('aborted before spawn: aborted')) }) it.skipIf(process.platform === 'win32')('reports the terminating signal of an externally self-killed command', async () => { diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts index b8f23a89c4..7b02470f7c 100644 --- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts +++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts @@ -8,6 +8,7 @@ import type { ProcessInspectorInternals, ProcessSnapshot, } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts' +import type { BoundProcessOwner } from '@deepseek-ai/dsh-subprocess-local/src/managed-owner.ts' import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess' class FakePty { @@ -113,6 +114,222 @@ function makeHandle(pty: FakePty, inspector: ProcessInspector, graceMs: number): } describe('LocalTerminalHandle', () => { + it('terminates a managed range with TERM when it stops within the grace period', async () => { + vi.useFakeTimers() + const pty = new FakePty() + const inspector = new FakeInspector() + const stopped = Promise.withResolvers() + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const owner: BoundProcessOwner = { + signal(signal) { + signals.push(signal) + if (signal === 'SIGTERM') { + pty.emitExit(0, 15) + stopped.resolve(undefined) + } + }, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) + + await handle.terminate() + + expect(signals).toEqual(['SIGTERM']) + await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' }) + expect(vi.getTimerCount()).toBe(0) + }) + + it('cancels the terminal-exit grace when the pty exits first', async () => { + vi.useFakeTimers() + const pty = new FakePty() + const stopped = Promise.withResolvers() + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const owner: BoundProcessOwner = { + signal(signal) { + signals.push(signal) + if (signal === 'SIGTERM') { + stopped.resolve(undefined) + setTimeout(() => { pty.emitExit(0, 15) }, 1) + } + }, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 100, 'linux', owner) + + const terminating = handle.terminate() + await vi.advanceTimersByTimeAsync(1) + await terminating + + expect(signals).toEqual(['SIGTERM']) + expect(vi.getTimerCount()).toBe(0) + }) + + it('escalates a managed range to KILL after the TERM grace expires', async () => { + vi.useFakeTimers() + const pty = new FakePty() + const inspector = new FakeInspector() + const stopped = Promise.withResolvers() + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const owner: BoundProcessOwner = { + signal(signal) { + signals.push(signal) + if (signal === 'SIGKILL') { + pty.emitExit(0, 9) + stopped.resolve(undefined) + } + }, + waitForExit: () => stopped.promise, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) + + const terminating = handle.terminate() + await vi.advanceTimersByTimeAsync(10) + await terminating + + expect(signals).toEqual(['SIGTERM', 'SIGKILL']) + }) + + it('force-kills and retries a managed range when observation first rejects', async () => { + const pty = new FakePty() + const failure = new Error('scope became unreadable') + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const waitForExit = vi.fn() + .mockRejectedValueOnce(failure) + .mockResolvedValue(undefined) + const owner: BoundProcessOwner = { + signal: (signal) => { signals.push(signal) }, + waitForExit, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) + + await expect(handle.terminate()).rejects.toBe(failure) + expect(signals).toEqual(['SIGTERM', 'SIGKILL']) + expect(waitForExit).toHaveBeenCalledTimes(2) + }) + + it('preserves both failed managed-range observations after force-kill', async () => { + const pty = new FakePty() + const firstFailure = new Error('scope became unreadable') + const finalFailure = new Error('scope stayed unreadable') + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const owner: BoundProcessOwner = { + signal: (signal) => { signals.push(signal) }, + waitForExit: vi.fn() + .mockRejectedValueOnce(firstFailure) + .mockRejectedValueOnce(finalFailure), + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) + + await expect(handle.terminate()).rejects.toMatchObject({ + errors: [firstFailure, finalFailure], + message: 'terminal managed-range cleanup failed', + }) + expect(signals).toEqual(['SIGTERM', 'SIGKILL']) + }) + + it('routes managed terminal host exit directly to KILL', () => { + const pty = new FakePty() + const inspector = new FakeInspector() + const signal = vi.fn() + const terminateForHostExit = vi.fn() + const owner: BoundProcessOwner = { signal, waitForExit: async () => {}, terminateForHostExit } + const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10, 'linux', owner) + + handle.terminateForHostExit() + + expect(signal).not.toHaveBeenCalled() + expect(terminateForHostExit).toHaveBeenCalledOnce() + expect(inspector.processes).toEqual([]) + expect(pty.kills).toEqual([]) + }) + + it('rejects managed outcome conversion and cleans through its owner exactly once', async () => { + const pty = new FakePty() + const failure = new Error('invalid bootstrap outcome') + const cleanup = vi.fn() + const owner: BoundProcessOwner = { + signal: vi.fn(), + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + cleanup, + } + const handle = new LocalTerminalHandle( + pty.asPty(), + new FakeInspector(), + 10, + 'linux', + owner, + () => { throw failure }, + ) + + pty.emitExit() + await expect(handle.done).rejects.toBe(failure) + await expect(handle.terminate()).resolves.toBeUndefined() + await expect(handle.terminate()).resolves.toBeUndefined() + await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() }) + }) + + it('runs owner cleanup once after repeated failed managed termination attempts', async () => { + const pty = new FakePty() + const failure = new Error('scope stayed unreadable') + const cleanup = vi.fn() + const owner: BoundProcessOwner = { + signal: vi.fn(), + waitForExit: vi.fn(async () => { throw failure }), + terminateForHostExit: vi.fn(), + cleanup, + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) + + await expect(handle.terminate()).rejects.toThrow('terminal managed-range cleanup failed') + await expect(handle.terminate()).rejects.toThrow('terminal managed-range cleanup failed') + expect(cleanup).not.toHaveBeenCalled() + pty.emitExit() + await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null }) + await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() }) + }) + + it('waits for the node-pty exit event after the managed range becomes empty', async () => { + const pty = new FakePty() + const owner: BoundProcessOwner = { + signal: vi.fn(), + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 100, 'linux', owner) + let settled = false + + const terminating = handle.terminate().then(() => { settled = true }) + await new Promise(resolve => setImmediate(resolve)) + expect(settled).toBe(false) + + pty.emitExit() + await terminating + }) + + it('rejects when a managed range stops but node-pty never publishes exit', async () => { + vi.useFakeTimers() + const pty = new FakePty() + const signals: Array<'SIGTERM' | 'SIGKILL'> = [] + const owner: BoundProcessOwner = { + signal: (signal) => { signals.push(signal) }, + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + } + const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10, 'linux', owner) + + const terminating = handle.terminate() + const rejected = expect(terminating).rejects.toThrow('terminal cleanup failed; surviving pid: 123') + await vi.advanceTimersByTimeAsync(10) + await rejected + expect(signals).toEqual(['SIGTERM']) + }) + it('force-kills descendants around the shell during synchronous host exit', () => { const pty = new FakePty() const inspector = new FakeInspector() diff --git a/packages/subprocess/subprocess-local/tests/windows-job.spec.ts b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts new file mode 100644 index 0000000000..19fadad5fb --- /dev/null +++ b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts @@ -0,0 +1,442 @@ +import { EventEmitter } from 'node:events' +import { fstatSync } from 'node:fs' +import { PassThrough } from 'node:stream' +import { describe, expect, it, vi } from 'vitest' +import { + launchWindowsJob, + probeWindowsJob, +} from '../src/windows-job.ts' +import { bindManagedProcess } from '../src/spawn.ts' + +class FakeChild extends EventEmitter { + pid: number | undefined = 432 + connected = true + stdin = new PassThrough() + stdout = new PassThrough() + stderr = new PassThrough() + targetStdin = new PassThrough() + targetStdout = new PassThrough() + targetStderr = new PassThrough() + stdio = [null, null, null, null, this.targetStdin, this.targetStdout, this.targetStderr] + sent: unknown[] = [] + killed: NodeJS.Signals[] = [] + sendError: Error | undefined + deferSendCallbacks = false + pendingSendCallbacks: Array<(error: Error | null) => void> = [] + throwOnSendCall: number | undefined + sendThrown: unknown = new Error('send threw') + private sendCalls = 0 + + send(message: unknown, callback?: (error: Error | null) => void): boolean { + this.sendCalls += 1 + if (this.sendCalls === this.throwOnSendCall) throw this.sendThrown + this.sent.push(message) + if (callback !== undefined && this.deferSendCallbacks) { + this.pendingSendCallbacks.push(callback) + } else { + queueMicrotask(() => { callback?.(this.sendError ?? null) }) + } + return true + } + deliverNextSend(error: Error | null): void { + const callback = this.pendingSendCallbacks.shift() + if (callback === undefined) throw new Error('no deferred send callback') + callback(error) + } + kill(signal: NodeJS.Signals): boolean { + this.killed.push(signal) + return true + } +} + +const spec = { + argv: ['tool.exe', 'literal arg'], + cwd: 'C:\\target', + env: { TARGET: 'yes' }, + stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' }, + graceMs: 100, +} as const + +function launch( + child = new FakeChild(), + request: Parameters[0] = spec, + emitSpawn = true, +) { + const spawn = vi.fn((_command: string, _args: readonly string[], _options: unknown) => child) + const result = launchWindowsJob(request, { TARGET: 'yes' }, { + spawn: spawn as never, + runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'], + }) + if (emitSpawn) child.emit('spawn') + return { child, result, spawn } +} + +describe('Windows Job capability', () => { + it('uses the production dependency paths by default', async () => { + vi.resetModules() + const child = new FakeChild() + const spawn = vi.fn(() => child) + const load = vi.fn(() => ({ bindings: true }) as never) + const probe = vi.fn() + vi.doMock('node:child_process', async importOriginal => ({ + ...await importOriginal(), + spawn, + })) + vi.doMock('@deepseek-ai/dsh-win32-process', () => ({ + loadWin32ProcessBindings: load, + probeCurrentTokenJobSupport: probe, + })) + try { + const isolated = await import('../src/windows-job.ts') + expect(isolated.probeWindowsJob()).toBe(true) + expect(load).toHaveBeenCalledOnce() + expect(probe).toHaveBeenCalledOnce() + + const result = isolated.launchWindowsJob(spec, { TARGET: 'yes' }) + expect(spawn).toHaveBeenCalledOnce() + child.emit('spawn') + child.emit('message', { type: 'target-exit', exitCode: 0 }) + child.connected = false + child.emit('close', 0, null) + await expect(result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + } finally { + vi.doUnmock('node:child_process') + vi.doUnmock('@deepseek-ai/dsh-win32-process') + vi.resetModules() + } + }) + + it('rechecks runner and empty Job support on every eligible spawn', () => { + const runnerAvailable = vi.fn(() => true) + const load = vi.fn(() => ({ bindings: true }) as never) + const probe = vi.fn() + const inputs = { + runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'] as [string, ...string[]], + runnerAvailable, + loadWin32ProcessBindings: load, + probeCurrentTokenJobSupport: probe, + } + expect(probeWindowsJob(inputs)).toBe(true) + expect(probeWindowsJob(inputs)).toBe(true) + expect(runnerAvailable).toHaveBeenCalledTimes(2) + expect(load).toHaveBeenCalledTimes(2) + expect(probe).toHaveBeenCalledTimes(2) + }) + + it('falls back when either runner or current Job capability is unavailable', () => { + expect(probeWindowsJob({ + resolveRunnerInvocation: () => { throw new Error('runner resolution failed') }, + })).toBe(false) + expect(probeWindowsJob({ runnerInvocation: ['/missing'], runnerAvailable: () => false })).toBe(false) + expect(probeWindowsJob({ + runnerInvocation: ['C:\\node.exe'], + runnerAvailable: () => true, + loadWin32ProcessBindings: () => { throw new Error('bindings missing') }, + })).toBe(false) + }) +}) + +describe('Windows parent runner contract', () => { + it('isolates runner stdio, carries target stdio on fd 4 through fd 6, and sends cwd/env', () => { + const { child, result, spawn } = launch() + expect(spawn).toHaveBeenCalledWith('C:\\node.exe', [ + 'C:\\runner.js', '--', 'tool.exe', 'literal arg', + ], expect.objectContaining({ + cwd: process.cwd(), + stdio: ['ignore', 'ignore', 'ignore', 'ipc', 'pipe', 'pipe', 2], + })) + expect(child.sent).toEqual([{ type: 'start', cwd: 'C:\\target', env: { TARGET: 'yes' } }]) + expect(result.stdin).toBe(child.targetStdin) + expect(result.stdout).toBe(child.targetStdout) + expect(result.stderr).toBe(child.targetStderr) + }) + + it('carries a null-device fd 4 for ignored stdin and closes the parent descriptor after spawn', () => { + const child = new FakeChild() + const ignored = { + ...spec, + stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'inherit' }, + } as const + const { result, spawn } = launch(child, ignored) + expect(spawn).toHaveBeenCalledWith('C:\\node.exe', expect.any(Array), expect.objectContaining({ + stdio: ['ignore', 'ignore', 'ignore', 'ipc', expect.any(Number), 'pipe', 2], + })) + const options = spawn.mock.calls[0]?.[2] as { stdio: unknown[] } + const carrier = options.stdio[4] + if (typeof carrier !== 'number') throw new Error('expected numeric null-device carrier') + expect(() => fstatSync(carrier)).toThrow() + expect(result.stdin).toBeNull() + }) + + it('closes the ignored-stdin descriptor when runner spawn throws synchronously', () => { + const ignored = { + ...spec, + stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'inherit' }, + } as const + let carrier: number | undefined + const spawn = vi.fn((_command: string, _args: readonly string[], options: unknown) => { + const candidate = (options as { stdio: unknown[] }).stdio[4] + if (typeof candidate !== 'number') throw new Error('expected numeric null-device carrier') + carrier = candidate + throw new Error('runner spawn failed') + }) + + expect(() => launchWindowsJob(ignored, { TARGET: 'yes' }, { + spawn: spawn as never, + runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'], + })).toThrow('runner spawn failed') + if (carrier === undefined) throw new Error('runner spawn was not attempted') + const closedCarrier = carrier + expect(() => fstatSync(closedCarrier)).toThrow() + }) + + it('maps target-exit to direct outcome and clean close to range quiescence', async () => { + const { child, result } = launch() + child.emit('message', { type: 'target-exit', exitCode: 7 }) + await expect(result.direct).resolves.toEqual({ exitCode: 7, signal: null }) + child.connected = false + child.emit('close', 0, null) + await expect(result.owner.waitForExit()).resolves.toBeUndefined() + }) + + it('latches target-exit while stdio drains and leaves later runner failure to waitForExit', async () => { + const { child, result } = launch() + const handle = bindManagedProcess(spec, result) + child.emit('message', { type: 'target-exit', exitCode: 7 }) + await Promise.resolve() + child.connected = false + child.emit('close', 127, null) + child.targetStdout.end() + child.targetStderr.end() + await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null }) + await expect(handle.waitForExit()).rejects.toThrow('exit code 127') + }) + + it('maps errors and restores raw start-cancellation reasons from the parent latch', async () => { + const spawned = launch() + spawned.child.emit('message', { + type: 'error', error: { name: 'Error', message: 'missing', code: 'ENOENT' }, + }) + await expect(spawned.result.direct).rejects.toMatchObject({ code: 'ENOENT' }) + spawned.child.connected = false + spawned.child.emit('close', 0, null) + await expect(spawned.result.owner.waitForExit()).resolves.toBeUndefined() + + const cancelled = launch() + const reason = new Error('caller aborted') + cancelled.result.owner.signal('SIGTERM', reason) + expect(cancelled.child.sent.at(-1)).toEqual({ type: 'terminate' }) + cancelled.child.emit('message', { + type: 'error', + error: { + name: 'Error', message: 'subprocess target start was cancelled', + }, + }) + await expect(cancelled.result.direct).rejects.toBe(reason) + cancelled.child.connected = false + cancelled.child.emit('close', 0, null) + await expect(cancelled.result.owner.waitForExit()).resolves.toBeUndefined() + + const nullCancelled = launch() + nullCancelled.result.owner.signal('SIGTERM', null) + nullCancelled.result.owner.signal('SIGKILL', new Error('later reason')) + nullCancelled.child.emit('message', { + type: 'error', + error: { + name: 'Error', message: 'subprocess target start was cancelled', + }, + }) + await expect(nullCancelled.result.direct).rejects.toBeNull() + nullCancelled.child.connected = false + nullCancelled.child.emit('close', 0, null) + await expect(nullCancelled.result.owner.waitForExit()).resolves.toBeUndefined() + + const implicit = launch() + implicit.result.owner.signal('SIGTERM') + implicit.child.emit('message', { + type: 'error', + error: { + name: 'Error', message: 'subprocess target start was cancelled', + }, + }) + await expect(implicit.result.direct).rejects.toBeUndefined() + implicit.child.connected = false + implicit.child.emit('close', 0, null) + await expect(implicit.result.owner.waitForExit()).resolves.toBeUndefined() + }) + + it('preserves a strict provider error after a termination request', async () => { + const spawned = launch() + const localReason = new Error('caller aborted after target commit') + spawned.result.owner.signal('SIGTERM', localReason) + spawned.child.emit('message', { + type: 'error', + error: { + name: 'Error', + message: 'poll failed', + code: 'EIO', + syscall: 'QueryInformationJobObject', + }, + }) + + const failure = await spawned.result.direct.catch((error: unknown) => error) + expect(failure).not.toBe(localReason) + expect(failure).toMatchObject({ + message: 'poll failed', + code: 'EIO', + syscall: 'QueryInformationJobObject', + }) + spawned.child.connected = false + spawned.child.emit('close', 127, null) + await expect(spawned.result.owner.waitForExit()).rejects.toThrow('exit code 127') + }) + + it('rejects direct and wait for runner error or abnormal runner exit', async () => { + const failed = launch() + failed.child.emit('message', { + type: 'error', error: { name: 'Error', message: 'Job assignment failed' }, + }) + await expect(failed.result.direct).rejects.toThrow('Job assignment failed') + failed.child.connected = false + failed.child.emit('close', 127, null) + await expect(failed.result.owner.waitForExit()).rejects.toThrow('exit code 127') + + const missing = launch() + missing.child.connected = false + missing.child.emit('close', null, 'SIGKILL') + await expect(missing.result.direct).rejects.toThrow('signal SIGKILL') + + const statusless = launch() + statusless.child.connected = false + statusless.child.emit('close', null, null) + await expect(statusless.result.direct).rejects.toThrow('without an exit status') + }) + + it('fails closed on malformed/duplicate result, runner spawn error, and start-send error', async () => { + const malformed = launch() + malformed.child.emit('message', { type: 'target-exit', exitCode: -1 }) + expect(malformed.child.killed).toEqual(['SIGKILL']) + await expect(malformed.result.direct).rejects.toThrow('invalid target-exit') + await expect(malformed.result.owner.waitForExit()).rejects.toThrow('invalid target-exit') + + const duplicate = launch() + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0 }) + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0 }) + await expect(duplicate.result.direct).resolves.toEqual({ exitCode: 0, signal: null }) + await expect(duplicate.result.owner.waitForExit()).rejects.toThrow('more than one direct result') + + const errored = launch(new FakeChild(), spec, false) + const spawnError = new Error('runner executable missing') + errored.child.emit('error', spawnError) + await expect(errored.result.direct).rejects.toBe(spawnError) + await expect(errored.result.owner.waitForExit()).resolves.toBeUndefined() + errored.child.emit('close', 127, null) + + const postSpawnError = launch() + const infrastructureError = new Error('runner failed after spawn') + postSpawnError.child.emit('error', infrastructureError) + await expect(postSpawnError.result.direct).rejects.toBe(infrastructureError) + await expect(postSpawnError.result.owner.waitForExit()).rejects.toBe(infrastructureError) + + const sendFailedChild = new FakeChild() + sendFailedChild.sendError = new Error('IPC send failed') + const sendFailed = launch(sendFailedChild) + await expect(sendFailed.result.direct).rejects.toThrow('IPC send failed') + await expect(sendFailed.result.owner.waitForExit()).rejects.toThrow('IPC send failed') + expect(sendFailedChild.killed).toEqual(['SIGKILL']) + + const noIpc = new FakeChild() + Object.defineProperty(noIpc, 'send', { value: undefined }) + const noIpcResult = launch(noIpc).result + await expect(noIpcResult.direct).rejects.toThrow('has no IPC channel') + await expect(noIpcResult.owner.waitForExit()).rejects.toThrow('has no IPC channel') + + const nonError = new FakeChild() + nonError.throwOnSendCall = 1 + nonError.sendThrown = 'start send failed' + const nonErrorResult = launch(nonError).result + await expect(nonErrorResult.direct).rejects.toBe('start send failed') + await expect(nonErrorResult.owner.waitForExit()).rejects.toBe('start send failed') + }) + + it('fails infrastructure and kills the runner when termination delivery fails', async () => { + const callback = launch() + await Promise.resolve() + callback.child.sendError = new Error('terminate callback failed') + callback.result.owner.signal('SIGTERM') + await expect(callback.result.direct).rejects.toThrow('terminate callback failed') + await expect(callback.result.owner.waitForExit()).rejects.toThrow('terminate callback failed') + expect(callback.child.killed).toEqual(['SIGKILL']) + + const throwingChild = new FakeChild() + throwingChild.throwOnSendCall = 2 + throwingChild.sendThrown = 'terminate send threw' + const throwing = launch(throwingChild) + throwing.result.owner.signal('SIGTERM') + await expect(throwing.result.direct).rejects.toBe('terminate send threw') + await expect(throwing.result.owner.waitForExit()).rejects.toBe('terminate send threw') + expect(throwing.child.killed).toEqual(['SIGKILL']) + + const errorChild = new FakeChild() + errorChild.throwOnSendCall = 2 + const error = launch(errorChild) + error.result.owner.signal('SIGTERM') + await expect(error.result.direct).rejects.toThrow('send threw') + await expect(error.result.owner.waitForExit()).rejects.toThrow('send threw') + }) + + it('accepts clean range settlement after a direct error races redundant termination delivery', async () => { + const child = new FakeChild() + const launched = launch(child) + const handle = bindManagedProcess(spec, launched.result) + await Promise.resolve() + child.deferSendCallbacks = true + child.emit('message', { + type: 'error', error: { name: 'Error', message: 'target start failed', code: 'ENOENT' }, + }) + await expect(handle.done).rejects.toMatchObject({ code: 'ENOENT' }) + expect(child.pendingSendCallbacks).toHaveLength(1) + + expect(child.connected).toBe(true) + child.deliverNextSend(new Error('late EPIPE')) + await Promise.resolve() + expect(child.killed).toEqual([]) + child.connected = false + child.emit('close', 0, null) + await expect(handle.waitForExit()).resolves.toBe(true) + }) + + it('accepts clean range settlement when a target result races redundant termination delivery', async () => { + const child = new FakeChild() + const launched = launch(child) + const handle = bindManagedProcess(spec, launched.result) + await Promise.resolve() + child.deferSendCallbacks = true + child.emit('message', { type: 'target-exit', exitCode: 7 }) + child.targetStdout.end() + child.targetStderr.end() + await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null }) + + launched.result.owner.signal('SIGTERM') + expect(child.pendingSendCallbacks).toHaveLength(1) + + expect(child.connected).toBe(true) + child.deliverNextSend(new Error('late EPIPE')) + await Promise.resolve() + expect(child.killed).toEqual([]) + child.connected = false + child.emit('close', 0, null) + await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null }) + await expect(handle.waitForExit()).resolves.toBe(true) + }) + + it('uses synchronous runner termination for host exit and isolates repeated control', () => { + const { child, result } = launch() + result.owner.signal('SIGTERM', new Error('first')) + result.owner.signal('SIGKILL', new Error('second')) + expect(child.sent.filter(message => (message as { type?: string }).type === 'terminate')).toHaveLength(1) + result.owner.terminateForHostExit() + expect(child.killed).toEqual(['SIGKILL']) + }) +}) diff --git a/packages/subprocess/subprocess-local/tsconfig.json b/packages/subprocess/subprocess-local/tsconfig.json index 48c2093a6e..58822fc3f4 100644 --- a/packages/subprocess/subprocess-local/tsconfig.json +++ b/packages/subprocess/subprocess-local/tsconfig.json @@ -17,6 +17,9 @@ { "path": "../subprocess" }, + { + "path": "../win32-process" + }, { "path": "../../util/timeout" } diff --git a/packages/subprocess/subprocess-local/tsdown.config.ts b/packages/subprocess/subprocess-local/tsdown.config.ts new file mode 100644 index 0000000000..afc75c8145 --- /dev/null +++ b/packages/subprocess/subprocess-local/tsdown.config.ts @@ -0,0 +1,15 @@ +import { defineConfig } from 'tsdown' + +export default defineConfig({ + entry: { + index: 'lib/types/index.js', + runner: 'lib/types/bin.js', + }, + outDir: 'lib', + format: ['esm'], + platform: 'node', + target: 'es2024', + fixedExtension: false, + dts: false, + clean: false, +}) diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml index a942fbee7b..bc381c4cce 100644 --- a/packages/subprocess/subprocess/README.i18n.yaml +++ b/packages/subprocess/subprocess/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md -README.md: 40ebde7a633f2280996c046433f4c9700925869f -README.zh.md: 3bfbb909f37e7339db7e3a71b97b4e00c81bc80c +README.md: c77b2866053def2775d39606083b24da1679660d +README.zh.md: 2a58e2b71901ff29f181b8b072892b6c93fbdaf1 diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md index 40ebde7a63..c77b286605 100644 --- a/packages/subprocess/subprocess/README.md +++ b/packages/subprocess/subprocess/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Any composition that runs child processes can start a fully specified child process or a real terminal session through `ctx.subprocess`, receive a live handle with streams and exit facts, and terminate the whole process tree on demand. The service provides executable lookup, the shared environment scrub, and bounded output capture, while every default — argv, deadlines, shell semantics — stays explicit on the request, so the consuming capability seams decide what a process means. A composition mounts one provider implementation (such as `dsh-subprocess-local`) that registers the service; the seam package itself is an abstract contract, not a loadable plugin. Nothing here reaches a model directly: process output and lifecycle are rendered by the consuming tools. +Any composition that runs child processes can start a fully specified child process or a real terminal session through `ctx.subprocess`, receive a live handle with streams and direct exit facts, then terminate and wait for the provider-managed range. The service provides executable lookup, the shared environment scrub, and bounded output capture, while every default — argv, deadlines, shell semantics — stays explicit on the request, so the consuming capability seams decide what a process means. A composition mounts one provider implementation (such as `dsh-subprocess-local`) that registers the service; the seam package itself is an abstract contract, not a loadable plugin. Nothing here reaches a model directly: process output and lifecycle are rendered by the consuming tools. ## Table of Contents @@ -25,7 +25,7 @@ Any composition that runs child processes can start a fully specified child proc ## Use this package -Mount a subprocess provider in any composition that must run child processes, and call `ctx.subprocess` from the capability that owns the command. The common path is explicit: resolve the executable, spawn with a fully specified request, read the output you asked for, and terminate the tree when the work is done. +Mount a subprocess provider in any composition that must run child processes, and call `ctx.subprocess` from the capability that owns the command. The common path is explicit: resolve the executable, spawn with a fully specified request, read the output you asked for, and terminate the managed range when the work is done. ### Mounting the service @@ -38,7 +38,7 @@ One provider registers `ctx.subprocess` per composition; load it beside the cons ### Starting a managed process -The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. `done` resolves with exit facts (`exitCode` and `signal`) when the process closes and rejects only for spawn-level failures; collected output stays readable after exit. +The request is fully explicit: the program and arguments, the working directory, one stdio disposition per stream, a termination grace, an optional abort signal, and optional environment overrides. Target and managed-range identities remain provider-private. `done` resolves with the direct command's exit facts (`exitCode` and `signal`) and rejects for spawn or provider failures; collected output stays readable after exit. ```text const executable = await ctx.subprocess.resolveExecutable('bash') @@ -62,7 +62,7 @@ Reads are offset-based and non-consuming: a background reader and a final batch ### Managing process lifetime -Termination is tree-scoped everywhere: `terminate()` escalates SIGTERM → grace → SIGKILL (Windows force-terminates immediately), is idempotent, and is a no-op once the tree is gone. The request's abort signal starts the same escalation, so a consumer-owned deadline can cancel a whole tree. `waitForExit()` resolves only when the entire tree has exited, not just the direct child, so a still-running helper is observable before teardown returns. Callers own deadlines and cause classification; the service only reacts. +Termination and waiting use one provider-managed range. `terminate()` starts the provider's documented procedure, is idempotent, and becomes a no-op after that range is empty; the request's abort signal starts the same procedure. `waitForExit()` observes the same range and resolves only after the provider proves it quiescent, so direct command completion does not hide a surviving descendant. It rejects when the selected owner can no longer prove quiescence. Providers document their native owners and weaker fallbacks; callers own deadlines, teardown ladders, and cause classification. ### Running a terminal session @@ -74,7 +74,7 @@ Children never inherit the harness's ambient secrets: credential-shaped names an ### What can go wrong -An executable that cannot be resolved fails loud with a stable error. A spawn that never starts rejects `done`; there is no buffered output for a process that never ran. A daemonized child that leaves its tree or session can outlive termination — provider READMEs document their observability limits. When a transport owns its own spawn (the SDK client, MCP), route around the service and import `scrubbedParentEnv` directly so environment policy stays single-sourced. +An executable that cannot be resolved fails loud with a stable error. A spawn that never starts rejects `done`; there is no buffered output for a process that never ran. `waitForExit()` also rejects when the provider cannot prove its selected range is empty, and a provider fallback may not own descendants that escape its process group or observed session. When a transport owns its own spawn (the SDK client, MCP), route around the service and import `scrubbedParentEnv` directly so environment policy stays single-sourced. ----- @@ -100,7 +100,7 @@ The seam is built on one separation: the service owns process coordinates and li ### Data model and flow -A spawn returns a live handle immediately; the request's abort signal drives the same termination escalation as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members. +A spawn returns a live handle immediately without exposing target identity. `done` independently reports the direct command outcome or failure, while `waitForExit()` reports managed-range quiescence. The request's abort signal drives the same termination procedure as `terminate()`. Collected readers are cursor-free: offsets are whole-stream byte coordinates the caller owns, so independent readers cannot consume one another's output, and a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. `spawnTerminal` is one deep primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members. ### Lifecycle and invariants @@ -140,8 +140,8 @@ No direct invalidation; the named consumers own any request-prefix changes. These limits define when the seam is a poor fit or leaves work to its consumers. They are current package constraints, not a comparison or a backlog. - **SDK-managed spawns remain outside** — a transport that owns its internal spawn (the SDK client, MCP) cannot route that call through this service; it can still import `scrubbedParentEnv` so environment policy stays single-sourced. -- **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the whole-tree wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template). -- **Observability is provider-specific** — a daemonized child that leaves its tree or session can outlive termination; providers document their substrate limits, and the seam adds no continuous process-table monitor. +- **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the managed-range wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template). +- **Observability is provider-specific** — native providers may own escaped descendants through systemd scopes or Windows Jobs, while fallback providers expose weaker process-group, tree, or session visibility. The seam adds no continuous process-table monitor. ### Dev Note diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md index 3bfbb909f3..2a58e2b719 100644 --- a/packages/subprocess/subprocess/README.zh.md +++ b/packages/subprocess/subprocess/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -任何需要运行子进程的组合都可以通过 `ctx.subprocess` 启动完全明确指定的子进程或真实终端会话，收到带流与退出事实的活动句柄，并按需终止整棵进程树。本服务提供可执行文件查找、共享的环境清理与有界输出捕获，而每一项默认值——argv、时限、shell 语义——都显式留在请求上，由消费方能力 seam 决定进程的含义。组合只需挂载一个提供方实现（如 `dsh-subprocess-local`）来注册该服务；seam 包本身是抽象约定，不是可直接加载的插件。本包不直接接触模型：进程输出与生命周期的渲染由消费方工具负责。 +任何需要运行子进程的组合都可以通过 `ctx.subprocess` 启动完全明确指定的子进程或真实终端会话，收到带流与直接退出事实的活动句柄，然后终止并等待由提供方管理的范围。本服务提供可执行文件查找、共享的环境清理与有界输出捕获，而每一项默认值——argv、时限、shell 语义——都显式留在请求上，由消费方能力 seam 决定进程的含义。组合只需挂载一个提供方实现（如 `dsh-subprocess-local`）来注册该服务；seam 包本身是抽象约定，不是可直接加载的插件。本包不直接接触模型：进程输出与生命周期的渲染由消费方工具负责。 ## 目录 @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -在需要运行子进程的组合中挂载一个 subprocess 提供方，并从拥有该命令的能力包调用 `ctx.subprocess`。常用路径是显式的：解析可执行文件、用完全明确的请求 spawn、读取你要的输出，并在工作完成时终止进程树。 +在需要运行子进程的组合中挂载一个 subprocess 提供方，并从拥有该命令的能力包调用 `ctx.subprocess`。常用路径是显式的：解析可执行文件、用完全明确的请求 spawn、读取你要的输出，并在工作完成时终止受管范围。 ### 挂载服务 @@ -38,7 +38,7 @@ kind: "package-reference" ### 启动受管进程 -请求完全明确：程序与参数、工作目录、每条流一种 stdio 处置方式、终止宽限期、可选的中止信号与可选的环境覆盖。进程关闭时，`done` 以退出事实（`exitCode` 与 `signal`）resolve，且只在 spawn 层面失败时 reject；收集输出在退出后仍可读取。 +请求完全明确：程序与参数、工作目录、每条流一种 stdio 处置方式、终止宽限期、可选的中止信号与可选的环境覆盖。目标与受管范围标识保留在提供方内部。`done` 以直接命令的退出事实（`exitCode` 与 `signal`）resolve，并在 spawn 或提供方失败时 reject；收集输出在退出后仍可读取。 ```text const executable = await ctx.subprocess.resolveExecutable('bash') @@ -62,7 +62,7 @@ const output = handle.collected.stdout?.readFrom(0) ### 管理进程生命周期 -终止在任何平台上都以进程树为范围：`terminate()` 执行 SIGTERM → 宽限期 → SIGKILL 升级（Windows 上立即强制终止），幂等，进程树消亡后为空操作。请求的中止信号会启动同样的升级，因此消费方自有的 deadline 可以取消整棵进程树。`waitForExit()` 只有在整棵进程树都退出后才会 resolve，而非只看直接子进程，因此在拆卸返回之前仍可观察到仍在运行的辅助进程。时限与原因分类归调用方所有；服务只做响应。 +终止与等待使用同一个由提供方管理的范围。`terminate()` 会启动提供方记录的流程，具有幂等性，并在该范围为空后成为空操作；请求的中止信号会启动同一流程。`waitForExit()` 观察同一范围，只在提供方证明它完全停稳后 resolve，因此直接命令结束不会掩盖仍存活的后代。所选 owner 无法再证明完全停稳时，它会 reject。提供方记录其 native owner 与较弱 fallback；时限、拆卸阶梯与原因分类归调用方所有。 ### 运行终端会话 @@ -74,7 +74,7 @@ const output = handle.collected.stdout?.readFrom(0) ### 可能出错的地方 -无法解析的可执行文件会以稳定的错误快速失败。从未启动成功的 spawn 会让 `done` reject；从未运行过的进程没有任何缓冲输出。脱离进程树或会话的 daemon 化子进程可能比终止更长寿——提供方 README 会记录各自的可观察性限制。当传输拥有自己的 spawn（SDK 客户端、MCP）时，请绕开本服务并直接导入 `scrubbedParentEnv`，让环境策略保持单一来源。 +无法解析的可执行文件会以稳定的错误快速失败。从未启动成功的 spawn 会让 `done` reject；从未运行过的进程没有任何缓冲输出。提供方无法证明所选范围为空时，`waitForExit()` 也会 reject；提供方 fallback 可能无法拥有逃离其进程组或已观察 session 的后代。当传输拥有自己的 spawn（SDK 客户端、MCP）时，请绕开本服务并直接导入 `scrubbedParentEnv`，让环境策略保持单一来源。 ----- @@ -100,7 +100,7 @@ const output = handle.collected.stdout?.readFrom(0) ### 数据模型与流程 -spawn 立即返回活动句柄；请求的中止信号驱动与 `terminate()` 相同的终止升级。收集模式的读取器无游标：偏移量是调用方拥有的全流字节坐标，因此独立读取器不会消费彼此的输出，偏移量滑出内存尾部的读取标记为 `lossy`，并在 spill 文件存在时指向它。`spawnTerminal` 是一项底层原语，因为普通管道无法分配控制终端或清理终端会话成员。 +spawn 会立即返回活动句柄，而不公开目标身份。`done` 独立报告直接命令的结果或失败，`waitForExit()` 则报告受管范围是否完全停稳。请求的中止信号驱动与 `terminate()` 相同的终止流程。收集模式的读取器无游标：偏移量是调用方拥有的全流字节坐标，因此独立读取器不会消费彼此的输出，偏移量滑出内存尾部的读取标记为 `lossy`，并在 spill 文件存在时指向它。`spawnTerminal` 是一项底层原语，因为普通管道无法分配控制终端或清理终端会话成员。 ### 生命周期与不变式 @@ -140,8 +140,8 @@ spawn 立即返回活动句柄；请求的中止信号驱动与 `terminate()` 这些限制说明该 seam 何时不合适，或何时把工作留给消费方。它们是当前包约束，不是对比或任务积压。 - **由 SDK 管理的 spawn 仍在服务之外**——拥有内部 spawn 的传输（SDK 客户端、MCP）无法把该调用路由到本服务；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。 -- **拆卸阶梯归消费方所有**——该 seam 只提供信号动词与整棵进程树的等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。 -- **可观察性取决于提供方**——脱离进程树或会话的 daemon 化子进程可能比终止更长寿；提供方记录各自的执行基底限制，seam 不新增持续的进程表监视器。 +- **拆卸阶梯归消费方所有**——该 seam 只提供信号动词与受管范围等待，不提供现成的完全停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。 +- **可观察性取决于提供方**——native 提供方可以通过 systemd scope 或 Windows Job 拥有逃逸后代，fallback 提供方则只暴露较弱的进程组、进程树或 session 可见性。该 seam 不新增持续的进程表监视器。 ### 开发备注 diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts index d31b3685e4..0cda343664 100644 --- a/packages/subprocess/subprocess/src/index.ts +++ b/packages/subprocess/subprocess/src/index.ts @@ -1,6 +1,6 @@ /** * Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup, - * fully specified managed process trees with raw or + * fully specified provider-managed process ranges with raw or * collected stdio, and one terminal-process primitive. Command defaulting, * shell semantics, deadlines, protocol framing, terminal readiness, and * presentation belong to consumers. The local implementation lives in @@ -92,17 +92,18 @@ declare module '@deepseek-ai/cordis' { * Implementations must honor these semantics: * - Executable paths belong to one execution world shared with the mounted * filesystem provider. - * - {@link spawn} returns immediately with a live handle; `done` resolves at - * process close with exit facts and rejects only for spawn-level failures. + * - {@link spawn} returns a live handle synchronously. Target identity remains + * provider-private; `done` resolves with the spawned command's exit facts and + * may reject for spawn or provider failures. * - Collect-mode readers are offset-based and non-consuming, so independent * readers never consume one another's output; lossy reads report truncation * and the spill file holding the complete stream when one exists. Piped * streams are handed to the caller raw and never buffered here. - * - {@link SubprocessHandle.terminate} (and the spec's abort signal) escalates - * SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every - * platform. {@link SubprocessHandle.waitForExit} observes whole-tree - * liveness, so a consumer-owned teardown ladder can hold each tier on real - * quiescence. + * - {@link SubprocessHandle.terminate} (and the spec's abort signal) starts the + * provider's documented procedure against its managed range. + * {@link SubprocessHandle.waitForExit} observes that same range so a + * consumer-owned teardown ladder can hold each tier on real quiescence; each + * provider documents its signalling and observability limits. * - Disposal of the service terminates all still-running managed processes * and awaits their exit. * - {@link spawnTerminal} owns terminal allocation, text transport, @@ -138,13 +139,14 @@ export abstract class SubprocessRuntime extends Service { * applies no defaults. * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment. * @returns the live process handle (streams/readers, signalling, outcome promise). + * @throws synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation. */ abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle /** * Allocate a real terminal and start one owned process session. This is the * only non-pipe process primitive: implementations own terminal byte I/O, - * foreground groups, signals, and complete session-tree cleanup. + * foreground groups, signals, and whole-session quiescence. * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation. * @returns the live terminal handle after allocation succeeds. */ diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts index 5d86f098d4..8f07e05fa9 100644 --- a/packages/subprocess/subprocess/src/types.ts +++ b/packages/subprocess/subprocess/src/types.ts @@ -1,7 +1,7 @@ /** * Vocabulary for the subprocess Service Definition: fully-specified spawn requests with * Node-shaped per-stream stdio modes, bounded collected output with spill - * recovery, raw piped streams, and tree-scoped termination. Command + * recovery, raw piped streams, and managed-range termination. Command * defaulting, shell semantics, protocol framing, and presentation belong to * consumers such as the bash executor seam. * @module dsh-subprocess/types @@ -81,14 +81,15 @@ export interface SubprocessSpawnSpec { stdio: SubprocessStdio /** * Positive finite grace period in milliseconds, no greater than - * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation - * and for draining still-open collected pipes after the process exits (an - * inherited descriptor held by a surviving descendant cannot hold the - * outcome open indefinitely). + * `MAX_TIMER_DELAY_MS`, available to the provider's termination procedure + * and used for draining still-open collected pipes after the process exits + * (an inherited descriptor held by a survivor cannot hold the outcome open + * indefinitely). Providers document whether range termination is staged or + * immediate. */ graceMs: number /** - * Abort signal — starts the terminate escalation on the process tree when + * Abort signal — starts the terminate escalation on the managed range when * it fires. The caller owns deadlines and cause classification; this seam * only reacts to the abort. */ @@ -156,17 +157,14 @@ export interface SubprocessCollectedOutputs { } /** - * A live child process rooted in its own process tree. Collected output + * A live subprocess and its provider-managed process range. Collected output * remains readable after exit; piped streams belong to the caller. * - * Termination is tree-scoped everywhere: POSIX signals the detached process - * group (falling back to the direct child when the group is gone), Windows - * terminates the tree via `taskkill /T`, so helper processes cannot outlive - * the handle unnoticed. + * Termination and {@link SubprocessHandle.waitForExit} use the same managed + * range. Each provider documents the range it can observe and its signalling + * and observation limits. */ export interface SubprocessHandle { - /** Process id (tree root); -1 when the spawn itself failed. */ - readonly pid: number /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */ readonly stdin: Writable | undefined /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */ @@ -175,20 +173,20 @@ export interface SubprocessHandle { readonly stderr: Readable | undefined /** Offset-based readers for collect-mode streams (also readable after exit). */ readonly collected: SubprocessCollectedOutputs - /** Resolves at process close with exit facts; rejects only for spawn-level failures. */ + /** Resolves with spawned-command exit facts; rejects for spawn or provider failures. */ readonly done: Promise /** - * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree - * (Windows force-terminates immediately) — the seam's only termination - * verb. Idempotent, a no-op once the tree is gone (the pid may be reused), - * and also triggered by the spec's abort signal. + * Begin the provider's documented termination procedure on the managed range + * — the seam's only termination verb. Idempotent, a no-op once that range is + * gone, and also triggered by the spec's abort signal. */ terminate(): void /** - * Wait until the process tree has exited — the tree, not just the direct - * child, so a still-running helper is observable before teardown returns. + * Wait until the same managed range is empty — not just until the spawned + * command reports its outcome, so surviving work remains observable. * @param signal - optional bound for the wait. - * @returns `true` when the tree exited, `false` when the signal aborted first. + * @returns `true` when the managed range is empty, `false` when the signal aborted first. + * @throws when the selected provider can no longer observe its managed range. */ waitForExit(signal?: AbortSignal): Promise } @@ -228,7 +226,7 @@ export interface SubprocessTerminalForeground { /** * One live terminal process and its owned OS session. Terminal allocation, - * foreground-group inspection/signalling, and session-tree cleanup are one + * foreground-group inspection/signalling, and whole-session quiescence are one * deep subprocess primitive because none can be reconstructed from ordinary * piped stdio without substrate-specific process control. */ @@ -237,7 +235,7 @@ export interface SubprocessTerminalHandle { readonly pid: number /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */ readonly output: Readable - /** Resolves when the top-level process exits; rejects only for a live transport failure. */ + /** Resolves when the top-level process exits; rejects for a terminal startup, provider, or live transport failure. */ readonly done: Promise /** * Write text to the terminal input. diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts index bd752352d2..1e71605781 100644 --- a/packages/subprocess/subprocess/tests/service.spec.ts +++ b/packages/subprocess/subprocess/tests/service.spec.ts @@ -26,7 +26,6 @@ class StubSubprocessRuntime extends SubprocessRuntime { ? { stdout: { readFrom: () => read } } : {} return { - pid: spec.argv.length, stdin: undefined, stdout: undefined, stderr: undefined, @@ -60,7 +59,7 @@ describe('SubprocessRuntime seam', () => { stdio: { stdin: 'ignore', stdout: { maxBytes: 1 }, stderr: 'inherit' }, graceMs: 1, }) - expect(handle.pid).toBe(1) + expect(Object.hasOwn(handle, 'pid')).toBe(false) expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: '', nextOffset: 0, lossy: false }) handle.terminate() await expect(handle.waitForExit()).resolves.toBe(true) diff --git a/packages/subprocess/win32-process/README.i18n.yaml b/packages/subprocess/win32-process/README.i18n.yaml index d9e4d4b2ab..93697c26e1 100644 --- a/packages/subprocess/win32-process/README.i18n.yaml +++ b/packages/subprocess/win32-process/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/subprocess/win32-process/README.md -README.md: c9652b542dc7d08851508619d663e750c115f3ec -README.zh.md: 6eb0b2e26092fc593c8d3d5088110a935bd8c0be +README.md: 7a4d12f7fe6ef553113e0f202886fd42e8a313a2 +README.zh.md: 8ebc614d38ea206cba792b90a2f118c028bf0447 diff --git a/packages/subprocess/win32-process/README.md b/packages/subprocess/win32-process/README.md index c9652b542d..7a4d12f7fe 100644 --- a/packages/subprocess/win32-process/README.md +++ b/packages/subprocess/win32-process/README.md @@ -1,5 +1,5 @@ --- -description: "Low-level Win32 process primitives for maintainers implementing or debugging the Windows ACL sandbox." +description: "Low-level Win32 process primitives for maintainers implementing or debugging the Windows ACL sandbox and ordinary subprocess Job runner." kind: "package-library" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Low-level Win32 process library consumed by the Windows ACL sandbox. It owns the repository's one Koffi binding table for reusable restricted-process, stdio, and Job Object operations; it is not a Cordis service and does not choose sandbox policy or public child behavior. Read this page when maintaining the sandbox's native process path or checking its handle-lifetime limits. +This low-level Win32 process library is consumed by the Windows ACL sandbox and the ordinary subprocess Job runner. It owns the repository's one Koffi binding table for reusable process, stdio, and Job Object operations; it is not a Cordis service and does not choose sandbox policy or public child behavior. Read this page when maintaining either native process path or checking its handle-lifetime limits. ## Table of Contents @@ -24,16 +24,16 @@ Low-level Win32 process library consumed by the Windows ACL sandbox. It owns the ## Behavior -- **One reusable ABI owner** — `abi.ts` owns the Win32 constants and x64 layout values consumed by the sandbox process paths. `ffi.ts` lazily loads `kernel32.dll` and `advapi32.dll`, verifies `STARTUPINFOW` and `PROCESS_INFORMATION`, exposes typed operations and error formatting, and lets sandbox policy bind its remaining APIs through the same loaded libraries. -- **Restricted-token creation** — `RestrictedProcessSpawnOptions` requires the sandbox's primary token and uses `CreateProcessAsUserW`. Piped and inherited-stdio paths share command-line quoting, cwd, the inherited environment block, checked return values, and handle cleanup. +- **One reusable ABI owner** — `abi.ts` owns the Win32 constants and x64 layout values consumed by both process paths. `ffi.ts` lazily loads `kernel32.dll` and `advapi32.dll`, verifies `STARTUPINFOW` and `PROCESS_INFORMATION`, exposes typed operations and error formatting, and lets sandbox policy bind its remaining APIs through the same loaded libraries. +- **Restricted-token creation** — `RestrictedProcessSpawnOptions` requires the sandbox's primary token and uses `CreateProcessAsUserW`. Piped and inherited-stdio paths share command-line quoting, cwd, the restricted-token null-environment policy, checked return values, and handle cleanup. - **Piped process primitive** — `spawnPipedProcess()` creates anonymous stdin/stdout/stderr pipes, closes stdin immediately, returns the two read ends, and leaves process waiting and pipe draining to the caller. Every partial failure closes the handles already owned by the operation, and every Koffi out-parameter or struct allocation is freed after its Win32 lifetime. - **Inherited-stdio Job primitive** — `spawnInheritedJobProcess()` creates one kill-on-close Job, temporarily marks the current stdio handles inheritable, creates the restricted child suspended, assigns it to the Job, and then resumes its initial thread. Target code cannot run before Job assignment; controlled assignment or resume failures terminate the suspended child or close the assigned Job before releasing every owned handle. -- **Explicit settlement ownership** — `waitForProcessExit()` waits and closes the process handle. `drainPipe()` reuses one native count slot while draining, frees it, and closes the pipe read handle. The sandbox retains its existing scheduling, result composition, and caller-owned Job closure. +- **Ordinary Job runner primitive** — `CurrentTokenProcessSpawnOptions` requires a resolved `applicationName`, the complete target environment, and three runner CRT descriptors dedicated to target stdin, stdout, and stderr. `spawnCurrentTokenJobProcess()` maps those descriptors to OS handles through Node's exported `uv_get_osfhandle()`, rejects invalid results, temporarily marks the handles inheritable, and passes them through `STARTF_USESTDHANDLES`. It sends a sorted UTF-16LE environment block with `CREATE_UNICODE_ENVIRONMENT`, creates the target suspended through `CreateProcessW`, assigns it to an unnamed kill-on-close Job, and resumes it only after assignment. The original command-line argv entry remains unchanged, and the runner can close its carrier descriptors without touching Node's own standard streams. +- **Ordinary settlement operations** — `pollProcessExit()` publishes direct exit separately, while `isJobEmpty()` reads `QueryInformationJobObject(JobObjectBasicAccountingInformation)` until `ActiveProcesses` reaches zero. Checked Job termination and handle closure keep the runner as the only native owner. +- **Explicit settlement ownership** — `waitForProcessExit()` waits and closes a sandbox process handle; ordinary runner process polling, Job accounting, and checked Job termination/closure remain separate operations. `drainPipe()` reuses one native count slot while draining, frees it, and closes the pipe read handle. Each caller owns its result composition and returned handles. The Windows ACL sandbox adds SID, DACL, grant, workspace, and public child policy above these primitives. - - ## Header verification @@ -43,7 +43,7 @@ The process, stdio, and Job constants plus selected structure sizes and offsets g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe ``` -The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their 64-bit sizes at module load. The probe remains the evidence for the other recorded offsets and constants. +The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their 64-bit sizes at module load. The probe additionally fixes pointer and handle widths, the Unicode-environment flag, and the basic Job accounting record size and `ActiveProcesses` offset used to determine quiescence; it remains the evidence for the other recorded offsets and constants. ## Model Experience @@ -52,7 +52,7 @@ The Koffi `STARTUPINFOW` and `PROCESS_INFORMATION` definitions also assert their #### What the model sees -Nothing directly. The package exposes `Win32ProcessBindings` and process primitives to the sandbox, which owns all model-visible tools, output, and diagnostics; this package contributes no prompt text or tool schema. +Nothing directly. The package exposes `Win32ProcessBindings`, `CurrentTokenProcessBindings`, and process primitives to the sandbox and ordinary runner, which own all model-visible tools, output, and diagnostics; this package contributes no prompt text or tool schema. #### Token effect @@ -68,8 +68,8 @@ The package contributes no stable request prefix, so it does not invalidate mode - **Windows-only native loading** — importing the generic types is portable, but resolving the binding table loads Windows DLLs and fails on other hosts. Cross-platform tests inject a binding table instead of loading native APIs. - **No public process service** — the package intentionally does not wrap its primitives in Cordis or Node streams. A consumer must own its policy, async scheduling, output limits, cancellation, and final handle closure. -- **Inherited environment only** — process creation passes a null environment block. The sandbox establishes changes through `SetEnvironmentVariableW` first because passing an explicit block through Koffi makes `CreateProcessAsUserW` fail with `ERROR_INVALID_PARAMETER`. Other callers that need environment changes must establish them before invoking the primitive or use their own runner process. -- **Restricted-token consumer only** — ordinary `CreateProcessW`, exact `applicationName`, parent-stdio release, and whole-Job settlement are absent until an ordinary process consumer requires them. +- **Restricted-token null environment** — the `CreateProcessAsUserW` sandbox primitives pass a null environment block and establish changes through `SetEnvironmentVariableW` first because an explicit block through Koffi fails with `ERROR_INVALID_PARAMETER`. The ordinary `CreateProcessW` runner instead requires a complete target environment and passes a sorted, double-NUL-terminated UTF-16LE block, including `=X:` drive entries, without mutating its own environment. +- **No standalone process API** — the package exposes the operations current sandbox and ordinary-runner consumers need, but it does not own Node streams, public handles, output policy, cancellation, or durable state. - **Create-to-assignment interruption** — the target starts suspended and cannot execute before Job assignment, but an external termination of the runner in the narrow interval between process creation and assignment can leave the suspended target behind. The package does not claim atomic Job attachment. - **Header evidence is architecture-specific** — the committed ABI probe and layout constants cover the repository's current 64-bit Windows targets. A new pointer width or incompatible Windows ABI requires updating the probe before support is claimed. diff --git a/packages/subprocess/win32-process/README.zh.md b/packages/subprocess/win32-process/README.zh.md index 6eb0b2e260..8ebc614d38 100644 --- a/packages/subprocess/win32-process/README.zh.md +++ b/packages/subprocess/win32-process/README.zh.md @@ -1,5 +1,5 @@ --- -description: "面向实现或排查 Windows ACL 沙箱的维护者，说明底层 Win32 进程原语。" +description: "面向实现或排查 Windows ACL 沙箱与普通子进程 Job runner 的维护者，说明底层 Win32 进程原语。" kind: "package-library" --- @@ -9,7 +9,7 @@ kind: "package-library" ## 概述 -供 Windows ACL 沙箱消费的底层 Win32 进程库。它唯一拥有仓库中可复用 restricted-process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护沙箱原生进程路径或检查 handle 生命周期限制时，请阅读本页。 +供 Windows ACL 沙箱与普通子进程 Job runner 消费的底层 Win32 进程库。它唯一拥有仓库中可复用 process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护任一原生进程路径或检查 handle 生命周期限制时，请阅读本页。 ## 目录 @@ -24,16 +24,16 @@ kind: "package-library" ## Behavior -- **唯一可复用 ABI owner** — `abi.ts` 拥有 sandbox process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll` 与 `advapi32.dll`，核验 `STARTUPINFOW` 和 `PROCESS_INFORMATION`，提供带类型的操作与错误格式化，并让 sandbox policy 通过同一组已加载库绑定剩余 API。 -- **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求 sandbox 的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引用、cwd、继承环境块、返回值检查与句柄清理。 +- **唯一可复用 ABI owner** — `abi.ts` 拥有两条 process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll` 与 `advapi32.dll`，核验 `STARTUPINFOW` 和 `PROCESS_INFORMATION`，提供带类型的操作与错误格式化，并让 sandbox policy 通过同一组已加载库绑定剩余 API。 +- **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求 sandbox 的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引用、cwd、restricted-token 空环境策略、返回值检查与句柄清理。 - **管道进程原语** — `spawnPipedProcess()` 创建匿名 stdin/stdout/stderr 管道，立即关闭 stdin，并返回两个读取端；调用方负责等待进程与排空管道。任一局部失败都会关闭该操作已经拥有的句柄，并在各自 Win32 生命周期结束后释放每个 Koffi 输出槽与结构体分配。 - **继承 stdio 的 Job 原语** — `spawnInheritedJobProcess()` 创建一个 kill-on-close Job，临时把当前 stdio 句柄设为可继承，以 suspended 状态创建 restricted child，把它分配给 Job，再恢复初始线程。目标代码不会在 Job 分配前运行；受控的分配或恢复失败会终止 suspended child，或在释放全部已拥有句柄前关闭已分配的 Job。 -- **显式结算归属** — `waitForProcessExit()` 等待并关闭进程句柄。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。sandbox 保留既有调度、result 组合与调用方拥有的 Job 关闭行为。 +- **ordinary Job runner 原语** — `CurrentTokenProcessSpawnOptions` 要求已解析的 `applicationName`、完整 target 环境，以及三个专用于 target stdin、stdout 与 stderr 的 runner CRT 描述符。`spawnCurrentTokenJobProcess()` 通过 Node 导出的 `uv_get_osfhandle()` 把这些描述符映射为 OS handle，拒绝无效结果，临时把 handle 设为可继承，并通过 `STARTF_USESTDHANDLES` 传入。它使用 `CREATE_UNICODE_ENVIRONMENT` 传入排序后的 UTF-16LE 环境块，再以 suspended 状态通过 `CreateProcessW` 创建 target、把它分配给 unnamed kill-on-close Job，并只在分配后恢复。原始命令行 argv 项保持不变，runner 也可以关闭自己的 carrier 描述符，而不触碰 Node 自身的标准流。 +- **ordinary 停稳操作** — `pollProcessExit()` 单独发布 direct exit，`isJobEmpty()` 则读取 `QueryInformationJobObject(JobObjectBasicAccountingInformation)`，直到 `ActiveProcesses` 归零。带检查的 Job 终止与 handle 关闭使 runner 保持唯一 native owner。 +- **显式结算归属** — `waitForProcessExit()` 等待并关闭 sandbox process handle；ordinary runner 的 process polling、Job accounting 与 checked Job termination/closure 是独立操作。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。每个调用方拥有自己的 result 组合与返回 handle。 Windows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。 - - ## 头部验证 @@ -43,7 +43,7 @@ process、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`ve g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe ``` -Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小；其余已记录偏移和常量由该探针提供证据。 +Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小。该探针还固定指针与 handle 宽度、Unicode 环境标志，以及用于判断停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移；其余已记录偏移和常量也由该探针提供证据。 ## Model Experience @@ -52,7 +52,7 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载 #### 模型看到什么 -没有直接内容。本包向 sandbox 提供 `Win32ProcessBindings` 与进程原语；sandbox 拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。 +没有直接内容。本包向 sandbox 与 ordinary runner 提供 `Win32ProcessBindings`、`CurrentTokenProcessBindings` 与进程原语；两者拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。 #### Token 影响 @@ -68,8 +68,8 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载 - **仅在 Windows 原生加载** — 导入通用类型可跨平台进行，但解析绑定表会加载 Windows DLL，并在其他宿主失败。跨平台测试注入绑定表，不加载原生 API。 - **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node streams。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。 -- **只继承环境** — 进程创建传入空环境块。sandbox 会先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会使 `CreateProcessAsUserW` 以 `ERROR_INVALID_PARAMETER` 失败。其他需要改写环境的调用方必须在调用原语前建立环境，或使用自己的 runner 进程。 -- **只有 restricted-token 消费方** — ordinary `CreateProcessW`、精确 `applicationName`、parent-stdio release 与 whole-Job settlement 在 ordinary process 消费方出现前均不提供。 +- **restricted-token 空环境** — `CreateProcessAsUserW` sandbox 原语传入空环境块，并先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会以 `ERROR_INVALID_PARAMETER` 失败。ordinary `CreateProcessW` runner 则要求完整 target 环境，并传入排序、双 NUL 结尾的 UTF-16LE 块，其中包括 `=X:` 驱动器条目，而不修改自身环境。 +- **没有 standalone process API** — 本包只暴露当前 sandbox 与 ordinary-runner consumer 所需的操作，不拥有 Node streams、公共 handle、output policy、cancellation 或 durable state。 - **创建到分配之间的中断** — 目标以 suspended 状态启动，不能在 Job 分配前执行，但 runner 若在进程创建到分配之间的极窄区间被外力终止，可能留下 suspended target。本包不声明原子 Job 附加保证。 - **header 证据限定架构** — 已提交的 ABI probe 与布局常量覆盖仓库当前 64 位 Windows 目标。支持新的指针宽度或不兼容 Windows ABI 前，必须先更新 probe。 diff --git a/packages/subprocess/win32-process/package.json b/packages/subprocess/win32-process/package.json index af386bf6d4..ac7e548d56 100644 --- a/packages/subprocess/win32-process/package.json +++ b/packages/subprocess/win32-process/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-win32-process", - "description": "Low-level Win32 process, stdio, and Job Object primitives for the DeepSeek Harness Windows sandbox", + "description": "Shared low-level Win32 process, stdio, and Job Object primitives", "version": "0.1.3-alpha.1", "publishConfig": { "access": "public" diff --git a/packages/subprocess/win32-process/src/abi.ts b/packages/subprocess/win32-process/src/abi.ts index fbdda9059f..e34d941613 100644 --- a/packages/subprocess/win32-process/src/abi.ts +++ b/packages/subprocess/win32-process/src/abi.ts @@ -6,8 +6,12 @@ export const STARTF_USESTDHANDLES = 0x00000100 export const HANDLE_FLAG_INHERIT = 0x1 /** Infinite WaitForSingleObject timeout. */ export const INFINITE = 0xFFFFFFFF +/** WaitForSingleObject returned because a zero-time probe is not signalled. */ +export const WAIT_TIMEOUT = 258 /** CreateProcess flag that prevents user code from running before resume. */ export const CREATE_SUSPENDED = 0x4 +/** CreateProcess flag selecting a UTF-16 environment block. */ +export const CREATE_UNICODE_ENVIRONMENT = 0x400 /** GetStdHandle selector for standard input. */ export const STD_INPUT_HANDLE = -10 /** GetStdHandle selector for standard output. */ @@ -26,8 +30,14 @@ export const ERROR_BROKEN_PIPE = 109 export const ERROR_NO_DATA = 232 /** Job limit that terminates every member when the final Job handle closes. */ export const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000 +/** QueryInformationJobObject class for basic accounting and active-process count. */ +export const JobObjectBasicAccountingInformation = 1 /** SetInformationJobObject class for JOBOBJECT_EXTENDED_LIMIT_INFORMATION. */ export const JobObjectExtendedLimitInformation = 9 +/** x64 JOBOBJECT_BASIC_ACCOUNTING_INFORMATION byte size. */ +export const JOBOBJECT_BASIC_ACCOUNTING_SIZE = 48 +/** Byte offset of ActiveProcesses in JOBOBJECT_BASIC_ACCOUNTING_INFORMATION. */ +export const JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET = 40 /** x64 JOBOBJECT_EXTENDED_LIMIT_INFORMATION byte size. */ export const JOBOBJECT_EXTENDED_LIMIT_SIZE = 144 /** Byte offset of BasicLimitInformation.LimitFlags in the extended Job record. */ diff --git a/packages/subprocess/win32-process/src/ffi.ts b/packages/subprocess/win32-process/src/ffi.ts index a2171d0023..c8b8445e0a 100644 --- a/packages/subprocess/win32-process/src/ffi.ts +++ b/packages/subprocess/win32-process/src/ffi.ts @@ -70,7 +70,7 @@ export interface Win32ProcessBindings { setHandleInformation(handle: NativePtr, mask: number, flags: number): number createProcessAsUserW( token: NativePtr, - applicationName: null, + applicationName: string | null, commandLine: string, processAttributes: null, threadAttributes: null, @@ -81,6 +81,18 @@ export interface Win32ProcessBindings { startupInfo: NativePtr, processInfo: NativePtr, ): number + createProcessW( + applicationName: string | null, + commandLine: string, + processAttributes: null, + threadAttributes: null, + inheritHandles: number, + creationFlags: number, + environment: Buffer | null, + currentDirectory: string | null, + startupInfo: NativePtr, + processInfo: NativePtr, + ): number readFile(file: NativePtr, buffer: Buffer, count: number, bytesRead: NativePtr, overlapped: null): number peekNamedPipe( pipe: NativePtr, @@ -94,12 +106,25 @@ export interface Win32ProcessBindings { getExitCodeProcess(process: NativePtr, exitCode: NativePtr): number createJobObjectW(attributes: null, name: null): NativePtr setInformationJobObject(job: NativePtr, cls: number, information: Buffer, length: number): number + queryInformationJobObject( + job: NativePtr, + cls: number, + information: Buffer, + length: number, + returnLength: null, + ): number assignProcessToJobObject(job: NativePtr, process: NativePtr): number resumeThread(thread: NativePtr): number terminateProcess(process: NativePtr, exitCode: number): number + terminateJobObject(job: NativePtr, exitCode: number): number getStdHandle(stdHandle: number): NativePtr } +/** Generic Win32 calls plus Node's libuv descriptor-to-handle bridge. */ +export interface CurrentTokenProcessBindings extends Win32ProcessBindings { + uvGetOsfhandle(fileDescriptor: number): NativePtr | null +} + /** Koffi STARTUPINFOW layout. */ export const STARTUPINFOW = koffi.struct('DSH_STARTUPINFOW', { cb: 'uint32', @@ -209,7 +234,7 @@ export function decodeProcessInfo(processInfo: NativePtr): ProcessInfoOutput { } let cachedContext: Win32BindingContext | undefined -let cached: Win32ProcessBindings | undefined +let cached: CurrentTokenProcessBindings | undefined /* v8 ignore start -- exercised by native Windows ABI and sandbox jobs. */ function bindingContext(): Win32BindingContext { @@ -226,9 +251,10 @@ function bindingContext(): Win32BindingContext { return cachedContext } -function bindings(): Win32ProcessBindings { +function bindings(): CurrentTokenProcessBindings { if (cached !== undefined) return cached const { kernel32, advapi32, bind } = bindingContext() + const node = koffi.load(null) cached = { closeHandle: bind(kernel32, 'CloseHandle', 'int', [PVOID]), getLastError: bind(kernel32, 'GetLastError', 'uint32', []), @@ -241,6 +267,10 @@ function bindings(): Win32ProcessBindings { PVOID, 'str16', 'str16', PVOID, PVOID, 'int', 'uint32', PVOID, 'str16', koffi.pointer(STARTUPINFOW), koffi.pointer(PROCESS_INFORMATION), ]), + createProcessW: bind(kernel32, 'CreateProcessW', 'int', [ + 'str16', 'str16', PVOID, PVOID, 'int', 'uint32', PVOID, 'str16', + koffi.pointer(STARTUPINFOW), koffi.pointer(PROCESS_INFORMATION), + ]), readFile: bind(kernel32, 'ReadFile', 'int', [PVOID, PVOID, 'uint32', koffi.pointer('uint32'), PVOID]), peekNamedPipe: bind(kernel32, 'PeekNamedPipe', 'int', [ PVOID, PVOID, 'uint32', koffi.pointer('uint32'), koffi.pointer('uint32'), koffi.pointer('uint32'), @@ -249,11 +279,16 @@ function bindings(): Win32ProcessBindings { getExitCodeProcess: bind(kernel32, 'GetExitCodeProcess', 'int', [PVOID, koffi.pointer('uint32')]), createJobObjectW: bind(kernel32, 'CreateJobObjectW', PVOID, [PVOID, 'str16']), setInformationJobObject: bind(kernel32, 'SetInformationJobObject', 'int', [PVOID, 'int', PVOID, 'uint32']), + queryInformationJobObject: bind(kernel32, 'QueryInformationJobObject', 'int', [ + PVOID, 'int', PVOID, 'uint32', PVOID, + ]), assignProcessToJobObject: bind(kernel32, 'AssignProcessToJobObject', 'int', [PVOID, PVOID]), resumeThread: bind(kernel32, 'ResumeThread', 'uint32', [PVOID]), terminateProcess: bind(kernel32, 'TerminateProcess', 'int', [PVOID, 'uint32']), + terminateJobObject: bind(kernel32, 'TerminateJobObject', 'int', [PVOID, 'uint32']), getStdHandle: bind(kernel32, 'GetStdHandle', PVOID, ['int']), - } as unknown as Win32ProcessBindings + uvGetOsfhandle: node.func('uv_get_osfhandle', PVOID, ['int']), + } as unknown as CurrentTokenProcessBindings return cached } @@ -264,9 +299,17 @@ function bindings(): Win32ProcessBindings { */ export function extendWin32ProcessBindings( create: (context: Win32BindingContext) => Extension, -): Win32ProcessBindings & Extension { +): CurrentTokenProcessBindings & Extension { return { ...bindings(), ...create(bindingContext()) } } + +/** + * Load the generic process binding table without policy-specific extensions. + * @returns shared Win32 process, stdio, and Job operations. + */ +export function loadWin32ProcessBindings(): CurrentTokenProcessBindings { + return bindings() +} /* v8 ignore stop */ /** diff --git a/packages/subprocess/win32-process/src/index.ts b/packages/subprocess/win32-process/src/index.ts index d6dee59d58..5fc6de85ce 100644 --- a/packages/subprocess/win32-process/src/index.ts +++ b/packages/subprocess/win32-process/src/index.ts @@ -1,4 +1,4 @@ -/** Low-level Win32 process, stdio, and Job Object primitives used by the Windows ACL sandbox. */ +/** Shared low-level Win32 process, stdio, and Job Object primitives. */ export { ERROR_INSUFFICIENT_BUFFER } from './abi.ts' export * from './errors.ts' @@ -9,20 +9,30 @@ export { decodeUint32, extendWin32ProcessBindings, isNullPtr, + loadWin32ProcessBindings, throwLastError, throwWin32, } from './ffi.ts' export type { + CurrentTokenProcessBindings, NativePtr, Win32ProcessBindings, } from './ffi.ts' export { + closeHandleChecked, drainPipe, + isJobEmpty, + pollProcessExit, + probeCurrentTokenJobSupport, spawnInheritedJobProcess, + spawnCurrentTokenJobProcess, spawnPipedProcess, + terminateJob, waitForProcessExit, } from './process.ts' export type { + CurrentTokenStdioFileDescriptors, + CurrentTokenProcessSpawnOptions, SpawnedJobProcess, SpawnedPipedProcess, } from './process.ts' diff --git a/packages/subprocess/win32-process/src/process.ts b/packages/subprocess/win32-process/src/process.ts index 7c676e1f7f..1c0fa7f90d 100644 --- a/packages/subprocess/win32-process/src/process.ts +++ b/packages/subprocess/win32-process/src/process.ts @@ -15,7 +15,7 @@ import { throwLastError, throwWin32, } from './ffi.ts' -import type { NativePtr, Win32ProcessBindings } from './ffi.ts' +import type { CurrentTokenProcessBindings, NativePtr, Win32ProcessBindings } from './ffi.ts' /** * Quote one argument according to CommandLineToArgvW parsing. @@ -53,14 +53,49 @@ export function buildCommandLine(program: string, args: readonly string[]): stri return [program, ...args].map(quoteArg).join(' ') } -/** Restricted-token process creation inputs owned by the Windows ACL sandbox. */ -export interface RestrictedProcessSpawnOptions { - /** Executable argv entry passed through CreateProcessAsUserW. */ +function compareWindowsEnvironmentKeys( + [left]: readonly [string, string], + [right]: readonly [string, string], +): number { + const foldedLeft = left.toUpperCase() + const foldedRight = right.toUpperCase() + return foldedLeft < foldedRight ? -1 : foldedLeft > foldedRight ? 1 : 0 +} + +function encodeWindowsEnvironment(env: Readonly>): Buffer { + const entries = Object.entries(env).sort(compareWindowsEnvironmentKeys) + const strings = entries.map(([key, value]) => `${key}=${value}`) + return Buffer.from(`${strings.join('\0')}\0\0`, 'utf16le') +} + +interface ProcessSpawnOptions { + /** Executable argv entry passed through CreateProcess. */ command: string /** Arguments excluding the executable. */ args: readonly string[] /** Existing child working directory. */ cwd: string +} + +/** Ordinary process creation inputs used by the local Win32 runner. */ +export interface CurrentTokenProcessSpawnOptions extends ProcessSpawnOptions { + /** Resolved executable path passed separately from the preserved argv entry. */ + applicationName: string + /** Complete target environment passed without mutating the runner. */ + env: Readonly> + /** Runner CRT descriptors carrying target stdin, stdout, and stderr. */ + stdio: CurrentTokenStdioFileDescriptors +} + +/** Runner CRT descriptors whose OS handles become the target standard handles. */ +export interface CurrentTokenStdioFileDescriptors { + stdin: number + stdout: number + stderr: number +} + +/** Restricted-token process creation inputs owned by the Windows ACL sandbox. */ +export interface RestrictedProcessSpawnOptions extends ProcessSpawnOptions { /** Restricted primary token supplied by sandbox policy. */ token: NativePtr } @@ -316,41 +351,71 @@ function createKillOnCloseJob(api: Win32ProcessBindings): NativePtr { return job } -/** - * Spawn suspended, assign the child to a kill-on-close Job, then resume it. - * @param api - active binding table. - * @param options - command, cwd, args, and restricted primary token. - * @returns caller-owned process and Job handles after successful resume. - * @remarks Node clears stdio handle inheritability at startup through - * uv_disable_stdio_inheritance. This operation temporarily restores the bits - * required by STARTF_USESTDHANDLES. Restoring them afterward is best-effort: - * failure must not replace the already-created child's outcome. - */ -export function spawnInheritedJobProcess( - api: Win32ProcessBindings, - options: RestrictedProcessSpawnOptions, -): SpawnedJobProcess { - const job = createKillOnCloseJob(api) - const getStdHandle = (selector: number, label: string): NativePtr => { +interface ProcessStandardHandles { + stdin: NativePtr + stdout: NativePtr + stderr: NativePtr +} + +// Koffi exposes PVOID as an unsigned 64-bit bigint on supported Windows hosts. +const UV_INVALID_OS_FILE_HANDLE = 0xffff_ffff_ffff_ffffn +const UV_INVALID_FILE_DESCRIPTOR = 0xffff_ffff_ffff_fffen + +function inheritedStandardHandles(api: Win32ProcessBindings): ProcessStandardHandles { + const get = (selector: number, label: string): NativePtr => { const handle = api.getStdHandle(selector) if (!isNullPtr(handle)) return handle - const win32Code = api.getLastError() - api.closeHandle(job) - throwWin32(api, 'GetStdHandle', win32Code, `null ${label} handle`) + throwLastError(api, 'GetStdHandle', `null ${label} handle`) } - const stdIn = getStdHandle(abi.STD_INPUT_HANDLE, 'stdin') - const stdOut = getStdHandle(abi.STD_OUTPUT_HANDLE, 'stdout') - const stdErr = getStdHandle(abi.STD_ERROR_HANDLE, 'stderr') + return { + stdin: get(abi.STD_INPUT_HANDLE, 'stdin'), + stdout: get(abi.STD_OUTPUT_HANDLE, 'stdout'), + stderr: get(abi.STD_ERROR_HANDLE, 'stderr'), + } +} + +function targetCarrierHandles( + api: CurrentTokenProcessBindings, + descriptors: CurrentTokenStdioFileDescriptors, +): ProcessStandardHandles { + const get = (fileDescriptor: number, label: string): NativePtr => { + const handle = api.uvGetOsfhandle(fileDescriptor) + if ( + isNullPtr(handle) + || handle === UV_INVALID_OS_FILE_HANDLE + || handle === UV_INVALID_FILE_DESCRIPTOR + ) { + throw new Error(`uv_get_osfhandle returned an invalid handle for target ${label} fd ${String(fileDescriptor)}`) + } + return handle + } + return { + stdin: get(descriptors.stdin, 'stdin'), + stdout: get(descriptors.stdout, 'stdout'), + stderr: get(descriptors.stderr, 'stderr'), + } +} + +/** Shared suspended-create, Job-assignment, and resume lifecycle. */ +function spawnJobProcess( + api: Win32ProcessBindings, + options: ProcessSpawnOptions, + resolveStdio: () => ProcessStandardHandles, + createName: 'CreateProcessAsUserW' | 'CreateProcessW', + create: (startupInfo: NativePtr, processInfo: NativePtr) => number, +): SpawnedJobProcess { + const job = createKillOnCloseJob(api) const enabled: NativePtr[] = [] let startupInfo: NativePtr | undefined let processInfo: NativePtr | undefined let created = 0 let createFailureCode = 0 try { + const stdio = resolveStdio() for (const [handle, label] of [ - [stdIn, 'stdin'], - [stdOut, 'stdout'], - [stdErr, 'stderr'], + [stdio.stdin, 'stdin'], + [stdio.stdout, 'stdout'], + [stdio.stderr, 'stderr'], ] as const) { if (api.setHandleInformation(handle, abi.HANDLE_FLAG_INHERIT, abi.HANDLE_FLAG_INHERIT) === 0) { throwLastError(api, 'SetHandleInformation', `${label} (enable inherit)`) @@ -361,19 +426,12 @@ export function spawnInheritedJobProcess( encodeStartupInfo(startupInfo, { cb: abi.STARTUPINFOW_SIZE, dwFlags: abi.STARTF_USESTDHANDLES, - hStdInput: stdIn, - hStdOutput: stdOut, - hStdError: stdErr, + hStdInput: stdio.stdin, + hStdOutput: stdio.stdout, + hStdError: stdio.stderr, }) processInfo = allocProcessInfo() - created = createRestrictedProcess( - api, - options, - buildCommandLine(options.command, options.args), - abi.CREATE_SUSPENDED, - startupInfo, - processInfo, - ) + created = create(startupInfo, processInfo) if (created === 0) createFailureCode = api.getLastError() } catch (error) { freeNative(processInfo) @@ -391,7 +449,7 @@ export function spawnInheritedJobProcess( api.closeHandle(job) throwWin32( api, - 'CreateProcessAsUserW', + createName, createFailureCode, `command: ${options.command}, cwd: ${options.cwd}`, ) @@ -407,7 +465,7 @@ export function spawnInheritedJobProcess( api.closeHandle(job) closeBestEffort(api, info.hThread) closeBestEffort(api, info.hProcess) - throw new Error(`CreateProcessAsUserW succeeded but returned null process/thread handles (pid ${info.dwProcessId})`) + throw new Error(`${createName} succeeded but returned null process/thread handles (pid ${info.dwProcessId})`) } if (api.assignProcessToJobObject(job, info.hProcess) === 0) { const win32Code = api.getLastError() @@ -427,3 +485,124 @@ export function spawnInheritedJobProcess( closeBestEffort(api, info.hThread) return { pid: info.dwProcessId, process: info.hProcess, job } } + +/** + * Spawn a restricted-token process suspended, assign its Job, then resume it. + * @param api - active binding table. + * @param options - command, cwd, args, and restricted primary token. + * @returns caller-owned process and Job handles after successful resume. + * @remarks Node clears stdio handle inheritability at startup through + * uv_disable_stdio_inheritance. This operation temporarily restores the bits + * required by STARTF_USESTDHANDLES. Restoring them afterward is best-effort: + * failure must not replace the already-created child's outcome. + */ +export function spawnInheritedJobProcess( + api: Win32ProcessBindings, + options: RestrictedProcessSpawnOptions, +): SpawnedJobProcess { + const commandLine = buildCommandLine(options.command, options.args) + return spawnJobProcess(api, options, () => inheritedStandardHandles(api), 'CreateProcessAsUserW', (startupInfo, processInfo) => + createRestrictedProcess( + api, + options, + commandLine, + abi.CREATE_SUSPENDED, + startupInfo, + processInfo, + )) +} + +/** + * Spawn an ordinary process suspended, assign its Job, then resume it. + * @param api - active binding table. + * @param options - command, cwd, argv, and target carrier descriptors. + * @returns caller-owned process and Job handles after successful resume. + */ +export function spawnCurrentTokenJobProcess( + api: CurrentTokenProcessBindings, + options: CurrentTokenProcessSpawnOptions, +): SpawnedJobProcess { + const commandLine = buildCommandLine(options.command, options.args) + const environment = encodeWindowsEnvironment(options.env) + return spawnJobProcess(api, options, () => targetCarrierHandles(api, options.stdio), 'CreateProcessW', (startupInfo, processInfo) => + api.createProcessW( + options.applicationName, + commandLine, + null, + null, + 1, + abi.CREATE_SUSPENDED | abi.CREATE_UNICODE_ENVIRONMENT, + environment, + options.cwd, + startupInfo, + processInfo, + )) +} + +/** + * Verify that an unnamed kill-on-close Job can be created and released now. + * @param api - active binding table. + */ +export function probeCurrentTokenJobSupport(api: CurrentTokenProcessBindings): void { + const job = createKillOnCloseJob(api) + closeHandleChecked(api, job, 'current-token Job capability probe') +} + +/** + * Poll one process handle without blocking the runner event loop. + * @param api - active binding table. + * @param process - caller-owned process handle. + * @returns the direct exit code when signalled, or undefined while running. + */ +export function pollProcessExit(api: Win32ProcessBindings, process: NativePtr): number | undefined { + const waitResult = api.waitForSingleObject(process, 0) + if (waitResult === abi.WAIT_TIMEOUT) return undefined + if (waitResult === 0xFFFFFFFF) throwLastError(api, 'WaitForSingleObject') + const exitCodeSlot = allocUint32() + try { + if (api.getExitCodeProcess(process, exitCodeSlot) === 0) throwLastError(api, 'GetExitCodeProcess') + return decodeUint32(exitCodeSlot) + } finally { + koffi.free(exitCodeSlot) + } +} + +/** + * Return whether a Job has no active processes. + * @param api - active binding table. + * @param job - caller-owned Job handle. + * @returns true once the Job reports zero active processes. + */ +export function isJobEmpty(api: Win32ProcessBindings, job: NativePtr): boolean { + const information = Buffer.alloc(abi.JOBOBJECT_BASIC_ACCOUNTING_SIZE) + if (api.queryInformationJobObject( + job, + abi.JobObjectBasicAccountingInformation, + information, + information.length, + null, + ) === 0) { + throwLastError(api, 'QueryInformationJobObject', 'active process count') + } + return information.readUInt32LE(abi.JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET) === 0 +} + +/** + * Terminate every process in a Job. + * @param api - active binding table. + * @param job - caller-owned Job handle. + * @param exitCode - direct Windows exit code assigned to members. + */ +export function terminateJob(api: Win32ProcessBindings, job: NativePtr, exitCode: number): void { + if (api.terminateJobObject(job, exitCode) === 0) throwLastError(api, 'TerminateJobObject') +} + +/** + * Close a caller-owned handle and report a labelled Win32 failure. + * @param api - active binding table. + * @param handle - handle to close. + * @param detail - lifecycle label for diagnostics. + */ +export function closeHandleChecked(api: Win32ProcessBindings, handle: NativePtr, detail: string): void { + if (api.closeHandle(handle) === 0) throwLastError(api, 'CloseHandle', detail) +} diff --git a/packages/subprocess/win32-process/tests/ordinary-process.spec.ts b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts new file mode 100644 index 0000000000..8b5d1011ef --- /dev/null +++ b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts @@ -0,0 +1,248 @@ +import koffi from 'koffi' +import { describe, expect, it, vi } from 'vitest' +import { + closeHandleChecked, + isJobEmpty, + pollProcessExit, + probeCurrentTokenJobSupport, + spawnCurrentTokenJobProcess, + terminateJob, + Win32Error, +} from '../src/index.ts' +import { + CREATE_SUSPENDED, + CREATE_UNICODE_ENVIRONMENT, + JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET, + JOBOBJECT_BASIC_ACCOUNTING_SIZE, + JobObjectBasicAccountingInformation, + WAIT_TIMEOUT, +} from '../src/abi.ts' +import { PROCESS_INFORMATION, STARTUPINFOW } from '../src/ffi.ts' +import type { + CurrentTokenProcessSpawnOptions, + CurrentTokenProcessBindings, + NativePtr, +} from '../src/index.ts' + +function options( + overrides: Partial = {}, +): CurrentTokenProcessSpawnOptions { + return { + command: 'probe.exe', + applicationName: 'C:\\resolved\\probe.exe', + args: [], + cwd: 'C:\\work', + env: {}, + stdio: { stdin: 4, stdout: 5, stderr: 6 }, + ...overrides, + } +} + +function api(overrides: Partial = {}): CurrentTokenProcessBindings { + return { + createJobObjectW: vi.fn(() => 50n), + setInformationJobObject: vi.fn(() => 1), + queryInformationJobObject: vi.fn((_job: NativePtr, _cls: number, information: Buffer) => { + information.writeUInt32LE(0, JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET) + return 1 + }), + getStdHandle: vi.fn((selector: number) => BigInt(100 - selector)), + uvGetOsfhandle: vi.fn((fileDescriptor: number) => BigInt(100 + fileDescriptor)), + setHandleInformation: vi.fn(() => 1), + createProcessW: vi.fn((_app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => { + koffi.encode(info, PROCESS_INFORMATION, { + hProcess: 60n, + hThread: 61n, + dwProcessId: 1234, + dwThreadId: 5678, + }) + return 1 + }), + assignProcessToJobObject: vi.fn(() => 1), + resumeThread: vi.fn(() => 0), + terminateProcess: vi.fn(() => 1), + terminateJobObject: vi.fn(() => 1), + waitForSingleObject: vi.fn(() => 0), + getExitCodeProcess: vi.fn((_process, slot) => { + koffi.encode(slot, 'uint32', 42) + return 1 + }), + closeHandle: vi.fn(() => 1), + getLastError: vi.fn(() => 5), + formatMessageW: vi.fn(() => 0), + ...overrides, + } as unknown as CurrentTokenProcessBindings +} + +describe('ordinary Job process operations', () => { + it('creates suspended, assigns the Job, and resumes before returning', () => { + const events: string[] = [] + const createProcessW = vi.fn(( + _app: unknown, + _line: unknown, + _pa: unknown, + _ta: unknown, + _inherit: unknown, + _flags: unknown, + _env: unknown, + _cwd: unknown, + _startup: unknown, + info: NativePtr, + ) => { + events.push('create') + koffi.encode(info, PROCESS_INFORMATION, { hProcess: 60n, hThread: 61n, dwProcessId: 1234, dwThreadId: 5678 }) + return 1 + }) + const bindings = api({ + createProcessW, + assignProcessToJobObject: vi.fn(() => { events.push('assign'); return 1 }), + resumeThread: vi.fn(() => { events.push('resume'); return 0 }), + closeHandle: vi.fn((handle: NativePtr) => { events.push(`close:${handle}`); return 1 }), + }) + expect(spawnCurrentTokenJobProcess(bindings, options({ + args: ['literal $VALUE', 'a b'], + env: { + ZED: 'last', + '=C:': 'C:\\work', + alpha: 'first', + ALPHA: 'same-folded-key', + _A: 'underscore', + }, + }))).toEqual({ pid: 1234, process: 60n, job: 50n }) + const environment = createProcessW.mock.calls[0]?.[6] as Buffer + expect(createProcessW).toHaveBeenCalledWith( + 'C:\\resolved\\probe.exe', + 'probe.exe "literal $VALUE" "a b"', + null, + null, + 1, + CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT, + environment, + 'C:\\work', + expect.anything(), + expect.anything(), + ) + expect(environment.toString('utf16le')).toBe( + '=C:=C:\\work\0alpha=first\0ALPHA=same-folded-key\0ZED=last\0_A=underscore\0\0', + ) + expect(events.indexOf('create')).toBeLessThan(events.indexOf('assign')) + expect(events.indexOf('assign')).toBeLessThan(events.indexOf('resume')) + expect(events).toContain('close:61') + }) + + it('reports CreateProcessW failure without replaying another creator', () => { + const bindings = api({ createProcessW: vi.fn(() => 0) }) + let caught: unknown + try { + spawnCurrentTokenJobProcess(bindings, options({ command: 'missing.exe' })) + } catch (error) { + caught = error + } + expect(caught).toMatchObject({ api: 'CreateProcessW', win32Code: 5 }) + }) + + it('resolves the target carrier descriptors and restores their handle flags', () => { + let startup: Record | undefined + const setHandleInformation = vi.fn(() => 1) + const uvGetOsfhandle = vi.fn( + (fileDescriptor: number) => BigInt(100 + fileDescriptor) as NativePtr, + ) + const bindings = api({ + setHandleInformation, + uvGetOsfhandle, + createProcessW: vi.fn((_app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, infoPtr, processInfo) => { + startup = koffi.decode(infoPtr, STARTUPINFOW) as Record + koffi.encode(processInfo, PROCESS_INFORMATION, { + hProcess: 60n, + hThread: 61n, + dwProcessId: 1234, + dwThreadId: 5678, + }) + return 1 + }), + }) + expect(spawnCurrentTokenJobProcess(bindings, options())).toEqual({ pid: 1234, process: 60n, job: 50n }) + expect(startup).toMatchObject({ hStdInput: 104n, hStdOutput: 105n, hStdError: 106n }) + expect(uvGetOsfhandle).toHaveBeenNthCalledWith(1, 4) + expect(uvGetOsfhandle).toHaveBeenNthCalledWith(2, 5) + expect(uvGetOsfhandle).toHaveBeenNthCalledWith(3, 6) + expect(setHandleInformation.mock.calls).toEqual([ + [104n, 1, 1], [105n, 1, 1], [106n, 1, 1], + [104n, 1, 0], [105n, 1, 0], [106n, 1, 0], + ]) + }) + + it('polls direct exit and Job emptiness without blocking', () => { + const queryInformationJobObject = vi.fn((_job: NativePtr, _cls: number, information: Buffer) => { + information.writeUInt32LE(1, JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET) + return 1 + }) + const running = api({ + waitForSingleObject: vi.fn(() => WAIT_TIMEOUT), + queryInformationJobObject, + }) + expect(pollProcessExit(running, 60n as NativePtr)).toBeUndefined() + expect(isJobEmpty(running, 50n as NativePtr)).toBe(false) + expect(queryInformationJobObject).toHaveBeenCalledWith( + 50n, + JobObjectBasicAccountingInformation, + expect.objectContaining({ length: JOBOBJECT_BASIC_ACCOUNTING_SIZE }), + JOBOBJECT_BASIC_ACCOUNTING_SIZE, + null, + ) + + const exited = api() + expect(pollProcessExit(exited, 60n as NativePtr)).toBe(42) + expect(isJobEmpty(exited, 50n as NativePtr)).toBe(true) + }) + + it('reports wait and exit-code query failures', () => { + const processWait = api({ waitForSingleObject: vi.fn(() => 0xFFFFFFFF) }) + expect(() => pollProcessExit(processWait, 60n as NativePtr)).toThrow(Win32Error) + + const exitCode = api({ getExitCodeProcess: vi.fn(() => 0) }) + expect(() => pollProcessExit(exitCode, 60n as NativePtr)).toThrow(Win32Error) + + const jobQuery = api({ queryInformationJobObject: vi.fn(() => 0) }) + expect(() => isJobEmpty(jobQuery, 50n as NativePtr)).toThrow(Win32Error) + }) + + it('checks Job termination and caller-owned handle closure', () => { + const terminateJobObject = vi.fn(() => 1) + const bindings = api({ terminateJobObject }) + expect(() => { terminateJob(bindings, 50n as NativePtr, 1) }).not.toThrow() + expect(() => { closeHandleChecked(bindings, 50n as NativePtr, 'test Job') }).not.toThrow() + expect(terminateJobObject).toHaveBeenCalledWith(50n, 1) + + const failing = api({ terminateJobObject: vi.fn(() => 0) }) + expect(() => { terminateJob(failing, 50n as NativePtr, 1) }).toThrow(Win32Error) + + const closeFailure = api({ closeHandle: vi.fn(() => 0) }) + expect(() => { closeHandleChecked(closeFailure, 50n as NativePtr, 'test Job') }).toThrow(Win32Error) + }) + + it('probes an unnamed Job and closes its handle', () => { + const closeHandle = vi.fn(() => 1) + const bindings = api({ closeHandle }) + expect(() => { probeCurrentTokenJobSupport(bindings) }).not.toThrow() + expect(closeHandle).toHaveBeenCalledExactlyOnceWith(50n) + }) + + it('rejects invalid carrier handles before target creation', () => { + const expectFailure = (invalid: NativePtr | null): void => { + const closeHandle = vi.fn(() => 1) + const createProcessW = vi.fn(() => 1) + expect(() => spawnCurrentTokenJobProcess(api({ + closeHandle, + createProcessW, + uvGetOsfhandle: vi.fn(() => invalid), + }), options())).toThrow('uv_get_osfhandle returned an invalid handle for target stdin fd 4') + expect(closeHandle).toHaveBeenCalledWith(50n) + expect(createProcessW).not.toHaveBeenCalled() + } + + for (const invalid of [null, 0n, 0xffff_ffff_ffff_ffffn, 0xffff_ffff_ffff_fffen]) { + expectFailure(invalid as NativePtr | null) + } + }) +}) diff --git a/packages/subprocess/win32-process/verify/abi-probe.cpp b/packages/subprocess/win32-process/verify/abi-probe.cpp index 1c9480105d..f57d707702 100644 --- a/packages/subprocess/win32-process/verify/abi-probe.cpp +++ b/packages/subprocess/win32-process/verify/abi-probe.cpp @@ -18,9 +18,11 @@ int wmain() P(offsetof(PROCESS_INFORMATION, hThread)); P(offsetof(PROCESS_INFORMATION, dwProcessId)); P(CREATE_SUSPENDED); + P(CREATE_UNICODE_ENVIRONMENT); P(STARTF_USESTDHANDLES); P(HANDLE_FLAG_INHERIT); P(INFINITE); + P(WAIT_TIMEOUT); P(STD_INPUT_HANDLE); P(STD_OUTPUT_HANDLE); P(STD_ERROR_HANDLE); @@ -29,6 +31,9 @@ int wmain() P(ERROR_INSUFFICIENT_BUFFER); P(ERROR_BROKEN_PIPE); P(ERROR_NO_DATA); + P(sizeof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION)); + P(offsetof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION, ActiveProcesses)); + P((int)JobObjectBasicAccountingInformation); P(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION)); P(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags)); P((int)JobObjectExtendedLimitInformation); @@ -36,9 +41,15 @@ int wmain() static_assert(sizeof(STARTUPINFOW) == 104, "STARTUPINFOW size"); static_assert(sizeof(PROCESS_INFORMATION) == 24, "PROCESS_INFORMATION size"); + static_assert(sizeof(HANDLE) == 8, "HANDLE size"); static_assert(CREATE_SUSPENDED == 0x4, "suspended process flag"); + static_assert(CREATE_UNICODE_ENVIRONMENT == 0x400, "Unicode environment flag"); static_assert(STARTF_USESTDHANDLES == 0x100, "std handles flag"); static_assert(HANDLE_FLAG_INHERIT == 0x1, "inherit flag"); + static_assert(WAIT_TIMEOUT == 258, "zero-time wait timeout"); + static_assert(sizeof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION) == 48, "job accounting size"); + static_assert(offsetof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION, ActiveProcesses) == 40, "active process offset"); + static_assert(JobObjectBasicAccountingInformation == 1, "basic accounting class"); static_assert(sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION) == 144, "job extended limit size"); static_assert(offsetof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION, BasicLimitInformation) + offsetof(JOBOBJECT_BASIC_LIMIT_INFORMATION, LimitFlags) == 16, "job LimitFlags offset"); static_assert(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE == 0x2000, "kill on job close flag"); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 12187d2443..ffc488f5c7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9131,6 +9131,9 @@ importers: packages/subprocess/subprocess-local: dependencies: + '@deepseek-ai/dsh-win32-process': + specifier: workspace:^ + version: link:../win32-process koffi: specifier: ^3.1.0 version: 3.1.1 diff --git a/python/sdk-runtime/runtime-bootstrap.mjs b/python/sdk-runtime/runtime-bootstrap.mjs new file mode 100644 index 0000000000..bc2fbede75 --- /dev/null +++ b/python/sdk-runtime/runtime-bootstrap.mjs @@ -0,0 +1,14 @@ +#!/usr/bin/env node +/** Private entry owned by the Python single-file runtime packaging. */ + +const selectorName = 'DSH_SUBPROCESS_RUNNER' +const selection = process.env[selectorName] + +if (selection === undefined) { + const { runCli } = await import('@deepseek-ai/dsh/lib/bin.js') + await runCli() +} else { + Reflect.deleteProperty(process.env, selectorName) + const { runSelectedSubprocessRunner } = await import('@deepseek-ai/dsh-subprocess-local/runner') + await runSelectedSubprocessRunner(selection) +} diff --git a/scripts/build-exe-for-python-sdk.spec.ts b/scripts/build-exe-for-python-sdk.spec.ts index 4933c59810..0fe43528f2 100644 --- a/scripts/build-exe-for-python-sdk.spec.ts +++ b/scripts/build-exe-for-python-sdk.spec.ts @@ -1,5 +1,5 @@ import { spawnSync } from 'node:child_process' -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { dirname, join, resolve } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' @@ -23,6 +23,32 @@ function run(env: NodeJS.ProcessEnv, ...args: string[]) { } describe('Python runtime executable builder CLI', () => { + it('keeps the single-file dispatcher on the Python packaging surface', () => { + const bootstrapPath = resolve(root, 'python/sdk-runtime/runtime-bootstrap.mjs') + const bootstrap = readFileSync(bootstrapPath, 'utf8') + const cliConfig = readFileSync(resolve(root, 'apps/cli/tsdown.config.ts'), 'utf8') + const cliTsconfig = readFileSync(resolve(root, 'apps/cli/tsconfig.json'), 'utf8') + const cliManifest = JSON.parse(readFileSync(resolve(root, 'apps/cli/package.json'), 'utf8')) as { + dependencies?: Record + devDependencies?: Record + } + const runtimeManifest = JSON.parse(readFileSync(resolve(root, 'python/sdk-runtime/package.json'), 'utf8')) as { + dependencies?: Record + } + + expect(existsSync(resolve(root, 'apps/cli/src/runtime-bootstrap.ts'))).toBe(false) + expect(cliConfig).not.toContain('runtime-bootstrap') + expect(cliConfig).toContain("clean: ['lib/*.js']") + expect(cliTsconfig).not.toContain('packages/subprocess/subprocess-local') + expect(cliManifest.dependencies).not.toHaveProperty('@deepseek-ai/dsh-subprocess-local') + expect(cliManifest.devDependencies).toHaveProperty('@deepseek-ai/dsh-subprocess-local') + expect(runtimeManifest.dependencies).toHaveProperty('@deepseek-ai/dsh-subprocess-local') + expect(bootstrap).toContain("import('@deepseek-ai/dsh/lib/bin.js')") + expect(bootstrap).toContain('await runCli()') + expect(bootstrap).toContain("import('@deepseek-ai/dsh-subprocess-local/runner')") + expect(bootstrap).toContain('await runSelectedSubprocessRunner(selection)') + }) + it('runs pnpm through its JavaScript entrypoint without a command shell', () => { const result = run( { npm_execpath: 'C:\\tools\\pnpm.cjs' }, @@ -34,6 +60,8 @@ describe('Python runtime executable builder CLI', () => { expect(result.status).toBe(0) expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs run verify-runtime-closure`) expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs --filter dsh-python-runtime-closure deploy`) + expect(result.stdout).not.toContain(resolve(root, 'python/sdk-runtime/runtime-bootstrap.mjs')) + expect(result.stdout).toContain('"bin":"runtime-bootstrap.mjs"') expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs exec pkg`) expect(result.stdout).not.toMatch(/pnpm\.cmd/i) }) diff --git a/scripts/build-exe-for-python-sdk.ts b/scripts/build-exe-for-python-sdk.ts index c9759418d7..f58a526e64 100644 --- a/scripts/build-exe-for-python-sdk.ts +++ b/scripts/build-exe-for-python-sdk.ts @@ -17,8 +17,8 @@ const root = resolve(import.meta.dirname, '..') /** The closure manifest whose dependencies define the executable. */ const DEPLOY_ROOT_PACKAGE = 'dsh-python-runtime-closure' -/** The sole application launcher inside the deployed closure. */ -const ENTRY_BIN = 'node_modules/@deepseek-ai/dsh/lib/bin.js' +/** The sole executable entry inside the deployed closure. */ +const ENTRY_BIN = 'runtime-bootstrap.mjs' /** Python-visible executable basename. */ const OUTPUT_BASENAME = 'deepseek-harness-sdk-runtime' /** Default Node major; SEA mode requires at least Node 22. */ @@ -406,7 +406,7 @@ class SingleExeBuild { throw new Error(`build-exe-for-python-sdk: ${manifestPath} missing — pnpm deploy did not produce a staged package.`) } if (!existsSync(join(this.staging, ENTRY_BIN))) { - throw new Error(`build-exe-for-python-sdk: ${join(this.staging, ENTRY_BIN)} missing — run without --skip-build so lib/ artifacts exist.`) + throw new Error(`build-exe-for-python-sdk: staged bootstrap ${join(this.staging, ENTRY_BIN)} is missing.`) } const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as Record await writeFile(manifestPath, `${JSON.stringify({ ...manifest, ...patch }, null, 2)}\n`) diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts index 676040300d..227e757d0c 100644 --- a/scripts/check-workspace-constraints.ts +++ b/scripts/check-workspace-constraints.ts @@ -164,11 +164,17 @@ const packageFileExtras: Readonly> = { // also shares its generated FFI code through a hashed runtime chunk. '@deepseek-ai/dsh-sandbox-windows-acl': ['lib/runner.js', 'lib/types-*.js'], '@deepseek-ai/dsh-skill-badge': ['assets'], + // Ordinary native containment ships a path-loaded runner and its shared + // runner chunk beside the existing node-pty permission repair. + '@deepseek-ai/dsh-subprocess-local': [ + 'lib/runner.js', + 'lib/runner-*.js', + 'scripts/ensure-spawn-helper.mjs', + ], // tsdown shares the repository/pack code between the lib entry and the bin // through a hashed chunk. The committed bin.js is the link target pnpm can // resolve at install time, before the build produces lib/bin.js. '@deepseek-ai/dsh-experimental-webworker-packer': ['bin.js', 'lib/repository-*.js'], - '@deepseek-ai/dsh-subprocess-local': ['scripts/ensure-spawn-helper.mjs'], } function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean { diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts index 7712416f7c..120a976863 100644 --- a/scripts/run-gates.spec.ts +++ b/scripts/run-gates.spec.ts @@ -548,6 +548,7 @@ describe('Node 24 lane ownership', () => { }) expect(subject.find(item => item.id === 'built-bin-smoke')?.args).toEqual( expect.arrayContaining([ + 'packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts', 'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts', 'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts', 'packages/experimental/agent-team/tests/built-lib.e2e.ts', diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 47701d8048..53a01d604e 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -782,6 +782,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate { 'apps/cli/tests/built-bin.e2e.ts', 'packages/host/directory-picker-native/tests/built-worker.e2e.ts', 'packages/sdk/server/tests/built-scope-carrier.e2e.ts', + 'packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts', 'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts', 'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts', 'packages/api/remotes/tests/built-lib.e2e.ts', diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index ee456875bc..fcbd55a995 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -769,7 +769,7 @@ def main() -> None: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--scenario", - choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-live", "direct"), + choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-live", "runner", "direct"), default="all", ) parser.add_argument("--exe", type=Path) @@ -788,13 +788,20 @@ def main() -> None: parser.error("--scenario sdk-profile-plugin requires --installed-wheel") if args.installed_wheel: args.exe = assert_installed_wheel_environment() - if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "direct"} and args.exe is None: - parser.error("--exe is required for custom, minimal, snapshot, and direct scenarios") + if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "runner", "direct"} and args.exe is None: + parser.error("--exe is required for custom, minimal, fs-search, spawn-node, snapshot, restart, runner, and direct scenarios") if args.update_snapshots and args.scenario not in {"all", "sdk-minimal", "sdk-snapshot", "sdk-restart"}: parser.error("--update-snapshots requires --scenario sdk-minimal, sdk-snapshot, sdk-restart, or all") if args.exe is not None and not args.exe.is_file(): parser.error(f"runtime executable does not exist: {args.exe}") + if args.scenario in {"all", "runner"}: + assert args.exe is not None + smoke_packaged_runner(args.exe.resolve()) + if args.scenario == "runner": + print("smoke-python-runtime: runner passed") + return + if args.scenario == "sdk-live": smoke_sdk_live() print("smoke-python-runtime: sdk-live passed") @@ -1435,6 +1442,104 @@ def smoke_direct(base_url: str, executable: Path) -> None: assert_session_log(sessions, root, EXPECTED_TEXT) +def smoke_packaged_runner(executable: Path) -> None: + """Exercise the private subprocess runner through the single-file entry.""" + with tempfile.TemporaryDirectory(prefix="dsh-packaged-runner-") as temporary: + root = Path(temporary).resolve() + target_script = ( + "import os,sys; " + "ok = (os.getcwd() == os.environ['PACKAGED_RUNNER_EXPECTED_CWD'] " + "and os.environ.get('DSH_SUBPROCESS_RUNNER') == 'target-collision-restored'); " + "sys.exit(7 if ok else 9)" + ) + if not IS_WINDOWS: + request_path = root / "launch-request.json" + target_env = dict(os.environ) + target_env["DSH_SUBPROCESS_RUNNER"] = "target-collision-restored" + target_env["PACKAGED_RUNNER_EXPECTED_CWD"] = str(root) + request_path.write_text( + json.dumps({"cwd": str(root), "env": target_env}), + encoding="utf-8", + ) + request_path.chmod(0o600) + environment = dict(os.environ) + environment["DSH_SUBPROCESS_RUNNER"] = str(request_path) + result = subprocess.run( + [str(executable), "--", sys.executable, "-c", target_script], + cwd=root, + env=environment, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + if result.returncode != 7 or request_path.exists() or (root / "startup-error.json").exists(): + raise AssertionError( + "packaged POSIX runner failed: " + f"exit={result.returncode}; stdout={result.stdout!r}; stderr={result.stderr!r}" + ) + return + + node = shutil.which("node") + if node is None: + raise AssertionError("packaged Windows runner smoke requires node on PATH") + helper = root / "windows-runner-smoke.mjs" + helper.write_text( + """import { spawn } from 'node:child_process' +const [runtime, target, cwd, targetScript] = process.argv.slice(2) +const child = spawn(runtime, ['--', target, '-c', targetScript], { + cwd, + env: { ...process.env, DSH_SUBPROCESS_RUNNER: 'windows' }, + stdio: ['ignore', 'ignore', 'ignore', 'ipc', 'pipe', 'pipe', 'pipe'], +}) +const messages = [] +let stdout = '' +let stderr = '' +child.stdio[4].destroy() +child.stdio[5].on('data', chunk => { stdout += chunk.toString() }) +child.stdio[6].on('data', chunk => { stderr += chunk.toString() }) +child.on('message', message => { messages.push(message) }) +const result = await new Promise((resolve, reject) => { + child.once('error', reject) + child.once('spawn', () => { + child.send({ + type: 'start', + cwd, + env: { + ...process.env, + DSH_SUBPROCESS_RUNNER: 'target-collision-restored', + PACKAGED_RUNNER_EXPECTED_CWD: cwd, + }, + }, error => { if (error) reject(error) }) + }) + child.once('close', (exitCode, signal) => { resolve({ exitCode, signal }) }) +}) +process.stdout.write(JSON.stringify({ ...result, messages, stdout, stderr })) +""", + encoding="utf-8", + ) + helper_result = subprocess.run( + [node, str(helper), str(executable), sys.executable, str(root), target_script], + cwd=root, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + if helper_result.returncode != 0: + raise AssertionError(f"packaged Windows runner helper failed: {helper_result.stderr}") + observed = json.loads(helper_result.stdout) + expected = { + "exitCode": 0, + "signal": None, + "messages": [{"type": "target-exit", "exitCode": 7}], + "stdout": "", + "stderr": "", + } + if observed != expected: + raise AssertionError(f"packaged Windows runner returned unexpected facts: {observed}") + + def is_idle_notification(message: dict[str, object]) -> bool: """Return whether a JSON-RPC notification marks a session idle.""" params = message.get("params") diff --git a/scripts/verify-application-entrypoints.spec.ts b/scripts/verify-application-entrypoints.spec.ts index a03240eb1c..0c84043dfc 100644 --- a/scripts/verify-application-entrypoints.spec.ts +++ b/scripts/verify-application-entrypoints.spec.ts @@ -74,6 +74,15 @@ describe('application entrypoints', () => { ]) }) + it('rejects a packaging dispatcher owned by the CLI workspace', () => { + const root = fixture() + write(root, 'apps/cli/src/runtime-bootstrap.ts', '#!/usr/bin/env node\n') + + expect(applicationEntrypointViolations(root)).toEqual([ + 'apps/cli/src/runtime-bootstrap.ts: executable source has no application/build/test classification', + ]) + }) + it('rejects a private Python application carrier outside dsh', () => { const root = fixture() write(root, 'packages/sdk/rogue-python-runtime/package.json', JSON.stringify({ private: true })) diff --git a/scripts/verify-application-entrypoints.ts b/scripts/verify-application-entrypoints.ts index d80deb1dce..1ec5342b4b 100644 --- a/scripts/verify-application-entrypoints.ts +++ b/scripts/verify-application-entrypoints.ts @@ -29,7 +29,7 @@ const MANIFEST_BIN_ALLOWLIST = new Map([ ['packages/experimental/webworker-packer/package.json', { 'dsh-pack-vfs-image': './bin.js' }], ]) -/** Every executable in a Node application workspace has one explicit role. */ +/** Every JavaScript executable in an application or packaging workspace has one explicit role. */ const EXECUTABLE_SOURCE_ALLOWLIST = new Map([ ['apps/cli/src/bin.ts', 'supported dsh application launcher'], ['packages/context/time-context/tests/fixtures/driver.ts', 'test-only subprocess driver'], @@ -44,6 +44,7 @@ const EXECUTABLE_SOURCE_ALLOWLIST = new Map([ ['packages/subagent/subagent-dsh-sdk/tests/fixtures/loader/driver.ts', 'test-only subprocess driver'], ['packages/test-support/loader-smoke/tests/fixtures/headless-driver.ts', 'test-only subprocess driver'], ['packages/test-support/llm-mock-server/src/bin.ts', 'test-only model server'], + ['python/sdk-runtime/runtime-bootstrap.mjs', 'private packaging-only runtime dispatcher'], ]) /** Root demos are application wrappers and therefore must visibly select dsh. */ @@ -65,6 +66,7 @@ const SOURCE_PATTERNS = [ 'packages/**/*.js', 'packages/**/*.mjs', 'packages/**/*.cjs', + 'python/sdk-runtime/*.mjs', ] const SOURCE_EXCLUDES = [ diff --git a/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl b/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl index d29ea26a77..36188dda08 100644 --- a/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl +++ b/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl @@ -2,20 +2,25 @@ {"type":"permission/preset","data":{"preset":"danger-full-access"}} {"type":"sandbox/mode","data":{"mode":"danger-full-access"}} {"type":"approval/policy","data":{"policy":"never"}} -{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Inspect the exact tools service API and tools/pre-execute event with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Inspect the exact tools service API, tools/pre-execute event, and subprocess service API with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} {"type":"turn/start","data":{"turn":1}} {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":1}} -{"type":"user/message","data":{"content":[{"type":"text","text":"Inspect the exact tools service API and tools/pre-execute event with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Inspect the exact tools service API, tools/pre-execute event, and subprocess service API with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"} {"type":"session/title","data":{"title":"Inspect the exact tools service","messageSeqs":[7],"source":{"kind":"fallback"}}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788233487763,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788233487763,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":1788233487763,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":1788233487763,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788233487763,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}} {"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProvenance\",\n \"declaration\": \"export interface AssistantProvenance {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"declaration\": \"export interface JsonSchemaNode {\\n type?: JsonSchemaType;\\n oneOf?: JsonSchemaNode[];\\n properties?: Record;\\n required?: string[];\\n additionalProperties?: boolean;\\n items?: JsonSchemaNode;\\n enum?: JsonSchemaScalar[];\\n const?: JsonSchemaScalar;\\n description?: string;\\n title?: string;\\n default?: JsonValue;\\n examples?: JsonValue;\\n}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProvenance {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[13],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} {"type":"step/start","data":{"turn":1,"step":2}} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788233487803,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788233487803,"index":0,"dt":[],"texts":["CORDIS_INSPECT_JSDOC_OK"]},{"type":"chunk","time":1788233487803,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}},{"type":"chunk","time":1788233487803,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788233487803,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-subprocess-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":2,"callId":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}} +{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-subprocess-api"},"content":[{"type":"tool-result","toolCallId":"inspect-subprocess-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"subprocess\",\n \"description\": \"Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\\n\\nImplementations must honor these semantics:\\n\\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\\n- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures.\\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\\n- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.\\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"subprocess\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"subprocess\"\n ],\n \"expression\": \"ctx.subprocess\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise\",\n \"description\": \"Resolve one configured executable in this provider's execution world. Absolute paths are verified; bare names use the provider's scrubbed PATH plus explicit environment overrides. Relative paths containing separators are rejected: the resolution base is undefined, so providers fail loud instead of guessing.\",\n \"parameters\": [\n {\n \"name\": \"command\",\n \"description\": \"absolute executable path or bare PATH name.\"\n },\n {\n \"name\": \"env\",\n \"description\": \"explicit environment entries used for lookup.\"\n },\n {\n \"name\": \"signal\",\n \"description\": \"aborts remote or local lookup.\"\n }\n ],\n \"returns\": \"a canonical executable path.\"\n },\n {\n \"signature\": \"abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle\",\n \"description\": \"Start one managed child process from a fully-specified spec; this seam applies no defaults.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"argv, directory, stdio dispositions, grace, cancellation, and environment.\"\n }\n ],\n \"returns\": \"the live process handle (streams/readers, signalling, outcome promise).\",\n \"throws\": [\n \"synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation.\"\n ]\n },\n {\n \"signature\": \"abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise\",\n \"description\": \"Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and whole-session quiescence.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\"\n }\n ],\n \"returns\": \"the live terminal handle after allocation succeeds.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"SubprocessCollect\",\n \"declaration\": \"export interface SubprocessCollect {\\n maxBytes: number;\\n spill?: {\\n maxBytes: number;\\n };\\n}\"\n },\n {\n \"name\": \"SubprocessCollectedOutputs\",\n \"declaration\": \"export interface SubprocessCollectedOutputs {\\n readonly stdout?: SubprocessOutputReader;\\n readonly stderr?: SubprocessOutputReader;\\n}\"\n },\n {\n \"name\": \"SubprocessHandle\",\n \"declaration\": \"export interface SubprocessHandle {\\n readonly stdin: Writable | undefined;\\n readonly stdout: Readable | undefined;\\n readonly stderr: Readable | undefined;\\n readonly collected: SubprocessCollectedOutputs;\\n readonly done: Promise;\\n terminate(): void;\\n waitForExit(signal?: AbortSignal): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessOutcome\",\n \"declaration\": \"export interface SubprocessOutcome {\\n exitCode: number | null;\\n signal: NodeJS.Signals | null;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputMode\",\n \"declaration\": \"export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;\"\n },\n {\n \"name\": \"SubprocessOutputRead\",\n \"declaration\": \"export interface SubprocessOutputRead {\\n text: string;\\n nextOffset: number;\\n lossy: boolean;\\n spillPath?: string;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputReader\",\n \"declaration\": \"export interface SubprocessOutputReader {\\n readFrom(fromByte: number): SubprocessOutputRead;\\n}\"\n },\n {\n \"name\": \"SubprocessSpawnSpec\",\n \"declaration\": \"export interface SubprocessSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n stdio: SubprocessStdio;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n env?: NodeJS.ProcessEnv | undefined;\\n}\"\n },\n {\n \"name\": \"SubprocessStdinMode\",\n \"declaration\": \"export type SubprocessStdinMode = 'ignore' | 'pipe' | {\\n readonly data: string;\\n};\"\n },\n {\n \"name\": \"SubprocessStdio\",\n \"declaration\": \"export interface SubprocessStdio {\\n stdin: SubprocessStdinMode;\\n stdout: SubprocessOutputMode;\\n stderr: SubprocessOutputMode;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalForeground\",\n \"declaration\": \"export interface SubprocessTerminalForeground {\\n processGroupId: number;\\n inputWaiting: boolean;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalHandle\",\n \"declaration\": \"export interface SubprocessTerminalHandle {\\n readonly pid: number;\\n readonly output: Readable;\\n readonly done: Promise;\\n write(data: string): Promise;\\n inspectForeground(): Promise;\\n signalForeground(signal: SubprocessTerminalSignal): Promise;\\n terminate(): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalSignal\",\n \"declaration\": \"export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';\"\n },\n {\n \"name\": \"SubprocessTerminalSpawnSpec\",\n \"declaration\": \"export interface SubprocessTerminalSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n env?: Record | undefined;\\n rows: number;\\n cols: number;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[18],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} +{"type":"step/start","data":{"turn":1,"step":3}} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["CORDIS_INSPECT_JSDOC_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":3}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl b/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl index a418ba6d08..f7a2d4d06b 100644 --- a/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl +++ b/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl @@ -2,20 +2,25 @@ {"type":"permission/preset","data":{"preset":"danger-full-access"}} {"type":"sandbox/mode","data":{"mode":"danger-full-access"}} {"type":"approval/policy","data":{"policy":"never"}} -{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Inspect the exact tools service API and tools/pre-execute event with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Inspect the exact tools service API, tools/pre-execute event, and subprocess service API with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} {"type":"turn/start","data":{"turn":1}} {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":1}} -{"type":"user/message","data":{"content":[{"type":"text","text":"Inspect the exact tools service API and tools/pre-execute event with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Inspect the exact tools service API, tools/pre-execute event, and subprocess service API with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"} {"type":"session/title","data":{"title":"Inspect the exact tools service","messageSeqs":[7],"source":{"kind":"fallback"}}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788233487763,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788233487763,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":1788233487763,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":1788233487763,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788233487763,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}} {"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProvenance\",\n \"declaration\": \"export interface AssistantProvenance {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"declaration\": \"export interface JsonSchemaNode {\\n type?: JsonSchemaType;\\n oneOf?: JsonSchemaNode[];\\n properties?: Record;\\n required?: string[];\\n additionalProperties?: boolean;\\n items?: JsonSchemaNode;\\n enum?: JsonSchemaScalar[];\\n const?: JsonSchemaScalar;\\n description?: string;\\n title?: string;\\n default?: JsonValue;\\n examples?: JsonValue;\\n}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProvenance {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[13],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} {"type":"step/start","data":{"turn":1,"step":2}} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788233487803,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788233487803,"index":0,"dt":[],"texts":["CORDIS_INSPECT_JSDOC_OK"]},{"type":"chunk","time":1788233487803,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}},{"type":"chunk","time":1788233487803,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788233487803,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-subprocess-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":2,"callId":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}} +{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-subprocess-api"},"content":[{"type":"tool-result","toolCallId":"inspect-subprocess-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"subprocess\",\n \"description\": \"Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\\n\\nImplementations must honor these semantics:\\n\\n- Executable paths belong to one execution world shared with the mounted filesystem provider.\\n- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures.\\n- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.\\n- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.\\n- Disposal of the service terminates all still-running managed processes and awaits their exit.\\n- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"subprocess\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"subprocess\"\n ],\n \"expression\": \"ctx.subprocess\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"abstract resolveExecutable( command: string, env?: Readonly>, signal?: AbortSignal, ): Promise\",\n \"description\": \"Resolve one configured executable in this provider's execution world. Absolute paths are verified; bare names use the provider's scrubbed PATH plus explicit environment overrides. Relative paths containing separators are rejected: the resolution base is undefined, so providers fail loud instead of guessing.\",\n \"parameters\": [\n {\n \"name\": \"command\",\n \"description\": \"absolute executable path or bare PATH name.\"\n },\n {\n \"name\": \"env\",\n \"description\": \"explicit environment entries used for lookup.\"\n },\n {\n \"name\": \"signal\",\n \"description\": \"aborts remote or local lookup.\"\n }\n ],\n \"returns\": \"a canonical executable path.\"\n },\n {\n \"signature\": \"abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle\",\n \"description\": \"Start one managed child process from a fully-specified spec; this seam applies no defaults.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"argv, directory, stdio dispositions, grace, cancellation, and environment.\"\n }\n ],\n \"returns\": \"the live process handle (streams/readers, signalling, outcome promise).\",\n \"throws\": [\n \"synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation.\"\n ]\n },\n {\n \"signature\": \"abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise\",\n \"description\": \"Allocate a real terminal and start one owned process session. This is the only non-pipe process primitive: implementations own terminal byte I/O, foreground groups, signals, and whole-session quiescence.\",\n \"parameters\": [\n {\n \"name\": \"spec\",\n \"description\": \"fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\"\n }\n ],\n \"returns\": \"the live terminal handle after allocation succeeds.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"SubprocessCollect\",\n \"declaration\": \"export interface SubprocessCollect {\\n maxBytes: number;\\n spill?: {\\n maxBytes: number;\\n };\\n}\"\n },\n {\n \"name\": \"SubprocessCollectedOutputs\",\n \"declaration\": \"export interface SubprocessCollectedOutputs {\\n readonly stdout?: SubprocessOutputReader;\\n readonly stderr?: SubprocessOutputReader;\\n}\"\n },\n {\n \"name\": \"SubprocessHandle\",\n \"declaration\": \"export interface SubprocessHandle {\\n readonly stdin: Writable | undefined;\\n readonly stdout: Readable | undefined;\\n readonly stderr: Readable | undefined;\\n readonly collected: SubprocessCollectedOutputs;\\n readonly done: Promise;\\n terminate(): void;\\n waitForExit(signal?: AbortSignal): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessOutcome\",\n \"declaration\": \"export interface SubprocessOutcome {\\n exitCode: number | null;\\n signal: NodeJS.Signals | null;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputMode\",\n \"declaration\": \"export type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;\"\n },\n {\n \"name\": \"SubprocessOutputRead\",\n \"declaration\": \"export interface SubprocessOutputRead {\\n text: string;\\n nextOffset: number;\\n lossy: boolean;\\n spillPath?: string;\\n}\"\n },\n {\n \"name\": \"SubprocessOutputReader\",\n \"declaration\": \"export interface SubprocessOutputReader {\\n readFrom(fromByte: number): SubprocessOutputRead;\\n}\"\n },\n {\n \"name\": \"SubprocessSpawnSpec\",\n \"declaration\": \"export interface SubprocessSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n stdio: SubprocessStdio;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n env?: NodeJS.ProcessEnv | undefined;\\n}\"\n },\n {\n \"name\": \"SubprocessStdinMode\",\n \"declaration\": \"export type SubprocessStdinMode = 'ignore' | 'pipe' | {\\n readonly data: string;\\n};\"\n },\n {\n \"name\": \"SubprocessStdio\",\n \"declaration\": \"export interface SubprocessStdio {\\n stdin: SubprocessStdinMode;\\n stdout: SubprocessOutputMode;\\n stderr: SubprocessOutputMode;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalForeground\",\n \"declaration\": \"export interface SubprocessTerminalForeground {\\n processGroupId: number;\\n inputWaiting: boolean;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalHandle\",\n \"declaration\": \"export interface SubprocessTerminalHandle {\\n readonly pid: number;\\n readonly output: Readable;\\n readonly done: Promise;\\n write(data: string): Promise;\\n inspectForeground(): Promise;\\n signalForeground(signal: SubprocessTerminalSignal): Promise;\\n terminate(): Promise;\\n}\"\n },\n {\n \"name\": \"SubprocessTerminalSignal\",\n \"declaration\": \"export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';\"\n },\n {\n \"name\": \"SubprocessTerminalSpawnSpec\",\n \"declaration\": \"export interface SubprocessTerminalSpawnSpec {\\n argv: readonly string[];\\n cwd: string;\\n env?: Record | undefined;\\n rows: number;\\n cols: number;\\n graceMs: number;\\n signal?: AbortSignal | undefined;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[18],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} +{"type":"step/start","data":{"turn":1,"step":3}} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["CORDIS_INSPECT_JSDOC_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":3}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}