@cursor/july 0.1.4 → 0.1.6

package/src/internal/cli-ax.ts

@@ -35,7 +35,12 @@ import { offerInstallCursorSkills } from "./install-cursor-skills.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
 import { openBrowser } from "./open-browser.js";
 import { startPlaygroundProxy } from "./playground-proxy.js";
-import { resolveProdSlug, resolveProdTarget } from "./resolve-prod-target.js";
+import {
+  ProdTargetError,
+  resolveProdAliasPlaygroundUrl,
+  resolveProdSlug,
+  resolveProdTarget,
+} from "./resolve-prod-target.js";
 import { runSession } from "./run-client.js";
 import {
   fetchSessionEvents,
@@ -92,8 +97,15 @@ export interface AxCliOptions {
    * Route chat/resume/run/call/eval/logs/sessions at the team's hosted
    * deployment
    * instead of a local ephemeral server. Mutually exclusive with `--url`.
+   * `eval` targets the deployment by default, so there `--prod` is just
+   * being explicit.
    */
   prod?: boolean;
+  /**
+   * `eval`: run against an ephemeral local server instead of the hosted
+   * deployment (the eval default). Mutually exclusive with `--url`/`--prod`.
+   */
+  local?: boolean;
   /** Cursor team id for `--prod` (defaults to the account's team). */
   team?: string;
   /** Cursor API key override for `--prod` management calls. */
@@ -654,6 +666,79 @@ export async function cmdTrajectory(options: AxCliOptions): Promise<number> {
   return trajectory.ok ? 0 : 1;
 }
 
+/**
+ * Which surface `eval` should target. Deployment is the default; `--local`
+ * opts into an ephemeral local server, `--url` into a running one.
+ * Exported for tests.
+ */
+export function resolveEvalTargetMode(
+  options: Pick<AxCliOptions, "local" | "prod" | "url">
+): "local" | "url" | "deployment" | { error: string } {
+  const flags = [
+    options.local === true ? "--local" : undefined,
+    options.prod === true ? "--prod" : undefined,
+    options.url !== undefined ? "--url" : undefined,
+  ].filter((flag) => flag !== undefined);
+  if (flags.length > 1) {
+    return { error: `${flags.join(" and ")} are mutually exclusive` };
+  }
+  if (options.local === true) {
+    return "local";
+  }
+  if (options.url !== undefined) {
+    return "url";
+  }
+  return "deployment";
+}
+
+/** Resolve the eval target; prints a CLI-ready error and returns an exit code on failure. */
+async function resolveEvalTarget(
+  options: AxCliOptions
+): Promise<ResolvedAgentTarget | number> {
+  const mode = resolveEvalTargetMode(options);
+  if (typeof mode === "object") {
+    process.stderr.write(`${mode.error}\n`);
+    return 2;
+  }
+  if (mode === "url") {
+    return { agentUrl: options.url!.replace(/\/$/, "") };
+  }
+  if (mode === "local") {
+    return startEphemeral(options);
+  }
+  try {
+    const prod = await resolveProdTarget({
+      dir: options.dir,
+      cwd: options.cwd,
+      slug: options.slug,
+      team: options.team,
+      apiKey: options.apiKey,
+      fetchImpl: options.fetchImpl,
+    });
+    return { agentUrl: prod.agentUrl, headers: prod.headers };
+  } catch (error) {
+    if (error instanceof ProdTargetError && error.notFound) {
+      // Keep the API error text: a 404 can also mean a wrong API host or a
+      // disabled feature gate, and the message distinguishes those from a
+      // genuinely missing deployment.
+      process.stderr.write(
+        `${sanitizeCustomerError(error.message)}\n` +
+          `Evals run on the hosted deployment by default.\n` +
+          `  deploy it first:  ${CLI_COMMAND_NAME} deploy --slug ${error.slug}\n` +
+          `  or run locally:   ${CLI_COMMAND_NAME} eval --local --dir ${options.dir}\n`
+      );
+      return 1;
+    }
+    process.stderr.write(
+      `${sanitizeCustomerError(
+        error instanceof Error ? error.message : String(error)
+      )}\n` +
+        `Evals run on the hosted deployment by default; pass --local to run on an ephemeral local server.\n`
+    );
+    return 1;
+  }
+}
+
 export async function cmdEval(options: AxCliOptions): Promise<number> {
   const projectRoot = resolve(options.cwd ?? process.cwd(), options.dir);
 
@@ -695,7 +780,10 @@ export async function cmdEval(options: AxCliOptions): Promise<number> {
     return 0;
   }
 
-  const target = await resolveTarget(options);
+  const target = await resolveEvalTarget(options);
+  if (typeof target === "number") {
+    return target;
+  }
   const stream = shouldStreamProgress(options);
   const progress = stream ? createStreamProgress() : undefined;
   try {
@@ -991,9 +1079,9 @@ export async function cmdSession(
 /**
  * `playground` — open the web UI against local / `--url` / `--prod`.
  *
- * Hosted engines need short-lived access headers a browser cannot set, so
- * `--prod` (and `--bearer-token`) run a loopback reverse proxy that injects
- * them. Ctrl-C stops the proxy.
+ * `--prod` opens the stable hosted alias playground URL; the SPA collects
+ * the alias token. `--bearer-token` (and other injected headers) still run a
+ * loopback reverse proxy — Ctrl-C stops that proxy.
  */
 export async function cmdPlayground(options: AxCliOptions): Promise<number> {
   if (options.prod === true && options.url !== undefined) {
@@ -1006,17 +1094,18 @@ export async function cmdPlayground(options: AxCliOptions): Promise<number> {
       ? options.sessionId.trim()
       : undefined;
 
-  // Hosted: mint engineAccess and refresh it for the life of the proxy.
+  // Hosted: open the alias playground; SPA owns alias-token sign-in.
   if (options.prod === true) {
-    let initial: Awaited<ReturnType<typeof resolveProdTarget>>;
+    let resolved: Awaited<ReturnType<typeof resolveProdAliasPlaygroundUrl>>;
     try {
-      initial = await resolveProdTarget({
+      resolved = await resolveProdAliasPlaygroundUrl({
         dir: options.dir,
         cwd: options.cwd,
         slug: options.slug,
         team: options.team,
         apiKey: options.apiKey,
         fetchImpl: options.fetchImpl,
+        sessionId,
       });
     } catch (error) {
       process.stderr.write(
@@ -1027,44 +1116,11 @@ export async function cmdPlayground(options: AxCliOptions): Promise<number> {
       return 1;
     }
 
-    let proxy: Awaited<ReturnType<typeof startPlaygroundProxy>>;
-    try {
-      proxy = await startPlaygroundProxy({
-        upstreamUrl: initial.agentUrl,
-        headers: initial.headers,
-        expiresAt: initial.expiresAt,
-        refreshUpstream: async () => {
-          const next = await resolveProdTarget({
-            dir: options.dir,
-            cwd: options.cwd,
-            slug: options.slug ?? initial.slug,
-            team: options.team,
-            apiKey: options.apiKey,
-            fetchImpl: options.fetchImpl,
-            err: () => {},
-          });
-          return {
-            upstreamUrl: next.agentUrl,
-            headers: next.headers,
-            expiresAt: next.expiresAt,
-          };
-        },
-      });
-    } catch (error) {
-      process.stderr.write(
-        `${sanitizeCustomerError(
-          error instanceof Error ? error.message : String(error)
-        )}\n`
-      );
-      return 1;
+    process.stdout.write(`${resolved.playgroundUrl}\n`);
+    if (options.print !== true) {
+      openBrowser(resolved.playgroundUrl);
     }
-
-    return await runPlaygroundProxySession({
-      proxy,
-      sessionId,
-      print: options.print === true,
-      signal: options.signal,
-    });
+    return 0;
   }
 
   const target = await resolveSessionTarget(options);

package/src/internal/cli-deploy.ts

@@ -674,7 +674,8 @@ async function deployOne(
       `  generation:  ${detail.generation}\n` +
       `  kind:        ${detail.deploymentKind}\n` +
       `  alias:       ${aliasUrl}\n` +
-      `  playground:  ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
+      `  playground:  ${aliasUrl}/playground (sign in with the alias token)\n` +
+      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
   );
   return 0;
 }
@@ -795,6 +796,7 @@ export async function cmdDeploymentStatus(
     `  generation:  ${detail.generation}`,
     `  kind:        ${detail.deploymentKind}`,
     `  alias:       ${aliasUrl}`,
+    `  playground:  ${aliasUrl}/playground`,
   ];
   if (detail.gitRepoUrl !== null && detail.gitRepoUrl !== undefined) {
     lines.push(`  repo:        ${detail.gitRepoUrl} @ ${detail.gitRef ?? ""}`);
@@ -1285,7 +1287,8 @@ function aliasTokenBlock(aliasToken: string): string {
   return (
     `\n  Alias token (shown ONCE — save it now, it cannot be retrieved again):\n\n` +
     `    ${aliasToken}\n\n` +
-    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL.\n` +
+    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL,\n` +
+    `  or paste it into the hosted playground (<alias>/playground) sign-in gate.\n` +
     `  Lost tokens: \`${CLI} rotate-token <slug>\` mints a replacement.\n\n`
   );
 }

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

@@ -68,7 +68,10 @@ export interface CursorEventRelayOptions {
   repos: readonly string[];
   events: readonly string[];
   stateDir: string;
-  /** Called for each matching event; failures are logged, not retried. */
+  /**
+   * Called for each matching event; failures retry a bounded number of
+   * times, then log and skip.
+   */
   dispatch: (event: CursorScmEvent) => Promise<void>;
   logger: (line: string) => void;
   /** Test seam. Defaults to global fetch. */
@@ -213,6 +216,12 @@ export class CursorEventRelay {
           events: [...this.options.events],
         })),
       }),
+      // Empty subscriptions drop this consumer's registration on clean stop
+      // instead of leaving it to lapse by TTL.
+      buildDeregistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: [],
+      }),
       applyRegistrationResponse: (json) => {
         const result = json as { repos?: SubscriptionStatus[] };
         const statuses = result.repos ?? [];

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

@@ -23,6 +23,11 @@ const DEFAULT_IDLE_POLL_DELAY_MS = 250;
 const MIN_BACKOFF_MS = 1_000;
 const MAX_BACKOFF_MS = 30_000;
 const AUTH_FAILURE_BACKOFF_MS = 60_000;
+/** Attempts per event before the offset advances past it. */
+const DISPATCH_ATTEMPTS = 3;
+const DISPATCH_RETRY_DELAYS_MS = [250, 1_000];
+/** Budget for the best-effort deregistration PUT during stop(). */
+const DEREGISTER_TIMEOUT_MS = 1_500;
 
 interface OffsetSnapshot {
   version: typeof OFFSET_SNAPSHOT_VERSION;
@@ -108,6 +113,14 @@ export interface RelayAdapter<TEvent extends { offset: string }> {
   readonly pollPath: string;
   /** The registration request body for this consumer id. */
   buildRegistrationBody(consumerId: string): unknown;
+  /**
+   * The empty-scope registration body used to deregister this consumer on a
+   * clean stop. When present, `stop()` best-effort PUTs it so the consumer's
+   * registration does not linger as a ghost until its server-side TTL (a
+   * ghost with this host's agent names makes name routing ambiguous for a
+   * redeployed sibling until it expires).
+   */
+  buildDeregistrationBody?(consumerId: string): unknown;
   /**
    * Apply the (ok) registration response: update the accepted-scope filter
    * and return the human-readable outcome lines to log. The core logs them
@@ -121,7 +134,10 @@ export interface RelayAdapter<TEvent extends { offset: string }> {
    * the offset but are not dispatched.
    */
   shouldDispatch(event: TEvent): boolean;
-  /** Handle one matching event. Failures are logged, not retried. */
+  /**
+   * Handle one matching event. Failures retry a bounded number of times
+   * ({@link DISPATCH_ATTEMPTS}), then log and skip.
+   */
   dispatch(event: TEvent): Promise<void>;
 }
 
@@ -147,6 +163,14 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
   private consumerId = "";
   /** undefined until the first registration, so a clean first success logs. */
   private lastRegistrationLog: string | undefined;
+  /** Whether any registration succeeded (gates the stop-time deregister). */
+  private registeredOnce = false;
+  /**
+   * The in-flight heartbeat re-registration, if any. `stop()` awaits it
+   * before deregistering so a just-sent heartbeat cannot land after the
+   * deregistration PUT and resurrect the registration for a full TTL.
+   */
+  private heartbeatPromise: Promise<boolean> | undefined;
 
   constructor(private readonly options: CursorRelayCoreOptions<TEvent>) {
     this.offsetStore = new RelayOffsetStore(options.stateDir);
@@ -170,7 +194,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
     const registered = await this.registerUntilSuccess();
     if (!registered) return;
     this.registerTimer = setInterval(() => {
-      void this.registerOnce();
+      this.heartbeatPromise = this.registerOnce();
     }, DEFAULT_REGISTER_INTERVAL_MS);
     this.registerTimer.unref?.();
     await this.consumeLoop();
@@ -229,6 +253,56 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
         timer.unref?.();
       }),
     ]);
+    // A heartbeat re-registration may be in flight (its fetch was just
+    // aborted); let it settle so it cannot land after the deregistration.
+    await this.heartbeatPromise?.catch(() => {});
+    await this.deregister();
+  }
+
+  /**
+   * Best-effort empty-scope PUT on clean stop, so this consumer's
+   * registration is dropped immediately instead of lingering until its
+   * server-side TTL. A ghost registration keeps this host's agent names
+   * live and makes name routing ambiguous for a redeployed sibling with a
+   * fresh consumer id. Failures only log — the TTL still cleans up.
+   */
+  private async deregister(): Promise<void> {
+    const adapter = this.options.adapter;
+    if (
+      adapter.buildDeregistrationBody === undefined ||
+      !this.registeredOnce ||
+      this.consumerId === ""
+    ) {
+      return;
+    }
+    const url = `${this.options.baseUrl.replace(/\/+$/, "")}${adapter.subscribePath}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEREGISTER_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+      const response = await this.fetchImpl(url, {
+        method: "PUT",
+        headers: {
+          authorization: `Bearer ${this.options.apiKey}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(adapter.buildDeregistrationBody(this.consumerId)),
+        signal: controller.signal,
+      });
+      if (response.ok) {
+        this.log("deregistered on shutdown");
+      } else {
+        this.log(
+          `deregistration failed: ${response.status} (registration lapses by TTL)`
+        );
+      }
+    } catch (error) {
+      this.log(
+        `deregistration failed: ${describeRelayError(error)} (registration lapses by TTL)`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
   private log(line: string): void {
@@ -291,6 +365,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
       this.logRegistrationOutcome(
         this.options.adapter.applyRegistrationResponse(json)
       );
+      this.registeredOnce = true;
       return true;
     } catch (error) {
       if (this.isAbort(error)) return false;
@@ -373,13 +448,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
           // on replay after a crash between dispatch and save).
           if (compareStreamOffsets(event.offset, offset) <= 0) continue;
           if (this.options.adapter.shouldDispatch(event)) {
-            try {
-              await this.options.adapter.dispatch(event);
-            } catch (error) {
-              this.log(
-                `dispatch failed at offset ${event.offset}: ${describeRelayError(error)}`
-              );
-            }
+            await this.dispatchWithRetry(event);
           }
           offset = event.offset;
         }
@@ -403,6 +472,43 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
     }
   }
 
+  /**
+   * Dispatch one event with a small bounded retry before the offset advances
+   * past it. Transient local failures (e.g. a connection reset while POSTing
+   * to the channel) used to drop the event outright; a poison event still
+   * only costs {@link DISPATCH_ATTEMPTS} tries and is then skipped, keeping
+   * at-least-once semantics without a retry loop.
+   */
+  private async dispatchWithRetry(event: TEvent): Promise<void> {
+    for (let attempt = 1; attempt <= DISPATCH_ATTEMPTS; attempt++) {
+      if (attempt > 1 && !this.running) {
+        this.log(
+          `dispatch abandoned at offset ${event.offset}: relay stopping`
+        );
+        return;
+      }
+      try {
+        await this.options.adapter.dispatch(event);
+        return;
+      } catch (error) {
+        if (attempt === DISPATCH_ATTEMPTS) {
+          this.log(
+            `dispatch failed at offset ${event.offset} after ${attempt} attempts: ${describeRelayError(error)}`
+          );
+          return;
+        }
+        this.log(
+          `dispatch attempt ${attempt} failed at offset ${event.offset}: ${describeRelayError(error)}; retrying`
+        );
+        await this.sleep(
+          DISPATCH_RETRY_DELAYS_MS[
+            Math.min(attempt - 1, DISPATCH_RETRY_DELAYS_MS.length - 1)
+          ]
+        );
+      }
+    }
+  }
+
   /** Log the failure, sleep, and return the backoff for the NEXT failure. */
   private async backoffAfterHttpFailure(
     response: Response,

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

@@ -44,8 +44,8 @@ export interface CursorSlackRelayOptions {
   agents: readonly CursorSlackAgentRegistration[];
   stateDir: string;
   /**
-   * Called for each event addressed to this consumer's agents; failures are
-   * logged, not retried.
+   * Called for each event addressed to this consumer's agents; failures
+   * retry a bounded number of times, then log and skip.
    */
   dispatch: (envelope: CursorSlackRelayEvent) => Promise<void>;
   logger: (line: string) => void;
@@ -163,6 +163,10 @@ export class CursorSlackRelay {
           })),
         };
       },
+      // Empty agents drop this consumer's registration on clean stop, so a
+      // redeployed sibling's identical agent names never tie with this
+      // host's ghost until the server-side TTL lapses.
+      buildDeregistrationBody: (consumerId) => ({ consumerId, agents: [] }),
       applyRegistrationResponse: (json) => {
         const result = json as RegistrationResponse;
         const agentStatuses = result.agents ?? [];

package/src/internal/discovery.ts

@@ -1611,8 +1611,8 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
             maxPlaygroundSessions: resolveABMaxPlaygroundSessions(
               project.abConfig?.maxPlaygroundSessions
             ),
-            durableSamples: project.abConfig?.persistSamples !== undefined,
-            durableSnapshots: project.abConfig?.persistSnapshots !== undefined,
+            durableSamples: project.storage?.abs !== undefined,
+            durableSnapshots: project.storage?.abs?.putSnapshot !== undefined,
           },
         }),
     storage: