@cursor/july 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/ab.ts

@@ -10,9 +10,8 @@
  *
  * Assignments and foldable metrics live in each session's `events.ndjson`
  * (survive serve restart). Optional project defaults in `agent/ab.config.ts`
- * ({@link defineABConfig}) let authors retain the playground fold window and
- * persist samples / aggregate snapshots wherever they like — same idea as
- * eval `persistRuns`.
+ * ({@link defineABConfig}) cap the playground fold window; durable
+ * sample/snapshot export lives on the `defineStorage` `abs` table.
  *
  * ```ts
  * import { defineAB, splitBySessionHash } from "@anysphere/agent-serve/ab";
@@ -31,20 +30,8 @@
  * ```
  */
 
-import { randomUUID } from "node:crypto";
-import { appendFile, mkdir } from "node:fs/promises";
-import { join } from "node:path";
-import type { ABSnapshot } from "./internal/ab-snapshot.js";
 import { normalizePositiveInt } from "./internal/bounded-int.js";
 import { brandDefinition } from "./internal/brand.js";
-import {
-  assertNonEmptyDir,
-  deleteFileInDir,
-  listJsonBasenames,
-  readJsonDir,
-  resolveProjectRelativeDir,
-  writeJsonFile,
-} from "./internal/json-dir-store.js";
 import type { SessionEvent, SessionInfo } from "./types.js";
 
 export type { ABSnapshot } from "./internal/ab-snapshot.js";
@@ -370,7 +357,7 @@ export function mergeABInstructions(
 }
 
 // ---------------------------------------------------------------------------
-// Project config (`agent/ab.config.ts`) — fold window + optional persistence
+// Project config (`agent/ab.config.ts`) — playground fold window
 // ---------------------------------------------------------------------------
 
 /** Default sessions folded into `GET /v1/abs` / the A/Bs tab. */
@@ -379,128 +366,36 @@ export const AB_DEFAULT_MAX_PLAYGROUND_SESSIONS = 200;
 /** Hard ceiling for {@link ABConfigFile.maxPlaygroundSessions}. */
 export const AB_MAX_PLAYGROUND_SESSIONS = 10_000;
 
