@myagentroam/node 0.9.142 → 0.9.143

package/dist/connector.js

@@ -304,7 +304,7 @@ export class NodeConnector {
     terminalManager;
     upgradeCoordinator;
     workspaceState = new WorkspaceDomainState();
-    workspaceWatchService = new WorkspaceWatchService(this.workspaceState, (workspaceId) => this.workspaceSessionService.ensureWatch(workspaceId), (workspaceId) => this.workspaceSessionService.stopWatch(workspaceId), (workspaceId) => this.workspaceWorkbenchService?.releaseWorkspace(workspaceId));
+    workspaceWatchService = new WorkspaceWatchService(this.workspaceState, (workspaceId) => this.workspaceSessionService.ensureWatch(workspaceId), (workspaceId) => this.workspaceSessionService.stopWatch(workspaceId), (workspaceId) => this.workspaceWorkbenchService?.releaseWorkspace(workspaceId), (watch) => this.workspaceWorkbenchService?.cancelFilePrewarm(watch));
     workspaceSessionService = new WorkspaceSessionService(this.workspaceState, {
         discover: (workspaceId, onRunnerDiscovered) => this.discoverWorkspaceSessions(workspaceId, onRunnerDiscovered),
         listPage: (workspaceId) => this.executeNodeOperation('session.list', { workspaceId, limit: 20 }),

package/dist/runner/mar-agent/conversation-normalizer.js

@@ -8,6 +8,8 @@ export class MarAgentConversationNormalizer {
     #subagentDetails = new Map();
     #subagentStarts = new Map();
     #subagentLifecycles = new Map();
+    #codeModeObservationIds = new Set();
+    #codeModeSourceCallIds = new Set();
     messageItemId(nativeItemId) {
         return itemId('message', nativeItemId);
     }
@@ -71,8 +73,8 @@ export class MarAgentConversationNormalizer {
             if (event.type === 'tool.started')
                 return this.#toolStarted(event);
             if (event.type === 'tool.completed')
-                return this.#toolCompleted(event);
-            return this.#toolFailed(event);
+                return [...this.#toolCompleted(event), ...this.#codeModeToolResults(event)];
+            return [...this.#toolFailed(event), ...this.#codeModeToolResults(event)];
         }
         if (event.type === 'hosted_tool.updated') {
             const sourceSummary = event.summary.sources
@@ -318,6 +320,72 @@ export class MarAgentConversationNormalizer {
             genericToolItem(state?.itemId ?? itemId('tool', event.callId), event.toolName, 'FAILED', state?.input, event.message ?? event.code, event.code, false, undefined, state?.subagentTitle, state?.subagentDetails)
         ];
     }
+    #codeModeToolResults(event) {
+        const items = [];
+        for (const observation of codeModeToolResults(event)) {
+            if ((observation.id !== undefined && this.#codeModeObservationIds.has(observation.id)) ||
+                this.#codeModeSourceCallIds.has(observation.source.callId))
+                continue;
+            const { toolName, input } = observation.source;
+            let projected = [];
+            if (toolName === 'apply_patch') {
+                if ((typeof input !== 'string' && record(input) === undefined) ||
+                    !isApplyPatchObservationData(observation.result.data))
+                    continue;
+                projected = this.#normalizeObservedToolResult(event, observation, observation.result.data);
+                if (observation.outcome === 'failed')
+                    projected = projected.map((item) => item.kind === 'file_change' ? { ...item, status: 'FAILED' } : item);
+            }
+            else if (toolName === 'todo_read') {
+                if (observation.outcome !== 'completed' ||
+                    record(input) === undefined ||
+                    !isTodoObservationData(observation.result.data))
+                    continue;
+                const todo = observation.result.data;
+                projected = this.normalize({
+                    ...eventMetadata(event, observation.source.callId),
+                    type: 'todo.updated',
+                    revision: todo.revision,
+                    items: todo.items
+                });
+            }
+            else if (marAgentSubagentOperation(toolName) !== undefined) {
+                if (!isSubagentToolInput(toolName, input) ||
+                    !isSubagentObservationData(observation.result.data, input))
+                    continue;
+                projected = this.#normalizeObservedToolResult(event, observation, observation.result.data);
+            }
+            if (projected.length === 0)
+                continue;
+            if (observation.id !== undefined)
+                this.#codeModeObservationIds.add(observation.id);
+            this.#codeModeSourceCallIds.add(observation.source.callId);
+            items.push(...projected);
+        }
+        return items;
+    }
+    #normalizeObservedToolResult(event, observation, data) {
+        const { callId, toolName, input } = observation.source;
+        const resultId = observation.id ?? 'call-' + callId;
+        this.normalize({
+            ...eventMetadata(event, resultId + ':started'),
+            type: 'tool.started',
+            toolName,
+            callId,
+            input
+        });
+        return this.normalize({
+            ...eventMetadata(event, resultId + ':completed'),
+            type: 'tool.completed',
+            toolName,
+            callId,
+            summary: observation.result.content,
+            ...(observation.result.truncated === undefined
+                ? {}
+                : { truncated: observation.result.truncated }),
+            data
+        });
+    }
     #subagentLifecycle(event) {
         const eventDescription = record(event)?.description;
         const eventTitle = compactRunnerText(typeof eventDescription === 'string' ? eventDescription : '', 500);
@@ -358,6 +426,188 @@ export class MarAgentConversationNormalizer {
         return [subagentStartItem(start, event.agentId, title, details, lifecycle)];
     }
 }
+function codeModeToolResults(event) {
+    if ((event.type !== 'tool.completed' && event.type !== 'tool.failed') ||
+        (event.toolName !== 'code_exec' && event.toolName !== 'code_exec_wait'))
+        return [];
+    const data = record(record(event)?.data);
+    if (data === undefined ||
+        typeof data.cellId !== 'string' ||
+        data.cellId.trim().length === 0 ||
+        (data.status !== 'running' &&
+            data.status !== 'completed' &&
+            data.status !== 'failed' &&
+            data.status !== 'cancelled') ||
+        ('cached' in data && typeof data.cached !== 'boolean'))
+        return [];
+    if (Object.hasOwn(data, 'calls'))
+        return codeModeCallResults(data.calls);
+    if (!Array.isArray(data.observations))
+        return [];
+    return codeModeObservationResults(data.observations);
+}
+function codeModeCallResults(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const call = record(entry);
+        const result = record(call?.result);
+        if (call === undefined ||
+            typeof call.callId !== 'string' ||
+            call.callId.trim().length === 0 ||
+            typeof call.toolName !== 'string' ||
+            !isPersonalizedToolName(call.toolName) ||
+            !('input' in call) ||
+            (call.status !== 'completed' && call.status !== 'failed') ||
+            result === undefined ||
+            typeof result.content !== 'string' ||
+            ('truncated' in result && typeof result.truncated !== 'boolean'))
+            return [];
+        return [
+            {
+                source: { callId: call.callId, toolName: call.toolName, input: call.input },
+                outcome: call.status,
+                result: {
+                    content: result.content,
+                    ...('data' in result ? { data: result.data } : {}),
+                    ...(typeof result.truncated === 'boolean' ? { truncated: result.truncated } : {})
+                }
+            }
+        ];
+    });
+}
+function codeModeObservationResults(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((value) => {
+        const observation = record(value);
+        const source = record(observation?.source);
+        const result = record(observation?.result);
+        if (observation?.type !== 'tool_result' ||
+            typeof observation.id !== 'string' ||
+            observation.id.trim().length === 0 ||
+            source === undefined ||
+            typeof source.callId !== 'string' ||
+            source.callId.trim().length === 0 ||
+            typeof source.toolName !== 'string' ||
+            !isPersonalizedToolName(source.toolName) ||
+            !('input' in source) ||
+            (observation.outcome !== 'completed' && observation.outcome !== 'failed') ||
+            result === undefined ||
+            typeof result.content !== 'string' ||
+            ('truncated' in result && typeof result.truncated !== 'boolean'))
+            return [];
+        return [
+            {
+                id: observation.id,
+                source: { callId: source.callId, toolName: source.toolName, input: source.input },
+                outcome: observation.outcome,
+                result: {
+                    content: result.content,
+                    ...('data' in result ? { data: result.data } : {}),
+                    ...(typeof result.truncated === 'boolean' ? { truncated: result.truncated } : {})
+                }
+            }
+        ];
+    });
+}
+function isPersonalizedToolName(toolName) {
+    // todo_write already emits the native todo.updated event; avoid a duplicate card here.
+    return (toolName === 'apply_patch' ||
+        toolName === 'todo_read' ||
+        marAgentSubagentOperation(toolName) !== undefined);
+}
+function isApplyPatchObservationData(value) {
+    const data = record(value);
+    const totals = record(data?.totals);
+    return (data !== undefined &&
+        Array.isArray(data.files) &&
+        data.files.every((entry) => {
+            const file = record(entry);
+            return (file !== undefined &&
+                typeof file.path === 'string' &&
+                file.path.trim().length > 0 &&
+                (file.targetPath === undefined ||
+                    (typeof file.targetPath === 'string' && file.targetPath.trim().length > 0)) &&
+                (file.operation === 'added' ||
+                    file.operation === 'modified' ||
+                    file.operation === 'deleted' ||
+                    file.operation === 'moved') &&
+                (file.operation !== 'moved' ||
+                    (typeof file.targetPath === 'string' && file.targetPath.trim().length > 0)) &&
+                Number.isSafeInteger(file.addedLines) &&
+                file.addedLines >= 0 &&
+                Number.isSafeInteger(file.deletedLines) &&
+                file.deletedLines >= 0);
+        }) &&
+        totals !== undefined &&
+        Number.isSafeInteger(totals.files) &&
+        totals.files >= 0 &&
+        Number.isSafeInteger(totals.addedLines) &&
+        totals.addedLines >= 0 &&
+        Number.isSafeInteger(totals.deletedLines) &&
+        totals.deletedLines >= 0);
+}
+function isTodoObservationData(value) {
+    const data = record(value);
+    if (data === undefined ||
+        !Number.isSafeInteger(data.revision) ||
+        data.revision < 0 ||
+        !Array.isArray(data.items))
+        return false;
+    return data.items.every((entry) => {
+        const item = record(entry);
+        if (item === undefined ||
+            typeof item.id !== 'string' ||
+            item.id.trim().length === 0 ||
+            typeof item.step !== 'string' ||
+            item.step.trim().length === 0 ||
+            (item.status !== 'pending' && item.status !== 'in_progress' && item.status !== 'completed') ||
+            !Number.isSafeInteger(data.revision))
+            return false;
+        return true;
+    });
+}
+function isSubagentToolInput(toolName, value) {
+    const input = record(value);
+    if (input === undefined)
+        return false;
+    if (toolName === 'agent_start')
+        return typeof input.description === 'string' && input.description.trim().length > 0;
+    if (toolName === 'agent_wait')
+        return (input.agentId === undefined || input.agentId === null || marAgentAgentId(input) !== undefined);
+    if (toolName === 'agent_message')
+        return (marAgentAgentId(input) !== undefined &&
+            typeof input.message === 'string' &&
+            input.message.trim().length > 0);
+    return toolName === 'agent_cancel' && marAgentAgentId(input) !== undefined;
+}
+function isSubagentObservationData(value, input) {
+    const data = record(value);
+    const inputAgentId = marAgentAgentId(input);
+    return (data !== undefined &&
+        typeof data.agentId === 'string' &&
+        data.agentId.trim().length > 0 &&
+        typeof data.description === 'string' &&
+        data.description.trim().length > 0 &&
+        (data.status === 'queued' ||
+            data.status === 'running' ||
+            data.status === 'completed' ||
+            data.status === 'failed' ||
+            data.status === 'cancelled' ||
+            data.status === 'interrupted') &&
+        (inputAgentId === undefined || data.agentId === inputAgentId));
+}
+function eventMetadata(event, eventId) {
+    return {
+        eventId,
+        sequence: event.sequence,
+        timestamp: event.timestamp,
+        sessionId: event.sessionId,
+        executionId: event.executionId,
+        ...(event.turnId === undefined ? {} : { turnId: event.turnId })
+    };
+}
 function itemId(kind, value) {
     return boundedConversationItemId(`mar-agent-${kind}`, value);
 }

package/dist/runner/mar-agent/history-projection.js

@@ -26,6 +26,7 @@ export function projectMarAgentHistory(session, entries, options = {}) {
         return created;
     };
     const replace = (turn, item) => {
+        turn = turns.get(turn.id) ?? turn;
         const index = turn.items.findIndex((candidate) => candidate.id === item.id);
         const items = [...turn.items];
         if (index < 0)

package/dist/service/workspace-code-navigation-service.js

@@ -147,6 +147,15 @@ export class WorkspaceCodeNavigationService {
                 truncated: targets.length > MAX_RESULTS || manifest.truncated
             };
         }
+        if (!current && cachedCandidates === undefined) {
+            const failure = this.failures.get(location.directory);
+            if (failure !== undefined) {
+                this.failures.delete(location.directory);
+                return emptyDefinitionResult({ state: 'FAILED', failureCode: failure });
+            }
+            this.startInitialBuild(workspace, location);
+            return emptyDefinitionResult({ state: 'BUILDING' });
+        }
         const requireFresh = !current;
         const prepared = await this.indexInput(workspace, requireFresh);
         if (!current) {

package/dist/service/workspace-file-service.js

@@ -2,13 +2,20 @@ import { isAbsolute, relative, resolve, win32 } from 'node:path';
 import { realpath } from 'node:fs/promises';
 import { listWorkspaceFiles, mutateWorkspaceFile, normalizeFilePreviewPath, readAbsoluteFileContentRange, readWorkspaceFileContentRange, readAbsoluteTextFile, readWorkspaceTextFile, writeWorkspaceTextFile, WorkspaceFileIndex } from '../workspace.js';
 const INDEX_CACHE_LIMIT = 32;
+const INDEX_CACHE_BYTE_LIMIT = 128 * 1024 * 1024;
+const INDEX_QUEUE_LIMIT = 16;
+const INDEX_QUEUE_TIMEOUT_MS = 120_000;
 export class WorkspaceFileService {
     state;
     onInvalidated;
+    indexLimits;
     mutationTails = new Map();
-    constructor(state, onInvalidated) {
+    indexQueue = [];
+    indexRunning = false;
+    constructor(state, onInvalidated, indexLimits = {}) {
         this.state = state;
         this.onInvalidated = onInvalidated;
+        this.indexLimits = indexLimits;
     }
     async list(workspace, input) {
         if ((input.path !== undefined && typeof input.path !== 'string') ||
@@ -151,12 +158,13 @@ export class WorkspaceFileService {
         if (typeof input.query !== 'string' ||
             (input.cursor !== undefined && typeof input.cursor !== 'string') ||
             (input.includeDirectories !== undefined && typeof input.includeDirectories !== 'boolean') ||
+            (input.waitForIndex !== undefined && typeof input.waitForIndex !== 'boolean') ||
             (input.limit !== undefined &&
                 (!Number.isInteger(input.limit) ||
                     input.limit < 1 ||
                     input.limit > 200)))
             throw new Error('FILE_SEARCH_LIMIT_EXCEEDED');
-        return this.index(workspace).search(input.query, typeof input.cursor === 'string' ? input.cursor : undefined, typeof input.limit === 'number' ? input.limit : undefined, input.includeDirectories === true);
+        return this.index(workspace).search(input.query, typeof input.cursor === 'string' ? input.cursor : undefined, typeof input.limit === 'number' ? input.limit : undefined, input.includeDirectories === true, input.waitForIndex !== false);
     }
     async mutate(workspace, input) {
         const action = input.action;
@@ -192,28 +200,104 @@ export class WorkspaceFileService {
     index(workspace) {
         let index = this.state.fileIndexes.get(workspace.id);
         if (index === undefined) {
-            if (this.state.fileIndexes.size >= INDEX_CACHE_LIMIT) {
-                const oldest = this.state.fileIndexes.entries().next().value;
-                if (oldest !== undefined) {
-                    oldest[1].dispose();
-                    this.state.fileIndexes.delete(oldest[0]);
-                }
-            }
-            index = new WorkspaceFileIndex(workspace.path);
+            index = new WorkspaceFileIndex(workspace.path, {
+                ...(this.indexLimits.indexByteLimit === undefined
+                    ? {}
+                    : { byteLimit: this.indexLimits.indexByteLimit }),
+                schedule: (run, background, needed) => this.scheduleIndex(run, background, needed),
+                onRebuilt: () => this.pruneIndexes(workspace.id)
+            });
         }
         this.state.fileIndexes.delete(workspace.id);
         this.state.fileIndexes.set(workspace.id, index);
+        this.pruneIndexes(workspace.id);
         return index;
     }
+    prepare(workspace, needed) {
+        if (!needed())
+            return Promise.resolve();
+        return this.index(workspace).prepare(needed);
+    }
+    /** Removes queued preparation whose Watch consumers have all gone away. */
+    prunePreparations() {
+        for (let index = this.indexQueue.length - 1; index >= 0; index -= 1) {
+            const job = this.indexQueue[index];
+            if (job.needed())
+                continue;
+            this.indexQueue.splice(index, 1);
+            clearTimeout(job.timer);
+            job.resolve();
+        }
+    }
+    pruneIndexes(protectedId) {
+        let bytes = [...this.state.fileIndexes.values()].reduce((total, index) => total + index.accountedBytes, 0);
+        const byteLimit = this.indexLimits.cacheByteLimit ?? INDEX_CACHE_BYTE_LIMIT;
+        for (const [id, index] of this.state.fileIndexes) {
+            if (this.state.fileIndexes.size <= INDEX_CACHE_LIMIT && bytes <= byteLimit)
+                break;
+            if (id === protectedId)
+                continue;
+            bytes -= index.accountedBytes;
+            index.dispose();
+            this.state.fileIndexes.delete(id);
+        }
+        this.prunePreparations();
+    }
+    scheduleIndex(run, background, needed) {
+        this.prunePreparations();
+        if (!needed())
+            return Promise.resolve();
+        if (this.indexQueue.length >= (this.indexLimits.queueLimit ?? INDEX_QUEUE_LIMIT))
+            return Promise.reject(new Error('FILE_SEARCH_LIMIT_EXCEEDED'));
+        return new Promise((resolve, reject) => {
+            const job = {
+                run,
+                background,
+                needed,
+                resolve: () => resolve(),
+                reject,
+                timer: setTimeout(() => {
+                    const index = this.indexQueue.indexOf(job);
+                    if (index < 0)
+                        return;
+                    this.indexQueue.splice(index, 1);
+                    reject(new Error('FILE_SEARCH_LIMIT_EXCEEDED'));
+                }, this.indexLimits.queueTimeoutMs ?? INDEX_QUEUE_TIMEOUT_MS)
+            };
+            job.timer.unref();
+            this.indexQueue.push(job);
+            this.runNextIndex();
+        });
+    }
+    runNextIndex() {
+        if (this.indexRunning)
+            return;
+        this.prunePreparations();
+        const foreground = this.indexQueue.findIndex((job) => !job.background());
+        const job = this.indexQueue.splice(foreground < 0 ? 0 : foreground, 1)[0];
+        if (job === undefined)
+            return;
+        clearTimeout(job.timer);
+        this.indexRunning = true;
+        void Promise.resolve()
+            .then(job.run)
+            .then(job.resolve, job.reject)
+            .finally(() => {
+            this.indexRunning = false;
+            this.runNextIndex();
+        });
+    }
     dispose(workspaceId) {
         if (workspaceId !== undefined) {
             this.state.fileIndexes.get(workspaceId)?.dispose();
             this.state.fileIndexes.delete(workspaceId);
+            this.prunePreparations();
             return;
         }
         for (const index of this.state.fileIndexes.values())
             index.dispose();
         this.state.fileIndexes.clear();
+        this.prunePreparations();
     }
 }
 function isFilePreviewAbsolutePath(path) {

package/dist/service/workspace-watch-controller.js

@@ -24,12 +24,15 @@ export class WorkspaceWatchController {
         const existing = this.options.watch.existing(workspace.id, key);
         if (existing !== undefined &&
             existing.watchId === input.watchId &&
-            JSON.stringify(existing.topics) === JSON.stringify(topics)) {
+            JSON.stringify(existing.topics) === JSON.stringify(topics) &&
+            (existing.prepareFiles === true) === (input.prepareFiles === true)) {
             this.options.watch.renew(workspace.id, key, input.watchId);
             return this.accepted(existing);
         }
-        const watch = this.options.watch.create(workspace.id, input.watchId, this.options.watch.sessionHash(input), input.workbenchConnectionId, this.options.nodeGeneration(), topics);
+        const watch = this.options.watch.create(workspace.id, input.watchId, this.options.watch.sessionHash(input), input.workbenchConnectionId, this.options.nodeGeneration(), topics, input.prepareFiles === true);
         void this.options.snapshots.initial(workspace, watch);
+        if (watch.prepareFiles)
+            this.options.snapshots.prewarmFiles(workspace, watch);
         return this.accepted(watch);
     }
     unwatch(input) {
@@ -49,7 +52,9 @@ export class WorkspaceWatchController {
             typeof input.watchId !== 'string' ||
             typeof input.workbenchConnectionId !== 'string' ||
             !/^[A-Za-z0-9_-]{8,128}$/.test(input.watchId) ||
-            (input.mode !== 'initial' && input.mode !== 'renew'))
+            (input.mode !== 'initial' && input.mode !== 'renew') ||
+            (input.prepareFiles !== undefined &&
+                (input.mode !== 'initial' || input.prepareFiles !== true)))
             throw new Error('WORKSPACE_WATCH_INVALID');
     }
     accepted(watch) {

package/dist/service/workspace-watch-service.js

@@ -5,11 +5,13 @@ export class WorkspaceWatchService {
     onSessionWatchRequired;
     onSessionWatchUnused;
     onWorkspaceWatchUnused;
-    constructor(state, onSessionWatchRequired, onSessionWatchUnused, onWorkspaceWatchUnused) {
+    onWatchRemoved;
+    constructor(state, onSessionWatchRequired, onSessionWatchUnused, onWorkspaceWatchUnused, onWatchRemoved = () => undefined) {
         this.state = state;
         this.onSessionWatchRequired = onSessionWatchRequired;
         this.onSessionWatchUnused = onSessionWatchUnused;
         this.onWorkspaceWatchUnused = onWorkspaceWatchUnused;
+        this.onWatchRemoved = onWatchRemoved;
     }
     parseTopics(input) {
         if (!plain(input.topics))
@@ -51,7 +53,7 @@ export class WorkspaceWatchService {
             throw new Error('WORKSPACE_WATCH_INVALID');
         return input.workbenchConnectionId;
     }
-    create(workspaceId, watchId, sessionHash, workbenchConnectionId, nodeGeneration, topics) {
+    create(workspaceId, watchId, sessionHash, workbenchConnectionId, nodeGeneration, topics, prepareFiles = false) {
         const key = `${sessionHash}:${workbenchConnectionId}`;
         for (const [activeWorkspaceId, watches] of this.state.watches)
             if (watches.has(key))
@@ -64,6 +66,7 @@ export class WorkspaceWatchService {
             nodeGeneration,
             expiresAt: Date.now() + WATCH_TTL_MS,
             topics,
+            prepareFiles,
             timer: undefined
         };
         watch.timer = this.expiryTimer(workspaceId, key);
@@ -102,8 +105,10 @@ export class WorkspaceWatchService {
             return;
         clearTimeout(watch.timer);
         watches?.delete(key);
-        if (watches?.size === 0) {
+        if (watches?.size === 0)
             this.state.watches.delete(workspaceId);
+        this.onWatchRemoved(watch);
+        if (watches?.size === 0) {
             this.clearRevisions(workspaceId);
             this.onWorkspaceWatchUnused(workspaceId);
         }
@@ -112,20 +117,25 @@ export class WorkspaceWatchService {
     }
     clear(workspaceId) {
         const watches = this.state.watches.get(workspaceId);
+        this.state.watches.delete(workspaceId);
         if (watches !== undefined)
-            for (const watch of watches.values())
+            for (const watch of watches.values()) {
                 clearTimeout(watch.timer);
-        this.state.watches.delete(workspaceId);
+                this.onWatchRemoved(watch);
+            }
         this.clearRevisions(workspaceId);
         this.onSessionWatchUnused(workspaceId);
         this.onWorkspaceWatchUnused(workspaceId);
     }
     clearAll() {
         const workspaceIds = [...this.state.watches.keys()];
-        for (const watches of this.state.watches.values())
-            for (const watch of watches.values())
-                clearTimeout(watch.timer);
+        const watchesByWorkspace = [...this.state.watches.values()];
         this.state.watches.clear();
+        for (const watches of watchesByWorkspace)
+            for (const watch of watches.values()) {
+                clearTimeout(watch.timer);
+                this.onWatchRemoved(watch);
+            }
         this.state.watchRevisions.clear();
         for (const workspaceId of workspaceIds) {
             this.onSessionWatchUnused(workspaceId);

package/dist/service/workspace-watch-snapshot-service.js

@@ -2,6 +2,7 @@ const FILES_REFRESH_INTERVAL_MS = 30_000;
 /** Owns Workspace topic reads, single-flight invalidation and directed snapshot delivery. */
 export class WorkspaceWatchSnapshotService {
     options;
+    filePrewarmTimers = new Map();
     refreshes = new Map();
     dirty = new Set();
     reads = new Map();
@@ -26,6 +27,23 @@ export class WorkspaceWatchSnapshotService {
             }
         }));
     }
+    prewarmFiles(workspace, watch) {
+        this.cancelFilePrewarm(watch);
+        const timer = setTimeout(() => {
+            this.filePrewarmTimers.delete(watch);
+            const needed = () => this.matches(workspace.id, watch) && watch.prepareFiles === true;
+            if (needed())
+                void this.options.files.prepare(workspace, needed).catch(() => undefined);
+        }, 750);
+        timer.unref();
+        this.filePrewarmTimers.set(watch, timer);
+    }
+    cancelFilePrewarm(watch) {
+        const timer = this.filePrewarmTimers.get(watch);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.filePrewarmTimers.delete(watch);
+    }
     async invalidate(workspaceId, topic) {
         const key = `${workspaceId}:${topic}`;
         const active = this.refreshes.get(key);
@@ -54,6 +72,11 @@ export class WorkspaceWatchSnapshotService {
         return this.refreshes.get(`${workspaceId}:${topic}`) ?? this.invalidate(workspaceId, topic);
     }
     clear(workspaceId) {
+        for (const [watch, timer] of this.filePrewarmTimers)
+            if (watch.workspaceId === workspaceId) {
+                clearTimeout(timer);
+                this.filePrewarmTimers.delete(watch);
+            }
         for (const key of [...this.dirty])
             if (key.startsWith(`${workspaceId}:`))
                 this.dirty.delete(key);
@@ -62,6 +85,9 @@ export class WorkspaceWatchSnapshotService {
                 this.signatures.delete(key);
     }
     clearAll() {
+        for (const timer of this.filePrewarmTimers.values())
+            clearTimeout(timer);
+        this.filePrewarmTimers.clear();
         if (this.filesRefreshTimer !== undefined)
             clearInterval(this.filesRefreshTimer);
         this.filesRefreshTimer = undefined;

package/dist/service/workspace-workbench-service.js

@@ -26,6 +26,10 @@ export class WorkspaceWorkbenchService {
             nodeGeneration: options.nodeGeneration
         });
     }
+    cancelFilePrewarm(watch) {
+        this.snapshots.cancelFilePrewarm(watch);
+        this.options.files.prunePreparations();
+    }
     operations() {
         return {
             ...this.watchController.operations(),

package/dist/workspace.js

@@ -3,7 +3,7 @@ import { lstat, mkdir, opendir, open, readdir, readFile, realpath, rename, rm, s
 import { homedir, platform as hostPlatform } from 'node:os';
 import { basename, dirname, isAbsolute, posix, relative, resolve, sep, win32 } from 'node:path';
 import { spawn } from 'node:child_process';
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 import { logNodeCommandFailure } from './operational.js';
 import { terminateProcessTree } from './process-tree.js';
 import { gitOperationEnvironment } from './service/git-operation-service.js';
@@ -21,6 +21,7 @@ const FILE_INDEX_IDLE_TTL_MS = 60 * 60 * 1_000;
 const FILE_INDEX_FRESHNESS_TTL_MS = 30_000;
 const FILE_INDEX_ENTRY_LIMIT = 100_000;
 const FILE_INDEX_METADATA_CONCURRENCY = 32;
+const FILE_INDEX_BYTE_LIMIT = 64 * 1024 * 1024;
 const DEFAULT_QUICK_OPEN_EXCLUDES = [
     '**/.git/**',
     '**/node_modules/**',
@@ -84,6 +85,11 @@ export class WorkspaceFileIndex {
     workspaceRoot;
     limits;
     entries = [];
+    fileEntries = [];
+    retainedBytes = 0;
+    failure;
+    foregroundRequested = false;
+    preparationConsumers = new Set();
     truncated = false;
     root;
     loading;
@@ -96,6 +102,28 @@ export class WorkspaceFileIndex {
         this.workspaceRoot = workspaceRoot;
         this.limits = limits;
     }
+    get accountedBytes() {
+        return this.retainedBytes;
+    }
+    /** Prepares only metadata; a queued background scan may lose its consumer. */
+    prepare(needed = () => true) {
+        if (!this.stale && this.root !== undefined) {
+            this.touch();
+            return Promise.resolve();
+        }
+        if (!needed())
+            return Promise.resolve();
+        this.preparationConsumers.add(needed);
+        this.startLoading(true, () => {
+            for (const consumer of this.preparationConsumers) {
+                if (consumer())
+                    return true;
+                this.preparationConsumers.delete(consumer);
+            }
+            return false;
+        });
+        return this.loading;
+    }
     async contentCandidates(options = {}) {
         await this.ensureLoaded(options.requireFresh === true);
         return this.currentContentCandidates();
@@ -118,16 +146,12 @@ export class WorkspaceFileIndex {
         if (this.loading !== undefined)
             return this.loading;
         if (this.stale || this.root === undefined) {
-            this.loading = this.rebuild().finally(() => {
-                this.loading = undefined;
-            });
+            this.startLoading();
             return this.loading;
         }
         if (requireFresh) {
             this.refreshAttemptedAt = Date.now();
-            this.loading = this.rebuild().finally(() => {
-                this.loading = undefined;
-            });
+            this.startLoading();
             return this.loading;
         }
         if (Date.now() - this.refreshAttemptedAt >=
@@ -138,7 +162,7 @@ export class WorkspaceFileIndex {
     currentContentCandidates() {
         this.touch();
         return {
-            entries: this.entries.filter((entry) => entry.kind === 'FILE'),
+            entries: this.fileEntries,
             truncated: this.truncated
         };
     }
@@ -148,25 +172,45 @@ export class WorkspaceFileIndex {
             clearTimeout(this.expiryTimer);
         this.expiryTimer = undefined;
         this.entries = [];
+        this.fileEntries = [];
+        this.root = undefined;
+        this.retainedBytes = 0;
+        this.failure = undefined;
+        this.foregroundRequested = false;
+        this.preparationConsumers.clear();
         this.truncated = false;
         this.stale = true;
         this.refreshedAt = 0;
         this.refreshAttemptedAt = 0;
     }
-    async search(query, cursor, limit = SEARCH_RESULT_LIMIT, includeDirectories = false) {
+    async search(query, cursor, limit = SEARCH_RESULT_LIMIT, includeDirectories = false, waitForIndex = true) {
+        const generation = this.lifecycleGeneration;
         if (query.trim().length === 0 ||
             query.length > 256 ||
             !Number.isSafeInteger(limit) ||
             limit < 1 ||
             limit > SEARCH_RESULT_LIMIT)
             throw new Error('FILE_SEARCH_LIMIT_EXCEEDED');
+        const after = decodeSearchCursor(cursor, query);
+        if (!waitForIndex && (this.stale || this.root === undefined)) {
+            if (this.failure !== undefined) {
+                const failure = this.failure;
+                this.failure = undefined;
+                throw failure;
+            }
+            this.foregroundRequested = true;
+            this.startLoading();
+            return { entries: [], nextCursor: null, truncated: false, indexState: 'BUILDING' };
+        }
         await this.ensureLoaded();
+        if (generation !== this.lifecycleGeneration || this.root === undefined)
+            throw new Error('FILE_INDEX_INVALIDATED');
         this.touch();
-        const after = decodeSearchCursor(cursor, query);
+        const terms = query.trim().toLocaleLowerCase().split(/\s+/u);
         const afterEntry = after === undefined
             ? undefined
             : this.entries.find((entry) => entry.path === after && (includeDirectories || entry.kind === 'FILE'));
-        const afterScore = afterEntry === undefined ? -1 : fuzzyPathScore(afterEntry.path, query);
+        const afterScore = afterEntry === undefined ? -1 : fuzzyPathScore(afterEntry.path, terms);
         const afterCandidate = afterEntry === undefined || afterScore < 0
             ? undefined
             : { entry: afterEntry, score: afterScore };
@@ -174,7 +218,7 @@ export class WorkspaceFileIndex {
         for (const entry of this.entries) {
             if (!includeDirectories && entry.kind !== 'FILE')
                 continue;
-            const score = fuzzyPathScore(entry.path, query);
+            const score = fuzzyPathScore(entry.path, terms);
             if (score < 0)
                 continue;
             const candidate = { entry, score };
@@ -183,38 +227,75 @@ export class WorkspaceFileIndex {
             ranked.add(candidate);
         }
         const candidates = ranked.sorted();
-        const page = candidates.slice(0, limit).map((candidate) => candidate.entry);
+        const page = candidates.slice(0, limit).map((candidate) => ({
+            ...candidate.entry,
+            score: candidate.score
+        }));
         const next = candidates[limit]?.entry.path;
         return {
             entries: page,
             nextCursor: next === undefined ? null : encodeSearchCursor(query, page.at(-1)?.path ?? after ?? ''),
-            truncated: next !== undefined || this.truncated
+            truncated: next !== undefined || this.truncated,
+            ...(!waitForIndex ? { indexState: 'READY' } : {})
         };
     }
     async ensureLoaded(requireFresh = false) {
+        const generation = this.lifecycleGeneration;
         if (!this.stale && this.root !== undefined) {
             if (Date.now() - this.refreshAttemptedAt >=
                 (this.limits.freshnessTtlMs ?? FILE_INDEX_FRESHNESS_TTL_MS)) {
                 if (requireFresh) {
+                    this.foregroundRequested = true;
                     if (this.loading === undefined) {
                         this.refreshAttemptedAt = Date.now();
-                        this.loading = this.rebuild().finally(() => {
-                            this.loading = undefined;
-                        });
+                        this.startLoading();
                     }
                     await this.loading;
+                    if (generation !== this.lifecycleGeneration)
+                        throw new Error('FILE_INDEX_INVALIDATED');
                 }
                 else
                     this.refreshInBackground();
             }
             return;
         }
-        if (this.loading === undefined) {
-            this.loading = this.rebuild().finally(() => {
-                this.loading = undefined;
-            });
-        }
+        this.startLoading();
         await this.loading;
+        if (generation !== this.lifecycleGeneration)
+            throw new Error('FILE_INDEX_INVALIDATED');
+    }
+    startLoading(background = false, needed = () => true) {
+        if (!background)
+            this.foregroundRequested = true;
+        if (this.loading !== undefined)
+            return;
+        const generation = this.lifecycleGeneration;
+        const current = () => generation === this.lifecycleGeneration;
+        const required = () => current() && (this.foregroundRequested || needed());
+        const run = async () => {
+            if (!current())
+                throw new Error('FILE_INDEX_INVALIDATED');
+            if (required())
+                await this.rebuild();
+            if (!current())
+                throw new Error('FILE_INDEX_INVALIDATED');
+        };
+        const pending = (this.limits.schedule?.(run, () => !this.foregroundRequested, required) ?? run())
+            .catch((error) => {
+            if (current())
+                this.failure = error;
+            throw error;
+        })
+            .finally(() => {
+            if (this.loading === pending) {
+                this.loading = undefined;
+                this.foregroundRequested = false;
+                this.preparationConsumers.clear();
+            }
+        });
+        this.loading = pending;
+        // A fast acknowledgement has no awaiting consumer; retain failure for its next query.
+        void this.loading.catch(() => undefined);
     }
     touch() {
         if (this.expiryTimer !== undefined)
@@ -227,11 +308,23 @@ export class WorkspaceFileIndex {
         const root = await resolveRegisteredWorkspaceRoot(this.workspaceRoot);
         if (generation !== this.lifecycleGeneration)
             return;
-        const excludes = [...DEFAULT_QUICK_OPEN_EXCLUDES, ...(await workspaceExcludePatterns(root))];
+        const excludeOptions = { dot: true, nocase: hostPlatform() !== 'linux' };
+        const excludes = [
+            // Fixed directory globs can use their compiled regex without splitting every path.
+            ...DEFAULT_QUICK_OPEN_EXCLUDES.map((pattern) => {
+                const matcher = new Minimatch(pattern, excludeOptions);
+                const regex = matcher.makeRe();
+                // Globstar also matches line terminators in valid filesystem names.
+                return regex ? new RegExp(regex.source, `${regex.flags}s`) : matcher;
+            }),
+            ...(await workspaceExcludePatterns(root)).map((pattern) => new Minimatch(pattern, excludeOptions))
+        ];
         if (generation !== this.lifecycleGeneration)
             return;
         const indexed = [];
         const entryLimit = this.limits.entryLimit ?? FILE_INDEX_ENTRY_LIMIT;
+        const byteLimit = this.limits.byteLimit ?? FILE_INDEX_BYTE_LIMIT;
+        let bytes = 0;
         let truncated = false;
         const directories = ['.'];
         let directoryCursor = 0;
@@ -255,10 +348,14 @@ export class WorkspaceFileIndex {
                 for (const entry of resolvedEntries) {
                     if (entry === undefined)
                         continue;
-                    if (entry.path === '.git' ||
-                        entry.path.startsWith('.git/') ||
-                        isExcluded(entry.path, excludes))
+                    if (entry.path === '.git' || entry.path.startsWith('.git/'))
                         continue;
+                    const entryBytes = 160 + 2 * (entry.path.length + entry.name.length);
+                    if (bytes + entryBytes > byteLimit) {
+                        truncated = true;
+                        break;
+                    }
+                    bytes += entryBytes;
                     if (entry.kind === 'DIRECTORY')
                         directories.push(entry.path);
                     indexed.push(entry);
@@ -278,7 +375,7 @@ export class WorkspaceFileIndex {
                     candidatePath.startsWith('.git/') ||
                     isExcluded(candidatePath, excludes))
                     continue;
-                pending.push(inspectWorkspaceIndexEntry(root, candidatePath, child.name));
+                pending.push(inspectWorkspaceIndexEntry(root, candidatePath, child.name, excludes));
                 if (pending.length >= FILE_INDEX_METADATA_CONCURRENCY)
                     await appendPending();
                 if (truncated)
@@ -291,20 +388,21 @@ export class WorkspaceFileIndex {
             return;
         this.root = root;
         this.entries = indexed;
+        this.fileEntries = indexed.filter((entry) => entry.kind === 'FILE');
+        this.retainedBytes = bytes;
+        this.failure = undefined;
         this.truncated = truncated;
         this.stale = false;
         this.refreshedAt = Date.now();
         this.refreshAttemptedAt = this.refreshedAt;
+        this.touch();
+        this.limits.onRebuilt?.();
     }
     refreshInBackground() {
         if (this.loading !== undefined)
             return;
         this.refreshAttemptedAt = Date.now();
-        this.loading = this.rebuild()
-            .catch(() => undefined)
-            .finally(() => {
-            this.loading = undefined;
-        });
+        this.startLoading(true);
     }
 }
 async function workspaceExcludePatterns(root) {
@@ -322,8 +420,9 @@ async function workspaceExcludePatterns(root) {
     });
 }
 function isExcluded(path, patterns) {
-    return patterns.some((pattern) => minimatch(path, pattern, { dot: true, nocase: hostPlatform() !== 'linux' }) ||
-        minimatch(`${path}/`, pattern, { dot: true, nocase: hostPlatform() !== 'linux' }));
+    return patterns.some((pattern) => pattern instanceof RegExp
+        ? pattern.test(path) || pattern.test(`${path}/`)
+        : pattern.match(path) || pattern.match(`${path}/`));
 }
 function compareRankedCandidate(left, right) {
     return right.score - left.score || left.entry.path.localeCompare(right.entry.path);
@@ -383,9 +482,8 @@ class RankedCandidateHeap {
         }
     }
 }
-function fuzzyPathScore(path, query) {
+function fuzzyPathScore(path, terms) {
     const source = path.toLocaleLowerCase();
-    const terms = query.trim().toLocaleLowerCase().split(/\s+/u);
     const name = source.slice(source.lastIndexOf('/') + 1);
     let total = 0;
     for (const needle of terms) {
@@ -397,6 +495,14 @@ function fuzzyPathScore(path, query) {
     return total - path.length / 1_000;
 }
 function fuzzyTermScore(source, name, needle) {
+    if (name === needle || source === needle)
+        return 1_000;
+    if (name.startsWith(needle) || source.startsWith(needle))
+        return 700;
+    if (source.endsWith(`/${needle}`) || source.includes(`/${needle}/`))
+        return 600;
+    if (name.includes(needle) || source.includes(needle))
+        return 500;
     let cursor = 0;
     let score = 0;
     let previous = -2;
@@ -410,11 +516,7 @@ function fuzzyTermScore(source, name, needle) {
         previous = index;
         cursor = index + 1;
     }
-    if (name.includes(needle))
-        score += 40;
-    else if (source.includes(needle))
-        score += 16;
-    return score;
+    return 100 + score / 1_000;
 }
 /**
  * Lists directory names only for the Workspace picker. Browsing begins at the
@@ -939,12 +1041,15 @@ async function resolveWorkspaceEntryMetadata(root, requestedPath) {
     const metadata = await lstat(candidate);
     return { path: candidate, metadata };
 }
-async function inspectWorkspaceIndexEntry(root, requestedPath, name) {
+async function inspectWorkspaceIndexEntry(root, requestedPath, name, excludes) {
     try {
         const entry = await resolveWorkspaceEntryMetadata(root, requestedPath);
         if (!entry.metadata.isFile() && !entry.metadata.isDirectory())
             return undefined;
         const safePath = relative(root, entry.path).split(sep).join('/');
+        // The requested path was already checked; aliases need the canonical-path check too.
+        if (safePath !== requestedPath && isExcluded(safePath, excludes))
+            return undefined;
         return entry.metadata.isDirectory()
             ? {
                 path: safePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.9.142",
+  "version": "0.9.143",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -35,9 +35,9 @@
     "ws": "^8.21.3",
     "zod": "4.4.3",
     "@myagentroam/marctl": "0.9.120",
-    "@myagentroam/agent": "0.9.142",
-    "@myagentroam/protocol": "0.9.142",
-    "@myagentroam/code-navigation": "0.9.129"
+    "@myagentroam/code-navigation": "0.9.129",
+    "@myagentroam/agent": "0.9.143",
+    "@myagentroam/protocol": "0.9.143"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"