@cursor/july 0.1.89 → 0.1.90

package/src/internal/server.ts

@@ -64,9 +64,11 @@ import {
 } from "./cursor/account-mcp.js";
 import { CursorBackendClient } from "./cursor/backend-client.js";
 import {
+  cursorBackendUrl,
   cursorExternalApiUrl,
   type ResolvedApiKey,
   resolveApiKey,
+  resolveApiKeySync,
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
 import { CursorGithubCredentialProvider } from "./cursor/github-credentials.js";
@@ -281,9 +283,9 @@ export async function startServer(
   const runSchedules = options.schedules ?? !dev;
   const runReminders = options.reminders ?? !dev;
 
-  // Identify this process to the Cursor backend as agentkit (the SDK reads
-  // this when building its client-version header) so the internal-only
-  // agentkit_enabled gate applies to every turn.
+  // CURSOR_AGENTKIT_VERSION is still the env the SDK reads when building
+  // its client-version header (wire prefix remains `agentkit-`). Setting it
+  // here makes the internal-only agentkit_enabled gate apply to every turn.
   process.env.CURSOR_AGENTKIT_VERSION ??= packageVersion();
 
   const authoredOtel = pickAuthoredOtel(
@@ -328,10 +330,18 @@ export async function startServer(
 
   // One resolution for every Cursor credential consumer (SDK runner, account
   // MCP bridge, SCM event relay, GitHub credentials): explicit option →
-  // CURSOR_API_KEY → stored `agent-serve login`.
+  // CURSOR_API_KEY → CURSOR_API_KEY_FILE (or the hosted default path) →
+  // stored `agent-serve login`. SDK / GitHub / account MCP re-read later;
+  // Slack and deployment-event relays capture the key at start.
   const accountKey = await resolveApiKey(
     options.apiKey === undefined ? {} : { apiKey: options.apiKey }
   );
+  // First present source wins (we define the order): option → env → file →
+  // stored login. Re-read so bind can drop env or file onto a listening process.
+  const liveCursorApiKey = (): string | undefined =>
+    resolveApiKeySync(
+      options.apiKey === undefined ? {} : { apiKey: options.apiKey }
+    )?.apiKey;
 
   // The SCM relay reads the event stream as the signed-in user, so
   // `cursorEvents` cannot work signed out. Require the credential before any
@@ -365,15 +375,15 @@ export async function startServer(
     const needsGithubAuth =
       cursorGithubConfig.scope !== undefined || githubProxyRequested;
     if (needsGithubAuth) {
-      const cursorGithubAuth =
-        cursorEventsAuth ??
-        (accountKey?.apiKey !== undefined && accountKey.apiKey.trim() !== ""
-          ? {
-              apiKey: accountKey.apiKey.trim(),
-              baseUrl: cursorExternalApiUrl(),
-            }
-          : undefined);
-      if (cursorGithubAuth === undefined) {
+      const currentGithubApiKey = (): string | undefined => {
+        const fromEvents = cursorEventsAuth?.apiKey.trim();
+        if (fromEvents !== undefined && fromEvents !== "") {
+          return fromEvents;
+        }
+        return liveCursorApiKey();
+      };
+      const githubApiKeyNow = currentGithubApiKey();
+      if (githubApiKeyNow === undefined && options.allowAnonymous !== true) {
         throw new Error(
           "githubChannel({ cursorAccount: true }) could not resolve Cursor event authentication."
         );
@@ -387,20 +397,39 @@ export async function startServer(
         logger(
           "[agent-sdk] warning: --allow-anonymous-cursor-github — every admitted HTTP caller can drive sessions holding the signed-in account's repo-scoped GitHub credential; serve this only behind a trusted boundary (e.g. an SSO proxy)"
         );
+        if (githubApiKeyNow === undefined) {
+          logger(
+            "[agent-sdk] GitHub auth: listening unsigned; credentials bind at task via CURSOR_API_KEY or CURSOR_API_KEY_FILE"
+          );
+        }
       }
       if (cursorGithubConfig.permissions === "contents-write") {
         logger(
           '[agent-sdk] warning: Cursor GitHub credentials include contents:write — the host holds a push-capable token shared with model-driven tools and untrusted webhook content; prefer permissions: "pr-write" unless this agent must push code'
         );
       }
+      const githubAuthBaseUrl = cursorExternalApiUrl();
+      const requireGithubApiKey = async (): Promise<string> => {
+        const apiKey = currentGithubApiKey();
+        if (apiKey === undefined) {
+          throw new Error(
+            `githubChannel({ cursorAccount: true }) has no Cursor credential yet. ${SIGN_IN_HINT}`
+          );
+        }
+        return apiKey;
+      };
       const githubProxyUrl = githubProxyRequested
-        ? resolveCursorGithubProxyUrl(cursorGithubAuth.baseUrl)
+        ? resolveCursorGithubProxyUrl(githubAuthBaseUrl)
         : undefined;
-      if (cursorGithubConfig.scope !== undefined) {
+      if (
+        cursorGithubConfig.scope !== undefined &&
+        githubApiKeyNow !== undefined
+      ) {
         const provider = new CursorGithubCredentialProvider({
           client: new CursorBackendClient({
-            backendUrl: cursorGithubAuth.baseUrl,
-            apiKey: cursorGithubAuth.apiKey,
+            backendUrl: githubAuthBaseUrl,
+            apiKey: githubApiKeyNow,
+            getApiKey: () => currentGithubApiKey() ?? "",
             logger,
           }),
           scope: cursorGithubConfig.scope,
@@ -420,9 +449,7 @@ export async function startServer(
             },
           };
           for (const target of cursorGithubTargets) {
-            target.accountRuntime.credentials.bind(
-              async () => cursorGithubAuth.apiKey
-            );
+            target.accountRuntime.credentials.bind(requireGithubApiKey);
             target.accountRuntime.credentials.bindProxyTransport(
               proxyTransport
             );
@@ -438,8 +465,8 @@ export async function startServer(
       } else if (githubProxyUrl !== undefined) {
         // `cursorAccount: true` with no `--repo`: skip the startup token mint
         // (it requires a repo list) and let github-proxy take the repo from
-        // each Octokit call. Hosted multi-tenant uses this with the
-        // deployment event stream.
+        // each Octokit call. Hosted freeze bakes this flag into the template
+        // so restore is GitHub-ready once Bind drops the key.
         const proxyTransport = {
           apiBaseUrl: githubProxyUrl,
           headers: {
@@ -447,16 +474,14 @@ export async function startServer(
           },
         };
         for (const target of cursorGithubTargets) {
-          target.accountRuntime.credentials.bind(
-            async () => cursorGithubAuth.apiKey
-          );
+          target.accountRuntime.credentials.bind(requireGithubApiKey);
           target.accountRuntime.credentials.bindProxyTransport(proxyTransport);
         }
         // `ctx.host.github` gets the same proxy transport; without this it
         // would fall back to ambient auth (env token / `gh`) or an
         // unauthenticated Octokit, and every host GitHub call would 404.
         hostGithubProxyResolver = createCursorGithubProxyHostResolver({
-          getApiKey: async () => cursorGithubAuth.apiKey,
+          getApiKey: requireGithubApiKey,
           transport: proxyTransport,
         });
         logger(
@@ -496,7 +521,12 @@ export async function startServer(
   }
   const sdkRunner =
     options.runner ??
-    new CursorSdkRunner({ apiKey: accountKey?.apiKey, logger });
+    new CursorSdkRunner({
+      ...(options.apiKey === undefined || options.apiKey.trim() === ""
+        ? {}
+        : { apiKey: options.apiKey }),
+      logger,
+    });
   // Grok Bot turns run on Cursor's hosted Grok Bot (Sand) harness through
   // the /v0/grokbot session API; the SDK side is a thin remote client. The
   // dispatching runner is only interposed when a mount needs it. An
@@ -521,7 +551,16 @@ export async function startServer(
   if (hasGrokBotMounts && options.runner === undefined) {
     runner = new RuntimeDispatchingRunner({
       sdkRunner,
-      grokbot: { apiKey: accountKey?.apiKey },
+      grokbot: {
+        ...(options.apiKey === undefined || options.apiKey.trim() === ""
+          ? {}
+          : { apiKey: options.apiKey }),
+        // `/v0/grokbot` lives on the external API (api.cursor.com), not
+        // api2. Prefer that default over the account key's backendUrl.
+        // Do not pass stored login as apiKey: that would pin it as an
+        // option and beat a later CURSOR_API_KEY_FILE bind.
+        backendUrl: cursorExternalApiUrl(),
+      },
     });
     logger(
       "[agent-sdk] grokbot runtime: remote client (turns run on the hosted Grok Bot harness)"
@@ -559,15 +598,21 @@ export async function startServer(
   }
   let accountBridge: CursorAccountMcpBridge | undefined;
   if (accountRefsBySlug.size > 0) {
-    if (accountKey === undefined) {
+    if (accountKey === undefined && options.allowAnonymous !== true) {
       throw new Error(
         `This project has Cursor account MCP connections (defineConnection({ cursorAccount: true })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
       );
     }
+    if (accountKey === undefined) {
+      logger(
+        "[agent-sdk] Cursor account MCP: listening unsigned; credentials bind at task via CURSOR_API_KEY or CURSOR_API_KEY_FILE"
+      );
+    }
     accountBridge = new CursorAccountMcpBridge({
       client: new CursorBackendClient({
-        backendUrl: accountKey.backendUrl,
-        apiKey: accountKey.apiKey,
+        backendUrl: accountKey?.backendUrl ?? cursorBackendUrl(),
+        apiKey: accountKey?.apiKey ?? "",
+        getApiKey: () => liveCursorApiKey() ?? "",
         logger,
       }),
       logger,
@@ -1035,8 +1080,13 @@ export async function startServer(
               ? undefined
               : { authorization: `Bearer ${options.authToken}` };
         if (options.cloudToolsUrl !== undefined && headers === undefined) {
-          throw new Error(
-            `Agent "${runtime.project.name}" needs a Cursor API key to authenticate --cloud-tools-url. ${SIGN_IN_HINT}`
+          if (options.allowAnonymous !== true) {
+            throw new Error(
+              `Agent "${runtime.project.name}" needs a Cursor API key to authenticate --cloud-tools-url. ${SIGN_IN_HINT}`
+            );
+          }
+          logger(
+            `[agent-sdk] --cloud-tools-url: listening unsigned; Bearer is taken from the key present at start`
           );
         }
         runtime.engine.setCloudServerToolsConnection({
@@ -2509,6 +2559,12 @@ function startCursorDeploymentRelay(input: {
     return undefined;
   }
   if (accountKey === undefined) {
+    if (input.options.allowAnonymous === true) {
+      logger(
+        "[agent-sdk] deployment-events: skipped while unsigned; long-poll relays need a key at start"
+      );
+      return undefined;
+    }
     throw new Error(
       `This project has channels subscribed to deployment events (deploymentsChannel({ deploySourceUris })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
     );
@@ -2591,6 +2647,12 @@ async function startCursorSlackRelay(input: {
     return undefined;
   }
   if (accountKey === undefined) {
+    if (options.allowAnonymous === true) {
+      logger(
+        "[agent-sdk] cursor-slack: skipped while unsigned; long-poll relays need a key at start"
+      );
+      return undefined;
+    }
     throw new Error(
       `This project has Slack channels using the Cursor account connection (slackChannel({ cursorAccount: true })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
     );

package/src/reminders.ts

@@ -2,7 +2,7 @@
  * Runtime reminders — per-session durable wakes.
  *
  * ```ts
- * import type { ReminderCreateInput } from "@anysphere/agent-serve/reminders";
+ * import type { ReminderCreateInput } from "@cursor/july/reminders";
  *
  * // Recurring ≈ setInterval; one-shot ≈ setTimeout.
  * await host.reminders?.create({

package/src/schedules.ts

@@ -6,7 +6,7 @@
  * handler form hands work off to a channel (and can call MCP via `args.host.mcp`):
  *
  * ```ts
- * import { defineSchedule } from "@anysphere/agent-serve/schedules";
+ * import { defineSchedule } from "@cursor/july/schedules";
  *
  * export default defineSchedule({
  *   cron: "0 9 * * 1-5",

package/src/skills.ts

@@ -7,7 +7,7 @@
  * content or inline sibling files:
  *
  * ```ts
- * import { defineSkill } from "@anysphere/agent-serve/skills";
+ * import { defineSkill } from "@cursor/july/skills";
  *
  * export default defineSkill({
  *   description: "Research unfamiliar topics before answering.",

package/src/storage.ts

@@ -16,7 +16,7 @@
  * not as required-or-lose-history hooks:
  *
  * ```ts
- * import { defineStorage } from "@anysphere/agent-serve/storage";
+ * import { defineStorage } from "@cursor/july/storage";
  *
  * export default defineStorage({
  *   put: (key, value) => db.upsert(key, value),

package/src/tools.ts

@@ -5,7 +5,7 @@
  * name the model sees. Export the definition as the module's default export:
  *
  * ```ts
- * import { defineTool } from "@anysphere/agent-serve/tools";
+ * import { defineTool } from "@cursor/july/tools";
  * import { z } from "zod";
  *
  * // Runs in-process on the agent-serve host (default). Authored MCP

package/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * Public types for @anysphere/agent-serve.
+ * Public types for @cursor/july.
  *
  * The framework is filesystem-first: customers author an agent as files under
  * an `agent/` directory (markdown for prose, TypeScript for typed behavior),
@@ -2690,7 +2690,7 @@ export interface DiscoveredHook {
 /** Live A/B metrics experiment (`agent/ab.ts` or `agent/ab/<name>.ts`). */
 export interface DiscoveredAB {
   name: string;
-  /** Branded `defineAB({ ... })` config (see `@anysphere/agent-serve/ab`). */
+  /** Branded `defineAB({ ... })` config (see `@cursor/july/ab`). */
   definition: BrandedDefinition<"ab">;
 }