@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/contract-types-sSlgppBC.d.ts

@@ -0,0 +1,352 @@
+/**
+ * 双向可赋值断言：`type _A = AssertMutuallyAssignable<CoreX, SdkX>` 结果必须为 true。
+ * 任一方向不可赋值（字段缺失 / 可选性漂移 / 联合分支不齐）结果为 never → 编译失败。
+ * 用法（core 侧 W2 挂靠）：
+ *   import type { AssertMutuallyAssignable } from "@zhushanwen/subagent-engine-sdk";
+ *   type _CoreSdkAgentEvent = AssertMutuallyAssignable<CoreAgentEvent, SdkAgentEvent>;
+ *   const _assert: _CoreSdkAgentEvent = true;
+ */
+type AssertMutuallyAssignable<A, B> = [A] extends [B] ? [B] extends [A] ? true : never : never;
+/** token 用量（message_end 单条消息增量）。← core execution/types.ts AgentUsage。 */
+interface AgentUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 本 message 的成本（USD）。无成本数据时缺省。 */
+    cost?: number;
+}
+interface AgentUsageTotal extends AgentUsage {
+    /** 四项之和。投影时不再手工求和。 */
+    total: number;
+    /** 累计成本（USD）。无成本数据时为 0。 */
+    cost: number;
+}
+/** tool 调用结果（tool_end 携带，含 structured-output 的 details）。 */
+interface ToolCallResult {
+    content?: unknown[];
+    details?: unknown;
+}
+/** tool 调用（导出的纯净数据形状，不含内部状态机）。 */
+interface ToolCall {
+    toolName: string;
+    args?: unknown;
+    result?: ToolCallResult;
+    isError?: boolean;
+}
+/** 内部 ToolCall：追加 _status 进行中标记与 startedTs（reducer 内部态，跨边界导出前 strip）。 */
+interface InternalToolCall extends ToolCall {
+    _status: "running" | "done" | "failed";
+    /** tool_start 到达时的墙钟时间戳（Date.now()，ms）。 */
+    startedTs: number;
+}
+/** 一个 turn 的完整内容（reducer turns[] 的元素）。 */
+interface Turn {
+    /** 本 turn assistant 正文（text_delta 流式累积，完整）。 */
+    text: string;
+    /** 本 turn 推理（thinking_delta 流式累积，完整）。 */
+    thinking: string;
+    /** 本 turn 工具调用（InternalToolCall：含完整 result + _status 进行中标记）。 */
+    toolCalls: InternalToolCall[];
+    /** 本 turn message_end 的 token 增量（聚合得 usage 总量）。 */
+    usageDelta?: AgentUsage;
+    /** turn_end 是否已到达。false=正在进行；true=已闭合。 */
+    closed: boolean;
+    /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。 */
+    closedTs?: number;
+}
+/**
+ * 引擎事件（8 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
+ * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ */
+type AgentEvent = {
+    type: "tool_start";
+    toolName: string;
+    args?: unknown;
+} | {
+    type: "tool_end";
+    toolName: string;
+    args?: unknown;
+    result?: ToolCallResult;
+    isError?: boolean;
+} | {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "thinking_delta";
+    delta: string;
+} | {
+    type: "turn_end";
+    summary?: string;
+} | {
+    type: "message_end";
+    usage?: AgentUsage;
+    error?: string;
+} | {
+    type: "compaction";
+} | {
+    type: "error";
+    message: string;
+};
+/**
+ * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / interact / read 的
+ * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
+ */
+interface EngineHandleData {
+    v: 1;
+    /** 引擎 id（'pi' | 'zcode' | ...）。 */
+    engineId: string;
+    /** 引擎自定义定位键值。pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }。 */
+    sessionRef: Record<string, string>;
+    /** 隔离池定位。pi 无池化恒 'shared'。 */
+    poolKey: string;
+    /** journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。 */
+    journalPath?: string;
+    /** probe 实测版本（漂移排查锚点）。 */
+    engineVersion?: string;
+    /** 适配器版本（golden 样本对齐排查）。 */
+    adapterVersion: string;
+}
+/**
+ * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
+ * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。两处消费：
+ *   - run.params.chat.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
+ *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）；
+ *   - host/roundLifecycle 载荷 anchor（引擎 → 宿主：轮次终态时回填当前锚点，
+ *     宿主据此刷新冷续依据——pi 定位键形态同 EngineHandleData.sessionRef 注释）。
+ * 类型层与 EngineHandleData 定位形态的对照由测试断言（Pick 可赋值闭包）锁定。
+ */
+interface ResumeAnchor {
+    /** 引擎定位键（pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }）。 */
+    sessionRef: Record<string, string>;
+    /** 隔离池定位（锚点补全 handle 重建所需；pi 无池化恒 'shared'）。 */
+    poolKey: string;
+    /** journal 绝对路径（read 降级链第②级数据源；无 journal 缺省）。 */
+    journalPath?: string;
+}
+/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义）。 */
+interface ReplayedTurn {
+    text: string;
+    thinking: string;
+    /** 导出的纯净形状（ToolCall，无 _status/startedTs）。 */
+    toolCalls: ToolCall[];
+    closed: true;
+}
+/**
+ * session 历史的引擎中立视图（协议 read 应答）。降级链三级：①引擎原生读取 →
+ * ②宿主 event journal 重放 → ③outcome-only。source 字段是 GUI 降级标记数据源。
+ */
+interface SessionView {
+    engineId: string;
+    sessionId?: string;
+    /** turns[] 派生数据（重放/重建产物）。 */
+    turns: ReplayedTurn[];
+    /** 各 turn usageDelta 聚合。 */
+    usage?: AgentUsageTotal;
+    source: "native" | "journal" | "outcome-only";
+}
+/**
+ * 引擎能力声明（11 位）。三级：native / emulated / unsupported。
+ * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
+ * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
+ */
+interface EngineCapabilities {
+    /** native: --json-schema/--output-schema/env 注入。 */
+    schemaEnforcement: "native" | "emulated";
+    /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
+    steer: "native" | "emulated" | "unsupported";
+    /** interact 控制面（message/close/cancel + idle）。 */
+    conversation: "native" | "unsupported";
+    /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
+    personaInjection: "file" | "flag" | "prompt";
+    /** 粗粒度引擎：GUI 显示降级为阶段态。 */
+    eventGranularity: "stream" | "coarse";
+    /** emulated = worktree 隔离（无 OS sandbox 的引擎用文件写维度隔离补齐）。 */
+    sandbox: "native" | "emulated" | "none";
+    /** 重建历史的能力（read 降级链第①级保真度上限）。 */
+    sessionRead: "full" | "partial" | "outcome-only";
+    resume: "native" | "cold" | "unsupported";
+    /** 优雅中断 or 只能杀进程（公共杀链兜底）。 */
+    interrupt: "native" | "kill-only";
+    /** kimi headless 固定 auto = ignored；GUI 据此隐藏/提示。 */
+    permissionMode: "native" | "fixed" | "ignored";
+    /** maxTurns 轮数上限执行能力位（pi=true / zcode=false）。 */
+    maxTurns: boolean;
+}
+/** 引擎探针报告（probe 应答）。ok=false 时 error 必填（恢复指引）。 */
+interface ProbeReport {
+    ok: boolean;
+    /** 实测版本（探测不到时为空串）。 */
+    engineVersion: string;
+    /** 二进制存在/版本解析/干跑回归逐项。 */
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail?: string;
+    }>;
+    /** engine_probe_failed 的恢复指引（ok=false 时必填）。 */
+    error?: {
+        code: string;
+        recovery: string;
+    };
+}
+/**
+ * interact 的 action（交互控制面）。interrupt: true = steer（抢占）/ false|缺省 =
+ * followUp（排队）；不支持抢占的引擎忽略。
+ */
+type InteractAction = {
+    kind: "message";
+    payload: string;
+    interrupt?: boolean;
+} | {
+    kind: "close";
+    payload?: {
+        force: boolean;
+    };
+} | {
+    kind: "cancel";
+};
+/** interact 的结果（失败码 = engine_session_not_resumable / engine_capability_unsupported 等）。 */
+type InteractResult = {
+    ok: true;
+    delivered: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** 失败分诊结构化标签。unknown（含缺省）= 可重试（语义守恒）。 */
+type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+/**
+ * AgentOutcome.usage 字段型（← core orchestration/models/types.ts AgentUsage 结构等价；
+ * SDK 改名消歧——core 的两个同名 AgentUsage 分属 execution 与 orchestration 域）。
+ */
+interface AgentOutcomeUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    contextTokens: number;
+    turns: number;
+}
+/** 单次 tool 调用记录（workflow trace 形态）。 */
+interface ToolCallEntry {
+    /** Tool name. */
+    name: string;
+    /** Args preview string. */
+    input: string;
+}
+/** worktree 句柄（结构等价副本；core 权威定义在 execution/types.ts:349）。 */
+interface WorktreeHandle {
+    /** checkout 目录（子 agent 工作目录）。 */
+    readonly path: string;
+    readonly branch: string;
+    readonly baseCommit: string;
+    /** 主仓库根目录（cleanup/scan 需要）。 */
+    readonly mainCwd: string;
+}
+/**
+ * 一次引擎执行的终态（协议 run 终态应答的 outcome 载荷）。锚定 core
+ * orchestration AgentResult 并追加引擎层字段（engineId / engineFallback / exitCode）。
+ */
+interface AgentOutcome {
+    content: string;
+    /** 失败分诊标签。产出侧 = 引擎；缺省 = unknown = 可重试。 */
+    failureKind?: AgentFailureKind;
+    /** native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：native 路径宿主不做二次校验）。 */
+    parsedOutput?: unknown;
+    usage?: AgentOutcomeUsage;
+    durationMs?: number;
+    /** 错误码前缀格式（`<code>: <detail>`，错误规格见协议 error-codes）。 */
+    error?: string;
+    /** 引擎语义 session id。 */
+    sessionId?: string;
+    sessionFile?: string;
+    /** 仅诊断——目录可能已被 finalize 清理，不得作为 cwd 复用。 */
+    worktreePath?: string;
+    toolCalls?: ToolCallEntry[];
+    /** 实际执行引擎（fallback 后可能 ≠ 请求值）。 */
+    engineId: string;
+    /** fallback 留痕（record 同步投影，GUI 警告条数据源）。 */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+    /** null = 被信号杀死（杀链/abort 合成终态的判据）。 */
+    exitCode?: number | null;
+}
+/**
+ * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
+ * 协议面 = initialize 应答 models? 与 listModels 应答 models 的元素型；
+ * manifest 解析与生成（gen:model-catalog）归 W4/W5 实装。
+ */
+interface ModelCatalogEntry {
+    id: string;
+    aliases?: string[];
+    canonicalRef?: string;
+}
+/**
+ * 单次 agent 调用的任务声明——引擎面子集（协议 run.params.task；core 全量
+ * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费面）。
+ *
+ * 字段裁决（对照 core orchestration/models/types.ts AgentCallOpts，2026-09-09）：
+ * - 入选 = 引擎消费面：任务语义（prompt/schema/thinkingLevel/skill/skillPath/agent/persona 注入）、
+ *   轮次预算（maxTurns/graceTurns/conversation/idleTimeoutMs）、隔离与权限（worktree/
+ *   fork/forkSource/denyTools/permissionMode）、诊断（description/scene）；
+ * - 排除并改挂 run.params.ctx（协议层已单列，task 内双写会分叉）：model（→ctx.model）、
+ *   schemaEnv（→ctx.schemaEnv）、cwd（→ctx.cwd）、engineFallback（→ctx.engineFallback）；
+ * - 排除（宿主侧消费，无引擎语义）：engine（路由决策已完成，收到的引擎即选中值）、
+ *   timeoutMs（宿主超时链 mergeTimeoutSignal → cancel 帧，非引擎参数）、returnMeta
+ *   （core 注释明确「dropped at the pi boundary」，非引擎消费）。
+ *
+ * W2 实装 EngineClient run 帧时以本类型为 params.task；core 侧全量 → 子集的方向性
+ * 收窄（多余字段宿主自持不透传）不构成类型漂移（断言方向见 contract-closure 测试样板）。
+ */
+interface AgentCallOpts {
+    /** The task prompt to send to the agent. */
+    prompt: string;
+    /** Optional JSON schema for structured output（引擎按 capabilities.schemaEnforcement 分流）。 */
+    schema?: Record<string, unknown>;
+    /** Thinking level override（"high" | "medium" | "low" 等引擎自解释词表）。 */
+    thinkingLevel?: string;
+    /** Scene name passed through for model-selection hints. */
+    scene?: string;
+    /** Turn 上限（turn limiter）。未传或 <=0 = 不限。 */
+    maxTurns?: number;
+    /** Turn limiter 宽限轮数：超 maxTurns 后允许继续的轮数。 */
+    graceTurns?: number;
+    /** Skill name to load（引擎解析为 SKILL.md 注入）。 */
+    skill?: string;
+    /** Resolved absolute path to the skill directory or SKILL.md file. */
+    skillPath?: string;
+    /** Human-readable description for logging and debugging（slug 源字段）。 */
+    description?: string;
+    /** Agent ref (absolute .md path)——身份解析锚点。 */
+    agent?: string;
+    /** System prompt injection CONTENT（非文件路径）。 */
+    appendSystemPrompt?: string[];
+    /** Inherit parent session context (fork mode)。与 worktree（文件隔离）独立。 */
+    fork?: boolean;
+    /**
+     * [v1.x 增量] fork-from 显式分叉源 session 文件绝对路径（断联 subagent 接续场景，
+     * 宿主点名任意已有 session 文件；fork=true 则由引擎用主 session 作源，两者互斥——
+     * 本字段存在时优先）。字段名对齐引擎侧既有 SpawnRunParams.forkSource（pi 引擎经
+     * `--fork <path>` 消费）。可选增量、负向兼容：无此概念的引擎（zcode）按未知可选
+     * 字段忽略，行为与不传一致；宿主能力门（capability-gate）仍按 steer/conversation
+     * 通道族预检，不依赖引擎对本字段的支持声明。
+     */
+    forkSource?: string;
+    /** Filesystem isolation: 新建 worktree | 复用外部已创建 worktree | 不隔离。 */
+    worktree?: boolean | WorktreeHandle;
+    /** 可持续对话模式：true = 轮次完成进 idle 态等待 message 续聊。 */
+    conversation?: boolean;
+    /** 空闲超时毫秒数（仅 conversation 模式有意义）。显式 0/负 = 禁用 idle GC。 */
+    idleTimeoutMs?: number;
+    /** 工具 denylist（各引擎做语法映射）。 */
+    denyTools?: string[];
+    /** 中立权限模式（映射按各引擎 capabilities.permissionMode）。 */
+    permissionMode?: string;
+}
+
+export type { AgentCallOpts as A, EngineCapabilities as E, InteractAction as I, ModelCatalogEntry as M, ProbeReport as P, ReplayedTurn as R, SessionView as S, ToolCall as T, WorktreeHandle as W, AgentEvent as a, AgentFailureKind as b, AgentOutcome as c, AgentOutcomeUsage as d, AgentUsage as e, AgentUsageTotal as f, AssertMutuallyAssignable as g, EngineHandleData as h, InteractResult as i, InternalToolCall as j, ResumeAnchor as k, ToolCallEntry as l, ToolCallResult as m, Turn as n };

