@tokenfactory/acc-runner 0.40.23 → 0.40.25

package/dist/warm-session/latency.d.ts

@@ -0,0 +1,72 @@
+/**
+ * CX-4 (WARM-SESSIONS): the first-token latency recorder.
+ *
+ * The default `OpsMetricsSink` the pool reports into. It keeps a bounded ring of
+ * recent first-token samples PER MODE (warm/cold) and computes p50/p95 with the
+ * nearest-rank method, so Pulse can render "warm p50 <= 1.5s / cold <= 4s" from
+ * one snapshot. No-token turns (an empty/failed reply, `firstTokenMs === null`)
+ * are counted but EXCLUDED from the percentile so a broken turn never flatters
+ * or poisons the latency picture. A follow-up wires an adapter over this that
+ * forwards each sample to the durable ops-metrics topic; this recorder is the
+ * pure, deterministic core the benchmark asserts against.
+ *
+ * STAGING: intentionally `dead-until-wired` — the ops-metrics/Pulse adapter over
+ * this recorder lands in a follow-up (see the task's Follow-ups).
+ */
+import { type FirstTokenMode, type FirstTokenSample, type OpsMetricsSink } from "./types.js";
+/** Percentile view of one mode's first-token samples (ms); null when empty. */
+export interface FirstTokenPercentiles {
+    /** Total samples recorded for the mode (includes no-token turns). */
+    count: number;
+    /** Samples that produced a visible token (the percentile population). */
+    tokenCount: number;
+    p50: number | null;
+    p95: number | null;
+    min: number | null;
+    max: number | null;
+    /** Simple arithmetic mean of the token-bearing samples (ms). */
+    mean: number | null;
+}
+/** A full warm-vs-cold snapshot plus the pass/fail against the plan targets. */
+export interface FirstTokenStats {
+    warm: FirstTokenPercentiles;
+    cold: FirstTokenPercentiles;
+    /** True when warm has ≥1 token sample and its p50 ≤ the warm target. */
+    warmP50WithinTarget: boolean;
+    /** True when cold has ≥1 token sample and its p95 ≤ the cold target. */
+    coldP95WithinTarget: boolean;
+    targets: {
+        warmP50Ms: number;
+        coldP95Ms: number;
+    };
+}
+/**
+ * Nearest-rank percentile over an ASCENDING-sorted array. `p` is 0..100. Returns
+ * null for an empty array. index = clamp(ceil(p/100 * n) - 1, 0, n-1).
+ */
+export declare function percentile(sortedAsc: readonly number[], p: number): number | null;
+export interface FirstTokenLatencyRecorderOptions {
+    /** Max samples retained per mode (ring buffer); older samples are evicted. */
+    maxSamplesPerMode?: number;
+    /** Warm p50 target (ms) — defaults to the plan's 1.5s. */
+    warmP50TargetMs?: number;
+    /** Cold p95 target (ms) — defaults to the plan's 4s. */
+    coldP95TargetMs?: number;
+}
+/** In-memory, bounded first-token recorder implementing `OpsMetricsSink`. */
+export declare class FirstTokenLatencyRecorder implements OpsMetricsSink {
+    private readonly byMode;
+    private readonly maxSamples;
+    private readonly warmP50TargetMs;
+    private readonly coldP95TargetMs;
+    constructor(opts?: FirstTokenLatencyRecorderOptions);
+    recordFirstToken(sample: FirstTokenSample): void;
+    /** All retained samples for a mode (stable copy). */
+    samples(mode: FirstTokenMode): readonly FirstTokenSample[];
+    private percentilesFor;
+    /** Current warm/cold percentiles plus pass/fail against the targets. */
+    snapshot(): FirstTokenStats;
+    /** Drop all retained samples (test/rig reset). */
+    reset(): void;
+}
+//# sourceMappingURL=latency.d.ts.map

package/dist/warm-session/latency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency.d.ts","sourceRoot":"","sources":["../../src/warm-session/latency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,wEAAwE;IACxE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wEAAwE;IACxE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAYD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjF;AAED,MAAM,WAAW,gCAAgC;IAC/C,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,6EAA6E;AAC7E,qBAAa,yBAA0B,YAAW,cAAc;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,IAAI,GAAE,gCAAqC;IAMvD,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAOhD,qDAAqD;IACrD,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,gBAAgB,EAAE;IAI1D,OAAO,CAAC,cAAc;IAoBtB,wEAAwE;IACxE,QAAQ,IAAI,eAAe;IAY3B,kDAAkD;IAClD,KAAK,IAAI,IAAI;CAId"}

