@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/journal-replay.d.cts

@@ -0,0 +1,45 @@
+import { n as Turn, f as AgentUsageTotal, a as AgentEvent, S as SessionView, h as EngineHandleData, R as ReplayedTurn } from './contract-types-sSlgppBC.cjs';
+
+/**
+ * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
+ * core ExecutionRecord 满足本视图（W2 断言挂靠点）；SDK 内自持 createReplayRecord 产出。
+ */
+interface ReplayRecordView {
+    turns: Turn[];
+    turnCount: number;
+    totalTokens: number;
+    lastError: string | undefined;
+}
+/** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
+declare function createReplayRecord(): ReplayRecordView;
+/**
+ * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
+ *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
+ *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
+ *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
+ *     totalTokens 累加
+ *   - error：存 record.lastError（getEventLog 派生 error 条目用）
+ *
+ * 唯一写点——replay 与 live 共用（重放等价性的实现体）。
+ *
+ * 穷尽性：switch 覆盖 AgentEvent 全部 variant；default 的 `never` 断言保证
+ * 新增 variant 时编译期报错（而非静默 no-op）。
+ */
+declare function updateFromEvent(record: ReplayRecordView, event: AgentEvent): void;
+/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义，§3.3.6）。 */
+declare function toReplayedTurn(turn: Turn): ReplayedTurn;
+/** 各 turn usageDelta 聚合为 AgentUsageTotal（无任何 usage 数据时 undefined）。 */
+declare function aggregateUsage(turns: readonly Turn[]): AgentUsageTotal | undefined;
+/**
+ * 事件流 → SessionView（live reducer 累积 turns——重放等价性的实现体）。
+ * journal I/O（replayJournal）不在此层——read 第②级降级编排（core 版
+ * replayJournalToSessionView）留 core，引擎侧按需自读 journal 后调本函数。
+ */
+declare function eventsToSessionView(events: readonly AgentEvent[], engineId: string, sessionId?: string): SessionView;
+/** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
+declare function sessionIdFromHandle(handle: EngineHandleData): string | undefined;
+
+export { type ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };

package/dist/journal-replay.d.ts

@@ -0,0 +1,45 @@
+import { n as Turn, f as AgentUsageTotal, a as AgentEvent, S as SessionView, h as EngineHandleData, R as ReplayedTurn } from './contract-types-sSlgppBC.js';
+
+/**
+ * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
+ * core ExecutionRecord 满足本视图（W2 断言挂靠点）；SDK 内自持 createReplayRecord 产出。
+ */
+interface ReplayRecordView {
+    turns: Turn[];
+    turnCount: number;
+    totalTokens: number;
+    lastError: string | undefined;
+}
+/** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
+declare function createReplayRecord(): ReplayRecordView;
+/**
+ * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
+ *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
+ *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
+ *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
+ *     totalTokens 累加
+ *   - error：存 record.lastError（getEventLog 派生 error 条目用）
+ *
+ * 唯一写点——replay 与 live 共用（重放等价性的实现体）。
+ *
+ * 穷尽性：switch 覆盖 AgentEvent 全部 variant；default 的 `never` 断言保证
+ * 新增 variant 时编译期报错（而非静默 no-op）。
+ */
+declare function updateFromEvent(record: ReplayRecordView, event: AgentEvent): void;
+/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义，§3.3.6）。 */
+declare function toReplayedTurn(turn: Turn): ReplayedTurn;
+/** 各 turn usageDelta 聚合为 AgentUsageTotal（无任何 usage 数据时 undefined）。 */
+declare function aggregateUsage(turns: readonly Turn[]): AgentUsageTotal | undefined;
+/**
+ * 事件流 → SessionView（live reducer 累积 turns——重放等价性的实现体）。
+ * journal I/O（replayJournal）不在此层——read 第②级降级编排（core 版
+ * replayJournalToSessionView）留 core，引擎侧按需自读 journal 后调本函数。
+ */
+declare function eventsToSessionView(events: readonly AgentEvent[], engineId: string, sessionId?: string): SessionView;
+/** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
+declare function sessionIdFromHandle(handle: EngineHandleData): string | undefined;
+
+export { type ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };

package/dist/journal-replay.js

@@ -0,0 +1,17 @@
+import {
+  aggregateUsage,
+  createReplayRecord,
+  eventsToSessionView,
+  sessionIdFromHandle,
+  toReplayedTurn,
+  updateFromEvent
+} from "./chunk-A75XDJIC.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  aggregateUsage,
+  createReplayRecord,
+  eventsToSessionView,
+  sessionIdFromHandle,
+  toReplayedTurn,
+  updateFromEvent
+};

package/dist/kill-chain.cjs

@@ -0,0 +1,221 @@
+"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/kill-chain.ts
+var kill_chain_exports = {};
+__export(kill_chain_exports, {
+  DEFAULT_KILL_GRACE_MS: () => DEFAULT_KILL_GRACE_MS,
+  DEFAULT_NATIVE_INTERRUPT_GRACE_MS: () => DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
+  HOST_TIMEOUT_ABORT_REASON: () => HOST_TIMEOUT_ABORT_REASON,
+  STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
+  abortWithFallback: () => abortWithFallback,
+  killChain: () => killChain,
+  synthesizeTimeoutOutcome: () => synthesizeTimeoutOutcome
+});
+module.exports = __toCommonJS(kill_chain_exports);
+
+// src/logger.ts
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+// src/error-message.ts
+function toErrorMessage(e) {
+  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);
+}
+
+// src/protocol/error-codes.ts
+var STDOUT_TAIL_ECHO_CHARS = 2e3;
+function truncate(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+var ENGINE_TIMEOUT_RECOVERY = "The engine was killed by the host timeout chain. Inspect the captured stdout tail, then re-run with a larger timeout, a narrower task, or `engine: pi`.";
+function engineTimeoutDetail(stdoutTail) {
+  return `host timeout chain exhausted (SIGTERM -> grace -> SIGKILL). Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. Recovery: ${ENGINE_TIMEOUT_RECOVERY}`;
+}
+
+// src/kill-chain.ts
+var logger = getLogger("subagents");
+var MS_PER_SECOND = 1e3;
+var DEFAULT_KILL_GRACE_MS = 5e3;
+var SIGKILL_REAP_TIMEOUT_MS = 1e4;
+var HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
+async function killChain(child, opts) {
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+  const exited = waitForExit(child);
+  safeKill(child, "SIGTERM");
+  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
+  if (graceful === "settled") return "terminated";
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+  if (opts.escalationNote !== void 0) {
+    logger.warn(
+      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`
+    );
+  }
+  safeKill(child, "SIGKILL");
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
+  return "killed";
+}
+function safeKill(child, signal) {
+  try {
+    child.kill(signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`
+    );
+  }
+}
+function synthesizeTimeoutOutcome(task, stdoutTail, engineId) {
+  return {
+    content: "",
+    // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
+    error: `engine_timeout: [slug=${task.description ?? "unknown"}] ${engineTimeoutDetail(stdoutTail)}`,
+    // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
+    exitCode: null,
+    engineId
+  };
+}
+var DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3e3;
+function abortWithFallback(child, signal, tryNativeInterrupt, opts) {
+  const graceMs = opts?.graceMs ?? DEFAULT_KILL_GRACE_MS;
+  const nativeGraceMs = opts?.nativeGraceMs ?? DEFAULT_NATIVE_INTERRUPT_GRACE_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      resolve(result);
+    }
+    function onExit() {
+      finish("terminated");
+    }
+    function runChain() {
+      void (async () => {
+        if (tryNativeInterrupt) {
+          try {
+            await tryNativeInterrupt();
+          } catch (err) {
+            logger.debug(
+              `[kill-chain] native interrupt failed, falling back to kill chain: ${toErrorMessage(err)}`
+            );
+          }
+          const stopped = await raceTimeout(waitForExit(child), nativeGraceMs);
+          if (stopped === "settled" || settled) return;
+        }
+        finish(await killChain(child, { graceMs }));
+      })();
+    }
+    function onAbort() {
+      runChain();
+    }
+    child.once("exit", onExit);
+    if (child.exitCode !== null || child.signalCode !== null) {
+      finish("terminated");
+      return;
+    }
+    if (signal.aborted) runChain();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function waitForExit(child) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    child.once("exit", () => resolve());
+  });
+}
+function raceTimeout(p, ms, unref = false) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve("timeout"), ms);
+    if (unref) timer.unref();
+    p.then(
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      },
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      }
+    );
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_KILL_GRACE_MS,
+  DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
+  HOST_TIMEOUT_ABORT_REASON,
+  STDOUT_TAIL_ECHO_CHARS,
+  abortWithFallback,
+  killChain,
+  synthesizeTimeoutOutcome
+});

package/dist/kill-chain.d.cts

@@ -0,0 +1,74 @@
+export { S as STDOUT_TAIL_ECHO_CHARS } from './error-codes-DHco5-i_.cjs';
+import { A as AgentCallOpts, c as AgentOutcome } from './contract-types-sSlgppBC.cjs';
+
+/**
+ * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
+ * 用结构接口而非 ChildProcess 类型：测试可注入 fake（ChildProcess 全字段构造过重），
+ * 且未来 driver host 的常驻进程句柄只要满足此形状即可复用杀链。
+ */
+interface KillableChild {
+    /** 非 null = 进程已退出（自然退出码）。 */
+    readonly exitCode: number | null;
+    /** 非 null = 进程被信号杀死。exitCode/signalCode 任一非 null 即已退出。 */
+    readonly signalCode: string | null;
+    /** 发信号。返回 false = 进程已不存在（kill no-op）。 */
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+/** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
+declare const DEFAULT_KILL_GRACE_MS = 5000;
+/**
+ * 宿主超时 abort 的 signal.reason 标记（对齐点④）。mergeTimeoutSignal（SAR 侧超时
+ * 合并链）产出；引擎 abort 合成终态时判别「超时 vs 用户 cancel」——超时统一走
+ * synthesizeTimeoutOutcome（engine_timeout），cancel 维持中止标记（engine_run_failed）。
+ */
+declare const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
+/** killChain 的参数形状。 */
+interface KillChainOptions {
+    /**
+     * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
+     * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
+     */
+    graceMs: number;
+    /**
+     * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
+     * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
+     */
+    unrefTimers?: boolean;
+    /**
+     * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
+     * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
+     */
+    escalationNote?: string;
+}
+/**
+ * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
+ *
+ * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
+ */
+declare function killChain(child: KillableChild, opts: KillChainOptions): Promise<"terminated" | "killed">;
+/**
+ * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
+ * 含 stdout 尾部 2000 字 + 恢复指引（§3.3.3 第 6 行）；exitCode: null = 被信号杀死
+ * （AgentOutcome 的杀链判据，§3.3.5）。
+ *
+ * engineId 参数注入（原 core 版缺省 DEFAULT_ENGINE_ID——SDK 不感知宿主路由缺省值，
+ * 调用方必须显式传实际引擎 id）。
+ */
+declare function synthesizeTimeoutOutcome(task: AgentCallOpts, stdoutTail: string, engineId: string): AgentOutcome;
+/** 原生中断后的宽限窗口默认值（ms）：中断指令送达 → 引擎自行收尾的等待上限。 */
+declare const DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3000;
+/**
+ * abort 两级编排 helper（D1 abort 分级的公共实现）：
+ * signal abort 时 ①先调引擎原生中断（tryNativeInterrupt，若有）并给宽限窗口，
+ * 窗口内未停（或无原生中断——CLI-only 引擎）则 ②走杀链兜底。
+ *
+ * 进程自然退出时以 'terminated' settle（挂在 exit 事件上，杀链对已退进程是 no-op），
+ * 调用方可安全 await；signal 永不 abort 且进程已退时也会 settle，不悬挂。
+ */
+declare function abortWithFallback(child: KillableChild, signal: AbortSignal, tryNativeInterrupt?: () => Promise<void>, opts?: {
+    graceMs?: number;
+    nativeGraceMs?: number;
+}): Promise<"terminated" | "killed">;
+
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome };

package/dist/kill-chain.d.ts

@@ -0,0 +1,74 @@
+export { S as STDOUT_TAIL_ECHO_CHARS } from './error-codes-Dhss2Kmk.js';
+import { A as AgentCallOpts, c as AgentOutcome } from './contract-types-sSlgppBC.js';
+
+/**
+ * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
+ * 用结构接口而非 ChildProcess 类型：测试可注入 fake（ChildProcess 全字段构造过重），
+ * 且未来 driver host 的常驻进程句柄只要满足此形状即可复用杀链。
+ */
+interface KillableChild {
+    /** 非 null = 进程已退出（自然退出码）。 */
+    readonly exitCode: number | null;
+    /** 非 null = 进程被信号杀死。exitCode/signalCode 任一非 null 即已退出。 */
+    readonly signalCode: string | null;
+    /** 发信号。返回 false = 进程已不存在（kill no-op）。 */
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+/** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
+declare const DEFAULT_KILL_GRACE_MS = 5000;
+/**
+ * 宿主超时 abort 的 signal.reason 标记（对齐点④）。mergeTimeoutSignal（SAR 侧超时
+ * 合并链）产出；引擎 abort 合成终态时判别「超时 vs 用户 cancel」——超时统一走
+ * synthesizeTimeoutOutcome（engine_timeout），cancel 维持中止标记（engine_run_failed）。
+ */
+declare const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
+/** killChain 的参数形状。 */
+interface KillChainOptions {
+    /**
+     * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
+     * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
+     */
+    graceMs: number;
+    /**
+     * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
+     * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
+     */
+    unrefTimers?: boolean;
+    /**
+     * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
+     * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
+     */
+    escalationNote?: string;
+}
+/**
+ * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
+ *
+ * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
+ */
+declare function killChain(child: KillableChild, opts: KillChainOptions): Promise<"terminated" | "killed">;
+/**
+ * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
+ * 含 stdout 尾部 2000 字 + 恢复指引（§3.3.3 第 6 行）；exitCode: null = 被信号杀死
+ * （AgentOutcome 的杀链判据，§3.3.5）。
+ *
+ * engineId 参数注入（原 core 版缺省 DEFAULT_ENGINE_ID——SDK 不感知宿主路由缺省值，
+ * 调用方必须显式传实际引擎 id）。
+ */
+declare function synthesizeTimeoutOutcome(task: AgentCallOpts, stdoutTail: string, engineId: string): AgentOutcome;
+/** 原生中断后的宽限窗口默认值（ms）：中断指令送达 → 引擎自行收尾的等待上限。 */
+declare const DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3000;
+/**
+ * abort 两级编排 helper（D1 abort 分级的公共实现）：
+ * signal abort 时 ①先调引擎原生中断（tryNativeInterrupt，若有）并给宽限窗口，
+ * 窗口内未停（或无原生中断——CLI-only 引擎）则 ②走杀链兜底。
+ *
+ * 进程自然退出时以 'terminated' settle（挂在 exit 事件上，杀链对已退进程是 no-op），
+ * 调用方可安全 await；signal 永不 abort 且进程已退时也会 settle，不悬挂。
+ */
+declare function abortWithFallback(child: KillableChild, signal: AbortSignal, tryNativeInterrupt?: () => Promise<void>, opts?: {
+    graceMs?: number;
+    nativeGraceMs?: number;
+}): Promise<"terminated" | "killed">;
+
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome };

package/dist/kill-chain.js

@@ -0,0 +1,23 @@
+import {
+  DEFAULT_KILL_GRACE_MS,
+  DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
+  HOST_TIMEOUT_ABORT_REASON,
+  abortWithFallback,
+  killChain,
+  synthesizeTimeoutOutcome
+} from "./chunk-LEOBWKRM.js";
+import "./chunk-PYO3YR7W.js";
+import {
+  STDOUT_TAIL_ECHO_CHARS
+} from "./chunk-PPEPBVCC.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  DEFAULT_KILL_GRACE_MS,
+  DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
+  HOST_TIMEOUT_ABORT_REASON,
+  STDOUT_TAIL_ECHO_CHARS,
+  abortWithFallback,
+  killChain,
+  synthesizeTimeoutOutcome
+};

package/dist/logger.cjs

@@ -0,0 +1,84 @@
+"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/logger.ts
+var logger_exports = {};
+__export(logger_exports, {
+  configureLoggerSink: () => configureLoggerSink,
+  getLogger: () => getLogger,
+  resetLoggerSinkForTests: () => resetLoggerSinkForTests
+});
+module.exports = __toCommonJS(logger_exports);
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+function configureLoggerSink(sink) {
+  getSinkSlot().current = sink;
+}
+function resetLoggerSinkForTests() {
+  getSinkSlot().current = void 0;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  configureLoggerSink,
+  getLogger,
+  resetLoggerSinkForTests
+});

