pi-herdr-subagents 0.1.0

package/test/integration/harness.ts

@@ -0,0 +1,319 @@
+/**
+ * Integration test harness for pi-herdr-subagents.
+ *
+ * Provides utilities to:
+ * - Detect whether herdr is available
+ * - Create isolated test environments with test agent definitions
+ * - Start real pi sessions in herdr panes
+ * - Poll for file creation and screen output
+ * - Clean up surfaces and temp files after tests
+ */
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync,
+  mkdirSync,
+  cpSync,
+  readdirSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+  unlinkSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import {
+  isTerminalAvailable,
+  createSubagentPane,
+  runInPane,
+  runScriptInPane,
+  readPane,
+  readPaneAsync,
+  closePane,
+  interruptPane,
+  shellQuote,
+} from "../../pi-extension/subagents/terminal.ts";
+
+type MuxBackend = "herdr";
+
+// Re-export mux primitives for tests
+export {
+  createSubagentPane,
+  runInPane,
+  runScriptInPane,
+  readPane,
+  readPaneAsync,
+  closePane,
+  interruptPane,
+  shellQuote,
+};
+export type { MuxBackend };
+
+// ── Paths ──
+
+const HARNESS_DIR = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(HARNESS_DIR, "../..");
+const TEST_AGENTS_SRC = join(HARNESS_DIR, "agents");
+
+/**
+ * Absolute path to the extension source in the working tree.
+ *
+ * Integration tests must exercise the code on the current branch — NOT the
+ * version installed as a pi-package under `~/.pi/agent/git/...` or the project
+ * mirror under `.pi/git/...`, which stays pinned to the last released tag.
+ *
+ * We force-load this file via `pi -ne -e <path>` in startPi() below so local
+ * edits are always the code under test, regardless of what pi-packages are
+ * installed on the host.
+ */
+const EXTENSION_SOURCE = join(PROJECT_ROOT, "pi-extension", "subagents", "index.ts");
+
+// ── Configuration ──
+
+/** Model used for integration tests. Override with PI_TEST_MODEL env var. */
+export const TEST_MODEL = process.env.PI_TEST_MODEL ?? "openrouter/free";
+
+/** Per-test timeout in ms. Override with PI_TEST_TIMEOUT env var. */
+export const PI_TIMEOUT = Number(process.env.PI_TEST_TIMEOUT ?? "120000");
+
+// ── Backend detection ──
+
+/** Detect whether the required herdr backend is available. */
+export function getAvailableBackends(): MuxBackend[] {
+  return isTerminalAvailable() ? ["herdr"] : [];
+}
+
+export function setBackend(_backend: MuxBackend): undefined {
+  return undefined;
+}
+
+export function restoreBackend(_prev: string | undefined): void {}
+
+export function focusSurface(_backend: MuxBackend, surface: string): void {
+  // Focus the tab containing the pane — herdr has no direct "focus pane X"
+  // CLI, but focusing the tab brings it to the foreground.
+  const info = execFileSync("herdr", ["pane", "get", surface], { encoding: "utf8" });
+  const tabId = JSON.parse(info)?.result?.pane?.tab_id;
+  if (tabId) execFileSync("herdr", ["tab", "focus", tabId], { encoding: "utf8" });
+}
+
+export function getFocusedSurface(_backend: MuxBackend): string | null {
+  try {
+    const info = execFileSync("herdr", ["pane", "current"], { encoding: "utf8" });
+    return JSON.parse(info)?.result?.pane?.pane_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function getSurfacePane(_backend: MuxBackend, surface: string): string | null {
+  return surface;
+}
+
+export async function waitForFocusedSurface(
+  backend: MuxBackend,
+  surface: string,
+  timeout: number = PI_TIMEOUT,
+): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (getFocusedSurface(backend) === surface) return;
+    await sleep(200);
+  }
+
+  throw new Error(
+    `Timeout (${timeout}ms) waiting for focused ${backend} surface ${surface}; ` +
+      `current focus is ${getFocusedSurface(backend) ?? "unknown"}`,
+  );
+}
+
+// ── Test environment ──
+
+export interface TestEnv {
+  /** Temp directory serving as the test project root */
+  dir: string;
+  /** Active mux backend for this test run */
+  backend: MuxBackend;
+  /** Surfaces created during the test (cleaned up automatically) */
+  surfaces: string[];
+  /** Temp files to clean up */
+  tempFiles: string[];
+}
+
+/**
+ * Create an isolated test environment with test agent definitions.
+ * The temp dir has `.pi/agents/` containing copies of all test agents.
+ */
+export function createTestEnv(backend: MuxBackend): TestEnv {
+  const dir = mkdtempSync(join(tmpdir(), "pi-integ-"));
+  const agentsDir = join(dir, ".pi", "agents");
+  mkdirSync(agentsDir, { recursive: true });
+
+  // Copy test agent definitions into the project-local agents dir
+  if (existsSync(TEST_AGENTS_SRC)) {
+    for (const file of readdirSync(TEST_AGENTS_SRC)) {
+      if (file.endsWith(".md")) {
+        cpSync(join(TEST_AGENTS_SRC, file), join(agentsDir, file));
+      }
+    }
+  }
+
+  return { dir, backend, surfaces: [], tempFiles: [] };
+}
+
+/**
+ * Clean up all resources created during the test.
+ */
+export function cleanupTestEnv(env: TestEnv): void {
+  for (const surface of env.surfaces) {
+    try {
+      closePane(surface);
+    } catch {}
+  }
+  for (const file of env.tempFiles) {
+    try {
+      unlinkSync(file);
+    } catch {}
+  }
+  try {
+    rmSync(env.dir, { recursive: true, force: true });
+  } catch {}
+}
+
+/**
+ * Create a surface and register it for automatic cleanup.
+ */
+export function createTrackedSurface(env: TestEnv, name: string): string {
+  const surface = createSubagentPane(name);
+  env.surfaces.push(surface);
+  return surface;
+}
+
+/**
+ * Remove a surface from tracking (after manual close).
+ */
+export function untrackSurface(env: TestEnv, surface: string): void {
+  env.surfaces = env.surfaces.filter((s) => s !== surface);
+}
+
+// ── Pi session management ──
+
+/**
+ * Start a pi session in a herdr pane with the subagents extension loaded.
+ * Returns immediately — the pi process runs asynchronously in the surface.
+ *
+ * The command ends with a sentinel so we can detect when pi exits:
+ *   `pi ...; echo '__TEST_DONE_'$?'__'`
+ */
+export function startPi(
+  surface: string,
+  testDir: string,
+  task: string,
+  opts?: { model?: string; extraArgs?: string },
+): void {
+  const model = opts?.model ?? TEST_MODEL;
+  const extra = opts?.extraArgs ?? "";
+
+  // Force pi to load the working-tree extension (not an installed pi-package
+  // snapshot). `-ne` disables extension auto-discovery, `-e <path>` loads the
+  // current branch's source directly. Without this, the tests silently run
+  // against whatever version is checked out under `~/.pi/agent/git/...`.
+  const cmd = [
+    `cd ${shellQuote(testDir)} &&`,
+    `pi`,
+    `-ne`,
+    `-e ${shellQuote(EXTENSION_SOURCE)}`,
+    `--model ${shellQuote(model)}`,
+    extra,
+    shellQuote(task),
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  runScriptInPane(surface, `${cmd}; echo '__TEST_DONE_'$?'__'`, {
+    scriptPath: join(testDir, `test-launch-${Date.now()}.sh`),
+  });
+}
+
+// ── Polling helpers ──
+
+/**
+ * Poll until a regex pattern appears in the surface's screen output.
+ * Throws on timeout with the last screen contents for debugging.
+ */
+export async function waitForScreen(
+  surface: string,
+  pattern: RegExp,
+  timeout: number = PI_TIMEOUT,
+  lines: number = 200,
+): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const screen = await readPaneAsync(surface, lines);
+      if (pattern.test(screen)) return screen;
+    } catch {}
+    await sleep(2000);
+  }
+
+  let finalScreen = "";
+  try {
+    finalScreen = readPane(surface, lines);
+  } catch {}
+  throw new Error(
+    `Timeout (${timeout}ms) waiting for pattern ${pattern}.\nLast screen:\n${finalScreen.slice(-1000)}`,
+  );
+}
+
+/**
+ * Poll until a file exists and optionally matches a content pattern.
+ * Returns the file content on success.
+ */
+export async function waitForFile(
+  path: string,
+  timeout: number = PI_TIMEOUT,
+  contentPattern?: RegExp,
+): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    if (existsSync(path)) {
+      const content = readFileSync(path, "utf8");
+      if (!contentPattern || contentPattern.test(content)) return content;
+    }
+    await sleep(2000);
+  }
+  throw new Error(
+    `Timeout (${timeout}ms) waiting for file: ${path}` +
+      (contentPattern ? ` matching ${contentPattern}` : ""),
+  );
+}
+
+/**
+ * Wait for the pi process in a surface to exit (sentinel detection).
+ * Returns the exit code.
+ */
+export async function waitForPiExit(
+  surface: string,
+  timeout: number = PI_TIMEOUT,
+): Promise<number> {
+  const screen = await waitForScreen(surface, /__TEST_DONE_(\d+)__/, timeout);
+  const match = screen.match(/__TEST_DONE_(\d+)__/);
+  return match ? parseInt(match[1], 10) : -1;
+}
+
+// ── Utilities ──
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function uniqueId(): string {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+
+/**
+ * Register a temp file for cleanup.
+ */
+export function trackTempFile(env: TestEnv, path: string): void {
+  env.tempFiles.push(path);
+}

package/test/integration/mux-surface.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Integration tests for herdr terminal operations.
+ *
+ * These tests exercise real herdr operations: creating panes,
+ * sending commands, reading output, preserving focus, and closing panes.
+ * No LLM calls — fast and free.
+ *
+ * Run `npm run test:integration` from inside herdr.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { unlinkSync } from "node:fs";
+import {
+  getAvailableBackends,
+  setBackend,
+  restoreBackend,
+  createTestEnv,
+  cleanupTestEnv,
+  createTrackedSurface,
+  getFocusedSurface,
+  untrackSurface,
+  runInPane,
+  runScriptInPane,
+  readPane,
+  readPaneAsync,
+  closePane,
+  interruptPane,
+  sleep,
+  uniqueId,
+  trackTempFile,
+  waitForFile,
+  waitForScreen,
+  type TestEnv,
+} from "./harness.ts";
+
+const backends = getAvailableBackends();
+const FOCUS_TEST_SHELL_READY_DELAY_MS = Number(process.env.PI_SUBAGENT_SHELL_READY_DELAY_MS ?? "2500");
+
+if (backends.length === 0) {
+  console.log("⚠️  herdr is unavailable — skipping terminal integration tests");
+  console.log("   Run inside herdr to enable these tests.");
+}
+
+for (const backend of backends) {
+  describe(`herdr terminal [${backend}]`, { timeout: 60_000 }, () => {
+    let prevMux: string | undefined;
+    let env: TestEnv;
+
+    before(() => {
+      prevMux = setBackend(backend);
+      env = createTestEnv(backend);
+    });
+
+    after(() => {
+      cleanupTestEnv(env);
+      restoreBackend(prevMux);
+    });
+
+    it("keeps focus on the current pane while creating and targeting subagent tabs", async () => {
+      const focusedPane = getFocusedSurface(backend);
+      assert.ok(focusedPane, "Expected herdr to report the currently focused pane");
+
+      const childA = createTrackedSurface(env, "focus-child-a");
+      await sleep(FOCUS_TEST_SHELL_READY_DELAY_MS);
+      assert.equal(getFocusedSurface(backend), focusedPane);
+
+      const childB = createTrackedSurface(env, "focus-child-b");
+      await sleep(FOCUS_TEST_SHELL_READY_DELAY_MS);
+      assert.equal(getFocusedSurface(backend), focusedPane);
+
+      const markerA = uniqueId();
+      const markerB = uniqueId();
+      runInPane(childA, `echo "FOCUS_A_${markerA}"`);
+      runInPane(childB, `echo "FOCUS_B_${markerB}"`);
+
+      await Promise.all([
+        waitForScreen(childA, new RegExp(`FOCUS_A_${markerA}`), 20_000, 50),
+        waitForScreen(childB, new RegExp(`FOCUS_B_${markerB}`), 20_000, 50),
+      ]);
+      assert.equal(getFocusedSurface(backend), focusedPane);
+    });
+
+    it("creates a surface, sends a command, reads output, and closes it", async () => {
+      const surface = createTrackedSurface(env, "echo-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      runInPane(surface, `echo "MARKER_${marker}"`);
+      await sleep(1500);
+
+      const screen = readPane(surface, 50);
+      assert.ok(
+        screen.includes(`MARKER_${marker}`),
+        `Expected screen to contain MARKER_${marker}. Got:\n${screen}`,
+      );
+
+      closePane(surface);
+      untrackSurface(env, surface);
+    });
+
+    it("preserves shell special characters in echo output", async () => {
+      const surface = createTrackedSurface(env, "escape-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      // Single-quoted string — $ and " are literal inside single quotes
+      runInPane(surface, `echo 'SPEC_${marker}_$HOME_"quotes"_done'`);
+      await sleep(1500);
+
+      const screen = readPane(surface, 50);
+      assert.ok(
+        screen.includes(`SPEC_${marker}`),
+        `Expected special-char output. Got:\n${screen}`,
+      );
+      // $ should be literal inside single quotes
+      assert.ok(
+        screen.includes("$HOME"),
+        `Expected literal $HOME in output. Got:\n${screen}`,
+      );
+    });
+
+    it("sends a long command via script file without truncation", async () => {
+      const surface = createTrackedSurface(env, "long-cmd-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      const longValue = "X".repeat(500);
+      const command = `echo "LONG_${marker}_${longValue}_END"`;
+
+      runScriptInPane(surface, command);
+      await sleep(2000);
+
+      const screen = readPane(surface, 50);
+      assert.ok(
+        screen.includes(`LONG_${marker}`),
+        `Expected long command output. Got:\n${screen.slice(0, 300)}...`,
+      );
+      assert.ok(
+        screen.includes("_END"),
+        `Expected full output (not truncated). Got:\n${screen.slice(-300)}`,
+      );
+    });
+
+    it("reads screen asynchronously", async () => {
+      const surface = createTrackedSurface(env, "async-read-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      runInPane(surface, `echo "ASYNC_${marker}"`);
+      await sleep(1500);
+
+      const screen = await readPaneAsync(surface, 50);
+      assert.ok(
+        screen.includes(`ASYNC_${marker}`),
+        `Async read should find marker. Got:\n${screen}`,
+      );
+    });
+
+    it("manages multiple surfaces concurrently", async () => {
+      const s1 = createTrackedSurface(env, "multi-1");
+      const s2 = createTrackedSurface(env, "multi-2");
+      await sleep(1500);
+
+      const m1 = uniqueId();
+      const m2 = uniqueId();
+      runInPane(s1, `echo "S1_${m1}"`);
+      runInPane(s2, `echo "S2_${m2}"`);
+      await sleep(1500);
+
+      const screen1 = readPane(s1, 50);
+      const screen2 = readPane(s2, 50);
+
+      assert.ok(screen1.includes(`S1_${m1}`), `Surface 1 missing marker. Got:\n${screen1}`);
+      assert.ok(screen2.includes(`S2_${m2}`), `Surface 2 missing marker. Got:\n${screen2}`);
+    });
+
+    it("writes output to a file and verifies via surface", async () => {
+      const surface = createTrackedSurface(env, "file-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      const filePath = `/tmp/pi-mux-test-${marker}.txt`;
+
+      runInPane(surface, `echo "FILE_${marker}" > ${filePath} && echo "WRITTEN_${marker}"`);
+
+      await waitForScreen(surface, new RegExp(`WRITTEN_${marker}`), 10_000, 50);
+      const content = await waitForFile(filePath, 10_000, new RegExp(`FILE_${marker}`));
+      assert.ok(content.includes(`FILE_${marker}`), `File content wrong. Got: ${content}`);
+
+      // Clean up
+      try {
+        unlinkSync(filePath);
+      } catch {}
+    });
+
+    it("delivers Escape as byte 27 to the target surface", async () => {
+      const surface = createTrackedSurface(env, "escape-byte-test");
+      await sleep(1000);
+
+      const marker = uniqueId();
+      const byteFile = `/tmp/pi-mux-escape-${marker}.txt`;
+      trackTempFile(env, byteFile);
+
+      const nodeProgram =
+        "const fs = require('node:fs');" +
+        "if (!process.stdin.isTTY) throw new Error('stdin is not a TTY');" +
+        "process.stdin.setRawMode(true);" +
+        "process.stdin.resume();" +
+        "process.stdout.write('ESC_READY\\n');" +
+        "process.stdin.once('data', (chunk) => {" +
+        `fs.writeFileSync(${JSON.stringify(byteFile)}, Array.from(chunk).join(','));` +
+        "process.exit(0);" +
+        "});";
+      const command = `node -e ${JSON.stringify(nodeProgram)}`;
+
+      runScriptInPane(surface, command);
+      await waitForScreen(surface, /ESC_READY/, 15_000, 50);
+
+      interruptPane(surface);
+
+      const content = await waitForFile(byteFile, 15_000, /^27$/);
+      assert.equal(content.trim(), "27");
+    });
+  });
+}