@zhushanwen/subagent-core 0.2.0

package/src/execution/manifest-store.ts

@@ -0,0 +1,256 @@
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+
+import { bestEffort } from "./best-effort.ts";
+
+export interface ManifestRecord {
+  id: string;
+  rootSessionId: string;
+  /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
+  parentRecordId?: string;
+  agentName: string;
+  /**
+   * 终态枚举：finalizeRecord 写 running/closed/cancelled 三态。
+   * SP-1 重构：旧 completed/failed 合并为 closed（L1 统一终态）。
+   * cancelled 保持独立（用户取消语义）。crashed 不进 manifest——
+   * crashed 是重启重建时靠 sidecar 四分支推断的派生态（见 record-store.ts reconstructAll）。
+   * 历史 "error"/"completed"/"failed" 值由读侧 mapManifestStatus 向后兼容映射。
+   */
+  status: "running" | "closed" | "cancelled";
+  createdAt: number;
+  completedAt?: number;
+  sessionFile?: string;
+  /** FR-7 补字段：manifest 写入时从 ExecutionRecord 抓取，供 manifestToSubagent 投影真实值。 */
+  task?: string;
+  slug?: string;
+  model?: string;
+}
+
+/** JSON.stringify 缩进空格数（no-magic-numbers 合规）。 */
+const MANIFEST_INDENT_SPACES = 2;
+
+/** [perf] 缓存校验戳（与 record-store.ts Stamp 同构；manifest 是小文件，mtime+size 足够）。 */
+interface Stamp {
+  mtimeMs: number;
+  size: number;
+}
+
+function statStamp(p: string): Stamp | null {
+  try {
+    const s = fs.statSync(p);
+    return { mtimeMs: s.mtimeMs, size: s.size };
+  } catch {
+    return null;
+  }
+}
+
+/** 合法 manifest status 集合（3 态；运行时守卫用，磁盘文件可能陈旧/损坏）。
+ * SP-1：completed/failed 合并为 closed。读侧 mapManifestStatus 向后兼容旧值。
+ * crashed 不在其中。 */
+const VALID_MANIFEST_STATUSES: ReadonlySet<string> = new Set([
+  "running",
+  "closed",
+  "cancelled",
+  "completed", // 向后兼容旧 manifest 数据
+  "failed",     // 向后兼容旧 manifest 数据
+]);
+
+/**
+ * 校验 JSON.parse 产物是否为合法 ManifestRecord。
+ * 关键字段类型检查——不合法返回 false，调用方据此过滤（防损坏/陈旧文件污染投影）。
+ */
+function isValidManifest(value: unknown): value is ManifestRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" &&
+    typeof v.rootSessionId === "string" &&
+    typeof v.agentName === "string" &&
+    typeof v.createdAt === "number" &&
+    typeof v.status === "string" &&
+    VALID_MANIFEST_STATUSES.has(v.status)
+  );
+}
+
+export class ManifestStore {
+  private readonly dir: string;
+
+  /** [perf] per-file 缓存：file → { stamp, record }。record=null 表示「已解析但非法」（缓存
+   *  负结果避免反复 parse 损坏文件）。stat 戳变化（writeManifest tmp→rename 后 mtime/size 变）
+   *  自动失效；删除的文件在下次扫描时修剪。 */
+  private readonly cache = new Map<string, { stamp: Stamp; record: ManifestRecord | null }>();
+
+  constructor(dir: string) {
+    this.dir = dir;
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 原子写：tmp → fsync → rename → fsync dir。真异步（fs.promises，不阻塞 event loop）。
+   *
+   * rename 失败时 best-effort 清理残留 tmp（用 renamed 标志在 catch 中决定是否 unlink），
+   * 不掩盖原错误。失败向上抛——调用方（finalizeRecord）决定降级策略。
+   */
+  async writeManifest(record: ManifestRecord): Promise<void> {
+    const filePath = path.join(this.dir, `${record.id}.json`);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    const content = JSON.stringify(record, null, MANIFEST_INDENT_SPACES);
+
+    let renamed = false;
+    try {
+      // 1. 写 tmp → fsync 文件
+      const fh = await fsPromises.open(tmpPath, "w");
+      try {
+        await fh.writeFile(content, "utf-8");
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+
+      // 2. rename tmp → final（放入 try：失败时 catch 清理 tmp）
+      await fsPromises.rename(tmpPath, filePath);
+      renamed = true;
+
+      // 3. fsync 目录（best-effort：POSIX 不要求，失败不否定已成功的 rename）
+      try {
+        const dirFh = await fsPromises.open(this.dir, "r");
+        try {
+          await dirFh.sync();
+        } finally {
+          await dirFh.close();
+        }
+      } catch (dirSyncErr) {
+        bestEffort(dirSyncErr, "fsync dir (writeManifest)");
+      }
+    } catch (err) {
+      // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
+      if (!renamed) {
+        try {
+          await fsPromises.unlink(tmpPath);
+        } catch (cleanupErr) {
+          // best-effort：tmp 可能已被 rename 消费或从未创建。不影响主错误（下面 re-throw err）
+          bestEffort(cleanupErr, "unlink tmp (writeManifest)");
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 按 id 读 manifest。文件不存在/JSON 损坏/schema 不合法均返回 null。
+   * 调用方需处理 null。
+   */
+  async readManifest(id: string): Promise<ManifestRecord | null> {
+    const filePath = path.join(this.dir, `${id}.json`);
+    try {
+      const content = await fsPromises.readFile(filePath, "utf-8");
+      const parsed: unknown = JSON.parse(content);
+      return isValidManifest(parsed) ? parsed : null;
+    } catch {
+      // 文件缺失（ENOENT）或 JSON 损坏（SyntaxError）均降级为 null
+      return null;
+    }
+  }
+
+  /**
+   * 同步读取所有 manifest 记录（best-effort，损坏/非法文件跳过）。
+   * 供 RecordStore.collectRecords 投影 orphan 记录使用——替代对私有 dir 的反射访问。
+   * 仅返回通过 isValidManifest 校验的记录。
+   *
+   * [perf] per-file 缓存 + stat 戳校验：collectRecords 每次渲染都调本方法，旧实现每次
+   * 全量 readFileSync + JSON.parse 千级 manifest（实测 ~300ms/次）。命中缓存的文件零读取。
+   */
+  listAllSync(): readonly ManifestRecord[] {
+    let files: string[];
+    try {
+      files = fs.readdirSync(this.dir);
+    } catch {
+      return [];
+    }
+    const names = files.filter((f) => f.endsWith(".json") && !f.includes(".tmp."));
+    const disk = new Set(names);
+
+    // 修剪已删除文件
+    for (const f of this.cache.keys()) {
+      if (!disk.has(f)) this.cache.delete(f);
+    }
+
+    const results: ManifestRecord[] = [];
+    for (const file of names) {
+      const filePath = path.join(this.dir, file);
+      const stamp = statStamp(filePath);
+      if (!stamp) {
+        this.cache.delete(file);
+        continue;
+      }
+      const cached = this.cache.get(file);
+      if (cached && cached.stamp.mtimeMs === stamp.mtimeMs && cached.stamp.size === stamp.size) {
+        if (cached.record) results.push(cached.record);
+        continue;
+      }
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const parsed: unknown = JSON.parse(content);
+        const record = isValidManifest(parsed) ? parsed : null;
+        this.cache.set(file, { stamp, record });
+        if (record) results.push(record);
+      } catch (fileErr) {
+        // best-effort：损坏/非法文件跳过（debug 记录便于排查）。缓存负结果防反复 parse。
+        this.cache.set(file, { stamp, record: null });
+        bestEffort(fileErr, `read manifest ${file} (listAllSync)`);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 启动时恢复 tmp 文件。
+   * 3 分支逻辑：
+   * 1. manifest 已存在 → 删 tmp（陈旧）
+   * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
+   * 3. tmp 非法 + manifest 缺失 → 删 tmp
+   */
+  async recoverTmpFiles(): Promise<{ deleted: number; recovered: number }> {
+    let deleted = 0;
+    let recovered = 0;
+
+    const files = fs.readdirSync(this.dir);
+    const tmpFiles = files.filter((f) => f.includes(".json.tmp."));
+
+    for (const tmpFile of tmpFiles) {
+      const tmpPath = path.join(this.dir, tmpFile);
+      const manifestId = tmpFile.split(".json.tmp.")[0];
+      const manifestPath = path.join(this.dir, `${manifestId}.json`);
+
+      if (fs.existsSync(manifestPath)) {
+        // 分支 1: manifest 已存在，删 tmp
+        fs.unlinkSync(tmpPath);
+        deleted++;
+      } else {
+        // 试解析 tmp
+        try {
+          const content = fs.readFileSync(tmpPath, "utf-8");
+          const parsed: unknown = JSON.parse(content);
+          if (isValidManifest(parsed)) {
+            // 分支 2: tmp 是合法 manifest，rename 为正式文件
+            fs.renameSync(tmpPath, manifestPath);
+            recovered++;
+          } else {
+            // 分支 3b: 合法 JSON 但非合法 manifest（缺必填字段），删
+            fs.unlinkSync(tmpPath);
+            deleted++;
+          }
+        } catch {
+          // 分支 3a: JSON.parse 失败，删
+          fs.unlinkSync(tmpPath);
+          deleted++;
+        }
+      }
+    }
+
+    return { deleted, recovered };
+  }
+}

package/src/execution/model-config-service.ts

@@ -0,0 +1,250 @@
+// src/runtime/model-config-service.ts
+//
+// 配置 + 模型解析领域 Service。"给定 agent 名 + 用户参数 + 主 agent 模型，用哪个模型？"
+//
+// 与 SubagentService（执行/记录/通知域）正交——本 Service 不碰 pool/store/notifier。
+// 上游：SubagentService.execute 内部调 resolveModel。
+// session_start 时经 initModel 注入 modelRegistry。
+
+import { AgentRegistry } from "./agent-registry.ts";
+import {
+  loadGlobalConfig,
+  readGlobalConfig,
+  type GlobalConfigReadResult,
+} from "./config.ts";
+import {
+  type AgentConfig,
+  type ModelInfo,
+  type ModelRegistryLike,
+  type ResolvedModel,
+  resolveModel,
+} from "./model-resolver.ts";
+import type { SubagentsGlobalConfig } from "./types.ts";
+
+// ============================================================
+// 类型
+// ============================================================
+
+/** Service 构造参数（进程级，跨 session 不变）。 */
+export interface ModelConfigServiceInit {
+  agentDir: string;
+  /** 项目根目录（ctx.cwd，用于推导 workspaceRoot 扫描 project 级资源）。 */
+  cwd: string;
+}
+
+/** session_start 注入参数（session 级，每次重建）。 */
+export interface ModelServiceSessionInit {
+  /** 模型注册表（鉴权 + 发现）。null 立即抛错（fail-fast）。 */
+  modelRegistry: ModelRegistryLike | null;
+  /** 当前 session ID。 */
+  sessionId: string;
+  /**
+   * 主 agent 当前 model（session_start 时注入，model_select 时刷新）。
+   *
+   * renderCall 阶段的 ToolRenderContext 不含 model 字段（SDK 限制），无法直接拿到
+   * 主 agent model。缓存后 renderCall 的 resolveModel 能命中第三层（ctxModel），
+   * 让标题行恢复显示 model——即使未显式传 model 也能展示默认 model。
+   *
+   * [HISTORICAL] 99f20da1e 引入三层 fallback 后，renderCall 因拿不到 ctxModel
+   * 而 resolveModel 拗错→降级不显示 model。此缓存修复该降级。
+   */
+  ctxModel?: ModelInfo;
+}
+
+// ============================================================
+// ModelConfigService
+// ============================================================
+
+/**
+ * 配置 + 模型解析 Service。进程级单例。
+ *
+ *   ┌──────────────────────────────────────────────────────┐
+ *   │  globalConfig（~/.pi/.../config.json，仅 maxConcurrent）│
+ *   │  agentRegistry（agent .md 发现 + frontmatter）         │
+ *   │  modelRegistry（SDK 注入的可用模型）                    │
+ *   │                                                      │
+ *   │  resolveModel: override → agentConfig → 主 agent model │
+ *   └──────────────────────────────────────────────────────┘
+ */
+export class ModelConfigService {
+  private globalConfig: SubagentsGlobalConfig;
+  private readonly agentRegistry: AgentRegistry;
+  private readonly agentRegistryDir: string;
+  private modelRegistry: ModelRegistryLike | null = null;
+  private _sessionId: string | undefined;
+  /** 主 agent 当前 model 缓存（session_start 注入，model_select 刷新）。 */
+  private _ctxModel: ModelInfo | undefined;
+
+  constructor(init: ModelConfigServiceInit) {
+    this.agentRegistryDir = init.agentDir;
+    this.globalConfig = loadGlobalConfig(init.agentDir);
+    this.agentRegistry = new AgentRegistry();
+  }
+
+  // ── 生命周期（index.ts 调）──────────────────────────────
+
+  /**
+   * session_start 注入。封装 3 步固定时序：
+   *   1. reloadGlobalConfig（复用时拿最新 config）
+   *   2. injectModelRegistry（fail-fast：null 抛错）
+   *   3. setSessionId
+   */
+  initModel(init: ModelServiceSessionInit): void {
+    // 1. 重载配置（agent 按需 loadByPath，无预热扫描）
+    this.reloadGlobalConfig();
+
+    // 2. modelRegistry（fail-fast）
+    if (init.modelRegistry === null) {
+      throw new Error("modelRegistry is required but got null");
+    }
+    this.modelRegistry = init.modelRegistry;
+
+    // 3. sessionId + ctxModel 缓存（model_select 后续调 setCtxModel 刷新）
+    this._sessionId = init.sessionId;
+    this._ctxModel = init.ctxModel;
+  }
+
+  /**
+   * 将一次三态读取结果提交到路由缓存（纯赋值幂等）。
+   *
+   * ok/absent 覆盖缓存、failed 保持缓存不动（坏 JSON 不能把好缓存打回缺省）；
+   * 返回入参便于链式消费。用途 = 构造性同源：session_start 初始化与 per-turn 引擎
+   * 检测各只读一次文件，同一读取结果既刷新路由缓存又充当检测基准，消灭两次独立
+   * 读取之间的分叉窗口（两次读值不一致时检测走 unchanged，状态段/路由永停旧值）。
+   */
+  applyGlobalConfig(read: GlobalConfigReadResult): GlobalConfigReadResult {
+    if (read.status !== "failed") {
+      this.globalConfig = read.config;
+    }
+    return read;
+  }
+
+  /**
+   * 三态重读全局配置并提交缓存（幂等可重入），返回本次读取结果供调用方感知。
+   *
+   * 从 initModel 提取（设计 D2）：引擎感知检测器 per-turn poll 发现 config 变更时
+   * 调用本方法，使「system prompt 现值、路由缓存、变更通知」同 turn 对齐——只改注入
+   * 不刷新路由缓存，会出现 prompt 说引擎 B、实际派发跑引擎 A（权威信息源说谎）。
+   * 幂等性：只做「读文件 → 按三态提交缓存」单向赋值，无时序状态，重复调用收敛到
+   * 同一结果。三态语义（failed 保持缓存、静默回落 DEFAULT 是旧缺陷——读失败曾把
+   * 好缓存打回缺省且调用方无法感知）：ok/absent 覆盖、failed 保持并携带原因。
+   */
+  reloadGlobalConfig(): GlobalConfigReadResult {
+    return this.applyGlobalConfig(readGlobalConfig(this.agentRegistryDir));
+  }
+
+  /**
+   * 刷新主 agent model 缓存。model_select 事件时调用。
+   * renderCall 的 resolveModel 读此缓存以显示标题行 model。
+   */
+  setCtxModel(model: ModelInfo | undefined): void {
+    this._ctxModel = model;
+  }
+
+  // ── 模型解析（SubagentService.execute 内部调）──────────────
+
+  /**
+   * 解析 agent 的模型（三层：override → agentConfig → 主 agent model）。
+   *
+   * @param agentRef   agent 引用（.md 绝对路径；查 agentConfig 的 model override）
+   * @param override   调用方显式 override（最高优先级）
+   * @param ctxModel   主 agent 当前模型（兜底，直接透传）
+   */
+  resolveModel(
+    agentRef: string,
+    override?: { model?: string; thinkingLevel?: string },
+    ctxModel?: ModelInfo,
+    /** 已解析的 agent 配置（调用方已加载时复用，避免同一 agentRef 二次 loadByPath）。 */
+    agentConfig?: AgentConfig,
+  ): ResolvedModel {
+    this.assertReady();
+    const config = agentConfig ?? (agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined);
+    // ctxModel 优先用显式传入（execute 路径），其次用 session 缓存（renderCall 路径）
+    return resolveModel(config, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
+  }
+
+  /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。
+   *  undefined = 合法缺省语义（未点名 / 默认 general-purpose 形态）。 */
+  getAgentConfig(agentRef?: string): AgentConfig | undefined {
+    return agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined;
+  }
+
+  /**
+   * 查询 agent 配置——显式 ref 失败即 throw（SubagentService.resolveIdentity 用）。
+   *
+   * 与 getAgentConfig 的语义分界（「用户显式点名」vs「默认 general-purpose」）：
+   * 用户显式点名的 agentRef（工具 agent 参数 / workflow agent({agent}) opts）解析
+   * 失败 = 配置错误，必须显式报错——错误文案含 <available_subagents> 恢复指引
+   * （对齐 workflow name not found 反馈风格），不允许静默降级为无配置
+   * general-purpose 形态（systemPrompt/工具白名单全丢且零反馈）。默认形态
+   * （不传 agent）走 getAgentConfig：undefined = 合法缺省，走 override → ctxModel 兑底。
+   */
+  getRequiredAgentConfig(agentRef: string): AgentConfig {
+    return this.agentRegistry.loadByPath(agentRef, true);
+  }
+
+  // ── 配置读取（subagent-service 调）────────────────────────
+
+  /** 全局配置深拷贝（调用方拿到副本，改不影响 Service 内部）。 */
+  getGlobalConfig(): SubagentsGlobalConfig {
+    return structuredClone(this.globalConfig);
+  }
+
+  /** 内部：session id 缓存（initModel 注入；当前无消费者，保留供未来 session 作用域需求）。 */
+  get sessionId(): string | undefined {
+    return this._sessionId;
+  }
+
+  /** agent 配置目录（SubagentService 构造 store/SessionRunnerContext 时读）。 */
+  getAgentDir(): string {
+    return this.agentRegistryDir;
+  }
+
+  /** modelRegistry（SubagentService 构造 factoryCtx 时读）。已注入保证非 null。 */
+  getModelRegistry(): ModelRegistryLike {
+    if (this.modelRegistry === null) {
+      throw new Error("modelRegistry not injected (initModel not called?)");
+    }
+    return this.modelRegistry;
+  }
+
+  // ── 内部 ────────────────────────────────────────────────
+
+  /** 校验 modelRegistry 已注入。 */
+  private assertReady(): void {
+    if (this.modelRegistry === null) {
+      throw new Error("modelRegistry not injected (initModel not called?)");
+    }
+  }
+}
+
+// ============================================================
+// 进程单例访问器
+// ============================================================
+
+// 用 globalThis[Symbol.for] 持有进程单例，避免 jiti 因路径字符串不同加载多份模块
+// 导致单例分裂（详见 docs/standards.md §7.5）。
+const MODEL_SERVICE_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagents.model-service");
+
+type ModelServiceSlot = { current: ModelConfigService | null };
+
+function getModelServiceSlot(): ModelServiceSlot {
+  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
+  // 避免双重断言。ModelServiceSlot 是运行时保证的固定形状（同文件唯一写入点）。
+  let slot = Reflect.get(globalThis, MODEL_SERVICE_SLOT_KEY) as ModelServiceSlot | undefined;
+  if (!slot) {
+    slot = { current: null };
+    Reflect.set(globalThis, MODEL_SERVICE_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** 获取进程单例。session_start 前为 null。 */
+export function getModelConfigService(): ModelConfigService | null {
+  return getModelServiceSlot().current;
+}
+
+/** 设置进程单例（session_start 首次创建时）。 */
+export function setModelConfigService(service: ModelConfigService): void {
+  getModelServiceSlot().current = service;
+}