-/** Default snapshot files kept when {@link ABConfigFile.persistSnapshots} is set. */
-export const AB_DEFAULT_RETAIN_SNAPSHOTS = 20;
-
-/** Hard ceiling for {@link ABConfigFile.retainSnapshots}. */
-export const AB_MAX_RETAIN_SNAPSHOTS = 500;
-
-/** Context passed to A/B persistence hooks. */
-export interface ABPersistContext {
-  /** Absolute agent project root (directory that contains `agent/`). */
-  projectRoot: string;
-}
-
-/**
- * Durable sink for {@link ABMetricSample} rows (same payload as
- * {@link ABConfig.onSample}). Session `events.ndjson` remains the source of
- * truth for assignment + fold; this is for analytics export.
- */
-export interface ABSamplePersistence {
-  save(sample: ABMetricSample, ctx: ABPersistContext): void | Promise<void>;
-}
-
-/**
- * Durable store for playground-style aggregate snapshots (`GET /v1/abs`).
- * Without this, aggregates are always recomputed from session logs (nothing
- * is kept after sessions are pruned).
- *
- * **Runtime note:** `serve` currently only calls {@link save} (after each
- * `GET /v1/abs`). {@link load} / {@link delete} are for author tooling or a
- * custom store; they are not wired into the playground hydrate path.
- */
-export interface ABSnapshotPersistence {
-  load(ctx: ABPersistContext): ABSnapshot[] | Promise<ABSnapshot[]>;
-  save(snapshot: ABSnapshot, ctx: ABPersistContext): void | Promise<void>;
-  delete?(snapshotId: string, ctx: ABPersistContext): void | Promise<void>;
-}
-
-/** Lets {@link defineABConfig} push `retainSnapshots` into {@link persistABSnapshotsToDir}. */
-const abSnapshotRetainState = new WeakMap<
-  ABSnapshotPersistence,
-  { retain: number }
->();
-
 /**
  * Project-wide A/B defaults (`agent/ab.config.ts`).
  *
  * **Assignments and foldable metrics** already persist in each session's
- * `events.ndjson` under `--state-root`. Use this config to:
- * - cap how many sessions the playground / `GET /v1/abs` folds
- * - export samples and/or aggregate snapshots to author-chosen storage
+ * `events.ndjson` under `--state-root`; durable sample/snapshot export
+ * lives on the `defineStorage` `abs` table (`agent/storage.ts`). This
+ * config only caps how many sessions the playground / `GET /v1/abs` folds.
  */
 export interface ABConfigFile {
   /**
    * Optional. Max newest sessions folded into **`GET /v1/abs` / the A/Bs
-   * tab** (and into {@link persistSnapshots} payloads). Does not prune
-   * session logs, change assignment, or limit {@link persistSamples}.
+   * tab**. Does not prune session logs or change assignment.
    *
    * Default {@link AB_DEFAULT_MAX_PLAYGROUND_SESSIONS}; hard-capped at
    * {@link AB_MAX_PLAYGROUND_SESSIONS}.
    */
   maxPlaygroundSessions?: number;
-  /**
-   * Snapshot-file budget when {@link persistSnapshots} is set.
-   * Default {@link AB_DEFAULT_RETAIN_SNAPSHOTS}; hard-capped at
-   * {@link AB_MAX_RETAIN_SNAPSHOTS}.
-   *
-   * When using {@link persistABSnapshotsToDir}, this value controls on-disk
-   * pruning (overriding the helper's `{ retain }` default). Custom stores
-   * should apply the same budget themselves.
-   */
-  retainSnapshots?: number;
-  /**
-   * Optional sink for cumulative metric samples (in addition to each
-   * experiment's {@link ABConfig.onSample}).
-   *
-   * ```ts
-   * persistSamples: persistABSamplesToDir(".agent-serve/ab-samples"),
-   * ```
-   */
-  persistSamples?: ABSamplePersistence;
-  /**
-   * Optional store for aggregate snapshots written when `GET /v1/abs` runs.
-   *
-   * ```ts
-   * persistSnapshots: persistABSnapshotsToDir(".agent-serve/ab-snapshots"),
-   * ```
-   */
-  persistSnapshots?: ABSnapshotPersistence;
 }
 
 /**
  * Defaults for every experiment under `agent/ab*` (`agent/ab.config.ts`).
  *
- * Session event logs remain the assignment/metrics source of truth; this
- * file controls the playground fold window and optional durable exports.
+ * Session event logs remain the assignment/metrics source of truth;
+ * durable exports go through the `defineStorage` `abs` table.
  */
 export function defineABConfig(config: ABConfigFile): ABConfigFile {
-  const persistSamples = normalizeSamplePersistence(config.persistSamples);
-  const persistSnapshots = normalizeSnapshotPersistence(
-    config.persistSnapshots
-  );
-  const helperRetain =
-    persistSnapshots !== undefined
-      ? abSnapshotRetainState.get(persistSnapshots)
-      : undefined;
-  let retainSnapshots: number | undefined;
-  if (config.retainSnapshots !== undefined) {
-    retainSnapshots = normalizeABRetainSnapshots(config.retainSnapshots);
-    if (helperRetain !== undefined) {
-      helperRetain.retain = retainSnapshots;
-    }
-  } else if (persistSnapshots !== undefined) {
-    retainSnapshots =
-      helperRetain?.retain ??
-      normalizeABRetainSnapshots(AB_DEFAULT_RETAIN_SNAPSHOTS);
-  }
   return {
     maxPlaygroundSessions: normalizeABMaxPlaygroundSessions(
       config.maxPlaygroundSessions ?? AB_DEFAULT_MAX_PLAYGROUND_SESSIONS
     ),
-    ...(retainSnapshots === undefined ? {} : { retainSnapshots }),
-    ...(persistSamples === undefined ? {} : { persistSamples }),
-    ...(persistSnapshots === undefined ? {} : { persistSnapshots }),
   };
 }
 
@@ -526,150 +421,3 @@ export function resolveABMaxPlaygroundSessions(value: unknown): number {
     return AB_DEFAULT_MAX_PLAYGROUND_SESSIONS;
   }
 }
