@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/engine/lens/engine-tools.js

@@ -0,0 +1,37 @@
+// The lens tools of an engine route's main session: `lens` and `lens_wave` over
+// one LensRunner and one LensWave, handed to the session as `customTools`
+// (roundsdk.ts RoundLensTools). A route builds this once per round's main
+// session. The planned wave is started by the engine through `launchWave` on the
+// same `wave` and `runner`; the session's `lens_wave` joins it.
+import { lensTools } from "../../../extensions/lens.js";
+import { createLensRunner } from "./runlens.js";
+import { LENS_TOOL, LENS_WAVE_TOOL } from "./tool.js";
+import { LensWave } from "./wave.js";
+/** `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 function engineLensTools(config, wave = new LensWave(), tap) {
+    const inner = createLensRunner(config);
+    const runner = tap
+        ? {
+            run: async (request) => {
+                const run = await inner.run(request);
+                try {
+                    tap(run);
+                }
+                catch {
+                    // a listener's failure is not the pass's
+                }
+                return run;
+            },
+            liveSessions: () => inner.liveSessions(),
+        }
+        : inner;
+    return {
+        factories: [],
+        customTools: lensTools({ runner, wave, env: config.env }),
+        toolNames: [LENS_TOOL, LENS_WAVE_TOOL],
+        runner,
+        wave,
+    };
+}
+//# sourceMappingURL=engine-tools.js.map

package/dist/src/engine/lens/engine-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-tools.js","sourceRoot":"","sources":["../../../../src/engine/lens/engine-tools.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,0EAA0E;AAC1E,0EAA0E;AAC1E,iFAAiF;AACjF,gEAAgE;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAqD,MAAM,cAAc,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC;kEACkE;AAClE,MAAM,UAAU,eAAe,CAC7B,MAAqB,EACrB,IAAI,GAAG,IAAI,QAAQ,EAAE,EACrB,GAA4B;IAE5B,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,MAAM,GAAe,GAAG;QAC5B,CAAC,CAAC;YACE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBACrB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACrC,IAAI,CAAC;oBACH,GAAG,CAAC,GAAG,CAAC,CAAC;gBACX,CAAC;gBAAC,MAAM,CAAC;oBACP,yCAAyC;gBAC3C,CAAC;gBACD,OAAO,GAAG,CAAC;YACb,CAAC;YACD,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE;SACzC;QACH,CAAC,CAAC,KAAK,CAAC;IACV,OAAO;QACL,SAAS,EAAE,EAAE;QACb,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;QACzD,SAAS,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC;QACtC,MAAM;QACN,IAAI;KACL,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,23 @@
+/** Env var pinning the agent discovery scope (`user` | `project`); read by
+ * `lensAgentsDir` (round-lens.ts). */
+export declare const SCOPE_ENV = "QCR_SUBAGENT_SCOPE";
+/** Env var carrying the process-wide cap on running lens sessions. */
+export declare const CONCURRENCY_ENV = "QCR_SUBAGENT_MAX_CONCURRENCY";
+/** Env var: sessions per shared cache key; 0 or unset ⇒ a random id each. */
+export declare const CACHE_GROUP_ENV = "QCR_SUBAGENT_CACHE_GROUP";
+/** Env var: how long a group's later sessions start after its first. */
+export declare const CACHE_STAGGER_ENV = "QCR_SUBAGENT_CACHE_STAGGER_MS";
+/** Default process-wide cap, the companion's desktop number. Equal to
+ * `DEFAULT_LENS_MAX_CONCURRENCY` (config.ts; this file imports nothing from the
+ * daemon), pinned by a test. */
+export declare const DEFAULT_MAX_CONCURRENCY = 4;
+/** Equal to `DEFAULT_LENS_CACHE_STAGGER_MS` (config.ts), pinned by a test. */
+export declare const DEFAULT_CACHE_STAGGER_MS = 2500;
+/** Resolve the process-wide cap from the environment (invalid/absent → 4).
+ * Strict digits only — "1e3" or "6x" is a misconfiguration, and a
+ * misconfiguration falls back to the safe default rather than whatever
+ * parseInt salvages from the prefix. */
+export declare function resolveMaxConcurrency(env?: Record<string, string | undefined>): number;
+export declare function resolveCacheGroup(env?: Record<string, string | undefined>): number;
+export declare function resolveCacheStagger(env?: Record<string, string | undefined>): number;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/env.ts"],"names":[],"mappings":"AAMA;sCACsC;AACtC,eAAO,MAAM,SAAS,uBAAuB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,eAAe,iCAAiC,CAAC;AAE9D,6EAA6E;AAC7E,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AAEjE;;gCAEgC;AAChC,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;wCAGwC;AACxC,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAKR;AAOD,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAE/F;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAEjG"}

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

