@cursor/july 0.1.96 → 0.1.99

package/src/internal/mcp-oauth-persist.ts

@@ -0,0 +1,127 @@
+/**
+ * Deployment-secret upsert for host MCP OAuth (`mcp oauth --store` and
+ * hosted Connect). File writes stay on FileMcpOAuthStore / the OAuth
+ * provider. Resolve the `--store` client at persist time so v2 freeze
+ * bind can drop the key after listen.
+ */
+
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR } from "../storage-backends/cursor-hosted.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "./cursor/credentials.js";
+import {
+  AgentServeDeployClient,
+  parseAgentServeMcpGatewayUrl,
+} from "./deploy-client.js";
+import { mcpOauthSecretNames } from "./mcp-oauth.js";
+
+export type McpOauthSecretsClient = {
+  setSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]>;
+};
+
+export type McpOauthSecretsTarget = {
+  client: McpOauthSecretsClient;
+  teamId: number;
+  slug: string;
+};
+
+function mcpOauthSecretsPayload(args: {
+  connection: string;
+  tokens: OAuthTokens;
+  clientId?: string;
+}): Array<{ name: string; value: string }> {
+  const names = mcpOauthSecretNames(args.connection);
+  const secrets: Array<{ name: string; value: string }> = [
+    { name: names.accessToken, value: args.tokens.access_token },
+  ];
+  const refresh = args.tokens.refresh_token?.trim();
+  if (refresh !== undefined && refresh !== "") {
+    secrets.push({ name: names.refreshToken, value: refresh });
+  }
+  const clientId = args.clientId?.trim();
+  if (clientId !== undefined && clientId !== "") {
+    secrets.push({ name: names.clientId, value: clientId });
+  }
+  return secrets;
+}
+
+export async function upsertHostMcpOauthSecrets(args: {
+  connection: string;
+  tokens: OAuthTokens;
+  clientId?: string;
+  target: McpOauthSecretsTarget;
+}): Promise<string[]> {
+  const payload = mcpOauthSecretsPayload(args);
+  if (payload.length === 0) {
+    return [];
+  }
+  return await args.target.client.setSecrets({
+    teamId: args.target.teamId,
+    slug: args.target.slug,
+    secrets: payload,
+  });
+}
+
+export type ResolveHostedMcpOauthSecretsArgs = {
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  cloudToolsUrl?: string;
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * Bind the CLI `--store` client when this process is a hosted engine
+ * (`AGENT_SERVE_DEPLOYMENT_ID`) and a live API key is present.
+ * Self-hosted / no deployment / unsigned: undefined.
+ */
+export function resolveHostedMcpOauthSecretsTarget(
+  args: ResolveHostedMcpOauthSecretsArgs = {}
+): McpOauthSecretsTarget | undefined {
+  const env = args.env ?? process.env;
+  const deploymentId = env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR]?.trim();
+  if (deploymentId === undefined || deploymentId === "") {
+    return undefined;
+  }
+  const resolved = resolveApiKeySync(
+    args.apiKey === undefined ? undefined : { apiKey: args.apiKey }
+  );
+  if (resolved === undefined) {
+    return undefined;
+  }
+  const fromUrl =
+    args.cloudToolsUrl === undefined
+      ? undefined
+      : parseAgentServeMcpGatewayUrl(args.cloudToolsUrl);
+  const slug =
+    args.slug !== undefined && args.slug !== "" ? args.slug : fromUrl?.slug;
+  const teamId = parseTeamId(args.team) ?? fromUrl?.teamId;
+  if (slug === undefined || teamId === undefined) {
+    return undefined;
+  }
+  return {
+    client: new AgentServeDeployClient({
+      backendUrl: cursorExternalApiUrl(),
+      apiKey: resolved.apiKey,
+    }),
+    teamId,
+    slug,
+  };
+}
+
+function parseTeamId(team: string | undefined): number | undefined {
+  if (team === undefined || team === "") {
+    return undefined;
+  }
+  const teamId = Number.parseInt(team, 10);
+  if (!Number.isInteger(teamId) || teamId <= 0) {
+    return undefined;
+  }
+  return teamId;
+}

package/src/internal/mcp-oauth.ts

@@ -411,13 +411,25 @@ export class HostMcpOAuthProvider implements OAuthClientProvider {
   }
 }
 
