@cursor/july 0.1.5 → 0.1.6

package/src/internal/resolve-prod-target.ts

@@ -48,6 +48,29 @@ export interface ResolvedProdTarget {
   expiresAt: string;
 }
 
+/**
+ * Thrown when a hosted deployment cannot be resolved. `notFound` is true
+ * when the deployment does not exist, so callers can suggest deploying
+ * (or running locally) instead of surfacing a bare API error.
+ */
+export class ProdTargetError extends Error {
+  constructor(
+    message: string,
+    readonly options: { slug: string; notFound?: boolean } = { slug: "" }
+  ) {
+    super(message);
+    this.name = "ProdTargetError";
+  }
+
+  get slug(): string {
+    return this.options.slug;
+  }
+
+  get notFound(): boolean {
+    return this.options.notFound === true;
+  }
+}
+
 /**
  * Look up a running deployment and return its engineAccess URL/headers.
  * Throws {@link Error} with a CLI-ready message on failure.
@@ -65,8 +88,10 @@ export async function resolveProdTarget(
     err,
   });
   if (typeof auth === "number") {
+    // Not "--prod": `eval` resolves the hosted deployment by default,
+    // without any flag.
     throw new Error(
-      `Could not resolve Cursor credentials/team for --prod (see above).`
+      `Could not resolve Cursor credentials/team for the hosted deployment (see above).`
     );
   }
 
@@ -83,8 +108,9 @@ export async function resolveProdTarget(
       });
     } catch (error) {
       if (error instanceof DeployApiError) {
-        throw new Error(
-          `Deployment "${slug}" (team ${auth.teamId}): ${error.message}`
+        throw new ProdTargetError(
+          `Deployment "${slug}" (team ${auth.teamId}): ${error.message}`,
+          { slug, notFound: error.status === 404 }
         );
       }
       throw error;
@@ -143,6 +169,78 @@ export async function resolveProdTarget(
   };
 }
 
+export interface ResolvedProdAliasPlayground {
+  /** Hosted playground URL on the API alias (SPA owns alias-token sign-in). */
+  playgroundUrl: string;
+  slug: string;
+}
+
+/**
+ * Look up a running deployment and return its stable alias playground URL.
+ * Does not mint `engineAccess` — the browser signs in with the alias token.
+ * Throws {@link Error} with a CLI-ready message on failure.
+ */
+export async function resolveProdAliasPlaygroundUrl(
+  options: ResolveProdTargetOptions & { sessionId?: string }
+): Promise<ResolvedProdAliasPlayground> {
+  const err =
+    options.err ?? ((text: string) => void process.stderr.write(text));
+  const slug = resolveProdSlug(options);
+  const auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+    err,
+  });
+  if (typeof auth === "number") {
+    throw new Error(
+      `Could not resolve Cursor credentials/team for the hosted deployment (see above).`
+    );
+  }
+
+  let detail: DeploymentDetail;
+  try {
+    detail = await auth.client.getDeployment({
+      teamId: auth.teamId,
+      slug,
+    });
+  } catch (error) {
+    if (error instanceof DeployApiError) {
+      throw new Error(
+        `Deployment "${slug}" (team ${auth.teamId}): ${error.message}`
+      );
+    }
+    throw error;
+  }
+
+  const statusOk = detail.status === "running" || detail.status === "degraded";
+  if (!statusOk) {
+    const lastError =
+      detail.lastError === null || detail.lastError === undefined
+        ? ""
+        : ` ${sanitizeCustomerFacingDetail(detail.lastError)}`;
+    throw new Error(
+      `Deployment "${slug}" is ${detail.status}, not running.${lastError}\n` +
+        `Deploy or wait: \`${CLI} deploy --slug ${slug}\` / \`${CLI} deployment ${slug}\``
+    );
+  }
+
+  const aliasBase = auth.client.aliasUrl(detail.engineAlias).replace(/\/$/, "");
+  const base = `${aliasBase}/playground`;
+  const sessionId =
+    options.sessionId !== undefined && options.sessionId.trim() !== ""
+      ? options.sessionId.trim()
+      : undefined;
+  const playgroundUrl =
+    sessionId === undefined
+      ? base
+      : `${base}?sessionId=${encodeURIComponent(sessionId)}`;
+
+  err(`${stderrPalette().dim(`Using hosted deployment "${slug}".`)}\n`);
+
+  return { playgroundUrl, slug };
+}
+
 /** Strip obvious hosting internals from customer-facing error fragments. */
 function sanitizeCustomerFacingDetail(message: string): string {
   return message

package/src/internal/server.ts

@@ -362,9 +362,8 @@ export async function startServer(
     const evalRuns = new EvalRunStore(
       project.rootDir,
       logger,
-      // defineStorage fallback for playground eval history; explicit
-      // `evals.config.ts` persistRuns still wins inside the store.
-      engine.storage?.asEvalRunPersistence()
+      // Playground eval history mirrors onto the defineStorage evals table.
+      engine.storage?.evalRuns()
     );
     // Eval history restores with the same startup step as sessions (reads
     // also hydrate lazily, but doing it here surfaces store problems at
@@ -738,6 +737,9 @@ export async function startServer(
       for (const runtime of runtimes) {
         runtime.scheduleRunner.stop();
         runtime.reminderRunner.stop();
+        // Before the engines close their storage coordinators, so the
+        // interrupted-batch write can still reach the sink.
+        runtime.evalRuns.close();
       }
       for (const stop of channelStopHooks) {
         try {

package/src/internal/session-engine.ts

@@ -204,8 +204,7 @@ export class SessionEngine {
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
    * records, event chunks, A/B samples/snapshots); the eval run store
-   * attaches via {@link StorageCoordinator.asEvalRunPersistence} at
-   * serve start.
+   * attaches via {@link StorageCoordinator.evalRuns} at serve start.
    */
   readonly storage: StorageCoordinator | undefined;
   /** In-flight lazy restores, deduped per channel + continuation key. */
@@ -261,18 +260,12 @@ export class SessionEngine {
             projectRoot: options.project.rootDir,
             logger: this.logger,
           });
-    // Domain-specific hooks win; the defineStorage sink is the fallback.
-    const persistSamples =
-      options.project.abConfig?.persistSamples ??
-      this.storage?.asABSamplePersistence();
     this.abCollector = new ABCollector(
       options.project.abs,
       this.logger,
       async (sessionId) => (await this.logs.get(sessionId)).snapshot(0),
-      {
-        projectRoot: options.project.rootDir,
-        persistSamples,
-      }
+      // Samples flow to the defineStorage `abs` table (no-op without one).
+      { persistSample: (sample) => this.storage?.abSample(sample) }
     );
     // Peer and Cursor-account transports are symbolic until the serve host
     // resolves them; the host-side MCP registry starts with the concrete
@@ -1592,6 +1585,7 @@ export class SessionEngine {
         return restoredSnapshot;
       }
     }
+    const abTable = this.project.storage?.abs;
     const snapshot = await buildABSnapshot({
       experiments: this.project.abs,
       agentName: this.project.name,
@@ -1602,27 +1596,13 @@ export class SessionEngine {
       logger: this.logger,
       config: {
         maxPlaygroundSessions,
-        durableSamples: abConfig?.persistSamples !== undefined,
-        durableSnapshots: abConfig?.persistSnapshots !== undefined,
+        durableSamples: abTable !== undefined,
+        durableSnapshots: abTable?.putSnapshot !== undefined,
       },
     });
-    // Side effect on the read path: playground polls GET /v1/abs ~every 4s.
-    // Authors who set persistSnapshots accept that write cadence.
-    const persistSnapshots = abConfig?.persistSnapshots;
-    if (persistSnapshots !== undefined) {
-      try {
-        await persistSnapshots.save(snapshot, {
-          projectRoot: this.project.rootDir,
-        });
-      } catch (error) {
-        this.logger(
-          `[agentkit] ab persistSnapshots.save threw: ${describeError(error)}`
-        );
-      }
-    } else {
-      // defineStorage fallback (throttled inside the coordinator).
-      this.storage?.abSnapshot(snapshot);
-    }
+    // Side effect on the read path: playground polls GET /v1/abs ~every 4s;
+    // the coordinator throttles the actual table write.
+    this.storage?.abSnapshot(snapshot);
     return snapshot;
   }
 

package/src/internal/storage-coordinator.ts

@@ -10,13 +10,13 @@
  * failures — a throwing sink is logged and its write dropped; storage
  * must never stall or fail a turn.
  *
- * Scaling shape: sessions, reminders, evals, and A/Bs all reduce to keyed
- * puts on the same queue, so one author-owned sink covers every domain,
- * and new domains are new key prefixes — not new config surface.
+ * Scaling shape: sessions and reminders reduce to keyed puts on the KV
+ * sink; eval runs and A/B metrics go to their dedicated tables
+ * (`evals` / `abs`). Everything shares one bounded, serialized queue.
  */
 
-import type { ABMetricSample, ABSamplePersistence } from "../ab.js";
-import type { EvalRunPersistence, EvalRunSnapshot } from "../evals.js";
+import type { ABMetricSample } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
 import {
   type ResolvedStoragePolicy,
   resolveStoragePolicy,
@@ -27,6 +27,7 @@ import {
 import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
+import type { EvalRunStorage } from "./eval-run-store.js";
 import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
 
 /** Event types that close a unit of work — flush point for turn-end batching. */
@@ -62,10 +63,12 @@ const DEBOUNCE_MAX_BATCH = 200;
  */
 const AB_SNAPSHOT_MIN_INTERVAL_MS = 60_000;
 
-/** One queued sink call. */
-type StorageOp =
-  | { op: "put"; key: string; value: JsonValue }
-  | { op: "delete"; key: string };
+/** One queued sink call (KV put/delete or a dedicated-table write). */
+interface StorageOp {
+  /** Human-readable op label for failure logs, e.g. `put(agentkit/v1/...)`. */
+  label: string;
+  run: (ctx: StorageContext) => void | Promise<void>;
+}
 
 export interface StorageCoordinatorOptions {
   definition: StorageDefinition;
@@ -182,18 +185,20 @@ export class StorageCoordinator {
     const ops: StorageOp[] = [];
     const first = buffer.events[0];
     if (first !== undefined) {
-      ops.push({
-        op: "put",
-        key: storageKeys.sessionEvents(this.agentName, sessionId, first.index),
-        value: buffer.events as unknown as JsonValue,
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.sessionEvents(this.agentName, sessionId, first.index),
+          buffer.events as unknown as JsonValue
+        )
+      );
     }
     if (buffer.record !== undefined) {
-      ops.push({
-        op: "put",
-        key: storageKeys.session(this.agentName, sessionId),
-        value: buffer.record as unknown as JsonValue,
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.session(this.agentName, sessionId),
+          buffer.record as unknown as JsonValue
+        )
+      );
       ops.push(...this.continuationOps(buffer.record));
     }
     if (ops.length > 0) {
@@ -214,25 +219,39 @@ export class StorageCoordinator {
     this.continuationIndex.set(record.sessionId, next);
     const ops: StorageOp[] = [];
     if (previous != null) {
-      ops.push({
-        op: "delete",
-        key: storageKeys.continuation(
-          this.agentName,
-          record.channelId,
-          previous
-        ),
-      });
+      ops.push(
+        this.deleteOp(
+          storageKeys.continuation(this.agentName, record.channelId, previous)
+        )
+      );
     }
     if (next != null) {
-      ops.push({
-        op: "put",
-        key: storageKeys.continuation(this.agentName, record.channelId, next),
-        value: { sessionId: record.sessionId },
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.continuation(this.agentName, record.channelId, next),
+          { sessionId: record.sessionId }
+        )
+      );
     }
     return ops;
   }
 
+  /** KV upsert op on the sink's `put`. */
+  private putOp(key: string, value: JsonValue): StorageOp {
+    return {
+      label: `put(${key})`,
+      run: (ctx) => this.definition.put(key, value, ctx),
+    };
+  }
+
+  /** KV delete op on the sink's `delete` (skipped when the hook is absent). */
+  private deleteOp(key: string): StorageOp {
+    return {
+      label: `delete(${key})`,
+      run: (ctx) => this.definition.delete?.(key, ctx),
+    };
+  }
+
   // ==========================================================================
   // Sessions (reads / restore)
   // ==========================================================================
@@ -351,11 +370,10 @@ export class StorageCoordinator {
     }
     this.enqueue(
       [
-        {
-          op: "put",
-          key: storageKeys.reminder(this.agentName, record.id),
-          value: record as unknown as JsonValue,
-        },
+        this.putOp(
+          storageKeys.reminder(this.agentName, record.id),
+          record as unknown as JsonValue
+        ),
       ],
       "policy"
     );
@@ -375,31 +393,29 @@ export class StorageCoordinator {
   }
 
   // ==========================================================================
-  // Evals
+  // Evals (dedicated `evals` table)
   // ==========================================================================
 
   /**
-   * Adapter for {@link EvalRunPersistence} so the playground eval store
-   * can fall back to this sink when `evals.config.ts` sets no
-   * `persistRuns`.
+   * Adapter over the sink's dedicated `evals` table for the playground
+   * eval-run store. Undefined when the table is not configured — eval
+   * history then stays in process memory.
    */
-  asEvalRunPersistence(): EvalRunPersistence {
+  evalRuns(): EvalRunStorage | undefined {
+    const table = this.definition.evals;
+    if (table === undefined) {
+      return undefined;
+    }
     return {
-      load: async () => {
-        const entries = await this.tryList(
-          storageKeys.evalRunPrefix(this.agentName)
-        );
-        return entries
-          .map((entry) => entry.value as unknown as EvalRunSnapshot)
-          .filter((run) => run != null);
-      },
       save: (run: EvalRunSnapshot) => {
+        // Clone at enqueue time: the store mutates snapshots in place as
+        // cases finish, and delivery is async.
+        const snapshot = structuredClone(run);
         this.enqueue(
           [
             {
-              op: "put",
-              key: storageKeys.evalRun(this.agentName, run.runId),
-              value: run as unknown as JsonValue,
+              label: `evals.put(${run.runId})`,
+              run: (ctx) => table.put(snapshot, ctx),
             },
           ],
           "policy"
@@ -409,86 +425,82 @@ export class StorageCoordinator {
         this.enqueue(
           [
             {
-              op: "delete",
-              key: storageKeys.evalRun(this.agentName, runId),
+              label: `evals.delete(${runId})`,
+              run: (ctx) => table.delete(runId, ctx),
             },
           ],
           "policy"
         );
       },
+      list: async () => {
+        try {
+          const runs = await table.list(this.context("restore"));
+          return Array.isArray(runs) ? runs : [];
+        } catch (error) {
+          this.logger(
+            `[agentkit] storage evals.list() failed: ${describeError(error)}`
+          );
+          return [];
+        }
+      },
     };
   }
 
   // ==========================================================================
-  // A/Bs
+  // A/Bs (dedicated `abs` table)
   // ==========================================================================
 
-  /**
-   * Adapter for {@link ABSamplePersistence} so the AB collector can fall
-   * back to this sink when `ab.config.ts` sets no `persistSamples`.
-   */
-  asABSamplePersistence(): ABSamplePersistence {
-    return {
-      save: (sample: ABMetricSample) => {
-        this.enqueue(
-          [
-            {
-              op: "put",
-              key: storageKeys.abSample(
-                this.agentName,
-                sample.sessionId,
-                sample.at
-              ),
-              value: sample as unknown as JsonValue,
-            },
-          ],
-          "policy"
-        );
-      },
-    };
+  /** Append one metric sample to the `abs` table (no-op without it). */
+  abSample(sample: ABMetricSample): void {
+    const table = this.definition.abs;
+    if (this.closed || table === undefined) {
+      return;
+    }
+    this.enqueue(
+      [
+        {
+          label: `abs.putSample(${sample.sessionId})`,
+          run: (ctx) => table.putSample(sample, ctx),
+        },
+      ],
+      "policy"
+    );
   }
 
   /**
    * Refresh the persisted aggregate A/B snapshot, throttled to once per
    * {@link AB_SNAPSHOT_MIN_INTERVAL_MS} (the playground recomputes the
-   * fold on every `GET /v1/abs` poll).
+   * fold on every `GET /v1/abs` poll). No-op without `abs.putSnapshot`.
    */
   abSnapshot(snapshot: ABSnapshot): void {
+    const putSnapshot = this.definition.abs?.putSnapshot;
     const now = Date.now();
     if (
       this.closed ||
+      putSnapshot === undefined ||
       now - this.lastAbSnapshotAt < AB_SNAPSHOT_MIN_INTERVAL_MS
     ) {
       return;
     }
     this.lastAbSnapshotAt = now;
     this.enqueue(
-      [
-        {
-          op: "put",
-          key: storageKeys.abSnapshot(this.agentName),
-          value: snapshot as unknown as JsonValue,
-        },
-      ],
+      [{ label: "abs.putSnapshot", run: (ctx) => putSnapshot(snapshot, ctx) }],
       "policy"
     );
   }
 
   /** Latest persisted aggregate A/B snapshot; errors read as absent. */
   async getLatestAbSnapshot(): Promise<ABSnapshot | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
+    const getSnapshot = this.definition.abs?.getSnapshot;
+    if (getSnapshot === undefined) {
       return undefined;
     }
     try {
-      const value = await get(
-        storageKeys.abSnapshot(this.agentName),
-        this.context("restore")
-      );
-      return value == null ? undefined : (value as unknown as ABSnapshot);
+      const value = await getSnapshot(this.context("restore"));
+      return value ?? undefined;
     } catch (error) {
       this.logger(
-        `[agentkit] storage get(ab-snapshot) failed: ${describeError(error)}`
+        `[agentkit] storage abs.getSnapshot() failed: ${describeError(error)}`
       );
       return undefined;
     }
@@ -593,14 +605,10 @@ export class StorageCoordinator {
     this.queue = this.queue.then(async () => {
       for (const op of ops) {
         try {
-          if (op.op === "put") {
-            await this.definition.put(op.key, op.value, ctx);
-          } else {
-            await this.definition.delete?.(op.key, ctx);
-          }
+          await op.run(ctx);
         } catch (error) {
           this.logger(
-            `[agentkit] storage ${op.op}(${op.key}) failed: ${describeError(error)}`
+            `[agentkit] storage ${op.label} failed: ${describeError(error)}`
           );
         } finally {
           this.pending -= 1;