@cursor/july 0.1.16 → 0.1.17

package/dist/internal/local-env.js

@@ -0,0 +1,47 @@
+/**
+ * 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();
+export function loadAgentLocalEnv(dir) {
+    for (const key of fileLoadedKeys) {
+        delete process.env[key];
+    }
+    const realKeys = new Set(Object.keys(process.env));
+    const loaded = [];
+    const tryLoad = (path) => {
+        if (!existsSync(path)) {
+            return;
+        }
+        process.loadEnvFile(path);
+        loaded.push(path);
+    };
+    const trackLoadedKeys = () => {
+        fileLoadedKeys = new Set(Object.keys(process.env).filter((key) => !realKeys.has(key)));
+    };
+    tryLoad(join(dir, ".env.local"));
+    let children;
+    try {
+        children = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+            .map((entry) => entry.name);
+    }
+    catch (_a) {
+        trackLoadedKeys();
+        return loaded;
+    }
+    for (const child of children) {
+        if (child === "node_modules") {
+            continue;
+        }
+        tryLoad(join(dir, child, ".env.local"));
+    }
+    trackLoadedKeys();
+    return loaded;
+}

package/dist/internal/playground/static.d.ts

@@ -18,6 +18,9 @@ export declare 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 declare function renderPlaygroundIndexHtml(baseHref: string): string;
 /** Serve one built asset from `dist/playground/assets/` by filename. */

package/dist/internal/playground/static.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../../src/internal/playground/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBvD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUlE;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAsB5D;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAiBvE"}
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../../src/internal/playground/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBvD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUlE;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAsB5D;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAiBvE"}

package/dist/internal/playground/static.js

