@cursor/july 0.1.93 → 0.1.95

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,
@@ -112,11 +113,16 @@ import {
   createHostSlackClient,
   type HostPlatforms,
 } from "./host-platforms.js";
+import {
+  HostedAdmissionLocalSendError,
+  isDuringHostedAdmission,
+} from "./hosted-admission-context.js";
 import {
   formatContinuationToken,
   newContinuationKey,
   newSessionId,
   newToolCallId,
+  parseContinuationToken,
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
@@ -136,7 +142,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 +203,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}`);
@@ -439,6 +469,7 @@ export class SessionEngine {
     // for why the choice does not belong to the agent author.
     const frameworkStorage = selectFrameworkStorageDefinition({
       authored: options.project.storage,
+      architecture: options.project.agent.architecture,
     });
     this.storage =
       frameworkStorage === undefined
@@ -474,7 +505,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)
       )
     );
@@ -782,6 +816,13 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
+    if (isDuringHostedAdmission()) {
+      // Only sends that bypassed the admission capture stub (typically a
+      // startup-captured `onStart` send) reach the engine inside the
+      // admission window; running one would leak an invisible local session
+      // on a sessionless pod.
+      throw new HostedAdmissionLocalSendError();
+    }
     const identity =
       channelId === HTTP_CHANNEL_ID
         ? httpContinuationIdentity(this.project.httpChannel)
@@ -2148,27 +2189,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
       ) {
@@ -2181,8 +2212,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) {
@@ -2212,10 +2242,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(
@@ -2229,16 +2260,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 &&
@@ -2250,7 +2282,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,
     });
@@ -2260,7 +2294,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)) {
@@ -2301,7 +2338,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;
@@ -2346,16 +2386,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
     );
   }
 
@@ -2371,9 +2409,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;
@@ -2783,12 +2819,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,
@@ -2805,47 +2997,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,
     });
 
@@ -2981,8 +3177,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/tool-catalog.ts

@@ -0,0 +1,106 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+
+import type {
+  DiscoveredTool,
+  JsonSchemaObject,
+  ToolEffect,
+  ToolExecution,
+} from "../types.js";
+
+/**
+ * Display names for the well-known tool names that do not come from MCP
+ * (authored tools have no title field; adding one to `defineTool` for a
+ * presentation concern is not worth the authoring surface).
+ */
+const WELL_KNOWN_TOOL_TITLES: Readonly<Record<string, string>> = {
+  diff: "Show change diffs",
+  glob: "Find files by pattern",
+  grep: "Search file contents",
+  ls: "List a directory",
+  read: "Read a file",
+  search: "Search with a typed query",
+  write: "Write a file",
+};
+
+function catalogTitle(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised === true) {
+    return tool.annotations?.title;
+  }
+  return WELL_KNOWN_TOOL_TITLES[tool.name];
+}
+
+/**
+ * Sand connector identifiers scope the connector name by owner
+ * (`dashboard-team-<id>-Buildkite`, `dashboard-<Name>`, `user-<Name>`);
+ * the suffix is the human-meaningful name.
+ */
+const CONNECTOR_SCOPE_PREFIX = /^(?:dashboard-team-\d+-|dashboard-|user-)/;
+
+/**
+ * Where a tool comes from, for humans: the upstream connector/plugin name
+ * when the tool declares one (the reserved `__conn__` selector's values
+ * name it), the connection name otherwise. One aggregating connection
+ * (e.g. a tenant `plugins` endpoint) hosts tools from several connectors,
+ * and "plugins" tells an operator nothing — "Buildkite" does.
+ */
+function catalogSource(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised !== true) {
+    return undefined;
+  }
+  const properties = tool.inputSchema.properties as
+    | Record<string, { enum?: unknown[] } | undefined>
+    | undefined;
+  const first = properties?.__conn__?.enum?.[0];
+  if (typeof first === "string" && first !== "") {
+    return first.replace(CONNECTOR_SCOPE_PREFIX, "");
+  }
+  return tool.connection;
+}
+
+/** Light listing entry: identifiers and curated display data only. */
+export interface CatalogListEntry {
+  name: string;
+  title?: string;
+  /** Connection name for advertised MCP tools; absent for authored tools. */
+  source?: string;
+}
+
+/** Full description behind `GET /v1/tools/:name`. */
+export interface CatalogDetailEntry extends CatalogListEntry {
+  description: string;
+  execution: ToolExecution;
+  needsApproval: boolean;
+  effect?: ToolEffect | "dynamic";
+  inputSchema: JsonSchemaObject;
+  outputSchema?: JsonSchemaObject;
+}
+
+export function catalogListEntry(tool: DiscoveredTool): CatalogListEntry {
+  return {
+    name: tool.name,
+    title: catalogTitle(tool),
+    source: catalogSource(tool),
+  };
+}
+
+export function catalogDetailEntry(tool: DiscoveredTool): CatalogDetailEntry {
+  return {
+    ...catalogListEntry(tool),
+    description: tool.description,
+    execution: tool.execution,
+    needsApproval: tool.needsApproval,
+    effect: tool.effect,
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+  };
+}

package/src/storage-backends/cursor-hosted.ts

@@ -74,8 +74,13 @@ export interface CursorHostedStorageOptions {
    * `https://api.cursor.com`).
    */
   baseUrl?: string;
-  /** Bearer credential (default: `CURSOR_API_KEY`). */
-  apiKey?: string;
+  /**
+   * Bearer credential (default: `CURSOR_API_KEY`). A function is
+   * re-resolved on every call: hosted freeze snapshots listen unsigned and
+   * bind the key file after serve start, so a value captured at construct
+   * time would be permanently absent.
+   */
+  apiKey?: string | (() => string | undefined);
   /** Injected for tests. */
   fetch?: typeof fetch;
 }
@@ -180,7 +185,9 @@ function toCasResult(response: KvCasResponse): KvCasResult {
 }
 
 function resolveApiKey(options: CursorHostedStorageOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  const configured =
+    typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(
       "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"