@cursor/bdk 0.2.1

package/dist/internal/deploy-client.js

@@ -0,0 +1,987 @@
+/**
+ * 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".
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { z } from "zod";
+import { MAX_SECRET_VALUE_BYTES, MAX_SECRETS, validateEgressDomain, validateSettableSecretName, } from "./hosting.js";
+export const TERMINAL_DEPLOY_STATUSES = new Set([
+    "running",
+    "degraded",
+    "failed",
+    "stopped",
+]);
+const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
+/** Returns a human error message, or undefined when the slug is valid. */
+export function validateDeploymentSlug(slug) {
+    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) {
+    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, status, 
+    /** Seconds to wait before retrying (from `Retry-After` on 429s). */
+    retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "DeployApiError";
+    }
+}
+/**
+ * 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) {
+    const raw = deployment.serviceAccountId;
+    if (raw === null || raw === undefined) {
+        return undefined;
+    }
+    const id = String(raw).trim();
+    return id === "" ? undefined : id;
+}
+export const TERMINAL_AGENTKIT_DEPLOY_STATUSES = new Set([
+    "running",
+    "failed",
+    "stopped",
+]);
+const agentkitCancelRunsResultSchema = 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(),
+});
+// 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();
+export class AgentServeDeployClient {
+    constructor(options) {
+        var _a;
+        this.backendUrl = options.backendUrl.endsWith("/")
+            ? options.backendUrl.slice(0, -1)
+            : options.backendUrl;
+        this.apiKey = options.apiKey;
+        this.fetchImpl = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+    }
+    /** Create or redeploy; 202 means accepted, not running (poll status). */
+    deploy(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const slugError = validateDeploymentSlug(args.slug);
+            if (slugError !== undefined) {
+                throw new DeployApiError(slugError, 400);
+            }
+            for (const domain of (_a = args.source.egressAllowedDomains) !== null && _a !== void 0 ? _a : []) {
+                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 = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ 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 = () => this.request({
+                method: "POST",
+                path: "/internal/agent-serve/deployments",
+                body,
+                context: { verb: "deploy", slug: args.slug },
+            });
+            let raw;
+            try {
+                raw = yield 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 = yield 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`.
+     */
+    deployAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const slugError = validateDeploymentSlug(args.slug);
+            if (slugError !== undefined) {
+                throw new DeployApiError(slugError, 400);
+            }
+            for (const component of (_a = args.components) !== null && _a !== void 0 ? _a : []) {
+                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 = yield this.request({
+                method: "POST",
+                path: "/internal/agentsdk/deployments",
+                body: Object.assign(Object.assign(Object.assign({ 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);
+        });
+    }
+    getAgentkitDeploy(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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`.
+     */
+    stopAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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.
+     */
+    startAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const encoded = encodeURIComponent(args.slug);
+            try {
+                const raw = yield 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 = yield this.request({
+                    method: "POST",
+                    path: `/internal/agentsdk/deployments/${encoded}/global-resume?teamId=${args.teamId}`,
+                    context: { verb: "start", slug: args.slug },
+                });
+                return agentkitGlobalSuspensionAcceptedSchema.parse(raw);
+            }
+        });
+    }
+    setAgentkitGlobalSuspension(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const action = args.suspended ? "global-stop" : "global-resume";
+            const cancelQuery = args.suspended === true && args.cancelRuns === true ? "&cancelRuns=true" : "";
+            const raw = yield 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);
+        });
+    }
+    killAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
+    unlockAgentkitDeploys(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
+    cancelAgentkitRuns(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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.
+     */
+    setAgentkitEventRepositories(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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.
+     */
+    upgradeAgentkitInstall(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "PUT",
+                path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/release?teamId=${args.teamId}`,
+                body: Object.assign(Object.assign({}, (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.
+     */
+    deleteAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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/*`.
+     */
+    startSession(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    getAgentkitSessionRuns(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
+    listDeployments(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "GET",
+                path: `/internal/agent-serve/deployments?teamId=${args.teamId}`,
+                context: { verb: "list deployments" },
+            });
+            return listResponseSchema.parse(raw).deployments;
+        });
+    }
+    listAgentkitDeployments(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const deployments = [];
+            let pageToken = null;
+            do {
+                const qs = `teamId=${args.teamId}&pageSize=100` +
+                    (pageToken === null ? "" : `&pageToken=${encodeURIComponent(pageToken)}`);
+                const page = agentkitDeploymentListResponseSchema.parse(yield 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;
+        });
+    }
+    getDeployment(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
+    stopDeployment(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
+    deleteDeployment(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    rotateAliasToken(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    rotateAgentsdkAliasToken(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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.
+     */
+    setSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateSecrets(args.secrets);
+            const raw = yield 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. */
+    setAgentkitSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateSecrets(args.secrets);
+            const raw = yield 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. */
+    listSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    listAgentkitSecrets(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    deleteSecret(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nameError = validateSettableSecretName(args.name);
+            if (nameError !== undefined) {
+                throw new DeployApiError(nameError, 400);
+            }
+            yield 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. */
+    deleteAgentkitSecret(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nameError = validateSettableSecretName(args.name);
+            if (nameError !== undefined) {
+                throw new DeployApiError(nameError, 400);
+            }
+            yield 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 },
+            });
+        });
+    }
+    validateSecrets(secrets) {
+        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).
+     */
+    exportAutomation(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let raw;
+            try {
+                raw = yield 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) {
+        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, slug) {
+        return `${this.backendUrl}/internal/agent-serve/mcp/${teamId}/${encodeURIComponent(slug)}`;
+    }
+    /** Team container images, newest first, with the per-team cap. */
+    listContainerImages(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    beginContainerImageUpload(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { name } = args, body = __rest(args, ["name"]);
+            const raw = yield 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. */
+    finalizeContainerImage(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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. */
+    deleteContainerImage(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.request({
+                method: "DELETE",
+                path: `/internal/agentsdk/images/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+                context: { verb: "remove image" },
+            });
+        });
+    }
+    request(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let response;
+            try {
+                response = yield this.fetchImpl(`${this.backendUrl}${args.path}`, Object.assign(Object.assign({ method: args.method, headers: Object.assign({ 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(60000) }));
+            }
+            catch (error) {
+                throw new DeployApiError(`Could not reach the Cursor backend at ${this.backendUrl}: ${error instanceof Error ? error.message : String(error)}`, 0);
+            }
+            const text = yield response.text();
+            if (!response.ok) {
+                throw mapErrorResponse(response, text, args.context);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (_a) {
+                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) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (_a) {
+        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) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (typeof parsed.error === "string" && parsed.error !== "") {
+            return parsed.error;
+        }
+    }
+    catch (_a) {
+        // Non-JSON body — fall through.
+    }
+    return undefined;
+}
+function mapErrorResponse(response, bodyText, context) {
+    var _a;
+    const serverError = serverErrorText(bodyText);
+    const slugPart = context.slug === undefined ? "" : ` "${context.slug}"`;
+    switch (response.status) {
+        case 400:
+            return new DeployApiError(serverError !== null && serverError !== void 0 ? 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 !== null && serverError !== void 0 ? 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 !== null && serverError !== void 0 ? 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 !== null && serverError !== void 0 ? serverError : "Rate limited"}${retryAfterSeconds === undefined ? "" : ` — retry in ${retryAfterSeconds}s`}`, 429, retryAfterSeconds);
+        }
+        default:
+            return new DeployApiError(`The ${context.verb} request failed (${response.status}): ${(_a = serverError !== null && serverError !== void 0 ? serverError : bodyText.slice(0, 300)) !== null && _a !== void 0 ? _a : "(empty body)"}`, response.status);
+    }
+}