@zhushanwen/subagent-engine-sdk 0.10.0 → 0.11.0

package/dist/protocol/index.js

@@ -5,14 +5,19 @@ import {
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   errorResponseFrameSchema,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-LM7P7OTA.js";
+} from "../chunk-QBXDEF4N.js";
 import {
   isNotificationFrame,
   isRequestFrame,
@@ -24,7 +29,11 @@ import {
   ENGINE_ERROR_CODE_PREFIX,
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   HANDSHAKE_TIMEOUT_MS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -44,7 +53,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "../chunk-JZN76I3S.js";
+} from "../chunk-NVF3PADP.js";
 import "../chunk-JSBRDJBE.js";
 export {
   AGENT_EVENT_TYPE_NAMES,
@@ -53,7 +62,11 @@ export {
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS,
@@ -67,6 +80,9 @@ export {
   SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported,
   engineConversationUnsupportedError,
@@ -81,6 +97,8 @@ export {
   isRequestFrame,
   isResponseFrame,
   isReverseRequestFrame,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,

package/dist/server/index.cjs

@@ -88,7 +88,7 @@ var EngineSdkError = class extends Error {
     this.recovery = recovery;
     this.data = data;
   }
-  /** 协议 error 帧载荷投影。 */
+  /** 协议 error 帧载荷派生视图。 */
   toStructured() {
     return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
   }

package/dist/server/index.d.cts

@@ -1,16 +1,16 @@
-import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-jSa1g28F.cjs';
-import { E as EngineSdkError } from '../error-codes-f-UO4a8D.cjs';
-import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-BLxg4ZFr.cjs';
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-BUHUMF9R.cjs';
+import { E as EngineSdkError } from '../error-codes-D_aPibUt.cjs';
+import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-CHiDwvRK.cjs';
 import { ReverseRequestClock } from '../spawn.cjs';
 import 'node:child_process';
 import '../env.cjs';
 
-/** 出站帧写入面（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
+/** 出站帧写侧（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
 type FrameWriter = (frame: unknown) => void;
 /**
- * 反向请求应答等待缺省上限（ms）——数据面分类 core 侧 10s，两阶段等待放宽一档兜底。
+ * 反向请求应答等待缺省上限（ms）——数据范围分类 core 侧 10s，两阶段等待放宽一档兜底。
  *
- * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议面常数，分叉会让同一宿主
+ * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议范围常数，分叉会让同一宿主
  * 在不同引擎下得到不同的超时语义。
  */
 declare const REVERSE_TIMEOUT_DEFAULT_MS = 60000;
@@ -22,8 +22,8 @@ interface ActiveRun {
 /**
  * 反向请求在途登记（引擎 → 宿主请求的应答等待项）。
  *
- * `method` 是 pi 引擎的扩展位（settle 时按通道守卫应答形态，如 askUser 的 UI 应答面
- * 检查）；zcode 无该通道守卫，可缺省。
+ * `method` 是 pi 引擎的扩展位（settle 时按通道检查应答形态，如 askUser 的 UI 应答
+ * 检查）；zcode 无该通道检查，可缺省。
  */
 interface ReversePending {
     resolve: (result: unknown) => void;
@@ -77,7 +77,7 @@ declare function reverseRequestRejection(method: string): {
 declare function unknownMethodError(id: number, method: string): EngineSdkError;
 /** 帧循环所需的最小上下文（引擎侧实现注入；每引擎构造一次，不在每帧重建）。 */
 interface FrameLoopContext {
-    /** 出站帧写入面。 */
+    /** 出站帧写侧。 */
     write: FrameWriter;
     /** 反向应答帧落地（各引擎的两阶段 ack 语义在此，**刻意不统一**）。 */
     settleReverse(id: number | string, frame: {
@@ -107,7 +107,7 @@ interface ReverseRequestSendContext {
     clock?: ReverseRequestClock;
     /** 请求 id 分配（各引擎可带自己的前缀与计数器）。 */
     nextId(): string;
-    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答面检查用；zcode 不记）。 */
+    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答侧检查用；zcode 不记）。 */
     pendingExtras?(method: string): Partial<ReversePending>;
 }
 declare function sendReverseRequest(ctx: ReverseRequestSendContext, method: string, params: unknown): Promise<unknown>;

package/dist/server/index.d.ts

@@ -1,16 +1,16 @@
-import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-jSa1g28F.js';
-import { E as EngineSdkError } from '../error-codes-DnFru4L4.js';
-import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-C2zvZqhP.js';
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-BUHUMF9R.js';
+import { E as EngineSdkError } from '../error-codes-DrNf0gwT.js';
+import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-BdIH3FwS.js';
 import { ReverseRequestClock } from '../spawn.js';
 import 'node:child_process';
 import '../env.js';
 
-/** 出站帧写入面（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
+/** 出站帧写侧（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
 type FrameWriter = (frame: unknown) => void;
 /**
- * 反向请求应答等待缺省上限（ms）——数据面分类 core 侧 10s，两阶段等待放宽一档兜底。
+ * 反向请求应答等待缺省上限（ms）——数据范围分类 core 侧 10s，两阶段等待放宽一档兜底。
  *
- * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议面常数，分叉会让同一宿主
+ * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议范围常数，分叉会让同一宿主
  * 在不同引擎下得到不同的超时语义。
  */
 declare const REVERSE_TIMEOUT_DEFAULT_MS = 60000;
@@ -22,8 +22,8 @@ interface ActiveRun {
 /**
  * 反向请求在途登记（引擎 → 宿主请求的应答等待项）。
  *
- * `method` 是 pi 引擎的扩展位（settle 时按通道守卫应答形态，如 askUser 的 UI 应答面
- * 检查）；zcode 无该通道守卫，可缺省。
+ * `method` 是 pi 引擎的扩展位（settle 时按通道检查应答形态，如 askUser 的 UI 应答
+ * 检查）；zcode 无该通道检查，可缺省。
  */
 interface ReversePending {
     resolve: (result: unknown) => void;
@@ -77,7 +77,7 @@ declare function reverseRequestRejection(method: string): {
 declare function unknownMethodError(id: number, method: string): EngineSdkError;
 /** 帧循环所需的最小上下文（引擎侧实现注入；每引擎构造一次，不在每帧重建）。 */
 interface FrameLoopContext {
-    /** 出站帧写入面。 */
+    /** 出站帧写侧。 */
     write: FrameWriter;
     /** 反向应答帧落地（各引擎的两阶段 ack 语义在此，**刻意不统一**）。 */
     settleReverse(id: number | string, frame: {
@@ -107,7 +107,7 @@ interface ReverseRequestSendContext {
     clock?: ReverseRequestClock;
     /** 请求 id 分配（各引擎可带自己的前缀与计数器）。 */
     nextId(): string;
-    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答面检查用；zcode 不记）。 */
+    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答侧检查用；zcode 不记）。 */
     pendingExtras?(method: string): Partial<ReversePending>;
 }
 declare function sendReverseRequest(ctx: ReverseRequestSendContext, method: string, params: unknown): Promise<unknown>;

package/dist/server/index.js

@@ -8,7 +8,7 @@ import {
 import {
   ENGINE_PROTOCOL_VERSION,
   EngineSdkError
-} from "../chunk-JZN76I3S.js";
+} from "../chunk-NVF3PADP.js";
 import "../chunk-JSBRDJBE.js";
 
 // src/server/index.ts

package/dist/spawn.cjs

@@ -24,6 +24,7 @@ __export(spawn_exports, {
   ENGINE_ABORT_KILL_GRACE_MS: () => ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV: () => ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct: () => armEngineSelfDestruct,
+  killOwnProcessGroup: () => killOwnProcessGroup,
   pumpNdjsonLines: () => pumpNdjsonLines,
   spawnEngineChild: () => spawnEngineChild
 });
@@ -232,13 +233,40 @@ function resolveHostRequestTimeoutMs(opts) {
   }
   return parsed;
 }
-function killOwnProcessGroup() {
+function killOwnProcessGroup(deps = {}) {
   const pid = process.pid;
+  const kill = deps.killFn ?? ((targetPid, signal) => process.kill(targetPid, signal));
+  if ((deps.platform ?? process.platform) === "win32") {
+    const fallbackSelfKill = (reason) => {
+      logger2.warn(`taskkill self-tree failed (${reason}); falling back to self SIGKILL`);
+      try {
+        kill(pid, "SIGKILL");
+      } catch (err) {
+        logger2.warn(
+          `self SIGKILL fallback failed (${String(err)}); descendant pi may linger until runtime sweep`
+        );
+      }
+    };
+    const spawnFn = deps.spawnFn ?? ((command, args, options) => (0, import_node_child_process.spawn)(command, [...args], options));
+    try {
+      const child = spawnFn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      child.on("error", (err) => {
+        fallbackSelfKill(String(err));
+      });
+      child.unref?.();
+    } catch (err) {
+      fallbackSelfKill(`spawn threw: ${String(err)}`);
+    }
+    return;
+  }
   try {
-    process.kill(-pid, "SIGKILL");
+    kill(-pid, "SIGKILL");
   } catch (err) {
     logger2.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
-    process.kill(pid, "SIGKILL");
+    kill(pid, "SIGKILL");
   }
 }
 function armEngineSelfDestruct(opts) {
@@ -307,6 +335,7 @@ function pumpNdjsonLines(stream, onLine) {
   ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
+  killOwnProcessGroup,
   pumpNdjsonLines,
   spawnEngineChild
 });

package/dist/spawn.d.cts

@@ -39,19 +39,19 @@ declare function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess;
 declare const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30000;
 /** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
 declare const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "TAIJI_ENGINE_HOST_REQUEST_TIMEOUT_MS";
-/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
+/** 反向请求计时侧操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
 interface ReverseRequestClock {
-    /** 反向请求已发出（未 ack）——进入计时面。 */
+    /** 反向请求已发出（未 ack）——进入计时侧。 */
     started(id: string): void;
     /**
      * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
-     * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
+     * 的 ack）——移出计时侧但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
      * ADR-0047 静默 ≠ 卡死）。
      */
     acked(id: string): void;
     /** 请求终结（应答完成/失败/取消）——彻底移出。 */
     settled(id: string): void;
-    /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
+    /** 卸载检查（引擎正常 shutdown 路径；自灭后幂等）。 */
     dispose(): void;
 }
 interface EngineSelfDestructOptions {
@@ -64,14 +64,40 @@ interface EngineSelfDestructOptions {
     /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
     killSelf?: () => void;
 }
+/** taskkill 子进程的最小面（self-destruct 是 fire-and-forget：只挂 error + unref）。 */
+type KillOwnProcessGroupSpawnResult = {
+    on(event: "error", listener: (err: Error) => void): unknown;
+    unref?: () => void;
+};
+/** 自灭杀链依赖（缺省 = 真实 platform / spawn / process.kill；测试注入分支用）。 */
+type KillOwnProcessGroupDeps = {
+    readonly platform?: NodeJS.Platform;
+    readonly spawnFn?: (command: string, args: readonly string[], options: {
+        readonly stdio: "ignore";
+        readonly windowsHide: boolean;
+    }) => KillOwnProcessGroupSpawnResult;
+    readonly killFn?: (pid: number, signal: NodeJS.Signals) => unknown;
+};
 /**
- * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
+ * 缺省自灭：先杀自己进程组（收割引擎 spawn 的任务子进程），失败回落杀自己。
+ *
+ * 平台矩阵（设计 D7）：POSIX = 负 pid 组杀；Windows 无进程组信号语义，用
+ * `taskkill /PID <self> /T /F` 树杀（stdio ignore + fire-and-forget，不阻塞自灭链）。
+ * Windows 分支在 taskkill 根本起不来（spawn 同步抛错，或 child 'error'：PATH 缺
+ * System32 / EMFILE 等）时回落 `SIGKILL` 杀自己（R2A-N4）：只杀自己是「可接受
+ * 降级」（后代 pi 交给 runtime sweep / 组登记），但引擎自身必须停住——否则引擎事件
+ * 循环仍有活句柄时宿主死后引擎与 pi 都不死，比原行为更差。两条失败路径都 warn 留痕。
+ * 依赖可注入 = 平台分支单测 seam（不实跑 Windows）。
+ */
+declare function killOwnProcessGroup(deps?: KillOwnProcessGroupDeps): void;
+/**
+ * 武装引擎侧自灭检查。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
  *
  * 判据：
- * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
+ * - 主判据 stdio EOF：stdin 'end'（数据范围读尽）或 'close'（fd 关闭）→ 立即自灭
  *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
  * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
- *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
+ *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除情形**：已 ack 的
  *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
  *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
  *
@@ -88,4 +114,4 @@ declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): Reverse
  */
 declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
 
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type KillOwnProcessGroupDeps, type KillOwnProcessGroupSpawnResult, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, killOwnProcessGroup, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.d.ts

@@ -39,19 +39,19 @@ declare function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess;
 declare const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30000;
 /** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
 declare const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "TAIJI_ENGINE_HOST_REQUEST_TIMEOUT_MS";
-/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
+/** 反向请求计时侧操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
 interface ReverseRequestClock {
-    /** 反向请求已发出（未 ack）——进入计时面。 */
+    /** 反向请求已发出（未 ack）——进入计时侧。 */
     started(id: string): void;
     /**
      * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
-     * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
+     * 的 ack）——移出计时侧但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
      * ADR-0047 静默 ≠ 卡死）。
      */
     acked(id: string): void;
     /** 请求终结（应答完成/失败/取消）——彻底移出。 */
     settled(id: string): void;
-    /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
+    /** 卸载检查（引擎正常 shutdown 路径；自灭后幂等）。 */
     dispose(): void;
 }
 interface EngineSelfDestructOptions {
@@ -64,14 +64,40 @@ interface EngineSelfDestructOptions {
     /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
     killSelf?: () => void;
 }
+/** taskkill 子进程的最小面（self-destruct 是 fire-and-forget：只挂 error + unref）。 */
+type KillOwnProcessGroupSpawnResult = {
+    on(event: "error", listener: (err: Error) => void): unknown;
+    unref?: () => void;
+};
+/** 自灭杀链依赖（缺省 = 真实 platform / spawn / process.kill；测试注入分支用）。 */
+type KillOwnProcessGroupDeps = {
+    readonly platform?: NodeJS.Platform;
+    readonly spawnFn?: (command: string, args: readonly string[], options: {
+        readonly stdio: "ignore";
+        readonly windowsHide: boolean;
+    }) => KillOwnProcessGroupSpawnResult;
+    readonly killFn?: (pid: number, signal: NodeJS.Signals) => unknown;
+};
 /**
- * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
+ * 缺省自灭：先杀自己进程组（收割引擎 spawn 的任务子进程），失败回落杀自己。
+ *
+ * 平台矩阵（设计 D7）：POSIX = 负 pid 组杀；Windows 无进程组信号语义，用
+ * `taskkill /PID <self> /T /F` 树杀（stdio ignore + fire-and-forget，不阻塞自灭链）。
+ * Windows 分支在 taskkill 根本起不来（spawn 同步抛错，或 child 'error'：PATH 缺
+ * System32 / EMFILE 等）时回落 `SIGKILL` 杀自己（R2A-N4）：只杀自己是「可接受
+ * 降级」（后代 pi 交给 runtime sweep / 组登记），但引擎自身必须停住——否则引擎事件
+ * 循环仍有活句柄时宿主死后引擎与 pi 都不死，比原行为更差。两条失败路径都 warn 留痕。
+ * 依赖可注入 = 平台分支单测 seam（不实跑 Windows）。
+ */
+declare function killOwnProcessGroup(deps?: KillOwnProcessGroupDeps): void;
+/**
+ * 武装引擎侧自灭检查。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
  *
  * 判据：
- * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
+ * - 主判据 stdio EOF：stdin 'end'（数据范围读尽）或 'close'（fd 关闭）→ 立即自灭
  *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
  * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
- *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
+ *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除情形**：已 ack 的
  *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
  *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
  *
@@ -88,4 +114,4 @@ declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): Reverse
  */
 declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
 
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type KillOwnProcessGroupDeps, type KillOwnProcessGroupSpawnResult, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, killOwnProcessGroup, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.js

@@ -3,12 +3,13 @@ import {
   ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
+  killOwnProcessGroup,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-HSNDUHFH.js";
-import "./chunk-CNCFMPEH.js";
+} from "./chunk-3MCOZY3Z.js";
+import "./chunk-TJMS3YOR.js";
 import "./chunk-PYO3YR7W.js";
-import "./chunk-JZN76I3S.js";
+import "./chunk-NVF3PADP.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {
@@ -16,6 +17,7 @@ export {
   ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
+  killOwnProcessGroup,
   pumpNdjsonLines,
   spawnEngineChild
 };

package/dist/ui-types.d.cts

@@ -58,8 +58,8 @@ type UiResponse = {
     ack: true;
 };
 /** UiResponse 载荷结构判定（四成员判别；形态对齐 reverse-channels 的
- *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前守卫，防宿主畸形帧
- *  静默流入 UI 队列（S7：askUser 应答跨界无守卫）。 */
+ *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前检查，防宿主畸形帧
+ *  静默流入 UI 队列（S7：askUser 应答跨界无检查）。 */
 declare function isUiResponse(value: unknown): value is UiResponse;
 /** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
  *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。

package/dist/ui-types.d.ts

@@ -58,8 +58,8 @@ type UiResponse = {
     ack: true;
 };
 /** UiResponse 载荷结构判定（四成员判别；形态对齐 reverse-channels 的
- *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前守卫，防宿主畸形帧
- *  静默流入 UI 队列（S7：askUser 应答跨界无守卫）。 */
+ *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前检查，防宿主畸形帧
+ *  静默流入 UI 队列（S7：askUser 应答跨界无检查）。 */
 declare function isUiResponse(value: unknown): value is UiResponse;
 /** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
  *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。

package/dist/zcode-db-paths.cjs

@@ -21,13 +21,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var zcode_db_paths_exports = {};
 __export(zcode_db_paths_exports, {
   ZCODE_HOST_DB_SUFFIX: () => ZCODE_HOST_DB_SUFFIX,
-  ZCODE_ISOLATED_DB_SEGMENTS: () => ZCODE_ISOLATED_DB_SEGMENTS
+  ZCODE_ISOLATED_DB_SEGMENTS: () => ZCODE_ISOLATED_DB_SEGMENTS,
+  ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS: () => ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS
 });
 module.exports = __toCommonJS(zcode_db_paths_exports);
 var ZCODE_HOST_DB_SUFFIX = [".zcode", "cli", "db", "db.sqlite"];
 var ZCODE_ISOLATED_DB_SEGMENTS = ["engines", "zcode", "session-db", "db.sqlite"];
+var ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS = [
+  "engines",
+  "zcode",
+  "pi-synced-provider-config.json"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ZCODE_HOST_DB_SUFFIX,
-  ZCODE_ISOLATED_DB_SEGMENTS
+  ZCODE_ISOLATED_DB_SEGMENTS,
+  ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS
 });

package/dist/zcode-db-paths.d.cts

@@ -11,5 +11,15 @@ declare const ZCODE_HOST_DB_SUFFIX: readonly [".zcode", "cli", "db", "db.sqlite"
  * 之外——池 TTL 清理不得触及会话库（设计 D1/F11）。
  */
 declare const ZCODE_ISOLATED_DB_SEGMENTS: readonly ["engines", "zcode", "session-db", "db.sqlite"];
+/**
+ * taiji 同步副本相对段（`<dataDir>/engines/zcode/pi-synced-provider-config.json`，
+ * 绝对路径 = join(dataDir, ...segments)）：runtime 启动段把 pi 侧 provider 映射落盘
+ * 的合并副本（唯一写方 = runtime provider 同步模块 zcode-provider-sync-wiring.ts，
+ * 读侧另一处 = session-records.ts zcodeModelListPaths 缺省拼装；引擎读侧 =
+ * zcode-subagent-cli preparer.ts 个人 provider 解析链——副本存在即用之，缺失回落
+ * 真实 `~/.zcode/v2/provider_config.json`）。与 ZCODE_ISOLATED_DB_SEGMENTS 同族：
+ * 同以 dataDir 为 join 根的 dataDir 相对段（区别于 homedir 根的 _SUFFIX 常量）。
+ */
+declare const ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS: readonly ["engines", "zcode", "pi-synced-provider-config.json"];
 
-export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS };
+export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS, ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS };

package/dist/zcode-db-paths.d.ts

@@ -11,5 +11,15 @@ declare const ZCODE_HOST_DB_SUFFIX: readonly [".zcode", "cli", "db", "db.sqlite"
  * 之外——池 TTL 清理不得触及会话库（设计 D1/F11）。
  */
 declare const ZCODE_ISOLATED_DB_SEGMENTS: readonly ["engines", "zcode", "session-db", "db.sqlite"];
+/**
+ * taiji 同步副本相对段（`<dataDir>/engines/zcode/pi-synced-provider-config.json`，
+ * 绝对路径 = join(dataDir, ...segments)）：runtime 启动段把 pi 侧 provider 映射落盘
+ * 的合并副本（唯一写方 = runtime provider 同步模块 zcode-provider-sync-wiring.ts，
+ * 读侧另一处 = session-records.ts zcodeModelListPaths 缺省拼装；引擎读侧 =
+ * zcode-subagent-cli preparer.ts 个人 provider 解析链——副本存在即用之，缺失回落
+ * 真实 `~/.zcode/v2/provider_config.json`）。与 ZCODE_ISOLATED_DB_SEGMENTS 同族：
+ * 同以 dataDir 为 join 根的 dataDir 相对段（区别于 homedir 根的 _SUFFIX 常量）。
+ */
+declare const ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS: readonly ["engines", "zcode", "pi-synced-provider-config.json"];
 
-export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS };
+export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS, ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS };

package/dist/zcode-db-paths.js

@@ -1,9 +1,11 @@
 import {
   ZCODE_HOST_DB_SUFFIX,
-  ZCODE_ISOLATED_DB_SEGMENTS
-} from "./chunk-CT3FEBDO.js";
+  ZCODE_ISOLATED_DB_SEGMENTS,
+  ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS
+} from "./chunk-QOFFM5YW.js";
 import "./chunk-JSBRDJBE.js";
 export {
   ZCODE_HOST_DB_SUFFIX,
-  ZCODE_ISOLATED_DB_SEGMENTS
+  ZCODE_ISOLATED_DB_SEGMENTS,
+  ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-engine-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Engine-side SDK for the subagent engine protocol: NDJSON stdio contract types, engine primitives (schema emulation, nesting guard, kill chain, journal replay projection, data-dir/paths resolution) — the shared contract root between subagent-core and engine CLI packages (engines import SDK only, never core)",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
       "default": "./dist/server/index.js"
     }
   },
-  "$comment": "W1 骨架（docs/design/subagent-engine-protocolization.impl-plan.md §2.1）。双形态同 subagent-core 先例（D4）：workspace 消费走 import 条件 -> src；npm 消费走 publishConfig -> dist。exports 面先收窄到 ./ 与 ./protocol（exports = semver 契约，收窄不放宽；引擎包 W5/W7 消费经主 barrel）。协议版本独立于包版本：ENGINE_PROTOCOL_VERSION = 1（src/protocol/engine-protocol.ts）。不变量：本包禁止 import @zhushanwen/subagent-core（守卫 .githooks/check-engine-sdk-boundary.mjs）。src/env.ts 与 src/spawn.ts 是 W12 领地（impl-plan §2.12），本单元仅空骨架占位。tsup entry 逐模块具名登记（§2.1 末行），新增模块必须同步登记。files 不含 src/（对齐 subagent-core 2026-09-16 同型收敛）：npm 消费面经 publishConfig 整体替换后全指 dist，TS 源仅服务 workspace（node_modules symlink 直读磁盘源文件，不经 tarball）；dist 产物无 sourcemap/sourceMappingURL，移除 src 零断链。已知残留：顶层 main（src/index.ts，workspace 形态载体）被 npm files 规则强制隐含打进 tarball，对 npm 消费者不可达，纯体积噪声。",
+  "$comment": "W1 骨架（docs/design/subagent-engine-protocolization.impl-plan.md §2.1）。双形态同 subagent-core 先例（D4）：workspace 消费走 import 条件 -> src；npm 消费走 publishConfig -> dist。exports 面先收窄到 ./ 与 ./protocol（exports = semver 契约，收窄不放宽；引擎包 W5/W7 消费经主 barrel）。协议版本独立于包版本：ENGINE_PROTOCOL_VERSION = 1（src/protocol/engine-protocol.ts）。不变量：本包禁止 import @zhushanwen/subagent-core（检查 .githooks/check-engine-sdk-boundary.mjs）。src/env.ts 与 src/spawn.ts 是 W12 领地（impl-plan §2.12），本单元仅空骨架占位。tsup entry 逐模块具名登记（§2.1 末行），新增模块必须同步登记。files 不含 src/（对齐 subagent-core 2026-09-16 同型收敛）：npm 消费方经 publishConfig 整体替换后全指 dist，TS 源仅服务 workspace（node_modules symlink 直读磁盘源文件，不经 tarball）；dist 产物无 sourcemap/sourceMappingURL，移除 src 零断链。已知残留：顶层 main（src/index.ts，workspace 形态载体）被 npm files 规则强制隐含打进 tarball，对 npm 消费者不可达，纯体积噪声。",
   "files": [
     "dist/"
   ],

package/dist/chunk-GSW3DMN6.js

@@ -1,39 +0,0 @@
-// src/relay-env.ts
-var RELAY_ENV_SOCKET = "TAIJI_SUBAGENT_RELAY_SOCKET";
-var RELAY_ENV_NODE = "TAIJI_SUBAGENT_RELAY_NODE";
-var RELAY_ENV_SCRIPT = "TAIJI_SUBAGENT_RELAY_SCRIPT";
-var RELAY_ENV_SESSION_ID = "TAIJI_SUBAGENT_RELAY_SESSION_ID";
-var RELAY_ENV_RECORD_ID = "TAIJI_SUBAGENT_RELAY_RECORD_ID";
-var RELAY_PROTOCOL_VERSION = 1;
-var RELAY_EXIT_CODES = {
-  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
-  VERSION_MISMATCH: 10,
-  /** relay socket 不可达（runtime 未运行或已重启）。 */
-  SOCKET_UNREACHABLE: 11,
-  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
-  SOCKET_CLOSED: 12,
-  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
-  MISSING_IDENTITY: 13
-};
-function isRelayActive(env) {
-  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
-}
-function readRelayForwardEnv(env) {
-  const socket = env[RELAY_ENV_SOCKET];
-  const node = env[RELAY_ENV_NODE];
-  const script = env[RELAY_ENV_SCRIPT];
-  if (!isRelayActive(env)) return void 0;
-  return { socket, node, script };
-}
-
-export {
-  RELAY_ENV_SOCKET,
-  RELAY_ENV_NODE,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_RECORD_ID,
-  RELAY_PROTOCOL_VERSION,
-  RELAY_EXIT_CODES,
-  isRelayActive,
-  readRelayForwardEnv
-};