@bbigbang/core 0.1.0

package/dist/services/agentFileAccessService.js

@@ -0,0 +1,1913 @@
+import path from 'node:path';
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { AgentWorkspaceServiceError, mapAgentWorkspaceError } from './agentWorkspaceService.js';
+const PATH_SEGMENT_PATTERN = '[A-Za-z0-9._~@%+=,-]+';
+const ABSOLUTE_PATH_RE = new RegExp(`(^|[\\s"'\\\`([{<])((?:/${PATH_SEGMENT_PATTERN})+/?)(?::\\d+(?::\\d+)?)?(?=$|[\\s"'\\\`)\\]}>;,!?，。；、])`, 'g');
+const RELATIVE_PATH_RE = new RegExp(`(^|[\\s"'\\\`([{<])((?:\\./)?${PATH_SEGMENT_PATTERN}(?:/${PATH_SEGMENT_PATTERN})+/?|(?:\\./)?${PATH_SEGMENT_PATTERN}/|${PATH_SEGMENT_PATTERN}\\.[A-Za-z0-9][A-Za-z0-9._~-]*)(?::\\d+(?::\\d+)?)?(?=$|[\\s"'\\\`)\\]}>;,!?，。；、])`, 'g');
+const FILE_EXTENSION_RE = /\.(?:avif|bmp|c|cc|cjs|cpp|cs|css|cts|env|gif|go|h|hpp|html|ico|java|jpeg|jpg|js|json|jsonl|jsx|kt|lock|log|md|mdx|mjs|mts|pdf|php|png|py|rb|rs|scss|sh|sql|svg|swift|tif|tiff|toml|ts|tsx|txt|webp|xml|yaml|yml)$/i;
+const CURRENT_ACCESS_INDEX_VERSION = 9;
+const DEFAULT_DIRECTORY_PAGE_LIMIT = 100;
+const MAX_DIRECTORY_PAGE_LIMIT = 200;
+const SINGLE_FILE_NAMES = new Set([
+    'AGENTS.md',
+    'Agents.md',
+    'CLAUDE.md',
+    'Dockerfile',
+    'Makefile',
+    'MEMORY.md',
+    'README.md',
+    'changelog.md',
+    'package.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    'tsconfig.json',
+    'vite.config.ts',
+]);
+export class AgentFileAccessServiceError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+export function getRunEventSeqCutoff(db, runId) {
+    if (!runId)
+        return null;
+    const row = db.prepare(`SELECT COALESCE(MAX(seq), 0) as maxSeq
+     FROM events
+     WHERE run_id = ?
+       AND method = 'node/event'`).get(runId);
+    return row?.maxSeq ?? 0;
+}
+export class AgentFileAccessService {
+    db;
+    getAgentById;
+    broker;
+    entryTokenSecret;
+    constructor(params) {
+        this.db = params.db;
+        this.getAgentById = params.getAgentById;
+        this.broker = params.broker;
+        this.entryTokenSecret = params.entryTokenSecret ?? 'agent-file-access-entry-token-secret';
+    }
+    recordEventAccesses(params) {
+        if (params.event.type !== 'tool.call' && params.event.type !== 'tool.result')
+            return;
+        const context = this.getRunContext(params.runId, params.conversationId);
+        if (!context.agentId)
+            return;
+        const candidates = extractPathCandidatesFromToolEvent(params.event, {
+            toolCall: params.event.type === 'tool.result'
+                ? this.loadToolCallEvent(params.runId, params.event.toolCallId)
+                : undefined,
+        });
+        if (candidates.length === 0)
+            return;
+        this.insertCandidates({
+            agentId: context.agentId,
+            nodeId: params.nodeId,
+            conversationId: context.conversationId,
+            runId: params.runId,
+            toolCallId: params.event.toolCallId,
+            candidates,
+            createdAt: params.createdAt ?? Date.now(),
+        });
+    }
+    ensureRunIndexed(runId) {
+        const indexed = this.db.prepare(`SELECT index_version as indexVersion
+       FROM agent_file_access_indexed_runs
+       WHERE run_id = ?`).get(runId);
+        if ((indexed?.indexVersion ?? 1) >= CURRENT_ACCESS_INDEX_VERSION)
+            return;
+        const context = this.getRunContext(runId);
+        if (!context.agentId) {
+            this.markRunIndexed(runId);
+            return;
+        }
+        if (!context.nodeId) {
+            this.markRunIndexed(runId);
+            return;
+        }
+        const agentId = context.agentId;
+        const nodeId = context.nodeId;
+        this.db.transaction(() => {
+            this.db.prepare(`DELETE FROM agent_file_accesses WHERE run_id = ?`).run(runId);
+            const rows = this.db.prepare(`SELECT payload_json as payloadJson, created_at as createdAt
+         FROM events
+         WHERE run_id = ?
+           AND method = 'node/event'
+           AND json_valid(payload_json)
+           AND json_extract(payload_json, '$.type') IN ('tool.call', 'tool.result')
+         ORDER BY seq ASC`).all(runId);
+            const toolCalls = new Map();
+            for (const row of rows) {
+                try {
+                    const event = JSON.parse(row.payloadJson);
+                    if (event.type !== 'tool.call' && event.type !== 'tool.result')
+                        continue;
+                    if (event.type === 'tool.call')
+                        toolCalls.set(event.toolCallId, event);
+                    const candidates = extractPathCandidatesFromToolEvent(event, {
+                        toolCall: event.type === 'tool.result' ? toolCalls.get(event.toolCallId) : undefined,
+                    });
+                    if (candidates.length === 0)
+                        continue;
+                    this.insertCandidates({
+                        agentId,
+                        nodeId,
+                        conversationId: context.conversationId,
+                        runId,
+                        toolCallId: event.toolCallId,
+                        candidates,
+                        createdAt: row.createdAt,
+                    });
+                }
+                catch {
+                    // Ignore malformed historical event payloads.
+                }
+            }
+            this.markRunIndexed(runId);
+        })();
+    }
+    getFileRefsForMessage(params) {
+        if (!params.runId || !params.content.trim())
+            return [];
+        const boundary = {
+            createdAt: params.createdAt,
+            seqCutoff: params.runEventSeqCutoff,
+        };
+        this.ensureRunIndexed(params.runId);
+        const accessCutoff = buildAccessBoundaryWhere(boundary);
+        const accesses = this.db.prepare(`SELECT access_id as accessId,
+              agent_id as agentId,
+              node_id as nodeId,
+              conversation_id as conversationId,
+              run_id as runId,
+              tool_call_id as toolCallId,
+              absolute_path as absolutePath,
+              kind,
+              source,
+              created_at as createdAt
+       FROM agent_file_accesses
+       WHERE agent_id = ?
+         AND run_id = ?
+         ${accessCutoff.sql}
+       ORDER BY length(absolute_path) DESC, created_at ASC`).all(params.agentId, params.runId, ...accessCutoff.params);
+        if (accesses.length === 0)
+            return [];
+        const refs = [];
+        const seen = new Set();
+        for (const token of scanMessagePathTokens(params.content)) {
+            const candidates = resolveTokenCandidates(token, accesses)
+                .filter((access) => this.accessEvidenceMatchesBoundary(access, token, boundary));
+            if (candidates.length !== 1)
+                continue;
+            const hit = candidates[0];
+            const key = `${token}:${hit.accessId}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            refs.push({
+                accessId: hit.accessId,
+                token,
+                absolutePath: hit.absolutePath,
+                kind: hit.kind,
+            });
+        }
+        return refs;
+    }
+    accessEvidenceMatchesBoundary(access, token, boundary) {
+        if (access.kind === 'directory') {
+            if (boundary.createdAt == null && boundary.seqCutoff == null)
+                return true;
+            return this.findLatestDirectoryEnumerationOutput(access, boundary) != null
+                || this.findLatestExplicitDirectoryAccess(access, boundary) != null;
+        }
+        if (token.endsWith('/'))
+            return false;
+        return this.accessExistsBeforeBoundary(access, boundary);
+    }
+    accessExistsBeforeBoundary(access, boundary) {
+        if (boundary.seqCutoff != null) {
+            const evidenceSeq = this.findAccessEvidenceSeq(access);
+            return evidenceSeq != null && evidenceSeq <= boundary.seqCutoff;
+        }
+        if (boundary.createdAt == null)
+            return true;
+        if (access.createdAt < boundary.createdAt)
+            return true;
+        if (access.createdAt > boundary.createdAt)
+            return false;
+        return false;
+    }
+    findAccessEvidenceSeq(access) {
+        if (!access.toolCallId)
+            return null;
+        const expectedType = access.source === 'tool_input' ? 'tool.call' : 'tool.result';
+        const row = this.db.prepare(`SELECT seq
+       FROM events
+       WHERE run_id = ?
+         AND method = 'node/event'
+         AND json_valid(payload_json)
+         AND json_extract(payload_json, '$.type') = ?
+         AND json_extract(payload_json, '$.toolCallId') = ?
+       ORDER BY seq DESC
+       LIMIT 1`).get(access.runId, expectedType, access.toolCallId);
+        return row?.seq ?? null;
+    }
+    async readAccess(params) {
+        const context = this.loadMessageAccessContext(params);
+        const { row, boundary, message } = context;
+        try {
+            if (row.kind === 'directory') {
+                const directory = await this.readAuthorizedDirectoryPath(row, row.absolutePath, message.messageId, boundary, {
+                    cursor: params.cursor,
+                    limit: params.limit,
+                });
+                if (directory)
+                    return directory;
+            }
+            const result = await this.broker.readExactPath(row.nodeId, row.absolutePath);
+            // Only list a directory when the access record was already typed as a directory.
+            // Unknown-to-file upgrades are useful for extensionless files, but unknown-to-directory
+            // must not auto-grant listing rights for sibling paths the agent never enumerated.
+            if (row.kind === 'unknown' && result.kind === 'file') {
+                this.db.prepare(`UPDATE agent_file_accesses
+           SET kind = 'file', updated_at = ?
+           WHERE access_id = ?`).run(Date.now(), row.accessId);
+            }
+            if (result.kind === 'directory' && row.kind !== 'directory') {
+                return {
+                    accessId: row.accessId,
+                    absolutePath: row.absolutePath,
+                    kind: 'directory',
+                    modifiedAt: result.modifiedAt,
+                };
+            }
+            return {
+                accessId: row.accessId,
+                absolutePath: row.absolutePath,
+                kind: result.kind,
+                ...(result.kind === 'file'
+                    ? {
+                        content: result.content,
+                        mimeType: result.mimeType,
+                        size: result.size,
+                        modifiedAt: result.modifiedAt,
+                    }
+                    : result.kind === 'directory'
+                        ? {
+                            entries: this.annotateDirectoryEntries(result.entries, row, message.messageId, boundary),
+                            directoryPage: result.directoryPage ?? singlePageInfo(result.entries.length),
+                            modifiedAt: result.modifiedAt,
+                        }
+                        : { modifiedAt: result.modifiedAt }),
+            };
+        }
+        catch (error) {
+            if (error instanceof AgentFileAccessServiceError)
+                throw error;
+            throw mapAgentFileAccessError(error);
+        }
+    }
+    async readDirectoryEntry(params) {
+        const context = this.loadMessageAccessContext(params);
+        const { row, boundary, message } = context;
+        const childPath = normalizeAbsolutePath(params.path)?.absolutePath;
+        if (!childPath) {
+            throw new AgentFileAccessServiceError(400, 'path must be an absolute path.');
+        }
+        if (childPath === row.absolutePath || !childPath.startsWith(`${row.absolutePath}/`)) {
+            throw new AgentFileAccessServiceError(403, 'Directory entry is outside the authorized directory.');
+        }
+        if (!this.verifyDirectoryEntryToken({
+            accessId: row.accessId,
+            messageId: context.message.messageId,
+            path: childPath,
+            token: params.entryToken,
+        })) {
+            throw new AgentFileAccessServiceError(403, 'Directory entry token is invalid.');
+        }
+        try {
+            if (this.isDirectoryPathAuthorized(row, childPath, boundary)) {
+                const directory = await this.readAuthorizedDirectoryPath(row, childPath, message.messageId, boundary, {
+                    cursor: params.cursor,
+                    limit: params.limit,
+                });
+                if (directory)
+                    return directory;
+            }
+            if (!this.isFilePathAuthorized(row, childPath, boundary)) {
+                throw new AgentFileAccessServiceError(403, 'Directory entry is not authorized for this message.');
+            }
+            const result = await this.broker.readExactPath(row.nodeId, childPath);
+            if (result.kind !== 'file') {
+                throw new AgentFileAccessServiceError(403, 'Directory entry is not authorized for listing.');
+            }
+            return {
+                accessId: row.accessId,
+                absolutePath: result.absolutePath,
+                kind: 'file',
+                content: result.content,
+                mimeType: result.mimeType,
+                size: result.size,
+                modifiedAt: result.modifiedAt,
+            };
+        }
+        catch (error) {
+            if (error instanceof AgentFileAccessServiceError)
+                throw error;
+            throw mapAgentFileAccessError(error);
+        }
+    }
+    async streamAccess(params) {
+        const { row } = this.loadMessageAccessContext(params);
+        if (row.kind === 'directory') {
+            throw new AgentFileAccessServiceError(400, 'Directory records cannot be streamed as files.');
+        }
+        try {
+            return await this.broker.streamExactPath(row.nodeId, row.absolutePath);
+        }
+        catch (error) {
+            throw mapAgentFileAccessError(error);
+        }
+    }
+    async streamDirectoryEntry(params) {
+        const context = this.loadMessageAccessContext(params);
+        const { row, boundary } = context;
+        const childPath = normalizeAbsolutePath(params.path)?.absolutePath;
+        if (!childPath) {
+            throw new AgentFileAccessServiceError(400, 'path must be an absolute path.');
+        }
+        if (childPath === row.absolutePath || !childPath.startsWith(`${row.absolutePath}/`)) {
+            throw new AgentFileAccessServiceError(403, 'Directory entry is outside the authorized directory.');
+        }
+        if (!this.verifyDirectoryEntryToken({
+            accessId: row.accessId,
+            messageId: context.message.messageId,
+            path: childPath,
+            token: params.entryToken,
+        })) {
+            throw new AgentFileAccessServiceError(403, 'Directory entry token is invalid.');
+        }
+        if (!this.isFilePathAuthorized(row, childPath, boundary)) {
+            throw new AgentFileAccessServiceError(403, 'Directory entry is not authorized for this message.');
+        }
+        try {
+            return await this.broker.streamExactPath(row.nodeId, childPath);
+        }
+        catch (error) {
+            throw mapAgentFileAccessError(error);
+        }
+    }
+    loadMessageAccessContext(params) {
+        const row = this.db.prepare(`SELECT access_id as accessId,
+              agent_id as agentId,
+              node_id as nodeId,
+              conversation_id as conversationId,
+              run_id as runId,
+              tool_call_id as toolCallId,
+              absolute_path as absolutePath,
+              kind,
+              source,
+              created_at as createdAt
+       FROM agent_file_accesses
+       WHERE access_id = ?`).get(params.accessId);
+        if (!row || row.agentId !== params.agentId) {
+            throw new AgentFileAccessServiceError(404, 'File access record not found.');
+        }
+        const messageId = params.messageId.trim();
+        if (!messageId) {
+            throw new AgentFileAccessServiceError(400, 'messageId is required.');
+        }
+        const message = this.db.prepare(`SELECT run_id as runId,
+              sender_id as senderId,
+              content,
+              created_at as createdAt,
+              run_event_seq_cutoff as runEventSeqCutoff
+       FROM channel_messages
+       WHERE message_id = ?`).get(messageId);
+        if (!message || message.runId !== row.runId || message.senderId !== row.agentId) {
+            throw new AgentFileAccessServiceError(403, 'File access record does not belong to this message.');
+        }
+        const refs = this.getFileRefsForMessage({
+            agentId: row.agentId,
+            runId: row.runId,
+            content: message.content,
+            createdAt: message.createdAt,
+            runEventSeqCutoff: message.runEventSeqCutoff,
+        });
+        if (!refs.some((ref) => ref.accessId === row.accessId)) {
+            throw new AgentFileAccessServiceError(403, 'File access record is not bound to this message.');
+        }
+        const agent = this.getAgentById(row.agentId);
+        if (!agent)
+            throw new AgentFileAccessServiceError(404, 'Agent not found.');
+        if (!row.nodeId)
+            throw new AgentFileAccessServiceError(409, 'File access record has no source node.');
+        return {
+            row,
+            message: { ...message, messageId },
+            agent,
+            boundary: { createdAt: message.createdAt, seqCutoff: message.runEventSeqCutoff },
+        };
+    }
+    async readAuthorizedDirectoryPath(rootRow, directoryPath, messageId, boundary, options) {
+        const directoryRow = this.directoryRowForPath(rootRow, directoryPath);
+        const directorySnapshot = this.findLatestDirectoryEnumerationOutput(directoryRow, boundary);
+        const explicitDirectoryAccess = this.findLatestExplicitDirectoryAccess(directoryRow, boundary);
+        const snapshotWins = directorySnapshot
+            && (explicitDirectoryAccess == null || compareRunEventPositions(directorySnapshot.position, explicitDirectoryAccess) >= 0);
+        if (snapshotWins && directorySnapshot.mode === 'snapshot') {
+            const entries = this.annotateDirectoryEntries(buildEnumeratedDirectoryEntries(directoryPath, directorySnapshot.candidates), rootRow, messageId, boundary);
+            const page = paginateDirectoryEntries(entries, options);
+            return {
+                accessId: rootRow.accessId,
+                absolutePath: directoryPath,
+                kind: 'directory',
+                entries: page.entries,
+                directoryPage: page.directoryPage,
+                modifiedAt: null,
+            };
+        }
+        if (!explicitDirectoryAccess && !(snapshotWins && directorySnapshot.mode === 'root_only_traversal'))
+            return null;
+        const result = options.cursor || typeof options.limit === 'number'
+            ? await this.broker.readExactPath(rootRow.nodeId, directoryPath, options)
+            : await this.broker.readExactPath(rootRow.nodeId, directoryPath);
+        if (result.kind !== 'directory') {
+            throw new AgentFileAccessServiceError(403, 'Authorized directory path is not a directory.');
+        }
+        return {
+            accessId: rootRow.accessId,
+            absolutePath: result.absolutePath,
+            kind: 'directory',
+            entries: this.annotateDirectoryEntries(result.entries, rootRow, messageId, boundary),
+            directoryPage: result.directoryPage ?? singlePageInfo(result.entries.length),
+            modifiedAt: result.modifiedAt,
+        };
+    }
+    annotateDirectoryEntries(entries, rootRow, messageId, boundary) {
+        return entries.map((entry) => {
+            const canOpen = entry.kind === 'file'
+                ? this.isFilePathAuthorized(rootRow, entry.path, boundary)
+                : this.isDirectoryPathAuthorized(rootRow, entry.path, boundary);
+            return {
+                ...entry,
+                canOpen,
+                ...(canOpen
+                    ? {
+                        entryToken: this.signDirectoryEntryToken({
+                            accessId: rootRow.accessId,
+                            messageId,
+                            path: entry.path,
+                        }),
+                    }
+                    : {}),
+            };
+        });
+    }
+    signDirectoryEntryToken(params) {
+        const payload = Buffer.from(JSON.stringify(params), 'utf8').toString('base64url');
+        const signature = createHmac('sha256', this.entryTokenSecret).update(payload).digest('base64url');
+        return `${payload}.${signature}`;
+    }
+    verifyDirectoryEntryToken(params) {
+        const [payload, signature] = params.token.split('.');
+        if (!payload || !signature)
+            return false;
+        const expectedSignature = createHmac('sha256', this.entryTokenSecret).update(payload).digest('base64url');
+        if (!safeEqual(signature, expectedSignature))
+            return false;
+        try {
+            const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+            return parsed.accessId === params.accessId
+                && parsed.messageId === params.messageId
+                && parsed.path === params.path;
+        }
+        catch {
+            return false;
+        }
+    }
+    isFilePathAuthorized(rootRow, filePath, boundary) {
+        if (filePath === rootRow.absolutePath || !filePath.startsWith(`${rootRow.absolutePath}/`))
+            return false;
+        const parentDirectory = path.posix.dirname(filePath);
+        const parentView = this.getDirectoryAuthorizationView(rootRow, parentDirectory, boundary);
+        if (parentView === 'explicit')
+            return true;
+        if (parentView !== 'snapshot')
+            return false;
+        const snapshot = this.findLatestDirectoryEnumerationOutput(this.directoryRowForPath(rootRow, parentDirectory), boundary);
+        return Boolean(snapshot?.candidates.some((candidate) => candidate.absolutePath === filePath && candidate.kind !== 'directory'));
+    }
+    isDirectoryPathAuthorized(rootRow, directoryPath, boundary) {
+        if (directoryPath === rootRow.absolutePath)
+            return rootRow.kind === 'directory';
+        if (!directoryPath.startsWith(`${rootRow.absolutePath}/`))
+            return false;
+        return this.getDirectoryAuthorizationView(rootRow, directoryPath, boundary) != null;
+    }
+    getDirectoryAuthorizationView(rootRow, directoryPath, boundary) {
+        const directoryRow = this.directoryRowForPath(rootRow, directoryPath);
+        const snapshot = this.findLatestDirectoryEnumerationOutput(directoryRow, boundary);
+        const explicit = this.findLatestExplicitDirectoryAccess(directoryRow, boundary);
+        if (snapshot && (explicit == null || compareRunEventPositions(snapshot.position, explicit) >= 0)) {
+            return snapshot.mode === 'root_only_traversal' ? 'explicit' : 'snapshot';
+        }
+        if (explicit)
+            return 'explicit';
+        return null;
+    }
+    directoryRowForPath(row, directoryPath) {
+        return {
+            ...row,
+            absolutePath: directoryPath,
+            kind: 'directory',
+        };
+    }
+    findLatestDirectoryEnumerationOutput(row, boundary) {
+        const cutoff = buildEventBoundaryWhere(boundary, 'created_at', 'seq');
+        const results = this.db.prepare(`SELECT payload_json as payloadJson,
+              created_at as createdAt,
+              seq
+       FROM events
+       WHERE run_id = ?
+         AND method = 'node/event'
+         AND json_valid(payload_json)
+         AND json_extract(payload_json, '$.type') = 'tool.result'
+         ${cutoff.sql}
+       ORDER BY created_at DESC, seq DESC`).all(row.runId, ...cutoff.params);
+        for (const resultRow of results) {
+            try {
+                const event = JSON.parse(resultRow.payloadJson);
+                if (event.type !== 'tool.result')
+                    continue;
+                const toolCall = this.loadToolCallEvent(row.runId, event.toolCallId);
+                if (!toolCall)
+                    continue;
+                const cwd = findCwd(toolCall.input);
+                const countOnlyRoots = collectShellCountOnlyDirectoryRootPaths(toolCall.input, cwd);
+                const roots = [...new Set([
+                        ...collectShellDirectoryRootPaths(toolCall.input, cwd),
+                        ...countOnlyRoots,
+                    ])];
+                if (roots.length === 0)
+                    continue;
+                if (!roots.some((root) => row.absolutePath === root || row.absolutePath.startsWith(`${root}/`)))
+                    continue;
+                const outputCandidates = extractPathCandidatesFromToolOutput(event.output, toolCall);
+                const position = { createdAt: resultRow.createdAt, seq: resultRow.seq };
+                if (roots.some((root) => root === row.absolutePath)
+                    || outputCandidates.some((candidate) => (candidate.absolutePath.startsWith(`${row.absolutePath}/`)
+                        || (candidate.absolutePath === row.absolutePath && candidate.kind === 'directory')))) {
+                    const hasChildOutput = outputCandidates.some((candidate) => candidate.absolutePath.startsWith(`${row.absolutePath}/`));
+                    const isRootOnlyTraversal = countOnlyRoots.some((root) => root === row.absolutePath)
+                        && !hasChildOutput;
+                    return {
+                        candidates: outputCandidates,
+                        position,
+                        mode: isRootOnlyTraversal ? 'root_only_traversal' : 'snapshot',
+                    };
+                }
+            }
+            catch {
+                // Ignore malformed historical tool results.
+            }
+        }
+        return null;
+    }
+    findLatestExplicitDirectoryAccess(row, boundary) {
+        const cutoff = buildEventBoundaryWhere(boundary, 'created_at', 'seq');
+        const results = this.db.prepare(`SELECT payload_json as payloadJson,
+              created_at as createdAt,
+              seq
+       FROM events
+       WHERE run_id = ?
+         AND method = 'node/event'
+         AND json_valid(payload_json)
+         AND json_extract(payload_json, '$.type') = 'tool.call'
+         ${cutoff.sql}
+       ORDER BY created_at DESC, seq DESC`).all(row.runId, ...cutoff.params);
+        for (const resultRow of results) {
+            try {
+                const event = JSON.parse(resultRow.payloadJson);
+                if (event.type !== 'tool.call')
+                    continue;
+                const candidates = extractPathCandidatesFromToolEvent(event);
+                if (candidates.some((candidate) => (candidate.absolutePath === row.absolutePath
+                    && candidate.kind === 'directory'
+                    && !isDirectoryOutputToolCall(event)))) {
+                    return { createdAt: resultRow.createdAt, seq: resultRow.seq };
+                }
+            }
+            catch {
+                // Ignore malformed historical tool calls.
+            }
+        }
+        return null;
+    }
+    getRunContext(runId, fallbackConversationId) {
+        const row = this.db.prepare(`SELECT c.agent_id as agentId,
+              c.id as conversationId,
+              c.node_id as nodeId
+       FROM runs r
+       JOIN conversations c ON c.session_key = r.session_key
+       WHERE r.run_id = ?
+       LIMIT 1`).get(runId);
+        if (row)
+            return row;
+        if (fallbackConversationId) {
+            const fallback = this.db.prepare(`SELECT agent_id as agentId,
+                id as conversationId,
+                node_id as nodeId
+         FROM conversations
+         WHERE id = ?`).get(fallbackConversationId);
+            if (fallback)
+                return fallback;
+        }
+        return { agentId: null, conversationId: fallbackConversationId ?? '', nodeId: null };
+    }
+    insertCandidates(params) {
+        const stmt = this.db.prepare(`INSERT INTO agent_file_accesses(
+         access_id, agent_id, node_id, conversation_id, run_id, tool_call_id,
+         absolute_path, kind, source, created_at, updated_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(run_id, absolute_path) DO UPDATE SET
+         kind = CASE
+           WHEN agent_file_accesses.kind = 'unknown' AND excluded.kind IN ('file', 'directory') THEN excluded.kind
+           ELSE agent_file_accesses.kind
+	         END,
+	         source = CASE
+	           WHEN agent_file_accesses.kind = 'directory' AND excluded.source = 'tool_output_directory' THEN excluded.source
+	           WHEN agent_file_accesses.kind = 'unknown' AND excluded.kind IN ('file', 'directory') THEN excluded.source
+	           ELSE agent_file_accesses.source
+	         END,
+	         tool_call_id = CASE
+	           WHEN agent_file_accesses.kind = 'directory' AND excluded.source = 'tool_output_directory' THEN excluded.tool_call_id
+	           WHEN agent_file_accesses.kind = 'unknown' AND excluded.kind IN ('file', 'directory') THEN excluded.tool_call_id
+	           ELSE COALESCE(agent_file_accesses.tool_call_id, excluded.tool_call_id)
+	         END,
+         updated_at = excluded.updated_at`);
+        const seen = new Set();
+        for (const candidate of params.candidates) {
+            if (seen.has(candidate.absolutePath))
+                continue;
+            seen.add(candidate.absolutePath);
+            stmt.run(randomUUID(), params.agentId, params.nodeId, params.conversationId, params.runId, params.toolCallId, candidate.absolutePath, candidate.kind, candidate.source, params.createdAt, Date.now());
+        }
+    }
+    loadToolCallEvent(runId, toolCallId) {
+        const row = this.db.prepare(`SELECT payload_json as payloadJson
+       FROM events
+       WHERE run_id = ?
+         AND method = 'node/event'
+         AND json_valid(payload_json)
+         AND json_extract(payload_json, '$.type') = 'tool.call'
+         AND json_extract(payload_json, '$.toolCallId') = ?
+       ORDER BY seq DESC
+       LIMIT 1`).get(runId, toolCallId);
+        if (!row)
+            return undefined;
+        try {
+            const event = JSON.parse(row.payloadJson);
+            return event.type === 'tool.call' ? event : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    markRunIndexed(runId) {
+        this.db.prepare(`INSERT INTO agent_file_access_indexed_runs(run_id, indexed_at, index_version)
+       VALUES(?, ?, ?)
+       ON CONFLICT(run_id) DO UPDATE SET
+         indexed_at = excluded.indexed_at,
+         index_version = excluded.index_version`).run(runId, Date.now(), CURRENT_ACCESS_INDEX_VERSION);
+    }
+}
+function buildEnumeratedDirectoryEntries(directoryPath, candidates) {
+    const prefix = `${directoryPath}/`;
+    const entries = new Map();
+    for (const child of candidates) {
+        if (!child.absolutePath.startsWith(prefix) || child.absolutePath === directoryPath)
+            continue;
+        const suffix = child.absolutePath.slice(prefix.length);
+        const [name, ...rest] = suffix.split('/');
+        if (!name)
+            continue;
+        const isNested = rest.length > 0;
+        const entryPath = isNested ? `${prefix}${name}` : child.absolutePath;
+        const kind = isNested || child.kind === 'directory' ? 'directory' : 'file';
+        const existing = entries.get(entryPath);
+        if (existing?.kind === 'directory')
+            continue;
+        entries.set(entryPath, {
+            name,
+            path: entryPath,
+            kind,
+            size: null,
+            modifiedAt: null,
+        });
+    }
+    return [...entries.values()].sort((left, right) => {
+        if (left.kind !== right.kind)
+            return left.kind === 'directory' ? -1 : 1;
+        return left.name.localeCompare(right.name);
+    });
+}
+function paginateDirectoryEntries(entries, options) {
+    const limit = normalizeDirectoryLimit(options.limit);
+    const offset = parseDirectoryCursor(options.cursor);
+    const pageEntries = entries.slice(offset, offset + limit);
+    const nextOffset = offset + pageEntries.length;
+    const hasMore = nextOffset < entries.length;
+    return {
+        entries: pageEntries,
+        directoryPage: {
+            nextCursor: hasMore ? String(nextOffset) : null,
+            hasMore,
+            limit,
+        },
+    };
+}
+function normalizeDirectoryLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return DEFAULT_DIRECTORY_PAGE_LIMIT;
+    return Math.min(MAX_DIRECTORY_PAGE_LIMIT, Math.max(1, Math.floor(value)));
+}
+function parseDirectoryCursor(value) {
+    if (!value)
+        return 0;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return parsed;
+}
+function singlePageInfo(entryCount) {
+    return {
+        nextCursor: null,
+        hasMore: false,
+        limit: entryCount,
+    };
+}
+function safeEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    if (leftBuffer.length !== rightBuffer.length)
+        return false;
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+function buildEventBoundaryWhere(boundary, createdAtColumn, seqColumn) {
+    if (seqColumn && boundary.seqCutoff != null) {
+        return {
+            sql: `AND ${seqColumn} <= ?`,
+            params: [boundary.seqCutoff],
+        };
+    }
+    if (boundary.createdAt == null)
+        return { sql: '', params: [] };
+    return {
+        sql: `AND ${createdAtColumn} < ?`,
+        params: [boundary.createdAt],
+    };
+}
+function buildAccessBoundaryWhere(boundary) {
+    if (boundary.seqCutoff != null)
+        return { sql: '', params: [] };
+    if (boundary.createdAt == null)
+        return { sql: '', params: [] };
+    return { sql: 'AND created_at < ?', params: [boundary.createdAt] };
+}
+function compareRunEventPositions(left, right) {
+    if (left.createdAt !== right.createdAt)
+        return left.createdAt - right.createdAt;
+    return left.seq - right.seq;
+}
+function extractPathCandidatesFromToolEvent(event, context = {}) {
+    const candidates = [];
+    if (event.type === 'tool.call') {
+        const cwd = findCwd(event.input);
+        collectStructuredPathCandidates(event.input, cwd, 'tool_input', candidates);
+        collectShellCommandPathCandidates(event.input, cwd, candidates);
+    }
+    else if (shouldTrustToolResultPaths(context.toolCall)) {
+        const outputCandidates = extractPathCandidatesFromToolOutput(event.output, context.toolCall);
+        for (const candidate of outputCandidates) {
+            candidates.push(candidate);
+        }
+        candidates.push(...deriveDirectoryCandidatesFromToolOutput(outputCandidates, context.toolCall));
+    }
+    return dedupeCandidates(candidates);
+}
+const PATH_FIELD_NAMES = new Set([
+    'absolute_path',
+    'absolutePath',
+    'dir',
+    'directory',
+    'file',
+    'file_name',
+    'file_path',
+    'fileName',
+    'filepath',
+    'filePath',
+    'files',
+    'folder',
+    'path',
+    'paths',
+]);
+const COMMAND_FIELD_NAMES = new Set(['cmd', 'command', 'shellCommand']);
+const SCRIPT_RUNNER_COMMANDS = new Set(['bash', 'bun', 'deno', 'node', 'python', 'python3', 'sh', 'ts-node', 'tsx', 'zsh']);
+const SHELL_COMMAND_WRAPPERS = new Set(['bash', 'sh', 'zsh']);
+const DIRECTORY_OUTPUT_COMMANDS = new Set(['fd', 'find']);
+const DIRECTORY_COUNT_ONLY_COMMANDS = new Set(['fd', 'find', 'ls']);
+const FILE_OPERAND_COMMANDS = new Set([
+    'cat',
+    'fd',
+    'find',
+    'grep',
+    'head',
+    'less',
+    'ls',
+    'more',
+    'nl',
+    'rg',
+    'sed',
+    'tail',
+    'wc',
+    ...SCRIPT_RUNNER_COMMANDS,
+]);
+const OUTPUT_PATH_COMMANDS = new Set(['fd', 'find', 'grep', 'ls', 'rg']);
+const OPTIONS_WITH_VALUES = new Set([
+    '-A',
+    '-B',
+    '-C',
+    '-e',
+    '-f',
+    '-g',
+    '-I',
+    '-m',
+    '-o',
+    '-t',
+    '--after-context',
+    '--before-context',
+    '--color',
+    '--config',
+    '--context',
+    '--encoding',
+    '--exclude',
+    '--exclude-dir',
+    '--glob',
+    '--ignore-file',
+    '--include',
+    '--input',
+    '--max-count',
+    '--max-depth',
+    '--output',
+    '--path-separator',
+    '--regexp',
+    '--sort',
+    '--type',
+]);
+function collectStructuredPathCandidates(value, cwd, source, out, fieldName) {
+    if (typeof value === 'string') {
+        if (fieldName && PATH_FIELD_NAMES.has(fieldName)) {
+            out.push(...extractPathValueCandidates(value, cwd, source));
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectStructuredPathCandidates(item, cwd, source, out, fieldName);
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    const record = value;
+    const nestedCwd = typeof record.cwd === 'string'
+        ? normalizeAbsolutePath(record.cwd)?.absolutePath ?? cwd
+        : cwd;
+    for (const [key, item] of Object.entries(record)) {
+        if (key === 'cwd')
+            continue;
+        collectStructuredPathCandidates(item, nestedCwd, source, out, key);
+    }
+}
+function extractPathValueCandidates(value, cwd, source) {
+    const cleaned = cleanPathToken(value);
+    const normalizedAbsolute = normalizeAbsolutePath(cleaned);
+    if (normalizedAbsolute) {
+        return [{
+                absolutePath: normalizedAbsolute.absolutePath,
+                kind: inferPathKind(cleaned, cleaned),
+                source,
+            }];
+    }
+    if (!cwd || !isRelativeCandidate(cleaned))
+        return [];
+    const normalizedRelative = normalizeRelativePath(cwd, cleaned);
+    if (!normalizedRelative)
+        return [];
+    return [{
+            absolutePath: normalizedRelative,
+            kind: inferPathKind(cleaned, cleaned),
+            source,
+        }];
+}
+function collectShellCommandPathCandidates(value, fallbackCwd, out) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectShellCommandPathCandidates(item, fallbackCwd, out);
+        return;
+    }
+    const record = value;
+    const cwd = typeof record.cwd === 'string'
+        ? normalizeAbsolutePath(record.cwd)?.absolutePath ?? fallbackCwd
+        : fallbackCwd;
+    for (const [key, item] of Object.entries(record)) {
+        if (COMMAND_FIELD_NAMES.has(key) && typeof item === 'string') {
+            out.push(...extractShellCommandCandidates(item, cwd));
+            continue;
+        }
+        collectShellCommandPathCandidates(item, cwd, out);
+    }
+}
+function shouldTrustToolResultPaths(toolCall) {
+    if (!toolCall)
+        return false;
+    if (isFileSemanticToolName(toolCall.name))
+        return true;
+    return getShellCommandNames(toolCall.input).some((commandName) => OUTPUT_PATH_COMMANDS.has(commandName));
+}
+function isDirectoryOutputToolCall(toolCall) {
+    return getShellCommandNames(toolCall.input).some((commandName) => DIRECTORY_OUTPUT_COMMANDS.has(commandName));
+}
+function isDirectoryOnlyEnumerationToolCall(toolCall) {
+    return inputHasDirectoryOnlyEnumeration(toolCall.input);
+}
+function isFileSemanticToolName(name) {
+    return /(?:^|[_.-])(?:read|list|open|stat|glob|search|grep|find)(?:[_-]?(?:file|files|path|paths|dir|directory|workspace))?/i.test(name)
+        || /(?:file|workspace|fs|path|directory)(?:[_-]?(?:read|list|open|stat|glob|search|grep|find))?/i.test(name);
+}
+function getShellCommandNames(value) {
+    const names = [];
+    const collectSegmentName = (segment, depth = 0) => {
+        const commandName = normalizeShellCommandName(segment);
+        if (!commandName)
+            return;
+        names.push(commandName);
+        if (depth >= 4 || !SHELL_COMMAND_WRAPPERS.has(commandName))
+            return;
+        const nestedCommand = extractNestedShellCommand(segment);
+        if (!nestedCommand)
+            return;
+        for (const nestedSegment of splitShellSegments(tokenizeShellCommand(nestedCommand))) {
+            collectSegmentName(nestedSegment, depth + 1);
+        }
+    };
+    const visit = (item) => {
+        if (!item || typeof item !== 'object')
+            return;
+        if (Array.isArray(item)) {
+            for (const child of item)
+                visit(child);
+            return;
+        }
+        for (const [key, child] of Object.entries(item)) {
+            if (COMMAND_FIELD_NAMES.has(key) && typeof child === 'string') {
+                for (const segment of splitShellSegments(tokenizeShellCommand(child))) {
+                    collectSegmentName(segment);
+                }
+            }
+            else {
+                visit(child);
+            }
+        }
+    };
+    visit(value);
+    return names;
+}
+function inputHasDirectoryOnlyEnumeration(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some((item) => inputHasDirectoryOnlyEnumeration(item));
+    for (const [key, child] of Object.entries(value)) {
+        if (COMMAND_FIELD_NAMES.has(key) && typeof child === 'string') {
+            if (commandHasDirectoryOnlyEnumeration(child))
+                return true;
+        }
+        else if (inputHasDirectoryOnlyEnumeration(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+function commandHasDirectoryOnlyEnumeration(command) {
+    let sawDirectoryOnly = false;
+    let sawOtherDirectoryOutput = false;
+    for (const segment of splitShellSegments(tokenizeShellCommand(command))) {
+        const commandName = normalizeShellCommandName(segment);
+        if (!commandName)
+            continue;
+        if (SHELL_COMMAND_WRAPPERS.has(commandName)) {
+            const nestedCommand = extractNestedShellCommand(segment);
+            if (!nestedCommand)
+                continue;
+            const nestedMode = commandDirectoryEnumerationMode(nestedCommand);
+            if (nestedMode === 'directory_only')
+                sawDirectoryOnly = true;
+            if (nestedMode === 'mixed_or_unknown')
+                sawOtherDirectoryOutput = true;
+            continue;
+        }
+        if (!DIRECTORY_OUTPUT_COMMANDS.has(commandName))
+            continue;
+        if (segmentHasDirectoryOnlyTypeFilter(commandName, segment)) {
+            sawDirectoryOnly = true;
+        }
+        else {
+            sawOtherDirectoryOutput = true;
+        }
+    }
+    return sawDirectoryOnly && !sawOtherDirectoryOutput;
+}
+function extractShellCountOnlyDirectoryRoots(command, cwd) {
+    const roots = [];
+    const segments = splitShellPipelineSegments(tokenizeShellCommandPreservingPipes(command));
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const commandName = normalizeShellCommandName(segment.tokens);
+        if (!commandName)
+            continue;
+        if (SHELL_COMMAND_WRAPPERS.has(commandName)) {
+            const nestedCommand = extractNestedShellCommand(segment.tokens);
+            if (nestedCommand)
+                roots.push(...extractShellCountOnlyDirectoryRoots(nestedCommand, cwd));
+            continue;
+        }
+        if (!DIRECTORY_COUNT_ONLY_COMMANDS.has(commandName))
+            continue;
+        const next = segments[index + 1];
+        if (!segment.pipeToNext || !next || !isWcLineCountOnlySegment(next.tokens))
+            continue;
+        roots.push(...extractShellDirectoryRootsFromSegment(commandName, segment.tokens, cwd));
+    }
+    return [...new Set(roots)];
+}
+function extractShellDirectoryRootsFromSegment(commandName, segment, cwd) {
+    const roots = [];
+    const operands = collectShellOperands(segment);
+    const pathOperands = commandName === 'ls'
+        ? selectCountOnlyLsRootOperands(operands, segment)
+        : selectPathOperandsForCommand(commandName, operands, segment);
+    for (const operand of pathOperands) {
+        const root = commandName === 'ls'
+            ? absolutePathFromLsDirectoryRootToken(operand, cwd)
+            : absolutePathFromShellToken(operand, cwd, commandName);
+        if (root)
+            roots.push(root);
+    }
+    if (pathOperands.length === 0
+        && cwd
+        && (commandName === 'find'
+            || commandName === 'fd'
+            || (operands.length === 0 && !segmentHasLsDirectorySelfOption(segment)))) {
+        roots.push(cwd);
+    }
+    return [...new Set(roots)];
+}
+function selectCountOnlyLsRootOperands(operands, segment) {
+    if (segmentHasLsDirectorySelfOption(segment))
+        return [];
+    return operands.filter((operand) => isLsDirectoryRootOperand(operand));
+}
+function segmentHasLsDirectorySelfOption(segment) {
+    return segment.some((token) => token === '--directory' || /^-[A-Za-z]*d[A-Za-z]*$/.test(token));
+}
+function isWcLineCountOnlySegment(segment) {
+    const commandIndex = commandTokenIndex(segment);
+    if (commandIndex < 0)
+        return false;
+    const commandName = normalizeShellCommandName(segment);
+    if (commandName !== 'wc')
+        return false;
+    let hasLineCount = false;
+    for (let index = commandIndex + 1; index < segment.length; index += 1) {
+        const token = segment[index];
+        if (isShellRedirectionToken(token))
+            continue;
+        if (isShellRedirectionOperator(token)) {
+            index += 1;
+            continue;
+        }
+        if (token === '--')
+            continue;
+        if (token === '-l' || token === '--lines') {
+            hasLineCount = true;
+            continue;
+        }
+        if (/^-[A-Za-z]*l[A-Za-z]*$/.test(token)) {
+            hasLineCount = true;
+            continue;
+        }
+        if (token.startsWith('-'))
+            continue;
+        return false;
+    }
+    return hasLineCount;
+}
+function commandDirectoryEnumerationMode(command) {
+    let sawDirectoryOnly = false;
+    for (const segment of splitShellSegments(tokenizeShellCommand(command))) {
+        const commandName = normalizeShellCommandName(segment);
+        if (!commandName)
+            continue;
+        if (SHELL_COMMAND_WRAPPERS.has(commandName)) {
+            const nestedCommand = extractNestedShellCommand(segment);
+            if (!nestedCommand)
+                continue;
+            const nestedMode = commandDirectoryEnumerationMode(nestedCommand);
+            if (nestedMode === 'mixed_or_unknown')
+                return nestedMode;
+            if (nestedMode === 'directory_only')
+                sawDirectoryOnly = true;
+            continue;
+        }
+        if (!DIRECTORY_OUTPUT_COMMANDS.has(commandName))
+            continue;
+        if (!segmentHasDirectoryOnlyTypeFilter(commandName, segment))
+            return 'mixed_or_unknown';
+        sawDirectoryOnly = true;
+    }
+    return sawDirectoryOnly ? 'directory_only' : 'none';
+}
+function extractShellCommandCandidates(command, cwd) {
+    const candidates = [];
+    for (const segment of splitShellSegments(tokenizeShellCommand(command))) {
+        const commandName = normalizeShellCommandName(segment);
+        if (!commandName || !FILE_OPERAND_COMMANDS.has(commandName))
+            continue;
+        if (SHELL_COMMAND_WRAPPERS.has(commandName)) {
+            const nestedCommand = extractNestedShellCommand(segment);
+            if (nestedCommand) {
+                candidates.push(...extractShellCommandCandidates(nestedCommand, cwd));
+                continue;
+            }
+        }
+        const operands = collectShellOperands(segment);
+        const pathOperands = selectPathOperandsForCommand(commandName, operands, segment);
+        for (const operand of pathOperands) {
+            const candidate = pathCandidateFromShellToken(operand, cwd, commandName);
+            if (candidate)
+                candidates.push(candidate);
+        }
+    }
+    return candidates;
+}
+function extractShellDirectoryRoots(command, cwd) {
+    const roots = [];
+    for (const segment of splitShellSegments(tokenizeShellCommand(command))) {
+        const commandName = normalizeShellCommandName(segment);
+        if (!commandName)
+            continue;
+        if (SHELL_COMMAND_WRAPPERS.has(commandName)) {
+            const nestedCommand = extractNestedShellCommand(segment);
+            if (nestedCommand)
+                roots.push(...extractShellDirectoryRoots(nestedCommand, cwd));
+            continue;
+        }
+        if (!DIRECTORY_OUTPUT_COMMANDS.has(commandName))
+            continue;
+        const operands = collectShellOperands(segment);
+        const pathOperands = selectPathOperandsForCommand(commandName, operands, segment);
+        for (const operand of pathOperands) {
+            const root = absolutePathFromShellToken(operand, cwd, commandName);
+            if (root)
+                roots.push(root);
+        }
+        if (pathOperands.length === 0 && cwd)
+            roots.push(cwd);
+    }
+    return roots;
+}
+function extractNestedShellCommand(tokens) {
+    let commandSeen = false;
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!commandSeen) {
+            if (isShellAssignment(token) || token === 'env' || token === 'command' || token === 'time')
+                continue;
+            commandSeen = true;
+            continue;
+        }
+        if (token === '-c' || token === '-lc' || token === '-ec' || token === '-elc') {
+            return tokens[index + 1] ?? null;
+        }
+        if (token.startsWith('-') && token.includes('c') && tokens[index + 1]) {
+            return tokens[index + 1];
+        }
+    }
+    return null;
+}
+function tokenizeShellCommand(command) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else if (char === '\\' && quote !== "'" && i + 1 < command.length) {
+                i += 1;
+                current += command[i];
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            continue;
+        }
+        if (char === ';' || char === '|') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            if (char === '|' && command[i + 1] === '|')
+                i += 1;
+            tokens.push(';');
+            continue;
+        }
+        if (char === '&' && command[i + 1] === '&') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            tokens.push(';');
+            i += 1;
+            continue;
+        }
+        if ((char === '>' || char === '<') && current === '') {
+            const next = command[i + 1];
+            if (next === char) {
+                tokens.push(`${char}${next}`);
+                i += 1;
+            }
+            else {
+                tokens.push(char);
+            }
+            continue;
+        }
+        if (char === '\\' && i + 1 < command.length) {
+            i += 1;
+            current += command[i];
+            continue;
+        }
+        current += char;
+    }
+    if (current)
+        tokens.push(current);
+    return tokens;
+}
+function tokenizeShellCommandPreservingPipes(command) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else if (char === '\\' && quote !== "'" && i + 1 < command.length) {
+                i += 1;
+                current += command[i];
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            continue;
+        }
+        if (char === ';') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            tokens.push(';');
+            continue;
+        }
+        if (char === '|') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            if (command[i + 1] === '|') {
+                tokens.push(';');
+                i += 1;
+            }
+            else {
+                tokens.push('|');
+                if (command[i + 1] === '&')
+                    i += 1;
+            }
+            continue;
+        }
+        if (char === '&' && command[i + 1] === '&') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            tokens.push(';');
+            i += 1;
+            continue;
+        }
+        if ((char === '>' || char === '<') && current === '') {
+            const next = command[i + 1];
+            if (next === char) {
+                tokens.push(`${char}${next}`);
+                i += 1;
+            }
+            else {
+                tokens.push(char);
+            }
+            continue;
+        }
+        if (char === '\\' && i + 1 < command.length) {
+            i += 1;
+            current += command[i];
+            continue;
+        }
+        current += char;
+    }
+    if (current)
+        tokens.push(current);
+    return tokens;
+}
+function splitShellSegments(tokens) {
+    const segments = [];
+    let current = [];
+    for (const token of tokens) {
+        if (token === ';') {
+            if (current.length > 0)
+                segments.push(current);
+            current = [];
+        }
+        else {
+            current.push(token);
+        }
+    }
+    if (current.length > 0)
+        segments.push(current);
+    return segments;
+}
+function splitShellPipelineSegments(tokens) {
+    const segments = [];
+    let current = [];
+    for (const token of tokens) {
+        if (token === ';' || token === '|') {
+            if (current.length > 0) {
+                segments.push({ tokens: current, pipeToNext: token === '|' });
+            }
+            current = [];
+        }
+        else {
+            current.push(token);
+        }
+    }
+    if (current.length > 0)
+        segments.push({ tokens: current, pipeToNext: false });
+    return segments;
+}
+function normalizeShellCommandName(tokens) {
+    for (const token of tokens) {
+        if (isShellAssignment(token))
+            continue;
+        if (token === 'env' || token === 'command' || token === 'time')
+            continue;
+        return path.posix.basename(token).toLowerCase();
+    }
+    return null;
+}
+function collectShellOperands(tokens) {
+    const operands = [];
+    let commandSeen = false;
+    let skipNext = false;
+    for (const token of tokens) {
+        if (!commandSeen) {
+            if (isShellAssignment(token) || token === 'env' || token === 'command' || token === 'time')
+                continue;
+            commandSeen = true;
+            continue;
+        }
+        if (skipNext) {
+            skipNext = false;
+            continue;
+        }
+        if (token === '--')
+            continue;
+        if (isShellRedirectionToken(token))
+            continue;
+        if (isShellRedirectionOperator(token)) {
+            skipNext = true;
+            continue;
+        }
+        if (token.startsWith('-')) {
+            const optionName = token.includes('=') ? token.slice(0, token.indexOf('=')) : token;
+            if (OPTIONS_WITH_VALUES.has(optionName))
+                skipNext = !token.includes('=');
+            continue;
+        }
+        operands.push(token);
+    }
+    return operands;
+}
+function selectPathOperandsForCommand(commandName, operands, segment) {
+    if (SCRIPT_RUNNER_COMMANDS.has(commandName)) {
+        if (segment.includes('-m'))
+            return [];
+        const firstPath = operands.find((operand) => isShellPathLike(operand));
+        return firstPath ? [firstPath] : [];
+    }
+    if (commandName === 'find') {
+        return collectFindRootOperands(segment);
+    }
+    if (commandName === 'fd') {
+        return collectFdRootOperands(operands);
+    }
+    if ((commandName === 'rg' || commandName === 'grep') && !segment.includes('--files')) {
+        const pathOperands = operands.filter((operand) => isShellPathLike(operand));
+        if (pathOperands.length === 0)
+            return [];
+        const firstOperand = operands.find((operand) => !operand.startsWith('-'));
+        return firstOperand && pathOperands[0] === firstOperand ? pathOperands.slice(1) : pathOperands;
+    }
+    return operands.filter((operand) => isShellPathLike(operand));
+}
+function segmentHasDirectoryOnlyTypeFilter(commandName, segment) {
+    const types = commandName === 'find'
+        ? collectFindTypeFilters(segment)
+        : commandName === 'fd'
+            ? collectFdTypeFilters(segment)
+            : [];
+    return types.length > 0 && types.every((type) => type === 'directory');
+}
+function collectFindTypeFilters(segment) {
+    const commandIndex = commandTokenIndex(segment);
+    if (commandIndex < 0)
+        return [];
+    const types = [];
+    for (let index = commandIndex + 1; index < segment.length; index += 1) {
+        const token = segment[index];
+        if (token === '-type' && segment[index + 1]) {
+            types.push(normalizeFindType(segment[index + 1]));
+            index += 1;
+        }
+    }
+    return types.filter(Boolean);
+}
+function normalizeFindType(value) {
+    return value === 'd' ? 'directory' : value;
+}
+function collectFdTypeFilters(segment) {
+    const commandIndex = commandTokenIndex(segment);
+    if (commandIndex < 0)
+        return [];
+    const types = [];
+    for (let index = commandIndex + 1; index < segment.length; index += 1) {
+        const token = segment[index];
+        if ((token === '-t' || token === '--type') && segment[index + 1]) {
+            types.push(normalizeFdType(segment[index + 1]));
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--type=')) {
+            types.push(normalizeFdType(token.slice('--type='.length)));
+            continue;
+        }
+        const shortMatch = token.match(/^-t(.+)$/);
+        if (shortMatch) {
+            types.push(...shortMatch[1].split('').map(normalizeFdType));
+        }
+    }
+    return types.filter(Boolean);
+}
+function normalizeFdType(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === 'd' || normalized === 'dir' || normalized === 'directory')
+        return 'directory';
+    return normalized;
+}
+function pathCandidateFromShellToken(token, cwd, commandName) {
+    if (!isShellPathLike(token) && !isDirectoryRootOperand(commandName, token))
+        return null;
+    const kind = inferShellOperandKind(commandName, token);
+    const absolute = normalizeAbsolutePath(token);
+    if (absolute) {
+        return {
+            absolutePath: absolute.absolutePath,
+            kind,
+            source: 'tool_input',
+        };
+    }
+    if (!cwd)
+        return null;
+    const relative = normalizeRelativePath(cwd, token);
+    if (!relative)
+        return null;
+    return {
+        absolutePath: relative,
+        kind,
+        source: 'tool_input',
+    };
+}
+function inferShellOperandKind(commandName, token) {
+    const kind = inferPathKind(token, token);
+    if (isDirectoryRootOperand(commandName, token) && kind === 'unknown')
+        return 'directory';
+    void commandName;
+    return kind;
+}
+function absolutePathFromShellToken(token, cwd, commandName) {
+    if (!isShellPathLike(token) && !isDirectoryRootOperand(commandName, token))
+        return null;
+    const absolute = normalizeAbsolutePath(token);
+    if (absolute)
+        return absolute.absolutePath;
+    if (!cwd)
+        return null;
+    return normalizeRelativePath(cwd, token);
+}
+function absolutePathFromLsDirectoryRootToken(token, cwd) {
+    if (!isLsDirectoryRootOperand(token))
+        return null;
+    const absolute = normalizeAbsolutePath(token);
+    if (absolute)
+        return absolute.absolutePath;
+    if (!cwd)
+        return null;
+    if (token === '.')
+        return normalizeAbsolutePath(cwd)?.absolutePath ?? null;
+    return normalizeRelativePath(cwd, token);
+}
+function isShellPathLike(token) {
+    const cleaned = cleanPathToken(token);
+    if (!cleaned || cleaned.includes('*') || cleaned.includes('?') || cleaned.includes('[') || cleaned.includes(']')) {
+        return false;
+    }
+    return Boolean(normalizeAbsolutePath(cleaned)) || isRelativeCandidate(cleaned);
+}
+function isDirectoryRootOperand(commandName, token) {
+    if (commandName !== 'find' && commandName !== 'fd')
+        return false;
+    const cleaned = cleanPathToken(token).replace(/^\.\//, '');
+    if (!cleaned || cleaned.startsWith('-') || cleaned.includes('://') || hasParentPathSegment(cleaned))
+        return false;
+    if (cleaned.includes('*') || cleaned.includes('?') || cleaned.includes('[') || cleaned.includes(']'))
+        return false;
+    if (cleaned === '.')
+        return true;
+    if (normalizeAbsolutePath(cleaned) || isRelativeCandidate(cleaned))
+        return true;
+    if (cleaned.includes('/'))
+        return true;
+    if (SINGLE_FILE_NAMES.has(cleaned) || FILE_EXTENSION_RE.test(cleaned))
+        return false;
+    return /^[A-Za-z0-9._~@%+=,-]+$/.test(cleaned);
+}
+function isLsDirectoryRootOperand(token) {
+    const rawCleaned = cleanPathToken(token);
+    const cleaned = rawCleaned.replace(/^\.\//, '');
+    if (!cleaned || cleaned.startsWith('-') || cleaned.includes('://') || hasParentPathSegment(cleaned))
+        return false;
+    if (cleaned.includes('*') || cleaned.includes('?') || cleaned.includes('[') || cleaned.includes(']'))
+        return false;
+    if (cleaned === '.')
+        return true;
+    if (rawCleaned.endsWith('/'))
+        return true;
+    if (normalizeAbsolutePath(cleaned))
+        return true;
+    if (rawCleaned.startsWith('./') && /^[A-Za-z0-9._~@%+=,-]+$/.test(cleaned))
+        return true;
+    return cleaned.includes('/') && isRelativeCandidate(cleaned);
+}
+function commandTokenIndex(tokens) {
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (isShellAssignment(token) || token === 'env' || token === 'command' || token === 'time')
+            continue;
+        return index;
+    }
+    return -1;
+}
+function collectFindRootOperands(segment) {
+    const commandIndex = commandTokenIndex(segment);
+    if (commandIndex < 0)
+        return [];
+    const roots = [];
+    for (let index = commandIndex + 1; index < segment.length; index += 1) {
+        const token = segment[index];
+        if (token === '--')
+            continue;
+        if (isShellRedirectionToken(token))
+            continue;
+        if (isShellRedirectionOperator(token))
+            break;
+        if (isFindLeadingOption(token)) {
+            if (token === '-D' || token === '-O')
+                index += 1;
+            continue;
+        }
+        if (/^-O\d+$/.test(token) || token.startsWith('-D'))
+            continue;
+        if (token.startsWith('-') || token === '(' || token === ')' || token === '!')
+            break;
+        if (isDirectoryRootOperand('find', token))
+            roots.push(token);
+    }
+    return roots;
+}
+function isFindLeadingOption(token) {
+    return token === '-H' || token === '-L' || token === '-P' || token === '-D' || token === '-O';
+}
+function collectFdRootOperands(operands) {
+    if (operands.length < 2)
+        return [];
+    return operands.slice(1).filter((operand) => isDirectoryRootOperand('fd', operand));
+}
+function isShellAssignment(token) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/.test(token);
+}
+function isShellRedirectionOperator(token) {
+    return /^(\d*)?(?:>|>>|<|<>|>&|<&|&>|&>>)$/.test(token);
+}
+function isShellRedirectionToken(token) {
+    return /^(\d*)?(?:>|>>|<|<>|>&|<&|&>|&>>).+/.test(token);
+}
+function deriveDirectoryCandidatesFromToolOutput(outputCandidates, toolCall) {
+    if (!toolCall)
+        return [];
+    const cwd = findCwd(toolCall.input);
+    const roots = [...new Set([
+            ...collectShellDirectoryRootPaths(toolCall.input, cwd),
+            ...collectShellCountOnlyDirectoryRootPaths(toolCall.input, cwd),
+        ])];
+    if (roots.length === 0)
+        return [];
+    const directories = roots.map((root) => ({
+        absolutePath: root,
+        kind: 'directory',
+        source: 'tool_output_directory',
+    }));
+    for (const candidate of outputCandidates) {
+        for (const directory of parentDirectoriesWithinRoots(candidate.absolutePath, roots)) {
+            directories.push({
+                absolutePath: directory,
+                kind: 'directory',
+                source: 'tool_output_directory',
+            });
+        }
+    }
+    return dedupeCandidates(directories);
+}
+function collectShellDirectoryRootPaths(value, fallbackCwd) {
+    if (!value || typeof value !== 'object')
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap((item) => collectShellDirectoryRootPaths(item, fallbackCwd));
+    const record = value;
+    const cwd = typeof record.cwd === 'string'
+        ? normalizeAbsolutePath(record.cwd)?.absolutePath ?? fallbackCwd
+        : fallbackCwd;
+    const roots = [];
+    for (const [key, item] of Object.entries(record)) {
+        if (COMMAND_FIELD_NAMES.has(key) && typeof item === 'string') {
+            roots.push(...extractShellDirectoryRoots(item, cwd));
+            continue;
+        }
+        roots.push(...collectShellDirectoryRootPaths(item, cwd));
+    }
+    return [...new Set(roots)];
+}
+function collectShellCountOnlyDirectoryRootPaths(value, fallbackCwd) {
+    if (!value || typeof value !== 'object')
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap((item) => collectShellCountOnlyDirectoryRootPaths(item, fallbackCwd));
+    const record = value;
+    const cwd = typeof record.cwd === 'string'
+        ? normalizeAbsolutePath(record.cwd)?.absolutePath ?? fallbackCwd
+        : fallbackCwd;
+    const roots = [];
+    for (const [key, item] of Object.entries(record)) {
+        if (COMMAND_FIELD_NAMES.has(key) && typeof item === 'string') {
+            roots.push(...extractShellCountOnlyDirectoryRoots(item, cwd));
+            continue;
+        }
+        roots.push(...collectShellCountOnlyDirectoryRootPaths(item, cwd));
+    }
+    return [...new Set(roots)];
+}
+function parentDirectoriesWithinRoots(absolutePath, roots) {
+    const directories = [];
+    let current = path.posix.dirname(absolutePath);
+    while (current && current !== '/' && current !== '.') {
+        const matchingRoot = roots.find((root) => current === root || current.startsWith(`${root}/`));
+        if (!matchingRoot)
+            break;
+        directories.push(current);
+        if (current === matchingRoot)
+            break;
+        current = path.posix.dirname(current);
+    }
+    return directories;
+}
+function findCwd(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const cwd = value.cwd;
+    return typeof cwd === 'string' ? normalizeAbsolutePath(cwd)?.absolutePath ?? null : null;
+}
+function extractPathCandidatesFromToolOutput(text, toolCall) {
+    const candidates = extractAbsolutePathsFromText(text, 'tool_output');
+    const cwd = toolCall ? findCwd(toolCall.input) : null;
+    if (cwd) {
+        candidates.push(...extractRelativePathsFromText(text, cwd, 'tool_output'));
+    }
+    const outputCandidates = dedupeCandidates(candidates);
+    if (!toolCall || !isDirectoryOnlyEnumerationToolCall(toolCall))
+        return outputCandidates;
+    return outputCandidates.map((candidate) => (candidate.kind === 'unknown'
+        ? { ...candidate, kind: 'directory' }
+        : candidate));
+}
+function extractAbsolutePathsFromText(text, source) {
+    const candidates = [];
+    ABSOLUTE_PATH_RE.lastIndex = 0;
+    for (const match of text.matchAll(ABSOLUTE_PATH_RE)) {
+        const raw = match[2] ?? '';
+        const normalized = normalizeAbsolutePath(raw);
+        if (!normalized)
+            continue;
+        candidates.push({
+            absolutePath: normalized.absolutePath,
+            kind: inferPathKind(raw, text.slice((match.index ?? 0), (match.index ?? 0) + (match[0]?.length ?? 0))),
+            source,
+        });
+    }
+    return candidates;
+}
+function extractRelativePathsFromText(text, cwd, source) {
+    const candidates = [];
+    RELATIVE_PATH_RE.lastIndex = 0;
+    for (const match of text.matchAll(RELATIVE_PATH_RE)) {
+        const raw = match[2] ?? '';
+        const normalized = normalizeRelativePath(cwd, raw);
+        if (!normalized)
+            continue;
+        candidates.push({
+            absolutePath: normalized,
+            kind: inferPathKind(raw, text.slice((match.index ?? 0), (match.index ?? 0) + (match[0]?.length ?? 0))),
+            source,
+        });
+    }
+    return candidates;
+}
+function normalizeAbsolutePath(raw) {
+    const cleaned = cleanPathToken(raw);
+    if (!cleaned || cleaned.includes('://') || hasParentPathSegment(cleaned) || !cleaned.startsWith('/'))
+        return null;
+    const normalized = normalizePathWithoutTrailingSlash(cleaned);
+    if (!normalized || normalized === '/' || hasParentPathSegment(normalized))
+        return null;
+    return { absolutePath: normalized };
+}
+function normalizeRelativePath(cwd, raw) {
+    const cleaned = cleanPathToken(raw).replace(/^\.\//, '');
+    if (!cleaned || cleaned.startsWith('/') || cleaned.startsWith('-') || cleaned.includes('://') || hasParentPathSegment(cleaned))
+        return null;
+    const base = normalizeAbsolutePath(cwd);
+    if (!base)
+        return null;
+    return normalizePathWithoutTrailingSlash(path.posix.join(base.absolutePath, cleaned));
+}
+function normalizePathWithoutTrailingSlash(value) {
+    const normalized = path.posix.normalize(value);
+    return normalized === '/' ? normalized : normalized.replace(/\/+$/g, '');
+}
+function cleanPathToken(raw) {
+    return raw
+        .trim()
+        .replace(/^[\s'"`(<\[]+/g, '')
+        .replace(/[\s'"`),.;!?>\]]+$/g, '')
+        .replace(/:(\d+)(?::\d+)?$/g, '');
+}
+function inferPathKind(pathToken, fullToken) {
+    if (pathToken.endsWith('/'))
+        return 'directory';
+    if (/:\d+(?::\d+)?$/.test(fullToken))
+        return 'file';
+    const basename = path.posix.basename(cleanPathToken(pathToken));
+    if (SINGLE_FILE_NAMES.has(basename) || FILE_EXTENSION_RE.test(basename))
+        return 'file';
+    return 'unknown';
+}
+function hasParentPathSegment(value) {
+    return value.split(/[\\/]+/).some((segment) => segment === '..');
+}
+function isRelativeCandidate(raw) {
+    const cleaned = cleanPathToken(raw);
+    if (!cleaned || cleaned.startsWith('-') || cleaned.startsWith('/') || cleaned.includes('://') || hasParentPathSegment(cleaned))
+        return false;
+    if (cleaned.includes('/'))
+        return true;
+    return SINGLE_FILE_NAMES.has(cleaned) || FILE_EXTENSION_RE.test(cleaned);
+}
+function dedupeCandidates(candidates) {
+    const byPath = new Map();
+    for (const candidate of candidates) {
+        const existing = byPath.get(candidate.absolutePath);
+        if (!existing || existing.kind === 'unknown')
+            byPath.set(candidate.absolutePath, candidate);
+    }
+    return [...byPath.values()];
+}
+function scanMessagePathTokens(content) {
+    const tokens = [];
+    const seen = new Set();
+    const scan = (regex) => {
+        regex.lastIndex = 0;
+        for (const match of content.matchAll(regex)) {
+            const token = cleanPathToken(match[2] ?? '');
+            if (!token || hasParentPathSegment(token) || seen.has(token))
+                continue;
+            seen.add(token);
+            tokens.push(token);
+        }
+    };
+    scan(ABSOLUTE_PATH_RE);
+    scan(RELATIVE_PATH_RE);
+    return tokens;
+}
+function resolveTokenCandidates(token, accesses) {
+    const requiresDirectory = token.endsWith('/');
+    if (token.startsWith('/')) {
+        const normalized = normalizeAbsolutePath(token)?.absolutePath;
+        if (!normalized)
+            return [];
+        return accesses.filter((access) => access.absolutePath === normalized && (!requiresDirectory || access.kind === 'directory'));
+    }
+    const relative = normalizePathWithoutTrailingSlash(token.replace(/^\.\//, ''));
+    if (!isRelativeCandidate(relative) && !(requiresDirectory && isBareRelativeDirectoryCandidate(relative)))
+        return [];
+    return accesses.filter((access) => pathEndsWithToken(access.absolutePath, relative) && (!requiresDirectory || access.kind === 'directory'));
+}
+function isBareRelativeDirectoryCandidate(raw) {
+    const cleaned = cleanPathToken(raw);
+    if (!cleaned || cleaned.startsWith('/') || cleaned.startsWith('-') || cleaned.includes('://') || hasParentPathSegment(cleaned))
+        return false;
+    if (cleaned.includes('/') || cleaned.includes('*') || cleaned.includes('?') || cleaned.includes('[') || cleaned.includes(']'))
+        return false;
+    if (SINGLE_FILE_NAMES.has(cleaned) || FILE_EXTENSION_RE.test(cleaned))
+        return false;
+    return /^[A-Za-z0-9._~@%+=,-]+$/.test(cleaned);
+}
+function pathEndsWithToken(absolutePath, token) {
+    const normalizedPath = path.posix.normalize(absolutePath);
+    const normalizedToken = normalizePathWithoutTrailingSlash(token).replace(/^\/+/, '');
+    if (!normalizedToken.includes('/')) {
+        return path.posix.basename(normalizedPath) === normalizedToken;
+    }
+    return normalizedPath.endsWith(`/${normalizedToken}`);
+}
+function mapAgentFileAccessError(error) {
+    const mapped = mapAgentWorkspaceError(error);
+    if (mapped instanceof AgentWorkspaceServiceError) {
+        return new AgentFileAccessServiceError(mapped.statusCode, mapped.message);
+    }
+    return new AgentFileAccessServiceError(500, String(error?.message ?? error));
+}