@cursor/july 0.1.107 → 0.1.109

package/src/internal/hosted-delivery.ts

@@ -3,6 +3,7 @@ import type {
   AuthPolicy,
   ChannelHandlerArgs,
   SendMessageOptions,
+  TurnOutcome,
 } from "../types.js";
 import { dispatchOutcome } from "./channel-dispatch.js";
 import {
@@ -20,7 +21,6 @@ import {
   GuestNetworkUnavailableError,
   type GuestNetworkWaitResult,
   type GuestNetworkWaitStats,
-  isQuietGuestConnectStallMessage,
   waitForGuestNetworkReady,
 } from "./guest-network.js";
 import {
@@ -40,10 +40,13 @@ import {
   HOSTED_GUEST_RETRY_TRANSIENT,
   type HostedAdmission,
   type HostedGuestRetryDisposition,
+  type HostedReminderFireDescriptorPayload,
+  hostedFailureClassification,
   hostedGuestErrorResponse,
   isHostedReminderAdmission,
   parseHostedAdmission,
   parseHostedExecution,
+  parseHostedReminderFireDescriptorPayload,
   parseHostedReminderFirePayload,
 } from "./hosted-delivery-protocol.js";
 import {
@@ -63,7 +66,10 @@ import {
   ReminderValidationError,
   UnknownReminderError,
 } from "./reminder-runner.js";
-import { statusForThrownRequestError } from "./request-error-status.js";
+import {
+  mapThrownRequestError,
+  statusForThrownRequestError,
+} from "./request-error-status.js";
 import type { Router } from "./router.js";
 import type { SessionRunExecutionWrite } from "./session-run-log.js";
 
@@ -170,6 +176,31 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
   };
 }
 
+/**
+ * Prefer the shared throw → HTTP mapper (guest network / connect stall /
+ * session busy / …) before collapsing into agent_admission_threw or
+ * background_dispatch_failed. Those agent codes otherwise hide typed
+ * transient failures that the outer handleRequest boundary never sees.
+ */
+function mappedAdmissionFailure(error: unknown): AdmissionDispatch | undefined {
+  const rejected = nonRetryableRejection(error);
+  if (rejected !== undefined) {
+    return rejected;
+  }
+  const mapped = mapThrownRequestError(error);
+  if (mapped === undefined) {
+    return undefined;
+  }
+  return {
+    response: hostedGuestErrorResponse({
+      status: mapped.status,
+      error: mapped.code,
+      retry: mapped.retry,
+      message: boundedMessage(mapped.message),
+    }),
+  };
+}
+
 /**
  * Run authored admission without creating a framework session. Authored
  * `task` callbacks execute as sessionless work; the first `send` is captured
@@ -210,9 +241,57 @@ async function dispatchHostedReminderAdmission(
       outcome: "fired" | "noop";
       reason?: string;
     }>;
+    /**
+     * Architecture v2: execute an immutable CP descriptor and apply the
+     * structured outcome. Must not GET/PUT reminder lifecycle documents.
+     */
+    executeReminderDescriptor?(
+      descriptor: HostedReminderFireDescriptorPayload
+    ): Promise<{
+      reminderId: string;
+      outcome: "fired" | "noop";
+      reason?: string;
+    }>;
   },
   delivery: HostedAdmission
 ): Promise<Response> {
+  const descriptor = parseHostedReminderFireDescriptorPayload(delivery.payload);
+  if (descriptor !== undefined) {
+    if (input.executeReminderDescriptor === undefined) {
+      return transientHostedError(
+        503,
+        "reminder_dispatch_unavailable",
+        "This guest has no reminder CP executor wired for hosted admission."
+      );
+    }
+    try {
+      const result = await input.executeReminderDescriptor(descriptor);
+      const outcome = result.outcome === "noop" ? "skip" : "task";
+      return Response.json({
+        ok: true,
+        v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+        outcome,
+      });
+    } catch (error) {
+      if (error instanceof UnknownReminderError) {
+        return terminalHostedError(
+          404,
+          "unknown_reminder",
+          boundedMessage(error.message)
+        );
+      }
+      if (error instanceof ReminderValidationError) {
+        return terminalHostedError(
+          400,
+          "invalid_reminder",
+          boundedMessage(error.message)
+        );
+      }
+      // Transient CP apply/fetch failures must remain retryable.
+      throw error;
+    }
+  }
+
   if (input.fireReminder === undefined) {
     return transientHostedError(
       503,
@@ -225,7 +304,7 @@ async function dispatchHostedReminderAdmission(
     return terminalHostedError(
       400,
       "invalid_reminder_payload",
-      "Expected reminder payload { reminderId, fireCount }."
+      "Expected reminder descriptor or legacy payload { reminderId, fireCount }."
     );
   }
   try {
@@ -281,17 +360,24 @@ async function runAdmission(
   let dispatched: Response;
   try {
     dispatched = await adapter.dispatch({
+      channelId: input.delivery.channelId,
       eventType: input.delivery.eventType,
       payload: input.delivery.payload,
       deliveryId: input.delivery.deliveryId,
       args,
     });
   } catch (error) {
-    const rejected = nonRetryableRejection(error);
-    if (rejected !== undefined) {
-      return rejected;
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
     }
-    throw error;
+    return {
+      response: terminalHostedError(
+        500,
+        "agent_admission_threw",
+        boundedMessage(error instanceof Error ? error.message : String(error))
+      ),
+    };
   }
   if (!dispatched.ok) {
     return {
@@ -305,9 +391,9 @@ async function runAdmission(
   try {
     await Promise.all(background);
   } catch (error) {
-    const rejected = nonRetryableRejection(error);
-    if (rejected !== undefined) {
-      return rejected;
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
     }
     return {
       response: terminalHostedError(
@@ -436,6 +522,17 @@ export function registerHostedDeliveryRoute(input: {
     outcome: "fired" | "noop";
     reason?: string;
   }>;
+  /**
+   * Architecture v2: execute an immutable CP fire descriptor and apply the
+   * structured outcome via the hosted ReminderControlPlane client.
+   */
+  executeReminderDescriptor?(
+    descriptor: HostedReminderFireDescriptorPayload
+  ): Promise<{
+    reminderId: string;
+    outcome: "fired" | "noop";
+    reason?: string;
+  }>;
   /**
    * Await the session's durable mirror (dispatch chain + storage queue)
    * before the execution reply: the control plane may park the pod the
@@ -735,8 +832,13 @@ export function registerHostedDeliveryRoute(input: {
             abortReason?:
               | ReturnType<typeof abortReasonFromTurnStatus>
               | "execute_throw";
+            failureCode?: string;
             error?: unknown;
           }): Promise<void> => {
+            const classification =
+              fields.failureCode === undefined
+                ? undefined
+                : hostedFailureClassification(fields.failureCode);
             await flushHostedExecutionRecord(sinks, {
               executionId,
               sessionPublicId: execution.sessionPublicId,
@@ -752,6 +854,8 @@ export function registerHostedDeliveryRoute(input: {
               ...(fields.abortReason === undefined
                 ? {}
                 : { abortReason: fields.abortReason }),
+              failureCode: fields.failureCode,
+              classification,
               ...(fields.error === undefined ? {} : { error: fields.error }),
             });
           };
@@ -788,28 +892,30 @@ export function registerHostedDeliveryRoute(input: {
               session.id,
               execution.sessionPublicId
             );
+            const hostedFailure =
+              outcome.status === "finished"
+                ? undefined
+                : hostedFailureForUnfinishedTurn(outcome);
             await writeDiag({
               sessionId: session.id,
               turnStatus: outcome.status,
               message: outcome.errorMessage,
               abortReason: abortReasonFromTurnStatus(
                 outcome.status,
-                outcome.errorMessage
+                outcome.cancellationReason
               ),
+              failureCode: hostedFailure?.error,
             });
-            if (outcome.status !== "finished") {
-              // waitForCompletion resolves (does not throw) on a quiet
-              // Connect abort. Map that to guest_connect_stalled so TAS
-              // retries the same pod. Real runner failures stay turn_failed.
-              const hostedFailure = hostedFailureForUnfinishedTurn(
-                outcome.errorMessage
-              );
+            if (hostedFailure !== undefined) {
               return {
                 status: 503,
                 body: {
                   ok: false,
                   error: hostedFailure.error,
                   retry: hostedFailure.retry,
+                  classification: hostedFailureClassification(
+                    hostedFailure.error
+                  ),
                   turnStatus: outcome.status,
                   message: outcome.errorMessage,
                 },
@@ -834,6 +940,7 @@ export function registerHostedDeliveryRoute(input: {
               turnStatus: "error",
               message: error instanceof Error ? error.message : String(error),
               abortReason: "execute_throw",
+              failureCode: "internal_error",
               error,
             });
             throw error;
@@ -862,19 +969,45 @@ function evictHostedSdkSessions(
   }
 }
 
-function hostedFailureForUnfinishedTurn(errorMessage: string | undefined): {
-  error: typeof GUEST_CONNECT_STALLED | "turn_failed";
+const TRANSIENT_TURN_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ABORT_ERR",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "canceled",
+  "unavailable",
+  "unknown",
+]);
+
+function hostedFailureForUnfinishedTurn(outcome: TurnOutcome): {
+  error:
+    | typeof GUEST_CONNECT_STALLED
+    | "agent_dependency_failed"
+    | "turn_cancelled"
+    | "turn_failed";
   retry: HostedGuestRetryDisposition;
 } {
+  if (outcome.errorCode === "agent_dependency_failed") {
+    return {
+      error: "agent_dependency_failed",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
+  }
   if (
-    errorMessage !== undefined &&
-    isQuietGuestConnectStallMessage(errorMessage)
+    outcome.status === "error" &&
+    outcome.errorCode !== undefined &&
+    TRANSIENT_TURN_ERROR_CODES.has(outcome.errorCode)
   ) {
     return {
       error: GUEST_CONNECT_STALLED,
       retry: HOSTED_GUEST_RETRY_TRANSIENT,
     };
   }
+  if (outcome.status === "cancelled") {
+    return {
+      error: "turn_cancelled",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
+  }
   return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
 }
 

package/src/internal/hosted-execution-diag.ts

@@ -8,7 +8,11 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { HOSTED_EXECUTION_DIAG_FILENAME } from "./hosted-delivery-protocol.js";
+import {
+  HOSTED_EXECUTION_DIAG_FILENAME,
+  type HostedFailureClassification,
+  parseHostedFailureClassification,
+} from "./hosted-delivery-protocol.js";
 
 export const HOSTED_EXECUTION_DIAG_VERSION = 1;
 /** Cap so a runaway message cannot fill the guest disk or the host log. */
@@ -57,6 +61,8 @@ export type HostedExecutionDiag = {
   signalAborted?: boolean;
   requestId?: string;
   abortReason?: HostedExecutionDiagAbortReason;
+  failureCode?: string;
+  classification?: HostedFailureClassification;
 };
 
 /** Written before the turn starts so a stalled execution still has a record. */
@@ -75,6 +81,8 @@ const DIAG_KEYS = new Set([
   "signalAborted",
   "requestId",
   "abortReason",
+  "failureCode",
+  "classification",
 ]);
 
 const ABORT_REASONS = new Set<HostedExecutionDiagAbortReason>([
@@ -137,13 +145,13 @@ export function hostedExecutionDiagPath(stateRoot: string): string {
 
 export function abortReasonFromTurnStatus(
   status: string,
-  message: string | undefined
+  cancellationReason: "signal" | "runner" | undefined
 ): HostedExecutionDiagAbortReason | undefined {
   if (status === "finished") {
     return undefined;
   }
   if (status === "cancelled") {
-    return message !== undefined && /abort/i.test(message)
+    return cancellationReason === "signal"
       ? "signal_abort"
       : "runner_cancelled";
   }
@@ -197,6 +205,14 @@ export function parseHostedExecutionDiag(
     HOSTED_ERROR_SNIPPET_MAX_CHARS
   );
   const requestId = boundedOptionalString(body.requestId, 128);
+  const failureCode = boundedOptionalString(body.failureCode, 64);
+  const classification =
+    body.classification === undefined
+      ? undefined
+      : parseHostedFailureClassification(body.classification);
+  if (body.classification !== undefined && classification === undefined) {
+    return undefined;
+  }
   const abortReason =
     body.abortReason === undefined
       ? undefined
@@ -226,6 +242,8 @@ export function parseHostedExecutionDiag(
     ...(body.signalAborted === true ? { signalAborted: true } : {}),
     ...(requestId === undefined ? {} : { requestId }),
     ...(abortReason === undefined ? {} : { abortReason }),
+    ...(failureCode === undefined ? {} : { failureCode }),
+    ...(classification === undefined ? {} : { classification }),
   };
 }
 

package/src/internal/hosted-execution-flush.ts

@@ -9,6 +9,7 @@
  * so TAS does not treat a previous delivery's terminal record as this one.
  */
 
+import type { HostedFailureClassification } from "./hosted-delivery-protocol.js";
 import {
   type HostedExecutionDiagAbortReason,
   hostedErrorStackSnippet,
@@ -46,6 +47,8 @@ export type HostedExecutionFlushFields = {
   durationMs: number;
   message?: string;
   abortReason?: HostedExecutionDiagAbortReason;
+  failureCode?: string;
+  classification?: HostedFailureClassification;
   error?: unknown;
 };
 
@@ -75,12 +78,12 @@ export async function flushHostedExecutionRecord(
       durationMs: fields.durationMs,
       ...(message === undefined ? {} : { message }),
       ...(stack === undefined || stack.length === 0 ? {} : { stack }),
-      ...(message !== undefined && /abort/i.test(message)
-        ? { signalAborted: true }
-        : {}),
+      signalAborted: fields.abortReason === "signal_abort" ? true : undefined,
       ...(fields.abortReason === undefined
         ? {}
         : { abortReason: fields.abortReason }),
+      failureCode: fields.failureCode,
+      classification: fields.classification,
     });
   }
   if (sinks.persistSessionRun !== undefined) {

package/src/internal/http-control-plane-session.ts

@@ -0,0 +1,104 @@
+/**
+ * Built-in HTTP channel admission for control-plane session starts.
+ *
+ * `agent-sdk run --prod` reaches the authenticated CP start route, which
+ * delivers `agentsdk.session` to the built-in `http` channel of every v2
+ * agent. The wake is `send(message, { dryRun, asOf })`; the session id, when
+ * the caller resumed an explicit `ses_…`, arrives through the hosted
+ * execution (never through this payload), so authored code cannot pick one.
+ */
+
+import type { ChannelHandlerArgs, HttpChannelDefinition } from "../types.js";
+import { skipped, turnStarted } from "./channel-dispatch.js";
+import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
+import {
+  AGENT_SDK_HTTP_CHANNEL_KIND,
+  AGENT_SDK_SESSION_EVENT_TYPE,
+} from "./hosted-catch-protocol.js";
+
+export type ControlPlaneSessionPayload = {
+  message: string;
+  dryRun?: boolean | undefined;
+  asOf?: string | undefined;
+};
+
+const PAYLOAD_KEYS = new Set(["message", "dryRun", "asOf"]);
+const MAX_MESSAGE_CHARS = 64 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parseControlPlaneSessionPayload(
+  payload: unknown
+):
+  | { ok: true; data: ControlPlaneSessionPayload }
+  | { ok: false; error: string } {
+  if (!isRecord(payload)) {
+    return { ok: false, error: "payload must be an object" };
+  }
+  if (Object.keys(payload).some((key) => !PAYLOAD_KEYS.has(key))) {
+    return { ok: false, error: "payload carries an unsupported field" };
+  }
+  const message =
+    typeof payload.message === "string" ? payload.message.trim() : "";
+  if (message.length === 0 || message.length > MAX_MESSAGE_CHARS) {
+    return { ok: false, error: "payload.message is required" };
+  }
+  if (payload.dryRun !== undefined && typeof payload.dryRun !== "boolean") {
+    return { ok: false, error: "payload.dryRun must be a boolean" };
+  }
+  if (
+    payload.asOf !== undefined &&
+    (typeof payload.asOf !== "string" || payload.asOf.trim().length === 0)
+  ) {
+    return { ok: false, error: "payload.asOf must be a non-empty string" };
+  }
+  return {
+    ok: true,
+    data: {
+      message,
+      dryRun: payload.dryRun === true ? true : undefined,
+      asOf: typeof payload.asOf === "string" ? payload.asOf.trim() : undefined,
+    },
+  };
+}
+
+export async function dispatchHttpControlPlaneSession(input: {
+  eventType: string;
+  payload: unknown;
+  args: ChannelHandlerArgs;
+  onMessage?: HttpChannelDefinition["onMessage"];
+}): Promise<Response> {
+  if (input.eventType !== AGENT_SDK_SESSION_EVENT_TYPE) {
+    return skipped("not a control-plane session");
+  }
+  const parsed = parseControlPlaneSessionPayload(input.payload);
+  if (!parsed.ok) {
+    return Response.json({ ok: false, error: parsed.error }, { status: 400 });
+  }
+  const message =
+    input.onMessage === undefined
+      ? parsed.data.message
+      : await input.onMessage(parsed.data.message, { auth: null });
+  const session = await input.args.send(message, {
+    dryRun: parsed.data.dryRun,
+    asOf: parsed.data.asOf,
+  });
+  return turnStarted(session);
+}
+
+export function attachHttpControlPlaneAdmission(
+  definition: HttpChannelDefinition
+): void {
+  attachHostedAdmissionAdapter(definition, {
+    kind: AGENT_SDK_HTTP_CHANNEL_KIND,
+    dispatch: ({ eventType, payload, args }) =>
+      dispatchHttpControlPlaneSession({
+        eventType,
+        payload,
+        args,
+        onMessage: definition.onMessage,
+      }),
+  });
+}

package/src/internal/init-scaffold.ts

@@ -20,7 +20,6 @@ const EMPTY_DIRS: readonly string[] = [
   "agent/subagents",
   "agent/channels",
   "agent/hooks",
-  "agent/ab",
   "agent/schedules",
   "agent/sandbox/workspace",
   "agent/lib",
@@ -101,7 +100,7 @@ Run the CLI under Node, never Bun.
 ## Pointers
 
 - Package loop: \`node_modules/${PACKAGE_NAME}/AGENTS.md\`
-- Skills: \`node_modules/${PACKAGE_NAME}/skills/\` (\`create-agent\`, \`evals\`, \`hillclimb\`, \`debug\`)
+- Skills: \`node_modules/${PACKAGE_NAME}/skills/\` (\`create-agent\`, \`deploy\`, \`evals\`, \`hillclimb\`, \`debug\`)
 - Docs: \`npx ${PACKAGE_NAME} docs\`
 - LLM docs index: \`node_modules/${PACKAGE_NAME}/dist/docs/llms.txt\`
 `;

package/src/internal/install-cursor-skills.ts

@@ -57,6 +57,8 @@ export interface PackageSkill {
   leafDir: string;
   /** Absolute path to the source skill directory in the package. */
   sourceDir: string;
+  /** Exact package version that supplied this skill. */
+  packageVersion: string;
 }
 
 export function cursorSkillsHome(home?: string): string {
@@ -116,6 +118,7 @@ export async function listShippedPackageSkills(
   } catch {
     return [];
   }
+  const packageVersion = await readPackageVersion(packageRoot);
 
   const skills: PackageSkill[] = [];
   for (const entry of entries) {
@@ -133,12 +136,23 @@ export async function listShippedPackageSkills(
     const name =
       parseFrontmatter(raw).data.name ||
       `${CURSOR_SKILLS_NAMESPACE}-${entry.name}`;
-    skills.push({ name, leafDir: entry.name, sourceDir });
+    skills.push({ name, leafDir: entry.name, sourceDir, packageVersion });
   }
   skills.sort((a, b) => a.leafDir.localeCompare(b.leafDir));
   return skills;
 }
 
+const PACKAGE_VERSION_PLACEHOLDER = "__CURSOR_JULY_VERSION__";
+
+async function readPackageVersion(packageRoot: string): Promise<string> {
+  const raw = await readFile(join(packageRoot, "package.json"), "utf8");
+  const manifest = JSON.parse(raw) as { version?: unknown };
+  if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
+    throw new Error("The @cursor/july package must declare a version.");
+  }
+  return manifest.version;
+}
+
 /**
  * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentsdk/.
  * Install still overwrites every shipped skill when the user confirms — this
@@ -200,7 +214,10 @@ export async function installCursorSkills(
     await makeTreeWritable(target);
     const skillMdPath = join(target, "SKILL.md");
     const raw = await readFile(skillMdPath, "utf8");
-    const adjusted = prepareSkillMarkdownForCursorInstall(raw);
+    const adjusted = prepareSkillMarkdownForCursorInstall(
+      raw,
+      skill.packageVersion
+    );
     if (adjusted !== raw) {
       await writeFile(skillMdPath, adjusted, "utf8");
     }
@@ -276,9 +293,13 @@ async function hasLegacyCursorSkillsNamespace(
 
 /**
  * Drop monorepo `paths` globs, set `alwaysApply: true` so Cursor injects the
- * body as a global rule, and fix package doc links for ~/.cursor installs.
+ * body as a global rule, bind package commands to the installing version, and
+ * fix package doc links for ~/.cursor installs.
  */
-export function prepareSkillMarkdownForCursorInstall(content: string): string {
+export function prepareSkillMarkdownForCursorInstall(
+  content: string,
+  packageVersion?: string
+): string {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (match === null) {
     return content;
@@ -291,7 +312,19 @@ export function prepareSkillMarkdownForCursorInstall(content: string): string {
     /\[`docs\/([^`]+)`\]\(\.\.\/\.\.\/docs\/[^)]+\)/g,
     "docs/$1 in the @cursor/july package"
   );
-  return `---\n${frontmatter.trimEnd()}\n---${adjustedBody}`;
+  if (
+    adjustedBody.includes(PACKAGE_VERSION_PLACEHOLDER) &&
+    (packageVersion === undefined || packageVersion.trim() === "")
+  ) {
+    throw new Error(
+      "Cannot install an Agent SDK skill without a package version."
+    );
+  }
+  const versionBoundBody =
+    packageVersion === undefined
+      ? adjustedBody
+      : adjustedBody.replaceAll(PACKAGE_VERSION_PLACEHOLDER, packageVersion);
+  return `---\n${frontmatter.trimEnd()}\n---${versionBoundBody}`;
 }
 
 function stripPathsFromFrontmatter(frontmatter: string): string {

package/src/internal/legacy-command-guard.ts

@@ -0,0 +1,59 @@
+import {
+  type AgentServeDeployClient,
+  DeployApiError,
+} from "./deploy-client.js";
+
+/**
+ * Classify a hosted slug by probing the v2 control plane.
+ *
+ * Only HTTP 404 means “not v2.” Auth, 5xx, and transport errors fail closed
+ * so a v2 slug cannot fall through to `/internal/agent-serve`. That probe
+ * shares the factory microlith path used by secrets; a factory outage will
+ * also block legacy `--prod` until it recovers.
+ */
+export async function deploymentArchitecture(args: {
+  client: AgentServeDeployClient;
+  teamId: number;
+  slug: string;
+}): Promise<"v1" | "v2"> {
+  try {
+    await args.client.getAgentkitDeploy({
+      teamId: args.teamId,
+      slug: args.slug,
+    });
+    return "v2";
+  } catch (error) {
+    if (error instanceof DeployApiError && error.status === 404) {
+      return "v1";
+    }
+    throw error;
+  }
+}
+
+export function unsupportedV2LegacyCommandError(slug: string): DeployApiError {
+  return new DeployApiError(
+    `This command is not supported for architecture v2 deployment "${slug}". The command stopped before calling the legacy v1 deployment API.`,
+    409
+  );
+}
+
+export function isUnsupportedV2LegacyCommandError(
+  error: unknown
+): error is DeployApiError {
+  return (
+    error instanceof DeployApiError &&
+    error.status === 409 &&
+    error.message.includes("not supported for architecture v2")
+  );
+}
+
+export async function rejectV2ForLegacyCommand(args: {
+  client: AgentServeDeployClient;
+  teamId: number;
+  slug: string;
+}): Promise<void> {
+  const architecture = await deploymentArchitecture(args);
+  if (architecture === "v2") {
+    throw unsupportedV2LegacyCommandError(args.slug);
+  }
+}