@bacnh85/pi-subagent 0.5.0 → 0.7.0

package/extensions/security.ts

@@ -0,0 +1,504 @@
+/**
+ * Security and validation helpers for pi-subagent.
+ *
+ * Centralizes all trust-boundary checks so that internal callers (tool handler,
+ * service/event path, parallel executor, chain executor) cannot bypass them.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Tools that child agents may use. The subagent tool is never included. */
+export const ALLOWED_CHILD_TOOLS = [
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"bash",
+	"edit",
+	"write",
+] as const;
+
+export const READ_ONLY_TOOLS: readonly string[] = ["read", "grep", "find", "ls"];
+export const MUTATION_TOOLS: readonly string[] = ["edit", "write"];
+export const EXECUTION_TOOLS: readonly string[] = ["bash"];
+
+/**
+ * Default timeout applied to every child execution unless an explicit timeout
+ * is provided. Children may request a shorter-but-not-longer timeout within
+ * the allowed range.
+ */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
+
+/**
+ * Absolute maximum timeout. Any requested value above this cap is rejected
+ * at validation time rather than silently clamped.
+ */
+export const MAX_TIMEOUT_MS = 60 * 60 * 1_000; // 60 minutes
+
+// ---------------------------------------------------------------------------
+// Canonical result status
+// ---------------------------------------------------------------------------
+
+export type SubagentStatus = "success" | "partial" | "error" | "aborted" | "timeout";
+
+/** Pi SDK stop reasons that indicate successful completion. */
+const SUCCESS_REASONS = new Set(["stop", "end_turn", "completed"]);
+
+/** Pi SDK stop reasons that indicate a partial / truncated response. */
+const PARTIAL_REASONS = new Set(["length", "max_tokens", "context_limit"]);
+
+/** Pi SDK stop reasons that indicate a provider or tool error. */
+const ERROR_REASONS = new Set([
+	"error",
+	"tool_error",
+	"authentication_error",
+	"provider_error",
+	"content_filter",
+]);
+
+/**
+ * Map a raw stop reason string to a canonical SubagentStatus.
+ *
+ * `isAborted` and `isTimeout` take precedence because the Pi SDK may emit
+ * "aborted" or "error" for both cases. Callers should pass the flags derived
+ * from their own abort controllers.
+ */
+export function classifyStopReason(
+	reason: string | undefined,
+	isAborted: boolean,
+	isTimeout: boolean,
+): SubagentStatus {
+	if (isAborted) return "aborted";
+	if (isTimeout) return "timeout";
+	if (!reason) return "success";
+	if (SUCCESS_REASONS.has(reason)) return "success";
+	if (PARTIAL_REASONS.has(reason)) return "partial";
+	if (ERROR_REASONS.has(reason)) return "error";
+	// Unknown stop reason — classify conservatively.
+	return "error";
+}
+
+// ---------------------------------------------------------------------------
+// Safe working-directory resolver
+// ---------------------------------------------------------------------------
+
+export interface SafeCwdOptions {
+	/** The workspace root (parent session's cwd). Must be an absolute path. */
+	workspaceRoot: string;
+	/** The child's requested working directory, if any. */
+	childCwd?: string;
+	/**
+	 * Trusted user setting that allows child cwd outside the workspace.
+	 * Must never come from the tool-calling model.
+	 */
+	allowExternalCwd?: boolean;
+}
+
+export interface SafeCwdResult {
+	path: string;
+	error?: string;
+}
+
+/**
+ * Resolve a child working directory that is guaranteed to be inside the
+ * workspace root.
+ *
+ * Rules:
+ * - No childCwd → return workspaceRoot.
+ * - Relative paths are resolved relative to workspaceRoot.
+ * - Absolute paths outside workspaceRoot are rejected unless allowExternalCwd.
+ * - `..` traversal that escapes workspaceRoot is rejected.
+ * - Symlinks are resolved via realpath and checked against workspaceRoot.
+ * - Non-existent directories are rejected.
+ * - Paths that are files instead of directories are rejected.
+ */
+export function resolveSafeCwd(options: SafeCwdOptions): SafeCwdResult {
+	const { workspaceRoot, childCwd, allowExternalCwd } = options;
+
+	// Normalise workspace root to an absolute canonical path.
+	const resolvedRoot = resolveCanonical(workspaceRoot);
+	if (!resolvedRoot) {
+		return { path: "", error: `Workspace root does not exist: ${workspaceRoot}` };
+	}
+	if (!isDirectorySync(resolvedRoot)) {
+		return { path: "", error: `Workspace root is not a directory: ${workspaceRoot}` };
+	}
+
+	// No child cwd → use workspace root.
+	if (!childCwd) {
+		return { path: resolvedRoot };
+	}
+
+	// Resolve the child path.
+	const absPath = path.resolve(resolvedRoot, childCwd);
+
+	// If the resolved path escapes the workspace via `..`, the resolved path
+	// will differ from the canonical workspace root prefix. We check by
+	// resolving the canonical absolute path.
+	const canonicalPath = resolveCanonical(absPath);
+	if (!canonicalPath) {
+		return { path: "", error: `Child working directory does not exist: ${childCwd}` };
+	}
+
+	if (!isDirectorySync(canonicalPath)) {
+		return { path: "", error: `Child working directory is a file, not a directory: ${childCwd}` };
+	}
+
+	// Check if the child path is inside the workspace.
+	if (!isPathInside(canonicalPath, resolvedRoot)) {
+		if (allowExternalCwd) {
+			return { path: canonicalPath };
+		}
+		return {
+			path: "",
+			error:
+				`Child working directory "${childCwd}" is outside the workspace root "${workspaceRoot}". ` +
+				`Paths outside the workspace are rejected by default.`,
+		};
+	}
+
+	return { path: canonicalPath };
+}
+
+/**
+ * Check if `child` is inside `parent` or equal to it, after resolving both
+ * to canonical paths. Rejects `..` traversal that escapes `parent`.
+ */
+function isPathInside(child: string, parent: string): boolean {
+	// Both must be absolute.
+	if (!path.isAbsolute(child) || !path.isAbsolute(parent)) return false;
+
+	const relative = path.relative(parent, child);
+	// relative must not start with ".." and must not be an absolute path.
+	return !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+/**
+ * Resolve a path to its canonical real path, or return null if it doesn't exist.
+ */
+function resolveCanonical(p: string): string | null {
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Synchronously check if a path is a directory.
+ */
+function isDirectorySync(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Tool allowlist validation
+// ---------------------------------------------------------------------------
+
+export interface ValidateToolsOptions {
+	/** Tool names from the agent definition or service override. */
+	tools: string[];
+	/** When true, only read-only tools are permitted. Mutation/execution tools are rejected. */
+	readOnly?: boolean;
+}
+
+export interface ValidateToolsResult {
+	/** Deduplicated and validated tool names. */
+	tools: string[];
+	/** Validation errors, if any. Empty array means valid. */
+	errors: string[];
+}
+
+/**
+ * Validate agent tool names against the allowlist.
+ *
+ * Always strips or rejects `subagent` to prevent recursive delegation.
+ * Deduplicates tool names.
+ * When `readOnly` is true, only READ_ONLY_TOOLS are permitted.
+ */
+export function validateAgentTools(options: ValidateToolsOptions): ValidateToolsResult {
+	const { readOnly = false } = options;
+	const seen = new Set<string>();
+	const tools: string[] = [];
+	const errors: string[] = [];
+
+	for (const raw of options.tools) {
+		const tool = raw.trim();
+		if (!tool) continue;
+
+		// Reject subagent regardless of casing (Pi tool names are case-sensitive
+		// but "subagent" should never pass through).
+		if (tool.toLowerCase() === "subagent") {
+			errors.push(`Tool "subagent" is not allowed in child agents (recursive delegation is prevented).`);
+			continue;
+		}
+
+		// Check against allowlist
+		if (!ALLOWED_CHILD_TOOLS.includes(tool as any)) {
+			errors.push(`Unknown tool "${tool}". Allowed tools: ${ALLOWED_CHILD_TOOLS.join(", ")}.`);
+			continue;
+		}
+
+		// Check read-only constraint
+		if (readOnly && !READ_ONLY_TOOLS.includes(tool)) {
+			errors.push(
+				`Tool "${tool}" is not allowed in read-only mode. Read-only tools: ${READ_ONLY_TOOLS.join(", ")}.`,
+			);
+			continue;
+		}
+
+		// Deduplicate
+		if (seen.has(tool)) continue;
+		seen.add(tool);
+		tools.push(tool);
+	}
+
+	return { tools, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Timeout validation
+// ---------------------------------------------------------------------------
+
+export interface NormalizeTimeoutOptions {
+	/** Requested timeout value from tool params, if any. */
+	requested?: number;
+	/** Global default when no timeout is specified. */
+	defaultValue?: number;
+	/** Absolute maximum allowed value. */
+	maxValue?: number;
+}
+
+export interface NormalizeTimeoutResult {
+	/** The validated timeout in milliseconds, or undefined if none was set and no default applies. */
+	timeoutMs: number | undefined;
+	/** Error message if the value is invalid. */
+	error?: string;
+}
+
+/**
+ * Validate and normalise a timeout value.
+ *
+ * Rules:
+ * - Must be a finite integer if provided.
+ * - Must be positive (> 0).
+ * - Must not exceed maxValue.
+ * - If no value is provided, defaultValue is used.
+ * - Returns undefined only when no value and no default are configured.
+ */
+export function normalizeTimeout(options: NormalizeTimeoutOptions): NormalizeTimeoutResult {
+	const { requested, defaultValue = DEFAULT_TIMEOUT_MS, maxValue = MAX_TIMEOUT_MS } = options;
+
+	if (requested === undefined || requested === null) {
+		// No explicit timeout — apply default.
+		return { timeoutMs: defaultValue };
+	}
+
+	if (typeof requested !== "number" || !Number.isFinite(requested)) {
+		return { timeoutMs: undefined, error: "Timeout must be a finite number." };
+	}
+
+	if (!Number.isInteger(requested)) {
+		return { timeoutMs: undefined, error: "Timeout must be an integer (milliseconds)." };
+	}
+
+	if (requested <= 0) {
+		return { timeoutMs: undefined, error: "Timeout must be a positive integer." };
+	}
+
+	if (requested > maxValue) {
+		return {
+			timeoutMs: undefined,
+			error: `Timeout ${requested}ms exceeds maximum allowed ${maxValue}ms (${maxValue / 60_000} minutes).`,
+		};
+	}
+
+	return { timeoutMs: requested };
+}
+
+// ---------------------------------------------------------------------------
+// Abort signal composition
+// ---------------------------------------------------------------------------
+
+/**
+ * Combine multiple abort signals into one, with correct listener cleanup.
+ *
+ * Works as a polyfill for AbortSignal.any() with proper cleanup semantics:
+ * - If any input signal is already aborted, the returned signal aborts immediately.
+ * - All event listeners are removed after the first abort or when `cleanup()` is called.
+ *
+ * Returns an object with the combined signal and a cleanup function.
+ * Callers MUST call `cleanup()` in a `finally` block.
+ */
+export function createCombinedAbortSignal(
+	signals: (AbortSignal | undefined | null | false)[],
+): { signal: AbortSignal; cleanup: () => void } {
+	const valid = signals.filter(Boolean) as AbortSignal[];
+
+	if (valid.length === 0) {
+		const controller = new AbortController();
+		return { signal: controller.signal, cleanup: () => {} };
+	}
+
+	if (valid.length === 1) {
+		return { signal: valid[0], cleanup: () => {} };
+	}
+
+	// Check if any is already aborted.
+	for (const sig of valid) {
+		if (sig.aborted) {
+			const controller = new AbortController();
+			controller.abort(sig.reason);
+			return { signal: controller.signal, cleanup: () => {} };
+		}
+	}
+
+	// Use native AbortSignal.any when available.
+	if (typeof (AbortSignal as any).any === "function") {
+		const combined = (AbortSignal as any).any(valid);
+		return { signal: combined, cleanup: () => {} };
+	}
+
+	// Manual fallback: create a controller and forward all signals.
+	const controller = new AbortController();
+	const listeners: Array<() => void> = [];
+
+	for (const sig of valid) {
+		const handler = () => {
+			controller.abort(sig.reason);
+		};
+		sig.addEventListener("abort", handler, { once: true });
+		listeners.push(() => sig.removeEventListener("abort", handler));
+	}
+
+	const cleanup = () => {
+		for (const remove of listeners) {
+			try {
+				remove();
+			} catch {
+				// Best-effort cleanup.
+			}
+		}
+	};
+
+	return { signal: controller.signal, cleanup };
+}
+
+// ---------------------------------------------------------------------------
+// Execution request validation
+// ---------------------------------------------------------------------------
+
+export const MAX_PARALLEL_TASKS = 8;
+export const MAX_CONCURRENCY = 4;
+export const MAX_CHAIN_LENGTH = 50;
+export const PER_TASK_OUTPUT_CAP = 50 * 1024; // 50 KB
+export const MAX_INSTRUCTIONS_LENGTH = 16 * 1024; // 16 KB
+
+export interface ValidateExecutionRequestOptions {
+	agentName?: string;
+	task?: string;
+	tasks?: unknown[];
+	chain?: unknown[];
+	timeout?: number;
+}
+
+export interface ValidationError {
+	field: string;
+	message: string;
+}
+
+/**
+ * Generic validation for execution requests.
+ * Enforces limits that TypeBox schemas may not cover, and defends against
+ * internal callers that bypass the public tool schema.
+ */
+export function validateExecutionRequest(
+	options: ValidateExecutionRequestOptions,
+): ValidationError[] {
+	const errors: ValidationError[] = [];
+
+	// Agent name
+	if (options.agentName !== undefined) {
+		if (typeof options.agentName !== "string" || options.agentName.trim().length === 0) {
+			errors.push({ field: "agent", message: "Agent name must be a non-empty string." });
+		}
+	}
+
+	// Task
+	if (options.task !== undefined) {
+		if (typeof options.task !== "string") {
+			errors.push({ field: "task", message: "Task must be a string." });
+		}
+	}
+
+	// Parallel tasks
+	if (options.tasks !== undefined) {
+		if (!Array.isArray(options.tasks)) {
+			errors.push({ field: "tasks", message: "Tasks must be an array." });
+		} else {
+			if (options.tasks.length > MAX_PARALLEL_TASKS) {
+				errors.push({
+					field: "tasks",
+					message: `Too many parallel tasks (${options.tasks.length}). Maximum is ${MAX_PARALLEL_TASKS}.`,
+				});
+			}
+			for (let i = 0; i < options.tasks.length; i++) {
+				const t = options.tasks[i] as Record<string, unknown>;
+				if (!t || typeof t.agent !== "string" || !t.agent.trim()) {
+					errors.push({ field: `tasks[${i}].agent`, message: "Agent name must be a non-empty string." });
+				}
+				if (typeof t.task !== "string") {
+					errors.push({ field: `tasks[${i}].task`, message: "Task must be a string." });
+				}
+			}
+		}
+	}
+
+	// Chain
+	if (options.chain !== undefined) {
+		if (!Array.isArray(options.chain)) {
+			errors.push({ field: "chain", message: "Chain must be an array." });
+		} else {
+			if (options.chain.length > MAX_CHAIN_LENGTH) {
+				errors.push({
+					field: "chain",
+					message: `Too many chain steps (${options.chain.length}). Maximum is ${MAX_CHAIN_LENGTH}.`,
+				});
+			}
+			for (let i = 0; i < options.chain.length; i++) {
+				const s = options.chain[i] as Record<string, unknown>;
+				if (!s || typeof s.agent !== "string" || !s.agent.trim()) {
+					errors.push({ field: `chain[${i}].agent`, message: "Agent name must be a non-empty string." });
+				}
+				if (typeof s.task !== "string") {
+					errors.push({ field: `chain[${i}].task`, message: "Task must be a string." });
+				}
+			}
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Truncate parallel task output to the per-task cap.
+ */
+export function truncateParallelOutput(output: string): string {
+	const byteLength = Buffer.byteLength(output, "utf8");
+	if (byteLength <= PER_TASK_OUTPUT_CAP) return output;
+
+	let truncated = output.slice(0, PER_TASK_OUTPUT_CAP);
+	while (Buffer.byteLength(truncated, "utf8") > PER_TASK_OUTPUT_CAP) {
+		truncated = truncated.slice(0, -1);
+	}
+	return `${truncated}\n\n[Output truncated: ${byteLength - Buffer.byteLength(truncated, "utf8")} bytes omitted.]`;
+}

package/extensions/service.ts

@@ -2,6 +2,12 @@ import { AuthStorage, type ExtensionContext } from "@earendil-works/pi-coding-ag
 import type { AgentConfig } from "./agents.ts";
 import { runSubAgent, type SubAgentResult } from "./runner.ts";
 import { resolveModel } from "./model.ts";
+import {
+	validateAgentTools,
+	normalizeTimeout,
+	resolveSafeCwd,
+	MAX_INSTRUCTIONS_LENGTH,
+} from "./security.ts";
 
 export const SUBAGENT_REQUEST_EVENT = "pi-subagent:run";
 
@@ -43,37 +49,42 @@ export async function runNamedAgent(options: {
 		// ponytail: env and headers stay on the parent modelRegistry — reuse it directly.
 	}
 
-	const timeoutController = options.timeout && options.timeout > 0 ? new AbortController() : undefined;
-	const timeoutId = timeoutController ? setTimeout(() => timeoutController.abort(), options.timeout) : undefined;
-	const signals = [options.signal, timeoutController?.signal].filter((value): value is AbortSignal => Boolean(value));
-	const signal = signals.length > 1
-		? typeof (AbortSignal as any).any === "function"
-			? (AbortSignal as any).any(signals)
-			: signals[0]
-		: signals[0];
-	const contract = options.instructions?.slice(0, 16 * 1024);
+	// Security: validate and normalise timeout.
+	const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
+
+	// Security: validate tools against allowlist.
+	const rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+	const toolValidation = validateAgentTools({ tools: rawTools });
+	if (toolValidation.errors.length > 0) {
+		throw new Error(`Tool validation errors for agent "${options.agent.name}": ${toolValidation.errors.join("; ")}`);
+	}
+
+	// Security: validate cwd (service caller must provide valid cwd).
+	// The service path uses the same policy as the tool path.
+	const safeCwd = resolveSafeCwd({ workspaceRoot: options.ctx.cwd, childCwd: options.cwd });
+	if (safeCwd.error) {
+		throw new Error(safeCwd.error);
+	}
+
+	const contract = options.instructions?.slice(0, MAX_INSTRUCTIONS_LENGTH);
 
 	try {
 		const result = await runSubAgent({
-			cwd: options.cwd,
+			cwd: safeCwd.path,
 			systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
 			task: options.task,
-			tools: (options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"]).filter((tool) => tool !== "subagent"),
+			tools: toolValidation.tools,
 			model,
 			authStorage,
 			modelRegistry,
-			signal,
+			signal: options.signal,
+			timeoutMs: effectiveTimeoutMs,
 			agentName: options.agent.name,
 			thinkingLevel: options.agent.thinking,
 			onMessage: options.onMessage,
 		});
-		if (timeoutController?.signal.aborted && !options.signal?.aborted) {
-			result.exitCode = 1;
-			result.stopReason = "timeout";
-			result.errorMessage ||= `Timeout after ${options.timeout}ms`;
-		}
 		return result;
 	} finally {
-		if (timeoutId) clearTimeout(timeoutId);
+		// No manual timeout handling needed — runSubAgent handles timeouts internally.
 	}
 }