brl-subagent 2.3.4

package/src/logging.ts

@@ -0,0 +1,135 @@
+/**
+ * brl-subagent — Structured Logging (F10)
+ *
+ * Provides leveled, structured logging with file output and rotation.
+ * Logs are written to .pi/subagent-logs/ in the project directory.
+ *
+ * Usage:
+ *   const log = createLogger("runner", cwd);
+ *   log.info("Subagent started", { model, thinkingLevel });
+ *   log.error("Subagent failed", { error: err.message });
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { LogLevel } from "./types";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Maximum single log file size before rotation (5MB) */
+const MAX_LOG_SIZE = 5 * 1024 * 1024;
+
+/** Maximum number of rotated log files to keep */
+const MAX_LOG_FILES = 5;
+
+/** Log levels in order of verbosity */
+const LOG_LEVELS: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+};
+
+/** Current minimum log level — can be changed at runtime */
+let minLevel: LogLevel = "info";
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+export interface Logger {
+	debug(message: string, data?: Record<string, unknown>): void;
+	info(message: string, data?: Record<string, unknown>): void;
+	warn(message: string, data?: Record<string, unknown>): void;
+	error(message: string, data?: Record<string, unknown>): void;
+}
+
+export function setLogLevel(level: LogLevel): void {
+	minLevel = level;
+}
+
+/**
+ * Create a logger for a specific module.
+ * Logs are written to `.pi/subagent-logs/<prefix>.log` relative to `cwd`.
+ */
+export function createLogger(prefix: string, cwd?: string): Logger {
+	const logDir = cwd ? path.join(cwd, ".pi", "subagent-logs") : undefined;
+
+	// Ensure log directory exists — owner-only (0o700) so other local users
+	// cannot list log files (F6 / issue #29). File writes below already use
+	// 0o600.
+	if (logDir) {
+		try {
+			fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+		} catch {
+			// Can't create log dir — fall back to console-only logging
+		}
+	}
+
+	function log(level: LogLevel, message: string, data?: Record<string, unknown>): void {
+		if (LOG_LEVELS[level] < LOG_LEVELS[minLevel]) return;
+
+		const timestamp = new Date().toISOString();
+		const entry = {
+			timestamp,
+			level,
+			prefix,
+			message,
+			...(data ? { data } : {}),
+		};
+
+		const line = JSON.stringify(entry);
+
+		// Console output
+		const consoleMethod = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+		consoleMethod(`[${prefix}] ${level.toUpperCase()}: ${message}`);
+
+		// File output
+		if (logDir) {
+			try {
+				const logFile = path.join(logDir, `${prefix}.log`);
+				rotateIfNeeded(logFile);
+				fs.appendFileSync(logFile, line + "\n", { encoding: "utf-8", mode: 0o600 });
+			} catch {
+				// Silently fail — logging should never crash the extension
+			}
+		}
+	}
+
+	return {
+		debug: (m, d) => log("debug", m, d),
+		info: (m, d) => log("info", m, d),
+		warn: (m, d) => log("warn", m, d),
+		error: (m, d) => log("error", m, d),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Log rotation
+// ---------------------------------------------------------------------------
+
+function rotateIfNeeded(logFile: string): void {
+	try {
+		const stat = fs.statSync(logFile);
+		if (stat.size < MAX_LOG_SIZE) return;
+
+		// Rotate: remove oldest, shift others, rename current
+		for (let i = MAX_LOG_FILES - 1; i >= 0; i--) {
+			const oldFile = i === 0 ? logFile : `${logFile}.${i}`;
+			const newFile = `${logFile}.${i + 1}`;
+			try {
+				if (i === MAX_LOG_FILES - 1) {
+					fs.unlinkSync(oldFile);
+				} else {
+					fs.renameSync(oldFile, newFile);
+				}
+			} catch {
+				// File might not exist — that's fine
+			}
+		}
+	} catch {
+		// Log file doesn't exist yet — nothing to rotate
+	}
+}

package/src/messaging.ts

@@ -0,0 +1,164 @@
+/**
+ * brl-subagent — Subagent-to-Subagent Messaging (E10)
+ *
+ * Provides an Intercom class that manages inter-subagent communication
+ * via a shared message channel. Subagents can send targeted or broadcast
+ * messages using a special output format parsed by the conductor.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface Message {
+	from: string;
+	content: string;
+	timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// Regex for extracting TO: patterns from subagent output
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches standalone lines like:
+ *   [TO:agent-id]:some message text
+ *   [TO:*]:broadcast message text
+ *
+ * Anchored to the line start (with optional leading whitespace) using the
+ * multiline flag, so ONLY standalone lines whose trimmed content begins
+ * with "[TO:" are matched — a mid-sentence mention (e.g. "append
+ * [TO:target]:msg ...") is NOT treated as a message.
+ *
+ * Not global: extractMessages builds its own stateful /g instance to
+ * avoid lastIndex leaks between calls.
+ *
+ * Group 1 = target id or "*"
+ * Group 2 = message content (rest of line after colon, trimmed by caller)
+ */
+export const TO_PATTERN = /^\s*\[TO:([^*\]]+|\*)\]:([^\n]+)/m;
+
+// ---------------------------------------------------------------------------
+// Intercom class
+// ---------------------------------------------------------------------------
+
+export class Intercom {
+	/**
+	 * Map of subagent ID → queue of incoming messages.
+	 * Keys are created lazily when a message is sent to a subagent.
+	 */
+	private messages: Map<string, Message[]> = new Map();
+
+	/**
+	 * Known subagent IDs. Populated via `register()` as subagents are spawned.
+	 * Used by `broadcast` to determine recipients.
+	 */
+	private knownIds: Set<string> = new Set();
+
+	/**
+	 * Register a subagent ID so it can receive broadcasts.
+	 */
+	register(id: string): void {
+		this.knownIds.add(id);
+	}
+
+	/**
+	 * Remove a subagent ID from the known set (for cleanup).
+	 */
+	unregister(id: string): void {
+		this.knownIds.delete(id);
+	}
+
+	/**
+	 * Send a message from one subagent to another.
+	 */
+	send(fromId: string, toId: string, content: string): void {
+		if (!this.messages.has(toId)) {
+			this.messages.set(toId, []);
+		}
+		this.messages.get(toId)!.push({
+			from: fromId,
+			content,
+			timestamp: Date.now(),
+		});
+	}
+
+	/**
+	 * Return all messages for a subagent without clearing the queue.
+	 */
+	receive(id: string): Message[] {
+		return this.messages.get(id) ?? [];
+	}
+
+	/**
+	 * Return all messages for a subagent and clear the queue.
+	 */
+	receiveAndClear(id: string): Message[] {
+		const msgs = this.messages.get(id) ?? [];
+		this.messages.set(id, []);
+		return msgs;
+	}
+
+	/**
+	 * Returns true if there are pending messages for this subagent.
+	 */
+	hasMessages(id: string): boolean {
+		const q = this.messages.get(id);
+		return q !== undefined && q.length > 0;
+	}
+
+	/**
+	 * Send a message to ALL known subagent IDs except the sender and any
+	 * explicitly excluded IDs.
+	 */
+	broadcast(fromId: string, content: string, excludeIds?: string[]): void {
+		const exclude = new Set(excludeIds ?? []);
+		exclude.add(fromId); // never send back to self
+
+		for (const id of this.knownIds) {
+			if (!exclude.has(id)) {
+				this.send(fromId, id, content);
+			}
+		}
+	}
+
+	/**
+	 * Return the list of all known subagent IDs.
+	 */
+	getKnownIds(): string[] {
+		return [...this.knownIds];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Output parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract all [TO:...] messages from a subagent's output text.
+ * Returns an array of { target, content } objects.
+ */
+export function extractMessages(
+	output: string,
+): Array<{ target: string; content: string }> {
+	const results: Array<{ target: string; content: string }> = [];
+	const regex = new RegExp(TO_PATTERN.source, `${TO_PATTERN.flags}g`);
+	let match: RegExpExecArray | null;
+	while ((match = regex.exec(output)) !== null) {
+		results.push({
+			target: match[1],
+			content: match[2].trim(),
+		});
+	}
+	return results;
+}
+
+/**
+ * Format a list of incoming messages into a string that can be appended
+ * to a subagent's task prompt.
+ */
+export function formatPendingMessages(messages: Message[]): string {
+	return messages
+		.map((m) => `From ${m.from}: ${m.content}`)
+		.join("\n");
+}

package/src/metrics.ts

@@ -0,0 +1,221 @@
+/**
+ * brl-subagent — SLA Metrics (E4)
+ *
+ * Computes performance metrics from run history and detects degradation
+ * against a baseline.
+ */
+
+import type { SubagentRun, SLAMetrics, DegradationReport, ErrorCategory } from "./types";
+
+// ---------------------------------------------------------------------------
+// Percentile helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the p-th percentile of a sorted numeric array (0-100).
+ * Uses linear interpolation between ranks for accuracy.
+ */
+function percentile(sorted: number[], p: number): number {
+	if (sorted.length === 0) return 0;
+	if (sorted.length === 1) return sorted[0];
+	const rank = (p / 100) * (sorted.length - 1);
+	const lower = Math.floor(rank);
+	const upper = Math.ceil(rank);
+	if (lower === upper) return sorted[lower];
+	const weight = rank - lower;
+	return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+
+// ---------------------------------------------------------------------------
+// SLA metric computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute SLA metrics from a list of SubagentRun records.
+ *
+ * Duration calculations use only runs that have finishedAt and durationMs set.
+ * Runs with status "running" are excluded from duration stats but counted in totalRuns.
+ *
+ * @param runs - Array of SubagentRun records (most recent first is fine; sorting happens internally)
+ * @returns Computed SLAMetrics
+ */
+export function computeSLAMetrics(runs: SubagentRun[]): SLAMetrics {
+	const totalRuns = runs.length;
+
+	if (totalRuns === 0) {
+		return {
+			totalRuns: 0,
+			successRate: 0,
+			failureRate: 0,
+			averageDurationMs: 0,
+			p50DurationMs: 0,
+			p95DurationMs: 0,
+			p99DurationMs: 0,
+			totalCost: 0,
+			averageCost: 0,
+			errorCategoryBreakdown: {},
+		};
+	}
+
+	// Count successes and failures (running runs are neither)
+	const succeeded = runs.filter((r) => r.status === "done").length;
+	const failed = runs.filter((r) => r.status === "failed").length;
+	const finishedRuns = succeeded + failed;
+
+	const successRate = finishedRuns > 0 ? succeeded / finishedRuns : 0;
+	const failureRate = finishedRuns > 0 ? failed / finishedRuns : 0;
+
+	// Duration stats — only runs with durationMs set
+	const durations = runs
+		.filter((r) => r.durationMs !== undefined && r.durationMs !== null)
+		.map((r) => r.durationMs!);
+
+	const sortedDurations = [...durations].sort((a, b) => a - b);
+
+	const averageDurationMs =
+		durations.length > 0
+			? durations.reduce((sum, d) => sum + d, 0) / durations.length
+			: 0;
+
+	const p50DurationMs = percentile(sortedDurations, 50);
+	const p95DurationMs = percentile(sortedDurations, 95);
+	const p99DurationMs = percentile(sortedDurations, 99);
+
+	// Cost stats
+	const costs = runs.map((r) => r.cost ?? 0);
+	const totalCost = costs.reduce((sum, c) => sum + c, 0);
+	const averageCost = totalRuns > 0 ? totalCost / totalRuns : 0;
+
+	// Error category breakdown
+	const errorCategoryBreakdown: Record<string, number> = {};
+	for (const run of runs) {
+		const cat = run.originalParams?.errorCategory as ErrorCategory | undefined;
+		if (cat) {
+			errorCategoryBreakdown[cat] = (errorCategoryBreakdown[cat] ?? 0) + 1;
+		}
+	}
+
+	return {
+		totalRuns,
+		successRate,
+		failureRate,
+		averageDurationMs,
+		p50DurationMs,
+		p95DurationMs,
+		p99DurationMs,
+		totalCost,
+		averageCost,
+		errorCategoryBreakdown,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Degradation detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare current SLA metrics against a baseline to detect degradation.
+ *
+ * Degradation is flagged if:
+ * - Success rate dropped by more than 10 percentage points, OR
+ * - P95 latency increased by more than 2x
+ *
+ * @param current - Current SLA metrics
+ * @param baseline - Baseline SLA metrics to compare against
+ * @returns DegradationReport with comparison results and recommendations
+ */
+// ---------------------------------------------------------------------------
+// Cost trend & sparkline (E1: Dashboard)
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the last N run costs as an array of numbers, most recent last.
+ * Filters to runs that have a cost field set.
+ */
+export function computeCostTrend(runs: SubagentRun[], count: number): number[] {
+	return runs
+		.filter((r) => r.cost !== undefined && r.cost !== null)
+		.slice(-count)
+		.map((r) => r.cost!);
+}
+
+/**
+ * Unicode sparkline characters, ordered from lowest to highest.
+ */
+const SPARKLINE_CHARS = ['\u2581', '\u2582', '\u2583', '\u2584', '\u2585', '\u2586', '\u2587', '\u2588'];
+
+/**
+ * Convert an array of numbers to a Unicode sparkline string.
+ * Values are scaled to the 8-character range. Empty array returns empty string.
+ */
+export function formatSparkline(values: number[]): string {
+	if (values.length === 0) return '';
+	const min = Math.min(...values);
+	const max = Math.max(...values);
+	const range = max - min;
+	if (range === 0) {
+		// All values equal — show middle character
+		return values.map(() => SPARKLINE_CHARS[3]).join('');
+	}
+	return values
+		.map((v) => {
+			const normalized = (v - min) / range;
+			const index = Math.min(Math.floor(normalized * SPARKLINE_CHARS.length), SPARKLINE_CHARS.length - 1);
+			return SPARKLINE_CHARS[index];
+		})
+		.join('');
+}
+
+export function computeDegradation(
+	current: SLAMetrics,
+	baseline: SLAMetrics,
+): DegradationReport {
+	const recommendations: string[] = [];
+
+	// Success rate change (percentage points, negative = drop)
+	const successRateChange =
+		baseline.successRate > 0
+			? (current.successRate - baseline.successRate) * 100
+			: 0;
+
+	// P95 latency change (ratio: current / baseline)
+	const p95Change =
+		baseline.p95DurationMs > 0
+			? current.p95DurationMs / baseline.p95DurationMs
+			: current.p95DurationMs > 0
+				? Infinity
+				: 0;
+
+	// Degradation criteria
+	const successRateDegraded = successRateChange < -10;
+	const p95Degraded = p95Change > 2;
+	const degraded = successRateDegraded || p95Degraded;
+
+	// Generate recommendations
+	if (successRateDegraded) {
+		recommendations.push(
+			`Success rate dropped by ${Math.abs(successRateChange).toFixed(1)}% ` +
+			`(from ${(baseline.successRate * 100).toFixed(1)}% to ${(current.successRate * 100).toFixed(1)}%). ` +
+			`Check error category breakdown for root cause.`,
+		);
+	}
+
+	if (p95Degraded) {
+		recommendations.push(
+			`P95 latency increased ${p95Change.toFixed(1)}x ` +
+			`(from ${baseline.p95DurationMs.toFixed(0)}ms to ${current.p95DurationMs.toFixed(0)}ms). ` +
+			`Consider increasing timeout or reducing task complexity.`,
+		);
+	}
+
+	if (!degraded) {
+		recommendations.push("No significant degradation detected. Metrics are within normal range.");
+	}
+
+	return {
+		degraded,
+		successRateChange,
+		p95Change,
+		recommendations,
+	};
+}

package/src/model-availability.ts

@@ -0,0 +1,73 @@
+/**
+ * Auth-aware model availability check (issue #4).
+ *
+ * A model may exist in pi's CATALOG (built-in model list) while its provider
+ * has no configured credentials (no API key / OAuth). Spawning a subagent with
+ * such a model fails at spawn time ("No API key found") instead of triggering
+ * the preset-model fallback. This module checks BOTH catalog presence AND
+ * provider auth configuration before a model is considered available.
+ *
+ * Structural subset of the pi SDK `ModelRegistry` (see
+ * @earendil-works/pi-coding-agent/dist/core/model-registry.d.ts):
+ *   - find(provider, modelId): Model | undefined
+ *   - getAll(): Model[]
+ *   - hasConfiguredAuth(model): boolean
+ *   - getProviderAuthStatus(provider): AuthStatus   // { configured: boolean; ... }
+ *
+ * Kept free of pi runtime imports so it can be unit-tested in isolation.
+ */
+
+export interface ModelLike {
+	provider: string;
+	id: string;
+}
+
+export interface ProviderAuthStatusLike {
+	configured?: boolean;
+	source?: string;
+	label?: string;
+}
+
+export interface ModelRegistryLike {
+	find?(provider: string, modelId: string): ModelLike | undefined;
+	getAll?(): ModelLike[];
+	hasConfiguredAuth?(model: ModelLike): boolean;
+	getProviderAuthStatus?(provider: string): ProviderAuthStatusLike | undefined;
+}
+
+/**
+ * Check that provider/model exists in the catalog AND that the provider has
+ * configured auth. Falls back to catalog-only presence when the registry
+ * exposes no auth API (old behavior).
+ */
+export function modelIsAvailable(
+	registry: ModelRegistryLike | undefined,
+	m: { provider: string; id: string },
+): boolean {
+	try {
+		// Find the model in the catalog
+		let model: ModelLike | undefined;
+		if (registry?.find) {
+			model = registry.find(m.provider, m.id);
+		}
+		if (!model) {
+			const models = registry?.getAll?.() ?? [];
+			model = models.find((x) => x.provider === m.provider && x.id === m.id);
+		}
+		if (!model) return false;
+
+		// Auth-aware check: model exists in catalog BUT provider must have configured auth
+		if (typeof registry?.hasConfiguredAuth === "function") {
+			return registry.hasConfiguredAuth(model);
+		}
+		// Fallback: getProviderAuthStatus (AuthStatus = { configured: boolean; ... })
+		if (typeof registry?.getProviderAuthStatus === "function") {
+			const status = registry.getProviderAuthStatus(m.provider);
+			return status?.configured === true;
+		}
+		// No auth API — trust the catalog (old behavior)
+		return true;
+	} catch {
+		return false;
+	}
+}