@cursor/bdk 0.2.2 → 0.2.3

package/src/extensions/cursor-grokbot-agents/lib/conversation.ts

@@ -0,0 +1,260 @@
+/**
+ * One exchange with a hosted Grok Bot agent, the way the grokbot runtime
+ * drives a turn: send a user message, then read the transcript until the
+ * agent's turn settles. Only `send-message` entries (what the agent delivers
+ * through SendToUser) are the reply; its internal work never appears in the
+ * transcript. Waits are bounded, so a long turn comes back as `running` and
+ * `check` picks it up from the caller's cursor.
+ *
+ * Sends and reads on one hosted agent are chained within this process, and
+ * a send waits for an in-flight turn to settle first, so a reply always
+ * attributes to the message that prompted it.
+ */
+
+import type { ToolContext } from "../../../types.js";
+import extension from "../extension.js";
+import { resolveAgentName } from "./agents.js";
+import {
+  type GrokBotAgentsBackend,
+  type GrokBotTurnStatus,
+  grokBotAgentsBackend,
+} from "./backend.js";
+import { type Contact, findContact, listContacts, saveContact } from "./contacts.js";
+import { KeyedLock } from "./lock.js";
+
+export const DEFAULT_WAIT_SECONDS = 120;
+export const MAX_WAIT_SECONDS = 600;
+
+/**
+ * Idle polls required before a turn counts as settled when the workflow
+ * never reported busy: covers the window between an accepted send and the
+ * workflow picking the signal up, which a `check` right after a short `ask`
+ * can still be inside.
+ */
+const MIN_IDLE_POLLS_WITHOUT_BUSY = 4;
+/**
+ * A session whose row is this young, and whose transcript is still empty,
+ * was created by the call that fetched it; the allowance covers clock skew
+ * between this host and the backend.
+ */
+const CREATED_WINDOW_MS = 60_000;
+/** The transcript tail of an agent nobody has spoken to. */
+const EMPTY_TRANSCRIPT_TAIL = "-1";
+
+export type ReplyStatus = "finished" | "running";
+
+// Type aliases, not interfaces: these are tool results.
+export type AskResult = {
+  agent: string;
+  sessionId: string;
+  status: ReplyStatus;
+  /** What the agent sent back, in order; absent when it sent nothing (yet). */
+  reply?: string;
+  /** Replies to earlier messages that this caller had not read yet. */
+  earlierReplies?: string[];
+  /** The account had no agent of that name; this call created an empty one. */
+  created?: true;
+  note?: string;
+};
+
+export type CheckResult = {
+  agent: string;
+  sessionId: string;
+  status: ReplyStatus;
+  reply?: string;
+  note?: string;
+};
+
+export type InterruptResult = {
+  agent: string;
+  sessionId: string;
+  interrupted: true;
+};
+
+type Replies = {
+  status: ReplyStatus;
+  deliveries: string[];
+  /** Newest `updatedSeq` consumed. */
+  cursor: string;
+};
+
+const agentLocks = new KeyedLock();
+
+export async function ask(
+  ctx: ToolContext,
+  input: { agent?: string; message: string; waitSeconds: number },
+): Promise<AskResult> {
+  const name = resolveAgentName(input.agent, extension.config.agents);
+  const backend = grokBotAgentsBackend();
+  const startedAt = Date.now();
+  const session = await backend.session(name);
+  return agentLocks.run(session.sessionId, async () => {
+    const contact = (await listContacts(ctx)).find(
+      candidate => candidate.sessionId === session.sessionId,
+    );
+    const created =
+      contact === undefined &&
+      session.latestUpdatedSeq === EMPTY_TRANSCRIPT_TAIL &&
+      session.createdAtMs >= startedAt - CREATED_WINDOW_MS;
+    const deadline = Date.now() + input.waitSeconds * 1000;
+    // A turn already in flight, from an earlier message or from the person
+    // in the app, must settle first; otherwise its deliveries would read as
+    // the reply to this message. Nothing is persisted on the way out, so
+    // `check` still returns whatever landed meanwhile.
+    const before = await collectReplies(backend, session.sessionId, {
+      cursor: contact?.cursor ?? session.latestUpdatedSeq,
+      deadline,
+      confirmIdle: false,
+    });
+    if (before.status === "running") {
+      throw new Error(
+        `"${session.name}" is still working on an earlier message; nothing was sent. Call check to read that reply, wait, or interrupt it.`,
+      );
+    }
+    await backend.send(session.sessionId, input.message);
+    const replies = await collectReplies(backend, session.sessionId, {
+      cursor: before.cursor,
+      deadline,
+      confirmIdle: true,
+    });
+    const now = ctx.now().toISOString();
+    await saveContact(ctx, {
+      name: session.name,
+      sessionId: session.sessionId,
+      cursor: replies.cursor,
+      firstContactAt: contact?.firstContactAt ?? now,
+      lastContactAt: now,
+    });
+    const notes = [
+      created
+        ? `No Grok Bot agent named "${session.name}" existed on this account, so an empty one was created. Check the name if that is unexpected.`
+        : undefined,
+      runningNote(session.name, replies.status),
+    ].filter(note => note !== undefined);
+    return {
+      agent: session.name,
+      sessionId: session.sessionId,
+      status: replies.status,
+      reply: joinReplies(replies.deliveries),
+      earlierReplies: before.deliveries.length === 0 ? undefined : before.deliveries,
+      created: created ? true : undefined,
+      note: notes.length === 0 ? undefined : notes.join(" "),
+    };
+  });
+}
+
+export async function check(
+  ctx: ToolContext,
+  input: { agent?: string; waitSeconds: number },
+): Promise<CheckResult> {
+  const contact = await knownContact(ctx, input.agent);
+  const backend = grokBotAgentsBackend();
+  return agentLocks.run(contact.sessionId, async () => {
+    // Re-read under the lock: a parallel call may have moved the cursor.
+    const current =
+      (await listContacts(ctx)).find(candidate => candidate.sessionId === contact.sessionId) ??
+      contact;
+    const replies = await collectReplies(backend, current.sessionId, {
+      cursor: current.cursor,
+      deadline: Date.now() + input.waitSeconds * 1000,
+      confirmIdle: true,
+    });
+    await saveContact(ctx, { ...current, cursor: replies.cursor });
+    return {
+      agent: current.name,
+      sessionId: current.sessionId,
+      status: replies.status,
+      reply: joinReplies(replies.deliveries),
+      note: runningNote(current.name, replies.status),
+    };
+  });
+}
+
+export async function interrupt(
+  ctx: ToolContext,
+  input: { agent?: string },
+): Promise<InterruptResult> {
+  const contact = await knownContact(ctx, input.agent);
+  await grokBotAgentsBackend().interrupt(contact.sessionId, "Interrupted from the Agent SDK.");
+  return {
+    agent: contact.name,
+    sessionId: contact.sessionId,
+    interrupted: true,
+  };
+}
+
+/**
+ * The caller's record of the named agent. Only `ask` resolves a name on the
+ * backend, because that creates an agent when none matches; the other tools
+ * reach agents the caller has already spoken to.
+ */
+async function knownContact(ctx: ToolContext, requested: string | undefined): Promise<Contact> {
+  const name = resolveAgentName(requested, extension.config.agents);
+  const contact = findContact(await listContacts(ctx), name);
+  if (contact === undefined) {
+    throw new Error(`You have not asked "${name}" anything yet; call ask first.`);
+  }
+  return contact;
+}
+
+/**
+ * Read the transcript after `cursor` until the agent's turn settles or the
+ * deadline passes. Only an empty page can settle the turn, so a backlog
+ * drains page by page first. With `confirmIdle`, an idle report may predate
+ * the workflow picking a message up, so settling takes
+ * {@link MIN_IDLE_POLLS_WITHOUT_BUSY} idle polls unless the turn was seen
+ * busy; without it, the first idle report settles.
+ */
+async function collectReplies(
+  backend: GrokBotAgentsBackend,
+  sessionId: string,
+  options: { cursor: string; deadline: number; confirmIdle: boolean },
+): Promise<Replies> {
+  const deliveries: string[] = [];
+  let cursor = options.cursor;
+  let sawBusy = false;
+  let idlePolls = 0;
+  while (true) {
+    const page = await backend.entries(sessionId, cursor);
+    cursor = page.latestUpdatedSeq;
+    for (const entry of page.entries) {
+      if (entry.kind === "send-message" && entry.text !== undefined) {
+        deliveries.push(entry.text);
+      }
+    }
+    const busy = isBusy(page.turn);
+    if (busy) {
+      sawBusy = true;
+    }
+    if (page.entries.length === 0 && !busy && page.turn.idle) {
+      idlePolls += 1;
+      if (sawBusy || !options.confirmIdle || idlePolls >= MIN_IDLE_POLLS_WITHOUT_BUSY) {
+        return { status: "finished", deliveries, cursor };
+      }
+    }
+    if (Date.now() >= options.deadline) {
+      return { status: "running", deliveries, cursor };
+    }
+    await sleep(extension.config.pollIntervalMs);
+  }
+}
+
+function isBusy(turn: GrokBotTurnStatus): boolean {
+  return turn.inFlight || turn.queued > 0;
+}
+
+function joinReplies(deliveries: string[]): string | undefined {
+  return deliveries.length === 0 ? undefined : deliveries.join("\n\n");
+}
+
+function runningNote(name: string, status: ReplyStatus): string | undefined {
+  return status === "running"
+    ? `"${name}" is still replying. Call check with the same agent to keep waiting; a reply so far, if any, is above.`
+    : undefined;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/extensions/cursor-grokbot-agents/lib/inputs.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AGENT_NAME_MAX_LENGTH } from "../extension.js";
+import { DEFAULT_WAIT_SECONDS, MAX_WAIT_SECONDS } from "./conversation.js";
+
+export const agentName: z.ZodOptional<z.ZodString> = z
+  .string()
+  .max(AGENT_NAME_MAX_LENGTH)
+  .optional()
+  .describe(
+    "The Grok Bot agent's name, as shown in the Grok Bot app. With agents configured, one of those; optional when exactly one is configured.",
+  );
+
+export const waitSeconds: z.ZodDefault<z.ZodNumber> = z
+  .number()
+  .int()
+  .min(0)
+  .max(MAX_WAIT_SECONDS)
+  .default(DEFAULT_WAIT_SECONDS)
+  .describe(
+    `How long to wait for the reply before returning status "running" (default ${DEFAULT_WAIT_SECONDS}, max ${MAX_WAIT_SECONDS}). 0 returns after one look.`,
+  );

