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-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml index 04eec8e0e1..6209091467 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md -2026-06-30-bash-stdin-env-trusted-plugin-api.md: 41be63fff598587ee9b873cf7edf51da788bc02a -2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md: 60721539d9d37857e145e289bb262482588139bf +2026-06-30-bash-stdin-env-trusted-plugin-api.md: 05501e0f0a5ff38df1e5e719574cd8bdada4f4d1 +2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md: 99ca2b9dddd710d9c79fc6e0ad726f68aca994ac diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md index 41be63fff5..05501e0f0a 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md @@ -6,7 +6,7 @@ English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md) ## Problem -The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.shell` capability seam ([dsh-shell](../../../../packages/shell/shell) → [dsh-bash-local](../../../../packages/shell/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This change adds those two inputs. +The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.shell` capability seam ([dsh-shell](../../../../packages/shell/shell) → [dsh-bash-local](../../../../packages/shell/bash-local)), with [provider-managed range termination](2026-08-28-subprocess-native-containment.md), output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This change adds those two inputs. `stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these Service Definition fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule. @@ -30,4 +30,4 @@ Three deliberate choices: ## Consequences -Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model-facing behavior remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/shell.md). +Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its managed-range termination, truncation, and spill behavior. The model-facing behavior remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/shell.md). diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md index 60721539d9..99ca2b9ddd 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md @@ -6,7 +6,7 @@ Status: implemented ## 问题 -钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令:钩子是一条 shell 命令,通过 **stdin 上的 JSON** 接收事件载荷,并从若干**环境变量**(`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……)读取上下文。harness 已经在 `ctx.shell` 能力 seam 后面有一个完善的命令执行器([dsh-shell](../../../../packages/shell/shell) → [dsh-bash-local](../../../../packages/shell/bash-local)),具备进程组终止、输出截断/spill 处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程底层机制——但该 seam 此前无法写入 stdin 或设置额外 env。本次变更添加这两个输入。 +钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令:钩子是一条 shell 命令,通过 **stdin 上的 JSON** 接收事件载荷,并从若干**环境变量**(`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……)读取上下文。harness 已经在 `ctx.shell` 能力 seam 后面有一个完善的命令执行器([dsh-shell](../../../../packages/shell/shell) → [dsh-bash-local](../../../../packages/shell/bash-local)),具备[由提供方管理的范围终止](2026-08-28-subprocess-native-containment.zh.md)、输出截断/spill 处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程底层机制——但该 seam 此前无法写入 stdin 或设置额外 env。本次变更添加这两个输入。 `stdin` 和 `env` 不构成新的模型能力,因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护,而非靠隐藏这些 Service Definition 字段;模型工具参数是静态 JSON,不会展开 shell 变量。因此这些字段服务于受信的进程内调用方(如钩子桥接层),它们需要传递结构化输入和 `CLAUDE_*` 变量,而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.zh.md)。 @@ -30,4 +30,4 @@ Status: implemented ## 后果 -钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量,保留其进程组终止、截断和 spill 行为。面向模型的行为不变,bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/subsystems/shell.zh.md)。 +钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量,保留其受管范围终止、截断和 spill 行为。面向模型的行为不变,bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/subsystems/shell.zh.md)。 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 66dd29f3a4..5e782d97b1 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: 95adc41bffff6d7711685ebc52cb73b2b455df41 -2026-07-06-timeout-deadline-library.zh.md: 8b7b18a2d1e7757102afc81bea03245de2707d86 +2026-07-06-timeout-deadline-library.md: f87036ff344cc8af2e0f0b90fabb962b6d45e2c0 +2026-07-06-timeout-deadline-library.zh.md: 2744b4897e76058fb252d45cd5f89c4e344b5b92 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 95adc41bff..f87036ff34 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 8b7b18a2d1..2744b4897e 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 83638635ad..3146f667bf 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: c152345772826ec4e2dbfd238726c429418c7897 -2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ea5e457afd761cb5071f8b584ef10fa7ffaa8210 +2026-07-10-single-file-executable-sdk-runtime-distribution.md: 847e174b87b3e37f2c818dfb00bf51648812deeb +2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 9f9c5b5a6f20e707e6a40cba1ced0ddd6c44fa97 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 c152345772..847e174b87 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 @@ -42,7 +42,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/` → 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/runtime-bootstrap.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. The packaging-owned bootstrap imports the public CLI 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) is called for all four targets by the [installed-wheel Python runtime pull-request validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) and the [public publication workflow](../process/2026-08-11-python-publication-workflow.md); `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / 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 additionally run a real DeepSeek two-turn tool smoke on every target; 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 verifies that the executable's deployment target fits the wheel tag. A full four-target run retains five artifacts, each containing one release file: the platform-independent SDK wheel and four 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 four native runtime wheels, then a single serialized job checks and publishes all five to the project PyPI registry. The [Windows x64 runtime decision](2026-08-23-python-sdk-windows-x64-runtime.md) owns the fourth 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 ea5e457afd..9f9c5b5a6f 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 @@ -42,7 +42,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/` → 恢复 legacy deploy 遗漏的直接工作区包,并拒绝剩余的 manifest 缺口 → 将暂存依赖中的符号链接替换为目标文件内容,删除包管理器的 `.bin` 链接,并在仍有任何符号链接时失败 → 注入 pkg 配置,其中 bin 为 `node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js`,assets 覆盖动态读取的 profile、bundle、前端、preset、原生库与配置文件 → 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 将 `deepseek-harness-sdk-runtime--` 写入 `dist-exe/` 并拷回运行时目录。由打包层拥有的 bootstrap 在普通启动时导入公开 CLI,而提供方私有选择会分派到同一个 `@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 Python 运行时拉取请求验证](../testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md)与[公开发布工作流](../process/2026-08-11-python-publication-workflow.zh.md)都会调用它构建全部四个目标;`workflow_dispatch` 仍可选择部分目标。linux-x64、linux-arm64(`ubuntu-24.04-arm`)、macos-arm64 与 win-x64(`windows-2025`)分别进行原生构建,并在适用平台缓存 `~/.pkg-cache`;macOS 的 ad-hoc 签名由 pkg 处理。每个平台都把发布形态的 SDK wheel 包与运行时 wheel 包安装到 checkout 外的干净 venv,证明包与可执行文件来源,再通过公开 SDK 与直接 NDJSON JSON-RPC 运行完整 keyless 场景。可信拉取请求还会在每个目标上运行真实 DeepSeek 双轮工具冒烟测试;fork 与 Dependabot head 不会获得密钥。Linux 会检查可执行文件和原生 addon 各自的 GLIBC 依赖,并额外运行 manylinux 2.28 冒烟测试;macOS 则验证可执行文件的部署目标符合 wheel 包标签。完整构建四个目标时保留 5 个产物,每个产物只含一个发布文件:平台无关的 SDK wheel 包与 4 个原生运行时 wheel 包;手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-v` 标签流水线,构建一个 SDK wheel 包和 4 个原生运行时 wheel 包,再由单个串行任务校验并将这 5 个文件发布到项目的 PyPI 注册表。[Windows x64 运行时决策](2026-08-23-python-sdk-windows-x64-runtime.zh.md)负责第四个目标及对 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 fcca895513..6da06a71ac 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: 86faad9929d3eb5b00e66bb1c46a2e35b135d954 -2026-07-16-explicit-turn-cancellation.zh.md: acf56e0629668a227324045ffd0521619dc45f33 +2026-07-16-explicit-turn-cancellation.md: 2d611d4f67b911fddea1e374f604277217dd7d54 +2026-07-16-explicit-turn-cancellation.zh.md: a87c45a2fbdc1e654665486fd340d034d70a9b98 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 86faad9929..2d611d4f67 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](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](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 acf56e0629..a87c45a2fb 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 事件](2026-08-06-agent-event-payload-objects.zh.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 事件](2026-08-06-agent-event-payload-objects.zh.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 48ceb0a573..6d05137fba 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: feac31b3eafced8158a8d79a0e5967a8de5e2f87 -2026-08-22-single-dsh-application-launcher.zh.md: 88fe4ef4d4e0436ecb450e3f5319be7acee6882b +2026-08-22-single-dsh-application-launcher.md: 352b6076191b03493f75df469b7f7fd8e3df098a +2026-08-22-single-dsh-application-launcher.zh.md: ae3b8c1984f973560a083bc046d868058db8d9ef 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 feac31b3ea..352b607619 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 packages `node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js` through the private `dsh-python-runtime-closure` deploy manifest. Its ordinary branch imports the public CLI; 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. The [Python profile-runtime decision](2026-08-23-python-sdk-dsh-profile-runtime.md) owns this launch, and the [Windows x64 runtime decision](2026-08-23-python-sdk-windows-x64-runtime.md) owns the fourth 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 88fe4ef4d4..ae3b8c1984 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 通过私有 `dsh-python-runtime-closure` 部署 manifest 打包 `node_modules/@deepseek-ai/dsh/lib/runtime-bootstrap.js`。其普通分支导入公开 CLI;提供方私有选择会在 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 启动别名。[Python profile 运行时决策](2026-08-23-python-sdk-dsh-profile-runtime.zh.md)负责该启动方式,[Windows x64 运行时决策](2026-08-23-python-sdk-windows-x64-runtime.zh.md)负责第四个载体。 diff --git a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.i18n.yaml index 138ca27a49..94b9f8d54c 100644 --- a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.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-27-process-table-snapshots.md -2026-08-27-process-table-snapshots.md: 27c364607ca1e03a926c309f26007477a8785636 -2026-08-27-process-table-snapshots.zh.md: 9c5fe65bb83a0d04fe5639b3ffefcf377c3588ef +2026-08-27-process-table-snapshots.md: 9b702fb16bad531fdc3d0ba46f436844afc8184b +2026-08-27-process-table-snapshots.zh.md: 1d63aca3f5bd123311c9eccc4d24d2f067bc3485 diff --git a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.md b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.md index 27c364607c..9b702fb16b 100644 --- a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.md +++ b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.md @@ -22,18 +22,20 @@ Measured by driving the production `MacProcessInspector` against a real process Any command spawning two or more children — a pipeline, `make`, `pnpm`, `git` — saturates the host event loop until it exits. -Teardown has the same structure. `signalProcess` fences each signal against PID reuse by asking liveness itself, so signalling N members costs N table reads. +Fallback terminal teardown has the same structure. `signalProcess` fences each signal against PID reuse by asking liveness itself, so signalling N observed members costs N table reads. ## Decision `ProcessInspector.snapshot()` returns a `ProcessSnapshot`, one observation of the process table that answers `tree(rootPid)`, `session(sessionId)`, and `alive(identity)`. It replaces the three per-question methods; the inspector's remaining surface is `foregroundPgid`, `isStdinWaiting`, `signalGroup`, and `signalProcess`. -Each caller captures one snapshot and answers every question of a single pass from it. `LocalTerminalHandle.descendants()` takes a snapshot, reads the tree and session from it, and filters survivors through the same `alive`, so a readiness poll costs one table read regardless of descendant count. `waitForMembers` captures a fresh snapshot per polling iteration, because its whole purpose is observing change. +Each caller captures one snapshot and answers every question of a single pass from it. `LocalTerminalHandle.descendants()` takes a snapshot, reads the tree and session from it, and filters survivors through the same `alive`, so a readiness poll costs one table read regardless of descendant count. Fallback `waitForMembers` captures a fresh snapshot per polling iteration, because its whole purpose is observing change. Signalling does not share that observation. `ProcessInspector.isAlive(identity)` answers current state from the narrowest per-identity source a platform offers — one `/proc//stat` read on Linux, one `ps` table on macOS, one process-handle check on Windows — and `signalProcess` takes that fence immediately before delivering the signal. An observation cannot stand in for it: the observation preserves the original PID-to-start-time pairing, so a recycled PID would still match it and take a signal meant for the process that exited. Reading the fence per target also keeps a failed read costing one target instead of the rest of a teardown round, which is what the [synchronous exit-cleanup contract](../bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md) requires. `signalMembers` and `waitForMembers` return before capturing anything when a round has no members, so a command that spawned no descendants pays no table read for its teardown sweeps. +Supported Linux terminal teardown bypasses those observational sweeps after binding a user-systemd scope and waits on manager-owned membership instead. Process-table snapshots remain authoritative for foreground/readiness inspection and for fallback or synchronous host-exit cleanup. The [native-containment decision](2026-08-28-subprocess-native-containment.md) owns that split. + Platform differences live in how a snapshot is built, not in what it promises: - **macOS** builds it from one `ps` table. That table exposes neither a session id nor a state column, so `session` is empty and `alive` reports presence with a matching start identity. @@ -62,7 +64,7 @@ Platform differences live in how a snapshot is built, not in what it promises: A readiness poll's process-table cost is now constant in descendant count. On macOS one poll performs one full table read plus the small `tpgid` read, which is the 0-descendant cost in the table above for every descendant count. -Teardown keeps its previous per-signal cost: one narrow liveness read per target, which on macOS is one `ps` fork per member. That cost was never the measured problem — a terminal tears down once, while its readiness path polls up to 600 times — so the fix deliberately spends it to keep the fence reading current state. +Fallback and synchronous host-exit teardown keep the previous per-signal cost: one narrow liveness read per target, which on macOS is one `ps` fork per member. That cost was never the measured problem — a terminal tears down once, while its readiness path polls up to 600 times — so the fix deliberately spends it to keep the fence reading current state. Supported Linux normal teardown uses scope membership instead of this scan. A snapshot is a point-in-time view, and the type's documentation says so. `waitForMembers` re-captures per iteration because observing change is its purpose, and no signal is ever decided from a captured view. diff --git a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.zh.md b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.zh.md index 9c5fe65bb8..1d63aca3f5 100644 --- a/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-27-process-table-snapshots.zh.md @@ -22,18 +22,20 @@ Status: implemented 任何派生两个及以上子进程的命令——一条管道、`make`、`pnpm`、`git`——都会把宿主事件循环打满,直到它退出。 -拆卸路径的结构相同。`signalProcess` 自己去问存活来给每个信号加 PID 复用围栏,因此向 N 个成员发信号要读 N 次表。 +fallback 终端拆卸路径的结构相同。`signalProcess` 自己去问存活来给每个信号加 PID 复用围栏,因此向 N 个已观察成员发信号要读 N 次表。 ## Decision `ProcessInspector.snapshot()` 返回一个 `ProcessSnapshot`,即对进程表的一次观察,由它回答 `tree(rootPid)`、`session(sessionId)` 和 `alive(identity)`。它取代了那三个按问题划分的方法;检查器剩下的接口是 `foregroundPgid`、`isStdinWaiting`、`signalGroup` 和 `signalProcess`。 -每个调用方捕获一次快照,并从中回答本次流程的全部问题。`LocalTerminalHandle.descendants()` 取一次快照,从中读取树与会话,并用同一个 `alive` 过滤幸存者,因此一次就绪轮询无论有多少子进程都只读一次表。`waitForMembers` 每一轮轮询各捕获一次新快照,因为它的用途正是观察变化。 +每个调用方捕获一次快照,并从中回答本次流程的全部问题。`LocalTerminalHandle.descendants()` 取一次快照,从中读取树与会话,并用同一个 `alive` 过滤幸存者,因此一次就绪轮询无论有多少子进程都只读一次表。fallback `waitForMembers` 每一轮轮询各捕获一次新快照,因为它的用途正是观察变化。 发信号不共用这份观察。`ProcessInspector.isAlive(identity)` 用各平台最窄的按标识来源回答当前状态——Linux 读一个 `/proc//stat`、macOS 读一次 `ps` 表、Windows 查一次进程句柄——`signalProcess` 在投递信号前就地取这道围栏。观察无法代替它:观察把原始的「PID 与起始时间」配对保留了下来,因此被复用的 PID 仍会与之匹配,并领走本该发给已退出进程的信号。逐目标读取围栏还让一次失败的读取只损失一个目标,而不是整轮拆卸的其余部分,这正是[同步退出清理约定](../bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md)的要求。 `signalMembers` 与 `waitForMembers` 在一轮没有成员时直接返回、不做任何捕获,因此没有派生子进程的命令,其拆卸扫描不付表读取代价。 +受支持的 Linux 终端在绑定 user-systemd scope 后,正常拆卸会绕过这些观察扫描,改为等待 manager 拥有的成员事实。进程表快照继续负责前台/就绪检查,以及 fallback 或同步宿主退出清理。[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责这项分工。 + 平台差异体现在快照如何构建,而不在它承诺什么: - **macOS** 由一张 `ps` 表构建。该表既不暴露会话 id 也不暴露状态列,所以 `session` 为空,`alive` 报告的是「存在且起始标识匹配」。 @@ -62,7 +64,7 @@ Status: implemented 一次就绪轮询的进程表代价现在与子进程数量无关。在 macOS 上,一次轮询执行一次完整表读取加一次小的 `tpgid` 读取,也就是上表中 0 子进程那一行的代价,对任意子进程数量都成立。 -拆卸保持原有的按次代价:每个目标一次窄的存活读取,在 macOS 上即每个成员一次 `ps` fork。这项代价从来不是实测到的问题——一个终端只拆卸一次,而它的就绪路径最多轮询 600 次——所以本次修复刻意付出它,以保证围栏读的是当前状态。 +fallback 与同步宿主退出拆卸保持原有的按次代价:每个目标一次窄的存活读取,在 macOS 上即每个成员一次 `ps` fork。这项代价从来不是实测到的问题——一个终端只拆卸一次,而它的就绪路径最多轮询 600 次——所以本次修复刻意付出它,以保证围栏读的是当前状态。受支持的 Linux 正常拆卸使用 scope 成员事实,不执行这项扫描。 快照是一个时间点视图,该类型的文档也这样声明。`waitForMembers` 每轮重新捕获是因为观察变化正是它的用途;任何信号都不会从一份已捕获的视图上做决定。 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 index 58cf47ce3e..07de32b014 100644 --- 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 @@ -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-28-subprocess-native-containment.md -2026-08-28-subprocess-native-containment.md: c4fad5a11be450a382a2fc66dbae81e30a0e84c8 -2026-08-28-subprocess-native-containment.zh.md: c8185e0e90a69440c2441fc95258261bb091300b +2026-08-28-subprocess-native-containment.md: 937c148101388aa49aac4826120218ff4a67a0e8 +2026-08-28-subprocess-native-containment.zh.md: 156d3a84d3a3a92a605866ee94a07616d18a09ee 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 index c4fad5a11b..937c148101 100644 --- a/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md +++ b/.agents/notes/implemented/architecture/2026-08-28-subprocess-native-containment.md @@ -28,17 +28,17 @@ The ordinary target result still comes from the same child process. The PTY path ### 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 uses Node IPC for exactly one start request, idempotent terminate control, and exactly one direct-result branch. Runner fd 0 through fd 2 are isolated, fd 3 carries IPC, and fd 4 through fd 6 carry target stdin, stdout, and stderr. The shared Win32 layer resolves those CRT descriptors through UCRT `_get_osfhandle`, passes the resulting OS handles through `STARTF_USESTDHANDLES`, and preserves a separately resolved `CreateProcessW` application path without changing the original argv entry. 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 carrier streams as the ordinary handle's stdio, and user bytes never pass through IPC. +The Windows parent starts the provider runner from a bootstrap cwd and environment, gives it the original target argv after a private `--` delimiter, and uses Node IPC for exactly one start request, 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 is always a pipe; when stdin is ignored, the parent destroys its writer before sending the start request so the target receives EOF without changing descriptor positions. The shared Win32 layer calls `GetStartupInfoW`, strictly decodes libuv's `cbReserved2`/`lpReserved2` table for fds 4 through 6, temporarily enables inheritance on those OS 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 carrier streams 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 settles `.done` only after a strict direct-result message and the existing stdout/stderr close or bounded-drain barrier. A later Job query or range-settlement failure rejects only `waitForExit()`. IPC loss before that `.done` barrier rejects `.done` as runner infrastructure failure; IPC loss afterward leaves the completed direct result unchanged but still rejects range settlement. 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. +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`. 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 `@deepseek-ai/dsh`'s packaging-owned `runtime-bootstrap.js`. That bootstrap imports the public CLI 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, 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, terminate, `target-exit`, `spawn-error`, `runner-error`, and `start-cancelled` messages. Errors carry only bounded Node-shaped fields. 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. +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 three result branches: `target-exit` with a numeric `exitCode`, `error` with bounded Node-shaped fields, and payload-free `start-cancelled`; the parent derives `signal: null`. A cancellation reason never crosses the wire, so the parent preserves the 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 @@ -54,7 +54,8 @@ This note owns the current native-containment mechanism. It partially updates th ## Verification -- Provider and protocol suites pin synchronous NUL rejection before launch side effects, strict request/result decoding, target cwd and complete environment restoration, private-variable collision, Linux PATH lookup with preserved argv, close-on-exec removal for inherited stdio, pre-exec error ownership, the three scope-establishment states, all four Windows result branches, start cancellation, result-send and IPC-disconnect failures, isolated carrier-descriptor closure, stdio settlement, active-process quiescence, and unique handle cleanup. +- 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, the three scope-establishment states, and exactly-once PTY managed-owner cleanup. +- Windows protocol and Win32 suites pin exactly three result branches, numeric-only target exits, raw local cancellation reasons, `EPERM`/`-4048` access-denied mapping, explicit sorted target environment blocks with `=C:` preservation and double-NUL termination, strict `GetStartupInfoW` libuv descriptor-table decoding, the always-piped ignored-stdin carrier, 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. 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 index c8185e0e90..156d3a84d3 100644 --- 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 @@ -28,17 +28,17 @@ request 被消费或 manager 已观察到 unit 都能建立 scope ownership。 ### Windows runner 与 Job -Windows parent 从 bootstrap cwd 与环境启动 provider runner,把原始 target argv 放在私有 `--` 分隔符之后,并通过 Node IPC 传递恰好一条 start request、幂等 terminate control 与恰好一个 direct-result 分支。runner 的 fd 0 至 fd 2 相互隔离,fd 3 承载 IPC,fd 4 至 fd 6 承载 target stdin、stdout 与 stderr。共享 Win32 层通过 UCRT `_get_osfhandle` 解析这些 CRT 描述符,经 `STARTF_USESTDHANDLES` 传递对应 OS handle,并保留单独解析的 `CreateProcessW` application path,而不改变原始 argv 项。suspended target 进入 Job 并恢复后,runner 只关闭 fd 4 至 fd 6,绝不改写或销毁 Node 标准流。parent 把 carrier stream 作为普通句柄的 stdio 返回,用户字节绝不经过 IPC。 +Windows parent 从 bootstrap cwd 与环境启动 provider runner,把原始 target argv 放在私有 `--` 分隔符之后,并通过 Node IPC 传递恰好一条 start request、幂等 terminate control 与恰好一个 result。runner 的 fd 0 至 fd 2 相互隔离,fd 3 承载 IPC,fd 4 至 fd 6 承载 target stdin、stdout 与 stderr。fd 4 始终是 pipe;忽略 stdin 时,parent 会在发送 start request 前销毁写端,使 target 在不改变描述符位置的情况下收到 EOF。共享 Win32 层调用 `GetStartupInfoW`,严格解码 libuv 的 `cbReserved2`/`lpReserved2` 表以取得 fd 4 至 fd 6 的 OS handle,临时启用这些 handle 的继承,并通过 `STARTF_USESTDHANDLES` 传入。`spawnCurrentTokenJobProcess` 要求单独解析的 `applicationName` 与完整 target 环境,并使用 `CREATE_UNICODE_ENVIRONMENT` 传入排序、双 NUL 结尾的 UTF-16LE 块,其中包括 `=X:` 驱动器条目,而不修改 runner 环境。suspended target 进入 Job 并恢复后,runner 只关闭 fd 4 至 fd 6,绝不改写或销毁 Node 标准流。parent 把 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 只有在收到严格 direct-result message,并且既有 stdout/stderr close 或有界 drain barrier 完成后才结算 `.done`。后续 Job query 或 range settlement failure 只会使 `waitForExit()` reject。在该 `.done` barrier 之前发生 IPC loss 会使 `.done` 以 runner infrastructure failure reject;之后发生 IPC loss 会保留已经完成的 direct result,但仍使 range settlement reject。disconnect 或 result-send failure 会让 runner 停止协议工作、终止并关闭自己唯一的 Job handle,然后以非零状态退出。最后一个 Job handle 关闭会终止剩余成员,但不会把 disconnected 路径改写成成功的完全停稳证明。 +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。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 单文件可执行程序则从 `@deepseek-ai/dsh` 由打包层拥有的 `runtime-bootstrap.js` 进入。私有 selector 不存在时,该 bootstrap 导入公共 CLI;否则会删除 selector,并分派到同一 subprocess runner core。公共 `dsh` 参数解析器没有隐藏 runner mode,打包也不提供第二个 Node 可执行程序。 -selector 是 per-spawn locator 或 sentinel,不是凭据或持久格式。Linux 使用一个严格 request 与一个可选严格 startup-error 文件;Windows 使用一条 IPC channel,承载闭合集 start、terminate、`target-exit`、`spawn-error`、`runner-error` 与 `start-cancelled` 消息。错误只携带有界的 Node-shaped 字段。缺失、额外、类型错误或未知字段都会 fail closed。target 环境可以包含 selector 名称及其 Windows 大小写变体,因为 provider 会单独传递 target 状态,并且只在私有选择值消费后才恢复该状态。 +selector 是 per-spawn locator 或 sentinel,不是凭据或持久格式。Linux 使用一个严格 request 与一个可选严格 startup-error 文件。Windows 使用一条 IPC channel,承载闭集的 `start` 与 `terminate` request,以及恰好三个 result 分支:只含数字 `exitCode` 的 `target-exit`、携带有界 Node-shaped 字段的 `error`,以及无载荷的 `start-cancelled`;parent 会派生 `signal: null`。取消 reason 不跨 wire 传递,因此 parent 会原样保留第一个本地 reason,包括 `null` 或 `undefined`。缺失、额外、类型错误或未知字段都会 fail closed。target 环境可以包含 selector 名称及其 Windows 大小写变体,因为 provider 会单独传递 target 状态,并且只在私有选择值消费后才恢复该状态。 ### Fallback 与 cleanup @@ -54,7 +54,8 @@ selector 是 per-spawn locator 或 sentinel,不是凭据或持久格式。Linu ## Verification -- provider 与协议测试套件固定同步 NUL 拒绝发生在启动副作用之前、严格 request/result 解码、target cwd 与完整环境恢复、私有变量碰撞、保留 argv 的 Linux PATH 查找、为继承 stdio 清除 close-on-exec、pre-exec error ownership、三种 scope 建立状态、全部 4 个 Windows result 分支、startup cancellation、result-send 与 IPC-disconnect failure、隔离 carrier 描述符关闭、stdio settlement、active-process 完全停稳,以及唯一 handle cleanup。 +- provider 与 Linux 协议测试套件固定同步 NUL 拒绝发生在启动副作用之前、严格 request/error 解码、target cwd 与完整环境恢复、私有变量碰撞、保留 argv 且对 symlink 敏感的 PATH 遍历、为继承 stdio 清除 close-on-exec、pre-exec error ownership、三种 scope 建立状态,以及 PTY managed-owner 恰好一次 cleanup。 +- Windows 协议与 Win32 测试套件固定恰好三个 result 分支、只含数字的 target exit、原样本地 cancellation reason、access denied 到 `EPERM`/`-4048` 的映射、显式排序的 target 环境块及 `=C:` 保留和双 NUL 结尾、严格的 `GetStartupInfoW` libuv 描述符表解码、始终使用 pipe 的 ignored-stdin carrier、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 保留。 diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml index 587e1ba665..2ce2a2cff6 100644 --- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md -2026-06-30-hook-protocol-lib.md: db00d0f880a073fbdd53a591e5d2412f620ecedc -2026-06-30-hook-protocol-lib.zh.md: 7b0208ec95a8e6ecdf9ebca5badab871a9747b43 +2026-06-30-hook-protocol-lib.md: c2549fb26fe5dfbf97362bc595bc77a599800fc7 +2026-06-30-hook-protocol-lib.zh.md: d9d7f018295950fde41ddb09caf8e2b481b85079 diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md index db00d0f880..c2549fb26f 100644 --- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md +++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md @@ -16,7 +16,7 @@ A new `packages/hooks/` group with `hook-protocol` as a pure library. It owns fo **Shared (here):** - **Matcher** — `matcherDiagnostic(pattern, mode)` and `matchesMatcher(pattern, query, mode)`. The ONE axis the dialects differ on is collapsed to the `mode` parameter: `claude` treats a pure `[A-Za-z0-9_|]+` pattern as a literal (pipe = exact-match alternation) and anything else as a regex; `codex` is always an unanchored regex. Match-all on absent/`''`/`'*'`. Each bridge ignores unsupported events before group parsing, discards matcher fields on supported events without matcher subjects, validates the remaining runnable groups, and treats an invalid regex there as a whole-config load failure, with a stable dialect/pattern/event diagnostic; no hook listeners are registered. Runtime matching still contains an invalid regex as a non-match, so a direct library caller never throws into the loop. -- **Execution** — `runHook(bash, hook, options)`. Runs a command hook through the `ctx.shell` seam rather than a bespoke `spawn`: the executor already provides the scrubbed-but-overridable env, process-group kills, and timeout the protocol needs, and `dsh-shell`'s `stdin`/`env` fields (added for exactly this) are the trusted-plugin API an in-process bridge is allowed to use. It serializes the bridge-built payload to stdin (trailing newline iff CC), honors the hook's `timeoutSec` (else `DEFAULT_HOOK_TIMEOUT_MS`, the 10-minute reference default both dialects share), and never throws (an executor rejection becomes a non-blocking-error `HookOutput`). +- **Execution** — `runHook(bash, hook, options)`. Runs a command hook through the `ctx.shell` seam rather than a bespoke `spawn`: the executor already provides the scrubbed-but-overridable env, [provider-managed range termination](../architecture/2026-08-28-subprocess-native-containment.md), and timeout the protocol needs, and `dsh-shell`'s `stdin`/`env` fields (added for exactly this) are the trusted-plugin API an in-process bridge is allowed to use. It serializes the bridge-built payload to stdin (trailing newline iff CC), honors the hook's `timeoutSec` (else `DEFAULT_HOOK_TIMEOUT_MS`, the 10-minute reference default both dialects share), and never throws (an executor rejection becomes a non-blocking-error `HookOutput`). - **Decode** — `parseHookOutput(exit, stdout, stderr)`, the exit-code + structured-stdout codec, producing a dialect-neutral `HookOutput`. Exit `0` → lenient JSON parse of stdout; exit `2` → blocking error with `stderr` as the reason (surfaced as `decision: 'block'` so no caller needs a separate exit-code branch); other → non-blocking error. Parses the CC structured-stdout fields that have a consumer on some path (`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`); the bridge honors only the subset meaningful for its dialect. Fields with no consumer on any path are not parsed at all (CC's `suppressOutput` — hook stdout never enters a transcript here, so there is nothing to suppress; see [the tighten-hook-protocol-contract Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)). - **Merge** — `mergeHookOutputs(outputs)`, folding multiple matched hooks into one most-restrictive `MergedHookOutcome`: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined `\n\n`, context/system-messages accumulated in order. - **`hook/*` session events** — `hook/invoked` / `hook/result`, declaration-merged into `SessionEventMap` (log-only, like `compaction/*` — NOT `SurfaceEventType`s), with `appendHookInvoked`/`appendHookResult` helpers so the invoked/result pairing and owner-defined execution relation stay consistent across bridges. `appendHookResult` also owns the durable record's semantics — the decision string (the hook's parsed decision, else `'stop'` on `continue:false`, else `'pass'`) and the 500-character `stderrSummary` truncation derive from the `HookOutput` here, not per-bridge. diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md index 7b0208ec95..d9d7f01829 100644 --- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md +++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md @@ -16,7 +16,7 @@ Status: implemented **共享(本库):** - **Matcher** — `matcherDiagnostic(pattern, mode)` 与 `matchesMatcher(pattern, query, mode)`。两种方言的唯一差异收敛到 `mode` 参数:`claude` 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量(管道符表示多个精确匹配备选项),其他 pattern 视为正则;`codex` 始终使用未锚定正则。缺省/`''`/`'*'` 匹配一切。每个桥接插件会在解析 group 前忽略不支持的事件,丢弃受支持但没有 matcher 匹配对象的事件上的 matcher 字段,校验其余可运行 group;其中任何无效正则都会导致整份配置加载失败,并给出包含方言/pattern/事件的稳定诊断,不会注册任何钩子监听器。运行时匹配仍会将无效正则隔离为不匹配,因此直接调用本库绝不向 agent loop(智能体循环)抛异常。 -- **执行** — `runHook(bash, hook, options)`。通过 `ctx.shell` seam 而非自建 `spawn` 运行命令钩子:执行器已提供清洗但可覆盖的 env、进程组 kill 和超时,正是协议所需的能力;`dsh-shell` 的 `stdin`/`env` 字段(正是为此添加的)是进程内桥接插件被允许使用的受信插件 API。它将桥接插件构建的 payload 序列化到 stdin(仅 CC 时追加尾部换行),遵守钩子的 `timeoutSec`(否则使用 `DEFAULT_HOOK_TIMEOUT_MS`,即两种方言共享的 10 分钟参考默认值),且从不抛异常(执行器拒绝变为 non-blocking-error 的 `HookOutput`)。 +- **执行** — `runHook(bash, hook, options)`。通过 `ctx.shell` seam 而非自建 `spawn` 运行命令钩子:执行器已提供清洗但可覆盖的 env、[由提供方管理的范围终止](../architecture/2026-08-28-subprocess-native-containment.zh.md)和超时,正是协议所需的能力;`dsh-shell` 的 `stdin`/`env` 字段(正是为此添加的)是进程内桥接插件被允许使用的受信插件 API。它将桥接插件构建的 payload 序列化到 stdin(仅 CC 时追加尾部换行),遵守钩子的 `timeoutSec`(否则使用 `DEFAULT_HOOK_TIMEOUT_MS`,即两种方言共享的 10 分钟参考默认值),且从不抛异常(执行器拒绝变为 non-blocking-error 的 `HookOutput`)。 - **解码** — `parseHookOutput(exit, stdout, stderr)`,exit-code + structured-stdout 编解码器,产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout;exit `2` → blocking error,`stderr` 为原因(以 `decision: 'block'` 呈现,调用方无需单独处理 exit-code 分支);其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段(`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`);桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析(CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript(文本记录),因此无需抑制;见 [收紧钩子协议约定 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.zh.md))。 - **合并** — `mergeHookOutputs(outputs)`,将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`:权限优先级 **deny > ask > allow**,停止状态从首个 `continue:false` 起保持不变,阻止原因以 `\n\n` 拼接,上下文/system-messages 按序累积。 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`,通过声明合并进入 `SessionEventMap`(仅日志,如 `compaction/*`——不是 `SurfaceEventType`),配有 `appendHookInvoked`/`appendHookResult` 辅助函数,确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义:decision 字符串(钩子解析出的 decision,否则 `continue:false` 时为 `'stop'`,否则为 `'pass'`)和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生,而非各桥接插件各自实现。 diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml index dcc666c622..889c7fb4e7 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md -2026-07-22-cross-platform-test-fixtures.md: 9114481543d6cae1661cbed70868eddb2faa09fc -2026-07-22-cross-platform-test-fixtures.zh.md: 710ec5887f02b5c3c71d69f16ab726323501ac92 +2026-07-22-cross-platform-test-fixtures.md: 603b3f0bcce62bd6ed7f7e89e3f2d65493532045 +2026-07-22-cross-platform-test-fixtures.zh.md: 89faa55a1e39ba1d9ea6b8b5e2c50a47d278942a diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md index 9114481543..603b3f0bcc 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md @@ -16,7 +16,7 @@ Tests of platform-neutral behavior construct absolute paths and `file:` URIs wit Transport-failure tests inject the connection's message writer and deliver the same asynchronous write callback error that a real Node stream would report. The production writer still writes framed messages to child stdin. This keeps a real child alive while the test deterministically distinguishes transport failure from process exit without reaching into platform-specific pipe handles. -Language-server teardown targets the whole descendant tree through a negative process-group id on POSIX and synchronous `taskkill /T /F` on Windows. Windows suppresses only taskkill's already-absent-tree status; command, permission, and other tree-kill failures remain teardown failures. A read-only provider query retries once only when its selected pooled transport fails before or during that query; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient. +Language-server teardown calls `SubprocessHandle.terminate()` and then awaits `waitForExit()`, so it neither inspects a PID nor chooses a platform kill command. The local provider's [native-containment decision](../architecture/2026-08-28-subprocess-native-containment.md) owns Linux scope, Windows Job, and disclosed fallback mechanics. A read-only provider query retries once only when its selected pooled transport fails before or during that query and teardown completes; errors from a still-live server are not replayed, and a query failure plus a teardown failure remain visible together. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient. Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection. Supported Windows paths remain inside the per-file coverage gate rather than being excluded with their test files. @@ -30,4 +30,4 @@ Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on tha ## Consequences -Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer. +Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Managed-range failures enter through the subprocess handle's wait operation rather than platform kill commands, so disposal keeps a failed quiescence proof visible to the caller. diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md index 710ec5887f..89faa55a1e 100644 --- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md +++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md @@ -16,7 +16,7 @@ Status: implemented 传输故障测试会注入连接的消息写入器,并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活,使测试无需触及平台特有的管道句柄,也能确定性地区分传输故障与进程退出。 -语言服务器的资源清理会终止整棵后代进程树:POSIX 使用负数进程组 ID,Windows 同步执行 `taskkill /T /F`。Windows 只会忽略 taskkill 返回的「进程树已经不存在」状态;命令执行失败、权限错误及其他终止进程树的失败仍属于资源清理失败。只读的提供方查询仅在选定的池化传输于该次查询开始前或执行期间失效时重试一次;服务器仍存活时返回的错误不会触发重试。终端测试会等待可观察的渲染输出,不假设一次事件循环轮转已经足够。 +语言服务器的资源清理会调用 `SubprocessHandle.terminate()`,然后等待 `waitForExit()`,因此它既不检查 PID,也不选择平台终止命令。本地提供方的[原生 containment 决策](../architecture/2026-08-28-subprocess-native-containment.zh.md)负责 Linux scope、Windows Job 与已声明的 fallback 机制。只读的提供方查询仅在选定的池化传输于该次查询开始前或执行期间失效,且资源清理完成时重试一次;服务器仍存活时返回的错误不会触发重试,查询失败与资源清理失败会一并保留。终端测试会等待可观察的渲染输出,不假设一次事件循环轮转已经足够。 对于真正仅存在于 POSIX 的原语,测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。Windows 上受支持的路径仍受逐文件覆盖率门禁约束,不会随测试文件一起排除。 @@ -30,4 +30,4 @@ Status: implemented ## 后果 -可移植 fixture 需要更显式地构造,因为预期路径要从共享的原生常量派生,传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言,以继续覆盖相应的产品行为。协议级优雅关停失败后,Windows 上的资源清理依赖宿主的 `taskkill` 命令;命令同步执行成功时,可确保 dispose(资源释放)在有限时间内完成,并确保清理返回前即可观察到后代进程退出;若进程树终止失败,资源释放逻辑仍能观察到该失败。 +可移植 fixture 需要更显式地构造,因为预期路径要从共享的原生常量派生,传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言,以继续覆盖相应的产品行为。受管范围失败通过子进程句柄的等待操作注入,而不是平台终止命令,因此资源释放会向调用方暴露无法证明完全停稳的失败。 diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 465000ba37..b0f4e02816 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 diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts index 39f7f561b7..aa0f3bb11b 100644 --- a/packages/subprocess/subprocess-local/src/index.ts +++ b/packages/subprocess/subprocess-local/src/index.ts @@ -273,7 +273,6 @@ export class LocalSubprocessRuntime extends SubprocessRuntime { this.internals.platform ?? process.platform, owner, scope?.resolveOutcome, - scope?.cleanup, ) this.terminals.add(handle) const release = async (): Promise => { diff --git a/packages/subprocess/subprocess-local/src/linux-execve.ts b/packages/subprocess/subprocess-local/src/linux-execve.ts index b3b40ba64b..a5bed81059 100644 --- a/packages/subprocess/subprocess-local/src/linux-execve.ts +++ b/packages/subprocess/subprocess-local/src/linux-execve.ts @@ -32,7 +32,7 @@ function systemError(errno: number, syscall: string, path?: string): Error { const subject = path === undefined ? syscall : `${syscall} '${path}'` const error = Object.assign(new Error(`${code}: ${detail}, ${subject}`), { code, - errno, + errno: uvError, syscall, }) return path === undefined ? error : Object.assign(error, { path }) diff --git a/packages/subprocess/subprocess-local/src/runner-launch.ts b/packages/subprocess/subprocess-local/src/runner-launch.ts index 94576a1a0d..7e6966969b 100644 --- a/packages/subprocess/subprocess-local/src/runner-launch.ts +++ b/packages/subprocess/subprocess-local/src/runner-launch.ts @@ -111,7 +111,7 @@ export function runnerStdio( 'ignore', 'ignore', 'ipc', - targetStdio[0], + 'pipe', spec.stdio.stdout === 'inherit' ? 1 : 'pipe', spec.stdio.stderr === 'inherit' ? 2 : 'pipe', ] diff --git a/packages/subprocess/subprocess-local/src/runner-protocol.ts b/packages/subprocess/subprocess-local/src/runner-protocol.ts index 606bea11e8..2e12f9f808 100644 --- a/packages/subprocess/subprocess-local/src/runner-protocol.ts +++ b/packages/subprocess/subprocess-local/src/runner-protocol.ts @@ -11,7 +11,7 @@ import { unlinkSync, writeFileSync, } from 'node:fs' -import { constants as osConstants, tmpdir } from 'node:os' +import { tmpdir } from 'node:os' import { basename, dirname, isAbsolute, join } from 'node:path' const STARTUP_ERROR_TEMPORARY = '.startup-error.tmp' @@ -36,8 +36,7 @@ export interface SerializedRunnerError { /** A Linux pre-exec failure published atomically beside its consumed request. */ export type LinuxStartupError = - | { type: 'spawn-error'; error: SerializedRunnerError } - | { type: 'runner-error'; error: SerializedRunnerError } + { type: 'error'; error: SerializedRunnerError } /** The only parent-to-runner start message on Windows. */ export interface WindowsStartRequest { @@ -53,9 +52,8 @@ export interface WindowsTerminateRequest { /** Exactly one direct-result branch is sent by a connected Windows runner. */ export type WindowsRunnerResult = - | { type: 'target-exit'; exitCode: number | null; signal: NodeJS.Signals | null } - | { type: 'spawn-error'; error: SerializedRunnerError } - | { type: 'runner-error'; error: SerializedRunnerError } + | { type: 'target-exit'; exitCode: number } + | { type: 'error'; error: SerializedRunnerError } | { type: 'start-cancelled' } /** Private paths owned by one Linux ordinary or PTY spawn. */ @@ -100,10 +98,10 @@ 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 !== 'spawn-error' && value.type !== 'runner-error') { + if (value.type !== 'error') { throw new Error('subprocess runner emitted an unknown error result') } - return { type: value.type, error: value.error } + return { type: 'error', error: value.error } } /** @@ -203,7 +201,7 @@ export function isWindowsTerminateRequest(value: unknown): value is WindowsTermi } /** - * Strictly parse one of the four Windows direct-result branches. + * Strictly parse one of the three Windows direct-result branches. * @param value - untrusted IPC payload. * @returns validated direct-result message. */ @@ -215,19 +213,17 @@ export function parseWindowsRunnerResult(value: unknown): WindowsRunnerResult { if (!hasExactKeys(value, ['type'])) throw new Error('subprocess runner emitted an invalid start-cancelled result') return { type: 'start-cancelled' } } - if (value.type === 'spawn-error' || value.type === 'runner-error') return parseErrorResult(value) + if (value.type === 'error') return parseErrorResult(value) if (value.type === 'target-exit') { - const validExitCode = value.exitCode === null - || (typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode) && value.exitCode >= 0) - const validSignal = value.signal === null - || (typeof value.signal === 'string' && Object.hasOwn(osConstants.signals, value.signal)) - if (!hasExactKeys(value, ['type', 'exitCode', 'signal']) || !validExitCode || !validSignal) { + 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 | null, - signal: value.signal as NodeJS.Signals | null, + exitCode: value.exitCode as number, } } throw new Error(`subprocess runner emitted an unknown Windows result: ${value.type}`) diff --git a/packages/subprocess/subprocess-local/src/spawn-runner.ts b/packages/subprocess/subprocess-local/src/spawn-runner.ts index 1ec4f04dd6..e2abddce32 100644 --- a/packages/subprocess/subprocess-local/src/spawn-runner.ts +++ b/packages/subprocess/subprocess-local/src/spawn-runner.ts @@ -1,7 +1,6 @@ /** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */ import { closeSync } from 'node:fs' -import { posix } from 'node:path' import { closeHandleChecked, isJobEmpty, @@ -67,27 +66,24 @@ const defaultInternals: SpawnRunnerInternals = { closeHandleChecked, } -function replaceEnvironment(target: NodeJS.ProcessEnv, env: Record): void { - for (const key of Object.keys(target)) Reflect.deleteProperty(target, key) - Object.assign(target, env) -} - function asSpawnError(error: unknown, program: string, args: readonly string[]): SerializedRunnerError { const serialized = serializeRunnerError(error) - const code = error instanceof Win32Error - ? error.win32Code === 2 || error.win32Code === 3 || error.win32Code === 267 + const win32Code = error instanceof Win32Error ? error.win32Code : undefined + const code = win32Code === undefined + ? serialized.code + : win32Code === 2 || win32Code === 3 || win32Code === 267 ? 'ENOENT' - : error.win32Code === 5 - ? 'EACCES' - : error.win32Code === 193 + : win32Code === 5 + ? 'EPERM' + : win32Code === 193 ? 'EFTYPE' : 'UNKNOWN' - : serialized.code if (code === undefined) return serialized return { ...serialized, message: `spawn ${program} ${code}: ${serialized.message}`, code, + ...win32Code === 5 ? { errno: -4048 } : {}, syscall: `spawn ${program}`, path: program, spawnargs: [...args], @@ -128,7 +124,10 @@ function execLinuxTarget( const path = request.env.PATH ?? '/usr/bin:/bin' let permissionFailure: Error | undefined for (const directory of path.split(':')) { - const candidate = posix.resolve(request.cwd, directory, program) + 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) { @@ -155,7 +154,7 @@ function runLinux( try { request = consumeLinuxLaunchRequest(files.requestPath) } catch (error) { - writeLinuxStartupError(files, { type: 'runner-error', error: serializeRunnerError(error) }) + writeLinuxStartupError(files, { type: 'error', error: serializeRunnerError(error) }) host.exitCode = 127 return } @@ -164,7 +163,7 @@ function runLinux( execLinuxTarget({ ...request, cwd: host.cwd() }, argv, internals) } catch (error) { writeLinuxStartupError(files, { - type: 'spawn-error', + type: 'error', error: asSpawnError(error, argv[0] as string, argv.slice(1)), }) host.exitCode = 127 @@ -267,13 +266,13 @@ class WindowsJobRunner { undefined, { ...this.host.env }, ) - replaceEnvironment(this.host.env, request.env) 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 @@ -287,7 +286,7 @@ class WindowsJobRunner { } catch (error) { if (!this.committed && error instanceof Win32Error && error.api === 'CreateProcessW') { await this.publishTerminalResult({ - type: 'spawn-error', + type: 'error', error: asSpawnError(error, this.argv[0] as string, this.argv.slice(1)), }, 0) return @@ -331,7 +330,7 @@ class WindowsJobRunner { if (exitCode !== undefined) { this.internals.closeHandleChecked(this.api, this.processHandle, 'ordinary direct process') this.processHandle = undefined - void this.publishTerminalResult({ type: 'target-exit', exitCode, signal: null }) + void this.publishTerminalResult({ type: 'target-exit', exitCode }) } } if (this.jobHandle !== undefined && this.internals.isJobEmpty(this.api, this.jobHandle)) { @@ -370,7 +369,7 @@ class WindowsJobRunner { if (!this.resultStarted) { this.resultStarted = true try { - await sendMessage(this.host, { type: 'runner-error', error: serializeRunnerError(error) }) + await sendMessage(this.host, { type: 'error', error: serializeRunnerError(error) }) this.resultDelivered = true } catch { // The disconnected parent observes runner infrastructure failure. @@ -443,7 +442,7 @@ export async function reportSpawnRunnerFailure( host: RunnerHost = process, ): Promise { if (selection === WINDOWS_RUNNER_SELECTION) { - try { await sendMessage(host, { type: 'runner-error', error: serializeRunnerError(error) }) } catch { /* No transport remains. */ } + try { await sendMessage(host, { type: 'error', error: serializeRunnerError(error) }) } catch { /* No transport remains. */ } host.exitCode = 127 if (host.connected) host.disconnect() return @@ -451,7 +450,7 @@ export async function reportSpawnRunnerFailure( if (selection !== undefined) { try { const files: LinuxLaunchFiles = linuxLaunchFilesFromLocator(selection) - writeLinuxStartupError(files, { type: 'runner-error', error: serializeRunnerError(error) }) + writeLinuxStartupError(files, { type: 'error', error: serializeRunnerError(error) }) } catch { // The parent will report an unconsumed request or missing runner result. } diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts index 5a3772c3a8..0a4f4564bd 100644 --- a/packages/subprocess/subprocess-local/src/spawn.ts +++ b/packages/subprocess/subprocess-local/src/spawn.ts @@ -342,7 +342,7 @@ export function validateSubprocessSpec(spec: SubprocessSpawnSpec): void { throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`) } if (spec.signal?.aborted) { - throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`) + throw spec.signal.reason } const [program] = spec.argv if (program === undefined || program.length === 0) { @@ -483,6 +483,7 @@ export function bindManagedProcess( let graceTimer: ReturnType | undefined let rangeExitObserved = false let rangeExitObservation: Promise | undefined + let directResultLatched = false let settled = false const scheduleOwnerCleanup = (): boolean => { @@ -563,17 +564,19 @@ export function bindManagedProcess( resolve(outcome) } const fail = (error: unknown): void => { - if (settled) return + if (settled || directResultLatched) return settled = true terminate() stopCollectors() cleanup() - /* v8 ignore next -- managed launch promises reject with Error instances. */ - const failure = error instanceof Error ? error : new Error(String(error)) - reject(failure) + // 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) } void launch.infrastructureFailure?.catch(fail) launch.direct.then((outcome) => { + if (settled) return + directResultLatched = true if (stdoutClosed === undefined && stderrClosed === undefined) { settle(outcome) return diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts index 15ec3fc7cb..d8330bf71a 100644 --- a/packages/subprocess/subprocess-local/src/terminal.ts +++ b/packages/subprocess/subprocess-local/src/terminal.ts @@ -43,6 +43,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. */ @@ -61,7 +62,6 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { private readonly platform: NodeJS.Platform = process.platform, private readonly managedOwner?: BoundProcessOwner, private readonly resolveManagedOutcome?: (outcome: SubprocessOutcome) => SubprocessOutcome, - private readonly cleanupManagedProtocol?: () => void, ) { this.pid = terminal.pid this.rootIdentity = inspector.snapshot().tree(this.pid).find(member => member.pid === this.pid) @@ -317,7 +317,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle { this.dataDisposable.dispose() this.exitDisposable.dispose() } finally { - void this.done.finally(() => { this.cleanupManagedProtocol?.() }).catch(() => {}) + void this.done.finally(() => { this.cleanupManagedOwner(this.managedOwner as BoundProcessOwner) }).catch(() => {}) } return } @@ -335,6 +335,12 @@ 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() diff --git a/packages/subprocess/subprocess-local/src/windows-job.ts b/packages/subprocess/subprocess-local/src/windows-job.ts index 845fb7e43a..74ab3206eb 100644 --- a/packages/subprocess/subprocess-local/src/windows-job.ts +++ b/packages/subprocess/subprocess-local/src/windows-job.ts @@ -57,18 +57,22 @@ export function probeWindowsJob(internals: WindowsJobInternals = {}): boolean { class WindowsJobOwner implements BoundProcessOwner { private cancellationReason: unknown + private cancellationReasonSet = false private terminationSent = false constructor( private readonly runner: RunnerProcess, private readonly exited: Promise, - private readonly failInfrastructure: (error: Error) => void, + private readonly failInfrastructure: (error: unknown) => void, ) { void this.exited.catch(() => {}) } signal(_signal: 'SIGTERM' | 'SIGKILL', cancellationReason?: unknown): void { - if (this.cancellationReason === undefined) this.cancellationReason = cancellationReason + if (!this.cancellationReasonSet) { + this.cancellationReason = cancellationReason + this.cancellationReasonSet = true + } if (this.terminationSent || !this.runner.connected) return this.terminationSent = true try { @@ -78,13 +82,15 @@ class WindowsJobOwner implements BoundProcessOwner { this.terminateForHostExit() }) } catch (error) { - this.failInfrastructure(error instanceof Error ? error : new Error(String(error))) + this.failInfrastructure(error) this.terminateForHostExit() } } startCancellationReason(): unknown { - return this.cancellationReason ?? new Error('subprocess target start was cancelled') + return this.cancellationReasonSet + ? this.cancellationReason + : new Error('subprocess target start was cancelled') } async waitForExit(): Promise { @@ -119,13 +125,15 @@ export function launchWindowsJob( env: runnerEnvironment(WINDOWS_RUNNER_SELECTION), stdio: runnerStdio(spec, true), }) as RunnerProcess + const targetStdin = child.stdio[4] as Writable | null + if (spec.stdio.stdin === 'ignore') targetStdin?.destroy() const direct = Promise.withResolvers() const infrastructure = Promise.withResolvers() const rangeExit = Promise.withResolvers() let resultSeen = false let infrastructureFailed = false - const failInfrastructure = (error: Error): void => { + const failInfrastructure = (error: unknown): void => { if (infrastructureFailed) return infrastructureFailed = true infrastructure.reject(error) @@ -144,16 +152,13 @@ export function launchWindowsJob( try { result = parseWindowsRunnerResult(value) } catch (error) { - /* v8 ignore next -- the closed parser raises Error instances for every malformed shape; - * conversion only defends future internal regressions. */ - const failure = error instanceof Error ? error : new Error(String(error)) - failInfrastructure(failure) + failInfrastructure(error) owner.terminateForHostExit() return } resultSeen = true if (result.type === 'target-exit') { - direct.resolve({ exitCode: result.exitCode, signal: result.signal }) + direct.resolve({ exitCode: result.exitCode, signal: null }) } else if (result.type === 'start-cancelled') { direct.reject(owner.startCancellationReason()) } else { @@ -194,14 +199,13 @@ export function launchWindowsJob( owner.terminateForHostExit() }) } catch (error) { - const failure = error instanceof Error ? error : new Error(String(error)) - failInfrastructure(failure) - direct.reject(failure) + failInfrastructure(error) + direct.reject(error) owner.terminateForHostExit() } return { - stdin: child.stdio[4] as Writable | null, + stdin: spec.stdio.stdin === 'ignore' ? null : targetStdin, stdout: child.stdio[5] as Readable | null, stderr: child.stdio[6] as Readable | null, direct: direct.promise, diff --git a/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts b/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts index 1b29fa0e09..c3679f60b0 100644 --- a/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts +++ b/packages/subprocess/subprocess-local/tests/linux-execve.spec.ts @@ -49,7 +49,7 @@ describe('Linux libc execve binding', () => { expect(errno).toHaveBeenCalledOnce() expect(failure).toMatchObject({ code: 'ENOENT', - errno: 2, + errno: -2, syscall: 'execve', path: '/missing/tool', }) @@ -69,7 +69,7 @@ describe('Linux libc execve binding', () => { const { loadLinuxExecve } = await import('../src/linux-execve.ts') expect(() => loadLinuxExecve()('/bin/tool', ['tool'], {})).toThrow(expect.objectContaining({ code: 'EBADF', - errno: 9, + errno: -9, syscall: 'fcntl', })) expect(nativeFcntl).toHaveBeenCalledExactlyOnceWith(0, 1, 0) @@ -91,7 +91,7 @@ describe('Linux libc execve binding', () => { const { loadLinuxExecve } = await import('../src/linux-execve.ts') expect(() => loadLinuxExecve()('/bin/tool', ['tool'], {})).toThrow(expect.objectContaining({ code: 'EIO', - errno: 5, + errno: -5, syscall: 'fcntl', })) expect(nativeFcntl.mock.calls).toEqual([ diff --git a/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts index 091f55a4b6..2422528df5 100644 --- a/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts +++ b/packages/subprocess/subprocess-local/tests/linux-scope.spec.ts @@ -228,7 +228,7 @@ describe('Linux scope establishment and quiescence', () => { const files = linuxLaunchFilesFromLocator(requestPath) unlinkSync(requestPath) writeLinuxStartupError(files, { - type: 'spawn-error', + type: 'error', error: { name: 'Error', message: 'spawn tool ENOENT', code: 'ENOENT' }, }) child.exit(127, null) @@ -408,7 +408,7 @@ describe('Linux PTY bootstrap reuse', () => { const files = linuxLaunchFilesFromLocator(requestPath) unlinkSync(requestPath) writeLinuxStartupError(files, { - type: 'spawn-error', error: { name: 'Error', message: 'bad cwd', code: 'ENOENT' }, + type: 'error', error: { name: 'Error', message: 'bad cwd', code: 'ENOENT' }, }) expect(() => scope.resolveOutcome({ exitCode: 127, signal: null })).toThrow('bad cwd') scope.cleanup() diff --git a/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts index 1a3a0681a9..d0b2751b56 100644 --- a/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts +++ b/packages/subprocess/subprocess-local/tests/spawn-runner.spec.ts @@ -138,12 +138,12 @@ describe('closed runner protocol', () => { const failure = Object.assign(new Error('spawn missing'), { name: 'SpawnError', code: 'ENOENT', errno: -2, syscall: 'spawn tool', path: 'tool', spawnargs: ['x'], }) - writeLinuxStartupError(files, { type: 'spawn-error', error: serializeRunnerError(failure) }) + 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).toMatchObject({ type: 'spawn-error', error: { code: 'ENOENT', path: 'tool', spawnargs: ['x'] } }) + expect(result).toMatchObject({ type: 'error', error: { code: 'ENOENT', path: 'tool', spawnargs: ['x'] } }) expect(deserializeRunnerError(result!.error)).toMatchObject({ name: 'SpawnError', message: 'spawn missing', code: 'ENOENT', errno: -2, }) @@ -190,19 +190,21 @@ describe('closed runner protocol', () => { expect(isWindowsTerminateRequest({ type: 'terminate' })).toBe(true) expect(isWindowsTerminateRequest({ type: 'terminate', reason: 'no' })).toBe(false) expect(parseWindowsRunnerResult({ type: 'start-cancelled' })).toEqual({ type: 'start-cancelled' }) - expect(parseWindowsRunnerResult({ type: 'target-exit', exitCode: null, signal: 'SIGTERM' })).toEqual({ - type: 'target-exit', exitCode: null, signal: 'SIGTERM', + expect(parseWindowsRunnerResult({ type: 'target-exit', exitCode: 7 })).toEqual({ + type: 'target-exit', exitCode: 7, }) - expect(parseWindowsRunnerResult({ type: 'spawn-error', error: { name: 'Error', message: 'bad' } })).toEqual({ - type: 'spawn-error', error: { name: 'Error', message: 'bad' }, + 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', payload: 1 }, - { type: 'target-exit', exitCode: -1, signal: null }, - { type: 'target-exit', exitCode: 0, signal: 'NOPE' }, - { type: 'runner-error', error: { name: 'Error', message: 'bad', cause: {} } }, + { 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() }) @@ -262,11 +264,13 @@ describe('runner launch inputs', () => { expect(runnerStdio({ ...spec, stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'pipe' }, - }, true)).toEqual(['ignore', 'ignore', 'ignore', 'ipc', 'ignore', 1, 'pipe']) + }, true)).toEqual(['ignore', 'ignore', 'ignore', 'ipc', 'pipe', 1, 'pipe']) }) 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' }) expect(validateTerminalTarget({ ...spec, rows: 24, cols: 80 })).toMatchObject({ EXPLICIT: 'yes' }) for (const invalid of [ { ...spec, argv: ['node\0'] }, @@ -410,7 +414,7 @@ describe('Linux one-shot exec bootstrap', () => { 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: 'spawn-error', error: { code: 'ENOENT', path: 'tool' }, + type: 'error', error: { code: 'ENOENT', path: 'tool' }, }) }) @@ -427,6 +431,40 @@ describe('Linux one-shot exec bootstrap', () => { '/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('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 () => { @@ -445,7 +483,7 @@ describe('Linux one-shot exec bootstrap', () => { ['/bin/sh', ['/bin/sh', '/work/bin/tool', 'literal arg'], { PATH: 'bin' }], ]) expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ - type: 'spawn-error', error: { code: 'EIO', path: 'tool' }, + type: 'error', error: { code: 'EIO', path: 'tool' }, }) }) @@ -454,7 +492,7 @@ describe('Linux one-shot exec bootstrap', () => { const execve = vi.fn((_file: string) => { throw Object.assign(new Error('denied'), { code: 'EACCES' }) }) 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: 'spawn-error', error: { code: 'EACCES' } }) + expect(readLinuxStartupError(files.startupErrorPath)).toMatchObject({ type: 'error', error: { code: 'EACCES' } }) const explicit = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) const fatal = vi.fn(() => { throw Object.assign(new Error('bad executable'), { code: 'EIO' }) }) @@ -466,7 +504,7 @@ describe('Linux one-shot exec bootstrap', () => { execve: vi.fn(() => { throw new Error('unclassified failure') }), })) expect(readLinuxStartupError(stackless.startupErrorPath)).toMatchObject({ - type: 'spawn-error', error: { message: 'unclassified failure' }, + type: 'error', error: { message: 'unclassified failure' }, }) const searched = track(createLinuxLaunchFiles({ cwd: '/work', env: {} })) @@ -477,20 +515,20 @@ describe('Linux one-shot exec bootstrap', () => { execve: searchedExecve as never, })) expect(readLinuxStartupError(searched.startupErrorPath)).toMatchObject({ - type: 'spawn-error', error: { code: 'EIO' }, + type: 'error', error: { code: 'EIO' }, }) }) - it('publishes request/protocol failures as runner errors', async () => { + 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: 'runner-error' }) + 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: 'runner-error', error: { message: 'delimiter failed' }, + type: 'error', error: { message: 'delimiter failed' }, }) }) }) @@ -500,7 +538,7 @@ describe('Windows Job runner protocol owner', () => { for (const [win32Code, code] of [ [3, 'ENOENT'], [267, 'ENOENT'], - [5, 'EACCES'], + [5, 'EPERM'], [193, 'EFTYPE'], [999, 'UNKNOWN'], ] as const) { @@ -508,7 +546,10 @@ describe('Windows Job runner protocol owner', () => { await runWindows(host, internals({ spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', win32Code) }), })) - expect(host.sent).toMatchObject([{ type: 'spawn-error', error: { code } }]) + expect(host.sent).toMatchObject([{ + type: 'error', + error: { code, ...win32Code === 5 ? { errno: -4048 } : {} }, + }]) } }) @@ -548,6 +589,7 @@ describe('Windows Job runner protocol owner', () => { ) 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) @@ -556,9 +598,9 @@ describe('Windows Job runner protocol owner', () => { 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, signal: null }]) + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) expect(host.exitCode).toBe(0) - expect(host.env).toEqual({ TARGET: 'yes', dsh_subprocess_runner: 'restored' }) + expect(host.env).toEqual({ SAFE: 'bootstrap' }) }) it('closes every target carrier before the first Windows poll', async () => { @@ -579,26 +621,26 @@ describe('Windows Job runner protocol owner', () => { }) await runWindows(host, native) expect(events).toEqual(['close:4', 'close:5', 'close:6', 'interval', 'poll']) - expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0, signal: null }]) + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) expect(host.exitCode).toBe(0) } finally { interval.mockRestore() } }) - it('exhausts spawn-error, runner-error, and payload-free start-cancelled', async () => { + it('exhausts target-exit, error, and payload-free start-cancelled', async () => { const spawnHost = new FakeRunnerHost() await runWindows(spawnHost, internals({ spawnCurrentTokenJobProcess: vi.fn(() => { throw new Win32Error('CreateProcessW', 2) }), })) - expect(spawnHost.sent).toMatchObject([{ type: 'spawn-error', error: { code: 'ENOENT', path: 'tool.exe' } }]) + 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: 'runner-error', error: { message: 'binding failed' } }]) + expect(runnerHost.sent).toMatchObject([{ type: 'error', error: { message: 'binding failed' } }]) expect(runnerHost.exitCode).toBe(127) const cancelledHost = new FakeRunnerHost() @@ -710,7 +752,7 @@ describe('Windows Job runner protocol owner', () => { await new Promise((resolveImmediate) => { setImmediate(resolveImmediate) }) failedHost.emit('message', { type: 'terminate' }) await failedRun - expect(failedHost.sent).toMatchObject([{ type: 'runner-error', error: { message: 'terminate Job failed' } }]) + expect(failedHost.sent).toMatchObject([{ type: 'error', error: { message: 'terminate Job failed' } }]) }) it('finishes when a later poll observes Job emptiness after result delivery', async () => { @@ -727,7 +769,7 @@ describe('Windows Job runner protocol owner', () => { ) host.emit('message', { type: 'start', cwd: 'C:\\target', env: {} }) await running - expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0, signal: null }]) + expect(host.sent).toEqual([{ type: 'target-exit', exitCode: 0 }]) expect(native.isJobEmpty).toHaveBeenCalledTimes(2) }) @@ -736,7 +778,7 @@ describe('Windows Job runner protocol owner', () => { await runWindows(failedHost, internals({ pollProcessExit: vi.fn(() => { throw new Error('poll failed') }), })) - expect(failedHost.sent).toMatchObject([{ type: 'runner-error', error: { message: '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) => { @@ -795,7 +837,7 @@ describe('Windows Job runner protocol owner', () => { 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: 'runner-error' }]) + expect(malformed.sent).toMatchObject([{ type: 'error' }]) const duplicate = new FakeRunnerHost() const native = internals({ pollProcessExit: vi.fn(() => undefined), isJobEmpty: vi.fn(() => false) }) @@ -803,7 +845,7 @@ describe('Windows Job runner protocol owner', () => { 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: 'runner-error' }]) + expect(duplicate.sent).toMatchObject([{ type: 'error' }]) const raced = new FakeRunnerHost() const racedRun = runSpawnRunner(WINDOWS_RUNNER_SELECTION, ['--', 'tool.exe'], hostArgument(raced), internals()) diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts index 9d78af0b4b..98008dad14 100644 --- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts +++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts @@ -313,11 +313,19 @@ describe('spawnSubprocess', () => { expect(result.signal).toBe(process.platform === 'win32' ? null : 'SIGTERM') }) - it('throws when the signal is already aborted before spawn', () => { - const controller = new AbortController() - controller.abort('too late') - expect(() => { validateSubprocessSpec(spec('echo hi', { signal: controller.signal })) }) - .toThrow(/aborted before spawn: too late/) + it('throws the raw signal reason when already aborted before spawn', () => { + for (const reason of ['too late', null] as const) { + const controller = new AbortController() + controller.abort(reason) + let thrown = false + try { + validateSubprocessSpec(spec('echo hi', { signal: controller.signal })) + } catch (error) { + thrown = true + expect(error).toBe(reason) + } + expect(thrown).toBe(true) + } }) it('rejects with a spawn error for a nonexistent cwd', async () => { @@ -778,6 +786,54 @@ 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('keeps an infrastructure failure authoritative when it precedes the direct result', async () => { + const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() + const infrastructureFailure = Promise.withResolvers() + const failure = new Error('runner failed before its result') + const handle = bindManagedProcess(spec('true', { + stdio: { stdin: 'ignore', stdout: 'inherit', stderr: 'inherit' }, + }), { + stdin: null, + stdout: null, + stderr: null, + direct: direct.promise, + infrastructureFailure: infrastructureFailure.promise, + owner: { + signal: vi.fn(), + waitForExit: async () => {}, + terminateForHostExit: vi.fn(), + }, + }) + + infrastructureFailure.reject(failure) + await expect(handle.done).rejects.toBe(failure) + direct.resolve({ exitCode: 0, signal: null }) + await Promise.resolve() + await expect(handle.done).rejects.toBe(failure) + }) + it('cleans a managed owner after direct settlement and contains a later infrastructure failure', async () => { const direct = Promise.withResolvers<{ exitCode: number; signal: null }>() const stopped = Promise.withResolvers() @@ -887,7 +943,7 @@ describe('coverage seams', () => { }) it('delivers an already-aborted managed spawn reason before target settlement', async () => { - const reason = new Error('caller cancelled') + const reason = null const controller = new AbortController() controller.abort(reason) const signal = vi.fn() @@ -1216,17 +1272,21 @@ 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('throws an undefined reason from a reason-less pre-aborted signal unchanged', () => { const bare = { aborted: true, reason: undefined, addEventListener() {}, removeEventListener() {}, } as unknown as AbortSignal - expect(() => { validateSubprocessSpec(spec('echo hi', { signal: bare })) }) - .toThrow(/aborted before spawn: aborted/) + let thrown = false + try { + validateSubprocessSpec(spec('echo hi', { signal: bare })) + } catch (error) { + thrown = true + expect(error).toBeUndefined() + } + expect(thrown).toBe(true) }) 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 e4b79ca2a4..97d35c1c97 100644 --- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts +++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts @@ -220,14 +220,15 @@ describe('LocalTerminalHandle', () => { expect(pty.kills).toEqual([]) }) - it('rejects managed outcome conversion and cleans its protocol after exit', async () => { + 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 cleanupManagedProtocol = vi.fn() + const cleanup = vi.fn() const owner: BoundProcessOwner = { signal: vi.fn(), waitForExit: async () => {}, terminateForHostExit: vi.fn(), + cleanup, } const handle = new LocalTerminalHandle( pty.asPty(), @@ -236,13 +237,33 @@ describe('LocalTerminalHandle', () => { 'linux', owner, () => { throw failure }, - cleanupManagedProtocol, ) pty.emitExit() await expect(handle.done).rejects.toBe(failure) await expect(handle.terminate()).resolves.toBeUndefined() - await vi.waitFor(() => { expect(cleanupManagedProtocol).toHaveBeenCalledOnce() }) + 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 () => { diff --git a/packages/subprocess/subprocess-local/tests/windows-job.spec.ts b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts index fc268d159c..8e58b3492f 100644 --- a/packages/subprocess/subprocess-local/tests/windows-job.spec.ts +++ b/packages/subprocess/subprocess-local/tests/windows-job.spec.ts @@ -22,11 +22,15 @@ class FakeChild extends EventEmitter { sendError: Error | undefined throwOnSendCall: number | undefined sendThrown: unknown = new Error('send threw') + stdinDestroyedAtStart: boolean | undefined private sendCalls = 0 send(message: unknown, callback?: (error: Error | null) => void): boolean { this.sendCalls += 1 if (this.sendCalls === this.throwOnSendCall) throw this.sendThrown + if ((message as { type?: string }).type === 'start') { + this.stdinDestroyedAtStart = this.targetStdin.destroyed + } this.sent.push(message) queueMicrotask(() => { callback?.(this.sendError ?? null) }) return true @@ -45,9 +49,12 @@ const spec = { graceMs: 100, } as const -function launch(child = new FakeChild()) { +function launch( + child = new FakeChild(), + request: Parameters[0] = spec, +) { const spawn = vi.fn(() => child) - const result = launchWindowsJob(spec, { TARGET: 'yes' }, { + const result = launchWindowsJob(request, { TARGET: 'yes' }, { spawn: spawn as never, runnerInvocation: ['C:\\node.exe', 'C:\\runner.js'], }) @@ -77,7 +84,7 @@ describe('Windows Job capability', () => { const result = isolated.launchWindowsJob(spec, { TARGET: 'yes' }) expect(spawn).toHaveBeenCalledOnce() - child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) + 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 }) @@ -134,29 +141,46 @@ describe('Windows parent runner contract', () => { expect(result.stderr).toBe(child.targetStderr) }) + it('always carries fd 4 and closes ignored stdin before sending start', () => { + 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', 'pipe', 'pipe', 2], + })) + expect(child.stdinDestroyedAtStart).toBe(true) + expect(result.stdin).toBeNull() + }) + 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, signal: null }) + 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('rejects done when runner failure precedes stdio settlement', async () => { + 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, signal: null }) + child.emit('message', { type: 'target-exit', exitCode: 7 }) await Promise.resolve() child.connected = false child.emit('close', 127, null) - await expect(handle.done).rejects.toThrow('exit code 127') + 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 spawn-error and start-cancelled without requiring public target identity', async () => { + it('maps error and preserves raw start-cancellation reasons', async () => { const spawned = launch() spawned.child.emit('message', { - type: 'spawn-error', error: { name: 'Error', message: 'missing', code: 'ENOENT' }, + type: 'error', error: { name: 'Error', message: 'missing', code: 'ENOENT' }, }) await expect(spawned.result.direct).rejects.toMatchObject({ code: 'ENOENT' }) spawned.child.connected = false @@ -173,6 +197,15 @@ describe('Windows parent runner contract', () => { 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: 'start-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.child.emit('message', { type: 'start-cancelled' }) await expect(implicit.result.direct).rejects.toThrow('target start was cancelled') @@ -181,10 +214,10 @@ describe('Windows parent runner contract', () => { await expect(implicit.result.owner.waitForExit()).resolves.toBeUndefined() }) - it('rejects direct and wait for runner-error or abnormal runner exit', async () => { + it('rejects direct and wait for runner error or abnormal runner exit', async () => { const failed = launch() failed.child.emit('message', { - type: 'runner-error', error: { name: 'Error', message: 'Job assignment failed' }, + type: 'error', error: { name: 'Error', message: 'Job assignment failed' }, }) await expect(failed.result.direct).rejects.toThrow('Job assignment failed') failed.child.connected = false @@ -205,13 +238,13 @@ describe('Windows parent runner contract', () => { 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, signal: null }) + malformed.child.emit('message', { type: 'target-exit', exitCode: -1 }) expect(malformed.child.killed).toEqual(['SIGKILL']) await expect(malformed.result.infrastructureFailure).rejects.toThrow('invalid target-exit') const duplicate = launch() - duplicate.child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) - duplicate.child.emit('message', { type: 'target-exit', exitCode: 0, signal: null }) + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0 }) + duplicate.child.emit('message', { type: 'target-exit', exitCode: 0 }) await expect(duplicate.result.infrastructureFailure).rejects.toThrow('more than one direct result') duplicate.child.connected = false duplicate.child.emit('close', 127, null) @@ -240,8 +273,8 @@ describe('Windows parent runner contract', () => { nonError.throwOnSendCall = 1 nonError.sendThrown = 'start send failed' const nonErrorResult = launch(nonError).result - await expect(nonErrorResult.direct).rejects.toThrow('start send failed') - await expect(nonErrorResult.infrastructureFailure).rejects.toThrow('start send failed') + await expect(nonErrorResult.direct).rejects.toBe('start send failed') + await expect(nonErrorResult.infrastructureFailure).rejects.toBe('start send failed') }) it('fails infrastructure and kills the runner when termination delivery fails', async () => { @@ -260,7 +293,7 @@ describe('Windows parent runner contract', () => { throwingChild.sendThrown = 'terminate send threw' const throwing = launch(throwingChild) throwing.result.owner.signal('SIGTERM') - await expect(throwing.result.infrastructureFailure).rejects.toThrow('terminate send threw') + await expect(throwing.result.infrastructureFailure).rejects.toBe('terminate send threw') expect(throwing.child.killed).toEqual(['SIGKILL']) const errorChild = new FakeChild() diff --git a/packages/subprocess/win32-process/README.i18n.yaml b/packages/subprocess/win32-process/README.i18n.yaml index de6dd4a638..4f85e01409 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: 1affe4e0ba0622be02edc6f06f1c6dd88b24a60c -README.zh.md: 6d908142cc6e721c40225773c14dcdd07e196e50 +README.md: d2c17f79e839b5ebba09a76f6f45bd3b19f8724f +README.zh.md: da639d75ec824cf45319baf83c6194ab80ef80d0 diff --git a/packages/subprocess/win32-process/README.md b/packages/subprocess/win32-process/README.md index 1affe4e0ba..d2c17f79e8 100644 --- a/packages/subprocess/win32-process/README.md +++ b/packages/subprocess/win32-process/README.md @@ -24,11 +24,11 @@ This low-level Win32 process library is consumed by the Windows ACL sandbox and ## Behavior -- **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`, `advapi32.dll`, and `ucrtbase.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. -- **Ordinary Job runner primitive** — `CurrentTokenProcessSpawnOptions.stdio` names three runner CRT descriptors dedicated to target stdin, stdout, and stderr. `spawnCurrentTokenJobProcess()` resolves their OS handles through UCRT `_get_osfhandle`, temporarily marks those handles inheritable, passes them through `STARTF_USESTDHANDLES`, creates the target suspended through `CreateProcessW`, assigns it to an unnamed kill-on-close Job, and resumes it only after assignment. A separately resolved `applicationName` preserves Node's executable search without changing the original command-line argv entry. It returns the direct-process handle and Job to the runner, which can close its carrier descriptors without touching Node's own standard streams. +- **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()` calls `GetStartupInfoW`, strictly decodes libuv's `cbReserved2`/`lpReserved2` descriptor table to recover the three OS handles, temporarily marks them 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. @@ -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 additionally fixes the basic Job accounting record size and `ActiveProcesses` offset used to determine quiescence; it 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 the `STARTUPINFOW` reserved-table offsets, pointer and handle widths, 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 @@ -68,7 +68,7 @@ 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 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 6d908142cc..da639d75ec 100644 --- a/packages/subprocess/win32-process/README.zh.md +++ b/packages/subprocess/win32-process/README.zh.md @@ -24,11 +24,11 @@ kind: "package-library" ## Behavior -- **唯一可复用 ABI owner** — `abi.ts` 拥有两条 process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll`、`advapi32.dll` 与 `ucrtbase.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。 -- **ordinary Job runner 原语** — `CurrentTokenProcessSpawnOptions.stdio` 指定三个专用于 target stdin、stdout 与 stderr 的 runner CRT 描述符。`spawnCurrentTokenJobProcess()` 通过 UCRT `_get_osfhandle` 解析对应 OS handle,临时把这些 handle 设为可继承,通过 `STARTF_USESTDHANDLES` 传入它们,再以 suspended 状态通过 `CreateProcessW` 创建 target、把它分配给 unnamed kill-on-close Job,并只在分配后恢复。单独解析的 `applicationName` 保留 Node 的 executable 搜索语义,同时不改变原始命令行 argv 项。它把 direct-process handle 与 Job 返回给 runner,后者可以关闭自己的 carrier 描述符,而不触碰 Node 自身的标准流。 +- **ordinary Job runner 原语** — `CurrentTokenProcessSpawnOptions` 要求已解析的 `applicationName`、完整 target 环境,以及三个专用于 target stdin、stdout 与 stderr 的 runner CRT 描述符。`spawnCurrentTokenJobProcess()` 调用 `GetStartupInfoW`,严格解码 libuv 的 `cbReserved2`/`lpReserved2` 描述符表以取得三个 OS 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。 @@ -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 位大小。该探针还固定用于判断停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移;其余已记录偏移和常量也由该探针提供证据。 +Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小。该探针还固定 `STARTUPINFOW` 保留表偏移、指针与 handle 宽度、Unicode 环境标志,以及用于判断停稳的基础 Job accounting record 大小与 `ActiveProcesses` 偏移;其余已记录偏移和常量也由该探针提供证据。 ## Model Experience @@ -68,7 +68,7 @@ Koffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载 - **仅在 Windows 原生加载** — 导入通用类型可跨平台进行,但解析绑定表会加载 Windows DLL,并在其他宿主失败。跨平台测试注入绑定表,不加载原生 API。 - **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node streams。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。 -- **只继承环境** — 进程创建传入空环境块。sandbox 会先通过 `SetEnvironmentVariableW` 建立改动,因为经 Koffi 传入显式环境块会使 `CreateProcessAsUserW` 以 `ERROR_INVALID_PARAMETER` 失败。其他需要改写环境的调用方必须在调用原语前建立环境,或使用自己的 runner 进程。 +- **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/src/abi.ts b/packages/subprocess/win32-process/src/abi.ts index d3b2eafcb4..3a9eb6ee60 100644 --- a/packages/subprocess/win32-process/src/abi.ts +++ b/packages/subprocess/win32-process/src/abi.ts @@ -10,6 +10,8 @@ export const INFINITE = 0xFFFFFFFF 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. */ @@ -44,3 +46,11 @@ export const JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET = 16 export const STARTUPINFOW_SIZE = 104 /** x64 PROCESS_INFORMATION byte size verified by the native probe. */ export const PROCESS_INFORMATION_SIZE = 24 +/** libuv CRT descriptor flag marking an inherited descriptor as open. */ +export const CRT_FOPEN = 0x01 +/** Largest descriptor count accepted by libuv's inherited stdio table. */ +export const MAX_INHERITED_STDIO_DESCRIPTORS = 256 +/** Byte width of the descriptor count at the start of libuv's stdio table. */ +export const INHERITED_STDIO_COUNT_SIZE = 4 +/** x64 HANDLE width in libuv's inherited stdio table. */ +export const INHERITED_STDIO_HANDLE_SIZE = 8 diff --git a/packages/subprocess/win32-process/src/ffi.ts b/packages/subprocess/win32-process/src/ffi.ts index 2664d9b130..a9ec2c3f92 100644 --- a/packages/subprocess/win32-process/src/ffi.ts +++ b/packages/subprocess/win32-process/src/ffi.ts @@ -18,8 +18,6 @@ export interface Win32BindingContext { readonly kernel32: ReturnType /** Token and security APIs. */ readonly advapi32: ReturnType - /** Universal CRT file-descriptor operations. */ - readonly ucrtbase: ReturnType /** Bind one stdcall function from a loaded Win32 library. */ readonly bind: ( library: ReturnType, @@ -55,6 +53,12 @@ export interface ProcessInfoOutput { dwThreadId: number } +/** STARTUPINFOW fields used to recover libuv's inherited descriptor table. */ +export interface StartupInfoOutput { + cbReserved2: number + lpReserved2: NativePtr | null +} + /** Generic Win32 calls consumed by restricted-token sandbox process operations. */ export interface Win32ProcessBindings { closeHandle(handle: NativePtr): number @@ -90,7 +94,7 @@ export interface Win32ProcessBindings { threadAttributes: null, inheritHandles: number, creationFlags: number, - environment: null, + environment: Buffer | null, currentDirectory: string | null, startupInfo: NativePtr, processInfo: NativePtr, @@ -122,9 +126,9 @@ export interface Win32ProcessBindings { getStdHandle(stdHandle: number): NativePtr } -/** Generic Win32 calls plus current-process CRT descriptor lookup. */ +/** Generic Win32 calls plus the inherited startup-information reader. */ export interface CurrentTokenProcessBindings extends Win32ProcessBindings { - getOsfHandle(fileDescriptor: number): number | bigint + getStartupInfoW(startupInfo: NativePtr): void } /** Koffi STARTUPINFOW layout. */ @@ -218,6 +222,15 @@ export function encodeStartupInfo(startupInfo: NativePtr, fields: StartupInfoInp koffi.encode(startupInfo, STARTUPINFOW, fields) } +/** + * Decode the inherited-descriptor fields from STARTUPINFOW. + * @param startupInfo - struct filled by GetStartupInfoW. + * @returns reserved buffer size and pointer. + */ +export function decodeStartupInfo(startupInfo: NativePtr): StartupInfoOutput { + return koffi.decode(startupInfo, STARTUPINFOW) as StartupInfoOutput +} + /** * Allocate a zeroed PROCESS_INFORMATION. * @returns allocated struct pointer. @@ -243,20 +256,19 @@ function bindingContext(): Win32BindingContext { if (cachedContext !== undefined) return cachedContext const kernel32 = koffi.load('kernel32.dll') const advapi32 = koffi.load('advapi32.dll') - const ucrtbase = koffi.load('ucrtbase.dll') const bind = ( lib: ReturnType, name: string, result: Ptr | string, args: Array, ): unknown => lib.func('__stdcall', name, result, args) - cachedContext = { kernel32, advapi32, ucrtbase, bind } + cachedContext = { kernel32, advapi32, bind } return cachedContext } function bindings(): CurrentTokenProcessBindings { if (cached !== undefined) return cached - const { kernel32, advapi32, ucrtbase, bind } = bindingContext() + const { kernel32, advapi32, bind } = bindingContext() cached = { closeHandle: bind(kernel32, 'CloseHandle', 'int', [PVOID]), getLastError: bind(kernel32, 'GetLastError', 'uint32', []), @@ -289,7 +301,7 @@ function bindings(): CurrentTokenProcessBindings { terminateProcess: bind(kernel32, 'TerminateProcess', 'int', [PVOID, 'uint32']), terminateJobObject: bind(kernel32, 'TerminateJobObject', 'int', [PVOID, 'uint32']), getStdHandle: bind(kernel32, 'GetStdHandle', PVOID, ['int']), - getOsfHandle: ucrtbase.func('_get_osfhandle', 'intptr_t', ['int']), + getStartupInfoW: bind(kernel32, 'GetStartupInfoW', 'void', [koffi.pointer(STARTUPINFOW)]), } as unknown as CurrentTokenProcessBindings return cached } diff --git a/packages/subprocess/win32-process/src/process.ts b/packages/subprocess/win32-process/src/process.ts index ad37f9abce..340044f742 100644 --- a/packages/subprocess/win32-process/src/process.ts +++ b/packages/subprocess/win32-process/src/process.ts @@ -9,6 +9,7 @@ import { allocUint32, decodeProcessInfo, decodePtr, + decodeStartupInfo, decodeUint32, encodeStartupInfo, isNullPtr, @@ -53,6 +54,19 @@ export function buildCommandLine(program: string, args: readonly string[]): stri return [program, ...args].map(quoteArg).join(' ') } +function compareWindowsEnvironmentKeys( + [left]: readonly [string, string], + [right]: readonly [string, string], +): number { + return left.toUpperCase().localeCompare(right.toUpperCase(), 'en-US') +} + +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 @@ -65,7 +79,9 @@ interface ProcessSpawnOptions { /** 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 + applicationName: string + /** Complete target environment passed without mutating the runner. */ + env: Readonly> /** Runner CRT descriptors carrying target stdin, stdout, and stderr. */ stdio: CurrentTokenStdioFileDescriptors } @@ -357,10 +373,48 @@ function targetCarrierHandles( api: CurrentTokenProcessBindings, descriptors: CurrentTokenStdioFileDescriptors, ): ProcessStandardHandles { + let startupInfo: NativePtr | undefined + let table: Buffer + try { + startupInfo = allocStartupInfo() + api.getStartupInfoW(startupInfo) + const inherited = decodeStartupInfo(startupInfo) + if (isNullPtr(inherited.lpReserved2)) { + throw new Error('GetStartupInfoW returned no inherited stdio table') + } + if (inherited.cbReserved2 < abi.INHERITED_STDIO_COUNT_SIZE) { + throw new Error('GetStartupInfoW returned a truncated inherited stdio table') + } + table = Buffer.from(koffi.view(inherited.lpReserved2, inherited.cbReserved2)) + } finally { + freeNative(startupInfo) + } + const count = table.readUInt32LE(0) + if (count > abi.MAX_INHERITED_STDIO_DESCRIPTORS) { + throw new Error(`inherited stdio table declares unsupported descriptor count ${String(count)}`) + } + const requiredSize = abi.INHERITED_STDIO_COUNT_SIZE + + count + + count * abi.INHERITED_STDIO_HANDLE_SIZE + if (table.length < requiredSize) { + throw new Error('GetStartupInfoW returned a truncated inherited stdio table') + } const get = (fileDescriptor: number, label: string): NativePtr => { - const handle = api.getOsfHandle(fileDescriptor) - if (handle !== -1 && handle !== -1n) return BigInt(handle) as NativePtr - throw new Error(`_get_osfhandle failed for target ${label} fd ${String(fileDescriptor)}`) + if (fileDescriptor >= count) { + throw new Error(`inherited stdio table is missing target ${label} fd ${String(fileDescriptor)}`) + } + const flags = table[abi.INHERITED_STDIO_COUNT_SIZE + fileDescriptor] as number + if ((flags & abi.CRT_FOPEN) === 0) { + throw new Error(`inherited stdio table marks target ${label} fd ${String(fileDescriptor)} closed`) + } + const handleOffset = abi.INHERITED_STDIO_COUNT_SIZE + + count + + fileDescriptor * abi.INHERITED_STDIO_HANDLE_SIZE + const handle = table.readBigUInt64LE(handleOffset) + if (handle === 0n || handle === 0xFFFFFFFFFFFFFFFFn || handle === 0xFFFFFFFFFFFFFFFEn) { + throw new Error(`inherited stdio table contains an invalid handle for target ${label} fd ${String(fileDescriptor)}`) + } + return handle as NativePtr } return { stdin: get(descriptors.stdin, 'stdin'), @@ -496,15 +550,16 @@ export function spawnCurrentTokenJobProcess( 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 ?? null, + options.applicationName, commandLine, null, null, 1, - abi.CREATE_SUSPENDED, - null, + abi.CREATE_SUSPENDED | abi.CREATE_UNICODE_ENVIRONMENT, + environment, options.cwd, startupInfo, processInfo, @@ -516,8 +571,8 @@ export function spawnCurrentTokenJobProcess( * @param api - active binding table. */ export function probeCurrentTokenJobSupport(api: CurrentTokenProcessBindings): void { - if (typeof api.getOsfHandle !== 'function') { - throw new Error('current-token Job support requires UCRT _get_osfhandle') + if (typeof api.getStartupInfoW !== 'function') { + throw new Error('current-token Job support requires GetStartupInfoW') } const job = createKillOnCloseJob(api) closeHandleChecked(api, job, 'current-token Job capability probe') diff --git a/packages/subprocess/win32-process/tests/ordinary-process.spec.ts b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts index 7885782548..5aa6b3e1f8 100644 --- a/packages/subprocess/win32-process/tests/ordinary-process.spec.ts +++ b/packages/subprocess/win32-process/tests/ordinary-process.spec.ts @@ -11,6 +11,10 @@ import { } from '../src/index.ts' import { CREATE_SUSPENDED, + CREATE_UNICODE_ENVIRONMENT, + CRT_FOPEN, + INHERITED_STDIO_COUNT_SIZE, + INHERITED_STDIO_HANDLE_SIZE, JOBOBJECT_BASIC_ACCOUNTING_ACTIVE_PROCESSES_OFFSET, JOBOBJECT_BASIC_ACCOUNTING_SIZE, JobObjectBasicAccountingInformation, @@ -18,11 +22,51 @@ import { } from '../src/abi.ts' import { PROCESS_INFORMATION, STARTUPINFOW } from '../src/ffi.ts' import type { + CurrentTokenProcessSpawnOptions, CurrentTokenProcessBindings, NativePtr, } from '../src/index.ts' +function inheritedStdioTable(count = 7): Buffer { + const table = Buffer.alloc( + INHERITED_STDIO_COUNT_SIZE + count + count * INHERITED_STDIO_HANDLE_SIZE, + ) + table.writeUInt32LE(count, 0) + for (let fileDescriptor = 0; fileDescriptor < count; fileDescriptor++) { + table[INHERITED_STDIO_COUNT_SIZE + fileDescriptor] = CRT_FOPEN + table.writeBigUInt64LE( + BigInt(100 + fileDescriptor), + INHERITED_STDIO_COUNT_SIZE + count + fileDescriptor * INHERITED_STDIO_HANDLE_SIZE, + ) + } + return table +} + +function startupInfo( + table: Buffer | null, + size = table?.length ?? 0, +): CurrentTokenProcessBindings['getStartupInfoW'] { + return vi.fn((startup: NativePtr) => { + koffi.encode(startup, STARTUPINFOW, { cbReserved2: size, lpReserved2: table }) + }) +} + +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 { + const table = inheritedStdioTable() return { createJobObjectW: vi.fn(() => 50n), setInformationJobObject: vi.fn(() => 1), @@ -31,7 +75,7 @@ function api(overrides: Partial = {}): CurrentToken return 1 }), getStdHandle: vi.fn((selector: number) => BigInt(100 - selector)), - getOsfHandle: vi.fn((fileDescriptor: number) => BigInt(67 + fileDescriptor)), + getStartupInfoW: startupInfo(table), setHandleInformation: vi.fn(() => 1), createProcessW: vi.fn((_app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, _startup, info) => { koffi.encode(info, PROCESS_INFORMATION, { @@ -83,25 +127,24 @@ describe('ordinary Job process operations', () => { resumeThread: vi.fn(() => { events.push('resume'); return 0 }), closeHandle: vi.fn((handle: NativePtr) => { events.push(`close:${handle}`); return 1 }), }) - expect(spawnCurrentTokenJobProcess(bindings, { - command: 'probe.exe', - applicationName: 'C:\\resolved\\probe.exe', + expect(spawnCurrentTokenJobProcess(bindings, options({ args: ['literal $VALUE', 'a b'], - cwd: 'C:\\work', - stdio: { stdin: 4, stdout: 5, stderr: 6 }, - })).toEqual({ pid: 1234, process: 60n, job: 50n }) + env: { ZED: 'last', '=C:': 'C:\\work', alpha: 'first' }, + }))).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, - null, + CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT, + environment, 'C:\\work', expect.anything(), expect.anything(), ) + expect(environment.toString('utf16le')).toBe('=C:=C:\\work\0alpha=first\0ZED=last\0\0') expect(events.indexOf('create')).toBeLessThan(events.indexOf('assign')) expect(events.indexOf('assign')).toBeLessThan(events.indexOf('resume')) expect(events).toContain('close:61') @@ -111,12 +154,7 @@ describe('ordinary Job process operations', () => { const bindings = api({ createProcessW: vi.fn(() => 0) }) let caught: unknown try { - spawnCurrentTokenJobProcess(bindings, { - command: 'missing.exe', - args: [], - cwd: 'C:\\work', - stdio: { stdin: 4, stdout: 5, stderr: 6 }, - }) + spawnCurrentTokenJobProcess(bindings, options({ command: 'missing.exe' })) } catch (error) { caught = error } @@ -125,10 +163,8 @@ describe('ordinary Job process operations', () => { it('resolves the target carrier descriptors and restores their handle flags', () => { let startup: Record | undefined - const getOsfHandle = vi.fn((fileDescriptor: number) => BigInt(67 + fileDescriptor)) const setHandleInformation = vi.fn(() => 1) const bindings = api({ - getOsfHandle, setHandleInformation, createProcessW: vi.fn((_app, _line, _pa, _ta, _inherit, _flags, _env, _cwd, infoPtr, processInfo) => { startup = koffi.decode(infoPtr, STARTUPINFOW) as Record @@ -141,17 +177,11 @@ describe('ordinary Job process operations', () => { return 1 }), }) - expect(spawnCurrentTokenJobProcess(bindings, { - command: 'probe.exe', - args: [], - cwd: 'C:\\work', - stdio: { stdin: 4, stdout: 5, stderr: 6 }, - })).toEqual({ pid: 1234, process: 60n, job: 50n }) - expect(getOsfHandle.mock.calls.map(([fileDescriptor]) => fileDescriptor)).toEqual([4, 5, 6]) - expect(startup).toMatchObject({ hStdInput: 71n, hStdOutput: 72n, hStdError: 73n }) + expect(spawnCurrentTokenJobProcess(bindings, options())).toEqual({ pid: 1234, process: 60n, job: 50n }) + expect(startup).toMatchObject({ hStdInput: 104n, hStdOutput: 105n, hStdError: 106n }) expect(setHandleInformation.mock.calls).toEqual([ - [71n, 1, 1], [72n, 1, 1], [73n, 1, 1], - [71n, 1, 0], [72n, 1, 0], [73n, 1, 0], + [104n, 1, 1], [105n, 1, 1], [106n, 1, 1], + [104n, 1, 0], [105n, 1, 0], [106n, 1, 0], ]) }) @@ -211,19 +241,44 @@ describe('ordinary Job process operations', () => { expect(closeHandle).toHaveBeenCalledExactlyOnceWith(50n) }) - it('rejects an unavailable carrier descriptor or CRT binding before target creation', () => { - const closeHandle = vi.fn(() => 1) - const missingDescriptor = api({ closeHandle, getOsfHandle: vi.fn(() => -1) }) - expect(() => spawnCurrentTokenJobProcess(missingDescriptor, { - command: 'probe.exe', - args: [], - cwd: 'C:\\work', - stdio: { stdin: 4, stdout: 5, stderr: 6 }, - })).toThrow('_get_osfhandle failed for target stdin fd 4') - expect(closeHandle).toHaveBeenCalledWith(50n) + it('strictly validates the inherited libuv descriptor table before target creation', () => { + const expectFailure = ( + getStartupInfoW: CurrentTokenProcessBindings['getStartupInfoW'], + message: string, + ): void => { + const closeHandle = vi.fn(() => 1) + expect(() => spawnCurrentTokenJobProcess(api({ closeHandle, getStartupInfoW }), options())) + .toThrow(message) + expect(closeHandle).toHaveBeenCalledWith(50n) + } - const missingBinding = api({ getOsfHandle: undefined as never }) + expectFailure(startupInfo(null), 'no inherited stdio table') + expectFailure(startupInfo(Buffer.alloc(3)), 'truncated inherited stdio table') + + const excessive = Buffer.alloc(INHERITED_STDIO_COUNT_SIZE) + excessive.writeUInt32LE(257, 0) + expectFailure(startupInfo(excessive), 'unsupported descriptor count 257') + + const truncated = Buffer.alloc(INHERITED_STDIO_COUNT_SIZE) + truncated.writeUInt32LE(7, 0) + expectFailure(startupInfo(truncated), 'truncated inherited stdio table') + expectFailure(startupInfo(inheritedStdioTable(6)), 'missing target stderr fd 6') + + const closed = inheritedStdioTable() + closed[INHERITED_STDIO_COUNT_SIZE + 4] = 0 + expectFailure(startupInfo(closed), 'marks target stdin fd 4 closed') + + for (const invalid of [0n, 0xFFFFFFFFFFFFFFFFn, 0xFFFFFFFFFFFFFFFEn]) { + const table = inheritedStdioTable() + table.writeBigUInt64LE( + invalid, + INHERITED_STDIO_COUNT_SIZE + 7 + 4 * INHERITED_STDIO_HANDLE_SIZE, + ) + expectFailure(startupInfo(table), 'invalid handle for target stdin fd 4') + } + + const missingBinding = api({ getStartupInfoW: undefined as never }) expect(() => { probeCurrentTokenJobSupport(missingBinding) }) - .toThrow('current-token Job support requires UCRT _get_osfhandle') + .toThrow('current-token Job support requires GetStartupInfoW') }) }) diff --git a/packages/subprocess/win32-process/verify/abi-probe.cpp b/packages/subprocess/win32-process/verify/abi-probe.cpp index 3cbb883ccf..6e1d4b4e60 100644 --- a/packages/subprocess/win32-process/verify/abi-probe.cpp +++ b/packages/subprocess/win32-process/verify/abi-probe.cpp @@ -10,6 +10,8 @@ int wmain() P(sizeof(HANDLE)); P(sizeof(STARTUPINFOW)); P(offsetof(STARTUPINFOW, dwFlags)); + P(offsetof(STARTUPINFOW, cbReserved2)); + P(offsetof(STARTUPINFOW, lpReserved2)); P(offsetof(STARTUPINFOW, hStdInput)); P(offsetof(STARTUPINFOW, hStdOutput)); P(offsetof(STARTUPINFOW, hStdError)); @@ -18,6 +20,7 @@ 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); @@ -40,7 +43,10 @@ int wmain() static_assert(sizeof(STARTUPINFOW) == 104, "STARTUPINFOW size"); static_assert(sizeof(PROCESS_INFORMATION) == 24, "PROCESS_INFORMATION size"); + static_assert(sizeof(int) == 4, "libuv stdio descriptor count size"); + static_assert(sizeof(HANDLE) == 8, "libuv stdio 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"); diff --git a/packages/typert/generator/tests/cordis-catalog.spec.ts b/packages/typert/generator/tests/cordis-catalog.spec.ts index 3a8dca4a38..240aeab248 100644 --- a/packages/typert/generator/tests/cordis-catalog.spec.ts +++ b/packages/typert/generator/tests/cordis-catalog.spec.ts @@ -80,8 +80,7 @@ describe('Typert-backed Cordis catalog', () => { ) } } - const runtimeApi = projector.renderRuntimeApi(model) - expect(runtimeApi).toBe( + expect(projector.renderRuntimeApi(model)).toBe( expected('packages/extensions/tool-cordis/src/api-catalog.ts'), ) }) diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index e4ea8485c6..b34496db90 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -1375,13 +1375,14 @@ 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', 'pipe', 'pipe', 'ipc'], + stdio: ['ignore', 'ignore', 'ignore', 'ipc', 'pipe', 'pipe', 'pipe'], }) const messages = [] let stdout = '' let stderr = '' -child.stdout.on('data', chunk => { stdout += chunk.toString() }) -child.stderr.on('data', chunk => { stderr += chunk.toString() }) +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) @@ -1416,7 +1417,7 @@ process.stdout.write(JSON.stringify({ ...result, messages, stdout, stderr })) expected = { "exitCode": 0, "signal": None, - "messages": [{"type": "target-exit", "exitCode": 7, "signal": None}], + "messages": [{"type": "target-exit", "exitCode": 7}], "stdout": "", "stderr": "", }