@cursor/july 0.1.1

package/dist/internal/ab-collector.js

@@ -0,0 +1,153 @@
+/**
+ * Stream-native collector for {@link defineAB} experiments.
+ *
+ * Pure fold over the session event log:
+ * - sticky arm = last `ab.assigned` for that experiment
+ * - metrics accumulate from the stream; `onSample` on turn complete/fail
+ *
+ * Enrollment is written by the engine at session creation (not here).
+ * In-memory state is a cache: on cold start (or after park eviction) the
+ * collector replays `events.ndjson` so counters survive restart.
+ *
+ * Hydration note: the engine appends before dispatch, so the first-touch
+ * replay already includes the current event — after rebuild we return
+ * without folding it again (and without re-firing `onSample`).
+ */
+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 { cloneABMetrics, } from "../ab.js";
+import { applyDeriveForEvent, emptyFoldedABSession, ensureArmAccum, foldABEvent, } from "./ab-fold.js";
+import { describeError } from "./describe-error.js";
+/** Drop cache after these — next event rehydrates from the durable log. */
+const EVICT_ON = new Set([
+    "session.waiting",
+    "session.completed",
+    "session.failed",
+]);
+export class ABCollector {
+    constructor(experiments, logger, loadEvents, options) {
+        this.experiments = experiments;
+        this.logger = logger;
+        this.loadEvents = loadEvents;
+        this.state = new Map();
+        this.hydrated = new Set();
+        this.projectRoot = options === null || options === void 0 ? void 0 : options.projectRoot;
+        this.persistSamples = options === null || options === void 0 ? void 0 : options.persistSamples;
+    }
+    get enabled() {
+        return this.experiments.length > 0;
+    }
+    /**
+     * Fold one live event. On first touch (or after eviction), replays the
+     * durable log first so enrollment + metrics match disk.
+     */
+    onEvent(event, sessionInfo, agentName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.enabled) {
+                return;
+            }
+            if (!this.hydrated.has(event.sessionId)) {
+                const history = yield this.loadEvents(event.sessionId);
+                // Rebuild arms + metrics only — do not re-fire onSample for past turns.
+                // History already includes `event` (append-before-dispatch).
+                for (const past of history) {
+                    yield this.fold(past, sessionInfo, agentName, { emitSamples: false });
+                }
+                this.hydrated.add(event.sessionId);
+                if (EVICT_ON.has(event.type)) {
+                    this.drop(event.sessionId);
+                }
+                return;
+            }
+            yield this.fold(event, sessionInfo, agentName, { emitSamples: true });
+            if (EVICT_ON.has(event.type)) {
+                this.drop(event.sessionId);
+            }
+        });
+    }
+    drop(sessionId) {
+        this.state.delete(sessionId);
+        this.hydrated.delete(sessionId);
+    }
+    fold(event, sessionInfo, agentName, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const session = this.sessionAccum(event.sessionId);
+            if (event.type === "ab.assigned") {
+                foldABEvent(session, event);
+                return;
+            }
+            if (session.arms.size === 0) {
+                return;
+            }
+            // Built-ins for every enrolled arm (shared fold).
+            foldABEvent(session, event);
+            for (const experiment of this.experiments) {
+                const variant = session.arms.get(experiment.name);
+                if (variant === undefined || variant === null) {
+                    continue;
+                }
+                const def = experiment.definition;
+                const accum = ensureArmAccum(session, experiment.name, variant);
+                if (def.derive !== undefined) {
+                    yield applyDeriveForEvent(accum.metrics.custom, def.derive, event, {
+                        agent: { name: agentName },
+                        channel: { id: sessionInfo.channelId },
+                        session: sessionInfo,
+                        experiment: experiment.name,
+                        variant,
+                    }, (key, error) => {
+                        this.logger(`[agent-serve] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
+                    });
+                }
+                if (!options.emitSamples) {
+                    continue;
+                }
+                const reason = sampleReason(event);
+                if (reason !== undefined) {
+                    const sample = Object.assign(Object.assign({ experiment: experiment.name, variant }, (((_a = def.variants[variant]) === null || _a === void 0 ? void 0 : _a.label) !== undefined
+                        ? { variantLabel: def.variants[variant].label }
+                        : {})), { sessionId: event.sessionId, channelId: sessionInfo.channelId, metrics: cloneABMetrics(accum.metrics), reason, at: event.at });
+                    try {
+                        yield def.onSample(sample);
+                    }
+                    catch (error) {
+                        this.logger(`[agent-serve] ab "${experiment.name}" onSample threw: ${describeError(error)}`);
+                    }
+                    if (this.persistSamples !== undefined &&
+                        this.projectRoot !== undefined) {
+                        try {
+                            yield this.persistSamples.save(sample, {
+                                projectRoot: this.projectRoot,
+                            });
+                        }
+                        catch (error) {
+                            this.logger(`[agent-serve] ab persistSamples.save threw: ${describeError(error)}`);
+                        }
+                    }
+                }
+            }
+        });
+    }
+    sessionAccum(sessionId) {
+        let session = this.state.get(sessionId);
+        if (session === undefined) {
+            session = emptyFoldedABSession();
+            this.state.set(sessionId, session);
+        }
+        return session;
+    }
+}
+function sampleReason(event) {
+    if (event.type === "turn.completed" || event.type === "turn.failed") {
+        return event.type;
+    }
+    return undefined;
+}

package/dist/internal/ab-fold.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure fold of a session event stream into A/B arms + cumulative metrics.
+ * Shared by {@link ABCollector} (live) and {@link buildABSnapshot} (read API).
+ */
+import { type ABCollectContext, type ABDefinition, type ABMetrics } from "../ab.js";
+import type { DiscoveredAB, SessionEvent, SessionInfo } from "../types.js";
+export interface ABArmAccum {
+    variant: string;
+    metrics: ABMetrics;
+    turnStartedAt: string | null;
+}
+export interface FoldedABSession {
+    /** experiment → variant key, or `null` for sticky skip */
+    arms: Map<string, string | null>;
+    /** experiment → metrics (only for enrolled arms) */
+    metrics: Map<string, ABArmAccum>;
+}
+export declare function emptyFoldedABSession(): FoldedABSession;
+/** Ensure a metrics bucket exists for an enrolled arm. */
+export declare function ensureArmAccum(state: FoldedABSession, experiment: string, variant: string): ABArmAccum;
+/** Fold one event's built-in metrics + assignment. Does not run `derive`. */
+export declare function foldABEvent(state: FoldedABSession, event: SessionEvent): void;
+export declare function foldABStream(events: readonly SessionEvent[]): FoldedABSession;
+/**
+ * Apply `derive` extractors for one event into `custom` counters.
+ * Errors are reported via `onError` and skipped.
+ */
+export declare function applyDeriveForEvent(custom: Record<string, number>, derive: NonNullable<ABDefinition["derive"]>, event: SessionEvent, collectCtx: ABCollectContext, onError: (key: string, error: unknown) => void): Promise<void>;
+/**
+ * Re-run `derive` extractors over the stream for enrolled arms.
+ * Mutates `state.metrics` in place. Errors are logged and skipped.
+ */
+export declare function applyABDerive(state: FoldedABSession, events: readonly SessionEvent[], experiments: readonly DiscoveredAB[], sessionInfo: SessionInfo, agentName: string, logger: (line: string) => void): Promise<void>;
+export declare function applyBuiltinMetrics(accum: ABArmAccum, event: SessionEvent): void;
+export declare function cloneFoldedMetrics(accum: ABArmAccum | undefined): ABMetrics | undefined;
+//# sourceMappingURL=ab-fold.d.ts.map

package/dist/internal/ab-fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab-fold.d.ts","sourceRoot":"","sources":["../../src/internal/ab-fold.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EAGf,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG3E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACjC,oDAAoD;IACpD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAClC;AAED,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,UAAU,CAWZ;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CA0B7E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,eAAe,CAM7E;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,EAC3C,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAC7C,OAAO,CAAC,IAAI,CAAC,CAWf;AAiBD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,WAAW,EAAE,SAAS,YAAY,EAAE,EACpC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,YAAY,GAClB,IAAI,CAgCN;AAcD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,SAAS,GAAG,SAAS,CAKvB"}

package/dist/internal/ab-fold.js

@@ -0,0 +1,171 @@
+/**
+ * Pure fold of a session event stream into A/B arms + cumulative metrics.
+ * Shared by {@link ABCollector} (live) and {@link buildABSnapshot} (read API).
+ */
+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 { cloneABMetrics, emptyABMetrics, } from "../ab.js";
+import { describeError } from "./describe-error.js";
+export function emptyFoldedABSession() {
+    return { arms: new Map(), metrics: new Map() };
+}
+/** Ensure a metrics bucket exists for an enrolled arm. */
+export function ensureArmAccum(state, experiment, variant) {
+    let accum = state.metrics.get(experiment);
+    if (accum === undefined) {
+        accum = {
+            variant,
+            metrics: emptyABMetrics(),
+            turnStartedAt: null,
+        };
+        state.metrics.set(experiment, accum);
+    }
+    return accum;
+}
+/** Fold one event's built-in metrics + assignment. Does not run `derive`. */
+export function foldABEvent(state, event) {
+    if (event.type === "ab.assigned") {
+        const { experiment, variant } = event.data;
+        state.arms.set(experiment, variant);
+        if (variant === null) {
+            state.metrics.delete(experiment);
+        }
+        else {
+            state.metrics.set(experiment, {
+                variant,
+                metrics: emptyABMetrics(),
+                turnStartedAt: null,
+            });
+        }
+        return;
+    }
+    if (state.arms.size === 0) {
+        return;
+    }
+    for (const [experiment, variant] of state.arms) {
+        if (variant === null) {
+            continue;
+        }
+        applyBuiltinMetrics(ensureArmAccum(state, experiment, variant), event);
+    }
+}
+export function foldABStream(events) {
+    const state = emptyFoldedABSession();
+    for (const event of events) {
+        foldABEvent(state, event);
+    }
+    return state;
+}
+/**
+ * Apply `derive` extractors for one event into `custom` counters.
+ * Errors are reported via `onError` and skipped.
+ */
+export function applyDeriveForEvent(custom, derive, event, collectCtx, onError) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        for (const [key, extract] of Object.entries(derive)) {
+            try {
+                const delta = yield extract(event, collectCtx);
+                if (typeof delta === "number" && Number.isFinite(delta)) {
+                    custom[key] = ((_a = custom[key]) !== null && _a !== void 0 ? _a : 0) + delta;
+                }
+            }
+            catch (error) {
+                onError(key, error);
+            }
+        }
+    });
+}
+function collectContext(experiment, variant, sessionInfo, agentName) {
+    return {
+        agent: { name: agentName },
+        channel: { id: sessionInfo.channelId },
+        session: sessionInfo,
+        experiment,
+        variant,
+    };
+}
+/**
+ * Re-run `derive` extractors over the stream for enrolled arms.
+ * Mutates `state.metrics` in place. Errors are logged and skipped.
+ */
+export function applyABDerive(state, events, experiments, sessionInfo, agentName, logger) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const experiment of experiments) {
+            const variant = state.arms.get(experiment.name);
+            if (variant === undefined || variant === null) {
+                continue;
+            }
+            const def = experiment.definition;
+            if (def.derive === undefined) {
+                continue;
+            }
+            const accum = ensureArmAccum(state, experiment.name, variant);
+            // Reset custom so a re-fold is idempotent.
+            accum.metrics.custom = {};
+            const ctx = collectContext(experiment.name, variant, sessionInfo, agentName);
+            for (const event of events) {
+                yield applyDeriveForEvent(accum.metrics.custom, def.derive, event, ctx, (key, error) => {
+                    logger(`[agent-serve] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
+                });
+            }
+        }
+    });
+}
+export function applyBuiltinMetrics(accum, event) {
+    const m = accum.metrics;
+    switch (event.type) {
+        case "turn.started":
+            accum.turnStartedAt = event.at;
+            break;
+        case "turn.completed": {
+            m.turns += 1;
+            const usage = event.data.usage;
+            if (usage !== undefined) {
+                m.inputTokens += usage.inputTokens;
+                m.outputTokens += usage.outputTokens;
+                m.cacheReadTokens += usage.cacheReadTokens;
+                m.cacheWriteTokens += usage.cacheWriteTokens;
+            }
+            addWallTime(accum, event.at);
+            break;
+        }
+        case "turn.failed":
+            m.turns += 1;
+            m.turnFailures += 1;
+            addWallTime(accum, event.at);
+            break;
+        case "action.result":
+            m.toolCalls += 1;
+            if (event.data.isError) {
+                m.toolErrors += 1;
+            }
+            break;
+        default:
+            break;
+    }
+}
+function addWallTime(accum, endedAt) {
+    if (accum.turnStartedAt === null) {
+        return;
+    }
+    const start = Date.parse(accum.turnStartedAt);
+    const end = Date.parse(endedAt);
+    accum.turnStartedAt = null;
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+        accum.metrics.wallTimeMs += end - start;
+    }
+}
+export function cloneFoldedMetrics(accum) {
+    if (accum === undefined) {
+        return undefined;
+    }
+    return cloneABMetrics(accum.metrics);
+}

