pi-subagents 0.3.0 → 0.3.2

package/types.ts

@@ -1,3 +1,13 @@
+/**
+ * Type definitions for the subagent extension
+ */
+
+import type { Message } from "@mariozechner/pi-ai";
+
+// ============================================================================
+// Basic Types
+// ============================================================================
+
 export interface MaxOutputConfig {
 	bytes?: number;
 	lines?: number;
@@ -11,6 +21,25 @@ export interface TruncationResult {
 	artifactPath?: string;
 }
 
+export interface Usage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+export interface TokenUsage {
+	input: number;
+	output: number;
+	total: number;
+}
+
+// ============================================================================
+// Progress Tracking
+// ============================================================================
+
 export interface AgentProgress {
 	index: number;
 	agent: string;
@@ -33,6 +62,52 @@ export interface ProgressSummary {
 	durationMs: number;
 }
 
+// ============================================================================
+// Results
+// ============================================================================
+
+export interface SingleResult {
+	agent: string;
+	task: string;
+	exitCode: number;
+	messages: Message[];
+	usage: Usage;
+	model?: string;
+	error?: string;
+	sessionFile?: string;
+	progress?: AgentProgress;
+	progressSummary?: ProgressSummary;
+	artifactPaths?: ArtifactPaths;
+	truncation?: TruncationResult;
+}
+
+export interface Details {
+	mode: "single" | "parallel" | "chain";
+	results: SingleResult[];
+	asyncId?: string;
+	asyncDir?: string;
+	progress?: AgentProgress[];
+	progressSummary?: ProgressSummary;
+	artifacts?: {
+		dir: string;
+		files: ArtifactPaths[];
+	};
+	truncation?: {
+		truncated: boolean;
+		originalBytes?: number;
+		originalLines?: number;
+		artifactPath?: string;
+	};
+	// Chain metadata for observability
+	chainAgents?: string[];      // Agent names in order, e.g., ["scout", "planner"]
+	totalSteps?: number;         // Total steps in chain
+	currentStepIndex?: number;   // 0-indexed current step (for running chains)
+}
+
+// ============================================================================
+// Artifacts
+// ============================================================================
+
 export interface ArtifactPaths {
 	inputPath: string;
 	outputPath: string;
@@ -49,6 +124,85 @@ export interface ArtifactConfig {
 	cleanupDays: number;
 }
 
+// ============================================================================
+// Async Execution
+// ============================================================================
+
+export interface AsyncStatus {
+	runId: string;
+	mode: "single" | "chain";
+	state: "queued" | "running" | "complete" | "failed";
+	startedAt: number;
+	endedAt?: number;
+	lastUpdate?: number;
+	currentStep?: number;
+	steps?: Array<{ agent: string; status: string; durationMs?: number; tokens?: TokenUsage }>;
+	sessionDir?: string;
+	outputFile?: string;
+	totalTokens?: TokenUsage;
+	sessionFile?: string;
+}
+
+export interface AsyncJobState {
+	asyncId: string;
+	asyncDir: string;
+	status: "queued" | "running" | "complete" | "failed";
+	mode?: "single" | "chain";
+	agents?: string[];
+	currentStep?: number;
+	stepsTotal?: number;
+	startedAt?: number;
+	updatedAt?: number;
+	sessionDir?: string;
+	outputFile?: string;
+	totalTokens?: TokenUsage;
+	sessionFile?: string;
+}
+
+// ============================================================================
+// Display
+// ============================================================================
+
+export type DisplayItem = 
+	| { type: "text"; text: string } 
+	| { type: "tool"; name: string; args: Record<string, unknown> };
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+export interface ErrorInfo {
+	hasError: boolean;
+	exitCode?: number;
+	errorType?: string;
+	details?: string;
+}
+
+// ============================================================================
+// Execution Options
+// ============================================================================
+
+export interface RunSyncOptions {
+	cwd?: string;
+	signal?: AbortSignal;
+	onUpdate?: (r: import("@mariozechner/pi-agent-core").AgentToolResult<Details>) => void;
+	maxOutput?: MaxOutputConfig;
+	artifactsDir?: string;
+	artifactConfig?: ArtifactConfig;
+	runId: string;
+	index?: number;
+	sessionDir?: string;
+	share?: boolean;
+}
+
+export interface ExtensionConfig {
+	asyncByDefault?: boolean;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
 export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
 	bytes: 200 * 1024,
 	lines: 5000,
@@ -63,6 +217,18 @@ export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
 	cleanupDays: 7,
 };
 
+export const MAX_PARALLEL = 8;
+export const MAX_CONCURRENCY = 4;
+export const RESULTS_DIR = "/tmp/pi-async-subagent-results";
+export const ASYNC_DIR = "/tmp/pi-async-subagent-runs";
+export const WIDGET_KEY = "subagent-async";
+export const POLL_INTERVAL_MS = 250;
+export const MAX_WIDGET_JOBS = 4;
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
 export function formatBytes(bytes: number): string {
 	if (bytes < 1024) return `${bytes}B`;
 	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;

package/utils.ts

@@ -0,0 +1,325 @@
+/**
+ * General utility functions for the subagent extension
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@mariozechner/pi-ai";
+import type { AsyncStatus, DisplayItem, ErrorInfo } from "./types.js";
+
+// ============================================================================
+// File System Utilities
+// ============================================================================
+
+// Cache for status file reads - avoid re-reading unchanged files
+const statusCache = new Map<string, { mtime: number; status: AsyncStatus }>();
+
+/**
+ * Read async job status from disk (with mtime-based caching)
+ */
+export function readStatus(asyncDir: string): AsyncStatus | null {
+	const statusPath = path.join(asyncDir, "status.json");
+	try {
+		const stat = fs.statSync(statusPath);
+		const cached = statusCache.get(statusPath);
+		if (cached && cached.mtime === stat.mtimeMs) {
+			return cached.status;
+		}
+		const content = fs.readFileSync(statusPath, "utf-8");
+		const status = JSON.parse(content) as AsyncStatus;
+		statusCache.set(statusPath, { mtime: stat.mtimeMs, status });
+		// Limit cache size to prevent memory leaks
+		if (statusCache.size > 50) {
+			const firstKey = statusCache.keys().next().value;
+			if (firstKey) statusCache.delete(firstKey);
+		}
+		return status;
+	} catch {
+		return null;
+	}
+}
+
+// Cache for output tail reads - avoid re-reading unchanged files
+const outputTailCache = new Map<string, { mtime: number; size: number; lines: string[] }>();
+
+/**
+ * Get the last N lines from an output file (with mtime/size-based caching)
+ */
+export function getOutputTail(outputFile: string | undefined, maxLines: number = 3): string[] {
+	if (!outputFile) return [];
+	let fd: number | null = null;
+	try {
+		const stat = fs.statSync(outputFile);
+		if (stat.size === 0) return [];
+
+		// Check cache using both mtime and size (size changes more frequently during writes)
+		const cached = outputTailCache.get(outputFile);
+		if (cached && cached.mtime === stat.mtimeMs && cached.size === stat.size) {
+			return cached.lines;
+		}
+
+		const tailBytes = 4096;
+		const start = Math.max(0, stat.size - tailBytes);
+		fd = fs.openSync(outputFile, "r");
+		const buffer = Buffer.alloc(Math.min(tailBytes, stat.size));
+		fs.readSync(fd, buffer, 0, buffer.length, start);
+		const content = buffer.toString("utf-8");
+		const allLines = content.split("\n").filter((l) => l.trim());
+		const lines = allLines.slice(-maxLines).map((l) => l.slice(0, 120) + (l.length > 120 ? "..." : ""));
+
+		// Cache the result
+		outputTailCache.set(outputFile, { mtime: stat.mtimeMs, size: stat.size, lines });
+		// Limit cache size
+		if (outputTailCache.size > 20) {
+			const firstKey = outputTailCache.keys().next().value;
+			if (firstKey) outputTailCache.delete(firstKey);
+		}
+
+		return lines;
+	} catch {
+		return [];
+	} finally {
+		if (fd !== null) {
+			try {
+				fs.closeSync(fd);
+			} catch {}
+		}
+	}
+}
+
+/**
+ * Get human-readable last activity time for a file
+ */
+export function getLastActivity(outputFile: string | undefined): string {
+	if (!outputFile) return "";
+	try {
+		// Single stat call - throws if file doesn't exist
+		const stat = fs.statSync(outputFile);
+		const ago = Date.now() - stat.mtimeMs;
+		if (ago < 1000) return "active now";
+		if (ago < 60000) return `active ${Math.floor(ago / 1000)}s ago`;
+		return `active ${Math.floor(ago / 60000)}m ago`;
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Find a file/directory by prefix in a directory
+ */
+export function findByPrefix(dir: string, prefix: string, suffix?: string): string | null {
+	if (!fs.existsSync(dir)) return null;
+	const entries = fs.readdirSync(dir).filter((entry) => entry.startsWith(prefix));
+	if (suffix) {
+		const withSuffix = entries.filter((entry) => entry.endsWith(suffix));
+		if (withSuffix.length > 0) return path.join(dir, withSuffix.sort()[0]);
+	}
+	if (entries.length === 0) return null;
+	return path.join(dir, entries.sort()[0]);
+}
+
+/**
+ * Find the latest session file in a directory
+ */
+export function findLatestSessionFile(sessionDir: string): string | null {
+	if (!fs.existsSync(sessionDir)) return null;
+	const files = fs.readdirSync(sessionDir)
+		.filter((f) => f.endsWith(".jsonl"))
+		.map((f) => {
+			const filePath = path.join(sessionDir, f);
+			return {
+				name: f,
+				path: filePath,
+				mtime: fs.statSync(filePath).mtimeMs,
+			};
+		})
+		.sort((a, b) => b.mtime - a.mtime);
+	return files.length > 0 ? files[0].path : null;
+}
+
+/**
+ * Write a prompt to a temporary file
+ */
+export function writePrompt(agent: string, prompt: string): { dir: string; path: string } {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+	const p = path.join(dir, `${agent.replace(/[^\w.-]/g, "_")}.md`);
+	fs.writeFileSync(p, prompt, { mode: 0o600 });
+	return { dir, path: p };
+}
+
+// ============================================================================
+// Message Parsing Utilities
+// ============================================================================
+
+/**
+ * Get the final text output from a list of messages
+ */
+export function getFinalOutput(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") return part.text;
+			}
+		}
+	}
+	return "";
+}
+
+/**
+ * Extract display items (text and tool calls) from messages
+ */
+export function getDisplayItems(messages: Message[]): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") items.push({ type: "text", text: part.text });
+				else if (part.type === "toolCall") items.push({ type: "tool", name: part.name, args: part.arguments });
+			}
+		}
+	}
+	return items;
+}
+
+/**
+ * Detect errors in subagent execution from messages
+ */
+export function detectSubagentError(messages: Message[]): ErrorInfo {
+	for (const msg of messages) {
+		if (msg.role === "toolResult" && (msg as any).isError) {
+			const text = msg.content.find((c) => c.type === "text");
+			const details = text && "text" in text ? text.text : undefined;
+			const exitMatch = details?.match(/exit(?:ed)?\s*(?:with\s*)?(?:code|status)?\s*[:\s]?\s*(\d+)/i);
+			return {
+				hasError: true,
+				exitCode: exitMatch ? parseInt(exitMatch[1], 10) : 1,
+				errorType: (msg as any).toolName || "tool",
+				details: details?.slice(0, 200),
+			};
+		}
+	}
+
+	for (const msg of messages) {
+		if (msg.role !== "toolResult") continue;
+		const toolName = (msg as any).toolName;
+		if (toolName !== "bash") continue;
+
+		const text = msg.content.find((c) => c.type === "text");
+		if (!text || !("text" in text)) continue;
+		const output = text.text;
+
+		const exitMatch = output.match(/exit(?:ed)?\s*(?:with\s*)?(?:code|status)?\s*[:\s]?\s*(\d+)/i);
+		if (exitMatch) {
+			const code = parseInt(exitMatch[1], 10);
+			if (code !== 0) {
+				return { hasError: true, exitCode: code, errorType: "bash", details: output.slice(0, 200) };
+			}
+		}
+
+		const errorPatterns = [
+			/command not found/i,
+			/permission denied/i,
+			/no such file or directory/i,
+			/segmentation fault/i,
+			/killed|terminated/i,
+			/out of memory/i,
+			/connection refused/i,
+			/timeout/i,
+		];
+		for (const pattern of errorPatterns) {
+			if (pattern.test(output)) {
+				return { hasError: true, exitCode: 1, errorType: "bash", details: output.slice(0, 200) };
+			}
+		}
+	}
+
+	return { hasError: false };
+}
+
+/**
+ * Extract a preview of tool arguments for display
+ */
+export function extractToolArgsPreview(args: Record<string, unknown>): string {
+	// Handle MCP tool calls - show server/tool info
+	if (args.tool && typeof args.tool === "string") {
+		const server = args.server && typeof args.server === "string" ? `${args.server}/` : "";
+		const toolArgs = args.args && typeof args.args === "string" ? ` ${args.args.slice(0, 40)}` : "";
+		return `${server}${args.tool}${toolArgs}`;
+	}
+	
+	const previewKeys = ["command", "path", "file_path", "pattern", "query", "url", "task", "describe", "search"];
+	for (const key of previewKeys) {
+		if (args[key] && typeof args[key] === "string") {
+			const value = args[key] as string;
+			return value.length > 60 ? `${value.slice(0, 57)}...` : value;
+		}
+	}
+	
+	// Fallback: show first string value found
+	for (const [key, value] of Object.entries(args)) {
+		if (typeof value === "string" && value.length > 0) {
+			const preview = value.length > 50 ? `${value.slice(0, 47)}...` : value;
+			return `${key}=${preview}`;
+		}
+	}
+	return "";
+}
+
+/**
+ * Extract text content from various message content formats
+ */
+export function extractTextFromContent(content: unknown): string {
+	if (!content) return "";
+	// Handle string content directly
+	if (typeof content === "string") return content;
+	// Handle array content
+	if (!Array.isArray(content)) return "";
+	const texts: string[] = [];
+	for (const part of content) {
+		if (part && typeof part === "object") {
+			// Handle { type: "text", text: "..." }
+			if ("type" in part && part.type === "text" && "text" in part) {
+				texts.push(String(part.text));
+			}
+			// Handle { type: "tool_result", content: "..." }
+			else if ("type" in part && part.type === "tool_result" && "content" in part) {
+				const inner = extractTextFromContent(part.content);
+				if (inner) texts.push(inner);
+			}
+			// Handle { text: "..." } without type
+			else if ("text" in part) {
+				texts.push(String(part.text));
+			}
+		}
+	}
+	return texts.join("\n");
+}
+
+// ============================================================================
+// Concurrency Utilities
+// ============================================================================
+
+/**
+ * Map over items with limited concurrency
+ */
+export async function mapConcurrent<T, R>(
+	items: T[],
+	limit: number,
+	fn: (item: T, i: number) => Promise<R>,
+): Promise<R[]> {
+	const results: R[] = new Array(items.length);
+	let next = 0;
+
+	async function worker(): Promise<void> {
+		while (next < items.length) {
+			const i = next++;
+			results[i] = await fn(items[i], i);
+		}
+	}
+
+	const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}