@cursor/july 0.1.103 → 0.1.105

package/dist/internal/session-engine.js

@@ -25,6 +25,7 @@ import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-s
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH, USER_STORE_MOUNT_PATH, } from "../files.js";
 import { cursorHostedFiles, isCursorHostedFilesAvailable, isCursorUserStoreFilesAvailable, } from "../files-backends/cursor-hosted.js";
+import { isFileSystemToolAlias, isMutatingFileSystemTool, localFileSystem, resolveFileSystemTools, resolveHostHarnessToolOptions, tempFs, unionFs, writeWorkspaceFilesToRoot, } from "../filesystem.js";
 import { storageKeysForArchitecture } from "../storage.js";
 import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
 import { ABCollector } from "./ab-collector.js";
@@ -43,6 +44,8 @@ import { describeError } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import { applyWebScratchUpdate, ingestHostAgentToolsScratch, remapScratchPaths, } from "./filesystem/scratch.js";
+import { fileSystemTool, hostFileToolsFromAuthored, rootFileToolsFromAuthored, synthesizeFileSystemTools, } from "./filesystem/tools.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
@@ -69,8 +72,8 @@ import { TurnGovernor } from "./turn-governor.js";
 import { TurnLeaseStore } from "./turn-lease-store.js";
 import { TurnOutbox } from "./turn-outbox.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
-import { buildAgentsMdContent, buildCloudMemorySection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, writeWorkspaceFiles, } from "./workspace.js";
-import { syncWorkspaceToStore } from "./workspace-sync.js";
+import { buildAgentsMdContent, buildCloudMemorySection, buildCloudSessionWorkspaceSection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, } from "./workspace.js";
+import { syncSessionWorkspaceFiles, syncWorkspaceToStore, WorkspaceFileRefusal, wipeSessionWorkspace, } from "./workspace-sync.js";
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
@@ -218,6 +221,12 @@ export class SessionEngine {
         this.cloudCostBackfillDone = new Set();
         /** Deduped in-flight cloud cost backfills, keyed by session id. */
         this.cloudCostBackfill = new Map();
+        /** Per-session FileSystem handle cache (not a tree snapshot). */
+        this.sessionRoots = new Map();
+        /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+        this.sessionRootInflight = new Map();
+        /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+        this.turnRoots = new Map();
         this.project = options.project;
         applyAgentContinuationDefaults(this.project);
         this.stateRoot = options.stateRoot;
@@ -1252,6 +1261,224 @@ export class SessionEngine {
             return this.interrupt(existing.sessionId);
         });
     }
