@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/engine/engines/zcode/constants.ts

@@ -1,176 +0,0 @@
-// src/execution/engine/engines/zcode/constants.ts
-//
-// ZcodeEngine 共享常量（P3）。独立成模块的原因：reader.ts 是双端复用的无状态模块
-// （设计 §3.3.7：runtime 侧也会 import），它需要的常量不能连带其他模块的模块级
-// 副作用（如 logger 初始化）一起加载——constants.ts 保持零 import 纯常量。
-//
-// 2026-09 重构（共享宿主 HOME）：删除 CLI spawn 降级链与 HOME 池化全部常量
-// （home-appserver 池/锁/pidfile/派生上限/凭据引导/probe 冒烟/漂移降级码）。
-// 引擎只走 app-server RPC，spawn env 不覆写 HOME（共享宿主 ~/.zcode/）。
-
-/** zcode 引擎的 registry key。 */
-export const ZCODE_ENGINE_ID = "zcode";
-
-/** zcode 适配器版本（handle.adapterVersion 数据源——golden 样本对齐排查锚点）。 */
-export const ZCODE_ADAPTER_VERSION = "2.0.0";
-
-/**
- * zcode CLI 缺省路径（12.4MB node bundle，不在 PATH——2026-08-25 实测）。
- * 组合根可用 deps.cliPath 覆盖（测试注入 / 未来安装形态变化）。
- */
-export 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 生产验证过的凭据源。共享宿主 HOME 后引擎侧只读它做模型解析校验；
- * app-server 进程侧 CLI 只认 ~/.zcode/cli/config.json（GUI 从不写该文件），由
- * appserver-launcher 的 fs 拦截 wrapper 把对该文件的读取重定向为「真实文件 +
- * v2 provider 注入」内存合并（同 id 时 v2 整条优先）——凭据实际供数仍以 v2 为
- * 权威源，并非直接消费宿主 HOME 的原始 cli config。
- */
-export const ZCODE_V2_CONFIG_PATH_SUFFIX = [".zcode", "v2", "config.json"] as const;
-
-/** zsub 同构的兜底缺省模型（v2 config 无 model.main 且 task 未指定时）。 */
-export const ZCODE_FALLBACK_DEFAULT_MODEL = "builtin:bigmodel-coding-plan/GLM-5.3";
-
-/**
- * 宿主 HOME 下 zcode 会话 db 的相对位置（共享 HOME 形态的 handle.sessionRef.dbPath
- * 锚点——绝对路径 = join(os.homedir(), ...suffix)；runtime 读侧用它做精确白名单，
- * 旧池时代 records 的相对 dbPath 仍按 poolKey 锚定兼容）。
- */
-export const ZCODE_HOST_DB_SUFFIX = [".zcode", "cli", "db", "db.sqlite"] as const;
-
-/** 杀链 grace 窗口：SIGTERM 后等这么久再 SIGKILL（zsub 同构 5s；实测 SIGTERM→exit 仅 103ms）。 */
-export const ZCODE_KILL_GRACE_MS = 5_000;
-
-/** 错误信息里保留的 stdout 尾部长度（engine_run_failed 规格：够诊断、不刷屏）。 */
-export const ZCODE_ERROR_TAIL_CHARS = 2000;
-
-/**
- * [R2] app-server 控制面请求默认超时（ms）。依据：旧 zsw 实现 REQUEST_TIMEOUT_MS=15s
- * （60+ fake-server 用例 + 真机 e2e 验证值）。
- */
-export const ZCODE_APPSERVER_REQUEST_TIMEOUT_MS = 15_000;
-
-/**
- * [R2] 连接崩溃错误信息附带的 stderr 尾部长度（字符）。设计 zcode-engine-appserver-
- * resident.md §3.1 失败路径 2 / §3.3 错误规格表「进程意外退出」行：stderr 尾 400 字符。
- */
-export const ZCODE_APPSERVER_STDERR_TAIL_CHARS = 400;
-
-/**
- * [R2] stderr 滚动缓冲上限（字符）：只保最近内容供崩溃诊断。旧 zsw 实现同值 2048。
- */
-export const ZCODE_APPSERVER_STDERR_TAIL_BUFFER_CHARS = 2048;
-
-/**
- * [R3] 终态判定后 session/read 兜底拉取的超时（ms）。read 是全文权威来源（不变量 1
- * 的双来源之二），失败不抛——降级收尾帧/delta 聚合。旧 zsw 实现 READ_TIMEOUT_MS=5000。
- */
-export const ZCODE_APPSERVER_TURN_READ_TIMEOUT_MS = 5_000;
-
-/**
- * [R3] 任务收尾 session/close 的控制面超时（ms，best-effort——失败只 warn 不抛）。
- * 旧 zsw 实现 RELEASE_CLOSE_TIMEOUT_MS=1500（wave2 D2，同值同语义）。
- */
-export const ZCODE_APPSERVER_TURN_CLOSE_TIMEOUT_MS = 1_500;
-
-/**
- * [R3 → superseded by P0-1] 旧「一轮终态等待」固定墙钟缺省值（ms）。**已被
- * `ZCODE_TURN_IDLE_TIMEOUT_MS`（idle 主判定）+ `ZCODE_TURN_MAX_TIMEOUT_MS`
- * （总上界兜底）两 timer 语义替换，session-channel 不再消费本值**——固定墙钟
- * 「到点=不可推进」判定被 2026-09 T001 深诊击穿（21% 活跃任务被误杀，见设计
- * timeout-zcode-turn-and-settled-watchdog.md §3.1/§4）。符号保留：audit/设计
- * 文档（timeout-audit-2026-09.md 等）以本名记录事故成因，删除即产生悬空引用。
- */
-export const ZCODE_APPSERVER_TURN_DEFAULT_TIMEOUT_MS = 300_000;
-
-// ============================================================
-// [P0-1 U1] turn 等待两 timer（idle 主判定 + 总上界回收兜底）
-// 设计权威源：docs/design/timeout-zcode-turn-and-settled-watchdog.md §6 D1/D2
-// ============================================================
-
-/** turn idle 主判定的 env 覆盖通道（>0 覆盖、≤0 关闭、非法值 warn+回落默认）。 */
-export const ZCODE_TURN_IDLE_TIMEOUT_ENV = "XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS";
-
-/** turn 总上界的 env 覆盖通道（语义同上；0=关闭后 chatty-wedge 无自动回收）。 */
-export const ZCODE_TURN_MAX_TIMEOUT_ENV = "XYZ_ZCODE_TURN_MAX_TIMEOUT_MS";
-
-/**
- * [P0-1 D1] turn idle 主判定缺省阈值（ms）：该 turn 任何事件到达刷新计时，连续
- * 静默达此值判「执行已不可推进」。活跃事件流零误杀（ADR-0047 逆否面）。默认
- * 30min 为先验值，⛔P-Z1 门（事件流 inter-event gap 分布）标定前用此默认。
- */
-export const ZCODE_TURN_IDLE_TIMEOUT_MS = 1_800_000;
-
-/**
- * [P0-1 D1] turn 总上界缺省值（ms）：从 openTurn 挂载起固定不刷新，兜 idle 覆盖
- * 不了的 chatty-wedge（事件持续但终态永不到达）。对超上界的合法极长任务是显式
- * 接受的残余误杀面（env 可调/可关 + 错误文案附自救指引）。默认 60min 为先验值
- * （T001 34 任务最长 541s，先验远离 6.6×），⛔P-Z0 门（任务总时长分布）标定前
- * 用此默认。
- */
-export const ZCODE_TURN_MAX_TIMEOUT_MS = 3_600_000;
-
-/** `parseZcodeTurnTimeoutEnv` 的解析结果（可判别联合——valid 分支 ms 必有）。 */
-export type ZcodeTurnTimeoutEnvParse =
-  | { state: "unset" }
-  | { state: "valid"; ms: number }
-  | { state: "invalid" };
-
-/**
- * 解析 turn 阈值 env 原始值（空串视同未设置，对齐 lifecycle-manager 先例的
- * `if (!raw)` 口径）。**与 `XYZ_SUBAGENT_IDLE_TIMEOUT_MS` 先例的刻意分歧（设计
- * D2/r3 SG-5 显式登记）**：先例 ≤0=非法回落且禁用后不认 env；本通道 ≤0=显式
- * 关闭该 timer（规则 19 的 opt-out 出路），非法（非数字）才回落默认——调用方
- * 必须对 invalid 与 ≤0 关闭分别 warn 留痕（生效行为可见，A10① 断言依据）。
- */
-export function parseZcodeTurnTimeoutEnv(
-  raw: string | undefined
-): ZcodeTurnTimeoutEnvParse {
-  if (raw === undefined || raw === "") return { state: "unset" };
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return { state: "invalid" };
-  return { state: "valid", ms: parsed };
-}
-
-/**
- * 共享宿主 HOME 语义下的 journal 分组 key（与 pi 引擎 PI_POOL_KEY='shared' 同构）：
- * journal 落 engineDataDir/engines/zcode/shared/journal-<taskId>.jsonl。无隔离池、
- * 无派生目录——key 是固定字面量，仅作 pool-manager 通用契约的分组锚点。
- */
-export const ZCODE_SHARED_POOL_KEY = "shared";
-
-/**
- * [R4 D3] abort 链第一级：session/stop 的控制面超时（ms）。stop 失败/超时即落
- * killChain（协议此时已不可信）。
- */
-export const ZCODE_APPSERVER_STOP_TIMEOUT_MS = 3_000;
-
-/**
- * [R4 D3] abort 链第二级：stop 送达后的终态确认 grace 窗口（ms）。窗口内终态
- * 到达 → 不杀共享进程；超时 → killChain 连坐。
- */
-export const ZCODE_APPSERVER_ABORT_GRACE_MS = 3_000;
-
-/**
- * [R4] app-server 内部错误码中「模型配置缺失」的归类判据（A.3：-32603 内部错误族，
- * 消息含 "Model config is missing"——错误规格表第 2 行：报 engine_credential_missing）。
- */
-export const ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING = -32603;
-
-/**
- * [R5] app-server 内部错误码「会话忙」：send 时该会话已有轮在跑（busy 不排队不打断）。
- * 单会话一任务是结构保证，运行中命中即 bug（错误文案引导上报 sessionId 与 state 流水）。
- */
-export const ZCODE_APPSERVER_ERR_BUSY_SESSION = -32010;
-
-/**
- * [R5] 崩溃收割确认的兜底窗口（ms）：killChain 在 `exit` 事件 resolve，而连接
- * finalize（onClose → 在途 turn 崩溃收割）挂 `close` 事件——channel 退订前等 onClose
- * 触发，本窗口兜底防 `close` 永不到达时 dispose 挂死。
- */
-export const ZCODE_APPSERVER_HARVEST_GRACE_MS = 1_000;