package/src/extensions/cursor-grokbot-agents/lib/lock.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-key chaining of async work. `host.kv` has no compare-and-swap, and a
+ * model that talks to two agents in one turn calls these tools in parallel,
+ * so read-modify-writes of one principal's records queue up here. The same
+ * chain keeps one hosted agent's sends and reads from interleaving within
+ * this process, so a reply attributes to the message that prompted it.
+ */
+export class KeyedLock {
+  private readonly chains = new Map<string, Promise<void>>();
+
+  run<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const previous = this.chains.get(key) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    const settled = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.chains.set(key, settled);
+    void settled.then(() => {
+      if (this.chains.get(key) === settled) {
+        this.chains.delete(key);
+      }
+    });
+    return run;
+  }
+}

package/src/extensions/cursor-grokbot-agents/skills/consult.md

@@ -0,0 +1,40 @@
+---
+description: "Talk to your Grok Bot agents: when to bring one in, how to write a message it can act on alone, and how to wait for, read, and interrupt its reply."
+---
+
+# Consulting a Grok Bot agent
+
+Bring a Grok Bot agent in when the person set one up for the job: a specialist with its own instructions, memory, and tools, such as one that decides whether an outdoor plan survives a forecast or one that keeps a household's calendar. Answer questions you can answer yourself.
+
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__ask` and so on. Every agent is addressed by its `agent` name, as it appears in the Grok Bot app. When exactly one agent is configured, `agent` can be omitted.
+
+## Write for a stranger
+
+Your message lands in the person's own conversation with that agent, the same one they see in the app. The agent does not see this conversation, your tools, or your earlier results. Say who is asking and why, paste the facts it needs rather than referring to them, and say what you want back and in what shape. One complete message beats a back-and-forth.
+
+## Ask
+
+Call `ask` with the `agent` and the `message`. It sends the message and waits up to `wait_seconds` for the agent's turn to finish. The result carries `status`, the `reply` (everything the agent sent back during that turn, in order), and `sessionId`.
+
+- `status: "finished"`: the turn is over; `reply` is the whole answer. No `reply` means the agent finished without sending anything.
+- `status: "running"`: the agent is still working. Call `check` with the same `agent` to keep waiting; whatever it had sent so far is already in `reply`.
+
+If `earlierReplies` is present, the agent had answered earlier messages that nobody read yet; pass them on when they matter, and do not mistake them for the reply to this message.
+
+If `created` is true, no agent of that name existed on the account and an empty one was created. Tell the person and check the spelling before asking it anything else.
+
+If `ask` fails because an agent of that name already exists in the Grok Bot app, nothing was created and nothing was sent. Tell the person. Do not invent a different name to get around it.
+
+If `ask` refuses because the agent is still working on an earlier message, nothing was sent. If you have already asked that agent, call `check` to read the reply, then ask again; use `interrupt` when the earlier work should stop. On first contact, `check` and `interrupt` cannot address the agent yet, so tell the person it is busy, wait for the existing turn to finish in the Grok Bot app, and retry `ask`.
+
+## Wait for a long reply
+
+Call `check` with the `agent`. It returns what the agent has sent since you last read, and `status: "running"` while the turn is still going. Pass `wait_seconds: 0` for a single look. Check when you need the answer, not in a tight loop; a long task can take minutes.
+
+## Interrupt
+
+Call `interrupt` with the `agent` to stop its current turn. The agent keeps its conversation, so a later `ask` continues from there.
+
+## Which agents
+
+`list` returns the agents configured for you, with what each is for, and the ones you have already asked. Names outside the configured set are refused; with no set configured, any name works, and an unknown name creates an agent.

package/src/extensions/cursor-grokbot-agents/tools/ask.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { ask as askAgent } from "../lib/conversation.js";
+import { agentName, waitSeconds } from "../lib/inputs.js";
+
+const ask: ToolDefinition = defineTool({
+  description:
+    'Send a message to one of your Grok Bot agents and wait for its reply. The message lands in your own conversation with that agent, which does not see this one, so include everything it needs. Long turns return status "running": call check to keep waiting.',
+  effect: "write",
+  needsApproval: () => extension.config.needsApproval,
+  inputSchema: z.object({
+    agent: agentName,
+    message: z
+      .string()
+      .min(1)
+      .describe(
+        "What to tell or ask the agent. Self-contained: who is asking, the facts it needs, and what you want back.",
+      ),
+    wait_seconds: waitSeconds,
+  }),
+  async execute(input, ctx) {
+    return askAgent(ctx, {
+      agent: input.agent,
+      message: input.message,
+      waitSeconds: input.wait_seconds,
+    });
+  },
+});
+
+export default ask;

package/src/extensions/cursor-grokbot-agents/tools/check.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { check as checkAgent } from "../lib/conversation.js";
+import { agentName, waitSeconds } from "../lib/inputs.js";
+
+const check: ToolDefinition = defineTool({
+  description:
+    'Wait for, or poll, the reply of a Grok Bot agent you asked: everything it has sent since you last read, and whether it is still working. Returns status "running" to keep waiting; pass wait_seconds 0 for a single look.',
+  // Reading advances the caller's cursor, which their other sessions read
+  // back, so a dry run answers this instead of running it.
+  effect: "write",
+  inputSchema: z.object({
+    agent: agentName,
+    wait_seconds: waitSeconds,
+  }),
+  async execute(input, ctx) {
+    return checkAgent(ctx, {
+      agent: input.agent,
+      waitSeconds: input.wait_seconds,
+    });
+  },
+});
+
+export default check;

package/src/extensions/cursor-grokbot-agents/tools/interrupt.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { interrupt as interruptAgent } from "../lib/conversation.js";
+import { agentName } from "../lib/inputs.js";
+
+const interrupt: ToolDefinition = defineTool({
+  description:
+    "Stop what a Grok Bot agent you asked is doing right now. It keeps its conversation; ask it again to continue.",
+  effect: "write",
+  inputSchema: z.object({ agent: agentName }),
+  async execute(input, ctx) {
+    return interruptAgent(ctx, { agent: input.agent });
+  },
+});
+
+export default interrupt;

package/src/extensions/cursor-grokbot-agents/tools/list.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { listContacts } from "../lib/contacts.js";
+
+const list: ToolDefinition = defineTool({
+  description:
+    "List the Grok Bot agents you can talk to: the ones configured for this agent, with what each is for, and the ones you have already asked, most recent first.",
+  effect: "read",
+  inputSchema: z.object({}),
+  async execute(_input, ctx) {
+    const contacts = await listContacts(ctx);
+    return {
+      configured: extension.config.agents ?? [],
+      contacted: contacts.map(contact => ({
+        name: contact.name,
+        sessionId: contact.sessionId,
+        firstContactAt: contact.firstContactAt,
+        lastContactAt: contact.lastContactAt,
+      })),
+    };
+  },
+});
+
+export default list;

package/src/internal/cli-ax.ts

@@ -17,7 +17,11 @@ import { lookupSessionContinuation, runChat } from "./chat-client.js";
 import { ensureCursorLogin } from "./cli-cursor.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { resolveApiKey } from "./cursor/credentials.js";
-import { type AgentkitSessionRuns, DeployApiError } from "./deploy-client.js";
+import {
+  type AgentkitSessionEventPoll,
+  type AgentkitSessionRuns,
+  DeployApiError,
+} from "./deploy-client.js";
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
 import {
   discoverEvals,
@@ -48,7 +52,7 @@ import {
   resolveTemplate,
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
-import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
+import { rejectV2ForLegacyCommand, v2HostedVerifyHint } from "./legacy-command-guard.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
 import { mapPool } from "./map-pool.js";
 import { openBrowser } from "./open-browser.js";
@@ -750,6 +754,9 @@ async function cmdHostedSession(options: AxCliOptions): Promise<number | "fallba
       componentKey: trimNonEmpty(options.componentKey),
     });
     console.log(JSON.stringify(accepted, null, 2));
+    if (accepted.sessionId === undefined) {
+      process.stderr.write(`${v2HostedVerifyHint(slug)}\n`);
+    }
     return 0;
   } catch (error) {
     if (error instanceof DeployApiError && error.status === 404) {
@@ -811,7 +818,15 @@ export async function cmdCall(options: AxCliOptions): Promise<number> {
     }
   }
 
-  const target = await resolveTarget(options);
+  let target: ResolvedAgentTarget;
+  try {
+    target = await resolveTarget(options);
+  } catch (error) {
+    process.stderr.write(
+      `${sanitizeCustomerError(error instanceof Error ? error.message : String(error))}\n`,
+    );
+    return 1;
+  }
   try {
     const body: { input: unknown; sessionId?: string } = { input };
     if (options.sessionId !== undefined) {
@@ -1906,7 +1921,13 @@ export async function cmdSessions(options: AxCliOptions): Promise<number> {
   }
 }
 
-function formatHostedSessionRuns(sessionId: string, runs: AgentkitSessionRuns): string {
+export const HOSTED_RUNS_LAG_NOTE = "Turn running; runs may lag behind events.";
+
+function formatHostedSessionRuns(
+  sessionId: string,
+  runs: AgentkitSessionRuns,
+  events?: AgentkitSessionEventPoll,
+): string {
   const lines = [`Session ${sessionId}`, `Hosted executions: ${runs.executions.length}`];
   for (const run of runs.executions) {
     const failure = run.error?.message ?? run.message ?? "";
@@ -1916,6 +1937,17 @@ function formatHostedSessionRuns(sessionId: string, runs: AgentkitSessionRuns):
       ...run.logs.map(log => `  ${log.line}`),
     );
   }
+  const latestType = events?.events.at(-1)?.type;
+  if (events !== undefined && events.events.length > 0) {
+    const latest = latestType === undefined ? "" : ` (latest ${latestType})`;
+    lines.push("", `Events: ${events.events.length}${latest}`);
+  }
+  const turnRunning =
+    runs.executions.at(-1)?.turnStatus === "running" ||
+    (runs.executions.length === 0 && events?.execution?.turnStatus === "running");
+  if (turnRunning && (events?.events.length ?? 0) > 0) {
+    lines.push(HOSTED_RUNS_LAG_NOTE);
+  }
   return `${lines.join("\n")}\n`;
 }
 
@@ -1933,19 +1965,32 @@ async function readHostedSessionRuns(
     return auth;
   }
   try {
+    const slug = resolveProdSlug(options);
     const runs = await auth.client.getAgentkitSessionRuns({
       teamId: auth.teamId,
-      slug: resolveProdSlug(options),
+      slug,
       sessionId,
     });
     if (options.rawEvents === true || trimNonEmpty(options.out) !== undefined) {
       process.stderr.write("--events and --out need an engine trajectory.\n");
       return 2;
     }
+    const latest = runs.executions.at(-1);
+    const events =
+      runs.executions.length === 0 || latest?.turnStatus === "running"
+        ? await auth.client
+            .getAgentkitSessionEvents({
+              teamId: auth.teamId,
+              slug,
+              sessionId,
+              afterEventIndex: -1,
+            })
+            .catch(() => undefined)
+        : undefined;
     process.stdout.write(
       options.json === true
         ? `${JSON.stringify({ sessionId, ...runs }, null, 2)}\n`
-        : formatHostedSessionRuns(sessionId, runs),
+        : formatHostedSessionRuns(sessionId, runs, events),
     );
     return 0;
   } catch (error) {
@@ -1988,7 +2033,7 @@ export async function cmdSession(
   }
   if (sessionId === undefined || sessionId.trim() === "") {
     process.stderr.write(
-      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events] [--out <file.ndjson>]\n` +
+      `Usage: ${CLI_COMMAND_NAME} session <ses_> [--url | --prod] [--slug <slug>] [--json | --text | --events] [--out <file.ndjson>]\n` +
         `   or: ${CLI_COMMAND_NAME} session --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]\n`,
     );
     return 2;

