@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/__tests__/smoke.test.ts

@@ -1,9 +1,16 @@
+import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 import { CORE_PACKAGE_VERSION } from "../index";
 
+// 对 package.json version 断言（单一事实源）：本测试是 src/index.ts 字面量与
+// package.json 双源同步的执法者——任何一侧 bump 后未同步另一侧立即红，
+// 替代旧硬编码 "0.1.0" 字面量（版本 bump 时必忘改的第三处双源）。
 describe("subagent-core scaffold smoke", () => {
-  it("exposes CORE_PACKAGE_VERSION", () => {
-    expect(CORE_PACKAGE_VERSION).toBe("0.1.0");
+  it("exposes CORE_PACKAGE_VERSION synced with package.json", () => {
+    const pkgVersion = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+    ).version;
+    expect(CORE_PACKAGE_VERSION).toBe(pkgVersion);
   });
 });

package/src/execution/__tests__/agent-profile.test.ts

@@ -0,0 +1,232 @@
+// src/execution/__tests__/agent-profile.test.ts
+//
+// parseAgentProfile 宽容解析测试（sink 设计 U2 / D3 / u-core-agent 验收①）。
+//
+// 字段形态覆盖矩阵（D3 定稿）：单行 key:value、行内数组、block-scalar、
+// 多行 `- item` 列表、无 frontmatter 宽容降级不抛；另含 legacy fallback
+// （meta=null 单行兜底）与 parseResourceMeta 严格层新字段投影断言
+// （AgentMeta 扩 maxTurns/disallowedTools/skills 的 typecheckMeta 行为）。
+
+import { describe, expect, fail, it } from "vitest";
+
+import { parseResourceMeta } from "../../shared/meta-parser.ts";
+import { parseAgentProfile } from "../agent-registry.ts";
+
+describe("parseAgentProfile（D3 宽容解析）", () => {
+  it("单行 key:value 全字段（IF1 通过）", () => {
+    const profile = parseAgentProfile(
+      `---
+name: coder
+description: coding agent
+model: anthropic/claude-3.5-sonnet
+thinkingLevel: high
+tools: read, bash
+maxTurns: 2
+disallowedTools: write, edit
+skills: code-review
+---
+body text`,
+      "/x/coder.md",
+    );
+    expect(profile.name).toBe("coder");
+    expect(profile.description).toBe("coding agent");
+    expect(profile.body).toBe("body text");
+    expect(profile.model).toBe("anthropic/claude-3.5-sonnet");
+    expect(profile.thinkingLevel).toBe("high");
+    expect(profile.tools).toEqual(["read", "bash"]);
+    expect(profile.maxTurns).toBe(2);
+    expect(profile.disallowedTools).toEqual(["write", "edit"]);
+    expect(profile.skills).toEqual(["code-review"]);
+    expect(profile.meta).not.toBeNull();
+    expect(profile.warnings).toEqual([]);
+  });
+
+  it("行内数组形态（tools: [read, bash]）", () => {
+    const profile = parseAgentProfile(
+      `---
+name: coder
+description: coding agent
+tools: [read, bash]
+---
+body`,
+      "/x/coder.md",
+    );
+    expect(profile.tools).toEqual(["read", "bash"]);
+    expect(profile.meta).not.toBeNull();
+  });
+
+  it("block-scalar description 完整保留（多行描述不截断）", () => {
+    const profile = parseAgentProfile(
+      `---
+name: reviewer
+description: |
+  first line of description
+  second line of description
+---
+body`,
+      "/x/reviewer.md",
+    );
+    // `|` clip chomping 保留单个末尾换行（eemeli/yaml 标准行为）
+    expect(profile.description).toBe("first line of description\nsecond line of description\n");
+    expect(profile.meta?.description).toBe(profile.description);
+  });
+
+  it("多行 `- item` 列表形态（tools/disallowedTools/skills）", () => {
+    const profile = parseAgentProfile(
+      `---
+name: builder
+description: build agent
+tools:
+  - read
+  - bash
+disallowedTools:
+  - write
+skills:
+  - code-review
+  - test-runner
+---
+body`,
+      "/x/builder.md",
+    );
+    expect(profile.tools).toEqual(["read", "bash"]);
+    expect(profile.disallowedTools).toEqual(["write"]);
+    expect(profile.skills).toEqual(["code-review", "test-runner"]);
+    expect(profile.maxTurns).toBeUndefined();
+  });
+
+  it("无 frontmatter：宽容降级不抛——name=stem、description 空串、全文 body、无 warning", () => {
+    const profile = parseAgentProfile("# README\n\nplain markdown.", "/x/README.md");
+    expect(profile.name).toBe("README");
+    expect(profile.description).toBe("");
+    expect(profile.body).toBe("# README\n\nplain markdown.");
+    expect(profile.meta).toBeNull();
+    expect(profile.warnings).toEqual([]);
+  });
+
+  it("未闭合 frontmatter：name 经 legacy fallback、全文作 body、warning 可见", () => {
+    const text = `---\nname: broken\nmodel: x/y`;
+    const profile = parseAgentProfile(text, "/x/broken.md");
+    expect(profile.name).toBe("broken");
+    expect(profile.body).toBe(text);
+    expect(profile.meta).toBeNull();
+    expect(profile.warnings).toHaveLength(1);
+    expect(profile.warnings[0]).toContain("未闭合");
+  });
+
+  it("IF1 失败（缺 description）：执行字段经单行 legacy fallback 不丢失 + warning", () => {
+    const profile = parseAgentProfile(
+      `---
+name: legacy
+model: anthropic/claude-3.5-sonnet
+tools: read, bash
+maxTurns: 5
+---
+body text`,
+      "/x/legacy.md",
+    );
+    expect(profile.meta).toBeNull();
+    expect(profile.name).toBe("legacy");
+    expect(profile.description).toBe("");
+    expect(profile.model).toBe("anthropic/claude-3.5-sonnet");
+    expect(profile.tools).toEqual(["read", "bash"]);
+    // legacy fallback 只认字符串形态：`maxTurns: 5` 单行 → Number 换算
+    expect(profile.maxTurns).toBe(5);
+    expect(profile.warnings).toHaveLength(1);
+    expect(profile.warnings[0]).toContain("legacy fallback");
+    expect(profile.body).toBe("body text");
+  });
+
+  it("IF1 失败 + maxTurns 非数字：忽略该字段并追加 warning（不抛）", () => {
+    const profile = parseAgentProfile(
+      `---
+name: weird
+maxTurns: many
+---
+body`,
+      "/x/weird.md",
+    );
+    expect(profile.meta).toBeNull();
+    expect(profile.maxTurns).toBeUndefined();
+    expect(profile.warnings.some((w) => w.includes("maxTurns"))).toBe(true);
+  });
+
+  it("name 缺省 stem（frontmatter 无 name 字段且 IF1 失败时）", () => {
+    const profile = parseAgentProfile("---\nmodel: x/y\n---\nbody", "/x/unnamed.md");
+    expect(profile.name).toBe("unnamed");
+    expect(profile.model).toBe("x/y");
+  });
+});
+
+describe("parseResourceMeta 严格层新字段投影（AgentMeta D3 扩展的 typecheckMeta 行为）", () => {
+  it("数字 maxTurns + 数组 disallowedTools/skills 投影进 AgentMeta", () => {
+    const meta = parseResourceMeta(
+      `---
+name: coder
+description: coding agent
+maxTurns: 2
+disallowedTools: [write]
+skills:
+  - code-review
+---
+body`,
+      "agent",
+    );
+    expect(meta).not.toBeNull();
+    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    expect(meta.maxTurns).toBe(2);
+    expect(meta.disallowedTools).toEqual(["write"]);
+    expect(meta.skills).toEqual(["code-review"]);
+  });
+
+  it("maxTurns 非有限数字 → reject（严格层不静默丢弃非法字段）", () => {
+    const meta = parseResourceMeta(
+      "---\nname: x\ndescription: y\nmaxTurns: many\n---\nbody",
+      "agent",
+    );
+    expect(meta).toBeNull();
+  });
+
+  it("disallowedTools 数组含非字符串 → reject", () => {
+    const meta = parseResourceMeta(
+      "---\nname: x\ndescription: y\ndisallowedTools: [write, 42]\n---\nbody",
+      "agent",
+    );
+    expect(meta).toBeNull();
+  });
+
+  it("disallowedTools/skills 空数组 → 键保留为 []（与 tools: [] 空列表语义一致）", () => {
+    const meta = parseResourceMeta(
+      "---\nname: x\ndescription: y\ntools: []\ndisallowedTools: []\nskills: []\n---\nbody",
+      "agent",
+    );
+    expect(meta).not.toBeNull();
+    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    expect("disallowedTools" in meta).toBe(true);
+    expect(meta.disallowedTools).toEqual([]);
+    expect("skills" in meta).toBe(true);
+    expect(meta.skills).toEqual([]);
+    // 同 fixture 的 tools 基准：空数组三字段族同语义
+    expect("tools" in meta).toBe(true);
+    expect(meta.tools).toEqual([]);
+  });
+
+  it("workflow meta 含 agent 专属新字段 → 串类 reject", () => {
+    const meta = parseResourceMeta(
+      "/* @pi-meta\nname: wf\ndescription: d\nphases: [a]\nmaxTurns: 2\n*/\ncode",
+      "workflow",
+    );
+    expect(meta).toBeNull();
+  });
+
+  it("缺 maxTurns/disallowedTools/skills 时 AgentMeta 不出现这些键（零回归）", () => {
+    const meta = parseResourceMeta(
+      "---\nname: x\ndescription: y\n---\nbody",
+      "agent",
+    );
+    expect(meta).not.toBeNull();
+    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    expect("maxTurns" in meta).toBe(false);
+    expect("disallowedTools" in meta).toBe(false);
+    expect("skills" in meta).toBe(false);
+  });
+});

package/src/execution/__tests__/agents-assembly.test.ts

@@ -0,0 +1,219 @@
+// src/execution/__tests__/agents-assembly.test.ts
+//
+// discoverAgents 装配函数测试（sink 设计 U2 / A6 / u-core-agent 验收②）。
+//
+// 等值对照口径：fixture 目录下，discoverAgents 产出与 pi 壳现装配循环
+// （subagent-list-injector.discoverAllAgents）产出「同序同名同字段」。
+// pi 壳装配循环无法直接 import 进 core 测试（core 对 pi-coding-agent /
+// pi-extension-logger 零运行时触点——vitest.config 头注红线），故 oracle 在
+// 测试内按 pi 循环逐句同构复刻，但全部消费 core 既有原语
+// （discoverResources + parseResourceMeta 严格层 + sortByCodepoint）——
+// 这正是 pi 循环消费的同一批 core 原语（pi 的 parseAgentFrontmatter 内部即
+// parseResourceMeta(content, "agent") 投影）。oracle 与被测实现走不同解析路径
+// （严格层 vs parseAgentProfile 宽容层），非自证。
+//
+// fixture 含全部清单可见性分支：正常条目（多形态）、同名遮蔽（hostRoots
+// last-writer-wins）、无 frontmatter（README，两边都不进清单）、IF1 失败
+// （缺 description，两边都不进清单）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { configureCore, resetCoreForTests } from "../../core/host-services.ts";
+import type { AgentEntry } from "../../shared/injection-render.ts";
+import { sortByCodepoint } from "../../shared/injection-render.ts";
+import { parseResourceMeta } from "../../shared/meta-parser.ts";
+import {
+  clearFileCache,
+  discoverResources,
+  getCachedFileContent,
+  type DiscoveryRoot,
+  type ScanConfig,
+} from "../../shared/resource-discovery.ts";
+import { discoverAgents } from "../agents-assembly.ts";
+
+// ── oracle：pi 壳 discoverAllAgents 装配循环的逐句同构（消费同一批 core 原语）──
+
+async function piAssemblyOracle(
+  workspaceRoot: string,
+  hostRoots: DiscoveryRoot[],
+): Promise<AgentEntry[]> {
+  const config: ScanConfig = { kind: "agents", workspaceRoot, hostRoots };
+  const resources = await discoverResources(config);
+
+  const agentMap = new Map<string, AgentEntry>();
+  for (const resource of resources) {
+    if (!resource.available) continue;
+    const content = getCachedFileContent(resource.path);
+    if (content === null) continue; // pi: catch → logger.error → skip
+    // pi parseAgentFrontmatter 的投影面（parseResourceMeta 严格层）
+    const meta = parseResourceMeta(content, "agent");
+    if (meta && meta.kind === "agent") {
+      agentMap.set(meta.name, {
+        name: meta.name,
+        description: meta.description,
+        when: meta.when,
+        examples: meta.examples,
+        path: resource.path,
+      });
+    } else if (content.trimStart().startsWith("---")) {
+      // pi: startsWithFrontmatter → logger.warn（清单可见性口径：无 frontmatter 不 warn）
+    }
+  }
+  return sortByCodepoint([...agentMap.values()], (a) => a.name);
+}
+
+// ── fixture ──────────────────────────────────────────────────
+
+function writeAgent(root: string, rel: string, content: string): string {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, "utf-8");
+  return abs;
+}
+
+describe("discoverAgents", () => {
+  let outerDir: string;
+  let workspaceRoot: string;
+  let hostRoot: string;
+  let logCalls: Array<{ level: string; component: string; message: string; data?: unknown }>;
+
+  beforeEach(() => {
+    outerDir = fs.mkdtempSync(path.join(os.tmpdir(), "agents-assembly-"));
+    workspaceRoot = path.join(outerDir, "ws");
+    hostRoot = path.join(outerDir, "host", "agents");
+    fs.mkdirSync(workspaceRoot, { recursive: true });
+    logCalls = [];
+    configureCore({
+      dataRoot: () => outerDir,
+      log: (level, component, message, data) => {
+        logCalls.push({ level, component, message, data });
+      },
+    });
+  });
+
+  afterEach(() => {
+    resetCoreForTests();
+    clearFileCache();
+    fs.rmSync(outerDir, { recursive: true, force: true });
+  });
+
+  it("与 pi 壳现装配循环产出等值（同序同名同字段）——多形态 fixture 对照", async () => {
+    // project-pi 源（workspaceRoot/.pi/agents）
+    writeAgent(
+      workspaceRoot,
+      ".pi/agents/alpha.md",
+      `---
+name: alpha
+description: single-line agent
+model: provider/model-a
+---
+alpha body`,
+    );
+    // block-scalar description + 多行 - item（zsw mini parser 全形态）
+    writeAgent(
+      workspaceRoot,
+      ".pi/agents/beta.md",
+      `---
+name: beta
+description: |
+  beta line one
+  beta line two
+tools:
+  - read
+  - bash
+---
+beta body`,
+    );
+    // 无 frontmatter（两边都不进清单、都不 warn）
+    writeAgent(workspaceRoot, ".pi/agents/README.md", "# docs\n");
+    // IF1 失败（缺 description，两边都不进清单、都 warn）
+    writeAgent(
+      workspaceRoot,
+      ".pi/agents/broken.md",
+      `---
+name: broken
+model: provider/x
+---
+broken body`,
+    );
+    // hostRoots 注入源（序位高于 project-pi）——同名遮蔽 alpha + 新增 gamma
+    writeAgent(
+      hostRoot,
+      "alpha.md",
+      `---
+name: alpha
+description: host shadowing version
+---
+host alpha body`,
+    );
+    writeAgent(
+      hostRoot,
+      "gamma.md",
+      `---
+name: gamma
+description: inline array agent
+tools: [read, grep]
+maxTurns: 2
+---
+gamma body`,
+    );
+
+    const hostRoots: DiscoveryRoot[] = [{ dir: hostRoot, source: "project-host" }];
+    const [actual, oracle] = await Promise.all([
+      discoverAgents(workspaceRoot, hostRoots),
+      piAssemblyOracle(workspaceRoot, hostRoots),
+    ]);
+
+    // 同序同名同字段（逐条目投影对比，path 为绝对路径逐字节一致）
+    expect(actual).toEqual(oracle);
+    // 码点序：alpha < beta < gamma
+    expect(actual.map((a) => a.name)).toEqual(["alpha", "beta", "gamma"]);
+    // 同名遮蔽：alpha = hostRoots 胜出版（path + description 都是注入根的）
+    const alpha = actual.find((a) => a.name === "alpha");
+    expect(alpha?.path).toBe(path.join(hostRoot, "alpha.md"));
+    expect(alpha?.description).toBe("host shadowing version");
+    // 无 frontmatter / IF1 失败不进清单
+    expect(actual.some((a) => a.path.endsWith("README.md"))).toBe(false);
+    expect(actual.some((a) => a.path.endsWith("broken.md"))).toBe(false);
+  });
+
+  it("hostRoots 为空时仍扫硬编码槽（project .pi/agents），等值口径不破", async () => {
+    writeAgent(
+      workspaceRoot,
+      ".pi/agents/solo.md",
+      "---\nname: solo\ndescription: only one\n---\nbody",
+    );
+    const [actual, oracle] = await Promise.all([
+      discoverAgents(workspaceRoot, []),
+      piAssemblyOracle(workspaceRoot, []),
+    ]);
+    expect(actual).toEqual(oracle);
+    expect(actual.map((a) => a.name)).toEqual(["solo"]);
+  });
+
+  it("IF1 失败（有 frontmatter）→ warn 口径内聚：仅该类文件 warn，README 不 warn", async () => {
+    writeAgent(
+      workspaceRoot,
+      ".pi/agents/broken.md",
+      "---\nname: broken\nmodel: provider/x\n---\nbody",
+    );
+    writeAgent(workspaceRoot, ".pi/agents/README.md", "# plain doc\n");
+
+    const actual = await discoverAgents(workspaceRoot, []);
+    expect(actual).toEqual([]);
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns).toHaveLength(1);
+    expect(warns[0]!.message).toContain("broken.md");
+    expect(warns[0]!.message).toContain("IF1 校验不通过");
+  });
+
+  it("空目录 / 不存在的 workspaceRoot：空清单不抛", async () => {
+    const actual = await discoverAgents(path.join(outerDir, "nonexistent"), []);
+    expect(actual).toEqual([]);
+  });
+});