package/src/execution/engine/engines/zcode/golden-sample.ts

@@ -1,47 +0,0 @@
-// src/execution/engine/engines/zcode/golden-sample.ts
-//
-// golden 语料内嵌副本（2026-09 收缩：CLI spawn 链删除后只剩 app-server 通道语料——
-// spawn 单 JSON 样本（ZCODE_GOLDEN_STDOUT）随 probe 干跑/spawn 回归一并删除）：
-//
-//   app-server NDJSON 帧序列（R3，D8-②）：常驻通道的 golden 帧序列语料，四类样本
-//   （create 应答 / 推送流 / 终态帧 / read 应答，附录 A.2 任务生命周期帧序）。
-//   来源：按 A.2 协议权威 + 旧 zsw 实现真机抓包形态合成（非实录，fixture _meta
-//   如实标注）；真机冒烟后替换。fixture __tests__/__fixtures__/zcode-golden-appserver.json
-//   是采集 SSOT，此处为运行时副本，更新样本需同步改两处（session-channel 测试
-//   diff 校验）。
-
-// ============================================================
-// [②app-server] NDJSON 帧序列语料（R3，附录 A.2 帧序逐字）
-// ============================================================
-
-/** 四类样本的结构（与 zcode-golden-appserver.json 的 frames 字段一一对应）。 */
-export interface AppServerGoldenFrames {
-  /** ① session/create 应答帧（NDJSON 单行；projection.sessionId 恒 "unknown" 勿用）。 */
-  createResponse: string;
-  /** ④ 推送流帧（NDJSON 逐行：state.updated / stream.chunk 无文本 / session/event delta 有文本）。 */
-  pushStream: string[];
-  /** ⑤ 终态帧（NDJSON 逐行：v4 telemetry turn.terminal 权威 + session/event 收尾帧全文/usage）。 */
-  terminal: string[];
-  /** ⑥ session/read 应答帧（NDJSON 单行：messages[].parts[]，text 全文 + step-finish tokens）。 */
-  readResponse: string;
-}
-
-/** [②app-server] golden 帧序列内嵌副本（采集 SSOT = zcode-golden-appserver.json，双副本 diff 防漂移）。 */
-export const ZCODE_APPSERVER_GOLDEN: AppServerGoldenFrames = {
-  createResponse:
-    '{"session":{"sessionId":"sess_golden_r3_01"},"projection":{"sessionId":"unknown","status":"idle","turnCount":0,"totalTokenCount":0,"contextUsed":0,"contextWindow":1000000}}',
-  pushStream: [
-    '{"method":"state.updated","params":{"sessionId":"sess_golden_r3_01","patch":{"status":"running"},"reason":"prompt_started"}}',
-    '{"method":"v4/telemetry/event","params":{"kind":"stream.chunk","channel":"text","chunkLength":6,"firstChunk":true,"assistantMessageId":"msg_golden_r3_01"}}',
-    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"你好","assistantMessageId":"msg_golden_r3_01"}}}',
-    '{"method":"v4/telemetry/event","params":{"kind":"stream.chunk","channel":"text","chunkLength":1,"firstChunk":false,"assistantMessageId":"msg_golden_r3_01"}}',
-    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"，","assistantMessageId":"msg_golden_r3_01"}}}',
-    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"任务完成","assistantMessageId":"msg_golden_r3_01"}}}',
-  ],
-  terminal: [
-    '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"success"}}',
-    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"response":"你好，任务完成","usage":{"inputTokens":12599,"outputTokens":17}}}}',
-  ],
-  readResponse:
-    '{"messages":[{"info":{"role":"user"},"parts":[{"type":"text","text":"做点什么"}]},{"info":{"role":"assistant"},"parts":[{"type":"text","text":"你好"},{"type":"text","text":"，任务完成"},{"type":"step-finish","tokens":{"input":12599,"output":17,"reasoning":0,"cache":512,"total":12616}}]}]}',
-};

