@cursor/july 0.1.33 → 0.1.35

package/src/internal/session-engine.ts

@@ -9,7 +9,7 @@
 
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import type { SDKCustomTool } from "@cursor/sdk";
+import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
 import {
   type ABDefinition,
   mergeABInstructions,
@@ -22,6 +22,7 @@ import {
   SlackNudgeStore,
 } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
+import { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -102,6 +103,7 @@ import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections
 import type { AgentRunner } from "./sdk-runner.js";
 import { SessionStore } from "./session-store.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
+import type { FrameworkSessionStore } from "./storage-roles.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -111,8 +113,10 @@ import {
 import { TurnGovernor } from "./turn-governor.js";
 import {
   buildAgentsMdContent,
+  buildCloudMemorySection,
   isNestedInGitRepo,
   materializeWorkspace,
+  SERVER_TOOLS_MCP_SERVER_NAME,
   writeWorkspaceFiles,
 } from "./workspace.js";
 
@@ -237,6 +241,12 @@ export interface EngineResolvedConnection {
   accountServersFilter?: readonly string[];
 }
 
+interface ActiveToolContext {
+  record: SessionRecord;
+  turnId: string;
+  emit: (payload: SessionEventPayload) => void;
+}
+
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
 }
@@ -286,6 +296,8 @@ export class SessionEngine {
   /** Sessions with a turn being admitted (before the run promise exists). */
   private readonly pendingTurns = new Set<string>();
   private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
+  /** Context used by the cloud turn's HTTP MCP callbacks. */
+  private readonly activeToolContexts = new Map<string, ActiveToolContext>();
   /** Aborts the in-flight turn per session so a follow-up can preempt it. */
   private readonly turnAborts = new Map<string, AbortController>();
   /** Serializes turn admission per session (latest follow-up wins). */
@@ -318,6 +330,8 @@ export class SessionEngine {
   private readonly artifactsStore: ArtifactsStore;
   /** Serve-time resolved connections (see {@link setResolvedConnections}). */
   private resolvedConnections: EngineResolvedConnection[] = [];
+  /** Direct server-tool HTTP MCP transport exposed only to cloud turns. */
+  private cloudServerToolsConnection: ConnectionTransport | undefined;
   private readonly getCloudUsage: (
     sdkAgentId: string
   ) => Promise<CloudAgentUsage | undefined>;
@@ -369,7 +383,7 @@ export class SessionEngine {
     });
     this.artifactsStore = new ArtifactsStore({
       stateRoot: options.stateRoot,
-      storage: this.storage,
+      agentName: options.project.name,
       config: options.project.artifacts,
     });
     this.abCollector = new ABCollector(
@@ -427,6 +441,10 @@ export class SessionEngine {
     }
   }
 
+  setCloudServerToolsConnection(connection: ConnectionTransport): void {
+    this.cloudServerToolsConnection = connection;
+  }
+
   /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / Slack nudges). */
   get host(): HostContext {
     return {
@@ -1317,7 +1335,12 @@ export class SessionEngine {
           },
           signal
         );
-        outcome = await this.runner.runTurn(request);
+        this.activeToolContexts.set(sessionId, { record, turnId, emit });
+        try {
+          outcome = await this.runner.runTurn(request);
+        } finally {
+          this.activeToolContexts.delete(sessionId);
+        }
       } catch (error) {
         this.approvals.cancelSession(sessionId, "deny");
         outcome = { status: "error", errorMessage: describeError(error) };
@@ -1441,9 +1464,23 @@ export class SessionEngine {
     if (isFirstTurn) {
       if (runtime === "cloud") {
         // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies.
-        const preamble = buildAgentsMdContent(agent, { includeScripts: true });
-        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+        // including agent tool script bodies. On hosted deployments the
+        // shared memory journal is on the store mount — say where. When the
+        // turn carries the session-bound server-tool MCP endpoint, the
+        // preamble also catalogs server tools under that MCP server name;
+        // without it a model told to "use <server tool>" finds no script
+        // and improvises a local substitute instead of calling the host.
+        const preamble = buildAgentsMdContent(agent, {
+          includeScripts: true,
+          serverToolsMcpName:
+            this.cloudServerToolsConnection === undefined
+              ? undefined
+              : SERVER_TOOLS_MCP_SERVER_NAME,
+        });
+        const memorySection = isCursorHostedFilesAvailable()
+          ? `\n\n${buildCloudMemorySection(this.project.name)}`
+          : "";
+        turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
       } else if (instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
         // borrowed harness cwd, agent tool scripts live only in the durable
@@ -1469,7 +1506,7 @@ export class SessionEngine {
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
       customTools:
         runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {},
-      mcpServers: this.buildMcpServers(runtime),
+      mcpServers: this.buildMcpServers(runtime, record.sessionId),
       subagents: buildRunnerSubagents(agent),
       onUpdate,
       signal,
@@ -1500,23 +1537,107 @@ export class SessionEngine {
   }
 
   /**
-   * Authored + resolved MCP servers for a turn; skips `hostOnly`, and skips
-   * host-OAuth connections on cloud turns (their tokens live on this host).
+   * Connection names a cloud turn can only reach through the host connection
+   * bridge on the tool MCP endpoint: filtered account connections without a
+   * public bridge URL, and host-OAuth connections whose tokens live on this
+   * host. `hostOnly` names are never bridged — that flag means the model
+   * must not see the connection at all, on any runtime.
+   */
+  cloudBridgeableConnectionNames(): string[] {
+    const hostOnlyNames = new Set(
+      this.project.agent.connections
+        .filter((connection) => connection.hostOnly === true)
+        .map((connection) => connection.name)
+    );
+    const names: string[] = [];
+    for (const connection of this.project.agent.connections) {
+      if (
+        !hostOnlyNames.has(connection.name) &&
+        isHostOauthConnectionTransport(connection.transport)
+      ) {
+        names.push(connection.name);
+      }
+    }
+    for (const resolved of this.resolvedConnections) {
+      if (
+        !hostOnlyNames.has(resolved.name) &&
+        resolved.accountServersFilter !== undefined &&
+        resolved.cloudUrl === undefined
+      ) {
+        names.push(resolved.name);
+      }
+    }
+    return names;
+  }
+
+  /**
+   * True when cloud turns reach `name` through the host connection bridge —
+   * the gate the tool MCP endpoint applies before forwarding a bridge
+   * request to `host.mcp`, so `hostOnly` connections (and arbitrary names)
+   * stay unreachable from a VM.
+   */
+  isCloudBridgedConnection(name: string): boolean {
+    if (this.cloudServerToolsConnection === undefined) {
+      return false;
+    }
+    return this.cloudBridgeableConnectionNames().includes(name);
+  }
+
+  /**
+   * Session-bound transport for one host-bridged connection: the tool MCP
+   * endpoint with the connection named, so `tools/list` / `tools/call`
+   * forward to the host-side client (`host.mcp`) where the credential —
+   * account bridge secret or host OAuth token — actually lives.
+   */
+  private cloudBridgeTransport(
+    sessionId: string,
+    connectionName: string
+  ): ConnectionTransport | undefined {
+    const connection = this.cloudServerToolsConnection;
+    if (connection === undefined || !("url" in connection)) {
+      return undefined;
+    }
+    const url = new URL(connection.url);
+    url.searchParams.set("agentkitSessionId", sessionId);
+    url.searchParams.set("connection", connectionName);
+    return { ...connection, url: url.toString() };
+  }
+
+  /**
+   * Authored + resolved MCP servers for a turn. Skips `hostOnly`. On cloud
+   * turns, connections whose credential lives on this host — filtered
+   * account connections without a public bridge URL, host-OAuth servers —
+   * mount as host connection bridges over the tool MCP endpoint instead of
+   * being omitted or failing the turn closed.
    */
   private buildMcpServers(
-    runtime: "local" | "cloud"
+    runtime: "local" | "cloud",
+    sessionId?: string
   ): Record<string, ConnectionTransport> {
     const hostOnlyNames = new Set(
       this.project.agent.connections
         .filter((connection) => connection.hostOnly === true)
         .map((connection) => connection.name)
     );
+    const bridgedNames = new Set(
+      runtime === "cloud" &&
+        sessionId !== undefined &&
+        this.cloudServerToolsConnection !== undefined &&
+        "url" in this.cloudServerToolsConnection
+        ? this.cloudBridgeableConnectionNames()
+        : []
+    );
     assertCloudCanHonorAccountServersFilters({
       runtime,
       resolvedConnections: this.resolvedConnections.filter(
         (resolved) => !hostOnlyNames.has(resolved.name)
       ),
+      bridgedNames,
     });
+    const bridgeTransport = (name: string): ConnectionTransport | undefined =>
+      sessionId === undefined || !bridgedNames.has(name)
+        ? undefined
+        : this.cloudBridgeTransport(sessionId, name);
     const servers: Record<string, ConnectionTransport> = {};
     for (const connection of this.project.agent.connections) {
       if (hostOnlyNames.has(connection.name)) {
@@ -1527,12 +1648,17 @@ export class SessionEngine {
       }
       // A cloud VM cannot use a credential that lives on this host, and the
       // cloud API rejects the `oauth` key outright ("Unrecognized key(s) in
-      // object: 'oauth'"), which fails the whole turn. Omit it there; host
-      // tools (`ctx.host.mcp`) still reach the server over the host client.
+      // object: 'oauth'"), which fails the whole turn. Mount the host
+      // connection bridge instead when serve has a cloud tools URL; omit
+      // otherwise (host tools via `ctx.host.mcp` still reach the server).
       if (
         runtime === "cloud" &&
         isHostOauthConnectionTransport(connection.transport)
       ) {
+        const bridged = bridgeTransport(connection.name);
+        if (bridged !== undefined) {
+          servers[connection.name] = bridged;
+        }
         continue;
       }
       servers[connection.name] = connection.transport;
@@ -1543,6 +1669,13 @@ export class SessionEngine {
       }
       const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
       if (url === undefined) {
+        // Filtered account connections bridge through the host so the
+        // `servers` filter is honored; unfiltered ones keep their documented
+        // fallback to the account's native connectors on the VM.
+        const bridged = bridgeTransport(resolved.name);
+        if (bridged !== undefined) {
+          servers[resolved.name] = bridged;
+        }
         continue;
       }
       servers[resolved.name] = {
@@ -1550,6 +1683,27 @@ export class SessionEngine {
         headers: resolved.headers,
       };
     }
+    if (
+      runtime === "cloud" &&
+      sessionId !== undefined &&
+      this.cloudServerToolsConnection !== undefined &&
+      this.project.agent.tools.some((tool) => tool.execution === "server")
+    ) {
+      if (servers[SERVER_TOOLS_MCP_SERVER_NAME] !== undefined) {
+        throw new Error(
+          `MCP connection name "${SERVER_TOOLS_MCP_SERVER_NAME}" is reserved for authored server tools on cloud turns.`
+        );
+      }
+      const connection = this.cloudServerToolsConnection;
+      if ("url" in connection) {
+        const url = new URL(connection.url);
+        url.searchParams.set("agentkitSessionId", sessionId);
+        servers[SERVER_TOOLS_MCP_SERVER_NAME] = {
+          ...connection,
+          url: url.toString(),
+        };
+      }
+    }
     return servers;
   }
 
@@ -1571,96 +1725,144 @@ export class SessionEngine {
         description: tool.description,
         inputSchema: tool.inputSchema as SDKCustomTool["inputSchema"],
         execute: async (args, context) => {
-          const validation = validateToolInput(
-            tool.definition.inputSchema,
-            args
-          );
-          if (!validation.ok) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `Invalid input for tool "${tool.name}": ${validation.message}`,
-                },
-              ],
-              isError: true,
-            };
-          }
-          const toolCallId = context.toolCallId ?? newToolCallId(tool.name);
-          const toolCtx: ToolContext = {
-            toolCallId,
-            session: this.sessionInfo(record),
-            workspaceDir: this.harnessCwd(record),
-            stateRoot: this.stateRoot,
-            host: this.hostForSession(record.sessionId),
-            artifacts: this.artifactsApi({
-              sessionId: record.sessionId,
-              turnId,
-            }),
-            send: (channelId, message, sendOptions = {}) =>
-              this.send(channelId, message, {
-                ...sendOptions,
-                auth:
-                  sendOptions.auth !== undefined
-                    ? sendOptions.auth
-                    : record.auth,
-              }),
-            getSession: (channelId, sessionId) =>
-              this.getChannelSession(channelId, sessionId),
-          };
-          try {
-            const needsGate = await evaluateNeedsApproval(
-              tool.definition.needsApproval,
-              validation.value
-            );
-            if (needsGate) {
-              const decision = await this.parkForApproval({
-                sessionId: record.sessionId,
-                turnId,
-                callId: toolCallId,
-                toolName: tool.name,
-                args: validation.value,
-                emit,
-              });
-              if (decision === "deny") {
-                return {
-                  content: [
-                    {
-                      type: "text",
-                      text: `Tool "${tool.name}" was denied by a human approver.`,
-                    },
-                  ],
-                  isError: true,
-                };
-              }
-            }
-            const started = Date.now();
-            this.logger(`[session] tool ${tool.name} start`);
-            const result = await execute(validation.value as never, toolCtx);
-            this.logger(
-              `[session] tool ${tool.name} done (${Date.now() - started}ms)`
-            );
-            return normalizeToolResult(result);
-          } catch (error) {
-            this.logger(
-              `[session] tool ${tool.name} failed: ${describeError(error)}`
-            );
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: `Tool "${tool.name}" failed: ${describeError(error)}`,
-                },
-              ],
-              isError: true,
-            };
-          }
+          return this.executeServerTool({
+            tool,
+            input: args,
+            toolCallId: context.toolCallId,
+            record,
+            turnId,
+            emit,
+          });
         },
       };
     }
     return tools;
   }
 
