@cursor/bdk 0.2.2 → 0.2.3

package/src/internal/cli-skills.ts

@@ -1,6 +1,6 @@
 /**
  * `install-skills` — install the package's coding-agent skills into
- * `~/.cursor/skills/agentsdk/` without running `init`.
+ * `~/.cursor/skills/bdk/` without running `init`.
  *
  * Never prompts: running the command is the confirmation. The interactive
  * offer lives in `init`. Consumer `npm install` / `npx` copies the same
@@ -12,7 +12,6 @@ import { CLI_COMMAND_NAME } from "./distribution.js";
 import {
   formatSkillInstall,
   installCursorSkills,
-  LEGACY_CURSOR_SKILLS_NAMESPACE,
   planSkillInstall,
   type SkillInstallPlan,
 } from "./install-cursor-skills.js";
@@ -61,7 +60,7 @@ export async function cmdInstallSkills(options: InstallSkillsCliOptions = {}): P
       return 0;
     }
     const action = plan.firstInstall ? "install" : "update";
-    out(`Would ${action} ${plan.leaves.length} Agent SDK ${noun}\n`);
+    out(`Would ${action} ${plan.leaves.length} BDK ${noun}\n`);
     out(previewBlock(plan));
     return 0;
   }
@@ -91,8 +90,8 @@ function previewBlock(plan: SkillInstallPlan): string {
   if (plan.orphans.length > 0) {
     lines.push(`  removes:  ${plan.orphans.join(", ")}`);
   }
-  if (plan.hasLegacyNamespace) {
-    lines.push(`  removes:  ${LEGACY_CURSOR_SKILLS_NAMESPACE}/ (legacy namespace)`);
+  for (const dir of plan.legacyDirs) {
+    lines.push(`  removes:  ${dir}`);
   }
   lines.push(`  location: ${plan.directory}`);
   return `${lines.join("\n")}\n`;

package/src/internal/connection-env.ts

@@ -0,0 +1,106 @@
+/**
+ * `${NAME}` expansion for MCP connection credentials, applied when a
+ * transport is built instead of when its module is imported.
+ *
+ * Discovery imports `mcp-connections/*.ts` once, at startup. A hosted
+ * deployment has none of its secrets in the environment at that point: the
+ * control plane binds them per request and `consumeHostedBoundSecrets` copies
+ * them into `process.env` at the top of the turn. A `process.env.TOKEN` read
+ * inside `defineConnection` therefore captures an empty value for the life of
+ * the process, while a `"Bearer ${TOKEN}"` template stays verbatim on the
+ * transport and resolves here, each time a client opens.
+ */
+
+import { createHash } from "node:crypto";
+import type { ConnectionTransport } from "../types.js";
+
+/** `${NAME}`, plus the `mcp.json` spelling `${env:NAME}`. */
+const ENV_TEMPLATE = /\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+type Env = Record<string, string | undefined>;
+
+/** Credential-bearing values of a transport: HTTP headers or stdio env. */
+function credentials(transport: ConnectionTransport): Record<string, string> | undefined {
+  if ("url" in transport) {
+    return transport.headers;
+  }
+  if ("command" in transport) {
+    return transport.env;
+  }
+  return undefined;
+}
+
+function expand(value: string, env: Env): string {
+  return value.replace(ENV_TEMPLATE, (_match, name: string) => env[name] ?? "");
+}
+
+/** The same object back when nothing templates, so callers can compare by identity. */
+function expandRecord(
+  values: Record<string, string> | undefined,
+  env: Env,
+): Record<string, string> | undefined {
+  if (values === undefined) {
+    return undefined;
+  }
+  const expanded: Record<string, string> = {};
+  let changed = false;
+  for (const [key, value] of Object.entries(values)) {
+    expanded[key] = expand(value, env);
+    changed ||= expanded[key] !== value;
+  }
+  return changed ? expanded : values;
+}
+
+/**
+ * Substitute `${NAME}` in the transport's headers (http/sse) or env (stdio)
+ * from the environment as it stands now. An unset variable resolves to an
+ * empty string, as reading it in the module would have.
+ */
+export function resolveConnectionEnvTemplates<T extends ConnectionTransport>(
+  transport: T,
+  env: Env = process.env,
+): T {
+  if ("url" in transport) {
+    const headers = expandRecord(transport.headers, env);
+    return headers === transport.headers ? transport : ({ ...transport, headers } as T);
+  }
+  if ("command" in transport) {
+    const spawnEnv = expandRecord(transport.env, env);
+    return spawnEnv === transport.env ? transport : ({ ...transport, env: spawnEnv } as T);
+  }
+  return transport;
+}
+
+/** Variables a transport templates that the environment does not define, in first-seen order. */
+export function unresolvedConnectionEnvNames(
+  transport: ConnectionTransport,
+  env: Env = process.env,
+): string[] {
+  const missing = new Set<string>();
+  for (const value of Object.values(credentials(transport) ?? {})) {
+    for (const match of value.matchAll(ENV_TEMPLATE)) {
+      const name = match[1];
+      if (name !== undefined && env[name] === undefined) {
+        missing.add(name);
+      }
+    }
+  }
+  return [...missing];
+}
+
+/**
+ * Identifies the credentials a client would open with right now, so a cached
+ * client is recognizable as stale once the environment changes underneath it.
+ * Hashed rather than stored, so the cache key is not a second copy of the
+ * secret.
+ */
+export function connectionCredentialsFingerprint(
+  transport: ConnectionTransport,
+  env: Env = process.env,
+): string {
+  const resolved = credentials(resolveConnectionEnvTemplates(transport, env));
+  if (resolved === undefined) {
+    return "";
+  }
+  return createHash("sha256").update(JSON.stringify(resolved)).digest("hex");
+}

