@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/debugroundpi.ts

@@ -0,0 +1,262 @@
+// The pane's side of a bot debug round: what runs inside tmux `debug-pr-<n>`.
+//
+// The daemon (src/debuground.ts) starts
+//
+//     node dist/src/ipc/launcher.js <launch-file> -- node dist/src/debugroundpi.js <spec-file>
+//
+// so this process already holds the round command's IPC capability on fd 3 (the
+// launcher claimed the launch file and unlinked it). It then
+//
+//   1. reads the spec file the daemon wrote (0600, no secret) and removes it;
+//   2. makes the pi its OWN agent dir: the owner's login BORROWED as a
+//      refresh-blanked copy (packages/pi-plugin/src/engine/auth.ts, the takeover's copy), never the
+//      refresher's file and never a write to it, plus the model and settings files
+//      and a link to the built lens agents. The pi cannot refresh;
+//   3. writes the round order the extension sends as the first message: the round's
+//      saved order (verified against the sha256 recorded at dispatch), the engine's
+//      lens section, and the command's marker, exactly as a worker builds it;
+//   4. runs interactive pi on the PR's REAL session JSONL (`--session`, which
+//      appends: not a fork) in the production tree's root even when the JSONL's
+//      header names the legacy tree (src/picwd.ts: its scripts, state/ and verdict/
+//      are there, and bash-guard sanctions the scripts only there), with the round's extensions, `/qcr-round` as its first
+//      message, and the capability fd inherited. The cwd's own context files are off
+//      and the reviewer stub is appended, so the dev instructions of the
+//      production tree never reach a reviewer;
+//   5. returns pi's exit code. The tmux session ends with this process, and the
+//      daemon's sweep settles the round and frees the lease.
+//
+// The pi's bash hands the capability fd to each command it runs (the extension's
+// bash tool), so the post shims read it for every post and send the daemon the
+// post request: the pi holds no GitHub credential and the post goes through the
+// one gate. The env it gets is an allowlist plus the round's own: no GitHub token of
+// any name. The pi runs as the separate tool uid where the image has one.
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import {
+  TOOL_UMASK,
+  checkToolUid,
+  shareWithToolGroup,
+  toolIsolation,
+  toolUidEnv,
+} from "@quickchatai/pi-quickreview/src/engine/tooluid.js";
+import { planLaunch } from "@quickchatai/pi-quickreview/src/engine/lens/launch-plan.js";
+import { engineLensSection } from "@quickchatai/pi-quickreview/src/engine/lens/section.js";
+import { CONTEXT_PACK_FILE } from "@quickchatai/pi-quickreview/src/contextpack.js";
+import { verifiedPayload } from "./session-command-payload.js";
+import { DEBUG_START_MESSAGE } from "./engine/debugpi.js";
+import { DEBUG_STATUS_NAME, debugSession, type DebugRoundSpec } from "./debuground.js";
+import { onTerminal, paneLaunch, prepareBorrowedAgent, takeoverEnv } from "./takeoverpi.js";
+
+export { DEBUG_START_MESSAGE };
+
+/** The order file's name inside the borrowed agent dir. */
+export const DEBUG_ORDER_NAME = "round-order.md";
+
+/** Read the spec the daemon wrote and remove the file. Throws on anything that is
+ * not a v1 debug-round spec. */
+export function readDebugSpec(file: string): DebugRoundSpec {
+  const raw = JSON.parse(readFileSync(file, "utf8")) as Partial<DebugRoundSpec> | null;
+  try {
+    unlinkSync(file);
+  } catch {
+    /* removed by someone else */
+  }
+  if (
+    !raw ||
+    raw.v !== 1 ||
+    typeof raw.pr !== "number" ||
+    raw.session !== debugSession(raw.pr) ||
+    typeof raw.command_id !== "string" ||
+    typeof raw.agent_dir !== "string" ||
+    typeof raw.borrow_dir !== "string" ||
+    typeof raw.session_dir !== "string" ||
+    typeof raw.model !== "string" ||
+    typeof raw.cwd !== "string" ||
+    typeof raw.system_prompt_file !== "string" ||
+    typeof raw.payload_path !== "string" ||
+    typeof raw.payload_sha256 !== "string" ||
+    typeof raw.marker !== "string" ||
+    typeof raw.passes_dir !== "string" ||
+    typeof raw.lens_dir !== "string" ||
+    typeof raw.root !== "string" ||
+    (raw.round_no !== null && typeof raw.round_no !== "number") ||
+    typeof raw.planned_wave !== "boolean" ||
+    typeof raw.idle_ms !== "number" ||
+    !Array.isArray(raw.extensions) ||
+    typeof raw.env !== "object" ||
+    raw.env === null
+  )
+    throw new Error("not a debug-round spec");
+  return raw as DebugRoundSpec;
+}
+
+/** The round order as a worker sends it: the saved order, the engine lens section
+ * (the wave the extension's command starts is named in it), and the marker. */
+export function debugRoundOrder(spec: DebugRoundSpec, path = process.env["PATH"]): string {
+  const payload = verifiedPayload(
+    { payload_path: spec.payload_path, payload_sha256: spec.payload_sha256 },
+    "the round's saved order",
+  );
+  if (!payload.ok) throw new Error(payload.why);
+  const tasks = join(spec.passes_dir, "tasks");
+  let wave: { dir: string; agents: string[] } | null = null;
+  if (spec.planned_wave && existsSync(tasks)) {
+    const plan = planLaunch(
+      { dirs: [spec.passes_dir] },
+      { QCR_SANDBOX_ROOT: spec.root, QCR_PR: String(spec.pr), PATH: path },
+    );
+    if (plan.ok && plan.units.length > 0)
+      wave = { dir: tasks, agents: plan.units.map((u) => u.agent) };
+  }
+  const section = engineLensSection(tasks, wave);
+  const order = `${payload.payload.toString("utf8").trimEnd()}\n\n${section}`;
+  return `${order}${order.endsWith("\n") ? "" : "\n"}\n${spec.marker}\n`;
+}
+
+/** Prepare the pi's own agent dir: the blanked login copy and models/settings (the
+ * takeover's borrow), the built lens agents linked, the order file, and the lens
+ * dir. Returns the order file. Nothing is written to the owner's dir. */
+export function prepareDebugAgent(spec: DebugRoundSpec, now?: () => number): { orderFile: string } {
+  prepareBorrowedAgent(spec, now);
+  // The lens passes read the built agents from the pi's agent dir.
+  const agents = join(spec.agent_dir, "agents");
+  const link = join(spec.borrow_dir, "agents");
+  if (existsSync(agents) && !existsSync(link)) symlinkSync(agents, link);
+  const orderFile = join(spec.borrow_dir, DEBUG_ORDER_NAME);
+  writeFileSync(orderFile, debugRoundOrder(spec), { mode: 0o600 });
+  chmodSync(orderFile, 0o600);
+  mkdirSync(spec.lens_dir, { recursive: true });
+  return { orderFile };
+}
+
+/** pi's argv for a bot debug round. Pure. */
+export function debugRoundArgv(spec: DebugRoundSpec): string[] {
+  return [
+    // Pre-trust the cwd's project resources: the modal would stall the pane.
+    "--approve",
+    // pi discovers no extension or skill of its own, and reads none of the production
+    // tree's context files: the reviewer stub takes their place.
+    "-ne",
+    "-ns",
+    "-nc",
+    "--model",
+    spec.model,
+    "--system-prompt",
+    spec.system_prompt_file,
+    ...(spec.stub_file ? ["--append-system-prompt", spec.stub_file] : []),
+    // The PR's real session, written to (not forked); a PR with none gets one born.
+    ...(spec.session_file ? ["--session", spec.session_file] : ["--session-dir", spec.session_dir]),
+    ...spec.extensions.flatMap((e) => ["--extension", e]),
+    "--name",
+    spec.session,
+    DEBUG_START_MESSAGE,
+  ];
+}
+
+/** The env the pi is started with: the takeover's (the allowlisted part of the
+ * pane's env, the daemon's spec env, the agent dir, no GitHub token), then the names
+ * the debug extension reads. */
+export function debugRoundEnv(
+  base: Readonly<Record<string, string | undefined>>,
+  spec: DebugRoundSpec,
+): NodeJS.ProcessEnv {
+  const env = takeoverEnv(base, spec);
+  env["QCR_DEBUG_ORDER_FILE"] = join(spec.borrow_dir, DEBUG_ORDER_NAME);
+  env["QCR_DEBUG_STATUS_FILE"] = join(spec.borrow_dir, DEBUG_STATUS_NAME);
+  env["QCR_DEBUG_LENS_DIR"] = spec.lens_dir;
+  env["QCR_DEBUG_PACK_FILE"] = join(spec.passes_dir, CONTEXT_PACK_FILE);
+  if (spec.stub_file) env["QCR_DEBUG_STUB_FILE"] = spec.stub_file;
+  if (spec.planned_wave) env["QCR_DEBUG_TASKS_DIR"] = spec.passes_dir;
+  else delete env["QCR_DEBUG_TASKS_DIR"];
+  return env;
+}
+
+export interface DebugPaneDeps {
+  piBin?: string;
+  env?: Readonly<Record<string, string | undefined>>;
+  now?: () => number;
+  /** Runs pi on the terminal with the capability fd inherited; resolves its exit
+   * code. Omitted: a child with the terminal's stdio. */
+  run?: (cmd: {
+    bin: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+  }) => Promise<number>;
+  log?: (line: string) => void;
+}
+
+/** Run the debug round the spec describes; resolves pi's exit code. A login that
+ * cannot be borrowed, or an order that does not verify, is a one-line failure and
+ * no pi: the pane ends, and the daemon's sweep hands the round to a worker. */
+export async function runDebugRoundPane(
+  specFile: string,
+  deps: DebugPaneDeps = {},
+): Promise<number> {
+  const log = deps.log ?? ((line: string) => console.error(line));
+  const procEnv = deps.env ?? process.env;
+  let spec: DebugRoundSpec;
+  try {
+    spec = readDebugSpec(specFile);
+  } catch (e) {
+    log(`debug round: ${(e as Error).message}`);
+    return 2;
+  }
+  try {
+    // The pi's bash runs in pi's uid: where the image asks for a separate tool uid
+    // the pi is started as that uid (below); where it asked and could not arrange it,
+    // there is no debug round.
+    checkToolUid(procEnv, {
+      what: "a debug round in pi",
+      instead: "none; the image must arrange the tool uid",
+      isolated: true,
+    });
+    prepareDebugAgent(spec, deps.now);
+  } catch (e) {
+    log(`debug round: ${(e as Error).message}`);
+    return 3;
+  }
+  const env = debugRoundEnv(procEnv, spec);
+  const pi = paneLaunch(debugRoundArgv(spec), deps.piBin ?? spec.pi_bin);
+  const launch = toolIsolation(pi.bin, pi.argv, procEnv);
+  if ("refused" in launch) {
+    log(`debug round: ${launch.refused}`);
+    return 3;
+  }
+  // The pi, as the tool uid, reads the agent dir the run uid made private, and writes
+  // the round's lens files.
+  // It also appends to the PR's JSONL (or births one in its session dir), which
+  // the run uid's worker wrote; what it writes stays group-writable for
+  // the worker of the next round.
+  const isolated = launch.isolated;
+  if (isolated) {
+    shareWithToolGroup(spec.borrow_dir);
+    shareWithToolGroup(spec.lens_dir);
+    shareWithToolGroup(spec.session_dir);
+    process.umask(TOOL_UMASK);
+  }
+  return (deps.run ?? onTerminal)({
+    bin: launch.bin,
+    args: launch.argv,
+    cwd: spec.cwd,
+    env: isolated ? toolUidEnv(env) : env,
+  });
+}
+
+// Run only as the entry point, not when a test imports runDebugRoundPane.
+if (process.argv[1]?.endsWith("debugroundpi.js")) {
+  const file = process.argv[2];
+  if (!file) {
+    console.error("usage: debugroundpi <spec-file>");
+    process.exit(2);
+  }
+  void runDebugRoundPane(file).then((code) => process.exit(code));
+}