package/dist/internal/ab-snapshot.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Read-only A/B metrics snapshot: fold durable session event streams into
+ * per-session assignments and aggregate arm totals. Used by `GET /v1/abs`.
+ */
+import { type ABMetrics, type ABVariantMeta } from "../ab.js";
+import type { DiscoveredAB, SessionEvent, SessionInfo, SessionRecord, SessionSummary } from "../types.js";
+export interface ABSnapshotAssignment {
+    experiment: string;
+    variant: string | null;
+    variantLabel?: string;
+    /** Present when enrolled (`variant` non-null). */
+    metrics?: ABMetrics;
+}
+export interface ABSnapshotSession {
+    sessionId: string;
+    channelId: string;
+    mode: string;
+    title?: string;
+    turnCount: number;
+    updatedAt?: string;
+    assignments: ABSnapshotAssignment[];
+}
+export interface ABSnapshotArm {
+    variant: string;
+    variantLabel?: string;
+    description?: string;
+    /** Sessions enrolled in this arm. */
+    sessions: number;
+    metrics: ABMetrics;
+}
+export interface ABSnapshotExperiment {
+    name: string;
+    variants: Record<string, ABVariantMeta>;
+    /** Sessions with sticky skip (`variant: null`). */
+    skipped: number;
+    arms: ABSnapshotArm[];
+}
+export interface ABSnapshotConfig {
+    /** Newest-first session fold window for this snapshot (`GET /v1/abs`). */
+    maxPlaygroundSessions?: number;
+    /** True when `persistSamples` is configured. */
+    durableSamples?: boolean;
+    /** True when `persistSnapshots` is configured. */
+    durableSnapshots?: boolean;
+    /** Set when writing via filesystem snapshot persistence helpers. */
+    snapshotId?: string;
+}
+export interface ABSnapshot {
+    experiments: ABSnapshotExperiment[];
+    sessions: ABSnapshotSession[];
+    config?: ABSnapshotConfig;
+}
+export interface BuildABSnapshotInput {
+    experiments: readonly DiscoveredAB[];
+    agentName: string;
+    /** Newest-first session list (same order as `GET /v1/sessions`). */
+    sessions: readonly SessionSummary[];
+    loadRecord: (sessionId: string) => Promise<SessionRecord | undefined>;
+    loadEvents: (sessionId: string) => Promise<SessionEvent[]>;
+    sessionInfo: (record: SessionRecord) => SessionInfo;
+    logger: (line: string) => void;
+    /** Max concurrent event-log reads (default 8). */
+    concurrency?: number;
+    /** Attached to the returned snapshot (playground / persistence meta). */
+    config?: ABSnapshotConfig;
+}
+export declare function buildABSnapshot(input: BuildABSnapshotInput): Promise<ABSnapshot>;
+/** Narrow helper so callers don't need the unused DiscoveredAB import above. */
+export type { DiscoveredAB };
+//# sourceMappingURL=ab-snapshot.d.ts.map

