@zhushanwen/subagent-core 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# @zhushanwen/subagent-core
+
+跨宿主共享的 subagent 执行层与 workflow 编排核心：pi extension（`@zhushanwen/pi-subagent-workflow`）与 zcode 插件（zsw）双宿主引用同一实现，消灭两套平行实现导致的逻辑漂移。
+
+- **双形态包（D4）**：workspace 消费 TS 源（exports 的 `import` 条件指向 `src/`），npm 消费 tsup 产物（dist ESM + CJS，`publishConfig` 在 publish 时整体替换 `exports`）。CJS 产物对 `@xyz-agent/extension-protocol` 设 tsup noExternal 防御性 bundle 边界——其 npm dist 仅 ESM，而 CJS 宿主（zsw，node>=20）的 require 链不能承载外部 ESM 依赖（设计 D4，见本仓 `docs/design/subagent-core-package-extraction.md` §3.3；当前 entry 闭包无 protocol 运行时引用、dist 实测零常量命中，未来一旦引入即 bundle）。其余依赖（ajv / yaml / proper-lockfile）保持外部依赖形态，均为常规 CJS 可 require 的双格式包。
+- **依赖闭包（D3）**：`@xyz-agent/extension-protocol` + `proper-lockfile` + `ajv` + `yaml`；宿主服务（日志 / 数据根 / 发现根 / 通知）经 `HostServices` 端口注入，core 闭包不含 pi SDK。
+- **workflows 资产（D1）**：内置 workflow 脚本（`.js` / `.cjs`）不参与编译，包内 `workflows/` 目录 src=dist 同字节直发，经 `./workflows/*` 子入口按原文件访问。
+- **公共 API 面即 semver 契约（D5）**：breaking 走 major；导出面收窄不放宽，新增导出走 minor。
+
+## 公共 API
+
+### 主入口（`@zhushanwen/subagent-core`）
+
+| 导出 | 类别 | 说明 |
+|------|------|------|
+| `configureCore(host)` | fn | 注入宿主服务（`HostServices`）；未注入即消费 `dataRoot()` 抛 `core_host_not_configured` |
+| `DEFAULT_DATA_ROOT` | const | core 内建缺省数据根（`~/.subagent-core`），供宿主显式选用（消除缺省静默漂目录） |
+| `HostServices` | type | 宿主服务端口：`dataRoot` / `log` / `discoveryRoots` |
+| `DiscoveryRoot` | type | 发现根条目 `{ dir, source }`（source 标签供遮蔽报告与测试断言） |
+| `getLogger(component)` | fn | facade 代理 logger——每次调用动态解析当前宿主实现，`configureCore` 前后透明切换 |
+| `CoreLogger`, `LogLevel` | type | logger 端口类型（`HostServices.log` 契约成员） |
+| `configureNotifyDomain(ports)` | fn | 注入通知域窄端口（投递内核工厂 + pending 活跃计数），成员可选、缺席降级 |
+| `NotifyDomainPorts` | type | 通知域端口结构（结构化签名，core 不 import 通知实现包） |
+| `EnginePort` | type | subagent 执行引擎唯一契约点（run / interact / read / probe 四能力面） |
+| `RunContext`, `EngineRunResult` | type | `EnginePort.run` 的运行期上下文与结果 |
+| `AgentTaskSpec`, `AgentOutcome`, `AgentEvent` | type | 任务声明 / 执行结果 / 事件流（引擎中立） |
+| `SessionView`, `ReplayedTurn`, `EngineHandle`, `EngineHandleData` | type | 会话视图 / 回放轮次 / 运行句柄 |
+| `EngineCapabilities`, `ProbeReport`, `PersonaSpec` | type | 能力声明 / 探针报告 / persona 声明 |
+| `InteractAction`, `InteractResult` | type | 交互控制面（chatMode message/close/cancel + idle） |
+| `ModelInfo`, `SubagentStream` | type | `RunContext` 成员类型（type-only，`SubagentStream` 由 core 内部构造） |
+| `routeEngine(opts)` | fn | 三层路由（调用参数 > frontmatter > 全局默认）+ probe fallback 编排的单一权威点 |
+| `EngineRouteOptions`, `EngineRouteResult`, `EngineRouting`, `EngineRoutingInput`, `EngineRoutingSource` | type | 路由层类型 |
+| `runWorkflow(spec, deps, signal?)` | fn | workflow run 生命周期入口（返回 runId） |
+| `abortRun(runId, deps, ...)` | fn | 终止 run（done 态 no-op） |
+| `RunSpec`, `LifecycleDeps` | type | `runWorkflow` 参数类型 |
+| `CORE_PACKAGE_VERSION` | const | 包版本常量（与 package.json 同步维护） |
+
+### 语义子入口（双端复用链专用）
+
+| 子入口 | 内容 |
+|--------|------|
+| `@zhushanwen/subagent-core/engines/zcode/reader` | zcode 引擎 session 历史读取（`readZcodeSessionView` / `ZcodeReaderError`） |
+| `@zhushanwen/subagent-core/engines/zcode/constants` | zcode 引擎常量（`ZCODE_ENGINE_ID` / 路径后缀 / 缺省模型等） |
+| `@zhushanwen/subagent-core/engine/paths` | 引擎数据目录路径推导（engines 根 / 池目录 / journal 路径） |
+| `@zhushanwen/subagent-core/relay-env` | relay 通道 env 名与协议常量 SSOT（extension / runtime / 代理三方共用） |
+
+### 资产子入口
+
+| 子入口 | 内容 |
+|--------|------|
+| `@zhushanwen/subagent-core/workflows/*` | 内置 workflow 脚本原文件（`chain.js` / `parallel.js` / `scatter-gather.js` / `map-reduce.js` / `review-fix-loop.js` + `review-fix-loop-utils.cjs` / `_shared/`），`require` 与 `import` 条件同径（D1 同字节直发） |
+
+仓内壳侧（pi extension）另有 `./* -> src/*` 通配深路径消费（`<pkg>/<域>/<路径>.ts` 形态）——该通配仅仓内保留，npm 发布面刻意收窄到上列受控入口（D5：exports 面即 semver 契约）。语义子入口精确条目优先于通配（Node exact-match-beats-pattern）。
+
+## 宿主接入示例
+
+两段示例同时是 `core_host_not_configured` 错误恢复指引的落点：**看到该错误 = 宿主壳未调 `configureCore`，按下述示例补注入后重试。**
+
+### pi 壳（workspace 引用）
+
+活例：本仓 `extensions/universal/subagent-workflow/src/host/pi-host.ts`（`createPiHostServices`）。要点：`dataRoot` / `discoveryRoots` 每次调用现取 `getAgentDir()`（禁模块级缓存——pi 实例按 session dir 隔离），log 桥接 `@zhushanwen/pi-extension-logger`，notify 桥接 `@xyz-agent/session-delivery` + `@zhushanwen/pi-pending-notifications`。扩展初始化最早处：
+
+```ts
+import { configureCore, configureNotifyDomain } from "@zhushanwen/subagent-core";
+import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.ts";
+
+configureCore(createPiHostServices());
+configureNotifyDomain(createPiNotifyDomainPorts());
+```
+
+### zsw / 独立宿主（npm 引用，纯 CJS）
+
+最小接入 = `configureCore({ dataRoot, log })` + `getLogger`。错误闭环：未注入时消费 core API 抛 `core_host_not_configured`（错误信息指向本节）→ 按下例补 `configureCore` → 重试：
+
+```js
+// Node >= 20，CommonJS
+const {
+  configureCore,
+  getLogger,
+  DEFAULT_DATA_ROOT,
+} = require("@zhushanwen/subagent-core");
+
+configureCore({
+  dataRoot() {
+    return DEFAULT_DATA_ROOT; // 或宿主自有数据根，如 path.join(os.homedir(), ".zcode", "zsw")
+  },
+  log(level, component, message, data) {
+    // 接宿主日志设施；最小实现可直接走 console（core 缺省 sink：warn/error 走 console、debug no-op）
+    (level === "error" ? console.error : console.debug)(`[${component}] ${message}`, data ?? "");
+  },
+  // discoveryRoots 可选：不传则用 core 内建缺省（user 级 agents/workflows 根）
+});
+
+const logger = getLogger("zsw"); // facade：configureCore 前后透明切换宿主实现
+logger.debug("host configured");
+```
+
+### 失败形态与恢复指引
+
+| 错误 | 触发 | 恢复 |
+|------|------|------|
+| `core_host_not_configured` | 未 `configureCore` 即消费 | 按上节示例补注入后重试（错误信息内含指引） |
+| `core_module_load_failed`（require 链） | 安装形态 / node 版本问题 | node 版本要求 >= 20；`rm -rf node_modules && npm i` 重装；确认经包 `exports` 的 `require` 条件加载 dist CJS，而非手工深引 `dist/` 内部路径 |
+| `core_module_load_failed`（worker scriptPath） | workflow worker 启动时 `workerData.scriptPath` 缺失 | D1：workflow 脚本以 **scriptPath 目录锚定**加载——宿主 spawn worker 时必须注入脚本绝对路径（`workerData.scriptPath`），staged / npm 安装布局下无 node_modules 解析面可回退；请检查宿主 worker 宿主点的注入代码，勿改脚本内 require 包名 |
+
+## 构建
+
+```bash
+pnpm run build   # tsup 多入口：主入口 + 4 语义子入口保形输出（dist/<entry> 与 src 同构，d.ts/d.cts 全覆盖）
+pnpm run test
+pnpm run typecheck
+```
+
+发布走本仓 changeset 管线；`publishConfig` 中的发布面与开发态 `exports` 必须同步维护（新增子入口时两处同改）。

package/dist/chunk-3VOERJPJ.js

@@ -0,0 +1,22 @@
+// src/execution/engine/engines/zcode/constants.ts
+var ZCODE_ENGINE_ID = "zcode";
+var ZCODE_ADAPTER_VERSION = "1.0.0";
+var ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+var ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"];
+var ZCODE_POOL_CONFIG_SUFFIX = [".zcode", "cli", "config.json"];
+var ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
+var ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+var ZCODE_KILL_GRACE_MS = 5e3;
+var ZCODE_ERROR_TAIL_CHARS = 2e3;
+
+export {
+  ZCODE_ENGINE_ID,
+  ZCODE_ADAPTER_VERSION,
+  ZCODE_CLI_DEFAULT_PATH,
+  ZCODE_V2_CONFIG_PATH_SUFFIX,
+  ZCODE_POOL_CONFIG_SUFFIX,
+  ZCODE_POOL_DB_RELATIVE_PATH,
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+  ZCODE_KILL_GRACE_MS,
+  ZCODE_ERROR_TAIL_CHARS
+};

package/dist/chunk-A4IVZWVX.js

@@ -0,0 +1,31 @@
+// src/execution/relay-env.ts
+var RELAY_ENV_SOCKET = "XYZ_SUBAGENT_RELAY_SOCKET";
+var RELAY_ENV_NODE = "XYZ_SUBAGENT_RELAY_NODE";
+var RELAY_ENV_SCRIPT = "XYZ_SUBAGENT_RELAY_SCRIPT";
+var RELAY_ENV_SESSION_ID = "XYZ_SUBAGENT_RELAY_SESSION_ID";
+var RELAY_ENV_RECORD_ID = "XYZ_SUBAGENT_RELAY_RECORD_ID";
+var RELAY_PROTOCOL_VERSION = 1;
+var RELAY_EXIT_CODES = {
+  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
+  VERSION_MISMATCH: 10,
+  /** relay socket 不可达（runtime 未运行或已重启）。 */
+  SOCKET_UNREACHABLE: 11,
+  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
+  SOCKET_CLOSED: 12,
+  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
+  MISSING_IDENTITY: 13
+};
+function isRelayActive(env) {
+  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
+}
+
+export {
+  RELAY_ENV_SOCKET,
+  RELAY_ENV_NODE,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_RECORD_ID,
+  RELAY_PROTOCOL_VERSION,
+  RELAY_EXIT_CODES,
+  isRelayActive
+};

