@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/engine/extfiles.js

@@ -0,0 +1,23 @@
+// Where the core's own pi extensions are, as files: beside this module in
+// whatever layout the package has. Built, this module is
+// `dist/src/engine/extfiles.js` and the extensions are `dist/extensions/*.js`;
+// run from source (vitest), it is `src/engine/extfiles.ts` and they are
+// `extensions/*.ts`. Never a path under the caller's checkout: an installed
+// package has none.
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The core's extension modules. */
+export const CORE_EXTENSIONS = [
+    "bash-guard",
+    "finding-clusters",
+    "ledger-pin",
+    "lens",
+    "pi-tool",
+];
+/** The absolute file of the core extension `name`, resolved from `from` (this
+ * module's URL by default). */
+export function coreExtensionFile(name, from = import.meta.url) {
+    const ext = extname(fileURLToPath(from)) === ".ts" ? ".ts" : ".js";
+    return fileURLToPath(new URL(`../../extensions/${name}${ext}`, from));
+}
+//# sourceMappingURL=extfiles.js.map

package/dist/src/engine/extfiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extfiles.js","sourceRoot":"","sources":["../../../src/engine/extfiles.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,yDAAyD;AACzD,+EAA+E;AAC/E,wEAAwE;AACxE,4EAA4E;AAC5E,oBAAoB;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,oCAAoC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY;IACZ,kBAAkB;IAClB,YAAY;IACZ,MAAM;IACN,SAAS;CACD,CAAC;AAGX;+BAC+B;AAC/B,MAAM,UAAU,iBAAiB,CAAC,IAAmB,EAAE,OAAe,MAAM,CAAC,IAAI,CAAC,GAAG;IACnF,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,oBAAoB,IAAI,GAAG,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/src/engine/keyroute.d.ts

@@ -0,0 +1,21 @@
+export type BenchAuthMode = "login" | "api-key";
+/** The review providers an API-key run can use besides OpenAI/Anthropic, and
+ * the key each one's pi needs (src/bench/auth.ts `BENCH_PROVIDERS` adds the
+ * models.json a bench sandbox gets). */
+export declare const KEY_ROUTE_PROVIDERS: {
+    readonly digitalocean: string;
+    readonly google: string;
+};
+export type BenchProviderId = keyof typeof KEY_ROUTE_PROVIDERS;
+export declare function benchProvider(env?: NodeJS.ProcessEnv): BenchProviderId | undefined;
+/** The sandbox's credential route, from `QCR_BENCH_AUTH` (unset = login). */
+export declare function benchAuthMode(env?: NodeJS.ProcessEnv): BenchAuthMode;
+/** A pi model spec as it runs under `mode`: the ChatGPT-login provider
+ * `openai-codex/` becomes the public API's `openai/` on the key route;
+ * every other spec (and every spec on the login route) is unchanged. */
+export declare function modelForAuth(spec: string, mode?: BenchAuthMode): string;
+/** The API keys a pi process may see on the key route — read from the
+ * container's environment (bench.sh's --env-file), passed on by NAME only.
+ * Empty on the login route, so nothing changes there. */
+export declare function apiKeyEnv(mode?: BenchAuthMode, env?: NodeJS.ProcessEnv): Record<string, string>;
+//# sourceMappingURL=keyroute.d.ts.map

package/dist/src/engine/keyroute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyroute.d.ts","sourceRoot":"","sources":["../../../src/engine/keyroute.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD;;wCAEwC;AACxC,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,GAAG,SAAS,CAO/F;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,aAAa,CAKjF;AAED;;wEAEwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,aAA+B,GAAG,MAAM,CAExF;AAED;;yDAEyD;AACzD,wBAAgB,SAAS,CACvB,IAAI,GAAE,aAA+B,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}

package/dist/src/engine/keyroute.js