package/src/diagnostics.ts

@@ -0,0 +1,14 @@
+/** A value named in a diagnostic: bounded, quoted and escaped. */
+export function describeValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value.slice(0, 40));
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  )
+    return String(value);
+  return Array.isArray(value)
+    ? "an array"
+    : `a${typeof value === "object" ? "n" : ""} ${typeof value}`;
+}

package/src/digest.ts

@@ -0,0 +1,183 @@
+// Digest support: the EOD sweep writes digest/<date>.md; the daemon lifts its
+// headline into state/status.json (the status collector's pickup surface).
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sandboxRoot } from "./config.js";
+import { DIGEST_DIR_NAME, digestFiles, zoneDayBounds } from "./eod.js";
+import {
+  cancelCauseLabel,
+  cancellationTotals,
+  roundUsage,
+  tallyCancellations,
+  type CancellationTally,
+  type StateStore,
+} from "./state.js";
+
+export const HEADLINE_MAX = 200;
+
+export function defaultDigestDir(): string {
+  return join(sandboxRoot(), DIGEST_DIR_NAME);
+}
+
+/** Write digest/<date>.md. Returns the path written. */
+export function writeDigest(
+  date: string,
+  content: string,
+  digestDir: string = defaultDigestDir(),
+): string {
+  mkdirSync(digestDir, { recursive: true });
+  const path = digestPath(date, digestDir);
+  writeFileSync(path, content.endsWith("\n") ? content : `${content}\n`);
+  return path;
+}
+
+/** Has the day's digest been written — the exact file `writeDigest` and the
+ * EOD sweep (`digest/{{date}}.md`, cwd = the sandbox root) produce. */
+export function digestWritten(date: string, digestDir: string = defaultDigestDir()): boolean {
+  return existsSync(digestPath(date, digestDir));
+}
+
+/** digest/<date>.md — the one spelling of a day's digest file. */
+function digestPath(date: string, digestDir: string): string {
+  return join(digestDir, `${date}.md`);
+}
+
+/** First non-empty, non-heading line, trimmed and truncated to 200 chars. */
+export function digestHeadline(content: string): string | undefined {
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith("#")) continue;
+    if (/^[-=]{3,}$/.test(line)) continue; // setext underline / rule
+    return line.length > HEADLINE_MAX ? line.slice(0, HEADLINE_MAX) : line;
+  }
+  return undefined;
+}
+
+/** Newest digest/<date>.md file name (lexicographic == chronological). */
+export function latestDigestFile(digestDir: string = defaultDigestDir()): string | undefined {
+  try {
+    const files = digestFiles(readdirSync(digestDir));
+    const last = files[files.length - 1];
+    return last === undefined ? undefined : join(digestDir, last);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Headline of the most recent digest — what the daemon copies into status.json. */
+export function latestDigestHeadline(digestDir: string = defaultDigestDir()): string | undefined {
+  const path = latestDigestFile(digestDir);
+  if (!path) return undefined;
+  try {
+    return digestHeadline(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+// ---- daily usage summary ---------------------------------------------------
+
+export interface DailyUsage {
+  date: string;
+  rounds: number;
+  tokens_in: number;
+  tokens_out: number;
+  /** est_usd is the one spend field (legacy spend_usd folded in). */
+  est_usd: number;
+}
+
+/**
+ * Aggregate one day's measured usage from the rounds table.
+ *
+ * Expired rounds are included: a round that blew its deadline still burned
+ * its tokens, and leaving it out would under-report the day's real cost —
+ * see `StateStore.totalSpend`.
+ */
+export function dailyUsage(store: StateStore, date: string): DailyUsage {
+  const rounds = store.roundsOn(date);
+  const { spend_usd, tokens_in, tokens_out } = roundUsage(rounds);
+  return { date, rounds: rounds.length, tokens_in, tokens_out, est_usd: spend_usd };
+}
+
+/** One digest-ready line, e.g. "usage: 3 rounds — 120000 in / 4000 out tokens — est $1.23". */
+export function usageSummaryLine(usage: DailyUsage): string {
+  return `usage: ${usage.rounds} rounds — ${usage.tokens_in} in / ${usage.tokens_out} out tokens — est $${usage.est_usd.toFixed(2)}`;
+}
+
+// ---- cancellations ---------------------------------------------------------
+
+export interface DailyCancellations {
+  date: string;
+  total: number;
+  /** The subset a human should act on — `LOUD_CANCEL_CAUSES`. */
+  loud: number;
+  by_cause: CancellationTally[];
+}
+
+/**
+ * One day's cancelled rounds, grouped by cause.
+ *
+ * The digest is where a day's shape is written down, so cancellations belong
+ * in it. Grouping is the whole point: most of the volume is the boot orphan
+ * sweep after a redeploy, and a total that lumps it in with a round that
+ * stopped dead says nothing.
+ */
+export function dailyCancellations(
+  store: StateStore,
+  date: string,
+  /** Read `date` as a calendar day in this zone (the EOD timer's). Absent ⇒
+   * the UTC date prefix, as every other `roundsOn` reader does. */
+  timeZone?: string,
+): DailyCancellations {
+  const byCause = tallyCancellations(roundsOnDay(store, date, timeZone));
+  return {
+    date,
+    ...cancellationTotals(byCause),
+    by_cause: byCause,
+  };
+}
+
+/** The rounds started on `date` — a zone-local calendar day when `timeZone`
+ * is given (midnight to midnight on that zone's wall clock, DST-correct). */
+function roundsOnDay(store: StateStore, date: string, timeZone?: string) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!timeZone || !m) return store.roundsOn(date);
+  const { start, end } = zoneDayBounds(Number(m[1]), Number(m[2]), Number(m[3]), timeZone);
+  return store.roundsStartedBetween(start.toISOString(), end.toISOString());
+}
+
+/**
+ * One digest-ready line, e.g.
+ * "cancelled: 4 rounds — stopped dead 1 ⚑, orphan sweep (redeploy) 3".
+ * A quiet day says so explicitly: "cancelled: none" is a fact, and a missing
+ * line would read as "not measured".
+ */
+export function cancellationSummaryLine(c: DailyCancellations): string {
+  if (c.total === 0) return "cancelled: none";
+  const parts = c.by_cause.map(
+    (b) => `${cancelCauseLabel(b.cause)} ${b.count}${b.loud ? " ⚑" : ""}`,
+  );
+  const stoppedDead = c.by_cause
+    .filter((item) => item.cause === "deadline_overrun")
+    .reduce((total, item) => total + item.count, 0);
+  const attention = stoppedDead === c.loud ? "stopped dead" : "need attention";
+  return `cancelled: ${c.total} round${c.total === 1 ? "" : "s"} — ${parts.join(", ")}${
+    c.loud > 0
+      ? ` (${c.loud} ${attention} — worth a look; the orphan sweep is a redeploy artefact and is not)`
+      : ""
+  }`;
+}
+
+/**
+ * Daemon-measured context appended to the EOD sweep prompt.
+ *
+ * The digest itself is written by the sweep's pi session from a frozen seed
+ * prompt the daemon may not edit, so the only render the daemon owns is the
+ * injected prompt, and the cancellation line rides it.
+ */
+export function eodDigestContext(store: StateStore, date: string, timeZone?: string): string {
+  // The EOD timer names a ZONE-LOCAL date; `timeZone` makes the selection
+  // window that same day, not the UTC date prefix.
+  return cancellationSummaryLine(dailyCancellations(store, date, timeZone));
+}