@cursor/july 0.1.94 → 0.1.95

package/src/internal/cli-deploy.ts

@@ -27,6 +27,7 @@ import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   type AgentkitDeployAccepted,
+  type AgentkitDeployComponent,
   type AgentkitDeployStatus,
   type AgentkitStopAccepted,
   AgentServeDeployClient,
@@ -294,10 +295,35 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     return targets;
   }
 
+  if (targets.length === 1) {
+    return deployOne(ctx, options, targets[0]!);
+  }
+
+  // Multi-agent parent: when every child declares `architecture: "v2"`,
+  // the v2 control plane models sibling agents as release components of
+  // ONE application, so deploy them together (one app, one component per
+  // child) instead of minting a separate application per child. Mixed and
+  // v1 parents keep the per-child sequential deploys.
+  const manifests: DeployManifest[] = [];
+  for (const target of targets) {
+    manifests.push(await readDeployManifest(target.dir));
+  }
+  if (manifests.every((manifest) => manifest.architecture === "v2")) {
+    return deployAgentsdkApplication(ctx, options, targets);
+  }
+  if (
+    !ctx.json &&
+    manifests.some((manifest) => manifest.architecture === "v2")
+  ) {
+    ctx.err(
+      `warning: agents under this parent mix architectures; deploying each separately (v2 children become standalone single-component applications).\n`
+    );
+  }
+
   // --path is per-agent (relative to the repo root). When deploying several
   // agents, ignore a shared --path so each target can infer its own path.
   let deployOptions = options;
