@cursor/july 0.1.93 → 0.1.95

package/src/index.ts

@@ -182,7 +182,9 @@ export {
   isCursorAccountTransport,
   isPeerConnectionTransport,
   isSymbolicConnectionTransport,
+  isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
+  normalizeConnectionEffects,
   normalizeCursorAccountServers,
   supportsKvCas,
 } from "./types.js";

package/src/internal/advertise-tools.ts

@@ -23,6 +23,10 @@
  * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
  * still fails the turn rather than running it with a silently shrunken
  * toolset.
+ *
+ * `defineConnection({ effects })` filters the listing before names are
+ * assigned: only tools whose MCP annotations classify as an intended
+ * effect are advertised. Unclassified tools are omitted, not guessed.
  */
 
 import type {
@@ -31,9 +35,11 @@ import type {
   HostMcpCallResult,
   HostMcpToolInfo,
   JsonSchemaObject,
+  McpToolAnnotations,
   ResolvedAgent,
   SessionInfo,
   ToolDefinition,
+  ToolEffect,
 } from "../types.js";
 import { brandDefinition } from "./brand.js";
 import type { HostMcpOneOff } from "./mcp-host.js";
@@ -41,6 +47,7 @@ import {
   sanitizeMcpToolName,
   suffixMcpToolName,
 } from "./sanitize-mcp-tool-name.js";
+import { classifyAnnotationsEffect } from "./tool-policy.js";
 
 /**
  * What the resolver needs from the host MCP registry: the shared cached
@@ -88,6 +95,13 @@ export async function resolveAdvertisedTools(args: {
   agent: ResolvedAgent;
   session: SessionInfo;
   hostMcp: AdvertiseHostMcp;
+  /**
+   * When set, a connection whose source or listing fails is reported here
+   * and skipped instead of throwing. Turns keep the throwing default (a
+   * turn must fail closed); the inspection catalog passes this so one
+   * broken connector does not hide every other tool.
+   */
+  onConnectionError?: (connection: string, error: unknown) => void;
   /** Test seam; defaults to {@link sourceForConnection}. */
   sourceFor?: (
     connection: DiscoveredConnection,
@@ -105,17 +119,25 @@ export async function resolveAdvertisedTools(args: {
   const claimed = new Set(args.agent.tools.map((tool) => tool.name));
   const resolved: DiscoveredTool[] = [];
   for (const connection of advertising) {
-    const source = await sourceFor(connection, args.session, args.hostMcp);
     let listed: HostMcpToolInfo[];
+    let source: AdvertisedToolSource;
     try {
+      source = await sourceFor(connection, args.session, args.hostMcp);
       listed = await source.listTools();
     } catch (error) {
+      if (args.onConnectionError !== undefined) {
+        args.onConnectionError(connection.name, error);
+        continue;
+      }
       throw new Error(
         `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
         { cause: error }
       );
     }
-    const exposed = exposeListedTools(listed, claimed);
+    const intended = listed.filter((info) =>
+      matchesIntendedEffects(info.annotations, connection.effects)
+    );
+    const exposed = exposeListedTools(intended, claimed);
     for (const { info, exposedName } of exposed) {
       resolved.push(toDiscoveredTool(connection, info, exposedName, source));
       claimed.add(exposedName);
@@ -210,6 +232,17 @@ function exposeListedTools(
   }));
 }
 
+function matchesIntendedEffects(
+  annotations: McpToolAnnotations | undefined,
+  effects: readonly ToolEffect[] | undefined
+): boolean {
+  if (effects === undefined) {
+    return true;
+  }
+  const effect = classifyAnnotationsEffect(annotations);
+  return effect !== undefined && effects.includes(effect);
+}
+
 function toDiscoveredTool(
   connection: DiscoveredConnection,
   info: HostMcpToolInfo,
@@ -222,10 +255,15 @@ function toDiscoveredTool(
       : info.description;
   const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
   const outputSchema = info.outputSchema;
+  const effect =
+    connection.effects === undefined
+      ? undefined
+      : classifyAnnotationsEffect(info.annotations);
   const definition: ToolDefinition = brandDefinition("tool", {
     description,
     inputSchema,
-    ...(outputSchema === undefined ? {} : { outputSchema }),
+    outputSchema,
+    effect,
     execute: async (input: Record<string, unknown>) =>
       formatMcpToolResult(
         connection.name,
@@ -237,16 +275,16 @@ function toDiscoveredTool(
     name: exposedName,
     description,
     inputSchema,
-    ...(outputSchema === undefined ? {} : { outputSchema }),
+    outputSchema,
     execution: "server",
     needsApproval: false,
+    effect,
     // The server's own annotations ride along (bounded at listing time), so
     // the harness listing carries them and effect classification can read
     // them. Absent stays absent — the fail-closed state.
-    ...(info.annotations === undefined
-      ? {}
-      : { annotations: info.annotations }),
+    annotations: info.annotations,
     advertised: true,
+    connection: connection.name,
     definition,
   };
 }

package/src/internal/cli-deploy.ts

@@ -27,6 +27,7 @@ import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   type AgentkitDeployAccepted,
+  type AgentkitDeployComponent,
   type AgentkitDeployStatus,
   type AgentkitStopAccepted,
   AgentServeDeployClient,
@@ -294,10 +295,35 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     return targets;
   }
 
+  if (targets.length === 1) {
+    return deployOne(ctx, options, targets[0]!);
+  }
+
+  // Multi-agent parent: when every child declares `architecture: "v2"`,
+  // the v2 control plane models sibling agents as release components of
+  // ONE application, so deploy them together (one app, one component per
+  // child) instead of minting a separate application per child. Mixed and
+  // v1 parents keep the per-child sequential deploys.
+  const manifests: DeployManifest[] = [];
+  for (const target of targets) {
+    manifests.push(await readDeployManifest(target.dir));
+  }
+  if (manifests.every((manifest) => manifest.architecture === "v2")) {
+    return deployAgentsdkApplication(ctx, options, targets);
+  }
+  if (
+    !ctx.json &&
+    manifests.some((manifest) => manifest.architecture === "v2")
+  ) {
+    ctx.err(
+      `warning: agents under this parent mix architectures; deploying each separately (v2 children become standalone single-component applications).\n`
+    );
+  }
+
   // --path is per-agent (relative to the repo root). When deploying several
   // agents, ignore a shared --path so each target can infer its own path.
   let deployOptions = options;
-  if (targets.length > 1 && options.path !== undefined) {
+  if (options.path !== undefined) {
     if (!ctx.json) {
       ctx.err(
         `warning: ignoring --path ${JSON.stringify(options.path)} for a multi-agent deploy; each agent infers its own path from git.\n`
@@ -306,10 +332,6 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     deployOptions = { ...options, path: undefined };
   }
 
-  if (targets.length === 1) {
-    return deployOne(ctx, deployOptions, targets[0]!);
-  }
-
   // Multi-agent batch: deploy sequentially; --json emits an array.
   const jsonResults: unknown[] = [];
   let failures = 0;
@@ -477,6 +499,19 @@ async function resolveDeployTargets(
     return [match];
   }
 
+  // An all-v2 parent deploys as ONE application (siblings are components
+  // of a single app on the v2 control plane), so "deploy the parent" is
+  // unambiguous and needs no picker or --all. A child that is v1 — or
+  // fails to load — keeps the interactive picker below.
+  if (await allChildrenAreV2(children)) {
+    if (!ctx.json) {
+      ctx.err(
+        `Deploying all ${children.length} v2 agents under ${basename(dir)} as one application (pass --slug <name> to deploy a single agent standalone).\n`
+      );
+    }
+    return [...children];
+  }
+
   const chooser =
     options.chooseTargets ??
     ((agents) =>
@@ -508,6 +543,27 @@ function formatAgentList(agents: readonly DeployTarget[]): string {
   return agents.map((agent, i) => `  ${i + 1}) ${agent.slug}\n`).join("");
 }
 
+/**
+ * True when every child agent project loads and declares
+ * `architecture: "v2"`. Broken projects count as not-v2 so target
+ * resolution falls back to the picker instead of failing the whole deploy
+ * on a child the user might not even select.
+ */
+async function allChildrenAreV2(
+  children: readonly DeployTarget[]
+): Promise<boolean> {
+  for (const child of children) {
+    try {
+      if ((await readDeployManifest(child.dir)).architecture !== "v2") {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * TTY picker for multi-agent parents. Non-interactive callers get `[]`
  * so {@link resolveDeployTargets} can print the --slug/--all hint.
@@ -777,6 +833,100 @@ async function deployOne(
   return 0;
 }
 
+/**
+ * Multi-agent parent whose children all declare `architecture: "v2"`:
+ * deploy ONE application whose release carries a component per child. The
+ * application slug derives from the parent directory name; each component
+ * key is the child's slug and its path is the child directory relative to
+ * the repo root (a shared --path names the parent's directory in the repo).
+ */
+async function deployAgentsdkApplication(
+  ctx: DeployCliContext,
+  options: DeployCliOptions,
+  targets: readonly DeployTarget[]
+): Promise<number> {
+  const parentDir = resolve(options.dir ?? ".");
+  const slug = slugFromDirectoryName(basename(parentDir));
+  if (slug === undefined) {
+    ctx.err(
+      `Could not derive an application slug from the parent directory name ${JSON.stringify(basename(parentDir))} — rename it (deploy slugs use lowercase letters, digits, '-' or '_').\n`
+    );
+    return 1;
+  }
+
+  const needsGitInference =
+    options.repo === undefined ||
+    options.ref === undefined ||
+    options.path === undefined;
+  const inferred = needsGitInference
+    ? await inferDeployGitSource(parentDir, {
+        ...(options.git === undefined ? {} : { git: options.git }),
+      })
+    : {};
+  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
+  const gitRef = options.ref ?? inferred.gitRef;
+  const parentPath = options.path ?? inferred.agentPath;
+
+  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
+    ctx.err(
+      `Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`
+    );
+    return 1;
+  }
+  if (gitRepoUrl === undefined) {
+    ctx.err(
+      `Could not resolve an https:// git repository URL for this deploy.\n` +
+        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n`
+    );
+    return 1;
+  }
+  for (const repo of options.cursorEventsRepos ?? []) {
+    if (!isValidCursorEventRepo(repo)) {
+      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
+      return 1;
+    }
+  }
+
+  const components: AgentkitDeployComponent[] = targets.map((target) => ({
+    componentKey: target.slug,
+    agentPath: [parentPath, basename(target.dir)]
+      .filter((part): part is string => part !== undefined && part !== "")
+      .join("/"),
+  }));
+
+  if (!ctx.json) {
+    ctx.err(
+      `Deploying "${slug}" as one v2 application with ${targets.length} components (slug from the parent directory name).\n` +
+        `  architecture: v2\n` +
+        `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
+        components
+          .map(
+            (component) =>
+              `  component: ${component.componentKey} (${component.agentPath ?? "."})\n`
+          )
+          .join("")
+    );
+  }
+
+  // Components bake sequentially on the control plane, so the default wait
+  // budget is per component; otherwise a 2+ component deploy routinely hits
+  // the client-side timeout while the server-side deploy is still fine. An
+  // explicitly passed timeout always wins.
+  const waitCtx =
+    options.timeoutMs === undefined
+      ? { ...ctx, timeoutMs: ctx.timeoutMs * targets.length }
+      : ctx;
+
+  return deployOneAgentsdk(waitCtx, undefined, {
+    slug,
+    gitRepoUrl,
+    gitRef,
+    agentPath: undefined,
+    components,
+    repositories: options.cursorEventsRepos,
+  });
+}
+
 /**
  * `architecture: "v2"` deploy: POST `/internal/agentkit/deployments` and
  * poll the matching GET. The v2 accept path starts freeze bake; it does
@@ -790,10 +940,17 @@ async function deployOneAgentsdk(
     gitRepoUrl: string;
     gitRef: string | undefined;
     agentPath: string | undefined;
+    components?: AgentkitDeployComponent[];
     repositories: string[] | undefined;
   }
 ): Promise<number> {
   const { slug } = args;
+  const componentsLine =
+    args.components === undefined
+      ? ""
+      : `  components:  ${args.components
+          .map((component) => component.componentKey)
+          .join(", ")}\n`;
   let accepted: AgentkitDeployAccepted;
   try {
     accepted = await ctx.client.deployAgentkit({
@@ -802,6 +959,7 @@ async function deployOneAgentsdk(
       gitRepoUrl: args.gitRepoUrl,
       gitRef: args.gitRef,
       agentPath: args.agentPath,
+      components: args.components,
       repositories: args.repositories,
     });
   } catch (error) {
@@ -817,7 +975,8 @@ async function deployOneAgentsdk(
       ctx.out(
         `Deploy accepted: ${slug} (team ${ctx.teamId}, v2)\n` +
           `  application: ${accepted.applicationId}\n` +
-          `  release:     ${accepted.releaseId}\n`
+          `  release:     ${accepted.releaseId}\n` +
+          componentsLine
       );
     }
     return 0;
@@ -851,7 +1010,12 @@ async function deployOneAgentsdk(
       `  status:       running\n` +
       `  architecture: v2\n` +
       `  application:  ${detail.applicationId}\n` +
-      `  release:      ${detail.releaseId}\n`
+      `  release:      ${detail.releaseId}\n` +
+      (args.components === undefined
+        ? ""
+        : `  components:   ${args.components
+            .map((component) => component.componentKey)
+            .join(", ")}\n`)
   );
   return 0;
 }

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

@@ -68,13 +68,15 @@ export async function cmdMcpOauth(
   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(
+  const authored = [
+    ...project.agent.connections,
+    ...(project.agent.hostConnections ?? []),
+  ];
+  const connection = authored.find(
     (entry) => entry.name === options.connection
   );
   if (connection === undefined) {
-    const known =
-      project.agent.connections.map((entry) => entry.name).join(", ") ||
-      "(none)";
+    const known = authored.map((entry) => entry.name).join(", ") || "(none)";
     err(
       `${LOG_PREFIX} Unknown MCP connection "${options.connection}". Authored: ${known}.\n`
     );