brl-subagent 2.3.4

package/src/sanitize.ts

@@ -0,0 +1,365 @@
+/**
+ * brl-subagent — Sanitization (F1, F2, F3)
+ *
+ * Input validation, environment isolation, and output sanitization
+ * to ensure security and robustness of subagent execution.
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { EMPTY_USAGE } from "./types";
+
+// ---------------------------------------------------------------------------
+// F1: Input sanitization
+// ---------------------------------------------------------------------------
+
+/**
+ * Shell metacharacters that could enable command injection when passed
+ * as CLI arguments. We aggressively reject any task containing these.
+ */
+// Intentional no-op: safe with spawn shell:false
+const SHELL_METACHARS = /(?!)/; // matches nothing — safe with shell: false
+
+/**
+ * Maximum allowed task length to prevent memory exhaustion from
+ * excessively long task descriptions.
+ */
+const MAX_TASK_LENGTH = 50_000; // 50KB
+
+/**
+ * Validate and sanitize the task string.
+ * Rejects tasks containing shell metacharacters or exceeding max length.
+ */
+export function sanitizeTask(task: string): { ok: true; value: string } | { ok: false; error: string } {
+	if (!task || task.trim().length === 0) {
+		return { ok: false, error: "Task must not be empty." };
+	}
+
+	if (task.length > MAX_TASK_LENGTH) {
+		return {
+			ok: false,
+			error: `Task too long (${task.length} chars). Maximum is ${MAX_TASK_LENGTH}.`,
+		};
+	}
+
+	if (SHELL_METACHARS.test(task)) {
+		const matches = task.match(SHELL_METACHARS);
+		const found = [...new Set(matches)].map((c) => `'${c}'`).join(", ");
+		return {
+			ok: false,
+			error: `Task contains disallowed characters: ${found}. Remove shell metacharacters and try again.`,
+		};
+	}
+
+	return { ok: true, value: task.trim() };
+}
+
+/**
+ * Validate and resolve a CWD path for subagent execution.
+ * - Must exist as a directory
+ * - Must be an absolute path (within reasonable bounds)
+ */
+export function validateCwd(raw: string | undefined, defaultCwd: string): { ok: true; value: string } | { ok: false; error: string } {
+	if (!raw) return { ok: true, value: defaultCwd };
+
+	const resolved = path.resolve(defaultCwd, raw);
+
+	// Prevent traversal to sensitive system directories
+	const dangerousPrefixes = ["/etc", "/sys", "/proc", "/dev", "/root"];
+	for (const prefix of dangerousPrefixes) {
+		if (resolved === prefix || resolved.startsWith(prefix + "/")) {
+			return { ok: false, error: `CWD path "${raw}" resolves to restricted system directory "${resolved}".` };
+		}
+	}
+
+	try {
+		const stat = fs.statSync(resolved);
+		if (!stat.isDirectory()) {
+			return { ok: false, error: `CWD path "${raw}" is not a directory.` };
+		}
+	} catch {
+		return { ok: false, error: `CWD path "${raw}" does not exist.` };
+	}
+
+	return { ok: true, value: resolved };
+}
+
+/**
+ * Validate an output file path to prevent writing outside the project.
+ * Path must resolve within the project root directory.
+ */
+export function validateOutputFile(raw: string, projectRoot: string): { ok: true; value: string } | { ok: false; error: string } {
+	const resolved = path.resolve(projectRoot, raw);
+
+	// Must be within the project root
+	const rel = path.relative(projectRoot, resolved);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		return {
+			ok: false,
+			error: `Output file path "${raw}" escapes the project root. Must be within the project directory.`,
+		};
+	}
+
+	// Must not point to a directory
+	try {
+		const stat = fs.statSync(resolved);
+		if (stat.isDirectory()) {
+			return { ok: false, error: `Output file path "${raw}" is a directory, not a file.` };
+		}
+	} catch {
+		// File doesn't exist yet — that's fine, it'll be created
+	}
+
+	return { ok: true, value: resolved };
+}
+
+// ---------------------------------------------------------------------------
+// F24: Agent id validation
+// ---------------------------------------------------------------------------
+
+/**
+ * F24: Agent ids are generated by this module's callers (generateUUID) and
+ * reach file paths via join(). path.join does NOT sanitize "../" or absolute
+ * segments, so any externally-supplied id (LLM tool params such as
+ * get_agent_status/steer_subagent/get_agent_result) must be validated before
+ * touching the filesystem — otherwise arbitrary .json read/overwrite via
+ * `join(STORAGE_DIR, \`${id}.json\`)`.
+ *
+ * Only UUIDs generated by this codebase are ever used as agent ids.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Validate an agent id before it is interpolated into a file path.
+ * Throws on any non-UUID value (path traversal, absolute paths, etc.).
+ */
+export function assertSafeAgentId(id: string): void {
+  if (!UUID_RE.test(id)) {
+    throw new Error(`Invalid agent id: ${id}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// F2: Environment isolation
+// ---------------------------------------------------------------------------
+
+/**
+ * Safe environment variables to pass to subagent processes.
+ * Only variables needed for the subagent to function are included.
+ * API keys, secrets, and other sensitive env vars are NOT propagated.
+ */
+const SAFE_ENV_KEYS = new Set([
+	"PATH",
+	"HOME",
+	"USER",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"TMPDIR",
+	"TEMP",
+	"TMP",
+	"SHELL",
+	"TERM",
+	"COLORTERM",
+	"NO_COLOR",
+	"FORCE_COLOR",
+	"NODE_ENV",
+	// brl-subagent recursion depth tracker
+	"BRL_SUBAGENT_DEPTH",
+]);
+
+/**
+ * Build a filtered environment object containing only safe variables.
+ * Accepts optional overrides for keys that are computed at spawn time
+ * (e.g., BRL_SUBAGENT_DEPTH) rather than inherited from the parent process.
+ */
+export function getSafeEnv(overrides?: Record<string, string>): Record<string, string> {
+	const env: Record<string, string> = {};
+	for (const [key, value] of Object.entries(process.env)) {
+		if (value !== undefined && SAFE_ENV_KEYS.has(key)) {
+			env[key] = value;
+		}
+	}
+	if (overrides) {
+		for (const [key, value] of Object.entries(overrides)) {
+			if (value !== undefined) {
+				env[key] = value;
+			}
+		}
+	}
+	return env;
+}
+
+// ---------------------------------------------------------------------------
+// F3: Output sanitization
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex to match ANSI escape sequences (CSI, OSC, etc.)
+ */
+const ANSI_ESCAPE_RE = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-ntqry=><~]))/g;
+
+/**
+ * Strip ANSI escape sequences from a string.
+ * Subagent output may contain terminal control codes that could
+ * interfere with the TUI or be used maliciously.
+ */
+export function stripAnsi(str: string): string {
+	return str.replace(ANSI_ESCAPE_RE, "");
+}
+
+/**
+ * Cap output size to prevent subagent results from overwhelming
+ * the conductor's context window or TUI.
+ *
+ * Returns the original string if within limits, or a truncated version
+ * with a clear notice about how much was omitted.
+ */
+export function capOutput(output: string, maxBytes: number = 100 * 1024): string {
+	const byteLength = Buffer.byteLength(output, "utf8");
+	if (byteLength <= maxBytes) return output;
+
+	// Truncate while keeping valid UTF-8
+	let truncated = output.slice(0, maxBytes);
+	while (Buffer.byteLength(truncated, "utf8") > maxBytes) {
+		truncated = truncated.slice(0, -1);
+	}
+
+	const omitted = byteLength - Buffer.byteLength(truncated, "utf8");
+	return `${truncated}\n\n[Output truncated: ${formatBytes(omitted)} omitted. Full output available in run history details.]`;
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * Maximum length for a sanitized error message (issue #30). Error text is
+ * persisted to disk AND echoed into the main agent's context — a runaway
+ * message (e.g. a swallowed tool dump) would bloat both.
+ */
+const MAX_ERROR_MESSAGE_LENGTH = 2000;
+
+/**
+ * Replace every occurrence of an absolute path prefix with a neutral
+ * placeholder, but ONLY at path boundaries (followed by a path separator or
+ * the end of the string). Boundary matching means neutralizing the cwd
+ * `/home/user/project` does not clobber a sibling like `/home/user/project2`,
+ * and a bare `/` root cwd is left untouched (it would otherwise match every
+ * separator in the message).
+ */
+function neutralizePathPrefix(text: string, prefix: string, replacement: string): string {
+	if (!prefix || prefix === "/") return text;
+	const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	// The boundary class must contain BOTH separators: in this template literal,
+	// `\\\\` is the escaped backslash in the compiled regex source, so the
+	// character class matches `\` (Windows) and `/` (POSIX). With only `/`, a
+	// Windows path like `C:\Users\me\project\node_modules\...` would never
+	// match mid-string (Fix 2, PR #63 review) and the raw cwd would leak.
+	return text.replace(new RegExp(`${escaped}(?=[\\\\/]|$)`, "g"), replacement);
+}
+
+/**
+ * Sanitize an error message before persisting/echoing (issue #30, F7).
+ *
+ * 1. Strips ANSI escape sequences (reuses `stripAnsi`).
+ * 2. Neutralizes the project root: the cwd absolute prefix (the passed `cwd`
+ *    or `process.cwd()`) becomes `<cwd>` — `/home/user/project/src/foo.ts` →
+ *    `<cwd>/src/foo.ts`.
+ * 3. Neutralizes the directory CONTAINING the project root (typically the
+ *    user's home in a `~/project` layout): it becomes `<home>`. The label is
+ *    a neutral placeholder — when the project does not live directly under
+ *    the home dir (e.g. `/var/www/app` → parent `/var/www`), the parent is
+ *    still replaced so the workspace root never leaks.
+ * 4. Caps length at 2000 chars with an ellipsis marker.
+ *
+ * Remaining-absolute-path policy: paths OUTSIDE the project root and its
+ * parent are left as-is (e.g. `/etc/passwd`, `/usr/bin/node`, `/tmp/x.log`).
+ * Issue #30 is specifically about CWD/home disclosure; system paths carry no
+ * personal structure and keeping them preserves debugging value. Messages
+ * that are short and clean (no ANSI, no cwd/parent prefixes) pass through
+ * unchanged. Pure and dependency-free.
+ */
+export function sanitizeErrorMessage(msg: string, cwd?: string): string {
+	let out = stripAnsi(msg);
+	let base = cwd ? path.normalize(cwd) : process.cwd();
+	// path.normalize preserves a trailing separator, which defeats the boundary
+	// lookahead mid-string (Fix 1, PR #63 review): a cwd of `/home/u/project/`
+	// would never match `/home/u/project/src/...` and the raw cwd would leak as
+	// `<home>/project/src/...`. Strip trailing separators — but keep `/` for a
+	// bare root cwd (the root-cwd test relies on `/` being left untouched).
+	base = base.replace(/[\\/]+$/, "");
+	if (!base) base = "/";
+	out = neutralizePathPrefix(out, base, "<cwd>");
+	const parent = path.dirname(base);
+	if (parent !== base) {
+		out = neutralizePathPrefix(out, parent, "<home>");
+	}
+	if (out.length > MAX_ERROR_MESSAGE_LENGTH) {
+		out = `${out.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…[truncated]`;
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Crash-result builder (DRY, issue #68)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the shared crash-result envelope used by the chain, graph, and single
+ * mode catches in index.ts (previously 3× duplicated construction, issue #68).
+ *
+ * - `details.errorMessage` is sanitized (F7, issues #30/#65) so absolute paths
+ *   never reach the main agent's context or the persisted errorMessage field.
+ * - `details.stderr` is intentionally the RAW error (`String(err)`) — pi only
+ *   serializes `content` into the LLM context, while the raw text persists to
+ *   the session file for post-mortems (issue #68 framing: extraction is DRY,
+ *   not a stderr-content change).
+ */
+export function buildCrashResult(mode: string, err: unknown, cwd: string): {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		messages: [];
+		usage: typeof EMPTY_USAGE;
+		exitCode: number;
+		stderr: string;
+		errorMessage: string;
+	};
+	isError: true;
+} {
+	const errorMessage = sanitizeErrorMessage(
+		err instanceof Error ? (err.message || String(err)) : String(err),
+		cwd,
+	);
+	return {
+		content: [{ type: "text", text: `${mode} crashed: ${errorMessage}` }],
+		details: {
+			messages: [],
+			usage: { ...EMPTY_USAGE },
+			exitCode: 1,
+			stderr: String(err),
+			errorMessage,
+		},
+		isError: true,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Recursion depth tracking
+// ---------------------------------------------------------------------------
+
+/** Env var used to track subagent nesting depth. */
+export const DEPTH_ENV_KEY = "BRL_SUBAGENT_DEPTH";
+
+/**
+ * Read the current subagent depth from the environment.
+ * Returns 0 for the main (conductor) process, 1+ for nested subagents.
+ */
+export function getCurrentDepth(): number {
+	const raw = process.env[DEPTH_ENV_KEY];
+	if (!raw) return 0;
+	const parsed = parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}

package/src/scheduler.ts

@@ -0,0 +1,187 @@
+/**
+ * brl-subagent — Dependency Graph Scheduler
+ *
+ * Cycle detection (DFS), topological sort (Kahn's algorithm),
+ * and graph validation for P10 dependency graph mode.
+ */
+
+import type { GraphTask } from "./types";
+import { MAX_GRAPH_TASKS } from "./types";
+
+// ---------------------------------------------------------------------------
+// Cycle detection — three-color DFS
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect cycles in the dependency graph.
+ * Returns the task IDs forming the cycle if found, or null if acyclic.
+ */
+export function detectCycle(tasks: GraphTask[]): string[] | null {
+	const byId = new Map<string, GraphTask>();
+	for (const t of tasks) byId.set(t.id, t);
+
+	// 0 = white (unvisited), 1 = gray (in current path), 2 = black (done)
+	const color = new Map<string, number>();
+	for (const t of tasks) color.set(t.id, 0);
+
+	const path: string[] = [];
+
+	function dfs(nodeId: string): boolean {
+		color.set(nodeId, 1);
+		path.push(nodeId);
+
+		const task = byId.get(nodeId);
+		if (task) {
+			for (const dep of task.dependsOn ?? []) {
+				const depColor = color.get(dep);
+				if (depColor === undefined) continue; // reference to non-existent id (validated elsewhere)
+				if (depColor === 1) {
+					// Found cycle — extract cycle path
+					const cycleStart = path.indexOf(dep);
+					path.push(dep);
+					return true;
+				}
+				if (depColor === 0 && dfs(dep)) {
+					return true;
+				}
+			}
+		}
+
+		path.pop();
+		color.set(nodeId, 2);
+		return false;
+	}
+
+	for (const t of tasks) {
+		if (color.get(t.id) === 0) {
+			if (dfs(t.id)) {
+				return [...path];
+			}
+		}
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Topological sort — Kahn's algorithm → execution waves
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform topological sort returning execution waves.
+ * Each wave contains tasks whose all dependencies are satisfied by previous waves.
+ * Tasks within a wave have no dependencies on each other and can run in parallel.
+ */
+export function topologicalSort(tasks: GraphTask[]):
+	| { ok: true; waves: GraphTask[][] }
+	| { ok: false; error: string } {
+	// Check for cycle first
+	const cycle = detectCycle(tasks);
+	if (cycle) {
+		return {
+			ok: false,
+			error: `Dependency cycle detected: ${cycle.join(" → ")}`,
+		};
+	}
+
+	const byId = new Map<string, GraphTask>();
+	for (const t of tasks) byId.set(t.id, t);
+
+	// Count incoming edges (dependsOn)
+	const inDegree = new Map<string, number>();
+	for (const t of tasks) {
+		inDegree.set(t.id, 0);
+	}
+	for (const t of tasks) {
+		for (const dep of t.dependsOn ?? []) {
+			if (byId.has(dep)) {
+				inDegree.set(t.id, (inDegree.get(t.id) ?? 0) + 1);
+			}
+		}
+	}
+
+	// Build adjacency: dep → dependent tasks
+	const dependents = new Map<string, string[]>();
+	for (const t of tasks) {
+		for (const dep of t.dependsOn ?? []) {
+			if (byId.has(dep)) {
+				if (!dependents.has(dep)) dependents.set(dep, []);
+				dependents.get(dep)!.push(t.id);
+			}
+		}
+	}
+
+	const waves: GraphTask[][] = [];
+	const processed = new Set<string>();
+
+	// Initial wave: tasks with in-degree 0
+	let currentWave = tasks
+		.filter((t) => (inDegree.get(t.id) ?? 0) === 0)
+		.sort((a, b) => a.id.localeCompare(b.id));
+
+	while (currentWave.length > 0) {
+		waves.push(currentWave);
+
+		const nextWave: GraphTask[] = [];
+		for (const task of currentWave) {
+			processed.add(task.id);
+			const deps = dependents.get(task.id) ?? [];
+			for (const depId of deps) {
+				if (processed.has(depId)) continue;
+				const newDegree = (inDegree.get(depId) ?? 1) - 1;
+				inDegree.set(depId, newDegree);
+				if (newDegree === 0) {
+					const depTask = byId.get(depId);
+					if (depTask) nextWave.push(depTask);
+				}
+			}
+		}
+
+		currentWave = nextWave.sort((a, b) => a.id.localeCompare(b.id));
+	}
+
+	return { ok: true, waves };
+}
+
+// ---------------------------------------------------------------------------
+// Graph validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the graph before scheduling.
+ * Returns array of error strings (empty = valid).
+ */
+export function validateGraph(tasks: GraphTask[]): string[] {
+	const errors: string[] = [];
+
+	if (tasks.length === 0) {
+		errors.push("Graph is empty — provide at least one task");
+		return errors;
+	}
+
+	if (tasks.length > MAX_GRAPH_TASKS) {
+		errors.push(
+			`Graph exceeds maximum of ${MAX_GRAPH_TASKS} tasks (${tasks.length} provided)`,
+		);
+	}
+
+	const ids = new Set<string>();
+	for (const t of tasks) {
+		if (ids.has(t.id)) {
+			errors.push(`Duplicate task ID: "${t.id}"`);
+		}
+		ids.add(t.id);
+	}
+
+	for (const t of tasks) {
+		for (const dep of t.dependsOn ?? []) {
+			if (!ids.has(dep)) {
+				errors.push(
+					`Task "${t.id}" depends on non-existent task "${dep}"`,
+				);
+			}
+		}
+	}
+
+	return errors;
+}