package/dist/warm-session/latency.js

@@ -0,0 +1,102 @@
+/**
+ * CX-4 (WARM-SESSIONS): the first-token latency recorder.
+ *
+ * The default `OpsMetricsSink` the pool reports into. It keeps a bounded ring of
+ * recent first-token samples PER MODE (warm/cold) and computes p50/p95 with the
+ * nearest-rank method, so Pulse can render "warm p50 <= 1.5s / cold <= 4s" from
+ * one snapshot. No-token turns (an empty/failed reply, `firstTokenMs === null`)
+ * are counted but EXCLUDED from the percentile so a broken turn never flatters
+ * or poisons the latency picture. A follow-up wires an adapter over this that
+ * forwards each sample to the durable ops-metrics topic; this recorder is the
+ * pure, deterministic core the benchmark asserts against.
+ *
+ * STAGING: intentionally `dead-until-wired` — the ops-metrics/Pulse adapter over
+ * this recorder lands in a follow-up (see the task's Follow-ups).
+ */
+import { COLD_FIRST_TOKEN_TARGET_MS, WARM_FIRST_TOKEN_P50_TARGET_MS, } from "./types.js";
+const EMPTY_PERCENTILES = {
+    count: 0,
+    tokenCount: 0,
+    p50: null,
+    p95: null,
+    min: null,
+    max: null,
+    mean: null,
+};
+/**
+ * Nearest-rank percentile over an ASCENDING-sorted array. `p` is 0..100. Returns
+ * null for an empty array. index = clamp(ceil(p/100 * n) - 1, 0, n-1).
+ */
+export function percentile(sortedAsc, p) {
+    const n = sortedAsc.length;
+    if (n === 0)
+        return null;
+    const rank = Math.ceil((p / 100) * n);
+    const idx = Math.min(n - 1, Math.max(0, rank - 1));
+    return sortedAsc[idx] ?? null;
+}
+const DEFAULT_MAX_SAMPLES = 1_000;
+/** In-memory, bounded first-token recorder implementing `OpsMetricsSink`. */
+export class FirstTokenLatencyRecorder {
+    byMode = {
+        warm: [],
+        cold: [],
+    };
+    maxSamples;
+    warmP50TargetMs;
+    coldP95TargetMs;
+    constructor(opts = {}) {
+        this.maxSamples = Math.max(1, Math.floor(opts.maxSamplesPerMode ?? DEFAULT_MAX_SAMPLES));
+        this.warmP50TargetMs = opts.warmP50TargetMs ?? WARM_FIRST_TOKEN_P50_TARGET_MS;
+        this.coldP95TargetMs = opts.coldP95TargetMs ?? COLD_FIRST_TOKEN_TARGET_MS;
+    }
+    recordFirstToken(sample) {
+        const bucket = this.byMode[sample.mode];
+        bucket.push(sample);
+        // Ring: drop the oldest once past the cap so retention stays bounded.
+        if (bucket.length > this.maxSamples)
+            bucket.splice(0, bucket.length - this.maxSamples);
+    }
+    /** All retained samples for a mode (stable copy). */
+    samples(mode) {
+        return [...this.byMode[mode]];
+    }
+    percentilesFor(mode) {
+        const all = this.byMode[mode];
+        if (all.length === 0)
+            return { ...EMPTY_PERCENTILES };
+        const tokenMs = all
+            .filter((s) => s.sawToken && typeof s.firstTokenMs === "number")
+            .map((s) => s.firstTokenMs)
+            .sort((a, b) => a - b);
+        const tokenCount = tokenMs.length;
+        const sum = tokenMs.reduce((acc, v) => acc + v, 0);
+        return {
+            count: all.length,
+            tokenCount,
+            p50: percentile(tokenMs, 50),
+            p95: percentile(tokenMs, 95),
+            min: tokenCount > 0 ? tokenMs[0] : null,
+            max: tokenCount > 0 ? tokenMs[tokenCount - 1] : null,
+            mean: tokenCount > 0 ? sum / tokenCount : null,
+        };
+    }
+    /** Current warm/cold percentiles plus pass/fail against the targets. */
+    snapshot() {
+        const warm = this.percentilesFor("warm");
+        const cold = this.percentilesFor("cold");
+        return {
+            warm,
+            cold,
+            warmP50WithinTarget: warm.p50 !== null && warm.p50 <= this.warmP50TargetMs,
+            coldP95WithinTarget: cold.p95 !== null && cold.p95 <= this.coldP95TargetMs,
+            targets: { warmP50Ms: this.warmP50TargetMs, coldP95Ms: this.coldP95TargetMs },
+        };
+    }
+    /** Drop all retained samples (test/rig reset). */
+    reset() {
+        this.byMode.warm.length = 0;
+        this.byMode.cold.length = 0;
+    }
+}
+//# sourceMappingURL=latency.js.map

