@cursor/july 0.1.102 → 0.1.104

package/dist/internal/session-engine.js

@@ -23,8 +23,9 @@ import { SLACK_CHANNEL_ID } from "../channels/slack/constants.js";
 import { materializeSlackNudgeCarrier } from "../channels/slack/nudge-carrier.js";
 import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
-import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, } from "../files.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";
@@ -39,9 +40,12 @@ import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { applyCloudUsageToEvents, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, mapSdkTokenUsage, } from "./cloud-turn-cost.js";
 import { applyAgentContinuationDefaults, channelContinuationIdentity, httpContinuationIdentity, } from "./continuation-channel.js";
 import { continuationSource, resolveV2Key, V2EngineError, } from "./continuation-identity.js";
+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";
@@ -55,6 +59,7 @@ import { McpOauthOnDemandHub } from "./mcp-oauth-on-demand.js";
 import { shouldStartProcessMemoryTelemetry, startProcessMemoryTelemetry, } from "./process-memory-telemetry.js";
 import { buildSessionContextBlock, SCHEDULE_CHANNEL_PREFIX, } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
+import { applyAuthoredResult } from "./result-output.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
@@ -67,7 +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, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, writeWorkspaceFiles, } from "./workspace.js";
+import { buildAgentsMdContent, buildCloudMemorySection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, } from "./workspace.js";
+import { syncWorkspaceToStore } from "./workspace-sync.js";
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
@@ -158,6 +164,8 @@ export class SessionEngine {
         var _a, _b, _c, _d, _e;
         /** In-flight lazy restores, deduped per channel + continuation key. */
         this.restoreInFlight = new Map();
+        /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+        this.cloudSyncs = new Map();
         this.channelsById = new Map();
         /** Sessions with a turn being admitted (before the run promise exists). */
         this.pendingTurns = new Set();
@@ -213,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;
@@ -353,9 +367,9 @@ export class SessionEngine {
         };
     }
     /**
-     * Host services with `files` bound to one session, so a relative path in a
-     * tool or hook resolves to that session's scope and can never be read as
-     * another session's. Unbound (no session) keeps `host.files` usable for
+     * Host services with `files` and `otel` bound to one session, so a relative
+     * path resolves to that session's scope and can never read another
+     * session's. Unbound (no session) keeps `host.files` usable for
      * `{ scope: "deployment" }` and fails loudly on session-scoped calls.
      */
     hostForSession(sessionId) {
@@ -1247,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
@@ -1293,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.
@@ -1328,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);
@@ -1375,22 +1609,24 @@ 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);
@@ -1398,7 +1634,13 @@ export class SessionEngine {
                     const pendingImages = record.pendingImages;
                     if (pendingFiles !== undefined &&
                         Object.keys(pendingFiles).length > 0) {
-                        yield writeWorkspaceFiles(harnessCwd, pendingFiles);
+                        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) ||
@@ -1418,6 +1660,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.
@@ -1435,7 +1685,7 @@ export class SessionEngine {
                     this.activeToolContexts.set(sessionId, { record, turnId, emit });
                     this.stubbedCallIds.set(sessionId, stubbed);
                     try {
-                        outcome = yield this.runner.runTurn(request);
+                        outcome = yield this.runTurnExecute(record, turnId, () => this.runner.runTurn(request));
                     }
                     finally {
                         this.activeToolContexts.delete(sessionId);
@@ -1449,6 +1699,7 @@ export class SessionEngine {
                 }
                 finally {
                     permit.release();
+                    this.dropTurnFileSystem(sessionId);
                     this.approvals.cancelSession(sessionId, "deny");
                     this.auths.cancelSession(sessionId, "deny");
                     yield this.clearPendingApprovals(sessionId);
@@ -1463,24 +1714,52 @@ 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 });
             }
+            const authored = this.project.result;
+            if (outcome.status === "finished" && authored !== undefined) {
+                const settled = yield applyAuthoredResult({
+                    definition: authored,
+                    text: finalResult,
+                    dryRun: record.dryRun === true,
+                    ctx: {
+                        session: this.sessionInfo(record),
+                        host: this.hostForSession(sessionId),
+                        artifacts: this.artifactsApi({ sessionId, turnId }),
+                        stateRoot: this.stateRoot,
+                        workspaceDir: harnessCwd,
+                    },
+                });
+                if (!settled.ok) {
+                    outcome = {
+                        status: "error",
+                        result: finalResult,
+                        errorMessage: `turn output failed: ${settled.message}`,
+                        usage: finalUsage,
+                        cost: finalCost,
+                    };
+                }
+            }
             if (outcome.status === "finished") {
                 yield this.appendEvent(sessionId, {
                     type: "turn.completed",
                     turnId,
-                    data: Object.assign(Object.assign(Object.assign({}, (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage })), (finalCost === undefined ? {} : { cost: finalCost })),
+                    data: {
+                        result: finalResult,
+                        usage: finalUsage,
+                        cost: finalCost,
+                    },
                 });
             }
             else {
@@ -1491,21 +1770,21 @@ 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" },
                     });
             }
             else {
@@ -1515,7 +1794,7 @@ export class SessionEngine {
                     data: {},
                 });
             }