package/dist/logger.d.cts

@@ -0,0 +1,24 @@
+/**
+ * SDK 侧 logger sink（引擎 CLI 注入宿主形态日志出口；core 版对应 HostServices.log）。
+ */
+interface LoggerSink {
+    log(level: LogLevel, component: string, message: string, data?: unknown): void;
+}
+/** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
+type LogLevel = "debug" | "warn" | "error";
+/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
+interface CoreLogger {
+    debug(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+}
+/**
+ * 注入日志 sink（引擎 CLI 启动早期调用；重复调用后者覆盖——测试切 sink 依赖此语义）。
+ * 解析发生在每次 logger 方法调用时，模块顶层已缓存的 logger 透明切换，无加载顺序依赖。
+ */
+declare function configureLoggerSink(sink: LoggerSink): void;
+/** 测试隔离专用：清空 sink 配置态（生产禁用）。 */
+declare function resetLoggerSinkForTests(): void;
+declare function getLogger(component: string): CoreLogger;
+
+export { type CoreLogger, type LogLevel, type LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests };

package/dist/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SDK 侧 logger sink（引擎 CLI 注入宿主形态日志出口；core 版对应 HostServices.log）。
+ */
+interface LoggerSink {
+    log(level: LogLevel, component: string, message: string, data?: unknown): void;
+}
+/** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
+type LogLevel = "debug" | "warn" | "error";
+/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
+interface CoreLogger {
+    debug(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+}
+/**
+ * 注入日志 sink（引擎 CLI 启动早期调用；重复调用后者覆盖——测试切 sink 依赖此语义）。
+ * 解析发生在每次 logger 方法调用时，模块顶层已缓存的 logger 透明切换，无加载顺序依赖。
+ */
+declare function configureLoggerSink(sink: LoggerSink): void;
+/** 测试隔离专用：清空 sink 配置态（生产禁用）。 */
+declare function resetLoggerSinkForTests(): void;
+declare function getLogger(component: string): CoreLogger;
+
+export { type CoreLogger, type LogLevel, type LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests };

package/dist/logger.js

@@ -0,0 +1,11 @@
+import {
+  configureLoggerSink,
+  getLogger,
+  resetLoggerSinkForTests
+} from "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  configureLoggerSink,
+  getLogger,
+  resetLoggerSinkForTests
+};