package/src/internal/cursor/backend-client.ts

@@ -938,6 +938,12 @@ function describeGithubTokenHttpFailure(
       detail === undefined ? "" : `: ${detail}`
     }. Run \`${CLI} login\` again or update CURSOR_API_KEY.`;
   }
+  if (status === 429) {
+    const cleaned =
+      detail === undefined ? undefined : detail.replace(/\[?resource_exhausted\]?/gi, "").trim();
+    const suffix = cleaned === undefined || cleaned === "" ? "" : `: ${cleaned}`;
+    return `${label} API rate limit (429)${suffix}. Retry after the rate-limit window.`;
+  }
   if (detail !== undefined) {
     return detail;
   }

package/src/internal/deploy-client.ts

@@ -372,6 +372,21 @@ export interface AgentkitSessionRuns {
   startLog: string | null;
 }
 
+/** One event from the hosted session event poll. */
+export interface AgentkitSessionEvent {
+  index?: number;
+  type?: string;
+}
+
+/**
+ * `GET .../sessions/:sessionId/events?afterEventIndex=` body.
+ * Events land before the run log on a long turn.
+ */
+export interface AgentkitSessionEventPoll {
+  events: AgentkitSessionEvent[];
+  execution: { executionId: string; turnStatus: string } | null;
+}
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -556,6 +571,25 @@ const agentkitSessionRunsSchema = z
   })
   .passthrough();
 