@@ -45,6 +45,9 @@ export function playgroundBundleExists() {
  * 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) {
     if (!playgroundBundleExists()) {

package/dist/internal/run-client.d.ts

@@ -34,6 +34,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;
 }
 /**
  * Run one or more messages against a live agent-serve base URL
@@ -43,6 +48,16 @@ export declare function runSession(options: RunClientOptions & {
     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). */

package/dist/internal/run-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-client.d.ts","sourceRoot":"","sources":["../../src/internal/run-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE,6EAA6E;AAC7E,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAF5B,YACE,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,EAI3B;CACF;AACD,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,EAAE,EAAE,OAAO,CAAC;CACb;AAQD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,gBAAgB,GAAG;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,gEAAgE;IAChE,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B,GACA,OAAO,CAAC,gBAAgB,CAAC,CAyD3B"}
+{"version":3,"file":"run-client.d.ts","sourceRoot":"","sources":["../../src/internal/run-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE,6EAA6E;AAC7E,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAF5B,YACE,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,EAI3B;CACF;AACD,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,gBAAgB,GAAG;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,gEAAgE;IAChE,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B,GACA,OAAO,CAAC,gBAAgB,CAAC,CA0D3B"}

package/dist/internal/run-client.js

@@ -35,6 +35,7 @@ const TERMINAL_TYPES = new Set([
  */
 export function runSession(options) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
         if (options.messages.length === 0) {
             throw new Error("runSession requires at least one message");
         }
@@ -42,7 +43,7 @@ export function runSession(options) {
         let sessionId = options.sessionId;
         let continuationToken = options.continuationToken;
         const allEvents = [];
-        let nextEventIndex = 0;
+        let nextEventIndex = (_a = options.startIndex) !== null && _a !== void 0 ? _a : 0;
         const auth = {
             bearerToken: options.bearerToken,
             headers: options.headers,
@@ -78,7 +79,7 @@ export function runSession(options) {
             throw new Error("server did not return a session id");
         }
         const trajectory = buildTrajectory(allEvents);
-        return Object.assign(Object.assign({ sessionId }, (continuationToken === undefined ? {} : { continuationToken })), { baseUrl, events: allEvents, trajectory, ok: trajectory.ok });
+        return Object.assign(Object.assign({ sessionId }, (continuationToken === undefined ? {} : { continuationToken })), { baseUrl, events: allEvents, trajectory, ok: trajectory.ok, nextEventIndex: allEvents.length === 0 ? undefined : nextEventIndex });
     });
 }
 function runOneTurn(args) {

package/dist/internal/sdk-runner.d.ts

@@ -5,13 +5,33 @@
  * settings; cloud agents use Cursor cloud (`bc-…` ids) with optional
  * `cloud` options from `defineAgent`.
  */
-import { type LocalAgentStore, type ModelSelection } from "@cursor/sdk";
+import { type LocalAgentStore, type ModelSelection, type RunResult } from "@cursor/sdk";
 import { type ModelSetting, type RunnerTurnRequest, type TurnOutcome } from "../types.js";
 /** 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;
+};
 export interface CursorSdkRunnerOptions {
     /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
     apiKey?: string;
@@ -28,10 +48,24 @@ export declare class CursorSdkRunner implements AgentRunner {
     private readonly options;
     private readonly agents;
     private readonly stores;
+    private readonly prewarmReleases;
     constructor(options?: CursorSdkRunnerOptions);
     runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+    /**
+     * 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.
+     */
+    prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
     dispose(): Promise<void>;
     private getAgent;
+    private requireApiKey;
+    private buildSharedOptions;
+    /**
+     * 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 buildLocalOptions;
     private openAgent;
     private openLocalAgent;
     private openCloudAgent;
@@ -47,4 +81,5 @@ export declare function isServerMintedCloudAgentId(id: string): boolean;
  */
 export declare function isLocalAgentNotFoundError(error: unknown, agentId: string): boolean;
 export declare function toModelSelection(model: ModelSetting): ModelSelection;
+export declare function runErrorMessage(result: Pick<RunResult, "error">): string;
 //# sourceMappingURL=sdk-runner.d.ts.map

package/dist/internal/sdk-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-runner.d.ts","sourceRoot":"","sources":["../../src/internal/sdk-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,cAAc,EAGpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,qBAAa,eAAgB,YAAW,WAAW;IAIrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;IAEtE,YAA6B,OAAO,GAAE,sBAA2B,EAAI;IAE/D,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0D9D;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ7B;IAED,OAAO,CAAC,QAAQ;YAYF,SAAS;YA2BT,cAAc;YAyCd,cAAc;IAqC5B,OAAO,CAAC,QAAQ;CAUjB;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAMT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAQpE"}
+{"version":3,"file":"sdk-runner.d.ts","sourceRoot":"","sources":["../../src/internal/sdk-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,iBAAiB,EACf,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,YAAY,GACZ,WAAW,GACX,OAAO,CACV,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAcxD,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,qBAAa,eAAgB,YAAW,WAAW;IAKrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAElE,YAA6B,OAAO,GAAE,sBAA2B,EAAI;IAE/D,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0D9D;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAepE;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAU7B;IAED,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,kBAAkB;IAc1B;;;OAGG;YACW,iBAAiB;YAkBjB,SAAS;YAOT,cAAc;YA6Bd,cAAc;IAqC5B,OAAO,CAAC,QAAQ;CAUjB;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAMT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAQpE;AAmED,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,MAAM,CAExE"}

package/dist/internal/sdk-runner.js

@@ -15,13 +15,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { mkdir } from "node:fs/promises";
-import { Agent, JsonlLocalAgentStore, } from "@cursor/sdk";
+import { Agent, createAgentPlatform, JsonlLocalAgentStore, } from "@cursor/sdk";
 import { DEFAULT_MODEL, } from "../types.js";
 export class CursorSdkRunner {
     constructor(options = {}) {
         this.options = options;
         this.agents = new Map();
         this.stores = new Map();
+        this.prewarmReleases = [];
     }
     runTurn(request) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -79,8 +80,30 @@ export class CursorSdkRunner {
             }
         });
     }
+    /**
+     * 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.
+     */
+    prewarm(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const platform = (yield createAgentPlatform());
+            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 = yield platform.prewarmLocalWorkspace(yield this.buildLocalOptions(request));
+            this.prewarmReleases.push(release);
+            return { warmed: true };
+        });
+    }
     dispose() {
         return __awaiter(this, void 0, void 0, function* () {
+            const releases = this.prewarmReleases.splice(0);
+            yield Promise.allSettled(releases.map((release) => release()));
             const agents = yield Promise.allSettled([...this.agents.values()]);
             this.agents.clear();
             for (const settled of agents) {
@@ -101,37 +124,50 @@ export class CursorSdkRunner {
         }
         return agentPromise;
     }
+    requireApiKey() {
+        var _a;
+        const apiKey = (_a = this.options.apiKey) !== null && _a !== void 0 ? _a : 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 }).");
+        }
+        return apiKey;
+    }
+    buildSharedOptions(request) {
+        var _a;
+        const subagents = toAgentDefinitions(request.subagents);
+        return Object.assign(Object.assign({ model: toModelSelection((_a = request.model) !== null && _a !== void 0 ? _a : DEFAULT_MODEL), apiKey: this.requireApiKey() }, (Object.keys(request.mcpServers).length > 0
+            ? { mcpServers: request.mcpServers }
+            : {})), (subagents === undefined ? {} : { agents: subagents }));
+    }
+    /**
+     * 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.
+     */
+    buildLocalOptions(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const store = (_a = this.options.store) !== null && _a !== void 0 ? _a : (yield this.getStore(request.runnerStateDir));
+            return Object.assign(Object.assign({}, this.buildSharedOptions(request)), { local: Object.assign({ cwd: request.workspaceDir, settingSources: ["project"], store }, (request.sandbox === true
+                    ? { sandboxOptions: { enabled: true } }
+                    : {})) });
+        });
+    }
     openAgent(request) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            const apiKey = (_a = this.options.apiKey) !== null && _a !== void 0 ? _a : 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 = (_b = request.model) !== null && _b !== void 0 ? _b : DEFAULT_MODEL;
