@zhushanwen/subagent-engine-sdk 0.2.0

package/src/paths.ts

@@ -0,0 +1,48 @@
+import { join } from 'node:path';
+
+/**
+ * 引擎数据目录布局 SSOT（引擎侧原语，自 core execution/engine/paths.ts 移入
+ * @zhushanwen/subagent-engine-sdk，实现体逐字等价）。
+ * 迁移处置（impl-plan §2.1 paths 行）：纯 `node:path` 模块 → **移入 SDK**（引擎侧需
+ * 自算池/journal 路径）；core 侧引用切换已完成（core execution/engine/paths.ts 为
+ * re-export shim，子入口 ./engine/paths 解析路径不变）。
+ *
+ * 设计权威源：subagent-engine-abstraction.md D5/D6。
+ *
+ * 为什么独立成模块：extension 写侧（journal 落盘 / preparer 池目录）与
+ * runtime 校验侧（subagent-extractor 前缀白名单）必须同源推导——
+ * 双方 import 同一份纯函数，禁止各自拼字符串漂移。
+ *
+ * 布局：`<dataDir>/engines/<engineId>/<pool-key>/journal-<taskId>.jsonl`
+ * 隔离池跨任务保留复用；journal 生命周期跟随 record，不随池删除（D5）。
+ */
+
+/** 路径段安全编码后的最大字符数（防超长段击穿文件名长度上限；runtime 校验侧同源）。 */
+const MAX_SEG_CHARS = 80;
+
+/** 路径段进入文件系统前的安全编码：路径穿越、分隔符、空白、超长全部归一。 */
+export function sanitizeSeg(input: string): string {
+  const s = input.replace(/[^A-Za-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return s.length > 0 ? s.slice(0, MAX_SEG_CHARS) : 'default';
+}
+
+export function resolveEnginesRoot(dataDir: string): string {
+  return join(dataDir, 'engines');
+}
+
+export function resolveEngineDir(dataDir: string, engineId: string): string {
+  return join(resolveEnginesRoot(dataDir), sanitizeSeg(engineId));
+}
+
+export function resolvePoolDir(dataDir: string, engineId: string, poolKey: string): string {
+  return join(resolveEngineDir(dataDir, sanitizeSeg(engineId)), sanitizeSeg(poolKey));
+}
+
+export function resolveJournalPath(
+  dataDir: string,
+  engineId: string,
+  poolKey: string,
+  taskId: string,
+): string {
+  return join(resolvePoolDir(dataDir, engineId, poolKey), `journal-${sanitizeSeg(taskId)}.jsonl`);
+}

package/src/port-contract.ts

@@ -0,0 +1,117 @@
+// src/port-contract.ts
+//
+// 引擎进程内契约面七符号 + parseCtxModel 单源（S4 簇 1 收编：pi/zcode 两包
+// port-types.ts 的逐字等价本地镜像收编——两包原地改 re-export shim，18 个 import
+// 点零改写；server.ts 的 parseCtxModel 模块级纯函数同批收编，实现以 pi 版为基线
+// 逐字迁移）。
+//
+// 为什么现在能收（W5/W7 双轨沉淀后的收编，不翻「SDK 类型闭包只收跨进程协议面」
+// 的原始裁决）：两包过渡期镜像经 W10 conformance 套件验证字段逐字等价、双轨已
+// 稳定，收编即消除克隆而非改变边界语义。RunContext 含 AbortSignal/回调/EngineStream
+// 等非序列化成员，跨进程面经各包 server.ts 帧映射——故收主 barrel，不进 protocol/
+// 子入口（protocol/ 是 semver 收窄的跨进程可序列化面）。
+//
+// 命名：全量任务声明在 SDK 侧名 EngineAgentCallOpts（主 barrel 已有 protocol 的
+// AgentCallOpts 引擎面子集——16 字段协议 run.params.task 形态，两者是子集/全量
+// 关系，不可同名共存；两包 shim 转名 re-export 保本包消费面 AgentCallOpts 不变）。
+//
+// onChildSpawned 统一采窄载荷形态（host/childSpawned 载荷形态；ChildProcess 句柄
+// 不跨协议面）——zcode 侧生产零调用（D6），形态统一无行为影响。
+//
+// 第三份镜像登记：core execution/engine/port.ts 的 RunContext 是宿主侧独立契约
+// （onChildSpawned 全 ChildProcess 句柄，概念域 = 宿主进程内），不收编、不 import
+// 本模块；漂移面由 W10 conformance 套件继续覆盖。
+
+import type {
+  AgentCallOpts as SdkAgentCallOpts,
+  AgentEvent,
+  AgentOutcome,
+  EngineCapabilities,
+  EngineHandleData,
+  InteractAction,
+  InteractResult,
+  ProbeReport,
+  ResumeAnchor,
+  SessionView,
+} from "./protocol/contract-types.ts";
+
+/**
+ * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
+ * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
+ * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
+ */
+export type EngineAgentCallOpts = SdkAgentCallOpts & {
+  model?: string;
+  cwd?: string;
+  schemaEnv?: string;
+};
+
+/**
+ * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
+ * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
+ */
+export interface EngineCtxModel {
+  id: string;
+  provider: string;
+  name?: string;
+  reasoning?: boolean;
+  thinkingLevelMap?: Record<string, unknown>;
+  contextWindow?: number;
+}
+
+/** text_delta streaming 出口（协议 host/streamDelta 的本地承载）。 */
+export interface EngineStream {
+  onDelta(delta: string): void;
+}
+
+/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+export interface RunContext {
+  taskId: string;
+  poolKey: string;
+  signal?: AbortSignal;
+  onEvent?: (event: AgentEvent) => void;
+  ctxModel?: EngineCtxModel;
+  stream?: EngineStream;
+  schemaEnv?: string;
+  engineFallback?: { from: string; reason: string };
+  onPoolResolved?: (poolKey: string) => void;
+  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+  /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
+  onChildSpawned?: (child: { pid: number | undefined; killed: boolean }) => void;
+  /**
+   * [v1.x] chat 会话形态参数（协议 run.params.chat 的进程内还原；缺省 = 一次性任务
+   * 形态）。recordId = chat 轮次关联键与 interact 定位键；resume 锚点存在 = 冷续
+   * （--session 续写原文件），不存在 = 首轮新建。
+   */
+  chat?: { recordId: string; resume?: ResumeAnchor };
+}
+
+export interface EngineHandle {
+  readonly data: EngineHandleData;
+}
+
+export interface EngineRunResult {
+  handle: EngineHandle;
+  outcome: AgentOutcome;
+}
+
+/** 引擎进程内的引擎契约点（core EnginePort 的结构等价镜像）。 */
+export interface EnginePort {
+  readonly id: string;
+  capabilities(): EngineCapabilities;
+  probe(opts?: { force?: boolean }): Promise<ProbeReport>;
+  run(task: EngineAgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
+  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
+  read(handle: EngineHandle): Promise<SessionView>;
+  listModels?(): Array<{ id: string; name?: string }> | null;
+  validateModel?(modelRef: string | undefined): { canonicalRef: string };
+  dispose?(): Promise<void>;
+}
+
+/** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */
+export function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined {
+  if (ref === undefined || ref.trim() === "") return undefined;
+  const slash = ref.indexOf("/");
+  if (slash <= 0 || slash === ref.length - 1) return undefined;
+  return { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}

package/src/protocol/contract-types.ts

@@ -0,0 +1,378 @@
+// src/protocol/contract-types.ts
+//
+// 引擎面契约类型 SSOT（协议两侧不许各写一份；core 反向 re-export 保上层消费面）。
+// 设计权威源：docs/design/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）
+//   - ReplayedTurn / SessionView / EngineHandleData / EngineCapabilities / ProbeReport /
+//     InteractAction / InteractResult / 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
+//     点名「AgentCallOpts.worktree 的 WorktreeHandle 即这类副本」）
+//
+// core 域类型（ExecutionRecord / Turn 的宿主内部态消费）留 core；SDK 侧一切类型为
+// 结构等价形态，漂移由双向可赋值断言（AssertMutuallyAssignable）在 typecheck 期抓出
+// ——core 侧断言挂靠归 W2（本文件导出该类型助手供其复用），SDK 侧样板见
+// src/__tests__/contract-closure.test.ts。
+
+// ============================================================
+// 断言助手（W2 core 侧双向可赋值断言复用）
+// ============================================================
+
+/**
+ * 双向可赋值断言：`type _A = AssertMutuallyAssignable<CoreX, SdkX>` 结果必须为 true。
+ * 任一方向不可赋值（字段缺失 / 可选性漂移 / 联合分支不齐）结果为 never → 编译失败。
+ * 用法（core 侧 W2 挂靠）：
+ *   import type { AssertMutuallyAssignable } from "@zhushanwen/subagent-engine-sdk";
+ *   type _CoreSdkAgentEvent = AssertMutuallyAssignable<CoreAgentEvent, SdkAgentEvent>;
+ *   const _assert: _CoreSdkAgentEvent = true;
+ */
+export type AssertMutuallyAssignable<A, B> = [A] extends [B]
+  ? [B] extends [A]
+    ? true
+    : never
+  : never;
+
+// ============================================================
+// 事件面（AgentEvent 及其字段型）
+// ============================================================
+
+/** token 用量（message_end 单条消息增量）。← core execution/types.ts AgentUsage。 */
+export interface AgentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  /** 本 message 的成本（USD）。无成本数据时缺省。 */
+  cost?: number;
+}
+
+export interface AgentUsageTotal extends AgentUsage {
+  /** 四项之和。投影时不再手工求和。 */
+  total: number;
+  /** 累计成本（USD）。无成本数据时为 0。 */
+  cost: number;
+}
+
+/** tool 调用结果（tool_end 携带，含 structured-output 的 details）。 */
+export interface ToolCallResult {
+  content?: unknown[];
+  details?: unknown;
+}
+
+/** tool 调用（导出的纯净数据形状，不含内部状态机）。 */
+export interface ToolCall {
+  toolName: string;
+  args?: unknown;
+  result?: ToolCallResult;
+  isError?: boolean;
+}
+
+/** 内部 ToolCall：追加 _status 进行中标记与 startedTs（reducer 内部态，跨边界导出前 strip）。 */
+export interface InternalToolCall extends ToolCall {
+  _status: "running" | "done" | "failed";
+  /** tool_start 到达时的墙钟时间戳（Date.now()，ms）。 */
+  startedTs: number;
+}
+
+/** 一个 turn 的完整内容（reducer turns[] 的元素）。 */
+export interface Turn {
+  /** 本 turn assistant 正文（text_delta 流式累积，完整）。 */
+  text: string;
+  /** 本 turn 推理（thinking_delta 流式累积，完整）。 */
+  thinking: string;
+  /** 本 turn 工具调用（InternalToolCall：含完整 result + _status 进行中标记）。 */
+  toolCalls: InternalToolCall[];
+  /** 本 turn message_end 的 token 增量（聚合得 usage 总量）。 */
+  usageDelta?: AgentUsage;
+  /** turn_end 是否已到达。false=正在进行；true=已闭合。 */
+  closed: boolean;
+  /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。 */
+  closedTs?: number;
+}
+
+/**
+ * 引擎事件（8 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
+ * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ */
+export type AgentEvent =
+  | { type: "tool_start"; toolName: string; args?: unknown }
+  | { type: "tool_end"; toolName: string; args?: unknown; result?: ToolCallResult; isError?: boolean }
+  | { type: "text_delta"; delta: string }
+  | { type: "thinking_delta"; delta: string }
+  | { type: "turn_end"; summary?: string }
+  | { type: "message_end"; usage?: AgentUsage; error?: string }
+  | { type: "compaction" }
+  | { type: "error"; message: string };
+
+// ============================================================
+// handle / read 视图
+// ============================================================
+
+/**
+ * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / interact / read 的
+ * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
+ */
+export interface EngineHandleData {
+  v: 1;
+  /** 引擎 id（'pi' | 'zcode' | ...）。 */
+  engineId: string;
+  /** 引擎自定义定位键值。pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }。 */
+  sessionRef: Record<string, string>;
+  /** 隔离池定位。pi 无池化恒 'shared'。 */
+  poolKey: string;
+  /** journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。 */
+  journalPath?: string;
+  /** probe 实测版本（漂移排查锚点）。 */
+  engineVersion?: string;
+  /** 适配器版本（golden 样本对齐排查）。 */
+  adapterVersion: string;
+}
+
+/**
+ * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
+ * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。两处消费：
+ *   - run.params.chat.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
+ *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）；
+ *   - host/roundLifecycle 载荷 anchor（引擎 → 宿主：轮次终态时回填当前锚点，
+ *     宿主据此刷新冷续依据——pi 定位键形态同 EngineHandleData.sessionRef 注释）。
+ * 类型层与 EngineHandleData 定位形态的对照由测试断言（Pick 可赋值闭包）锁定。
+ */
+export interface ResumeAnchor {
+  /** 引擎定位键（pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }）。 */
+  sessionRef: Record<string, string>;
+  /** 隔离池定位（锚点补全 handle 重建所需；pi 无池化恒 'shared'）。 */
+  poolKey: string;
+  /** journal 绝对路径（read 降级链第②级数据源；无 journal 缺省）。 */
+  journalPath?: string;
+}
+
+/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义）。 */
+export interface ReplayedTurn {
+  text: string;
+  thinking: string;
+  /** 导出的纯净形状（ToolCall，无 _status/startedTs）。 */
+  toolCalls: ToolCall[];
+  closed: true;
+}
+
+/**
+ * session 历史的引擎中立视图（协议 read 应答）。降级链三级：①引擎原生读取 →
+ * ②宿主 event journal 重放 → ③outcome-only。source 字段是 GUI 降级标记数据源。
+ */
+export interface SessionView {
+  engineId: string;
+  sessionId?: string;
+  /** turns[] 派生数据（重放/重建产物）。 */
+  turns: ReplayedTurn[];
+  /** 各 turn usageDelta 聚合。 */
+  usage?: AgentUsageTotal;
+  source: "native" | "journal" | "outcome-only";
+}
+
+// ============================================================
+// 能力 / 探针 / 交互
+// ============================================================
+
+/**
+ * 引擎能力声明（11 位）。三级：native / emulated / unsupported。
+ * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
+ * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
+ */
+export interface EngineCapabilities {
+  /** native: --json-schema/--output-schema/env 注入。 */
+  schemaEnforcement: "native" | "emulated";
+  /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
+  steer: "native" | "emulated" | "unsupported";
+  /** interact 控制面（message/close/cancel + idle）。 */
+  conversation: "native" | "unsupported";
+  /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
+  personaInjection: "file" | "flag" | "prompt";
+  /** 粗粒度引擎：GUI 显示降级为阶段态。 */
+  eventGranularity: "stream" | "coarse";
+  /** emulated = worktree 隔离（无 OS sandbox 的引擎用文件写维度隔离补齐）。 */
+  sandbox: "native" | "emulated" | "none";
+  /** 重建历史的能力（read 降级链第①级保真度上限）。 */
+  sessionRead: "full" | "partial" | "outcome-only";
+  resume: "native" | "cold" | "unsupported";
+  /** 优雅中断 or 只能杀进程（公共杀链兜底）。 */
+  interrupt: "native" | "kill-only";
+  /** kimi headless 固定 auto = ignored；GUI 据此隐藏/提示。 */
+  permissionMode: "native" | "fixed" | "ignored";
+  /** maxTurns 轮数上限执行能力位（pi=true / zcode=false）。 */
+  maxTurns: boolean;
+}
+
+/** 引擎探针报告（probe 应答）。ok=false 时 error 必填（恢复指引）。 */
+export interface ProbeReport {
+  ok: boolean;
+  /** 实测版本（探测不到时为空串）。 */
+  engineVersion: string;
+  /** 二进制存在/版本解析/干跑回归逐项。 */
+  checks: Array<{ name: string; ok: boolean; detail?: string }>;
+  /** engine_probe_failed 的恢复指引（ok=false 时必填）。 */
+  error?: { code: string; recovery: string };
+}
+
+/**
+ * interact 的 action（交互控制面）。interrupt: true = steer（抢占）/ false|缺省 =
+ * followUp（排队）；不支持抢占的引擎忽略。
+ */
+export type InteractAction =
+  | { kind: "message"; payload: string; interrupt?: boolean }
+  | { kind: "close"; payload?: { force: boolean } }
+  | { kind: "cancel" };
+
+/** interact 的结果（失败码 = engine_session_not_resumable / engine_capability_unsupported 等）。 */
+export type InteractResult =
+  | { ok: true; delivered: true }
+  | { ok: false; code: string; message: string };
+
+// ============================================================
+// 终态 / 任务声明
+// ============================================================
+
+/** 失败分诊结构化标签。unknown（含缺省）= 可重试（语义守恒）。 */
+export type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+
+/**
+ * AgentOutcome.usage 字段型（← core orchestration/models/types.ts AgentUsage 结构等价；
+ * SDK 改名消歧——core 的两个同名 AgentUsage 分属 execution 与 orchestration 域）。
+ */
+export interface AgentOutcomeUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+/** 单次 tool 调用记录（workflow trace 形态）。 */
+export interface ToolCallEntry {
+  /** Tool name. */
+  name: string;
+  /** Args preview string. */
+  input: string;
+}
+
+/** worktree 句柄（结构等价副本；core 权威定义在 execution/types.ts:349）。 */
+export interface WorktreeHandle {
+  /** checkout 目录（子 agent 工作目录）。 */
+  readonly path: string;
+  readonly branch: string;
+  readonly baseCommit: string;
+  /** 主仓库根目录（cleanup/scan 需要）。 */
+  readonly mainCwd: string;
+}
+
+/**
+ * 一次引擎执行的终态（协议 run 终态应答的 outcome 载荷）。锚定 core
+ * orchestration AgentResult 并追加引擎层字段（engineId / engineFallback / exitCode）。
+ */
+export interface AgentOutcome {
+  content: string;
+  /** 失败分诊标签。产出侧 = 引擎；缺省 = unknown = 可重试。 */
+  failureKind?: AgentFailureKind;
+  /** native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：native 路径宿主不做二次校验）。 */
+  parsedOutput?: unknown;
+  usage?: AgentOutcomeUsage;
+  durationMs?: number;
+  /** 错误码前缀格式（`<code>: <detail>`，错误规格见协议 error-codes）。 */
+  error?: string;
+  /** 引擎语义 session id。 */
+  sessionId?: string;
+  sessionFile?: string;
+  /** 仅诊断——目录可能已被 finalize 清理，不得作为 cwd 复用。 */
+  worktreePath?: string;
+  toolCalls?: ToolCallEntry[];
+  /** 实际执行引擎（fallback 后可能 ≠ 请求值）。 */
+  engineId: string;
+  /** fallback 留痕（record 同步投影，GUI 警告条数据源）。 */
+  engineFallback?: { from: string; reason: string };
+  /** null = 被信号杀死（杀链/abort 合成终态的判据）。 */
+  exitCode?: number | null;
+}
+
+// ============================================================
+// AgentCallOpts 引擎面子集（协议 run.params.task）
+// ============================================================
+
+/**
+ * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
+ * 协议面 = initialize 应答 models? 与 listModels 应答 models 的元素型；
+ * manifest 解析与生成（gen:model-catalog）归 W4/W5 实装。
+ */
+export interface ModelCatalogEntry {
+  id: string;
+  aliases?: string[];
+  canonicalRef?: string;
+}
+
+/**
+ * 单次 agent 调用的任务声明——引擎面子集（协议 run.params.task；core 全量
+ * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费面）。
+ *
+ * 字段裁决（对照 core orchestration/models/types.ts AgentCallOpts，2026-09-09）：
+ * - 入选 = 引擎消费面：任务语义（prompt/schema/thinkingLevel/skill/skillPath/agent/persona 注入）、
+ *   轮次预算（maxTurns/graceTurns/conversation/idleTimeoutMs）、隔离与权限（worktree/
+ *   fork/forkSource/denyTools/permissionMode）、诊断（description/scene）；
+ * - 排除并改挂 run.params.ctx（协议层已单列，task 内双写会分叉）：model（→ctx.model）、
+ *   schemaEnv（→ctx.schemaEnv）、cwd（→ctx.cwd）、engineFallback（→ctx.engineFallback）；
+ * - 排除（宿主侧消费，无引擎语义）：engine（路由决策已完成，收到的引擎即选中值）、
+ *   timeoutMs（宿主超时链 mergeTimeoutSignal → cancel 帧，非引擎参数）、returnMeta
+ *   （core 注释明确「dropped at the pi boundary」，非引擎消费）。
+ *
+ * W2 实装 EngineClient run 帧时以本类型为 params.task；core 侧全量 → 子集的方向性
+ * 收窄（多余字段宿主自持不透传）不构成类型漂移（断言方向见 contract-closure 测试样板）。
+ */
+export interface AgentCallOpts {
+  /** The task prompt to send to the agent. */
+  prompt: string;
+  /** Optional JSON schema for structured output（引擎按 capabilities.schemaEnforcement 分流）。 */
+  schema?: Record<string, unknown>;
+  /** Thinking level override（"high" | "medium" | "low" 等引擎自解释词表）。 */
+  thinkingLevel?: string;
+  /** Scene name passed through for model-selection hints. */
+  scene?: string;
+  /** Turn 上限（turn limiter）。未传或 <=0 = 不限。 */
+  maxTurns?: number;
+  /** Turn limiter 宽限轮数：超 maxTurns 后允许继续的轮数。 */
+  graceTurns?: number;
+  /** Skill name to load（引擎解析为 SKILL.md 注入）。 */
+  skill?: string;
+  /** Resolved absolute path to the skill directory or SKILL.md file. */
+  skillPath?: string;
+  /** Human-readable description for logging and debugging（slug 源字段）。 */
+  description?: string;
+  /** Agent ref (absolute .md path)——身份解析锚点。 */
+  agent?: string;
+  /** System prompt injection CONTENT（非文件路径）。 */
+  appendSystemPrompt?: string[];
+  /** Inherit parent session context (fork mode)。与 worktree（文件隔离）独立。 */
+  fork?: boolean;
+  /**
+   * [v1.x 增量] fork-from 显式分叉源 session 文件绝对路径（断联 subagent 接续场景，
+   * 宿主点名任意已有 session 文件；fork=true 则由引擎用主 session 作源，两者互斥——
+   * 本字段存在时优先）。字段名对齐引擎侧既有 SpawnRunParams.forkSource（pi 引擎经
+   * `--fork <path>` 消费）。可选增量、负向兼容：无此概念的引擎（zcode）按未知可选
+   * 字段忽略，行为与不传一致；宿主能力门（capability-gate）仍按 steer/conversation
+   * 通道族预检，不依赖引擎对本字段的支持声明。
+   */
+  forkSource?: string;
+  /** Filesystem isolation: 新建 worktree | 复用外部已创建 worktree | 不隔离。 */
+  worktree?: boolean | WorktreeHandle;
+  /** 可持续对话模式：true = 轮次完成进 idle 态等待 message 续聊。 */
+  conversation?: boolean;
+  /** 空闲超时毫秒数（仅 conversation 模式有意义）。显式 0/负 = 禁用 idle GC。 */
+  idleTimeoutMs?: number;
+  /** 工具 denylist（各引擎做语法映射）。 */
+  denyTools?: string[];
+  /** 中立权限模式（映射按各引擎 capabilities.permissionMode）。 */
+  permissionMode?: string;
+}

package/src/protocol/engine-protocol.ts

@@ -0,0 +1,81 @@
+// src/protocol/engine-protocol.ts
+//
+// 引擎协议 v1 版本常量与协商（W1 契约根）。设计权威源：
+// docs/design/subagent-engine-protocolization.md §3.3 + impl-plan §2.1。
+//
+// 传输 = stdio NDJSON（每行一个 JSON 对象）。stdout 独占协议帧；stderr 常驻排空
+// （内存环形缓冲尾 400 字符，崩溃现场由 engine_crashed 携带，宿主侧不落盘）。
+//
+// 版本协商：ENGINE_PROTOCOL_VERSION = 1；core 支持 >=1 <2；越界 →
+// engine_protocol_mismatch（含双方版本 + 升级指引），该引擎标记不可用，
+// 不影响其他引擎与宿主。
+//
+// [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）]：chat 域增量（run.params.chat
+// 可选参数、host/roundLifecycle 通道、host/streamDelta 的 recordId 关联形态）以
+// **可选载荷/可选参数**形态向后兼容，major 不 bump、不引入 minor 协商位：
+//   - 新 core × 旧引擎：chat 请求被 conversation gate 同步拒（manifest 无 gate 位，
+//     A6 方向——engine_capability_unsupported + 升级引擎包指引）；run 域零影响；
+//   - 旧 core × 新引擎：新引擎可能发出旧 core 词表外的 host/roundLifecycle——
+//     既有反向路由对未知 host/* 通道回 {unsupported:true} 引擎自行降级，无需
+//     独立负向场景（设计已裁决）。
+
+/** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
+export const ENGINE_PROTOCOL_VERSION = 1;
+
+/**
+ * core 侧支持的协议版本区间（半开区间 [min, max)）：当前 = [1, 2)。
+ * 引擎版本落在区间外 → engine_protocol_mismatch。
+ */
+export const SUPPORTED_PROTOCOL_RANGE = { min: 1, max: 2 } as const;
+
+/** 版本兼容判定（core 握手判据；引擎侧对称用于拒绝过旧/过新宿主）。 */
+export function isProtocolVersionCompatible(version: number): boolean {
+  return (
+    Number.isInteger(version) &&
+    version >= SUPPORTED_PROTOCOL_RANGE.min &&
+    version < SUPPORTED_PROTOCOL_RANGE.max
+  );
+}
+
+// ============================================================
+// 量级常量（impl-plan §2.1 逐项写死，双侧同源）
+// ============================================================
+
+/** 正向数据面反向请求（帧④数据面类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
+export const REVERSE_REQUEST_TIMEOUT_MS = 10_000;
+
+/** initialize 握手超时（ms）：超时 → engine_handshake_timeout，该引擎不可用。 */
+export const HANDSHAKE_TIMEOUT_MS = 10_000;
+
+/** cancel 后引擎收敛终态的窗口（ms）；超时 core 走杀链。 */
+export const CANCEL_SETTLE_GRACE_MS = 3_000;
+
+/** engine_crashed 后重建上限与指数退避序列（ms）：1s / 2s / 4s，超限标记不可用至宿主重启。 */
+export const CRASH_REBUILD_MAX_ATTEMPTS = 3;
+// 逐档具名（impl-plan §2.1 写死 1s/2s/4s；数组字面量元素会触发 no-magic-numbers，
+// 且具名档位与 core kill-chain 的 MS_PER_SECOND 私有具名常量惯例同型）。
+const CRASH_REBUILD_BACKOFF_STEP_1_MS = 1_000;
+const CRASH_REBUILD_BACKOFF_STEP_2_MS = 2_000;
+const CRASH_REBUILD_BACKOFF_STEP_3_MS = 4_000;
+export const CRASH_REBUILD_BACKOFF_MS = [
+  CRASH_REBUILD_BACKOFF_STEP_1_MS,
+  CRASH_REBUILD_BACKOFF_STEP_2_MS,
+  CRASH_REBUILD_BACKOFF_STEP_3_MS,
+] as const;
+
+/** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
+export const STDERR_TAIL_CHARS = 400;
+
+/** 事件合并开关 env 名（设计级默认关闭 = 值 "0"；A1 要求事件逐字段等价，合并不可开）。 */
+export const ENGINE_EVENT_COALESCE_ENV = "XYZ_ENGINE_EVENT_COALESCE";
+export const ENGINE_EVENT_COALESCE_DEFAULT = "0";
+
+/**
+ * 反向请求超时二分（帧④注释，R9-2）：
+ * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+ *   host/childSpawned / host/childStateChanged / host/roundLifecycle[v1.x]）：10s 未答 =
+ *   引擎故障；
+ * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
+ */
+export type ReverseRequestTimeoutClass = "data-plane" | "interaction";