+    hasRootOverride() {
+        return this.project.agent.root !== undefined;
+    }
+    /**
+     * FileSystem for this turn or `callTool`. Authored `root` (static or
+     * factory) is cached per session when `cache` is set; unscoped
+     * `callTool` passes the invocation id and does not cache, so factories
+     * cannot share one tree across callers. A static handle is used as
+     * authored — every session sees that same object. Host-default agents
+     * get `localFileSystem` against the harness cwd — same path verbs as
+     * the Cursor SDK natives, always through the synthesized tools.
+     */
+    resolveFileSystem(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.project.agent.root;
+            if (authored === undefined) {
+                return localFileSystem({ cwd: options.cwd });
+            }
+            const authoredRoot = yield this.resolveAuthoredFileSystem(options);
+            if (options.cache) {
+                const existing = this.turnRoots.get(options.sessionId);
+                if (existing !== undefined) {
+                    return existing.root;
+                }
+            }
+            const root = unionFs({
+                "/": authoredRoot,
+                "/tmp": tempFs(),
+            });
+            if (options.cache && this.isTurnRunning(options.sessionId)) {
+                this.turnRoots.set(options.sessionId, { root, cwd: options.cwd });
+            }
+            return root;
+        });
+    }
+    resolveAuthoredFileSystem(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.project.agent.root;
+            if (authored === undefined) {
+                throw new Error("resolveAuthoredFileSystem requires an authored root");
+            }
+            if (options.cache) {
+                const cached = this.sessionRoots.get(options.sessionId);
+                if (cached !== undefined) {
+                    return cached;
+                }
+                const inflight = this.sessionRootInflight.get(options.sessionId);
+                if (inflight !== undefined) {
+                    return inflight;
+                }
+            }
+            const resolve = () => __awaiter(this, void 0, void 0, function* () {
+                if (typeof authored !== "function") {
+                    return authored;
+                }
+                const host = this.hostForSession(options.cache ? options.sessionId : undefined);
+                const ctx = Object.assign(Object.assign({ sessionId: options.sessionId, agentName: this.project.agent.name }, (options.continuationKey === undefined
+                    ? {}
+                    : { continuationKey: options.continuationKey })), { host: { files: host.files, reminders: host.reminders } });
+                return yield authored(ctx);
+            });
+            if (!options.cache) {
+                return resolve();
+            }
+            const pending = resolve();
+            this.sessionRootInflight.set(options.sessionId, pending);
+            try {
+                const resolved = yield pending;
+                this.sessionRoots.set(options.sessionId, resolved);
+                return resolved;
+            }
+            finally {
+                this.sessionRootInflight.delete(options.sessionId);
+            }
+        });
+    }
+    dropTurnFileSystem(sessionId) {
+        this.turnRoots.delete(sessionId);
+    }
+    prepareScratchToolInput(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (options.sessionId === undefined) {
+                return options.input;
+            }
+            const turn = this.turnRoots.get(options.sessionId);
+            if (turn === undefined) {
+                return options.input;
+            }
+            yield ingestHostAgentToolsScratch({
+                cwd: turn.cwd,
+                root: turn.root,
+            });
+            return remapScratchPaths(options.input, turn.cwd);
+        });
+    }
+    withTurnScratchTools(tools, sessionId) {
+        const turn = this.turnRoots.get(sessionId);
+        if (turn === undefined) {
+            return tools;
+        }
+        return tools.map((tool) => {
+            const execute = tool.definition.execute;
+            if (typeof execute !== "function") {
+                return tool;
+            }
+            return Object.assign(Object.assign({}, tool), { definition: Object.assign(Object.assign({}, tool.definition), { execute: (input, ctx) => __awaiter(this, void 0, void 0, function* () {
+                        const remapped = yield this.prepareScratchToolInput({
+                            sessionId,
+                            input: input !== null &&
+                                typeof input === "object" &&
+                                !Array.isArray(input)
+                                ? input
+                                : {},
+                        });
+                        return execute(remapped, ctx);
+                    }) }) });
+        });
+    }
+    nativeFileSystemOutcome(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { toolName, input, callId } = options;
+            if (!isFileSystemToolAlias(toolName)) {
+                return undefined;
+            }
+            // Same policy the authored callTool path asks: a dry-run write is
+            // answered by the host. Native edit/delete used to return before
+            // decideToolCall and persist through the FileSystem.
+            const decision = decideToolCall({
+                dryRun: options.dryRun === true,
+                effect: isMutatingFileSystemTool(toolName) ? "write" : "read",
+                input,
+            });
+            if (decision.kind === "answer") {
+                return {
+                    callId,
+                    toolName,
+                    isError: false,
+                    result: decision.result,
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                };
+            }
+            const root = yield this.resolveFileSystem({
+                sessionId: (_a = options.sessionId) !== null && _a !== void 0 ? _a : callId,
+                continuationKey: options.continuationKey,
+                cache: options.sessionId !== undefined,
+                cwd: options.cwd,
+            });
+            const rawArgs = input !== null && typeof input === "object" && !Array.isArray(input)
+                ? input
+                : {};
+            const args = yield this.prepareScratchToolInput({
+                sessionId: options.sessionId,
+                input: rawArgs,
+            });
+            const tool = fileSystemTool(root, toolName, args);
+            const execute = tool === null || tool === void 0 ? void 0 : tool.definition.execute;
+            if (tool === undefined || typeof execute !== "function") {
+                // A resolved root owns this native name. Falling through would let
+                // an authored lookalike run, or surface UnknownToolError after we
+                // already advertised the FileSystem tool.
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: {
+                        status: "error",
+                        error: { message: `FileSystem cannot handle ${toolName}` },
+                    },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: `FileSystem cannot handle ${toolName}`,
+                };
+            }
+            const validation = validateToolInput(tool.definition.inputSchema, args);
+            if (!validation.ok) {
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: {
+                        status: "error",
+                        error: { message: validation.message },
+                    },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: validation.message,
+                };
+            }
+            try {
+                const value = yield execute(validation.value, {
+                    toolCallId: callId,
+                    workspaceDir: options.cwd,
+                });
+                return {
+                    callId,
+                    toolName,
+                    isError: false,
+                    result: normalizeToolResult(value),
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: { status: "error", error: { message } },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: message,
+                };
+            }
+        });
+    }
     /**
      * Local harness cwd for a session: per-send override, else the shared
      * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
@@ -1298,14 +1525,16 @@ export class SessionEngine {
             const workspaceDir = (_a = agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir;
             if (workspaceDir === undefined ||
                 agent.runtime !== "local" ||
+                this.hasRootOverride() ||
                 this.runner.prewarm === undefined) {
                 return;
             }
             const startedAt = Date.now();
             try {
-                const outcome = yield this.runner.prewarm(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.sandbox) === true }, (agent.allowedTools === undefined
+                const harness = resolveHostHarnessToolOptions(agent.allowedTools);
+                const outcome = yield this.runner.prewarm(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.sandbox) === true }, (harness.tools === undefined ? {} : { tools: harness.tools })), (harness.disallowedTools === undefined
                     ? {}
-                    : { tools: agent.allowedTools })), { 
+                    : { disallowedTools: harness.disallowedTools })), { 
                     // No session yet, so auth'd connections are omitted rather than
                     // warmed without an identity; the per-send flag still has to match
                     // the turns' requests or the warmed executor is one no turn asks for.
@@ -1333,7 +1562,7 @@ export class SessionEngine {
     }
     executeTurn(record, turnId, message, isFirstTurn, signal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             const sessionId = record.sessionId;
             const workspaceDir = this.scaffoldDir(record);
             const harnessCwd = this.harnessCwd(record);
@@ -1380,35 +1609,48 @@ export class SessionEngine {
                     // cwd is overridden (e.g. a PR worktree). A/B variant instruction
                     // overlays are applied via agentForSession.
                     const agent = this.agentForSession(record);
-                    yield materializeWorkspace({
-                        agent,
-                        workspaceDir,
-                        seed: isFirstTurn,
-                        stateRoot: this.stateRoot,
-                    });
-                    this.materializedWorkspaces.add(sessionId);
-                    // Must precede the carrier: the harness resolves rules, skills,
-                    // `mcp.json` and hooks from its git root, so a workspace nested in an
-                    // outer repo would load that repo's hooks instead of the ones written
-                    // just below. Only for directories this session owns — a borrowed
-                    // checkout or worktree keeps its own root.
-                    if (!this.hasBorrowedWorkspace(record)) {
-                        yield ensureOwnGitRoot(harnessCwd);
+                    if (!this.hasRootOverride()) {
+                        yield materializeWorkspace({
+                            agent,
+                            workspaceDir,
+                            seed: isFirstTurn,
+                            stateRoot: this.stateRoot,
+                        });
+                        this.materializedWorkspaces.add(sessionId);
+                        // Must precede the carrier: the harness resolves rules, skills,
+                        // `mcp.json` and hooks from its git root, so a workspace nested in an
+                        // outer repo would load that repo's hooks instead of the ones written
+                        // just below. Only for directories this session owns — a borrowed
+                        // checkout or worktree keeps its own root.
+                        if (!this.hasBorrowedWorkspace(record)) {
+                            yield ensureOwnGitRoot(harnessCwd);
+                        }
+                        yield this.materializeNudgeCarrier(record, harnessCwd);
                     }
-                    yield this.materializeNudgeCarrier(record, harnessCwd);
                     // Baseline before the agent can run, so a follow-up that arrives and
                     // drains before the first tool boundary still counts as an increase.
                     yield this.baselineDeliveredNudges(record);
                     const pendingFiles = record.pendingWorkspaceFiles;
                     const pendingImages = record.pendingImages;
-                    if (pendingFiles !== undefined &&
-                        Object.keys(pendingFiles).length > 0) {
-                        yield writeWorkspaceFiles(harnessCwd, pendingFiles);
+                    const runtime = resolveSessionRuntime({
+                        agentRuntime: agent.runtime,
+                        cloudOverride: record.cloudOverride,
+                    });
+                    const hasPendingFiles = pendingFiles !== undefined && Object.keys(pendingFiles).length > 0;
+                    if (hasPendingFiles && runtime !== "cloud") {
+                        const root = yield this.resolveFileSystem({
+                            sessionId,
+                            continuationKey: (_a = record.continuationKey) !== null && _a !== void 0 ? _a : undefined,
+                            cache: true,
+                            cwd: harnessCwd,
+                        });
+                        yield writeWorkspaceFilesToRoot(root, pendingFiles);
                     }
-                    if ((pendingFiles !== undefined &&
-                        Object.keys(pendingFiles).length > 0) ||
+                    if ((hasPendingFiles && runtime !== "cloud") ||
                         (pendingImages !== undefined && pendingImages.length > 0)) {
-                        yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: current.pendingWorkspaceFiles === pendingFiles
+                        yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: hasPendingFiles &&
+                                runtime !== "cloud" &&
+                                current.pendingWorkspaceFiles === pendingFiles
                                 ? undefined
                                 : current.pendingWorkspaceFiles, pendingImages: current.pendingImages === pendingImages
                                 ? undefined
@@ -1423,6 +1665,14 @@ export class SessionEngine {
                         (this.hasBorrowedWorkspace(record) ||
                             (yield isNestedInGitRepo(harnessCwd)));
                     const request = yield this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                        const turn = this.turnRoots.get(sessionId);
+                        if (turn !== undefined) {
+                            update = yield applyWebScratchUpdate({
+                                cwd: turn.cwd,
+                                root: turn.root,
+                                update,
+                            });
+                        }
                         mapper.handleUpdate(update);
                         // Yield so the HTTP NDJSON writer can flush tool start/result
                         // events while sibling parallel tools are still executing.
@@ -1454,6 +1704,7 @@ export class SessionEngine {
                 }
                 finally {
                     permit.release();
+                    this.dropTurnFileSystem(sessionId);
                     this.approvals.cancelSession(sessionId, "deny");
                     this.auths.cancelSession(sessionId, "deny");
                     yield this.clearPendingApprovals(sessionId);
@@ -1468,15 +1719,15 @@ export class SessionEngine {
                 const title = mapper.title;
                 yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { title })));
             }
-            const finalResult = (_a = outcome.result) !== null && _a !== void 0 ? _a : mapper.finalText;
-            const finalUsage = (_b = outcome.usage) !== null && _b !== void 0 ? _b : mapper.usage;
+            const finalResult = (_b = outcome.result) !== null && _b !== void 0 ? _b : mapper.finalText;
+            const finalUsage = (_c = outcome.usage) !== null && _c !== void 0 ? _c : mapper.usage;
             const finalCost = finalUsage === undefined
                 ? undefined
                 : yield this.estimateTurnCost({
-                    model: (_c = this.project.agent.model) !== null && _c !== void 0 ? _c : DEFAULT_MODEL,
+                    model: (_d = this.project.agent.model) !== null && _d !== void 0 ? _d : DEFAULT_MODEL,
                     usage: finalUsage,
                     agentId: record.sdkAgentId,
-                    conversationId: (_d = record.sdkAgentId) !== null && _d !== void 0 ? _d : sessionId,
+                    conversationId: (_e = record.sdkAgentId) !== null && _e !== void 0 ? _e : sessionId,
                 });
             if (finalCost !== undefined) {
                 outcome = Object.assign(Object.assign({}, outcome), { cost: finalCost });
@@ -1524,22 +1775,23 @@ export class SessionEngine {
                     data: {
                         message: interrupted
                             ? "turn interrupted"
-                            : ((_e = outcome.errorMessage) !== null && _e !== void 0 ? _e : (outcome.status === "cancelled"
+                            : ((_f = outcome.errorMessage) !== null && _f !== void 0 ? _f : (outcome.status === "cancelled"
                                 ? "turn cancelled"
                                 : "turn failed")),
                     },
                 });
             }
             const current = yield this.sessions.get(sessionId);
-            const mode = (_f = current === null || current === void 0 ? void 0 : current.mode) !== null && _f !== void 0 ? _f : record.mode;
+            const mode = (_g = current === null || current === void 0 ? void 0 : current.mode) !== null && _g !== void 0 ? _g : record.mode;
             if (mode === "task") {
                 yield this.appendEvent(sessionId, outcome.status === "finished"
                     ? { type: "session.completed", turnId, data: {} }
                     : {
                         type: "session.failed",
                         turnId,
-                        data: { message: (_g = outcome.errorMessage) !== null && _g !== void 0 ? _g : "task failed" },
+                        data: { message: (_h = outcome.errorMessage) !== null && _h !== void 0 ? _h : "task failed" },
                     });
+                yield this.wipeCloudSessionWorkspace(sessionId);
             }
             else {
                 yield this.appendEvent(sessionId, {
@@ -1582,6 +1834,58 @@ export class SessionEngine {
             workspacePrefix: store.workspacePrefix,
         }));
     }
+    /**
+     * Replace this session's store prefix with the pending `workspaceFiles`.
+     * Undefined when the write did not land; the prompt must not name the
+     * mount, matching ensureCloudWorkspaceSynced.
+     */
+    syncCloudSessionWorkspaceFiles(store, sessionId, files) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const workspacePrefix = store.sessionWorkspacePrefix(sessionId);
+            try {
+                const relPaths = yield syncSessionWorkspaceFiles({
+                    sink: store.sink,
+                    files,
+                    workspacePrefix,
+                });
+                return {
+                    dir: `${store.mountPath}/${workspacePrefix}`,
+                    relPaths,
+                };
+            }
+            catch (error) {
+                this.logger(`[workspace] ${store.label} session files sync failed: ${error instanceof Error ? error.message : String(error)}`);
+                if (error instanceof WorkspaceFileRefusal) {
+                    yield this.clearPendingWorkspaceFiles(sessionId, files);
+                }
+                return undefined;
+            }
+        });
+    }
+    wipeCloudSessionWorkspace(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const store = this.cloudStore();
+            if (store === undefined) {
+                return;
+            }
+            try {
+                yield wipeSessionWorkspace({
+                    sink: store.sink,
+                    workspacePrefix: store.sessionWorkspacePrefix(sessionId),
+                });
+            }
+            catch (error) {
+                this.logger(`[workspace] ${store.label} session files wipe failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    clearPendingWorkspaceFiles(sessionId, pending) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: current.pendingWorkspaceFiles === pending
+                    ? undefined
+                    : current.pendingWorkspaceFiles })));
+        });
+    }
     /**
      * With files authored, every first cloud turn re-copies the authored
      * bytes and the memo only dedupes concurrent first turns. The mount is
@@ -1623,6 +1927,7 @@ export class SessionEngine {
             mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
             skillsPrefix: agentStoreKeys.skillsPrefix(),
             workspacePrefix: agentStoreKeys.workspacePrefix(),
+            sessionWorkspacePrefix: (sessionId) => agentStoreKeys.sessionWorkspacePrefix(sessionId),
             label: "deployment store",
         };
         if (v2Hosting.kind === "cursor-managed") {
@@ -1641,6 +1946,7 @@ export class SessionEngine {
                 mountPath: USER_STORE_MOUNT_PATH,
                 skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
                 workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
+                sessionWorkspacePrefix: (sessionId) => agentStoreKeys.userSessionWorkspacePrefix(this.project.name, sessionId),
                 label: "user store",
             };
         }
@@ -1649,6 +1955,7 @@ export class SessionEngine {
     buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal, images) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
+            var _d;
             // Per-session cloud attach (channel/tool handoff) forces cloud runtime
             // even when the agent defaults to local for chat server tools.
             const runtime = resolveSessionRuntime({
@@ -1659,6 +1966,15 @@ export class SessionEngine {
             // allowlist, and a restriction that silently does not apply is worse
             // than a refused turn. Non-local agents already fail discovery; this
             // guards hybrid agents' per-send cloud sessions.
+            //
+            // Factory roots omit `allowedTools` at discovery (the live handle is
+            // resolved per session). The allowlist guard below therefore never
+            // fires for `defineAgent({ root: (ctx) => … })` with omitted `tools`,
+            // and a per-send `cloud` attach would skip the virtual-root allowlist
+            // and run unrestricted on a VM. Any authored root refuses non-local turns.
+            if (runtime !== "local" && this.hasRootOverride()) {
+                throw new Error(`Agent "${agent.name}" declares root, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`);
+            }
             if (runtime !== "local" && agent.allowedTools !== undefined) {
                 throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`);
             }
@@ -1679,6 +1995,38 @@ export class SessionEngine {
                     override: record.cloudOverride,
                 })
                 : undefined;
