@quickchatai/pi-quickreview 0.0.0-stage → 1.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/semaphore.ts"],"names":[],"mappings":"AAGA,4CAA4C;AAC5C,qBAAa,iBAAiB;IAIhB,QAAQ,CAAC,OAAO,EAAE,MAAM;IAHpC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsD;gBAEzD,OAAO,EAAE,MAAM;IAIpC,gEAAgE;IAChE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,eAAe;IAIjB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAc9B"}

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

@@ -0,0 +1,44 @@
+// The process-wide lens cap: a FIFO counting semaphore with per-call weights.
+// Pure. Lifted from the retired extensions/subagents.ts.
+/** A weighted counting semaphore (FIFO). */
+export class WeightedSemaphore {
+    permits;
+    available;
+    waiters = [];
+    constructor(permits) {
+        this.permits = permits;
+        this.available = permits;
+    }
+    /** Number of permits currently held (for tests/diagnostics). */
+    get held() {
+        return this.permits - this.available;
+    }
+    normalizeWeight(weight) {
+        return Math.max(1, Math.min(weight, this.permits));
+    }
+    async acquire(weight) {
+        const w = this.normalizeWeight(weight);
+        if (this.available >= w && this.waiters.length === 0) {
+            this.available -= w;
+            return;
+        }
+        await new Promise((resolve) => {
+            this.waiters.push({ weight: w, resolve });
+        });
+    }
+    release(weight) {
+        this.available += this.normalizeWeight(weight);
+        if (this.available > this.permits)
+            this.available = this.permits;
+        while (this.waiters.length > 0 &&
+            this.waiters[0] !== undefined &&
+            this.available >= this.waiters[0].weight) {
+            const next = this.waiters.shift();
+            if (!next)
+                break;
+            this.available -= next.weight;
+            next.resolve();
+        }
+    }
+}
+//# sourceMappingURL=semaphore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../../../../src/engine/lens/semaphore.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yDAAyD;AAEzD,4CAA4C;AAC5C,MAAM,OAAO,iBAAiB;IAIP;IAHb,SAAS,CAAS;IACT,OAAO,GAAmD,EAAE,CAAC;IAE9E,YAAqB,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;QAClC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,gEAAgE;IAChE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;IACvC,CAAC;IAEO,eAAe,CAAC,MAAc;QACpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC;QACjE,OACE,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YACvB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS;YAC7B,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EACxC,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI;gBAAE,MAAM;YACjB,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC;YAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,34 @@
+import { LENS_TOOL, LENS_WAVE_TOOL } from "../../lensresult.js";
+import { type QcrTool } from "../../../extensions/pi-tool.js";
+import { type LensWave, type WaveRunner } from "./wave.js";
+export { LENS_TOOL, LENS_WAVE_TOOL };
+/** More passes than this in one `lens` call is a mistake, not a plan. */
+export declare const MAX_LENS_TASKS = 64;
+/** A pass's text in a parallel result is cut here, as the native tool cuts it;
+ * the whole of it stays in `details`. */
+export declare const PER_TASK_OUTPUT_CAP: number;
+export interface LensToolDeps {
+    /** Starts a pass. The runner's cap and cache groups bound the fan-out. */
+    runner: WaveRunner;
+    /** The round's rows in flight. */
+    wave: LensWave;
+    /** The session's environment: `lens_wave` resolves its dirs against it
+     * (QCR_SANDBOX_ROOT, QCR_PR, QCR_LAUNCH_PLAN_DIRS), as launch_plan does. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** The sandbox root `lens_wave` falls back to when `env` names none: the
+     * interactive pi's cwd, as its host resolves it. */
+    cwd?: () => string;
+}
+type Execute = QcrTool["execute"];
+/** The `lens` tool's execute. */
+export declare function lensExecute(deps: LensToolDeps): Execute;
+/** The `lens_wave` tool's execute. */
+export declare function lensWaveExecute(deps: LensToolDeps): Execute;
+/** The `lens` tool definition. Parameters are plain JSON Schema (a TypeBox
+ * schema is plain JSON Schema at runtime). */
+export declare function lensDefinition(deps: LensToolDeps): QcrTool;
+/** The `lens_wave` tool definition. */
+export declare function lensWaveDefinition(deps: LensToolDeps): QcrTool;
+/** Both tools, in registration order. */
+export declare function lensToolDefinitions(deps: LensToolDeps): QcrTool[];
+//# sourceMappingURL=tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/tool.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAmB,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAc,KAAK,OAAO,EAAsB,MAAM,gCAAgC,CAAC;AAG9F,OAAO,EAAa,KAAK,QAAQ,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;yCACyC;AACzC,eAAO,MAAM,mBAAmB,QAAY,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,UAAU,CAAC;IACnB,kCAAkC;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf;gFAC4E;IAC5E,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAClD;wDACoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,KAAK,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAmKlC,iCAAiC;AACjC,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAqCvD;AAQD,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CA+E3D;AAaD;8CAC8C;AAC9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CA0B1D;AAED,uCAAuC;AACvC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CA6C9D;AAED,yCAAyC;AACzC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,EAAE,CAEjE"}

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