-  if (targets.length > 1 && options.path !== undefined) {
+  if (options.path !== undefined) {
     if (!ctx.json) {
       ctx.err(
         `warning: ignoring --path ${JSON.stringify(options.path)} for a multi-agent deploy; each agent infers its own path from git.\n`
@@ -306,10 +332,6 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     deployOptions = { ...options, path: undefined };
   }
 
-  if (targets.length === 1) {
-    return deployOne(ctx, deployOptions, targets[0]!);
-  }
-
   // Multi-agent batch: deploy sequentially; --json emits an array.
   const jsonResults: unknown[] = [];
   let failures = 0;
@@ -477,6 +499,19 @@ async function resolveDeployTargets(
     return [match];
   }
 
+  // An all-v2 parent deploys as ONE application (siblings are components
+  // of a single app on the v2 control plane), so "deploy the parent" is
+  // unambiguous and needs no picker or --all. A child that is v1 — or
+  // fails to load — keeps the interactive picker below.
+  if (await allChildrenAreV2(children)) {
+    if (!ctx.json) {
+      ctx.err(
+        `Deploying all ${children.length} v2 agents under ${basename(dir)} as one application (pass --slug <name> to deploy a single agent standalone).\n`
+      );
+    }
+    return [...children];
+  }
+
   const chooser =
     options.chooseTargets ??
     ((agents) =>
@@ -508,6 +543,27 @@ function formatAgentList(agents: readonly DeployTarget[]): string {
   return agents.map((agent, i) => `  ${i + 1}) ${agent.slug}\n`).join("");
 }
 
+/**
+ * True when every child agent project loads and declares
+ * `architecture: "v2"`. Broken projects count as not-v2 so target
+ * resolution falls back to the picker instead of failing the whole deploy
+ * on a child the user might not even select.
+ */
+async function allChildrenAreV2(
+  children: readonly DeployTarget[]
+): Promise<boolean> {
+  for (const child of children) {
+    try {
+      if ((await readDeployManifest(child.dir)).architecture !== "v2") {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * TTY picker for multi-agent parents. Non-interactive callers get `[]`
  * so {@link resolveDeployTargets} can print the --slug/--all hint.
@@ -777,6 +833,100 @@ async function deployOne(
   return 0;
 }
 
+/**
+ * Multi-agent parent whose children all declare `architecture: "v2"`:
+ * deploy ONE application whose release carries a component per child. The
+ * application slug derives from the parent directory name; each component
+ * key is the child's slug and its path is the child directory relative to
+ * the repo root (a shared --path names the parent's directory in the repo).
+ */
+async function deployAgentsdkApplication(
+  ctx: DeployCliContext,
+  options: DeployCliOptions,
+  targets: readonly DeployTarget[]
+): Promise<number> {
+  const parentDir = resolve(options.dir ?? ".");
+  const slug = slugFromDirectoryName(basename(parentDir));
+  if (slug === undefined) {
+    ctx.err(
+      `Could not derive an application slug from the parent directory name ${JSON.stringify(basename(parentDir))} — rename it (deploy slugs use lowercase letters, digits, '-' or '_').\n`
+    );
+    return 1;
+  }
+
+  const needsGitInference =
+    options.repo === undefined ||
+    options.ref === undefined ||
+    options.path === undefined;
+  const inferred = needsGitInference
+    ? await inferDeployGitSource(parentDir, {
+        ...(options.git === undefined ? {} : { git: options.git }),
+      })
+    : {};
+  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
+  const gitRef = options.ref ?? inferred.gitRef;
+  const parentPath = options.path ?? inferred.agentPath;
+
+  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
+    ctx.err(
+      `Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`
+    );
+    return 1;
+  }
+  if (gitRepoUrl === undefined) {
+    ctx.err(
+      `Could not resolve an https:// git repository URL for this deploy.\n` +
+        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n`
+    );
+    return 1;
+  }
+  for (const repo of options.cursorEventsRepos ?? []) {
+    if (!isValidCursorEventRepo(repo)) {
+      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
+      return 1;
+    }
+  }
+
+  const components: AgentkitDeployComponent[] = targets.map((target) => ({
+    componentKey: target.slug,
+    agentPath: [parentPath, basename(target.dir)]
+      .filter((part): part is string => part !== undefined && part !== "")
+      .join("/"),
+  }));
+
+  if (!ctx.json) {
+    ctx.err(
+      `Deploying "${slug}" as one v2 application with ${targets.length} components (slug from the parent directory name).\n` +
+        `  architecture: v2\n` +
+        `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
+        components
+          .map(
+            (component) =>
+              `  component: ${component.componentKey} (${component.agentPath ?? "."})\n`
+          )
+          .join("")
+    );
+  }
+
+  // Components bake sequentially on the control plane, so the default wait
+  // budget is per component; otherwise a 2+ component deploy routinely hits
+  // the client-side timeout while the server-side deploy is still fine. An
+  // explicitly passed timeout always wins.
+  const waitCtx =
+    options.timeoutMs === undefined
+      ? { ...ctx, timeoutMs: ctx.timeoutMs * targets.length }
+      : ctx;
+
+  return deployOneAgentsdk(waitCtx, undefined, {
+    slug,
+    gitRepoUrl,
+    gitRef,
+    agentPath: undefined,
+    components,
+    repositories: options.cursorEventsRepos,
+  });
+}
+
 /**
  * `architecture: "v2"` deploy: POST `/internal/agentkit/deployments` and
  * poll the matching GET. The v2 accept path starts freeze bake; it does
@@ -790,10 +940,17 @@ async function deployOneAgentsdk(
     gitRepoUrl: string;
     gitRef: string | undefined;
     agentPath: string | undefined;
+    components?: AgentkitDeployComponent[];
     repositories: string[] | undefined;
   }
 ): Promise<number> {
   const { slug } = args;
+  const componentsLine =
+    args.components === undefined
+      ? ""
+      : `  components:  ${args.components
+          .map((component) => component.componentKey)
+          .join(", ")}\n`;
   let accepted: AgentkitDeployAccepted;
   try {
     accepted = await ctx.client.deployAgentkit({
@@ -802,6 +959,7 @@ async function deployOneAgentsdk(
       gitRepoUrl: args.gitRepoUrl,
       gitRef: args.gitRef,
       agentPath: args.agentPath,
+      components: args.components,
       repositories: args.repositories,
     });
   } catch (error) {
@@ -817,7 +975,8 @@ async function deployOneAgentsdk(
       ctx.out(
         `Deploy accepted: ${slug} (team ${ctx.teamId}, v2)\n` +
           `  application: ${accepted.applicationId}\n` +
-          `  release:     ${accepted.releaseId}\n`
+          `  release:     ${accepted.releaseId}\n` +
+          componentsLine
       );
     }
     return 0;
@@ -851,7 +1010,12 @@ async function deployOneAgentsdk(
       `  status:       running\n` +
       `  architecture: v2\n` +
       `  application:  ${detail.applicationId}\n` +
-      `  release:      ${detail.releaseId}\n`
+      `  release:      ${detail.releaseId}\n` +
+      (args.components === undefined
+        ? ""
+        : `  components:   ${args.components
+            .map((component) => component.componentKey)
+            .join(", ")}\n`)
   );
   return 0;
 }

package/src/internal/conversation-mirror.ts

@@ -0,0 +1,330 @@
+/**
+ * Durable mirror for the SDK runner's conversation store.
+ *
+ * The Cursor SDK keeps each local conversation in SQLite under the engine's
+ * state root (`runner/index.db` + `runner/agents/agent-<hash>/store.db`).
+ * That disk dies with the pod: on architecture v2, session **records** and
+ * event chunks survive replacement through the control-plane storage mirror
+ * (framework-storage-selection.ts), but the conversation itself was never
+ * hydrated anywhere — a replacement pod resumed every thread as a fresh
+ * conversation.
+ *
+ * This module mirrors the conversation through the SDK's own store APIs —
+ * the agent document (which carries `sdkMetadata.blobEncryptionKey`, without
+ * which the checkpoint blobs cannot be decrypted) plus its content-addressed
+ * checkpoint blobs — into the deployment's shared file storage. On
+ * Cursor-managed hosting that is the Agent Store reached over
+ * `/v0/agent-serve-files` presigned URLs: the store is **not mounted** as a
+ * filesystem in the engine VM (the FUSE mount at
+ * {@link DEPLOYMENT_STORE_MOUNT_PATH} exists only on cloud-runtime VMs), so
+ * the mirror moves bytes through the {@link FileSink} contract instead.
+ *
+ * Going through the store APIs rather than copying `store.db` files sidesteps
+ * WAL consistency and the shared `index.db` (per-session raw copies would
+ * clobber other sessions' rows); checkpoint blobs are content-addressed, so
+ * repeat persists upload only what is new.
+ *
+ * Timing: the runner hydrates before `Agent.resume` (so a follow-up landing
+ * on a fresh pod — including a v2 hosted-execution delivery — finds the
+ * conversation before the turn runs) and persists after each local turn
+ * settles, **awaited**, because a hosted pod can be parked immediately after
+ * the execution reply.
+ *
+ * Run rows and run events are deliberately not mirrored: they are per-pod
+ * bookkeeping (turn numbers, stream offsets), and the durable session event
+ * stream already lives in the control-plane storage mirror.
+ */
+
+import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
+import type { AgentProject } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+
+/**
+ * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
+ * durable file storage. Implemented by {@link createConversationMirror};
+ * consumed by the SDK runner.
+ */
+export interface ConversationMirror {
+  /**
+   * Restore `sdkAgentId`'s conversation into `store` when the store does not
+   * already hold it. Resolves `true` when a conversation was restored,
+   * `false` on a definitive miss (never persisted, or already local — the
+   * caller falls through to its fresh-conversation path). A sink **failure**
+   * propagates: an outage must fail the turn (retryable) rather than
+   * silently fork the thread onto a fresh conversation.
+   */
+  hydrate(store: LocalAgentStore, sdkAgentId: string): Promise<boolean>;
+  /**
+   * Mirror `sdkAgentId`'s conversation from `store` to the sink
+   * (last write wins). No-op until the conversation has a checkpoint.
+   */
+  persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
+}
+
+/** Wire shape at {@link agentStoreKeys.conversationManifest}. */
+interface ConversationManifestV1 {
+  v: 1;
+  /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
+  agent: LocalAgentDocument;
+  /** Checkpoint blob ids present under the conversation's blob prefix. */
+  blobIds: string[];
+  persistedAtMs: number;
+}
+
+export interface CreateConversationMirrorOptions {
+  sink: FileSink;
+  /** Agent name baked into every minted key. */
+  agentName: string;
+  logger?: (line: string) => void;
+}
+
+/** Build a {@link ConversationMirror} over a {@link FileSink}. */
+export function createConversationMirror(
+  options: CreateConversationMirrorOptions
+): ConversationMirror {
+  const { sink, agentName } = options;
+  const logger = options.logger ?? (() => {});
+  /** Blob ids known to be in the sink, per SDK agent id (upload dedupe). */
+  const mirrored = new Map<string, Set<string>>();
+  /**
+   * Per-conversation serialization so a persist cannot interleave with a
+   * hydrate (or another persist) for the same conversation.
+   */
+  const chains = new Map<string, Promise<unknown>>();
+
+  function serialize<T>(sdkAgentId: string, run: () => Promise<T>): Promise<T> {
+    const previous = chains.get(sdkAgentId) ?? Promise.resolve();
+    const next = previous.then(run, run);
+    chains.set(
+      sdkAgentId,
+      next.catch(() => {})
+    );
+    return next;
+  }
+
+  async function mirroredBlobIds(sdkAgentId: string): Promise<Set<string>> {
+    const cached = mirrored.get(sdkAgentId);
+    if (cached !== undefined) {
+      return cached;
+    }
+    // Seed from the previous manifest so a fresh pod does not re-upload the
+    // whole history on its first persist. A miss (or parse failure) seeds
+    // empty — re-uploading is wasteful, never wrong.
+    const seeded = new Set<string>();
+    try {
+      const manifest = await readManifest(sink, agentName, sdkAgentId);
+      for (const blobId of manifest?.blobIds ?? []) {
+        seeded.add(blobId);
+      }
+    } catch (error) {
+      logger(
+        `[agent-sdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`
+      );
+    }
+    mirrored.set(sdkAgentId, seeded);
+    return seeded;
+  }
+
+  return {
+    persist(store, sdkAgentId): Promise<void> {
+      return serialize(sdkAgentId, async () => {
+        const document = await store.agents.get({ agentId: sdkAgentId });
+        if (document === null || document.latestCheckpoint == null) {
+          // Nothing restorable yet (no conversation, or no checkpoint).
+          return;
+        }
+        const uploaded = await mirroredBlobIds(sdkAgentId);
+        const blobIds = await listCheckpointBlobIds(store, sdkAgentId);
+        for (const blobId of blobIds) {
+          if (uploaded.has(blobId)) {
+            continue;
+          }
+          const bytes = await store.checkpoints.get({
+            agentId: sdkAgentId,
+            blobId,
+          });
+          if (bytes === null) {
+            continue;
+          }
+          await sink.put(
+            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+            bytes
+          );
+          // Content-addressed: once in the sink, never re-uploaded.
+          uploaded.add(blobId);
+        }
+        const manifest: ConversationManifestV1 = {
+          v: 1,
+          // The referenced run is pod-local bookkeeping and is not mirrored;
+          // a hydrated store must not point at a run row it does not hold.
+          agent: { ...document, activeRunId: null },
+          blobIds: blobIds.filter((blobId) => uploaded.has(blobId)),
+          persistedAtMs: Date.now(),
+        };
+        // Manifest last: it only ever references blobs already uploaded.
+        await sink.put(
+          agentStoreKeys.conversationManifest(agentName, sdkAgentId),
+          new TextEncoder().encode(JSON.stringify(manifest))
+        );
+      });
+    },
+
+    hydrate(store, sdkAgentId): Promise<boolean> {
+      return serialize(sdkAgentId, async () => {
+        const existing = await store.agents.get({ agentId: sdkAgentId });
+        if (existing !== null) {
+          return false;
+        }
+        const manifest = await readManifest(sink, agentName, sdkAgentId);
+        if (manifest === undefined) {
+          return false;
+        }
+        const rootBlobId = manifest.agent.latestCheckpoint?.rootBlobId;
+        const restored = new Set<string>();
+        for (const blobId of manifest.blobIds) {
+          const body = await sink.get(
+            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)
+          );
+          const bytes =
+            body === undefined
+              ? undefined
+              : body instanceof Uint8Array
+                ? body
+                : body.body;
+          if (bytes === undefined) {
+            // Definitive absence (never uploaded, or deleted). A missing
+            // root blob makes the conversation unrestorable — fall through
+            // to the caller's fresh-conversation path rather than creating
+            // an agent row whose checkpoint cannot load.
+            if (blobId === rootBlobId) {
+              logger(
+                `[agent-sdk] conversation mirror: the root checkpoint blob for ${sdkAgentId} is missing from the sink; treating the conversation as unrestorable`
+              );
+              return false;
+            }
+            continue;
+          }
+          if (
+            (await store.checkpoints.get({ agentId: sdkAgentId, blobId })) ===
+            null
+          ) {
+            await store.checkpoints.create({
+              agentId: sdkAgentId,
+              blobId,
+              data: bytes,
+            });
+          }
+          restored.add(blobId);
+        }
+        if (rootBlobId !== undefined && !restored.has(rootBlobId)) {
+          logger(
+            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`
+          );
+          return false;
+        }
+        await store.agents.create({
+          agent: { ...manifest.agent, activeRunId: null },
+        });
+        mirrored.set(sdkAgentId, restored);
+        logger(
+          `[agent-sdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`
+        );
+        return true;
+      });
+    },
+  };
+}
+
+async function readManifest(
+  sink: FileSink,
+  agentName: string,
+  sdkAgentId: string
+): Promise<ConversationManifestV1 | undefined> {
+  const body = await sink.get(
+    agentStoreKeys.conversationManifest(agentName, sdkAgentId)
+  );
+  if (body === undefined) {
+    return undefined;
+  }
+  const bytes = body instanceof Uint8Array ? body : body.body;
+  const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    (parsed as { v?: unknown }).v !== 1
+  ) {
+    throw new Error(
+      `conversation mirror: unsupported manifest for ${sdkAgentId}`
+    );
+  }
+  const manifest = parsed as ConversationManifestV1;
+  if (
+    manifest.agent === null ||
+    typeof manifest.agent !== "object" ||
+    manifest.agent.agentId !== sdkAgentId ||
+    !Array.isArray(manifest.blobIds)
+  ) {
+    throw new Error(
+      `conversation mirror: malformed manifest for ${sdkAgentId}`
+    );
+  }
+  return manifest;
+}
+
+async function listCheckpointBlobIds(
+  store: LocalAgentStore,
+  sdkAgentId: string
+): Promise<string[]> {
+  const blobIds: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await store.checkpoints.list({
+      filter: { agentIds: [sdkAgentId], cursor },
+    });
+    blobIds.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return blobIds;
+}
+
+/**
+ * Whether (and over which sink) this serve process mirrors conversations.
+ *
+ * Selected for architecture-v2 agents on Cursor-managed hosting — the same
+ * generation signal as framework-storage-selection.ts, plus a provisioned
+ * deployment file store. Self-hosted v2 keeps everything on the state root
+ * (the operator owns the disk), and v1 keeps today's behavior while it runs.
+ */
+export function selectConversationMirror(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+}): ConversationMirror | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  if (
+    env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined ||
+    !isCursorHostedFilesAvailable(env as NodeJS.ProcessEnv)
+  ) {
+    return undefined;
+  }
+  return createConversationMirror({
+    sink: cursorHostedFiles({
+      // Full chain (env → key file → stored login): frozen engines listen
+      // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
+      // is constructed.
+      apiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+  });
+}

package/src/internal/deferred-channel-session.ts

@@ -0,0 +1,61 @@
+import type { ChannelSession } from "../types.js";
+
+const deferredSessions = new WeakSet<ChannelSession>();
+
+/**
+ * Authored code touched a member of the deferred handle that needs the live
+ * session. This is deterministic (the session never exists during admission),
+ * so the admission route surfaces it as a non-retryable 422 rather than a
+ * retryable failure.
+ */
+export class DeferredChannelSessionError extends Error {
+  constructor(member: string) {
+    super(
+      `ChannelSession.${member} is not available on a send() captured ` +
+        "during hosted admission: the control plane allocates the session " +
+        "(and runs the turn) only after this delivery is acknowledged, so " +
+        "the handle cannot observe it yet. Move work that needs the live " +
+        "session into the session turn instead."
+    );
+  }
+}
+
+function unavailable(member: string): never {
+  throw new DeferredChannelSessionError(member);
+}
+
+/**
+ * Inert `ChannelSession` returned by the hosted-admission `send` stub: every
+ * member fails loudly via {@link DeferredChannelSessionError}. Caveat: new
+ * OPTIONAL members added to `ChannelSession` slip through this factory
+ * silently (reads return `undefined`) until a throwing getter is added here.
+ */
+export function createDeferredChannelSession(): ChannelSession {
+  const session: ChannelSession = {
+    get id(): string {
+      return unavailable("id");
+    },
+    get continuationToken(): string | null {
+      return unavailable("continuationToken");
+    },
+    get isNew(): boolean {
+      return unavailable("isNew");
+    },
+    get coalesced(): boolean | undefined {
+      return unavailable("coalesced");
+    },
+    get info(): ChannelSession["info"] {
+      return unavailable("info");
+    },
+    getEventStream: async () => unavailable("getEventStream()"),
+    waitForCompletion: async () => unavailable("waitForCompletion()"),
+    setContinuationToken: async () => unavailable("setContinuationToken()"),
+  };
+  deferredSessions.add(session);
+  return session;
+}
+
+/** True when `send()` returned a hosted-admission capture handle. */
+export function isDeferredChannelSession(session: ChannelSession): boolean {
+  return deferredSessions.has(session);
+}

package/src/internal/deploy-client.ts

@@ -224,6 +224,16 @@ export interface AgentkitDeployAccepted {
   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;
+}
+
 /** Customer-visible v2 deploy status (`GET /internal/agentkit/deployments/:slug`). */
 export type AgentkitCustomerStatus =
   | "pending"
@@ -576,7 +586,9 @@ export class AgentServeDeployClient {
   /**
    * Create or redeploy onto the v2 control plane
    * (`POST /internal/agentkit/deployments`). 202 means accepted; poll
-   * {@link getAgentkitDeploy} until a terminal status.
+   * {@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;
@@ -584,12 +596,22 @@ export class AgentServeDeployClient {
     gitRepoUrl: string;
     gitRef?: string;
     agentPath?: string;
+    components?: AgentkitDeployComponent[];
     repositories?: 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/agentkit/deployments",
@@ -599,6 +621,7 @@ export class AgentServeDeployClient {
         gitRepoUrl: args.gitRepoUrl,
         gitRef: args.gitRef,
         agentPath: args.agentPath,
+        components: args.components,
         repositories:
           args.repositories !== undefined && args.repositories.length > 0
             ? args.repositories