@harperfast/harper-pro 5.0.25 → 5.1.0-beta.1

package/core/agent/operations.ts

@@ -0,0 +1,148 @@
+/**
+ * Operations API surface for the built-in agent (#626).
+ *
+ * Six handlers, all super_user-only — the auth check is inline because none
+ * of these ops are registered in `utility/operation_authorization.ts`'s
+ * `requiredPermissions` map. Without the inline gate, a non-SU request would
+ * fall through the standard flow and be allowed.
+ */
+
+import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
+import { OPERATIONS_ENUM } from '../utility/hdbTerms.ts';
+import { ClientError } from '../utility/errors/hdbError.ts';
+import { createSession, getSession, listSessions, appendMessage, resolveApproval, setStatus } from './session.ts';
+import type { AgentConfig, AgentMessage, AgentRunStatus } from './types.ts';
+
+export interface OperationDeps {
+	getConfig: () => AgentConfig;
+	setConfig: (patch: Partial<AgentConfig>) => AgentConfig;
+	startRun: (sessionId: string) => void;
+	cancelRun: (sessionId: string) => boolean;
+}
+
+export function buildOperations(deps: OperationDeps): OperationDefinition[] {
+	return [
+		{
+			name: OPERATIONS_ENUM.AGENT_PROMPT,
+			execute: async (op) => agentPrompt(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.GET_AGENT_SESSION,
+			execute: async (op) => getAgentSession(op),
+		},
+		{
+			name: OPERATIONS_ENUM.LIST_AGENT_SESSIONS,
+			execute: async (op) => listAgentSessions(op),
+		},
+		{
+			name: OPERATIONS_ENUM.CANCEL_AGENT_RUN,
+			execute: async (op) => cancelAgentRun(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.APPROVE_AGENT_ACTION,
+			execute: async (op) => approveAgentAction(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.SET_AGENT_CONFIG,
+			execute: async (op) => setAgentConfig(op, deps),
+		},
+	];
+}
+
+function requireSuperUser(op: any): void {
+	if (!op?.hdb_user?.role?.permission?.super_user) {
+		throw new ClientError('Agent operations require super_user', 403);
+	}
+}
+
+async function agentPrompt(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const config = deps.getConfig();
+	if (!config.enabled) {
+		throw new ClientError('Agent component is disabled (agent.enabled=false)', 409);
+	}
+	const message = String(op?.message ?? '').trim();
+	if (!message) throw new ClientError('message is required', 400);
+
+	let sessionId: string = op?.session_id;
+	if (sessionId) {
+		const existing = await getSession(sessionId);
+		if (!existing) throw new ClientError(`Unknown session ${sessionId}`, 404);
+		if (existing.status === 'running' || existing.status === 'awaiting_approval') {
+			throw new ClientError(
+				`Session ${sessionId} is ${existing.status}; resolve or cancel before sending another prompt`,
+				409
+			);
+		}
+		await appendMessage(sessionId, asUserMessage(message));
+	} else {
+		const created = await createSession({
+			user: op?.hdb_user?.username ?? config.user,
+			model: config.model,
+			provider: config.provider,
+			initialMessage: asUserMessage(message),
+		});
+		sessionId = created.session_id;
+	}
+
+	deps.startRun(sessionId);
+	return { session_id: sessionId, status: 'running' satisfies AgentRunStatus };
+}
+
+async function getAgentSession(op: any) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	if (!sessionId) throw new ClientError('session_id is required', 400);
+	const session = await getSession(sessionId);
+	if (!session) throw new ClientError(`Unknown session ${sessionId}`, 404);
+	return session;
+}
+
+async function listAgentSessions(op: any) {
+	requireSuperUser(op);
+	const limit = Number.isFinite(op?.limit) ? Number(op.limit) : undefined;
+	return { sessions: await listSessions({ limit }) };
+}
+
+async function cancelAgentRun(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	if (!sessionId) throw new ClientError('session_id is required', 400);
+	const session = await getSession(sessionId);
+	if (!session) throw new ClientError(`Unknown session ${sessionId}`, 404);
+	// Abort any active controller (best-effort — there may not be one if the loop is paused
+	// in `awaiting_approval` or sitting `idle` between turns). Always update the persisted
+	// status so a paused session can still be terminated by the operator.
+	const signalledLiveRun = deps.cancelRun(sessionId);
+	const wasTerminal = session.status === 'completed' || session.status === 'aborted' || session.status === 'error';
+	if (!wasTerminal) await setStatus(sessionId, 'aborted', 'Cancelled by operator');
+	return { cancelled: !wasTerminal, signalledLiveRun };
+}
+
+async function approveAgentAction(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	const approvalId = String(op?.approval_id ?? '');
+	if (!sessionId || !approvalId) {
+		throw new ClientError('session_id and approval_id are required', 400);
+	}
+	const approved = op?.approved !== false;
+	const resolved = await resolveApproval(sessionId, approvalId, approved);
+	// Either decision should resume the loop: an approval means execute the saved tool call;
+	// a denial means hand the operator-rejection observation back to the model so it can adjust.
+	deps.startRun(sessionId);
+	return resolved;
+}
+
+async function setAgentConfig(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const patch: Partial<AgentConfig> = {};
+	for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
+		if (op?.[key] !== undefined) (patch as any)[key] = op[key];
+	}
+	return deps.setConfig(patch);
+}
+
+function asUserMessage(content: string): AgentMessage {
+	return { role: 'user', content, createdAt: Date.now() };
+}

package/core/agent/session.ts

@@ -0,0 +1,187 @@
+/**
+ * Built-in agent session storage. Backed by `system.hdb_agent_session` so
+ * transcripts and pending approvals survive restarts. The exported helpers
+ * are async to keep the surface uniform — once the underlying store gains
+ * non-blocking paths the call sites won't have to change.
+ *
+ * Intentionally separate from #511's `ConversationResource`: that primitive
+ * is app-facing (per-tenant, multi-user, user-defined schema) while this
+ * table is server-local and operator-owned.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { table } from '../resources/databases.ts';
+import { SYSTEM_SCHEMA_NAME, SYSTEM_TABLE_NAMES } from '../utility/hdbTerms.ts';
+import type { AgentMessage, AgentRunStatus, AgentSessionRow, ApprovalRequest } from './types.ts';
+
+let cachedTable: any;
+
+export function getAgentSessionTable(): any {
+	if (cachedTable) return cachedTable;
+	cachedTable = table({
+		table: SYSTEM_TABLE_NAMES.AGENT_SESSION_TABLE_NAME,
+		database: SYSTEM_SCHEMA_NAME,
+		audit: true,
+		trackDeletes: false,
+		attributes: [
+			{ name: 'session_id', isPrimaryKey: true },
+			{ name: 'user', type: 'string', indexed: true },
+			{ name: 'status', type: 'string', indexed: true },
+			{ name: 'messages' },
+			{ name: 'pendingApprovals' },
+			{ name: 'model', type: 'string' },
+			{ name: 'provider', type: 'string' },
+			{ name: 'createdAt', type: 'number', indexed: true },
+			{ name: 'updatedAt', type: 'number', indexed: true },
+			{ name: 'lastError', type: 'string' },
+		],
+	});
+	return cachedTable;
+}
+
+export interface CreateSessionOpts {
+	sessionId?: string;
+	user: string;
+	model?: string;
+	provider?: string;
+	initialMessage?: AgentMessage;
+}
+
+export async function createSession(opts: CreateSessionOpts): Promise<AgentSessionRow> {
+	const now = Date.now();
+	const row: AgentSessionRow = {
+		session_id: opts.sessionId ?? randomUUID(),
+		user: opts.user,
+		status: 'idle',
+		messages: opts.initialMessage ? [opts.initialMessage] : [],
+		pendingApprovals: [],
+		model: opts.model,
+		provider: opts.provider,
+		createdAt: now,
+		updatedAt: now,
+	};
+	await getAgentSessionTable().primaryStore.put(row.session_id, row);
+	return row;
+}
+
+export async function getSession(sessionId: string): Promise<AgentSessionRow | undefined> {
+	return getAgentSessionTable().primaryStore.get(sessionId);
+}
+
+export async function listSessions(opts: { limit?: number } = {}): Promise<AgentSessionRow[]> {
+	const limit = opts.limit ?? 100;
+	const out: AgentSessionRow[] = [];
+	for (const entry of getAgentSessionTable().primaryStore.getRange({ reverse: true, limit })) {
+		if (entry.value) out.push(entry.value as AgentSessionRow);
+	}
+	return out;
+}
+
+/**
+ * Per-session mutation lock. Each row mutation is a read-modify-write against the table; without
+ * serialization, two concurrent mutations on the same session (e.g. the loop appending an assistant
+ * message while the operator resolves an approval) both read the same row and the second `put`
+ * clobbers the first — a lost update. This chains all mutations for a given session id so they
+ * apply sequentially. Reads (`getSession`/`listSessions`) intentionally don't take the lock.
+ */
+const sessionLocks = new Map<string, Promise<unknown>>();
+
+function withSessionLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+	const prev = (sessionLocks.get(sessionId) ?? Promise.resolve()).catch(() => {});
+	const result = prev.then(() => fn());
+	const tail = result.catch(() => {});
+	sessionLocks.set(sessionId, tail);
+	void tail.then(() => {
+		if (sessionLocks.get(sessionId) === tail) sessionLocks.delete(sessionId);
+	});
+	return result;
+}
+
+export function appendMessage(sessionId: string, message: AgentMessage): Promise<AgentSessionRow> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		session.messages.push(message);
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return session;
+	});
+}
+
+export function setStatus(sessionId: string, status: AgentRunStatus, lastError?: string): Promise<AgentSessionRow> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		session.status = status;
+		session.lastError = lastError;
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return session;
+	});
+}
+
+export function addPendingApproval(
+	sessionId: string,
+	approval: Omit<ApprovalRequest, 'id' | 'createdAt'>
+): Promise<ApprovalRequest> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry: ApprovalRequest = { ...approval, id: randomUUID(), createdAt: Date.now() };
+		session.pendingApprovals.push(entry);
+		session.status = 'awaiting_approval';
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return entry;
+	});
+}
+
+export function markApprovalConsumed(sessionId: string, approvalId: string): Promise<void> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+		if (!entry) throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+		if (!entry.resolved) throw new Error(`Approval ${approvalId} not yet resolved`);
+		if (entry.consumed) return;
+		entry.consumed = true;
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+	});
+}
+
+export function resolveApproval(sessionId: string, approvalId: string, approved: boolean): Promise<ApprovalRequest> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+		if (!entry) throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+		if (entry.resolved) throw new Error(`Approval ${approvalId} already resolved`);
+		entry.resolved = true;
+		entry.approved = approved;
+		entry.resolvedAt = Date.now();
+		// Either decision (approve or deny) returns the session to a resumable `idle` state so the
+		// loop can run again and deliver the resulting observation to the model. Operators who want
+		// to terminate the whole run should use `cancel_agent_run` instead of denying.
+		if (!session.pendingApprovals.some((a) => !a.resolved)) {
+			session.status = 'idle';
+		}
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return entry;
+	});
+}
+
+async function requireSession(sessionId: string): Promise<AgentSessionRow> {
+	const session = await getSession(sessionId);
+	if (!session) throw new Error(`No agent session ${sessionId}`);
+	return session;
+}
+
+/**
+ * Reset the cached table reference. Test-only seam; production code lets the
+ * lazy-getter initialize once per process.
+ */
+export function _resetForTests(): void {
+	cachedTable = undefined;
+}
+
+/** Inject a mock table accessor for unit tests. Pass `undefined` to restore the lazy default. */
+export function _setTableForTests(mock: any): void {
+	cachedTable = mock;
+}

