@rohaquinlop/pi-subagents 0.5.0 → 0.5.1

package/index.ts

@@ -19,6 +19,9 @@ import { discoverAgents, mergeAgents, substitutePlaceholders, formatConnectorCon
 import { zeroUsage, accumulateUsage, validateAgents, MAX_LOOP_CONTEXT, parseJudgeVerdict } from "./lib/pipeline-helpers";
 import { buildSubagentErrorContent, buildPipelineErrorContent, buildLoopErrorContent } from "./lib/error-helpers";
 import { detectCycle } from "./lib/loop-detector";
+import { extractCycleSignature, LOOP_PRIOR_ITERATIONS_HEADER } from "./lib/cycle-signature";
+import { validateAgentGraphAcyclicity } from "./lib/agent-graph";
+import { checkDepth } from "./lib/depth-limit";
 
 interface ToolEvent {
 	tool: string;
@@ -83,6 +86,7 @@ interface ExtensionConfig {
 	maxConcurrency?: number;
 	subagentTimeoutMs?: number;      // wall-clock, default 600000 (10 min). 0 = disabled.
 	subagentIdleTimeoutMs?: number;  // no-stdout watchdog, default 300000 (5 min). 0 = disabled.
+	maxSubagentDepth?: number;       // max nesting depth, default 8. Hard backstop against recursion loops.
 }
 
 const EXT_DIR = path.dirname(new URL(import.meta.url).pathname);
@@ -379,6 +383,15 @@ async function buildPiArgs(
 	cwd: string,
 ): Promise<{ args: string[]; tempDir: string; childEnv: NodeJS.ProcessEnv }> {
 	const piBin = resolvePiBinary();
+
+	// Depth check (before resource allocation to avoid temp-dir leaks on throw)
+	const currentDepth = parseInt(process.env.PI_SUBAGENT_DEPTH || "0", 10);
+	const maxDepth = extensionConfig.maxSubagentDepth ?? 8;
+	const depthResult = checkDepth(currentDepth, maxDepth);
+	if (!depthResult.allowed) {
+		throw new Error(depthResult.error!);
+	}
+
 	const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-sub-"));
 
 	// Write system prompt to temp file
@@ -460,6 +473,8 @@ async function buildPiArgs(
 		childEnv.PI_SUBAGENT_ALLOWED = agent.subagentAgents.join(",");
 	}
 
+	childEnv.PI_SUBAGENT_DEPTH = String(depthResult.newDepth);
+
 	return { args: [piBin.command, ...args], tempDir, childEnv };
 }
 
@@ -565,6 +580,13 @@ async function runSubagent(
 		let childClosed = false;
 		let sigkillTimer: ReturnType<typeof setTimeout> | undefined;
 		let callHistory: string[] = [];	// sliding window of tool-call signatures for cycle detection
+		// NOTE: Cycle detection is PER-CHILD — each runSubagent() call has its own
+		// fresh callHistory. Cross-step loops in pipeline (A→B→A→B) and cross-iteration
+		// re-delegation in loop are NOT caught by the tool-call detector. They are
+		// bounded instead by: pipeline's 2-5 step cap, loop's 2-5 iteration cap, the
+		// depth cap (default 8), and wall-clock (10 min) + idle (5 min) timeouts.
+		// This is a deliberate tradeoff — per-child detection avoids false positives
+		// from parallel siblings sharing history.
 
 		const safeResolve = (code: number) => {
 			if (resolved) return;
@@ -643,7 +665,7 @@ async function runSubagent(
 					// ── Cycle detection (parent-side, context-free) ──
 					// Signature = toolName + args preview. Two calls with different args
 					// (different file, or same file different content) → different sig.
-					const sig = `${evt.toolName}:${extractToolArgsPreview((evt.args || {}) as Record<string, unknown>)}`;
+					const sig = extractCycleSignature(evt.toolName, (evt.args || {}) as Record<string, unknown>);
 					const cycleResult = detectCycle(callHistory, sig);
 					callHistory.push(sig);
 					if (callHistory.length > 24) callHistory = callHistory.slice(-24);
@@ -1145,7 +1167,7 @@ async function runLoop(
 				}
 			}
 			const contextBlock = keptOutputs.join("\n\n");
-			fullTask = `${task}\n\n## Prior iterations:\n${contextBlock}`;
+			fullTask = `${task}\n\n${LOOP_PRIOR_ITERATIONS_HEADER}\n${contextBlock}`;
 		}
 
 		const iterStart = Date.now();
@@ -1375,6 +1397,13 @@ export default function (pi: ExtensionAPI) {
 	semaphore = new Semaphore(extensionConfig.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
 	agents = loadAgents();
 
+	// Validate agent graph acyclicity (warning only — depth cap backstops recursion)
+	const cycleError = validateAgentGraphAcyclicity(agents);
+	if (cycleError) {
+		console.error(`[pi-subagents] WARNING: ${cycleError}`);
+		console.error(`[pi-subagents] The depth cap (maxSubagentDepth=${extensionConfig.maxSubagentDepth ?? 8}) prevents infinite recursion, but this agent configuration should be fixed.`);
+	}
+
 	// If spawned as a child by a parent subagent process, PI_SUBAGENT_ALLOWED
 	// pins which agents we're allowed to expose. Filter the registry now, before
 	// any tool description sees the agent list — the child LLM should not even

package/lib/agent-graph.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent graph validation — detects cycles in agent delegation graphs.
+ *
+ * Uses WHITE/GRAY/BLACK DFS coloring to detect back edges (GRAY neighbor = cycle).
+ * Returns null if acyclic, or a human-readable cycle string if cyclic.
+ */
+import type { AgentConfig } from "./types";
+
+type Color = "white" | "gray" | "black";
+
+/**
+ * Validate that the agent delegation graph is acyclic.
+ *
+ * Builds a directed graph from agent.subagentAgents references and runs
+ * DFS cycle detection. Handles: self-loops, 2-node cycles, N-node cycles,
+ * disconnected components, and references to agents not in the graph
+ * (skipped — they're external/leaf nodes).
+ *
+ * @param agents Array of agent configurations
+ * @returns null if acyclic, or a human-readable cycle string like
+ *          "Cycle detected in agent delegation graph: A → B → A"
+ */
+export function validateAgentGraphAcyclicity(agents: AgentConfig[]): string | null {
+    // Build adjacency list from agent configs
+    const agentNames = new Set(agents.map((a) => a.name));
+    const graph = new Map<string, string[]>();
+
+    for (const agent of agents) {
+        const targets = agent.subagentAgents ?? [];
+        // Filter out references to non-existent agents (external/leaf nodes)
+        graph.set(agent.name, targets.filter((t) => agentNames.has(t)));
+    }
+
+    // WHITE/GRAY/BLACK DFS coloring
+    const color = new Map<string, Color>();
+    const parent = new Map<string, string | null>();
+
+    for (const name of agentNames) {
+        color.set(name, "white");
+    }
+
+    // DFS from each unvisited node (handles disconnected components)
+    for (const start of agentNames) {
+        if (color.get(start) !== "white") continue;
+
+        // Iterative DFS using explicit stack
+        // Stack entries: [node, iterator index into neighbors]
+        const stack: Array<{ node: string; neighborIdx: number }> = [];
+        stack.push({ node: start, neighborIdx: 0 });
+        color.set(start, "gray");
+        parent.set(start, null);
+
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = graph.get(frame.node) ?? [];
+
+            if (frame.neighborIdx < neighbors.length) {
+                const neighbor = neighbors[frame.neighborIdx];
+                frame.neighborIdx++;
+
+                if (color.get(neighbor) === "gray") {
+                    // Back edge found — reconstruct cycle path
+                    const cyclePath = reconstructCyclePath(stack, neighbor);
+                    return `Cycle detected in agent delegation graph: ${cyclePath}`;
+                }
+
+                if (color.get(neighbor) === "white") {
+                    color.set(neighbor, "gray");
+                    parent.set(neighbor, frame.node);
+                    stack.push({ node: neighbor, neighborIdx: 0 });
+                }
+                // If black, it's a cross/forward edge — skip
+            } else {
+                // All neighbors explored — backtrack
+                color.set(frame.node, "black");
+                stack.pop();
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Reconstruct the cycle path from the DFS stack when a back edge is found.
+ * The back edge goes from the current top of stack to `target`.
+ * The cycle is: target → ... → top → target
+ */
+function reconstructCyclePath(
+    stack: Array<{ node: string; neighborIdx: number }>,
+    target: string,
+): string {
+    // Find target in the stack
+    let targetIdx = -1;
+    for (let i = 0; i < stack.length; i++) {
+        if (stack[i].node === target) {
+            targetIdx = i;
+            break;
+        }
+    }
+
+    if (targetIdx === -1) {
+        // Self-loop case: target is the current node
+        return `${target} → ${target}`;
+    }
+
+    // Build path from target to current top, then back to target
+    const path: string[] = [];
+    for (let i = targetIdx; i < stack.length; i++) {
+        path.push(stack[i].node);
+    }
+    path.push(target);
+
+    return path.join(" → ");
+}

package/lib/cycle-signature.ts

@@ -0,0 +1,153 @@
+/**
+ * Cycle-detection signature builder for tool calls.
+ *
+ * Unlike `extractToolArgsPreview` (optimized for TUI display), this module
+ * retains distinguishing arguments so that different calls doing different
+ * work produce different signatures (no false positives) while identical
+ * re-invocations collapse (true positives preserved).
+ */
+import * as crypto from "node:crypto";
+
+/**
+ * Header injected by the loop tool when accumulating prior iteration context
+ * into a subagent task. Shared here so normalizeTaskForSignature stays in sync
+ * with the injection site in index.ts — changing one without the other would
+ * silently break loop-context stripping (false-negative loop detection).
+ */
+export const LOOP_PRIOR_ITERATIONS_HEADER = "## Prior iterations:";
+
+/**
+ * Deterministic 48-bit fingerprint (12 hex chars) via SHA-256.
+ * Used for cycle-detection signatures: same input → same fingerprint,
+ * different inputs → different fingerprints (collision-resistant enough
+ * for a 24-entry sliding window).
+ */
+export function taskFingerprint(str: string): string {
+    return crypto.createHash("sha256").update(str, "utf8").digest("hex").slice(0, 12);
+}
+
+/**
+ * Conservatively normalize a subagent task string for cycle-signature hashing.
+ * Strips injected connector context (## Prior iterations:, ## Key findings,
+ * ## Implementation results, ## Research findings) which varies per invocation
+ * but is not the "real" task, then collapses whitespace and lowercases.
+ * Preserves the core task instruction.
+ *
+ * Limitation: only strips the 4 known headers. A user-defined agent with a
+ * connector header NOT in this set would leave its {previous} content in the
+ * task hash, causing two identical logical tasks with varying prior context to
+ * produce different hashes — the detector could miss a loop (false negative).
+ * This is a deliberate tradeoff (conservative normalization preserves real task
+ * instructions; aggressive stripping risks over-collapsing different tasks).
+ * Residual risk is bounded by loop/pipeline/depth/timeout caps.
+ */
+export function normalizeTaskForSignature(task: string): string {
+    const stripped = task
+        .replace(new RegExp(LOOP_PRIOR_ITERATIONS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "[\\s\\S]*$", "m"), "")
+        .replace(/## Key findings[\s\S]*$/m, "")
+        .replace(/## Implementation results[\s\S]*$/m, "")
+        .replace(/## Research findings[\s\S]*$/m, "");
+    return stripped.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+/** Collapse any whitespace run (incl. newlines) into a single space. */
+function flatten(s: string): string {
+    return s.replace(/\s+/g, " ").trim();
+}
+
+const MAX_CYCLE_SIG_COMPONENT = 120;
+
+/**
+ * Build a cycle-detection signature for a tool call. Unlike extractToolArgsPreview
+ * (optimized for TUI display), this retains distinguishing arguments so that
+ * different calls doing different work produce different signatures (no false
+ * positives) while identical re-invocations collapse (true positives preserved).
+ * Components are capped to bound memory in the 24-entry sliding window.
+ */
+export function extractCycleSignature(toolName: string, args: Record<string, unknown>): string {
+    const cap = (s: string, max: number = MAX_CYCLE_SIG_COMPONENT) =>
+        s.length > max ? s.slice(0, max) : s;
+
+    switch (toolName) {
+        case "bash":
+        case "safe_bash": {
+            const cmd = cap(flatten(String(args.command || "")));
+            const cwd = args.cwd ? `:${cap(flatten(String(args.cwd)), 60)}` : "";
+            return `${toolName}:${cmd}${cwd}`;
+        }
+        case "read": {
+            // Include offset (and limit) so pagination of the same file is progress, not a loop.
+            const p = cap(flatten(String(args.path || "")));
+            const offset = args.offset ?? 0;
+            const limit = args.limit ?? "";
+            return `read:${p}@${offset}${limit !== "" ? "/" + limit : ""}`;
+        }
+        case "write": {
+            const p = cap(flatten(String(args.path || "")));
+            const contentHash = args.content
+                ? taskFingerprint(String(args.content).slice(0, 1000))
+                : "nocontent";
+            return `write:${p}:${contentHash}`;
+        }
+        case "edit": {
+            const p = cap(flatten(String(args.path || "")));
+            let body = "";
+            if (Array.isArray(args.edits) && args.edits.length > 0) {
+                body = (args.edits as Array<{ newText?: string; new_string?: string }>)
+                    .map((e) => String(e?.newText || e?.new_string || ""))
+                    .join("\n");
+            } else {
+                body = String(args.newText || args.new_string || args.content || "");
+            }
+            const contentHash = body ? taskFingerprint(body.slice(0, 500)) : "noedit";
+            return `edit:${p}:${contentHash}`;
+        }
+        case "grep": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            const ex = args.exclude ? `!${cap(flatten(String(args.exclude)), 40)}` : "";
+            return `grep:${pat}${p}${ex}`;
+        }
+        case "find":
+        case "fffind": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            return `${toolName}:${pat}${p}`;
+        }
+        case "ffgrep": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            return `ffgrep:${pat}${p}`;
+        }
+        case "ls": {
+            return `ls:${cap(flatten(String(args.path || ".")))}`;
+        }
+        case "web_search": {
+            return `web_search:${cap(flatten(String(args.query || "")))}`;
+        }
+        case "web_fetch": {
+            return `web_fetch:${cap(flatten(String(args.url || "")))}`;
+        }
+        case "subagent": {
+            // CRITICAL: include task fingerprint so different delegations are distinguishable.
+            const agent = flatten(String(args.agent || ""));
+            const taskHash = args.task
+                ? taskFingerprint(normalizeTaskForSignature(String(args.task)))
+                : "notask";
+            return `subagent:${agent}:${taskHash}`;
+        }
+        case "gh_cli": {
+            return `gh_cli:${cap(flatten(String(args.command || "")))}`;
+        }
+        case "read_pdf": {
+            return `read_pdf:${cap(flatten(String(args.path || "")))}`;
+        }
+        case "clarification_ui": {
+            return `clarification_ui:${cap(flatten(JSON.stringify(args)))}`;
+        }
+        default: {
+            const s = JSON.stringify(args);
+            return `${toolName}:${cap(flatten(s))}`;
+        }
+    }
+}

package/lib/depth-limit.ts

@@ -0,0 +1,35 @@
+/**
+ * Depth-limiting logic for subagent nesting.
+ *
+ * Pure helper functions for checking and propagating subagent depth.
+ * Extracted for testability — the actual depth enforcement happens in
+ * buildPiArgs() in index.ts.
+ */
+
+export interface DepthCheckResult {
+    allowed: boolean;
+    newDepth: number;
+    error?: string;
+}
+
+/**
+ * Check whether a new subagent spawn is allowed given the current depth and max.
+ *
+ * @param currentDepth The current nesting depth (from PI_SUBAGENT_DEPTH env var)
+ * @param maxDepth The maximum allowed depth (from config or default of 8)
+ * @returns DepthCheckResult with allowed flag, newDepth, and optional error message
+ */
+export function checkDepth(currentDepth: number, maxDepth: number): DepthCheckResult {
+    const newDepth = currentDepth + 1;
+    if (newDepth > maxDepth) {
+        return {
+            allowed: false,
+            newDepth,
+            error:
+                `Subagent depth limit exceeded (${newDepth} > ${maxDepth}). ` +
+                `This likely indicates a recursion loop in agent delegation. ` +
+                `Set maxSubagentDepth in config.json to increase the limit.`,
+        };
+    }
+    return { allowed: true, newDepth };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rohaquinlop/pi-subagents",
-    "version": "0.5.0",
+    "version": "0.5.1",
     "description": "Pi extension for delegating tasks to subagents — parallel execution, agent discovery, and TUI rendering",
     "keywords": [
         "pi-package",