+  /**
+   * True while `sessionId` has a turn in flight. The host connection bridge
+   * applies this before forwarding to `host.mcp` — the same window
+   * {@link callActiveServerTool} enforces for authored server tools — so an
+   * endpoint credential that outlives a turn (e.g. in a VM's MCP config)
+   * cannot reach host-credentialed connectors between turns.
+   */
+  hasActiveTurn(sessionId: string): boolean {
+    return this.activeToolContexts.has(sessionId);
+  }
+
+  async callActiveServerTool(
+    sessionId: string,
+    toolName: string,
+    input: unknown
+  ): Promise<SDKCustomToolResult> {
+    const active = this.activeToolContexts.get(sessionId);
+    if (active === undefined) {
+      return toolErrorResult(
+        `Session ${sessionId} has no active turn for tool "${toolName}".`
+      );
+    }
+    const tool = this.project.agent.tools.find(
+      (candidate) =>
+        candidate.name === toolName && candidate.execution === "server"
+    );
+    if (tool === undefined) {
+      return toolErrorResult(`Unknown server tool "${toolName}".`);
+    }
+    const toolCallId = newToolCallId(toolName);
+    this.logger(
+      `[session] cloud HTTP MCP tool ${toolName} dispatch (${sessionId}, ${toolCallId})`
+    );
+    const result = await this.executeServerTool({
+      tool,
+      input,
+      toolCallId,
+      record: active.record,
+      turnId: active.turnId,
+      emit: active.emit,
+    });
+    this.logger(
+      `[session] cloud HTTP MCP tool ${toolName} complete (${sessionId}, ${toolCallId}, isError=${isErrorEnvelope(result)})`
+    );
+    return result;
+  }
+
+  private async executeServerTool(args: {
+    tool: ResolvedAgent["tools"][number];
+    input: unknown;
+    toolCallId?: string;
+    record: SessionRecord;
+    turnId: string;
+    emit: (payload: SessionEventPayload) => void;
+  }): Promise<SDKCustomToolResult> {
+    const execute = args.tool.definition.execute;
+    if (args.tool.execution !== "server" || typeof execute !== "function") {
+      return toolErrorResult(`Tool "${args.tool.name}" is not a server tool.`);
+    }
+    const validation = validateToolInput(
+      args.tool.definition.inputSchema,
+      args.input
+    );
+    if (!validation.ok) {
+      return toolErrorResult(
+        `Invalid input for tool "${args.tool.name}": ${validation.message}`
+      );
+    }
+    const toolCallId = args.toolCallId ?? newToolCallId(args.tool.name);
+    const toolCtx: ToolContext = {
+      toolCallId,
+      session: this.sessionInfo(args.record),
+      workspaceDir: this.harnessCwd(args.record),
+      stateRoot: this.stateRoot,
+      host: this.hostForSession(args.record.sessionId),
+      artifacts: this.artifactsApi({
+        sessionId: args.record.sessionId,
+        turnId: args.turnId,
+      }),
+      send: (channelId, message, sendOptions = {}) =>
+        this.send(channelId, message, {
+          ...sendOptions,
+          auth: sendOptions.auth ?? args.record.auth,
+        }),
+      getSession: (channelId, sessionId) =>
+        this.getChannelSession(channelId, sessionId),
+    };
+    try {
+      const needsGate = await evaluateNeedsApproval(
+        args.tool.definition.needsApproval,
+        validation.value
+      );
+      if (needsGate) {
+        const decision = await this.parkForApproval({
+          sessionId: args.record.sessionId,
+          turnId: args.turnId,
+          callId: toolCallId,
+          toolName: args.tool.name,
+          args: validation.value,
+          emit: args.emit,
+        });
+        if (decision === "deny") {
+          return toolErrorResult(
+            `Tool "${args.tool.name}" was denied by a human approver.`
+          );
+        }
+      }
+      const started = Date.now();
+      this.logger(`[session] tool ${args.tool.name} start`);
+      const result = await execute(validation.value as never, toolCtx);
+      this.logger(
+        `[session] tool ${args.tool.name} done (${Date.now() - started}ms)`
+      );
+      return normalizeToolResult(result);
+    } catch (error) {
+      this.logger(
+        `[session] tool ${args.tool.name} failed: ${describeError(error)}`
+      );
+      return toolErrorResult(
+        `Tool "${args.tool.name}" failed: ${describeError(error)}`
+      );
+    }
+  }
+
   /**
    * Park a server-tool call until a human approves or denies. Emits
    * `action.approval_requested` / `action.approval_resolved` on the
@@ -2166,15 +2368,48 @@ export class SessionEngine {
     if (options?.includeAll === true) {
       return records;
     }
+    const owned = await this.ownedSessionIds(caller);
+    return records.filter(
+      (record) => record.sessionId !== undefined && owned.has(record.sessionId)
+    );
+  }
+
+  /**
+   * One artifact's file/blob payload for `GET /v1/artifacts/:id/content`.
+   * Same visibility rule as {@link listArtifacts}. Undefined when the
+   * artifact is missing, invisible to the caller, or carries no payload.
+   */
+  async getArtifactContent(
+    caller: AuthContext | null,
+    id: string,
+    options?: { includeAll?: boolean }
+  ): Promise<{ record: ArtifactRecord; body: Uint8Array } | undefined> {
+    const record = await this.artifactsStore.get(id);
+    if (record === undefined || record.content === undefined) {
+      return undefined;
+    }
+    if (options?.includeAll !== true) {
+      if (record.sessionId === undefined) {
+        return undefined;
+      }
+      const owned = await this.ownedSessionIds(caller);
+      if (!owned.has(record.sessionId)) {
+        return undefined;
+      }
+    }
+    const body = await this.artifactsStore.getContent(id);
+    return body === undefined ? undefined : { record, body };
+  }
+
+  private async ownedSessionIds(
+    caller: AuthContext | null
+  ): Promise<Set<string>> {
     const sessions = await this.sessions.list();
-    const owned = new Set(
+    return new Set(
       sessions
         .filter((record) => samePrincipal(record.auth, caller))
         .map((record) => record.sessionId)
     );
-    return records.filter(
-      (record) => record.sessionId !== undefined && owned.has(record.sessionId)
-    );
   }
 
   /**
@@ -2715,7 +2950,7 @@ export class SessionEngine {
   }
 
   private async runBulkRestore(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     policy: { maxSessions: number; maxAgeMs: number; maxTotalBytes: number }
   ): Promise<void> {
     const loaded = await storage.listSessions();
@@ -2876,7 +3111,7 @@ export class SessionEngine {
   }
 
   private async loadAndMaterializeByContinuation(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     channelId: string,
     continuationKey: string
   ): Promise<SessionRecord | undefined> {
@@ -2892,7 +3127,7 @@ export class SessionEngine {
   }
 
   private async loadAndMaterializeById(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     sessionId: string
   ): Promise<SessionRecord | undefined> {
     const record = await storage.getSessionById(sessionId);
@@ -2998,6 +3233,13 @@ function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function toolErrorResult(message: string): SDKCustomToolResult {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
 async function defaultGetCloudUsage(
   sdkAgentId: string
 ): Promise<CloudAgentUsage | undefined> {