-            return Object.assign(Object.assign(Object.assign({}, outcome), (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage }));
+            return Object.assign(Object.assign({}, outcome), { result: finalResult, usage: finalUsage });
         });
     }
     /**
@@ -1525,75 +1804,89 @@ export class SessionEngine {
      * first-turn S3 scan can discover them. False when the sync fails: the
      * turn then runs without store skills rather than pointing discovery at
      * paths that do not exist.
-     *
-     * With skills authored, every first cloud turn re-copies the authored
+     */
+    ensureCloudSkillsSynced(store) {
+        const skills = this.project.agent.skills;
+        return this.syncToCloudStore("skills", store, skills.length > 0, () => syncSkillsToStore({
+            sink: store.sink,
+            agentName: this.project.name,
+            skills,
+            skillsPrefix: store.skillsPrefix,
+        }));
+    }
+    /**
+     * Sync `agent/sandbox/workspace/**` seeds onto the Agent Store at
+     * `workspace/…` (hosted) or `agent-serve/<agent>/workspace/…`
+     * (personal-key local+cloud) before the first cloud prompt, which names
+     * the mounted directory (see buildCloudWorkspaceSection).
+     */
+    ensureCloudWorkspaceSynced(store) {
+        const seedFiles = this.project.agent.seedFiles;
+        return this.syncToCloudStore("workspace", store, seedFiles.length > 0, () => syncWorkspaceToStore({
+            sink: store.sink,
+            seedFiles,
+            workspacePrefix: store.workspacePrefix,
+        }));
+    }
+    /**
+     * With files authored, every first cloud turn re-copies the authored
      * bytes and the memo only dedupes concurrent first turns. The mount is
      * writable from cloud sessions, so a once-per-process copy would let one
      * session's edits masquerade as agent definition for every later session
      * until the engine restarts; re-syncing keeps the store true to discovery
      * the same way local materialization always rewrites skills. Without
-     * skills the sync is best-effort stale cleanup and one attempt per
-     * process is enough, success or not — a deployment without the files
+     * authored files the sync is best-effort stale cleanup and one attempt
+     * per process is enough, success or not — a deployment without the files
      * surface must not fail and log on every new session for a feature it
      * does not use.
      */
