@quickchatai/pi-quickreview 0.0.0-stage → 1.2.0

package/dist/src/engine/reviewsdk.js

@@ -0,0 +1,180 @@
+// The runtime `qcr review` hosts its main session on when `[engine] runtime =
+// "sdk"`: the round's session as an in-process SDK session, with the pieces the
+// `pi` child gets as files handed over as data (packages/pi-plugin/src/engine/roundsdk.ts).
+//
+// The route prepares a private agent dir for the run (src/hostroute.ts
+// prepareHostRun: a refresh-blanked copy of the owner's login, the model list,
+// settings.json), and the round's spec names it (`PI_CODING_AGENT_DIR`). This
+// runtime builds its host on that dir when the first session is asked for:
+//
+//   login        read from the dir's auth.json by engineCredentials: an
+//                in-memory, read-only copy, refused up front when the token would
+//                expire inside the turn. An API key in the spec's env (the key
+//                route) is given to the runtime in memory.
+//   settings     the dir's settings.json supplies what the process route's pi
+//                reads from it: the durable retry and the HTTP idle timeout.
+//   dispatcher   pi's HTTP dispatcher is installed when the route owns its
+//                process (`qcr review`); inside a running pi (the plugin's
+//                /review, `hostPi`) pi's own is reused.
+//   lens tool    the engine's own (`lens`, `lens_wave`: engineLensTools,
+//                packages/pi-plugin/src/engine/lens/engine-tools.ts), through the `lens` option, or,
+//                with the `engine` option, over a runner this module builds on
+//                the host: the passes are SDK sessions of this process, not `pi`
+//                children, so the process env is never changed. A route that
+//                hands neither has no lens tool and gets no session. The
+//                `engine` option carries the round's `engineLens` (wave.ts),
+//                which the round reads: its board and runner, and whether the
+//                engine starts the planned wave (`[pi] engine_wave`).
+//
+// Stopping: every session is in the live registry (livesessions.ts), which the
+// detached driver's signal handler aborts and disposes before it exits.
+//
+// One runtime hosts one review at a time: its lens board and its lens runner
+// are the run's (the round clears the board when it starts), so a caller that
+// runs reviews side by side builds a runtime per run (packages/pi-plugin/src/reviewapi.ts asks
+// for one per run) and disposes it after.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { lensRunConfigFromEnv } from "../../extensions/lens.js";
+import { CONTEXT_PACK_FILE } from "../contextpack.js";
+import { agentDirSettings } from "./agentdir.js";
+import { applyEnvApiKeys, engineCredentials } from "./auth.js";
+import { engineLensTools } from "./lens/engine-tools.js";
+import { LensWave } from "./lens/wave.js";
+import { PiHost } from "./pisdk.js";
+import { credentialPaths, loginSourceDirs } from "./toolfence.js";
+import { checkToolUid, toolIdsOf } from "./tooluid.js";
+import { BASH_ENV_ALLOW, reviewerStub, roundSdkExtras } from "./roundsdk.js";
+import { sdkRuntime } from "./sdkruntime.js";
+/** The lens runner's config on the review route's host: the passes read the agent
+ * dir's agents, carry the reviewer stub and the same bash env allowlist as
+ * the main session, and (with a context pack beside the round's ledger) warm
+ * their cache groups with it. */
+export function engineLensConfig(host, spec) {
+    const base = lensRunConfigFromEnv(spec.env, host, spec.cwd);
+    const root = spec.env["QCR_SANDBOX_ROOT"];
+    if (root === undefined)
+        throw new Error("a round's spec names its production tree (QCR_SANDBOX_ROOT)");
+    const ledger = spec.env["QCR_LEDGER_FILE"];
+    const packPath = ledger === undefined ? undefined : join(dirname(ledger), CONTEXT_PACK_FILE);
+    const pack = packPath !== undefined && existsSync(packPath) ? readFileSync(packPath, "utf8") : "";
+    return {
+        ...base,
+        agentsFiles: [reviewerStub(root, spec.cwd)],
+        bashEnv: { allow: BASH_ENV_ALLOW },
+        ...(base.cache && pack ? { cache: { ...base.cache, pack } } : {}),
+    };
+}
+/** `SessionSpec.env` names this dir: the run's private pi agent dir. */
+const AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+/**
+ * The review route's SDK runtime. One host per agent dir, built lazily at the
+ * first session; no session, no host, no network and no env change.
+ */
+export function reviewSdkRuntime(options = {}) {
+    const procEnv = options.processEnv ?? process.env;
+    const hosts = new Map();
+    const engine = options.engine;
+    const wave = engine?.wave ?? new LensWave();
+    // The tools of the host built last: one agent dir per review, so one.
+    let lens;
+    /** The runner's config with the host's warn sink, unless it has its own. */
+    function withWarn(config) {
+        const warn = options.warn;
+        return config.warn || !warn ? config : { ...config, warn: (m) => warn(`[lens] ${m}`) };
+    }
+    function lensOf(spec, host) {
+        if (options.lens === undefined)
+            throw new Error("the review runtime has no lens tool: pass `engine`, `lens` or `extras`");
+        return options.lens(spec, host);
+    }
+    async function runtimeFor(spec) {
+        const agentDir = spec.env[AGENT_DIR_ENV];
+        if (agentDir === undefined || !isAbsolute(agentDir))
+            throw new Error(`the review's spec names no absolute ${AGENT_DIR_ENV}: ${String(agentDir)}`);
+        let built = hosts.get(agentDir);
+        if (built === undefined) {
+            built = (async () => {
+                const auth = engineCredentials({
+                    srcDir: agentDir,
+                    needMs: spec.limits.timeoutMs,
+                    ...(options.authMarginMs !== undefined ? { marginMs: options.authMarginMs } : {}),
+                });
+                const ids = toolIdsOf(procEnv);
+                const hostPi = options.hostPi === true;
+                const hostOptions = {
+                    agentDir,
+                    ownsProcess: !hostPi && options.ownsProcess !== false,
+                    ...(hostPi ? { hostPi: true } : {}),
+                    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+                    // The model's bash and every lens session's, as the tool uid.
+                    ...(ids !== null && !("refused" in ids) ? { toolUid: ids } : {}),
+                    // The round's agent dir is a copy: the login it was copied from (the
+                    // wrapper's /qcr-login, group-readable by this uid) is fenced too.
+                    fenceDirs: [
+                        ...loginSourceDirs(procEnv),
+                        ...credentialPaths(procEnv, spec.env),
+                        ...(options.fenceDirs ?? []),
+                    ],
+                    credentials: auth.credentials,
+                    settings: agentDirSettings(agentDir),
+                    configureModels: async (runtime) => {
+                        await applyEnvApiKeys(runtime, spec.env);
+                    },
+                };
+                const host = await (options.makeHost ?? PiHost.create)(hostOptions);
+                const tools = engine
+                    ? engineLensTools(withWarn((engine.config ?? engineLensConfig)(host, spec)), wave)
+                    : undefined;
+                if (tools)
+                    lens = tools;
+                const rt = sdkRuntime(host, {
+                    extras: options.extras ??
+                        ((s) => roundSdkExtras({
+                            lens: tools ?? lensOf(s, host),
+                            ...(options.warn ? { log: options.warn } : {}),
+                        })(s)),
+                    ...(options.backstop ? { backstop: options.backstop } : {}),
+                });
+                return { rt, host };
+            })();
+            // A host that failed to build is not kept: the next ask tries again.
+            built.catch(() => hosts.delete(agentDir));
+            hosts.set(agentDir, built);
+        }
+        return (await built).rt;
+    }
+    async function dispose() {
+        const all = [...hosts.values()];
+        hosts.clear();
+        lens = undefined;
+        for (const b of await Promise.allSettled(all))
+            if (b.status === "fulfilled")
+                b.value.host.dispose();
+    }
+    async function open(spec, start) {
+        // Every session is ours and runs its tools as the tool uid.
+        checkToolUid(procEnv, { what: "the SDK runtime", instead: "", isolated: true });
+        const rt = await runtimeFor(spec);
+        return start(rt);
+    }
+    const route = engine && {
+        wave,
+        // Built with the host, which the round's session has by the time it launches.
+        runner: {
+            run: (request) => {
+                if (lens === undefined)
+                    return Promise.reject(new Error("the lens runner is not built: no session was created"));
+                return lens.runner.run(request);
+            },
+        },
+        plannedWave: engine.plannedWave,
+    };
+    return {
+        create: (spec) => open(spec, (rt) => rt.create(spec)),
+        resume: (file, spec) => open(spec, (rt) => rt.resume(file, spec)),
+        dispose,
+        ...(route ? { engineLens: route } : {}),
+    };
+}
+//# sourceMappingURL=reviewsdk.js.map

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

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

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

