@cursor/bdk 0.2.2 → 0.2.3

package/src/bin/agent-serve.ts

@@ -48,6 +48,7 @@ import {
   cmdDeployments,
   cmdEventRepos,
   cmdKill,
+  cmdRollback,
   cmdRotateToken,
   cmdSecretsList,
   cmdSecretsSet,
@@ -66,6 +67,7 @@ import {
   PACKAGE_NAME,
   packageVersion,
 } from "../internal/distribution.js";
+import { v2HostedVerifyHint } from "../internal/legacy-command-guard.js";
 import { loadAgentLocalEnv } from "../internal/local-env.js";
 import {
   ENTER_RESTART_EXIT_CODE,
@@ -97,6 +99,7 @@ Usage:
                           [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} sessions    [--url <baseUrl> | --prod] [--json]
                           [--slug <slug>] [--team <id>] [--dir <path>]
+                          v2: unsupported. ${v2HostedVerifyHint()}
   ${CLI} session     <sessionId> [--url <baseUrl> | --prod]
                           [--json | --text | --events] [--out <file.ndjson>]
                           [--slug <slug>] [--team <id>] [--dir <path>]
@@ -114,6 +117,7 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
+                          v2: unsupported. ${v2HostedVerifyHint()}
   ${CLI} skill       <name> [--dir <path> | --url <baseUrl> | --prod]
                           [--slug <slug>] [--team <id>] [--text]
   ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
@@ -157,6 +161,7 @@ Usage:
   ${CLI} cancel-runs <slug> [--team <id>] [--json]
   ${CLI} event-repos <slug> [--repo <owner/name>]... [--team <id>] [--json]
   ${CLI} upgrade     <slug> [--release <id|version>] [--team <id>] [--json]
+  ${CLI} rollback    <slug> [--release <id|version>] [--team <id>] [--json]
   ${CLI} delete      <slug> [--team <id>] [--json] [--no-wait]
   ${CLI} rotate-token <slug> [--team <id>]
   ${CLI} secrets     set <slug> NAME... | list <slug> | unset <slug> NAME
@@ -189,8 +194,10 @@ Commands:
               the current buffer. --prod shows deploy progress until the
               hosted deployment is running, then tails runtime logs. Without
               --prod, tails the local server (or --url).
-  sessions    List sessions on a running agent (or --prod hosted deployment).
-  session     Show one session. Default: text trajectory. --json for trajectory
+  sessions    List sessions on a running agent or a v1 --prod deployment.
+              Unsupported on architecture v2. ${v2HostedVerifyHint()}
+  session     Show one session. On v2: \`${CLI} session <ses_> --prod --slug <slug>\`.
+              Default: text trajectory. --json for trajectory
               JSON; --events for the raw event list. To continue interactively,
               use \`${CLI} resume [id]\`.
   cost        Pull cost metrics. With a session id: per-turn token usage and
@@ -208,13 +215,14 @@ Commands:
               Streams tool calls and reply text to stderr when stderr is a TTY.
               Pass --prod to hit the hosted deployment instead of a local server.
               On an AgentSDK v2 slug, --prod starts a hosted session through
-              the control plane (Temporal, no resident engine); --session
-              ses_… resumes that exact session. A 404 falls back to the v1
+              the control plane (Temporal, no resident engine). ${v2HostedVerifyHint()}
+              --session ses_… resumes that exact session. A 404 falls back to the v1
               engine alias.
   trajectory  Summarize an events.ndjson file into a trajectory.
   call        Call an authored server tool deterministically (no model turn)
               via POST /v1/tools/:toolName. --session runs it inside an
               existing session and records it on that session's event stream.
+              Unsupported on architecture v2. ${v2HostedVerifyHint()}
   skill       Read an authored skill deterministically (no model turn)
               via GET /v1/skills/:skillName. --text prints SKILL.md.
   init        Scaffold a project (skipping existing files), npm install,
@@ -234,8 +242,8 @@ Commands:
               -> MCP). Review the project, then run \`validate\` / \`dev\`.
               Warnings never fail the command.
   install-skills
-              Refresh the Agent SDK skills for coding agents in
-              ~/.cursor/skills/agentsdk and print where they landed.
+              Refresh the BDK skills for coding agents in
+              ~/.cursor/skills/bdk and print where they landed.
               Installed copies set alwaysApply so Cursor injects them
               into context. \`npm install\` / \`npx\` already copies them
               (postinstall); this command overwrites with the package
@@ -306,6 +314,9 @@ Commands:
   upgrade     Move this team's install onto a release, the newest ready one
               by default. Deploying a multi-tenant application publishes a
               release without moving any tenant onto it.
+  rollback    Move this team's install onto an earlier ready release, the
+              nearest one by default. Does not publish a release. Pass
+              --release to choose an older id or version.
   delete      Delete a deployment (teardown + purge the record) and wait
               until GET 404s. The slug is then free to redeploy.
   rotate-token Mint a new alias token for a deployment (shown once); the old
@@ -392,7 +403,10 @@ Options:
                      --dir basename. Mutually exclusive with --url. Requires
                      \`${CLI} login\`. For eval, this is how you opt into the
                      persisted server-side batch (default is local).
+                     v2: ${v2HostedVerifyHint()} call --prod and
+                     sessions --prod stay on v1.
   --dry-run          run/session --prod: mark the hosted v2 turn non-mutating.
+                     ${v2HostedVerifyHint()}
   --component        run/session --prod: wake this v2 component key,
                      not the application default.
   --as-of            run/session --prod: freeze the session clock at this
@@ -893,6 +907,13 @@ async function main(argv: string[]): Promise<number> {
       );
     }
 
+    case "rollback": {
+      return cmdRollback(
+        { slug: positionals[0], release: values.release },
+        deployOptionsFromValues(values),
+      );
+    }
+
     case "delete": {
       return cmdDelete(positionals[0], deployOptionsFromValues(values));
     }

package/src/channels/github/auth.ts

@@ -215,11 +215,50 @@ export async function createGitHubInstallationToken(input: {
     privateKey,
     ...(input.api?.apiBaseUrl === undefined ? {} : { baseUrl: input.api.apiBaseUrl }),
   });
-  const result = await auth({
-    type: "installation",
-    installationId: input.installationId,
-  });
-  return result.token;
+  try {
+    const result = await auth({
+      type: "installation",
+      installationId: input.installationId,
+    });
+    return result.token;
+  } catch (error) {
+    throw installationTokenMintError(error, {
+      appId,
+      installationId: input.installationId,
+    });
+  }
+}
+
+/**
+ * Octokit's bare mint failure ("Not Found - <docs url>") names neither the
+ * app nor the installation, which makes a revoked installation or an
+ * app/installation credential mismatch undiagnosable from production logs.
+ * Rewrap with both ids and, for 404, the two causes that produce it.
+ */
+function installationTokenMintError(
+  error: unknown,
+  context: { appId: string; installationId: number },
+): Error {
+  const status =
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    typeof (error as { status: unknown }).status === "number"
+      ? (error as { status: number }).status
+      : undefined;
+  const detail = error instanceof Error ? error.message : String(error);
+  const hint =
+    status === 404
+      ? " — the installation does not exist for this app: it was uninstalled or suspended, or the configured app credentials belong to a different GitHub App than the one this installation id refers to"
+      : "";
+  const wrapped = new Error(
+    `githubChannel: failed to mint an installation access token (app ${context.appId}, installation ${context.installationId}): ${detail}${hint}`,
+    error instanceof Error ? { cause: error } : undefined,
+  );
+  if (status !== undefined) {
+    (wrapped as Error & { status?: number }).status = status;
+  }
+  return wrapped;
 }
 
 /**

package/src/connections.ts

@@ -18,7 +18,7 @@
  *
  * export default defineConnection({
  *   url: "https://mcp.linear.app/mcp",
- *   headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+ *   headers: { authorization: "Bearer ${LINEAR_TOKEN}" },
  * });
  *
  * // TypeScript tools, packaged as stdio MCP for the agent environment:

package/src/extensions/cursor-grokbot-agents/extension.ts

@@ -0,0 +1,132 @@
+/**
+ * Your Grok Bot agents as an extension. Mount it and the agent can talk to
+ * the Grok Bot agents of the host's account: send a message, read the
+ * reply, keep waiting on a long turn, interrupt one.
+ *
+ * ```ts
+ * // agent/extensions/grokbot.ts
+ * import cursorGrokBotAgents from "@cursor/bdk/extensions/cursor-grokbot-agents";
+ *
+ * export default cursorGrokBotAgents({
+ *   agents: [
+ *     { name: "Plan Keeper", description: "Keeps or moves outdoor plans." },
+ *   ],
+ * });
+ * ```
+ *
+ * Contributes `grokbot__ask`, `grokbot__check`, `grokbot__interrupt`,
+ * `grokbot__list` and the `grokbot__consult` skill (the namespace is the
+ * mount filename), over the same public `/v0/grokbot` session API the
+ * grokbot runtime uses, under the serve host's Cursor API key
+ * (`CURSOR_API_KEY`, key file, or `login`). Agents are addressed by name and
+ * resolved on the account the key belongs to; a message lands in that
+ * account's own conversation with the agent, and the reply is what the agent
+ * sends back during that turn. The tools run on the serve host, so they
+ * need the local runtime.
+ *
+ * This is the other direction from `defineAgent({ runtime: "grokbot" })`:
+ * the runtime runs *this* agent's turns on the hosted Grok Bot harness; the
+ * extension keeps the agent where it is and lets it talk to *other* Grok
+ * Bot agents.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+
+/**
+ * A Grok Bot agent the model may address, by the name shown in the app.
+ * Type alias, not an interface: `list` returns these.
+ */
+export type ConfiguredGrokBotAgent = {
+  name: string;
+  /** What the agent is for; shown to the model by `list`. */
+  description?: string;
+};
+
+/** Mount options; every field is optional. */
+export interface CursorGrokBotAgentsOptions {
+  /**
+   * The Grok Bot agents the model may talk to, by name. This is the
+   * allowlist for a call's own `agent`: names outside it are refused, and a
+   * lone configured agent is the default when a call names none. Without
+   * it, any name goes through and `needsApproval` defaults to true, since
+   * an unknown name creates an agent of that name on the account.
+   */
+  agents?: Array<string | ConfiguredGrokBotAgent>;
+  /**
+   * Park messages for a human approval. Defaults to `true` when no `agents`
+   * are configured; `false` once they are. Pass an explicit boolean to
+   * override. Configured names still bound the model's choice regardless.
+   */
+  needsApproval?: boolean;
+  /** Cursor API key. Defaults to the serve host's own key. */
+  apiKey?: string;
+  /**
+   * How often to read the agent's transcript while waiting for a reply, in
+   * milliseconds. Defaults to 750.
+   */
+  pollIntervalMs?: number;
+}
+
+/** {@link CursorGrokBotAgentsOptions} with defaults applied. */
+export interface CursorGrokBotAgentsConfig {
+  agents?: ConfiguredGrokBotAgent[];
+  needsApproval: boolean;
+  apiKey?: string;
+  pollIntervalMs: number;
+}
+
+/** The backend's session name limit. */
+export const AGENT_NAME_MAX_LENGTH = 255;
+const DEFAULT_POLL_INTERVAL_MS = 750;
+
+const agentName = z
+  .string()
+  .trim()
+  .min(1, "Grok Bot agent names must not be empty.")
+  .max(AGENT_NAME_MAX_LENGTH);
+
+const configuredAgent: z.ZodType<
+  ConfiguredGrokBotAgent,
+  z.ZodTypeDef,
+  string | ConfiguredGrokBotAgent
+> = z
+  .union([agentName, z.object({ name: agentName, description: z.string().optional() })])
+  .transform(agent => (typeof agent === "string" ? { name: agent } : agent));
+
+const agents = z
+  .array(configuredAgent)
+  .min(1, "agents must name at least one Grok Bot agent; omit it to allow any.")
+  .refine(
+    list => new Set(list.map(agent => agent.name.toLowerCase())).size === list.length,
+    "agents must not repeat a name (names match case-insensitively).",
+  );
+
+const config: z.ZodType<
+  CursorGrokBotAgentsConfig,
+  z.ZodTypeDef,
+  CursorGrokBotAgentsOptions | undefined
+> = z
+  .object({
+    agents: agents.optional(),
+    needsApproval: z.boolean().optional(),
+    apiKey: z.string().optional(),
+    pollIntervalMs: z.number().int().min(1).default(DEFAULT_POLL_INTERVAL_MS),
+  })
+  .default({})
+  .transform(options => ({
+    ...options,
+    needsApproval: options.needsApproval ?? options.agents === undefined,
+  }));
+
+const cursorGrokBotAgents: Extension<
+  CursorGrokBotAgentsConfig,
+  CursorGrokBotAgentsOptions | undefined
+> = defineExtension({
+  root: import.meta.dirname,
+  description: "Talk to your Grok Bot agents and read their replies.",
+  config,
+});
+
+export default cursorGrokBotAgents;

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

@@ -0,0 +1,42 @@
+/**
+ * Which Grok Bot agent a call addresses. The model names one per call, but
+ * the author's `agents` are the allowlist: with them configured, a name
+ * outside the list is refused (the backend would create an agent of that
+ * name), and a lone configured agent stands in when the call names none.
+ * Matching is case-insensitive and resolves to the configured spelling,
+ * since the backend looks names up exactly.
+ */
+
+import type { ConfiguredGrokBotAgent } from "../extension.js";
+
+export function resolveAgentName(
+  requested: string | undefined,
+  configured: ConfiguredGrokBotAgent[] | undefined,
+): string {
+  const name = requested?.trim();
+  if (configured === undefined) {
+    if (name === undefined || name === "") {
+      throw new Error("`agent` is required: this extension has no configured Grok Bot agents.");
+    }
+    return name;
+  }
+  const names = configured.map(agent => `"${agent.name}"`).join(", ");
+  if (name === undefined || name === "") {
+    const only = configured.length === 1 ? configured[0] : undefined;
+    if (only === undefined) {
+      throw new Error(
+        `\`agent\` is required: this extension configures several Grok Bot agents (${names}).`,
+      );
+    }
+    return only.name;
+  }
+  const match =
+    configured.find(agent => agent.name === name) ??
+    configured.find(agent => agent.name.toLowerCase() === name.toLowerCase());
+  if (match === undefined) {
+    throw new Error(
+      `"${name}" is not one of this extension's configured Grok Bot agents (${names}).`,
+    );
+  }
+  return match.name;
+}

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