-
-/** Validate {@link ABConfigFile.retainSnapshots}. */
-export function normalizeABRetainSnapshots(value: unknown): number {
-  return normalizePositiveInt(value, {
-    label: "ab.config.ts: retainSnapshots",
-    max: AB_MAX_RETAIN_SNAPSHOTS,
-  });
-}
-
-function normalizeSamplePersistence(
-  value: ABSamplePersistence | undefined
-): ABSamplePersistence | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (
-    typeof value !== "object" ||
-    value === null ||
-    typeof value.save !== "function"
-  ) {
-    throw new Error(
-      "ab.config.ts: persistSamples must define save(sample, ctx)"
-    );
-  }
-  return value;
-}
-
-function normalizeSnapshotPersistence(
-  value: ABSnapshotPersistence | undefined
-): ABSnapshotPersistence | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (
-    typeof value !== "object" ||
-    value === null ||
-    typeof value.load !== "function" ||
-    typeof value.save !== "function"
-  ) {
-    throw new Error(
-      "ab.config.ts: persistSnapshots must define load(ctx) and save(snapshot, ctx)"
-    );
-  }
-  if (value.delete !== undefined && typeof value.delete !== "function") {
-    throw new Error("ab.config.ts: persistSnapshots.delete must be a function");
-  }
-  return value;
-}
-
-/**
- * Append-only NDJSON {@link ABSamplePersistence} under `dir` (relative to
- * the agent project root).
- *
- * ```ts
- * // agent/ab.config.ts
- * export default defineABConfig({
- *   persistSamples: persistABSamplesToDir(".agent-serve/ab-samples"),
- * });
- * ```
- */
-export function persistABSamplesToDir(dir: string): ABSamplePersistence {
-  const relativeDir = assertNonEmptyDir(dir, "persistABSamplesToDir");
-  const resolveDir = (projectRoot: string): string =>
-    resolveProjectRelativeDir({ dir: relativeDir, projectRoot });
-
-  return {
-    async save(sample, ctx) {
-      const root = resolveDir(ctx.projectRoot);
-      await mkdir(root, { recursive: true });
-      await appendFile(
-        join(root, "samples.ndjson"),
-        `${JSON.stringify(sample)}\n`,
-        "utf8"
-      );
-    },
-  };
-}
-
-/**
- * Filesystem {@link ABSnapshotPersistence}: one JSON file per snapshot under
- * `dir`, pruned to `retain` files (default {@link AB_DEFAULT_RETAIN_SNAPSHOTS}).
- *
- * Prefer setting {@link ABConfigFile.retainSnapshots} in `defineABConfig` —
- * that value is applied to this helper's prune budget. Pass `{ retain }` here
- * only when constructing the helper outside `defineABConfig`, or as a default
- * that `retainSnapshots` may override.
- */
-export function persistABSnapshotsToDir(
-  dir: string,
-  options?: { retain?: number }
-): ABSnapshotPersistence {
-  const relativeDir = assertNonEmptyDir(dir, "persistABSnapshotsToDir");
-  const retainState = {
-    retain: normalizeABRetainSnapshots(
-      options?.retain ?? AB_DEFAULT_RETAIN_SNAPSHOTS
-    ),
-  };
-  const resolveDir = (projectRoot: string): string =>
-    resolveProjectRelativeDir({ dir: relativeDir, projectRoot });
-  let saveChain: Promise<void> = Promise.resolve();
-
-  const persist: ABSnapshotPersistence = {
-    async load(ctx) {
-      return readJsonDir<ABSnapshot>(resolveDir(ctx.projectRoot), {
-        sortBasenames: "desc",
-      });
-    },
-    async save(snapshot, ctx) {
-      const run = async (): Promise<void> => {
-        const root = resolveDir(ctx.projectRoot);
-        const snapshotId =
-          snapshot.config?.snapshotId ??
-          `absnap_${randomUUID().replace(/-/g, "")}`;
-        const toWrite: ABSnapshot = {
-          ...snapshot,
-          config: {
-            ...snapshot.config,
-            snapshotId,
-          },
-        };
-        await writeJsonFile({
-          root,
-          fileName: `${snapshotId}.json`,
-          value: toWrite,
-        });
-        const names = (await listJsonBasenames(root)).sort().reverse();
-        for (const stale of names.slice(retainState.retain)) {
-          await deleteFileInDir({ root, fileName: stale });
-        }
-      };
-      const next = saveChain.then(run, run);
-      saveChain = next.then(
-        () => undefined,
-        () => undefined
-      );
-      await next;
-    },
-    async delete(snapshotId, ctx) {
-      await deleteFileInDir({
-        root: resolveDir(ctx.projectRoot),
-        fileName: `${snapshotId}.json`,
-      });
-    },
-  };
-  abSnapshotRetainState.set(persist, retainState);
-  return persist;
-}

package/src/bin/agent-serve.ts

@@ -90,7 +90,7 @@ Usage:
   ${CLI} init        [dir] [--json]
   ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
                           [--tag <tag>]... [--verbose] [--timeout-ms <n>]
-                          [--no-stream] [--url <baseUrl> | --prod] [--slug <slug>]
+                          [--no-stream] [--local | --url <baseUrl>] [--slug <slug>]
                           [--team <id>]
   ${CLI} info        [--dir <path>] [--json]
   ${CLI} validate    [--dir <path>]
@@ -155,9 +155,11 @@ Commands:
               machine-readable and never blocks on login. No directory:
               print the setup guide.
   eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
-              Pass evalId args to select: one datapoint (weather/nyc), a whole
-              file (weather → all cases in that file), several of either, or
-              omit to run all.
+              Runs against the team's hosted deployment by default (slug from
+              --slug or the directory name); pass --local for an ephemeral
+              local server, or --url for a running one. Pass evalId args to
+              select: one datapoint (weather/nyc), a whole file (weather →
+              all cases in that file), several of either, or omit to run all.
   info        Print the discovered agent surface (tools, skills, channels, ...).
   validate    Check the project(s) and exit non-zero on error diagnostics.
   login       Sign the host in to Cursor: browser sign-in mints a named,
@@ -192,7 +194,7 @@ Agent loop:
   ${CLI} validate --dir .
   ${CLI} info --dir . --json
   ${CLI} run --dir . --message "..."
-  ${CLI} eval --dir .
+  ${CLI} eval --local --dir .
   ${CLI} dev .
 
 Options:
@@ -231,7 +233,10 @@ Options:
   --prod             chat/resume/run/call/eval/logs/sessions/session/playground:
                      use the team's hosted deployment. Slug from --slug or the
                      --dir basename. Mutually exclusive with --url. Requires