+            const authoredRoot = this.hasRootOverride();
+            const root = runtime === "local"
+                ? yield this.resolveFileSystem({
+                    sessionId: record.sessionId,
+                    continuationKey: (_d = record.continuationKey) !== null && _d !== void 0 ? _d : undefined,
+                    cache: true,
+                    cwd: this.harnessCwd(record),
+                })
+                : undefined;
+            const harnessTools = runtime === "local" && root !== undefined
+                ? authoredRoot
+                    ? {
+                        tools: resolveFileSystemTools({
+                            root,
+                            tools: agent.allowedTools,
+                        }),
+                    }
+                    : resolveHostHarnessToolOptions(agent.allowedTools)
+                : undefined;
+            const fileTools = root === undefined
+                ? []
+                : synthesizeFileSystemTools(root, authoredRoot
+                    ? rootFileToolsFromAuthored(agent.allowedTools)
+                    : hostFileToolsFromAuthored(agent.allowedTools));
+            // Host-default keeps native SemanticSearch (the host index).
+            // `localFileSystem.search` is empty, so synthesizing would
+            // replace a working index with an empty custom tool.
+            const synthesized = root === undefined
+                ? []
+                : this.withTurnScratchTools(authoredRoot
+                    ? fileTools
+                    : fileTools.filter((tool) => tool.name !== "SemanticSearch"), record.sessionId);
             let turnPrompt = prompt;
             if (isFirstTurn) {
                 const contextBlock = buildSessionContextBlock({
@@ -1690,32 +2038,37 @@ export class SessionEngine {
                 });
                 turnPrompt = `${contextBlock}\n\n${prompt}`;
             }
-            if (isFirstTurn) {
-                if (runtime === "cloud") {
-                    // Cloud VMs have no materialized workspace: ship the full context,
-                    // including agent tool script bodies. Authored skills and workspace
-                    // seeds land on the store mount (skills for native discovery, seeds
-                    // for the model's file tools), and on hosted deployments the shared
-                    // memory journal is on that mount too — say where. When the turn
-                    // carries the session-bound server-tool MCP endpoint, the preamble
-                    // catalogs server tools under that MCP server name *before* the
-                    // agent-tool "write the script if missing" recipe, so a model told
-                    // to "use <server tool>" calls MCP instead of inventing a .sh.
-                    const preamble = buildAgentsMdContent(agent, {
+            if (runtime === "cloud") {
+                // Cloud VMs have no materialized workspace: ship the full context,
+                // including agent tool script bodies. Authored skills and workspace
+                // seeds land on the store mount (skills for native discovery, seeds
+                // for the model's file tools), per-turn workspaceFiles land under
+                // the session prefix, and on hosted deployments the shared memory
+                // journal is on that mount too — say where. When the turn carries
+                // the session-bound server-tool MCP endpoint, the preamble catalogs
+                // server tools under that MCP server name *before* the agent-tool
+                // "write the script if missing" recipe, so a model told to "use
+                // <server tool>" calls MCP instead of inventing a .sh.
+                const hosted = isCursorHostedFilesAvailable();
+                const store = hosted || isCursorUserStoreFilesAvailable()
+                    ? this.cloudStore()
+                    : undefined;
+                let preamble = "";
+                const sections = [];
+                const pending = record.pendingWorkspaceFiles;
+                if (isFirstTurn) {
+                    preamble = buildAgentsMdContent(agent, {
                         includeScripts: true,
                         serverToolsMcpName: this.cloudServerToolsConnection === undefined
                             ? undefined
                             : SERVER_TOOLS_MCP_SERVER_NAME,
                     });
-                    const hosted = isCursorHostedFilesAvailable();
-                    // Synced whenever a store is reachable, not just when skills or
-                    // seeds exist: removing the last one has to delete its store copies
-                    // too.
-                    const store = hosted || isCursorUserStoreFilesAvailable()
-                        ? this.cloudStore()
-                        : undefined;
-                    let sections = "";
-                    if (store !== undefined) {
+                }
+                if (store !== undefined) {
+                    if (isFirstTurn) {
+                        // Synced whenever a store is reachable, not just when skills or
+                        // seeds exist: removing the last one has to delete its store copies
+                        // too.
                         const [, seedsSynced] = yield Promise.all([
                             this.ensureCloudSkillsSynced(store),
                             this.ensureCloudWorkspaceSynced(store),
@@ -1723,32 +2076,62 @@ export class SessionEngine {
                         // Only name the mount when the bytes landed; a failed sync must
                         // not send the model looking for files that are not there.
                         if (seedsSynced && agent.seedFiles.length > 0) {
-                            const dir = `${store.mountPath}/${store.workspacePrefix}`;
-                            sections += `\n\n${buildCloudWorkspaceSection(dir)}`;
+                            sections.push(buildCloudWorkspaceSection(`${store.mountPath}/${store.workspacePrefix}`));
                         }
                     }
-                    if (hosted) {
-                        sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
+                    if (pending !== undefined && Object.keys(pending).length > 0) {
+                        const synced = yield this.syncCloudSessionWorkspaceFiles(store, record.sessionId, pending);
+                        if (synced !== undefined) {
+                            sections.push(buildCloudSessionWorkspaceSection(synced.dir, synced.relPaths));
+                            yield this.clearPendingWorkspaceFiles(record.sessionId, pending);
+                        }
                     }
-                    turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
                 }
-                else if (runtime === "local" && instructionsInvisibleToHarness) {
-                    // Local workspace whose AGENTS.md the harness will not load. With a
-                    // borrowed harness cwd, agent tool scripts live only in the durable
-                    // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-                    // reference on-disk paths under the harness cwd. Grokbot turns are
-                    // excluded: their instructions ride the request's `instructions`
-                    // field into the Sand system prompt instead.
-                    const includeScripts = this.hasBorrowedWorkspace(record);
-                    const preamble = buildAgentsMdContent(agent, { includeScripts });
-                    turnPrompt = `${preamble}\n\n${turnPrompt}`;
+                else if (pending !== undefined && Object.keys(pending).length > 0) {
+                    yield this.clearPendingWorkspaceFiles(record.sessionId, pending);
+                }
+                if (isFirstTurn && hosted) {
+                    sections.push(buildCloudMemorySection(this.project.name));
+                }
+                if (preamble !== "" || sections.length > 0) {
+                    turnPrompt = [preamble, ...sections, turnPrompt]
+                        .filter((part) => part !== "")
+                        .join("\n\n");
                 }
             }
+            else if (isFirstTurn && runtime === "local" && authoredRoot) {
+                // Virtual roots skip materialize, so AGENTS.md never lands on disk.
+                // Ship the same preamble the borrowed-cwd local path uses.
+                const preamble = buildAgentsMdContent(Object.assign(Object.assign({}, agent), { tools: [...agent.tools, ...synthesized] }), { includeScripts: true });
+                const workspaceInfo = `<user_info>\nWorkspace Path: /\n</user_info>`;
+                turnPrompt =
+                    preamble === ""
+                        ? `${workspaceInfo}\n\n${turnPrompt}`
+                        : `${workspaceInfo}\n\n${preamble}\n\n${turnPrompt}`;
+            }
+            else if (isFirstTurn &&
+                runtime === "local" &&
+                instructionsInvisibleToHarness) {
+                // Local workspace whose AGENTS.md the harness will not load. With a
+                // borrowed harness cwd, agent tool scripts live only in the durable
+                // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+                // reference on-disk paths under the harness cwd. Grokbot turns are
+                // excluded: their instructions ride the request's `instructions`
+                // field into the Sand system prompt instead.
+                const includeScripts = this.hasBorrowedWorkspace(record);
+                const preamble = buildAgentsMdContent(agent, { includeScripts });
+                turnPrompt = `${preamble}\n\n${turnPrompt}`;
+            }
             return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
                 ? {}
-                : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
-                ? { tools: agent.allowedTools }
-                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime, agentName: agent.name }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { 
+                : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: authoredRoot
+                    ? false
+                    : ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && harnessTools !== undefined
+                ? Object.assign(Object.assign({}, (harnessTools.tools === undefined
+                    ? {}
+                    : { tools: harnessTools.tools })), (harnessTools.disallowedTools === undefined
+                    ? {}
+                    : { disallowedTools: harnessTools.disallowedTools })) : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime, agentName: agent.name }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { 
                 // The hosted Grok Bot harness reads no workspace AGENTS.md: grokbot
                 // turns carry the composed instructions into the hosted session,
                 // which surfaces them in the Sand system prompt. The box never sees
@@ -1759,7 +2142,7 @@ export class SessionEngine {
                     : undefined }), (runtime === "cloud" && !isCursorHostedFilesAvailable()
                 ? { agentServeAgent: this.project.name }
                 : {})), { customTools: runtime === "local"
-                    ? yield this.buildCustomTools(record, agent, turnId, emit)
+                    ? yield this.buildCustomTools(record, agent, turnId, emit, synthesized)
                     : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId, yield this.evaluateConnectionAuth(record)) }), (runtime === "local" && this.hasAttachedAuthedConnections()
                 ? { perSendMcpServers: true }
                 : {})), { subagents: buildRunnerSubagents(agent), onUpdate,
@@ -1982,8 +2365,8 @@ export class SessionEngine {
             return evaluated;
         });
     }
-    buildCustomTools(record, agent, turnId, emit) {
-        return __awaiter(this, void 0, void 0, function* () {
+    buildCustomTools(record_1, agent_1, turnId_1, emit_1) {
+        return __awaiter(this, arguments, void 0, function* (record, agent, turnId, emit, extraTools = []) {
             const tools = {};
             const register = (tool) => {
                 tools[tool.name] = Object.assign(Object.assign(Object.assign({ description: tool.description, inputSchema: tool.inputSchema }, (tool.outputSchema === undefined
@@ -2003,7 +2386,7 @@ export class SessionEngine {
                         });
                     }) });
             };
-            for (const tool of agent.tools) {
+            for (const tool of [...agent.tools, ...extraTools]) {
                 if (tool.execution !== "server") {
                     continue;
                 }
@@ -2672,6 +3055,7 @@ export class SessionEngine {
     callTool(toolName_1) {
         return __awaiter(this, arguments, void 0, function* (toolName, input = {}, options = {}) {
             var _a;
+            var _b, _c;
             const callId = newToolCallId(toolName);
             // Identity resolves before the tool lookup: advertised connection tools
             // only exist relative to a session (per-session auth), so finding them
@@ -2681,6 +3065,24 @@ export class SessionEngine {
             const session = identity.session;
             let workspaceDir = identity.workspaceDir;
             let scratchDir = identity.scratchDir;
+            if (isFileSystemToolAlias(toolName) &&
+                identity.busy &&
+                record !== undefined &&
+                isMutatingFileSystemTool(toolName)) {
+                throw new SessionBusyError(record.sessionId);
+            }
+            const native = yield this.nativeFileSystemOutcome({
+                toolName,
+                input,
+                callId,
+                sessionId: record === null || record === void 0 ? void 0 : record.sessionId,
+                continuationKey: (_c = (_b = record === null || record === void 0 ? void 0 : record.continuationKey) !== null && _b !== void 0 ? _b : session.continuationKey) !== null && _c !== void 0 ? _c : undefined,
+                cwd: workspaceDir,
+                dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true,
+            });
+            if (native !== undefined) {
+                return native;
+            }
             let tool = this.project.agent.tools.find((t) => t.name === toolName);
             if (tool === undefined &&
                 this.project.agent.connections.some((c) => c.advertiseTools === true)) {
@@ -2769,7 +3171,8 @@ export class SessionEngine {
             const turnMaterialized = record !== undefined &&
                 identity.busy &&
                 this.materializedWorkspaces.has(record.sessionId);
-            if (record === undefined || workspaceUnavailable || !turnMaterialized) {
+            if (!this.hasRootOverride() &&
+                (record === undefined || workspaceUnavailable || !turnMaterialized)) {
                 yield materializeWorkspace({
                     agent: this.project.agent,
                     workspaceDir: record === undefined || workspaceUnavailable
@@ -3548,7 +3951,8 @@ export class SessionEngine {
     }
     runCloudTurnCostBackfill(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a;
+            var _b, _c;
             const log = yield this.logs.get(sessionId);
             const events = yield log.snapshot(0);
             if (!events.some((event) => isUnpricedCompletedTurn(event))) {
@@ -3559,9 +3963,7 @@ export class SessionEngine {
                 return;
             }
             const record = yield this.sessions.get(sessionId);
-            const sdkAgentId = (_a = ((record === null || record === void 0 ? void 0 : record.sdkAgentId) !== undefined && record.sdkAgentId.startsWith("bc-")
-                ? record.sdkAgentId
-                : undefined)) !== null && _a !== void 0 ? _a : cloudSdkAgentIdFromEvents(events);
+            const sdkAgentId = (_b = (((_a = record === null || record === void 0 ? void 0 : record.sdkAgentId) === null || _a === void 0 ? void 0 : _a.startsWith("bc-")) ? record.sdkAgentId : undefined)) !== null && _b !== void 0 ? _b : cloudSdkAgentIdFromEvents(events);
             if (sdkAgentId === undefined) {
                 return;
             }
@@ -3569,7 +3971,7 @@ export class SessionEngine {
             if (billed === undefined) {
                 return;
             }
-            const model = (_b = this.project.agent.model) !== null && _b !== void 0 ? _b : DEFAULT_MODEL;
+            const model = (_c = this.project.agent.model) !== null && _c !== void 0 ? _c : DEFAULT_MODEL;
             const patched = applyCloudUsageToEvents(events, billed, model);
             if (patched === undefined) {
                 return;