package/src/execution/engine/engines/zcode/parser.ts

@@ -1,102 +0,0 @@
-// src/execution/engine/engines/zcode/parser.ts
-//
-// ZcodeEngine usage 映射与 coarse 事件件（2026-09 收缩）：CLI stdout 有界收集/
-// 终 JSON 解析/buildRunFailedMessage 随 spawn 链删除（app-server 路径的终态来自
-// session-channel 的 read 兜底帧，不经 stdout 解析）。保留件：
-//   - ZcodeRawUsage / mapZcodeUsage / mapZcodeOutcomeUsage：原生 usage 形状 →
-//     事件层（execution）与终态层（orchestration）AgentUsage（spawn 时代实测形状，
-//     app-server 收尾帧 usage 同形——session-channel 消费）；
-//   - ZcodeTerminalPayload：app-server 轮成功态的载荷形态（turnResultToPayload 组装）；
-//   - synthesizeCoarseEvents：终态合成最小事件序列（不变量：turn_end 最后、其前
-//     至少一个 message_end）。
-//
-// 事件产出不变量（设计 §3.3.7，coarse 口径）：turn_end 前至少一个 message_end；
-// message_end.usage 出现时为完整 AgentUsage 形状（缺数据给显式 0，不给残缺对象）。
-
-import type { AgentUsage as ExecutionAgentUsage } from "../../../types.ts";
-import type { AgentUsage as OutcomeAgentUsage } from "../../../../orchestration/models/types.ts";
-import type { AgentEvent } from "../../types.ts";
-
-// ============================================================
-// usage 映射（含运行时 guard——禁 any）
-// ============================================================
-
-/** 原生 usage 形状（2026-08-25 实测 0.16.5，字段名带 Tokens 后缀；app-server 收尾帧同形）。 */
-export interface ZcodeRawUsage {
-  source?: unknown;
-  modelRequestCount?: unknown;
-  inputTokens?: unknown;
-  outputTokens?: unknown;
-  totalTokens?: unknown;
-  cacheReadTokens?: unknown;
-  cacheWriteTokens?: unknown;
-  reasoningTokens?: unknown;
-}
-
-function finiteOr(v: unknown, fallback: number): number {
-  const n = typeof v === "number" ? v : Number(v);
-  return Number.isFinite(n) ? n : fallback;
-}
-
-/** 原生 usage → 事件层 AgentUsage（execution 版：四项 token；cost 无来源缺省）。 */
-export function mapZcodeUsage(raw: unknown): ExecutionAgentUsage | undefined {
-  if (typeof raw !== "object" || raw === null) return undefined;
-  const r = raw as ZcodeRawUsage;
-  if (r.inputTokens === undefined && r.outputTokens === undefined) return undefined;
-  return {
-    input: finiteOr(r.inputTokens, 0),
-    output: finiteOr(r.outputTokens, 0),
-    cacheRead: finiteOr(r.cacheReadTokens, 0),
-    cacheWrite: finiteOr(r.cacheWriteTokens, 0),
-  };
-}
-
-/**
- * 原生 usage + projection → 终态层 AgentUsage（orchestration 版：cost/contextTokens/
- * turns 为必填）。zcode 不回传 cost（调研附录 A「cost 回传 ❌」）——显式 0（消费方按
- * 「显示降级」处理，不给残缺）；contextTokens 取 projection.contextUsed（当前上下文
- * 占用），turns 取 projection.turnCount。
- */
-export function mapZcodeOutcomeUsage(rawUsage: unknown, projection: unknown): OutcomeAgentUsage | undefined {
-  const base = mapZcodeUsage(rawUsage);
-  if (base === undefined) return undefined;
-  const p =
-    typeof projection === "object" && projection !== null ? (projection as Record<string, unknown>) : {};
-  const r = typeof rawUsage === "object" && rawUsage !== null ? (rawUsage as ZcodeRawUsage) : {};
-  const contextTokens = firstFinite(p["contextUsed"], r.totalTokens, 0);
-  const turns = firstFinite(p["turnCount"], 1);
-  return { ...base, cost: 0, contextTokens, turns };
-}
-
-function firstFinite(...vals: unknown[]): number {
-  for (const v of vals) {
-    const n = typeof v === "number" ? v : Number(v);
-    if (Number.isFinite(n)) return n;
-  }
-  return 0;
-}
-
-/** 轮成功态的载荷形态（app-server 路径由 turnResultToPayload 组装：response 必 string）。 */
-export interface ZcodeTerminalPayload {
-  sessionId?: string;
-  response: string;
-  /** 事件层 usage（execution 版 AgentUsage——message_end 合成用）。 */
-  usage?: ExecutionAgentUsage;
-  /** 终态层 usage（orchestration 版 AgentUsage——AgentOutcome.usage 用）。 */
-  outcomeUsage?: OutcomeAgentUsage;
-  /** projection.turnCount（gui/record 的轮数参考；解析不出则缺省）。 */
-  turnCount?: number;
-}
-
-// ============================================================
-// coarse 事件合成（不变量：turn_end 最后、其前至少一个 message_end）
-// ============================================================
-
-/** 终态成功时合成的最小事件序列（coarse 引擎只有终态级信息——设计 D3 eventGranularity）。 */
-export function synthesizeCoarseEvents(response: string, usage?: ExecutionAgentUsage): AgentEvent[] {
-  return [
-    // usage 给不出完整形状时显式缺省整个字段，不给残缺对象（不变量 2）
-    { type: "message_end", ...(usage !== undefined ? { usage } : {}) },
-    { type: "turn_end" },
-  ] as AgentEvent[];
-}

