@cursor/july 0.1.16 → 0.1.18

package/src/internal/evals-client.ts

@@ -488,6 +488,11 @@ export function snapshotToEvalRunResults(
     path: c.fileId,
     ...(c.description === undefined ? {} : { description: c.description }),
     ok: c.ok === true,
+    // Older serve processes send no verdict; infer it from `ok` so a remote
+    // batch still prints and reports consistently.
+    verdict: c.verdict ?? (c.ok === true ? "passed" : "failed"),
+    ...(c.skipReason === undefined ? {} : { skipReason: c.skipReason }),
+    ...(c.metadata === undefined ? {} : { metadata: c.metadata }),
     assertions: c.assertions ?? [],
     ...(c.sessionId === undefined ? {} : { sessionId: c.sessionId }),
     inputs: c.inputs ?? [],

package/src/internal/local-env.ts

@@ -0,0 +1,53 @@
+/**
+ * Loads an agent directory's `.env.local` (and each immediate child's,
+ * for multi-agent hosts) into process.env. Real env always wins —
+ * `process.loadEnvFile` never overrides. Values a previous call loaded are
+ * refreshed, so a reload picks up edits made since.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// Not real env, so a reload has to clear them first: loadEnvFile skips
+// anything already in process.env, which would pin the first-boot values.
+let fileLoadedKeys = new Set<string>();
+
+export function loadAgentLocalEnv(dir: string): string[] {
+  for (const key of fileLoadedKeys) {
+    delete process.env[key];
+  }
+  const realKeys = new Set(Object.keys(process.env));
+  const loaded: string[] = [];
+  const tryLoad = (path: string): void => {
+    if (!existsSync(path)) {
+      return;
+    }
+    process.loadEnvFile(path);
+    loaded.push(path);
+  };
+  const trackLoadedKeys = (): void => {
+    fileLoadedKeys = new Set(
+      Object.keys(process.env).filter((key) => !realKeys.has(key))
+    );
+  };
+
+  tryLoad(join(dir, ".env.local"));
+
+  let children: string[];
+  try {
+    children = readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+      .map((entry) => entry.name);
+  } catch {
+    trackLoadedKeys();
+    return loaded;
+  }
+  for (const child of children) {
+    if (child === "node_modules") {
+      continue;
+    }
+    tryLoad(join(dir, child, ".env.local"));
+  }
+  trackLoadedKeys();
+  return loaded;
+}

package/src/internal/playground/static.ts

@@ -52,6 +52,9 @@ export function playgroundBundleExists(): boolean {
  * The SPA `index.html` with a `<base href>` injected so its relative asset
  * URLs resolve under the mount point (`/playground/` or `/<slug>/playground/`).
  * Falls back to a helpful placeholder page when the bundle is missing.
+ * The hosted alias performs the same injection for its central copy
+ * (`backend/server/src/agentServe/aliasPlaygroundShell.ts`) — keep them
+ * behaviorally aligned.
  */
 export function renderPlaygroundIndexHtml(baseHref: string): string {
   if (!playgroundBundleExists()) {

package/src/internal/reminder-runner.ts

@@ -336,6 +336,36 @@ export class ReminderRunner {
     return n;
   }
 
+  /**
+   * Re-key armed reminders when a channel rotates a session's continuation
+   * token (the built-in HTTP channel rotates after every follow-up). Without
+   * this, a reminder armed before the rotation misses its session at fire
+   * time and disarms as `session_gone`.
+   */
+  async rekeyContinuation(
+    channelId: string,
+    oldToken: string,
+    newToken: string
+  ): Promise<number> {
+    const armed = await this.store.listArmed();
+    let n = 0;
+    for (const record of armed) {
+      if (
+        record.channelId !== channelId ||
+        record.continuationToken !== oldToken
+      ) {
+        continue;
+      }
+      await this.persist({
+        ...record,
+        continuationToken: newToken,
+        updatedAt: new Date().toISOString(),
+      });
+      n += 1;
+    }
+    return n;
+  }
+
   /** Fire one reminder immediately (dev / hillclimb). */
   async dispatch(reminderId: string): Promise<{
     reminderId: string;

package/src/internal/run-client.ts

@@ -46,6 +46,11 @@ export interface RunSessionResult {
   events: SessionEvent[];
   trajectory: Trajectory;
   ok: boolean;
+  /**
+   * Index to pass as `startIndex` on the next call for this session. Undefined
+   * when the turn streamed nothing, in which case reuse the previous value.
+   */
+  nextEventIndex?: number;
 }
 
 const TERMINAL_TYPES = new Set([
@@ -63,6 +68,16 @@ export async function runSession(
     messages: string[];
     sessionId?: string;
     continuationToken?: string;
+    /**
+     * First event index to read when resuming an existing session.
+     *
+     * The stream replays from `startIndex` and this client stops at the first
+     * terminal event, so a caller that sends several turns across separate
+     * `runSession` calls **must** pass the index after its last consumed event
+     * (see {@link RunSessionResult.nextEventIndex}). Omitting it replays the
+     * earlier turn and returns those stale events instead of the new turn's.
+     */
+    startIndex?: number;
     /** Applied only when creating a new session (first message). */
     workspaceDir?: string;
     /** Applied only when creating a new session (first message). */
@@ -78,7 +93,7 @@ export async function runSession(
   let sessionId = options.sessionId;
   let continuationToken = options.continuationToken;
   const allEvents: SessionEvent[] = [];
-  let nextEventIndex = 0;
+  let nextEventIndex = options.startIndex ?? 0;
 
   const auth: RequestAuth = {
     bearerToken: options.bearerToken,
@@ -126,6 +141,7 @@ export async function runSession(
     events: allEvents,
     trajectory,
     ok: trajectory.ok,
+    nextEventIndex: allEvents.length === 0 ? undefined : nextEventIndex,
   };
 }
 

package/src/internal/sdk-runner.ts

@@ -12,6 +12,7 @@ import {
   type AgentDefinition,
   type AgentOptions,
   type CloudAgentOptions,
+  createAgentPlatform,
   JsonlLocalAgentStore,
   type LocalAgentStore,
   type ModelSelection,
@@ -30,9 +31,48 @@ import {
 /** Internal seam between the session engine and the Cursor SDK harness. */
 export interface AgentRunner {
   runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+  /**
+   * Resolve a local workspace before any session needs it, so the first turn
+   * is not the one that pays for it. Best effort, hence the reported outcome:
+   * a runner that cannot warm must say so rather than let a caller log
+   * success over a workspace that was never touched.
+   */
+  prewarm?(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
   dispose?(): Promise<void>;
 }
 
+/**
+ * The parts of a turn that decide which local executor it runs on. Must stay
+ * a subset of {@link RunnerTurnRequest} — anything that disagrees warms an
+ * executor no turn will ask for.
+ */
+export type RunnerPrewarmRequest = Pick<
+  RunnerTurnRequest,
+  | "workspaceDir"
+  | "runnerStateDir"
+  | "sandbox"
+  | "mcpServers"
+  | "subagents"
+  | "model"
+>;
+
+/** Whether a workspace was actually resolved, and why not when it wasn't. */
+export type PrewarmOutcome =
+  | { readonly warmed: true }
+  | { readonly warmed: false; readonly reason: string };
+
+/**
+ * `CursorAgentPlatform.prewarmLocalWorkspace` as of `@cursor/sdk` 1.0.26.
+ * Declared structurally so this keeps building — and reports that it skipped
+ * warming — against the pinned older SDK. Delete once the pin passes that
+ * version.
+ */
+type MaybePrewarmingPlatform = {
+  prewarmLocalWorkspace?: (
+    options: AgentOptions
+  ) => Promise<() => Promise<void>>;
+};
+
 export interface CursorSdkRunnerOptions {
   /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
   apiKey?: string;
@@ -46,15 +86,90 @@ export interface CursorSdkRunnerOptions {
   logger?: (line: string) => void;
 }
 
+/**
+ * How long one SDK agent handle (and the Connect transport inside it) may be
+ * reused before the runner retires it.
+ *
+ * The transport exchanges the account API key for a short-lived access token
+ * (`SessionType.API_KEY_TOKEN`, 60 minutes) once per handle, and has no
+ * reliable refresh: an Unauthenticated rejection on the agent's streaming RPC
+ * surfaces while the stream is being read — outside the transport's
+ * request-time 401 retry — so an expired token gets replayed on every
+ * subsequent turn until the handle is rebuilt. Long-lived sessions (watch
+ * wakes, crons) hit this at the ~60 minute mark and then fail forever.
+ * Retiring the handle comfortably before the token can expire keeps them
+ * healthy: `Agent.resume` rehydrates the same conversation from the runner
+ * store on a fresh transport, so recycling costs only transport warmth.
+ */
+const MAX_AGENT_HANDLE_AGE_MS = 45 * 60 * 1000;
+
+interface CachedAgentHandle {
+  agent: Promise<SDKAgent>;
+  openedAtMs: number;
+}
+
+/**
+ * The backend's `NotLoggedIn` copy ("Authentication error" title, "try
+ * logging out and back in." detail) as it surfaces through SDK RunResults.
+ * Deliberately narrow: this gates a one-shot in-place retry, and matching
+ * broader error text would retry turns that a fresh transport cannot fix.
+ */
+export function isAuthErrorMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /authentication error|try logging out and back in/i.test(message);
+}
+
 export class CursorSdkRunner implements AgentRunner {
-  private readonly agents = new Map<string, Promise<SDKAgent>>();
+  private readonly agents = new Map<string, CachedAgentHandle>();
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
+  private readonly prewarmReleases: Array<() => Promise<void>> = [];
 
   constructor(private readonly options: CursorSdkRunnerOptions = {}) {}
 
   async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    let sawUpdate = false;
+    const tracked: RunnerTurnRequest = {
+      ...request,
+      onUpdate: (update) => {
+        sawUpdate = true;
+        return request.onUpdate(update);
+      },
+    };
+    const outcome = await this.runTurnAttempt(tracked);
+    if (
+      outcome.status !== "error" ||
+      !isAuthErrorMessage(outcome.errorMessage) ||
+      sawUpdate ||
+      request.isFirstTurn ||
+      request.signal?.aborted === true
+    ) {
+      return outcome;
+    }
+    // The turn died on an authentication failure before producing any output
+    // — the signature of a handle whose exchanged access token expired (the
+    // failed attempt already evicted it). Retrying once on a fresh handle is
+    // safe here because nothing streamed and no tool ran. First turns are
+    // excluded: their token was exchanged moments ago, so the credential
+    // itself is the problem and a retry cannot succeed.
+    this.log(
+      `[agentkit] session ${request.sessionId}: retrying the turn on a fresh SDK agent handle after an authentication failure`
+    );
     try {
-      const agent = await this.getAgent(request);
+      return await this.runTurnAttempt(tracked);
+    } catch {
+      // The retry was best effort; report the original failure.
+      return outcome;
+    }
+  }
+
+  private async runTurnAttempt(
+    request: RunnerTurnRequest
+  ): Promise<TurnOutcome> {
+    const agentPromise = this.getAgent(request);
+    try {
+      const agent = await agentPromise;
       const run = await agent.send(request.prompt, {
         onDelta: async ({ update }) => {
           try {
@@ -100,20 +215,56 @@ export class CursorSdkRunner implements AgentRunner {
       }
       try {
         const result = await run.wait();
-        return toTurnOutcome(result);
+        const outcome = toTurnOutcome(result);
+        if (outcome.status === "error") {
+          // An error result usually means the handle's transport is poisoned
+          // — most often a cached access token that aged past its 60-minute
+          // lifetime and gets replayed on every request (stream failures
+          // bypass the transport's 401 retry). Retire the handle so the next
+          // attempt resumes the conversation from the store on a fresh
+          // transport instead of failing every turn until a restart.
+          this.evictAgent(request.sessionId, agentPromise);
+        }
+        return outcome;
       } finally {
         signal?.removeEventListener("abort", onAbort);
       }
     } catch (error) {
       // Drop the cached agent so a dead Connect/HTTP2 session cannot poison
       // the next turn (terminal/shell overflow often kills the transport).
-      this.agents.delete(request.sessionId);
+      this.evictAgent(request.sessionId, agentPromise);
       throw error;
     }
   }
 
+  /**
+   * Build the local executor for a workspace before any session asks for it.
+   * The warmed executor is reference counted, so the lease is held until
+   * {@link dispose}; dropping it early would tear the workspace back down.
+   */
+  async prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome> {
+    const platform = (await createAgentPlatform()) as MaybePrewarmingPlatform;
+    if (typeof platform.prewarmLocalWorkspace !== "function") {
+      // Older @cursor/sdk. Turns still work; they just pay on the first one.
+      return {
+        warmed: false,
+        reason:
+          "the installed @cursor/sdk has no prewarmLocalWorkspace; upgrade it to warm the workspace before the first turn",
+      };
+    }
+    const release = await platform.prewarmLocalWorkspace(
+      await this.buildLocalOptions(request)
+    );
+    this.prewarmReleases.push(release);
+    return { warmed: true };
+  }
+
   async dispose(): Promise<void> {
-    const agents = await Promise.allSettled([...this.agents.values()]);
+    const releases = this.prewarmReleases.splice(0);
+    await Promise.allSettled(releases.map((release) => release()));
+    const agents = await Promise.allSettled(
+      [...this.agents.values()].map((handle) => handle.agent)
+    );
     this.agents.clear();
     for (const settled of agents) {
       if (settled.status === "fulfilled") {
@@ -123,58 +274,104 @@ export class CursorSdkRunner implements AgentRunner {
   }
 
   private getAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
-    let agentPromise = this.agents.get(request.sessionId);
-    if (agentPromise === undefined) {
-      agentPromise = this.openAgent(request).catch((error) => {
-        this.agents.delete(request.sessionId);
-        throw error;
-      });
-      this.agents.set(request.sessionId, agentPromise);
+    const cached = this.agents.get(request.sessionId);
+    if (cached !== undefined) {
+      const ageMs = Date.now() - cached.openedAtMs;
+      if (ageMs < MAX_AGENT_HANDLE_AGE_MS) {
+        return cached.agent;
+      }
+      // Past this age the handle's exchanged access token could expire
+      // mid-turn. Retire it and reopen below on a fresh transport.
+      this.log(
+        `[agentkit] session ${request.sessionId}: recycling the SDK agent handle after ${Math.round(ageMs / 60_000)} min so the turn runs on a fresh access token`
+      );
+      this.evictAgent(request.sessionId, cached.agent);
     }
+    const agentPromise = this.openAgent(request).catch((error) => {
+      // Nothing opened, so there is no handle to close — just free the slot.
+      this.agents.delete(request.sessionId);
+      throw error;
+    });
+    this.agents.set(request.sessionId, {
+      agent: agentPromise,
+      openedAtMs: Date.now(),
+    });
     return agentPromise;
   }
 
-  private async openAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+  /**
+   * Drop a cached handle and close it best-effort to release its transport
+   * and executor lease. Identity-checked so a turn that lost a race with a
+   * newer open cannot evict the replacement handle.
+   */
+  private evictAgent(sessionId: string, agent: Promise<SDKAgent>): void {
+    const cached = this.agents.get(sessionId);
+    if (cached === undefined || cached.agent !== agent) {
+      return;
+    }
+    this.agents.delete(sessionId);
+    void cached.agent.then((sdkAgent) => sdkAgent.close()).catch(() => {});
+  }
+
+  private log(line: string): void {
+    (this.options.logger ?? (() => {}))(line);
+  }
+
+  private requireApiKey(): string {
     const apiKey = this.options.apiKey ?? process.env.CURSOR_API_KEY;
     if (apiKey === undefined || apiKey.trim() === "") {
       throw new Error(
         "The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY, or pass serve({ apiKey })."
       );
     }
-    const model = request.model ?? DEFAULT_MODEL;
+    return apiKey;
+  }
+
+  private buildSharedOptions(
+    request: RunnerPrewarmRequest
+  ): Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents"> {
     const subagents = toAgentDefinitions(request.subagents);
-    const shared: Pick<
-      AgentOptions,
-      "model" | "apiKey" | "mcpServers" | "agents"
-    > = {
-      model: toModelSelection(model),
-      apiKey,
+    return {
+      model: toModelSelection(request.model ?? DEFAULT_MODEL),
+      apiKey: this.requireApiKey(),
       ...(Object.keys(request.mcpServers).length > 0
         ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
         : {}),
       ...(subagents === undefined ? {} : { agents: subagents }),
     };
-
-    if (request.runtime === "cloud") {
-      return this.openCloudAgent(request, shared);
-    }
-    return this.openLocalAgent(request, shared);
   }
 
-  private async openLocalAgent(
-    request: RunnerTurnRequest,
-    shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">
-  ): Promise<SDKAgent> {
+  /**
+   * The options that decide which local executor a turn runs on. Prewarming
+   * goes through here too, so a warmed workspace is the one turns land on.
+   */
+  private async buildLocalOptions(
+    request: RunnerPrewarmRequest
+  ): Promise<AgentOptions> {
     const store =
       this.options.store ?? (await this.getStore(request.runnerStateDir));
-    const options: AgentOptions = {
-      ...shared,
+    return {
+      ...this.buildSharedOptions(request),
       local: {
         cwd: request.workspaceDir,
         settingSources: ["project"],
         store,
+        ...(request.sandbox === true
+          ? { sandboxOptions: { enabled: true } }
+          : {}),
       },
     };
+  }
+
+  private async openAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    if (request.runtime === "cloud") {
+      return this.openCloudAgent(request, this.buildSharedOptions(request));
+    }
+    return this.openLocalAgent(request);
+  }
+
+  private async openLocalAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    const options = await this.buildLocalOptions(request);
 
     if (request.isFirstTurn || request.sdkAgentId === undefined) {
       return Agent.create({
@@ -195,7 +392,7 @@ export class CursorSdkRunner implements AgentRunner {
       // conversation under the same id beats failing this thread's turns
       // forever ("Agent … not found" on every follow-up). The channel's
       // warm-turn prompt context re-hydrates the thread history.
-      (this.options.logger ?? (() => {}))(
+      this.log(
         `[agentkit] no stored conversation for ${agentId} on this host; starting a fresh one`
       );
       return Agent.create({ ...options, agentId });
@@ -341,11 +538,13 @@ function toTurnOutcome(result: RunResult): TurnOutcome {
   return {
     status: result.status,
     ...(result.result === undefined ? {} : { result: result.result }),
-    // The published RunResult carries no structured error details; failures
-    // thrown by send()/wait() surface through the engine's catch instead.
     ...(result.status === "error"
-      ? { errorMessage: "The Cursor agent run failed" }
+      ? { errorMessage: runErrorMessage(result) }
       : {}),
     ...(usage === undefined ? {} : { usage }),
   };
 }
+
+export function runErrorMessage(result: Pick<RunResult, "error">): string {
+  return result.error?.message?.trim() || "The Cursor agent run failed";
+}

package/src/internal/server.ts

@@ -385,6 +385,12 @@ export async function startServer(
     // channel or route can address them (continuation tokens must resolve).
     await engine.restoreStoredSessions();
 
+    // Resolve a shared harness workspace in the background: on a large repo
+    // that takes seconds, and a deployment coming online should absorb it
+    // rather than whoever sends the first message. No-op unless the agent
+    // pins `local.workspaceDir`.
+    void engine.prewarmSharedWorkspace();
+
     if (!githubAuthWarmed) {
       // Soft ambient GitHub auth check before channel onStart (which may call
       // host.github). Missing auth is a warning only — serve still starts.
@@ -415,6 +421,8 @@ export async function startServer(
       cancel: (id, reason) => reminderRunner.cancel(id, reason),
       cancelForContinuation: (token, reason) =>
         reminderRunner.cancelForContinuation(token, reason),
+      rekeyContinuation: (channelId, oldToken, newToken) =>
+        reminderRunner.rekeyContinuation(channelId, oldToken, newToken),
       dispatch: (id) => reminderRunner.dispatch(id),
     });
     engine.setEvals({
@@ -911,6 +919,10 @@ function mountAgentRoutes(
         name: project.name,
         dev,
         basePath: base,
+        // Framework version, for SPA/engine skew observability now that the
+        // hosted playground shell is served centrally (backend deploys)
+        // while engines stay on their install-time version.
+        version: packageVersion(),
         ...(multi ? { indexPath: "/" } : {}),
       }),
   });