@cursor/july 0.1.92 → 0.1.94

package/src/internal/session-engine.ts

@@ -49,6 +49,7 @@ import {
   type ConnectionTransport,
   DEFAULT_MODEL,
   DIRECT_TOOL_CALL_CHANNEL_ID,
+  type DiscoveredTool,
   type HookHandler,
   type HostContext,
   type HttpChannelDefinition,
@@ -117,6 +118,7 @@ import {
   newContinuationKey,
   newSessionId,
   newToolCallId,
+  parseContinuationToken,
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
@@ -136,7 +138,7 @@ import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
-import { decideToolCall } from "./tool-policy.js";
+import { decideToolCall, resolveEffect } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -197,6 +199,30 @@ export class ToolNotDirectlyCallableError extends Error {
   }
 }
 
+export class InvalidContinuationTokenError extends Error {
+  constructor(detail: string) {
+    super(`Invalid continuation token: ${detail}`);
+    this.name = "InvalidContinuationTokenError";
+  }
+}
+
+/**
+ * A session-bound direct call whose harness cwd cannot be materialized and
+ * whose effect is not read: a write tool may rely on ctx.workspaceDir being
+ * the real session workspace, so it fails typed instead of silently running
+ * in a scratch directory.
+ */
+export class WorkspaceUnavailableError extends Error {
+  constructor(toolName: string, cause: unknown) {
+    super(
+      `Session workspace unavailable for tool "${toolName}": ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`
+    );
+    this.name = "WorkspaceUnavailableError";
+  }
+}
+
 export class ToolInputError extends Error {
   constructor(args: { toolName: string; detail: string }) {
     super(`Invalid input for tool "${args.toolName}": ${args.detail}`);
@@ -283,6 +309,11 @@ interface ActiveToolContext {
 
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
+  /**
+   * Hosted v2 control-plane identity. Private host plumbing only: channel
+   * authors cannot choose a session id through the public SendMessageOptions.
+   */
+  hostedSessionId?: string;
 }
 
 interface CoalescedQueuedTurn {
@@ -469,7 +500,10 @@ export class SessionEngine {
     // resolves them; the host-side MCP registry starts with the concrete
     // connections and gains the rest via setResolvedConnections.
     this.mcpHost = new McpHost(
-      options.project.agent.connections.filter(
+      [
+        ...options.project.agent.connections,
+        ...(options.project.agent.hostConnections ?? []),
+      ].filter(
         (connection) => !isSymbolicConnectionTransport(connection.transport)
       )
     );
@@ -816,6 +850,14 @@ export class SessionEngine {
     }
 
     if (existing !== undefined) {
+      if (
+        sendOptions.hostedSessionId !== undefined &&
+        existing.sessionId !== sendOptions.hostedSessionId
+      ) {
+        throw new V2EngineError(
+          `v2: continuation belongs to session ${existing.sessionId}, not ${sendOptions.hostedSessionId}`
+        );
+      }
       if (!samePrincipal(existing.auth, auth)) {
         throw new SessionAuthError(existing.sessionId);
       }
@@ -886,11 +928,22 @@ export class SessionEngine {
       );
     }
 
+    if (sendOptions.hostedSessionId !== undefined) {
+      const collision = await this.getOrRestoreSession(
+        sendOptions.hostedSessionId
+      );
+      if (collision !== undefined) {
+        throw new V2EngineError(
+          `v2: hosted session id ${sendOptions.hostedSessionId} already belongs to another mailbox`
+        );
+      }
+    }
+
     const now = new Date().toISOString();
     const channelState = this.initialChannelState(channelId, sendOptions.state);
     const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
     let record: SessionRecord = {
-      sessionId: newSessionId(),
+      sessionId: sendOptions.hostedSessionId ?? newSessionId(),
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
@@ -2124,27 +2177,17 @@ export class SessionEngine {
    * 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.
+   * host.
    */
   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)
-      ) {
+      if (isHostOauthConnectionTransport(connection.transport)) {
         names.push(connection.name);
       }
     }
     for (const resolved of this.resolvedConnections) {
       if (
-        !hostOnlyNames.has(resolved.name) &&
         resolved.accountServersFilter !== undefined &&
         resolved.cloudUrl === undefined
       ) {
@@ -2157,8 +2200,7 @@ export class SessionEngine {
   /**
    * 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.
+   * request to `host.mcp`, so arbitrary names stay unreachable from a VM.
    */
   isCloudBridgedConnection(name: string): boolean {
     if (this.cloudServerToolsConnection === undefined) {
@@ -2188,10 +2230,11 @@ export class SessionEngine {
   }
 
   /**
-   * 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
+   * Authored + resolved MCP servers for a turn. Skips advertised
+   * connections (those surface as named server tools). 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(
@@ -2205,16 +2248,17 @@ export class SessionEngine {
       return {};
     }
     // Advertised connections surface as named server tools instead of an
-    // attached MCP server (each tool appears exactly once), so they are
-    // excluded here alongside hostOnly.
-    const hostOnlyNames = new Set(
+    // attached MCP server (each tool appears exactly once).
+    const advertisedNames = new Set(
       this.project.agent.connections
-        .filter(
-          (connection) =>
-            connection.hostOnly === true || connection.advertiseTools === true
-        )
+        .filter((connection) => connection.advertiseTools === true)
         .map((connection) => connection.name)
     );
+    const hostConnectionNames = new Set(
+      (this.project.agent.hostConnections ?? []).map(
+        (connection) => connection.name
+      )
+    );
     const bridgedNames = new Set(
       runtime === "cloud" &&
         sessionId !== undefined &&
@@ -2226,7 +2270,9 @@ export class SessionEngine {
     assertCloudCanHonorAccountServersFilters({
       runtime,
       resolvedConnections: this.resolvedConnections.filter(
-        (resolved) => !hostOnlyNames.has(resolved.name)
+        (resolved) =>
+          !advertisedNames.has(resolved.name) &&
+          !hostConnectionNames.has(resolved.name)
       ),
       bridgedNames,
     });
@@ -2236,7 +2282,10 @@ export class SessionEngine {
         : this.cloudBridgeTransport(sessionId, name);
     const servers: Record<string, ConnectionTransport> = {};
     for (const connection of this.project.agent.connections) {
-      if (hostOnlyNames.has(connection.name)) {
+      if (
+        advertisedNames.has(connection.name) ||
+        hostConnectionNames.has(connection.name)
+      ) {
         continue;
       }
       if (isSymbolicConnectionTransport(connection.transport)) {
@@ -2277,7 +2326,10 @@ export class SessionEngine {
       servers[connection.name] = connection.transport;
     }
     for (const resolved of this.resolvedConnections) {
-      if (hostOnlyNames.has(resolved.name)) {
+      if (
+        advertisedNames.has(resolved.name) ||
+        hostConnectionNames.has(resolved.name)
+      ) {
         continue;
       }
       const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
@@ -2322,16 +2374,14 @@ export class SessionEngine {
 
   /**
    * True when a connection with per-session `auth` attaches to the model
-   * (not `hostOnly`, not advertised). These turns set
+   * (not advertised). These turns set
    * {@link RunnerTurnRequest.perSendMcpServers} so the evaluated headers
    * ride every send instead of being pinned on the cached agent handle.
    */
   private hasAttachedAuthedConnections(): boolean {
     return this.project.agent.connections.some(
       (connection) =>
-        connection.auth !== undefined &&
-        connection.hostOnly !== true &&
-        connection.advertiseTools !== true
+        connection.auth !== undefined && connection.advertiseTools !== true
     );
   }
 
@@ -2347,9 +2397,7 @@ export class SessionEngine {
   ): Promise<ReadonlyMap<string, Record<string, string>> | undefined> {
     const authed = this.project.agent.connections.filter(
       (connection) =>
-        connection.auth !== undefined &&
-        connection.hostOnly !== true &&
-        connection.advertiseTools !== true
+        connection.auth !== undefined && connection.advertiseTools !== true
     );
     if (authed.length === 0) {
       return undefined;
@@ -2759,12 +2807,168 @@ export class SessionEngine {
    * with the same `{ content, isError }` envelope the model would see, not
    * an exception.
    */
+  /**
+   * The session identity a direct call (or catalog listing) runs under:
+   * an explicit sessionId, a continuation token resolved to a live (or
+   * restorable) session with the same owner/busy checks a sessionId call
+   * gets, or — when neither maps to a session — a synthetic identity
+   * carrying the token's channel id and continuation key so binding
+   * resolvers (e.g. VFS mounts) can still serve the call.
+   */
+  private async resolveDirectCallIdentity(
+    callId: string,
+    options: Pick<CallToolOptions, "auth" | "sessionId" | "continuationToken">
+  ): Promise<{
+    record: SessionRecord | undefined;
+    session: SessionInfo;
+    workspaceDir: string;
+    scratchDir: string | undefined;
+  }> {
+    if (
+      options.sessionId !== undefined &&
+      options.continuationToken !== undefined
+    ) {
+      throw new InvalidContinuationTokenError(
+        "mutually exclusive with sessionId — a real session already carries its own continuation key"
+      );
+    }
+    const auth = options.auth ?? null;
+    let record: SessionRecord | undefined;
+    let continuation: { channelId: string; key: string } | null = null;
+    if (options.sessionId !== undefined) {
+      record = await this.sessions.get(options.sessionId);
+      if (record === undefined) {
+        throw new UnknownSessionError(options.sessionId);
+      }
+    } else if (options.continuationToken !== undefined) {
+      continuation = parseContinuationToken(options.continuationToken);
+      if (continuation === null) {
+        throw new InvalidContinuationTokenError(
+          `expected "<channelId>:<key>" (as /v1/sessions lists it), got "${options.continuationToken}"`
+        );
+      }
+      // A token that maps to a live (or restorable) session takes the
+      // session path: same owner check, same turn serialization, same
+      // event recording as an explicit sessionId. Skipping those just
+      // because the caller addressed the session by token would fail open.
+      record =
+        (await this.sessions.findByContinuation(
+          continuation.channelId,
+          continuation.key
+        )) ??
+        (await this.restoreSessionByContinuation(
+          continuation.channelId,
+          continuation.key
+        ));
+      if (record !== undefined && !samePrincipal(record.auth, auth)) {
+        throw new SessionAuthError(record.sessionId);
+      }
+    }
+    if (record !== undefined) {
+      // Direct calls respect the same serialization as follow-up sends: a
+      // running model turn owns the session workspace and event stream.
+      if (
+        this.activeTurns.has(record.sessionId) ||
+        this.pendingTurns.has(record.sessionId)
+      ) {
+        throw new SessionBusyError(record.sessionId);
+      }
+      return {
+        record,
+        session: this.sessionInfo(record),
+        workspaceDir: this.harnessCwd(record),
+        scratchDir: undefined,
+      };
+    }
+    // No session behind the token (or no token at all): a synthetic
+    // session carries the token's channel id and key, so binding resolvers
+    // keyed on the continuation key (e.g. VFS mounts) can serve the call
+    // with no live session. The workspace stays scratch and nothing is
+    // recorded on a session event stream.
+    const scratchDir = join(this.stateRoot, "tool-calls", callId);
+    return {
+      record: undefined,
+      session: {
+        id: callId,
+        channelId: continuation?.channelId ?? DIRECT_TOOL_CALL_CHANNEL_ID,
+        mode: "task",
+        continuationKey: continuation?.key,
+        auth,
+      },
+      workspaceDir: scratchDir,
+      scratchDir,
+    };
+  }
+
+  /**
+   * The live tool catalog for one session identity: authored server tools
+   * plus the advertised passthroughs a turn under the same identity would
+   * see, under their model-facing names. A connection whose listing fails
+   * is skipped and reported in `connectionErrors` — the inspection surface
+   * degrades legibly instead of hiding every other tool behind one broken
+   * connector.
+   */
+  async listCatalogTools(
+    options: Pick<
+      CallToolOptions,
+      "auth" | "sessionId" | "continuationToken"
+    > = {}
+  ): Promise<{
+    tools: DiscoveredTool[];
+    connectionErrors: Array<{ connection: string; message: string }>;
+  }> {
+    const { session } = await this.resolveDirectCallIdentity(
+      newToolCallId("catalog"),
+      options
+    );
+    const connectionErrors: Array<{ connection: string; message: string }> = [];
+    const advertised = await resolveAdvertisedTools({
+      agent: this.project.agent,
+      session,
+      hostMcp: this.mcpHost,
+      onConnectionError: (connection, error) => {
+        connectionErrors.push({
+          connection,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      },
+    });
+    return {
+      tools: [...this.project.agent.tools, ...advertised],
+      connectionErrors,
+    };
+  }
+
   async callTool(
     toolName: string,
     input: unknown = {},
     options: CallToolOptions = {}
   ): Promise<ToolCallOutcome> {
-    const tool = this.project.agent.tools.find((t) => t.name === toolName);
+    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
+    // needs the same identity the call runs under.
+    const identity = await this.resolveDirectCallIdentity(callId, options);
+    const record = identity.record;
+    const session = identity.session;
+    let workspaceDir = identity.workspaceDir;
+    let scratchDir = identity.scratchDir;
+    let tool = this.project.agent.tools.find((t) => t.name === toolName);
+    if (
+      tool === undefined &&
+      this.project.agent.connections.some((c) => c.advertiseTools === true)
+    ) {
+      // Advertised passthroughs are ordinary server tools in the session's
+      // namespace; resolve the live listing so direct calls address them by
+      // the same model-facing name a turn would. A listing failure fails
+      // the call closed, like it fails a turn.
+      const advertised = await resolveAdvertisedTools({
+        agent: this.project.agent,
+        session,
+        hostMcp: this.mcpHost,
+      });
+      tool = advertised.find((t) => t.name === toolName);
+    }
     if (tool === undefined) {
       throw new UnknownToolError(
         toolName,
@@ -2781,47 +2985,51 @@ export class SessionEngine {
     if (!validation.ok) {
       throw new ToolInputError({ toolName, detail: validation.message });
     }
-
-    const callId = newToolCallId(toolName);
-    const auth = options.auth ?? null;
-    let record: SessionRecord | undefined;
-    let session: SessionInfo;
-    let workspaceDir: string;
-    let scratchDir: string | undefined;
-    if (options.sessionId !== undefined) {
-      record = await this.sessions.get(options.sessionId);
+    let workspaceUnavailable = false;
+    try {
+      await mkdir(workspaceDir, { recursive: true });
+    } catch (error) {
       if (record === undefined) {
-        throw new UnknownSessionError(options.sessionId);
+        throw error;
       }
-      // Direct calls respect the same serialization as follow-up sends: a
-      // running model turn owns the session workspace and event stream.
-      if (
-        this.activeTurns.has(record.sessionId) ||
-        this.pendingTurns.has(record.sessionId)
-      ) {
-        throw new SessionBusyError(record.sessionId);
+      // A session's harness cwd can be a path the serving process cannot
+      // create (e.g. an absolute `local.cwd` like /repo on a hosted pod
+      // where the sandboxed harness would have made it). Read-effect calls
+      // fall back to a scratch workspace instead of failing: tools that
+      // resolve their state from the session identity (VFS mounts) never
+      // touch ctx.workspaceDir. Advertised passthroughs are relocatable by
+      // construction: their execute body forwards to the connection and
+      // never reads the workspace. A write (or undeclared, which resolves
+      // to write) authored tool may rely on ctx.workspaceDir being the
+      // real session workspace, so silently relocating it is not safe —
+      // fail typed instead.
+      const relocatable =
+        tool.advertised === true ||
+        resolveEffect(tool.definition.effect, validation.value) === "read";
+      if (!relocatable) {
+        throw new WorkspaceUnavailableError(toolName, error);
       }
-      session = this.sessionInfo(record);
-      workspaceDir = this.harnessCwd(record);
-    } else {
-      session = {
-        id: callId,
-        channelId: DIRECT_TOOL_CALL_CHANNEL_ID,
-        mode: "task",
-        auth,
-      };
+      this.logger(
+        `[session] tool ${toolName} workspace unavailable (direct ${callId}); using scratch: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
       scratchDir = join(this.stateRoot, "tool-calls", callId);
       workspaceDir = scratchDir;
+      workspaceUnavailable = true;
+      await mkdir(workspaceDir, { recursive: true });
     }
-    await mkdir(workspaceDir, { recursive: true });
     // Match what a model turn would see: session workspaces get the same
     // scaffold as executeTurn (seeds only before the first turn); scratch
     // workspaces are materialized fresh.
     await materializeWorkspace({
       agent: this.project.agent,
       workspaceDir:
-        record === undefined ? workspaceDir : this.scaffoldDir(record),
-      seed: record === undefined || record.turnCount === 0,
+        record === undefined || workspaceUnavailable
+          ? workspaceDir
+          : this.scaffoldDir(record),
+      seed:
+        record === undefined || workspaceUnavailable || record.turnCount === 0,
       stateRoot: this.stateRoot,
     });
 
@@ -2957,8 +3165,9 @@ export class SessionEngine {
       isError,
       result,
       durationMs,
-      ...(errorMessage === undefined ? {} : { errorMessage }),
-      ...(record === undefined ? {} : { sessionId: record.sessionId }),
+      errorMessage,
+      sessionId: record?.sessionId,
+      scratchWorkspace: workspaceUnavailable ? true : undefined,
     };
   }
 

package/src/internal/shallow-clone.ts

@@ -155,8 +155,14 @@ export type CommitRangeDiff =
 export async function tryDiffCommitRange(args: {
   /** Existing checkout to run git in (see {@link createShallowPrCheckout}). */
   checkoutDir: string;
-  /** The checkout's clone target; supplies the remote's ref + auth conventions. */
-  target: ScmCloneTarget;
+  /**
+   * The checkout's clone target; supplies the remote's ref + auth
+   * conventions. Omit for SCMs without a clone target (e.g. Origin, where
+   * the host checkout is the reviewed repo): the diff then relies on
+   * commits already present locally, plus one uncredentialed fetch-by-SHA
+   * through the checkout's own remote.
+   */
+  target?: ScmCloneTarget | undefined;
   from: string;
   to: string;
   /** Restrict the diff to one path when set. */
@@ -171,10 +177,13 @@ export async function tryDiffCommitRange(args: {
         "Could not compute a reliable diff because a commit SHA was not a full 40-character SHA.",
     };
   }
-  const credential = cloneCredential(
-    args.target,
-    args.auth ?? defaultCloneAuth(args.target)
-  );
+  const credential =
+    args.target === undefined
+      ? undefined
+      : cloneCredential(
+          args.target,
+          args.auth ?? defaultCloneAuth(args.target)
+        );
   for (const sha of [args.from, args.to]) {
     if (
       !(await ensureCommitFetched(
@@ -222,7 +231,7 @@ function isFullCommitSha(value: string): boolean {
 async function ensureCommitFetched(
   checkoutDir: string,
   sha: string,
-  target: ScmCloneTarget,
+  target: ScmCloneTarget | undefined,
   credential: GitCredential | undefined
 ): Promise<boolean> {
   if ((await revParse(checkoutDir, sha)) !== undefined) {
@@ -231,15 +240,20 @@ async function ensureCommitFetched(
   const attempts = [
     [...FETCH_ARGS, sha],
     // Deeper history on the PR head ref: the older end of an inter-run range
-    // is usually an ancestor of the tip rather than the tip itself.
-    [
-      "fetch",
-      "--depth=200",
-      "--no-tags",
-      "--quiet",
-      "origin",
-      target.prHeadRef,
-    ],
+    // is usually an ancestor of the tip rather than the tip itself. Only
+    // possible when the clone target (and so the PR head ref) is known.
+    ...(target === undefined
+      ? []
+      : [
+          [
+            "fetch",
+            "--depth=200",
+            "--no-tags",
+            "--quiet",
+            "origin",
+            target.prHeadRef,
+          ],
+        ]),
   ];
   for (const attempt of attempts) {
     try {