@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/node-executor.d.cts

@@ -0,0 +1,63 @@
+/** L0 注入的引擎执行器路径 env（与 relay 的 XYZ_SUBAGENT_RELAY_NODE 不复用）。 */
+declare const ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
+/**
+ * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
+ *
+ * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
+ * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
+ * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
+ */
+declare function probeNodeExecutor(execPath: string, isElectron: boolean): Promise<boolean>;
+/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
+declare function resetEngineNodeProbeCache(): void;
+/** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
+type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
+/** resolveEngineNodeLaunch 的可注入项（测试隔离用；生产全部走缺省推导）。 */
+interface EngineNodeLaunchOptions {
+    /** 引擎 CLI 入口绝对路径（descriptor command / staged bin 解析结果）。 */
+    entryPath: string;
+    /** 入口附加参数（descriptor args；缺省 []）。 */
+    args?: readonly string[];
+    /** 宿主形态。 */
+    hostKind: EngineNodeHostKind;
+    /** 读取 XYZ_AGENT_ENGINE_NODE 的 env 快照（矩阵① 的注入通道）。 */
+    env?: Record<string, string | undefined>;
+    /** 宿主 process.execPath（缺省 process.execPath）。 */
+    execPath?: string;
+    /** 宿主自身是否 Electron（缺省 process.versions.electron !== undefined）。 */
+    isElectronHost?: boolean;
+    /** 平台覆盖（缺省 process.platform）。 */
+    platform?: NodeJS.Platform;
+}
+/** 解析结果：spawn(command, args) 形态 + buildEngineChildEnv 的 electronRunAsNode 输入。 */
+interface EngineNodeLaunch {
+    command: string;
+    args: string[];
+    /** 执行器为 Electron 二进制 → true（L0 注入 ELECTRON_RUN_AS_NODE=1）。 */
+    electronRunAsNode: boolean;
+}
+/**
+ * 宿主 × 平台二维矩阵解析（W9 §2.9）。返回 spawn argv；不直接 spawn——调用方
+ * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
+ *
+ * 判定序（与规格逐行对应）：
+ *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
+ *   pi-extension → 注入执行器（env XYZ_AGENT_ENGINE_NODE），缺失/探针失败 =
+ *     engine_not_found + 指引；
+ *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；
+ *   standalone → PATH node（探针失败 = engine_not_found + 安装指引）；
+ *   其余（dev 形态、非 Windows 非 .cmd、无矩阵命中的兜底）→ 直接 spawn 入口本体
+ *   （shebang `#!/usr/bin/env node` 走 PATH node——引擎 bin 均带 shebang，dev/独立
+ *   安装形态与现状一致）。
+ */
+declare function resolveEngineNodeLaunch(opts: EngineNodeLaunchOptions): Promise<EngineNodeLaunch>;
+/**
+ * EngineClient 的自由字符串 hostKind（'pi' / 'runtime' / …）→ 矩阵行归一：
+ *   'runtime*' → runtime-sidecar（②：sidecar execPath 权威）；
+ *   env 已注入 XYZ_AGENT_ENGINE_NODE（打包态 runtime 注入主 pi 进程的通道）→
+ *     pi-extension（①：必须用注入执行器——pi 宿主自身 execPath 是 pi binary）；
+ *   其余 → standalone（③：PATH node）。
+ */
+declare function hostKindOf(hostKind: string, env?: Record<string, string | undefined>): EngineNodeHostKind;
+
+export { ENGINE_NODE_ENV, type EngineNodeHostKind, type EngineNodeLaunch, type EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch };

package/dist/node-executor.d.ts