@@ -0,0 +1,42 @@
+// The lens tool's env: the names its config rides on (round.ts and the bench
+// set them from `[engine] lens_*`; the companion's launch line sets the cap)
+// and the readers that turn them back into numbers. Pure. The names keep their
+// `QCR_SUBAGENT_` spelling: they predate the lens tool, and the env inventory
+// (packages/pi-plugin/src/engine/envmap.ts) and every launch line already carry them.
+/** Env var pinning the agent discovery scope (`user` | `project`); read by
+ * `lensAgentsDir` (round-lens.ts). */
+export const SCOPE_ENV = "QCR_SUBAGENT_SCOPE";
+/** Env var carrying the process-wide cap on running lens sessions. */
+export const CONCURRENCY_ENV = "QCR_SUBAGENT_MAX_CONCURRENCY";
+/** Env var: sessions per shared cache key; 0 or unset ⇒ a random id each. */
+export const CACHE_GROUP_ENV = "QCR_SUBAGENT_CACHE_GROUP";
+/** Env var: how long a group's later sessions start after its first. */
+export const CACHE_STAGGER_ENV = "QCR_SUBAGENT_CACHE_STAGGER_MS";
+/** Default process-wide cap, the companion's desktop number. Equal to
+ * `DEFAULT_LENS_MAX_CONCURRENCY` (config.ts; this file imports nothing from the
+ * daemon), pinned by a test. */
+export const DEFAULT_MAX_CONCURRENCY = 4;
+/** Equal to `DEFAULT_LENS_CACHE_STAGGER_MS` (config.ts), pinned by a test. */
+export const DEFAULT_CACHE_STAGGER_MS = 2500;
+/** Resolve the process-wide cap from the environment (invalid/absent → 4).
+ * Strict digits only — "1e3" or "6x" is a misconfiguration, and a
+ * misconfiguration falls back to the safe default rather than whatever
+ * parseInt salvages from the prefix. */
+export function resolveMaxConcurrency(env = process.env) {
+    const raw = (env[CONCURRENCY_ENV] ?? "").trim();
+    if (!/^\d{1,2}$/.test(raw))
+        return DEFAULT_MAX_CONCURRENCY;
+    const n = Number.parseInt(raw, 10);
+    return n >= 1 && n <= 64 ? n : DEFAULT_MAX_CONCURRENCY;
+}
+function nonNegativeInt(raw, fallback) {
+    const n = Number.parseInt((raw ?? "").trim(), 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+export function resolveCacheGroup(env = process.env) {
+    return nonNegativeInt(env[CACHE_GROUP_ENV], 0);
+}
+export function resolveCacheStagger(env = process.env) {
+    return nonNegativeInt(env[CACHE_STAGGER_ENV], DEFAULT_CACHE_STAGGER_MS);
+}
+//# sourceMappingURL=env.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../../src/engine/lens/env.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,sFAAsF;AAEtF;sCACsC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,oBAAoB,CAAC;AAE9C,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,8BAA8B,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAE1D,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAEjE;;gCAEgC;AAChC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C;;;wCAGwC;AACxC,MAAM,UAAU,qBAAqB,CACnC,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,uBAAuB,CAAC;IAC3D,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC;AACzD,CAAC;AAED,SAAS,cAAc,CAAC,GAAuB,EAAE,QAAgB;IAC/D,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAA0C,OAAO,CAAC,GAAG;IACrF,OAAO,cAAc,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAA0C,OAAO,CAAC,GAAG;IACvF,OAAO,cAAc,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,wBAAwB,CAAC,CAAC;AAC1E,CAAC"}

package/dist/src/engine/lens/launch-plan.d.ts

@@ -0,0 +1,63 @@
+/** Env var naming EXTRA sanctioned task dirs, exactly, separated by the
+ * platform path delimiter — the bench's `<case>/tasks` and `<case>/tasks-sweep`
+ * (src/bench/runner.ts). Production never sets it. */
+export declare const LAUNCH_PLAN_DIRS_ENV = "QCR_LAUNCH_PLAN_DIRS";
+/** The pointer a task-file launch carries — the exact words the round
+ * templates prescribe (packages/pi-plugin/src/passtasks.ts renderPassTaskNote). */
+export declare function taskPointer(path: string): string;
+/** One unit of a planned launch. */
+export interface LaunchUnit {
+    /** "plan" for the round's tasks dir, "optional" for a follow-up round's
+     * optional rows, "sweep" for the sweep's. */
+    phase: "plan" | "sweep" | "optional";
+    /** 1-based row, as the plan tables print it. */
+    row: number;
+    agent: string;
+    file: string;
+    path: string;
+    task: string;
+}
+export type LaunchPlan = {
+    ok: true;
+    units: LaunchUnit[];
+    skipped: LaunchUnit[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function realDir(path: string): string | undefined;
+/** The extra sanctioned dirs from the environment, each resolved; one that
+ * does not exist sanctions nothing. */
+export declare function sanctionedExtras(env: Record<string, string | undefined>): Set<string>;
+/** Resolve one `dirs` entry to a sanctioned task dir, or say why not. */
+export declare function resolveTaskDir(input: string, realRoot: string, extras: ReadonlySet<string>, pr: string | undefined): {
+    dir: string;
+    phase: "plan" | "sweep" | "optional";
+    passes: string | undefined;
+} | {
+    error: string;
+};
+/** The discovery task files of one dir, in row order (= the daemon's launch
+ * order). Regular files only: a symlink is never followed. */
+export declare function listTaskFiles(dir: string): Array<{
+    row: number;
+    agent: string;
+    file: string;
+}>;
+/** The keys a unit answers to in `extra` and `skip`: its file name (with or
+ * without `.md`), its row (`3`, or `sweep:3` / `optional:3` outside the
+ * plan), its agent, its phase's wildcard (`plan:*` / `optional:*` /
+ * `sweep:*`) and `*`. */
+export declare function unitKeys(u: Pick<LaunchUnit, "phase" | "row" | "file" | "agent">): string[];
+export declare function stringList(value: unknown): string[] | undefined;
+/**
+ * Plan a launch: resolve and confine the dirs, list their discovery task
+ * files, apply `skip` and `extra`. Pure over the filesystem it reads; never
+ * throws — every refusal is an `{ ok: false }` with the reason.
+ */
+export declare function planLaunch(params: Record<string, unknown>, env?: Record<string, string | undefined>, 
+/** The sandbox root when the env names none (QCR_SANDBOX_ROOT): the
+ * launching process's cwd, as its host resolves it. Every round's env names
+ * the root; an interactive pi's may not. */
+cwd?: string): LaunchPlan;
+//# sourceMappingURL=launch-plan.d.ts.map

package/dist/src/engine/lens/launch-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-plan.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/launch-plan.ts"],"names":[],"mappings":"AAQA;;sDAEsD;AACtD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAS3D;mFACmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB;iDAC6C;IAC7C,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IACrC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,UAAU,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxD;AAED;uCACuC;AACvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CASrF;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3B,EAAE,EAAE,MAAM,GAAG,SAAS,GAEpB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACjF;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA+BpB;AAED;8DAC8D;AAC9D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU9F;AAED;;;yBAGyB;AACzB,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,EAAE,CAG1F;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAK/D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe;AACrD;;4CAE4C;AAC5C,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,CAoFZ"}

package/dist/src/engine/lens/launch-plan.js

@@ -0,0 +1,203 @@
+// Planning a launch from a round's task files: which directories a lens
+// launch may read (confined to the round's own pass dirs), which files are
+// discovery rows, and how `skip` / `extra` apply. Pure over the filesystem it
+// reads. Lifted from the retired extensions/subagents.ts, whose `launch_plan`
+// tool it planned for; `lens_wave` (tool.ts) is its successor.
+import { readdirSync, realpathSync } from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+/** Env var naming EXTRA sanctioned task dirs, exactly, separated by the
+ * platform path delimiter — the bench's `<case>/tasks` and `<case>/tasks-sweep`
+ * (src/bench/runner.ts). Production never sets it. */
+export const LAUNCH_PLAN_DIRS_ENV = "QCR_LAUNCH_PLAN_DIRS";
+/** A round's pass directory, as dispatch.ts names it. */
+const PASSES_DIR_RE = /^pr-\d+-round-\d+-passes$/;
+/** A task file, as passtasks.ts names it: the 1-based row, then the agent. */
+const TASK_FILE_RE = /^(\d{2,})-([a-z0-9][a-z0-9-]*)\.md$/;
+/** The validator's agent ids — `pass-validate` and its tier variants. */
+const VALIDATOR_AGENT_RE = /^pass-validate(--|$)/;
+/** The pointer a task-file launch carries — the exact words the round
+ * templates prescribe (packages/pi-plugin/src/passtasks.ts renderPassTaskNote). */
+export function taskPointer(path) {
+    return `Task file: ${path}. Read it first; it is your complete task.`;
+}
+export function realDir(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The extra sanctioned dirs from the environment, each resolved; one that
+ * does not exist sanctions nothing. */
+export function sanctionedExtras(env) {
+    const out = new Set();
+    for (const raw of (env[LAUNCH_PLAN_DIRS_ENV] ?? "").split(delimiter)) {
+        const p = raw.trim();
+        if (!p || !isAbsolute(p))
+            continue;
+        const real = realDir(p);
+        if (real)
+            out.add(real);
+    }
+    return out;
+}
+/** Resolve one `dirs` entry to a sanctioned task dir, or say why not. */
+export function resolveTaskDir(input, realRoot, extras, pr) {
+    const real = realDir(resolve(realRoot, input));
+    if (!real)
+        return { error: `${input}: no such directory` };
+    // Resolved too: on the legacy VM `<sandbox>/state` was a SYMLINK to the state volume
+    // (its entrypoint), and the plain Docker path still links it, so a resolved task dir lives under its target.
+    const state = realDir(join(realRoot, "state")) ?? join(realRoot, "state");
+    // A PR session (QCR_PR, set by the daemon — the session cannot set its own
+    // environment) launches only its own PR's rounds.
+    const ownPasses = (name) => PASSES_DIR_RE.test(name) && (pr === undefined || name.startsWith(`pr-${pr}-round-`));
+    if (dirname(real) === state && ownPasses(basename(real))) {
+        // The round's pass dir: its plan tasks. The sweep's dir is named itself.
+        const tasks = realDir(join(real, "tasks"));
+        if (!tasks || tasks !== join(real, "tasks"))
+            return { error: `${input}: the round has no task files (no tasks/ directory)` };
+        return { dir: tasks, phase: "plan", passes: real };
+    }
+    const name = basename(real);
+    // `tasks-optional` — a follow-up round's optional rows.
+    const phaseOf = (n) => n === "tasks-sweep" ? "sweep" : n === "tasks-optional" ? "optional" : "plan";
+    if ((name === "tasks" || name === "tasks-sweep" || name === "tasks-optional") &&
+        dirname(dirname(real)) === state &&
+        ownPasses(basename(dirname(real))))
+        return { dir: real, phase: phaseOf(name), passes: dirname(real) };
+    if (extras.has(real))
+        return { dir: real, phase: phaseOf(name), passes: undefined };
+    return {
+        error: `${input}: not a round's task directory (only state/pr-<n>-round-<k>-passes/tasks, …/tasks-sweep or …/tasks-optional)`,
+    };
+}
+/** The discovery task files of one dir, in row order (= the daemon's launch
+ * order). Regular files only: a symlink is never followed. */
+export function listTaskFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        const m = TASK_FILE_RE.exec(entry.name);
+        if (!m || m[1] === undefined || m[2] === undefined)
+            continue;
+        if (VALIDATOR_AGENT_RE.test(m[2]))
+            continue;
+        out.push({ row: Number.parseInt(m[1], 10), agent: m[2], file: entry.name });
+    }
+    return out.sort((a, b) => a.row - b.row || a.file.localeCompare(b.file));
+}
+/** The keys a unit answers to in `extra` and `skip`: its file name (with or
+ * without `.md`), its row (`3`, or `sweep:3` / `optional:3` outside the
+ * plan), its agent, its phase's wildcard (`plan:*` / `optional:*` /
+ * `sweep:*`) and `*`. */
+export function unitKeys(u) {
+    const row = u.phase === "plan" ? String(u.row) : `${u.phase}:${u.row}`;
+    return [u.file, u.file.replace(/\.md$/, ""), row, u.agent, `${u.phase}:*`, "*"];
+}
+export function stringList(value) {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return [value];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string"))
+        return undefined;
+    return value;
+}
+/**
+ * Plan a launch: resolve and confine the dirs, list their discovery task
+ * files, apply `skip` and `extra`. Pure over the filesystem it reads; never
+ * throws — every refusal is an `{ ok: false }` with the reason.
+ */
+export function planLaunch(params, env = process.env, 
+/** The sandbox root when the env names none (QCR_SANDBOX_ROOT): the
+ * launching process's cwd, as its host resolves it. Every round's env names
+ * the root; an interactive pi's may not. */
+cwd) {
+    try {
+        const dirs = stringList(params.dirs ?? params.dir);
+        if (!dirs || dirs.length === 0)
+            return {
+                ok: false,
+                error: "`dirs` must name the round's task directory (one to three paths)",
+            };
+        if (dirs.length > 3)
+            return {
+                ok: false,
+                error: "at most three dirs: the round's tasks, its tasks-optional and its tasks-sweep",
+            };
+        const skip = stringList(params.skip);
+        if (!skip)
+            return { ok: false, error: "`skip` must be a list of row keys" };
+        const extraRaw = params.extra ?? {};
+        if (typeof extraRaw !== "object" || extraRaw === null || Array.isArray(extraRaw))
+            return { ok: false, error: "`extra` must map a row key to text" };
+        const extra = Object.entries(extraRaw);
+        if (extra.some(([, v]) => typeof v !== "string"))
+            return { ok: false, error: "`extra` values must be text" };
+        const root = env.QCR_SANDBOX_ROOT?.trim() || cwd;
+        if (!root)
+            return { ok: false, error: "no sandbox root: QCR_SANDBOX_ROOT is not set" };
+        const realRoot = realDir(root);
+        if (!realRoot)
+            return { ok: false, error: `sandbox root ${root} is not readable` };
+        const extras = sanctionedExtras(env);
+        const resolved = [];
+        for (const d of dirs) {
+            const r = resolveTaskDir(d, realRoot, extras, env.QCR_PR?.trim() || undefined);
+            if ("error" in r)
+                return { ok: false, error: r.error };
+            if (resolved.some((x) => x.dir === r.dir))
+                continue;
+            if (resolved.some((x) => x.phase === r.phase))
+                return { ok: false, error: `two ${r.phase} task directories in one launch` };
+            if (resolved.some((x) => x.passes !== r.passes))
+                return { ok: false, error: "the task directories belong to different rounds" };
+            resolved.push(r);
+        }
+        // Plan rows first, then the optional rows, then the sweep's — the daemon's
+        // launch order within each.
+        const rank = { plan: 0, optional: 1, sweep: 2 };
+        resolved.sort((a, b) => rank[a.phase] - rank[b.phase]);
+        const all = [];
+        for (const r of resolved) {
+            for (const f of listTaskFiles(r.dir)) {
+                const path = join(r.dir, f.file);
+                all.push({ phase: r.phase, ...f, path, task: taskPointer(path) });
+            }
+        }
+        if (all.length === 0)
+            return {
+                ok: false,
+                error: `no discovery task files in ${resolved.map((r) => r.dir).join(", ")}`,
+            };
+        // Every key must hit a row: a typo must never silently drop the prior
+        // findings the session meant to assign, nor launch a row it meant to raise.
+        const hits = (key) => all.filter((u) => unitKeys(u).includes(key));
+        for (const key of skip)
+            if (hits(key).length === 0)
+                return { ok: false, error: `skip: no row answers to "${key}"` };
+        for (const [key] of extra)
+            if (hits(key).length === 0)
+                return { ok: false, error: `extra: no row answers to "${key}"` };
+        const skipped = all.filter((u) => skip.some((k) => unitKeys(u).includes(k)));
+        const units = all
+            .filter((u) => !skipped.includes(u))
+            .map((u) => {
+            const added = extra
+                .filter(([k]) => unitKeys(u).includes(k))
+                .map(([, v]) => v.trim())
+                .filter((v) => v);
+            return added.length ? { ...u, task: [u.task, ...added].join("\n\n") } : u;
+        });
+        if (units.length === 0)
+            return { ok: false, error: "every row was skipped: nothing to launch" };
+        return { ok: true, units, skipped };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=launch-plan.js.map

package/dist/src/engine/lens/launch-plan.js.map

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

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

@@ -0,0 +1,22 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/** Short hashes of the parts that make up a request's cacheable prefix, in
+ * request order (never their content). */
+export declare function prefixDigest(payload: unknown): string;
+/**
+ * The pack-first payload, or undefined to send the original. Pure.
+ * `appended` is the lens body as pi appended it; `pack` the pack's text.
+ */
+export declare function packFirstPayload(payload: unknown, appended: string, pack: string): Record<string, unknown> | undefined;
+export interface LeafCacheOptions {
+    /** The round's context pack text. Blank: the extension does nothing. */
+    pack: string;
+    /** The cache group's key (= its shared session id). */
+    cacheKey: string;
+    /** The lens body as appended to the system prompt; "" for a group's warm-up. */
+    body?: string;
+    /** Told once when a request is not the shape the rewrite expects. */
+    onUnexpected?: () => void;
+}
+/** The extension that puts the pack first and pins the cache key. */
+export declare function leafCache(options: LeafCacheOptions): ExtensionFactory;
+//# sourceMappingURL=leaf-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-cache.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/leaf-cache.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAKxE;0CAC0C;AAC1C,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAkBrD;AAWD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAmCrC;AAaD,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAarE"}

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

@@ -0,0 +1,115 @@
+// leaf-cache, the pack-first payload rewrite and the SDK lens's extension that
+// applies it.
+//
+// The request layout: the lens body comes out of pi's `<addendum>` block in
+// `instructions`; the input becomes the pack (user role, fenced data), then the
+// lens body as a developer message, then the task. The pack is then the prefix
+// every lens request of a cache group extends (docs/prompt-caching.md).
+//
+// leafCache({ pack, cacheKey }) rewrites each request pack-first, and on a payload that carries
+// a `prompt_cache_key` sets it to the group's key. Under the shared session id
+// of a cache group (docs/probes/p4.6-codex-cache-routing.md) the key already
+// equals that id, so the second edit is a belt for a pi that derives the key
+// another way, not what routes the cache. Fail-open, always: a payload that is
+// not the expected shape goes out unchanged, and a throw inside the handler is
+// pi's to contain (it reports it as an extension error), never the request's.
+//
+// VERIFY-ON-PIN (pi 1.3.0, re-read at 1.4.0): `before_provider_request` may return a replacement
+// payload; the codex payload carries `instructions` (string), `input` (an array
+// of `{ role, content: [{ type: "input_text", text }] }`) and `prompt_cache_key`.
+import { createHash } from "node:crypto";
+const ADDENDUM_OPEN = "<addendum>";
+const ADDENDUM_CLOSE = "</addendum>";
+/** Short hashes of the parts that make up a request's cacheable prefix, in
+ * request order (never their content). */
+export function prefixDigest(payload) {
+    const h = (v) => createHash("sha256")
+        .update(JSON.stringify(v ?? null))
+        .digest("hex")
+        .slice(0, 10);
+    if (typeof payload !== "object" || payload === null)
+        return "no payload";
+    const p = payload;
+    const input = Array.isArray(p.input) ? p.input : [];
+    const rest = Object.fromEntries(Object.entries(p).filter(([k]) => !["instructions", "input", "tools"].includes(k)));
+    return [
+        `other=${h(rest)}`,
+        `instructions=${h(p.instructions)}`,
+        `tools=${h(p.tools)}`,
+        ...input.slice(0, 3).map((m, i) => `input${i}=${h(m)}`),
+    ].join(" ");
+}
+function textMessage(role, text) {
+    return { role, content: [{ type: "input_text", text }] };
+}
+/**
+ * The pack-first payload, or undefined to send the original. Pure.
+ * `appended` is the lens body as pi appended it; `pack` the pack's text.
+ */
+export function packFirstPayload(payload, appended, pack) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return undefined;
+    const p = payload;
+    const instructions = p.instructions;
+    const input = p.input;
+    const body = appended.trim();
+    if (typeof instructions !== "string" || !Array.isArray(input) || !pack.trim())
+        return undefined;
+    // A group's WARM-UP (no lens text): only the pack goes first, so its request
+    // is exactly the prefix every lens request of the group extends.
+    if (!body)
+        return { ...p, input: [textMessage("user", pack), ...input] };
+    const at = instructions.indexOf(body);
+    if (at < 0 || instructions.indexOf(body, at + 1) >= 0)
+        return undefined;
+    let start = at;
+    let end = at + body.length;
+    // The whole `<addendum>…</addendum>` block when the body is all it holds.
+    const open = instructions.lastIndexOf(ADDENDUM_OPEN, at);
+    const close = instructions.indexOf(ADDENDUM_CLOSE, end);
+    if (open >= 0 &&
+        close >= 0 &&
+        instructions.slice(open + ADDENDUM_OPEN.length, at).trim() === "" &&
+        instructions.slice(end, close).trim() === "") {
+        start = open;
+        end = close + ADDENDUM_CLOSE.length;
+    }
+    const before = instructions.slice(0, start).trimEnd();
+    const after = instructions.slice(end).trim();
+    if (!before)
+        return undefined;
+    const base = after ? `${before}\n\n${after}` : before;
+    return {
+        ...p,
+        instructions: base,
+        input: [textMessage("user", pack), textMessage("developer", body), ...input],
+    };
+}
+/** The payload with `prompt_cache_key` set to `cacheKey`, or undefined when it
+ * carries no string key or already has this one. */
+function withCacheKey(payload, cacheKey) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        return undefined;
+    const p = payload;
+    const held = p["prompt_cache_key"];
+    return typeof held === "string" && held !== cacheKey
+        ? { ...p, prompt_cache_key: cacheKey }
+        : undefined;
+}
+/** The extension that puts the pack first and pins the cache key. */
+export function leafCache(options) {
+    return (pi) => {
+        if (!options.pack.trim())
+            return;
+        let warned = false;
+        pi.on("before_provider_request", (event) => {
+            const packed = packFirstPayload(event.payload, options.body ?? "", options.pack);
+            if (packed === undefined && !warned) {
+                warned = true;
+                options.onUnexpected?.();
+            }
+            return withCacheKey(packed ?? event.payload, options.cacheKey) ?? packed;
+        });
+    };
+}
+//# sourceMappingURL=leaf-cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-cache.js","sourceRoot":"","sources":["../../../../src/engine/lens/leaf-cache.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,cAAc;AACd,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,+EAA+E;AAC/E,wEAAwE;AACxE,EAAE;AACF,gGAAgG;AAChG,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,EAAE;AACF,iGAAiG;AACjG,gFAAgF;AAChF,kFAAkF;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,aAAa,GAAG,YAAY,CAAC;AACnC,MAAM,cAAc,GAAG,aAAa,CAAC;AAErC;0CAC0C;AAC1C,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,MAAM,CAAC,GAAG,CAAC,CAAU,EAAE,EAAE,CACvB,UAAU,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;SACjC,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClB,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IACzE,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CACnF,CAAC;IACF,OAAO;QACL,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE;QAClB,gBAAgB,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE;QACnC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE;QACrB,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAOD,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgB,EAChB,QAAgB,EAChB,IAAY;IAEZ,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAChG,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IACtB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAChG,6EAA6E;IAC7E,iEAAiE;IACjE,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;IACzE,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,EAAE,GAAG,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,MAAM,IAAI,GAAG,YAAY,CAAC,WAAW,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACxD,IACE,IAAI,IAAI,CAAC;QACT,KAAK,IAAI,CAAC;QACV,YAAY,CAAC,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE;QACjE,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAC5C,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,GAAG,GAAG,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC;IACtC,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IACtD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO;QACL,GAAG,CAAC;QACJ,YAAY,EAAE,IAAI;QAClB,KAAK,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED;oDACoD;AACpD,SAAS,YAAY,CAAC,OAAgB,EAAE,QAAgB;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAChG,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACnC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ;QAClD,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,gBAAgB,EAAE,QAAQ,EAAE;QACtC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAaD,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,OAAO,CAAC,EAAE,EAAE,EAAE;QACZ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO;QACjC,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,EAAE,CAAC,EAAE,CAAC,yBAAyB,EAAE,CAAC,KAAK,EAAE,EAAE;YACzC,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACjF,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC;gBACpC,MAAM,GAAG,IAAI,CAAC;gBACd,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;YAC3B,CAAC;YACD,OAAO,YAAY,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC;QAC3E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,14 @@
+import type { WeightedSemaphore } from "./semaphore.js";
+export interface Permit {
+    /** Give the permit back. Idempotent. */
+    release(): void;
+}
+export interface Permits {
+    /** Resolves with the permit once `weight` of them are free. `lensId` names the
+     * pass (a broker keys on it). A `signal` that aborts while waiting ends the
+     * wait and rejects; the local semaphore ignores it, as it always has. */
+    acquire(lensId: string, weight: number, signal?: AbortSignal): Promise<Permit>;
+}
+/** The local semaphore as a port. */
+export declare function localPermits(semaphore: WeightedSemaphore): Permits;
+//# sourceMappingURL=permits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permits.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/permits.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,MAAM,WAAW,MAAM;IACrB,wCAAwC;IACxC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB;;6EAEyE;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChF;AAED,qCAAqC;AACrC,wBAAgB,YAAY,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAclE"}

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

@@ -0,0 +1,18 @@
+/** The local semaphore as a port. */
+export function localPermits(semaphore) {
+    return {
+        async acquire(_lensId, weight) {
+            await semaphore.acquire(weight);
+            let given = false;
+            return {
+                release: () => {
+                    if (given)
+                        return;
+                    given = true;
+                    semaphore.release(weight);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=permits.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permits.js","sourceRoot":"","sources":["../../../../src/engine/lens/permits.ts"],"names":[],"mappings":"AAsBA,qCAAqC;AACrC,MAAM,UAAU,YAAY,CAAC,SAA4B;IACvD,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM;YAC3B,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,KAAK,GAAG,KAAK,CAAC;YAClB,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAI,KAAK;wBAAE,OAAO;oBAClB,KAAK,GAAG,IAAI,CAAC;oBACb,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}