package/core/agent/tools/fsTools.ts

@@ -0,0 +1,276 @@
+/**
+ * Operator-only filesystem tools for the built-in agent (#626).
+ *
+ * Every path is resolved against the configured scopes (componentsRoot,
+ * logDir, configDir) and rejected if it escapes them. Writes are restricted
+ * to `componentsRoot` — `logDir` and `configDir` are observation-only so
+ * the agent can read logs and inspect config without rewriting either.
+ *
+ * Lifted in spirit from the external `harper-agent` CLI's file tools; the
+ * sandboxing rules are tightened here because the in-process agent can
+ * reach more of the filesystem than a remote CLI.
+ */
+
+import { readFile, writeFile, readdir, stat, mkdir, realpath, lstat, open } from 'node:fs/promises';
+import { resolve, dirname, relative, sep, isAbsolute } from 'node:path';
+import type { AgentTool, AgentToolContext, AgentScopes } from '../types.ts';
+
+const MAX_READ_BYTES = 5 * 1024 * 1024; // 5 MiB
+const MAX_WRITE_BYTES = 5 * 1024 * 1024;
+const MAX_GREP_RESULTS = 500;
+const MAX_PATTERN_LENGTH = 1000;
+const DEFAULT_TAIL_LINES = 200;
+const TAIL_READ_BYTES = 1 * 1024 * 1024; // 1 MiB — enough for thousands of normal log lines
+
+type Access = 'read' | 'write';
+
+async function resolveScoped(scopes: AgentScopes, path: string, access: Access): Promise<string> {
+	const absolute = resolve(path);
+	const candidates = [scopes.componentsRoot];
+	if (access === 'read') {
+		candidates.push(scopes.logDir, scopes.configDir);
+	}
+	// Reject a symlink leaf. `safeRealPath` resolves existing symlinks via `realpath` (so a link to
+	// an out-of-scope *existing* file is caught by the isInside check below) — but a link whose
+	// target does NOT exist makes `realpath` throw, and the fallback returns the link's own in-scope
+	// path. `writeFile`/`readFile` then follow the link out of scope. An explicit lstat closes that
+	// gap: a legitimate component/log/config file is never a symlink.
+	try {
+		const linkStat = await lstat(absolute);
+		if (linkStat.isSymbolicLink()) {
+			throw new Error(`Refusing to ${access} through a symlink: ${path}`);
+		}
+	} catch (err) {
+		// ENOENT (path doesn't exist yet — normal for a new-file write) is fine; rethrow anything else
+		// (including our own symlink rejection).
+		if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') throw err;
+	}
+	const realAbsolute = await safeRealPath(absolute);
+	for (const root of candidates) {
+		const realRoot = await safeRealPath(root);
+		if (isInside(realAbsolute, realRoot)) return realAbsolute;
+	}
+	throw new Error(`Path is outside the agent's ${access} scope: ${path}`);
+}
+
+async function safeRealPath(p: string): Promise<string> {
+	try {
+		return await realpath(p);
+	} catch {
+		// Missing leaf is fine — resolve the deepest existing ancestor and join.
+		const parent = dirname(p);
+		if (parent === p) return p;
+		const parentReal = await safeRealPath(parent);
+		return resolve(parentReal, p.slice(parent.length + 1));
+	}
+}
+
+function isInside(child: string, parent: string): boolean {
+	const rel = relative(parent, child);
+	// On Windows, `path.relative` returns an absolute path when the two arguments are on
+	// different drive letters (e.g. C:\components vs D:\etc). Without this check the agent
+	// could escape its scope by naming a path on another drive.
+	if (isAbsolute(rel)) return false;
+	return rel === '' || (!rel.startsWith('..') && !rel.includes(`..${sep}`));
+}
+
+export const readFileTool: AgentTool = {
+	def: {
+		name: 'read_file',
+		description: 'Read a UTF-8 text file within componentsRoot, logDir, or configDir.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const st = await stat(path);
+		if (st.size > MAX_READ_BYTES) {
+			throw new Error(`File ${path} exceeds ${MAX_READ_BYTES}-byte read cap (size ${st.size})`);
+		}
+		const content = await readFile(path, 'utf8');
+		return { path, size: st.size, content };
+	},
+};
+
+export const writeFileTool: AgentTool = {
+	def: {
+		name: 'write_file',
+		description: 'Write a UTF-8 text file within componentsRoot. Creates parent directories as needed.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path under componentsRoot.' },
+				content: { type: 'string', description: 'UTF-8 file contents.' },
+			},
+			required: ['path', 'content'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const content = String(args.content ?? '');
+		if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES) {
+			throw new Error(`Write exceeds ${MAX_WRITE_BYTES}-byte cap`);
+		}
+		const path = await resolveScoped(ctx.scopes, args.path, 'write');
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile(path, content, 'utf8');
+		return { path, bytesWritten: Buffer.byteLength(content, 'utf8') };
+	},
+	destructive: true,
+};
+
+export const listDirTool: AgentTool = {
+	def: {
+		name: 'list_dir',
+		description: 'List the immediate entries in a directory within an allowed scope.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const entries = await readdir(path, { withFileTypes: true });
+		return {
+			path,
+			entries: entries.map((e) => ({
+				name: e.name,
+				kind: e.isDirectory() ? 'directory' : e.isFile() ? 'file' : 'other',
+			})),
+		};
+	},
+};
+
+export const grepFilesTool: AgentTool = {
+	def: {
+		name: 'grep_files',
+		description: 'Search recursively under a scoped directory for a regex pattern. Returns matched lines.',
+		parameters: {
+			type: 'object',
+			properties: {
+				root: { type: 'string', description: 'Directory to search under.' },
+				pattern: { type: 'string', description: 'JavaScript-compatible regular expression source.' },
+				flags: { type: 'string', description: 'Regex flags (default: "i").' },
+				maxResults: { type: 'integer', minimum: 1, maximum: MAX_GREP_RESULTS },
+			},
+			required: ['root', 'pattern'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const root = await resolveScoped(ctx.scopes, args.root, 'read');
+		// Cap pattern length. A maliciously crafted regex (e.g. nested quantifiers) can backtrack
+		// catastrophically and block the main thread; JS has no native per-match timeout. The agent
+		// is super_user-gated so this is self-inflicted DoS rather than a privilege boundary, but a
+		// length cap removes the easiest footgun without a worker-thread regex sandbox.
+		const patternSource = String(args.pattern ?? '');
+		if (patternSource.length > MAX_PATTERN_LENGTH) {
+			throw new Error(`grep pattern exceeds ${MAX_PATTERN_LENGTH}-char cap`);
+		}
+		const pattern = new RegExp(patternSource, args.flags ?? 'i');
+		const cap = Math.min(args.maxResults ?? MAX_GREP_RESULTS, MAX_GREP_RESULTS);
+		const results: Array<{ path: string; line: number; text: string }> = [];
+		await walk(root, async (file) => {
+			if (results.length >= cap) return false;
+			// `stat` first so a multi-GB log or database file can't be slurped into memory by a
+			// well-formed grep request. Anything over the read cap is silently skipped.
+			let size = 0;
+			try {
+				const st = await stat(file);
+				size = st.size;
+			} catch {
+				return true;
+			}
+			if (size > MAX_READ_BYTES) return true;
+			const text = await readFile(file, 'utf8').catch(() => '');
+			if (!text) return true;
+			const lines = text.split('\n');
+			for (let i = 0; i < lines.length; i++) {
+				if (results.length >= cap) return false;
+				if (pattern.test(lines[i])) results.push({ path: file, line: i + 1, text: lines[i] });
+			}
+			return true;
+		});
+		return { root, count: results.length, results };
+	},
+};
+
+export const tailFileTool: AgentTool = {
+	def: {
+		name: 'tail_file',
+		description: 'Return the last N lines of a UTF-8 file. Useful for log tails.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+				lines: { type: 'integer', minimum: 1, maximum: 5000 },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const wanted = Math.min(args.lines ?? DEFAULT_TAIL_LINES, 5000);
+		// Read only the trailing TAIL_READ_BYTES — a multi-GB log file otherwise OOMs the process.
+		const st = await stat(path);
+		const start = Math.max(0, st.size - TAIL_READ_BYTES);
+		const truncated = start > 0;
+		const fh = await open(path, 'r');
+		try {
+			const buf = Buffer.alloc(st.size - start);
+			await fh.read(buf, 0, buf.length, start);
+			const text = buf.toString('utf8');
+			const all = text.split('\n');
+			// `split('\n')` on a file ending with `\n` leaves a trailing empty entry — drop it so the
+			// "last N lines" the agent sees matches what a human reading the file would see.
+			if (all.length > 0 && all[all.length - 1] === '') all.pop();
+			// When we read from a mid-file offset the first "line" is almost certainly a partial
+			// fragment of a real line. Drop it so we don't hand the agent a misleading prefix.
+			if (truncated && all.length > 0) all.shift();
+			const sliceStart = Math.max(0, all.length - wanted);
+			return { path, lines: all.slice(sliceStart), truncated };
+		} finally {
+			await fh.close();
+		}
+	},
+};
+
+export const fsTools: AgentTool[] = [readFileTool, writeFileTool, listDirTool, grepFilesTool, tailFileTool];
+
+async function walk(root: string, visit: (file: string) => Promise<boolean>): Promise<void> {
+	// Resolve the scope root once via realpath so the per-entry symlink check below has a
+	// stable comparison anchor; otherwise a symlink in the root itself could shift the anchor.
+	const realRoot = await safeRealPath(root);
+	const stack: string[] = [root];
+	while (stack.length) {
+		const dir = stack.pop()!;
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = resolve(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === 'node_modules' || entry.name === '.git') continue;
+				// Re-resolve via realpath so a symlinked directory pointing outside the scope is rejected.
+				// Without this, `componentsRoot/escape -> /etc` would let grep walk into /etc.
+				const realFull = await safeRealPath(full);
+				if (!isInside(realFull, realRoot)) continue;
+				stack.push(full);
+			} else if (entry.isFile()) {
+				const realFull = await safeRealPath(full);
+				if (!isInside(realFull, realRoot)) continue;
+				const proceed = await visit(full);
+				if (proceed === false) return;
+			}
+		}
+	}
+}