@@ -0,0 +1,166 @@
+import type { CoreConfig } from "../reviewconfig.js";
+import type { Ecosystem } from "../ecosystem.js";
+import type { PrFileEntry } from "../githubcore.js";
+import type { RoundMemory } from "../memoryport.js";
+import { usageFromEvents, type ModelErrors, type Stages } from "./roundevents.js";
+import { type BenchPostingReport } from "./caseout.js";
+import { type AuthRejected, type EngineAuth } from "./auth.js";
+import type { PiRun, Runtime } from "./port.js";
+import { type RoundLive } from "./livewire.js";
+import { type LaunchUnit } from "./lens/launch-plan.js";
+import { type EngineRoute } from "./lens/wave.js";
+import { type OneShotPrompts, type OneShotTarget } from "./prompts.js";
+import { type CoreExtension } from "./extfiles.js";
+/** The extensions a round's main session runs with, in load order: the
+ * command guard, the ledger pin, and the live PR session's `cluster_findings`
+ * tool (the same grouping code on both routes). */
+export declare const ROUND_EXTENSIONS: readonly CoreExtension[];
+export type { PiRun };
+export declare function readJson(path: string): unknown;
+/** Why a session's JSON output file cannot be used: `undefined` when it parses,
+ * `"missing"` when absent, otherwise the parser's message. */
+export declare function jsonProblem(path: string): string | undefined;
+/** The scored BENCHMARK MODE files the session wrote that do not parse. A
+ * missing file is not listed here (`missingOutputs` lists it). */
+export declare function unparseableOutputs(caseDir: string, renderOutputs: boolean): string[];
+/** The scored BENCHMARK MODE files the session has not written. */
+export declare function missingOutputs(caseDir: string, renderOutputs: boolean): string[];
+/** The session's event stream and stderr in a case dir. */
+export declare const PI_RUN_FILES: readonly ["pi-events.jsonl", "pi-stderr.log"];
+export interface RoundSpec {
+    /** The production tree (prompts/, extensions/, agents/). Where the session
+     * runs unless `cwd` says otherwise (the bench: its project-scope lens
+     * agents live under it). */
+    root: string;
+    /** Where pi runs, and so which context file, project settings and project
+     * agents it discovers. Omitted: `root`. The host route (`qcr review`) passes
+     * the run's own dir outside every checkout, holding the reviewer stub, so a
+     * checkout never carries a context file of ours (src/hostroute.ts). */
+    cwd?: string;
+    /** Which lens agents the session resolves: "project" (the nearest
+     * `.pi/agents` above the cwd, the bench's) or "user" (`<agentDir>/agents`,
+     * the host route's). Omitted: "project". */
+    agentScope?: "project" | "user";
+    /** pi's agent dir for this run (its login). */
+    agentDir: string;
+    /** The prepared checkout of the target, at its head. */
+    tree: string;
+    /** The files the target changes. */
+    files: PrFileEntry[];
+    target: OneShotTarget;
+    /** Where the session's files, the event stream and the rendered review go. */
+    outDir: string;
+    cfg: CoreConfig;
+    ecosystem: Ecosystem;
+    timeoutMs: number;
+    /** The login the run will use, as the engine's auth module read it
+     * (packages/pi-plugin/src/engine/auth.ts). Given, the round refuses before it writes anything
+     * when the token would expire inside `timeoutMs` (`AuthExpiring`). */
+    auth?: Pick<EngineAuth, "expiresAt" | "provider">;
+    /** pi's spill dir. Omitted: `<outDir>/tmp`, removed when the run ends. A
+     * given dir is emptied here (what an earlier attempt left is not this
+     * attempt's) and is the caller's to remove. */
+    tmpDir?: string;
+    /** Prompts rendered by the caller (a bench follow-up). Omitted: the first
+     * round's, rendered here. On an engine lens route the round appends the
+     * engine-only section to their order (`result.prompts` carries the sent one). */
+    prompts?: OneShotPrompts;
+    dependencyNote?: string;
+    /** The memory seed for the first round's prompt (ignored with `prompts`). */
+    memory?: RoundMemory;
+    /** Names the run in log lines (default `repo#number`). */
+    label?: string;
+    /** The session name pi is given (default `oneshot-<number>`). */
+    sessionName?: string;
+    /** When the caller's clock started, so the continuation's budget counts
+     * work done before the runner (default: now). */
+    startedAt?: number;
+    /** Hard stop in dollars: the session (lens children with it) is killed once
+     * pi's own price for the round reaches this. The result says `capped`. */
+    capUsd?: number;
+    /** Where the round's LiveEvent log goes (src/live/). Omitted: none is written. */
+    live?: RoundLive;
+    log?: (line: string) => void;
+    /** Stops the round: an abort before the session exists starts none, and one
+     * during a turn aborts it (lens children with it) and skips the
+     * continuation. The round then settles what was written, as after any stop. */
+    signal?: AbortSignal;
+}
+export interface RoundResult {
+    prompts: OneShotPrompts;
+    plannedLenses: string[];
+    piRun: PiRun;
+    /** The one `--continue` ran. */
+    continued: boolean;
+    /** The round was stopped at `capUsd` before it finished. */
+    capped: boolean;
+    /** Why the round could not be read: no session to continue, or the output
+     * stream failed. */
+    error?: string;
+    /** Distinct warning lines from pi's stderr, then usage and render problems. */
+    warnings: string[];
+    /** The provider refused the login mid-round (authwatch's signature in pi's
+     * output). The round's own `error` names it too when nothing else does. */
+    authError?: AuthRejected;
+    /** Absent when the event stream could not be read. */
+    usage?: ReturnType<typeof usageFromEvents>;
+    modelErrors?: ModelErrors;
+    stages?: Stages["phases"];
+    /** pi's own price for the whole round (every lens child included). */
+    costUsd: number | null;
+    /** outcome.json: verdict, passes, summary. */
+    outcome?: Record<string, unknown>;
+    /** The findings record, after the production post-checks. */
+    findings?: unknown;
+    /** The rendered review body (review.md); null when nothing was rendered. */
+    review: string | null;
+    /** The rendered inline comments (comments.json). */
+    comments?: unknown[];
+    /** `[posting]` policy applied inside the render step (non-default only). */
+    renderedPosting?: BenchPostingReport;
+}
+/** What a round writes before its session starts, and what the session is
+ * started with. `runRound` hosts the session on a runtime; the debug round
+ * (src/engine/debugpi.ts) hands the same things to an interactive pi. */
+export interface PreparedRound {
+    /** The order, the engine-only section included on an engine route. */
+    prompts: OneShotPrompts;
+    /** The system prompt file the round wrote. */
+    sysPath: string;
+    /** The environment the session's tools see (no GitHub token). */
+    env: NodeJS.ProcessEnv;
+    sessionName: string;
+    /** Where the main session's JSONL goes (kept per round). */
+    sessionDir: string;
+    /** The session's event stream and stderr files. */
+    events: string;
+    stderr: string;
+    /** The planned discovery wave (engine route with `plannedWave` only). */
+    waveUnits: LaunchUnit[];
+    startWarnings: string[];
+    tmpDir: string;
+    /** `tmpDir` is the round's own: removed when it ends. */
+    ownTmp: boolean;
+}
+/** Write the round's files into `i.outDir` and work out the session's env, order
+ * and wave. `route` is the engine route the round runs on, if any. Throws only
+ * for an unwritable output dir or a login that cannot cover the run (`auth`). */
+export declare function prepareRound(i: RoundSpec, route: Pick<EngineRoute, "plannedWave"> | undefined): PreparedRound;
+/** Run one review round on `runtime`. A round that fails is a returned outcome
+ * (`error`, absent `outcome`), never a throw; only an unwritable output dir, a
+ * login that cannot cover the run (`auth`), or a runtime that cannot create the
+ * session (`runtime.create` rejects) throws.
+ *
+ * A runtime that hosts the engine's lens tools (`runtime.engineLens`, wave.ts)
+ * makes this an engine lens route: the order gains the engine-only section
+ * (prompts.ts engineLensSection), and with `plannedWave` the round starts the
+ * planned discovery wave itself, from the round's `tasks/` (never pass-validate),
+ * after the main session exists and before its first prompt; the session joins it
+ * through `lens_wave` (rule 9). Everything else stays the session's. */
+export declare function runRound(i: RoundSpec, runtime: Runtime): Promise<RoundResult>;
+/** Read what a finished round left in `outDir`: warnings from pi's stderr, the
+ * refused login, usage and stages, the price, and the outcome, findings and
+ * rendered review. `r` is the last turn; `metered` is what the session's budget
+ * counted, the price when the stream cannot be priced. */
+export declare function settleRound(i: RoundSpec, prep: Pick<PreparedRound, "events" | "stderr" | "startWarnings">, result: RoundResult, r: PiRun, metered: number): RoundResult;
+//# sourceMappingURL=round.d.ts.map

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

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