@cursor/july 0.1.10 → 0.1.12

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

@@ -0,0 +1,254 @@
+/**
+ * `agentkit mcp oauth <connection> [--store]` for `defineConnection({ url, oauth: true })`.
+ */
+
+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 { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { resolveDeployAuth } from "./cli-deploy.js";
+import { loadAgentProject } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI, LOG_PREFIX } from "./distribution.js";
+import {
+  createHostMcpOAuthProvider,
+  MCP_OAUTH_CALLBACK_URL,
+  mcpOauthSecretNames,
+  openBrowser,
+  waitForMcpOAuthCallback,
+} from "./mcp-oauth.js";
+import { resolveProdSlug } from "./resolve-prod-target.js";
+
+export type McpOauthCliOptions = {
+  dir: string;
+  connection: string;
+  /** Upsert MCP_OAUTH_* on the hosted deployment. */
+  store?: boolean;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  err?: (text: string) => void;
+  out?: (text: string) => void;
+};
+
+function describe(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+  const cause = error.cause;
+  if (!(cause instanceof Error)) {
+    return error.message;
+  }
+  const code =
+    "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+  const detail =
+    code === undefined ? cause.message : `${cause.message} (${code})`;
+  return `${error.message}: ${detail}`;
+}
+
+export async function cmdMcpOauth(
+  options: McpOauthCliOptions
+): Promise<number> {
+  const err = options.err ?? ((text) => process.stderr.write(text));
+  const out = options.out ?? ((text) => process.stdout.write(text));
+  const project = await loadAgentProject(options.dir);
+  const connection = project.agent.connections.find(
+    (entry) => entry.name === options.connection
+  );
+  if (connection === undefined) {
+    const known =
+      project.agent.connections.map((entry) => entry.name).join(", ") ||
+      "(none)";
+    err(
+      `${LOG_PREFIX} Unknown MCP connection "${options.connection}". Authored: ${known}.\n`
+    );
+    return 1;
+  }
+
+  const transport = connection.transport;
+  if (!("url" in transport) || transport.oauth !== true) {
+    err(
+      `${LOG_PREFIX} "${options.connection}" must be defineConnection({ url, oauth: true }).\n`
+    );
+    return 1;
+  }
+
+  out(
+    `${LOG_PREFIX} Authorizing "${options.connection}" (${transport.url})…\n`
+  );
+
+  let authorizationUrl: URL | undefined;
+  const provider = await createHostMcpOAuthProvider({
+    identifier: options.connection,
+    resourceUrl: transport.url,
+    onRedirect: (url) => {
+      authorizationUrl = url;
+    },
+  });
+
+  const client = new Client({ name: "agentkit-mcp-oauth", version: "0.1.0" });
+  const url = new URL(transport.url);
+  const requestInit =
+    transport.headers === undefined
+      ? undefined
+      : { headers: transport.headers };
+
+  const makeTransport = ():
+    | StreamableHTTPClientTransport
+    | SSEClientTransport => {
+    if (transport.type === "sse") {
+      return new SSEClientTransport(url, {
+        authProvider: provider,
+        requestInit,
+      });
+    }
+    return new StreamableHTTPClientTransport(url, {
+      authProvider: provider,
+      requestInit,
+    });
+  };
+
+  let mcpTransport = makeTransport();
+  let authorized = false;
+  try {
+    await client.connect(mcpTransport);
+    out(`${LOG_PREFIX} "${options.connection}" already authorized.\n`);
+    await client.close().catch(() => undefined);
+    authorized = true;
+  } catch (error) {
+    if (!(error instanceof UnauthorizedError)) {
+      err(
+        `${LOG_PREFIX} Failed to connect to "${options.connection}": ${describe(error)}\n`
+      );
+      return 1;
+    }
+  }
+
+  if (!authorized) {
+    const redirect = authorizationUrl ?? provider.lastRedirectUrl;
+    if (redirect === undefined) {
+      err(
+        `${LOG_PREFIX} Auth required but no authorization URL was provided.\n`
+      );
+      return 1;
+    }
+
+    out(`${LOG_PREFIX} Open if needed:\n  ${redirect.toString()}\n`);
+    out(`${LOG_PREFIX} Waiting on ${MCP_OAUTH_CALLBACK_URL}…\n`);
+    openBrowser(redirect.toString());
+
+    let callback: Awaited<ReturnType<typeof waitForMcpOAuthCallback>>;
+    try {
+      callback = await waitForMcpOAuthCallback();
+    } catch (error) {
+      err(`${LOG_PREFIX} OAuth callback failed: ${describe(error)}\n`);
+      return 1;
+    }
+
+    try {
+      await mcpTransport.finishAuth(callback.code);
+    } catch (error) {
+      err(`${LOG_PREFIX} Token exchange failed: ${describe(error)}\n`);
+      return 1;
+    }
+
+    mcpTransport = makeTransport();
+    try {
+      await client.connect(mcpTransport);
+      const tools = await client.listTools();
+      out(
+        `${LOG_PREFIX} Authorized "${options.connection}" (${tools.tools.length} tools). Local tokens in the agent-serve config dir.\n`
+      );
+      await client.close().catch(() => undefined);
+    } catch (error) {
+      err(
+        `${LOG_PREFIX} Reconnect failed: ${describe(error)}. Re-run \`${CLI} mcp oauth ${options.connection}\`.\n`
+      );
+      return 1;
+    }
+  }
+
+  if (options.store !== true) {
+    return 0;
+  }
+  return storeOauthSecrets({
+    connection: options.connection,
+    dir: options.dir,
+    slug: options.slug,
+    team: options.team,
+    apiKey: options.apiKey,
+    tokens: provider.tokens(),
+    clientId: provider.clientInformation()?.client_id,
+    err,
+    out,
+  });
+}
+
+async function storeOauthSecrets(args: {
+  connection: string;
+  dir: string;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  tokens: OAuthTokens | undefined;
+  clientId: string | undefined;
+  err: (text: string) => void;
+  out: (text: string) => void;
+}): Promise<number> {
+  const tokens = args.tokens;
+  if (tokens === undefined || tokens.access_token.trim() === "") {
+    args.err(
+      `${LOG_PREFIX} No access token to store for "${args.connection}".\n`
+    );
+    return 1;
+  }
+
+  let slug: string;
+  try {
+    slug = resolveProdSlug({ dir: args.dir, slug: args.slug });
+  } catch (error) {
+    args.err(`${LOG_PREFIX} ${describe(error)}\n`);
+    return 1;
+  }
+
+  const auth = await resolveDeployAuth({
+    team: args.team,
+    apiKey: args.apiKey,
+    err: args.err,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+
+  const names = mcpOauthSecretNames(args.connection);
+  const secrets: Array<{ name: string; value: string }> = [
+    { name: names.accessToken, value: tokens.access_token },
+  ];
+  if (
+    tokens.refresh_token !== undefined &&
+    tokens.refresh_token.trim() !== ""
+  ) {
+    secrets.push({ name: names.refreshToken, value: tokens.refresh_token });
+  }
+  if (args.clientId !== undefined && args.clientId.trim() !== "") {
+    secrets.push({ name: names.clientId, value: args.clientId });
+  }
+
+  try {
+    const secretNames = await auth.client.setSecrets({
+      teamId: auth.teamId,
+      slug,
+      secrets,
+    });
+    args.out(
+      `${LOG_PREFIX} Stored on ${slug}: ${secrets.map((s) => s.name).join(", ")}.\n` +
+        `${LOG_PREFIX} Secrets now: ${secretNames.join(", ")}. Next deploy picks them up.\n`
+    );
+    return 0;
+  } catch (error) {
+    args.err(
+      `${LOG_PREFIX} Failed to store secrets on ${slug}: ${describe(error)}\n`
+    );
+    return 1;
+  }
+}

package/src/internal/cli-mcp.ts

@@ -89,7 +89,10 @@ export interface McpCliOptions {
 
 export async function cmdMcp(
   subcommand: string | undefined,
-  options: McpCliOptions
+  options: McpCliOptions & {
+    oauthConnection?: string;
+    store?: boolean;
+  }
 ): Promise<number> {
   const err = options.err ?? defaultErr;
   if (subcommand === undefined) {
@@ -98,9 +101,29 @@ export async function cmdMcp(
   if (subcommand === "install") {
     return cmdMcpInstall(options);
   }
+  if (subcommand === "oauth") {
+    const connection = options.oauthConnection;
+    if (connection === undefined || connection.trim() === "") {
+      err(
+        `Usage: ${CLI} mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]\n` +
+          `Authorize defineConnection({ url, oauth: true }) (host PKCE).\n` +
+          `--store upserts MCP_OAUTH_<NAME>_* secrets on the hosted deployment.\n`
+      );
+      return 1;
+    }
+    const { cmdMcpOauth } = await import("./cli-mcp-oauth.js");
+    return cmdMcpOauth({
+      dir: options.dir,
+      connection,
+      store: options.store,
+      slug: options.slug,
+      team: options.team,
+      apiKey: options.apiKey,
+    });
+  }
   err(
     `Unknown mcp subcommand "${subcommand}".\n` +
-      `Usage: ${CLI} mcp [install] --prod [--slug <slug>] | --url <baseUrl>\n`
+      `Usage: ${CLI} mcp [install|oauth <connection>] --prod [--slug <slug>] | --url <baseUrl>\n`
   );
   return 1;
 }

package/src/internal/cursor/account-mcp.ts

@@ -213,48 +213,89 @@ export class CursorAccountMcpBridge {
 
   /**
    * Startup DX: log the account's connector statuses for `refs` without
-   * blocking serve startup. Surfaces "needsAuth" connectors (authorize in
-   * Cursor) and filters that matched nothing (typo'd connector names).
+   * blocking serve startup. Surfaces "needsAuth" / "error" connectors with
+   * remediation hints (and a backend probe detail for `error`), and filters
+   * that matched nothing (typo'd connector names).
+   *
+   * Returns a promise that settles when every ref's log lines are written —
+   * callers may ignore it; tests can await it.
    */
-  logPreflight(refs: CursorAccountConnectionRef[]): void {
-    for (const ref of refs) {
-      void this.getCatalog(ref)
-        .then((catalog) => {
-          const summary = catalog.servers
-            .map(
-              (server) =>
-                `${server.serverIdentifier} (${
-                  server.status === "connected"
-                    ? `${server.tools.length} tools`
-                    : server.status
-                })`
-            )
-            .join(", ");
-          this.logger(
-            `[agentkit] Cursor account MCP connection "${ref.name}": ${
-              catalog.servers.length === 0
-                ? "no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the `servers` filter"
-                : summary
-            }`
-          );
-          const needsAuth = catalog.servers.filter(
-            (server) => server.status === "needsAuth"
-          );
-          if (needsAuth.length > 0) {
-            this.logger(
-              `[agentkit] Cursor account MCP connection "${ref.name}": ${needsAuth
-                .map((server) => server.serverIdentifier)
-                .join(
-                  ", "
-                )} need re-authorization in Cursor before their tools appear`
+  logPreflight(refs: CursorAccountConnectionRef[]): Promise<void> {
+    return Promise.all(refs.map((ref) => this.runPreflight(ref))).then(
+      () => undefined
+    );
+  }
+
+  private async runPreflight(ref: CursorAccountConnectionRef): Promise<void> {
+    try {
+      const catalog = await this.getCatalog(ref);
+      if (catalog.servers.length === 0) {
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the \`servers\` filter`
+        );
+        return;
+      }
+
+      const errorDetails = new Map<string, string>();
+      await Promise.all(
+        catalog.servers
+          .filter((server) => server.status === "error")
+          .map(async (server) => {
+            const detail = await diagnoseConnectorError(
+              this.client,
+              server.serverIdentifier
             );
-          }
-        })
-        .catch((error: unknown) => {
-          this.logger(
-            `[agentkit] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
-          );
-        });
+            if (detail !== undefined) {
+              errorDetails.set(server.serverIdentifier, detail);
+            }
+          })
+      );
+
+      const summary = catalog.servers
+        .map((server) =>
+          formatServerStatusSummary(
+            server,
+            errorDetails.get(server.serverIdentifier)
+          )
+        )
+        .join(", ");
+      this.logger(
+        `[agentkit] Cursor account MCP connection "${ref.name}": ${summary}`
+      );
+
+      const needsAuth = catalog.servers.filter(
+        (server) => server.status === "needsAuth"
+      );
+      if (needsAuth.length > 0) {
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": ${needsAuth
+            .map((server) => server.serverIdentifier)
+            .join(
+              ", "
+            )} need re-authorization in Cursor (dashboard → MCP / Settings → MCP) before their tools appear`
+        );
+      }
+
+      const errored = catalog.servers.filter(
+        (server) => server.status === "error"
+      );
+      if (errored.length > 0) {
+        const details = errored
+          .map((server) => {
+            const detail = errorDetails.get(server.serverIdentifier);
+            return detail === undefined
+              ? server.serverIdentifier
+              : `${server.serverIdentifier} (${detail})`;
+          })
+          .join("; ");
+        this.logger(
+          `[agentkit] Cursor account MCP connection "${ref.name}": ${details} — Cursor backend could not use this connector (not a missing agentkit login). Re-check the server in Cursor dashboard → MCP, confirm the URL is healthy, and retry after the backend can reach it`
+        );
+      }
+    } catch (error: unknown) {
+      this.logger(
+        `[agentkit] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
+      );
     }
   }
 
@@ -283,13 +324,22 @@ export class CursorAccountMcpBridge {
       const tool = await this.findTool(ref, request.params.name);
       if (tool === undefined) {
         const catalog = await this.getCatalog(ref);
+        const unhealthy = catalog.servers.filter(
+          (server) => server.status !== "connected"
+        );
+        const statusHint =
+          unhealthy.length === 0
+            ? ""
+            : ` Unhealthy connectors: ${unhealthy
+                .map((server) => `${server.serverIdentifier}=${server.status}`)
+                .join(", ")}.`;
         return {
           content: [
             {
               type: "text",
               text: `Unknown tool "${request.params.name}". Available: ${
                 catalog.tools.map((t) => t.exposedName).join(", ") || "(none)"
-              }.`,
+              }.${statusHint}`,
             },
           ],
           isError: true,
@@ -470,3 +520,65 @@ function trimTrailingSlash(url: string): string {
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+/** One-line status for the preflight summary (`name (12 tools)` / `name (error: …)`). */
+export function formatServerStatusSummary(
+  server: AccountMcpServer,
+  errorDetail?: string
+): string {
+  switch (server.status) {
+    case "connected":
+      return `${server.serverIdentifier} (${server.tools.length} tools)`;
+    case "needsAuth":
+      return `${server.serverIdentifier} (needsAuth — re-authorize in Cursor)`;
+    case "loading":
+      return `${server.serverIdentifier} (loading)`;
+    case "error": {
+      const detail =
+        errorDetail === undefined || errorDetail.trim() === ""
+          ? "backend could not reach connector"
+          : errorDetail.trim();
+      return `${server.serverIdentifier} (error: ${detail})`;
+    }
+    default:
+      return `${server.serverIdentifier} (${server.status})`;
+  }
+}
+
+/**
+ * Best-effort detail for an `error`-status connector. ListSandMcpTools only
+ * returns the status enum today, so probe ExecuteSandMcpTool (ping) and surface
+ * the backend failure text (e.g. `HTTP MCP tool execution failed: fetch failed`).
+ */
+export async function diagnoseConnectorError(
+  client: Pick<CursorBackendClient, "executeAccountMcpTool">,
+  serverIdentifier: string
+): Promise<string | undefined> {
+  try {
+    const result = await client.executeAccountMcpTool({
+      serverIdentifier,
+      // Conventional health tool; even a tool-not-found path usually still
+      // surfaces the same transport failure when the connector is down.
+      toolName: `${serverIdentifier}-ping`,
+      args: {},
+    });
+    const text = result.content
+      .filter(
+        (part): part is { type: "text"; text: string } => part.type === "text"
+      )
+      .map((part) => part.text.trim())
+      .filter((part) => part.length > 0)
+      .join(" ");
+    if (result.isError) {
+      return text.length > 0
+        ? text
+        : "backend reported an error with no detail";
+    }
+    // Listing said error but ping succeeded — surface that inconsistency.
+    return text.length > 0
+      ? `listing reported error but probe succeeded: ${text}`
+      : "listing reported error but probe succeeded";
+  } catch (error: unknown) {
+    return describeError(error);
+  }
+}

package/src/internal/cursor-event-relay.ts

@@ -25,6 +25,8 @@ export type CursorScmPullRequestMeta = {
   title?: string;
   body?: string | null;
   draft?: boolean;
+  /** True when the PR was merged — required by closed+merged channel hooks. */
+  merged?: boolean;
   authorLogin?: string;
   headRef?: string;
   headSha?: string;
@@ -163,6 +165,9 @@ export function scmMetadataToGitHubPayload(event: {
       head: { ref: headRef, sha: headSha },
       base: { ref: baseRef, sha: prMeta?.baseSha },
     };
+    if (prMeta?.merged !== undefined) {
+      pullRequest.merged = prMeta.merged;
+    }
     if (prMeta?.authorLogin !== undefined) {
       pullRequest.user = { login: prMeta.authorLogin };
     }

package/src/internal/discovery.ts

@@ -21,6 +21,7 @@ import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
 import { httpChannel } from "../channels.js";
 import type { StorageDefinition } from "../storage.js";
 import {
+  type AgentConcurrencyOptions,
   type AgentConfigDefinition,
   type AgentHostingOptions,
   type AgentProject,
@@ -40,6 +41,7 @@ import {
   type HookDefinition,
   type HttpChannelDefinition,
   type InstructionsDefinition,
+  MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
   type ResolvedAgent,
   type ScheduleDefinition,
@@ -50,6 +52,7 @@ import {
   toPublicCloudInfo,
 } from "../types.js";
 import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
+import { normalizePositiveInt } from "./bounded-int.js";
 import { getDefinitionKind } from "./brand.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
@@ -372,6 +375,7 @@ async function loadAgent(
           cwd: localCwd,
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
+  const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -393,6 +397,7 @@ async function loadAgent(
     cloud,
     local,
     hosting,
+    concurrency,
     tools,
     skills,
     connections,
@@ -469,6 +474,37 @@ function resolveHosting(
   };
 }
 
+/**
+ * Validate the authored `concurrency` block. Invalid values are **error**
+ * diagnostics (serve refuses to start): silently dropping a turn ceiling
+ * would fail open to unlimited parallelism, the opposite of what the
+ * author asked for.
+ */
+function resolveConcurrency(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  concurrency: AgentConcurrencyOptions | undefined
+): AgentConcurrencyOptions | undefined {
+  if (concurrency === undefined || concurrency.maxRunningTurns === undefined) {
+    return undefined;
+  }
+  try {
+    return {
+      maxRunningTurns: normalizePositiveInt(concurrency.maxRunningTurns, {
+        label: "concurrency.maxRunningTurns",
+        max: MAX_RUNNING_TURNS_LIMIT,
+      }),
+    };
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+}
+
 async function loadAgentConfig(
   ctx: DiscoveryContext,
   agentDir: string,
@@ -831,11 +867,24 @@ function connectionTransportLabel(transport: ConnectionTransport): string {
     return `agent:${transport.agent}`;
   }
   if ("url" in transport) {
-    return transport.url;
+    return transport.oauth === true
+      ? `${transport.url} (oauth)`
+      : transport.url;
   }
   return transport.command;
 }
 
+function hasAuthorizationHeader(
+  headers: Record<string, string> | undefined
+): boolean {
+  if (headers === undefined) {
+    return false;
+  }
+  return Object.keys(headers).some(
+    (key) => key.toLowerCase() === "authorization"
+  );
+}
+
 function connectionTransport(
   connection: ConnectionDefinition
 ): ConnectionTransport | undefined {
@@ -852,11 +901,10 @@ function connectionTransport(
   }
   if ("url" in connection && !isBlank(connection.url)) {
     return {
-      ...(connection.type === undefined ? {} : { type: connection.type }),
+      type: connection.type,
       url: connection.url,
-      ...(connection.headers === undefined
-        ? {}
-        : { headers: connection.headers }),
+      headers: connection.headers,
+      oauth: connection.oauth === true ? true : undefined,
     };
   }
   if ("command" in connection && !isBlank(connection.command)) {
@@ -974,6 +1022,19 @@ async function loadConnections(
       continue;
     }
     const connection = definition as ConnectionDefinition;
+    if (
+      "url" in connection &&
+      connection.oauth === true &&
+      hasAuthorizationHeader(connection.headers)
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          "MCP connection `oauth: true` cannot set an Authorization header. Drop the header or remove `oauth`.",
+      });
+      continue;
+    }
     const transport = connectionTransport(connection);
     if (transport === undefined) {
       ctx.diagnostics.push({
@@ -1009,9 +1070,8 @@ async function loadConnections(
     connections.push({
       name,
       transport,
-      ...(connection.description === undefined
-        ? {}
-        : { description: connection.description }),
+      description: connection.description,
+      hostOnly: connection.hostOnly,
     });
   }
   return connections;
@@ -1529,6 +1589,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
     local: agent.local,
     hosting: agent.hosting,
+    concurrency: agent.concurrency,
     mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
     instructions:
       agent.instructions === undefined
@@ -1554,6 +1615,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     connections: agent.connections.map((connection) => ({
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
+      hostOnly: connection.hostOnly,
     })),
     subagents: agent.subagents.map((subagent) => ({
       name: subagent.name,