-            const subagents = toAgentDefinitions(request.subagents);
-            const shared = Object.assign(Object.assign({ model: toModelSelection(model), apiKey }, (Object.keys(request.mcpServers).length > 0
-                ? { mcpServers: request.mcpServers }
-                : {})), (subagents === undefined ? {} : { agents: subagents }));
             if (request.runtime === "cloud") {
-                return this.openCloudAgent(request, shared);
+                return this.openCloudAgent(request, this.buildSharedOptions(request));
             }
-            return this.openLocalAgent(request, shared);
+            return this.openLocalAgent(request);
         });
     }
-    openLocalAgent(request, shared) {
+    openLocalAgent(request) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
-            const store = (_a = this.options.store) !== null && _a !== void 0 ? _a : (yield this.getStore(request.runnerStateDir));
-            const options = Object.assign(Object.assign({}, shared), { local: {
-                    cwd: request.workspaceDir,
-                    settingSources: ["project"],
-                    store,
-                } });
+            var _a, _b, _c;
+            const options = yield this.buildLocalOptions(request);
             if (request.isFirstTurn || request.sdkAgentId === undefined) {
-                return Agent.create(Object.assign(Object.assign({}, options), { agentId: (_b = request.sdkAgentId) !== null && _b !== void 0 ? _b : request.sessionId }));
+                return Agent.create(Object.assign(Object.assign({}, options), { agentId: (_a = request.sdkAgentId) !== null && _a !== void 0 ? _a : request.sessionId }));
             }
-            const agentId = (_c = request.sdkAgentId) !== null && _c !== void 0 ? _c : request.sessionId;
+            const agentId = (_b = request.sdkAgentId) !== null && _b !== void 0 ? _b : request.sessionId;
             try {
                 return yield Agent.resume(agentId, options);
             }
@@ -144,7 +180,7 @@ export class CursorSdkRunner {
                 // 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.
-                ((_d = this.options.logger) !== null && _d !== void 0 ? _d : (() => { }))(`[agentkit] no stored conversation for ${agentId} on this host; starting a fresh one`);
+                ((_c = this.options.logger) !== null && _c !== void 0 ? _c : (() => { }))(`[agentkit] no stored conversation for ${agentId} on this host; starting a fresh one`);
                 return Agent.create(Object.assign(Object.assign({}, options), { agentId }));
             }
         });
@@ -242,6 +278,10 @@ function toTurnOutcome(result) {
             ? {}
             : { reasoningTokens: result.usage.reasoningTokens }));
     return Object.assign(Object.assign(Object.assign({ status: result.status }, (result.result === undefined ? {} : { result: result.result })), (result.status === "error"
-        ? { errorMessage: "The Cursor agent run failed" }
+        ? { errorMessage: runErrorMessage(result) }
         : {})), (usage === undefined ? {} : { usage }));
 }
+export function runErrorMessage(result) {
+    var _a, _b;
+    return ((_b = (_a = result.error) === null || _a === void 0 ? void 0 : _a.message) === null || _b === void 0 ? void 0 : _b.trim()) || "The Cursor agent run failed";
+}

package/dist/internal/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAqFrB,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAapE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAYD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAmpB3B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAqFrB,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAapE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAYD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAypB3B"}

package/dist/internal/server.js