@@ -0,0 +1,63 @@
+/** L0 注入的引擎执行器路径 env（与 relay 的 XYZ_SUBAGENT_RELAY_NODE 不复用）。 */
+declare const ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
+/**
+ * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
+ *
+ * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
+ * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
+ * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
+ */
+declare function probeNodeExecutor(execPath: string, isElectron: boolean): Promise<boolean>;
+/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
+declare function resetEngineNodeProbeCache(): void;
+/** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
+type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
+/** resolveEngineNodeLaunch 的可注入项（测试隔离用；生产全部走缺省推导）。 */
+interface EngineNodeLaunchOptions {
+    /** 引擎 CLI 入口绝对路径（descriptor command / staged bin 解析结果）。 */
+    entryPath: string;
+    /** 入口附加参数（descriptor args；缺省 []）。 */
+    args?: readonly string[];
+    /** 宿主形态。 */
+    hostKind: EngineNodeHostKind;
+    /** 读取 XYZ_AGENT_ENGINE_NODE 的 env 快照（矩阵① 的注入通道）。 */
+    env?: Record<string, string | undefined>;
+    /** 宿主 process.execPath（缺省 process.execPath）。 */
+    execPath?: string;
+    /** 宿主自身是否 Electron（缺省 process.versions.electron !== undefined）。 */
+    isElectronHost?: boolean;
+    /** 平台覆盖（缺省 process.platform）。 */
+    platform?: NodeJS.Platform;
+}
+/** 解析结果：spawn(command, args) 形态 + buildEngineChildEnv 的 electronRunAsNode 输入。 */
+interface EngineNodeLaunch {
+    command: string;
+    args: string[];
+    /** 执行器为 Electron 二进制 → true（L0 注入 ELECTRON_RUN_AS_NODE=1）。 */
+    electronRunAsNode: boolean;
+}
+/**
+ * 宿主 × 平台二维矩阵解析（W9 §2.9）。返回 spawn argv；不直接 spawn——调用方
+ * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
+ *
+ * 判定序（与规格逐行对应）：
+ *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
+ *   pi-extension → 注入执行器（env XYZ_AGENT_ENGINE_NODE），缺失/探针失败 =
+ *     engine_not_found + 指引；
+ *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；
+ *   standalone → PATH node（探针失败 = engine_not_found + 安装指引）；
+ *   其余（dev 形态、非 Windows 非 .cmd、无矩阵命中的兜底）→ 直接 spawn 入口本体
+ *   （shebang `#!/usr/bin/env node` 走 PATH node——引擎 bin 均带 shebang，dev/独立
+ *   安装形态与现状一致）。
+ */
+declare function resolveEngineNodeLaunch(opts: EngineNodeLaunchOptions): Promise<EngineNodeLaunch>;
+/**
+ * EngineClient 的自由字符串 hostKind（'pi' / 'runtime' / …）→ 矩阵行归一：
+ *   'runtime*' → runtime-sidecar（②：sidecar execPath 权威）；
+ *   env 已注入 XYZ_AGENT_ENGINE_NODE（打包态 runtime 注入主 pi 进程的通道）→
+ *     pi-extension（①：必须用注入执行器——pi 宿主自身 execPath 是 pi binary）；
+ *   其余 → standalone（③：PATH node）。
+ */
+declare function hostKindOf(hostKind: string, env?: Record<string, string | undefined>): EngineNodeHostKind;
+
+export { ENGINE_NODE_ENV, type EngineNodeHostKind, type EngineNodeLaunch, type EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch };

package/dist/node-executor.js

@@ -0,0 +1,16 @@
+import {
+  ENGINE_NODE_ENV,
+  hostKindOf,
+  probeNodeExecutor,
+  resetEngineNodeProbeCache,
+  resolveEngineNodeLaunch
+} from "./chunk-ZOFFJNJD.js";
+import "./chunk-PPEPBVCC.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  ENGINE_NODE_ENV,
+  hostKindOf,
+  probeNodeExecutor,
+  resetEngineNodeProbeCache,
+  resolveEngineNodeLaunch
+};

package/dist/paths.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/paths.ts
+var paths_exports = {};
+__export(paths_exports, {
+  resolveEngineDir: () => resolveEngineDir,
+  resolveEnginesRoot: () => resolveEnginesRoot,
+  resolveJournalPath: () => resolveJournalPath,
+  resolvePoolDir: () => resolvePoolDir,
+  sanitizeSeg: () => sanitizeSeg
+});
+module.exports = __toCommonJS(paths_exports);
+var import_node_path = require("path");
+var MAX_SEG_CHARS = 80;
+function sanitizeSeg(input) {
+  const s = input.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.length > 0 ? s.slice(0, MAX_SEG_CHARS) : "default";
+}
+function resolveEnginesRoot(dataDir) {
+  return (0, import_node_path.join)(dataDir, "engines");
+}
+function resolveEngineDir(dataDir, engineId) {
+  return (0, import_node_path.join)(resolveEnginesRoot(dataDir), sanitizeSeg(engineId));
+}
+function resolvePoolDir(dataDir, engineId, poolKey) {
+  return (0, import_node_path.join)(resolveEngineDir(dataDir, sanitizeSeg(engineId)), sanitizeSeg(poolKey));
+}
+function resolveJournalPath(dataDir, engineId, poolKey, taskId) {
+  return (0, import_node_path.join)(resolvePoolDir(dataDir, engineId, poolKey), `journal-${sanitizeSeg(taskId)}.jsonl`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveEngineDir,
+  resolveEnginesRoot,
+  resolveJournalPath,
+  resolvePoolDir,
+  sanitizeSeg
+});

package/dist/paths.d.cts

@@ -0,0 +1,8 @@
+/** 路径段进入文件系统前的安全编码：路径穿越、分隔符、空白、超长全部归一。 */
+declare function sanitizeSeg(input: string): string;
+declare function resolveEnginesRoot(dataDir: string): string;
+declare function resolveEngineDir(dataDir: string, engineId: string): string;
+declare function resolvePoolDir(dataDir: string, engineId: string, poolKey: string): string;
+declare function resolveJournalPath(dataDir: string, engineId: string, poolKey: string, taskId: string): string;
+
+export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg };

package/dist/paths.d.ts

@@ -0,0 +1,8 @@
+/** 路径段进入文件系统前的安全编码：路径穿越、分隔符、空白、超长全部归一。 */
+declare function sanitizeSeg(input: string): string;
+declare function resolveEnginesRoot(dataDir: string): string;
+declare function resolveEngineDir(dataDir: string, engineId: string): string;
+declare function resolvePoolDir(dataDir: string, engineId: string, poolKey: string): string;
+declare function resolveJournalPath(dataDir: string, engineId: string, poolKey: string, taskId: string): string;
+
+export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg };

package/dist/paths.js

@@ -0,0 +1,15 @@
+import {
+  resolveEngineDir,
+  resolveEnginesRoot,
+  resolveJournalPath,
+  resolvePoolDir,
+  sanitizeSeg
+} from "./chunk-OPMY4G4M.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  resolveEngineDir,
+  resolveEnginesRoot,
+  resolveJournalPath,
+  resolvePoolDir,
+  sanitizeSeg
+};

package/dist/port-contract.cjs

@@ -0,0 +1,35 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/port-contract.ts
+var port_contract_exports = {};
+__export(port_contract_exports, {
+  parseCtxModel: () => parseCtxModel
+});
+module.exports = __toCommonJS(port_contract_exports);
+function parseCtxModel(ref) {
+  if (ref === void 0 || ref.trim() === "") return void 0;
+  const slash = ref.indexOf("/");
+  if (slash <= 0 || slash === ref.length - 1) return void 0;
+  return { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseCtxModel
+});

package/dist/port-contract.d.cts

@@ -0,0 +1,88 @@
+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';
+
+/**
+ * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
+ * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
+ * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
+ */
+type EngineAgentCallOpts = AgentCallOpts & {
+    model?: string;
+    cwd?: string;
+    schemaEnv?: string;
+};
+/**
+ * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
+ * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
+ */
+interface EngineCtxModel {
+    id: string;
+    provider: string;
+    name?: string;
+    reasoning?: boolean;
+    thinkingLevelMap?: Record<string, unknown>;
+    contextWindow?: number;
+}
+/** text_delta streaming 出口（协议 host/streamDelta 的本地承载）。 */
+interface EngineStream {
+    onDelta(delta: string): void;
+}
+/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+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;
+    };
+}
+interface EngineHandle {
+    readonly data: EngineHandleData;
+}
+interface EngineRunResult {
+    handle: EngineHandle;
+    outcome: AgentOutcome;
+}
+/** 引擎进程内的引擎契约点（core EnginePort 的结构等价镜像）。 */
+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。 */
+declare function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined;
+
+export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, parseCtxModel };

package/dist/port-contract.d.ts

@@ -0,0 +1,88 @@
+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';
+
+/**
+ * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
+ * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
+ * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
+ */
+type EngineAgentCallOpts = AgentCallOpts & {
+    model?: string;
+    cwd?: string;
+    schemaEnv?: string;
+};
+/**
+ * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
+ * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
+ */
+interface EngineCtxModel {
+    id: string;
+    provider: string;
+    name?: string;
+    reasoning?: boolean;
+    thinkingLevelMap?: Record<string, unknown>;
+    contextWindow?: number;
+}
+/** text_delta streaming 出口（协议 host/streamDelta 的本地承载）。 */
+interface EngineStream {
+    onDelta(delta: string): void;
+}
+/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+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;
+    };
+}
+interface EngineHandle {
+    readonly data: EngineHandleData;
+}
+interface EngineRunResult {
+    handle: EngineHandle;
+    outcome: AgentOutcome;
+}
+/** 引擎进程内的引擎契约点（core EnginePort 的结构等价镜像）。 */
+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。 */
+declare function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined;
+
+export { type EngineAgentCallOpts, type EngineCtxModel, type EngineHandle, type EnginePort, type EngineRunResult, type EngineStream, type RunContext, parseCtxModel };

package/dist/port-contract.js

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