@zhushanwen/subagent-engine-sdk 0.2.0

package/src/env.ts

@@ -0,0 +1,265 @@
+// src/env.ts
+//
+// 引擎子进程 env 契约（W12，impl-plan §2.12 / 设计 §3.5.1 D7）。
+//
+// F9：buildOutboundChildEnv 在 @xyz-agent/shared，而 SDK 的消费面（zsw 宿主、引擎
+// CLI 包）不可依赖 shared——SDK 是跨宿主 SSOT，故本文件自持全部常量与构建器，
+// 不 import @xyz-agent/shared。
+//
+// 基座常量单源：下方 ENGINE_ENV_PREFIXES / ENGINE_ENV_DENY_LIST 是
+// packages/shared/src/constants.ts 同名 SSOT 的构建期生成物（逐项相等由
+// .githooks/check_env_whitelist_sync.py 断言）；改动必须两处同批提交。
+
+import { getLogger } from "./logger.ts";
+
+const logger = getLogger("engine-sdk/env");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 基座常量（@generated 镜像：packages/shared/src/constants.ts ENGINE_ENV_* SSOT）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
+export const ENGINE_ENV_PREFIXES: readonly string[] = [
+  'XYZ_', 'XYZ_AGENT_', 'XYZ_SUBAGENT_',
+];
+
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
+export const ENGINE_ENV_DENY_LIST: readonly string[] = [
+  'XYZ_AGENT_PACKAGED',
+  'XYZ_RUNTIME_TOKEN',
+  'XYZ_AGENT_API_KEY',
+  'XYZ_SUBAGENT_RELAY_SESSION_ID',
+  'XYZ_SUBAGENT_RELAY_RECORD_ID',
+  'XYZ_SUBAGENT_RELAY_STDIN',
+  'XYZ_SUBAGENT_RELAY_STDOUT',
+  'XYZ_SUBAGENT_RELAY_STDERR',
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// L0 基础设施键（core 过滤之后显式注入，不受放行/剥除约束）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+export const ENGINE_ENV_L0_INFRA_KEYS: readonly string[] = [
+  'XYZ_AGENT_DATA_DIR',
+  'XYZ_AGENT_ENGINE_NODE',
+  'ELECTRON_RUN_AS_NODE',
+  'XYZ_AGENT_SUBAGENT',
+  'XYZ_SUBAGENT_RELAY_SOCKET',
+  'XYZ_SUBAGENT_RELAY_NODE',
+  'XYZ_SUBAGENT_RELAY_SCRIPT',
+];
+
+/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
+export interface EngineRelayEnv {
+  socket: string;
+  node: string;
+  script: string;
+}
+
+/** buildEngineChildEnv 入参。 */
+export interface EngineChildEnvOptions {
+  /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
+  dataDir: string;
+  /** L0：执行器路径（descriptor command 的执行体；Electron 二进制时另置 electronRunAsNode） */
+  engineNode?: string;
+  /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
+  electronRunAsNode?: boolean;
+  /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 XYZ_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
+  relay?: EngineRelayEnv;
+  /** L0：引擎侧身份 env（PI_SUBAGENT_ROOT_SESSION_ID 等，base-tool-enhance / 递归可见性消费） */
+  identityEnv?: Record<string, string | undefined>;
+  /** L2：manifest 声明的 envPrefixes 放行清单（保留前缀拒绝 + 形态校验） */
+  envPrefixes?: readonly string[];
+  /** L2：引擎私有 env 候选（descriptor processEnv；未声明前缀不放行 + warn） */
+  processEnv?: Record<string, string | undefined>;
+}
+
+/** manifest envPrefixes 合法形态：大小写不敏感的 [A-Za-z0-9_]+（如 `MYENGINE_`）。 */
+const ENV_PREFIX_SHAPE_RE = /^[A-Za-z0-9_]+$/;
+
+/** deny/剥除键删除：Windows env 键语义不区分大小写，统一 lower-case 比较。 */
+function deleteEnvKeysCaseInsensitive(
+  env: Record<string, string>,
+  names: readonly string[],
+): void {
+  const lowered = new Set(names.map((n) => n.toLowerCase()));
+  for (const key of Object.keys(env)) {
+    if (lowered.has(key.toLowerCase())) delete env[key];
+  }
+}
+
+/**
+ * L2 前缀清单武装：逐条形态校验 + 保留前缀拒绝，非法条目丢弃 + warn（包继续可用）。
+ * 返回 null 表示无任何合法前缀（跳过 processEnv 放行）。
+ */
+function compileManifestPrefixes(prefixes: readonly string[]): string[] | null {
+  const compiled: string[] = [];
+  for (const raw of prefixes) {
+    if (!ENV_PREFIX_SHAPE_RE.test(raw)) {
+      logger.warn(
+        `envPrefixes entry dropped (invalid shape, expected ^[A-Za-z0-9_]+$): ${JSON.stringify(raw)}`,
+      );
+      continue;
+    }
+    const lowered = raw.toLowerCase();
+    if (ENGINE_ENV_PREFIXES.some((reserved) => lowered.startsWith(reserved.toLowerCase()))) {
+      logger.warn(
+        `envPrefixes entry dropped (reserved prefix, infra keys are L0-only): ${JSON.stringify(raw)}`,
+      );
+      continue;
+    }
+    compiled.push(lowered);
+  }
+  return compiled.length > 0 ? compiled : null;
+}
+
+/**
+ * L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键写入 env。
+ * - 双侧声明（processEnv + envPrefixes）→ compile 后按前缀放行，未命中 warn；
+ * - 只声明 processEnv（manifest 无 envPrefixes）→ 全部不放行 + warn。
+ */
+function applyManifestAllowlist(
+  env: Record<string, string>,
+  opts: EngineChildEnvOptions,
+): void {
+  if (opts.processEnv !== undefined && opts.envPrefixes !== undefined) {
+    const compiled = compileManifestPrefixes(opts.envPrefixes);
+    if (compiled !== null) {
+      for (const [key, value] of Object.entries(opts.processEnv)) {
+        if (value === undefined) continue;
+        const loweredKey = key.toLowerCase();
+        if (compiled.some((prefix) => loweredKey.startsWith(prefix))) {
+          env[key] = value;
+        } else {
+          logger.warn(`processEnv key not allowed (no declared envPrefix matches): ${key}`);
+        }
+      }
+    }
+  } else if (opts.processEnv !== undefined) {
+    for (const key of Object.keys(opts.processEnv)) {
+      logger.warn(`processEnv key not allowed (manifest declares no envPrefixes): ${key}`);
+    }
+  }
+}
+
+/**
+ * L0 基础设施键显式注入（最后写入 = 最高优先级）：dataDir 恒注入 / engineNode、
+ * ELECTRON_RUN_AS_NODE（条件）/ XYZ_AGENT_SUBAGENT=1 / relay 三键 / identityEnv。
+ */
+function injectL0InfraKeys(
+  env: Record<string, string>,
+  opts: EngineChildEnvOptions,
+): void {
+  env.XYZ_AGENT_DATA_DIR = opts.dataDir;
+  if (opts.engineNode !== undefined) env.XYZ_AGENT_ENGINE_NODE = opts.engineNode;
+  if (opts.electronRunAsNode === true) env.ELECTRON_RUN_AS_NODE = "1";
+  env.XYZ_AGENT_SUBAGENT = "1";
+  if (opts.relay !== undefined) {
+    env.XYZ_SUBAGENT_RELAY_SOCKET = opts.relay.socket;
+    env.XYZ_SUBAGENT_RELAY_NODE = opts.relay.node;
+    env.XYZ_SUBAGENT_RELAY_SCRIPT = opts.relay.script;
+  }
+  if (opts.identityEnv !== undefined) {
+    for (const [key, value] of Object.entries(opts.identityEnv)) {
+      if (value !== undefined) env[key] = value;
+    }
+  }
+}
+
+/**
+ * `buildEngineChildEnv(baseEnv, opts)`：引擎子进程 env 三层契约（高者覆盖低者）。
+ *
+ * 写死次序 = 先过滤（L1 deny/剥除 → L2 manifest 放行）后 L0 显式注入——
+ * 「core 过滤之后显式注入」即此语义：baseEnv 是调用方（core/宿主）已过滤的基座，
+ * L0 键在最后写入故不受 L1 剥除影响（交集为 ∅ 由测试断言兜底）。
+ *
+ * 层规格（impl-plan §2.12 三层表）：
+ * - L0 基础设施键：XYZ_AGENT_DATA_DIR / XYZ_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
+ *   （条件）/ XYZ_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
+ *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
+ *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+export function buildEngineChildEnv(
+  baseEnv: Record<string, string | undefined>,
+  opts: EngineChildEnvOptions,
+): Record<string, string> {
+  // 基座拷贝（undefined 值不进 env——Node spawn 的 env 值须是 string）
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (value !== undefined) env[key] = value;
+  }
+
+  // L1：deny + 显式剥除（先于 L0，保证 L0 注入不受剥除影响）
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+
+  // L2：manifest envPrefixes 放行 processEnv（在 L0 之前——L0 基础设施键优先级最高）
+  applyManifestAllowlist(env, opts);
+
+  // L1 兜底复检：deny/剥除恒高于 manifest 放行——宽前缀（如声明 XYZ_ 形态的
+  // 宽松清单）也不允许经 L2 把 deny 键带回来。L0 未注入，此轮只清 L2 写入面。
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+
+  // L0：基础设施键显式注入（最后写入 = 最高优先级）
+  injectL0InfraKeys(env, opts);
+
+  return env;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 通用出站构建器（引擎无关 deny 剥离）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** buildOutboundChildEnv 入参（SDK 版；语义见函数头注释）。 */
+export interface BuildOutboundChildEnvOptions {
+  /** 父进程 env 快照（调用方显式注入；本函数绝不改写它） */
+  parentEnv: Record<string, string | undefined>;
+  /** 强制注入/覆盖的键；值为 undefined 时执行删除语义 */
+  extras?: Record<string, string | undefined>;
+  /** 基座前缀白名单；缺省 = 全量继承父 env（与 shared 版的差异，见函数头注释） */
+  prefixes?: readonly string[];
+}
+
+/**
+ * 通用子进程出站 env 构建器（deny 剥离终态），供非引擎 spawn 面（worktree git
+ * execFile 等）复用——R3 MF-C：deny 键不进 git 子进程，git hooks 等后代不再可能
+ * 消费生命周期标志 / WS 令牌。
+ *
+ * 与 @xyz-agent/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
+ * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
+ * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
+ * 兜底语义与 shared 版一致。需要白名单形态时调用方显式传 prefixes。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+export function buildOutboundChildEnv(
+  opts: BuildOutboundChildEnvOptions,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const loweredPrefixes =
+    opts.prefixes !== undefined
+      ? opts.prefixes.map((p) => p.toLowerCase())
+      : null;
+  for (const [key, value] of Object.entries(opts.parentEnv)) {
+    if (value === undefined) continue;
+    if (loweredPrefixes !== null) {
+      const loweredKey = key.toLowerCase();
+      if (!loweredPrefixes.some((prefix) => loweredKey.startsWith(prefix))) continue;
+    }
+    out[key] = value;
+  }
+  if (opts.extras !== undefined) {
+    for (const [key, value] of Object.entries(opts.extras)) {
+      if (value !== undefined) out[key] = value;
+      else delete out[key];
+    }
+  }
+  deleteEnvKeysCaseInsensitive(out, ENGINE_ENV_DENY_LIST);
+  return out;
+}

package/src/error-message.ts

@@ -0,0 +1,22 @@
+// src/error-message.ts
+//
+// 「错误 → 可读字符串」兜底单源（round1-reuse R11 微副本收编：core
+// src/core/error-message.ts、pi/zcode 引擎包 error-message.ts 副本自本模块
+// re-export 收编；此前各包自持先例见各自 shim 注释）。
+//
+// [A8 修复]（round1 business-logic S1 登记，可操作性修复）：非 Error 的 object
+// 入参改 JSON.stringify 结构化文本（协议错误帧 {code,message,recovery} 直进文案，
+// 不再退化为 "[object Object]"）；stringify 抛错（循环引用等）兜底 String(e)。
+// Error 入参输出逐字节不变。
+
+export function toErrorMessage(e: unknown): string {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null) {
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
+  }
+  return String(e);
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+// src/index.ts
+//
+// @zhushanwen/subagent-engine-sdk 主 barrel。
+// u-foundation 契约根（impl-plan §2 W1 行）：协议面（帧型/方法/错误码/版本协商/
+// JSON Schema/契约类型）+ 引擎侧原语（7 模块）+ UI 请求契约类型。
+// 不变量（设计 §3.10.1）：本包禁止 import @zhushanwen/subagent-core——守卫
+// .githooks/check-engine-sdk-boundary.mjs（SDK 源码 + dist 双侧扫描）。
+
+// ── 协议面（契约类型 SSOT + 帧型 + 方法 + 反向通道 + 错误码 + 版本协商 + schema）──
+export * from "./protocol/index.ts";
+
+// ── 引擎侧原语（7 模块，impl-plan §2.1 原语迁移处置表）──
+export * from "./schema-emulation.ts";
+export * from "./nesting-guard.ts";
+export * from "./logger.ts";
+export * from "./kill-chain.ts";
+export * from "./journal-replay.ts";
+export * from "./data-dir.ts";
+export * from "./paths.ts";
+
+// ── UI 请求契约类型（host/askUser 反向通道载荷；core 反向 re-export 保消费面）──
+export * from "./ui-types.ts";
+
+// UI channel 提取 + channel 注册表（round1-reuse R1：core execution 与 pi 引擎 CLI
+// 的逐字等价副本自本模块 re-export 收编）。
+export * from "./ui-channels.ts";
+
+// W12 落地（impl-plan §2.12）：env/spawn 原语（三层 env 契约 + 引擎子进程唯一 spawn
+// 入口 + 宿主死亡自灭守卫）。
+export * from "./env.ts";
+export * from "./spawn.ts";
+
+// W9 落地（impl-plan §2.9）：引擎 CLI 启动解析（宿主 × 平台二维矩阵 + node 执行器探针，
+// 探针复刻 runtime relay-env 先例）。
+export * from "./node-executor.ts";
+
+// stderr tee 轮转/清理单源（前缀参数化；两引擎包的 logs/stderr-rotation.ts 为薄包装）。
+export * from "./logs/stderr-rotation.ts";
+
+// relay 通道 env 名与协议常量 SSOT（round1-reuse R9：core ./relay-env 子入口与 pi
+// 引擎包副本自本模块 re-export 收编，消 5 个 XYZ_SUBAGENT_RELAY_* env 名双副本）。
+export * from "./relay-env.ts";
+
+// 「错误 → 可读字符串」与 best-effort 吞错 helper 单源（round1-reuse R11：core 与
+// pi/zcode 引擎包的微副本 re-export 收编；toErrorMessage 含 A8 修复——非 Error
+// object 入参 JSON.stringify 结构化文本，Error 入参逐字节不变）。
+export * from "./error-message.ts";
+export * from "./best-effort.ts";
+
+// journal 文件读取单源（S4 簇 6：core event-journal 与 zcode journal-io 的
+// replayJournal/parseLine 逐字等价双副本收编；JournalWriter 写侧留 core）。
+export * from "./journal-io.ts";
+
+// 引擎进程内契约面七符号 + parseCtxModel（S4 簇 1：pi/zcode port-types.ts 本地镜像
+// 收编，两包改 re-export shim。收主 barrel 不进 protocol/——RunContext 含
+// AbortSignal/回调非序列化成员；全量任务声明名 EngineAgentCallOpts 避让 protocol
+// 的 AgentCallOpts 引擎面子集）。
+export * from "./port-contract.ts";
+
+// 引擎 CLI 进程入口样板（S4 簇 2：pi/zcode main.ts 同构段收编，两包收缩为薄层；
+// armEngineSelfDestruct 与 server 构造留薄层，configureLoggerSink/readline 循环
+// 在此）。
+export * from "./cli-entry.ts";

package/src/journal-io.ts

@@ -0,0 +1,82 @@
+// src/journal-io.ts
+//
+// journal 文件读取单源（S4 簇 6 收编：core execution/engine/common/event-journal.ts
+// 与 zcode-subagent-cli journal-io.ts 的 replayJournal/parseLine 逐字等价双副本收编
+// ——引擎包不能 import core，单源只能落 SDK；core 改 re-export、zcode 改 import，
+// 消费方路径零改动）。
+//
+// 实现以 core 版为准逐字迁移：私有 JournalLine 保留全字段形态（{v,ts,taskId,
+// engineId,seq,event}——taskId/engineId 仅诊断字段，重放在 map event 前即丢弃，
+// 故 zcode 旧副本的缩略行形态与本版无行为差异）。行格式权威：docs/architecture/
+// subagent-engine-abstraction.md §3.3.6（JSONL 中立 v1）；格式漂移面由 W10 golden
+// 往返测试 + core/zcode 各自 journal 直测覆盖。
+//
+// 分层：只承接读侧（replay）。JournalWriter（写入器）留 core——宿主侧职责；本模块
+// 与 journal-replay.ts（纯投影，无 fs）分离，保持投影层零文件系统依赖。
+
+import { readFileSync } from "node:fs";
+
+import type { AgentEvent } from "./protocol/contract-types.ts";
+
+/** journal 单行（JSONL，§3.3.6 v1）。私有形态：重放只消费 seq/event。 */
+interface JournalLine {
+  v: 1;
+  /** host 落盘时刻（Date.now()，ms）。 */
+  ts: number;
+  /** = RunContext.taskId = record.id（journal 文件名与池引用计数 key）。 */
+  taskId: string;
+  engineId: string;
+  seq: number;
+  /** AgentEvent 原样（onEvent 回调对象的 JSON.stringify 直接产物，无二次变换）。 */
+  event: AgentEvent;
+}
+
+/**
+ * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。
+ *
+ * - 文件不存在 → []（降级链语义：②级不可达不算错误，调用方落 ③级）；
+ * - 损坏行跳过（追加写产物末行可能截断；跳过优于整体失败——设计 C5「三级都不 throw」）；
+ * - 按 seq 稳定排序后返回（重放顺序权威是 seq，不依赖文件行序的隐式保证，§3.3.6）。
+ */
+export function replayJournal(path: string): AgentEvent[] {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const lines: JournalLine[] = [];
+  for (const row of raw.split("\n")) {
+    const trimmed = row.trim();
+    if (trimmed === "") continue;
+    const parsed = parseLine(trimmed);
+    if (parsed !== undefined) lines.push(parsed);
+  }
+  lines.sort((a, b) => a.seq - b.seq);
+  return lines.map((l) => l.event);
+}
+
+/** 单行 parse + 结构 guard（v=1 + event 形状最小判别：object 且 type 为 string）。 */
+function parseLine(trimmed: string): JournalLine | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const rec = parsed as Record<string, unknown>;
+  const event = rec.event;
+  if (rec.v !== 1 || typeof rec.ts !== "number" || typeof rec.seq !== "number") return undefined;
+  if (typeof event !== "object" || event === null || typeof (event as Record<string, unknown>).type !== "string") {
+    return undefined;
+  }
+  return {
+    v: 1,
+    ts: rec.ts,
+    taskId: typeof rec.taskId === "string" ? rec.taskId : "",
+    engineId: typeof rec.engineId === "string" ? rec.engineId : "",
+    seq: rec.seq,
+    event: event as AgentEvent,
+  };
+}