@cursor/july 0.1.102 → 0.1.104

package/src/internal/cursor/bound-secret-file.ts

@@ -0,0 +1,108 @@
+/**
+ * Destroying a hosted v2 task-bind secret file after its value is in
+ * `process.env`.
+ *
+ * The bind files under `/run/cursor/secrets/` are an IPC channel, not a
+ * credential store: the control plane cannot set another process's
+ * environment, so it drops the value on tmpfs and July copies it into
+ * `process.env` before anything authored runs. Once that copy succeeds the
+ * on-disk value is pure liability — authored agent code runs in this pod and
+ * can read any world-readable path.
+ *
+ * Unlink is preferred. It is not always available: pod-daemon writes the
+ * files as root, and removing a directory entry needs write permission on
+ * `/run/cursor/secrets`, which is root-owned. Making that directory writable
+ * by the guest is not the fix — untrusted guest code could then plant a
+ * symlink that the next root-side bind write would follow. The binder instead
+ * relaxes the two secret files themselves so the guest can truncate them, and
+ * this module falls back to a zero-length overwrite. Both readers treat an
+ * empty bind file as unsigned.
+ */
+
+import {
+  closeSync,
+  fsyncSync,
+  ftruncateSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+} from "node:fs";
+
+/**
+ * What happened to a bind file. Only `readable` is a failure: the secret
+ * survived the consume and callers must not run authored code.
+ */
+export type BoundSecretFileDisposal =
+  /** Nothing recoverable was there — missing, empty, or unreadable already. */
+  | { state: "absent" }
+  /** Directory entry removed. */
+  | { state: "unlinked" }
+  /** Truncated to zero length and fsynced; an empty file remains. */
+  | { state: "wiped" }
+  /** Still recoverable by a later `readFile`. */
+  | { state: "readable"; reason: string };
+
+/**
+ * Whether a later `readFile` of this path could still recover a secret.
+ * A read failure counts as unrecoverable: this process just read the file
+ * during hydrate, so losing access to it means the content is gone.
+ */
+export function boundSecretFileIsReadable(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
+function errorReason(error: unknown): string {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return typeof code === "string" ? code : "unknown";
+}
+
+/**
+ * Remove a bind file's contents from disk, preferring unlink over an empty
+ * leftover. Callers must have already copied the value into `process.env`:
+ * this is destructive and there is no second bind until the control plane
+ * rewrites the file before the next hosted request.
+ */
+export function destroyBoundSecretFile(path: string): BoundSecretFileDisposal {
+  if (!boundSecretFileIsReadable(path)) {
+    // Nothing recoverable, so nothing to fail over. Still try to clear the
+    // empty leftover: whether that succeeds does not change the disposal,
+    // because there is no secret here either way.
+    try {
+      unlinkSync(path);
+    } catch {
+      // Already gone, or a directory the guest cannot write. Both are fine.
+    }
+    return { state: "absent" };
+  }
+  let unlinkReason: string | undefined;
+  try {
+    unlinkSync(path);
+    if (!boundSecretFileIsReadable(path)) {
+      return { state: "unlinked" };
+    }
+    unlinkReason = "recreated";
+  } catch (error) {
+    unlinkReason = errorReason(error);
+  }
+  try {
+    const fd = openSync(path, "r+");
+    try {
+      ftruncateSync(fd, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (error) {
+    return {
+      state: "readable",
+      reason: `unlink ${unlinkReason}, truncate ${errorReason(error)}`,
+    };
+  }
+  return boundSecretFileIsReadable(path)
+    ? { state: "readable", reason: `unlink ${unlinkReason}, truncate no-op` }
+    : { state: "wiped" };
+}

package/src/internal/cursor/credentials.ts

@@ -4,13 +4,16 @@
  * Exactly one kind of secret exists at runtime: a **personal Cursor user API
  * key**. Two ways to obtain it, one code path after that:
  *
- * - `agent-serve login` runs the same PKCE browser flow as `cursor-agent`
+ * - `agent-sdk login` runs the same PKCE browser flow as `cursor-agent`
  *   and Sand, then uses the short-lived session once to mint a named,
  *   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.
+ *   drops the key at task time without restarting July. On the hosted path
+ *   that file is consumed into `CURSOR_API_KEY` and destroyed before
+ *   anything authored runs, so this fallback is there for local,
+ *   self-hosted, and the unsigned window before the first bind.
  * - Stored `july login` is last. Same order for hosted and self-hosted:
  *   option → env → file → login.
  *
@@ -26,6 +29,10 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { CLI_COMMAND_NAME } from "../distribution.js";
+import {
+  type BoundSecretFileDisposal,
+  destroyBoundSecretFile,
+} from "./bound-secret-file.js";
 
 export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
 export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
@@ -182,9 +189,11 @@ export interface ResolvedApiKey {
 
 /**
  * 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.
+ * The binder writes the key here after restore, and hosted admission /
+ * execution consume it into `process.env.CURSOR_API_KEY` and destroy the
+ * file before authored work — this is an IPC handoff, not a credential
+ * source July keeps reading. Override with `CURSOR_API_KEY_FILE`. A missing
+ * file is unsigned — self-hosted then uses `CURSOR_API_KEY` or stored login.
  */
 export const DEFAULT_CURSOR_API_KEY_FILE: string =
   "/run/cursor/secrets/CURSOR_API_KEY";
@@ -195,12 +204,18 @@ export const DEFAULT_CURSOR_API_KEY_FILE: string =
  * listens before the binder drops the key; self-hosted falls through to
  * env or login.
  */
+export function resolveCursorApiKeyFilePath(
+  filePath?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const configured = filePath ?? env.CURSOR_API_KEY_FILE;
+  return configured !== undefined && configured.trim() !== ""
+    ? configured.trim()
+    : DEFAULT_CURSOR_API_KEY_FILE;
+}
+
 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;
+  const path = resolveCursorApiKeyFilePath(filePath);
   try {
     const raw = readFileSync(path, "utf8").trim();
     return raw === "" ? undefined : raw;
@@ -209,6 +224,56 @@ export function readApiKeyFromFile(filePath?: string): string | undefined {
   }
 }
 
+export type BoundCursorApiKeyConsumeResult = {
+  /** The file supplied `CURSOR_API_KEY` on this call. */
+  applied: boolean;
+  disposal: BoundSecretFileDisposal;
+};
+
+/**
+ * Copy the task-bind key file into `process.env.CURSOR_API_KEY`, then destroy
+ * the file.
+ *
+ * Hosted v2 cannot set another process's environment from the binder, so it
+ * drops a tmpfs file. Teaching every reader to open that file misses authored
+ * `process.env.CURSOR_API_KEY` and leaves a secret on disk. Hosted admission /
+ * execution call this once per request, next to the deployment-secrets
+ * consume: after it returns, env-only readers work and the key is no longer
+ * recoverable from disk. The control plane re-binds before the next request.
+ *
+ * The env write always happens before the destroy, never the other way round.
+ * An already-set `CURSOR_API_KEY` is not overwritten, but the file is still
+ * destroyed — env is the source, the file is only the handoff.
+ *
+ * A `readable` disposal means the secret survived; callers on the hosted path
+ * must fail the request rather than run authored code.
+ */
+export function consumeBoundCursorApiKey(options?: {
+  filePath?: string;
+  env?: NodeJS.ProcessEnv;
+}): BoundCursorApiKeyConsumeResult {
+  const env = options?.env ?? process.env;
+  const path = resolveCursorApiKeyFilePath(options?.filePath, env);
+  const envKeyAlreadySet =
+    env.CURSOR_API_KEY !== undefined && env.CURSOR_API_KEY.trim() !== "";
+  let raw = "";
+  try {
+    raw = readFileSync(path, "utf8").trim();
+  } catch {
+    return { applied: false, disposal: { state: "absent" } };
+  }
+  if (raw === "") {
+    return { applied: false, disposal: destroyBoundSecretFile(path) };
+  }
+  if (!envKeyAlreadySet) {
+    env.CURSOR_API_KEY = raw;
+  }
+  return {
+    applied: !envKeyAlreadySet,
+    disposal: destroyBoundSecretFile(path),
+  };
+}
+
 /**
  * First present source wins. We define the order; operators do not.
  * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`

package/src/internal/cursor/hosted-bound-secrets.ts

@@ -0,0 +1,75 @@
+/**
+ * The hosted v2 per-request secret handoff: bind files in, `process.env` out,
+ * nothing recoverable left on disk.
+ *
+ * The control plane rewrites `/run/cursor/secrets/` before every hosted
+ * admission and execution because it cannot set the already-running July
+ * process's environment. This module closes that handoff at the top of each
+ * request: copy both documents into `process.env`, then destroy them. Hosted
+ * request code and authored agents read env from there on — nothing on the
+ * hosted path should open these paths again.
+ *
+ * It fails closed. A secret that survives the consume would sit world-readable
+ * next to authored agent code for the length of a turn, so the caller returns
+ * a retryable error instead of dispatching. The next request re-binds and
+ * consumes again.
+ */
+
+import {
+  consumeBoundCursorApiKey,
+  DEFAULT_CURSOR_API_KEY_FILE,
+} from "./credentials.js";
+import {
+  consumeBoundDeploymentSecrets,
+  DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE,
+} from "./hosted-deployment-secrets.js";
+
+/** Wire error code for a bind file that outlived its consume. */
+export const BOUND_SECRETS_NOT_CONSUMED = "bound_secrets_not_consumed";
+
+export type HostedBoundSecretsResult =
+  | { ok: true }
+  | { ok: false; code: typeof BOUND_SECRETS_NOT_CONSUMED; message: string };
+
+/**
+ * Hydrate `process.env` from both bind files and remove them from disk.
+ * Returns a failure when either secret is still readable afterwards.
+ *
+ * Both paths are platform constants, deliberately not the `CURSOR_API_KEY_FILE`
+ * override that {@link resolveApiKeySync} honors. That override is a read
+ * chain; this is a destructive consume. Following it here would let authored
+ * code redirect the destroy at a decoy path — reporting success while the real
+ * bind file stays live — and would delete an operator's own long-lived key
+ * file on a surface that points the variable at one.
+ */
+export function consumeHostedBoundSecrets(options?: {
+  apiKeyFilePath?: string;
+  deploymentSecretsFilePath?: string;
+}): HostedBoundSecretsResult {
+  const survivors: string[] = [];
+
+  const secretsPath =
+    options?.deploymentSecretsFilePath ??
+    DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE;
+  const secrets = consumeBoundDeploymentSecrets(secretsPath);
+  if (secrets.disposal.state === "readable") {
+    survivors.push(`${secretsPath} (${secrets.disposal.reason})`);
+  }
+
+  const apiKeyPath = options?.apiKeyFilePath ?? DEFAULT_CURSOR_API_KEY_FILE;
+  const apiKey = consumeBoundCursorApiKey({ filePath: apiKeyPath });
+  if (apiKey.disposal.state === "readable") {
+    survivors.push(`${apiKeyPath} (${apiKey.disposal.reason})`);
+  }
+
+  if (survivors.length === 0) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    code: BOUND_SECRETS_NOT_CONSUMED,
+    message:
+      `Task-bind secrets are still readable after being hydrated into the ` +
+      `environment, so authored work did not run: ${survivors.join(", ")}.`,
+  };
+}

package/src/internal/cursor/hosted-deployment-secrets.ts

@@ -4,11 +4,18 @@
  * The deployment host rewrites this tmpfs document before each admission and
  * execution request. July reloads it synchronously because the process was
  * already running in the frozen snapshot when the task-specific values
- * arrived.
+ * arrived, then destroys the document: `process.env` is the source authored
+ * code reads, and the file is only how the value crossed the process
+ * boundary.
  */
 
 import { readFileSync } from "node:fs";
 
+import {
+  type BoundSecretFileDisposal,
+  destroyBoundSecretFile,
+} from "./bound-secret-file.js";
+
 export const DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE =
   "/run/cursor/secrets/AGENT_SERVE_DEPLOYMENT_SECRETS.json";
 
@@ -48,17 +55,11 @@ function parseBoundSecrets(path: string): Record<string, string> | undefined {
 }
 
 /**
- * Refresh `process.env` from the latest bound document. A missing or malformed
- * file is a no-op; an empty valid document removes values loaded by an earlier
- * bind after the deployment secret was unset.
+ * Apply the latest bound document to `process.env`. An empty valid document
+ * removes values loaded by an earlier bind after the deployment secret was
+ * unset, which is why the applied names are tracked across calls.
  */
-export function refreshBoundDeploymentSecrets(
-  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE
-): void {
-  const secrets = parseBoundSecrets(path);
-  if (secrets === undefined) {
-    return;
-  }
+function applyBoundSecrets(secrets: Record<string, string>): void {
   for (const name of appliedSecretNames) {
     if (!(name in secrets)) {
       delete process.env[name];
@@ -70,3 +71,33 @@ export function refreshBoundDeploymentSecrets(
     appliedSecretNames.add(name);
   }
 }
+
+export type BoundDeploymentSecretsConsumeResult = {
+  /** The document supplied values on this call. */
+  applied: boolean;
+  disposal: BoundSecretFileDisposal;
+};
+
+/**
+ * Apply the bound document to `process.env`, then destroy it.
+ *
+ * The env refresh always runs first, so a failed destroy never costs the
+ * request its secrets. A malformed document is destroyed too: it carries no
+ * values this process can use, and leaving it on disk only leaves whatever
+ * the control plane did manage to write.
+ *
+ * A `readable` disposal means the document survived; hosted callers must fail
+ * the request rather than run authored code next to a live secrets file.
+ */
+export function consumeBoundDeploymentSecrets(
+  path: string = DEFAULT_AGENT_SERVE_DEPLOYMENT_SECRETS_FILE
+): BoundDeploymentSecretsConsumeResult {
+  const secrets = parseBoundSecrets(path);
+  if (secrets !== undefined) {
+    applyBoundSecrets(secrets);
+  }
+  return {
+    applied: secrets !== undefined,
+    disposal: destroyBoundSecretFile(path),
+  };
+}

package/src/internal/cursor/hosted-store-secrets.ts

@@ -1,7 +1,7 @@
 /**
  * Task-time bind paths for hosted deployment file-store source ids.
  *
- * Freeze v2 snapshots start `agent-serve serve` at bake time without a service
+ * Freeze v2 snapshots start `agent-sdk serve` at bake time without a service
  * account, so neither store id is in process env. Execute-from-freeze binds
  * the deployment credential and store ids into `/run/cursor/secrets/` without
  * restarting July — the same pattern as {@link DEFAULT_CURSOR_API_KEY_FILE}.

package/src/internal/cursor-account-mcp-auth.ts

@@ -20,6 +20,7 @@ import type {
 } from "./cursor/backend-client.js";
 import { LOG_PREFIX } from "./distribution.js";
 import { openBrowser } from "./mcp-oauth.js";
+import { sleep as defaultSleep } from "./sleep.js";
 
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 const DEFAULT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
@@ -66,10 +67,6 @@ export interface AuthorizeCursorAccountConnectorsResult {
   errored: Array<{ name: string; error: string }>;
 }
 
-function sleepMs(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Authorize the deployment service account for the connection's connectors.
  * Already-authorized connectors are skipped; the rest get a browser OAuth
@@ -81,7 +78,7 @@ export async function authorizeCursorAccountConnectors(
   const { backendClient, teamId, serviceAccountId, connectionName, out, err } =
     args;
   const open = args.openBrowserImpl ?? openBrowser;
-  const sleep = args.sleep ?? sleepMs;
+  const sleep = args.sleep ?? defaultSleep;
   const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const pollTimeoutMs = args.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
   const redirectUri = mcpOauthRedirectUri();

package/src/internal/cursor-deployment-relay.ts

@@ -60,14 +60,18 @@ export function currentDeploymentSubscriptions(
   return typeof subscriptions === "function" ? subscriptions() : subscriptions;
 }
 
-/** Normalize the channel's `deploySourceUris` option into concrete subscriptions. */
+/**
+ * Normalize the channel's `deploySourceUris` option into concrete
+ * subscriptions. An omitted or empty option resolves to none, which callers
+ * read as "defer to the deploy scope".
+ */
 export function resolveDeploymentSubscriptions(options: {
-  deploySourceUris: readonly (string | DeploymentSubscription)[];
+  deploySourceUris?: readonly (string | DeploymentSubscription)[];
   environments?: readonly string[];
   events?: readonly DeploymentEventType[];
 }): ResolvedSubscription[] {
   const bySource = new Map<string, ResolvedSubscription>();
-  for (const entry of options.deploySourceUris) {
+  for (const entry of options.deploySourceUris ?? []) {
     const subscription: DeploymentSubscription =
       typeof entry === "string" ? { deploySourceUri: entry } : entry;
     // Case-folded only: `Deployment.deploy_source_uri` has no documented
@@ -106,10 +110,10 @@ export function resolveDeploymentSubscriptions(options: {
         ? []
         : [...new Set([...existing.environments, ...environments])];
   }
-  // Empty is legal here and means "this channel wants nothing". The
-  // wire-level empty list means deregister. The host re-resolves on each
-  // heartbeat, so a channel that later fills `deploySourceUris` can
-  // register without a restart.
+  // Empty means "this channel names nothing". The relay wire reads that as
+  // deregistration, hosted admission reads it as "defer to the deploy
+  // scope". The host re-resolves on each heartbeat, so a channel that later
+  // fills `deploySourceUris` registers without a restart.
   return [...bySource.values()];
 }
 

package/src/internal/deploy-manifest.ts

@@ -31,7 +31,6 @@
 
 import { z } from "zod";
 import { isPublicEndpointPolicy } from "../channels.js";
-import type { ContinuationIdentity } from "../continuation.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
@@ -40,7 +39,10 @@ import {
   channelDeclaredEventTypes,
   handshakeChannelContinuation,
 } from "./continuation-channel.js";
-import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
+import {
+  CONTINUATION_SELECTORS,
+  type ContinuationIdentity,
+} from "./continuation-identity.js";
 import {
   projectInfo,
   runtimeArchitectureCompatibilityError,

package/src/internal/discovery/ab.ts

@@ -5,6 +5,7 @@
 import { basename, extname, join, relative } from "node:path";
 import type { ABConfigFile } from "../../ab.js";
 import type { DiscoveredAB } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
 import {
   findModuleFile,
@@ -17,21 +18,31 @@ import { importDefault } from "./modules.js";
 
 export async function loadABs(
   ctx: DiscoveryContext,
-  agentDir: string
+  agentDir: string,
+  onDisable?: (source: string, path: string) => void
 ): Promise<DiscoveredAB[]> {
   const abs: DiscoveredAB[] = [];
   const seen = new Set<string>();
 
   const single = await findModuleFile(agentDir, "ab");
   if (single !== undefined) {
-    const definition = await importDefault(ctx, single, "ab");
+    const definition = await importDefault(
+      ctx,
+      single,
+      onDisable === undefined ? "ab" : ["ab", "disabled"]
+    );
     if (definition !== undefined) {
-      const name = resolveABName(definition, "ab");
-      seen.add(name);
-      abs.push({
-        name,
-        definition: definition as DiscoveredAB["definition"],
-      });
+      if (getDefinitionKind(definition) === "disabled") {
+        onDisable?.("ab", single);
+      } else {
+        const name = resolveABName(definition, "ab");
+        seen.add(name);
+        abs.push({
+          name,
+          source: "ab",
+          definition: definition as DiscoveredAB["definition"],
+        });
+      }
     }
   }
 
@@ -43,10 +54,18 @@ export async function loadABs(
       }
       const rel = toPosix(relative(absDir, filePath));
       const stem = rel.slice(0, -extname(rel).length);
-      const definition = await importDefault(ctx, filePath, "ab");
+      const definition = await importDefault(
+        ctx,
+        filePath,
+        onDisable === undefined ? "ab" : ["ab", "disabled"]
+      );
       if (definition === undefined) {
         continue;
       }
+      if (getDefinitionKind(definition) === "disabled") {
+        onDisable?.(stem, filePath);
+        continue;
+      }
       const name = resolveABName(definition, stem);
       if (seen.has(name)) {
         ctx.diagnostics.push({
@@ -59,6 +78,7 @@ export async function loadABs(
       seen.add(name);
       abs.push({
         name,
+        source: stem,
         definition: definition as DiscoveredAB["definition"],
       });
     }