package/src/internal/cli-deploy.ts

@@ -1,5 +1,5 @@
 /**
- * `agent-sdk deploy | deployments | deployment | stop | delete | rotate-token |
+ * `agent-sdk deploy | deployments | deployment | stop | rollback | delete | rotate-token |
  * secrets set|list|unset` — Heroku-style deploys
  * onto Cursor's managed agent-serve hosting.
  *
@@ -1787,12 +1787,45 @@ const RELEASE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]
 export async function cmdUpgrade(
   args: { slug: string | undefined; release: string | undefined },
   options: DeployCliOptions,
+): Promise<number> {
+  return cmdPinRelease(args, options, {
+    usage: `Usage: ${CLI} upgrade <slug> [--release <id|version>] [--team <id>] [--json]\n`,
+    pin: (client, request) => client.upgradeAgentkitInstall(request),
+    success: (slug, releaseId) => `${slug} now runs release ${releaseId}.\n`,
+  });
+}
+
+export async function cmdRollback(
+  args: { slug: string | undefined; release: string | undefined },
+  options: DeployCliOptions,
+): Promise<number> {
+  return cmdPinRelease(args, options, {
+    usage: `Usage: ${CLI} rollback <slug> [--release <id|version>] [--team <id>] [--json]\n`,
+    pin: (client, request) => client.rollbackAgentkitInstall(request),
+    success: (slug, releaseId) => `${slug} rolled back to release ${releaseId}.\n`,
+  });
+}
+
+async function cmdPinRelease(
+  args: { slug: string | undefined; release: string | undefined },
+  options: DeployCliOptions,
+  pin: {
+    usage: string;
+    pin: (
+      client: AgentServeDeployClient,
+      request: {
+        teamId: number;
+        slug: string;
+        releaseId?: string;
+        version?: string;
+      },
+    ) => Promise<string>;
+    success: (slug: string, releaseId: string) => string;
+  },
 ): Promise<number> {
   const { slug, release } = args;
   if (slug === undefined || slug === "") {
-    (options.err ?? ((text: string) => void process.stderr.write(text)))(
-      `Usage: ${CLI} upgrade <slug> [--release <id|version>] [--team <id>] [--json]\n`,
-    );
+    (options.err ?? ((text: string) => void process.stderr.write(text)))(pin.usage);
     return 1;
   }
   const ctx = await prepare(options);
@@ -1802,7 +1835,7 @@ export async function cmdUpgrade(
   const selector = release?.trim() ?? "";
   let releaseId: string;
   try {
-    releaseId = await ctx.client.upgradeAgentkitInstall({
+    releaseId = await pin.pin(ctx.client, {
       teamId: ctx.teamId,
       slug,
       ...(selector === ""
@@ -1817,7 +1850,7 @@ export async function cmdUpgrade(
   if (ctx.json) {
     ctx.out(`${JSON.stringify({ releaseId }, null, 2)}\n`);
   } else {
-    ctx.out(`${slug} now runs release ${releaseId}.\n`);
+    ctx.out(pin.success(slug, releaseId));
   }
   return 0;
 }

package/src/internal/cli-mcp-oauth.ts

@@ -15,6 +15,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
 import { isCursorAccountTransport } from "../types.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
+import { resolveConnectionEnvTemplates } from "./connection-env.js";
 import { CursorBackendClient } from "./cursor/backend-client.js";
 import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { deploymentServiceAccountId } from "./deploy-client.js";
@@ -76,7 +77,7 @@ export async function cmdMcpOauth(options: McpOauthCliOptions): Promise<number>
     return 1;
   }
 
-  const transport = connection.transport;
+  const transport = resolveConnectionEnvTemplates(connection.transport);
   if (isCursorAccountTransport(transport)) {
     return cmdMcpOauthCursorAccount(options, {
       servers: transport.servers,