+function clientForRedirect(
+  info: OAuthClientInformationFull | undefined,
+  redirectUrl: string
+): OAuthClientInformationFull | undefined {
+  if (info === undefined || !info.redirect_uris.includes(redirectUrl)) {
+    return undefined;
+  }
+  return info;
+}
+
 export async function createHostMcpOAuthProvider(args: {
   identifier: string;
   resourceUrl: string;
   store?: FileMcpOAuthStore;
   onRedirect?: (url: URL) => void;
+  redirectUrl?: string;
 }): Promise<HostMcpOAuthProvider> {
   const store = args.store ?? new FileMcpOAuthStore();
+  const redirectUrl = args.redirectUrl ?? MCP_OAUTH_CALLBACK_URL;
   const [fileTokens, fileClient, omitResourceIndicator] = await Promise.all([
     store.loadTokens(args.identifier, args.resourceUrl),
     store.loadClientInformation(args.identifier, args.resourceUrl),
@@ -427,8 +439,12 @@ export async function createHostMcpOAuthProvider(args: {
     identifier: args.identifier,
     resourceUrl: args.resourceUrl,
     store,
+    redirectUrl,
     tokens: fileTokens ?? tokensFromEnv(args.identifier),
-    clientInformation: fileClient ?? clientIdFromEnv(args.identifier),
+    clientInformation: clientForRedirect(
+      fileClient ?? clientIdFromEnv(args.identifier),
+      redirectUrl
+    ),
     onRedirect: args.onRedirect,
     omitResourceIndicator,
   });

package/src/internal/null-kv-storage.ts

@@ -0,0 +1,74 @@
+/**
+ * The inert KV half of hosted v2 storage.
+ *
+ * The control-plane KV proxy (`/internal/agent-serve/storage/*`) authorizes a
+ * request by mapping the caller's pod service account to a row in the v1
+ * deployment table. Architecture v2 registers its deployments in the factory
+ * control plane instead, so every proxy call from a v2 pod answers
+ * `403 No Agent Serve deployment is bound to this service account`. The
+ * lazy-restore path deliberately propagates read failures (a store outage must
+ * not read as "unknown continuation token"), so those 403s fail follow-up
+ * deliveries outright.
+ *
+ * This backend stands in for the proxy until it can resolve v2 deployments:
+ * writes are dropped, reads are definitive misses, and lists are empty. It is
+ * paired with the framework file store (see framework-file-storage.ts), which
+ * authorizes by store source id rather than by deployment row and therefore
+ * still carries session records, event transcripts, and the continuation
+ * index — the state sessions are restored from.
+ *
+ * Author KV is the one thing that must not silently accept writes here, since
+ * handlers read their own writes back. {@link AUTHOR_KV_UNSUPPORTED} marks the
+ * definition so `ctx.host.kv` falls back to `--state-root` disk instead, the
+ * same fallback a deployment with no configured backend gets.
+ */
+
+import type { StorageConfig } from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/**
+ * Marker stamped on a definition whose KV core cannot serve `ctx.host.kv`,
+ * even though `get` is present for framework session state. Explicit
+ * `unique symbol` annotation required for `--isolatedDeclarations` (TS9010).
+ */
+export const AUTHOR_KV_UNSUPPORTED: unique symbol = Symbol.for(
+  "@cursor/july.storage.author-kv-unsupported"
+);
+
+/** True when `value` was built from {@link nullKvStorage}. */
+export function isAuthorKvUnsupported(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[AUTHOR_KV_UNSUPPORTED] === true
+  );
+}
+
+type NullKvStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  readonly [AUTHOR_KV_UNSUPPORTED]: true;
+};
+
+/**
+ * A KV core that stores nothing. `get` resolving `undefined` is honest here
+ * rather than dangerous: nothing was ever written, so a miss cannot shadow a
+ * session that exists elsewhere.
+ *
+ * No `cas` group and no `listNewest`: conditional writes over a store that
+ * forgets would report a lock acquired, and write-time ordering means nothing
+ * without writes.
+ */
+export function nullKvStorage(): NullKvStorageMethods {
+  return {
+    [AUTHOR_KV_UNSUPPORTED]: true,
+    put(): void {},
+    get(): JsonValue | undefined {
+      return undefined;
+    },
+    delete(): void {},
+    list(): [] {
+      return [];
+    },
+  };
+}

package/src/internal/otel/collector.ts

@@ -284,6 +284,36 @@ export function createOtelCollector(
           );
         return;
       }
