@zhushanwen/subagent-engine-sdk 0.2.1 → 0.4.0

package/dist/port-contract.d.cts

@@ -1,4 +1,4 @@
-import { A as AgentCallOpts, h as EngineHandleData, E as EngineCapabilities, P as ProbeReport, a as AgentEvent, k as ResumeAnchor, c as AgentOutcome, I as InteractAction, i as InteractResult, S as SessionView } from './contract-types-sSlgppBC.cjs';
+import { A as AgentCallOpts, h as EngineHandleData, E as EngineCapabilities, P as ProbeReport, a as AgentEvent, i as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-C71Sqq8d.cjs';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -26,10 +26,21 @@ interface EngineCtxModel {
 interface EngineStream {
     onDelta(delta: string): void;
 }
-/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+/**
+ * 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 落盘路径与记录含该值分段，改名不改值）。
+ */
+declare const SHARED_POOL_KEY = "shared";
+/** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
 interface RunContext {
     taskId: string;
-    poolKey: string;
     signal?: AbortSignal;
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
@@ -39,19 +50,43 @@ interface RunContext {
         from: string;
         reason: string;
     };
-    onPoolResolved?: (poolKey: string) => void;
-    onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+    /**
+     * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
+     * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录（协议 run.params.ctx.sessionDir 的
+     * 进程内还原）——pi 引擎组装 `--session-dir` 的唯一权威值（宿主
+     * getSubagentSessionDir 推导，引擎不自推导）。additive 可选：缺省走引擎内
+     * [LEGACY] fallback（独立运行/测试形态）。
+     */
+    sessionDir?: string;
+    onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {
         pid: number | undefined;
         killed: boolean;
     }) => void;
     /**
-     * [v1.x] chat 会话形态参数（协议 run.params.chat 的进程内还原；缺省 = 一次性任务
-     * 形态）。recordId = chat 轮次关联键与 interact 定位键；resume 锚点存在 = 冷续
-     * （--session 续写原文件），不存在 = 首轮新建。
+     * 子进程退出态上报（host/childStateChanged 载荷形态；SR-4 接线：宿主镜像据此取消
+     * 该 pid 的挂起 dialog）。引擎侧只在 exited 相位上报——running 由 onChildSpawned 覆盖。
+     */
+    onChildStateChanged?: (p: {
+        pid: number;
+        recordId: string;
+        state: "running" | "exited";
+        killed: boolean;
+        exitCode?: number;
+        signal?: string;
+    }) => void;
+    /**
+     * [H1 U6 终态] resume 续聊参数（协议 run.params.resume 的进程内还原；唯一会话形态
+     * 键——原 v1.x `chat` 字段已随键切换退役）。recordId = 轮次关联键与镜像帧锚定键；
+     * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。缺省 =
+     * 一次性任务形态。
      */
-    chat?: {
+    resume?: {
         recordId: string;
         resume?: ResumeAnchor;
     };
@@ -71,7 +106,6 @@ interface EnginePort {
         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;
@@ -85,4 +119,4 @@ interface EnginePort {
 /** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */
 declare function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined;
 
-export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, parseCtxModel };
+export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, SHARED_POOL_KEY, parseCtxModel };

package/dist/port-contract.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentCallOpts, h as EngineHandleData, E as EngineCapabilities, P as ProbeReport, a as AgentEvent, k as ResumeAnchor, c as AgentOutcome, I as InteractAction, i as InteractResult, S as SessionView } from './contract-types-sSlgppBC.js';
+import { A as AgentCallOpts, h as EngineHandleData, E as EngineCapabilities, P as ProbeReport, a as AgentEvent, i as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-C71Sqq8d.js';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -26,10 +26,21 @@ interface EngineCtxModel {
 interface EngineStream {
     onDelta(delta: string): void;
 }
-/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+/**
+ * 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 落盘路径与记录含该值分段，改名不改值）。
+ */
+declare const SHARED_POOL_KEY = "shared";
+/** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
 interface RunContext {
     taskId: string;
-    poolKey: string;
     signal?: AbortSignal;
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
@@ -39,19 +50,43 @@ interface RunContext {
         from: string;
         reason: string;
     };
-    onPoolResolved?: (poolKey: string) => void;
-    onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+    /**
+     * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
+     * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录（协议 run.params.ctx.sessionDir 的
+     * 进程内还原）——pi 引擎组装 `--session-dir` 的唯一权威值（宿主
+     * getSubagentSessionDir 推导，引擎不自推导）。additive 可选：缺省走引擎内
+     * [LEGACY] fallback（独立运行/测试形态）。
+     */
+    sessionDir?: string;
+    onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {
         pid: number | undefined;
         killed: boolean;
     }) => void;
     /**
-     * [v1.x] chat 会话形态参数（协议 run.params.chat 的进程内还原；缺省 = 一次性任务
-     * 形态）。recordId = chat 轮次关联键与 interact 定位键；resume 锚点存在 = 冷续
-     * （--session 续写原文件），不存在 = 首轮新建。
+     * 子进程退出态上报（host/childStateChanged 载荷形态；SR-4 接线：宿主镜像据此取消
+     * 该 pid 的挂起 dialog）。引擎侧只在 exited 相位上报——running 由 onChildSpawned 覆盖。
+     */
+    onChildStateChanged?: (p: {
+        pid: number;
+        recordId: string;
+        state: "running" | "exited";
+        killed: boolean;
+        exitCode?: number;
+        signal?: string;
+    }) => void;
+    /**
+     * [H1 U6 终态] resume 续聊参数（协议 run.params.resume 的进程内还原；唯一会话形态
+     * 键——原 v1.x `chat` 字段已随键切换退役）。recordId = 轮次关联键与镜像帧锚定键；
+     * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。缺省 =
+     * 一次性任务形态。
      */
-    chat?: {
+    resume?: {
         recordId: string;
         resume?: ResumeAnchor;
     };
@@ -71,7 +106,6 @@ interface EnginePort {
         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;
@@ -85,4 +119,4 @@ interface EnginePort {
 /** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */
 declare function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined;
 
-export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, parseCtxModel };
+export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, SHARED_POOL_KEY, parseCtxModel };

package/dist/port-contract.js

@@ -1,7 +1,9 @@
 import {
+  SHARED_POOL_KEY,
   parseCtxModel
-} from "./chunk-RULLX6C6.js";
+} from "./chunk-LQR73V67.js";
 import "./chunk-JSBRDJBE.js";
 export {
+  SHARED_POOL_KEY,
   parseCtxModel
 };

package/dist/protocol/index.cjs

@@ -35,7 +35,6 @@ __export(protocol_exports, {
   HANDSHAKE_TIMEOUT_MS: () => HANDSHAKE_TIMEOUT_MS,
   PROTOCOL_METHODS: () => PROTOCOL_METHODS,
   REVERSE_CHANNELS: () => REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES: () => REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS: () => REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS: () => REVERSE_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
@@ -48,8 +47,6 @@ __export(protocol_exports, {
   errorResponseFrameSchema: () => errorResponseFrameSchema,
   isEngineErrorPassthroughCode: () => isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode: () => isEngineProtocolErrorCode,
-  isHostRoundLifecycleParams: () => isHostRoundLifecycleParams,
-  isHostStreamDeltaParams: () => isHostStreamDeltaParams,
   isNotificationFrame: () => isNotificationFrame,
   isProtocolVersionCompatible: () => isProtocolVersionCompatible,
   isRequestFrame: () => isRequestFrame,
@@ -59,6 +56,7 @@ __export(protocol_exports, {
   protocolErrorSchema: () => protocolErrorSchema,
   requestFrameSchema: () => requestFrameSchema,
   reverseRequestFrameSchema: () => reverseRequestFrameSchema,
+  runSessionParamsSchema: () => runSessionParamsSchema,
   schemaEmulationFailedDetail: () => schemaEmulationFailedDetail,
   successResponseFrameSchema: () => successResponseFrameSchema
 });
@@ -114,7 +112,6 @@ var PROTOCOL_METHODS = [
   "probe",
   "run",
   "cancel",
-  "interact",
   "read",
   "listModels",
   "validateModel",
@@ -126,44 +123,19 @@ var PROTOCOL_METHODS = [
 var REVERSE_CHANNELS = [
   "host/log",
   "host/askUser",
-  "host/permission",
   "host/streamDelta",
-  "host/poolResolved",
   "host/handleReady",
   "host/childSpawned",
-  "host/childStateChanged",
-  "host/roundLifecycle"
+  "host/childStateChanged"
 ];
 var REVERSE_CHANNEL_TIMEOUT_CLASS = {
   "host/log": "data-plane",
   "host/streamDelta": "data-plane",
-  "host/poolResolved": "data-plane",
   "host/handleReady": "data-plane",
   "host/childSpawned": "data-plane",
   "host/childStateChanged": "data-plane",
-  "host/roundLifecycle": "data-plane",
-  "host/askUser": "interaction",
-  "host/permission": "interaction"
+  "host/askUser": "interaction"
 };
-function isHostStreamDeltaParams(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  const hasRunId = typeof v.runId === "string";
-  const hasRecordId = typeof v.recordId === "string";
-  if (hasRunId === hasRecordId) return false;
-  return typeof v.delta === "string";
-}
-function isHostRoundLifecycleParams(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  const hasRunId = typeof v.runId === "string";
-  const hasRecordId = typeof v.recordId === "string";
-  if (hasRunId === hasRecordId) return false;
-  if (v.phase === "settled" || v.phase === "idle") return true;
-  if (v.phase !== "failed") return false;
-  const err = v.error;
-  return typeof err === "object" && err !== null && typeof err.code === "string" && typeof err.message === "string";
-}
 
 // src/protocol/error-codes.ts
 var ENGINE_PROTOCOL_ERROR_CODES = [
@@ -215,7 +187,7 @@ function engineProtocolMismatchError(engineVersion) {
 function engineConversationUnsupportedError(engineId) {
   return new EngineSdkError(
     "engine_capability_unsupported",
-    `engine '${engineId}' \u4E0D\u652F\u6301 conversation\uFF08capabilities.conversation = 'unsupported'\uFF0Cmanifest \u65E0 conversation gate \u4F4D\u2014\u2014\u65E0\u540C\u8FDB\u7A0B idle \u590D\u7528\uFF0Cmessage/close \u4EA4\u4E92\u63A7\u5236\u9762\u4E0D\u53EF\u7528\uFF09`,
+    `engine '${engineId}' \u4E0D\u652F\u6301 resume \u7EED\u804A\uFF08capabilities.conversation = 'unsupported'\uFF0Cmanifest \u65E0 conversation gate \u4F4D\uFF09`,
     `\u53BB\u6389 conversation \u53C2\u6570\uFF08\u4E00\u6B21\u6027\u4EFB\u52A1\u9ED8\u8BA4\u5F62\u6001\uFF09\uFF0C\u6216\u4FEE manifest capabilities / \u5347\u7EA7\u5F15\u64CE\u5305\uFF08\u82E5\u5F15\u64CE\u5B9E\u9645\u652F\u6301\u8BE5\u80FD\u529B\uFF09`,
     { engineId, capability: "conversation", declared: "unsupported" }
   );
@@ -316,6 +288,7 @@ var notificationFrameSchema = {
                 "turn_end",
                 "message_end",
                 "compaction",
+                "activity",
                 "error"
               ]
             }
@@ -353,7 +326,26 @@ var FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
   "password",
   "secret"
 ];
-var REVERSE_CHANNEL_NAMES = REVERSE_CHANNELS;
+var runSessionParamsSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineRunSessionParams",
+  type: "object",
+  additionalProperties: false,
+  required: ["recordId"],
+  properties: {
+    recordId: { type: "string" },
+    resume: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionRef"],
+      properties: {
+        // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
+        sessionRef: { type: "object", additionalProperties: { type: "string" } },
+        journalPath: { type: "string" }
+      }
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CANCEL_SETTLE_GRACE_MS,
@@ -371,7 +363,6 @@ var REVERSE_CHANNEL_NAMES = REVERSE_CHANNELS;
   HANDSHAKE_TIMEOUT_MS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
@@ -384,8 +375,6 @@ var REVERSE_CHANNEL_NAMES = REVERSE_CHANNELS;
   errorResponseFrameSchema,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
-  isHostRoundLifecycleParams,
-  isHostStreamDeltaParams,
   isNotificationFrame,
   isProtocolVersionCompatible,
   isRequestFrame,
@@ -395,6 +384,7 @@ var REVERSE_CHANNEL_NAMES = REVERSE_CHANNELS;
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
+  runSessionParamsSchema,
   schemaEmulationFailedDetail,
   successResponseFrameSchema
 });