@cursor/bdk 0.2.2 → 0.2.3

package/src/internal/hosting.ts

@@ -7,8 +7,8 @@
  * locally with the same grammar the server enforces.
  */
 
-/** `hosting.egressDomains` cap (backend caps the deploy body at 20). */
-export const MAX_EGRESS_DOMAINS = 20;
+/** `hosting.egressDomains` cap (the manifest schema and deploy body agree). */
+export const MAX_EGRESS_DOMAINS = 64;
 /** Max secrets per deployment. */
 export const MAX_SECRETS = 32;
 /** Max secret value size in bytes. */
@@ -46,12 +46,19 @@ const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 // leading `*.` wildcard. Labels: alphanumeric with interior hyphens.
 const EGRESS_DOMAIN_PATTERN = /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+$/;
 
+/** `host:port` asks for raw TCP egress; a wildcard host has no address to open. */
+const EGRESS_TCP_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+:([1-9]\d{0,4})$/;
+
 /** Returns a human error message, or undefined when the domain is valid. */
 export function validateEgressDomain(domain: string): string | undefined {
   if (EGRESS_DOMAIN_PATTERN.test(domain)) {
     return undefined;
   }
-  return `Invalid egress domain ${JSON.stringify(domain)}: use a lowercase hostname with at least two labels and an alphabetic TLD (e.g. "api.example.com"), optionally with a single leading "*." wildcard.`;
+  const tcp = EGRESS_TCP_PATTERN.exec(domain);
+  if (tcp !== null && Number(tcp[3]) <= 65535) {
+    return undefined;
+  }
+  return `Invalid egress domain ${JSON.stringify(domain)}: use a lowercase hostname with at least two labels and an alphabetic TLD (e.g. "api.example.com"), optionally with a single leading "*." wildcard or a trailing ":port" for raw TCP.`;
 }
 
 /**

package/src/internal/install-cursor-skills.ts

@@ -1,8 +1,8 @@
 /**
  * Offer to install the package's coding-agent skills into the user's
- * personal Cursor skills dir under `~/.cursor/skills/agentsdk/<skill>/`.
+ * personal Cursor skills dir under `~/.cursor/skills/bdk/<skill>/`.
  *
- * Cursor walks `~/.cursor/skills` recursively, so the `agentsdk/` folder is
+ * Cursor walks `~/.cursor/skills` recursively, so the `bdk/` folder is
  * only organizational — identity comes from the leaf folder that holds
  * SKILL.md. Installed copies get `alwaysApply: true` so Cursor injects the
  * skill body as a global rule instead of leaving it as an on-demand catalog
@@ -22,10 +22,13 @@ import { parseFrontmatter } from "./frontmatter.js";
 import { stdoutPalette } from "./terminal-style.js";
 
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
-export const CURSOR_SKILLS_NAMESPACE = "agentsdk";
+export const CURSOR_SKILLS_NAMESPACE = "bdk";
 
-/** Pre-rename install folder. Install deletes this so `/agentkit-*` rows disappear. */
-export const LEGACY_CURSOR_SKILLS_NAMESPACE = "agentkit";
+/**
+ * Earlier install folders. Deleted on install so stale skill ids stop
+ * being discovered next to the current copies.
+ */
+const LEGACY_CURSOR_SKILLS_NAMESPACES = ["agentsdk", "agentkit"] as const;
 
 /** How long the `init` offer waits for an answer before skipping the install. */
 export const SKILL_PROMPT_TIMEOUT_MS = 45_000;
