docs(subagent): qualify ACP cleanup failure

This commit is contained in:
pku-xht 2026-08-21 07:38:48 +08:00
parent 075108dc08
commit d90003b4e0
4 changed files with 8 additions and 7 deletions

View file

@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/subagent/subagent-acp/README.md
README.md: 00f084c8252c001d98d04c8ccc1dff5f14976683
README.zh.md: 3b820805d23b39757376edc14a3d75860f2e8eae
README.md: 93a1578ac060a0493f52da5f85372039333eb5dc
README.zh.md: fd7da81f7202406099b815ff3122454637aa87fb

View file

@ -6,7 +6,7 @@ The ACP provider runs each subagent in a fresh subprocess and drives it as an Ag
## Start and ownership
`start(request)` resolves the child's working directory, then performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped; a working-directory resolution failure rejects before anything is spawned. Non-cancellation rejections expose only fixed provider, stage, and category facts in their Error message; the original failure remains on the internal cause chain and in Host diagnostics.
`start(request)` resolves the child's working directory, then performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure ordinarily rejects after the subprocess is reaped; when cleanup itself rejects, ordered safe startup/teardown facts preserve both failures without claiming process exit. A working-directory resolution failure rejects before anything is spawned. Non-cancellation rejections expose only fixed provider, stage, and category facts in their Error message; the original failure remains on the internal cause chain and in Host diagnostics.
The working directory is the configured `cwd` override when set, else the delegating parent session's cwd — never the server process's own cwd, because one server process serves sessions from many workspaces. The parent-derived value must be an absolute path naming a directory the harness can enter (search permission — what a subprocess cwd needs), and the same resolved path becomes both the subprocess cwd and the ACP `session/new` workspace.

View file

@ -6,7 +6,7 @@ ACP(Agent Client Protocol)提供方会在全新的子进程中运行每个 s
## 启动与所有权
`start(request)` 先解析子 agent 的工作目录,再依次执行 `spawn` → ACP `initialize` → `newSession`,然后才兑现。因此,兑现表示远程会话已就绪,所有权也已转移给调用方。spawn 失败、初始化失败、新建会话失败或因发布前取消而失败时,只有在子进程已回收后才会拒绝;工作目录解析失败则会在尚未 spawn 任何进程时拒绝。非取消拒绝的 Error 消息只公开固定的 provider、stage 与 category 事实;原始失败仍保留在内部 cause 链和 Host 诊断中。
`start(request)` 先解析子 agent 的工作目录,再依次执行 `spawn` → ACP `initialize` → `newSession`,然后才兑现。因此,兑现表示远程会话已就绪,所有权也已转移给调用方。spawn 失败、初始化失败、新建会话失败或因发布前取消而失败时,通常会在子进程已回收后拒绝;若清理自身也拒绝,有序的安全 startup/teardown 事实会保留两项失败,但不会宣称进程已经退出。工作目录解析失败则会在尚未 spawn 任何进程时拒绝。非取消拒绝的 Error 消息只公开固定的 provider、stage 与 category 事实;原始失败仍保留在内部 cause 链和 Host 诊断中。
工作目录优先使用已配置的 `cwd` 覆盖值,否则使用执行委派的父会话 cwd,绝不使用服务器进程自身的 cwd,因为同一个服务器进程会服务来自多个工作区的会话。从父级取得的值必须是绝对路径,指向 harness 可以进入的目录(具备搜索权限,这是子进程 cwd 的要求);解析后的同一路径同时作为子进程 cwd 和 ACP `session/new` 工作区。

View file

@ -322,9 +322,10 @@ function terminalFailure(
/**
* Start and publish one ACP child after initialization and session creation.
* Child failures resolve through the run result; startup and teardown failures
* reject with fixed safe facts after process reap, retaining original causes
* for Host observation. Disposal cancels, kills, and reaps the child.
* Child failures resolve through the run result. Startup rejects with fixed
* safe facts after provider-owned cleanup; successful cleanup proves process
* reap, while cleanup failure preserves both causes without claiming
* quiescence. Disposal cancels, kills, and reaps the child.
* @param request - the start request; its signal is the cancellation channel.
* @param spec - the resolved spawn spec: command/args/cwd, env, permission
* policy, dispose graces, and the optional error sink.