package/dist/execution/engine/engines/zcode/constants.cjs

@@ -0,0 +1,54 @@
+"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/execution/engine/engines/zcode/constants.ts
+var constants_exports = {};
+__export(constants_exports, {
+  ZCODE_ADAPTER_VERSION: () => ZCODE_ADAPTER_VERSION,
+  ZCODE_CLI_DEFAULT_PATH: () => ZCODE_CLI_DEFAULT_PATH,
+  ZCODE_ENGINE_ID: () => ZCODE_ENGINE_ID,
+  ZCODE_ERROR_TAIL_CHARS: () => ZCODE_ERROR_TAIL_CHARS,
+  ZCODE_FALLBACK_DEFAULT_MODEL: () => ZCODE_FALLBACK_DEFAULT_MODEL,
+  ZCODE_KILL_GRACE_MS: () => ZCODE_KILL_GRACE_MS,
+  ZCODE_POOL_CONFIG_SUFFIX: () => ZCODE_POOL_CONFIG_SUFFIX,
+  ZCODE_POOL_DB_RELATIVE_PATH: () => ZCODE_POOL_DB_RELATIVE_PATH,
+  ZCODE_V2_CONFIG_PATH_SUFFIX: () => ZCODE_V2_CONFIG_PATH_SUFFIX
+});
+module.exports = __toCommonJS(constants_exports);
+var ZCODE_ENGINE_ID = "zcode";
+var ZCODE_ADAPTER_VERSION = "1.0.0";
+var ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+var ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"];
+var ZCODE_POOL_CONFIG_SUFFIX = [".zcode", "cli", "config.json"];
+var ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
+var ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+var ZCODE_KILL_GRACE_MS = 5e3;
+var ZCODE_ERROR_TAIL_CHARS = 2e3;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZCODE_ADAPTER_VERSION,
+  ZCODE_CLI_DEFAULT_PATH,
+  ZCODE_ENGINE_ID,
+  ZCODE_ERROR_TAIL_CHARS,
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+  ZCODE_KILL_GRACE_MS,
+  ZCODE_POOL_CONFIG_SUFFIX,
+  ZCODE_POOL_DB_RELATIVE_PATH,
+  ZCODE_V2_CONFIG_PATH_SUFFIX
+});

