pi-herdr-subagents 0.1.0

package/test/integration/subagent-lifecycle.test.ts

@@ -0,0 +1,329 @@
+/**
+ * Integration tests for the full subagent lifecycle.
+ *
+ * These tests spawn real pi sessions with real LLM calls.
+ * Each test creates a herdr pane, runs pi with a task that uses the subagent
+ * tool, and verifies the outcome through marker files and terminal output.
+ *
+ * Duration: ~30-120s per test, depending on the selected model.
+ *
+ * Run `npm run test:integration` from inside herdr.
+ *
+ * Configuration:
+ *   PI_TEST_MODEL     — model for all pi sessions (default: openrouter/free)
+ *   PI_TEST_TIMEOUT   — per-test timeout in ms (default: 120000)
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import {
+  getAvailableBackends,
+  setBackend,
+  restoreBackend,
+  createTestEnv,
+  cleanupTestEnv,
+  createTrackedSurface,
+  startPi,
+  waitForScreen,
+  waitForFile,
+  sleep,
+  uniqueId,
+  trackTempFile,
+  readPane,
+  PI_TIMEOUT,
+  type TestEnv,
+} from "./harness.ts";
+
+const backends = getAvailableBackends();
+
+if (backends.length === 0) {
+  console.log("⚠️  herdr is unavailable — skipping subagent lifecycle integration tests");
+  console.log("   Run inside herdr to enable these tests.");
+}
+
+for (const backend of backends) {
+  describe(`subagent-lifecycle [${backend}]`, { timeout: PI_TIMEOUT * 3 }, () => {
+    let prevMux: string | undefined;
+    let env: TestEnv;
+
+    before(() => {
+      prevMux = setBackend(backend);
+      env = createTestEnv(backend);
+    });
+
+    after(() => {
+      cleanupTestEnv(env);
+      restoreBackend(prevMux);
+    });
+
+    // ── Basic spawn + completion ──
+
+    it("spawns a subagent that writes a file and verifies the session", async () => {
+      const id = uniqueId();
+      const markerFile = `/tmp/pi-integ-echo-${id}.txt`;
+      trackTempFile(env, markerFile);
+
+      const surface = createTrackedSurface(env, `echo-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `Call the subagent tool with these EXACT parameters:`,
+        `  name: "Echo-${id}"`,
+        `  agent: "test-echo"`,
+        `  task: "Run this bash command: echo 'PASS_${id}' > '${markerFile}'"`,
+        `Do not do anything else. Just call the subagent tool once.`,
+        `After you receive the subagent result, say INTEGRATION_COMPLETE.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      // Verify: subagent created the marker file
+      const content = await waitForFile(markerFile, PI_TIMEOUT, /PASS/);
+      assert.ok(
+        content.includes(`PASS_${id}`),
+        `Marker file should contain PASS_${id}. Got: ${content.trim()}`,
+      );
+
+      // Verify: outer pi received the subagent result
+      const screen = await waitForScreen(
+        surface,
+        /INTEGRATION_COMPLETE|completed|Sub-agent.*"Echo/i,
+        PI_TIMEOUT,
+      );
+
+      // Verify: session file was created (shown in steer result)
+      const sessionMatch = screen.match(/Session:\s*(\S+\.jsonl)/);
+      if (sessionMatch) {
+        const sessionFile = sessionMatch[1];
+        assert.ok(existsSync(sessionFile), `Subagent session file should exist: ${sessionFile}`);
+
+        const lines = readFileSync(sessionFile, "utf8").trim().split("\n");
+        assert.ok(lines.length >= 2, `Session should have ≥2 entries, got ${lines.length}`);
+
+        const header = JSON.parse(lines[0]);
+        assert.equal(header.type, "session", "First entry should be session header");
+        assert.ok(header.id, "Session header should have an id");
+      }
+    });
+
+    // ── In-progress activity snapshots ──
+
+    it("keeps a long active tool call from surfacing false stalled status", async () => {
+      const id = uniqueId();
+      const startFile = `/tmp/pi-integ-status-start-${id}.txt`;
+      const markerFile = `/tmp/pi-integ-status-${id}.txt`;
+      trackTempFile(env, startFile);
+      trackTempFile(env, markerFile);
+
+      const surface = createTrackedSurface(env, `status-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `Call the subagent tool with these EXACT parameters:`,
+        `  name: "Status-${id}"`,
+        `  agent: "test-echo"`,
+        `  task: "Run this bash command: echo 'START_${id}' > '${startFile}'; sleep 90; echo 'STATUS_${id}' > '${markerFile}'"`,
+        `Do not do anything else. Just call the subagent tool once.`,
+        `After you receive the subagent result, say STATUS_TEST_DONE.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      const activeScreen = await waitForScreen(surface, /active[\s\S]*bash|bash[\s\S]*active/i, PI_TIMEOUT, 300);
+      assert.doesNotMatch(activeScreen, /Subagent status[\s\S]*stalled|stalled[\s\S]*Subagent status/i);
+
+      await waitForFile(startFile, PI_TIMEOUT, /START_/);
+      assert.equal(existsSync(markerFile), false, "Completion marker should not exist before the long sleep");
+      await sleep(65_000);
+      assert.equal(existsSync(markerFile), false, "Completion marker should not exist before the watchdog assertion");
+      const watchdogScreen = readPane(surface, 300);
+      assert.doesNotMatch(watchdogScreen, /Subagent status[\s\S]*stalled|stalled[\s\S]*Subagent status/i);
+
+      const content = await waitForFile(markerFile, PI_TIMEOUT, /STATUS_/);
+      assert.ok(content.includes(`STATUS_${id}`), `Marker file should contain STATUS_${id}`);
+
+      const completionScreen = await waitForScreen(
+        surface,
+        /STATUS_TEST_DONE|completed|Sub-agent.*"Status-/i,
+        PI_TIMEOUT,
+        300,
+      );
+      assert.ok(/STATUS_TEST_DONE|completed/i.test(completionScreen));
+    });
+
+    // ── Parallel subagent spawn ──
+
+    it("spawns two subagents in parallel and both complete", async () => {
+      const id = uniqueId();
+      const fileA = `/tmp/pi-integ-para-${id}-a.txt`;
+      const fileB = `/tmp/pi-integ-para-${id}-b.txt`;
+      trackTempFile(env, fileA);
+      trackTempFile(env, fileB);
+
+      const surface = createTrackedSurface(env, `parallel-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `You must call the subagent tool TWICE. Make both calls before waiting for results.`,
+        ``,
+        `First call:`,
+        `  name: "ParaA-${id}"`,
+        `  agent: "test-echo"`,
+        `  task: "Run: echo 'DONE_A_${id}' > '${fileA}'"`,
+        ``,
+        `Second call:`,
+        `  name: "ParaB-${id}"`,
+        `  agent: "test-echo"`,
+        `  task: "Run: echo 'DONE_B_${id}' > '${fileB}'"`,
+        ``,
+        `Call both subagent tools NOW, do not wait between them.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      // Both marker files should appear
+      const [contentA, contentB] = await Promise.all([
+        waitForFile(fileA, PI_TIMEOUT, /DONE_A/),
+        waitForFile(fileB, PI_TIMEOUT, /DONE_B/),
+      ]);
+
+      assert.ok(contentA.includes(`DONE_A_${id}`), `File A should contain marker`);
+      assert.ok(contentB.includes(`DONE_B_${id}`), `File B should contain marker`);
+    });
+
+    // ── Fork mode ──
+
+    it("fork mode creates a child session linked to the parent", async () => {
+      const id = uniqueId();
+      const markerFile = `/tmp/pi-integ-fork-${id}.txt`;
+      trackTempFile(env, markerFile);
+
+      const surface = createTrackedSurface(env, `fork-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `Call the subagent tool with these EXACT parameters:`,
+        `  name: "Fork-${id}"`,
+        `  fork: true`,
+        `  task: "Run this bash command: echo 'FORK_OK_${id}' > '${markerFile}'"`,
+        `Do not set the agent parameter. Just set name, fork, and task.`,
+        `After you receive the result, say FORK_COMPLETE.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      // Verify: forked subagent created the file
+      const content = await waitForFile(markerFile, PI_TIMEOUT, /FORK_OK/);
+      assert.ok(content.includes(`FORK_OK_${id}`), `Fork marker file should exist with content`);
+
+      // Wait for the outer pi to show the result
+      const screen = await waitForScreen(
+        surface,
+        /FORK_COMPLETE|completed|Sub-agent.*"Fork/i,
+        PI_TIMEOUT,
+      );
+
+      // Verify: the forked session has a parent link
+      const sessionMatch = screen.match(/Session:\s*(\S+\.jsonl)/);
+      if (sessionMatch) {
+        const sessionFile = sessionMatch[1];
+        assert.ok(existsSync(sessionFile), `Fork session file should exist: ${sessionFile}`);
+
+        const entries = readFileSync(sessionFile, "utf8")
+          .trim()
+          .split("\n")
+          .map((l) => JSON.parse(l));
+        const header = entries[0];
+        assert.equal(header.type, "session", "First entry should be session header");
+        assert.ok(header.parentSession, "Fork session should have parentSession field");
+        // Fork sessions include parent context (model_change entries etc.)
+        assert.ok(entries.length >= 2, "Fork session should have context entries beyond header");
+      }
+    });
+
+    // ── caller_ping ──
+
+    it("subagent caller_ping sends notification back to the parent", async () => {
+      const id = uniqueId();
+
+      const surface = createTrackedSurface(env, `ping-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `Call the subagent tool with these EXACT parameters:`,
+        `  name: "Ping-${id}"`,
+        `  agent: "test-ping"`,
+        `  task: "PING_TEST_${id}"`,
+        `Just call the subagent tool once. Do not do anything else before calling it.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      // The test-ping agent calls caller_ping, which steers a "needs help" message
+      // back to the outer pi. Look for it on screen.
+      const screen = await waitForScreen(
+        surface,
+        /needs help|PING|caller_ping|ping/i,
+        PI_TIMEOUT,
+      );
+
+      assert.ok(
+        /needs help|PING/i.test(screen),
+        `Screen should show ping notification. Got:\n${screen.slice(-800)}`,
+      );
+    });
+
+    // ── Agent discovery ──
+
+    it("subagent discovers project-local test agents", async () => {
+      const id = uniqueId();
+      const markerFile = `/tmp/pi-integ-discovery-${id}.txt`;
+      trackTempFile(env, markerFile);
+
+      const surface = createTrackedSurface(env, `discovery-${id}`);
+      await sleep(1000);
+
+      // Use subagents_list to verify test agents are discoverable,
+      // then spawn one to prove it works end-to-end.
+      const task = [
+        `First, call the subagents_list tool to see available agents.`,
+        `Then call the subagent tool:`,
+        `  name: "Disco-${id}"`,
+        `  agent: "test-echo"`,
+        `  task: "Run: echo 'DISCO_${id}' > '${markerFile}'"`,
+        `After you receive the subagent result, say DISCOVERY_DONE.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      // The test-echo agent (discovered from project .pi/agents/) should work
+      const content = await waitForFile(markerFile, PI_TIMEOUT, /DISCO/);
+      assert.ok(content.includes(`DISCO_${id}`), `Discovery test marker should exist`);
+    });
+
+    // ── Subagent with custom system prompt ──
+
+    it("passes systemPrompt to subagent", async () => {
+      const id = uniqueId();
+      const markerFile = `/tmp/pi-integ-sysprompt-${id}.txt`;
+      trackTempFile(env, markerFile);
+
+      const surface = createTrackedSurface(env, `sysprompt-${id}`);
+      await sleep(1000);
+
+      const task = [
+        `Call the subagent tool with these parameters:`,
+        `  name: "SysP-${id}"`,
+        `  agent: "test-echo"`,
+        `  systemPrompt: "Always start your response with CUSTOM_PROMPT_ACTIVE."`,
+        `  task: "Write 'SYSPROMPT_${id}' to ${markerFile} using bash: echo 'SYSPROMPT_${id}' > '${markerFile}'"`,
+        `After the subagent completes, say SYSPROMPT_TEST_DONE.`,
+      ].join("\n");
+
+      startPi(surface, env.dir, task);
+
+      const content = await waitForFile(markerFile, PI_TIMEOUT, /SYSPROMPT/);
+      assert.ok(content.includes(`SYSPROMPT_${id}`), `System prompt test marker should exist`);
+    });
+  });
+}

package/test/system-prompt-mode.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Smoke tests for the systemPromptMode feature.
+ * Tests: frontmatter parsing, identity routing, CLI flag generation.
+ */
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, msg: string) {
+  if (condition) {
+    console.log(`  ✅ ${msg}`);
+    passed++;
+  } else {
+    console.log(`  ❌ ${msg}`);
+    failed++;
+  }
+}
+
+// --- Extracted logic under test ---
+
+function parseFrontmatter(content: string) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const frontmatter = match[1];
+  const get = (key: string) => {
+    const m = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    return m ? m[1].trim() : undefined;
+  };
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
+  const spm = get("system-prompt");
+  return {
+    systemPromptMode: spm === "replace" ? "replace" : spm === "append" ? "append" : undefined,
+    body: body || undefined,
+  };
+}
+
+function simulateRouting(
+  agentBody: string | undefined,
+  systemPromptMode: "append" | "replace" | undefined,
+  paramSystemPrompt: string | undefined,
+) {
+  const identity = agentBody ?? paramSystemPrompt ?? null;
+  const identityInSystemPrompt = systemPromptMode && identity;
+  const roleBlock = identity && !identityInSystemPrompt ? `\n\n${identity}` : "";
+
+  let cliFlag: string | null = null;
+  if (identityInSystemPrompt && identity) {
+    cliFlag = systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt";
+  }
+
+  return { roleBlock, cliFlag, identityInSystemPrompt: !!identityInSystemPrompt };
+}
+
+// --- Fixtures ---
+
+const AGENT_REPLACE = `---
+model: anthropic/claude-sonnet-4-20250514
+system-prompt: replace
+auto-exit: true
+---
+
+You are a specialized agent.`;
+
+const AGENT_APPEND = `---
+model: anthropic/claude-sonnet-4-20250514
+system-prompt: append
+---
+
+You are an appended identity.`;
+
+const AGENT_DEFAULT = `---
+model: anthropic/claude-sonnet-4-20250514
+---
+
+You are a default agent.`;
+
+const AGENT_INVALID = `---
+model: anthropic/claude-sonnet-4-20250514
+system-prompt: foobar
+---
+
+Body here.`;
+
+// --- Test 1: Frontmatter parsing ---
+console.log("\n🧪 Frontmatter parsing of system-prompt field");
+
+const r1 = parseFrontmatter(AGENT_REPLACE)!;
+assert(r1.systemPromptMode === "replace", "system-prompt: replace → mode is 'replace'");
+assert(r1.body === "You are a specialized agent.", "body extracted correctly");
+
+const r2 = parseFrontmatter(AGENT_APPEND)!;
+assert(r2.systemPromptMode === "append", "system-prompt: append → mode is 'append'");
+
+const r3 = parseFrontmatter(AGENT_DEFAULT)!;
+assert(r3.systemPromptMode === undefined, "no system-prompt field → mode is undefined");
+
+const r4 = parseFrontmatter(AGENT_INVALID)!;
+assert(r4.systemPromptMode === undefined, "system-prompt: foobar → mode is undefined (ignored)");
+
+// --- Test 2: Identity routing ---
+console.log("\n🧪 Identity routing (system prompt vs user message)");
+
+const s1 = simulateRouting("You are X.", "replace", undefined);
+assert(s1.roleBlock === "", "replace mode: roleBlock empty (not in task)");
+assert(s1.cliFlag === "--system-prompt", "replace mode: uses --system-prompt flag");
+
+const s2 = simulateRouting("You are X.", "append", undefined);
+assert(s2.roleBlock === "", "append mode: roleBlock empty (not in task)");
+assert(s2.cliFlag === "--append-system-prompt", "append mode: uses --append-system-prompt flag");
+
+const s3 = simulateRouting("You are X.", undefined, undefined);
+assert(s3.roleBlock === "\n\nYou are X.", "no mode: roleBlock contains identity");
+assert(s3.cliFlag === null, "no mode: no CLI flag");
+
+const s4 = simulateRouting(undefined, undefined, undefined);
+assert(s4.roleBlock === "", "no identity: roleBlock empty");
+assert(s4.cliFlag === null, "no identity: no CLI flag");
+
+const s5 = simulateRouting(undefined, "replace", undefined);
+assert(s5.roleBlock === "", "mode set but no body: roleBlock empty");
+assert(s5.cliFlag === null, "mode set but no body: no CLI flag");
+
+const s6 = simulateRouting(undefined, "replace", "Param identity");
+assert(s6.cliFlag === "--system-prompt", "mode + param systemPrompt: uses CLI flag");
+assert(s6.roleBlock === "", "mode + param systemPrompt: roleBlock empty");
+
+// --- Test 3: End-to-end with temp agent files ---
+console.log("\n🧪 End-to-end with temp agent files");
+
+const tmpDir = mkdtempSync(join(tmpdir(), "pi-test-spm-"));
+const agentsDir = join(tmpDir, ".pi", "agents");
+mkdirSync(agentsDir, { recursive: true });
+
+writeFileSync(join(agentsDir, "test-replace.md"), AGENT_REPLACE);
+writeFileSync(join(agentsDir, "test-append.md"), AGENT_APPEND);
+writeFileSync(join(agentsDir, "test-default.md"), AGENT_DEFAULT);
+
+function loadFromDir(name: string) {
+  const p = join(agentsDir, `${name}.md`);
+  if (!existsSync(p)) return null;
+  return parseFrontmatter(readFileSync(p, "utf8"));
+}
+
+const t1 = loadFromDir("test-replace")!;
+assert(t1.systemPromptMode === "replace", "file test-replace.md → replace mode");
+assert(t1.body === "You are a specialized agent.", "file test-replace.md → body correct");
+
+const t2 = loadFromDir("test-append")!;
+assert(t2.systemPromptMode === "append", "file test-append.md → append mode");
+
+const t3 = loadFromDir("test-default")!;
+assert(t3.systemPromptMode === undefined, "file test-default.md → no mode");
+
+rmSync(tmpDir, { recursive: true });
+
+// --- Summary ---
+console.log(`\n${"=".repeat(40)}`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);
+console.log("All tests passed! ✅\n");