@cursor/july 0.1.107 → 0.1.108

package/src/internal/cli-cursor.ts

@@ -17,6 +17,7 @@ import {
   revokeMintedUserApiKey,
 } from "./cursor/backend-client.js";
 import {
+  type ApiKeySource,
   clearStoredCredentials,
   credentialsFilePath,
   cursorBackendUrl,
@@ -255,7 +256,7 @@ function formatIdentity(identity: CursorIdentity): string {
   return name === "" ? `${email}${team}` : `${name} <${email}>${team}`;
 }
 
-function describeSource(source: "option" | "env" | "file" | "login"): string {
+function describeSource(source: ApiKeySource): string {
   switch (source) {
     case "option":
       return "explicit --api-key / serve({ apiKey })";
@@ -263,6 +264,8 @@ function describeSource(source: "option" | "env" | "file" | "login"): string {
       return "CURSOR_API_KEY environment variable";
     case "file":
       return "CURSOR_API_KEY_FILE (task bind)";
+    case "service-account":
+      return "CURSOR_SERVICE_ACCOUNT_KEY environment variable";
     case "login":
       return `stored login (${credentialsFilePath()})`;
   }

package/src/internal/cli-deploy.ts

@@ -11,7 +11,7 @@
  */
 
 import { basename, resolve } from "node:path";
-import { isPublicEndpointPolicy } from "../channels.js";
+import { catchAuthDeclaration, isPublicEndpointPolicy } from "../channels.js";
 import {
   type AgentArchitecture,
   type AgentHostingOptions,
@@ -62,6 +62,10 @@ import {
   isValidCursorEventRepo,
   validateSettableSecretName,
 } from "./hosting.js";
+import {
+  deploymentArchitecture,
+  rejectV2ForLegacyCommand,
+} from "./legacy-command-guard.js";
 import { deployProgressLabel, sanitizeCustomerError } from "./logs-client.js";
 import { sleep } from "./sleep.js";
 import { stderrPalette } from "./terminal-style.js";
@@ -739,6 +743,17 @@ async function deployOne(
       `  public: ${publicRoutePaths.join(", ")} (served WITHOUT the alias token — these channels authenticate requests themselves)\n`
     );
   }
+  const deadSecretChannels =
+    manifest?.publicChannelIdsWithDeadSecretPolicies ?? [];
+  if (!ctx.json && deadSecretChannels.length > 0) {
+    ctx.err(
+      `warning: ${deadSecretChannels
+        .map((channelId) => `/v1/channels/${channelId}`)
+        .join(
+          ", "
+        )}: publicEndpoint() sits beside sharedSecretAuth()/hmacSignatureAuth() — auth chains are any-of, so every request is admitted and those secret policies never run. Drop publicEndpoint() to enforce them, or drop them to make the intent explicit.\n`
+    );
+  }
 
   if (manifest?.architecture === "v2") {
     if (!ctx.json) {
@@ -1192,6 +1207,13 @@ interface DeployManifest {
    * `X-Agent-Alias-Token` (the channel authenticates deliveries itself).
    */
   publicChannelIds: string[];
+  /**
+   * Public channels whose auth chain also carries `sharedSecretAuth` /
+   * `hmacSignatureAuth`. Chains are any-of, so `publicEndpoint()` admits
+   * every request and those secret policies never gate anything — locally
+   * or on the control plane; surfaced as a warning.
+   */
+  publicChannelIdsWithDeadSecretPolicies: string[];
   /**
    * `publicEndpoint()` on the built-in HTTP channel — a no-op on hosting
    * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
@@ -1240,6 +1262,18 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
         (channel.definition.auth ?? []).some(isPublicEndpointPolicy)
       )
       .map((channel) => channel.id),
+    publicChannelIdsWithDeadSecretPolicies: project.channels
+      .filter((channel) => {
+        const auth = channel.definition.auth ?? [];
+        return (
+          auth.some(isPublicEndpointPolicy) &&
+          auth.some((policy) => {
+            const kind = catchAuthDeclaration(policy)?.kind;
+            return kind !== undefined && kind !== "public";
+          })
+        );
+      })
+      .map((channel) => channel.id),
     httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
       isPublicEndpointPolicy
     ),
@@ -1636,6 +1670,11 @@ export async function cmdRotateToken(
   }
   let aliasToken: string;
   try {
+    await rejectV2ForLegacyCommand({
+      client: ctx.client,
+      teamId: ctx.teamId,
+      slug,
+    });
     aliasToken = await ctx.client.rotateAliasToken({
       teamId: ctx.teamId,
       slug,
@@ -1673,6 +1712,11 @@ export async function cmdRotatePodCredential(
   }
   let podCredentialMaskedKey: string;
   try {
+    await rejectV2ForLegacyCommand({
+      client: ctx.client,
+      teamId: ctx.teamId,
+      slug,
+    });
     podCredentialMaskedKey = await ctx.client.rotatePodCredential({
       teamId: ctx.teamId,
       slug,
@@ -1699,15 +1743,11 @@ async function secretDeploymentArchitecture(
   ctx: DeployCliContext,
   slug: string
 ): Promise<"v1" | "v2"> {
-  try {
-    await ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug });
-    return "v2";
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 404) {
-      return "v1";
-    }
-    throw error;
-  }
+  return deploymentArchitecture({
+    client: ctx.client,
+    teamId: ctx.teamId,
+    slug,
+  });
 }
 
 export async function cmdSecretsSet(

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

@@ -20,6 +20,10 @@ import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { deploymentServiceAccountId } from "./deploy-client.js";
 import { loadAgentProject } from "./discovery.js";
 import { CLI_COMMAND_NAME as CLI, LOG_PREFIX } from "./distribution.js";
+import {
+  isUnsupportedV2LegacyCommandError,
+  rejectV2ForLegacyCommand,
+} from "./legacy-command-guard.js";
 import {
   createHostMcpOAuthProvider,
   MCP_OAUTH_CALLBACK_URL,
@@ -290,12 +294,21 @@ async function cmdMcpOauthCursorAccount(
 
   let serviceAccountId: string | undefined;
   try {
+    await rejectV2ForLegacyCommand({
+      client: auth.client,
+      teamId: auth.teamId,
+      slug,
+    });
     const detail = await auth.client.getDeployment({
       teamId: auth.teamId,
       slug,
     });
     serviceAccountId = deploymentServiceAccountId(detail);
   } catch (error) {
+    if (isUnsupportedV2LegacyCommandError(error)) {
+      err(`${LOG_PREFIX} ${error.message}\n`);
+      return 1;
+    }
     err(
       `${LOG_PREFIX} Could not load deployment "${slug}" (team ${auth.teamId}): ${describe(error)}\n` +
         `${LOG_PREFIX} Deploy first with \`${CLI} deploy\`.\n`
@@ -382,6 +395,11 @@ async function storeOauthSecrets(args: {
   }
 
   try {
+    await rejectV2ForLegacyCommand({
+      client: auth.client,
+      teamId: auth.teamId,
+      slug,
+    });
     const secretNames = await upsertHostMcpOauthSecrets({
       connection: args.connection,
       tokens,

package/src/internal/cli-mcp.ts

@@ -32,6 +32,7 @@ import { dirname, join } from "node:path";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { DeployApiError } from "./deploy-client.js";
 import { CLI_COMMAND_NAME as CLI, LOG_PREFIX } from "./distribution.js";
+import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
 import {
   ProdTargetError,
   resolveProdSlug,
@@ -653,6 +654,16 @@ async function cmdMcpInstallRemote(options: McpCliOptions): Promise<number> {
   if (typeof auth === "number") {
     return auth;
   }
+  try {
+    await rejectV2ForLegacyCommand({
+      client: auth.client,
+      teamId: auth.teamId,
+      slug,
+    });
+  } catch (error) {
+    err(`${describeError(error)}\n`);
+    return 1;
+  }
 
   // Verify the deployment resolves before writing config that cannot work.
   // A 403 here is team membership or cloud-agent entitlement, not an

package/src/internal/cli-slack.ts

@@ -20,7 +20,10 @@ import {
   runSlackManifest,
   type SlackCliExec,
 } from "./cli-slack-manual.js";
-import { cursorExternalApiUrl } from "./cursor/credentials.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "./cursor/credentials.js";
 import { slugFromDirectoryName } from "./deploy-client.js";
 import { inferDeployGitSource } from "./deploy-source.js";
 import { describeError } from "./describe-error.js";
@@ -113,7 +116,8 @@ create/destroy/icon — dedicated Socket Mode app via the Cursor dashboard:
   create   Opens the signed-in dashboard wizard. Finish name, workspace,
            and Slack consent there. The CLI writes the token pair into
            <dir>/.env.local and runs doctor. Requires \`${CLI} login\`
-           (or CURSOR_API_KEY). --prod provisions the prod app (default
+           (or CURSOR_API_KEY). A team service-account key cannot
+           provision Slack apps. --prod provisions the prod app (default
            dev). --name / --icon / --channel-posts prefill the wizard.
   destroy  Delete the provisioned Slack app for this agent (+env). Tokens
            already in .env.local are left in place (they just stop working).
@@ -397,6 +401,15 @@ async function prepareProvision(
   const out =
     options.out ?? ((text: string) => void process.stdout.write(text));
   const err = errStream(options);
+  const credential = resolveApiKeySync(
+    options.apiKey === undefined ? undefined : { apiKey: options.apiKey }
+  );
+  if (credential?.source === "service-account") {
+    err(
+      `A team service-account key cannot provision Slack apps. Sign in with \`${CLI} login\` or set CURSOR_API_KEY.\n`
+    );
+    return 1;
+  }
   const auth = await resolveDeployAuth({
     team: options.team,
     apiKey: options.apiKey,

package/src/internal/cursor/credentials.ts

@@ -176,10 +176,15 @@ export async function clearStoredCredentials(): Promise<boolean> {
 }
 
 // ============================================================================
-// Resolution (option > env > file > stored login)
+// Resolution (option > env > file > service account > stored login)
 // ============================================================================
 
-export type ApiKeySource = "option" | "env" | "file" | "login";
+export type ApiKeySource =
+  | "option"
+  | "env"
+  | "file"
+  | "service-account"
+  | "login";
 
 export interface ResolvedApiKey {
   apiKey: string;
@@ -274,10 +279,25 @@ export function consumeBoundCursorApiKey(options?: {
   };
 }
 
+function presentEnvKey(name: string): string | undefined {
+  const value = process.env[name];
+  if (value === undefined) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
 /**
  * First present source wins. We define the order; operators do not.
  * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`
- * (hosted default path if unset) → stored `july login`.
+ * (hosted default path if unset) → `CURSOR_SERVICE_ACCOUNT_KEY` → stored
+ * `july login`.
+ *
+ * A cloud-agent VM often has the service-account key and no user API key.
+ * The explicit key and the hosted bind file still win, so a task credential
+ * is not replaced by the ambient service-account key. The service-account
+ * key wins over a leftover personal login.
  */
 export function resolveApiKeySync(options?: {
   apiKey?: string;
@@ -287,14 +307,22 @@ export function resolveApiKeySync(options?: {
   if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
     return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
   }
-  const envKey = process.env.CURSOR_API_KEY;
-  if (envKey !== undefined && envKey.trim() !== "") {
-    return { apiKey: envKey.trim(), source: "env", backendUrl };
+  const envKey = presentEnvKey("CURSOR_API_KEY");
+  if (envKey !== undefined) {
+    return { apiKey: envKey, source: "env", backendUrl };
   }
   const fileKey = readApiKeyFromFile();
   if (fileKey !== undefined) {
     return { apiKey: fileKey, source: "file", backendUrl };
   }
+  const serviceAccountKey = presentEnvKey("CURSOR_SERVICE_ACCOUNT_KEY");
+  if (serviceAccountKey !== undefined) {
+    return {
+      apiKey: serviceAccountKey,
+      source: "service-account",
+      backendUrl,
+    };
+  }
   const stored = readStoredCredentialsSync();
   if (stored !== undefined && stored.backendUrl === backendUrl) {
     return { apiKey: stored.apiKey, source: "login", backendUrl };
@@ -313,7 +341,7 @@ export async function resolveApiKey(options?: {
 }
 
 /** One-line hint for "no credentials" errors, shared across surfaces. */
-export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / pass serve({ apiKey })).`;
+export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / CURSOR_SERVICE_ACCOUNT_KEY / pass serve({ apiKey })).`;
 
 // ============================================================================
 // PKCE browser login (mirrors cursor-agent / Sand)

package/src/internal/deploy-client.ts

@@ -285,6 +285,21 @@ export interface AgentkitStopAccepted {
   status: string;
 }
 
+/**
+ * `POST /internal/agentsdk/deployments/:slug/sessions` 202 body. A hosted v2
+ * session start is a Temporal delivery: a fresh start allocates `ses_…`
+ * only after admission (poll the session list), so the ack is the delivery
+ * and workflow ids. `sessionId` is present only when the call resumed one.
+ */
+export interface AgentkitStartSessionAccepted {
+  deliveryId: string;
+  workflowId: string;
+  sessionMode: "event" | "continuation";
+  sessionId?: string;
+  dryRun?: true;
+  asOf?: string;
+}
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -373,6 +388,17 @@ const agentkitStopAcceptedSchema = z
   })
   .passthrough();
 
+const agentkitStartSessionAcceptedSchema = z
+  .object({
+    deliveryId: z.string().min(1),
+    workflowId: z.string().min(1),
+    sessionMode: z.enum(["event", "continuation"]),
+    sessionId: z.string().min(1).optional(),
+    dryRun: z.literal(true).optional(),
+    asOf: z.string().min(1).optional(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -691,6 +717,34 @@ export class AgentServeDeployClient {
     return agentkitStopAcceptedSchema.parse(raw);
   }
 
+  /**
+   * Start (or, with `sessionId`, resume) a hosted v2 session through the
+   * control plane (`POST /internal/agentsdk/deployments/:slug/sessions`).
+   * Does not talk to the v1 engine alias or `/engine/*`.
+   */
+  async startSession(args: {
+    teamId: number;
+    slug: string;
+    message: string;
+    sessionId?: string;
+    dryRun?: boolean;
+    asOf?: string;
+  }): Promise<AgentkitStartSessionAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/sessions`,
+      body: {
+        teamId: args.teamId,
+        message: args.message,
+        sessionId: args.sessionId,
+        dryRun: args.dryRun === true ? true : undefined,
+        asOf: args.asOf,
+      },
+      context: { verb: "start session", slug: args.slug },
+    });
+    return agentkitStartSessionAcceptedSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",

package/src/internal/deploy-manifest.ts

@@ -30,7 +30,11 @@
  */
 
 import { z } from "zod";
-import { isPublicEndpointPolicy } from "../channels.js";
+import {
+  type CatchAuthDeclaration,
+  catchAuthDeclaration,
+  isPublicEndpointPolicy,
+} from "../channels.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
@@ -58,6 +62,40 @@ export const DEPLOY_MANIFEST_VERSION: 1 = 1;
  */
 const continuationIdentitySchema = z.enum(CONTINUATION_SELECTORS);
 
+const CATCH_MAX_ROUTES = 32;
+const CATCH_MAX_AUTH_POLICIES = 4;
+
+const catchDeclarationSchema = z.object({
+  routes: z
+    .array(
+      z.object({
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+        path: z.string().min(1).max(1024),
+      })
+    )
+    .min(1)
+    .max(CATCH_MAX_ROUTES),
+  auth: z
+    .array(
+      z.discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("header"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+        }),
+        z.object({
+          kind: z.literal("hmac-sha256"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+          prefix: z.string().max(32).optional(),
+        }),
+        z.object({ kind: z.literal("public") }),
+      ])
+    )
+    .min(1)
+    .max(CATCH_MAX_AUTH_POLICIES),
+});
+
 const agentDeployManifestV1Schema = z.object({
   manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
   generatedAtMs: z.number().int().nonnegative(),
@@ -78,6 +116,7 @@ const agentDeployManifestV1Schema = z.object({
           kind: z.string().min(1).max(32).optional(),
           eventTypes: z.array(z.string().min(1).max(64)).max(64).optional(),
           continuation: continuationIdentitySchema,
+          catch: catchDeclarationSchema.optional(),
         })
       )
       .max(64),
@@ -110,7 +149,22 @@ export interface AgentDeployManifestDeclarations {
     kind?: string;
     eventTypes?: string[];
     continuation: ContinuationIdentity;
+    /**
+     * Control-plane catch routes: present only for an authored channel
+     * whose auth chain carries a `sharedSecretAuth` / `hmacSignatureAuth`
+     * policy. The control plane accepts exactly these `(method, path)`
+     * pairs and verifies the named deployment secret before any compute.
+     */
+    catch?: AgentDeployManifestCatchDeclaration;
+  }>;
+}
+
+export interface AgentDeployManifestCatchDeclaration {
+  routes: Array<{
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
   }>;
+  auth: CatchAuthDeclaration[];
 }
 
 export interface AgentDeployManifestV1 {
@@ -158,6 +212,7 @@ export function buildAgentDeployManifest(
       kind,
       eventTypes,
       continuation: channelContinuationIdentity(channel.definition),
+      catch: channelCatchDeclaration(channel.definition),
     };
   });
 
@@ -195,6 +250,65 @@ export function buildAgentDeployManifest(
   };
 }
 
+/**
+ * Catch declaration for one authored channel: its routes, gated by the
+ * catch-capable policies in its auth chain (`sharedSecretAuth`,
+ * `hmacSignatureAuth`, or `publicEndpoint()` for handler-verified routes).
+ * A routed channel with none of those declares nothing and is not reachable
+ * through the catch API.
+ */
+export function channelCatchDeclaration(
+  definition: AgentProject["channels"][number]["definition"]
+): AgentDeployManifestCatchDeclaration | undefined {
+  const routes = definition.routes ?? [];
+  if (routes.length === 0) {
+    return undefined;
+  }
+  const declared = (definition.auth ?? [])
+    .map(catchAuthDeclaration)
+    .filter((declaration) => declaration !== undefined);
+  if (declared.length === 0) {
+    return undefined;
+  }
+  // An auth chain is any-of, so `publicEndpoint()` beside secret policies
+  // admits everything locally and on the control plane alike. Declare one
+  // `public` entry (the control plane then decrypts nothing) but keep the
+  // shared-secret header policies next to it: they are what the control
+  // plane uses to strip those header values before the request is
+  // claim-checked, and senders keep sending the secret regardless of
+  // whether anything still checks it. HMAC policies carry body digests,
+  // not secrets, so nothing is lost by dropping them.
+  const isPublic = declared.some((policy) => policy.kind === "public");
+  const auth = isPublic
+    ? [
+        { kind: "public" as const },
+        ...declared.filter((policy) => policy.kind === "header"),
+      ]
+    : declared;
+  if (routes.length > CATCH_MAX_ROUTES) {
+    if (isPublic) {
+      // publicEndpoint() channels deployed before catch existed; they stay
+      // reachable the way they were (not through catch) rather than
+      // failing the deploy.
+      return undefined;
+    }
+    throw new Error(
+      `Catch channels may declare at most ${CATCH_MAX_ROUTES} routes (got ${routes.length}).`
+    );
+  }
+  if (auth.length > CATCH_MAX_AUTH_POLICIES) {
+    throw new Error(
+      isPublic
+        ? `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} auth policies; publicEndpoint() plus ${String(auth.length - 1)} sharedSecretAuth() policies is ${String(auth.length)}. Drop publicEndpoint() or the shared-secret policies it makes dead.`
+        : `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} secret policies (got ${auth.length}).`
+    );
+  }
+  return {
+    routes: routes.map((route) => ({ method: route.method, path: route.path })),
+    auth,
+  };
+}
+
 /**
  * Parse an untrusted manifest (round-trip check for the CLI's own output;
  * the CP re-validates server-side with its own copy of the contract).

package/src/internal/describe-error.ts

@@ -2,3 +2,31 @@
 export function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+export function describeErrorCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const numericCode = (error as { code?: unknown }).code;
+    if (numericCode === 1) {
+      return "canceled";
+    }
+    if (numericCode === 14) {
+      return "unavailable";
+    }
+    if (numericCode === 2) {
+      return "unknown";
+    }
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error as { name?: unknown }).name === "AbortError"
+  ) {
+    return "ABORT_ERR";
+  }
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" && code.length <= 64 ? code : undefined;
+}