@@ -0,0 +1,208 @@
+/**
+ * The `/v0/grokbot` session API as the tools use it: the same four routes
+ * the grokbot runtime drives, on the external API host (`api.cursor.com`;
+ * they 404 on api2), under the host's Cursor API key. A session is a hosted
+ * Grok Bot agent of the key's account, get-or-created by name; messages go
+ * into its one conversation, and the transcript is read back as entries
+ * after a cursor, with the turn's status alongside.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+  SIGN_IN_HINT,
+} from "../../../internal/cursor/credentials.js";
+import extension from "../extension.js";
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+export class GrokBotApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "GrokBotApiError";
+  }
+}
+
+// Type aliases, not interfaces: these flow into tool results.
+export type GrokBotSession = {
+  /** The hosted agent's durable id; every other route addresses it. */
+  sessionId: string;
+  /** The name as the backend stores it (trimmed). */
+  name: string;
+  createdAtMs: number;
+  /** Transcript tail: reading after it skips the conversation's history. */
+  latestUpdatedSeq: string;
+};
+
+export type GrokBotEntry = {
+  seq: string;
+  updatedSeq: string;
+  kind: string;
+  role?: string;
+  text?: string;
+  createdAtMs: number;
+};
+
+export type GrokBotTurnStatus = {
+  idle: boolean;
+  inFlight: boolean;
+  queued: number;
+};
+
+export type GrokBotEntriesPage = {
+  entries: GrokBotEntry[];
+  latestUpdatedSeq: string;
+  turn: GrokBotTurnStatus;
+};
+
+const sessionSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAtMs: z.number(),
+  latestUpdatedSeq: z.string(),
+});
+
+const sendSchema = z.object({
+  messageId: z.string(),
+  delivery: z.string(),
+});
+
+const entriesSchema: z.ZodType<GrokBotEntriesPage> = z.object({
+  entries: z.array(
+    z.object({
+      seq: z.string(),
+      updatedSeq: z.string(),
+      kind: z.string(),
+      role: z.string().optional(),
+      text: z.string().optional(),
+      createdAtMs: z.number(),
+    }),
+  ),
+  latestUpdatedSeq: z.string(),
+  turn: z.object({
+    idle: z.boolean(),
+    inFlight: z.boolean(),
+    queued: z.number(),
+  }),
+});
+
+export class GrokBotAgentsBackend {
+  constructor(
+    private readonly apiKey: () => string,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  /** `POST /v0/grokbot/sessions`: the account's agent of that name, created when missing. */
+  async session(name: string): Promise<GrokBotSession> {
+    // No `instructions`: the agent is somebody's, configured in the app, and
+    // an omitted field never touches its stored profile.
+    const parsed = sessionSchema.parse(
+      await this.request("POST", "/v0/grokbot/sessions", { name }),
+    );
+    return {
+      sessionId: parsed.id,
+      name: parsed.name,
+      createdAtMs: parsed.createdAtMs,
+      latestUpdatedSeq: parsed.latestUpdatedSeq,
+    };
+  }
+
+  /** Deliver one user message to the agent's conversation. */
+  async send(sessionId: string, text: string): Promise<void> {
+    const { delivery } = sendSchema.parse(
+      await this.request("POST", `/v0/grokbot/sessions/${sessionId}/messages`, {
+        text,
+        messageId: randomUUID(),
+      }),
+    );
+    if (delivery !== "accepted_temporal" && delivery !== "duplicate") {
+      throw new GrokBotApiError(
+        `The Grok Bot agent's harness did not accept the message (delivery: ${delivery}).`,
+      );
+    }
+  }
+
+  /** Transcript entries after `afterUpdatedSeq`, oldest first, with the turn's status. */
+  async entries(sessionId: string, afterUpdatedSeq: string): Promise<GrokBotEntriesPage> {
+    return entriesSchema.parse(
+      await this.request(
+        "GET",
+        `/v0/grokbot/sessions/${sessionId}/entries?afterUpdatedSeq=${encodeURIComponent(afterUpdatedSeq)}`,
+      ),
+    );
+  }
+
+  async interrupt(sessionId: string, reason: string): Promise<void> {
+    await this.request("POST", `/v0/grokbot/sessions/${sessionId}/interrupt`, {
+      reason,
+    });
+  }
+
+  private async request(method: "GET" | "POST", path: string, body?: unknown): Promise<unknown> {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${this.apiKey()}`,
+      "x-cursor-client-type": "agent-serve",
+      "x-request-id": randomUUID(),
+    };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${cursorExternalApiUrl()}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (error) {
+      throw new GrokBotApiError(
+        `Grok Bot API ${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new GrokBotApiError(
+        `Grok Bot API ${method} ${path} failed (${response.status}): ${apiErrorMessage(text)}`,
+        response.status,
+      );
+    }
+    return JSON.parse(text) as unknown;
+  }
+}
+
+let backend: GrokBotAgentsBackend | undefined;
+
+/** The process-wide backend for this mount, built on first use. */
+export function grokBotAgentsBackend(): GrokBotAgentsBackend {
+  backend ??= new GrokBotAgentsBackend(apiKey);
+  return backend;
+}
+
+export function apiKey(): string {
+  // Read per call: the host can sign in after the mount.
+  const key = resolveApiKeySync({ apiKey: extension.config.apiKey });
+  if (key === undefined) {
+    throw new Error(`Grok Bot agents need a Cursor API key. ${SIGN_IN_HINT}`);
+  }
+  return key.apiKey;
+}
+
+/** The route's `{ error }` envelope when it is one, the raw body otherwise. */
+function apiErrorMessage(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown; message?: unknown };
+    const message = parsed.error ?? parsed.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+  } catch {
+    // Not JSON; fall through to the raw body.
+  }
+  return text.slice(0, 300);
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Who has talked to which Grok Bot agent, and how far into its transcript
+ * they have read. The tools authenticate with the serve host's one Cursor
+ * API key, so every agent is that account's; what the host keeps per
+ * principal is the read cursor, so `check` returns what the agent said
+ * since that caller last read, and a lookup by name for `check` and
+ * `interrupt`, which never create an agent the caller has not spoken to.
+ */
+
+import { z } from "zod";
+import type { ToolContext } from "../../../types.js";
+import { KeyedLock } from "./lock.js";
+
+const PREFIX = "grokbot-agents";
+
+// Type alias, not an interface: contacts flow into tool results.
+export type Contact = {
+  /** The agent's name as the backend stores it. */
+  name: string;
+  /** The hosted agent's `/v0/grokbot` session id. */
+  sessionId: string;
+  /** Newest transcript `updatedSeq` this principal has read. */
+  cursor: string;
+  firstContactAt: string;
+  lastContactAt: string;
+};
+
+const contactsSchema: z.ZodType<Contact[]> = z.array(
+  z.object({
+    name: z.string(),
+    sessionId: z.string(),
+    cursor: z.string(),
+    firstContactAt: z.string(),
+    lastContactAt: z.string(),
+  }),
+);
+
+const locks = new KeyedLock();
+
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export function principalOf(ctx: ToolContext): string {
+  const auth = ctx.session.auth;
+  return auth === null ? "anonymous" : `${auth.principalType}:${auth.principalId}`;
+}
+
+/** The caller's contacts, most recently spoken to first. */
+export async function listContacts(ctx: ToolContext): Promise<Contact[]> {
+  const contacts = contactsSchema.safeParse(await ctx.host.kv.get(contactsKey(principalOf(ctx))));
+  return contacts.success ? contacts.data : [];
+}
+
+/** The contact of that name, exact spelling first, then case-insensitively. */
+export function findContact(contacts: Contact[], name: string): Contact | undefined {
+  const wanted = name.trim();
+  return (
+    contacts.find(contact => contact.name === wanted) ??
+    contacts.find(contact => contact.name.toLowerCase() === wanted.toLowerCase())
+  );
+}
+
+/** Insert or replace the caller's record of one agent, newest first. */
+export async function saveContact(ctx: ToolContext, contact: Contact): Promise<void> {
+  const key = contactsKey(principalOf(ctx));
+  await locks.run(key, async () => {
+    const others = (await listContacts(ctx)).filter(
+      existing => existing.sessionId !== contact.sessionId,
+    );
+    await ctx.host.kv.put(key, [contact, ...others]);
+  });
+}
+
+function contactsKey(principal: string): string {
+  return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
+}