package/dist/execution/engine/engines/zcode/constants.d.cts

@@ -0,0 +1,31 @@
+/** zcode 引擎的 registry key。 */
+declare const ZCODE_ENGINE_ID = "zcode";
+/** zcode 适配器版本（handle.adapterVersion 数据源——golden 样本对齐排查锚点）。 */
+declare const ZCODE_ADAPTER_VERSION = "1.0.0";
+/**
+ * zcode CLI 缺省路径（12.4MB node bundle，不在 PATH——2026-08-25 实测）。
+ * 组合根可用 deps.cliPath 覆盖（测试注入 / 未来安装形态变化）。
+ */
+declare const ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+/**
+ * 唯一凭据源 config（桌面端登录态，zsub V2_CONFIG_PATH 同构）。
+ * 为什么绝不读 ~/.zcode/cli/config.json：它不在 ZCode GUI 管理面，可能残留历史
+ * 验证配置（2026-08-25 事故：8/24 zsub 开发残留把默认模型劫持到失效 router 端点，
+ * turn 0 即 401）；桌面端登录凭据落在 v2/config.json，是 zsub 生产验证过的凭据源。
+ */
+declare const ZCODE_V2_CONFIG_PATH_SUFFIX: readonly [".zcode", "v2", "config.json"];
+/** 池内 config.json 相对隔离 HOME 的位置（CLI 只读 $HOME/.zcode/cli/config.json）。 */
+declare const ZCODE_POOL_CONFIG_SUFFIX: readonly [".zcode", "cli", "config.json"];
+/**
+ * 池内 db.sqlite 相对隔离 HOME 的位置（handle.sessionRef.dbPath 的值——相对池目录
+ * 自描述，read 时经 resolvePoolDir + 该相对路径重定位，设计 §3.3.6）。
+ */
+declare const ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
+/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
+declare const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+/** 杀链 grace 窗口：SIGTERM 后等这么久再 SIGKILL（zsub 同构 5s；实测 SIGTERM→exit 仅 103ms）。 */
+declare const ZCODE_KILL_GRACE_MS = 5000;
+/** 错误信息里保留的 stdout 尾部长度（engine_run_failed 规格：够诊断、不刷屏）。 */
+declare const ZCODE_ERROR_TAIL_CHARS = 2000;
+
+export { ZCODE_ADAPTER_VERSION, ZCODE_CLI_DEFAULT_PATH, ZCODE_ENGINE_ID, ZCODE_ERROR_TAIL_CHARS, ZCODE_FALLBACK_DEFAULT_MODEL, ZCODE_KILL_GRACE_MS, ZCODE_POOL_CONFIG_SUFFIX, ZCODE_POOL_DB_RELATIVE_PATH, ZCODE_V2_CONFIG_PATH_SUFFIX };

package/dist/execution/engine/engines/zcode/constants.d.ts