-                     \`${CLI} login\`.
+                     \`${CLI} login\`. (eval already defaults to the
+                     deployment; there --prod is just being explicit.)
+  --local            eval: run against an ephemeral local server instead of
+                     the hosted deployment. Mutually exclusive with --url.
   --once             logs: print current progress / log buffer once and exit
                      (default is to follow).
   --print            playground: print the URL only; do not open a browser.
@@ -347,6 +352,7 @@ async function main(argv: string[]): Promise<number> {
       "no-docs": { type: "boolean", default: false },
       url: { type: "string" },
       prod: { type: "boolean", default: false },
+      local: { type: "boolean", default: false },
       message: { type: "string", multiple: true },
       input: { type: "string" },
       "messages-file": { type: "string" },
@@ -628,6 +634,7 @@ async function main(argv: string[]): Promise<number> {
           tags: values.tag,
           url: values.url,
           prod: values.prod,
+          local: values.local,
           team: values.team,
           apiKey: values["api-key"],
           slug: values.slug,
@@ -1045,6 +1052,7 @@ function axFromOptions(
     toolInput: partial.toolInput,
     url: partial.url,
     prod: partial.prod,
+    local: partial.local,
     team: partial.team,
     apiKey: partial.apiKey,
     fetchImpl: partial.fetchImpl,

package/src/evals.ts

@@ -48,13 +48,6 @@
 
 import { normalizePositiveInt } from "./internal/bounded-int.js";
 import { brandDefinition } from "./internal/brand.js";
-import {
-  assertNonEmptyDir,
-  deleteFileInDir,
-  readJsonDir,
-  resolveProjectRelativeDir,
-  writeJsonFile,
-} from "./internal/json-dir-store.js";
 import type { SessionEvent } from "./types.js";
 
 export type Expectation =
@@ -322,35 +315,6 @@ export interface EvalRunSnapshot {
   };
 }
 
-/** Context passed to {@link EvalRunPersistence} hooks. */
-export interface EvalRunPersistContext {
-  /** Absolute agent project root (directory that contains `evals/`). */
-  projectRoot: string;
-}
-
-/**
- * Durable store for playground eval batches. Without {@link EvalConfigFile.persistRuns},
- * runs live only in the serve process memory — lost on restart, and capped by
- * {@link EvalConfigFile.maxPlaygroundRuns} (default {@link EVAL_DEFAULT_MAX_PLAYGROUND_RUNS}).
- *
- * Implement your own (S3, DB, …) or use {@link persistEvalRunsToDir}.
- * `delete` is required so {@link EvalConfigFile.maxPlaygroundRuns} can prune
- * durable history (otherwise pruned rows reload on the next hydrate).
- */
-export interface EvalRunPersistence {
-  /** Load saved runs (any order). Called once when the serve process hydrates. */
-  load(
-    ctx: EvalRunPersistContext
-  ): EvalRunSnapshot[] | Promise<EvalRunSnapshot[]>;
-  /**
-   * Persist a full snapshot. Called when a batch starts, after each case
-   * finishes, and when the batch completes or fails.
-   */
-  save(run: EvalRunSnapshot, ctx: EvalRunPersistContext): void | Promise<void>;
-  /** Remove a run that falls outside {@link EvalConfigFile.maxPlaygroundRuns}. */
-  delete(runId: string, ctx: EvalRunPersistContext): void | Promise<void>;
-}
-
 export interface EvalConfigFile {
   timeoutMs?: number;
   /**
@@ -361,52 +325,30 @@ export interface EvalConfigFile {
   maxConcurrency: number;
   /**
    * Optional. Max batches kept in the **playground / `/v1/dev/evals*`**
-   * history window (in-memory, and pruned from {@link persistRuns} via
-   * {@link EvalRunPersistence.delete}).
+   * history window (in-memory, and pruned from the `defineStorage` evals
+   * table when one is configured).
    * Does not affect `agent-serve eval` CLI runs.
    *
    * Default {@link EVAL_DEFAULT_MAX_PLAYGROUND_RUNS}; hard-capped at
    * {@link EVAL_MAX_PLAYGROUND_RUNS}. Newest batches win.
    */
   maxPlaygroundRuns?: number;
-  /**
-   * Optional durable store for playground eval batches. Omit this and runs
-   * are **not** surviving process restart (only the in-memory
-   * {@link maxPlaygroundRuns} window).
-   *
-   * ```ts
-   * import {
-   *   defineEvalConfig,
-   *   persistEvalRunsToDir,
-   * } from "@anysphere/agent-serve/evals";
-   *
-   * export default defineEvalConfig({
-   *   maxConcurrency: 20,
-   *   maxPlaygroundRuns: 50,
-   *   // Survive serve restarts (relative to the agent project root):
-   *   persistRuns: persistEvalRunsToDir(".agent-serve/eval-runs"),
-   * });
-   * ```
-   */
-  persistRuns?: EvalRunPersistence;
 }
 
 /**
  * Defaults for every eval under `evals/` (`evals/evals.config.ts`).
  * `maxConcurrency` is required (1–{@link EVAL_MAX_CONCURRENCY_LIMIT}).
  *
- * Playground batches default to **in-memory only** (see {@link maxPlaygroundRuns} /
- * {@link persistRuns}).
+ * Playground batches default to **in-memory only**; author an `evals`
+ * table in `agent/storage.ts` (`defineStorage`) to survive serve restart.
  */
 export function defineEvalConfig(config: EvalConfigFile): EvalConfigFile {
-  const persistRuns = normalizePersistRuns(config.persistRuns);
   return {
     ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
     maxConcurrency: normalizeEvalMaxConcurrency(config.maxConcurrency),
     maxPlaygroundRuns: normalizeEvalMaxPlaygroundRuns(
       config.maxPlaygroundRuns ?? EVAL_DEFAULT_MAX_PLAYGROUND_RUNS
     ),
-    ...(persistRuns === undefined ? {} : { persistRuns }),
   };
 }
 
@@ -443,59 +385,3 @@ export function resolveEvalMaxPlaygroundRuns(value: unknown): number {
     return EVAL_DEFAULT_MAX_PLAYGROUND_RUNS;
   }
 }
-
-function normalizePersistRuns(
-  value: EvalRunPersistence | undefined
-): EvalRunPersistence | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (
-    typeof value !== "object" ||
-    value === null ||
-    typeof value.load !== "function" ||
-    typeof value.save !== "function" ||
-    typeof value.delete !== "function"
-  ) {
-    throw new Error(
-      "evals.config.ts: persistRuns must define load(ctx), save(run, ctx), and delete(runId, ctx)"
-    );
-  }
-  return value;
-}
-
-/**
- * Filesystem {@link EvalRunPersistence}: one JSON file per run under `dir`
- * (relative paths resolve against the agent project root).
- *
- * ```ts
- * export default defineEvalConfig({
- *   maxConcurrency: 20,
- *   persistRuns: persistEvalRunsToDir(".agent-serve/eval-runs"),
- * });
- * ```
- */
-export function persistEvalRunsToDir(dir: string): EvalRunPersistence {
-  const relativeDir = assertNonEmptyDir(dir, "persistEvalRunsToDir");
-  const resolveDir = (projectRoot: string): string =>
-    resolveProjectRelativeDir({ dir: relativeDir, projectRoot });
-
-  return {
-    async load(ctx) {
-      return readJsonDir<EvalRunSnapshot>(resolveDir(ctx.projectRoot));
-    },
-    async save(run, ctx) {
-      await writeJsonFile({
-        root: resolveDir(ctx.projectRoot),
-        fileName: `${run.runId}.json`,
-        value: run,
-      });
-    },
-    async delete(runId, ctx) {
-      await deleteFileInDir({
-        root: resolveDir(ctx.projectRoot),
-        fileName: `${runId}.json`,
-      });
-    },
-  };
-}

package/src/index.ts

@@ -105,10 +105,12 @@ export type {
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {
+  StorageABTable,
   StorageConfig,
   StorageContext,
   StorageDefinition,
   StorageEntry,
+  StorageEvalsTable,
   StoragePolicy,
   StorageRestorePolicy,
 } from "./storage.js";

package/src/internal/ab-collector.ts

@@ -16,7 +16,7 @@
 
 import {
   type ABDefinition,
-  type ABSamplePersistence,
+  type ABMetricSample,
   type ABSampleReason,
   cloneABMetrics,
 } from "../ab.js";
@@ -33,8 +33,11 @@ import { describeError } from "./describe-error.js";
 export type { DiscoveredAB };
 
 export interface ABCollectorOptions {
-  projectRoot: string;
-  persistSamples?: ABSamplePersistence;
+  /**
+   * Durable sample export (the `defineStorage` `abs` table, via the
+   * coordinator). Fire-and-forget; must never throw.
+   */
+  persistSample?: (sample: ABMetricSample) => void;
 }
 
 /** Drop cache after these — next event rehydrates from the durable log. */
@@ -47,8 +50,9 @@ const EVICT_ON: ReadonlySet<SessionEvent["type"]> = new Set([
 export class ABCollector {
   private readonly state = new Map<string, FoldedABSession>();
   private readonly hydrated = new Set<string>();
-  private readonly projectRoot: string | undefined;
-  private readonly persistSamples: ABSamplePersistence | undefined;
+  private readonly persistSample:
+    | ((sample: ABMetricSample) => void)
+    | undefined;
 
   constructor(
     private readonly experiments: readonly DiscoveredAB[],
@@ -56,8 +60,7 @@ export class ABCollector {
     private readonly loadEvents: (sessionId: string) => Promise<SessionEvent[]>,
     options?: ABCollectorOptions
   ) {
-    this.projectRoot = options?.projectRoot;
-    this.persistSamples = options?.persistSamples;
+    this.persistSample = options?.persistSample;
   }
 
   get enabled(): boolean {
@@ -155,7 +158,7 @@ export class ABCollector {
       }
       const reason = sampleReason(event);
       if (reason !== undefined) {
-        const sample = {
+        const sample: ABMetricSample = {
           experiment: experiment.name,
           variant,
           ...(def.variants[variant]?.label !== undefined
@@ -174,20 +177,7 @@ export class ABCollector {
             `[agentkit] ab "${experiment.name}" onSample threw: ${describeError(error)}`
           );
         }
-        if (
-          this.persistSamples !== undefined &&
-          this.projectRoot !== undefined
-        ) {
-          try {
-            await this.persistSamples.save(sample, {
-              projectRoot: this.projectRoot,
-            });
-          } catch (error) {
-            this.logger(
-              `[agentkit] ab persistSamples.save threw: ${describeError(error)}`
-            );
-          }
-        }
+        this.persistSample?.(sample);
       }
     }
   }

package/src/internal/ab-snapshot.ts

@@ -58,12 +58,10 @@ export interface ABSnapshotExperiment {
 export interface ABSnapshotConfig {
   /** Newest-first session fold window for this snapshot (`GET /v1/abs`). */
   maxPlaygroundSessions?: number;
-  /** True when `persistSamples` is configured. */
+  /** True when the `defineStorage` `abs` table is configured. */
   durableSamples?: boolean;
-  /** True when `persistSnapshots` is configured. */
+  /** True when the `abs` table also stores the aggregate snapshot. */
   durableSnapshots?: boolean;
-  /** Set when writing via filesystem snapshot persistence helpers. */
-  snapshotId?: string;
 }
 
 export interface ABSnapshot {