package/dist/data-dir.cjs

@@ -0,0 +1,117 @@
+"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/data-dir.ts
+var data_dir_exports = {};
+__export(data_dir_exports, {
+  XYZ_DATA_DIR_ENV: () => XYZ_DATA_DIR_ENV,
+  resetDataDirWarnForTests: () => resetDataDirWarnForTests,
+  resolveEngineDataDir: () => resolveEngineDataDir
+});
+module.exports = __toCommonJS(data_dir_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/data-dir.ts
+var logger = getLogger("subagents");
+var XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+var WARNED_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.data-dir-warned");
+function getWarnedSlot() {
+  let slot = Reflect.get(globalThis, WARNED_SLOT_KEY);
+  if (!slot) {
+    slot = { current: false };
+    Reflect.set(globalThis, WARNED_SLOT_KEY, slot);
+  }
+  return slot;
+}
+function resetDataDirWarnForTests() {
+  getWarnedSlot().current = false;
+}
+function resolveEngineDataDir(env, opts = {}) {
+  const fromEnv = env[XYZ_DATA_DIR_ENV]?.trim();
+  if (fromEnv !== void 0 && fromEnv !== "") return fromEnv;
+  const fallback = opts.fallbackDataRoot?.trim();
+  if (fallback === void 0 || fallback === "") {
+    throw new Error(
+      `[subagent-engine-sdk] engine_not_found: ${XYZ_DATA_DIR_ENV} is not set and no fallback data root was injected. Recovery: the host must inject ${XYZ_DATA_DIR_ENV} into the engine process env (xyz-agent runtime / pi extension host do this at spawn), or pass { fallbackDataRoot } when calling resolveEngineDataDir from a host that resolves the data root itself.`
+    );
+  }
+  if (!getWarnedSlot().current) {
+    getWarnedSlot().current = true;
+    const warn = opts.warn ?? defaultWarn;
+    warn(
+      `[engine-data-dir] ${XYZ_DATA_DIR_ENV} is not set; engine journal/pool fall back to the injected data root (${fallback}). The xyz-agent host normally injects this env \u2014 if you are running inside xyz-agent, check the runtime spawn env; standalone installs intentionally use the injected root.`
+    );
+  }
+  return fallback;
+}
+function defaultWarn(msg) {
+  logger.warn(msg);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  XYZ_DATA_DIR_ENV,
+  resetDataDirWarnForTests,
+  resolveEngineDataDir
+});

