@rohaquinlop/pi-subagents 0.3.0 → 0.5.0

package/lib/error-helpers.ts

@@ -0,0 +1,66 @@
+/**
+ * Error-message helpers for subagent tool returns.
+ *
+ * pi-agent-core drops the `isError` flag on normal tool returns, so `content`
+ * is the only reliable channel to communicate failure context back to the main
+ * LLM. These helpers build clear, actionable messages so the LLM can retry,
+ * redirect, or report.
+ */
+
+/** Minimal shape the helper needs from a subagent result. */
+interface SubagentErrorResult {
+	agent: string;
+	exitCode: number;
+	output: string;
+	progress: {
+		error?: string;
+		lastMessage?: string;
+	};
+}
+
+/**
+ * Build a clear, actionable error message for the main LLM when a single
+ * subagent fails. The `content` channel is the only reliable one (pi-agent-core
+ * drops a returned `isError` flag on normal tool returns), so this must carry
+ * enough context for the LLM to retry, redirect, or report.
+ */
+export function buildSubagentErrorContent(result: SubagentErrorResult): string {
+	const parts: string[] = [];
+	parts.push(`[Subagent error] Agent "${result.agent}" failed (exit code ${result.exitCode}).`);
+	if (result.progress.error) {
+		parts.push(`Error: ${result.progress.error}`);
+	}
+	if (result.progress.lastMessage) {
+		parts.push(`Last message: ${result.progress.lastMessage}`);
+	}
+	if (result.output && result.output !== "(no output)") {
+		parts.push(`Output:\n${result.output}`);
+	}
+	return parts.join("\n");
+}
+
+export function buildPipelineErrorContent(
+	stepIndex: number,
+	stepAgent: string,
+	result: { exitCode: number; output: string; progress: { error?: string } },
+): string {
+	return [
+		`Pipeline failed at step ${stepIndex + 1} (agent: ${stepAgent}).`,
+		`Exit code: ${result.exitCode}`,
+		result.progress.error ? `Error: ${result.progress.error}` : null,
+		result.output ? `Output:\n${result.output}` : "(no output)",
+	].filter(Boolean).join("\n");
+}
+
+export function buildLoopErrorContent(
+	iteration: number,
+	agentName: string,
+	result: { exitCode: number; output: string; progress: { error?: string } },
+): string {
+	return [
+		`Loop failed at iteration ${iteration + 1} (agent: ${agentName}).`,
+		`Exit code: ${result.exitCode}`,
+		result.progress.error ? `Error: ${result.progress.error}` : null,
+		result.output ? `Output:\n${result.output}` : "(no output)",
+	].filter(Boolean).join("\n");
+}

package/lib/helpers.ts

@@ -50,8 +50,11 @@ export function parseAgentMd(content: string, filePath: string): AgentConfig | n
     const subagentAgents = fields.subagent_agents
         ? normalizeTools(fields.subagent_agents)
         : undefined;
+    const connector = fields.connector
+        ? fields.connector.replace(/^"|"$/g, "")
+        : undefined;
 