@@ -40,9 +43,9 @@ export const CURSOR_JULY_SKILLS_HOME_ENV = "CURSOR_JULY_SKILLS_HOME";
 export const CURSOR_JULY_SKIP_SKILL_INSTALL_ENV = "CURSOR_JULY_SKIP_SKILL_INSTALL";
 
 export interface PackageSkill {
-  /** Frontmatter `name` (e.g. agentsdk-create-agent). */
+  /** Frontmatter `name` (e.g. bdk-create-agent). */
   name: string;
-  /** Leaf install directory under agentsdk/ (e.g. create-agent). */
+  /** Leaf install directory under bdk/ (e.g. create-agent). */
   leafDir: string;
   /** Absolute path to the source skill directory in the package. */
   sourceDir: string;
@@ -71,27 +74,26 @@ export function isConsumerPackageInstall(packageRoot: string): boolean {
   return packageRoot.split(/[\\/]/).includes("node_modules");
 }
 
-/** `~/.cursor/skills/agentsdk` — where package skills are installed. */
-export function agentsdkCursorSkillsDir(skillsHome: string = cursorSkillsHome()): string {
+/** `~/.cursor/skills/bdk` — where package skills are installed. */
+export function bdkCursorSkillsDir(skillsHome: string = cursorSkillsHome()): string {
   return join(skillsHome, CURSOR_SKILLS_NAMESPACE);
 }
 
-/** Pre-rename `~/.cursor/skills/agentkit`. */
-export function legacyAgentkitCursorSkillsDir(skillsHome: string = cursorSkillsHome()): string {
-  return join(skillsHome, LEGACY_CURSOR_SKILLS_NAMESPACE);
+function legacyCursorSkillsDirs(skillsHome: string): string[] {
+  return LEGACY_CURSOR_SKILLS_NAMESPACES.map(name => join(skillsHome, name));
 }
 
-/** Absolute install path for one skill: `…/agentsdk/<leafDir>`. */
+/** Absolute install path for one skill: `…/bdk/<leafDir>`. */
 export function skillInstallPath(
   skill: Pick<PackageSkill, "leafDir">,
   skillsHome: string = cursorSkillsHome(),
 ): string {
-  return join(agentsdkCursorSkillsDir(skillsHome), skill.leafDir);
+  return join(bdkCursorSkillsDir(skillsHome), skill.leafDir);
 }
 
 /**
  * Skills shipped next to the running package. Uses the frontmatter `name`
- * when present, otherwise `agentsdk-<dir>`.
+ * when present, otherwise `bdk-<dir>`.
  */
 export async function listShippedPackageSkills(
   packageRoot: string = packageRootDir(),
@@ -137,7 +139,7 @@ async function readPackageVersion(packageRoot: string): Promise<string> {
 }
 
 /**
- * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentsdk/.
+ * Skills that do not yet have a SKILL.md under ~/.cursor/skills/bdk/.
  * Install still overwrites every shipped skill when the user confirms — this
  * helper is for messaging (fresh install vs update).
  */
@@ -163,22 +165,22 @@ export interface SkillInstallResult {
   installed: string[];
   /** Leaf dirs deleted because the package no longer ships them. */
   removed: string[];
-  /** True when leftover `~/.cursor/skills/agentkit` was deleted. */
-  removedLegacyNamespace: boolean;
+  /** Leftover namespace dirs deleted (`…/agentsdk`, `…/agentkit`). */
+  removedLegacyDirs: string[];
 }
 
 /**
- * Copy each skill directory into `skillsHome/agentsdk/<leafDir>/`.
+ * Copy each skill directory into `skillsHome/bdk/<leafDir>/`.
  * Always overwrites so a package upgrade refreshes local Cursor skills.
  * Strips monorepo-only frontmatter, sets `alwaysApply: true` so Cursor
  * loads the body into context, and removes leaf dirs no longer shipped.
- * Also deletes leftover `skillsHome/agentkit/` from the previous namespace.
+ * Also deletes leftover `skillsHome/agentsdk/` and `skillsHome/agentkit/`.
  */
 export async function installCursorSkills(
   skills: readonly PackageSkill[],
   skillsHome: string = cursorSkillsHome(),
 ): Promise<SkillInstallResult> {
-  const namespaceDir = agentsdkCursorSkillsDir(skillsHome);
+  const namespaceDir = bdkCursorSkillsDir(skillsHome);
   await mkdir(namespaceDir, { recursive: true });
 
   const removed = await orphanLeaves(namespaceDir, skills);
@@ -203,8 +205,8 @@ export async function installCursorSkills(
     }
     installed.push(skill.leafDir);
   }
-  const removedLegacyNamespace = await removeLegacyCursorSkillsNamespace(skillsHome);
-  return { installed, removed, removedLegacyNamespace };
+  const removedLegacyDirs = await removeLegacyCursorSkillsNamespaces(skillsHome);
+  return { installed, removed, removedLegacyDirs };
 }
 
 async function makeTreeWritable(root: string): Promise<void> {
@@ -245,25 +247,26 @@ async function orphanLeaves(
     .map(entry => entry.name);
 }
 
-/** Drop leftover `skillsHome/agentkit` from the previous install namespace. */
-async function removeLegacyCursorSkillsNamespace(skillsHome: string): Promise<boolean> {
-  const legacyDir = legacyAgentkitCursorSkillsDir(skillsHome);
-  try {
-    await stat(legacyDir);
-  } catch {
-    return false;
+/** Drop leftover earlier install folders so stale skill ids are not discovered. */
+async function removeLegacyCursorSkillsNamespaces(skillsHome: string): Promise<string[]> {
+  const present = await existingLegacyCursorSkillsDirs(skillsHome);
+  for (const dir of present) {
+    await rm(dir, { recursive: true, force: true });
   }
-  await rm(legacyDir, { recursive: true, force: true });
-  return true;
+  return present;
 }
 
-async function hasLegacyCursorSkillsNamespace(skillsHome: string): Promise<boolean> {
-  try {
-    await stat(legacyAgentkitCursorSkillsDir(skillsHome));
-    return true;
-  } catch {
-    return false;
+async function existingLegacyCursorSkillsDirs(skillsHome: string): Promise<string[]> {
+  const present: string[] = [];
+  for (const dir of legacyCursorSkillsDirs(skillsHome)) {
+    try {
+      await stat(dir);
+      present.push(dir);
+    } catch {
+      continue;
+    }
   }
+  return present;
 }
 
 /**
@@ -289,7 +292,7 @@ export function prepareSkillMarkdownForCursorInstall(
     adjustedBody.includes(PACKAGE_VERSION_PLACEHOLDER) &&
     (packageVersion === undefined || packageVersion.trim() === "")
   ) {
-    throw new Error("Cannot install an Agent SDK skill without a package version.");
+    throw new Error("Cannot install a BDK skill without a package version.");
   }
   const versionBoundBody =
     packageVersion === undefined
@@ -333,7 +336,7 @@ export interface SkillInstallPlan {
   shipped: PackageSkill[];
   /** Resolved `~/.cursor/skills`, to install into. */
   skillsHome: string;
-  /** Install target: `<skillsHome>/agentsdk`. */
+  /** Install target: `<skillsHome>/bdk`. */
   directory: string;
   /** Leaf dirs the package ships. */
   leaves: string[];
@@ -341,8 +344,8 @@ export interface SkillInstallPlan {
   firstInstall: boolean;
   /** Installed leaf dirs the package dropped; installing deletes them. */
   orphans: string[];
-  /** True when leftover `skillsHome/agentkit` still exists. */
-  hasLegacyNamespace: boolean;
+  /** Leftover namespace dirs that still exist. Installing deletes them. */
+  legacyDirs: string[];
 }
 
 /** What an install would do, for the offer and for `install-skills`. */
@@ -351,7 +354,7 @@ export async function planSkillInstall(options?: {
   skillsHome?: string;
 }): Promise<SkillInstallPlan> {
   const skillsHome = options?.skillsHome ?? cursorSkillsHome();
-  const directory = agentsdkCursorSkillsDir(skillsHome);
+  const directory = bdkCursorSkillsDir(skillsHome);
   const shipped = await listShippedPackageSkills(options?.packageRoot);
   const present = await Promise.all(
     shipped.map(async skill => {
@@ -370,20 +373,20 @@ export async function planSkillInstall(options?: {
     leaves: shipped.map(skill => skill.leafDir),
     firstInstall: present.every(isPresent => !isPresent),
     orphans: await orphanLeaves(directory, shipped),
-    hasLegacyNamespace: await hasLegacyCursorSkillsNamespace(skillsHome),
+    legacyDirs: await existingLegacyCursorSkillsDirs(skillsHome),
   };
 }
 
-/** `Installed 9 Agent SDK skills`, what it dropped, and where it went. */
+/** `Installed 9 BDK skills`, what it dropped, and where it went. */
 export function formatSkillInstall(plan: SkillInstallPlan, result: SkillInstallResult): string {
   const noun = result.installed.length === 1 ? "skill" : "skills";
   const verb = plan.firstInstall ? "Installed" : "Updated";
-  const lines = [`${verb} ${result.installed.length} Agent SDK ${noun}`];
+  const lines = [`${verb} ${result.installed.length} BDK ${noun}`];
   if (result.removed.length > 0) {
     lines.push(`  removed:  ${result.removed.join(", ")}`);
   }
-  if (result.removedLegacyNamespace) {
-    lines.push(`  removed:  ${legacyAgentkitCursorSkillsDir(plan.skillsHome)} (legacy namespace)`);
+  for (const dir of result.removedLegacyDirs) {
+    lines.push(`  removed:  ${dir}`);
   }
   lines.push(`  location: ${plan.directory}`);
   return `${lines.join("\n")}\n`;
@@ -406,7 +409,7 @@ export interface SyncCursorSkillsOnPackageInstallOptions {
 }
 
 /**
- * Copy shipped coding-agent skills into ~/.cursor/skills/agentsdk during a
+ * Copy shipped coding-agent skills into ~/.cursor/skills/bdk during a
  * consumer `npm install` / `npx`. Never throws: a failed copy must not fail
  * the package install. No-op in the monorepo source tree and when
  * `CURSOR_JULY_SKIP_SKILL_INSTALL=1`.
@@ -459,7 +462,7 @@ export interface OfferInstallCursorSkillsOptions {
 
 /**
  * On a TTY, offer to install/update every shipped package skill into
- * ~/.cursor/skills/agentsdk (always overwriting). No-op when non-interactive
+ * ~/.cursor/skills/bdk (always overwriting). No-op when non-interactive
  * or the package ships no skills. An unanswered prompt skips the install
  * rather than blocking the caller — see `SKILL_PROMPT_TIMEOUT_MS`.
  */
@@ -484,7 +487,7 @@ export async function offerInstallCursorSkills(
   const noun = plan.shipped.length === 1 ? "skill" : "skills";
   const verb = plan.firstInstall ? "Install" : "Update";
   const c = stdoutPalette();
-  out(`${verb} ${plan.shipped.length} Agent SDK ${noun} in ${plan.directory}?\n`);
+  out(`${verb} ${plan.shipped.length} BDK ${noun} in ${plan.directory}?\n`);
   out(c.dim(`  ${plan.leaves.join(", ")}\n`));
   if (!plan.firstInstall) {
     out(c.dim("  (overwrites existing copies with the package version)\n"));
@@ -492,8 +495,8 @@ export async function offerInstallCursorSkills(
   if (plan.orphans.length > 0) {
     out(c.dim(`  (deletes ${plan.orphans.join(", ")})\n`));
   }
-  if (plan.hasLegacyNamespace) {
-    out(c.dim(`  (deletes leftover ${legacyAgentkitCursorSkillsDir(plan.skillsHome)})\n`));
+  for (const dir of plan.legacyDirs) {
+    out(c.dim(`  (deletes leftover ${dir})\n`));
   }
 
   const confirm =

package/src/internal/legacy-command-guard.ts

@@ -1,4 +1,5 @@
 import { type AgentServeDeployClient, DeployApiError } from "./deploy-client.js";
+import { CLI_COMMAND_NAME } from "./distribution.js";
 
 /**
  * Classify a hosted slug by probing the v2 control plane.
@@ -27,9 +28,20 @@ export async function deploymentArchitecture(args: {
   }
 }
 
+/** `run --prod` returns a delivery; read the session after it is allocated. */
+export function v2HostedVerifyHint(slug = "<slug>"): string {
+  return (
+    `\`${CLI_COMMAND_NAME} run --prod\` returns a delivery. ` +
+    `An accept without sessionId is expected. ` +
+    `Poll the delivery until the session is allocated, then ` +
+    `\`${CLI_COMMAND_NAME} session <ses_> --prod --slug ${slug}\`.`
+  );
+}
+
 export function unsupportedV2LegacyCommandError(slug: string): DeployApiError {
   return new DeployApiError(
-    `This command is not supported for architecture v2 deployment "${slug}". The command stopped before calling the legacy v1 deployment API.`,
+    `This command is not supported for architecture v2 deployment "${slug}". ` +
+      `call and sessions stay on the v1 API. ${v2HostedVerifyHint(slug)}`,
     409,
   );
 }

package/src/internal/mcp-host.ts

@@ -24,6 +24,10 @@ import {
   type JsonObject,
   type McpToolAnnotations,
 } from "../types.js";
+import {
+  connectionCredentialsFingerprint,
+  resolveConnectionEnvTemplates,
+} from "./connection-env.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
 import { instrumentedMcpFetch, mcpTraceMeta, runMcpClientSpan } from "./otel/mcp.js";
@@ -67,6 +71,12 @@ interface OpenedConnection {
   close: () => Promise<void>;
 }
 
+interface CachedClient {
+  /** Fingerprint of the credentials this client opened with. */
+  credentials: string;
+  opened: Promise<OpenedConnection>;
+}
+
 /**
  * A non-caching view of one connection: every operation opens a fresh
  * client and closes it afterwards. See {@link McpHost.oneOff}.
@@ -78,7 +88,7 @@ export interface HostMcpOneOff {
 
 export class McpHost implements HostMcpRegistry {
   private readonly byName = new Map<string, DiscoveredConnection>();
-  private readonly clients = new Map<string, Promise<OpenedConnection>>();
+  private readonly clients = new Map<string, CachedClient>();
   private oauthRedirectUrl: string | undefined;
 
   constructor(connections: DiscoveredConnection[]) {
@@ -187,20 +197,20 @@ export class McpHost implements HostMcpRegistry {
   }
 
   async dropClient(name: string): Promise<void> {
-    const pending = this.clients.get(name);
+    const cached = this.clients.get(name);
     this.clients.delete(name);
-    if (pending === undefined) {
+    if (cached === undefined) {
       return;
     }
     try {
-      await (await pending).close();
+      await (await cached.opened).close();
     } catch {
       // Best-effort teardown.
     }
   }
 
   async close(): Promise<void> {
-    const opened = await Promise.allSettled([...this.clients.values()]);
+    const opened = await Promise.allSettled([...this.clients.values()].map(entry => entry.opened));
     this.clients.clear();
     await Promise.allSettled(
       opened.map(async settled => {
@@ -234,23 +244,41 @@ export class McpHost implements HostMcpRegistry {
     }
   }
 
+  /**
+   * Cached per connection, but only for as long as the credentials it opened
+   * with still apply: a hosted deployment binds its secrets per request, so a
+   * rotated (or first-ever) value would otherwise never reach a client opened
+   * on an earlier turn.
+   */
   private getClient(name: string): Promise<OpenedConnection> {
-    let pending = this.clients.get(name);
-    if (pending === undefined) {
-      pending = this.connect(name).catch(error => {
-        this.clients.delete(name);
-        throw error;
-      });
-      this.clients.set(name, pending);
+    const credentials = connectionCredentialsFingerprint(this.requireConnection(name).transport);
+    const cached = this.clients.get(name);
+    if (cached !== undefined) {
+      if (cached.credentials === credentials) {
+        return cached.opened;
+      }
+      void this.dropClient(name);
     }
-    return pending;
+    // Only evict this entry: a connect that fails after its credentials were
+    // replaced would otherwise orphan the client that replaced it.
+    const entry: CachedClient = {
+      credentials,
+      opened: this.connect(name).catch(error => {
+        if (this.clients.get(name) === entry) {
+          this.clients.delete(name);
+        }
+        throw error;
+      }),
+    };
+    this.clients.set(name, entry);
+    return entry.opened;
   }
 
   private async invalidateClient(name: string, opened: OpenedConnection): Promise<void> {
-    const pending = this.clients.get(name);
-    if (pending !== undefined) {
+    const cached = this.clients.get(name);
+    if (cached !== undefined) {
       try {
-        if ((await pending) === opened) {
+        if ((await cached.opened) === opened) {
           this.clients.delete(name);
         }
       } catch {
@@ -385,7 +413,7 @@ async function openConnection(
 }
 
 async function createTransport(connection: DiscoveredConnection, oauthRedirectUrl?: string) {
-  const transport = connection.transport;
+  const transport = resolveConnectionEnvTemplates(connection.transport);
   if ("agent" in transport) {
     // Peers are resolved to concrete URLs by the serve host before any call
     // (SessionEngine.setResolvedConnections); reaching here means the

package/src/internal/sdk-runner.ts

@@ -210,12 +210,23 @@ export function isModelCapacityError(
   message: string | undefined,
   code?: string | undefined,
 ): boolean {
+  if (isGithubApiRateLimitMessage(message)) {
+    return false;
+  }
   if (code !== undefined && /^(resource_exhausted|unavailable)$/i.test(code)) {
     return true;
   }
   return message !== undefined && /resource_exhausted|\[unavailable\]/i.test(message);
 }
 
+/** GitHub token 429s share `resource_exhausted` with model capacity. */
+export function isGithubApiRateLimitMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /github/i.test(message) && /(rate limit|\b429\b)/i.test(message);
+}
+
 export function isModelCapacityErrorMessage(message: string | undefined): boolean {
   return isModelCapacityError(message);
 }

package/src/internal/server.ts

@@ -377,8 +377,14 @@ export async function startServer(
   // The SCM relay reads the event stream as the signed-in user, so
   // `cursorEvents` cannot work signed out. Require the credential before any
   // slow or stateful startup work (playground build, channel onStart, cron).
+  // Not on a hosted v2 guest: under `--no-control-plane` with no v1 mount
+  // this process never polls `/v0/scm-events` (the hosted control plane
+  // owns ingest), and a persistent slot starts before its first credential
+  // is bound, so demanding one here would refuse a guest that never needed it.
+  const hostedControlPlaneOwnsIngest =
+    noControlPlane && mounts.every(mount => isV2Project(mount.project));
   const cursorEventsAuth =
-    effectiveCursorEvents === undefined
+    effectiveCursorEvents === undefined || hostedControlPlaneOwnsIngest
       ? undefined
       : requireCursorEventsAuth(effectiveCursorEvents, accountKey);
 
@@ -1136,6 +1142,12 @@ export async function startServer(
         "[agent-sdk] cursor-events: skipping v2 scm-events poll (--no-control-plane); hosted CP owns ingest",
       );
     }
+  } else if (hostedControlPlaneOwnsIngest && effectiveCursorEvents !== undefined) {
+    // No credential was required above, so no relay object was built; the
+    // outcome is the same skip.
+    logger(
+      "[agent-sdk] cursor-events: skipping v2 scm-events poll (--no-control-plane); hosted CP owns ingest",
+    );
   }
 
   // Cursor deployment-events relay: automatic when a mounted agent authored

package/src/internal/session-engine.ts

@@ -104,6 +104,7 @@ import {
   isUnpricedCompletedTurn,
   mapSdkTokenUsage,
 } from "./cloud-turn-cost.js";
+import { resolveConnectionEnvTemplates } from "./connection-env.js";
 import {
   applyAgentContinuationDefaults,
   channelContinuationIdentity,
@@ -3002,7 +3003,7 @@ export class SessionEngine {
         if (evaluated === undefined) {
           continue;
         }
-        const transport = connection.transport;
+        const transport = resolveConnectionEnvTemplates(connection.transport);
         if ("url" in transport) {
           servers[connection.name] = {
             ...transport,
@@ -3011,7 +3012,9 @@ export class SessionEngine {
         }
         continue;
       }
-      servers[connection.name] = connection.transport;
+      // Templated credentials resolve here, once per turn: the module that
+      // declared them was imported before the platform bound any secret.
+      servers[connection.name] = resolveConnectionEnvTemplates(connection.transport);
     }
     for (const resolved of this.resolvedConnections) {
       if (advertisedNames.has(resolved.name) || hostConnectionNames.has(resolved.name)) {
@@ -3660,11 +3663,12 @@ export class SessionEngine {
     if (!isHostOauthConnectionTransport(authored.transport)) {
       return undefined;
     }
+    const transport = resolveConnectionEnvTemplates(authored.transport);
     return await this.oauthHub.mint({
       connection,
-      url: authored.transport.url,
-      type: authored.transport.type === "sse" ? "sse" : "http",
-      headers: authored.transport.headers,
+      url: transport.url,
+      type: transport.type === "sse" ? "sse" : "http",
+      headers: transport.headers,
       sessionId,
     });
   }

package/src/types.ts

@@ -342,7 +342,10 @@ export interface AgentHostingOptions {
    * Domains the deployed engine pod may reach (egress allowlist), e.g.
    * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
    * Lowercase hostnames with at least two labels and an alphabetic TLD;
-   * max 20. `agent-sdk deploy` sends these as `egressAllowedDomains`
+   * max 64. A `"host:port"` entry (e.g. `"clickhouse.example.com:9440"`)
+   * opens raw TCP to that host's addresses, for wire protocols the proxy
+   * cannot read a TLS hostname from.
+   * `agent-sdk deploy` sends these as `egressAllowedDomains`
    * (unioned with any `--allow-domain` flags). Only valid on repo-backed
    * deployments. Deployment-scoped like {@link secretNames}: not capped by
    * the team's Cloud Agent egress allowlist. The platform still merges a
@@ -1219,6 +1222,13 @@ export interface DiscoveredExtension {
  *   resolves to a bridge on this host that executes every tool **on the
  *   Cursor backend** with the account's stored OAuth credentials — tokens
  *   never reach this host.
+ *
+ * Credentials belong in `headers` (http/sse) and `env` (stdio) as `${NAME}`
+ * templates, which the transport keeps verbatim and expands from the
+ * environment each time a client opens. Reading `process.env` in the
+ * connection module instead pins whatever the variable held when discovery
+ * imported it, which on Cursor hosting is nothing: the platform binds a
+ * deployment's secrets per request, long after that import.
  */
 export type ConnectionTransport =
   | {

package/templates/agents-md/bot/lib/collect.ts

@@ -335,10 +335,7 @@ async function readFile(
 ): Promise<string | undefined> {
   try {
     const { data } = await octokit.rest.repos.getContent(args);
-    if (Array.isArray(data) || data.encoding !== "base64") {
-      return undefined;
-    }
-    if (typeof data.content !== "string") {
+    if (Array.isArray(data) || data.type !== "file" || data.encoding !== "base64") {
       return undefined;
     }
     return Buffer.from(data.content, "base64").toString("utf8");

package/templates/code-wiki/bot/channels/github.ts

@@ -90,8 +90,8 @@ async function loadWiki(
       if (
         body === undefined ||
         Array.isArray(body) ||
-        body.encoding !== "base64" ||
-        typeof body.content !== "string"
+        body.type !== "file" ||
+        body.encoding !== "base64"
       ) {
         return;
       }

package/templates/demo/bot/channels/github.ts

@@ -12,7 +12,11 @@ function wake(url: string, github: GitHubHandle) {
   if (start === undefined || ref === undefined) {
     return null;
   }
-  return { task: () => startDemo(start, github, ref) };
+  return {
+    task: async () => {
+      await startDemo(start, github, ref);
+    },
+  };
 }
 
 export default githubChannel({

package/templates/pr-autofixer/bot/lib/start-drive.ts

@@ -7,13 +7,13 @@ import { fetchPrState, isTerminalPrState } from "./pr-state.js";
 
 export type StartDriveErrorCode = "missing_pr" | "unrecognized_pr";
 
-export interface StartDriveError {
+export type StartDriveError = {
   ok: false;
   code: StartDriveErrorCode;
   error: string;
-}
+};
 
-export interface StartDriveSuccess {
+export type StartDriveSuccess = {
   ok: true;
   pr: string;
   sessionId: string | null;
@@ -23,7 +23,7 @@ export interface StartDriveSuccess {
   status: string;
   result: string | null;
   mergeConflictReminderId: string | null;
-}
+};
 
 export type StartDriveResult = StartDriveError | StartDriveSuccess;