@@ -0,0 +1,31 @@
+/** zcode 引擎的 registry key。 */
+declare const ZCODE_ENGINE_ID = "zcode";
+/** zcode 适配器版本（handle.adapterVersion 数据源——golden 样本对齐排查锚点）。 */
+declare const ZCODE_ADAPTER_VERSION = "1.0.0";
+/**
+ * zcode CLI 缺省路径（12.4MB node bundle，不在 PATH——2026-08-25 实测）。
+ * 组合根可用 deps.cliPath 覆盖（测试注入 / 未来安装形态变化）。
+ */
+declare const ZCODE_CLI_DEFAULT_PATH = "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+/**
+ * 唯一凭据源 config（桌面端登录态，zsub V2_CONFIG_PATH 同构）。
+ * 为什么绝不读 ~/.zcode/cli/config.json：它不在 ZCode GUI 管理面，可能残留历史
+ * 验证配置（2026-08-25 事故：8/24 zsub 开发残留把默认模型劫持到失效 router 端点，
+ * turn 0 即 401）；桌面端登录凭据落在 v2/config.json，是 zsub 生产验证过的凭据源。
+ */
+declare const ZCODE_V2_CONFIG_PATH_SUFFIX: readonly [".zcode", "v2", "config.json"];
+/** 池内 config.json 相对隔离 HOME 的位置（CLI 只读 $HOME/.zcode/cli/config.json）。 */
+declare const ZCODE_POOL_CONFIG_SUFFIX: readonly [".zcode", "cli", "config.json"];
+/**
+ * 池内 db.sqlite 相对隔离 HOME 的位置（handle.sessionRef.dbPath 的值——相对池目录
+ * 自描述，read 时经 resolvePoolDir + 该相对路径重定位，设计 §3.3.6）。
+ */
+declare const ZCODE_POOL_DB_RELATIVE_PATH = ".zcode/cli/db/db.sqlite";
+/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
+declare const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
+/** 杀链 grace 窗口：SIGTERM 后等这么久再 SIGKILL（zsub 同构 5s；实测 SIGTERM→exit 仅 103ms）。 */
+declare const ZCODE_KILL_GRACE_MS = 5000;
+/** 错误信息里保留的 stdout 尾部长度（engine_run_failed 规格：够诊断、不刷屏）。 */
+declare const ZCODE_ERROR_TAIL_CHARS = 2000;
+
+export { ZCODE_ADAPTER_VERSION, ZCODE_CLI_DEFAULT_PATH, ZCODE_ENGINE_ID, ZCODE_ERROR_TAIL_CHARS, ZCODE_FALLBACK_DEFAULT_MODEL, ZCODE_KILL_GRACE_MS, ZCODE_POOL_CONFIG_SUFFIX, ZCODE_POOL_DB_RELATIVE_PATH, ZCODE_V2_CONFIG_PATH_SUFFIX };

package/dist/execution/engine/engines/zcode/constants.js

@@ -0,0 +1,22 @@
+import {
+  ZCODE_ADAPTER_VERSION,
+  ZCODE_CLI_DEFAULT_PATH,
+  ZCODE_ENGINE_ID,
+  ZCODE_ERROR_TAIL_CHARS,
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+  ZCODE_KILL_GRACE_MS,
+  ZCODE_POOL_CONFIG_SUFFIX,
+  ZCODE_POOL_DB_RELATIVE_PATH,
+  ZCODE_V2_CONFIG_PATH_SUFFIX
+} from "../../../../chunk-3VOERJPJ.js";
+export {
+  ZCODE_ADAPTER_VERSION,
+  ZCODE_CLI_DEFAULT_PATH,
+  ZCODE_ENGINE_ID,
+  ZCODE_ERROR_TAIL_CHARS,
+  ZCODE_FALLBACK_DEFAULT_MODEL,
+  ZCODE_KILL_GRACE_MS,
+  ZCODE_POOL_CONFIG_SUFFIX,
+  ZCODE_POOL_DB_RELATIVE_PATH,
+  ZCODE_V2_CONFIG_PATH_SUFFIX
+};

package/dist/execution/engine/engines/zcode/reader.cjs