-    return { name, description, tools, model, thinking, systemPrompt, filePath, subagentAgents };
+    return { name, description, tools, model, thinking, systemPrompt, filePath, subagentAgents, connector };
 }
 
 /**
@@ -90,6 +93,34 @@ export function mergeAgents(builtIn: AgentConfig[], user: AgentConfig[]): AgentC
     return Array.from(byName.values());
 }
 
+/**
+ * Replace {previous} placeholder in a task string with the prior step's output.
+ * Truncation happens here — this is the single truncation point.
+ */
+export function substitutePlaceholders(
+    task: string,
+    previousOutput: string,
+    maxContextChars: number = 16000,
+): string {
+    const truncated = previousOutput.length > maxContextChars
+        ? previousOutput.slice(0, maxContextChars) + "\n\n[Context truncated for pipeline]"
+        : previousOutput;
+    return task.replace(/\{previous\}/g, truncated);
+}
+
+/**
+ * Format an agent's output using its connector template.
+ * Pure formatting function — does NOT truncate. Truncation is handled
+ * by substitutePlaceholders() before this is called.
+ */
+export function formatConnectorContext(
+    output: string,
+    connectorTemplate?: string,
+): string {
+    if (!connectorTemplate) return output;
+    return connectorTemplate.replace(/\{output\}/g, output);
+}
+
 /**
  * Parses PI_SUBAGENT_ALLOWED env var into a Set of agent names.
  * Returns null if the env var is not set or empty (meaning no restriction).

package/lib/loop-detector.ts

@@ -0,0 +1,40 @@
+/**
+ * Cycle detector for tool-call streams. Watches a sliding window of
+ * tool-call signatures for a sub-sequence of length P repeated 3 times
+ * (P in [2,8]). Catches an agent stuck in a tool-call loop without
+ * imposing any count cap on legitimate work. Purely parent-side.
+ */
+const WINDOW_SIZE = 24;
+const MIN_PATTERN_LEN = 2;
+const MAX_PATTERN_LEN = 8;
+const REPETITIONS = 3;
+
+export interface CycleResult {
+    cycle: boolean;
+    pattern?: string[];   // the repeating sub-sequence of signatures (length P)
+}
+
+/**
+ * Detect whether `newSig` completes a 3× cycle. Pure: does NOT mutate `history`.
+ * The caller pushes `newSig` onto its own history AFTER calling this.
+ */
+export function detectCycle(history: string[], newSig: string): CycleResult {
+    const window = [...history, newSig];
+    const start = Math.max(0, window.length - WINDOW_SIZE);
+    const w = window.slice(start);
+    for (let p = MIN_PATTERN_LEN; p <= MAX_PATTERN_LEN; p++) {
+        const needed = p * REPETITIONS;
+        if (w.length < needed) continue;
+        const tail = w.slice(-needed);
+        const pattern = tail.slice(0, p);
+        let isCycle = true;
+        for (let i = 0; i < p; i++) {
+            if (pattern[i] !== tail[p + i] || pattern[i] !== tail[2 * p + i]) {
+                isCycle = false;
+                break;
+            }
+        }
+        if (isCycle) return { cycle: true, pattern };
+    }
+    return { cycle: false };
+}

package/lib/pipeline-helpers.ts

