@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/__tests__/subagent-service-notify-gate.test.ts

@@ -0,0 +1,271 @@
+// src/execution/__tests__/subagent-service-notify-gate.test.ts
+//
+// [u-svc / T4] 通知可靠性（subagent-service 侧三措施）：
+//   - T4①/PS-2：kickOffChatRound.then notify 门按 closedReason 白名单放行——
+//     parent-new/parent-fork 不注入（可能已切换的）新 session（A-6 决策落实）；
+//   - T4②/PS-4：idleTimeoutMs 非法值（>2^31-1 / 非有限值）在 spawn 入口同步 fail-fast，
+//     错误含合法范围（不静默 clamp、不静默不挂）；
+//   - T4④/PS-5：shutdown flush 被 isIdle 门拦时，未投递 pending 复写落盘（ledger entry
+//     通道，notifyId 幂等）供重启 replay——修复「flush 后 dispose 防丢失」注释承诺差距。
+//
+// mock 形态沿用 subagent-service-message-close.test.ts；notify-ledger 用真模块
+//（bindNotifyLedgerHost + fake host 构造 pending）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+const { killChildSpy } = vi.hoisted(() => ({ killChildSpy: vi.fn() }));
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
+  runSpawn: vi.fn(),
+  killAllSpawnedChildren: vi.fn(),
+  getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  spawnedChildren: new Map(),
+  killRecordChildWithEscalation: killChildSpy,
+}));
+
+import { bindNotifyLedgerHost, NOTIFY_LEDGER_CUSTOM_TYPE, _resetNotifyLedgerForTest } from "../notify-ledger.ts";
+import { createRecord } from "../execution-record.ts";
+import { ModelConfigService } from "../model-config-service.ts";
+import type { RecordStore } from "../record-store.ts";
+import { notifyGateAllowsDelivery, SubagentService } from "../subagent-service.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { MAX_TIMER_DELAY_MS } from "../../shared/timer-delay.ts";
+import type { ExecutionRecord } from "../types.ts";
+
+function makeTmpAgentDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "svc-notify-gate-"));
+}
+
+function makePi(): PiLike & {
+  appendEntry: ReturnType<typeof vi.fn>;
+  events: { emit: ReturnType<typeof vi.fn> };
+  sendMessage: ReturnType<typeof vi.fn>;
+  on?: ReturnType<typeof vi.fn>;
+} {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike & {
+    appendEntry: ReturnType<typeof vi.fn>;
+    events: { emit: ReturnType<typeof vi.fn> };
+    sendMessage: ReturnType<typeof vi.fn>;
+    on?: ReturnType<typeof vi.fn>;
+  };
+}
+
+interface ServiceInternals {
+  store: RecordStore;
+}
+
+type MockPi = ReturnType<typeof makePi>;
+
+function setup(initOverrides: Partial<{ isIdle: () => boolean }> = {}): {
+  agentDir: string;
+  service: SubagentService;
+  store: RecordStore;
+  pi: MockPi;
+} {
+  const agentDir = makeTmpAgentDir();
+  const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
+  const service = new SubagentService({ cwd: agentDir, modelService });
+  const pi = makePi();
+  service.initSession({ pi, sessionId: "root-session", isIdle: initOverrides.isIdle });
+  const store = (service as unknown as ServiceInternals).store;
+  return { agentDir, service, store, pi };
+}
+
+describe("T4① notify gate closedReason whitelist", () => {
+  it("blocks cancelled, parent-new, parent-fork; allows real closures and undefined (CAS-winner path)", () => {
+    expect(notifyGateAllowsDelivery("cancelled")).toBe(false);
+    expect(notifyGateAllowsDelivery("parent-new")).toBe(false);
+    expect(notifyGateAllowsDelivery("parent-fork")).toBe(false);
+    expect(notifyGateAllowsDelivery("user-close")).toBe(true);
+    expect(notifyGateAllowsDelivery("gc")).toBe(true);
+    expect(notifyGateAllowsDelivery("parent-shutdown")).toBe(true);
+    expect(notifyGateAllowsDelivery(undefined)).toBe(true);
+  });
+
+  it("kickOffChatRound.then does not inject parent-new closed records into the session", async () => {
+    const { agentDir, service, pi } = setup();
+    const record = createRecord("sa-gate-new", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "background",
+      slug: "t",
+      task: "test",
+      startedAt: 1000,
+      rootSessionId: "root-session",
+      controller: new AbortController(),
+    });
+    // 模拟 disposeAllRecords 先行编排性关闭后，迟到的 kickOffChatRound.then 回注
+    record.closedReason = "parent-new";
+    const stub = vi.fn().mockResolvedValue({
+      text: "",
+      turns: 0,
+      durationMs: 1,
+      success: false,
+      error: "closed due to parent-new",
+      sessionId: record.id,
+      toolCalls: [],
+    });
+    (service as unknown as Record<string, unknown>).runAndFinalize = stub;
+    // [D4 后形态] 轮次编排入口 kickOffChatRound（私有，bracket 调用先例见
+    // subagent-service-recovery-bounds.test.ts privateFn）；opts 形参仍是 ExecuteOptions
+    //（task/slug），chat 分支由 ticket lossless 携带——task 声明形参不参与校验。
+    const kickOffChatRound = (
+      service as unknown as Record<string, (...args: unknown[]) => void>
+    )["kickOffChatRound"];
+    kickOffChatRound.call(service, record, { task: "t", slug: "gate" }, {}, {}, undefined, 1000, undefined);
+    await vi.waitFor(() => expect(stub).toHaveBeenCalled());
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("kickOffChatRound.then still notifies for real failure closures (gc)", async () => {
+    const { agentDir, service, pi } = setup();
+    const record = createRecord("sa-gate-gc", {
+      agent: "general-purpose",
+      model: "test/model",
+      mode: "background",
+      slug: "t",
+      task: "test",
+      startedAt: 1000,
+      rootSessionId: "root-session",
+      controller: new AbortController(),
+    });
+    record.closedReason = "gc";
+    (service as unknown as Record<string, unknown>).runAndFinalize = vi.fn().mockResolvedValue({});
+    const kickOffChatRound = (
+      service as unknown as Record<string, (...args: unknown[]) => void>
+    )["kickOffChatRound"];
+    kickOffChatRound.call(service, record, { task: "t", slug: "gate" }, {}, {}, undefined, 1000, undefined);
+    await vi.waitFor(() => expect(pi.sendMessage).toHaveBeenCalled());
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+});
+
+describe("T4② idleTimeoutMs entry fail-fast", () => {
+  let agentDir: string;
+  let service: SubagentService;
+
+  beforeEach(() => {
+    ({ agentDir, service } = setup());
+  });
+
+  afterEach(() => {
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("execute rejects idleTimeoutMs above the setTimeout limit with the valid range in the message", async () => {
+    await expect(service.execute({ task: "x", slug: "test", idleTimeoutMs: MAX_TIMER_DELAY_MS + 1 })).rejects.toThrow(
+      new RegExp(`${MAX_TIMER_DELAY_MS}`),
+    );
+    await expect(service.execute({ task: "x", slug: "test", idleTimeoutMs: 3_000_000_000 })).rejects.toThrow(/2\^31-1/);
+  });
+
+  it("execute rejects non-finite idleTimeoutMs", async () => {
+    await expect(service.execute({ task: "x", slug: "test", idleTimeoutMs: Number.NaN })).rejects.toThrow(/not a finite number/);
+  });
+
+  it("rejects before any record is created (no side effects)", async () => {
+    const internals = service as unknown as ServiceInternals;
+    await expect(service.executeAndAwait({ task: "x", slug: "test", idleTimeoutMs: 3_000_000_000 })).rejects.toThrow();
+    expect(internals.store.listRunning()).toHaveLength(0);
+  });
+
+  it("accepts valid values (0 = explicit disable, positive within limit)", async () => {
+    // 校验通过后执行链继续（runSpawn 被 mock，返回 undefined result 会在后续流程抛错/
+    // 返回——但绝不能是 idleTimeoutMs 校验错误）
+    await expect(service.execute({ task: "x", slug: "test", idleTimeoutMs: 0 })).rejects.not.toThrow(/idleTimeoutMs/);
+  });
+});
+
+describe("T4④ shutdown flush blocked → pending persisted for replay", () => {
+  let agentDir: string;
+  let service: SubagentService;
+  let pi: MockPi;
+
+  beforeEach(() => {
+    _resetNotifyLedgerForTest();
+    ({ agentDir, service, pi } = setup({ isIdle: () => false }));
+  });
+
+  afterEach(() => {
+    _resetNotifyLedgerForTest();
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("persists undelivered pending notifications as ledger entries on dispose when main agent is busy", () => {
+    // 绑定真 ledger 并制造一条未投递 pending（isIdle=false → attemptDeliver 挂回 pending）
+    const ledger = bindNotifyLedgerHost({
+      appendLedgerEntry: (customType, data) => pi.appendEntry(customType, data),
+      readSessionEntries: () => [],
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: (message) => pi.sendMessage(message as never),
+    });
+    const recorded = ledger.record("notify-1", "Subagent x completed", { id: "sa-x", agent: "x" });
+    expect(recorded).toBe(true);
+    expect(ledger.pendingEntries()).toHaveLength(1);
+
+    service.dispose();
+
+    // 复写落盘：NOTIFY_LEDGER_CUSTOM_TYPE entry 携带 notifyId（幂等键）+ v1 schema
+    const replayEntries = pi.appendEntry.mock.calls.filter(
+      (c) => c[0] === NOTIFY_LEDGER_CUSTOM_TYPE && (c[1] as { notifyId?: string })?.notifyId === "notify-1",
+    );
+    expect(replayEntries.length).toBeGreaterThanOrEqual(2); // record 原账 + dispose 复写
+    expect(replayEntries[0]?.[1]).toMatchObject({ v: 1, notifyId: "notify-1" });
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("persisted to ledger for replay"),
+      expect.objectContaining({ count: 1 }),
+    );
+    // 重启 replay 可重放：新 ledger 实例扫账面（含复写 entry）应入账该 pending
+    const host2 = {
+      appendLedgerEntry: vi.fn(),
+      readSessionEntries: () =>
+        pi.appendEntry.mock.calls
+          .filter((c) => c[0] === NOTIFY_LEDGER_CUSTOM_TYPE)
+          .map((c) => ({ type: "custom", customType: c[0], data: c[1] })),
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: vi.fn(),
+    };
+    const ledger2 = bindNotifyLedgerHost(host2);
+    expect(ledger2.recoverFromSession()).toBe(1);
+  });
+
+  it("does not rewrite when main agent is idle (flush already delivered)", () => {
+    const ledger = bindNotifyLedgerHost({
+      appendLedgerEntry: (customType, data) => pi.appendEntry(customType, data),
+      readSessionEntries: () => [],
+      isIdle: () => false,
+      onAgentSettled: () => {},
+      sendDelivery: (message) => pi.sendMessage(message as never),
+    });
+    ledger.record("notify-2", "content", { id: "sa-y" });
+    pi.appendEntry.mockClear();
+
+    // idle service：flush 投出（无门拦），dispose 无复写动作
+    const idleService = new SubagentService({
+      cwd: agentDir,
+      modelService: new ModelConfigService({ agentDir, cwd: agentDir }),
+    });
+    const piIdle = makePi();
+    idleService.initSession({ pi: piIdle, sessionId: "root-session", isIdle: () => true });
+    idleService.dispose();
+    expect(piIdle.appendEntry).not.toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/subagent-service-parent-guard.test.ts

@@ -26,10 +26,13 @@ const { loggerMock } = vi.hoisted(() => ({
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
 // mock session-runner（import 链需要 runSpawn/killAllSpawnedChildren/getChildByRecord 存在）
-vi.mock("../session-runner.ts", () => ({
+vi.mock("../engine/engines/pi/session-runner.ts", () => ({
   runSpawn: vi.fn(),
   killAllSpawnedChildren: vi.fn(),
   getChildByRecord: vi.fn(() => undefined),
+  registerSpawnedChildForRecord: vi.fn(),
+  killRecordChildWithEscalation: vi.fn(),
+  spawnedChildren: new Map(),
 }));
 
 import { createRecord } from "../execution-record.ts";
@@ -56,11 +59,12 @@ function makePi(): PiLike {
   } as unknown as PiLike;
 }
 
-/** 暴露私有字段供测试注入身份。 */
+/** 暴露私有字段供测试注入身份。[D3-⑤] 基线住进 execNesting（公共层
+ * ExecutionNestingContext），注入经 setBaseline 测试面。 */
 interface ServiceInternals {
   store: RecordStore;
   sessionRootId: string | null;
-  execCtxBaseline: { recordId: string | undefined; depth: number } | null;
+  execNesting: { setBaseline(state: { recordId: string | undefined; depth: number } | null): void };
 }
 
 /** 构造一个 chatMode idle record（message/close action 的典型目标态）。 */
@@ -74,12 +78,12 @@ function makeRecord(
     model: "test/model",
     mode: "background",
     task: "test",
-    slug: "test",
     startedAt: 1000,
     rootSessionId: sessionRootId,
     chatMode: true,
     controller: new AbortController(),
     ...overrides,
+    slug: overrides.slug ?? "test",
   });
 }
 
@@ -92,7 +96,7 @@ describe("[v4 A-5 / P7] getRecordForAction 直接父校验", () => {
 
   beforeEach(() => {
     agentDir = makeTmpAgentDir();
-    const modelService = new ModelConfigService({ agentDir });
+    const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     service = new SubagentService({ cwd: agentDir, modelService });
     // initSession 建立 sessionRootId=sessionId（本 session 树的根）。execCtxBaseline 的
     // 真实值由 initSession 从 env 读取（见 recursive-visibility-baseline.test.ts），但本测试
@@ -105,65 +109,65 @@ describe("[v4 A-5 / P7] getRecordForAction 直接父校验", () => {
 
   afterEach(() => {
     service.dispose();
-    fs.rmSync(agentDir, { recursive: true, force: true });
+    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   // ---------- 身份 sa-A：直接父，放行孙级 B ----------
 
   it("身份=sa-A（直接父）→ 放行操作孙级 record B（parentRecordId=sa-A）", () => {
-    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "idle" });
+    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "running" });
     store.register(recordB);
-    internals.execCtxBaseline = PARENT_A;
+    internals.execNesting.setBaseline(PARENT_A);
 
-    expect(service.getRecordForAction("sa-B")).toBe(recordB);
+    expect(service.chatActions.getRecordForAction("sa-B")).toBe(recordB);
   });
 
   // ---------- 身份 undefined（主进程）：拒绝孙级，放行根层 ----------
 
   it("身份=undefined（主进程）拒绝孙级 record B，错误含 'direct parent' + 'parent=sa-A'", () => {
-    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "idle" });
+    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "running" });
     store.register(recordB);
-    internals.execCtxBaseline = MAIN_PROCESS;
+    internals.execNesting.setBaseline(MAIN_PROCESS);
 
-    expect(() => service.getRecordForAction("sa-B")).toThrow(/direct parent/);
-    expect(() => service.getRecordForAction("sa-B")).toThrow(/see \/subagents list, parent=sa-A/);
+    expect(() => service.chatActions.getRecordForAction("sa-B")).toThrow(/direct parent/);
+    expect(() => service.chatActions.getRecordForAction("sa-B")).toThrow(/see \/subagents list, parent=sa-A/);
   });
 
   it("身份=undefined（主进程）放行顶层 record（parentRecordId=undefined 视为根层）", () => {
-    const topRecord = makeRecord("sa-top", sessionRootId, { parentRecordId: undefined, depth: 0, status: "idle" });
+    const topRecord = makeRecord("sa-top", sessionRootId, { parentRecordId: undefined, depth: 0, status: "running" });
     store.register(topRecord);
-    internals.execCtxBaseline = MAIN_PROCESS;
+    internals.execNesting.setBaseline(MAIN_PROCESS);
 
-    expect(service.getRecordForAction("sa-top")).toBe(topRecord);
+    expect(service.chatActions.getRecordForAction("sa-top")).toBe(topRecord);
   });
 
   // ---------- 身份 sa-B（兄弟进程）：拒绝孙级 ----------
 
   it("身份=sa-B（兄弟进程）拒绝孙级 record B（parentRecordId=sa-A ≠ baseline sa-B）", () => {
-    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "idle" });
+    const recordB = makeRecord("sa-B", sessionRootId, { parentRecordId: "sa-A", depth: 2, status: "running" });
     store.register(recordB);
-    internals.execCtxBaseline = SIBLING_B;
+    internals.execNesting.setBaseline(SIBLING_B);
 
-    expect(() => service.getRecordForAction("sa-B")).toThrow(/direct parent/);
-    expect(() => service.getRecordForAction("sa-B")).toThrow(/see \/subagents list, parent=sa-A/);
+    expect(() => service.chatActions.getRecordForAction("sa-B")).toThrow(/direct parent/);
+    expect(() => service.chatActions.getRecordForAction("sa-B")).toThrow(/see \/subagents list, parent=sa-A/);
   });
 
   // ---------- 身份缺省语义 + 更深递归 ----------
 
   it("子进程（baseline=sa-A）拒绝顶层 record（身份缺省视为根层，仅主进程可操作）", () => {
-    const topRecord = makeRecord("sa-top", sessionRootId, { parentRecordId: undefined, depth: 0, status: "idle" });
+    const topRecord = makeRecord("sa-top", sessionRootId, { parentRecordId: undefined, depth: 0, status: "running" });
     store.register(topRecord);
-    internals.execCtxBaseline = PARENT_A;
+    internals.execNesting.setBaseline(PARENT_A);
 
-    expect(() => service.getRecordForAction("sa-top")).toThrow(/direct parent/);
+    expect(() => service.chatActions.getRecordForAction("sa-top")).toThrow(/direct parent/);
   });
 
   it("P7 场景：主进程拒绝曾孙 record C（parentRecordId=sa-B），错误含 baseline=root + parent=sa-B", () => {
-    const recordC = makeRecord("sa-C", sessionRootId, { parentRecordId: "sa-B", depth: 3, status: "idle" });
+    const recordC = makeRecord("sa-C", sessionRootId, { parentRecordId: "sa-B", depth: 3, status: "running" });
     store.register(recordC);
-    internals.execCtxBaseline = MAIN_PROCESS;
+    internals.execNesting.setBaseline(MAIN_PROCESS);
 
-    const fn = () => service.getRecordForAction("sa-C");
+    const fn = () => service.chatActions.getRecordForAction("sa-C");
     expect(fn).toThrow(/direct parent/);
     expect(fn).toThrow(/see \/subagents list, parent=sa-B/);
     expect(fn).toThrow(/baseline=\(root\)/);
@@ -171,10 +175,10 @@ describe("[v4 A-5 / P7] getRecordForAction 直接父校验", () => {
 
   it("rootSessionId 不匹配仍优先拒绝（直接父校验在 rootSessionId 校验之后，不绕过归属守卫）", () => {
     // 跨 session 树的 record：rootSessionId 不匹配 → 走首个 throw（not found or not owned）
-    const foreignRecord = makeRecord("sa-foreign", "other-session", { parentRecordId: "sa-A", depth: 2, status: "idle" });
+    const foreignRecord = makeRecord("sa-foreign", "other-session", { parentRecordId: "sa-A", depth: 2, status: "running" });
     store.register(foreignRecord);
-    internals.execCtxBaseline = PARENT_A;
+    internals.execNesting.setBaseline(PARENT_A);
 
-    expect(() => service.getRecordForAction("sa-foreign")).toThrow(/not found or not owned/);
+    expect(() => service.chatActions.getRecordForAction("sa-foreign")).toThrow(/not found or not owned/);
   });
 });