@cursor/july 0.1.89 → 0.1.90

package/src/connections.ts

@@ -8,7 +8,7 @@
  * `hostOnly: true` to keep it off the model (still on `host.mcp`).
  *
  * ```ts
- * import { defineConnection } from "@anysphere/agent-serve/connections";
+ * import { defineConnection } from "@cursor/july/connections";
  *
  * export default defineConnection({
  *   url: "https://mcp.linear.app/mcp",

package/src/evals.ts

@@ -7,7 +7,7 @@
  * `t.messageIncludes(...)`, or `t.check(value, includes(...))`.
  *
  * ```ts
- * import { defineEval, includes } from "@anysphere/agent-serve/evals";
+ * import { defineEval, includes } from "@cursor/july/evals";
  *
  * // One datapoint — id is the file path (evals/weather/nyc.eval.ts → weather/nyc)
  * export default defineEval({

package/src/hooks.ts

@@ -6,7 +6,7 @@
  * transcripts to your own database). Handlers are observe-only.
  *
  * ```ts
- * import { defineHook } from "@anysphere/agent-serve/hooks";
+ * import { defineHook } from "@cursor/july/hooks";
  *
  * export default defineHook({
  *   events: {

package/src/index.ts

@@ -1,12 +1,12 @@
 /**
- * @anysphere/agent-serve
+ * @cursor/july
  *
  * Filesystem-first framework for Cursor agents: define an agent as markdown
  * and TypeScript files under an `agent/` directory, and serve it over
  * channels with the Cursor SDK as the execution harness.
  *
  * ```ts
- * import { serve } from "@anysphere/agent-serve";
+ * import { serve } from "@cursor/july";
  *
  * const handle = await serve(".", { port: 3000 });
  * console.log(`agent listening on ${handle.url}`);

package/src/internal/cli-convert-automation.ts

@@ -1,6 +1,6 @@
 /**
  * `agent-serve convert-automation <url>` — export a Cursor Automation into
- * an agentkit project.
+ * an agentsdk project.
  *
  * Fetches the automation's workflow from the backend export endpoint
  * (Bearer user API key, same credential chain as deploy), runs the pure

package/src/internal/cli-cursor.ts

@@ -148,10 +148,12 @@ export async function cmdLogin(options: CursorCliOptions): Promise<number> {
 /**
  * Gate for commands that need a Cursor credential before they can do useful
  * work (`serve`, `dev`, interactive `init`). Already-signed-in hosts
- * (`--api-key` / `CURSOR_API_KEY` / stored login) return immediately.
- * Otherwise an interactive host runs {@link cmdLogin}; a non-interactive
- * one (CI, Docker) fails fast with {@link SIGN_IN_HINT} instead of polling
- * a browser that will never open.
+ * (`--api-key` / `CURSOR_API_KEY` / `CURSOR_API_KEY_FILE` / stored login) return immediately.
+ * Hosted `--allow-anonymous` (v1 alias-token engines and v2 freeze bake)
+ * skips this gate so health/manifest can bind without a Cursor key.
+ * Self-hosted omit the flag: an interactive host runs {@link cmdLogin};
+ * a non-interactive one (CI, Docker) fails fast with {@link SIGN_IN_HINT}
+ * instead of polling a browser that will never open.
  */
 export async function ensureCursorLogin(
   options: {
@@ -161,6 +163,12 @@ export async function ensureCursorLogin(
      * TTY.
      */
     interactive?: boolean;
+    /**
+     * `serve --allow-anonymous`: listen without a Cursor credential.
+     * Model turns still fail later if a key is required; freeze only
+     * needs `/v1/health` and `/v1/manifest`.
+     */
+    allowAnonymous?: boolean;
     /** Test seam. */
     login?: (options: CursorCliOptions) => Promise<number>;
   } = {}
@@ -169,6 +177,9 @@ export async function ensureCursorLogin(
   if (resolved !== undefined) {
     return 0;
   }
+  if (options.allowAnonymous === true) {
+    return 0;
+  }
   const interactive = options.interactive ?? process.stderr.isTTY === true;
   if (!interactive) {
     process.stderr.write(`Not signed in to Cursor. ${SIGN_IN_HINT}\n`);
@@ -243,12 +254,14 @@ function formatIdentity(identity: CursorIdentity): string {
   return name === "" ? `${email}${team}` : `${name} <${email}>${team}`;
 }
 
-function describeSource(source: "option" | "env" | "login"): string {
+function describeSource(source: "option" | "env" | "file" | "login"): string {
   switch (source) {
     case "option":
       return "explicit --api-key / serve({ apiKey })";
     case "env":
       return "CURSOR_API_KEY environment variable";
+    case "file":
+      return "CURSOR_API_KEY_FILE (task bind)";
     case "login":
       return `stored login (${credentialsFilePath()})`;
   }

package/src/internal/convert-automation/convert-workflow.ts

@@ -1,5 +1,5 @@
 /**
- * Pure Workflow → agentkit project converter.
+ * Pure Workflow → agentsdk project converter.
  *
  * Maps an exported Cursor automation (proto3 workflow JSON + enriched MCP
  * server list) to project files, warnings, and setup steps. No I/O, no
@@ -185,7 +185,7 @@ function renderInstructions(
 }
 
 /**
- * Strip Cursor-backend prompt markup that means nothing in agentkit:
+ * Strip Cursor-backend prompt markup that means nothing in agentsdk:
  * `@[label](action:...)` action tokens become their label text, and
  * unresolvable `%%INLINECODE<n>%%` storage placeholders are flagged (their
  * content is not in the export).
@@ -972,7 +972,7 @@ function emitSlackChannel(
         ? "channel-created"
         : "reaction-added";
     out.warnings.push(
-      `Slack ${kind} trigger has no agentkit equivalent — its config is inlined as a comment in ${path}; handle the Slack event yourself on a dedicated Socket Mode app.`
+      `Slack ${kind} trigger has no agentsdk equivalent — its config is inlined as a comment in ${path}; handle the Slack event yourself on a dedicated Socket Mode app.`
     );
   }
   let reactionDropped = false;
@@ -995,7 +995,7 @@ function emitSlackChannel(
   }
   if (reactionDropped) {
     out.warnings.push(
-      "The Slack trigger marked triggering messages with a completion reaction; agentkit has no completion-reaction option, so that signal is lost unless agent/instructions.md tells the agent to add the reaction itself via Slack tools."
+      "The Slack trigger marked triggering messages with a completion reaction; agentsdk has no completion-reaction option, so that signal is lost unless agent/instructions.md tells the agent to add the reaction itself via Slack tools."
     );
   }
   if (socketMode) {
@@ -1042,8 +1042,8 @@ function emitSlackChannel(
     if (blocksUnauthenticated) {
       out.warnings.push(
         includeBotPosts
-          ? "Some Slack watches only fired for authenticated Cursor users while others allowed anyone; agentkit has one bot-post setting per channel, so the export keeps bot posts ENABLED (the open watches depend on them) and the authenticated-only watches lose both their sender gate and their bot exclusion. Split the channels or add an onChannelPost gate."
-          : "The Slack trigger only fired for authenticated Cursor users (linked accounts on the owning team); agentkit has no equivalent sender gate, so the exported watch dispatches for ANY channel member (bot posts stay excluded). Add an onChannelPost gate in the channel if that matters."
+          ? "Some Slack watches only fired for authenticated Cursor users while others allowed anyone; agentsdk has one bot-post setting per channel, so the export keeps bot posts ENABLED (the open watches depend on them) and the authenticated-only watches lose both their sender gate and their bot exclusion. Split the channels or add an onChannelPost gate."
+          : "The Slack trigger only fired for authenticated Cursor users (linked accounts on the owning team); agentsdk has no equivalent sender gate, so the exported watch dispatches for ANY channel member (bot posts stay excluded). Add an onChannelPost gate in the channel if that matters."
       );
     }
     const engagement: string[] = [];
@@ -1309,9 +1309,9 @@ const ACTION_STEPS: Partial<Record<keyof ActionJson, string>> = {
   resolveReviewThreads:
     "Verify: resolve_review_threads — no built-in equivalent; resolve threads via the GitHub GraphQL API in a hook or tool.",
   microsoftTeams:
-    "Verify: microsoft_teams post — agentkit has no Teams channel; wire the Microsoft Teams API yourself.",
+    "Verify: microsoft_teams post — agentsdk has no Teams channel; wire the Microsoft Teams API yourself.",
   readMicrosoftTeams:
-    "Verify: read_microsoft_teams — agentkit has no Teams tools; wire the Microsoft Teams API yourself.",
+    "Verify: read_microsoft_teams — agentsdk has no Teams tools; wire the Microsoft Teams API yourself.",
 };
 
 interface SlackIntegrationState {
@@ -1375,7 +1375,7 @@ function behaviorSteps(
   const disabled = workflow.disabledDefaultTools ?? [];
   if (disabled.length > 0) {
     steps.push(
-      `Verify: disabled_default_tools (${disabled.join(", ")}) — agentkit has no default automation tools; enforce the equivalent restriction in agent/instructions.md.`
+      `Verify: disabled_default_tools (${disabled.join(", ")}) — agentsdk has no default automation tools; enforce the equivalent restriction in agent/instructions.md.`
     );
   }
   return steps;

package/src/internal/convert-automation/types.ts

@@ -1,5 +1,5 @@
 /**
- * Types for `convertWorkflow` — the pure automation → agentkit project
+ * Types for `convertWorkflow` — the pure automation → agentsdk project
  * converter behind `agent-serve convert-automation`.
  *
  * The workflow arrives as generic proto3 JSON (lowerCamelCase field names,

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

@@ -296,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;
@@ -303,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", {}));
@@ -443,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),
@@ -525,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
@@ -541,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),
@@ -576,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;
   }

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/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/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(