+const agentkitSessionEventPollSchema = z
+  .object({
+    events: z.array(
+      z
+        .object({
+          index: z.number().optional(),
+          type: z.string().optional(),
+        })
+        .passthrough(),
+    ),
+    execution: z
+      .object({
+        executionId: z.string(),
+        turnStatus: z.string(),
+      })
+      .nullable(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -983,26 +1017,44 @@ export class AgentServeDeployClient {
     return agentkitEventRepositoriesSchema.parse(raw).repositories;
   }
 
-  /**
-   * Pin a v2 install onto a release
-   * (`PUT /internal/agentsdk/deployments/:slug/release`), newest ready one
-   * when neither selector is given. A multi-tenant deploy leaves tenants
-   * on the release they were installed on.
-   */
   async upgradeAgentkitInstall(args: {
     teamId: number;
     slug: string;
     releaseId?: string;
     version?: string;
   }): Promise<string> {
+    return this.pinAgentkitInstall("upgrade", args);
+  }
+
+  async rollbackAgentkitInstall(args: {
+    teamId: number;
+    slug: string;
+    releaseId?: string;
+    version?: string;
+  }): Promise<string> {
+    return this.pinAgentkitInstall("rollback", args);
+  }
+
+  private async pinAgentkitInstall(
+    direction: "upgrade" | "rollback",
+    args: {
+      teamId: number;
+      slug: string;
+      releaseId?: string;
+      version?: string;
+    },
+  ): Promise<string> {
     const raw = await this.request({
-      method: "PUT",
-      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/release?teamId=${args.teamId}`,
+      method: direction === "upgrade" ? "PUT" : "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/${direction === "upgrade" ? "release" : "rollback"}?teamId=${args.teamId}`,
       body: {
         ...(args.releaseId === undefined ? {} : { releaseId: args.releaseId }),
         ...(args.version === undefined ? {} : { version: args.version }),
       },
-      context: { verb: "upgrade", slug: args.slug },
+      context: {
+        verb: direction === "upgrade" ? "upgrade" : "roll back",
+        slug: args.slug,
+      },
     });
     return agentkitInstallReleaseSchema.parse(raw).releaseId;
   }
@@ -1064,6 +1116,24 @@ export class AgentServeDeployClient {
     return agentkitSessionRunsSchema.parse(raw);
   }
 
+  /** Events written so far. Pass `afterEventIndex: -1` to read from the start. */
+  async getAgentkitSessionEvents(args: {
+    teamId: number;
+    slug: string;
+    sessionId: string;
+    afterEventIndex: number;
+  }): Promise<AgentkitSessionEventPoll> {
+    const raw = await this.request({
+      method: "GET",
+      path:
+        `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}` +
+        `/sessions/${encodeURIComponent(args.sessionId)}/events` +
+        `?teamId=${args.teamId}&afterEventIndex=${args.afterEventIndex}`,
+      context: { verb: "get session events", slug: args.slug },
+    });
+    return agentkitSessionEventPollSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",

package/src/internal/discovery/connections.ts

@@ -16,6 +16,7 @@ import {
   normalizeCursorAccountServers,
   type ToolEffect,
 } from "../../types.js";
+import { unresolvedConnectionEnvNames } from "../connection-env.js";
 import { packageInlineStdioConnection } from "../package-inline-stdio.js";
 import { type DiscoveryContext, displayPath, errorMessage, isBlank } from "./context.js";
 import { importDefault, moduleEntries } from "./modules.js";
@@ -424,6 +425,16 @@ export async function compileConnection(
     });
     return undefined;
   }
+  // A warning, never an error: templates resolve when the connection opens,
+  // and a hosted deployment binds its secrets after discovery has run.
+  const unresolved = unresolvedConnectionEnvNames(transport);
+  if (unresolved.length > 0) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, entryPath),
+      message: `MCP connection "${name}" templates ${unresolved.map(variable => `\${${variable}}`).join(", ")}, which the environment does not set. The value resolves when the connection opens, so hosted deployments are fine; locally, set it before the turn or the credential is empty.`,
+    });
+  }
   return {
     name,
     transport,

package/src/internal/hosted-delivery-protocol.ts

@@ -1,3 +1,9 @@
+/**
+ * Private control-plane/engine wire contract. Version 2 is unreleased and
+ * intentionally strict: unknown fields and modes fail closed. After release,
+ * any shape or semantic change must use a new version and a rolling
+ * compatibility window. See `docs/agent-serve/hosted-delivery-protocol.md`.
+ */
 export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
@@ -251,7 +257,7 @@ export type HostedAdmissionPlatformHandoff = {
   };
 };
 
