@cursor/bdk 0.2.1 → 0.2.3

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/files-backends/cursor-hosted.ts

@@ -925,10 +925,10 @@ export function cursorHostedFiles(options: CursorHostedFilesOptions = {}): Hoste
         if (files.wire !== "flush") {
           return false;
         }
-        // The flush wire's deletes are conditional server-side: when this
-        // process has no observed etag, the server resolves the current one —
-        // the lookup that costs a stat round trip on `/v0` — and a key that
-        // is already absent settles as `already_deleted`.
+        // With an observed etag the flush delete is If-Match on that version.
+        // Without one, the server tombstones whatever live object occupies
+        // the key (no directory walk here) and an absent key settles as
+        // `already_deleted`.
         const cached = observedEtags.get(key);
         const response = await flushPost<FlushWireResponse>(options, "/flush", {
           store: files.store,

package/src/internal/artifacts-store.ts

@@ -107,6 +107,12 @@ export interface CreateArtifactsStoreOptions {
   config?: ArtifactsConfig;
   /** Explicit sink override (tests). Omitted → hosted store or local disk. */
   sink?: FileSink;
+  /**
+   * Whether `tag` enforces {@link ArtifactsConfig.max} by listing and
+   * deleting. Default true. Hosted architecture v2 passes false: the
+   * installation store is allowed to grow, and a tag must not list the prefix.
+   */
+  enforceCap?: () => boolean;
 }
 
 /** Kind used by freeform tags when no kinds are declared. */
@@ -114,8 +120,11 @@ export const ARTIFACT_DEFAULT_KIND = "artifact";
 
 /**
  * Upsert + list semantics over one {@link ArtifactRowStore}: kind/schema
- * validation, deterministic ids for keyed tags, and `max` eviction. The
- * engine wraps this into the per-context {@link ArtifactsApi} facades and
+ * validation, deterministic ids for keyed tags, and `max` eviction.
+ * Architecture v1 and self-hosted v2 evict. Hosted architecture v2 sets
+ * {@link CreateArtifactsStoreOptions.enforceCap} false and does not list
+ * or delete on tag. The engine wraps this into the per-context
+ * {@link ArtifactsApi} facades and
  * owns the `artifact.tagged` event append.
  */
 export class ArtifactsStore {
@@ -123,6 +132,7 @@ export class ArtifactsStore {
   private readonly content: ArtifactContentStore;
   private readonly config: ArtifactsConfig | undefined;
   private readonly max: number;
+  private readonly enforceCap: () => boolean;
   /** Serializes tags so read-modify-write upserts and eviction don't race. */
   private tagChain: Promise<unknown> = Promise.resolve();
 
@@ -137,6 +147,7 @@ export class ArtifactsStore {
     }
     this.config = options.config;
     this.max = resolveArtifactsMax(options.config);
+    this.enforceCap = options.enforceCap ?? (() => true);
   }
 
   tag(input: ArtifactTagInput): Promise<ArtifactRecord> {
@@ -181,7 +192,7 @@ export class ArtifactsStore {
       }
     }
     await this.rows.put(record);
-    if (existing === undefined) {
+    if (existing === undefined && this.enforceCap()) {
       await this.evictPastCap();
     }
     return record;

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,

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,