@cursor/bdk 0.2.1

package/src/internal/deploy-client.ts

@@ -0,0 +1,1504 @@
+/**
+ * Thin client for the Agent Serve deployment management API
+ * (`/internal/agent-serve/deployments` on the Cursor backend) and the v2
+ * AgentSDK accept path (`/internal/agentsdk/deployments`). Pure
+ * request/response + error mapping — no console I/O, no polling loops;
+ * rendering lives in `cli-deploy.ts`.
+ *
+ * Auth is the user API key sent directly as the bearer (the routes are
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
+ * The endpoints are gated on the `agent_serve_mvp` Statsig gate and 404
+ * when it is off — the error mapping says so instead of "not found".
+ */
+
+import { z } from "zod";
+import {
+  MAX_SECRET_VALUE_BYTES,
+  MAX_SECRETS,
+  validateEgressDomain,
+  validateSettableSecretName,
+} from "./hosting.js";
+
+export type DeploymentStatus =
+  | "pending"
+  | "deploying"
+  | "running"
+  | "degraded"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "deleting";
+
+/** Customer-safe deploy progress (no hosting phase / infra names). */
+export type DeploymentProgress =
+  | "queued"
+  | "preparing"
+  | "creating"
+  | "building"
+  | "starting"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "deleting"
+  | "degraded";
+
+export const TERMINAL_DEPLOY_STATUSES: ReadonlySet<DeploymentStatus> = new Set([
+  "running",
+  "degraded",
+  "failed",
+  "stopped",
+]);
+
+/**
+ * What gets deployed. Today the control plane builds the engine itself from
+ * a git ref, so the only member is the slug/git-ref shape. When
+ * artifact-based deploys ship ("build locally + upload"), add an
+ * `{ kind: "artifact", ... }` member here and a branch in
+ * {@link AgentServeDeployClient.deploy} — the command surface and everything
+ * downstream stays unchanged.
+ */
+export type DeploySource = {
+  kind: "git-ref";
+  gitRepoUrl: string;
+  gitRef?: string;
+  agentPath?: string;
+  /** Repos whose SCM events the deployed engine pulls (`owner/name`). */
+  cursorEventRepos?: string[];
+  /**
+   * Egress allowlist for the engine pod.
+   */
+  egressAllowedDomains?: string[];
+  /**
+   * `/v1/channels/…` subtrees the stable alias serves WITHOUT
+   * `X-Agent-Alias-Token` (channels authored with `publicEndpoint()`).
+   */
+  publicRoutePaths?: string[];
+};
+
+const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
+
+/** Returns a human error message, or undefined when the slug is valid. */
+export function validateDeploymentSlug(slug: string): string | undefined {
+  if (SLUG_PATTERN.test(slug)) {
+    return undefined;
+  }
+  return `Invalid slug ${JSON.stringify(slug)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`;
+}
+
+/** Derive a valid slug from a directory name, or undefined if impossible. */
+export function slugFromDirectoryName(name: string): string | undefined {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return SLUG_PATTERN.test(slug) ? slug : undefined;
+}
+
+export class DeployApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    /** Seconds to wait before retrying (from `Retry-After` on 429s). */
+    readonly retryAfterSeconds?: number,
+  ) {
+    super(message);
+    this.name = "DeployApiError";
+  }
+}
+
+// ============================================================================
+// Response shapes (backend `serializeDeployment` + route-specific bodies).
+// Interfaces are hand-written (the package compiles with
+// --isolatedDeclarations, so exported types cannot be z.infer of an
+// unannotated schema); the zod schemas below stay module-internal.
+// ============================================================================
+
+export interface DeployAccepted {
+  id: number;
+  slug: string;
+  teamId: number;
+  status: string;
+  generation: number;
+  deploymentKind: string;
+  engineAlias: string;
+  /** Present exactly once, on the deploy that minted the record. */
+  aliasToken?: string;
+}
+
+export interface Deployment {
+  id: number;
+  slug: string;
+  teamId: number;
+  deploymentKind: string;
+  gitRepoUrl?: string | null;
+  gitRef?: string;
+  agentPath?: string;
+  desiredState?: string;
+  status: DeploymentStatus;
+  /**
+   * Customer-safe deploy progress (no hosting internals). Present on newer
+   * backends; older responses omit it.
+   */
+  progress?: DeploymentProgress;
+  /**
+   * Live step while the deploy converges (e.g. "Checking out source…").
+   * Null when running / stopped or when only a failure is on the row.
+   * Present on newer backends; older responses omit it.
+   */
+  statusMessage?: string | null;
+  generation: number;
+  observedGeneration?: number | null;
+  engineGeneration?: number | null;
+  publicId?: string;
+  engineUrl?: string | null;
+  /** Anyrun pod id for the active engine, when coordinates are known. */
+  enginePodId?: string | null;
+  lastError?: string | null;
+  engineAlias: string;
+  desiredUpdatedAt?: string;
+  lastReconciledAt?: string | null;
+  /** SCM-event repos configured on the deployment (`owner/name`). */
+  cursorEventRepos?: string[];
+  /** Normalized egress allowlist for the engine pod. */
+  egressAllowedDomains?: string[];
+  /** Channel subtrees the alias serves without `X-Agent-Alias-Token`. */
+  publicRoutePaths?: string[];
+  /** Service-account id (`sa_…`); null on legacy rows. */
+  serviceAccountId?: string | number | null;
+  /**
+   * The durable file store's address on `/v0/agent-serve-files` (also pinned
+   * into the pod env as `AGENT_SERVE_STORE_SOURCE_ID`).
+   */
+  agentStoreSourceId?: string;
+  /** Masked pod credential; the raw key is never returned. */
+  podCredentialMaskedKey?: string | null;
+  /** Names of the secrets set on the deployment (values never returned). */
+  secretNames?: string[];
+}
+
+/** Short-lived direct pod access minted by the status route. */
+export interface EngineAccess {
+  url: string;
+  headers: Record<string, string>;
+  expiresAt: string;
+}
+
+export interface DeploymentDetail extends Deployment {
+  engineAccess?: EngineAccess | null;
+}
+
+/**
+ * The deployment's dedicated service-account id (`sa_…`), or undefined for
+ * legacy rows that predate service-account-backed deploys. Normalizes the
+ * wire shape (string in prod, number in old fixtures, null when unset).
+ */
+export function deploymentServiceAccountId(
+  deployment: Pick<Deployment, "serviceAccountId">,
+): string | undefined {
+  const raw = deployment.serviceAccountId;
+  if (raw === null || raw === undefined) {
+    return undefined;
+  }
+  const id = String(raw).trim();
+  return id === "" ? undefined : id;
+}
+
+export interface StopAccepted {
+  id: number;
+  status: string;
+}
+
+export type DeleteAccepted = StopAccepted;
+
+/**
+ * `POST /internal/agentsdk/deployments` 202 body. Distinct from v1
+ * {@link DeployAccepted}: the v2 control plane returns catalog ids, not
+ * an engine alias or one-shot alias token.
+ */
+export interface AgentkitDeployAccepted {
+  applicationId: string;
+  releaseId: string;
+  status: string;
+}
+
+/**
+ * One release component of a v2 multi-component deploy: a stable key (the
+ * child agent's slug) plus that agent's directory relative to the repo
+ * root.
+ */
+export interface AgentkitDeployComponent {
+  componentKey: string;
+  agentPath?: string;
+  persistent?: boolean;
+  /** Team container image (`agent-sdk images push`) this component runs in. */
+  image?: string;
+}
+
+/** Customer-visible v2 deploy status (`GET /internal/agentsdk/deployments/:slug`). */
+export type AgentkitCustomerStatus = "pending" | "deploying" | "running" | "failed" | "stopped";
+
+export type AgentkitDeployProgress =
+  | "queued"
+  | "creating"
+  | "building"
+  | "starting"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopped";
+
+export interface AgentkitDeployStatus {
+  applicationId: string;
+  releaseId: string;
+  slug: string;
+  teamId: number;
+  status: AgentkitCustomerStatus;
+  progress: AgentkitDeployProgress;
+  statusMessage: string | null;
+  /** Why the bake failed. Null/absent unless `status` is `failed`. */
+  lastError?: string | null;
+  /**
+   * `owner/name` scopes the deployment's GitHub/Origin channels watch.
+   * Absent on control planes that predate the field.
+   */
+  repositories?: string[];
+  /** Names of application-scoped secrets (values are never returned). */
+  secretNames?: string[];
+}
+
+/** One v2 application from `GET /internal/agentsdk/deployments`. */
+export interface AgentkitDeploymentListItem {
+  architecture: "v2";
+  applicationId: string;
+  releaseId: string;
+  slug: string;
+  teamId: number;
+  status: AgentkitCustomerStatus;
+  deployments: Array<{ desiredUpdatedAt: string }>;
+}
+
+export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> = new Set([
+  "running",
+  "failed",
+  "stopped",
+]);
+
+/**
+ * `POST /internal/agentsdk/deployments/:slug/stop` 202 body. Like v1
+ * {@link StopAccepted} but keyed by catalog ids instead of the numeric
+ * deployment row id.
+ */
+export interface AgentkitStopAccepted {
+  applicationId: string;
+  releaseId: string;
+  status: string;
+  /**
+   * `"global"` when the backend stopped every tenant install of a
+   * multi-tenant app. Resume with `start <slug>`.
+   */
+  scope?: "global";
+  deployLocked?: boolean;
+  cancellation?: AgentkitCancelRunsResult;
+}
+
+export interface AgentkitGlobalSuspensionAccepted {
+  applicationId: string;
+  status: "running" | "stopped";
+  cancellation?: AgentkitCancelRunsResult;
+}
+
+export interface AgentkitCancelRunsResult {
+  batchesStarted: number;
+  failed: number;
+  sessionsMarkedFailed?: number;
+}
+
+const agentkitCancelRunsResultSchema: z.ZodType<AgentkitCancelRunsResult> = z.object({
+  batchesStarted: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  sessionsMarkedFailed: z.number().int().nonnegative().optional(),
+});
+
+const agentkitEventRepositoriesSchema = z.object({
+  repositories: z.array(z.string()),
+});
+
+const agentkitInstallReleaseSchema = z.object({
+  releaseId: z.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 hosted execution of a v2 session: a pod wake that ran (or tried to
+ * run) a turn. `turnStatus` is the engine's outcome (`finished`, `error`,
+ * `running`, …); `processDeath` marks an entry flushed from a crash handler.
+ */
+export interface AgentkitSessionRun {
+  executionId: string;
+  writtenAt: string;
+  turnStatus: string;
+  durationMs: number;
+  message?: string;
+  error?: { name: string; message: string; stack?: string };
+  processDeath?: boolean;
+  logs: Array<{ index: number; at: string; line: string }>;
+}
+
+/**
+ * `GET /internal/agentsdk/deployments/:slug/sessions/:sessionId/runs` body.
+ * A v2 deployment has no resident engine to query, so these durable
+ * control-plane snapshots are the session's history.
+ */
+export interface AgentkitSessionRuns {
+  executions: AgentkitSessionRun[];
+  /** Engine start.log tee; null when the framework store has no snapshot. */
+  startLog: string | null;
+}
+
+/** One secret's metadata from the list endpoint — names only, never values. */
+export interface SecretInfo {
+  name: string;
+  createdAt: string;
+}
+
+/** One pushed container image (`agent-sdk images list`). */
+export interface ContainerImageInfo {
+  name: string;
+  sizeBytes: number;
+  sha256: string | null;
+  dockerImageId: string | null;
+  platform: string | null;
+  pushedByUserId: number | null;
+  pushedAt: string;
+}
+
+/** Phase one of `images push`: an open multipart upload and its presigned part URLs. */
+export interface ContainerImageUpload {
+  name: string;
+  uploadId: string;
+  partSizeBytes: number;
+  parts: Array<{ partNumber: number; url: string }>;
+  expiresAt: string;
+}
+
+/**
+ * `GET /internal/agent-serve/automations/:uuid/export` response
+ * (backend `agentServeAutomationExport.ts`). Name + transport references
+ * only — the backend never exports URLs or credential material.
+ */
+export interface AutomationExportMcpServer {
+  id?: string;
+  name: string;
+  transportType: "http" | "sse" | "stdio";
+}
+
+export interface AutomationExport {
+  automation: {
+    uuid: string;
+    name: string;
+    enabled: boolean;
+    scope: string;
+    webUrl: string;
+  };
+  /** The Workflow as generic proto3 JSON. */
+  workflow: Record<string, unknown>;
+  mcpServers: AutomationExportMcpServer[];
+}
+
+// All response schemas are `.passthrough()`: the backend keeps growing the
+// deployment payload (serviceAccountId, egressAllowedDomains, secret
+// metadata, ...) and unknown fields must flow through untouched — both so
+// parsing never breaks on a newer backend and so `--json` output stays
+// faithful to the API instead of silently dropping fields.
+const deployAcceptedSchema = z
+  .object({
+    id: z.number(),
+    slug: z.string(),
+    teamId: z.number(),
+    status: z.string(),
+    generation: z.number(),
+    deploymentKind: z.string(),
+    engineAlias: z.string(),
+    aliasToken: z.string().optional(),
+  })
+  .passthrough();
+
+const agentkitDeployAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    status: z.string(),
+  })
+  .passthrough();
+
+const agentkitDeployStatusSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    slug: z.string().min(1),
+    teamId: z.number(),
+    status: z.enum(["pending", "deploying", "running", "failed", "stopped"]),
+    progress: z.enum([
+      "queued",
+      "creating",
+      "building",
+      "starting",
+      "finalizing",
+      "running",
+      "failed",
+      "stopped",
+    ]),
+    statusMessage: z.string().nullable(),
+    // Optional: backends that predate the v2 bake-failure column omit it.
+    lastError: z.string().nullable().optional(),
+    secretNames: z.array(z.string()).optional(),
+  })
+  .passthrough();
+
+const agentkitDeploymentListItemSchema = z
+  .object({
+    architecture: z.literal("v2"),
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    slug: z.string().min(1),
+    teamId: z.number(),
+    status: agentkitDeployStatusSchema.shape.status,
+    deployments: z.array(z.object({ desiredUpdatedAt: z.string() }).passthrough()),
+  })
+  .passthrough();
+
+const agentkitDeploymentListResponseSchema = z.object({
+  deployments: z.array(agentkitDeploymentListItemSchema),
+  nextPageToken: z.string().nullable(),
+});
+
+const agentkitStopAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    status: z.string(),
+    // Tolerate scope values a newer backend may add: parse only "global",
+    // drop anything else rather than failing the stop response.
+    scope: z.literal("global").optional().catch(undefined),
+    deployLocked: z.boolean().optional(),
+    cancellation: agentkitCancelRunsResultSchema.optional(),
+  })
+  .passthrough();
+
+const agentkitGlobalSuspensionAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    status: z.enum(["running", "stopped"]),
+    cancellation: agentkitCancelRunsResultSchema.optional(),
+  })
+  .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 agentkitSessionRunsSchema = z
+  .object({
+    executions: z.array(
+      z
+        .object({
+          executionId: z.string().min(1),
+          writtenAt: z.string(),
+          turnStatus: z.string(),
+          durationMs: z.number().nonnegative(),
+          message: z.string().optional(),
+          error: z
+            .object({
+              name: z.string(),
+              message: z.string(),
+              stack: z.string().optional(),
+            })
+            .passthrough()
+            .optional(),
+          processDeath: z.boolean().optional(),
+          logs: z.array(
+            z
+              .object({
+                index: z.number(),
+                at: z.string(),
+                line: z.string(),
+              })
+              .passthrough(),
+          ),
+        })
+        .passthrough(),
+    ),
+    startLog: z.string().nullable(),
+  })
+  .passthrough();
+
+const deploymentSchema = z.object({
+  id: z.number(),
+  slug: z.string(),
+  teamId: z.number(),
+  deploymentKind: z.string(),
+  gitRepoUrl: z.string().nullable().optional(),
+  gitRef: z.string().optional(),
+  agentPath: z.string().optional(),
+  desiredState: z.string().optional(),
+  status: z.enum([
+    "pending",
+    "deploying",
+    "running",
+    "degraded",
+    "failed",
+    "stopping",
+    "stopped",
+    "deleting",
+  ]),
+  progress: z
+    .enum([
+      "queued",
+      "preparing",
+      "creating",
+      "building",
+      "starting",
+      "finalizing",
+      "running",
+      "failed",
+      "stopping",
+      "stopped",
+      "deleting",
+      "degraded",
+    ])
+    .optional(),
+  statusMessage: z.string().nullable().optional(),
+  generation: z.number(),
+  observedGeneration: z.number().nullable().optional(),
+  engineGeneration: z.number().nullable().optional(),
+  publicId: z.string().optional(),
+  engineUrl: z.string().nullable().optional(),
+  enginePodId: z.string().nullable().optional(),
+  lastError: z.string().nullable().optional(),
+  engineAlias: z.string(),
+  desiredUpdatedAt: z.string().optional(),
+  lastReconciledAt: z.string().nullable().optional(),
+  cursorEventRepos: z.array(z.string()).optional(),
+  egressAllowedDomains: z.array(z.string()).optional(),
+  publicRoutePaths: z.array(z.string()).optional(),
+  // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
+  // legacy rows that predate service-account-backed deploys.
+  serviceAccountId: z.union([z.string(), z.number()]).nullable().optional(),
+  agentStoreSourceId: z.string().optional(),
+  podCredentialMaskedKey: z.string().nullable().optional(),
+  secretNames: z.array(z.string()).optional(),
+});
+
+const deploymentListItemSchema = deploymentSchema.passthrough();
+
+const deploymentDetailSchema = deploymentSchema
+  .extend({
+    engineAccess: z
+      .object({
+        url: z.string(),
+        headers: z.record(z.string()),
+        expiresAt: z.string(),
+      })
+      .nullable()
+      .optional(),
+  })
+  .passthrough();
+
+const listResponseSchema = z.object({
+  deployments: z.array(deploymentListItemSchema),
+});
+
+const stopAcceptedSchema = z
+  .object({
+    id: z.number(),
+    status: z.string(),
+  })
+  .passthrough();
+
+const rotateResponseSchema = z
+  .object({
+    aliasToken: z.string().min(1),
+  })
+  .passthrough();
+
+const setSecretsResponseSchema = z
+  .object({
+    secretNames: z.array(z.string()),
+  })
+  .passthrough();
+
+const listSecretsResponseSchema = z
+  .object({
+    secrets: z.array(z.object({ name: z.string(), createdAt: z.string() }).passthrough()),
+  })
+  .passthrough();
+
+const containerImageSchema = z
+  .object({
+    name: z.string(),
+    sizeBytes: z.number(),
+    sha256: z.string().nullable(),
+    dockerImageId: z.string().nullable(),
+    platform: z.string().nullable(),
+    pushedByUserId: z.number().nullable(),
+    pushedAt: z.string(),
+  })
+  .passthrough();
+
+const listContainerImagesResponseSchema = z
+  .object({ images: z.array(containerImageSchema), limit: z.number() })
+  .passthrough();
+
+const containerImageUploadSchema = z
+  .object({
+    name: z.string(),
+    uploadId: z.string(),
+    partSizeBytes: z.number().int().positive(),
+    parts: z.array(z.object({ partNumber: z.number().int().positive(), url: z.string() })),
+    expiresAt: z.string(),
+  })
+  .passthrough();
+
+const automationExportSchema = z
+  .object({
+    automation: z
+      .object({
+        uuid: z.string(),
+        name: z.string(),
+        enabled: z.boolean(),
+        scope: z.string(),
+        webUrl: z.string(),
+      })
+      .passthrough(),
+    workflow: z.record(z.unknown()),
+    mcpServers: z.array(
+      z
+        .object({
+          id: z.string().optional(),
+          name: z.string(),
+          transportType: z.enum(["http", "sse", "stdio"]),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface AgentServeDeployClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class AgentServeDeployClient {
+  private readonly backendUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: AgentServeDeployClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /** Create or redeploy; 202 means accepted, not running (poll status). */
+  async deploy(args: {
+    teamId: number;
+    slug: string;
+    source: DeploySource;
+    template?: string;
+  }): Promise<DeployAccepted> {
+    const slugError = validateDeploymentSlug(args.slug);
+    if (slugError !== undefined) {
+      throw new DeployApiError(slugError, 400);
+    }
+    for (const domain of args.source.egressAllowedDomains ?? []) {
+      const domainError = validateEgressDomain(domain);
+      if (domainError !== undefined) {
+        throw new DeployApiError(domainError, 400);
+      }
+    }
+    // Only the git-ref member exists today; a future artifact member would
+    // upload the build first and post a different body from this branch.
+    const body: Record<string, unknown> = {
+      teamId: args.teamId,
+      slug: args.slug,
+      gitRepoUrl: args.source.gitRepoUrl,
+      ...(args.source.gitRef === undefined ? {} : { gitRef: args.source.gitRef }),
+      ...(args.source.agentPath === undefined ? {} : { agentPath: args.source.agentPath }),
+      ...(args.source.cursorEventRepos === undefined
+        ? {}
+        : { cursorEventRepos: args.source.cursorEventRepos }),
+      ...(args.source.egressAllowedDomains === undefined
+        ? {}
+        : { egressAllowedDomains: args.source.egressAllowedDomains }),
+      // JSON.stringify drops undefined keys.
+      publicRoutePaths: args.source.publicRoutePaths,
+      template: args.template,
+    };
+    const send = (): Promise<unknown> =>
+      this.request({
+        method: "POST",
+        path: "/internal/agent-serve/deployments",
+        body,
+        context: { verb: "deploy", slug: args.slug },
+      });
+    let raw: unknown;
+    try {
+      raw = await send();
+    } catch (error) {
+      const unsupportedTemplate =
+        args.template !== undefined &&
+        error instanceof DeployApiError &&
+        error.status === 400 &&
+        error.message.toLowerCase().includes("template") &&
+        /unrecognized|unknown/i.test(error.message);
+      if (!unsupportedTemplate) {
+        throw error;
+      }
+      delete body.template;
+      raw = await send();
+    }
+    return deployAcceptedSchema.parse(raw);
+  }
+
+  /**
+   * Create or redeploy onto the v2 control plane
+   * (`POST /internal/agentsdk/deployments`). 202 means accepted; poll
+   * {@link getAgentkitDeploy} until a terminal status. `components` deploys
+   * one application with several release components (one per agent
+   * directory); it is mutually exclusive with `agentPath`.
+   */
+  async deployAgentkit(args: {
+    teamId: number;
+    slug: string;
+    gitRepoUrl: string;
+    gitRef?: string;
+    agentPath?: string;
+    components?: AgentkitDeployComponent[];
+    repositories?: string[];
+    /** Redeploy an existing Cursor-managed (multi-tenant) product. */
+    multiTenant?: boolean;
+    persistent?: boolean;
+    /** Single-agent `hosting.image`; components carry their own. */
+    image?: string;
+  }): Promise<AgentkitDeployAccepted> {
+    const slugError = validateDeploymentSlug(args.slug);
+    if (slugError !== undefined) {
+      throw new DeployApiError(slugError, 400);
+    }
+    for (const component of args.components ?? []) {
+      const keyError = validateDeploymentSlug(component.componentKey);
+      if (keyError !== undefined) {
+        throw new DeployApiError(
+          `Invalid component key ${JSON.stringify(component.componentKey)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`,
+          400,
+        );
+      }
+    }
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agentsdk/deployments",
+      body: {
+        teamId: args.teamId,
+        slug: args.slug,
+        gitRepoUrl: args.gitRepoUrl,
+        gitRef: args.gitRef,
+        agentPath: args.agentPath,
+        components: args.components,
+        repositories:
+          args.repositories !== undefined && args.repositories.length > 0
+            ? args.repositories
+            : undefined,
+        ...(args.multiTenant === true ? { multiTenant: true } : {}),
+        persistent: args.persistent,
+        ...(args.image === undefined ? {} : { image: args.image }),
+      },
+      context: { verb: "deploy", slug: args.slug },
+    });
+    return agentkitDeployAcceptedSchema.parse(raw);
+  }
+
+  async getAgentkitDeploy(args: { teamId: number; slug: string }): Promise<AgentkitDeployStatus> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "get deployment", slug: args.slug },
+    });
+    return agentkitDeployStatusSchema.parse(raw);
+  }
+
+  /**
+   * Stop a v2 deployment (`POST /internal/agentsdk/deployments/:slug/stop`).
+   * 202 means accepted; poll {@link getAgentkitDeploy} until `stopped`.
+   */
+  async stopAgentkit(args: {
+    teamId: number;
+    slug: string;
+    cancelRuns?: boolean;
+  }): Promise<AgentkitStopAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path:
+        `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/stop?teamId=${args.teamId}` +
+        (args.cancelRuns === true ? "&cancelRuns=true" : ""),
+      context: { verb: "stop", slug: args.slug },
+    });
+    return agentkitStopAcceptedSchema.parse(raw);
+  }
+
+  /**
+   * Start a v2 deployment (`POST /internal/agentsdk/deployments/:slug/start`).
+   * Older backends only expose `/global-resume`; fall back there.
+   */
+  async startAgentkit(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitGlobalSuspensionAccepted> {
+    const encoded = encodeURIComponent(args.slug);
+    try {
+      const raw = await this.request({
+        method: "POST",
+        path: `/internal/agentsdk/deployments/${encoded}/start?teamId=${args.teamId}`,
+        context: { verb: "start", slug: args.slug },
+      });
+      return agentkitGlobalSuspensionAcceptedSchema.parse(raw);
+    } catch (error) {
+      if (!(error instanceof DeployApiError) || error.status !== 404) {
+        throw error;
+      }
+      const raw = await this.request({
+        method: "POST",
+        path: `/internal/agentsdk/deployments/${encoded}/global-resume?teamId=${args.teamId}`,
+        context: { verb: "start", slug: args.slug },
+      });
+      return agentkitGlobalSuspensionAcceptedSchema.parse(raw);
+    }
+  }
+
+  async setAgentkitGlobalSuspension(args: {
+    teamId: number;
+    slug: string;
+    suspended: boolean;
+    cancelRuns?: boolean;
+  }): Promise<AgentkitGlobalSuspensionAccepted> {
+    const action = args.suspended ? "global-stop" : "global-resume";
+    const cancelQuery =
+      args.suspended === true && args.cancelRuns === true ? "&cancelRuns=true" : "";
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/${action}?teamId=${args.teamId}${cancelQuery}`,
+      context: {
+        verb: args.suspended ? "globally stop" : "globally resume",
+        slug: args.slug,
+      },
+    });
+    return agentkitGlobalSuspensionAcceptedSchema.parse(raw);
+  }
+
+  async killAgentkit(args: { teamId: number; slug: string }): Promise<AgentkitStopAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/kill?teamId=${args.teamId}`,
+      context: { verb: "kill", slug: args.slug },
+    });
+    return agentkitStopAcceptedSchema.parse(raw);
+  }
+
+  async unlockAgentkitDeploys(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<{ applicationId: string; deployLocked: boolean }> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/unlock-deploys?teamId=${args.teamId}`,
+      context: { verb: "unlock deploys", slug: args.slug },
+    });
+    return z
+      .object({
+        applicationId: z.string().min(1),
+        deployLocked: z.literal(false),
+      })
+      .parse(raw);
+  }
+
+  async cancelAgentkitRuns(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitCancelRunsResult> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/cancel-runs?teamId=${args.teamId}`,
+      context: { verb: "cancel runs", slug: args.slug },
+    });
+    return agentkitCancelRunsResultSchema.parse(raw);
+  }
+
+  /**
+   * Repoint a v2 install's event repositories
+   * (`PUT /internal/agentsdk/deployments/:slug/event-repositories`). Deploy
+   * cannot carry these for a multi-tenant product.
+   */
+  async setAgentkitEventRepositories(args: {
+    teamId: number;
+    slug: string;
+    repositories: string[];
+  }): Promise<string[]> {
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/event-repositories?teamId=${args.teamId}`,
+      body: { repositories: args.repositories },
+      context: { verb: "set event repositories", slug: args.slug },
+    });
+    return agentkitEventRepositoriesSchema.parse(raw).repositories;
+  }
+
+  /**
+   * Pin a v2 install onto a release
+   * (`PUT /internal/agentsdk/deployments/:slug/release`), newest ready one
+   * when neither selector is given. A multi-tenant deploy leaves tenants
+   * on the release they were installed on.
+   */
+  async upgradeAgentkitInstall(args: {
+    teamId: number;
+    slug: string;
+    releaseId?: string;
+    version?: string;
+  }): Promise<string> {
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/release?teamId=${args.teamId}`,
+      body: {
+        ...(args.releaseId === undefined ? {} : { releaseId: args.releaseId }),
+        ...(args.version === undefined ? {} : { version: args.version }),
+      },
+      context: { verb: "upgrade", slug: args.slug },
+    });
+    return agentkitInstallReleaseSchema.parse(raw).releaseId;
+  }
+
+  /**
+   * Delete a v2 deployment (`DELETE /internal/agentsdk/deployments/:slug`).
+   * 202 means accepted; poll {@link getAgentkitDeploy} until 404.
+   */
+  async deleteAgentkit(args: { teamId: number; slug: string }): Promise<AgentkitStopAccepted> {
+    const raw = await this.request({
+      method: "DELETE",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "delete", slug: args.slug },
+    });
+    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;
+    componentKey?: 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,
+        componentKey: args.componentKey,
+      },
+      context: { verb: "start session", slug: args.slug },
+    });
+    return agentkitStartSessionAcceptedSchema.parse(raw);
+  }
+
+  /** Hosted executions and the start-log tee for one v2 session. */
+  async getAgentkitSessionRuns(args: {
+    teamId: number;
+    slug: string;
+    sessionId: string;
+  }): Promise<AgentkitSessionRuns> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/sessions/${encodeURIComponent(args.sessionId)}/runs?teamId=${args.teamId}`,
+      context: { verb: "get session runs", slug: args.slug },
+    });
+    return agentkitSessionRunsSchema.parse(raw);
+  }
+
+  async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments?teamId=${args.teamId}`,
+      context: { verb: "list deployments" },
+    });
+    return listResponseSchema.parse(raw).deployments;
+  }
+
+  async listAgentkitDeployments(args: { teamId: number }): Promise<AgentkitDeploymentListItem[]> {
+    const deployments: AgentkitDeploymentListItem[] = [];
+    let pageToken: string | null = null;
+    do {
+      const qs =
+        `teamId=${args.teamId}&pageSize=100` +
+        (pageToken === null ? "" : `&pageToken=${encodeURIComponent(pageToken)}`);
+      const page = agentkitDeploymentListResponseSchema.parse(
+        await this.request({
+          method: "GET",
+          path: `/internal/agentsdk/deployments?${qs}`,
+          context: { verb: "list architecture v2 deployments" },
+        }),
+      );
+      deployments.push(...page.deployments);
+      pageToken = page.nextPageToken;
+    } while (pageToken !== null);
+    return deployments;
+  }
+
+  async getDeployment(args: { teamId: number; slug: string }): Promise<DeploymentDetail> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "get deployment", slug: args.slug },
+    });
+    return deploymentDetailSchema.parse(raw);
+  }
+
+  async stopDeployment(args: { teamId: number; slug: string }): Promise<StopAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/stop?teamId=${args.teamId}`,
+      context: { verb: "stop", slug: args.slug },
+    });
+    return stopAcceptedSchema.parse(raw);
+  }
+
+  async deleteDeployment(args: { teamId: number; slug: string }): Promise<DeleteAccepted> {
+    const raw = await this.request({
+      method: "DELETE",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "delete", slug: args.slug },
+    });
+    return stopAcceptedSchema.parse(raw);
+  }
+
+  /** Returns the new alias token exactly once; the old one dies now. */
+  async rotateAliasToken(args: { teamId: number; slug: string }): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/rotate-alias-token?teamId=${args.teamId}`,
+      context: { verb: "rotate alias token", slug: args.slug },
+    });
+    return rotateResponseSchema.parse(raw).aliasToken;
+  }
+
+  /** Rotate the alias token on an AgentSDK v2 deployment. */
+  async rotateAgentsdkAliasToken(args: { teamId: number; slug: string }): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/rotate-alias-token?teamId=${args.teamId}`,
+      context: { verb: "rotate alias token", slug: args.slug },
+    });
+    return rotateResponseSchema.parse(raw).aliasToken;
+  }
+
+  /**
+   * Upsert secrets by name (unlisted names stay untouched). Returns the
+   * post-write union of secret names, sorted. Validates names and value
+   * sizes client-side with the backend's grammar before any network call.
+   */
+  async setSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]> {
+    this.validateSecrets(args.secrets);
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets`,
+      body: { teamId: args.teamId, secrets: args.secrets },
+      context: { verb: "set secrets", slug: args.slug },
+    });
+    return setSecretsResponseSchema.parse(raw).secretNames;
+  }
+
+  /** Upsert application-scoped secrets on an AgentSDK v2 deployment. */
+  async setAgentkitSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]> {
+    this.validateSecrets(args.secrets);
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets`,
+      body: { teamId: args.teamId, secrets: args.secrets },
+      context: { verb: "set secrets", slug: args.slug },
+    });
+    return setSecretsResponseSchema.parse(raw).secretNames;
+  }
+
+  /** Secret names + creation times; values are never returned. */
+  async listSecrets(args: { teamId: number; slug: string }): Promise<SecretInfo[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets?teamId=${args.teamId}`,
+      context: { verb: "list secrets", slug: args.slug },
+    });
+    return listSecretsResponseSchema.parse(raw).secrets;
+  }
+
+  /** Secret names + creation times for an AgentSDK v2 application. */
+  async listAgentkitSecrets(args: { teamId: number; slug: string }): Promise<SecretInfo[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets?teamId=${args.teamId}`,
+      context: { verb: "list secrets", slug: args.slug },
+    });
+    return listSecretsResponseSchema.parse(raw).secrets;
+  }
+
+  /** Remove one secret by name; 404 when it is not set. */
+  async deleteSecret(args: { teamId: number; slug: string; name: string }): Promise<void> {
+    const nameError = validateSettableSecretName(args.name);
+    if (nameError !== undefined) {
+      throw new DeployApiError(nameError, 400);
+    }
+    await this.request({
+      method: "DELETE",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+      context: { verb: "unset secret", slug: args.slug },
+    });
+  }
+
+  /** Remove one application-scoped secret from an AgentSDK v2 deployment. */
+  async deleteAgentkitSecret(args: { teamId: number; slug: string; name: string }): Promise<void> {
+    const nameError = validateSettableSecretName(args.name);
+    if (nameError !== undefined) {
+      throw new DeployApiError(nameError, 400);
+    }
+    await this.request({
+      method: "DELETE",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/secrets/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+      context: { verb: "unset secret", slug: args.slug },
+    });
+  }
+
+  private validateSecrets(secrets: Array<{ name: string; value: string }>): void {
+    for (const { name, value } of secrets) {
+      const nameError = validateSettableSecretName(name);
+      if (nameError !== undefined) {
+        throw new DeployApiError(nameError, 400);
+      }
+      if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
+        throw new DeployApiError(
+          `The value for ${name} is too large (max ${MAX_SECRET_VALUE_BYTES} bytes).`,
+          400,
+        );
+      }
+    }
+    if (secrets.length > MAX_SECRETS) {
+      throw new DeployApiError(
+        `Too many secrets in one request (${secrets.length}); deployments hold at most ${MAX_SECRETS}.`,
+        400,
+      );
+    }
+  }
+
+  /**
+   * Read an Automation's exported workflow definition for
+   * `convert-automation`. Missing, no-access, and gate-off all surface as
+   * indistinguishable 404s on the backend, so they map to one message here
+   * (the wrong-host 404 hint from {@link mapErrorResponse} passes through).
+   */
+  async exportAutomation(args: { uuid: string }): Promise<AutomationExport> {
+    let raw: unknown;
+    try {
+      raw = await this.request({
+        method: "GET",
+        path: `/internal/agent-serve/automations/${encodeURIComponent(args.uuid)}/export`,
+        context: { verb: "export automation" },
+      });
+    } catch (error) {
+      if (
+        error instanceof DeployApiError &&
+        error.status === 404 &&
+        !error.message.includes("api.cursor.com")
+      ) {
+        throw new DeployApiError(
+          `Automation ${args.uuid} was not found or you don't have access to it (the agent_serve_mvp feature gate may also be off for your team).`,
+          404,
+        );
+      }
+      throw error;
+    }
+    return automationExportSchema.parse(raw);
+  }
+
+  /** Full URL of the stable engine alias for a deployment. */
+  aliasUrl(engineAlias: string): string {
+    return `${this.backendUrl}${engineAlias}`;
+  }
+
+  /**
+   * Stable remote MCP gateway URL for a deployment, on the user-API-key
+   * surface (headless / CLI, `agent-sdk login` credential). The gateway
+   * mints/refreshes engineAccess server-side and proxies `/v1/mcp` to the
+   * pod, so a signed-in client never sees a pod hostname or port token.
+   */
+  mcpGatewayUrl(teamId: number, slug: string): string {
+    return `${this.backendUrl}/internal/agent-serve/mcp/${teamId}/${encodeURIComponent(slug)}`;
+  }
+
+  /** Team container images, newest first, with the per-team cap. */
+  async listContainerImages(args: {
+    teamId: number;
+  }): Promise<{ images: ContainerImageInfo[]; limit: number }> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentsdk/images?teamId=${args.teamId}`,
+      context: { verb: "list images" },
+    });
+    return listContainerImagesResponseSchema.parse(raw);
+  }
+
+  /** Start (or restart) the upload for `name`; 409 when a new name would exceed the cap. */
+  async beginContainerImageUpload(args: {
+    teamId: number;
+    name: string;
+    sizeBytes: number;
+    sha256: string;
+    dockerImageId?: string;
+    platform?: string;
+  }): Promise<ContainerImageUpload> {
+    const { name, ...body } = args;
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/images/${encodeURIComponent(name)}/begin`,
+      body,
+      context: { verb: "push image" },
+    });
+    return containerImageUploadSchema.parse(raw);
+  }
+
+  /** Every part is uploaded: complete the object and mark the image ready. */
+  async finalizeContainerImage(args: {
+    teamId: number;
+    name: string;
+    uploadId: string;
+    parts: Array<{ partNumber: number; etag: string }>;
+  }): Promise<ContainerImageInfo> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/images/${encodeURIComponent(args.name)}/finalize`,
+      body: { teamId: args.teamId, uploadId: args.uploadId, parts: args.parts },
+      context: { verb: "push image" },
+    });
+    return z.object({ image: containerImageSchema }).passthrough().parse(raw).image;
+  }
+
+  /** Remove one image and its tarball; 404 when there is none by that name. */
+  async deleteContainerImage(args: { teamId: number; name: string }): Promise<void> {
+    await this.request({
+      method: "DELETE",
+      path: `/internal/agentsdk/images/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+      context: { verb: "remove image" },
+    });
+  }
+
+  private async request(args: {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+    context: { verb: string; slug?: string };
+  }): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}${args.path}`, {
+        method: args.method,
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+          ...(args.body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(args.body === undefined ? {} : { body: JSON.stringify(args.body) }),
+        signal: AbortSignal.timeout(60_000),
+      });
+    } catch (error) {
+      throw new DeployApiError(
+        `Could not reach the Cursor backend at ${this.backendUrl}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        0,
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw mapErrorResponse(response, text, args.context);
+    }
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new DeployApiError(
+        `The Cursor backend returned a non-JSON response to ${args.context.verb}.`,
+        response.status,
+      );
+    }
+  }
+}
+
+const MCP_GATEWAY_PATH = /^\/internal\/agent-serve\/mcp\/(\d+)\/([^/]+)(?:\/tools)?\/?$/;
+
+/**
+ * Inverse of {@link AgentServeDeployClient.mcpGatewayUrl}. Also accepts
+ * the hosted `--cloud-tools-url` form (`…/tools`).
+ */
+export function parseAgentServeMcpGatewayUrl(
+  url: string,
+): { teamId: number; slug: string } | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const match = MCP_GATEWAY_PATH.exec(parsed.pathname);
+  if (match === null) {
+    return undefined;
+  }
+  const teamId = Number.parseInt(match[1]!, 10);
+  if (!Number.isInteger(teamId) || teamId <= 0) {
+    return undefined;
+  }
+  const slug = decodeURIComponent(match[2]!);
+  if (validateDeploymentSlug(slug) !== undefined) {
+    return undefined;
+  }
+  return { teamId, slug };
+}
+
+// ============================================================================
+// Error mapping (HTTP → actionable human messages)
+// ============================================================================
+
+function serverErrorText(bodyText: string): string | undefined {
+  try {
+    const parsed = JSON.parse(bodyText) as { error?: unknown };
+    if (typeof parsed.error === "string" && parsed.error !== "") {
+      return parsed.error;
+    }
+  } catch {
+    // Non-JSON body — fall through.
+  }
+  return undefined;
+}
+
+function mapErrorResponse(
+  response: Response,
+  bodyText: string,
+  context: { verb: string; slug?: string },
+): DeployApiError {
+  const serverError = serverErrorText(bodyText);
+  const slugPart = context.slug === undefined ? "" : ` "${context.slug}"`;
+  switch (response.status) {
+    case 400:
+      return new DeployApiError(
+        serverError ?? `The ${context.verb} request was rejected as invalid.`,
+        400,
+      );
+    case 401:
+      return new DeployApiError(
+        "The Cursor API key was rejected. Run `agent-sdk login` again or update CURSOR_API_KEY.",
+        401,
+      );
+    case 403:
+      return new DeployApiError(
+        `${serverError ?? "Not authorized"} — deploying needs team membership and the cloud-agent entitlement on that team.`,
+        403,
+      );
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a missing deployment / closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new DeployApiError(
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/* and /internal/agentsdk/*.`,
+          404,
+        );
+      }
+      return new DeployApiError(
+        context.slug === undefined
+          ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`
+          : `Deployment${slugPart} was not found — check the slug and --team, or the agent_serve_mvp feature gate may not be enabled for your team.`,
+        404,
+      );
+    }
+    case 409:
+      // The server's 409 body distinguishes real conflicts (CAS races,
+      // "still deploying", architecture-v2 slugs on the v1 surface); keep
+      // its message when present.
+      return new DeployApiError(
+        serverError ??
+          `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,
+        409,
+      );
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSeconds =
+        retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
+          ? Number(retryAfterHeader)
+          : undefined;
+      return new DeployApiError(
+        `${serverError ?? "Rate limited"}${
+          retryAfterSeconds === undefined ? "" : ` — retry in ${retryAfterSeconds}s`
+        }`,
+        429,
+        retryAfterSeconds,
+      );
+    }
+    default:
+      return new DeployApiError(
+        `The ${context.verb} request failed (${response.status}): ${
+          serverError ?? bodyText.slice(0, 300) ?? "(empty body)"
+        }`,
+        response.status,
+      );
+  }
+}