@cursor/july 0.1.6 → 0.1.7

package/dist/internal/evals-client.js

@@ -0,0 +1,262 @@
+/**
+ * HTTP client for playground eval batches (`/v1/dev/evals/runs`).
+ *
+ * Used by `agentkit eval --prod` (or `--url`) so the batch runs on the serve
+ * process and is mirrored to `defineStorage` when an `evals` table is
+ * configured. Without those flags, eval keeps the in-process ephemeral path
+ * in `cli-ax.ts`.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { matchesEvalIdFilter } from "../evals.js";
+import { mergeRequestHeaders } from "./request-headers.js";
+const DEFAULT_POLL_MS = 1000;
+export class RemoteEvalError extends Error {
+    constructor(message, status, code, activeRunId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.activeRunId = activeRunId;
+        this.name = "RemoteEvalError";
+    }
+}
+/**
+ * Start a batch on the target serve via `POST /v1/dev/evals/runs`, poll until
+ * terminal, and return CLI-shaped case results.
+ */
+export function runRemoteEvals(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b, _c;
+        const baseUrl = options.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_b = options.fetchImpl) !== null && _b !== void 0 ? _b : fetch;
+        const auth = {
+            bearerToken: options.bearerToken,
+            headers: options.headers,
+        };
+        const started = yield startRemoteEvalRun({
+            baseUrl,
+            auth,
+            fetchImpl,
+            filterIds: options.filterIds,
+            tags: options.tags,
+            timeoutMs: options.timeoutMs,
+            verbose: options.verbose,
+            signal: options.signal,
+        });
+        (_a = options.onSnapshot) === null || _a === void 0 ? void 0 : _a.call(options, started);
+        const snapshot = yield pollRemoteEvalRun({
+            baseUrl,
+            runId: started.runId,
+            auth,
+            fetchImpl,
+            pollMs: (_c = options.pollMs) !== null && _c !== void 0 ? _c : DEFAULT_POLL_MS,
+            signal: options.signal,
+            onSnapshot: options.onSnapshot,
+        });
+        return { snapshot, results: snapshotToEvalRunResults(snapshot) };
+    });
+}
+/** List datapoints from `GET /v1/dev/evals` (same surface a remote run uses). */
+export function listRemoteEvals(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        let resp;
+        try {
+            resp = yield fetchImpl(`${baseUrl}/v1/dev/evals`, {
+                headers: mergeRequestHeaders(args.auth),
+                signal: args.signal,
+            });
+        }
+        catch (error) {
+            throw new RemoteEvalError(error instanceof Error ? error.message : "Could not list evals.", undefined, "start_failed");
+        }
+        if (!resp.ok) {
+            throw new RemoteEvalError(`Could not list evals (HTTP ${resp.status}).`, resp.status, "start_failed");
+        }
+        const body = (yield resp.json());
+        const listed = [];
+        for (const row of (_b = body.evals) !== null && _b !== void 0 ? _b : []) {
+            if (typeof row.id !== "string" || row.id === "") {
+                continue;
+            }
+            if (typeof row.fileId !== "string" || row.fileId === "") {
+                continue;
+            }
+            const tags = Array.isArray(row.tags)
+                ? row.tags.filter((t) => typeof t === "string")
+                : undefined;
+            listed.push(Object.assign(Object.assign({ id: row.id, fileId: row.fileId }, (typeof row.description === "string"
+                ? { description: row.description }
+                : {})), (tags === undefined || tags.length === 0 ? {} : { tags })));
+        }
+        let selected = listed;
+        if (args.filterIds !== undefined && args.filterIds.length > 0) {
+            selected = selected.filter((e) => args.filterIds.some((f) => matchesEvalIdFilter(e.id, f)));
+        }
+        if (args.tags !== undefined && args.tags.length > 0) {
+            selected = selected.filter((e) => { var _a; return ((_a = e.tags) !== null && _a !== void 0 ? _a : []).some((t) => args.tags.includes(t)); });
+        }
+        return selected;
+    });
+}
+export function startRemoteEvalRun(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        const body = {};
+        if (args.filterIds !== undefined && args.filterIds.length > 0) {
+            body.filterIds = args.filterIds;
+        }
+        if (args.tags !== undefined && args.tags.length > 0) {
+            body.tags = args.tags;
+        }
+        if (args.timeoutMs !== undefined) {
+            body.timeoutMs = args.timeoutMs;
+        }
+        if (args.verbose === true) {
+            body.verbose = true;
+        }
+        let resp;
+        try {
+            resp = yield fetchImpl(`${baseUrl}/v1/dev/evals/runs`, {
+                method: "POST",
+                headers: Object.assign({ "content-type": "application/json" }, mergeRequestHeaders(args.auth)),
+                body: JSON.stringify(body),
+                signal: args.signal,
+            });
+        }
+        catch (error) {
+            throw new RemoteEvalError(error instanceof Error ? error.message : "Could not start eval run.", undefined, "start_failed");
+        }
+        const json = (yield resp.json().catch(() => ({})));
+        if (json.error === "no_matching_evals") {
+            throw new RemoteEvalError("No matching evals found.", 404, "no_matching_evals");
+        }
+        if (resp.status === 409 || json.error === "eval_run_in_progress") {
+            throw new RemoteEvalError(json.activeRunId !== undefined && json.activeRunId !== ""
+                ? `An eval run is already in progress (${json.activeRunId}).`
+                : "An eval run is already in progress.", 409, "eval_run_in_progress", typeof json.activeRunId === "string" ? json.activeRunId : undefined);
+        }
+        if (!resp.ok) {
+            const detail = typeof json.message === "string" && json.message !== ""
+                ? json.message
+                : typeof json.error === "string" && json.error !== ""
+                    ? json.error
+                    : `HTTP ${resp.status}`;
+            throw new RemoteEvalError(`Could not start eval run: ${detail}`, resp.status, "start_failed");
+        }
+        if (typeof json.runId !== "string" || json.runId === "") {
+            throw new RemoteEvalError("Eval start response missing runId.", undefined, "start_failed");
+        }
+        return json;
+    });
+}
+/** One-shot `GET /v1/dev/evals/runs/:runId` (no polling). */
+export function getRemoteEvalRun(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        let resp;
+        try {
+            resp = yield fetchImpl(`${baseUrl}/v1/dev/evals/runs/${encodeURIComponent(args.runId)}`, {
+                headers: mergeRequestHeaders(args.auth),
+                signal: args.signal,
+            });
+        }
+        catch (error) {
+            throw new RemoteEvalError(error instanceof Error ? error.message : "Could not fetch eval run.", undefined, "poll_failed");
+        }
+        if (resp.status === 404) {
+            throw new RemoteEvalError(`Unknown eval run ${args.runId}.`, 404, "unknown_eval_run");
+        }
+        if (!resp.ok) {
+            throw new RemoteEvalError(`Could not fetch eval run (HTTP ${resp.status}).`, resp.status, "poll_failed");
+        }
+        return (yield resp.json());
+    });
+}
+/** Recent batches from `GET /v1/dev/evals/runs`. */
+export function listRemoteEvalRuns(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        let resp;
+        try {
+            resp = yield fetchImpl(`${baseUrl}/v1/dev/evals/runs`, {
+                headers: mergeRequestHeaders(args.auth),
+                signal: args.signal,
+            });
+        }
+        catch (error) {
+            throw new RemoteEvalError(error instanceof Error ? error.message : "Could not list eval runs.", undefined, "poll_failed");
+        }
+        if (!resp.ok) {
+            throw new RemoteEvalError(`Could not list eval runs (HTTP ${resp.status}).`, resp.status, "poll_failed");
+        }
+        const body = (yield resp.json());
+        const runs = Array.isArray(body.runs)
+            ? body.runs.filter((r) => r !== null &&
+                typeof r === "object" &&
+                typeof r.runId === "string")
+            : [];
+        return Object.assign({ runs }, (typeof body.activeRunId === "string" && body.activeRunId !== ""
+            ? { activeRunId: body.activeRunId }
+            : {}));
+    });
+}
+export function pollRemoteEvalRun(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        var _c;
+        const pollMs = (_c = args.pollMs) !== null && _c !== void 0 ? _c : DEFAULT_POLL_MS;
+        let lastJson = "";
+        for (;;) {
+            if (((_a = args.signal) === null || _a === void 0 ? void 0 : _a.aborted) === true) {
+                throw new RemoteEvalError("Eval wait aborted.", undefined, "aborted");
+            }
+            const snap = yield getRemoteEvalRun(args);
+            const serialized = JSON.stringify(snap);
+            if (serialized !== lastJson) {
+                lastJson = serialized;
+                (_b = args.onSnapshot) === null || _b === void 0 ? void 0 : _b.call(args, snap);
+            }
+            if (snap.status !== "running") {
+                return snap;
+            }
+            yield sleep(pollMs, args.signal);
+        }
+    });
+}
+export function snapshotToEvalRunResults(snapshot) {
+    return snapshot.cases.map((c) => { var _a, _b, _c, _d; return (Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: c.id, path: c.fileId }, (c.description === undefined ? {} : { description: c.description })), { ok: c.ok === true, assertions: (_a = c.assertions) !== null && _a !== void 0 ? _a : [] }), (c.sessionId === undefined ? {} : { sessionId: c.sessionId })), { inputs: (_b = c.inputs) !== null && _b !== void 0 ? _b : [] }), (c.finalText === undefined ? {} : { finalText: c.finalText })), (c.tools === undefined ? {} : { tools: c.tools })), (c.toolCalls === undefined ? {} : { toolCalls: c.toolCalls })), (c.error === undefined ? {} : { error: c.error })), { logs: (_c = c.logs) !== null && _c !== void 0 ? _c : [], durationMs: (_d = c.durationMs) !== null && _d !== void 0 ? _d : 0 })); });
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) {
+            reject(new RemoteEvalError("Eval wait aborted.", undefined, "aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new RemoteEvalError("Eval wait aborted.", undefined, "aborted"));
+        };
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/internal/init-project.js

@@ -301,15 +301,15 @@ Recommended loop once the project exists:
   1. Edit agent/ + tools under agent/tools/
   2. ${CLI_COMMAND_NAME} info --dir . --json
   3. ${CLI_COMMAND_NAME} run --dir . --message "..."
-  4. ${CLI_COMMAND_NAME} eval --local --dir .
+  4. ${CLI_COMMAND_NAME} eval --dir .
 
 Evals:
   Create evals/**/*.eval.ts using defineEval from ${PACKAGE_NAME}/evals
   Case id is the path: evals/weather/nyc.eval.ts → weather/nyc
   Required: evals/evals.config.ts with defineEvalConfig({ maxConcurrency })
     (hard-capped at 200 due to model provider request limits)
-  Run: ${CLI_COMMAND_NAME} eval --local [--json] [evalId...]
-    (omit --local to run against the hosted deployment)
+  Run: ${CLI_COMMAND_NAME} eval [--json] [evalId...]
+    (pass --prod to run against the hosted deployment)
 
 See AGENTS.md in the ${PACKAGE_NAME} package for the full loop.
 `);

package/dist/internal/json-dir-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Small filesystem helpers for one-JSON-file-per-id persistence under a
+ * project-relative directory (eval run snapshots, A/B aggregate snapshots).
+ */
+export declare function assertNonEmptyDir(dir: string, fnName: string): string;
+/** Resolve `dir` against `projectRoot` when relative. */
+export declare function resolveProjectRelativeDir(args: {
+    dir: string;
+    projectRoot: string;
+}): string;
+/** List `*.json` basenames in `root` (any order). Missing dir → []. */
+export declare function listJsonBasenames(root: string): Promise<string[]>;
+/**
+ * Read and JSON.parse every `*.json` file under `root`. Missing dir → [].
+ * Unreadable or corrupt files are skipped so one bad snapshot cannot wipe
+ * the rest of the history.
+ */
+export declare function readJsonDir<T>(root: string, options?: {
+    sortBasenames?: "asc" | "desc";
+}): Promise<T[]>;
+/** Atomically write JSON under `root`/`fileName` (temp file + rename). */
+export declare function writeJsonFile(args: {
+    root: string;
+    fileName: string;
+    value: unknown;
+}): Promise<void>;
+/** Best-effort delete; ignores missing files. */
+export declare function deleteFileInDir(args: {
+    root: string;
+    fileName: string;
+}): Promise<void>;
+//# sourceMappingURL=json-dir-store.d.ts.map

package/dist/internal/json-dir-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-dir-store.d.ts","sourceRoot":"","sources":["../../src/internal/json-dir-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAET;AAWD,uEAAuE;AACvE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWvE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBd;AAED,0EAA0E;AAC1E,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB"}

package/dist/internal/persistence-coordinator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Runtime for `definePersistence` (`agent/persistence.ts`).
+ *
+ * The coordinator is the single funnel between the engine's hot paths and
+ * the author's key-value sink. The sink is four functions (`put` / `get` /
+ * `delete` / `list`); the coordinator owns everything else: it mints every
+ * key from the versioned scheme ({@link persistenceKeys}), coalesces
+ * session records and batches event chunks per turn (or debounce window),
+ * serializes delivery on one bounded queue per agent, and isolates
+ * failures — a throwing sink is logged and its write dropped; persistence
+ * must never stall or fail a turn.
+ *
+ * Scaling shape: sessions, 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.
+ */
+import type { ABSamplePersistence } from "../ab.js";
+import type { EvalRunPersistence } from "../evals.js";
+import { type PersistenceContext, type PersistenceDefinition, type ResolvedPersistencePolicy } from "../persistence.js";
+import type { SessionEvent, SessionRecord } from "../types.js";
+import type { ABSnapshot } from "./ab-snapshot.js";
+export interface PersistenceCoordinatorOptions {
+    definition: PersistenceDefinition;
+    agentName: string;
+    projectRoot: string;
+    logger: (line: string) => void;
+}
+export declare class PersistenceCoordinator {
+    readonly policy: ResolvedPersistencePolicy;
+    private readonly definition;
+    private readonly agentName;
+    private readonly projectRoot;
+    private readonly logger;
+    /** Per-session pending state (events + coalesced record). */
+    private readonly buffers;
+    /**
+     * Last continuation key written to the sink per session, so a token
+     * change emits a delete for the stale index entry alongside the new put.
+     */
+    private readonly continuationIndex;
+    /** Single delivery chain: writes reach the sink serialized, in order. */
+    private queue;
+    /** Ops on the queue not yet delivered (bounded by MAX_PENDING_OPS). */
+    private pending;
+    /** Ops dropped because the queue was full. */
+    private dropped;
+    private lastAbSnapshotAt;
+    private closed;
+    constructor(options: PersistenceCoordinatorOptions);
+    /** Durable session-record update (engine calls after every store save). */
+    sessionRecord(record: SessionRecord): void;
+    /** One appended session event (engine calls from its dispatch funnel). */
+    event(event: SessionEvent): void;
+    /**
+     * A boundary event's dispatch settled: channel/hook handlers ran and
+     * their record updates (channel state, continuation tokens) are
+     * buffered. This — not the append — is the turn-end flush point, so the
+     * persisted session record includes the boundary event's own handler
+     * mutations. Debounced batching intentionally ignores boundaries.
+     */
+    eventDispatched(event: SessionEvent): void;
+    /** Flush everything buffered for one session (ordered: events, record). */
+    flushSession(sessionId: string, reason?: PersistenceContext["reason"]): void;
+    /**
+     * Index maintenance for `continuation/{channelId}/{token}` → sessionId:
+     * put the current token, delete the previous one when it changed.
+     */
+    private continuationOps;
+    /** Whether the sink can serve the startup bulk restore (`list`). */
+    get canBulkRestore(): boolean;
+    /**
+     * Saved session records for this agent (startup restore). Errors are
+     * logged and read as "nothing saved" — a broken store must never block
+     * serve start.
+     */
+    listSessions(): Promise<SessionRecord[]>;
+    /**
+     * Saved event stream for one session: chunk values concatenated in key
+     * order (chunks are keyed by their first event's index, zero-padded, so
+     * ascending key order is append order). Errors read as an empty stream.
+     */
+    listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
+    /**
+     * One saved session by channel continuation key (lazy restore). Unlike
+     * the startup reads, sink errors **propagate**: a failing store must
+     * fail the follow-up (which the caller can retry) rather than read as
+     * "unknown token" — that would mint a new session under the same
+     * continuation key and permanently shadow the real one on this host.
+     * A definitive miss (no index entry, or a write-only sink without
+     * `get`) resolves undefined.
+     */
+    getSessionByContinuation(channelId: string, continuationKey: string): Promise<SessionRecord | undefined>;
+    /**
+     * Adapter for {@link EvalRunPersistence} so the playground eval store
+     * can fall back to this sink when `evals.config.ts` sets no
+     * `persistRuns`.
+     */
+    asEvalRunPersistence(): EvalRunPersistence;
+    /**
+     * Adapter for {@link ABSamplePersistence} so the AB collector can fall
+     * back to this sink when `ab.config.ts` sets no `persistSamples`.
+     */
+    asABSamplePersistence(): ABSamplePersistence;
+    /**
+     * 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).
+     */
+    abSnapshot(snapshot: ABSnapshot): void;
+    /** Latest persisted aggregate A/B snapshot; errors read as absent. */
+    getLatestAbSnapshot(): Promise<ABSnapshot | undefined>;
+    /**
+     * Flush all buffers and drain the queue, giving the sink at most
+     * {@link CLOSE_DRAIN_TIMEOUT_MS} — a hung sink must not stall shutdown
+     * past the pod grace period. Called from engine close.
+     */
+    close(): Promise<void>;
+    /** Pending deliveries (exposed for tests and drain instrumentation). */
+    whenIdle(): Promise<void>;
+    private buffer;
+    private armDebounce;
+    /** `list` wrapper for the startup reads: missing hook or throw ⇒ empty. */
+    private tryList;
+    private enqueue;
+    private context;
+}
+//# sourceMappingURL=persistence-coordinator.d.ts.map

package/dist/internal/persistence-coordinator.d.ts.map

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

package/dist/internal/server.js

@@ -846,14 +846,16 @@ function mountAgentRoutes(router, runtime, args) {
             const body = yield readJsonObject(request);
             const filterIds = asStringArray(body === null || body === void 0 ? void 0 : body.filterIds);
             const tags = asStringArray(body === null || body === void 0 ? void 0 : body.tags);
+            const timeoutMs = asPositiveInt(body === null || body === void 0 ? void 0 : body.timeoutMs);
+            const verbose = (body === null || body === void 0 ? void 0 : body.verbose) === true;
             const authHeader = request.headers.get("authorization");
             const bearerToken = (authHeader === null || authHeader === void 0 ? void 0 : authHeader.toLowerCase().startsWith("bearer "))
                 ? authHeader.slice("bearer ".length).trim()
                 : undefined;
             try {
-                const snap = yield runtime.evalRuns.start(Object.assign(Object.assign(Object.assign({}, (filterIds === undefined ? {} : { filterIds })), (tags === undefined ? {} : { tags })), (bearerToken === undefined || bearerToken === ""
+                const snap = yield runtime.evalRuns.start(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (filterIds === undefined ? {} : { filterIds })), (tags === undefined ? {} : { tags })), (bearerToken === undefined || bearerToken === ""
                     ? {}
-                    : { bearerToken })));
+                    : { bearerToken })), (timeoutMs === undefined ? {} : { timeoutMs })), (verbose ? { verbose: true } : {})));
                 return jsonResponse(snap, { status: 202 });
             }
             catch (error) {
@@ -1488,6 +1490,13 @@ function asStringArray(value) {
     }
     return out.length === 0 ? undefined : out;
 }
+function asPositiveInt(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const n = Math.floor(value);
+    return n > 0 ? n : undefined;
+}
 function assertReminderReadable(input) {
     return __awaiter(this, void 0, void 0, function* () {
         const existing = yield input.engine.sessions.findByContinuation(input.reminder.channelId, input.reminder.continuationToken);

package/dist/persistence.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Durable persistence plug-in for agent-serve.
+ *
+ * Author `agent/persistence.ts` with {@link definePersistence} to mirror the
+ * framework's durable state into storage you own (a database, S3, a data
+ * pipeline, …). Without it, state lives under `--state-root` on local disk
+ * only (and eval/A/B history follows the narrower `persistRuns` /
+ * `persistSamples` / `persistSnapshots` hooks).
+ *
+ * The sink is a plain key-value store — four functions, no schema:
+ *
+ * ```ts
+ * import { definePersistence } from "@anysphere/agent-serve/persistence";
+ *
+ * export default definePersistence({
+ *   put: (key, value) => db.upsert(key, value),
+ *   get: (key) => db.get(key),
+ *   delete: (key) => db.delete(key),
+ *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
+ * });
+ * ```
+ *
+ * The **framework mints every key** from a stable, versioned scheme (see
+ * {@link persistenceKeys}) and decides **when** to call the sink: session
+ * records and event chunks flush when a turn's handlers have settled,
+ * reads happen at serve start (bulk restore), on continuation-token misses
+ * (lazy restore), and at playground hydration. Authors do not schedule
+ * reads or writes — the only timing knobs are {@link PersistencePolicy}'s
+ * `debounceMs` (event write batching) and `restore` (startup hydration).
+ *
+ * Because keys are opaque strings to the sink, new kinds of durable state
+ * (reminders, channel cursors, thread affinity, …) are new key prefixes —
+ * existing sinks store them with no code changes.
+ *
+ * Delivery semantics: writes are **serialized** (one sink call in flight
+ * per agent, in order), **bounded** (a sink that falls behind sheds writes
+ * rather than growing memory), and **at-most-once** — a throwing `put` is
+ * logged and dropped, never retried, and never fails a turn. The local
+ * event log under `--state-root` remains the live source of truth; this
+ * interface is the durable mirror.
+ */
+import type { JsonValue } from "./types.js";
+/** One `{ key, value }` pair returned by {@link PersistenceConfig.list}. */
+export interface PersistenceEntry {
+    key: string;
+    value: JsonValue;
+}
+/** Context passed to every sink call. */
+export interface PersistenceContext {
+    /** Agent name (also baked into every key; see {@link persistenceKeys}). */
+    agentName: string;
+    /** Absolute agent project root (directory that contains `agent/`). */
+    projectRoot: string;
+    /**
+     * Why the framework is calling:
+     * - `"policy"` — a flush trigger fired (turn end, debounce, change)
+     * - `"shutdown"` — the serve process is draining; last chance to write
+     * - `"restore"` — serve start or a lazy restore; reads rebuilding state
+     */
+    reason: "policy" | "shutdown" | "restore";
+}
+export interface PersistencePolicy {
+    /**
+     * Batch event-chunk writes on a quiet-period timer instead of flushing
+     * once per turn. The debounce **spans turn boundaries** — a rapid
+     * multi-turn exchange becomes one write when the session goes quiet —
+     * so it is the right choice for chatty sessions where per-turn writes
+     * are too many. Unset (default): one event chunk per turn.
+     */
+    debounceMs?: number;
+    /**
+     * Guardrails for the **startup bulk restore**. Whatever `list` returns
+     * is filtered to these caps before anything is written to local disk, so
+     * a large store cannot blow up `--state-root` or stall serve start.
+     * Newest sessions (by `updatedAt`) win within each cap.
+     *
+     * `"off"` disables the startup restore entirely — sessions then restore
+     * one at a time as follow-ups actually arrive (lazy-only; recommended
+     * for high-traffic deployments).
+     */
+    restore?: PersistenceRestorePolicy | "off";
+}
+/** Caps applied to the startup bulk restore. See {@link PersistencePolicy.restore}. */
+export interface PersistenceRestorePolicy {
+    /** Max sessions materialized (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS}). */
+    maxSessions?: number;
+    /**
+     * Skip sessions whose `updatedAt` is older than this (default
+     * {@link PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
+     * reachable lazily on their next follow-up.
+     */
+    maxAgeMs?: number;
+    /**
+     * Stop restoring once this many bytes of records + events have been
+     * written (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
+     * Checked before each session is written, so one oversized stream
+     * cannot blow past the budget.
+     */
+    maxTotalBytes?: number;
+}
+export interface PersistenceConfig {
+    /** Optional label surfaced on `GET /v1/info` diagnostics. */
+    name?: string;
+    /** Timing knobs; see {@link PersistencePolicy}. */
+    policy?: PersistencePolicy;
+    /**
+     * Store one value under a key (upsert, last-write-wins). Called on the
+     * framework's schedule — never concurrently, always in order. Keep it
+     * fast or buffer internally: the delivery queue is bounded, so a sink
+     * that falls behind sustained traffic sheds writes (logged) instead of
+     * growing memory; it never stalls the agent loop.
+     */
+    put(key: string, value: JsonValue, ctx: PersistenceContext): void | Promise<void>;
+    /** Remove a key. Optional — without it, deletions are skipped. */
+    delete?(key: string, ctx: PersistenceContext): void | Promise<void>;
+    /**
+     * Point lookup. Optional — required for **lazy restore** (resolving a
+     * continuation token on a replacement host) and the A/B backfill.
+     * Return `undefined`/`null` only for a **definitive** miss: on the lazy
+     * restore path a throw propagates and fails the follow-up (retryable) —
+     * a store outage must not read as "unknown token", which would fork the
+     * conversation onto a new session.
+     */
+    get?(key: string, ctx: PersistenceContext): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
+    /**
+     * All entries under a key prefix, in ascending key order. Optional —
+     * required for the **startup bulk restore** (sessions + event streams)
+     * and playground eval history.
+     */
+    list?(prefix: string, ctx: PersistenceContext): PersistenceEntry[] | Promise<PersistenceEntry[]>;
+}
+export type PersistenceDefinition = PersistenceConfig & {
+    readonly __agentServe: "persistence";
+};
+/**
+ * Author the project persistence sink (`agent/persistence.ts`, default
+ * export). See the module doc for semantics and an example.
+ */
+export declare function definePersistence(config: PersistenceConfig): PersistenceDefinition;
+/**
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
+ * (the `v1/` root): sinks may treat them as opaque strings, or route on
+ * prefixes (e.g. event chunks to object storage, everything else to a
+ * database). Channel ids and continuation tokens are the only segments
+ * that may contain caller-controlled characters; they are URI-encoded.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `v1/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
+ * | `v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
+ * | `v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
+ */
+export declare const persistenceKeys: {
+    readonly session: (agent: string, sessionId: string) => string;
+    readonly sessionPrefix: (agent: string) => string;
+    readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
+    readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
+    readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
+    readonly evalRun: (agent: string, runId: string) => string;
+    readonly evalRunPrefix: (agent: string) => string;
+    readonly abSample: (agent: string, sessionId: string, at: string) => string;
+    readonly abSnapshot: (agent: string) => string;
+};
+export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;
+export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS: number;
+export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1073741824;
+/** {@link PersistencePolicy} with defaults applied. */
+export interface ResolvedPersistencePolicy {
+    /** Event-chunk flush trigger: per turn, or debounced across turns. */
+    events: "turnEnd" | {
+        debounceMs: number;
+    };
+    restore: "off" | {
+        maxSessions: number;
+        maxAgeMs: number;
+        maxTotalBytes: number;
+    };
+}
+/** Apply {@link PersistencePolicy} defaults (exposed for tooling/tests). */
+export declare function resolvePersistencePolicy(policy: PersistencePolicy | undefined): ResolvedPersistencePolicy;
+//# sourceMappingURL=persistence.d.ts.map