@cursor/july 0.1.105 → 0.1.108

package/src/internal/channel-state.ts

@@ -0,0 +1,96 @@
+import { isDeepStrictEqual } from "node:util";
+import type { JsonValue } from "../types.js";
+
+type JsonRecord = Record<string, JsonValue>;
+
+function asRecord(value: JsonValue | undefined): JsonRecord | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as JsonRecord;
+}
+
+/**
+ * Shallow-merge a wake patch into durable channel state. Null / undefined
+ * patch values leave the existing key alone so sticky fields survive.
+ */
+export function mergeChannelStateSkipNull(
+  current: JsonValue | undefined,
+  patch: JsonValue | undefined
+): JsonValue | undefined {
+  if (patch === undefined) {
+    return current;
+  }
+  const currentRecord = asRecord(current);
+  const patchRecord = asRecord(patch);
+  if (currentRecord === undefined || patchRecord === undefined) {
+    return structuredClone(patch);
+  }
+  const merged = { ...currentRecord };
+  for (const [key, value] of Object.entries(patchRecord)) {
+    if (value !== null && value !== undefined) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Apply handler mutations made against a turn snapshot without reverting
+ * unchanged fields refreshed by a later delivery. At a changed path, objects
+ * merge recursively, arrays and scalars replace, and deletions win.
+ */
+export function mergeChannelStateMutation(args: {
+  current: JsonValue | undefined;
+  before: JsonValue;
+  after: JsonValue;
+}): JsonValue | undefined {
+  const { current, before, after } = args;
+  if (isDeepStrictEqual(before, after)) {
+    return current;
+  }
+  const currentRecord = asRecord(current);
+  const beforeRecord = asRecord(before);
+  const afterRecord = asRecord(after);
+  if (
+    currentRecord === undefined ||
+    beforeRecord === undefined ||
+    afterRecord === undefined
+  ) {
+    return structuredClone(after);
+  }
+
+  const merged = structuredClone(currentRecord);
+  const keys = new Set([
+    ...Object.keys(beforeRecord),
+    ...Object.keys(afterRecord),
+  ]);
+  for (const key of keys) {
+    const hadBefore = Object.hasOwn(beforeRecord, key);
+    const hasAfter = Object.hasOwn(afterRecord, key);
+    if (
+      hadBefore &&
+      hasAfter &&
+      isDeepStrictEqual(beforeRecord[key], afterRecord[key])
+    ) {
+      continue;
+    }
+    if (!hasAfter) {
+      delete merged[key];
+      continue;
+    }
+    const currentValue = merged[key];
+    const afterValue = afterRecord[key]!;
+    merged[key] =
+      hadBefore ||
+      (asRecord(currentValue) !== undefined &&
+        asRecord(afterValue) !== undefined)
+        ? (mergeChannelStateMutation({
+            current: currentValue,
+            before: hadBefore ? beforeRecord[key]! : {},
+            after: afterValue,
+          }) as JsonValue)
+        : structuredClone(afterValue);
+  }
+  return merged;
+}

package/src/internal/cli-ax.ts

@@ -23,6 +23,7 @@ import { lookupSessionContinuation, runChat } from "./chat-client.js";
 import { ensureCursorLogin } from "./cli-cursor.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { resolveApiKey } from "./cursor/credentials.js";
+import { DeployApiError } from "./deploy-client.js";
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
 import {
   discoverEvals,
@@ -53,6 +54,7 @@ import {
   resolveTemplate,
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
+import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
 import { mapPool } from "./map-pool.js";
 import { openBrowser } from "./open-browser.js";
@@ -189,6 +191,13 @@ export interface AxCliOptions {
   resume?: boolean;
   /** Abort signal (tests / programmatic stop of `playground` proxy). */
   signal?: AbortSignal;
+  /**
+   * `run --prod` / `session --prod --message`: hosted v2 session start on
+   * the agentsdk control plane. `--dry-run` marks the turn non-mutating;
+   * `--as-of` freezes the session clock at a timezone-bearing instant.
+   */
+  dryRun?: boolean;
+  asOf?: string;
 }
 
 export interface ResolvedAgentTarget {
@@ -594,6 +603,15 @@ export async function cmdChat(options: AxCliOptions): Promise<number> {
 }
 
 export async function cmdRun(options: AxCliOptions): Promise<number> {
+  // Only a v2-shaped request tries the control plane; every v1 `run --prod`
+  // form (multi-turn, continuation token, local session id, --url) keeps its
+  // engine-alias path untouched.
+  if (options.prod === true && hostedSessionRejection(options) === undefined) {
+    const started = await cmdHostedSession(options);
+    if (started !== "fallback") {
+      return started;
+    }
+  }
   const messages = options.messages ?? [];
   if (messages.length === 0) {
     die("Provide --message (repeatable) or --messages-file");
@@ -703,6 +721,74 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
   }
 }
 
+const HOSTED_SESSION_ID_RE = /^ses_[a-f0-9]{24}$/;
+
+/**
+ * Hosted v2 session start: POST the agentsdk control plane, which hands the
+ * wake to Temporal (no resident engine, no `/engine/*` alias). `--session
+ * ses_…` resumes that exact session; there is no continuation token on
+ * this path. A 404 means the slug is not a v2 control-plane deployment, so
+ * `run --prod` falls back to the v1 engine alias.
+ */
+/** Why these options cannot be a hosted v2 session start, if they cannot. */
+function hostedSessionRejection(options: AxCliOptions): string | undefined {
+  if (options.url !== undefined) {
+    return "--prod session start talks to the agentsdk control plane; do not pass --url";
+  }
+  const messages = options.messages ?? [];
+  if (messages.length !== 1 || messages[0]?.trim() === "") {
+    return "Provide exactly one --message (the wake). Multi-turn runs are local-only.";
+  }
+  if (trimNonEmpty(options.continuationToken) !== undefined) {
+    return "--continuation-token is not a hosted v2 identity; pass --session ses_… to resume a session";
+  }
+  const sessionId = trimNonEmpty(options.sessionId);
+  if (sessionId !== undefined && !HOSTED_SESSION_ID_RE.test(sessionId)) {
+    return `--session must be a hosted session id (ses_…), got ${sessionId}`;
+  }
+  return undefined;
+}
+
+async function cmdHostedSession(
+  options: AxCliOptions
+): Promise<number | "fallback"> {
+  const rejection = hostedSessionRejection(options);
+  if (rejection !== undefined) {
+    die(rejection);
+  }
+  const messages = options.messages ?? [];
+  const sessionId = trimNonEmpty(options.sessionId);
+  const auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+  const slug = resolveProdSlug(options);
+  try {
+    const accepted = await auth.client.startSession({
+      teamId: auth.teamId,
+      slug,
+      message: messages[0]!.trim(),
+      sessionId,
+      dryRun: options.dryRun,
+      asOf: options.asOf,
+    });
+    console.log(JSON.stringify(accepted, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof DeployApiError && error.status === 404) {
+      return "fallback";
+    }
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 1;
+  }
+}
+
 /**
  * `agent-sdk call <tool>` — deterministic tool invocation over
  * `POST /v1/tools/:toolName` (ephemeral local server unless --url).
@@ -1727,6 +1813,11 @@ export async function cmdLogs(options: AxCliOptions): Promise<number> {
       if (typeof auth === "number") {
         return auth;
       }
+      await rejectV2ForLegacyCommand({
+        client: auth.client,
+        teamId: auth.teamId,
+        slug,
+      });
       await runLogsTail({
         prod: true,
         dir: options.dir,
@@ -1750,6 +1841,7 @@ export async function cmdLogs(options: AxCliOptions): Promise<number> {
             apiKey: options.apiKey,
             fetchImpl: options.fetchImpl,
             err: () => {},
+            skipLegacyArchitectureCheck: true,
           });
           return { agentUrl: target.agentUrl, headers: target.headers };
         },
@@ -1864,9 +1956,26 @@ export async function cmdSession(
   sessionId: string | undefined,
   options: AxCliOptions
 ): Promise<number> {
+  if (options.prod === true && (options.messages?.length ?? 0) > 0) {
+    // `session --prod [ses_…] --message` is the same hosted start as
+    // `run --prod`, with the positional id as the session to resume. Unlike
+    // `run`, a 404 is an error here: this form is explicitly v2.
+    const started = await cmdHostedSession({
+      ...options,
+      sessionId: trimNonEmpty(sessionId) ?? options.sessionId,
+    });
+    if (started === "fallback") {
+      process.stderr.write(
+        `Hosted session start returned 404 for slug ${resolveProdSlug(options)}: deploy a running AgentSDK v2 agent, or use \`${CLI_COMMAND_NAME} run --prod\` (falls back to the v1 engine).\n`
+      );
+      return 1;
+    }
+    return started;
+  }
   if (sessionId === undefined || sessionId.trim() === "") {
     process.stderr.write(
-      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events] [--out <file.ndjson>]\n`
+      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events] [--out <file.ndjson>]\n` +
+        `   or: ${CLI_COMMAND_NAME} session --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]\n`
     );
     return 2;
   }

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
     ),
@@ -1570,14 +1604,26 @@ export async function cmdDelete(
   if (typeof ctx === "number") {
     return ctx;
   }
-  let accepted: DeleteAccepted;
+  // Same dispatch as `stop`: v1 409s architecture-v2 slugs, so the v2
+  // DELETE goes first. A v2 404 (missing slug, or an older backend)
+  // falls through to the v1 agent-serve delete.
+  let architecture: "v1" | "v2" = "v2";
+  let accepted: DeleteAccepted | AgentkitStopAccepted;
   try {
-    accepted = await ctx.client.deleteDeployment({
-      teamId: ctx.teamId,
-      slug,
-    });
+    accepted = await ctx.client.deleteAgentkit({ teamId: ctx.teamId, slug });
   } catch (error) {
-    return renderApiError(error, ctx.err);
+    if (!(error instanceof DeployApiError) || error.status !== 404) {
+      return renderApiError(error, ctx.err);
+    }
+    try {
+      accepted = await ctx.client.deleteDeployment({
+        teamId: ctx.teamId,
+        slug,
+      });
+      architecture = "v1";
+    } catch (v1Error) {
+      return renderApiError(v1Error, ctx.err);
+    }
   }
   if (ctx.noWait) {
     if (ctx.json) {
@@ -1588,7 +1634,11 @@ export async function cmdDelete(
     return 0;
   }
   try {
-    await pollUntilGone(ctx, slug);
+    await pollUntilGone(ctx, slug, () =>
+      architecture === "v2"
+        ? ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug })
+        : ctx.client.getDeployment({ teamId: ctx.teamId, slug })
+    );
   } catch (error) {
     return renderApiError(error, ctx.err);
   }
@@ -1620,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,
@@ -1657,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,
@@ -1683,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(
@@ -2103,7 +2159,12 @@ function transientDeployStatusWaitMs(
  */
 async function pollUntilGone(
   ctx: DeployCliContext,
-  slug: string
+  slug: string,
+  getDetail: () => Promise<{
+    status: string;
+    progress?: DeploymentProgress;
+    statusMessage?: string | null;
+  }>
 ): Promise<void> {
   const startedAt = Date.now();
   const tty = process.stderr.isTTY === true;
@@ -2126,10 +2187,7 @@ async function pollUntilGone(
 
   for (;;) {
     try {
-      const detail = await ctx.client.getDeployment({
-        teamId: ctx.teamId,
-        slug,
-      });
+      const detail = await getDetail();
       report(deployProgressLabel(detail));
     } catch (error: unknown) {
       if (error instanceof DeployApiError && error.status === 404) {

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,