@@ -0,0 +1,276 @@
+"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/execution/engine/engines/zcode/reader.ts
+var reader_exports = {};
+__export(reader_exports, {
+  ZcodeReaderError: () => ZcodeReaderError,
+  readZcodeSessionView: () => readZcodeSessionView
+});
+module.exports = __toCommonJS(reader_exports);
+var fs = __toESM(require("fs"), 1);
+
+// src/execution/engine/engines/zcode/constants.ts
+var ZCODE_ENGINE_ID = "zcode";
+
+// src/execution/engine/engines/zcode/reader.ts
+var ZcodeReaderError = class extends Error {
+  code;
+  /** 原始失败细节（缺文件/表漂移/运行时不支持）。 */
+  detail;
+  constructor(detail, hint) {
+    super(
+      `[engine_session_read_failed] zcode \u539F\u751F session \u8BFB\u53D6\u5931\u8D25\uFF1A${detail}\u3002` + (hint ?? "\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u6216\u7B2C\u2462\u7EA7\uFF08outcome-only\uFF09\u3002")
+    );
+    this.name = "ZcodeReaderError";
+    this.code = "engine_session_read_failed";
+    this.detail = detail;
+  }
+};
+function parseJsonField(raw, ctx) {
+  try {
+    const v = JSON.parse(raw);
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? v : void 0;
+  } catch (err) {
+    throw new ZcodeReaderError(
+      `${ctx} \u884C data \u4E0D\u662F\u5408\u6CD5 JSON\uFF08${err instanceof Error ? err.message : String(err)}\uFF09`,
+      "db \u5185\u5BB9\u635F\u574F\u6216\u7248\u672C\u4E0D\u517C\u5BB9\u2014\u2014\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u3002"
+    );
+  }
+}
+function finiteOr(v, fallback) {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function usageFromStepFinish(part) {
+  const tokens = part.tokens;
+  if (typeof tokens !== "object" || tokens === null) return void 0;
+  const t = tokens;
+  const cache = typeof t.cache === "object" && t.cache !== null ? t.cache : {};
+  if (t.input === void 0 && t.output === void 0) return void 0;
+  return {
+    input: finiteOr(t.input, 0),
+    output: finiteOr(t.output, 0),
+    cacheRead: finiteOr(cache.read, 0),
+    cacheWrite: finiteOr(cache.write, 0)
+  };
+}
+function toolFromPart(part) {
+  const toolName = typeof part.tool === "string" ? part.tool : "unknown";
+  let state;
+  if (typeof part.state === "string") {
+    try {
+      const v = JSON.parse(part.state);
+      state = typeof v === "object" && v !== null ? v : void 0;
+    } catch {
+      state = void 0;
+    }
+  }
+  const status = typeof state?.status === "string" ? state.status : "unknown";
+  const output = state?.output;
+  return {
+    toolName,
+    ...state?.input !== void 0 ? { args: state.input } : {},
+    // 输出形态（实测）：string（内容）或 object（结构化）——分别映射到 pi ToolCallResult
+    // 的 content[] / details，不发明第二形状
+    ...typeof output === "string" ? { result: { content: [output] } } : {},
+    ...typeof output === "object" && output !== null ? { result: { details: output } } : {},
+    ...status !== "completed" ? { isError: true } : {}
+  };
+}
+var TotalsAcc = class {
+  input = 0;
+  output = 0;
+  cacheRead = 0;
+  cacheWrite = 0;
+  cost = 0;
+  has = false;
+  add(u) {
+    this.has = true;
+    this.input += u.input;
+    this.output += u.output;
+    this.cacheRead += u.cacheRead;
+    this.cacheWrite += u.cacheWrite;
+    this.cost += u.cost ?? 0;
+  }
+  toTotal() {
+    if (!this.has) return void 0;
+    return {
+      input: this.input,
+      output: this.output,
+      cacheRead: this.cacheRead,
+      cacheWrite: this.cacheWrite,
+      cost: this.cost,
+      total: this.input + this.output + this.cacheRead + this.cacheWrite
+    };
+  }
+};
+function closeTurn(acc, turns, totals) {
+  if (acc === null) return;
+  turns.push({ text: acc.text, thinking: acc.thinking, toolCalls: acc.toolCalls, closed: true });
+  if (acc.usageDelta !== void 0) totals.add(acc.usageDelta);
+}
+function rowToMessageRow(v) {
+  if (typeof v === "object" && v !== null && "id" in v && "data" in v) {
+    const r = v;
+    if (typeof r.id === "string" && typeof r.data === "string") return { id: r.id, data: r.data };
+  }
+  throw new ZcodeReaderError("message \u884C\u5F62\u72B6\u5F02\u5E38\uFF08id/data \u5217\u7F3A\u5931\u6216\u7C7B\u578B\u6F02\u79FB\uFF09");
+}
+function rowToPartRow(v) {
+  if (typeof v === "object" && v !== null && "data" in v) {
+    const r = v;
+    if (typeof r.data === "string") return { data: r.data };
+  }
+  throw new ZcodeReaderError("part \u884C\u5F62\u72B6\u5F02\u5E38\uFF08data \u5217\u7F3A\u5931\u6216\u7C7B\u578B\u6F02\u79FB\uFF09");
+}
+function resolveSessionId(db, sessionId) {
+  if (sessionId !== void 0) {
+    const hit = db.prepare("SELECT id FROM session WHERE id = ?").get(sessionId);
+    if (hit === void 0) {
+      throw new ZcodeReaderError(
+        `session \u4E0D\u5B58\u5728\uFF1A${sessionId}`,
+        "sessionId \u53EF\u80FD\u6765\u81EA\u5DF2\u6E05\u7406\u7684\u6C60\u2014\u2014\u964D\u7EA7\u5230 outcome-only\u3002"
+      );
+    }
+    return sessionId;
+  }
+  const latest = db.prepare("SELECT id FROM session ORDER BY time_created DESC LIMIT 1").get();
+  if (latest === void 0 || typeof latest.id !== "string") {
+    throw new ZcodeReaderError("db \u5185\u65E0\u4EFB\u4F55 session \u884C");
+  }
+  return latest.id;
+}
+function loadGroupedParts(db, sessionId) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const raw of db.prepare(
+    "SELECT part.message_id AS mid, part.data AS data FROM part JOIN message ON part.message_id = message.id WHERE part.session_id = ? ORDER BY message.sequence, part.sequence"
+  ).all(sessionId)) {
+    if (typeof raw !== "object" || raw === null || !("mid" in raw)) continue;
+    const mid = String(raw.mid);
+    const arr = grouped.get(mid) ?? [];
+    arr.push(rowToPartRow(raw));
+    grouped.set(mid, arr);
+  }
+  return grouped;
+}
+function appendPartText(current, part) {
+  return current === "" ? String(part.text ?? "") : current + "\n" + String(part.text ?? "");
+}
+function applyPartToTurn(part, acc, turns, totals) {
+  switch (part.type) {
+    case "text":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.text = appendPartText(acc.text, part);
+      return acc;
+    case "reasoning":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.thinking = appendPartText(acc.thinking, part);
+      return acc;
+    case "tool":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.toolCalls.push(toolFromPart(part));
+      return acc;
+    case "step-finish": {
+      const u = usageFromStepFinish(part);
+      const cost = finiteOr(part.cost, 0);
+      if (acc === null) acc = { text: "", thinking: "", toolCalls: [] };
+      if (u !== void 0) acc.usageDelta = cost > 0 ? { ...u, cost } : u;
+      closeTurn(acc, turns, totals);
+      return null;
+    }
+    default:
+      return acc;
+  }
+}
+function collectTurns(messages, grouped, totals) {
+  const turns = [];
+  for (const msg of messages) {
+    const parsedMsg = parseJsonField(msg.data, "message");
+    if (parsedMsg?.role !== "assistant") continue;
+    let acc = null;
+    for (const partRow of grouped.get(msg.id) ?? []) {
+      const part = parseJsonField(partRow.data, "part");
+      if (part === void 0) continue;
+      acc = applyPartToTurn(part, acc, turns, totals);
+    }
+    closeTurn(acc, turns, totals);
+  }
+  return turns;
+}
+function buildView(db, sessionId) {
+  const messages = db.prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY sequence").all(sessionId).map(rowToMessageRow);
+  const totals = new TotalsAcc();
+  const turns = collectTurns(messages, loadGroupedParts(db, sessionId), totals);
+  const usageTotal = totals.toTotal();
+  return {
+    engineId: ZCODE_ENGINE_ID,
+    sessionId,
+    ...usageTotal !== void 0 ? { usage: usageTotal } : {},
+    turns,
+    source: "native"
+  };
+}
+async function readZcodeSessionView(dbPath, sessionId) {
+  if (!fs.existsSync(dbPath)) {
+    throw new ZcodeReaderError(`db \u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${dbPath}`);
+  }
+  const sqliteModuleId = "node:sqlite";
+  const sqliteMod = await import(sqliteModuleId).catch(() => void 0);
+  const DatabaseSyncCtor = sqliteMod?.DatabaseSync;
+  if (typeof DatabaseSyncCtor !== "function") {
+    throw new ZcodeReaderError(
+      "\u5F53\u524D node \u8FD0\u884C\u65F6\u4E0D\u652F\u6301 node:sqlite\uFF08\u9700 >=22.13\uFF09",
+      "\u5347\u7EA7 node \u6216\u6539\u7528\u7B2C\u2461\u7EA7\uFF08\u5BBF\u4E3B event journal\uFF09\u8BFB\u53D6\u3002"
+    );
+  }
+  const open = DatabaseSyncCtor;
+  let db;
+  try {
+    db = new open(dbPath, { readOnly: true });
+    return buildView(db, resolveSessionId(db, sessionId));
+  } catch (err) {
+    if (err instanceof ZcodeReaderError) throw err;
+    throw new ZcodeReaderError(
+      `sqlite \u67E5\u8BE2\u5931\u8D25\uFF08${err instanceof Error ? err.message : String(err)}\uFF09`,
+      "\u7591\u4F3C\u8868\u7ED3\u6784\u6F02\u79FB\uFF08zcode schema_migration \u5347\u7EA7\uFF09\u2014\u2014\u8C03\u7528\u65B9\u5E94\u964D\u7EA7\u5230\u7B2C\u2461\u7EA7\uFF1B\u5E76\u628A\u65B0 schema \u6837\u672C\u8865\u5F55\u8FDB golden \u5E93\u540E\u66F4\u65B0 reader\u3002"
+    );
+  } finally {
+    try {
+      db?.close();
+    } catch (err) {
+      void err;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ZcodeReaderError,
+  readZcodeSessionView
+});

package/dist/execution/engine/engines/zcode/reader.d.cts

@@ -0,0 +1,20 @@
+import { S as SessionView } from '../../../../types-BxyAidGf.cjs';
+
+type ZcodeReaderErrorCode = "engine_session_read_failed";
+declare class ZcodeReaderError extends Error {
+    readonly code: ZcodeReaderErrorCode;
+    /** 原始失败细节（缺文件/表漂移/运行时不支持）。 */
+    readonly detail: string;
+    constructor(detail: string, hint?: string);
+}
+/**
+ * 读取 zcode session 的引擎中立视图（read 第①级）。
+ *
+ * @param dbPath    db.sqlite 绝对路径（引擎 read() 由 handle 解析后传入）
+ * @param sessionId 目标 session；缺省取池内最新（time_created DESC 首行）
+ * @throws ZcodeReaderError db 缺失/表漂移/node:sqlite 不可用/session 不存在——
+ *         结构化错误供调用方走降级链②③级
+ */
+declare function readZcodeSessionView(dbPath: string, sessionId?: string): Promise<SessionView>;
+
+export { ZcodeReaderError, type ZcodeReaderErrorCode, readZcodeSessionView };

package/dist/execution/engine/engines/zcode/reader.d.ts

@@ -0,0 +1,20 @@
+import { S as SessionView } from '../../../../types-BxyAidGf.js';
+
+type ZcodeReaderErrorCode = "engine_session_read_failed";
+declare class ZcodeReaderError extends Error {
+    readonly code: ZcodeReaderErrorCode;
+    /** 原始失败细节（缺文件/表漂移/运行时不支持）。 */
+    readonly detail: string;
+    constructor(detail: string, hint?: string);
+}
+/**
+ * 读取 zcode session 的引擎中立视图（read 第①级）。
+ *
+ * @param dbPath    db.sqlite 绝对路径（引擎 read() 由 handle 解析后传入）
+ * @param sessionId 目标 session；缺省取池内最新（time_created DESC 首行）
+ * @throws ZcodeReaderError db 缺失/表漂移/node:sqlite 不可用/session 不存在——
+ *         结构化错误供调用方走降级链②③级
+ */
+declare function readZcodeSessionView(dbPath: string, sessionId?: string): Promise<SessionView>;
+
+export { ZcodeReaderError, type ZcodeReaderErrorCode, readZcodeSessionView };