package/src/execution/engine/engines/zcode/preparer.ts

@@ -1,235 +0,0 @@
-// src/execution/engine/engines/zcode/preparer.ts
-//
-// ZcodeEngine prepare 期模型解析件（P3 起源，2026-09 收缩）：隔离 HOME 池化与
-// 池内 config 引导随 CLI spawn 链删除（共享宿主 HOME——app-server 的凭据经
-// appserver-launcher fs 拦截注入 v2 provider，本文件只剩 v2 单源的模型引用
-// 解析/校验/清单：
-//   - **凭据源 = v2 config 单源（2026-08-25 用户拍板）**：只读 `~/.zcode/v2/config.json`
-//     （ZCode 桌面登录态落点，GUI 管理面）。曾泛化过「v2 + cli config 双源合并」，
-//     但 `~/.zcode/cli/config.json` 不在 GUI 管理面、可能残留历史验证配置
-//     （8/24 zsub 开发残留把默认模型劫持到失效 router 端点的 401 事故），撤掉依赖；
-//   - 凭据缺失/模型不可解析抛结构化 ZcodePrepareError（错误码对齐设计 §3.3.3：
-//     engine_credential_missing / model_not_available），一律先于进程创建。
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { ZCODE_FALLBACK_DEFAULT_MODEL, ZCODE_V2_CONFIG_PATH_SUFFIX } from "./constants.ts";
-
-// ============================================================
-// 结构化错误（prepare 期——进程创建前 reject 的载体）
-// ============================================================
-
-export type ZcodePrepareErrorCode =
-  | "engine_credential_missing"
-  | "model_not_available"
-  | "engine_capability_unsupported";
-
-/** prepare 期错误：code 对齐设计 §3.3.3 错误规格表，message 自带恢复指引。 */
-export class ZcodePrepareError extends Error {
-  readonly code: ZcodePrepareErrorCode;
-
-  constructor(code: ZcodePrepareErrorCode, message: string) {
-    super(`[${code}] ${message}`);
-    this.name = "ZcodePrepareError";
-    this.code = code;
-  }
-}
-
-// ============================================================
-// 源 config 读取（运行时 guard，禁 any）
-// ============================================================
-
-/** provider 注册表条目的最小消费面（凭据 + 模型清单校验）。 */
-export interface ZcodeProviderEntry {
-  options?: { apiKey?: unknown };
-  models?: Record<string, unknown>;
-  [k: string]: unknown;
-}
-
-interface SourceConfig {
-  /** provider 注册表（来自 v2 config，逐条运行时 guard）。 */
-  providers: Map<string, ZcodeProviderEntry>;
-}
-
-/** unknown 的 Record 窄化 guard（替代 as 全可选断言——taste/no-unsafe-cast）。 */
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/** provider 条目一律按 ZcodeProviderEntry 消费（索引签名形态，无需逐键校验）。 */
-function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
-  return isRecord(v);
-}
-
-function readSourceConfig(absPath: string): SourceConfig {
-  const empty: SourceConfig = { providers: new Map() };
-  let raw: string;
-  try {
-    raw = fs.readFileSync(absPath, "utf8");
-  } catch {
-    return empty;
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return empty;
-  }
-  if (!isRecord(parsed)) return empty;
-  const conf: SourceConfig = { providers: new Map() };
-  const provider = parsed["provider"];
-  if (isRecord(provider)) {
-    for (const [id, entry] of Object.entries(provider)) {
-      if (isProviderEntry(entry)) conf.providers.set(id, entry);
-    }
-  }
-  return conf;
-}
-
-// ============================================================
-// 模型解析（v2 单源，zsub resolve 同构）
-// ============================================================
-
-function modelShort(ref: string): string {
-  return ref.slice(ref.lastIndexOf("/") + 1);
-}
-
-function providerOf(ref: string): string {
-  return ref.slice(0, ref.lastIndexOf("/"));
-}
-
-/** [R4] 规范化全名 provider/model → create 参数的 per-session model 拆分（A.2 ① strict 对象）。 */
-export function splitZcodeModelRef(modelRef: string): { providerId: string; modelId: string } {
-  return { providerId: providerOf(modelRef), modelId: modelShort(modelRef) };
-}
-
-export function hasApiKey(entry: ZcodeProviderEntry): boolean {
-  const key = entry.options?.apiKey;
-  return typeof key === "string" && key !== "";
-}
-
-export interface ZcodeSourcePaths {
-  /** 桌面登录态 config（唯一凭据源）。缺省 ~/.zcode/v2/config.json。 */
-  v2ConfigPath?: string;
-}
-
-export function defaultV2ConfigPath(): string {
-  return path.join(os.homedir(), ...ZCODE_V2_CONFIG_PATH_SUFFIX);
-}
-
-/**
- * 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。
- * 导出（sink 设计 U1 模型切分四件之一）：barrel re-export 供第三宿主模型路由消费，
- * 实现体内聚本文件不挪。
- */
-export const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
-
-/**
- * 短名模型（如 "GLM-5.3"）的默认 provider 决策。让位条件（对齐点⑦）：显式默认引擎
- * 模型配置引入时（config.json 出现 per-engine model 映射 / engineRouting 级模型缺省），
- * 本函数的「内置常量优先」须让位为「配置值优先」——引擎路由层（engine/routing.ts 的
- * taskModel 判定处）是引入该配置时应同步调整的决策点，避免出现「路由按配置模型选了
- * 引擎、prepare 却按内置常量落池」的分裂。首期无该配置，常量即权威。
- */
-function defaultProviderForShortName(
-  merged: Map<string, ZcodeProviderEntry>,
-  withKey: Array<[string, ZcodeProviderEntry]>,
-): string {
-  if (merged.has(DEFAULT_PROVIDER_ID)) return DEFAULT_PROVIDER_ID;
-  return withKey[0]![0];
-}
-
-/**
- * 解析并校验模型引用 → 规范化全名 `provider/model`。
- *
- * 解析链（requested > 默认链）：
- *   1. 显式 requested（task.model）；
- *   2. ZCODE_FALLBACK_DEFAULT_MODEL（zsub 同构兜底）。
- *
- * 校验对「带 apiKey 的 provider 注册表」做（没配凭据的 provider 写进池也跑不起来，
- * resolve 期报错比运行时挂掉可诊断——zsub 经验）。provider 存在但无 apiKey →
- * engine_credential_missing；provider/模型不存在 → model_not_available（列可用清单）。
- */
-export function resolveZcodeModelRef(requested: string | undefined, sources?: ZcodeSourcePaths): string {
-  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
-  const merged = v2.providers;
-  const withKey = [...merged.entries()].filter(([, e]) => hasApiKey(e));
-  const wanted = requested?.trim() || undefined;
-  const target = wanted ?? ZCODE_FALLBACK_DEFAULT_MODEL;
-
-  if (withKey.length === 0) {
-    const hint = wanted
-      ? `model="${wanted}" 不能校验`
-      : `默认模型 "${target}" 不能校验`;
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `zcode 引擎找不到任何带 apiKey 的 provider（${hint}）。已读源：${sources?.v2ConfigPath ?? defaultV2ConfigPath()}。` +
-        `恢复指引：先在 ZCode 桌面端登录并配置 provider（v2 config 内存在含 apiKey 的条目）后重试；` +
-        `凭据配置说明见 docs/research/agent-engine-zcode.md。`,
-    );
-  }
-
-  const provider = target.includes("/")
-    ? providerOf(target)
-    : defaultProviderForShortName(merged, withKey);
-  const short = modelShort(target);
-  const entry = merged.get(provider);
-  if (!entry) {
-    const known = withKey.map(([id]) => id).join(", ");
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知 provider "${provider}"（带凭据的 provider: ${known}）。` +
-        `恢复指引：改用上述 provider 之一（全名 provider/model），或先在 ZCode 桌面端配置该 provider 后重试。`,
-    );
-  }
-  if (!hasApiKey(entry)) {
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `provider "${provider}" 存在但未配置 apiKey。` +
-        `恢复指引：在 ZCode 桌面端为该 provider 登录配置凭据，或改用已配凭据的 provider（${withKey.map(([id]) => id).join(", ")}）后重试。`,
-    );
-  }
-  const models = Object.keys(entry.models ?? {});
-  if (models.length > 0 && !models.includes(short)) {
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知模型 "${short}"（provider ${provider} 下可用: ${models.join(", ")}）。` +
-        `恢复指引：改用该 provider 下的模型，或先在 ZCode 桌面端启用目标模型后重试。`,
-    );
-  }
-  return `${provider}/${short}`;
-}
-
-// ============================================================
-// 模型清单（U7 可发现性——v2 单源聚合，与 resolveZcodeModelRef 的凭据校验同判据）
-// ============================================================
-
-/**
- * 列出当前环境 zcode 引擎实际可用的模型（v2 config 内带 apiKey 的 provider × 其
- * models 清单）。消费方：EnginePort.listModels（system prompt 引擎段 / GUI）。
- * 失败安全：v2 config 不可读 → 空清单（可发现性降级不阻塞主流程）。
- */
-export function listZcodeModels(sources?: ZcodeSourcePaths): Array<{ id: string; name?: string }> {
-  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
-  const out: Array<{ id: string; name?: string }> = [];
-  for (const [pid, entry] of v2.providers) {
-    if (!hasApiKey(entry)) continue;
-    const providerName =
-      typeof entry["name"] === "string" && entry["name"].trim() !== "" ? entry["name"].trim() : undefined;
-    const models = Object.keys(entry.models ?? {});
-    for (const model of models) {
-      out.push({
-        id: `${pid}/${model}`,
-        ...(providerName !== undefined ? { name: `${providerName} · ${model}` } : {}),
-      });
-    }
-  }
-  return out;
-}
-
-// ============================================================
-// 池 key 与目录（2026-09 删除：HOME 池化随 CLI spawn 链一并退役——共享宿主 HOME
-// 后无隔离池、无 config 引导，本文件只剩 v2 单源的模型解析/清单校验件）
-// ============================================================