@cursor/july 0.1.96 → 0.1.99

package/src/internal/init-project.ts

@@ -74,6 +74,7 @@ type TemplateEntry = {
 
 const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
+  "agents-md": { dir: "agents-md" },
   "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
@@ -711,6 +712,7 @@ Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
   npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
+  npx ${PACKAGE_NAME} init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
   npx ${PACKAGE_NAME} init ./security-help --template security-help   # answer security questions in Slack
   npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues

package/src/internal/logs-client.ts

@@ -114,6 +114,11 @@ export function sanitizeCustomerError(message: string): string {
 /**
  * One-line label for `agent-sdk deploy` polling (TTY spinner / non-TTY
  * transitions). Uses statusMessage → progress → raw status.
+ *
+ * Deliberately does NOT include `lastError`. The spinner redraws with
+ * `\r\x1b[2K`, which clears one physical row, so a reason long enough to
+ * soft-wrap would leave the earlier rows on screen. Callers print the
+ * reason once on the final line instead.
  */
 export function deployProgressLabel(detail: {
   status: string;

package/src/internal/mcp-endpoint.ts

@@ -293,7 +293,11 @@ function buildConnectionBridgeMcpServer(
     if (reason !== undefined) {
       throw new Error(reason);
     }
-    const tools = await engine.host.mcp.listTools(connectionName);
+    const tools = await engine.runWithMcpPark(
+      sessionId ?? "",
+      "tools/list",
+      () => engine.host.mcp.listTools(connectionName)
+    );
     return {
       tools: tools.map((tool) => ({
         name: tool.name,
@@ -327,10 +331,15 @@ function buildConnectionBridgeMcpServer(
       return sdkResultToMcpResult(answer.result);
     }
     try {
-      const result = await engine.host.mcp.callTool(
-        connectionName,
+      const result = await engine.runWithMcpPark(
+        sessionId ?? "",
         request.params.name,
-        request.params.arguments ?? {}
+        () =>
+          engine.host.mcp.callTool(
+            connectionName,
+            request.params.name,
+            request.params.arguments ?? {}
+          )
       );
       return {
         // The host client already speaks MCP, so the content array is valid

package/src/internal/mcp-host.ts

@@ -26,6 +26,47 @@ import type {
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
 
+export class McpNeedsAuthError extends Error {
+  readonly connection: string;
+
+  constructor(connection: string, cause?: unknown) {
+    super(
+      `MCP connection "${connection}" needs authorization. Run \`${CLI} mcp oauth ${connection}\`.`
+    );
+    this.name = "McpNeedsAuthError";
+    this.connection = connection;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+export function isMcpNeedsAuthError(
+  error: unknown
+): error is McpNeedsAuthError {
+  return error instanceof McpNeedsAuthError;
+}
+
+export function hostMcpCallNeedsAuth(result: HostMcpCallResult): boolean {
+  if (result.isError !== true) {
+    return false;
+  }
+  const text = result.content
+    .map((part) => (part.type === "text" ? part.text : ""))
+    .join("\n");
+  return text.includes("needsAuth") || text.includes("needs authorization");
+}
+
+function throwIfCallNeedsAuth(
+  connection: string,
+  result: HostMcpCallResult
+): HostMcpCallResult {
+  if (hostMcpCallNeedsAuth(result)) {
+    throw new McpNeedsAuthError(connection);
+  }
+  return result;
+}
+
 interface OpenedConnection {
   client: Client;
   close: () => Promise<void>;
@@ -46,6 +87,7 @@ export interface HostMcpOneOff {
 export class McpHost implements HostMcpRegistry {
   private readonly byName = new Map<string, DiscoveredConnection>();
   private readonly clients = new Map<string, Promise<OpenedConnection>>();
+  private oauthRedirectUrl: string | undefined;
 
   constructor(connections: DiscoveredConnection[]) {
     for (const connection of connections) {
@@ -53,6 +95,11 @@ export class McpHost implements HostMcpRegistry {
     }
   }
 
+  /** Public serve callback for host OAuth (not the CLI loopback port on pods). */
+  setOAuthRedirectUrl(url: string): void {
+    this.oauthRedirectUrl = url;
+  }
+
   /**
    * Register a connection after construction (serve-time resolved peers).
    * Clients open lazily on first use, so adding before first call is safe.
@@ -82,10 +129,11 @@ export class McpHost implements HostMcpRegistry {
    * mapping as registry calls.
    */
   oneOff(connection: DiscoveredConnection): HostMcpOneOff {
+    const redirectUrl = this.oauthRedirectUrl;
     const withFreshClient = async <T>(
       run: (client: Client) => Promise<T>
     ): Promise<T> => {
-      const opened = await openConnection(connection);
+      const opened = await openConnection(connection, redirectUrl);
       try {
         return await run(opened.client);
       } finally {
@@ -104,7 +152,10 @@ export class McpHost implements HostMcpRegistry {
             name: toolName,
             arguments: args,
           });
-          return normalizeCallResult(result);
+          return throwIfCallNeedsAuth(
+            connection.name,
+            normalizeCallResult(result)
+          );
         }),
     };
   }
@@ -119,10 +170,23 @@ export class McpHost implements HostMcpRegistry {
         name: toolName,
         arguments: args,
       });
-      return normalizeCallResult(result);
+      return throwIfCallNeedsAuth(connectionName, normalizeCallResult(result));
     });
   }
 
+  async dropClient(name: string): Promise<void> {
+    const pending = this.clients.get(name);
+    this.clients.delete(name);
+    if (pending === undefined) {
+      return;
+    }
+    try {
+      await (await pending).close();
+    } catch {
+      // Best-effort teardown.
+    }
+  }
+
   async close(): Promise<void> {
     const opened = await Promise.allSettled([...this.clients.values()]);
     this.clients.clear();
@@ -198,7 +262,7 @@ export class McpHost implements HostMcpRegistry {
         `Unknown MCP connection "${name}". Authored MCP connections: ${known}.`
       );
     }
-    return openConnection(connection);
+    return openConnection(connection, this.oauthRedirectUrl);
   }
 }
 
@@ -283,13 +347,14 @@ function toToolInfo(tool: {
 }
 
 async function openConnection(
-  connection: DiscoveredConnection
+  connection: DiscoveredConnection,
+  oauthRedirectUrl?: string
 ): Promise<OpenedConnection> {
   const client = new Client({
     name: "agent-serve",
     version: "0.1.0",
   });
-  const transport = await createTransport(connection);
+  const transport = await createTransport(connection, oauthRedirectUrl);
   try {
     await client.connect(transport);
   } catch (error) {
@@ -297,10 +362,7 @@ async function openConnection(
       error instanceof UnauthorizedError &&
       isOauthHttpTransport(connection.transport)
     ) {
-      throw new Error(
-        `MCP connection "${connection.name}" needs authorization. Run \`${CLI} mcp oauth ${connection.name}\`.`,
-        { cause: error }
-      );
+      throw new McpNeedsAuthError(connection.name, error);
     }
     throw error;
   }
@@ -322,7 +384,10 @@ async function openConnection(
   };
 }
 
-async function createTransport(connection: DiscoveredConnection) {
+async function createTransport(
+  connection: DiscoveredConnection,
+  oauthRedirectUrl?: string
+) {
   const transport = connection.transport;
   if ("agent" in transport) {
     // Peers are resolved to concrete URLs by the serve host before any call
@@ -365,6 +430,7 @@ async function createTransport(connection: DiscoveredConnection) {
       ? await createHostMcpOAuthProvider({
           identifier: connection.name,
           resourceUrl: transport.url,
+          redirectUrl: oauthRedirectUrl,
         })
       : undefined;
 

package/src/internal/mcp-oauth-on-demand.ts

@@ -0,0 +1,352 @@
+/**
+ * Mid-run host MCP OAuth: mint an authUrl, finish on the public serve
+ * callback (file tokens). Deployment secrets persist from the
+ * authenticated park, not from that callback.
+ *
+ * CLI `mcp oauth` still uses the loopback callback. This path is recovery
+ * and first-use without a separate `--store` step.
+ */
+
+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 { describeError } from "./describe-error.js";
+import { LOG_PREFIX } from "./distribution.js";
+import {
+  createHostMcpOAuthProvider,
+  FileMcpOAuthStore,
+  MCP_OAUTH_CALLBACK_URL,
+} from "./mcp-oauth.js";
+import {
+  type McpOauthSecretsTarget,
+  type ResolveHostedMcpOauthSecretsArgs,
+  resolveHostedMcpOauthSecretsTarget,
+  upsertHostMcpOauthSecrets,
+} from "./mcp-oauth-persist.js";
+
+export function mcpOauthServeCallbackPath(basePath = ""): string {
+  return `${basePath}/v1/mcp-oauth/callback`;
+}
+
+export function mcpOauthServeCallbackUrl(
+  origin: string,
+  basePath = ""
+): string {
+  return `${origin.replace(/\/$/, "")}${mcpOauthServeCallbackPath(basePath)}`;
+}
+
+export type BeginHostMcpOauthResult =
+  | { status: "authorized" }
+  | {
+      status: "needs_auth";
+      authUrl: string;
+      state: string;
+      finish: (code: string) => Promise<void>;
+      abort: () => Promise<void>;
+    };
+
+export async function beginHostMcpOauth(args: {
+  connection: string;
+  url: string;
+  type?: "http" | "sse";
+  headers?: Record<string, string>;
+  redirectUrl: string;
+  store?: FileMcpOAuthStore;
+}): Promise<BeginHostMcpOauthResult> {
+  let authorizationUrl: URL | undefined;
+  const provider = await createHostMcpOAuthProvider({
+    identifier: args.connection,
+    resourceUrl: args.url,
+    store: args.store,
+    redirectUrl: args.redirectUrl,
+    onRedirect: (url) => {
+      authorizationUrl = url;
+    },
+  });
+
+  const client = new Client({ name: "agent-sdk-mcp-oauth", version: "0.1.0" });
+  const url = new URL(args.url);
+  const requestInit =
+    args.headers === undefined ? undefined : { headers: args.headers };
+
+  const makeTransport = ():
+    | StreamableHTTPClientTransport
+    | SSEClientTransport => {
+    if (args.type === "sse") {
+      return new SSEClientTransport(url, {
+        authProvider: provider,
+        requestInit,
+      });
+    }
+    return new StreamableHTTPClientTransport(url, {
+      authProvider: provider,
+      requestInit,
+    });
+  };
+
+  const transport = makeTransport();
+  try {
+    await client.connect(transport);
+    await client.close().catch(() => undefined);
+    return { status: "authorized" };
+  } catch (error) {
+    if (!(error instanceof UnauthorizedError)) {
+      throw error;
+    }
+  }
+
+  const redirect = authorizationUrl ?? provider.lastRedirectUrl;
+  if (redirect === undefined) {
+    throw new Error(
+      `Auth required for "${args.connection}" but no authorization URL was provided.`
+    );
+  }
+  const state = redirect.searchParams.get("state") ?? "";
+  if (state === "") {
+    throw new Error(
+      `Auth required for "${args.connection}" but the authorization URL had no state.`
+    );
+  }
+
+  return {
+    status: "needs_auth",
+    authUrl: redirect.toString(),
+    state,
+    finish: async (code: string) => {
+      await transport.finishAuth(code);
+      await transport.close?.().catch(() => undefined);
+    },
+    abort: async () => {
+      await transport.close?.().catch(() => undefined);
+    },
+  };
+}
+
+type BoundAttempt = {
+  connection: string;
+  resourceUrl: string;
+  finish: (code: string) => Promise<void>;
+  abort: () => Promise<void>;
+  sessionId?: string;
+  callId?: string;
+};
+
+export type McpOauthCompleteResult = {
+  connection: string;
+  sessionId?: string;
+  callId?: string;
+};
+
+export class McpOauthOnDemandHub {
+  private readonly attempts = new Map<string, BoundAttempt>();
+  private readonly completed = new Map<string, BoundAttempt>();
+  private readonly finishing = new Map<
+    string,
+    Promise<McpOauthCompleteResult>
+  >();
+  private readonly aborted = new Set<string>();
+  callbackUrl: string | undefined;
+  secrets?: McpOauthSecretsTarget;
+  // Identity only — resolve the key at persist, after freeze bind.
+  secretsBind?: ResolveHostedMcpOauthSecretsArgs;
+  logger?: (line: string) => void;
+  private store?: FileMcpOAuthStore;
+
+  async mint(args: {
+    connection: string;
+    url: string;
+    type?: "http" | "sse";
+    headers?: Record<string, string>;
+    sessionId?: string;
+  }): Promise<{ authUrl: string; state: string } | { authorized: true }> {
+    const redirectUrl = this.callbackUrl ?? MCP_OAUTH_CALLBACK_URL;
+    const store = this.fileStore();
+    const started = await beginHostMcpOauth({
+      connection: args.connection,
+      url: args.url,
+      type: args.type,
+      headers: args.headers,
+      redirectUrl,
+      store,
+    });
+    if (started.status === "authorized") {
+      return { authorized: true };
+    }
+    this.attempts.set(started.state, {
+      connection: args.connection,
+      resourceUrl: args.url,
+      finish: started.finish,
+      abort: started.abort,
+      sessionId: args.sessionId,
+    });
+    return { authUrl: started.authUrl, state: started.state };
+  }
+
+  async abortCall(sessionId: string, callId: string): Promise<void> {
+    await this.dropWhere(
+      (attempt) => attempt.sessionId === sessionId && attempt.callId === callId,
+      true
+    );
+  }
+
+  async abortSession(sessionId: string): Promise<void> {
+    await this.dropWhere((attempt) => attempt.sessionId === sessionId, false);
+  }
+
+  async close(): Promise<void> {
+    await this.dropWhere(() => true, true);
+  }
+
+  private async dropWhere(
+    match: (attempt: BoundAttempt) => boolean,
+    includeCompleted: boolean
+  ): Promise<void> {
+    const jobs: Array<Promise<void>> = [];
+    for (const [state, attempt] of this.attempts) {
+      if (!match(attempt)) {
+        continue;
+      }
+      this.aborted.add(state);
+      this.attempts.delete(state);
+      jobs.push(attempt.abort().catch(() => undefined));
+    }
+    if (includeCompleted) {
+      for (const [state, attempt] of this.completed) {
+        if (!match(attempt)) {
+          continue;
+        }
+        this.aborted.add(state);
+        this.completed.delete(state);
+      }
+    }
+    await Promise.all(jobs);
+  }
+
+  bind(
+    state: string,
+    sessionId: string,
+    callId: string
+  ): "pending" | "already_done" | "unknown" {
+    const live = this.attempts.get(state);
+    if (live !== undefined) {
+      live.sessionId = sessionId;
+      live.callId = callId;
+      return "pending";
+    }
+    const done = this.completed.get(state);
+    if (done !== undefined) {
+      done.sessionId = sessionId;
+      done.callId = callId;
+      return "already_done";
+    }
+    return "unknown";
+  }
+
+  async complete(state: string, code: string): Promise<McpOauthCompleteResult> {
+    if (this.aborted.has(state)) {
+      throw new Error("Unknown OAuth state.");
+    }
+    const pending = this.finishing.get(state);
+    if (pending !== undefined) {
+      return await pending;
+    }
+    const attempt = this.attempts.get(state);
+    if (attempt === undefined) {
+      throw new Error("Unknown OAuth state.");
+    }
+    const run = this.finishAttempt(state, attempt, code);
+    this.finishing.set(state, run);
+    return await run;
+  }
+
+  private async finishAttempt(
+    state: string,
+    attempt: BoundAttempt,
+    code: string
+  ): Promise<McpOauthCompleteResult> {
+    try {
+      await attempt.finish(code);
+      this.attempts.delete(state);
+      if (!this.aborted.has(state)) {
+        this.completed.set(state, attempt);
+      }
+      return {
+        connection: attempt.connection,
+        sessionId: attempt.sessionId,
+        callId: attempt.callId,
+      };
+    } finally {
+      this.finishing.delete(state);
+    }
+  }
+
+  private fileStore(): FileMcpOAuthStore {
+    this.store ??= new FileMcpOAuthStore();
+    return this.store;
+  }
+
+  async persistFor(connection: string, resourceUrl: string): Promise<void> {
+    const target =
+      this.secrets ??
+      resolveHostedMcpOauthSecretsTarget(this.secretsBind ?? {});
+    if (target === undefined) {
+      return;
+    }
+    const store = this.fileStore();
+    const tokens = await store.loadTokens(connection, resourceUrl);
+    if (tokens === undefined || tokens.access_token.trim() === "") {
+      return;
+    }
+    const client = await store.loadClientInformation(connection, resourceUrl);
+    try {
+      const names = await upsertHostMcpOauthSecrets({
+        connection,
+        tokens,
+        clientId: client?.client_id,
+        target,
+      });
+      this.logger?.(
+        `${LOG_PREFIX} MCP OAuth tokens stored on the deployment (${names.join(", ")}).`
+      );
+    } catch (error) {
+      this.logger?.(
+        `${LOG_PREFIX} MCP OAuth persist failed for "${connection}": ${describeError(error)}`
+      );
+    }
+  }
+
+  async handleCallback(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state") ?? "";
+    if (this.aborted.has(state)) {
+      return oauthHtml(404, "<h1>Not found</h1>");
+    }
+    if (this.completed.has(state)) {
+      return oauthHtml(200, "<h1>Authorized</h1><p>Return to the agent.</p>");
+    }
+    if (!this.attempts.has(state)) {
+      return oauthHtml(404, "<h1>Not found</h1>");
+    }
+    if (code !== null && code !== "") {
+      try {
+        await this.complete(state, code);
+      } catch {
+        return oauthHtml(400, "<h1>Authorization failed</h1>");
+      }
+      if (this.aborted.has(state)) {
+        return oauthHtml(404, "<h1>Not found</h1>");
+      }
+      return oauthHtml(200, "<h1>Authorized</h1><p>Return to the agent.</p>");
+    }
+    return oauthHtml(400, "<h1>Authorization failed</h1>");
+  }
+}
+
+function oauthHtml(status: number, body: string): Response {
+  return new Response(`<!doctype html><html><body>${body}</body></html>`, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}