package/dist/data-dir.d.cts

@@ -0,0 +1,20 @@
+/** xyz-agent 数据目录 env 名（与 packages/shared/src/paths.ts 的 SSOT 变量同名）。 */
+declare const XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+/** 测试隔离专用：重置 warn-once 标记（生产禁用）。 */
+declare function resetDataDirWarnForTests(): void;
+/**
+ * 解析引擎数据目录（journal 落盘 / 隔离池的根）：
+ *   1. env[XYZ_AGENT_DATA_DIR]（宿主注入，权威通道）；
+ *   2. 缺失 + opts.fallbackDataRoot 显式传入（宿主解析过的数据根）→ 用之 + warn 一次
+ *      （非权威通道回退必须可观测——journal 落点变化不留静默漂移）；
+ *   3. 两者皆缺 → 抛错（engine_not_found 语义：错误含 env 名、期望值示例与恢复动作；
+ *      impl-plan §2.9「缺 env 且无注入 → 显式报错（附期望路径）」）。
+ *
+ * 每次调用重新解析（env 读取是零成本操作，不缓存路径防测试/宿主切换时读到旧值）。
+ */
+declare function resolveEngineDataDir(env: NodeJS.ProcessEnv, opts?: {
+    fallbackDataRoot?: string;
+    warn?: (msg: string) => void;
+}): string;
+
+export { XYZ_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir };

package/dist/data-dir.d.ts

@@ -0,0 +1,20 @@
+/** xyz-agent 数据目录 env 名（与 packages/shared/src/paths.ts 的 SSOT 变量同名）。 */
+declare const XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+/** 测试隔离专用：重置 warn-once 标记（生产禁用）。 */
+declare function resetDataDirWarnForTests(): void;
+/**
+ * 解析引擎数据目录（journal 落盘 / 隔离池的根）：
+ *   1. env[XYZ_AGENT_DATA_DIR]（宿主注入，权威通道）；
+ *   2. 缺失 + opts.fallbackDataRoot 显式传入（宿主解析过的数据根）→ 用之 + warn 一次
+ *      （非权威通道回退必须可观测——journal 落点变化不留静默漂移）；
+ *   3. 两者皆缺 → 抛错（engine_not_found 语义：错误含 env 名、期望值示例与恢复动作；
+ *      impl-plan §2.9「缺 env 且无注入 → 显式报错（附期望路径）」）。
+ *
+ * 每次调用重新解析（env 读取是零成本操作，不缓存路径防测试/宿主切换时读到旧值）。
+ */
+declare function resolveEngineDataDir(env: NodeJS.ProcessEnv, opts?: {
+    fallbackDataRoot?: string;
+    warn?: (msg: string) => void;
+}): string;
+
+export { XYZ_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir };

package/dist/data-dir.js

@@ -0,0 +1,12 @@
+import {
+  XYZ_DATA_DIR_ENV,
+  resetDataDirWarnForTests,
+  resolveEngineDataDir
+} from "./chunk-GT6YLLN4.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  XYZ_DATA_DIR_ENV,
+  resetDataDirWarnForTests,
+  resolveEngineDataDir
+};