@cursor/july 0.1.16 → 0.1.17

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/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;
@@ -49,6 +89,7 @@ export interface CursorSdkRunnerOptions {
 export class CursorSdkRunner implements AgentRunner {
   private readonly agents = new Map<string, Promise<SDKAgent>>();
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
+  private readonly prewarmReleases: Array<() => Promise<void>> = [];
 
   constructor(private readonly options: CursorSdkRunnerOptions = {}) {}
 
@@ -112,7 +153,31 @@ export class CursorSdkRunner implements AgentRunner {
     }
   }
 
+  /**
+   * 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 releases = this.prewarmReleases.splice(0);
+    await Promise.allSettled(releases.map((release) => release()));
     const agents = await Promise.allSettled([...this.agents.values()]);
     this.agents.clear();
     for (const settled of agents) {
@@ -134,47 +199,61 @@ export class CursorSdkRunner implements AgentRunner {
     return agentPromise;
   }
 
-  private async openAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+  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({
@@ -341,11 +420,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.
@@ -911,6 +917,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: "/" } : {}),
       }),
   });

package/src/internal/session-engine.ts

@@ -39,6 +39,7 @@ import {
   type PendingApproval,
   type ReceiveInput,
   type ResolvedAgent,
+  type RunnerSubagent,
   type RunnerTurnRequest,
   type SendMessageFn,
   type SendMessageOptions,
@@ -957,13 +958,18 @@ export class SessionEngine {
   }
 
   /**
-   * Local harness cwd for a session: per-send override, else
-   * `<agent.local.cwd>/<sessionId>`, else the durable session workspace.
+   * Local harness cwd for a session: per-send override, else the shared
+   * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
+   * the durable session workspace.
    */
   harnessCwd(record: SessionRecord): string {
     if (record.workspaceOverride !== undefined) {
       return record.workspaceOverride;
     }
+    const shared = this.project.agent.local?.workspaceDir;
+    if (shared !== undefined) {
+      return shared;
+    }
     const agentCwd = this.project.agent.local?.cwd;
     if (agentCwd !== undefined) {
       return join(agentCwd, record.sessionId);
@@ -972,12 +978,64 @@ export class SessionEngine {
   }
 
   /**
-   * Directory that receives AGENTS.md / skills / agent tools. When the
-   * harness cwd is a one-off override (e.g. PR worktree), scaffold stays in
-   * the durable session workspace; otherwise scaffold lands in the harness.
+   * True when the harness cwd is a directory the session does not own — a
+   * per-send override (e.g. a PR worktree) or a workspace shared by every
+   * session. Agent scaffold has to stay out of those, so it lands in the
+   * durable session workspace and the instructions travel inline instead.
+   */
+  private hasBorrowedWorkspace(record: SessionRecord): boolean {
+    return (
+      record.workspaceOverride !== undefined ||
+      this.project.agent.local?.workspaceDir !== undefined
+    );
+  }
+
+  /**
+   * Resolve the shared harness workspace during startup, so the first session
+   * is not the one that waits for it. Only possible with
+   * `local.workspaceDir`: every other layout gives a session its own cwd,
+   * which is unknowable until that session exists.
+   *
+   * Best effort — warming is an optimization, and a turn rebuilds on its own.
    */
+  async prewarmSharedWorkspace(): Promise<void> {
+    const agent = this.project.agent;
+    const workspaceDir = agent.local?.workspaceDir;
+    if (
+      workspaceDir === undefined ||
+      agent.runtime !== "local" ||
+      this.runner.prewarm === undefined
+    ) {
+      return;
+    }
+    const startedAt = Date.now();
+    try {
+      const outcome = await this.runner.prewarm({
+        workspaceDir,
+        runnerStateDir: join(this.stateRoot, "runner"),
+        sandbox: agent.local?.sandbox === true,
+        mcpServers: this.buildMcpServers("local"),
+        subagents: buildRunnerSubagents(agent),
+        ...(agent.model === undefined ? {} : { model: agent.model }),
+      });
+      // Report what happened rather than that the call returned: a runner
+      // that cannot warm resolves cleanly, and logging success there would
+      // tell an operator the workspace is hot when nothing touched it.
+      this.logger(
+        outcome.warmed
+          ? `[agentkit] warmed ${workspaceDir} in ${Date.now() - startedAt}ms`
+          : `[agentkit] did not warm ${workspaceDir}: ${outcome.reason}`
+      );
+    } catch (error) {
+      this.logger(
+        `[agentkit] could not warm ${workspaceDir}: ${describeError(error)}`
+      );
+    }
+  }
+
+  /** Directory that receives AGENTS.md / skills / agent tools. */
   private scaffoldDir(record: SessionRecord): string {
-    if (record.workspaceOverride !== undefined) {
+    if (this.hasBorrowedWorkspace(record)) {
       return this.sessions.workspaceDir(record.sessionId);
     }
     return this.harnessCwd(record);
@@ -1053,13 +1111,13 @@ export class SessionEngine {
           });
         }
         // The harness only loads the scaffolded AGENTS.md when the session
-        // workspace is its own project root. With a per-session cwd override
-        // (PR worktree) the scaffold lands elsewhere, and a workspace nested
-        // inside a git repo re-roots harness rules at that repo — in both
-        // cases deliver instructions inline on the first turn instead.
+        // workspace is its own project root. When the harness cwd is borrowed
+        // (PR worktree, shared checkout) the scaffold lands elsewhere, and a
+        // workspace nested inside a git repo re-roots harness rules at that
+        // repo — in both cases deliver instructions inline on the first turn.
         const instructionsInvisibleToHarness =
           isFirstTurn &&
-          (record.workspaceOverride !== undefined ||
+          (this.hasBorrowedWorkspace(record) ||
             (await isNestedInGitRepo(harnessCwd)));
         const request = this.buildTurnRequest(
           record,
@@ -1201,10 +1259,10 @@ export class SessionEngine {
         turnPrompt = `${preamble}\n\n${turnPrompt}`;
       } else if (instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
-        // per-session harness cwd override, agent tool scripts live only in
-        // the durable scaffold dir — embed bodies like cloud. Otherwise the
-        // catalog can reference on-disk paths under the harness cwd.
-        const includeScripts = record.workspaceOverride !== undefined;
+        // borrowed harness cwd, agent tool scripts live only in the durable
+        // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+        // reference on-disk paths under the harness cwd.
+        const includeScripts = this.hasBorrowedWorkspace(record);
         const preamble = buildAgentsMdContent(agent, { includeScripts });
         turnPrompt = `${preamble}\n\n${turnPrompt}`;
       }
@@ -1215,6 +1273,7 @@ export class SessionEngine {
         ? {}
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
+      sandbox: this.project.agent.local?.sandbox === true,
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,
@@ -1224,12 +1283,7 @@ export class SessionEngine {
       customTools:
         runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {},
       mcpServers: this.buildMcpServers(runtime),
-      subagents: agent.subagents.map((subagent) => ({
-        name: subagent.name,
-        description: subagent.description ?? subagent.name,
-        prompt: subagentPrompt(subagent),
-        ...(subagent.model === undefined ? {} : { model: subagent.model }),
-      })),
+      subagents: buildRunnerSubagents(agent),
       onUpdate,
       signal,
       // Local follow-ups expire any lingering active run so a preempted turn
@@ -2509,6 +2563,20 @@ function subagentPrompt(subagent: ResolvedAgent): string {
   return subagent.description ?? subagent.name;
 }
 
+/**
+ * Subagents as the runner takes them. Shared by turns and by workspace
+ * warming, which has to describe the same agent a turn would to reach the
+ * executor that turn will run on.
+ */
+function buildRunnerSubagents(agent: ResolvedAgent): RunnerSubagent[] {
+  return agent.subagents.map((subagent) => ({
+    name: subagent.name,
+    description: subagent.description ?? subagent.name,
+    prompt: subagentPrompt(subagent),
+    ...(subagent.model === undefined ? {} : { model: subagent.model }),
+  }));
+}
+
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }