@deepseek-ai/dsh-subagent-acp 0.1.2-rc.1 → 0.1.5-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-acp/README.md
-README.md: 2d929738de2f761cbc597fae6cb52f7d44d83536
-README.zh.md: d67e174a44497148d08ef54d13f17df934db2018
+README.md: 87fb7f3101d2d329300213bed2acb4a479c83b72
+README.zh.md: 399a262b9b6a4bba650552388b210d87f69f5687

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-subagent-acp` runs each delegated child in a fresh subprocess and drives it as an Agent Client Protocol client: the child gets its own runtime, session, model configuration, and tools, and it can be any ACP-compatible agent, not just Harness. It is the out-of-process alternative to the in-process spawn and fork backends, sharing only the parent session's working directory with the child. Each run spawns a fresh process, initializes an ACP session, sends the task, and collects the streamed final answer; permission prompts are auto-answered by configuration, so no human is needed. The parent receives only the child's final answer or a safe error — no intermediate messages or tool traffic crosses the boundary. Choose it when the child must be fully isolated from the parent harness and can speak ACP.
+Use this package to delegate a task to an ACP-compatible agent running in a fresh subprocess with its own runtime, session, model, and tools. Each run shares only the selected working directory, sends the task over ACP, and returns the child's final answer or a safe error; intermediate messages and tool traffic stay outside the parent conversation. Permission prompts are answered by configured policy without human interaction. Choose it when delegation needs process isolation or a non-Harness ACP agent, and choose an in-process backend when the child must share parent capabilities.
 
 ## Table of Contents
 
@@ -67,7 +67,7 @@ A successful run returns the child's final streamed assistant text as the result
 
 ### Failure and recovery
 
-A spawn, initialization, or new-session failure rejects before publication, ordinarily after the child process is reaped. If cleanup also fails, the rejection preserves ordered safe startup and teardown facts without claiming whole-tree quiescence. Non-cancellation errors expose only fixed provider, stage, and category facts; the original failure stays on the internal cause chain and in Host diagnostics. After publication, a prompt, transport, or early-process failure resolves as `error` with a safe diagnostic, while local cancellation resolves as `aborted` without failure detail.
+A spawn, initialization, or new-session failure rejects before publication, ordinarily after the managed range is proven quiescent. If cleanup also fails, the rejection preserves ordered safe startup and teardown facts without claiming whole-range quiescence. Non-cancellation errors expose only fixed provider, stage, and category facts; the original failure stays on the internal cause chain and in Host diagnostics. After publication, a prompt, transport, or early-process failure resolves as `error` with a safe diagnostic, while local cancellation resolves as `aborted` without failure detail.
 
 ### Safe diagnostics
 
@@ -91,7 +91,7 @@ This section explains how the backend drives a child over ACP and where the obse
 
 ### Start and ownership flow
 
-A start resolves the child's working directory (the configured `cwd` override, else the parent session's cwd), spawns the command through the subprocess seam, performs the ACP `initialize` and `newSession` handshake, and only then publishes the run. Fulfillment means a remote session is ready and ownership has transferred to the caller. Disposal is idempotent: it closes stdin and waits a configured grace for cooperative quiescence, then escalates through SIGTERM to SIGKILL and awaits whole-tree exit. Cleanup failures remain observable as ordered safe facts and never claim quiescence.
+A start resolves the child's working directory (the configured `cwd` override, else the parent session's cwd), spawns the command through the subprocess seam, performs the ACP `initialize` and `newSession` handshake, and only then publishes the run. Fulfillment means a remote session is ready and ownership has transferred to the caller. Disposal is idempotent: it closes stdin and waits a configured grace for cooperative quiescence, then escalates through SIGTERM to SIGKILL and awaits whole-range exit. Cleanup failures remain observable as ordered safe facts and never claim quiescence.
 
 ### Stop-reason mapping
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-subagent-acp` 在全新的子进程中运行每个被委派的子 agent，并作为 Agent Client Protocol 客户端驱动它：子 agent（智能体）拥有自己的运行时、会话、模型配置和工具，可以是任何兼容 ACP 的 agent，而不只是 Harness。它是进程内 spawn 与 fork 后端的进程外替代方案，只与子 agent 共享父会话的工作目录。每次运行都会 spawn 全新进程、初始化 ACP 会话、发送任务并收集流式最终答案；权限提示由配置自动应答，因此无需人工参与。父级只收到子 agent 的最终答案或安全错误——中间消息与工具流量不会跨越边界。当子 agent 必须与父 harness 完全隔离且能说 ACP 时，选择它。
+使用本包可将任务委派给运行在全新子进程中的 ACP 兼容 agent；子 agent 拥有独立的运行时、会话、模型和工具。每次运行只共享选定的工作目录，通过 ACP 发送任务，并返回子 agent 的最终答案或安全错误；中间消息和工具流量不会进入父级对话。权限提示由配置的策略自动应答，无需人工介入。当委派需要进程隔离或需要使用非 Harness ACP agent 时选择本包；当子 agent 必须共享父级能力时，选择进程内后端。
 
 ## 目录
 
@@ -67,7 +67,7 @@ DeepSeek Harness 子进程使用产品启动器和一个显式的绝对路径 `D
 
 ### 失败与恢复
 
-spawn、初始化或新建会话失败会在发布前拒绝，通常先等待子进程被回收。如果清理也失败，拒绝会保留有序、安全的启动与拆卸事实，但不会声称整棵进程树已经停稳。非取消错误只暴露固定的提供方、阶段与类别事实；原始失败保留在内部 cause 链与 Host 诊断中。发布后，提示词、传输或进程提前退出会以携带安全诊断的 `error` 结算；本地取消则以不带失败详情的 `aborted` 结算。
+spawn、初始化或新建会话失败会在发布前拒绝，通常先证明 managed range 已经完全停稳。如果清理也失败，拒绝会保留有序、安全的启动与拆卸事实，但不会声称整个 range 已经停稳。非取消错误只暴露固定的提供方、阶段与类别事实；原始失败保留在内部 cause 链与 Host 诊断中。发布后，提示词、传输或进程提前退出会以携带安全诊断的 `error` 结算；本地取消则以不带失败详情的 `aborted` 结算。
 
 ### 安全诊断
 
@@ -91,7 +91,7 @@ spawn、初始化或新建会话失败会在发布前拒绝，通常先等待子
 
 ### 启动与所有权流程
 
-一次启动先解析子 agent 的工作目录（配置的 `cwd` 覆盖值，否则取父会话 cwd），经子进程 seam spawn 命令，完成 ACP `initialize` 与 `newSession` 握手，然后才发布运行。兑现意味着远程会话已就绪、所有权已转移给调用方。dispose（资源释放）是幂等的：先关闭 stdin 并按配置的宽限等待协作式完全停稳，再经 SIGTERM 升级到 SIGKILL，并等待整棵进程树退出。清理失败会作为有序的安全事实保持可观察，且绝不声称已经完全停稳。
+一次启动先解析子 agent 的工作目录（配置的 `cwd` 覆盖值，否则取父会话 cwd），经子进程 seam spawn 命令，完成 ACP `initialize` 与 `newSession` 握手，然后才发布运行。兑现意味着远程会话已就绪、所有权已转移给调用方。dispose（资源释放）是幂等的：先关闭 stdin 并按配置的宽限等待协作式完全停稳，再经 SIGTERM 升级到 SIGKILL，并等待整个 managed range 退出。清理失败会作为有序的安全事实保持可观察，且绝不声称已经完全停稳。
 
 ### 停止原因映射
 

package/lib/index.js

@@ -74,8 +74,8 @@ function permissionRequestKind(kind) {
 	const candidate = kind ?? "unknown";
 	return ACP_TOOL_KINDS.has(candidate) ? candidate : "unknown";
 }
-/** Bounded whole-tree exit wait: polls the handle's tree liveness until it exits or `ms` elapses. */
-async function treeExitsWithin(child, ms) {
+/** Bounded managed-range exit wait: observes the handle's range until it is empty or `ms` elapses. */
+async function rangeExitsWithin(child, ms) {
 	const controller = new AbortController();
 	const timer = setTimeout(() => {
 		controller.abort();
@@ -88,22 +88,31 @@ async function treeExitsWithin(child, ms) {
 }
 /**
 * Cooperative teardown ladder for an out-of-process agent, over the seam's
-* public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
+* public verbs; resolves only at whole-range quiescence: stdin EOF (the child's
 * window to flush persistence and reap its own descendants), then the
 * terminate() escalation (SIGTERM → spec grace → SIGKILL) and its
-* whole-tree exit proof.
+* whole-range exit proof.
 * @param child - the spawned ACP child's handle.
 * @param eofGraceMs - tier-1 window after stdin EOF.
 */
 async function disposeAcpChild(child, eofGraceMs) {
-	if (child.pid <= 0) {
-		await child.done.catch(() => {});
-		return;
-	}
+	const failures = [];
 	child.stdin?.end();
-	if (await treeExitsWithin(child, eofGraceMs)) return;
+	let exited = false;
+	try {
+		exited = await rangeExitsWithin(child, eofGraceMs);
+	} catch (error) {
+		failures.push(toError(error));
+	}
+	if (exited) return;
 	child.terminate();
-	await child.waitForExit();
+	try {
+		await child.waitForExit();
+	} catch (error) {
+		failures.push(toError(error));
+	}
+	if (failures.length === 1) throw failures[0];
+	if (failures.length > 1) throw new AggregateError(failures, "ACP subprocess teardown failed");
 }
 /**
 * Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}.
@@ -154,11 +163,7 @@ function reportFailure(spec, error) {
 	} catch {}
 }
 /** Classify an unpublished failure from the active protocol operation and observed process facts. */
-function startupFailure(error, stage, child, outcome) {
-	if (child.pid <= 0) return new AcpRunFailure({
-		stage: "process",
-		category: "process-start"
-	}, error);
+function startupFailure(error, stage, outcome) {
 	return new AcpRunFailure(
 		/* v8 ignore next -- Windows anonymous pipes cannot expose a live-child protocol close during startup. */
 		outcome === void 0 ? {
@@ -194,10 +199,10 @@ function terminalFailure(reason, permission) {
 /**
 * Start and publish one ACP child after initialization and session creation.
 * Child failures resolve through the run result. Startup rejects with fixed
-* safe facts after provider-owned cleanup; successful cleanup proves process
-* reap. Cleanup failure preserves startup plus teardown facts for an ordinary
+* safe facts after provider-owned cleanup; successful cleanup proves managed
+* range quiescence. Cleanup failure preserves startup plus teardown facts for an ordinary
 * failure, or teardown alone after cancellation, without claiming quiescence.
-* Disposal cancels, kills, and reaps the child.
+* Disposal cancels, terminates, and settles the child's managed range.
 * @param request - the start request; its signal is the cancellation channel.
 * @param spec - the resolved spawn spec: command/args/cwd, env, permission
 * policy, dispose graces, and the optional error sink.
@@ -230,18 +235,22 @@ async function startAcpRun(request, spec) {
 	if (child.stdin === void 0 || child.stdout === void 0) throw new Error("subagent-acp: subprocess implementation dropped a piped protocol stream");
 	/* v8 ignore stop */
 	let processOutcome;
+	let processFailure;
 	const processDone = child.done.then((outcome) => {
 		processOutcome = outcome;
 		return outcome;
+	}, (error) => {
+		processFailure = toError(error);
+		throw processFailure;
 	});
-	const spawnFailed = processDone.then(
+	const processRejected = processDone.then(
 		/* v8 ignore next -- the success arm's never-settling executor is intentionally empty. */
 		() => new Promise(() => {}),
 		(err) => Promise.reject(toError(err))
 	);
-	spawnFailed.catch(() => {});
+	processRejected.catch(() => {});
 	const observeProcessOutcome = async (signal) => {
-		if (processOutcome !== void 0 || child.pid <= 0) return processOutcome;
+		if (processOutcome !== void 0) return processOutcome;
 		const timeout = AbortSignal.timeout(Math.ceil(spec.disposeGraceMs));
 		const bound = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
 		const aborted = Promise.withResolvers();
@@ -255,7 +264,6 @@ async function startAcpRun(request, spec) {
 		try {
 			return await Promise.race([processDone, aborted.promise]);
 		} catch {
-			/* v8 ignore next -- a published child.done cannot reject; spawn rejection is consumed before publication. */
 			return processOutcome;
 		} finally {
 			bound.removeEventListener("abort", onObservationAbort);
@@ -331,18 +339,20 @@ async function startAcpRun(request, spec) {
 				/* v8 ignore next -- cancelSettled wins the startup race before this post-response guard can settle it. */
 				if (flags.cancelled) throw new Error("subagent cancelled before the ACP session started");
 			})(),
-			spawnFailed,
+			processRejected,
 			cancelSettled.then(() => {
 				throw new Error("subagent cancelled before the ACP session started");
 			})
 		]);
 	} catch (error) {
 		request.signal.removeEventListener("abort", onAbort);
-		const startup = flags.cancelled ? { kind: "cancelled" } : {
+		const cancelledBeforeCleanup = flags.cancelled;
+		const observedOutcome = !cancelledBeforeCleanup && !(error instanceof AcpRunFailure) ? await observeProcessOutcome() : void 0;
+		const startup = cancelledBeforeCleanup ? { kind: "cancelled" } : {
 			kind: "failed",
-			failure: error instanceof AcpRunFailure ? error : startupFailure(error, startupStage, child, await observeProcessOutcome())
+			failure: error instanceof AcpRunFailure ? error : startupFailure(error, startupStage, observedOutcome)
 		};
-		if (startup.kind === "cancelled") {} else reportFailure(spec, error instanceof AcpRunFailure ? error.cause : error);
+		if (startup.kind === "cancelled") {} else reportFailure(spec, error instanceof AcpRunFailure ? error.cause : processFailure ?? error);
 		try {
 			await disposeProcess();
 		} catch (cleanupError) {
@@ -392,7 +402,7 @@ async function startAcpRun(request, spec) {
 							outcome
 						}, latestPermission);
 					}
-					throw error;
+					throw processFailure ?? error;
 				}
 			},
 			collectOutput,

package/lib/types/run.d.ts

@@ -51,7 +51,7 @@ export interface AcpRunSpec {
     disposeGraceMs: number;
     /**
      * Spawn function from the subprocess seam (`ctx.subprocess.spawn`), so the
-     * child rides the shared scrub, tree-scoped teardown, and service-owned
+     * child rides the shared scrub, managed-range teardown, and service-owned
      * lifetime instead of a package-local child_process path.
      */
     spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
@@ -74,10 +74,10 @@ export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
 export declare function acpConfigurationFailure(cause: unknown): Error;
 /**
  * Cooperative teardown ladder for an out-of-process agent, over the seam's
- * public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
+ * public verbs; resolves only at whole-range quiescence: stdin EOF (the child's
  * window to flush persistence and reap its own descendants), then the
  * terminate() escalation (SIGTERM → spec grace → SIGKILL) and its
- * whole-tree exit proof.
+ * whole-range exit proof.
  * @param child - the spawned ACP child's handle.
  * @param eofGraceMs - tier-1 window after stdin EOF.
  */
@@ -104,10 +104,10 @@ export declare function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[];
 /**
  * Start and publish one ACP child after initialization and session creation.
  * Child failures resolve through the run result. Startup rejects with fixed
- * safe facts after provider-owned cleanup; successful cleanup proves process
- * reap. Cleanup failure preserves startup plus teardown facts for an ordinary
+ * safe facts after provider-owned cleanup; successful cleanup proves managed
+ * range quiescence. Cleanup failure preserves startup plus teardown facts for an ordinary
  * failure, or teardown alone after cancellation, without claiming quiescence.
- * Disposal cancels, kills, and reaps the child.
+ * Disposal cancels, terminates, and settles the child's managed range.
  * @param request - the start request; its signal is the cancellation channel.
  * @param spec - the resolved spawn spec: command/args/cwd, env, permission
  * policy, dispose graces, and the optional error sink.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-acp",
   "description": "Out-of-process ACP subagent backend: drives a child agent in a spawned subprocess over the Agent Client Protocol",
-  "version": "0.1.2-rc.1",
+  "version": "0.1.5-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -28,33 +28,33 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.5-alpha.1"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.4.0",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-brand": "^0.1.5-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-app-boot": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-subagent": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-app-boot": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.5-alpha.1"
   }
 }