+      case "action.auth_requested": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent("auth_requested", undefined, startTime);
+        emitLog(
+          "action.auth_requested",
+          SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "cursor.tool.name": event.data.toolName,
+            "agent_sdk.call_id": event.data.callId,
+            "agent_sdk.mcp_connection": event.data.connection,
+          })
+        );
+        return;
+      }
+      case "action.auth_resolved": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent(
+            "auth_resolved",
+            attrs({
+              "agent_sdk.decision": event.data.decision,
+              "agent_sdk.decision_by": event.data.by,
+              "agent_sdk.mcp_connection": event.data.connection,
+            }),
+            startTime
+          );
+        return;
+      }
       case "action.result": {
         const turn = ensureTurn(event, session, startTime);
         const span = turn?.tools.get(event.data.callId);

package/src/internal/server.ts

@@ -50,6 +50,7 @@ import type {
   ReminderInfo,
   ServeOptions,
 } from "../types.js";
+import { InvalidAsOfError, VacuousTimeArgsError } from "./as-of.js";
 import { V2EngineError } from "./continuation-identity.js";
 import { selectConversationMirror } from "./conversation-mirror.js";
 import {
@@ -109,6 +110,7 @@ import {
 } from "./handleAgentServeTrigger.js";
 import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
 import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
+import { hostedErrorStackSnippet } from "./hosted-execution-diag.js";
 import {
   buildHttpChannelRoutes,
   errorResponse,
@@ -130,6 +132,11 @@ import {
   MCP_ENDPOINT_PATH,
   TOOL_MCP_ENDPOINT_PATH,
 } from "./mcp-endpoint.js";
+import {
+  mcpOauthServeCallbackPath,
+  mcpOauthServeCallbackUrl,
+} from "./mcp-oauth-on-demand.js";
+import type { McpOauthSecretsTarget } from "./mcp-oauth-persist.js";
 import { isLoopbackAddress } from "./net.js";
 import { createOtelCollector, type OtelCollector } from "./otel/collector.js";
 import { pickAuthoredOtel, resolveOtelConfig } from "./otel/config.js";
@@ -181,6 +188,11 @@ import {
   UnknownToolError,
   WorkspaceUnavailableError,
 } from "./session-engine.js";
+import {
+  registerSessionRunFatalFlush,
+  selectSessionRunLogStore,
+  unregisterSessionRunFatalFlush,
+} from "./session-run-log.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
 import { catalogDetailEntry, catalogListEntry } from "./tool-catalog.js";
 
@@ -240,6 +252,10 @@ function isV2Project(project: { agent: { architecture?: string } }): boolean {
 export interface StartServerInternalOptions {
   /** Test seam: replace the Cursor SDK runner (integration tests). */
   runner?: AgentRunner;
+  /** Test seam: bind the `--store` secrets client for on-demand MCP OAuth. */
+  mcpOauthSecrets?: McpOauthSecretsTarget;
+  /** Test seam: persist hosted-execution run logs without a live store. */
+  sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
 }
 
 /**
@@ -525,6 +541,20 @@ export async function startServer(
     mounts.length === 1 && mounts[0] !== undefined
       ? selectConversationMirror({ project: mounts[0].project, logger })
       : undefined;
+  const sessionRunLog =
+    options.sessionRunLog ??
+    (mounts.length === 1 && mounts[0] !== undefined
+      ? selectSessionRunLogStore({
+          project: mounts[0].project,
+          logger,
+          snapshotLogs: () => logRing.since(),
+        })
+      : undefined);
+  if (sessionRunLog !== undefined) {
+    registerSessionRunFatalFlush((error) =>
+      sessionRunLog.flushProcessDeath("uncaught_exception", error)
+    );
+  }
   const sdkRunner =
     options.runner ??
     new CursorSdkRunner({
@@ -647,6 +677,12 @@ export async function startServer(
       otel: otelCollector,
       otelMeter: otelRuntime?.meter,
     });
+    engine.oauthCallbackHub.secrets = options.mcpOauthSecrets;
+    engine.oauthCallbackHub.secretsBind = {
+      slug: slug === "" ? undefined : slug,
+      cloudToolsUrl: options.cloudToolsUrl,
+    };
+    engine.oauthCallbackHub.logger = logger;
     // Rehydrate sessions from the authored storage sink before any
     // channel or route can address them (continuation tokens must resolve).
     await engine.restoreStoredSessions();
@@ -732,6 +768,8 @@ export async function startServer(
       multi,
       logger,
       logRing,
+      diagStateRoot: baseStateRoot,
+      sessionRunLog,
       ...(options.authToken === undefined
         ? {}
         : { authToken: options.authToken }),
@@ -762,6 +800,8 @@ export async function startServer(
           },
           resolveApproval: (sessionId, callId, decision, auth) =>
             engine.resolveApproval(sessionId, callId, decision, auth),
+          resolveAuth: (sessionId, callId, decision, auth) =>
+            engine.resolveAuth(sessionId, callId, decision, auth),
           hasContinuationSession: (continuationToken) =>
             engine.hasContinuationSession(channel.id, continuationToken),
           isContinuationBusy: (continuationToken) =>
@@ -1013,6 +1053,7 @@ export async function startServer(
   const address = server.address() as AddressInfo;
   const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
   const url = `http://${displayHost}:${boundPort}`;
+  const oauthOrigin = (options.publicUrl ?? url).replace(/\/$/, "");
 
   // Resolve peer + Cursor account MCP connections now that the listen port is
   // known (see resolved-connections.ts for the URL/runtime rules).
@@ -1039,6 +1080,20 @@ export async function startServer(
     if (resolved.length > 0) {
       runtime.engine.setResolvedConnections(resolved);
     }
+    const oauthBase = runtime.slug === "" ? "" : `/${runtime.slug}`;
+    runtime.engine.setMcpOauthCallbackUrl(
+      mcpOauthServeCallbackUrl(oauthOrigin, oauthBase)
+    );
+    if (accountBridge !== undefined && accountRefs !== undefined) {
+      const bridge = accountBridge;
+      runtime.engine.setCursorAccountAuthProbe(async (connection) => {
+        const ref = accountRefs.find((entry) => entry.name === connection);
+        if (ref === undefined) {
+          return undefined;
+        }
+        return await bridge.probeAuthUrl(ref);
+      });
+    }
     const hasServerTools = runtime.project.agent.tools.some(
       (tool) => tool.execution === "server"
     );
@@ -1168,6 +1223,10 @@ export async function startServer(
       return runtime.engine.callTool(toolName, input, callOptions);
     },
     close: async () => {
+      if (sessionRunLog !== undefined) {
+        await sessionRunLog.flushProcessDeath("process_exit");
+        unregisterSessionRunFatalFlush();
+      }
       playgroundDev?.stop();
       await cursorDeploymentRelay?.stop();
       await cursorEventRelay?.stop();
@@ -1222,15 +1281,29 @@ function mountAgentRoutes(
     multi: boolean;
     logger: (line: string) => void;
     logRing: LogRing;
+    sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
     authToken?: string;
     allowAnonymous?: boolean;
     /** Cursor account bridge + this mount's account MCP connections, when authored. */
     accountBridge?: CursorAccountMcpBridge;
     accountRefs?: CursorAccountConnectionRef[];
+    /**
+     * Serve `--state-root`. Hosted-execution writes `hosted-execution.json`
+     * here so the Temporal host can read a stable path after the POST.
+     */
+    diagStateRoot?: string;
   }
 ): void {
   const { slug, project, engine, scheduleRunner, reminderRunner } = runtime;
-  const { dev, playground, noControlPlane, multi, logger, logRing } = args;
+  const {
+    dev,
+    playground,
+    noControlPlane,
+    multi,
+    logger,
+    logRing,
+    sessionRunLog,
+  } = args;
   // "" (single) -> "/v1/..."; "my-agent" (multi) -> "/my-agent/v1/...".
   const base = slug === "" ? "" : `/${slug}`;
 
@@ -1288,6 +1361,13 @@ function mountAgentRoutes(
         }),
       drainSessionDurability: (sessionId) =>
         engine.drainSessionDurability(sessionId),
+      ...(args.diagStateRoot === undefined
+        ? {}
+        : { stateRoot: args.diagStateRoot }),
+      ...(sessionRunLog === undefined
+        ? {}
+        : { persistSessionRun: (document) => sessionRunLog.persist(document) }),
+      snapshotLogs: () => logRing.since(),
     });
   }
   // Playground lists/opens Slack (and other channel) sessions across
