@pi-unipi/subagents 2.4.0 → 2.5.0

package/src/__tests__/esc-propagation.test.ts

@@ -1,162 +0,0 @@
-/**
- * Test: ESC propagation — all children abort on parent ESC
- *
- * Verifies:
- * - forwardAbortSignal wires parent signal to child session
- * - abortAll stops all running agents
- * - All agents stop within reasonable time
- */
-
-import { describe, it, mock, beforeEach } from "node:test";
-import assert from "node:assert/strict";
-
-// Mock AbortController to track abort calls
-function createMockAbortController() {
-  let aborted = false;
-  const listeners: Array<() => void> = [];
-  return {
-    get signal() {
-      return {
-        aborted,
-        addEventListener: (_event: string, listener: () => void) => {
-          listeners.push(listener);
-        },
-        removeEventListener: (_event: string, listener: () => void) => {
-          const idx = listeners.indexOf(listener);
-          if (idx !== -1) listeners.splice(idx, 1);
-        },
-      };
-    },
-    abort() {
-      aborted = true;
-      for (const listener of listeners) listener();
-    },
-    get wasAborted() {
-      return aborted;
-    },
-  };
-}
-
-describe("ESC Propagation", () => {
-  describe("forwardAbortSignal", () => {
-    it("should call session.abort() when signal fires", () => {
-      // Simulate the forwardAbortSignal logic from agent-runner.ts
-      const sessionAborted = { value: false };
-      const session = { abort: () => { sessionAborted.value = true; } };
-      const controller = createMockAbortController();
-
-      // Wire abort signal
-      const onAbort = () => session.abort();
-      controller.signal.addEventListener("abort", onAbort);
-
-      // Trigger abort
-      controller.abort();
-
-      assert.equal(sessionAborted.value, true, "Session should be aborted");
-    });
-
-    it("should not call session.abort() if signal not fired", () => {
-      const sessionAborted = { value: false };
-      const session = { abort: () => { sessionAborted.value = true; } };
-      const controller = createMockAbortController();
-
-      const onAbort = () => session.abort();
-      controller.signal.addEventListener("abort", onAbort);
-
-      // Don't abort
-      assert.equal(sessionAborted.value, false, "Session should not be aborted");
-    });
-
-    it("should cleanup listener when returned function called", () => {
-      const controller = createMockAbortController();
-      let callCount = 0;
-      const onAbort = () => { callCount++; };
-      controller.signal.addEventListener("abort", onAbort);
-
-      // Simulate cleanup
-      const cleanup = () => controller.signal.removeEventListener("abort", onAbort);
-      cleanup();
-
-      controller.abort();
-      assert.equal(callCount, 0, "Listener should not fire after cleanup");
-    });
-  });
-
-  describe("abortAll", () => {
-    it("should abort all running agents", () => {
-      const agents = new Map<string, { abortController: ReturnType<typeof createMockAbortController>; status: string }>();
-
-      // Create 3 mock agents
-      for (let i = 0; i < 3; i++) {
-        const controller = createMockAbortController();
-        agents.set(`agent-${i}`, {
-          abortController: controller,
-          status: "running",
-        });
-      }
-
-      // Simulate abortAll
-      let abortedCount = 0;
-      for (const [id, record] of agents) {
-        if (record.status === "running") {
-          record.abortController.abort();
-          record.status = "stopped";
-          abortedCount++;
-        }
-      }
-
-      assert.equal(abortedCount, 3, "Should abort all 3 agents");
-      for (const [_, record] of agents) {
-        assert.equal(record.status, "stopped", "All agents should be stopped");
-        assert.equal(record.abortController.wasAborted, true, "All controllers should be aborted");
-      }
-    });
-
-    it("should handle queued agents by removing from queue", () => {
-      const queue = [
-        { id: "queued-1", status: "queued" },
-        { id: "queued-2", status: "queued" },
-      ];
-      const agents = new Map<string, { status: string }>();
-
-      for (const item of queue) {
-        agents.set(item.id, { status: item.status });
-      }
-
-      // Simulate abortAll for queued
-      for (const item of queue) {
-        const record = agents.get(item.id);
-        if (record) {
-          record.status = "stopped";
-        }
-      }
-      queue.length = 0;
-
-      assert.equal(queue.length, 0, "Queue should be empty");
-      for (const [_, record] of agents) {
-        assert.equal(record.status, "stopped", "All queued agents should be stopped");
-      }
-    });
-  });
-
-  describe("ESC timing", () => {
-    it("should abort within reasonable time", async () => {
-      const controller = createMockAbortController();
-      let abortedAt: number | null = null;
-      const startedAt = Date.now();
-
-      const onAbort = () => { abortedAt = Date.now(); };
-      controller.signal.addEventListener("abort", onAbort);
-
-      // Simulate abort after small delay
-      setTimeout(() => controller.abort(), 10);
-
-      // Wait for abort
-      await new Promise(resolve => setTimeout(resolve, 50));
-
-      assert.notEqual(abortedAt, null, "Should have aborted");
-      const elapsed = abortedAt! - startedAt;
-      assert.ok(elapsed < 500, `Abort should happen within 500ms, took ${elapsed}ms`);
-    });
-  });
-});