@@ -241,6 +241,11 @@ export function startServer(mounts_1) {
             // Rehydrate sessions from the authored storage sink before any
             // channel or route can address them (continuation tokens must resolve).
             yield 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.
@@ -687,7 +692,11 @@ function mountAgentRoutes(router, runtime, args) {
         method: "GET",
         pattern: `${base}/v1/meta`,
         auth: "none",
-        handler: () => jsonResponse(Object.assign({ name: project.name, dev, basePath: base }, (multi ? { indexPath: "/" } : {}))),
+        handler: () => jsonResponse(Object.assign({ 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: "/" } : {}))),
     });
     router.add({
         method: "GET",

package/dist/internal/session-engine.d.ts

@@ -227,15 +227,28 @@ export declare class SessionEngine {
     getContinuationLastBotMessageTs(channelId: string, continuationToken: string): Promise<string | undefined>;
     interruptContinuation(channelId: string, continuationToken: string): Promise<boolean>;
     /**
-     * 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;
     /**
-     * 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;
+    /**
+     * 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.
+     */
+    prewarmSharedWorkspace(): Promise<void>;
+    /** Directory that receives AGENTS.md / skills / agent tools. */
     private scaffoldDir;
     private executeTurn;
     private buildTurnRequest;

package/dist/internal/session-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-engine.d.ts","sourceRoot":"","sources":["../../src/internal/session-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-engine.d.ts","sourceRoot":"","sources":["../../src/internal/session-engine.ts"],"names":[],"mappings":"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"}

package/dist/internal/session-engine.js

@@ -666,27 +666,72 @@ 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) {
-        var _a;
+        var _a, _b;
         if (record.workspaceOverride !== undefined) {
             return record.workspaceOverride;
         }
-        const agentCwd = (_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.cwd;
+        const shared = (_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir;
+        if (shared !== undefined) {
+            return shared;
+        }
+        const agentCwd = (_b = this.project.agent.local) === null || _b === void 0 ? void 0 : _b.cwd;
         if (agentCwd !== undefined) {
             return join(agentCwd, record.sessionId);
         }
         return this.sessions.workspaceDir(record.sessionId);
     }
     /**
-     * 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.
+     */
+    hasBorrowedWorkspace(record) {
+        var _a;
+        return (record.workspaceOverride !== undefined ||
+            ((_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.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.
      */
+    prewarmSharedWorkspace() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const agent = this.project.agent;
+            const workspaceDir = (_a = agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir;
+            if (workspaceDir === undefined ||
+                agent.runtime !== "local" ||
+                this.runner.prewarm === undefined) {
+                return;
+            }
+            const startedAt = Date.now();
+            try {
+                const outcome = yield this.runner.prewarm(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.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. */
     scaffoldDir(record) {
-        if (record.workspaceOverride !== undefined) {
+        if (this.hasBorrowedWorkspace(record)) {
             return this.sessions.workspaceDir(record.sessionId);
         }
         return this.harnessCwd(record);
@@ -752,12 +797,12 @@ 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) ||
                             (yield isNestedInGitRepo(harnessCwd)));
                     const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
                         mapper.handleUpdate(update);
@@ -833,7 +878,7 @@ export class SessionEngine {
         });
     }
     buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal) {
-        var _a, _b;
+        var _a, _b, _c;
         // Per-session cloud attach (channel/tool handoff) forces cloud runtime
         // even when the agent defaults to local for chat server tools.
         const runtime = resolveSessionRuntime({
@@ -865,17 +910,17 @@ export class SessionEngine {
             }
             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}`;
             }
         }
         return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
             ? {}
-            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime), subagents: agent.subagents.map((subagent) => { var _a; return (Object.assign({ name: subagent.name, description: (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name, prompt: subagentPrompt(subagent) }, (subagent.model === undefined ? {} : { model: subagent.model }))); }), onUpdate,
+            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true, runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime), subagents: buildRunnerSubagents(agent), onUpdate,
             signal, 
             // Local follow-ups expire any lingering active run so a preempted turn
             // (or one orphaned by a crashed process) never blocks this send.
@@ -1897,6 +1942,14 @@ function subagentPrompt(subagent) {
     }
     return (_a = subagent.description) !== null && _a !== void 0 ? _a : 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) {
+    return agent.subagents.map((subagent) => { var _a; return (Object.assign({ name: subagent.name, description: (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name, prompt: subagentPrompt(subagent) }, (subagent.model === undefined ? {} : { model: subagent.model }))); });
+}
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }