@cursor/july 0.1.48 → 0.1.49

package/src/internal/process-memory-telemetry.ts

@@ -0,0 +1,373 @@
+/**
+ * Process heap + event-log residency for hosted engines.
+ *
+ * Pod RSS (`runner_daemon.pod.memory_usage_bytes`) cannot show a V8 heap-cap
+ * OOM: the cgroup limit is tens of GB while Node aborts near
+ * `--max-old-space-size`. The live path is `/v1/health`: the control plane
+ * already probes every engine and emits `cursor.agent_serve.engine.*` gauges.
+ * An optional in-process sampler (`AGENT_SDK_MEMORY_METRICS=1`) still logs
+ * and, if a Datadog key happens to be in the pod, posts directly.
+ *
+ * `event_log.events_retained` is the in-process cache size (the OOM
+ * suspect). `event_log.events_total` is the durable recorded count. They
+ * are equal today; a later consume-and-drop change should split them.
+ */
+
+import { getHeapStatistics } from "node:v8";
+import type { Attributes, Meter } from "@opentelemetry/api";
+import type { EventLogMemoryStats } from "./event-log.js";
+
+const DEFAULT_INTERVAL_MS = 15_000;
+const DEFAULT_DD_SITE = "us5.datadoghq.com";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MB = 1024 * 1024;
+
+export const MEMORY_METRIC_PREFIX = "agent_sdk.memory";
+export const EVENT_LOG_METRIC_PREFIX = "agent_sdk.event_log";
+
+export type ProcessMemorySample = {
+  heapUsedBytes: number;
+  heapTotalBytes: number;
+  heapLimitBytes: number;
+  rssBytes: number;
+  externalBytes: number;
+};
+
+export type DatadogMemoryMetricsConfig = {
+  apiKey: string;
+  seriesUrl: string;
+  timeoutMs: number;
+};
+
+export type ProcessMemoryTelemetryOptions = {
+  agentName: string;
+  getEventLogStats: () => EventLogMemoryStats;
+  logger?: (line: string) => void;
+  meter?: Meter;
+  env?: NodeJS.ProcessEnv;
+  intervalMs?: number;
+  now?: () => number;
+  memoryUsage?: () => {
+    heapUsed: number;
+    heapTotal: number;
+    rss: number;
+    external: number;
+  };
+  heapSizeLimit?: () => number;
+  postSeries?: (
+    config: DatadogMemoryMetricsConfig,
+    body: string
+  ) => Promise<void>;
+};
+
+export function shouldStartProcessMemoryTelemetry(
+  env: NodeJS.ProcessEnv = process.env
+): boolean {
+  const flag = env.AGENT_SDK_MEMORY_METRICS?.trim().toLowerCase();
+  return flag === "1" || flag === "true";
+}
+
+export function resolveDatadogMemoryMetricsConfig(
+  env: NodeJS.ProcessEnv = process.env
+): DatadogMemoryMetricsConfig | undefined {
+  const apiKey = env.DATADOG_API_KEY?.trim() || env.DD_API_KEY?.trim();
+  if (apiKey === undefined || apiKey === "") {
+    return undefined;
+  }
+  const site = env.DD_SITE?.trim() || DEFAULT_DD_SITE;
+  return {
+    apiKey,
+    seriesUrl: `https://api.${site}/api/v1/series`,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  };
+}
+
+export function sampleProcessMemory(
+  args: {
+    memoryUsage?: ProcessMemoryTelemetryOptions["memoryUsage"];
+    heapSizeLimit?: ProcessMemoryTelemetryOptions["heapSizeLimit"];
+  } = {}
+): ProcessMemorySample {
+  const usage = args.memoryUsage?.() ?? process.memoryUsage();
+  const heapLimitBytes =
+    args.heapSizeLimit?.() ?? getHeapStatistics().heap_size_limit;
+  return {
+    heapUsedBytes: usage.heapUsed,
+    heapTotalBytes: usage.heapTotal,
+    heapLimitBytes,
+    rssBytes: usage.rss,
+    externalBytes: usage.external,
+  };
+}
+
+export type MemoryHealthFields = {
+  memory: ProcessMemorySample & { heapUsedRatio: number };
+  eventLog: EventLogMemoryStats;
+};
+
+export function heapUsedRatio(memory: ProcessMemorySample): number {
+  return memory.heapLimitBytes > 0
+    ? memory.heapUsedBytes / memory.heapLimitBytes
+    : 0;
+}
+
+export function sumEventLogStats(
+  stats: readonly EventLogMemoryStats[]
+): EventLogMemoryStats {
+  let residentSessions = 0;
+  let eventsRetained = 0;
+  let eventsTotal = 0;
+  for (const item of stats) {
+    residentSessions += item.residentSessions;
+    eventsRetained += item.eventsRetained;
+    eventsTotal += item.eventsTotal;
+  }
+  return { residentSessions, eventsRetained, eventsTotal };
+}
+
+/** Fields attached to `/v1/health` so the control plane can scrape them. */
+export function buildMemoryHealthFields(
+  eventLog: EventLogMemoryStats,
+  sample: ProcessMemorySample = sampleProcessMemory()
+): MemoryHealthFields {
+  return {
+    memory: { ...sample, heapUsedRatio: heapUsedRatio(sample) },
+    eventLog,
+  };
+}
+
+/**
+ * Best-effort health payload. Sampling or event-log stats must never fail
+ * `/v1/health`; omit the fields instead.
+ */
+export function collectMemoryHealthFields(args: {
+  eventLog: () => EventLogMemoryStats;
+  sample?: () => ProcessMemorySample;
+}): MemoryHealthFields | Record<string, never> {
+  try {
+    return buildMemoryHealthFields(
+      args.eventLog(),
+      args.sample === undefined ? sampleProcessMemory() : args.sample()
+    );
+  } catch {
+    return {};
+  }
+}
+
+export function formatMemoryLogLine(args: {
+  agentName: string;
+  memory: ProcessMemorySample;
+  eventLog: EventLogMemoryStats;
+}): string {
+  const ratio = heapUsedRatio(args.memory);
+  return (
+    `[agent-sdk:memory] agent=${args.agentName}` +
+    ` heap_used_mb=${mb(args.memory.heapUsedBytes)}` +
+    ` heap_total_mb=${mb(args.memory.heapTotalBytes)}` +
+    ` heap_limit_mb=${mb(args.memory.heapLimitBytes)}` +
+    ` heap_used_ratio=${ratio.toFixed(3)}` +
+    ` rss_mb=${mb(args.memory.rssBytes)}` +
+    ` event_log.sessions=${args.eventLog.residentSessions}` +
+    ` event_log.retained=${args.eventLog.eventsRetained}` +
+    ` event_log.total=${args.eventLog.eventsTotal}`
+  );
+}
+
+export function buildDatadogGaugeSeries(args: {
+  agentName: string;
+  memory: ProcessMemorySample;
+  eventLog: EventLogMemoryStats;
+  timestampSec: number;
+}): Array<{
+  metric: string;
+  type: "gauge";
+  points: [[number, number]];
+  tags: string[];
+}> {
+  const tags = [`agent_sdk.agent:${sanitizeTag(args.agentName)}`];
+  const heapRatio = heapUsedRatio(args.memory);
+  const points: Array<{ name: string; value: number }> = [
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_used_bytes`,
+      value: args.memory.heapUsedBytes,
+    },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_total_bytes`,
+      value: args.memory.heapTotalBytes,
+    },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_limit_bytes`,
+      value: args.memory.heapLimitBytes,
+    },
+    { name: `${MEMORY_METRIC_PREFIX}.rss_bytes`, value: args.memory.rssBytes },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.external_bytes`,
+      value: args.memory.externalBytes,
+    },
+    { name: `${MEMORY_METRIC_PREFIX}.heap_used_ratio`, value: heapRatio },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`,
+      value: args.eventLog.residentSessions,
+    },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.events_retained`,
+      value: args.eventLog.eventsRetained,
+    },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.events_total`,
+      value: args.eventLog.eventsTotal,
+    },
+  ];
+  return points.map((point) => ({
+    metric: point.name,
+    type: "gauge",
+    points: [[args.timestampSec, point.value]],
+    tags,
+  }));
+}
+
+/** Start the sampler. Returns a stop function. */
+export function startProcessMemoryTelemetry(
+  options: ProcessMemoryTelemetryOptions
+): () => void {
+  const env = options.env ?? process.env;
+  const logger = options.logger ?? (() => {});
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const datadog = resolveDatadogMemoryMetricsConfig(env);
+  const attributes: Attributes = { "agent_sdk.agent": options.agentName };
+  let stopped = false;
+  let inFlight: Promise<void> | undefined;
+
+  const sample = (): void => {
+    if (stopped) {
+      return;
+    }
+    const memory = sampleProcessMemory({
+      memoryUsage: options.memoryUsage,
+      heapSizeLimit: options.heapSizeLimit,
+    });
+    const eventLog = options.getEventLogStats();
+    logger(
+      formatMemoryLogLine({ agentName: options.agentName, memory, eventLog })
+    );
+    recordOtel(options.meter, memory, eventLog, attributes);
+    if (datadog === undefined) {
+      return;
+    }
+    const body = JSON.stringify({
+      series: buildDatadogGaugeSeries({
+        agentName: options.agentName,
+        memory,
+        eventLog,
+        timestampSec: Math.floor((options.now?.() ?? Date.now()) / 1000),
+      }),
+    });
+    const post = options.postSeries ?? defaultPostSeries;
+    inFlight = post(datadog, body).catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger(`[agent-sdk:memory] datadog flush failed: ${message}`);
+    });
+  };
+
+  sample();
+  const timer = setInterval(sample, intervalMs);
+  timer.unref();
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+    void inFlight;
+  };
+}
+
+function recordOtel(
+  meter: Meter | undefined,
+  memory: ProcessMemorySample,
+  eventLog: EventLogMemoryStats,
+  attributes: Attributes
+): void {
+  if (meter === undefined) {
+    return;
+  }
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.heap_used_bytes`).record(
+    memory.heapUsedBytes,
+    attributes
+  );
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.heap_limit_bytes`).record(
+    memory.heapLimitBytes,
+    attributes
+  );
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.rss_bytes`).record(
+    memory.rssBytes,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_retained`).record(
+    eventLog.eventsRetained,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_total`).record(
+    eventLog.eventsTotal,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`).record(
+    eventLog.residentSessions,
+    attributes
+  );
+}
+
+type HistogramInstrument = {
+  record: (value: number, attributes?: Attributes) => void;
+};
+
+const histograms = new WeakMap<Meter, Map<string, HistogramInstrument>>();
+
+function histogram(meter: Meter, name: string): HistogramInstrument {
+  let byName = histograms.get(meter);
+  if (byName === undefined) {
+    byName = new Map();
+    histograms.set(meter, byName);
+  }
+  const existing = byName.get(name);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const unit = name.endsWith("_bytes") ? "By" : "{count}";
+  const created = meter.createHistogram(name, { unit });
+  byName.set(name, created);
+  return created;
+}
+
+async function defaultPostSeries(
+  config: DatadogMemoryMetricsConfig,
+  body: string
+): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+  try {
+    const response = await fetch(config.seriesUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "DD-API-KEY": config.apiKey,
+      },
+      body,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function mb(bytes: number): string {
+  return (bytes / MB).toFixed(1);
+}
+
+function sanitizeTag(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_\-./:]+/g, "_");
+  return normalized === "" ? "unknown" : normalized;
+}

package/src/internal/server.ts

@@ -135,6 +135,10 @@ import {
   playgroundDevBasePath,
   startPlaygroundDevServer,
 } from "./playground/toolchain.js";
+import {
+  collectMemoryHealthFields,
+  sumEventLogStats,
+} from "./process-memory-telemetry.js";
 import {
   ReminderRunner,
   ReminderValidationError,
@@ -162,6 +166,13 @@ import {
 } from "./session-engine.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
 
+function memoryHealthFields(engines: readonly SessionEngine[]) {
+  return collectMemoryHealthFields({
+    eventLog: () =>
+      sumEventLogStats(engines.map((engine) => engine.eventLogMemoryStats())),
+  });
+}
+
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
 
 /** `GET /v1/artifacts` limit defaults / ceiling. */
@@ -636,6 +647,7 @@ export async function startServer(
             slug,
             name: project.name,
           })),
+          ...memoryHealthFields(runtimes.map((runtime) => runtime.engine)),
         }),
     });
   }
@@ -1049,6 +1061,7 @@ function mountAgentRoutes(
         ok: true,
         name: project.name,
         version: packageVersion(),
+        ...memoryHealthFields([engine]),
       }),
   });
 

package/src/internal/session-engine.ts

@@ -91,7 +91,7 @@ import {
   namespacedKv,
   storageCasKv,
 } from "./durable-session-store.js";
-import { EventLogStore } from "./event-log.js";
+import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
@@ -112,6 +112,10 @@ import { validateToolInput } from "./json-schema.js";
 import { LedgerServing, newLedgerPodId } from "./ledger-serving.js";
 import { McpHost } from "./mcp-host.js";
 import type { OtelCollector } from "./otel/collector.js";
+import {
+  shouldStartProcessMemoryTelemetry,
+  startProcessMemoryTelemetry,
+} from "./process-memory-telemetry.js";
 import {
   buildSessionContextBlock,
   SCHEDULE_CHANNEL_PREFIX,
@@ -364,6 +368,7 @@ export class SessionEngine {
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
   private readonly otelHost: HostOtelSessionApi;
+  private readonly stopMemoryTelemetry: (() => void) | undefined;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -480,6 +485,14 @@ export class SessionEngine {
     }
     this.ledgerServing = this.buildLedgerServing(options);
     this.ledgerServing?.start();
+    this.stopMemoryTelemetry = shouldStartProcessMemoryTelemetry()
+      ? startProcessMemoryTelemetry({
+          agentName: options.project.name,
+          getEventLogStats: () => this.logs.memoryStats(),
+          logger: this.logger,
+          meter: options.otelMeter,
+        })
+      : undefined;
   }
 
   /**
@@ -3445,8 +3458,14 @@ export class SessionEngine {
       });
   }
 
+  /** In-process event-log residency (OOM-suspect cache vs durable count). */
+  eventLogMemoryStats(): EventLogMemoryStats {
+    return this.logs.memoryStats();
+  }
+
   /** Drain running turns, dispatches, and pending writes, then dispose. */
   async close(): Promise<void> {
+    this.stopMemoryTelemetry?.();
     this.approvals.cancelAll("deny");
     // Ledger deliveries spawn turns, so settle them before activeTurns.
     await this.ledgerServing?.close();

package/src/internal/slack-provision-client.ts

@@ -6,11 +6,11 @@
  *
  * Auth is the user API key sent directly as the bearer (the routes are
  * `wrapUserApiRoute` on the backend); there is no token exchange here.
- * The endpoints are gated on the `agent_serve_slack_provisioning` Statsig
- * gate and 404 when it is off — the error mapping says so instead of
- * "not found". Expected provisioning failures carry a stable JSON `code`
+ * The endpoints ride `requireAgentServeAccess` and 404 `{ error: "Not found" }`
+ * when Agent Serve is off — same mapping as other agent-sdk deploy 404s.
+ * Expected provisioning failures carry a stable JSON `code`
  * (`not_connected`, `insufficient_scopes`, `manager_reauth_required`,
- * `app_conflict`, `app_cap_reached`, `ratelimited`, `invalid_app_id`, …)
+ * `app_conflict`, `ratelimited`, `invalid_app_id`, …)
  * which flows through on {@link SlackProvisionApiError.code} so the CLI
  * can branch.
  */
@@ -398,8 +398,8 @@ function mapErrorResponse(
           { status: 404 }
         );
       }
-      // The gate-off body is exactly {error: "Not found"}; anything else
-      // (e.g. "App not found" on delete) is a real not-found to surface.
+      // `{ error: "Not found" }` is Agent Serve off (`requireAgentServeAccess`),
+      // not a Slack-only enrollment bar.
       if (serverError !== undefined && serverError !== "Not found") {
         return new SlackProvisionApiError(serverError, {
           status: 404,
@@ -407,7 +407,7 @@ function mapErrorResponse(
         });
       }
       return new SlackProvisionApiError(
-        `Not found — Cursor's "Add to Slack" provisioning (the agent_serve_slack_provisioning feature gate) is not enabled for this account yet.`,
+        `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`,
         { status: 404 }
       );
     }

