@cursor/july 0.1.103 → 0.1.104

package/src/internal/session-engine.ts

@@ -37,6 +37,17 @@ import {
   isCursorHostedFilesAvailable,
   isCursorUserStoreFilesAvailable,
 } from "../files-backends/cursor-hosted.js";
+import {
+  type FileSystem,
+  isFileSystemToolAlias,
+  isMutatingFileSystemTool,
+  localFileSystem,
+  resolveFileSystemTools,
+  resolveHostHarnessToolOptions,
+  tempFs,
+  unionFs,
+  writeWorkspaceFilesToRoot,
+} from "../filesystem.js";
 import { storageKeysForArchitecture } from "../storage.js";
 import {
   type AgentProject,
@@ -69,6 +80,7 @@ import {
   type PendingAuth,
   type ReceiveInput,
   type ResolvedAgent,
+  type RootContext,
   type RunnerSubagent,
   type RunnerTurnRequest,
   type SendMessageFn,
@@ -124,6 +136,17 @@ import { describeError } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { type EventLogMemoryStats, 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";
@@ -184,7 +207,6 @@ import {
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
-  writeWorkspaceFiles,
 } from "./workspace.js";
 import { syncWorkspaceToStore } from "./workspace-sync.js";
 
@@ -510,6 +532,15 @@ export class SessionEngine {
   private readonly cloudCostBackfillDone = new Set<string>();
   /** Deduped in-flight cloud cost backfills, keyed by session id. */
   private readonly cloudCostBackfill = new Map<string, Promise<void>>();
+  /** Per-session FileSystem handle cache (not a tree snapshot). */
+  private readonly sessionRoots = new Map<string, FileSystem>();
+  /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+  private readonly sessionRootInflight = new Map<string, Promise<FileSystem>>();
+  /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+  private readonly turnRoots = new Map<
+    string,
+    { root: FileSystem; cwd: string }
+  >();
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
@@ -1793,6 +1824,261 @@ export class SessionEngine {
     return this.interrupt(existing.sessionId);
   }
 
+  private hasRootOverride(): boolean {
+    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.
+   */
+  private async resolveFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+    cwd: string;
+  }): Promise<FileSystem> {
+    const authored = this.project.agent.root;
+    if (authored === undefined) {
+      return localFileSystem({ cwd: options.cwd });
+    }
+    const authoredRoot = await 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;
+  }
+
+  private async resolveAuthoredFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+  }): Promise<FileSystem> {
+    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 = async (): Promise<FileSystem> => {
+      if (typeof authored !== "function") {
+        return authored;
+      }
+      const host = this.hostForSession(
+        options.cache ? options.sessionId : undefined
+      );
+      const ctx: RootContext = {
+        sessionId: options.sessionId,
+        agentName: this.project.agent.name,
+        ...(options.continuationKey === undefined
+          ? {}
+          : { continuationKey: options.continuationKey }),
+        host: { files: host.files, reminders: host.reminders },
+      };
+      return await authored(ctx);
+    };
+    if (!options.cache) {
+      return resolve();
+    }
+    const pending = resolve();
+    this.sessionRootInflight.set(options.sessionId, pending);
+    try {
+      const resolved = await pending;
+      this.sessionRoots.set(options.sessionId, resolved);
+      return resolved;
+    } finally {
+      this.sessionRootInflight.delete(options.sessionId);
+    }
+  }
+
+  private dropTurnFileSystem(sessionId: string): void {
+    this.turnRoots.delete(sessionId);
+  }
+
+  private async prepareScratchToolInput(options: {
+    sessionId?: string;
+    input: Record<string, unknown>;
+  }): Promise<Record<string, unknown>> {
+    if (options.sessionId === undefined) {
+      return options.input;
+    }
+    const turn = this.turnRoots.get(options.sessionId);
+    if (turn === undefined) {
+      return options.input;
+    }
+    await ingestHostAgentToolsScratch({
+      cwd: turn.cwd,
+      root: turn.root,
+    });
+    return remapScratchPaths(options.input, turn.cwd);
+  }
+
+  private withTurnScratchTools(
+    tools: DiscoveredTool[],
+    sessionId: string
+  ): DiscoveredTool[] {
+    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 {
+        ...tool,
+        definition: {
+          ...tool.definition,
+          execute: async (input, ctx) => {
+            const remapped = await this.prepareScratchToolInput({
+              sessionId,
+              input:
+                input !== null &&
+                typeof input === "object" &&
+                !Array.isArray(input)
+                  ? (input as Record<string, unknown>)
+                  : {},
+            });
+            return execute(remapped as never, ctx);
+          },
+        },
+      };
+    });
+  }
+
+  private async nativeFileSystemOutcome(options: {
+    toolName: string;
+    input: unknown;
+    callId: string;
+    sessionId?: string;
+    continuationKey?: string;
+    cwd: string;
+    dryRun?: boolean;
+  }): Promise<ToolCallOutcome | undefined> {
+    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 = await this.resolveFileSystem({
+      sessionId: options.sessionId ?? callId,
+      continuationKey: options.continuationKey,
+      cache: options.sessionId !== undefined,
+      cwd: options.cwd,
+    });
+    const rawArgs =
+      input !== null && typeof input === "object" && !Array.isArray(input)
+        ? (input as Record<string, unknown>)
+        : {};
+    const args = await this.prepareScratchToolInput({
+      sessionId: options.sessionId,
+      input: rawArgs,
+    });
+    const tool = fileSystemTool(root, toolName, args);
+    const execute = 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 = await execute(
+        validation.value as never,
+        {
+          toolCallId: callId,
+          workspaceDir: options.cwd,
+        } as never
+      );
+      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
@@ -1840,19 +2126,22 @@ export class SessionEngine {
     if (
       workspaceDir === undefined ||
       agent.runtime !== "local" ||
+      this.hasRootOverride() ||
       this.runner.prewarm === undefined
     ) {
       return;
     }
     const startedAt = Date.now();
     try {
+      const harness = resolveHostHarnessToolOptions(agent.allowedTools);
       const outcome = await this.runner.prewarm({
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
-        ...(agent.allowedTools === undefined
+        ...(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.
@@ -1942,22 +2231,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);
-        await 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)) {
-          await ensureOwnGitRoot(harnessCwd);
+        if (!this.hasRootOverride()) {
+          await 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)) {
+            await ensureOwnGitRoot(harnessCwd);
+          }
+          await this.materializeNudgeCarrier(record, harnessCwd);
         }
-        await 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.
         await this.baselineDeliveredNudges(record);
@@ -1967,7 +2258,13 @@ export class SessionEngine {
           pendingFiles !== undefined &&
           Object.keys(pendingFiles).length > 0
         ) {
-          await writeWorkspaceFiles(harnessCwd, pendingFiles);
+          const root = await this.resolveFileSystem({
+            sessionId,
+            continuationKey: record.continuationKey ?? undefined,
+            cache: true,
+            cwd: harnessCwd,
+          });
+          await writeWorkspaceFilesToRoot(root, pendingFiles);
         }
         if (
           (pendingFiles !== undefined &&
@@ -2004,6 +2301,14 @@ export class SessionEngine {
           instructionsInvisibleToHarness,
           emit,
           async (update) => {
+            const turn = this.turnRoots.get(sessionId);
+            if (turn !== undefined) {
+              update = await 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.
@@ -2039,6 +2344,7 @@ export class SessionEngine {
         outcome = { status: "error", errorMessage: describeError(error) };
       } finally {
         permit.release();
+        this.dropTurnFileSystem(sessionId);
         this.approvals.cancelSession(sessionId, "deny");
         this.auths.cancelSession(sessionId, "deny");
         await this.clearPendingApprovals(sessionId);
@@ -2291,6 +2597,17 @@ 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.`
@@ -2319,6 +2636,48 @@ export class SessionEngine {
             override: record.cloudOverride,
           })
         : undefined;
+    const authoredRoot = this.hasRootOverride();
+    const root =
+      runtime === "local"
+        ? await this.resolveFileSystem({
+            sessionId: record.sessionId,
+            continuationKey: record.continuationKey ?? 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({
@@ -2374,6 +2733,18 @@ export class SessionEngine {
           sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
         }
         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(
+          { ...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
         // borrowed harness cwd, agent tool scripts live only in the durable
@@ -2392,9 +2763,18 @@ export class SessionEngine {
         ? {}
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
-      sandbox: this.project.agent.local?.sandbox === true,
-      ...(runtime === "local" && agent.allowedTools !== undefined
-        ? { tools: agent.allowedTools }
+      sandbox: authoredRoot
+        ? false
+        : this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && harnessTools !== undefined
+        ? {
+            ...(harnessTools.tools === undefined
+              ? {}
+              : { tools: harnessTools.tools }),
+            ...(harnessTools.disallowedTools === undefined
+              ? {}
+              : { disallowedTools: harnessTools.disallowedTools }),
+          }
         : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
@@ -2418,7 +2798,13 @@ export class SessionEngine {
         : {}),
       customTools:
         runtime === "local"
-          ? await this.buildCustomTools(record, agent, turnId, emit)
+          ? await this.buildCustomTools(
+              record,
+              agent,
+              turnId,
+              emit,
+              synthesized
+            )
           : {},
       mcpServers: this.buildMcpServers(
         runtime,
@@ -2712,7 +3098,8 @@ export class SessionEngine {
     record: SessionRecord,
     agent: ResolvedAgent,
     turnId: string,
-    emit: (payload: SessionEventPayload) => void
+    emit: (payload: SessionEventPayload) => void,
+    extraTools: DiscoveredTool[] = []
   ): Promise<Record<string, SDKCustomTool>> {
     const tools: Record<string, SDKCustomTool> = {};
     const register = (tool: ResolvedAgent["tools"][number]): void => {
@@ -2742,7 +3129,7 @@ export class SessionEngine {
         },
       };
     };
-    for (const tool of agent.tools) {
+    for (const tool of [...agent.tools, ...extraTools]) {
       if (tool.execution !== "server") {
         continue;
       }
@@ -3682,6 +4069,27 @@ 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 = await this.nativeFileSystemOutcome({
+      toolName,
+      input,
+      callId,
+      sessionId: record?.sessionId,
+      continuationKey:
+        record?.continuationKey ?? session.continuationKey ?? undefined,
+      cwd: workspaceDir,
+      dryRun: record?.dryRun === true,
+    });
+    if (native !== undefined) {
+      return native;
+    }
     let tool = this.project.agent.tools.find((t) => t.name === toolName);
     if (
       tool === undefined &&
@@ -3783,7 +4191,10 @@ export class SessionEngine {
       record !== undefined &&
       identity.busy &&
       this.materializedWorkspaces.has(record.sessionId);
-    if (record === undefined || workspaceUnavailable || !turnMaterialized) {
+    if (
+      !this.hasRootOverride() &&
+      (record === undefined || workspaceUnavailable || !turnMaterialized)
+    ) {
       await materializeWorkspace({
         agent: this.project.agent,
         workspaceDir:
@@ -4745,9 +5156,8 @@ export class SessionEngine {
     }
     const record = await this.sessions.get(sessionId);
     const sdkAgentId =
-      (record?.sdkAgentId !== undefined && record.sdkAgentId.startsWith("bc-")
-        ? record.sdkAgentId
-        : undefined) ?? cloudSdkAgentIdFromEvents(events);
+      (record?.sdkAgentId?.startsWith("bc-") ? record.sdkAgentId : undefined) ??
+      cloudSdkAgentIdFromEvents(events);
     if (sdkAgentId === undefined) {
       return;
     }