@@ -0,0 +1,345 @@
+// Our lens tools: `lens` and `lens_wave` (owner ruling), the engine routes'
+// replacement for pi's native `subagent` and the glue's `launch_plan` (retired);
+// a consumer still reads all four, for the transcripts and ledgers of
+// older rounds (packages/pi-plugin/src/lensresult.ts isLensTool).
+//
+//   lens        one pass, `{agent, task}`, or several at once, `{tasks: [...]}`:
+//               the rows the session raises, the lenses it adds, the validator.
+//   lens_wave   the round's planned discovery wave, from the task files the
+//               engine wrote (dirs: the round's tasks, tasks-optional and
+//               tasks-sweep, bounded and confined exactly as launch_plan's are,
+//               with the same `extra` / `skip`). The engine launches that wave
+//               itself at round start, so `lens_wave` JOINS it: a row that
+//               is running is waited for, a row that is done is returned, and
+//               a row that was never started is started. Nothing runs twice.
+//
+// Both return what the native tools return, so every consumer reads them
+// unchanged: `details.results` holds one LensResult v1 per pass (with the run's
+// `id`, which is how a pass joined by two calls is counted once), `details.mode`
+// is `single` or `parallel`, and a pass still running reports `exitCode: -1`
+// in the updates. The tools run passes on a LensRunner (runlens.ts): the cap,
+// the cache groups and the retry-once deadline are the runner's, not theirs.
+// This module touches no pi SDK; packages/pi-plugin/extensions/lens.ts and the round's hosting
+// give the definitions to pi.
+import { LENS_TOOL, LENS_WAVE_TOOL } from "../../lensresult.js";
+import { textResult } from "../../../extensions/pi-tool.js";
+import { planLaunch } from "./launch-plan.js";
+import { runSafely } from "./wave.js";
+export { LENS_TOOL, LENS_WAVE_TOOL };
+/** More passes than this in one `lens` call is a mistake, not a plan. */
+export const MAX_LENS_TASKS = 64;
+/** A pass's text in a parallel result is cut here, as the native tool cuts it;
+ * the whole of it stays in `details`. */
+export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+const ZERO_USAGE = { input: 0, output: 0, cacheRead: 0, cost: 0 };
+const isFailed = (r) => r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+function truncated(output) {
+    const bytes = Buffer.byteLength(output, "utf8");
+    if (bytes <= PER_TASK_OUTPUT_CAP)
+        return output;
+    let cut = output.slice(0, PER_TASK_OUTPUT_CAP);
+    while (Buffer.byteLength(cut, "utf8") > PER_TASK_OUTPUT_CAP)
+        cut = cut.slice(0, -1);
+    return `${cut}\n\n[Output truncated: ${bytes - Buffer.byteLength(cut, "utf8")} bytes omitted. Full output preserved in tool details.]`;
+}
+function outputOf(run) {
+    return (isFailed(run.result) ? run.result.errorMessage : undefined) || run.text || "(no output)";
+}
+/** A pass that has not reported yet, in the native tool's still-running shape. */
+function placeholder(agent, task) {
+    return { agent, task, exitCode: -1, messages: [], usage: ZERO_USAGE };
+}
+/** One slot of `details.results`: the pass's LensResult v1 and the task it ran. */
+function slot(run, task) {
+    return { ...run.result, task };
+}
+function error(tool, message, hint) {
+    return {
+        ...textResult(`${tool}: ${message}. ${hint}`, { [tool]: { error: message } }),
+        isError: true,
+    };
+}
+/** The result of a parallel call: the native summary text, `details.results`
+ * in the order asked. */
+function parallelResult(entries, extraDetails = {}) {
+    const finished = entries.filter((e) => e.run !== undefined);
+    const succeeded = finished.filter((e) => !isFailed(e.run.result)).length;
+    const summaries = entries.map((e) => {
+        if (e.run === undefined)
+            return `### [${e.agent}] still running\n\n(no output yet)`;
+        const status = isFailed(e.run.result)
+            ? `failed${e.run.result.stopReason && e.run.result.stopReason !== "end" ? ` (${e.run.result.stopReason})` : ""}`
+            : "completed";
+        return `### [${e.agent}] ${status}\n\n${truncated(outputOf(e.run))}`;
+    });
+    return textResult(`Parallel: ${succeeded}/${entries.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`, {
+        mode: "parallel",
+        results: resultsOf(entries),
+        ...extraDetails,
+    });
+}
+function resultsOf(entries) {
+    return entries.map((e) => (e.run ? slot(e.run, e.task) : placeholder(e.agent, e.task)));
+}
+function progressUpdate(entries, extraDetails = {}) {
+    const done = entries.filter((e) => e.run !== undefined).length;
+    return textResult(`Parallel: ${done}/${entries.length} done, ${entries.length - done} running...`, {
+        mode: "parallel",
+        results: resultsOf(entries),
+        ...extraDetails,
+    });
+}
+/**
+ * Wait for every entry's run, telling `onUpdate` each time one lands. Resolves
+ * early, with whatever has landed, when `signal` aborts; the runs themselves are
+ * ended by the signal only where the caller handed it to them.
+ */
+async function awaitEntries(entries, runs, signal, onUpdate, extraDetails) {
+    let stop;
+    const aborted = new Promise((resolve) => {
+        if (signal === undefined)
+            return;
+        if (signal.aborted)
+            return resolve("aborted");
+        stop = () => resolve("aborted");
+        signal.addEventListener("abort", stop, { once: true });
+    });
+    const landed = Promise.all(runs.map(async (p, i) => {
+        const run = await p;
+        entries[i].run = run;
+        try {
+            onUpdate?.(progressUpdate(entries, extraDetails));
+        }
+        catch {
+            // a progress listener's failure is not the call's
+        }
+    })).then(() => "done");
+    try {
+        return await Promise.race([landed, aborted]);
+    }
+    finally {
+        if (stop !== undefined)
+            signal?.removeEventListener("abort", stop);
+    }
+}
+function readLensCall(params) {
+    if (params["chain"] !== undefined)
+        return "`chain` is not supported: launch each lens yourself, or several at once with `tasks`";
+    const hasTasks = params["tasks"] !== undefined;
+    const hasSingle = params["agent"] !== undefined || params["task"] !== undefined;
+    if (hasTasks && hasSingle)
+        return "give `agent` and `task`, or `tasks`, not both";
+    if (hasTasks) {
+        const raw = params["tasks"];
+        if (!Array.isArray(raw) || raw.length === 0)
+            return "`tasks` must be a non-empty list";
+        if (raw.length > MAX_LENS_TASKS)
+            return `at most ${MAX_LENS_TASKS} tasks in one call`;
+        const tasks = [];
+        for (const [i, t] of raw.entries()) {
+            const o = typeof t === "object" && t !== null ? t : {};
+            if (typeof o["agent"] !== "string" ||
+                typeof o["task"] !== "string" ||
+                !o["agent"] ||
+                !o["task"])
+                return `tasks[${i}] needs an \`agent\` and a \`task\``;
+            tasks.push({ agent: o["agent"], task: o["task"] });
+        }
+        return { mode: "parallel", tasks };
+    }
+    if (typeof params["agent"] !== "string" || typeof params["task"] !== "string")
+        return "give `agent` and `task`, or `tasks`";
+    if (!params["agent"] || !params["task"])
+        return "give `agent` and `task`, or `tasks`";
+    return { mode: "single", tasks: [{ agent: params["agent"], task: params["task"] }] };
+}
+/** The `lens` tool's execute. */
+export function lensExecute(deps) {
+    return async function lens(_id, params, signal, onUpdate) {
+        const call = readLensCall(params ?? {});
+        if (typeof call === "string")
+            return error(LENS_TOOL, call, "Nothing was launched.");
+        const update = onUpdate;
+        const runs = call.tasks.map((t) => runSafely(deps.runner, { agent: t.agent, task: t.task, ...(signal ? { signal } : {}) }));
+        const entries = call.tasks.map((t) => ({ ...t, run: undefined }));
+        const outcome = await awaitEntries(entries, runs, signal, update, {});
+        if (call.mode === "parallel") {
+            const result = parallelResult(entries);
+            return outcome === "aborted" ? { ...result, isError: true } : result;
+        }
+        const run = entries[0].run;
+        const only = call.tasks[0];
+        if (run === undefined)
+            return {
+                ...textResult(`Agent aborted: ${only.agent} was stopped before it answered`, {
+                    mode: "single",
+                    results: [placeholder(only.agent, only.task)],
+                }),
+                isError: true,
+            };
+        if (isFailed(run.result))
+            return {
+                ...textResult(`Agent ${run.result.stopReason || "failed"}: ${outputOf(run)}`, {
+                    mode: "single",
+                    results: [slot(run, only.task)],
+                }),
+                isError: true,
+            };
+        return textResult(run.text || "(no output)", {
+            mode: "single",
+            results: [slot(run, only.task)],
+        });
+    };
+}
+// ---- lens_wave -----------------------------------------------------------
+function unitSummary(u) {
+    return { phase: u.phase, row: u.row, agent: u.agent };
+}
+/** The `lens_wave` tool's execute. */
+export function lensWaveExecute(deps) {
+    return async function lensWave(_id, params, signal, onUpdate) {
+        const p = params ?? {};
+        const hasDirs = p["dirs"] !== undefined || p["dir"] !== undefined;
+        const update = onUpdate;
+        let rows;
+        const launched = [];
+        let skipped = [];
+        const extraIgnored = [];
+        if (!hasDirs) {
+            if (p["extra"] !== undefined || p["skip"] !== undefined)
+                return error(LENS_WAVE_TOOL, "`extra` and `skip` name rows of a task directory, so they need `dirs`", "Nothing was launched.");
+            rows = deps.wave.rows();
+            if (rows.length === 0)
+                return error(LENS_WAVE_TOOL, "the engine has launched no wave in this round", "Pass the round's task directory in `dirs`, or launch lenses yourself with `lens`.");
+        }
+        else {
+            const plan = planLaunch(p, { ...deps.env }, deps.cwd?.());
+            if (!plan.ok)
+                return error(LENS_WAVE_TOOL, plan.error, "Nothing was launched here: launch the rows with `lens`, all in this one turn.");
+            skipped = plan.skipped;
+            rows = [];
+            for (const unit of plan.units) {
+                const { row, started } = deps.wave.start(deps.runner, unit, "call", signal);
+                rows.push(row);
+                if (started)
+                    launched.push(unit);
+                else if (unit.task !== row.task)
+                    extraIgnored.push(unit.path);
+            }
+        }
+        const joined = rows.filter((r) => !launched.some((u) => u.path === r.key));
+        const summary = {
+            launched: launched.map(unitSummary),
+            joined: joined.map((r) => unitSummary(r.unit)),
+            skipped: skipped.map(unitSummary),
+            ...(extraIgnored.length > 0 ? { extra_ignored: extraIgnored } : {}),
+        };
+        const details = { lens_wave: summary };
+        const entries = rows.map((r) => ({
+            agent: r.unit.agent,
+            task: r.task,
+            run: r.result,
+        }));
+        const outcome = await awaitEntries(entries, rows.map((r) => r.done), signal, update, details);
+        const result = parallelResult(entries, details);
+        if (outcome === "aborted") {
+            const running = entries.filter((e) => e.run === undefined).length;
+            return {
+                ...result,
+                content: [
+                    {
+                        type: "text",
+                        text: `lens_wave was stopped with ${running} lens(es) still running.\n\n${result.content[0].text}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return result;
+    };
+}
+// ---- definitions ---------------------------------------------------------
+const TASK_ITEM = {
+    type: "object",
+    properties: {
+        agent: { type: "string", description: "The lens, by name (an agent of the built set)." },
+        task: { type: "string", description: "Its task: the whole message it is sent." },
+    },
+    required: ["agent", "task"],
+};
+/** The `lens` tool definition. Parameters are plain JSON Schema (a TypeBox
+ * schema is plain JSON Schema at runtime). */
+export function lensDefinition(deps) {
+    return {
+        name: LENS_TOOL,
+        label: "Lens",
+        description: "Run lens passes: one (`agent` + `task`) or several at once (`tasks`). Each pass is a read-only " +
+            "reviewer that works alone and answers with its findings; it cannot launch anything itself. Use it for " +
+            "the lenses you raise or add, the validator, and any pass the round's wave does not cover. The round's " +
+            "planned discovery wave is collected with `lens_wave`, not launched here. Several passes belong in ONE " +
+            "call so they run together. Returns each pass's result in `details.results`, in the order asked.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "The lens, by name. With `task`." },
+                task: { type: "string", description: "Its task. With `agent`." },
+                tasks: {
+                    type: "array",
+                    items: TASK_ITEM,
+                    minItems: 1,
+                    maxItems: MAX_LENS_TASKS,
+                    description: "Several passes to run at once, each `{agent, task}`.",
+                },
+            },
+        },
+        execute: lensExecute(deps),
+    };
+}
+/** The `lens_wave` tool definition. */
+export function lensWaveDefinition(deps) {
+    return {
+        name: LENS_WAVE_TOOL,
+        label: "Lens wave",
+        description: "Collect this review round's planned discovery wave. The engine launched the wave when the round " +
+            "began, from the task files it wrote (state/pr-<n>-round-<k>-passes/tasks); this returns the results of " +
+            "every row that is finished and waits for the rows still running. It never launches a row twice. With no " +
+            "arguments it returns the wave the engine launched. With `dirs` it covers the rows of those task " +
+            "directories (the round's tasks, a follow-up round's tasks-optional, the sweep's tasks-sweep) and " +
+            "starts any row nobody has started yet. A row you raise to another tier belongs in `skip`, and " +
+            "you run it with `lens`. Returns the same result `lens` returns for a parallel call.",
+        parameters: {
+            type: "object",
+            properties: {
+                dirs: {
+                    type: "array",
+                    items: { type: "string" },
+                    minItems: 1,
+                    maxItems: 3,
+                    description: "The round's task directory (…-passes/tasks, or the …-passes dir itself), and optionally the " +
+                        "follow-up round's optional rows (…-passes/tasks-optional) and the sweep's …-passes/tasks-sweep.",
+                },
+                extra: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "Text appended after the pointer of a row this call starts (prior findings assigned to that lens, a " +
+                        "site, a question). Key: the row number as the plan table prints it (`sweep:<row>` for a sweep row, " +
+                        "`optional:<row>` for an optional row), the task file name, the agent name (every row of that " +
+                        "agent), `plan:*` / `optional:*` / `sweep:*` (every row of that phase) or `*` (every row). A row the " +
+                        "engine already started keeps the text it started with.",
+                },
+                skip: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Rows (same keys as `extra`) NOT to cover here because you run them yourself with `lens` at a " +
+                        "raised tier.",
+                },
+            },
+        },
+        execute: lensWaveExecute(deps),
+    };
+}
+/** Both tools, in registration order. */
+export function lensToolDefinitions(deps) {
+    return [lensDefinition(deps), lensWaveDefinition(deps)];
+}
+//# sourceMappingURL=tool.js.map

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

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

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

@@ -0,0 +1,63 @@
+import type { Runtime } from "../port.js";
+import type { LaunchUnit } from "./launch-plan.js";
+import type { LensRequest, LensRun } from "./runlens.js";
+/** What a wave needs of the runner: start one pass. */
+export interface WaveRunner {
+    run(request: LensRequest): Promise<LensRun>;
+}
+/** Who started a row. */
+export type WaveOrigin = "engine" | "call";
+export interface WaveRow {
+    /** The task file's path: the row's identity. */
+    key: string;
+    unit: LaunchUnit;
+    origin: WaveOrigin;
+    /** The task text the row was started with (its pointer plus any `extra`). */
+    task: string;
+    /** Settles with the pass's result; never rejects. */
+    done: Promise<LensRun>;
+    /** The result, once `done` has settled. */
+    result: LensRun | undefined;
+    /** The call's abort ended it before the model did. */
+    aborted: boolean;
+}
+/** One pass, as a result however it ends: runLens does not reject, but a runner
+ * that does (a host that cannot be built) is still a failed pass. */
+export declare function runSafely(runner: WaveRunner, request: LensRequest): Promise<LensRun>;
+export declare class LensWave {
+    private readonly byKey;
+    /** The row for a task file, if one was started. */
+    get(key: string): WaveRow | undefined;
+    /** Every row, in the order they were started. */
+    rows(): WaveRow[];
+    /** Rows still running. */
+    running(): number;
+    /** Start a row, unless a row for the same task file is already on the board:
+     * then that row is returned and nothing is started. `started` tells which. */
+    start(runner: WaveRunner, unit: LaunchUnit, origin: WaveOrigin, signal?: AbortSignal): {
+        row: WaveRow;
+        started: boolean;
+    };
+    /** Forget every row (a new round on the same board). */
+    clear(): void;
+}
+/**
+ * The engine's launch of the planned wave: every unit started at once (the
+ * runner's own cap and session stagger pace them), none twice. Returns the
+ * rows; the engine keeps `signal` to end the wave with the round.
+ */
+export declare function launchWave(wave: LensWave, runner: WaveRunner, units: readonly LaunchUnit[], signal?: AbortSignal): WaveRow[];
+/** What a runtime that hosts the engine's lens tools hands the round: the board
+ * its `lens_wave` reads, the runner behind it, and whether the engine starts the
+ * planned wave (`[pi] engine_wave`) or leaves the launch to the main session. */
+export interface EngineRoute {
+    wave: LensWave;
+    runner: WaveRunner;
+    plannedWave: boolean;
+}
+/** A runtime that carries an engine route (packages/pi-plugin/src/engine/reviewsdk.ts). The round
+ * (round.ts) reads it off the runtime it is given. */
+export type EngineRouteRuntime = Runtime & {
+    readonly engineLens?: EngineRoute;
+};
+//# sourceMappingURL=wave.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wave.d.ts","sourceRoot":"","sources":["../../../../src/engine/lens/wave.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEzD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAED,yBAAyB;AACzB,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,OAAO;IACtB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;qEACqE;AACrE,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBpF;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAEpD,mDAAmD;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIrC,iDAAiD;IACjD,IAAI,IAAI,OAAO,EAAE;IAIjB,0BAA0B;IAC1B,OAAO,IAAI,MAAM;IAIjB;kFAC8E;IAC9E,KAAK,CACH,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,UAAU,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE;IA6BrC,wDAAwD;IACxD,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,EAAE,CAEX;AAED;;iFAEiF;AACjF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;sDACsD;AACtD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC"}

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

@@ -0,0 +1,95 @@
+// The round's lens wave, as a board of rows in flight.
+//
+// On an engine route the round's engine launches the PLANNED discovery wave at
+// round start, and the main session runs alongside it. `lens_wave` is how the
+// session collects it: finished rows come back as they are, running rows are
+// waited for, and nothing is launched twice. A row is keyed by its task file's
+// path (planLaunch resolves every dir to its real path, so the engine's launch
+// and the session's `lens_wave({dirs})` name the same file the same way).
+//
+// The board holds the promise of each row's run, nothing else. It never
+// schedules: the engine (or, for a row the session names, the session's own
+// `lens_wave` call) starts a row, and a started row is joined by every later
+// call. A row is forgotten only when the call that launched it was aborted: a
+// lens that failed or timed out stays on the board as the failure it was, and
+// the session re-runs it through `lens` if it wants it again.
+import { randomUUID } from "node:crypto";
+/** One pass, as a result however it ends: runLens does not reject, but a runner
+ * that does (a host that cannot be built) is still a failed pass. */
+export function runSafely(runner, request) {
+    return Promise.resolve()
+        .then(() => runner.run(request))
+        .catch((e) => ({
+        text: "",
+        result: {
+            id: randomUUID(),
+            agent: request.agent,
+            model: "unknown",
+            usage: { input: 0, output: 0, cacheRead: 0, cost: 0 },
+            messages: [],
+            exitCode: 1,
+            stopReason: "error",
+            errorMessage: e instanceof Error ? e.message : String(e),
+        },
+    }));
+}
+export class LensWave {
+    byKey = new Map();
+    /** The row for a task file, if one was started. */
+    get(key) {
+        return this.byKey.get(key);
+    }
+    /** Every row, in the order they were started. */
+    rows() {
+        return [...this.byKey.values()];
+    }
+    /** Rows still running. */
+    running() {
+        return this.rows().filter((r) => r.result === undefined).length;
+    }
+    /** Start a row, unless a row for the same task file is already on the board:
+     * then that row is returned and nothing is started. `started` tells which. */
+    start(runner, unit, origin, signal) {
+        const held = this.byKey.get(unit.path);
+        if (held !== undefined)
+            return { row: held, started: false };
+        // `done` is assigned below: the settling callback needs the row itself.
+        const row = {
+            key: unit.path,
+            unit,
+            origin,
+            task: unit.task,
+            result: undefined,
+            aborted: false,
+        };
+        row.done = runSafely(runner, {
+            agent: unit.agent,
+            task: unit.task,
+            ...(signal ? { signal } : {}),
+        }).then((run) => {
+            row.result = run;
+            if (signal?.aborted && run.result.stopReason === "aborted") {
+                row.aborted = true;
+                // Its caller ended it: the next call may start the row afresh.
+                if (this.byKey.get(unit.path) === row)
+                    this.byKey.delete(unit.path);
+            }
+            return run;
+        });
+        this.byKey.set(unit.path, row);
+        return { row, started: true };
+    }
+    /** Forget every row (a new round on the same board). */
+    clear() {
+        this.byKey.clear();
+    }
+}
+/**
+ * The engine's launch of the planned wave: every unit started at once (the
+ * runner's own cap and session stagger pace them), none twice. Returns the
+ * rows; the engine keeps `signal` to end the wave with the round.
+ */
+export function launchWave(wave, runner, units, signal) {
+    return units.map((unit) => wave.start(runner, unit, "engine", signal).row);
+}
+//# sourceMappingURL=wave.js.map

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

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