@@ -0,0 +1,58 @@
+// The credential route a one-shot round runs on. Shared by the bench and
+// `qcr review`, so it is core; the bench's login handling and its provider
+// catalogs stay in src/bench/auth.ts.
+//
+// The published bench runs used a ChatGPT login; an outsider re-running the
+// benchmark brings an API key instead. `QCR_BENCH_AUTH=api-key`:
+//   - every `openai-codex/` model spec (the ChatGPT-login provider) is
+//     rewritten to `openai/`, the same model id on the public OpenAI API;
+//   - a pi process sees the provider's key, by NAME from the environment
+//     (`apiKeyEnv`), never on argv.
+import { RUNTIME_KEY_ENVS } from "./auth.js";
+/** The review providers an API-key run can use besides OpenAI/Anthropic, and
+ * the key each one's pi needs (src/bench/auth.ts `BENCH_PROVIDERS` adds the
+ * models.json a bench sandbox gets). */
+export const KEY_ROUTE_PROVIDERS = {
+    digitalocean: RUNTIME_KEY_ENVS["digitalocean"],
+    google: RUNTIME_KEY_ENVS["google"],
+};
+export function benchProvider(env = process.env) {
+    const provider = env["QCR_BENCH_PROVIDER"];
+    if (!provider)
+        return undefined;
+    if (Object.hasOwn(KEY_ROUTE_PROVIDERS, provider))
+        return provider;
+    throw new Error(`QCR_BENCH_PROVIDER must be ${Object.keys(KEY_ROUTE_PROVIDERS).join(" | ")} or unset`);
+}
+/** The sandbox's credential route, from `QCR_BENCH_AUTH` (unset = login). */
+export function benchAuthMode(env = process.env) {
+    const v = (env["QCR_BENCH_AUTH"] ?? "").trim();
+    if (v === "" || v === "login")
+        return "login";
+    if (v === "api-key")
+        return "api-key";
+    throw new Error(`QCR_BENCH_AUTH must be login | api-key (got "${v}")`);
+}
+/** A pi model spec as it runs under `mode`: the ChatGPT-login provider
+ * `openai-codex/` becomes the public API's `openai/` on the key route;
+ * every other spec (and every spec on the login route) is unchanged. */
+export function modelForAuth(spec, mode = benchAuthMode()) {
+    return mode === "api-key" ? spec.replace(/^openai-codex\//, "openai/") : spec;
+}
+/** The API keys a pi process may see on the key route — read from the
+ * container's environment (bench.sh's --env-file), passed on by NAME only.
+ * Empty on the login route, so nothing changes there. */
+export function apiKeyEnv(mode = benchAuthMode(), env = process.env) {
+    if (mode !== "api-key")
+        return {};
+    const out = {};
+    const provider = benchProvider(env);
+    const keys = provider ? [KEY_ROUTE_PROVIDERS[provider]] : ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"];
+    for (const k of keys) {
+        const v = env[k];
+        if (v)
+            out[k] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=keyroute.js.map

package/dist/src/engine/keyroute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyroute.js","sourceRoot":"","sources":["../../../src/engine/keyroute.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,2EAA2E;AAC3E,sCAAsC;AACtC,EAAE;AACF,4EAA4E;AAC5E,iEAAiE;AACjE,uEAAuE;AACvE,0EAA0E;AAC1E,yEAAyE;AACzE,oCAAoC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAI7C;;wCAEwC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAE;IAC/C,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAE;CAC3B,CAAC;AAGX,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,QAAQ,GAAG,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC3C,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,QAAQ,CAAC;QAAE,OAAO,QAA2B,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,8BAA8B,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CACtF,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IAC9C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED;;wEAEwE;AACxE,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAsB,aAAa,EAAE;IAC9E,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC;AAED;;yDAEyD;AACzD,MAAM,UAAU,SAAS,CACvB,OAAsB,aAAa,EAAE,EACrC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAClC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;IAClG,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/engine/lens/cache-group.d.ts

@@ -0,0 +1,20 @@
+/** A group older than this starts afresh: the provider's cache is short-lived. */
+export declare const CACHE_GROUP_MAX_AGE_MS: number;
+/** One cache group's place: its key, whether the caller is its first child,
+ * and how long a pack-less child should wait. */
+export interface CacheSlot {
+    key: string;
+    first: boolean;
+    delayMs: number;
+}
+/** Hands out cache keys: per model, one per group of `size` children, a fresh
+ * group when the last is full or stale. */
+export declare class CacheGrouper {
+    readonly size: number;
+    readonly staggerMs: number;
+    private readonly newKey;
+    private readonly groups;
+    constructor(size: number, staggerMs: number, newKey?: () => string);
+    next(now: number, model?: string): CacheSlot;
+}
+//# sourceMappingURL=cache-group.d.ts.map

package/dist/src/engine/lens/cache-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-group.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/cache-group.ts"],"names":[],"mappings":"AAMA,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,QAAa,CAAC;AAEjD;iDACiD;AACjD,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;2CAC2C;AAC3C,qBAAa,YAAY;IAIrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyE;gBAGrF,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACT,MAAM,GAAE,MAAM,MAAmB;IAGpD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,SAAS;CAUzC"}

package/dist/src/engine/lens/cache-group.js

@@ -0,0 +1,31 @@
+// Cache grouping for lens children: which provider cache key a child shares.
+// Pure (the key source is injectable). Lifted from the retired
+// extensions/subagents.ts; the rationale for the groups is in
+// docs/prompt-caching.md.
+import { randomUUID } from "node:crypto";
+/** A group older than this starts afresh: the provider's cache is short-lived. */
+export const CACHE_GROUP_MAX_AGE_MS = 4 * 60_000;
+/** Hands out cache keys: per model, one per group of `size` children, a fresh
+ * group when the last is full or stale. */
+export class CacheGrouper {
+    size;
+    staggerMs;
+    newKey;
+    groups = new Map();
+    constructor(size, staggerMs, newKey = randomUUID) {
+        this.size = size;
+        this.staggerMs = staggerMs;
+        this.newKey = newKey;
+    }
+    next(now, model = "") {
+        const g = this.groups.get(model);
+        if (g === undefined || g.members >= this.size || now - g.leaderAt > CACHE_GROUP_MAX_AGE_MS) {
+            const key = this.newKey();
+            this.groups.set(model, { key, leaderAt: now, members: 1 });
+            return { key, first: true, delayMs: 0 };
+        }
+        g.members += 1;
+        return { key: g.key, first: false, delayMs: Math.max(0, g.leaderAt + this.staggerMs - now) };
+    }
+}
+//# sourceMappingURL=cache-group.js.map

package/dist/src/engine/lens/cache-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-group.js","sourceRoot":"","sources":["../../../../src/engine/lens/cache-group.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+DAA+D;AAC/D,8DAA8D;AAC9D,0BAA0B;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,kFAAkF;AAClF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,MAAM,CAAC;AAUjD;2CAC2C;AAC3C,MAAM,OAAO,YAAY;IAIZ;IACA;IACQ;IALF,MAAM,GAAG,IAAI,GAAG,EAA8D,CAAC;IAEhG,YACW,IAAY,EACZ,SAAiB,EACT,SAAuB,UAAU;QAFzC,SAAI,GAAJ,IAAI,CAAQ;QACZ,cAAS,GAAT,SAAS,CAAQ;QACT,WAAM,GAAN,MAAM,CAA2B;IACjD,CAAC;IAEJ,IAAI,CAAC,GAAW,EAAE,KAAK,GAAG,EAAE;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,sBAAsB,EAAE,CAAC;YAC3F,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3D,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC1C,CAAC;QACD,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QACf,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,EAAE,CAAC;IAC/F,CAAC;CACF"}

package/dist/src/engine/lens/cache-run.d.ts

@@ -0,0 +1,65 @@
+/** The longest a packed group's lens waits for its warm-up. */
+export declare const WARMUP_WAIT_MS = 30000;
+/** The warm-up's whole task: it exists to put the pack in the cache. */
+export declare const WARMUP_REPLY_TASK = "Reply with the single word OK.";
+/** What the group disposes: a pi session, as far as the group knows it. */
+export interface Retired {
+    dispose(): void;
+}
+/** One group's shared state while any member is alive. */
+declare class Lifetime {
+    members: number;
+    readonly sessions: Retired[];
+    /** The group's warm-up, memoised: set once, by the group's first lens. */
+    warmup: Promise<void> | undefined;
+}
+/** A member's hold on its group. Released exactly once. */
+export declare class CacheLease {
+    readonly key: string;
+    /** Whether this member is the group's first. */
+    readonly first: boolean;
+    /** How long a pack-less member should wait before starting. */
+    readonly delayMs: number;
+    private readonly life;
+    private readonly leave;
+    private released;
+    constructor(key: string, 
+    /** Whether this member is the group's first. */
+    first: boolean, 
+    /** How long a pack-less member should wait before starting. */
+    delayMs: number, life: Lifetime, leave: () => void);
+    /** A finished session, to be disposed with the group, never before. */
+    keep(session: Retired): void;
+    /** The group's warm-up if one was started, to await. */
+    warmup(): Promise<void> | undefined;
+    /**
+     * Start the group's warm-up unless it already started; return it either way.
+     * `run` never rejects; it is handed `keep` for the session it makes. The
+     * warm-up is a member of the group until it settles, so a group whose lenses
+     * all finished first still waits to dispose it.
+     */
+    startWarmup(run: (keep: (s: Retired) => void) => Promise<void>): Promise<void>;
+    /** The member is done with the group. The last release disposes its sessions. */
+    release(): void;
+}
+/** Per model, cache groups of `size`; each live group's lifetime. */
+export declare class CacheGroups {
+    private readonly onDisposed?;
+    private readonly grouper;
+    private readonly lives;
+    /** `onDisposed` is told each time a group's sessions are disposed: the
+     * production evidence the cleanupSessionResources pin rests on. */
+    constructor(size: number, staggerMs: number, newKey?: () => string, onDisposed?: ((key: string, sessions: number) => void) | undefined);
+    /** Join the group for `model`'s next lens. */
+    join(model: string, nowMs: number): CacheLease;
+    private settle;
+    /** Groups with a member alive now (diagnostics and tests). */
+    liveGroups(): number;
+}
+/** Resolve after `ms`, or as soon as `signal` aborts (the caller then checks it). */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+/** Wait for `p`, but at most `ms` (or until `signal` aborts). True when `p`
+ * settled first. The timer never outlives the wait. */
+export declare function settledWithin(p: Promise<unknown>, ms: number, signal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=cache-run.d.ts.map

package/dist/src/engine/lens/cache-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-run.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/cache-run.ts"],"names":[],"mappings":"AAkBA,+DAA+D;AAC/D,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,mCAAmC,CAAC;AAElE,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,0DAA0D;AAC1D,cAAM,QAAQ;IACZ,OAAO,SAAK;IACZ,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAM;IAClC,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;CACnC;AAED,2DAA2D;AAC3D,qBAAa,UAAU;IAInB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IATxB,OAAO,CAAC,QAAQ,CAAS;gBAGd,GAAG,EAAE,MAAM;IACpB,gDAAgD;IACvC,KAAK,EAAE,OAAO;IACvB,+DAA+D;IACtD,OAAO,EAAE,MAAM,EACP,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,IAAI;IAGpC,uEAAuE;IACvE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B,wDAAwD;IACxD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;IAInC;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAY9E,iFAAiF;IACjF,OAAO,IAAI,IAAI;CAMhB;AAED,qEAAqE;AACrE,qBAAa,WAAW;IAUpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAT9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD;uEACmE;gBAEjE,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,MAAM,EACJ,UAAU,CAAC,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,aAAA;IAKvE,8CAA8C;IAC9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU;IAc9C,OAAO,CAAC,MAAM;IAcd,8DAA8D;IAC9D,UAAU,IAAI,MAAM;CAGrB;AAED,qFAAqF;AACrF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrE;AAED;uDACuD;AACvD,wBAAsB,aAAa,CACjC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/src/engine/lens/cache-run.js

@@ -0,0 +1,159 @@
+// The runtime side of lens cache groups: who shares a group, when a group
+// is warm, and when its sessions may be disposed. Pure over its injected clock
+// and key source (no pi, no filesystem); the runner supplies the sessions.
+//
+// A group's lens sessions share ONE session id, which is its cache key: pi
+// derives prompt_cache_key and the routing headers from the session id, so
+// that is what puts the group's requests on one backend cache
+// (docs/probes/p4.6-codex-cache-routing.md). The price is in dispose: pi's
+// session.dispose() runs cleanupSessionResources(sessionId), which closes
+// every provider transport held for that id, a sibling's live websocket
+// included. So no session of a group is disposed until the whole group is done:
+// each member leases the group, hands its finished sessions over with keep(),
+// and the last release disposes them together.
+//
+// Seen in production at pi 1.3.0: cleanupSessionResources closes by session id
+// alone (groups disposed their sessions together, and no sibling lens failed after).
+import { CacheGrouper } from "./cache-group.js";
+/** The longest a packed group's lens waits for its warm-up. */
+export const WARMUP_WAIT_MS = 30_000;
+/** The warm-up's whole task: it exists to put the pack in the cache. */
+export const WARMUP_REPLY_TASK = "Reply with the single word OK.";
+/** One group's shared state while any member is alive. */
+class Lifetime {
+    members = 0;
+    sessions = [];
+    /** The group's warm-up, memoised: set once, by the group's first lens. */
+    warmup;
+}
+/** A member's hold on its group. Released exactly once. */
+export class CacheLease {
+    key;
+    first;
+    delayMs;
+    life;
+    leave;
+    released = false;
+    constructor(key, 
+    /** Whether this member is the group's first. */
+    first, 
+    /** How long a pack-less member should wait before starting. */
+    delayMs, life, leave) {
+        this.key = key;
+        this.first = first;
+        this.delayMs = delayMs;
+        this.life = life;
+        this.leave = leave;
+    }
+    /** A finished session, to be disposed with the group, never before. */
+    keep(session) {
+        this.life.sessions.push(session);
+    }
+    /** The group's warm-up if one was started, to await. */
+    warmup() {
+        return this.life.warmup;
+    }
+    /**
+     * Start the group's warm-up unless it already started; return it either way.
+     * `run` never rejects; it is handed `keep` for the session it makes. The
+     * warm-up is a member of the group until it settles, so a group whose lenses
+     * all finished first still waits to dispose it.
+     */
+    startWarmup(run) {
+        if (this.life.warmup !== undefined)
+            return this.life.warmup;
+        this.life.members += 1;
+        const life = this.life;
+        const settle = () => {
+            life.members -= 1;
+            this.leave();
+        };
+        life.warmup = run((s) => life.sessions.push(s)).then(settle, settle);
+        return life.warmup;
+    }
+    /** The member is done with the group. The last release disposes its sessions. */
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.life.members -= 1;
+        this.leave();
+    }
+}
+/** Per model, cache groups of `size`; each live group's lifetime. */
+export class CacheGroups {
+    onDisposed;
+    grouper;
+    lives = new Map();
+    /** `onDisposed` is told each time a group's sessions are disposed: the
+     * production evidence the cleanupSessionResources pin rests on. */
+    constructor(size, staggerMs, newKey, onDisposed) {
+        this.onDisposed = onDisposed;
+        this.grouper = new CacheGrouper(size, staggerMs, newKey);
+    }
+    /** Join the group for `model`'s next lens. */
+    join(model, nowMs) {
+        const slot = this.grouper.next(nowMs, model);
+        let life = this.lives.get(slot.key);
+        if (life === undefined) {
+            life = new Lifetime();
+            this.lives.set(slot.key, life);
+        }
+        life.members += 1;
+        const held = life;
+        return new CacheLease(slot.key, slot.first, slot.delayMs, held, () => this.settle(slot.key, held));
+    }
+    settle(key, life) {
+        if (life.members > 0)
+            return;
+        if (this.lives.get(key) === life)
+            this.lives.delete(key);
+        const retired = life.sessions.splice(0);
+        for (const s of retired) {
+            try {
+                s.dispose();
+            }
+            catch {
+                // already disposed
+            }
+        }
+        if (retired.length > 0)
+            this.onDisposed?.(key, retired.length);
+    }
+    /** Groups with a member alive now (diagnostics and tests). */
+    liveGroups() {
+        return this.lives.size;
+    }
+}
+/** Resolve after `ms`, or as soon as `signal` aborts (the caller then checks it). */
+export function delay(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/** Wait for `p`, but at most `ms` (or until `signal` aborts). True when `p`
+ * settled first. The timer never outlives the wait. */
+export async function settledWithin(p, ms, signal) {
+    const stop = new AbortController();
+    const timeout = signal ? AbortSignal.any([signal, stop.signal]) : stop.signal;
+    let won = false;
+    const settle = () => {
+        won = true;
+    };
+    try {
+        await Promise.race([p.then(settle, settle), delay(ms, timeout)]);
+    }
+    finally {
+        stop.abort();
+    }
+    return won;
+}
+//# sourceMappingURL=cache-run.js.map

package/dist/src/engine/lens/cache-run.js.map

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

package/dist/src/engine/lens/deadline.d.ts

@@ -0,0 +1,54 @@
+/** The shape of a native subagent tool result, as far as the glue reads it. */
+export interface ParallelNativeResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    details: {
+        mode?: string;
+        results: unknown[];
+        [key: string]: unknown;
+    };
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Env var carrying the per-pass deadline in minutes (on the VM, config.toml
+ * [pi] subagent_pass_deadline_min riding the session command line). Absent,
+ * "0" or malformed ⇒ no deadline: the companion and the bench run unchanged
+ * unless they set it. */
+export declare const PASS_DEADLINE_ENV = "QCR_SUBAGENT_PASS_DEADLINE_MIN";
+/** The per-pass deadline in ms, or undefined for none. Minutes may be
+ * fractional; anything but a plain non-negative number up to 240 is a
+ * misconfiguration and means no deadline (never a surprise kill). */
+export declare function resolvePassDeadlineMs(env?: Record<string, string | undefined>): number | undefined;
+/** "8", "0.5" — the deadline as the operator wrote it, for the failure text. */
+export declare function minutesText(ms: number): string;
+/** The failure text a pass that timed out twice returns in its slot. */
+export declare function passTimeoutMessage(agent: string, deadlineMs: number): string;
+/**
+ * Run one pass under the per-pass deadline: each attempt gets its own
+ * AbortSignal composed of the caller's signal OR a fresh timer, which native
+ * honours by killing its child (SIGTERM, then SIGKILL). An attempt the TIMER
+ * ended is retried once with a fresh deadline; a second timeout answers
+ * "timed_out". The caller's abort always wins and is never retried: it
+ * rethrows exactly as before. A result native returns after the timer fired
+ * (the child finished as it was being killed) is a result, not a timeout.
+ */
+export declare function runUnderDeadline<T>(attempt: (signal: AbortSignal) => Promise<T>, callerSignal: AbortSignal | undefined, deadlineMs: number, onTimeout?: (attemptNo: number) => void): Promise<T | "timed_out">;
+/** The one task a call runs, when it runs exactly one: a single-mode
+ * `{agent, task}` call or a one-element `tasks` array. */
+export declare function soleTask(params: Record<string, unknown>): {
+    agent: string;
+    task: unknown;
+    mode: "single" | "parallel";
+} | undefined;
+/** A pass that timed out twice, in native's own result shape for its mode,
+ * so the combined result, round-progress and the session read it as one
+ * failed pass with the timeout named. */
+export declare function timedOutResult(sole: {
+    agent: string;
+    task: unknown;
+    mode: "single" | "parallel";
+}, deadlineMs: number): ParallelNativeResult;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/src/engine/lens/deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/deadline.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACxE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;yBAGyB;AACzB,eAAO,MAAM,iBAAiB,mCAAmC,CAAC;AAElE;;qEAEqE;AACrE,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,GAAG,SAAS,CAMpB;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5C,YAAY,EAAE,WAAW,GAAG,SAAS,EACrC,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC,CAmB1B;AAED;0DAC0D;AAC1D,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,GAAG,SAAS,CAc3E;AAED;;yCAEyC;AACzC,wBAAgB,cAAc,CAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,EACnE,UAAU,EAAE,MAAM,GACjB,oBAAoB,CA+BtB"}

package/dist/src/engine/lens/deadline.js

@@ -0,0 +1,111 @@
+// The per-pass deadline: its env knob, the retry-once runner and the result a
+// pass that timed out twice answers with. Pure — no pi, no filesystem. Lifted
+// from the retired extensions/subagents.ts.
+/** Env var carrying the per-pass deadline in minutes (on the VM, config.toml
+ * [pi] subagent_pass_deadline_min riding the session command line). Absent,
+ * "0" or malformed ⇒ no deadline: the companion and the bench run unchanged
+ * unless they set it. */
+export const PASS_DEADLINE_ENV = "QCR_SUBAGENT_PASS_DEADLINE_MIN";
+/** The per-pass deadline in ms, or undefined for none. Minutes may be
+ * fractional; anything but a plain non-negative number up to 240 is a
+ * misconfiguration and means no deadline (never a surprise kill). */
+export function resolvePassDeadlineMs(env = process.env) {
+    const raw = (env[PASS_DEADLINE_ENV] ?? "").trim();
+    if (!/^\d{1,3}(?:\.\d{1,6})?$/.test(raw))
+        return undefined;
+    const minutes = Number(raw);
+    if (!(minutes > 0) || minutes > 240)
+        return undefined;
+    return Math.max(1, Math.round(minutes * 60_000));
+}
+/** "8", "0.5" — the deadline as the operator wrote it, for the failure text. */
+export function minutesText(ms) {
+    const min = ms / 60_000;
+    return Number.isInteger(min) ? String(min) : String(Number(min.toFixed(3)));
+}
+/** The failure text a pass that timed out twice returns in its slot. */
+export function passTimeoutMessage(agent, deadlineMs) {
+    return `pass ${agent} timed out after ${minutesText(deadlineMs)} min (retried once)`;
+}
+/**
+ * Run one pass under the per-pass deadline: each attempt gets its own
+ * AbortSignal composed of the caller's signal OR a fresh timer, which native
+ * honours by killing its child (SIGTERM, then SIGKILL). An attempt the TIMER
+ * ended is retried once with a fresh deadline; a second timeout answers
+ * "timed_out". The caller's abort always wins and is never retried: it
+ * rethrows exactly as before. A result native returns after the timer fired
+ * (the child finished as it was being killed) is a result, not a timeout.
+ */
+export async function runUnderDeadline(attempt, callerSignal, deadlineMs, onTimeout) {
+    for (let attemptNo = 1; attemptNo <= 2; attemptNo++) {
+        callerSignal?.throwIfAborted();
+        const timer = new AbortController();
+        const handle = setTimeout(() => timer.abort(new Error(`per-pass deadline of ${minutesText(deadlineMs)} min reached`)), deadlineMs);
+        const signal = callerSignal ? AbortSignal.any([callerSignal, timer.signal]) : timer.signal;
+        try {
+            return await attempt(signal);
+        }
+        catch (err) {
+            if (callerSignal?.aborted || !timer.signal.aborted)
+                throw err;
+            onTimeout?.(attemptNo);
+        }
+        finally {
+            clearTimeout(handle);
+        }
+    }
+    return "timed_out";
+}
+/** The one task a call runs, when it runs exactly one: a single-mode
+ * `{agent, task}` call or a one-element `tasks` array. */
+export function soleTask(params) {
+    if (Array.isArray(params.tasks)) {
+        if (params.tasks.length !== 1)
+            return undefined;
+        const t = params.tasks[0];
+        const agent = typeof t === "object" && t !== null ? t.agent : undefined;
+        return typeof agent === "string"
+            ? { agent, task: t.task, mode: "parallel" }
+            : undefined;
+    }
+    if (params.chain !== undefined)
+        return undefined;
+    return typeof params.agent === "string"
+        ? { agent: params.agent, task: params.task, mode: "single" }
+        : undefined;
+}
+/** A pass that timed out twice, in native's own result shape for its mode,
+ * so the combined result, round-progress and the session read it as one
+ * failed pass with the timeout named. */
+export function timedOutResult(sole, deadlineMs) {
+    const message = passTimeoutMessage(sole.agent, deadlineMs);
+    const result = {
+        agent: sole.agent,
+        agentSource: "unknown",
+        task: sole.task,
+        exitCode: 1,
+        messages: [],
+        stderr: "",
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            cost: 0,
+            contextTokens: 0,
+            turns: 0,
+        },
+        stopReason: "error",
+        errorMessage: message,
+        timedOut: true,
+    };
+    const text = sole.mode === "parallel"
+        ? `Parallel: 0/1 succeeded\n\n### [${sole.agent}] failed (timeout)\n\n${message}`
+        : `Agent timeout: ${message}`;
+    return {
+        content: [{ type: "text", text }],
+        details: { mode: sole.mode, agentScope: undefined, projectAgentsDir: null, results: [result] },
+        isError: true,
+    };
+}
+//# sourceMappingURL=deadline.js.map

package/dist/src/engine/lens/deadline.js.map

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

package/dist/src/engine/lens/engine-tools.d.ts

@@ -0,0 +1,13 @@
+import type { RoundLensTools } from "../roundsdk.js";
+import { type LensRun, type LensRunConfig, type LensRunner } from "./runlens.js";
+import { LensWave } from "./wave.js";
+export interface EngineLensTools extends RoundLensTools {
+    /** Starts a pass; the engine's wave and the session's `lens` run on it. */
+    runner: LensRunner;
+    /** The round's rows in flight. */
+    wave: LensWave;
+}
+/** `tap` hears every finished pass, however it was started (the wave, a `lens`
+ * call): a route that totals the passes' spend reads it there. */
+export declare function engineLensTools(config: LensRunConfig, wave?: LensWave, tap?: (run: LensRun) => void): EngineLensTools;
+//# sourceMappingURL=engine-tools.d.ts.map

package/dist/src/engine/lens/engine-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-tools.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/engine-tools.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAoB,KAAK,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnG,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,2EAA2E;IAC3E,MAAM,EAAE,UAAU,CAAC;IACnB,kCAAkC;IAClC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;kEACkE;AAClE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,IAAI,WAAiB,EACrB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC3B,eAAe,CAuBjB"}