-    ensureCloudSkillsSynced() {
-        if (this.cloudSkillsSync !== undefined) {
-            return this.cloudSkillsSync;
-        }
-        const target = this.cloudSkillsStore();
-        if (target === undefined) {
-            this.cloudSkillsSync = Promise.resolve(false);
-            return this.cloudSkillsSync;
+    syncToCloudStore(surface, store, authored, run) {
+        const inFlight = this.cloudSyncs.get(surface);
+        if (inFlight !== undefined) {
+            return inFlight;
         }
-        const skills = this.project.agent.skills;
-        let sync = syncSkillsToStore({
-            sink: target.sink,
-            agentName: this.project.name,
-            skills,
-            skillsPrefix: target.skillsPrefix,
-        }).then(() => true, (error) => {
-            this.logger(`[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`);
+        let sync = run().then(() => true, (error) => {
+            this.logger(`[${surface}] ${store.label} sync failed: ${error instanceof Error ? error.message : String(error)}`);
             return false;
         });
-        if (skills.length > 0) {
+        if (authored) {
             sync = sync.finally(() => {
-                this.cloudSkillsSync = undefined;
+                this.cloudSyncs.delete(surface);
             });
         }
-        this.cloudSkillsSync = sync;
+        this.cloudSyncs.set(surface, sync);
         return sync;
     }
     /**
      * Hosted deployments own the deployment store. Local `serve`/`run` with
      * a personal API key writes into the USER store under `agent-serve/`.
      */
-    cloudSkillsStore() {
+    cloudStore() {
         const v2Hosting = resolveAgentV2Hosting({
             architecture: this.project.agent.architecture,
         });
+        const deployment = {
+            mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
+            skillsPrefix: agentStoreKeys.skillsPrefix(),
+            workspacePrefix: agentStoreKeys.workspacePrefix(),
+            label: "deployment store",
+        };
         if (v2Hosting.kind === "cursor-managed") {
-            return {
-                sink: cursorHostedFiles({
+            return Object.assign({ sink: cursorHostedFiles({
                     resolveStoreSourceId: () => v2Hosting.resolveStoreIds().deploymentStoreSourceId,
-                }),
-                skillsPrefix: agentStoreKeys.skillsPrefix(),
-                label: "deployment store",
-            };
+                }) }, deployment);
         }
         if (v2Hosting.kind === "not-v2" && isCursorHostedFilesAvailable()) {
-            return {
-                sink: cursorHostedFiles(),
-                skillsPrefix: agentStoreKeys.skillsPrefix(),
-                label: "deployment store",
-            };
+            return Object.assign({ sink: cursorHostedFiles() }, deployment);
         }
         if (isCursorUserStoreFilesAvailable()) {
             return {
                 sink: cursorHostedFiles({
                     storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
                 }),
+                mountPath: USER_STORE_MOUNT_PATH,
                 skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+                workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
                 label: "user store",
             };
         }
@@ -1602,6 +1895,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({
@@ -1612,6 +1906,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.`);
             }
@@ -1632,6 +1935,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({
@@ -1646,13 +1981,14 @@ export class SessionEngine {
             if (isFirstTurn) {
                 if (runtime === "cloud") {
                     // Cloud VMs have no materialized workspace: ship the full context,
-                    // including agent tool script bodies. On hosted deployments authored
-                    // skills land on the store mount for native discovery, and 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.
+                    // 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, {
                         includeScripts: true,
                         serverToolsMcpName: this.cloudServerToolsConnection === undefined
@@ -1660,17 +1996,39 @@ export class SessionEngine {
                             : SERVER_TOOLS_MCP_SERVER_NAME,
                     });
                     const hosted = isCursorHostedFilesAvailable();
-                    // Synced whenever a store is reachable, not just when skills exist:
-                    // removing the last skill has to delete its store copies too.
-                    // Discovery is native (`--agent-store-skills-dir`); this only has
-                    // to land the bytes.
-                    if (hosted || isCursorUserStoreFilesAvailable()) {
-                        yield this.ensureCloudSkillsSynced();
+                    // 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) {
+                        const [, seedsSynced] = yield Promise.all([
+                            this.ensureCloudSkillsSynced(store),
+                            this.ensureCloudWorkspaceSynced(store),
+                        ]);
+                        // 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)}`;
+                        }
+                    }
+                    if (hosted) {
+                        sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
                     }
-                    const memorySection = hosted
-                        ? `\n\n${buildCloudMemorySection(this.project.name)}`
-                        : "";
-                    turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
+                    turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
+                }
+                else if (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 (runtime === "local" && instructionsInvisibleToHarness) {
                     // Local workspace whose AGENTS.md the harness will not load. With a
@@ -1686,9 +2044,14 @@ export class SessionEngine {
             }
             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
@@ -1699,7 +2062,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,
@@ -1922,8 +2285,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
@@ -1943,7 +2306,7 @@ export class SessionEngine {
                         });
                     }) });
             };
-            for (const tool of agent.tools) {
+            for (const tool of [...agent.tools, ...extraTools]) {
                 if (tool.execution !== "server") {
                     continue;
                 }
@@ -2091,6 +2454,23 @@ export class SessionEngine {
             }
         });
     }
+    /**
+     * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+     * turn span for the whole harness run. Host files / VFS RPCs happen
+     * here, not under `runInCall`. No-op when OTel is off.
+     */
+    runTurnExecute(record, turnId, fn) {
+        const otel = this.otel;
+        const run = () => Promise.resolve(fn());
+        if (otel === undefined) {
+            return run();
+        }
+        return otel.runInTurn({
+            sessionId: record.sessionId,
+            session: this.sessionInfo(record),
+            turnId,
+        }, run);
+    }
     /**
      * Bind outbound inject (Factory / Cursor API `traceparent`) to the
      * tool span. No-op when OTel is off.
@@ -2595,6 +2975,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
@@ -2604,6 +2985,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)) {
@@ -2692,7 +3091,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
@@ -2946,7 +3346,10 @@ export class SessionEngine {
             if (record === undefined) {
                 return;
             }
-            const sessionCtx = { session: this.sessionInfo(record) };
+            const sessionCtx = {
+                session: this.sessionInfo(record),
+                host: this.hostForSession(record.sessionId),
+            };
             const channelEvents = this.channelEventHandlersFor(record.channelId);
             if (channelEvents !== undefined) {
                 // Handlers are declared against the narrowed event for their key; the
@@ -2985,20 +3388,13 @@ export class SessionEngine {
                         continue;
                     }
                     try {
-                        yield handler(event, {
-                            agent: { name: this.project.name },
-                            channel: {
+                        yield handler(event, Object.assign(Object.assign({}, sessionCtx), { agent: { name: this.project.name }, channel: {
                                 id: record.channelId,
                                 continuationToken: record.continuationKey,
-                            },
-                            session: this.sessionInfo(record),
-                            stateRoot: this.stateRoot,
-                            host: this.hostForSession(record.sessionId),
-                            artifacts: this.artifactsApi({
+                            }, stateRoot: this.stateRoot, artifacts: this.artifactsApi({
                                 sessionId: record.sessionId,
                                 turnId: event.turnId,
-                            }),
-                        });
+                            }) }));
                     }
                     catch (error) {
                         this.logger(`[agent-sdk] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
@@ -3006,9 +3402,9 @@ export class SessionEngine {
                 }
             }
             if (this.abCollector.enabled) {
-                yield this.abCollector.onEvent(event, this.sessionInfo(record), this.project.name);
+                yield this.abCollector.onEvent(event, sessionCtx.session, this.project.name);
             }
-            (_a = this.otel) === null || _a === void 0 ? void 0 : _a.onEvent(event, this.sessionInfo(record));
+            (_a = this.otel) === null || _a === void 0 ? void 0 : _a.onEvent(event, sessionCtx.session);
         });
     }
     channelEventHandlersFor(channelId) {
@@ -3475,7 +3871,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))) {
@@ -3486,9 +3883,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;
             }
@@ -3496,7 +3891,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;
@@ -3910,9 +4305,6 @@ function subagentPrompt(subagent) {
 function buildRunnerSubagents(agent) {
     return agent.subagents.map((subagent) => { var _a; return (Object.assign({ name: subagent.name, description: (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name, prompt: subagentPrompt(subagent) }, (subagent.model === undefined ? {} : { model: subagent.model }))); });
 }
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 function toolErrorResult(message) {
     return {
         content: [{ type: "text", text: message }],