package/src/execution/__tests__/chat-engine-routing.test.ts

@@ -561,6 +561,77 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
     expect(h?.journalPath).toBe(resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId));
   });
 
+  // ============================================================
+  // [R4 §3.4 不变量 3] onHandleReady 运行中回填：create 应答后立即落 entry——
+  // 运行中 GUI 经 entry 重建 record 即得 ①②级读取钥匙（不等 run resolve）
+  // ============================================================
+
+  it("[onHandleReady] create 应答后回调 → record.engineHandle 立即回填 + reportRecordTransition 落 entry（record 仍 running）", async () => {
+    process.env.XYZ_AGENT_DATA_DIR = agentDir;
+    const { service, zcode, pi } = setup(agentDir);
+    const POOL = "zcode-appserver-home";
+    let releaseRun!: (v: { handle: EngineHandle; outcome: AgentOutcome }) => void;
+    zcode.runImpl = (task, ctx) => {
+      ctx.onPoolResolved?.(POOL);
+      // create 应答后的回调时点（app-server 引擎在 session/create 应答后触发）
+      ctx.onHandleReady?.({
+        sessionRef: { dbPath: ".zcode/cli/db/db.sqlite", sessionId: "sess-live-1" },
+        poolKey: POOL,
+      });
+      return new Promise((resolve) => {
+        releaseRun = resolve; // 挂起 run——模拟运行中任务
+      });
+    };
+    const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+    await vi.waitFor(() => expect(zcode.runs.length).toBe(1));
+
+    // run 尚未 resolve（record 仍 running）：engineHandle 已回填且 entry 已落盘
+    await vi.waitFor(() => {
+      const entries = pi.appendEntry.mock.calls.filter((c) => c[0] === "subagent-record");
+      const withHandle = entries.filter(
+        (c) => (c[1] as Record<string, unknown>).engineHandle !== undefined,
+      );
+      expect(withHandle.length).toBeGreaterThan(0);
+    });
+    const running = service.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
+    expect(running?.engineHandle).toEqual({
+      sessionRef: { dbPath: ".zcode/cli/db/db.sqlite", sessionId: "sess-live-1" },
+      poolKey: POOL,
+      journalPath: resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId),
+    });
+    // 回填 entry 的 journalPath 与 onPoolResolved retarget 后的实际落盘路径一致（同源）
+    expect(fs.existsSync(resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId))).toBe(false);
+
+    // 终态收口（防 dangling）
+    releaseRun({ handle: fakeHandle(), outcome: doneOutcome("ok") });
+    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+  }, 10_000);
+
+  it("[onHandleReady] 引擎不回调（spawn 形态）时零回填——终态回填仍兜底（行为不变）", async () => {
+    process.env.XYZ_AGENT_DATA_DIR = agentDir;
+    const { service, zcode, pi } = setup(agentDir);
+    const POOL = "zcode-p-glm";
+    zcode.runImpl = (task, ctx) => {
+      ctx.onPoolResolved?.(POOL); // 只 onPoolResolved——spawn 引擎形态（无 onHandleReady）
+      return Promise.resolve({
+        handle: {
+          data: { v: 1, engineId: "zcode", sessionRef: { dbPath: "sessions.db", sessionId: "sess-1" }, poolKey: POOL, adapterVersion: "test" },
+        },
+        outcome: doneOutcome("ok"),
+      });
+    };
+    const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+    await vi.waitFor(() => expect(service.findRecord(handle.subagentId)).toBeUndefined());
+    const entries = pi.appendEntry.mock.calls.filter((c) => c[0] === "subagent-record");
+    // 运行中回填 entry 不存在（register 写点无 engineHandle；archive 终态侧才有）
+    const runningEntries = entries.slice(0, -1);
+    for (const c of runningEntries) {
+      expect((c[1] as Record<string, unknown>).engineHandle).toBeUndefined();
+    }
+    const final = entries[entries.length - 1][1] as Record<string, unknown>;
+    expect(final.engineHandle).toMatchObject({ poolKey: POOL });
+  });
+
   it("[D5 回归] pi 纯缺省路径 entry 不含 engine/engineFallback/engineHandle 键", async () => {
     const { service, pi } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir));

package/src/execution/__tests__/chatmode-first-round-closure-spawn.test.ts

@@ -58,6 +58,7 @@ vi.mock("../alive-store.ts", () => ({ writeAliveMarker: vi.fn() }));
 // chatMode agent_end 早返回（continue），不读 session-pending；统一 count=0 防干扰。
 vi.mock("../session-pending.ts", () => ({
   readActivePendingFromSessionFile: vi.fn(() => ({ count: 0 })),
+  prunePendingCursor: vi.fn(),
 }));
 
 vi.mock("../temp-prompt.ts", () => ({