package/dist/internal/ab-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab-snapshot.d.ts","sourceRoot":"","sources":["../../src/internal/ab-snapshot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,aAAa,EAGnB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACtE,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC3D,WAAW,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,WAAW,CAAC;IACpD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAiOrB;AAiBD,gFAAgF;AAChF,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/internal/ab-snapshot.js

@@ -0,0 +1,208 @@
+/**
+ * Read-only A/B metrics snapshot: fold durable session event streams into
+ * per-session assignments and aggregate arm totals. Used by `GET /v1/abs`.
+ */
+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 { cloneABMetrics, emptyABMetrics, } from "../ab.js";
+import { applyABDerive, cloneFoldedMetrics, foldABStream } from "./ab-fold.js";
+import { mapPool } from "./map-pool.js";
+export function buildABSnapshot(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const experiments = input.experiments;
+        const experimentByName = new Map(experiments.map((experiment) => [experiment.name, experiment]));
+        const armTotals = new Map();
+        const skipped = new Map();
+        for (const experiment of experiments) {
+            armTotals.set(experiment.name, new Map());
+            skipped.set(experiment.name, 0);
+            for (const variant of Object.keys(experiment.definition.variants)) {
+                armTotals.get(experiment.name).set(variant, {
+                    sessions: 0,
+                    metrics: emptyABMetrics(),
+                });
+            }
+        }
+        const concurrency = Math.max(1, (_a = input.concurrency) !== null && _a !== void 0 ? _a : 8);
+        const sessionRows = [];
+        function processOne(summary) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                var _c, _d;
+                const record = yield input.loadRecord(summary.sessionId);
+                if (record === undefined) {
+                    return;
+                }
+                // Eval harness sessions never enroll; keep them out of aggregates too.
+                if (record.purpose === "eval") {
+                    return;
+                }
+                const events = yield input.loadEvents(summary.sessionId);
+                const folded = foldABStream(events);
+                if (experiments.length > 0) {
+                    yield applyABDerive(folded, events, experiments, input.sessionInfo(record), input.agentName, input.logger);
+                }
+                const assignments = [];
+                // Prefer declared experiment order; include unknown arms from the log after.
+                const seen = new Set();
+                for (const experiment of experiments) {
+                    seen.add(experiment.name);
+                    const variant = folded.arms.get(experiment.name);
+                    if (variant === undefined) {
+                        continue;
+                    }
+                    const def = experiment.definition;
+                    const label = variant === null ? undefined : (_a = def.variants[variant]) === null || _a === void 0 ? void 0 : _a.label;
+                    const metrics = variant === null
+                        ? undefined
+                        : cloneFoldedMetrics(folded.metrics.get(experiment.name));
+                    assignments.push(Object.assign(Object.assign({ experiment: experiment.name, variant }, (label !== undefined ? { variantLabel: label } : {})), (metrics !== undefined ? { metrics } : {})));
+                    if (variant === null) {
+                        skipped.set(experiment.name, ((_c = skipped.get(experiment.name)) !== null && _c !== void 0 ? _c : 0) + 1);
+                    }
+                    else {
+                        const bucket = (_b = armTotals.get(experiment.name)) === null || _b === void 0 ? void 0 : _b.get(variant);
+                        if (bucket !== undefined && metrics !== undefined) {
+                            bucket.sessions += 1;
+                            addMetrics(bucket.metrics, metrics);
+                        }
+                        else if (bucket === undefined) {
+                            // Assigned to an arm no longer in the definition — still surface it.
+                            const arms = (_d = armTotals.get(experiment.name)) !== null && _d !== void 0 ? _d : new Map();
+                            const created = {
+                                sessions: 1,
+                                metrics: metrics !== undefined
+                                    ? cloneABMetrics(metrics)
+                                    : emptyABMetrics(),
+                            };
+                            arms.set(variant, created);
+                            armTotals.set(experiment.name, arms);
+                        }
+                    }
+                }
+                for (const [experiment, variant] of folded.arms) {
+                    if (seen.has(experiment)) {
+                        continue;
+                    }
+                    const metrics = variant === null
+                        ? undefined
+                        : cloneFoldedMetrics(folded.metrics.get(experiment));
+                    assignments.push(Object.assign({ experiment,
+                        variant }, (metrics !== undefined ? { metrics } : {})));
+                }
+                if (assignments.length === 0) {
+                    return;
+                }
+                sessionRows.push(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: summary.sessionId, channelId: summary.channelId, mode: summary.mode }, (summary.title === undefined ? {} : { title: summary.title })), { turnCount: summary.turnCount }), (summary.updatedAt === undefined
+                    ? {}
+                    : { updatedAt: summary.updatedAt })), { assignments }));
+            });
+        }
+        yield mapPool(input.sessions, concurrency, (summary) => __awaiter(this, void 0, void 0, function* () {
+            yield processOne(summary);
+        }));
+        // Preserve newest-first order from the sessions list.
+        const order = new Map(input.sessions.map((summary, index) => [summary.sessionId, index]));
+        sessionRows.sort((a, b) => { var _a, _b; return ((_a = order.get(a.sessionId)) !== null && _a !== void 0 ? _a : 0) - ((_b = order.get(b.sessionId)) !== null && _b !== void 0 ? _b : 0); });
+        const experimentRows = experiments.map((experiment) => {
+            var _a;
+            var _b, _c, _d;
+            const def = experiment.definition;
+            const arms = [];
+            for (const [variant, meta] of Object.entries(def.variants)) {
+                const bucket = (_b = (_a = armTotals.get(experiment.name)) === null || _a === void 0 ? void 0 : _a.get(variant)) !== null && _b !== void 0 ? _b : {
+                    sessions: 0,
+                    metrics: emptyABMetrics(),
+                };
+                arms.push(Object.assign(Object.assign(Object.assign({ variant }, (meta.label !== undefined ? { variantLabel: meta.label } : {})), (meta.description !== undefined
+                    ? { description: meta.description }
+                    : {})), { sessions: bucket.sessions, metrics: cloneABMetrics(bucket.metrics) }));
+            }
+            // Orphan arms from the log (no longer in definition).
+            for (const [variant, bucket] of (_c = armTotals.get(experiment.name)) !== null && _c !== void 0 ? _c : []) {
+                if (variant in def.variants) {
+                    continue;
+                }
+                arms.push({
+                    variant,
+                    sessions: bucket.sessions,
+                    metrics: cloneABMetrics(bucket.metrics),
+                });
+            }
+            return {
+                name: experiment.name,
+                variants: def.variants,
+                skipped: (_d = skipped.get(experiment.name)) !== null && _d !== void 0 ? _d : 0,
+                arms,
+            };
+        });
+        // Experiments that appear only in logs (definition removed).
+        const known = new Set(experiments.map((experiment) => experiment.name));
+        const orphanNames = new Set();
+        for (const row of sessionRows) {
+            for (const assignment of row.assignments) {
+                if (!known.has(assignment.experiment)) {
+                    orphanNames.add(assignment.experiment);
+                }
+            }
+        }
+        for (const name of orphanNames) {
+            const armsMap = new Map();
+            let skipCount = 0;
+            for (const row of sessionRows) {
+                for (const assignment of row.assignments) {
+                    if (assignment.experiment !== name) {
+                        continue;
+                    }
+                    if (assignment.variant === null) {
+                        skipCount += 1;
+                        continue;
+                    }
+                    const bucket = (_b = armsMap.get(assignment.variant)) !== null && _b !== void 0 ? _b : {
+                        sessions: 0,
+                        metrics: emptyABMetrics(),
+                    };
+                    bucket.sessions += 1;
+                    if (assignment.metrics !== undefined) {
+                        addMetrics(bucket.metrics, assignment.metrics);
+                    }
+                    armsMap.set(assignment.variant, bucket);
+                }
+            }
+            experimentRows.push({
+                name,
+                variants: {},
+                skipped: skipCount,
+                arms: [...armsMap.entries()].map(([variant, bucket]) => ({
+                    variant,
+                    sessions: bucket.sessions,
+                    metrics: cloneABMetrics(bucket.metrics),
+                })),
+            });
+        }
+        return Object.assign({ experiments: experimentRows, sessions: sessionRows }, (input.config === undefined ? {} : { config: input.config }));
+    });
+}
+function addMetrics(target, delta) {
+    var _a;
+    target.turns += delta.turns;
+    target.turnFailures += delta.turnFailures;
+    target.toolCalls += delta.toolCalls;
+    target.toolErrors += delta.toolErrors;
+    target.inputTokens += delta.inputTokens;
+    target.outputTokens += delta.outputTokens;
+    target.cacheReadTokens += delta.cacheReadTokens;
+    target.cacheWriteTokens += delta.cacheWriteTokens;
+    target.wallTimeMs += delta.wallTimeMs;
+    for (const [key, value] of Object.entries(delta.custom)) {
+        target.custom[key] = ((_a = target.custom[key]) !== null && _a !== void 0 ? _a : 0) + value;
+    }
+}