@zhushanwen/subagent-engine-sdk 0.3.0 → 0.5.0

package/dist/protocol/index.d.ts

@@ -1,6 +1,6 @@
-export { A as AnyFrame, E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-BUx92qYi.js';
-import { E as EngineCapabilities, M as ModelCatalogEntry, A as AgentCallOpts, i as ResumeAnchor, h as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from '../contract-types-ByIFoLrY.js';
-export { a as AgentEvent, b as AgentFailureKind, d as AgentOutcomeUsage, e as AgentUsage, f as AgentUsageTotal, g as AssertMutuallyAssignable, I as InternalToolCall, R as ReplayedTurn, T as ToolCall, j as ToolCallEntry, k as ToolCallResult, l as Turn, W as WorktreeHandle } from '../contract-types-ByIFoLrY.js';
+export { E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-OvQlqiQw.js';
+import { E as EngineCapabilities, M as ModelCatalogEntry, A as AgentCallOpts, i as ResumeAnchor, h as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from '../contract-types-Dsvy79r3.js';
+export { a as AgentEvent, b as AgentFailureKind, d as AgentOutcomeUsage, e as AgentUsage, f as AgentUsageTotal, g as AssertMutuallyAssignable, I as InternalToolCall, R as ReplayedTurn, T as ToolCall, j as ToolCallEntry, k as ToolCallResult, l as Turn, W as WorktreeHandle } from '../contract-types-Dsvy79r3.js';
 import { UiRequest, UiResponse } from '../ui-types.js';
 
 /** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
@@ -31,16 +31,16 @@ declare const ENGINE_EVENT_COALESCE_ENV = "XYZ_ENGINE_EVENT_COALESCE";
 declare const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+ * - 数据面类（host/log / host/streamDelta / host/handleReady /
  *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
- * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */
 type ReverseRequestTimeoutClass = "data-plane" | "interaction";
 
 /**
  * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
- * [H1] `interact` 成员已随 chat-run 统一退役（docs/design/subagent-chat-run-unification.md
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
  * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
  */
 type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
@@ -50,8 +50,6 @@ declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel"
  * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
  */
 interface RunContextParams {
-    /** 隔离池归属（journal 归属错 = 缺失后果）。 */
-    poolKey: string;
     /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
     cwd: string;
     /** 请求模型 ref（未传 = 引擎缺省模型）。 */
@@ -83,7 +81,7 @@ interface RunContextParams {
     sessionDir?: string;
 }
 /**
- * [H1] run 的 resume 会话形态参数（设计 docs/design/subagent-chat-run-unification.md
+ * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
  * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
  * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
  * 泛化为「resume 续聊」。
@@ -208,13 +206,13 @@ interface ProtocolResultMap {
 }
 
 /**
- * 反向通道名联合（恰好 8 个；REVERSE_CHANNELS 常量数组与之同源互证）。
+ * 反向通道名联合（恰好 6 个；REVERSE_CHANNELS 常量数组与之同源互证）。
  */
-type ReverseChannel = "host/log" | "host/askUser" | "host/permission" | "host/streamDelta" | "host/poolResolved" | "host/handleReady" | "host/childSpawned" | "host/childStateChanged";
+type ReverseChannel = "host/log" | "host/askUser" | "host/streamDelta" | "host/handleReady" | "host/childSpawned" | "host/childStateChanged";
 /**
  * 通道名全集（运行时顺序化枚举；与 ReverseChannel 的同源关系由测试断言）。
  */
-declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
+declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
 /**
  * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
@@ -235,59 +233,24 @@ interface HostAskUserParams {
 }
 /** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
 type HostAskUserResult = UiResponse;
-/**
- * host/permission：权限询问（引擎请求宿主裁决工具执行）。
- * v1 骨架字段（设计未钉死载荷细节，细化归各引擎提取设计；W2 实装 core 应答端时
- * 若需扩展走 additive 演进）。
- */
-interface HostPermissionParams {
-    runId: string;
-    toolName: string;
-    args?: unknown;
-    /** 请求方向引擎给出的原因/说明（展示用）。 */
-    reason?: string;
-}
-/** host/permission 两阶段结果。 */
-type HostPermissionResult = {
-    approved: boolean;
-} | {
-    unsupported: true;
-};
 /**
  * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
  *
- * [H1 U6 现行语义] 关联键恒 runId（run 域轮与 chat 续聊轮已统一为 run——续聊轮
- * 是携带 resume 锚点的新 run，runId 由 core 在 run 帧分配）。recordId 键分支是
- * v1.x 旧引擎的兼容载荷形态（存量兼容读，现行引擎不写）。
- * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
+ * 关联键恒为 runId（runId 由 core 在 run 帧分配）；[H1] chat 续聊轮经 resume run
+ * 复用 runId 关联（原 recordId 关联键随 interact 面退役删除）。
  */
-type HostStreamDeltaParams = {
+interface HostStreamDeltaParams {
     runId: string;
-    recordId?: undefined;
     delta: string;
-} | {
-    recordId: string;
-    runId?: undefined;
-    delta: string;
-};
-/** streamDelta 载荷结构判定（关联键互斥 + delta 形状；消费侧共用，防双侧各写一份）。 */
-declare function isHostStreamDeltaParams(value: unknown): value is HostStreamDeltaParams;
-/**
- * host/poolResolved：journal 落盘路径单一权威（契约：必须在首个事件 emit 前调用——
- * 否则 journal 归属错）。载荷 = core onPoolResolved(poolKey) 的 runId 关联形态。
- */
-interface HostPoolResolvedParams {
-    runId: string;
-    poolKey: string;
 }
 /**
  * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
  * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
+ * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议面 poolKey 退役删除。
  */
 interface HostHandleReadyParams {
     runId: string;
     sessionRef: Record<string, string>;
-    poolKey: string;
 }
 /**
  * host/childSpawned：引擎内一次性子进程 pid 上报。
@@ -312,40 +275,6 @@ interface HostChildStateChangedParams {
     exitCode?: number;
     signal?: string;
 }
-/** 通道 → 载荷类型映射。 */
-interface ReverseChannelParamsMap {
-    "host/log": HostLogParams;
-    "host/askUser": HostAskUserParams;
-    "host/permission": HostPermissionParams;
-    "host/streamDelta": HostStreamDeltaParams;
-    "host/poolResolved": HostPoolResolvedParams;
-    "host/handleReady": HostHandleReadyParams;
-    "host/childSpawned": HostChildSpawnedParams;
-    "host/childStateChanged": HostChildStateChangedParams;
-}
-/** 通道 → 异步/同步结果类型映射（ack 两阶段通道的第二阶段 result）。 */
-interface ReverseChannelResultMap {
-    "host/log": {
-        ok: true;
-    };
-    "host/askUser": HostAskUserResult;
-    "host/permission": HostPermissionResult;
-    "host/streamDelta": {
-        ok: true;
-    };
-    "host/poolResolved": {
-        ok: true;
-    };
-    "host/handleReady": {
-        ok: true;
-    };
-    "host/childSpawned": {
-        ok: true;
-    };
-    "host/childStateChanged": {
-        ok: true;
-    };
-}
 
 /** 协议错误对象 schema。 */
 declare const protocolErrorSchema: {
@@ -486,7 +415,7 @@ declare const reverseRequestFrameSchema: {
         };
         readonly method: {
             readonly type: "string";
-            readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
+            readonly enum: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
         };
         readonly params: {};
     };
@@ -605,7 +534,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
             };
             readonly method: {
                 readonly type: "string";
-                readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
+                readonly enum: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
             };
             readonly params: {};
         };
@@ -638,11 +567,9 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
  * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
  */
 declare const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: readonly ["apikey", "api_key", "token", "credential", "password", "secret"];
-/** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
-declare const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[];
 /**
  * run.params 的会话形态参数载荷 schema（draft-07 深载荷片段）。设计权威源：
- * docs/design/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
+ * docs/architecture/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
  *
  * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
  * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
@@ -662,7 +589,7 @@ declare const runSessionParamsSchema: {
         readonly resume: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly required: readonly ["sessionRef", "poolKey"];
+            readonly required: readonly ["sessionRef"];
             readonly properties: {
                 readonly sessionRef: {
                     readonly type: "object";
@@ -670,9 +597,6 @@ declare const runSessionParamsSchema: {
                         readonly type: "string";
                     };
                 };
-                readonly poolKey: {
-                    readonly type: "string";
-                };
                 readonly journalPath: {
                     readonly type: "string";
                 };
@@ -681,4 +605,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { AgentCallOpts, AgentOutcome, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostPermissionParams, type HostPermissionResult, type HostPoolResolvedParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_NAMES, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseChannelParamsMap, type ReverseChannelResultMap, type ReverseRequestTimeoutClass, type RunContextParams, type RunParams, type RunResult, type RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isHostStreamDeltaParams, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { AgentCallOpts, AgentOutcome, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseRequestTimeoutClass, type RunContextParams, type RunParams, type RunResult, type RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };

package/dist/protocol/index.js

@@ -3,10 +3,8 @@ import {
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   errorResponseFrameSchema,
-  isHostStreamDeltaParams,
   isNotificationFrame,
   isRequestFrame,
   isResponseFrame,
@@ -17,7 +15,7 @@ import {
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-TGDMOLZU.js";
+} from "../chunk-TW2FAMAJ.js";
 import {
   CANCEL_SETTLE_GRACE_MS,
   CRASH_REBUILD_BACKOFF_MS,
@@ -42,7 +40,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "../chunk-WS4WAZVR.js";
+} from "../chunk-F5JZMK74.js";
 import "../chunk-JSBRDJBE.js";
 export {
   CANCEL_SETTLE_GRACE_MS,
@@ -60,7 +58,6 @@ export {
   HANDSHAKE_TIMEOUT_MS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
@@ -73,7 +70,6 @@ export {
   errorResponseFrameSchema,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
-  isHostStreamDeltaParams,
   isNotificationFrame,
   isProtocolVersionCompatible,
   isRequestFrame,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-engine-sdk",
-  "version": "0.3.0",
+  "version": "0.5.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",

package/src/env.ts

@@ -67,7 +67,14 @@ export interface EngineChildEnvOptions {
   electronRunAsNode?: boolean;
   /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 XYZ_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
   relay?: EngineRelayEnv;
-  /** L0：引擎侧身份 env（PI_SUBAGENT_ROOT_SESSION_ID 等，base-tool-enhance / 递归可见性消费） */
+  /**
+   * L0：引擎侧身份 env 透传通道（identityEnv）。现行事实（ext-simplify-17 D4，
+   * 20260914 真机探针证实）：PI_SUBAGENT_ROOT_SESSION_ID / PI_SUBAGENT_SELF_RECORD_ID
+   * 两键已无写入方（本通道现无人传值），引擎链统一 subagent 标记 = XYZ_AGENT_SUBAGENT=1
+   * （见 injectL0InfraKeys 恒注入），base-tool-enhance 判据已重锚新标记。通道保留待
+   * 另行裁决，读者见 docs/architecture/ext-simplify-17-shared-extraction.md §3.1 D4
+   * 与探针报告 .tmp/dev-flow/ext-simplify-17-d4-probe.md。
+   */
   identityEnv?: Record<string, string | undefined>;
   /** L2：manifest 声明的 envPrefixes 放行清单（保留前缀拒绝 + 形态校验） */
   envPrefixes?: readonly string[];

package/src/nesting-guard.ts

@@ -17,7 +17,7 @@
 //
 // [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
 // 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
-// 单点于公共层。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-⑤
+// 单点于公共层。设计权威源：docs/design/dual-track（已删 git 可追溯）§3.3 D3-⑤
 // + 双轨清单 #10。
 
 import { AsyncLocalStorage } from "node:async_hooks";

package/src/paths.ts

@@ -7,7 +7,7 @@ import { join } from 'node:path';
  * 自算池/journal 路径）；core 侧引用切换已完成（core execution/engine/paths.ts 为
  * re-export shim，子入口 ./engine/paths 解析路径不变）。
  *
- * 设计权威源：subagent-engine-abstraction.md D5/D6。
+ * 设计权威源：constraints.json C-ext-15（原 subagent-engine-abstraction.md D5/D6，已删，git 可追溯）。
  *
  * 为什么独立成模块：extension 写侧（journal 落盘 / preparer 池目录）与
  * runtime 校验侧（subagent-extractor 前缀白名单）必须同源推导——

package/src/port-contract.ts

@@ -63,19 +63,21 @@ export interface EngineStream {
 }
 
 /**
- * 无隔离池引擎的恒定池 key（pi / zcode 共用；值锚定）：两引擎进程内全局一份运行态
- * （pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享宿主 HOME + journal 固定分组），
- * poolKey 恒本值。core（PI_POOL_KEY / JOURNAL_INITIAL_POOL_KEY）与两引擎包
- * （PI_POOL_KEY / ZCODE_SHARED_POOL_KEY）的等值异名常量一律 = 本常量——**值逐字
- * 不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。zcode 池化引擎在
- * prepare 期经 ctx.onPoolResolved retarget 到实际池 key，与本占位值不冲突。
+ * journal 固定分组 key（值锚定，**只承载、不透传**）：journal 落盘路径
+ * `<dataDir>/engines/<engineId>/<本值>/journal-<taskId>.jsonl` 的第二段，两引擎恒
+ * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
+ * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
+ * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
+ * 三类消费：① journal 落盘路径构造（core journal-wiring）；② 存量 record 兼容
+ * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
+ * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
+ * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
  */
 export const SHARED_POOL_KEY = "shared";
 
 /** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
 export interface RunContext {
   taskId: string;
-  poolKey: string;
   signal?: AbortSignal;
   onEvent?: (event: AgentEvent) => void;
   ctxModel?: EngineCtxModel;
@@ -94,8 +96,7 @@ export interface RunContext {
    * [LEGACY] fallback（独立运行/测试形态）。
    */
   sessionDir?: string;
-  onPoolResolved?: (poolKey: string) => void;
-  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
   /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
   onChildSpawned?: (child: { pid: number | undefined; killed: boolean }) => void;
   /**

package/src/protocol/contract-types.ts

@@ -1,21 +1,21 @@
 // src/protocol/contract-types.ts
 //
 // 引擎面契约类型 SSOT（协议两侧不许各写一份；core 反向 re-export 保上层消费面）。
-// 设计权威源：docs/design/subagent-engine-protocolization.md §3.5.1 D7 类型闭包表 +
+// 设计权威源：docs/architecture/subagent-engine-protocolization.md §3.5.1 D7 类型闭包表 +
 // impl-plan §2.1「类型闭包处置」。
 //
 // 搬运口径（逐字对照，结构等价、零 core import）：
 //   - AgentEvent / AgentUsage / AgentUsageTotal / ToolCallResult / ToolCall /
-//     InternalToolCall / Turn ← core execution/types.ts（2026-09-09 实测 :164-:313）
+//     InternalToolCall / Turn ← core execution/assembly/types.ts（2026-09-09 实测 :164-:313）
 //   - ReplayedTurn / SessionView / EngineHandleData / EngineCapabilities / ProbeReport /
 //     AgentOutcome ← core execution/engine/types.ts
 //   - AgentFailureKind / AgentOutcomeUsage（core 名 AgentUsage，orchestration 版）/
 //     ToolCallEntry / AgentCallOpts 子集 ← core orchestration/models/types.ts
-//   - WorktreeHandle ← core execution/types.ts:349（SDK 结构等价副本——设计 §3.5.1
+//   - WorktreeHandle ← core execution/assembly/types.ts:349（SDK 结构等价副本——设计 §3.5.1
 //     点名「AgentCallOpts.worktree 的 WorktreeHandle 即这类副本」）
 //
 // [H1] InteractAction / InteractResult 已随 chat-run 统一退役（U5 删除；
-// docs/design/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
+// docs/architecture/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
 //
 // core 域类型（ExecutionRecord / Turn 的宿主内部态消费）留 core；SDK 侧一切类型为
 // 结构等价形态，漂移由双向可赋值断言（AssertMutuallyAssignable）在 typecheck 期抓出
@@ -44,7 +44,7 @@ export type AssertMutuallyAssignable<A, B> = [A] extends [B]
 // 事件面（AgentEvent 及其字段型）
 // ============================================================
 
-/** token 用量（message_end 单条消息增量）。← core execution/types.ts AgentUsage。 */
+/** token 用量（message_end 单条消息增量）。← core execution/assembly/types.ts AgentUsage。 */
 export interface AgentUsage {
   input: number;
   output: number;
@@ -100,7 +100,7 @@ export interface Turn {
 
 /**
  * 引擎事件（9 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
  *
  * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
  * （core journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
@@ -131,9 +131,11 @@ export interface EngineHandleData {
   engineId: string;
   /** 引擎自定义定位键值。pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }。 */
   sessionRef: Record<string, string>;
-  /** 隔离池定位。pi 无池化恒 'shared'。 */
-  poolKey: string;
-  /** journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。 */
+  /**
+   * journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。
+   * [池抽象降级 2026-09-13] 原 poolKey 字段已删除——两引擎 poolKey 恒 'shared'
+   * （SDK SHARED_POOL_KEY），journal 固定落 engines/<engineId>/shared/，字段零信息量。
+   */
   journalPath?: string;
   /** probe 实测版本（漂移排查锚点）。 */
   engineVersion?: string;
@@ -152,8 +154,6 @@ export interface EngineHandleData {
 export interface ResumeAnchor {
   /** 引擎定位键（pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }）。 */
   sessionRef: Record<string, string>;
-  /** 隔离池定位（锚点补全 handle 重建所需；pi 无池化恒 'shared'）。 */
-  poolKey: string;
   /** journal 绝对路径（read 降级链第②级数据源；无 journal 缺省）。 */
   journalPath?: string;
 }
@@ -196,11 +196,16 @@ export interface EngineCapabilities {
   /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
   steer: "native" | "emulated" | "unsupported";
   /**
-   * [H1 D5 语义收窄] resume 能力位（chat 续聊 = 新 run + resume 锚点的承载前提；
+   * [H1 D5 语义收窄 + modeless] 「怎么续」形态轴兼 message 资格轴：
+   * 位非 'unsupported' = 引擎可续聊（core capability-gate 的 message 资格门消费），
+   * 值区分续聊形态——native（原地续写）/ cold（冷恢复重建 + 新 run + resume 锚点）。
    * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
-   * 「resume 续聊能力」，gate 判据与消费方不变）。
+   * 「resume 续聊能力」。[modeless 波2] 会话形态键只剩 run.params.resume（协议
+   * task.conversation 已删），本轴不再是 per-run 模式开关——描述各引擎的真实
+   * 续聊差异（gate 判据仍是 `=== "unsupported"` 拒绝，"cold" 与 "native" 等价
+   * 放行）。
    */
-  conversation: "native" | "unsupported";
+  conversation: "native" | "cold" | "unsupported";
   /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
   personaInjection: "file" | "flag" | "prompt";
   /** 粗粒度引擎：GUI 显示降级为阶段态。 */
@@ -258,7 +263,7 @@ export interface ToolCallEntry {
   input: string;
 }
 
-/** worktree 句柄（结构等价副本；core 权威定义在 execution/types.ts:349）。 */
+/** worktree 句柄（结构等价副本；core 权威定义在 execution/assembly/types.ts:349）。 */
 export interface WorktreeHandle {
   /** checkout 目录（子 agent 工作目录）。 */
   readonly path: string;
@@ -317,7 +322,7 @@ export interface ModelCatalogEntry {
  *
  * 字段裁决（对照 core orchestration/models/types.ts AgentCallOpts，2026-09-09）：
  * - 入选 = 引擎消费面：任务语义（prompt/schema/thinkingLevel/skill/skillPath/agent/persona 注入）、
- *   轮次预算（maxTurns/graceTurns/conversation/idleTimeoutMs）、隔离与权限（worktree/
+ *   轮次预算（maxTurns/graceTurns/idleTimeoutMs）、隔离与权限（worktree/
  *   fork/forkSource/denyTools/permissionMode）、诊断（description/scene）；
  * - 排除并改挂 run.params.ctx（协议层已单列，task 内双写会分叉）：model（→ctx.model）、
  *   schemaEnv（→ctx.schemaEnv）、cwd（→ctx.cwd）、engineFallback（→ctx.engineFallback）；
@@ -364,9 +369,7 @@ export interface AgentCallOpts {
   forkSource?: string;
   /** Filesystem isolation: 新建 worktree | 复用外部已创建 worktree | 不隔离。 */
   worktree?: boolean | WorktreeHandle;
-  /** 可持续对话模式：true = 轮次完成进 idle 态等待 message 续聊。 */
-  conversation?: boolean;
-  /** 空闲超时毫秒数（仅 conversation 模式有意义）。显式 0/负 = 禁用 idle GC。 */
+  /** 空闲超时毫秒数（[modeless] 全体 record 的 idle 回收节奏；显式 0/负 = 禁用 idle GC）。 */
   idleTimeoutMs?: number;
   /** 工具 denylist（各引擎做语法映射）。 */
   denyTools?: string[];

package/src/protocol/engine-protocol.ts

@@ -1,7 +1,7 @@
 // src/protocol/engine-protocol.ts
 //
 // 引擎协议 v1 版本常量与协商（W1 契约根）。设计权威源：
-// docs/design/subagent-engine-protocolization.md §3.3 + impl-plan §2.1。
+// docs/architecture/subagent-engine-protocolization.md §3.3 + impl-plan §2.1。
 //
 // 传输 = stdio NDJSON（每行一个 JSON 对象）。stdout 独占协议帧；stderr 常驻排空
 // （内存环形缓冲尾 400 字符，崩溃现场由 engine_crashed 携带，宿主侧不落盘）。
@@ -11,17 +11,18 @@
 // 不影响其他引擎与宿主。
 //
 // [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）][H1 后历史叙述——run.params.chat
-// 已随 U6 删除，现唯一会话形态键 = run.params.resume]：chat 域增量（原 run.params.chat
-// 可选参数、host/streamDelta 的 recordId 关联形态）曾以**可选载荷/可选参数**形态向后
-// 兼容，major 不 bump、不引入 minor 协商位：
-//   - 新 core × 旧引擎：conversation 请求（resume 续聊形态）被 conversation gate
+// 已随 U6 删除，现唯一会话形态键 = run.params.resume；[modeless 波2] 协议 task 的
+// conversation 键已删（core 侧 deprecated 参数不再上 wire，resume 键携带全部会话
+// 形态）]：chat 域增量曾以**可选载荷/可选参数**形态向后兼容，major 不 bump、不引入
+// minor 协商位：
+//   - 新 core × 旧引擎：会话形态请求（resume 续聊）被 conversation gate
 //     同步拒（manifest 无 gate 位，
 //     A6 方向——engine_capability_unsupported + 升级引擎包指引）；run 域零影响；
 //   事件变体增量同政策（例：activity 活性信号变体）：新变体以可选载荷形态进
 //   union，旧宿主 runtime 对其 no-op（reducer default 分支安全落空 / journal
 //   豁免面不感知），协议版本维持 1、不 bump。
 //
-// [H1 双键过渡（chat-run 统一，docs/design/subagent-chat-run-unification.md §3.3
+// [H1 双键过渡（chat-run 统一，docs/architecture/subagent-chat-run-unification.md §3.3
 // D3 + §5 U1 行）][H1 U6 已切换]：run.params.resume 曾与原 run.params.chat 载荷
 // 同形并存（additive 可选，协议版本维持 1）；U1 只加键——U2-U5 过渡期 core 恒
 // 构造旧 `chat` 键、pi 引擎恒读 `ctx.chat`。U6 已单批同时切换写端（core 构造
@@ -83,9 +84,9 @@ export const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+ * - 数据面类（host/log / host/streamDelta / host/handleReady /
  *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
- * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */
 export type ReverseRequestTimeoutClass = "data-plane" | "interaction";

package/src/protocol/error-codes.ts

@@ -101,33 +101,32 @@ export function engineProtocolMismatchError(engineVersion: number): EngineSdkErr
 }
 
 // ============================================================
-// [v1.x] conversation gate 位负向：conversation 请求（resume 续聊会话形态）同步拒
+// conversation gate 位负向：manifest 能力轴（message 资格 / 「怎么续」形态轴）
 // ============================================================
 
 /**
- * [v1.x] resume 会话形态（run.params.resume）的 gate 拒绝具名错误（chat-domain
- * 设计 §3.2 D1-A + 验收 A6：manifest 无 conversation gate 位的引擎收到
- * conversation 请求 → 同步拒；[H1] 文案随 D5 语义收窄——续聊 = resume 续聊）。
- * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
- * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
- * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
+ * 引擎 conversation 位拒绝的具名错误（[modeless 波2] 语义：无 resume 续聊通道的
+ * 引擎，message 续聊资格被拒——manifest conversation 能力轴消费，core
+ * capability-gate 的 conversation 分支与 message 资格门双写点共用本构造器）。
+ * 文案契约：错误码 engine_capability_unsupported + 「去掉参数 / 修 manifest /
+ * 升级引擎包」恢复指引，两侧一致防漂移。
  */
 export function engineConversationUnsupportedError(engineId: string): EngineSdkError {
   return new EngineSdkError(
     "engine_capability_unsupported",
     `engine '${engineId}' 不支持 resume 续聊（capabilities.conversation = 'unsupported'，` +
       `manifest 无 conversation gate 位）`,
-    `去掉 conversation 参数（一次性任务默认形态），或修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）`,
+    `去掉 conversation 参数（modeless 下无行为效果），或修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）`,
     { engineId, capability: "conversation", declared: "unsupported" },
   );
 }
 
 /**
- * [v1.x] resume 会话形态（run.params.resume / task.conversation=true）派发前的同步 gate：
- * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
- * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
- * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支
- * 覆盖同一能力位，协议客户端路径（W3 接线）消费本函数，防两处判据漂移。
+ * resume 会话形态（run.params.resume——唯一会话形态键）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError
+ * ——进程/record 创建前同步拒（A6 方向防御：manifest/实装漂移时引擎侧自拒，
+ * 与 core capability-gate 同一能力位，防两侧判据漂移）。[modeless 波2] 协议
+ * task 的 conversation 键已删，本 gate 只对 resume 形态键生效。
  */
 export function assertChatConversationSupported(
   engineId: string,

package/src/protocol/frames.ts

@@ -82,13 +82,11 @@ export interface ReverseRequestFrame {
 export type ReverseResponseResult =
   /** 数据面类：处理确认。 */
   | { ok: true }
-  /** 人机交互类（askUser/permission）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+  /** 人机交互类（askUser）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
   | { ack: true }
   /** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
   | { unsupported: true };
 
-export type AnyFrame = RequestFrame | ResponseFrame | NotificationFrame | ReverseRequestFrame;
-
 // ============================================================
 // 判别守卫（W2 行解析器消费；结构判定，不抛错）
 // ============================================================

package/src/protocol/methods.ts

@@ -5,7 +5,7 @@
 //
 // [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：增量以可选参数形态落在 run.params.chat
 // （会话形态参数 + 冷续 resume 锚点），major 不 bump。[H1] chat-run 统一后续聊 =
-// 新 run + resume 锚点（docs/design/subagent-chat-run-unification.md §3.3 D5/D7），
+// 新 run + resume 锚点（docs/architecture/subagent-chat-run-unification.md §3.3 D5/D7），
 // 既有 interact 方法已随 U5 删除，方法集收敛为 9 个。
 //
 // 应答面补充约定（设计 §3.3）：initialize 应答仅诊断（与 manifest 不一致 → warn 留痕，
@@ -26,7 +26,7 @@ import type {
 
 /**
  * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
- * [H1] `interact` 成员已随 chat-run 统一退役（docs/design/subagent-chat-run-unification.md
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
  * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
  */
 export type ProtocolMethod =
@@ -61,8 +61,6 @@ export const PROTOCOL_METHODS = [
  * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
  */
 export interface RunContextParams {
-  /** 隔离池归属（journal 归属错 = 缺失后果）。 */
-  poolKey: string;
   /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
   cwd: string;
   /** 请求模型 ref（未传 = 引擎缺省模型）。 */
@@ -96,7 +94,7 @@ export interface RunContextParams {
 // ============================================================
 
 /**
- * [H1] run 的 resume 会话形态参数（设计 docs/design/subagent-chat-run-unification.md
+ * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
  * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
  * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
  * 泛化为「resume 续聊」。