package/src/__tests__/file-lock.test.ts

@@ -1,244 +0,0 @@
-/**
- * Test: File locking — concurrent writes to same file queue correctly
- *
- * Verifies:
- * - Per-file locking works correctly
- * - Same file writes queue (second waits for first)
- * - Different file writes proceed in parallel
- * - Lock release unblocks waiting acquires
- * - releaseAll releases all locks for an agent
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-
-// Inline FileLock implementation for testing (avoids TS import issues)
-interface FileLockEntry {
-  agentId: string;
-  filePath: string;
-  promise: Promise<void>;
-  release: () => void;
-}
-
-class FileLock {
-  private locks = new Map<string, FileLockEntry>();
-  private queues = new Map<string, Array<() => void>>();
-
-  async acquire(filePath: string, agentId: string): Promise<() => void> {
-    while (this.locks.has(filePath)) {
-      await new Promise<void>((resolve) => {
-        const queue = this.queues.get(filePath) ?? [];
-        queue.push(resolve);
-        this.queues.set(filePath, queue);
-      });
-    }
-
-    let releaseFn: () => void;
-    const promise = new Promise<void>((resolve) => {
-      releaseFn = () => {
-        this.locks.delete(filePath);
-        resolve();
-        const queue = this.queues.get(filePath);
-        if (queue && queue.length > 0) {
-          const next = queue.shift()!;
-          next();
-        }
-      };
-    });
-
-    const entry: FileLockEntry = {
-      agentId,
-      filePath,
-      promise,
-      release: releaseFn!,
-    };
-
-    this.locks.set(filePath, entry);
-    return releaseFn!;
-  }
-
-  isLocked(filePath: string): boolean {
-    return this.locks.has(filePath);
-  }
-
-  getHolder(filePath: string): string | undefined {
-    return this.locks.get(filePath)?.agentId;
-  }
-
-  get lockCount(): number {
-    return this.locks.size;
-  }
-
-  releaseAll(agentId: string): void {
-    for (const [filePath, entry] of this.locks) {
-      if (entry.agentId === agentId) {
-        entry.release();
-      }
-    }
-  }
-
-  clear(): void {
-    for (const entry of this.locks.values()) {
-      entry.release();
-    }
-    this.locks.clear();
-    this.queues.clear();
-  }
-}
-
-describe("FileLock", () => {
-  describe("Basic locking", () => {
-    it("should acquire lock on unlocked file", async () => {
-      const lock = new FileLock();
-      const release = await lock.acquire("/src/auth.ts", "agent-1");
-
-      assert.equal(lock.isLocked("/src/auth.ts"), true);
-      assert.equal(lock.getHolder("/src/auth.ts"), "agent-1");
-      assert.equal(lock.lockCount, 1);
-
-      release();
-      assert.equal(lock.isLocked("/src/auth.ts"), false);
-    });
-
-    it("should track multiple locks on different files", async () => {
-      const lock = new FileLock();
-      const release1 = await lock.acquire("/src/auth.ts", "agent-1");
-      const release2 = await lock.acquire("/src/login.ts", "agent-2");
-
-      assert.equal(lock.lockCount, 2);
-      assert.equal(lock.getHolder("/src/auth.ts"), "agent-1");
-      assert.equal(lock.getHolder("/src/login.ts"), "agent-2");
-
-      release1();
-      release2();
-      assert.equal(lock.lockCount, 0);
-    });
-  });
-
-  describe("Queuing behavior", () => {
-    it("should queue second acquire on same file", async () => {
-      const lock = new FileLock();
-      const events: string[] = [];
-
-      // First acquire
-      const release1 = await lock.acquire("/src/auth.ts", "agent-1");
-      events.push("agent-1-acquired");
-
-      // Second acquire (should queue)
-      const acquire2Promise = lock.acquire("/src/auth.ts", "agent-2").then((release) => {
-        events.push("agent-2-acquired");
-        return release;
-      });
-
-      // agent-2 should not have acquired yet
-      assert.deepEqual(events, ["agent-1-acquired"]);
-
-      // Release first lock
-      release1();
-      events.push("agent-1-released");
-
-      // Wait for agent-2
-      const release2 = await acquire2Promise;
-      assert.deepEqual(events, ["agent-1-acquired", "agent-1-released", "agent-2-acquired"]);
-
-      release2();
-    });
-
-    it("should queue multiple acquires on same file", async () => {
-      const lock = new FileLock();
-      const events: string[] = [];
-
-      const release1 = await lock.acquire("/src/auth.ts", "agent-1");
-      events.push("1-acquired");
-
-      const p2 = lock.acquire("/src/auth.ts", "agent-2").then(r => { events.push("2-acquired"); return r; });
-      const p3 = lock.acquire("/src/auth.ts", "agent-3").then(r => { events.push("3-acquired"); return r; });
-
-      release1();
-      const release2 = await p2;
-      assert.deepEqual(events, ["1-acquired", "2-acquired"]);
-
-      release2();
-      const release3 = await p3;
-      assert.deepEqual(events, ["1-acquired", "2-acquired", "3-acquired"]);
-
-      release3();
-    });
-  });
-
-  describe("Parallel different files", () => {
-    it("should allow parallel writes to different files", async () => {
-      const lock = new FileLock();
-      const events: string[] = [];
-
-      // Both should acquire immediately (different files)
-      const release1 = await lock.acquire("/src/auth.ts", "agent-1");
-      events.push("auth-acquired");
-
-      const release2 = await lock.acquire("/src/login.ts", "agent-2");
-      events.push("login-acquired");
-
-      assert.deepEqual(events, ["auth-acquired", "login-acquired"]);
-      assert.equal(lock.lockCount, 2);
-
-      release1();
-      release2();
-    });
-  });
-
-  describe("releaseAll", () => {
-    it("should release all locks for a specific agent", async () => {
-      const lock = new FileLock();
-
-      // agent-1 holds 3 files
-      await lock.acquire("/src/a.ts", "agent-1");
-      await lock.acquire("/src/b.ts", "agent-1");
-      await lock.acquire("/src/c.ts", "agent-1");
-
-      // agent-2 holds 1 file
-      await lock.acquire("/src/d.ts", "agent-2");
-
-      assert.equal(lock.lockCount, 4);
-
-      // Release all for agent-1
-      lock.releaseAll("agent-1");
-
-      assert.equal(lock.lockCount, 1);
-      assert.equal(lock.isLocked("/src/a.ts"), false);
-      assert.equal(lock.isLocked("/src/b.ts"), false);
-      assert.equal(lock.isLocked("/src/c.ts"), false);
-      assert.equal(lock.isLocked("/src/d.ts"), true);
-    });
-
-    it("should unblock queued acquires when releasing all", async () => {
-      const lock = new FileLock();
-      const events: string[] = [];
-
-      const release1 = await lock.acquire("/src/a.ts", "agent-1");
-      const p2 = lock.acquire("/src/a.ts", "agent-2").then(r => { events.push("agent-2-acquired"); return r; });
-
-      // Release all for agent-1
-      lock.releaseAll("agent-1");
-
-      const release2 = await p2;
-      assert.deepEqual(events, ["agent-2-acquired"]);
-
-      release2();
-    });
-  });
-
-  describe("clear", () => {
-    it("should release all locks and clear queues", async () => {
-      const lock = new FileLock();
-
-      await lock.acquire("/src/a.ts", "agent-1");
-      await lock.acquire("/src/b.ts", "agent-2");
-
-      lock.clear();
-
-      assert.equal(lock.lockCount, 0);
-      assert.equal(lock.isLocked("/src/a.ts"), false);
-      assert.equal(lock.isLocked("/src/b.ts"), false);
-    });
-  });
-});

package/src/__tests__/shutdown-stale-ctx.test.ts

@@ -1,185 +0,0 @@
-/**
- * Test: background agents must not touch a stale extension runtime
- *
- * BUG — Pi crashed on exit with:
- *   "This extension ctx is stale after session replacement or reload."
- *   at pi.sendMessage (loader.js:240)
- *   at onComplete (packages/subagents/src/index.ts)
- *
- * Sequence:
- *  1. A background agent (e.g. the session-name generator) is still running.
- *  2. The user quits. Pi emits `session_shutdown`, then immediately calls
- *     `AgentSession.dispose()`, which invalidates the extension runtime.
- *  3. Our handler calls `abortAll()`, but aborting only *signals* the
- *     AbortController — the in-flight promise still settles on a later
- *     microtask and invokes the completion callback.
- *  4. That callback called `pi.sendMessage()`, which is `assertActive`-gated,
- *     so it threw from an async continuation with no catch → process crash.
- *
- * FIX — a `sessionEnded` flag set at the top of the `session_shutdown` handler
- * (before `abortAll()`), checked at the top of the completion callback, plus a
- * try/catch around `sendMessage` for the session-replacement race.
- *
- * The flag is scoped to the extension factory, not the module: `/new`,
- * `/fork` and `/resume` also emit `session_shutdown` and pi re-invokes the
- * factory for the replacement session, so a fresh closure resets it.
- * (Verified against pi 0.80.2: `/new` emits `shutdown reason=new`, then the
- * factory runs again with `ended=false`.)
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-
-const ROOT = join(import.meta.dirname, "../../../..");
-
-function readSource(relativePath: string): string {
-  const fullPath = join(ROOT, relativePath);
-  if (!existsSync(fullPath)) throw new Error(`File not found: ${fullPath}`);
-  return readFileSync(fullPath, "utf-8");
-}
-
-// ─── Behavioural: reproduce the race ────────────────────────────────
-
-/**
- * Minimal stand-in for pi's runtime: every `assertActive`-gated method throws
- * once the session has been disposed.
- */
-function createFakeRuntime() {
-  let stale = false;
-  return {
-    invalidate() {
-      stale = true;
-    },
-    sendMessage() {
-      if (stale) {
-        throw new Error(
-          "This extension ctx is stale after session replacement or reload.",
-        );
-      }
-      return { delivered: true };
-    },
-    setSessionName() {
-      if (stale) {
-        throw new Error(
-          "This extension ctx is stale after session replacement or reload.",
-        );
-      }
-    },
-    // pi.events is NOT assertActive-gated — it keeps working.
-    events: { emit() {} },
-  };
-}
-
-/**
- * Reproduces the extension's shutdown wiring.
- *
- * @param guard - whether to apply the `sessionEnded` fix
- */
-function simulateShutdownRace(guard: boolean) {
-  const pi = createFakeRuntime();
-  let sessionEnded = false;
-  const errors: Error[] = [];
-
-  // The completion callback registered with AgentManager.
-  const onComplete = () => {
-    if (guard && sessionEnded) return;
-    pi.sendMessage();
-  };
-
-  // A background agent whose promise is still pending at shutdown.
-  let settle!: () => void;
-  const inFlight = new Promise<void>((resolve) => {
-    settle = resolve;
-  }).then(() => {
-    try {
-      onComplete();
-    } catch (error) {
-      // In production this is an unhandled rejection that kills the process.
-      errors.push(error as Error);
-    }
-  });
-
-  // --- session_shutdown handler ---
-  if (guard) sessionEnded = true; // must be set BEFORE abortAll()
-  settle(); // abortAll(): signals abort; the promise settles a tick later
-  // --- pi disposes the session right after handlers resolve ---
-  pi.invalidate();
-
-  return { done: inFlight, errors };
-}
-
-describe("shutdown race — background agent completing after dispose", () => {
-  it("reproduces the stale-ctx crash without the guard", async () => {
-    const { done, errors } = simulateShutdownRace(false);
-    await done;
-
-    assert.equal(errors.length, 1, "expected the unguarded path to throw");
-    assert.match(errors[0].message, /stale after session replacement/);
-  });
-
-  it("does not touch the stale runtime with the guard", async () => {
-    const { done, errors } = simulateShutdownRace(true);
-    await done;
-
-    assert.deepEqual(errors, [], "guarded path must not throw");
-  });
-});
-
-// ─── Source contract: the wiring must stay correct ──────────────────
-
-describe("subagents shutdown wiring", () => {
-  const src = readSource("packages/subagents/src/index.ts");
-
-  it("declares the sessionEnded guard", () => {
-    assert.match(
-      src,
-      /let sessionEnded = false;/,
-      "expected a `sessionEnded` guard flag",
-    );
-  });
-
-  it("sets the guard before aborting, inside session_shutdown", () => {
-    const handler = src.match(
-      /pi\.on\(\s*"session_shutdown"[\s\S]*?\}\s*\);/,
-    )?.[0];
-    assert.ok(handler, "session_shutdown handler not found");
-
-    const guardIdx = handler.indexOf("sessionEnded = true");
-    const abortIdx = handler.indexOf("abortAll()");
-
-    assert.notEqual(guardIdx, -1, "handler must set sessionEnded = true");
-    assert.notEqual(abortIdx, -1, "handler must still call abortAll()");
-    assert.ok(
-      guardIdx < abortIdx,
-      "sessionEnded must be set BEFORE abortAll(), which settles in-flight promises",
-    );
-  });
-
-  it("checks the guard before any pi call in the completion callback", () => {
-    const guardIdx = src.indexOf("if (sessionEnded) return;");
-    assert.notEqual(guardIdx, -1, "completion callback must bail when sessionEnded");
-
-    const sendIdx = src.indexOf("pi.sendMessage");
-    assert.notEqual(sendIdx, -1, "expected a pi.sendMessage call");
-    assert.ok(
-      guardIdx < sendIdx,
-      "the guard must be checked before pi.sendMessage is reached",
-    );
-  });
-
-  it("wraps sendMessage in try/catch for the session-replacement race", () => {
-    const block = src.match(/try\s*\{\s*pi\.sendMessage[\s\S]*?\}\s*catch\s*\{[\s\S]*?\}/);
-    assert.ok(
-      block,
-      "pi.sendMessage must be wrapped in try/catch — a notification is best-effort",
-    );
-  });
-
-  it("keeps setSessionName defensively wrapped", () => {
-    // Badge generation also runs on a background agent.
-    const block = src.match(/try\s*\{\s*pi\.setSessionName[\s\S]*?\}\s*catch/);
-    assert.ok(block, "pi.setSessionName must stay wrapped in try/catch");
-  });
-});