@@ -0,0 +1,53 @@
+import type { AgentConfig, AgentUsage } from "./types";
+
+/**
+ * Create a zeroed-out AgentUsage object.
+ */
+export function zeroUsage(): AgentUsage {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+
+/**
+ * Accumulate usage from one step/iteration into the running total.
+ */
+export function accumulateUsage(total: AgentUsage, step: AgentUsage): AgentUsage {
+    return {
+        input: total.input + step.input,
+        output: total.output + step.output,
+        cacheRead: total.cacheRead + step.cacheRead,
+        cacheWrite: total.cacheWrite + step.cacheWrite,
+        cost: total.cost + step.cost,
+        turns: total.turns + step.turns,
+    };
+}
+
+/**
+ * Validate that all referenced agent names exist in the loaded agents array.
+ * Returns the first missing agent name, or null if all are valid.
+ */
+export function validateAgents(
+    agentNames: string[],
+    agents: AgentConfig[],
+): string | null {
+    for (const name of agentNames) {
+        if (!agents.some((a) => a.name === name)) return name;
+    }
+    return null;
+}
+
+/**
+ * Maximum total characters for accumulated loop context (prior iteration outputs).
+ * When exceeded, oldest iterations are dropped first, keeping only the last 2–3.
+ */
+export const MAX_LOOP_CONTEXT = 48000;
+
+/**
+ * Parse a judge agent's response to determine if it signals satisfaction.
+ * Extracts the first non-empty line, strips markdown formatting, and checks
+ * for word-boundary YES match. Returns false on any parse failure.
+ */
+export function parseJudgeVerdict(response: string): boolean {
+    const firstLine = response.split('\n').find(l => l.trim()) || '';
+    const cleaned = firstLine.replace(/[*_`#]/g, '').trim().toUpperCase();
+    return /\bYES\b/.test(cleaned);
+}

package/lib/types.ts

@@ -7,4 +7,57 @@ export interface AgentConfig {
     systemPrompt: string;
     filePath: string;
     subagentAgents?: string[];
+    connector?: string;  // Single-line prompt template, e.g. "## Findings\n\n{output}"
+}
+
+export interface AgentUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+}
+
+export interface PipelineStep {
+    agent: string;
+    task: string;  // May contain {previous} placeholder
+    connector?: string;  // Override agent's default connector for this step
+}
+
+export interface PipelineStepResult {
+    agent: string;
+    task: string;
+    output: string;
+    exitCode: number;
+    usage: AgentUsage;
+    durationMs: number;
+}
+
+export interface PipelineResult {
+    steps: PipelineStepResult[];
+    currentStep?: number;  // Present during live execution updates
+    finalOutput: string;
+    stoppedAt?: number;  // 0-indexed step where pipeline stopped (on error)
+    error?: string;  // Error message if pipeline failed
+    totalUsage: AgentUsage;
+    totalDurationMs: number;
+}
+
+export interface LoopIterationResult {
+    iteration: number;
+    output: string;
+    exitCode: number;
+    usage: AgentUsage;
+    durationMs: number;
+    judgeVerdict?: { satisfied: boolean; response: string };  // Present when judge is configured
+}
+
+export interface LoopResult {
+    iterations: LoopIterationResult[];
+    currentIteration?: number;  // Present during live execution updates
+    finalOutput: string;
+    stoppedBecause: "max_iterations" | "judge_satisfied" | "error";
+    totalUsage: AgentUsage;
+    totalDurationMs: number;
 }

package/package.json

@@ -1,42 +1,42 @@
 {
-  "name": "@rohaquinlop/pi-subagents",
-  "version": "0.3.0",
-  "description": "Pi extension for delegating tasks to subagents — parallel execution, agent discovery, and TUI rendering",
-  "keywords": [
-    "pi-package",
-    "subagent",
-    "parallel",
-    "coding-agent",
-    "extension"
-  ],
-  "license": "MIT",
-  "author": "rohaquinlop",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rohaquinlop/pi-subagents.git"
-  },
-  "files": [
-    "index.ts",
-    "agents/",
-    "tools/",
-    "lib/",
-    "README.md"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "vitest": "^3.2.0"
-  }
+    "name": "@rohaquinlop/pi-subagents",
+    "version": "0.5.0",
+    "description": "Pi extension for delegating tasks to subagents — parallel execution, agent discovery, and TUI rendering",
+    "keywords": [
+        "pi-package",
+        "subagent",
+        "parallel",
+        "coding-agent",
+        "extension"
+    ],
+    "license": "MIT",
+    "author": "rohaquinlop",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rohaquinlop/pi-subagents.git"
+    },
+    "files": [
+        "index.ts",
+        "agents/",
+        "tools/",
+        "lib/",
+        "README.md"
+    ],
+    "pi": {
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*",
+        "@sinclair/typebox": "*"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "devDependencies": {
+        "vitest": "^3.2.0"
+    }
 }

package/tools/safe-bash.ts

@@ -6,6 +6,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createBashTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
+const DEFAULT_SAFE_BASH_TIMEOUT_S = 300; // 5 minutes — kills stuck commands instead of relying on the 10-min wall-clock
+
 const DANGEROUS_PATTERNS = [
 	/\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
 	/\brm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
@@ -46,7 +48,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			command: Type.String({ description: "Bash command to execute" }),
 			timeout: Type.Optional(
-				Type.Number({ description: "Timeout in seconds (optional)" }),
+				Type.Number({ description: "Timeout in seconds (default: 300s/5min; pass a larger value for builds/tests/installs)" }),
 			),
 		}),
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -54,7 +56,8 @@ export default function (pi: ExtensionAPI) {
 			if (danger) {
 				throw new Error(danger);
 			}
-			return bashTool.execute(toolCallId, params, signal, onUpdate);
+			const timeout = params.timeout ?? DEFAULT_SAFE_BASH_TIMEOUT_S;
+			return bashTool.execute(toolCallId, { ...params, timeout }, signal, onUpdate);
 		},
 	});
 }