@cursor/july 0.1.88 → 0.1.90

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

@@ -15,6 +15,8 @@
 
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import type { McpToolAnnotations } from "../../types.js";
+import { boundedToolAnnotations } from "../mcp-host.js";
 
 const CLIENT_VERSION = "agent-serve-0.1.0";
 const EXCHANGE_PATH = "/auth/exchange_user_api_key";
@@ -85,6 +87,8 @@ const mcpToolSchema = z.object({
   inputSchema: z.unknown().optional(),
   /** Flat JSON-string output schema (`output_schema_json` on the proto). */
   outputSchemaJson: z.string().optional(),
+  /** Flat JSON-string MCP annotations (`annotations_json` on the proto). */
+  annotationsJson: z.string().optional(),
 });
 
 const getAvailableMcpServersResponseSchema = z.object({
@@ -154,6 +158,13 @@ export interface AccountMcpTool {
    * matching the optional MCP `Tool.outputSchema` field.
    */
   outputSchema?: Record<string, unknown>;
+  /**
+   * MCP spec tool annotations as the connector's server reported them,
+   * bounded to the spec fields at parse time. Absent stays absent —
+   * untrusted hints, and the fail-closed signal for consumers that classify
+   * on them (dry-run effect resolution).
+   */
+  annotations?: McpToolAnnotations;
 }
 
 export interface AccountMcpServer {
@@ -285,6 +296,12 @@ async function parseRpcResponse(
 export interface CursorBackendClientOptions {
   backendUrl: string;
   apiKey: string;
+  /**
+   * Re-read the key on each authenticated call. Hosted freeze listens
+   * unsigned and the binder drops the key after restore; a constructor-frozen
+   * key would miss that bind.
+   */
+  getApiKey?: () => string;
   logger?: (line: string) => void;
   /** Test seam; defaults to global fetch. */
   fetchImpl?: typeof fetch;
@@ -292,21 +309,26 @@ export interface CursorBackendClientOptions {
 
 export class CursorBackendClient {
   private readonly backendUrl: string;
-  private readonly apiKey: string;
+  private readonly resolveApiKey: () => string;
   private readonly logger: (line: string) => void;
   private readonly fetchImpl: typeof fetch;
   private token: { value: string; expiresAtMs: number } | undefined;
   private tokenExchange: Promise<string> | undefined;
+  private lastExchangedApiKey: string | undefined;
 
   constructor(options: CursorBackendClientOptions) {
     this.backendUrl = options.backendUrl.endsWith("/")
       ? options.backendUrl.slice(0, -1)
       : options.backendUrl;
-    this.apiKey = options.apiKey;
+    this.resolveApiKey = options.getApiKey ?? (() => options.apiKey);
     this.logger = options.logger ?? (() => {});
     this.fetchImpl = options.fetchImpl ?? fetch;
   }
 
+  private currentApiKey(): string {
+    return this.resolveApiKey().trim();
+  }
+
   /** Who this API key acts as. */
   async getMe(): Promise<CursorIdentity> {
     return getMeResponseSchema.parse(await this.rpc("GetMe", {}));
@@ -331,11 +353,13 @@ export class CursorBackendClient {
       status: server.status,
       tools: (server.tools ?? []).map((tool) => {
         const outputSchema = parseOutputSchemaJson(tool.outputSchemaJson);
+        const annotations = parseAnnotationsJson(tool.annotationsJson);
         return {
           name: tool.name,
           description: tool.description ?? "",
           inputSchema: normalizeInputSchema(tool.inputSchema),
           ...(outputSchema === undefined ? {} : { outputSchema }),
+          ...(annotations === undefined ? {} : { annotations }),
         };
       }),
     }));
@@ -430,7 +454,7 @@ export class CursorBackendClient {
           method: "POST",
           headers: {
             "content-type": "application/json",
-            authorization: `Bearer ${this.apiKey}`,
+            authorization: `Bearer ${this.currentApiKey()}`,
           },
           body: JSON.stringify({ repos: [...repos], permissions }),
           signal: AbortSignal.timeout(30_000),
@@ -512,6 +536,18 @@ export class CursorBackendClient {
    * when none is cached or it is near expiry.
    */
   private getAccessToken(): Promise<string> {
+    const apiKey = this.currentApiKey();
+    if (apiKey === "") {
+      return Promise.reject(
+        new CursorBackendError(
+          "The Cursor backend client has no API key yet. Bind CURSOR_API_KEY or CURSOR_API_KEY_FILE before authenticated calls."
+        )
+      );
+    }
+    if (this.lastExchangedApiKey !== apiKey) {
+      this.token = undefined;
+      this.tokenExchange = undefined;
+    }
     if (
       this.token !== undefined &&
       Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS
@@ -528,13 +564,14 @@ export class CursorBackendClient {
   }
 
   private async exchangeApiKey(): Promise<string> {
+    const apiKey = this.currentApiKey();
     let response: Response;
     try {
       response = await this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
         method: "POST",
         headers: {
           "content-type": "application/json",
-          authorization: `Bearer ${this.apiKey}`,
+          authorization: `Bearer ${apiKey}`,
         },
         body: "{}",
         signal: AbortSignal.timeout(30_000),
@@ -563,6 +600,7 @@ export class CursorBackendClient {
       value: body.data.accessToken,
       expiresAtMs: jwtExpiryMs(body.data.accessToken),
     };
+    this.lastExchangedApiKey = apiKey;
     this.logger("[agent-sdk] cursor account: minted a fresh access token");
     return body.data.accessToken;
   }
@@ -707,6 +745,26 @@ function parseOutputSchemaJson(
     : undefined;
 }
 
+/**
+ * Parse the flat JSON-string annotations off the wire and bound them to the
+ * MCP-spec fields. Malformed or non-object payloads behave like absent ones,
+ * so readers fail closed.
+ */
+function parseAnnotationsJson(
+  annotationsJson: string | undefined
+): McpToolAnnotations | undefined {
+  if (annotationsJson === undefined) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(annotationsJson);
+  } catch {
+    return undefined;
+  }
+  return boundedToolAnnotations(parsed);
+}
+
 type McpResultJson = z.infer<typeof mcpResultSchema>;
 
 function toCallResult(result: McpResultJson): AccountMcpCallResult {

package/src/internal/cursor/credentials.ts

@@ -9,6 +9,10 @@
  *   dashboard-revocable user API key — only the key is stored.
  * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
  *   CI and hosted deployments stay env-driven.
+ * - `CURSOR_API_KEY_FILE` (or the hosted default path) is next: freeze bind
+ *   drops the key at task time without restarting July.
+ * - Stored `july login` is last. Same order for hosted and self-hosted:
+ *   option → env → file → login.
  *
  * There is deliberately no session-token storage, refresh-token rotation, or
  * cross-tool credential sharing here: short-lived access tokens are minted
@@ -16,6 +20,7 @@
  */
 
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -43,10 +48,11 @@ export function cursorBackendUrl(): string {
 
 /**
  * External API base URL for routes served only by the external-api
- * microlith (`/internal/agent-serve/*`, engine aliases). In production
- * these are mounted on api.cursor.com and 404 on api2.cursor.sh, so the
- * deploy surface needs its own default. `CURSOR_API_BASE_URL` still
- * overrides everything for local dev, where one server mounts all routes.
+ * microlith (`/internal/agent-serve/*`, `/v0/grokbot/*`, engine aliases).
+ * In production these are mounted on api.cursor.com and 404 on
+ * api2.cursor.sh, so the deploy surface needs its own default.
+ * `CURSOR_API_BASE_URL` still overrides everything for local dev, where
+ * one server mounts all routes.
  */
 export function cursorExternalApiUrl(): string {
   return trimTrailingSlash(
@@ -100,20 +106,13 @@ export function credentialsFilePath(): string {
   return join(configDirPath(), "credentials.json");
 }
 
-export async function readStoredCredentials(): Promise<
-  StoredCredentials | undefined
-> {
-  let raw: string;
-  try {
-    raw = await readFile(credentialsFilePath(), "utf8");
-  } catch {
-    return undefined;
-  }
+function parseStoredCredentialsJson(
+  raw: string
+): StoredCredentials | undefined {
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw) as unknown;
   } catch {
-    // Corrupt file — treat as signed out; login rewrites it.
     return undefined;
   }
   const credentials = storedCredentialsSchema.safeParse(parsed);
@@ -126,6 +125,28 @@ export async function readStoredCredentials(): Promise<
   };
 }
 
+export function readStoredCredentialsSync(): StoredCredentials | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(credentialsFilePath(), "utf8");
+  } catch {
+    return undefined;
+  }
+  return parseStoredCredentialsJson(raw);
+}
+
+export async function readStoredCredentials(): Promise<
+  StoredCredentials | undefined
+> {
+  let raw: string;
+  try {
+    raw = await readFile(credentialsFilePath(), "utf8");
+  } catch {
+    return undefined;
+  }
+  return parseStoredCredentialsJson(raw);
+}
+
 export async function writeStoredCredentials(
   credentials: StoredCredentials
 ): Promise<void> {
@@ -148,10 +169,10 @@ export async function clearStoredCredentials(): Promise<boolean> {
 }
 
 // ============================================================================
-// Resolution (option > env > stored login)
+// Resolution (option > env > file > stored login)
 // ============================================================================
 
-export type ApiKeySource = "option" | "env" | "login";
+export type ApiKeySource = "option" | "env" | "file" | "login";
 
 export interface ResolvedApiKey {
   apiKey: string;
@@ -160,15 +181,43 @@ export interface ResolvedApiKey {
 }
 
 /**
- * Resolve the account API key for `backendUrl` (defaults to the active
- * backend): explicit option → `CURSOR_API_KEY` → stored login. A stored key
- * minted against a different backend is ignored rather than sent to the
- * wrong host.
+ * Hosted task-bind path. Not a secret: the snapshot may name this path.
+ * The binder writes the key here after restore; July re-reads on each use.
+ * Override with `CURSOR_API_KEY_FILE`. A missing file is unsigned — self-hosted
+ * then uses `CURSOR_API_KEY` or stored login.
  */
-export async function resolveApiKey(options?: {
+export const DEFAULT_CURSOR_API_KEY_FILE: string =
+  "/run/cursor/secrets/CURSOR_API_KEY";
+
+/**
+ * Read `CURSOR_API_KEY_FILE` (or {@link DEFAULT_CURSOR_API_KEY_FILE} when
+ * unset). Missing/empty files are unsigned, not an error — freeze bake
+ * listens before the binder drops the key; self-hosted falls through to
+ * env or login.
+ */
+export function readApiKeyFromFile(filePath?: string): string | undefined {
+  const configured = filePath ?? process.env.CURSOR_API_KEY_FILE;
+  const path =
+    configured !== undefined && configured.trim() !== ""
+      ? configured.trim()
+      : DEFAULT_CURSOR_API_KEY_FILE;
+  try {
+    const raw = readFileSync(path, "utf8").trim();
+    return raw === "" ? undefined : raw;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * First present source wins. We define the order; operators do not.
+ * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`
+ * (hosted default path if unset) → stored `july login`.
+ */
+export function resolveApiKeySync(options?: {
   apiKey?: string;
   backendUrl?: string;
-}): Promise<ResolvedApiKey | undefined> {
+}): ResolvedApiKey | undefined {
   const backendUrl = options?.backendUrl ?? cursorBackendUrl();
   if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
     return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
@@ -177,15 +226,29 @@ export async function resolveApiKey(options?: {
   if (envKey !== undefined && envKey.trim() !== "") {
     return { apiKey: envKey.trim(), source: "env", backendUrl };
   }
-  const stored = await readStoredCredentials();
+  const fileKey = readApiKeyFromFile();
+  if (fileKey !== undefined) {
+    return { apiKey: fileKey, source: "file", backendUrl };
+  }
+  const stored = readStoredCredentialsSync();
   if (stored !== undefined && stored.backendUrl === backendUrl) {
     return { apiKey: stored.apiKey, source: "login", backendUrl };
   }
   return undefined;
 }
 
+/**
+ * {@link resolveApiKeySync} as a Promise for call sites that already await.
+ */
+export async function resolveApiKey(options?: {
+  apiKey?: string;
+  backendUrl?: string;
+}): Promise<ResolvedApiKey | undefined> {
+  return resolveApiKeySync(options);
+}
+
 /** One-line hint for "no credentials" errors, shared across surfaces. */
-export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / pass serve({ apiKey })).`;
+export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / pass serve({ apiKey })).`;
 
 // ============================================================================
 // PKCE browser login (mirrors cursor-agent / Sand)

package/src/internal/deploy-client.ts

@@ -1,6 +1,7 @@
 /**
  * Thin client for the Agent Serve deployment management API
- * (`/internal/agent-serve/deployments` on the Cursor backend). Pure
+ * (`/internal/agent-serve/deployments` on the Cursor backend) and the v2
+ * AgentSDK accept path (`/internal/agentkit/deployments`). Pure
  * request/response + error mapping — no console I/O, no polling loops;
  * rendering lives in `cli-deploy.ts`.
  *
@@ -212,6 +213,48 @@ export interface StopAccepted {
 
 export type DeleteAccepted = StopAccepted;
 
+/**
+ * `POST /internal/agentkit/deployments` 202 body. Distinct from v1
+ * {@link DeployAccepted}: the v2 control plane returns catalog ids, not
+ * an engine alias or one-shot alias token.
+ */
+export interface AgentkitDeployAccepted {
+  applicationId: string;
+  releaseId: string;
+  status: string;
+}
+
+/** Customer-visible v2 deploy status (`GET /internal/agentkit/deployments/:slug`). */
+export type AgentkitCustomerStatus =
+  | "pending"
+  | "deploying"
+  | "running"
+  | "failed"
+  | "stopped";
+
+export type AgentkitDeployProgress =
+  | "queued"
+  | "creating"
+  | "building"
+  | "starting"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopped";
+
+export interface AgentkitDeployStatus {
+  applicationId: string;
+  releaseId: string;
+  slug: string;
+  teamId: number;
+  status: AgentkitCustomerStatus;
+  progress: AgentkitDeployProgress;
+  statusMessage: string | null;
+}
+
+export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> =
+  new Set(["running", "failed", "stopped"]);
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -260,6 +303,35 @@ const deployAcceptedSchema = z
   })
   .passthrough();
 
+const agentkitDeployAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    status: z.string(),
+  })
+  .passthrough();
+
+const agentkitDeployStatusSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    slug: z.string().min(1),
+    teamId: z.number(),
+    status: z.enum(["pending", "deploying", "running", "failed", "stopped"]),
+    progress: z.enum([
+      "queued",
+      "creating",
+      "building",
+      "starting",
+      "finalizing",
+      "running",
+      "failed",
+      "stopped",
+    ]),
+    statusMessage: z.string().nullable(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -482,6 +554,54 @@ export class AgentServeDeployClient {
     return deployAcceptedSchema.parse(raw);
   }
 
+  /**
+   * Create or redeploy onto the v2 control plane
+   * (`POST /internal/agentkit/deployments`). 202 means accepted; poll
+   * {@link getAgentkitDeploy} until a terminal status.
+   */
+  async deployAgentkit(args: {
+    teamId: number;
+    slug: string;
+    gitRepoUrl: string;
+    gitRef?: string;
+    agentPath?: string;
+    repositories?: string[];
+  }): Promise<AgentkitDeployAccepted> {
+    const slugError = validateDeploymentSlug(args.slug);
+    if (slugError !== undefined) {
+      throw new DeployApiError(slugError, 400);
+    }
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agentkit/deployments",
+      body: {
+        teamId: args.teamId,
+        slug: args.slug,
+        gitRepoUrl: args.gitRepoUrl,
+        gitRef: args.gitRef,
+        agentPath: args.agentPath,
+        repositories:
+          args.repositories !== undefined && args.repositories.length > 0
+            ? args.repositories
+            : undefined,
+      },
+      context: { verb: "deploy", slug: args.slug },
+    });
+    return agentkitDeployAcceptedSchema.parse(raw);
+  }
+
+  async getAgentkitDeploy(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitDeployStatus> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentkit/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "get deployment", slug: args.slug },
+    });
+    return agentkitDeployStatusSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",
@@ -756,7 +876,7 @@ function mapErrorResponse(
       // (api2 vs api.cursor.com), not a missing deployment / closed gate.
       if (/Route \S+ not found/i.test(bodyText)) {
         return new DeployApiError(
-          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/* and /internal/agentkit/*.`,
           404
         );
       }

package/src/internal/discovery.ts

@@ -2021,7 +2021,7 @@ async function loadABConfig(
         severity: "error",
         path: displayPath(ctx, path),
         message:
-          "ab.config.ts must default-export defineABConfig({ ... }) from @anysphere/agent-serve/ab.",
+          "ab.config.ts must default-export defineABConfig({ ... }) from @cursor/july/ab.",
       });
       return undefined;
     }

package/src/internal/distribution.ts

@@ -81,6 +81,37 @@ export function packageVersion(): string {
   return typeof parsed.version === "string" ? parsed.version : "0.0.0";
 }
 
+/** Facts `agent-sdk version` / `--version` print. */
+export interface CliVersionInfo {
+  /** Published npm name (`@cursor/july`). */
+  name: string;
+  /** `package.json` version of this install. */
+  version: string;
+  /** Bin the process was invoked as (`agent-sdk` / `agent-serve`). */
+  cli: string;
+}
+
+export function cliVersionInfo(): CliVersionInfo {
+  return {
+    name: PACKAGE_NAME,
+    version: packageVersion(),
+    cli: CLI_COMMAND_NAME,
+  };
+}
+
+/**
+ * Text or JSON for `version` / `--version` / `-V`.
+ * Text is the bare `package.json` version (npm-style). `--json` is the
+ * complete `{ name, version, cli }` payload.
+ */
+export function formatCliVersion(options?: { json?: boolean }): string {
+  const info = cliVersionInfo();
+  if (options?.json === true) {
+    return `${JSON.stringify(info, null, 2)}\n`;
+  }
+  return `${info.version}\n`;
+}
+
 /**
  * Authoring entry subpaths and their dist-relative output files — the
  * runtime mirror of the package `exports` map (the source of truth;

package/src/internal/eval-runner.ts

@@ -479,7 +479,7 @@ function resolveEvalMaxConcurrency(config: Partial<EvalConfigFile>): number {
   if (config.maxConcurrency === undefined) {
     throw new Error(
       `evals/evals.config.ts must define maxConcurrency (1–${EVAL_MAX_CONCURRENCY_LIMIT}; hard limit is due to model provider request limits). Example:\n` +
-        `  import { defineEvalConfig } from "@anysphere/agent-serve/evals";\n` +
+        `  import { defineEvalConfig } from "@cursor/july/evals";\n` +
         `  export default defineEvalConfig({ maxConcurrency: 20 });`
     );
   }

package/src/internal/grokbot/runner.ts

@@ -13,15 +13,21 @@
 
 import { randomUUID } from "node:crypto";
 import type { RunnerTurnRequest, TurnOutcome } from "../../types.js";
-import { cursorBackendUrl } from "../cursor/credentials.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "../cursor/credentials.js";
 import type { AgentRunner } from "./../sdk-runner.js";
 
 export interface GrokBotRunnerOptions {
-  /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
+  /** Cursor API key. Resolved as option → env → file → stored login. */
   apiKey?: string;
   /** Test seam. Defaults to global fetch. */
   fetchImpl?: typeof fetch;
-  /** Test seam. Defaults to {@link cursorBackendUrl}. */
+  /**
+   * Test seam. Defaults to {@link cursorExternalApiUrl} (`api.cursor.com`).
+   * `/v0/grokbot` is an external-api microlith route — it 404s on api2.
+   */
   backendUrl?: string;
   /** Test seam. Poll interval while a turn runs. */
   pollIntervalMs?: number;
@@ -89,14 +95,17 @@ class GrokBotApiClient {
 
   constructor(options: GrokBotRunnerOptions) {
     this.fetchImpl = options.fetchImpl ?? fetch;
-    this.baseUrl = (options.backendUrl ?? cursorBackendUrl()).replace(
+    this.baseUrl = (options.backendUrl ?? cursorExternalApiUrl()).replace(
       /\/$/,
       ""
     );
-    const apiKey = options.apiKey ?? process.env.CURSOR_API_KEY;
+    const apiKey = resolveApiKeySync({
+      apiKey: options.apiKey,
+      backendUrl: options.backendUrl,
+    })?.apiKey;
     if (apiKey === undefined || apiKey === "") {
       throw new Error(
-        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY or agent-sdk login) to reach the hosted Grok Bot harness.'
+        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY, CURSOR_API_KEY_FILE, or agent-sdk login) to reach the hosted Grok Bot harness.'
       );
     }
     this.apiKey = apiKey;

package/src/internal/init-project.ts

@@ -6,6 +6,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import { runfiles } from "@bazel/runfiles";
 import type { ModelSetting } from "../types.js";
 import {
   canonicalTemplateName,
@@ -103,7 +104,7 @@ export function resolveTemplate(name: string): TemplateResolution {
     };
   }
   const entry = TEMPLATES[resolved];
-  const dir = join(packageRootDir(), "templates", entry.dir);
+  const dir = resolvePackagePath("templates", entry.dir);
   return {
     ok: true,
     name: resolved,
@@ -115,6 +116,15 @@ export function resolveTemplate(name: string): TemplateResolution {
   };
 }
 
+function resolvePackagePath(...segments: string[]): string {
+  if (runfiles.workspace !== undefined) {
+    return runfiles.resolveWorkspaceRelative(
+      ["packages", "agent-serve", ...segments].join("/")
+    );
+  }
+  return join(packageRootDir(), ...segments);
+}
+
 export type InitTargetCheck = { ok: true } | { ok: false; message: string };
 
 /**

package/src/internal/mcp-endpoint.ts

@@ -318,8 +318,9 @@ function buildConnectionBridgeMcpServer(
     }
     // The one tool path that never reaches `executeServerTool`, so it asks
     // the policy itself.
-    const answer = engine.bridgedCallAnswer({
+    const answer = await engine.bridgedCallAnswer({
       sessionId: sessionId ?? "",
+      connectionName,
       toolName: request.params.name,
     });
     if (answer.answered) {

package/src/internal/sdk-runner.ts

@@ -29,6 +29,7 @@ import {
   type TurnUsage,
 } from "../types.js";
 import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
 
 /** Internal seam between the session engine and the Cursor SDK harness. */
 export interface AgentRunner {
@@ -427,14 +428,19 @@ export class CursorSdkRunner implements AgentRunner {
     (this.options.logger ?? (() => {}))(line);
   }
 
+  /**
+   * Re-resolve on every turn. Hosted freeze snapshots listen unsigned; the
+   * binder drops `CURSOR_API_KEY` / `CURSOR_API_KEY_FILE` at task time into
+   * the already-running process, which must not have closed over `undefined`.
+   */
   private requireApiKey(): string {
-    const apiKey = this.options.apiKey ?? process.env.CURSOR_API_KEY;
-    if (apiKey === undefined || apiKey.trim() === "") {
+    const resolved = resolveApiKeySync({ apiKey: this.options.apiKey });
+    if (resolved === undefined) {
       throw new Error(
-        "The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY, or pass serve({ apiKey })."
+        "The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY or CURSOR_API_KEY_FILE, or pass serve({ apiKey })."
       );
     }
-    return apiKey;
+    return resolved.apiKey;
   }
 
   private buildSharedOptions(