-export type HostedAdmission = {
+export type HostedAdmissionInput = {
   v: 2;
   channelId: string;
   /**
@@ -270,9 +276,20 @@ export type HostedAdmission = {
   platformHandoff?: HostedAdmissionPlatformHandoff;
 };
 
+export type HostedAdmissionStart = HostedAdmissionInput & { mode: "start" };
+
+export type HostedAdmissionStatus = {
+  v: 2;
+  mode: "status";
+  deliveryId: string;
+};
+
+export type HostedAdmission = HostedAdmissionStart | HostedAdmissionStatus;
+
 export type HostedAdmissionOutcome =
   | { ok: true; v: 2; outcome: "skip" | "task" }
-  | { ok: true; v: 2; outcome: "send"; admissionToken: string };
+  | { ok: true; v: 2; outcome: "send"; admissionToken: string }
+  | { ok: true; v: 2; outcome: "started" | "running" };
 
 /**
  * Cap on delivery IDs an owner execute may report as consumed (primary +
@@ -281,19 +298,19 @@ export type HostedAdmissionOutcome =
  */
 export const HOSTED_MAX_CONSUMED_DELIVERY_IDS = 16;
 
-/** Hosted-execution run mode. Omitted/`execute` is the legacy wait path. */
-export type HostedExecutionMode = "execute" | "enqueue";
+/** Hosted-execution is unary: start/status for owners, enqueue for guests. */
+export type HostedExecutionMode = "enqueue" | "start" | "status";
 
 export type HostedExecution = {
   v: 2;
   admissionToken: string;
   sessionPublicId: string;
   /**
-   * `execute` (default when omitted) runs the owner send and waits for the
-   * coalesce chain. `enqueue` injects into an accepting owner or returns
-   * `not_active`.
+   * `enqueue` injects into an accepting owner or returns `not_active`.
+   * `start` launches the owner turn and returns `started` immediately.
+   * `status` returns `running` or replays the terminal response.
    */
-  mode?: HostedExecutionMode;
+  mode: HostedExecutionMode;
 };
 
 export type HostedExecutionOutcome =
@@ -303,16 +320,17 @@ export type HostedExecutionOutcome =
       outcome: "send";
       /**
        * Primary delivery id then accepted enqueue ids; length 1..16.
-       * Optional for old-guest compatibility; callers must normalize absent
-       * lists to `[primaryDeliveryId]`.
        */
-      consumedDeliveryIds?: string[];
+      consumedDeliveryIds: string[];
     }
   | { ok: true; v: 2; outcome: "enqueued" }
-  | { ok: true; v: 2; outcome: "not_active" };
+  | { ok: true; v: 2; outcome: "not_active" }
+  | { ok: true; v: 2; outcome: "started" }
+  | { ok: true; v: 2; outcome: "running" };
 
 const DELIVERY_KEYS = new Set([
   "v",
+  "mode",
   "channelId",
   "channelKind",
   "eventType",
@@ -435,10 +453,18 @@ export function parseHostedAdmission(value: unknown): HostedAdmission | undefine
     return undefined;
   }
   const body = value as Record<string, unknown>;
+  if (body.mode === "status") {
+    return Object.keys(body).every(key => key === "v" || key === "mode" || key === "deliveryId") &&
+      body.v === HOSTED_DELIVERY_PROTOCOL_VERSION &&
+      boundedString(body.deliveryId, 256)
+      ? (body as HostedAdmissionStatus)
+      : undefined;
+  }
   if (
     Object.keys(body).some(key => !DELIVERY_KEYS.has(key)) ||
     !Object.hasOwn(body, "payload") ||
     body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    body.mode !== "start" ||
     !boundedString(body.channelId, 128) ||
     !boundedString(body.channelKind, 128) ||
     !boundedString(body.eventType, 128) ||
@@ -468,7 +494,7 @@ export function parseHostedExecution(value: unknown): HostedExecution | undefine
   ) {
     return undefined;
   }
-  if (body.mode !== undefined && body.mode !== "execute" && body.mode !== "enqueue") {
+  if (body.mode !== "enqueue" && body.mode !== "start" && body.mode !== "status") {
     return undefined;
   }
   return body as HostedExecution;
@@ -501,7 +527,12 @@ export function parseHostedExecutionOutcome(value: unknown): HostedExecutionOutc
   ) {
     return undefined;
   }
-  if (body.outcome === "enqueued" || body.outcome === "not_active") {
+  if (
+    body.outcome === "enqueued" ||
+    body.outcome === "not_active" ||
+    body.outcome === "started" ||
+    body.outcome === "running"
+  ) {
     if (body.consumedDeliveryIds !== undefined) {
       return undefined;
     }
@@ -510,10 +541,6 @@ export function parseHostedExecutionOutcome(value: unknown): HostedExecutionOutc
   if (body.outcome !== "send") {
     return undefined;
   }
-  // Old guests omit consumedDeliveryIds; accept and let callers normalize.
-  if (body.consumedDeliveryIds === undefined) {
-    return { ok: true, v: 2, outcome: "send" };
-  }
   const consumedDeliveryIds = parseConsumedDeliveryIds(body.consumedDeliveryIds);
   if (consumedDeliveryIds === undefined) {
     return undefined;
@@ -530,7 +557,7 @@ export function parseHostedExecutionOutcome(value: unknown): HostedExecutionOutc
  * True when the admission envelope is the reserved internal reminder fire
  * path (not an authored channel event).
  */
-export function isHostedReminderAdmission(delivery: HostedAdmission): boolean {
+export function isHostedReminderAdmission(delivery: HostedAdmissionInput): boolean {
   return (
     delivery.channelKind === HOSTED_REMINDER_CHANNEL_KIND &&
     delivery.eventType === HOSTED_REMINDER_EVENT_TYPE
@@ -768,20 +795,30 @@ export function parseHostedReminderFireDescriptorPayload(
   };
 }
 
+const HOSTED_ADMISSION_OUTCOME_KEYS = new Set(["ok", "v", "outcome", "admissionToken"]);
+
 export function parseHostedAdmissionOutcome(value: unknown): HostedAdmissionOutcome | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return undefined;
   }
   const body = value as Record<string, unknown>;
   if (
+    Object.keys(body).some(key => !HOSTED_ADMISSION_OUTCOME_KEYS.has(key)) ||
     body.ok !== true ||
     body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
-    (body.outcome !== "skip" && body.outcome !== "send" && body.outcome !== "task")
+    (body.outcome !== "skip" &&
+      body.outcome !== "send" &&
+      body.outcome !== "task" &&
+      body.outcome !== "started" &&
+      body.outcome !== "running")
   ) {
     return undefined;
   }
   if (body.outcome === "send" && !boundedString(body.admissionToken, 128)) {
     return undefined;
   }
+  if (body.outcome !== "send" && Object.hasOwn(body, "admissionToken")) {
+    return undefined;
+  }
   return body as HostedAdmissionOutcome;
 }