package/dist/warm-session/latency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latency.js","sourceRoot":"","sources":["../../src/warm-session/latency.ts"],"names":[],"mappings":"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"}

package/dist/warm-session/pool.d.ts

@@ -0,0 +1,153 @@
+/**
+ * CX-4 (WARM-SESSIONS): the warm-session pool.
+ *
+ * Holds at most one pre-spawned, resumable engine session per ACTIVE
+ * conversation and routes each turn through the fastest available path:
+ *
+ *   - WARM HIT  — a `ready`, alive session exists for the conversation → resume
+ *     it (fast first token). The session is marked `in_use` for the turn and
+ *     returned to `ready` on a CLEAN finish so the NEXT turn is warm too.
+ *   - COLD MISS — no warm session (never warmed, still warming, evicted, or
+ *     expired) → fall through to the injected `coldStream`, which is the
+ *     UNCHANGED per-turn spawn (an engine's `streamTurn`). A background
+ *     `prewarm` is kicked so the conversation's NEXT turn is warm. The cold path
+ *     is byte-for-byte the pre-warm behaviour, so cold latency is a strict
+ *     regression baseline.
+ *
+ * Every turn emits ONE first-token latency sample (tagged warm/cold) to the
+ * injected `OpsMetricsSink`. Idle sessions are swept after a TTL with clean
+ * teardown, and — critically — an IDLE warm session holds ZERO capacity:
+ * `capacityHeld()` counts only `in_use` sessions, so a warm-but-idle session is
+ * never mistaken for an in-flight turn by the chat-lane claim budget.
+ *
+ * Fully injectable (factory / cold path / clock / metrics / logger), so the
+ * whole lifecycle — warm/cold routing, latency tagging, idle sweep, teardown,
+ * capacity accounting — is exercised with a fake clock and scripted engine, no
+ * `claude` binary and no network.
+ *
+ * STAGING: intentionally `dead-until-wired` — the companion folds `capacityHeld()`
+ * into its chat-lane claim budget and routes turns through `runTurn` in a
+ * follow-up (see the task's Follow-ups).
+ */
+import type { EngineStreamChunk, EngineStreamTurnOptions } from "../engines/types.js";
+import { type FirstTokenMode, type OpsMetricsSink, type WarmSessionFactory, type WarmSpawnArgs, type WarmTeardownReason } from "./types.js";
+/** The unchanged cold path: an engine's per-turn `streamTurn`. */
+export type ColdStreamFn = (opts: EngineStreamTurnOptions) => AsyncIterable<EngineStreamChunk>;
+export interface WarmSessionPoolOptions {
+    /** Pre-spawns resumable sessions (the ONE engine seam). */
+    factory: WarmSessionFactory;
+    /** The unchanged per-turn spawn used when no warm session is ready. */
+    coldStream: ColdStreamFn;
+    /** Where first-token latency samples are reported. */
+    metrics: OpsMetricsSink;
+    /** Idle-expiry TTL (ms); a `ready` session idle longer than this is torn down. */
+    idleTtlMs?: number;
+    /** Max concurrent warm sessions; a cold miss past this does not prewarm. */
+    maxSessions?: number;
+    /** Idle-sweep cadence for `start()` (ms). */
+    sweepIntervalMs?: number;
+    /** Clock (test seam). */
+    now?: () => number;
+    /** Best-effort log sink. */
+    onLog?: (line: string) => void;
+}
+/** The result of routing one turn: the chosen mode + the measured stream. */
+export interface WarmTurnHandle {
+    /** Whether the turn is being served warm (reused session) or cold (fresh spawn). */
+    mode: FirstTokenMode;
+    /** The warm session id when `mode === "warm"`, else null. */
+    sessionId: string | null;
+    /**
+     * The turn's delta stream, instrumented for first-token latency. Iterating to
+     * completion (or breaking / throwing early) records exactly ONE latency sample
+     * and releases the warm session. The consumer drives it exactly as it would a
+     * bare `streamTurn`.
+     */
+    stream: AsyncGenerator<EngineStreamChunk, void, void>;
+}
+/** Observable pool sizes (for logging / the doctor surface). */
+export interface WarmPoolStats {
+    size: number;
+    ready: number;
+    warming: number;
+    inUse: number;
+    /** Capacity held right now — equals `inUse` (idle warm sessions hold none). */
+    capacityHeld: number;
+}
+export declare class WarmSessionPool {
+    private readonly opts;
+    private readonly entries;
+    private readonly idleTtlMs;
+    private readonly maxSessions;
+    private readonly sweepIntervalMs;
+    private readonly now;
+    private timer;
+    private stopped;
+    constructor(opts: WarmSessionPoolOptions);
+    /** Number of conversations with a warm-session slot (any phase). */
+    size(): number;
+    /** Conversations with a `ready`, reusable warm session. */
+    readyConversations(): string[];
+    /**
+     * Capacity held by the pool RIGHT NOW: the count of sessions with a turn
+     * actively streaming (`in_use`). An idle/warming warm session holds ZERO —
+     * this is the "idle != tokens" invariant the chat-lane claim budget relies on,
+     * so a wired companion adds THIS (not the warm-session count) to its in-flight
+     * accounting. A pre-warmed but idle conversation must never shrink the budget.
+     */
+    capacityHeld(): number;
+    stats(): WarmPoolStats;
+    /**
+     * Pre-spawn a resumable session for a conversation ahead of its next turn.
+     * Idempotent + deduped: a no-op when a `ready`/`warming`/`in_use` slot already
+     * exists, and concurrent calls share ONE warm-up. Returns true when a session
+     * is (or is already) warming/ready, false when the pool declined (stopped or
+     * at the `maxSessions` cap). Never throws — a failed warm logs and resolves
+     * false so the cold path still serves the turn.
+     */
+    prewarm(conversationId: string, args?: Omit<WarmSpawnArgs, "conversationId">): Promise<boolean>;
+    /** Run the factory warm-up, transitioning the entry to `ready` or evicting it. */
+    private doWarm;
+    /**
+     * Route one turn. Returns the chosen `mode`, the warm `sessionId` (or null),
+     * and an instrumented `stream` the caller drives exactly like a bare
+     * `streamTurn`. Consuming the stream to its end — or breaking/throwing early —
+     * records ONE first-token latency sample and releases the warm session.
+     */
+    runTurn(opts: EngineStreamTurnOptions): WarmTurnHandle;
+    /**
+     * Wrap a delta stream to (a) time the first VISIBLE token, (b) emit one latency
+     * sample on completion, and (c) release the warm session — back to `ready` on a
+     * clean finish, or torn down + evicted on abort/error (a resumed session left
+     * mid-turn is unsafe to reuse). A cold turn has no session to release.
+     */
+    private instrument;
+    /**
+     * Release a warm session after its turn. Clean finish → back to `ready` (the
+     * next turn reuses it, `lastUsedAt` reset so the idle clock restarts). Fault /
+     * abort → teardown + evict so a corrupt resumed session is never reused. If the
+     * pool stopped mid-turn, the session is torn down regardless.
+     */
+    private release;
+    /**
+     * Tear down every `ready` session idle longer than the TTL. `in_use` sessions
+     * (a turn is streaming) and `warming` slots are never expired. Returns the
+     * count torn down. Safe to call ad hoc or from the sweep interval.
+     */
+    sweepIdle(nowMs?: number): Promise<number>;
+    /**
+     * Explicitly evict one conversation's session (e.g. the conversation went
+     * inactive, or a dead handle was detected). No-op when absent or in_use.
+     */
+    evict(conversationId: string, reason?: WarmTeardownReason): Promise<boolean>;
+    /** Start the periodic idle sweep. Idempotent. */
+    start(): void;
+    /**
+     * Stop the pool: cancel the sweep and tear down EVERY session (including any
+     * in-flight one) so a shutdown leaves no orphaned process. Returns after all
+     * teardowns settle. Idempotent.
+     */
+    stop(): Promise<void>;
+    private log;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/warm-session/pool.d.ts.map

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