package/src/storage.ts

@@ -9,9 +9,12 @@
  * The sink is a plain key-value store — put/get/delete/list, no schema —
  * plus a conditional-write group ({@link StorageConfig.cas}, the substrate
  * for framework coordination; optional for plain storage, required by
- * coordination features) and two optional dedicated tables
- * ({@link StorageConfig.evals} and {@link StorageConfig.abs}) for
- * eval-run and A/B history:
+ * coordination features). Implementing that small KV core is enough for
+ * FULL functionality: eval-run and A/B history are derived over the core
+ * when the optional dedicated tables ({@link StorageConfig.evals} and
+ * {@link StorageConfig.abs}) are not authored — those groups exist as
+ * backend-native optimizations (a real table, an analytics pipeline),
+ * not as required-or-lose-history hooks:
  *
  * ```ts
  * import { defineStorage } from "@anysphere/agent-serve/storage";
@@ -207,13 +210,20 @@ export interface StorageConfig {
   /** Timing knobs; see {@link StoragePolicy}. */
   policy?: StoragePolicy;
   /**
-   * Dedicated eval-runs table. Omit it and playground eval history stays
-   * in process memory (lost on restart).
+   * Dedicated eval-runs table — a backend-native optimization, not a
+   * requirement. When omitted, `defineStorage` derives the table over the
+   * KV core (one key per run under `agentkit/v1/{agent}/eval-runs/`),
+   * which needs core `put`, `delete`, and `list`; only when the core
+   * lacks `delete` or `list` does playground eval history stay in process
+   * memory (lost on restart).
    */
   evals?: StorageEvalsTable;
   /**
-   * Dedicated A/B table. Omit it and metric samples are not exported
-   * (session event logs remain the assignment/fold source of truth).
+   * Dedicated A/B table — a backend-native optimization, not a
+   * requirement. When omitted, `defineStorage` derives it over the KV
+   * core: `putSample` and `putSnapshot` need only core `put` (always
+   * present), `getSnapshot` additionally needs core `get`. Session event
+   * logs remain the assignment/fold source of truth either way.
    */
   abs?: StorageABTable;
   /**
@@ -249,7 +259,8 @@ export interface StorageConfig {
   /**
    * All entries under a key prefix, in ascending key order. Optional —
    * required for the **startup bulk restore** (sessions + event streams)
-   * and playground eval history.
+   * and, together with `delete`, for the derived eval-runs table
+   * (playground eval history).
    */
   list?(
     prefix: string,
@@ -326,7 +337,91 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
   }
   // Validate eagerly so a bad policy fails at discovery, not first flush.
   resolveStoragePolicy(config.policy);
-  return brandDefinition("storage", config);
+  // A backend that implements only the KV core gets full functionality:
+  // the dedicated tables are backend-native optimizations, derived over
+  // the core when absent. Authored groups always win.
+  const derivedEvals =
+    config.evals === undefined ? deriveEvalsTable(config) : undefined;
+  const derivedAbs =
+    config.abs === undefined ? deriveAbsTable(config) : undefined;
+  return brandDefinition("storage", {
+    ...config,
+    ...(derivedEvals === undefined ? {} : { evals: derivedEvals }),
+    ...(derivedAbs === undefined ? {} : { abs: derivedAbs }),
+  });
+}
+
+/**
+ * Eval-runs table over the KV core: one key per run under
+ * {@link storageKeys.evalRun}, hydrate via prefix `list`, prune via
+ * `delete`. Requires core `put` + `delete` + `list`; without `delete` or
+ * `list` there is no derivation (pruning or hydration would silently not
+ * work) and eval history stays in process memory.
+ */
+function deriveEvalsTable(
+  config: StorageConfig
+): StorageEvalsTable | undefined {
+  if (config.delete === undefined || config.list === undefined) {
+    return undefined;
+  }
+  return {
+    put: (run, ctx) =>
+      config.put(
+        storageKeys.evalRun(ctx.agentName, run.runId),
+        run as unknown as JsonValue,
+        ctx
+      ),
+    delete: (runId, ctx) =>
+      config.delete?.(storageKeys.evalRun(ctx.agentName, runId), ctx),
+    list: async (ctx) => {
+      const entries =
+        (await config.list?.(storageKeys.evalRunsPrefix(ctx.agentName), ctx)) ??
+        [];
+      return entries.map((entry) => entry.value as unknown as EvalRunSnapshot);
+    },
+  };
+}
+
+/**
+ * A/B table over the KV core. Each sample lands as its own key (identity
+ * = experiment + sessionId + at, matching the dedicated table's row
+ * uniqueness): appending to one array value would need read-modify-write
+ * — lost updates under concurrent writers without CAS, and unbounded
+ * value growth — while a key per sample keeps `putSample` a blind put
+ * with real append-only semantics. The aggregate snapshot lives at one
+ * fixed key via plain `put` (last-write-wins is correct for "latest").
+ * Requires only core `put`; `getSnapshot` is included when core `get`
+ * exists.
+ */
+function deriveAbsTable(config: StorageConfig): StorageABTable {
+  const get = config.get;
+  return {
+    putSample: (sample, ctx) =>
+      config.put(
+        storageKeys.abSample(
+          ctx.agentName,
+          sample.experiment,
+          sample.sessionId,
+          sample.at
+        ),
+        sample as unknown as JsonValue,
+        ctx
+      ),
+    putSnapshot: (snapshot, ctx) =>
+      config.put(
+        storageKeys.abSnapshot(ctx.agentName),
+        snapshot as unknown as JsonValue,
+        ctx
+      ),
+    ...(get === undefined
+      ? {}
+      : {
+          getSnapshot: async (ctx: StorageContext) => {
+            const value = await get(storageKeys.abSnapshot(ctx.agentName), ctx);
+            return (value ?? undefined) as ABSnapshot | undefined;
+          },
+        }),
+  };
 }
 
 // ============================================================================
@@ -357,9 +452,14 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
+ * | `agentkit/v1/{agent}/eval-runs/{runId}` | `EvalRunSnapshot` (derived `evals` table) |
+ * | `agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` | `ABMetricSample` (derived `abs` table, append-only) |
+ * | `agentkit/v1/{agent}/ab-snapshot` | `ABSnapshot` (derived `abs` table, LWW) |
  *
- * Eval-run and A/B history do not flow through this KV scheme — they have
- * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
+ * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
+ * by the tables `defineStorage` derives over the KV core; a backend that
+ * authors dedicated {@link StorageConfig.evals} / {@link StorageConfig.abs}
+ * groups never sees them.
  */
 export const storageKeys = {
   session: (agent: string, sessionId: string): string =>
@@ -387,6 +487,25 @@ export const storageKeys = {
   kv: (agent: string, key: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
   kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
+  /** One playground eval-run snapshot (derived `evals` table). */
+  evalRun: (agent: string, runId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
+  evalRunsPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
+  /**
+   * One A/B metric sample (derived `abs` table); the segments mirror the
+   * dedicated table's row identity (experiment + sessionId + at).
+   */
+  abSample: (
+    agent: string,
+    experiment: string,
+    sessionId: string,
+    at: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
+  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
+  abSnapshot: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
 } as const;
 
 /**