@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/logs/stderr-rotation.cjs

@@ -0,0 +1,151 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/logs/stderr-rotation.ts
+var stderr_rotation_exports = {};
+__export(stderr_rotation_exports, {
+  DEFAULT_STDERR_KEEP_DAYS: () => DEFAULT_STDERR_KEEP_DAYS,
+  DEFAULT_STDERR_MAX_BYTES: () => DEFAULT_STDERR_MAX_BYTES,
+  cleanupSiblingStderrLogs: () => cleanupSiblingStderrLogs,
+  cleanupStaleStderrLogs: () => cleanupStaleStderrLogs,
+  isPidAlive: () => isPidAlive,
+  rotateStderrLogIfNeeded: () => rotateStderrLogIfNeeded,
+  stderrLogPathFor: () => stderrLogPathFor,
+  stderrLogPidOf: () => stderrLogPidOf,
+  stderrRotationParams: () => stderrRotationParams
+});
+module.exports = __toCommonJS(stderr_rotation_exports);
+var fs = __toESM(require("fs"), 1);
+var import_node_path = require("path");
+var BYTES_PER_KB = 1024;
+var DEFAULT_MAX_FILE_MB = 50;
+var MS_PER_SECOND = 1e3;
+var SECONDS_PER_MINUTE = 60;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+var DEFAULT_STDERR_MAX_BYTES = DEFAULT_MAX_FILE_MB * BYTES_PER_KB * BYTES_PER_KB;
+var DAY_MS = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+var DEFAULT_STDERR_KEEP_DAYS = 7;
+function positiveIntEnv(env, key) {
+  const raw = env[key];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+function stderrRotationParams(env) {
+  return {
+    maxBytes: positiveIntEnv(env, "XYZ_LOG_MAX_BYTES") ?? DEFAULT_STDERR_MAX_BYTES,
+    keepDays: positiveIntEnv(env, "XYZ_LOG_KEEP_DAYS") ?? DEFAULT_STDERR_KEEP_DAYS
+  };
+}
+function stderrLogPathFor(engineDataDir, pid, prefix) {
+  return (0, import_node_path.join)(engineDataDir, "logs", `${prefix}${pid}.log`);
+}
+function stderrLogPidOf(fileName, prefix) {
+  if (!fileName.startsWith(prefix)) return void 0;
+  const rest = fileName.slice(prefix.length);
+  const pidToken = rest.split(".", 1)[0] ?? "";
+  if (!/^\d+$/.test(pidToken)) return void 0;
+  return Number(pidToken);
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function rotateStderrLogIfNeeded(path, params) {
+  let size;
+  try {
+    size = fs.statSync(path).size;
+  } catch {
+    return false;
+  }
+  if (size <= params.maxBytes) return false;
+  const rotated = `${path}.${Date.now()}`;
+  try {
+    fs.renameSync(path, rotated);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function cleanupStaleStderrLogs(logsDir, env, prefix, now = Date.now()) {
+  const params = stderrRotationParams(env);
+  const expiryMs = params.keepDays * DAY_MS;
+  let deleted = 0;
+  let skipped = 0;
+  let names;
+  try {
+    names = fs.readdirSync(logsDir);
+  } catch {
+    return { deleted, skipped };
+  }
+  for (const name of names) {
+    const pid = stderrLogPidOf(name, prefix);
+    if (pid === void 0) continue;
+    if (isPidAlive(pid)) {
+      skipped += 1;
+      continue;
+    }
+    const full = (0, import_node_path.join)(logsDir, name);
+    try {
+      if (fs.statSync(full).mtimeMs > now - expiryMs) {
+        skipped += 1;
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    try {
+      fs.rmSync(full, { force: true });
+      deleted += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { deleted, skipped };
+}
+function cleanupSiblingStderrLogs(logPath, env, prefix, now) {
+  return cleanupStaleStderrLogs((0, import_node_path.dirname)(logPath), env, prefix, now);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_STDERR_KEEP_DAYS,
+  DEFAULT_STDERR_MAX_BYTES,
+  cleanupSiblingStderrLogs,
+  cleanupStaleStderrLogs,
+  isPidAlive,
+  rotateStderrLogIfNeeded,
+  stderrLogPathFor,
+  stderrLogPidOf,
+  stderrRotationParams
+});

package/dist/logs/stderr-rotation.d.cts

@@ -0,0 +1,37 @@
+declare const DEFAULT_STDERR_MAX_BYTES: number;
+/** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
+declare const DEFAULT_STDERR_KEEP_DAYS = 7;
+/** 轮转参数（env 覆盖面 = 宿主 logger 同款 XYZ_LOG_* 两键）。 */
+interface StderrRotationParams {
+    maxBytes: number;
+    keepDays: number;
+}
+/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
+declare function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams;
+/** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
+declare function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string;
+/** 从文件名解析实例 pid（非本前缀形态返回 undefined——调用方跳过）。 */
+declare function stderrLogPidOf(fileName: string, prefix: string): number | undefined;
+/** pid 存活探测（跨实例：ESRCH = 死；EPERM = 存活但非属主，按存活保守处理）。 */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
+ * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
+ * 文件——轮转是取证面优化，不是主通道）。
+ */
+declare function rotateStderrLogIfNeeded(path: string, params: StderrRotationParams): boolean;
+interface CleanupResult {
+    /** 已删除文件数。 */
+    deleted: number;
+    /** 命中前缀但跳过（pid 存活 / mtime 未过期 / 探测不确定）的文件数。 */
+    skipped: number;
+}
+/**
+ * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
+ * 零删除（取证面 best-effort）。
+ */
+declare function cleanupStaleStderrLogs(logsDir: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
+/** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */
+declare function cleanupSiblingStderrLogs(logPath: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
+
+export { type CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, type StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams };

package/dist/logs/stderr-rotation.d.ts

@@ -0,0 +1,37 @@
+declare const DEFAULT_STDERR_MAX_BYTES: number;
+/** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
+declare const DEFAULT_STDERR_KEEP_DAYS = 7;
+/** 轮转参数（env 覆盖面 = 宿主 logger 同款 XYZ_LOG_* 两键）。 */
+interface StderrRotationParams {
+    maxBytes: number;
+    keepDays: number;
+}
+/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
+declare function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams;
+/** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
+declare function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string;
+/** 从文件名解析实例 pid（非本前缀形态返回 undefined——调用方跳过）。 */
+declare function stderrLogPidOf(fileName: string, prefix: string): number | undefined;
+/** pid 存活探测（跨实例：ESRCH = 死；EPERM = 存活但非属主，按存活保守处理）。 */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
+ * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
+ * 文件——轮转是取证面优化，不是主通道）。
+ */
+declare function rotateStderrLogIfNeeded(path: string, params: StderrRotationParams): boolean;
+interface CleanupResult {
+    /** 已删除文件数。 */
+    deleted: number;
+    /** 命中前缀但跳过（pid 存活 / mtime 未过期 / 探测不确定）的文件数。 */
+    skipped: number;
+}
+/**
+ * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
+ * 零删除（取证面 best-effort）。
+ */
+declare function cleanupStaleStderrLogs(logsDir: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
+/** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */
+declare function cleanupSiblingStderrLogs(logPath: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
+
+export { type CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, type StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams };

package/dist/logs/stderr-rotation.js

@@ -0,0 +1,23 @@
+import {
+  DEFAULT_STDERR_KEEP_DAYS,
+  DEFAULT_STDERR_MAX_BYTES,
+  cleanupSiblingStderrLogs,
+  cleanupStaleStderrLogs,
+  isPidAlive,
+  rotateStderrLogIfNeeded,
+  stderrLogPathFor,
+  stderrLogPidOf,
+  stderrRotationParams
+} from "../chunk-HYES77BR.js";
+import "../chunk-JSBRDJBE.js";
+export {
+  DEFAULT_STDERR_KEEP_DAYS,
+  DEFAULT_STDERR_MAX_BYTES,
+  cleanupSiblingStderrLogs,
+  cleanupStaleStderrLogs,
+  isPidAlive,
+  rotateStderrLogIfNeeded,
+  stderrLogPathFor,
+  stderrLogPidOf,
+  stderrRotationParams
+};

package/dist/nesting-guard.cjs

@@ -0,0 +1,95 @@
+"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/nesting-guard.ts
+var nesting_guard_exports = {};
+__export(nesting_guard_exports, {
+  ExecutionNestingContext: () => ExecutionNestingContext,
+  NESTED_SPAWN_ENV: () => NESTED_SPAWN_ENV,
+  NestedSpawnRejectedError: () => NestedSpawnRejectedError,
+  assertNotNestedSpawn: () => assertNotNestedSpawn,
+  buildNestedSpawnEnv: () => buildNestedSpawnEnv
+});
+module.exports = __toCommonJS(nesting_guard_exports);
+var import_node_async_hooks = require("async_hooks");
+var NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+var NATIVE_NESTED_KEYS = ["CLAUDECODE", "ZSW_NESTED"];
+var NATIVE_NESTED_PREFIXES = ["PI_SUBAGENT_"];
+var NestedSpawnRejectedError = class extends Error {
+  code = "nested_spawn_rejected";
+  /** 恢复指引：指向具体下一步，非安慰性文案。 */
+  recovery;
+  constructor() {
+    super(
+      "nested_spawn_rejected: this process is already a subagent (XYZ_AGENT_SUBAGENT=1)"
+    );
+    this.name = "NestedSpawnRejectedError";
+    this.recovery = "Subagents must not spawn further subagents (unbounded recursion guard). Do the work directly inside the current task instead of delegating.";
+  }
+};
+function buildNestedSpawnEnv(baseEnv) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (NATIVE_NESTED_KEYS.includes(key)) continue;
+    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    env[key] = value;
+  }
+  env[NESTED_SPAWN_ENV] = "1";
+  return env;
+}
+function assertNotNestedSpawn(env) {
+  if (env[NESTED_SPAWN_ENV] === "1") {
+    throw new NestedSpawnRejectedError();
+  }
+}
+var ExecutionNestingContext = class {
+  als = new import_node_async_hooks.AsyncLocalStorage();
+  baselineState = null;
+  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+  setBaseline(state) {
+    this.baselineState = state;
+  }
+  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+  current() {
+    return this.als.getStore() ?? this.baselineState;
+  }
+  /**
+   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+   */
+  baseline() {
+    return this.baselineState;
+  }
+  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+  run(state, fn) {
+    return this.als.run(state, fn);
+  }
+  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+  enterWith(state) {
+    this.als.enterWith(state);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExecutionNestingContext,
+  NESTED_SPAWN_ENV,
+  NestedSpawnRejectedError,
+  assertNotNestedSpawn,
+  buildNestedSpawnEnv
+});

package/dist/nesting-guard.d.cts

@@ -0,0 +1,65 @@
+/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
+declare const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
+type SpawnEnv = Record<string, string | undefined>;
+/**
+ * nested_spawn_rejected 的结构化错误（自 core errors.ts 内联；code/recovery 与 core
+ * 词表逐字一致，EngineError 类形态对齐 SDK protocol/error-codes.ts 的 EngineSdkError）。
+ */
+declare class NestedSpawnRejectedError extends Error {
+    readonly code = "nested_spawn_rejected";
+    /** 恢复指引：指向具体下一步，非安慰性文案。 */
+    readonly recovery: string;
+    constructor();
+}
+/**
+ * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
+ * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
+ */
+declare function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv;
+/**
+ * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
+ * nested_spawn_rejected——文案说明防护规则、指向 task 内自行完成。
+ * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
+ */
+declare function assertNotNestedSpawn(env: SpawnEnv): void;
+/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
+interface ExecutionNestingState {
+    recordId: string | undefined;
+    depth: number;
+}
+/**
+ * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
+ *
+ * 机制（原样迁移，行为零变化）：
+ *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
+ *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
+ *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
+ *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
+ *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
+ *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
+ *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
+ *
+ * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
+ * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
+ * （session-context-resolver），公共层只提供状态存取单点。
+ */
+declare class ExecutionNestingContext {
+    private readonly als;
+    private baselineState;
+    /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+    setBaseline(state: ExecutionNestingState | null): void;
+    /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+    current(): ExecutionNestingState | null;
+    /**
+     * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+     * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+     */
+    baseline(): ExecutionNestingState | null;
+    /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+    run<T>(state: ExecutionNestingState, fn: () => T): T;
+    /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+    enterWith(state: ExecutionNestingState): void;
+}
+
+export { ExecutionNestingContext, type ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, type SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv };

package/dist/nesting-guard.d.ts

@@ -0,0 +1,65 @@
+/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
+declare const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
+/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
+type SpawnEnv = Record<string, string | undefined>;
+/**
+ * nested_spawn_rejected 的结构化错误（自 core errors.ts 内联；code/recovery 与 core
+ * 词表逐字一致，EngineError 类形态对齐 SDK protocol/error-codes.ts 的 EngineSdkError）。
+ */
+declare class NestedSpawnRejectedError extends Error {
+    readonly code = "nested_spawn_rejected";
+    /** 恢复指引：指向具体下一步，非安慰性文案。 */
+    readonly recovery: string;
+    constructor();
+}
+/**
+ * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
+ * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
+ */
+declare function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv;
+/**
+ * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
+ * nested_spawn_rejected——文案说明防护规则、指向 task 内自行完成。
+ * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
+ */
+declare function assertNotNestedSpawn(env: SpawnEnv): void;
+/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
+interface ExecutionNestingState {
+    recordId: string | undefined;
+    depth: number;
+}
+/**
+ * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
+ *
+ * 机制（原样迁移，行为零变化）：
+ *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
+ *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
+ *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
+ *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
+ *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
+ *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
+ *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
+ *
+ * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
+ * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
+ * （session-context-resolver），公共层只提供状态存取单点。
+ */
+declare class ExecutionNestingContext {
+    private readonly als;
+    private baselineState;
+    /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
+    setBaseline(state: ExecutionNestingState | null): void;
+    /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
+    current(): ExecutionNestingState | null;
+    /**
+     * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
+     * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
+     */
+    baseline(): ExecutionNestingState | null;
+    /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
+    run<T>(state: ExecutionNestingState, fn: () => T): T;
+    /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
+    enterWith(state: ExecutionNestingState): void;
+}
+
+export { ExecutionNestingContext, type ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, type SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv };

package/dist/nesting-guard.js

@@ -0,0 +1,15 @@
+import {
+  ExecutionNestingContext,
+  NESTED_SPAWN_ENV,
+  NestedSpawnRejectedError,
+  assertNotNestedSpawn,
+  buildNestedSpawnEnv
+} from "./chunk-365AUV6N.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  ExecutionNestingContext,
+  NESTED_SPAWN_ENV,
+  NestedSpawnRejectedError,
+  assertNotNestedSpawn,
+  buildNestedSpawnEnv
+};

package/dist/node-executor.cjs

@@ -0,0 +1,180 @@
+"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/node-executor.ts
+var node_executor_exports = {};
+__export(node_executor_exports, {
+  ENGINE_NODE_ENV: () => ENGINE_NODE_ENV,
+  hostKindOf: () => hostKindOf,
+  probeNodeExecutor: () => probeNodeExecutor,
+  resetEngineNodeProbeCache: () => resetEngineNodeProbeCache,
+  resolveEngineNodeLaunch: () => resolveEngineNodeLaunch
+});
+module.exports = __toCommonJS(node_executor_exports);
+var import_node_child_process = require("child_process");
+
+// src/protocol/error-codes.ts
+var EngineSdkError = class extends Error {
+  code;
+  recovery;
+  data;
+  constructor(code, detail, recovery, data) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineSdkError";
+    this.code = code;
+    this.recovery = recovery;
+    this.data = data;
+  }
+  /** 协议 error 帧载荷投影。 */
+  toStructured() {
+    return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
+  }
+};
+
+// src/node-executor.ts
+var ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
+var PROBE_TIMEOUT_MS = 5e3;
+function probeNodeExecutor(execPath, isElectron) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let child = null;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child?.kill("SIGKILL");
+      } catch {
+      }
+      resolve(ok);
+    };
+    const env = {};
+    if (process.env.PATH !== void 0) env.PATH = process.env.PATH;
+    if (process.env.HOME !== void 0) env.HOME = process.env.HOME;
+    if (isElectron) env.ELECTRON_RUN_AS_NODE = "1";
+    try {
+      child = (0, import_node_child_process.spawn)(execPath, ["--eval", "process.exit(0)"], {
+        env,
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    const timer = setTimeout(() => finish(false), PROBE_TIMEOUT_MS);
+    timer.unref();
+    child.on("error", () => finish(false));
+    child.on("exit", (code) => finish(code === 0));
+  });
+}
+var probeCache = /* @__PURE__ */ new Map();
+function probeCached(execPath, isElectron) {
+  const key = `${execPath}:${isElectron}`;
+  let p = probeCache.get(key);
+  if (!p) {
+    p = probeNodeExecutor(execPath, isElectron);
+    probeCache.set(key, p);
+  }
+  return p;
+}
+function resetEngineNodeProbeCache() {
+  probeCache.clear();
+}
+function engineNotFound(detail, recovery) {
+  return new EngineSdkError("engine_not_found", detail, recovery);
+}
+function launchEnvOf(opts) {
+  return opts.env ?? process.env;
+}
+async function resolvePiExtensionLaunch(entryPath, entryArgs, env) {
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode === void 0 || engineNode === "") {
+    throw engineNotFound(
+      `pi extension host must spawn engines via injected executor ${ENGINE_NODE_ENV}, but it is not set (host process.execPath is the pi binary, not a node executor)`,
+      `The xyz-agent runtime injects ${ENGINE_NODE_ENV} when spawning the pi host. If you are running the extension inside a packaged app, report this as a packaging regression; standalone pi installs do not use the pi-extension host kind.`
+    );
+  }
+  const isElectron = env.ELECTRON_RUN_AS_NODE === "1";
+  if (!await probeCached(engineNode, isElectron)) {
+    throw engineNotFound(
+      `injected node executor failed the probe: ${engineNode} (isElectron=${isElectron})`,
+      `Verify the executor exists and can run plain node semantics (Electron binaries need ELECTRON_RUN_AS_NODE=1). The host re-probes after restart.`
+    );
+  }
+  return { command: engineNode, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+async function resolveRuntimeSidecarLaunch(entryPath, entryArgs, opts) {
+  const execPath = opts.execPath ?? process.execPath;
+  const isElectron = opts.isElectronHost ?? process.versions.electron !== void 0;
+  if (!await probeCached(execPath, isElectron)) {
+    throw engineNotFound(
+      `runtime sidecar executor failed the probe: ${execPath} (isElectron=${isElectron})`,
+      `The sidecar process.execPath must run plain node semantics (ELECTRON_RUN_AS_NODE=1 for Electron binaries). Check how the runtime sidecar was spawned.`
+    );
+  }
+  return { command: execPath, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+async function resolveStandaloneLaunch(entryPath, entryArgs) {
+  if (!await probeCached("node", false)) {
+    throw engineNotFound(
+      `no usable 'node' on PATH for standalone engine launch (entry: ${entryPath})`,
+      `Install Node.js >= 22 and ensure 'node' is on PATH (https://nodejs.org/), or configure the engine explicitly via subagents/config.json.`
+    );
+  }
+  return { command: "node", args: [entryPath, ...entryArgs], electronRunAsNode: false };
+}
+async function resolveEngineNodeLaunch(opts) {
+  const platform = opts.platform ?? process.platform;
+  const entryArgs = [...opts.args ?? []];
+  if (platform === "win32" && opts.entryPath.toLowerCase().endsWith(".cmd")) {
+    return {
+      command: "cmd.exe",
+      args: ["/c", opts.entryPath, ...entryArgs],
+      electronRunAsNode: false
+    };
+  }
+  if (!/\.(?:js|mjs|cjs|ts)$/i.test(opts.entryPath)) {
+    return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+  }
+  if (opts.hostKind === "pi-extension") {
+    return resolvePiExtensionLaunch(opts.entryPath, entryArgs, launchEnvOf(opts));
+  }
+  if (opts.hostKind === "runtime-sidecar") {
+    return resolveRuntimeSidecarLaunch(opts.entryPath, entryArgs, opts);
+  }
+  if (opts.hostKind === "standalone") {
+    return resolveStandaloneLaunch(opts.entryPath, entryArgs);
+  }
+  return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+}
+function hostKindOf(hostKind, env = process.env) {
+  if (hostKind.startsWith("runtime")) return "runtime-sidecar";
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode !== void 0 && engineNode !== "") return "pi-extension";
+  return "standalone";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENGINE_NODE_ENV,
+  hostKindOf,
+  probeNodeExecutor,
+  resetEngineNodeProbeCache,
+  resolveEngineNodeLaunch
+});