@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/deploy-client.ts

@@ -1,1504 +0,0 @@
-/**
- * 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,
-      );
-  }
-}