@@ -1303,6 +1383,13 @@ function mountAgentRoutes(
   // tools (Slack principals never match local/anonymous HTTP auth).
   const relaxSessionApprovalAuth = relaxSessionReadAuth;
 
+  router.add({
+    method: "GET",
+    pattern: `${base}${mcpOauthServeCallbackPath()}`,
+    auth: "none",
+    handler: (request) => engine.oauthCallbackHub.handleCallback(request),
+  });
+
   router.add({
     method: "GET",
     pattern: `${base}/v1/health`,
@@ -1387,11 +1474,56 @@ function mountAgentRoutes(
     },
   });
 
+  // v2 only: one session-level hosted-execution log on the framework
+  // store. Distinct from GET /v1/logs (process-wide ring). Keyed by the
+  // factory session public id so an execute_throw that never minted a
+  // July session is still readable after the pod parks.
+  if (isV2Project(project) && sessionRunLog !== undefined) {
+    router.add({
+      method: "GET",
+      pattern: `${base}/v1/session/:sessionId/runs`,
+      auth: httpAuth,
+      handler: async (_request, ctx) => {
+        const sessionId = ctx.params.sessionId ?? "";
+        if (sessionId.length === 0 || sessionId.includes("/")) {
+          return errorResponse(
+            400,
+            "invalid_request",
+            "Expected a session id."
+          );
+        }
+        const record = await engine.getOrRestoreSession(sessionId);
+        if (record === undefined) {
+          return errorResponse(
+            404,
+            "session_not_found",
+            `Unknown session ${sessionId}.`
+          );
+        }
+        const ownership = requireSessionOwner(record, ctx.auth, {
+          relax: relaxSessionReadAuth,
+          beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+          requestIp: ctx.requestIp,
+        });
+        if (ownership !== undefined) {
+          return ownership;
+        }
+        const document = await sessionRunLog.read(sessionId);
+        return jsonResponse({
+          sessionId,
+          updatedAt: document?.updatedAt,
+          lastFailure: document?.lastFailure ?? null,
+          executions: document?.executions ?? [],
+        });
+      },
+    });
+  }
+
   router.add({
     method: "GET",
     pattern: `${base}/v1/sessions`,
     auth: httpAuth,
-    handler: async (_request, ctx) => {
+    handler: async (request, ctx) => {
       // Same gate as requireSessionOwner / relaxSessionReadAuth: never with
       // bearer or custom channel auth (strict per-principal isolation).
       // `--allow-anonymous` alone is a shared-principal trust boundary (corp
@@ -1401,9 +1533,14 @@ function mountAgentRoutes(
         (relaxSessionReadAuthBeyondLoopback ||
           (typeof ctx.requestIp === "string" &&
             isLoopbackAddress(ctx.requestIp)));
-      const listed = await engine.listSessionsWithSource(ctx.auth, {
-        includeAll,
-      });
+      // `?latest=1` — only the newest visible session. Clients binding a
+      // default session (agsh) do not need the whole list, and on hosted
+      // storage the whole list is a database scan.
+      const latest = new URL(request.url).searchParams.get("latest");
+      const listed =
+        latest === "1" || latest === "true"
+          ? await engine.latestSessionWithSource(ctx.auth, { includeAll })
+          : await engine.listSessionsWithSource(ctx.auth, { includeAll });
       return jsonResponse({
         sessions: listed.sessions,
         source: listed.source,
@@ -1613,23 +1750,22 @@ function mountAgentRoutes(
         return binding.errorResponse;
       }
       try {
-        const catalog = await engine.listCatalogTools({
+        const described = await engine.describeCatalogTool(toolName, {
           auth: ctx.auth,
           ...binding,
         });
-        const tool = catalog.tools.find((t) => t.name === toolName);
-        if (tool === undefined) {
+        if (described.tool === undefined) {
           return jsonResponse(
             {
               ok: false,
               error: "unknown_tool",
               message: `Unknown tool "${toolName}".`,
-              availableTools: catalog.tools.map((t) => t.name),
+              availableTools: described.availableTools,
             },
             { status: 404 }
           );
         }
-        return jsonResponse(catalogDetailEntry(tool));
+        return jsonResponse(catalogDetailEntry(described.tool));
       } catch (error) {
         if (error instanceof InvalidContinuationTokenError) {
           return errorResponse(
@@ -2779,6 +2915,11 @@ async function handleRequest(
       );
     } else if (error instanceof SessionAuthError) {
       response = errorResponse(403, "forbidden", error.message);
+    } else if (
+      error instanceof InvalidAsOfError ||
+      error instanceof VacuousTimeArgsError
+    ) {
+      response = errorResponse(400, "invalid_request", error.message);
     } else {
       logger(
         `[agent-sdk] request failed: ${
@@ -2787,7 +2928,14 @@ async function handleRequest(
             : String(error)
         }`
       );
-      response = errorResponse(500, "internal_error", "Internal server error.");
+      const snippet = hostedErrorStackSnippet(error);
+      response = errorResponse(
+        500,
+        "internal_error",
+        snippet.length > 0
+          ? `Internal server error: ${snippet}`
+          : "Internal server error."
+      );
     }
   }