@cursor/july 0.1.10 → 0.1.11

package/src/internal/mcp-host.ts

@@ -9,6 +9,7 @@
  *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
  */
 
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -20,6 +21,8 @@ import type {
   HostMcpToolInfo,
   JsonObject,
 } from "../types.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
 
 interface OpenedConnection {
   client: Client;
@@ -118,8 +121,21 @@ async function openConnection(
     name: "agent-serve",
     version: "0.1.0",
   });
-  const transport = createTransport(connection);
-  await client.connect(transport);
+  const transport = await createTransport(connection);
+  try {
+    await client.connect(transport);
+  } catch (error) {
+    if (
+      error instanceof UnauthorizedError &&
+      isOauthHttpTransport(connection.transport)
+    ) {
+      throw new Error(
+        `MCP connection "${connection.name}" needs authorization. Run \`${CLI} mcp oauth ${connection.name}\`.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
 
   return {
     client,
@@ -138,7 +154,7 @@ async function openConnection(
   };
 }
 
-function createTransport(connection: DiscoveredConnection) {
+async function createTransport(connection: DiscoveredConnection) {
   const transport = connection.transport;
   if ("agent" in transport) {
     // Peers are resolved to concrete URLs by the serve host before any call
@@ -176,16 +192,24 @@ function createTransport(connection: DiscoveredConnection) {
     transport.headers === undefined
       ? undefined
       : { headers: transport.headers };
+  const authProvider =
+    transport.oauth === true
+      ? await createHostMcpOAuthProvider({
+          identifier: connection.name,
+          resourceUrl: transport.url,
+        })
+      : undefined;
 
   if (transport.type === "sse") {
-    return new SSEClientTransport(url, {
-      ...(requestInit === undefined ? {} : { requestInit }),
-    });
+    return new SSEClientTransport(url, { requestInit, authProvider });
   }
+  return new StreamableHTTPClientTransport(url, { requestInit, authProvider });
+}
 
-  return new StreamableHTTPClientTransport(url, {
-    ...(requestInit === undefined ? {} : { requestInit }),
-  });
+function isOauthHttpTransport(
+  transport: DiscoveredConnection["transport"]
+): boolean {
+  return "url" in transport && transport.oauth === true;
 }
 
 function normalizeCallResult(result: unknown): HostMcpCallResult {

package/src/internal/mcp-oauth.ts

@@ -0,0 +1,496 @@
+/**
+ * Host-side MCP OAuth for `defineConnection({ url, oauth: true })`.
+ * Local: mcp-auth.json. Prod secrets: `mcp oauth <name> --store`.
+ */
+
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { dirname, join } from "node:path";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { configDirPath } from "./cursor/credentials.js";
+
+export const MCP_OAUTH_CALLBACK_PORT = 8787;
+export const MCP_OAUTH_CALLBACK_PATH = "/callback";
+export const MCP_OAUTH_CALLBACK_URL: string = `http://localhost:${MCP_OAUTH_CALLBACK_PORT}${MCP_OAUTH_CALLBACK_PATH}`;
+
+/** `anytool` → `MCP_OAUTH_ANYTOOL`. */
+export function mcpOauthEnvPrefix(connection: string): string {
+  const key = connection
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return `MCP_OAUTH_${key.length > 0 ? key : "CONNECTION"}`;
+}
+
+export type McpOauthSecretNames = {
+  accessToken: string;
+  refreshToken: string;
+  clientId: string;
+};
+
+export function mcpOauthSecretNames(connection: string): McpOauthSecretNames {
+  const prefix = mcpOauthEnvPrefix(connection);
+  return {
+    accessToken: `${prefix}_ACCESS_TOKEN`,
+    refreshToken: `${prefix}_REFRESH_TOKEN`,
+    clientId: `${prefix}_CLIENT_ID`,
+  };
+}
+
+export function tokensFromEnv(
+  connection: string,
+  env: NodeJS.ProcessEnv = process.env
+): OAuthTokens | undefined {
+  const names = mcpOauthSecretNames(connection);
+  const access = env[names.accessToken]?.trim();
+  if (access === undefined || access === "") {
+    return undefined;
+  }
+  const refresh = env[names.refreshToken]?.trim();
+  return {
+    access_token: access,
+    refresh_token:
+      refresh === undefined || refresh === "" ? undefined : refresh,
+    token_type: "Bearer",
+  };
+}
+
+export function clientIdFromEnv(
+  connection: string,
+  env: NodeJS.ProcessEnv = process.env
+): OAuthClientInformationFull | undefined {
+  const clientId = env[mcpOauthSecretNames(connection).clientId]?.trim();
+  if (clientId === undefined || clientId === "") {
+    return undefined;
+  }
+  return {
+    client_id: clientId,
+    redirect_uris: [MCP_OAUTH_CALLBACK_URL],
+  };
+}
+
+interface AuthEntry {
+  /** MCP resource URL this entry was issued for (origin + path, no query). */
+  resourceUrl?: string;
+  tokens?: OAuthTokens;
+  clientInfo?: OAuthClientInformationFull;
+}
+
+type AuthFile = Record<string, AuthEntry>;
+
+const locks = new Map<string, Promise<void>>();
+
+/** Sibling of `credentials.json` under `~/.config/agent-serve/`. */
+export function defaultMcpAuthPath(): string {
+  return join(configDirPath(), "mcp-auth.json");
+}
+
+/** Canonical MCP resource key for binding stored tokens to a server URL. */
+export function normalizeMcpResourceUrl(url: string): string {
+  const parsed = new URL(url);
+  parsed.hash = "";
+  parsed.search = "";
+  // Drop default ports so http://h:80 and http://h match.
+  if (
+    (parsed.protocol === "https:" && parsed.port === "443") ||
+    (parsed.protocol === "http:" && parsed.port === "80")
+  ) {
+    parsed.port = "";
+  }
+  let path = parsed.pathname;
+  if (path.length > 1 && path.endsWith("/")) {
+    path = path.slice(0, -1);
+  }
+  return `${parsed.origin}${path === "/" ? "" : path}`;
+}
+
+export class FileMcpOAuthStore {
+  private cache: AuthFile | undefined;
+  private loading: Promise<AuthFile> | undefined;
+
+  constructor(readonly path: string = defaultMcpAuthPath()) {}
+
+  async loadTokens(
+    id: string,
+    resourceUrl: string
+  ): Promise<OAuthTokens | undefined> {
+    return (await this.entryFor(id, resourceUrl))?.tokens;
+  }
+
+  async loadClientInformation(
+    id: string,
+    resourceUrl: string
+  ): Promise<OAuthClientInformationFull | undefined> {
+    return (await this.entryFor(id, resourceUrl))?.clientInfo;
+  }
+
+  async saveTokens(
+    id: string,
+    resourceUrl: string,
+    tokens: OAuthTokens
+  ): Promise<void> {
+    await this.update(id, resourceUrl, (entry) => {
+      entry.tokens = tokens;
+    });
+  }
+
+  async saveClientInformation(
+    id: string,
+    resourceUrl: string,
+    clientInfo: OAuthClientInformationFull
+  ): Promise<void> {
+    await this.update(id, resourceUrl, (entry) => {
+      entry.clientInfo = clientInfo;
+    });
+  }
+
+  async deleteCredentials(id: string): Promise<void> {
+    await this.withLock(async () => {
+      const data = await this.read();
+      delete data[id];
+      await this.write(data);
+    });
+  }
+
+  private async entryFor(
+    id: string,
+    resourceUrl: string
+  ): Promise<AuthEntry | undefined> {
+    const entry = (await this.read())[id];
+    if (entry === undefined) {
+      return undefined;
+    }
+    const bound = entry.resourceUrl;
+    if (bound === undefined || bound !== normalizeMcpResourceUrl(resourceUrl)) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  private async update(
+    id: string,
+    resourceUrl: string,
+    mutate: (entry: AuthEntry) => void
+  ): Promise<void> {
+    const normalized = normalizeMcpResourceUrl(resourceUrl);
+    await this.withLock(async () => {
+      const data = await this.read();
+      const existing = data[id];
+      const entry: AuthEntry =
+        existing?.resourceUrl === normalized ? { ...existing } : {};
+      entry.resourceUrl = normalized;
+      mutate(entry);
+      data[id] = entry;
+      await this.write(data);
+    });
+  }
+
+  private async read(): Promise<AuthFile> {
+    if (this.cache !== undefined) {
+      return this.cache;
+    }
+    this.loading ??= this.readDisk().then((data) => {
+      this.cache = data;
+      return data;
+    });
+    return this.loading;
+  }
+
+  private async readDisk(): Promise<AuthFile> {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(this.path, "utf8"));
+      if (typeof parsed !== "object" || parsed === null) {
+        return {};
+      }
+      return parsed as AuthFile;
+    } catch (error: unknown) {
+      if (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error as { code: unknown }).code === "ENOENT"
+      ) {
+        return {};
+      }
+      throw error;
+    }
+  }
+
+  private async write(data: AuthFile): Promise<void> {
+    this.cache = data;
+    await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+    await writeFile(this.path, `${JSON.stringify(data, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    await chmod(this.path, 0o600);
+  }
+
+  private async withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const prev = locks.get(this.path) ?? Promise.resolve();
+    let release!: () => void;
+    locks.set(
+      this.path,
+      new Promise<void>((resolve) => {
+        release = resolve;
+      })
+    );
+    try {
+      await prev;
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}
+
+type ProviderArgs = {
+  identifier: string;
+  resourceUrl: string;
+  store: FileMcpOAuthStore;
+  redirectUrl?: string;
+  onRedirect?: (url: URL) => void;
+  tokens?: OAuthTokens;
+  clientInformation?: OAuthClientInformationFull;
+};
+
+export class HostMcpOAuthProvider implements OAuthClientProvider {
+  private tokensValue: OAuthTokens | undefined;
+  private clientInfo: OAuthClientInformationFull | undefined;
+  private verifier: string | undefined;
+  private redirect: URL | undefined;
+  private readonly meta: OAuthClientMetadata;
+  private readonly args: ProviderArgs;
+
+  constructor(args: ProviderArgs) {
+    this.args = args;
+    this.tokensValue = args.tokens;
+    this.clientInfo = args.clientInformation;
+    this.meta = {
+      redirect_uris: [args.redirectUrl ?? MCP_OAUTH_CALLBACK_URL],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "agentkit",
+    };
+  }
+
+  get redirectUrl(): string {
+    return this.args.redirectUrl ?? MCP_OAUTH_CALLBACK_URL;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return this.meta;
+  }
+
+  get lastRedirectUrl(): URL | undefined {
+    return this.redirect;
+  }
+
+  state(): string {
+    return randomUUID();
+  }
+
+  clientInformation(): OAuthClientInformationFull | undefined {
+    return this.clientInfo;
+  }
+
+  async saveClientInformation(info: OAuthClientInformationFull): Promise<void> {
+    this.clientInfo = info;
+    await this.args.store.saveClientInformation(
+      this.args.identifier,
+      this.args.resourceUrl,
+      info
+    );
+  }
+
+  tokens(): OAuthTokens | undefined {
+    return this.tokensValue;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    this.tokensValue = tokens;
+    await this.args.store.saveTokens(
+      this.args.identifier,
+      this.args.resourceUrl,
+      tokens
+    );
+  }
+
+  redirectToAuthorization(url: URL): void {
+    this.redirect = url;
+    this.args.onRedirect?.(url);
+  }
+
+  async saveCodeVerifier(codeVerifier: string): Promise<void> {
+    this.verifier = codeVerifier;
+  }
+
+  codeVerifier(): string {
+    if (this.verifier === undefined) {
+      throw new Error("No PKCE code verifier saved for this OAuth attempt.");
+    }
+    return this.verifier;
+  }
+
+  async invalidateCredentials(
+    scope: "all" | "client" | "tokens" | "verifier"
+  ): Promise<void> {
+    if (scope === "tokens" || scope === "all") {
+      this.tokensValue = undefined;
+    }
+    if (scope === "client" || scope === "all") {
+      this.clientInfo = undefined;
+    }
+    if (scope === "verifier" || scope === "all") {
+      this.verifier = undefined;
+      this.redirect = undefined;
+    }
+    if (scope === "all") {
+      await this.args.store.deleteCredentials(this.args.identifier);
+    }
+  }
+}
+
+export async function createHostMcpOAuthProvider(args: {
+  identifier: string;
+  resourceUrl: string;
+  store?: FileMcpOAuthStore;
+  onRedirect?: (url: URL) => void;
+}): Promise<HostMcpOAuthProvider> {
+  const store = args.store ?? new FileMcpOAuthStore();
+  const [fileTokens, fileClient] = await Promise.all([
+    store.loadTokens(args.identifier, args.resourceUrl),
+    store.loadClientInformation(args.identifier, args.resourceUrl),
+  ]);
+  return new HostMcpOAuthProvider({
+    identifier: args.identifier,
+    resourceUrl: args.resourceUrl,
+    store,
+    tokens: fileTokens ?? tokensFromEnv(args.identifier),
+    clientInformation: fileClient ?? clientIdFromEnv(args.identifier),
+    onRedirect: args.onRedirect,
+  });
+}
+
+export type OAuthCallbackResult = {
+  code: string;
+  state?: string;
+};
+
+export async function waitForMcpOAuthCallback(args?: {
+  port?: number;
+  path?: string;
+  timeoutMs?: number;
+}): Promise<OAuthCallbackResult> {
+  const port = args?.port ?? MCP_OAUTH_CALLBACK_PORT;
+  const path = args?.path ?? MCP_OAUTH_CALLBACK_PATH;
+  const timeoutMs = args?.timeoutMs ?? 5 * 60 * 1000;
+
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const finish = (
+      result: OAuthCallbackResult | undefined,
+      error?: Error
+    ): void => {
+      if (done) {
+        return;
+      }
+      done = true;
+      clearTimeout(timer);
+      server.close();
+      if (error !== undefined) {
+        reject(error);
+        return;
+      }
+      if (result !== undefined) {
+        resolve(result);
+      }
+    };
+
+    const server: Server = createServer((req, res) => {
+      if (req.url === "/favicon.ico") {
+        res.writeHead(404).end();
+        return;
+      }
+      const url = new URL(req.url ?? "", `http://localhost:${port}`);
+      if (url.pathname !== path) {
+        res.writeHead(404).end("Not found");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const oauthError = url.searchParams.get("error");
+      const state = url.searchParams.get("state") ?? undefined;
+      if (code) {
+        res
+          .writeHead(200, { "content-type": "text/html; charset=utf-8" })
+          .end(
+            "<!doctype html><html><body><h1>Authorized</h1><p>Return to agentkit.</p></body></html>"
+          );
+        finish({ code, state });
+        return;
+      }
+      res
+        .writeHead(400, { "content-type": "text/html; charset=utf-8" })
+        .end(
+          `<!doctype html><html><body><h1>Authorization failed</h1><p>${oauthError ?? "missing code"}</p></body></html>`
+        );
+      finish(
+        undefined,
+        new Error(`OAuth authorization failed: ${oauthError ?? "missing code"}`)
+      );
+    });
+
+    const timer = setTimeout(() => {
+      finish(
+        undefined,
+        new Error(
+          `Timed out waiting for OAuth callback on http://localhost:${port}${path}`
+        )
+      );
+    }, timeoutMs);
+
+    server.on("error", (error) => {
+      finish(
+        undefined,
+        new Error(
+          `OAuth callback port ${port} failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        )
+      );
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+export function openBrowser(url: string): void {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(
+      `Refusing to open non-http(s) authorization URL: ${parsed.protocol}`
+    );
+  }
+  const href = parsed.href;
+  if (process.platform === "darwin") {
+    execFile("open", [href], () => undefined);
+    return;
+  }
+  if (process.platform === "win32") {
+    // Avoid `cmd /c start` — authorize URLs with `&` are shell-metachar risks.
+    execFile(
+      "rundll32",
+      ["url.dll,FileProtocolHandler", href],
+      () => undefined
+    );
+    return;
+  }
+  execFile("xdg-open", [href], () => undefined);
+}

package/src/internal/resolved-connections.ts

@@ -35,8 +35,13 @@ export function validateMountConnectionsConfig(args: {
     return;
   }
   const label = args.slug === "" ? args.project.name : args.slug;
+  const hostOnlyNames = new Set(
+    agent.connections
+      .filter((connection) => connection.hostOnly === true)
+      .map((connection) => connection.name)
+  );
   const filteredRefs = args.accountRefs.filter(
-    (ref) => ref.servers !== undefined
+    (ref) => ref.servers !== undefined && !hostOnlyNames.has(ref.name)
   );
   if (filteredRefs.length === 0) {
     return;

package/src/internal/sdk-runner.ts

@@ -42,6 +42,8 @@ export interface CursorSdkRunnerOptions {
    * `LocalAgentStore` for heavy multi-session concurrency.
    */
   store?: LocalAgentStore;
+  /** Diagnostics for degraded paths (resume-miss fallback). */
+  logger?: (line: string) => void;
 }
 
 export class CursorSdkRunner implements AgentRunner {
@@ -180,7 +182,24 @@ export class CursorSdkRunner implements AgentRunner {
         agentId: request.sdkAgentId ?? request.sessionId,
       });
     }
-    return Agent.resume(request.sdkAgentId ?? request.sessionId, options);
+
+    const agentId = request.sdkAgentId ?? request.sessionId;
+    try {
+      return await Agent.resume(agentId, options);
+    } catch (error) {
+      if (!isLocalAgentNotFoundError(error, agentId)) {
+        throw error;
+      }
+      // Host replacement: the session record survived in durable storage,
+      // but the conversation store died with the old pod. A fresh
+      // conversation under the same id beats failing this thread's turns
+      // forever ("Agent … not found" on every follow-up). The channel's
+      // warm-turn prompt context re-hydrates the thread history.
+      (this.options.logger ?? (() => {}))(
+        `[agentkit] no stored conversation for ${agentId} on this host; starting a fresh one`
+      );
+      return Agent.create({ ...options, agentId });
+    }
   }
 
   private async openCloudAgent(
@@ -237,6 +256,23 @@ export function isServerMintedCloudAgentId(id: string): boolean {
   return id.startsWith("bc-");
 }
 
+/**
+ * `Agent.resume` on a store with no row for the agent ("Agent <id> not
+ * found", surfaced by every built-in {@link LocalAgentStore} backend).
+ * Deliberately narrow: transient store/transport failures must propagate
+ * rather than silently fork the thread onto a fresh conversation.
+ */
+export function isLocalAgentNotFoundError(
+  error: unknown,
+  agentId: string
+): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes(agentId) &&
+    /\bnot found\b/i.test(error.message)
+  );
+}
+
 export function toModelSelection(model: ModelSetting): ModelSelection {
   if (typeof model === "string") {
     return { id: model };

package/src/internal/server.ts

@@ -49,7 +49,6 @@ import {
 } from "./cursor/account-mcp.js";
 import { CursorBackendClient } from "./cursor/backend-client.js";
 import {
-  cursorBackendUrl,
   cursorExternalApiUrl,
   type ResolvedApiKey,
   resolveApiKey,
@@ -286,9 +285,10 @@ export async function startServer(
   }
   const runner =
     options.runner ??
-    new CursorSdkRunner(
-      accountKey === undefined ? {} : { apiKey: accountKey.apiKey }
-    );
+    new CursorSdkRunner({
+      ...(accountKey === undefined ? {} : { apiKey: accountKey.apiKey }),
+      logger,
+    });
 
   const router = new Router();
   const runtimes: MountedRuntime[] = [];
@@ -387,6 +387,12 @@ export async function startServer(
         reminderRunner.cancelForContinuation(token, reason),
       dispatch: (id) => reminderRunner.dispatch(id),
     });
+    engine.setEvals({
+      list: () => evalRuns.list(),
+      get: (runId) => evalRuns.get(runId),
+      listRunsWithActive: () => evalRuns.listRunsWithActive(),
+      start: (input) => evalRuns.start(input),
+    });
     const runtime: MountedRuntime = {
       slug,
       project,
@@ -1609,7 +1615,9 @@ async function startCursorSlackRelay(input: {
       `This project has Slack channels using the Cursor account connection (slackChannel({ cursorAccount: true })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
     );
   }
-  const baseUrl = accountKey.backendUrl ?? cursorBackendUrl();
+  // Same host split as scm-events: `/v0/slack-events/*` is on api.cursor.com,
+  // not api2 (accountKey.backendUrl 404s these routes).
+  const baseUrl = cursorExternalApiUrl();
   const baseStateRoot =
     options.stateRoot ??
     join(targets[0].runtime.project.rootDir, ".agent-serve");