@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/extensions/tui-view.ts

@@ -0,0 +1,489 @@
+// tui-view — the companion's read-only window onto the operator's view: what
+// is on the operator's screen right now, and the derived state behind it.
+//
+// The one rule, and it is structural: these tools read state the TUI has
+// already fetched. They are never a fetcher.
+//
+// Every value they return was produced by the TUI, on the operator's machine,
+// with the operator's ssh credential, for the operator's own screen, and
+// written to a file on a bind mount. Nothing here opens a socket, spawns a
+// process, or asks the TUI to go and get anything. That is not a matter of taste: the TUI's reach is
+// real (`src/tui/remote.ts` runs `ssh <host> …`, and the deploy tab can run
+// `deploy.sh sync`), and the companion's own reach (the companion boundary) is
+// its own ssh access and guarded tools, not the TUI's. A `tui_*` tool that
+// could trigger a fetch would let the companion make the TUI act on the VM on
+// its behalf — laundering the TUI's access through a read verb. So:
+//
+//   * the only imports are `node:fs` (read) and `node:path` — no
+//     `node:child_process`, no `node:net/http/https`, no `fetch`, no import of
+//     anything under `src/`, above all not `remote.ts`;
+//   * no tool takes a parameter. There is no host to name, no command to pass,
+//     no path to traverse — the tools read two fixed filenames under
+//     `$QCR_FEED_DIR` and nothing else;
+//   * a missing or stale file is answered as such ("the TUI is closed"), never
+//     refreshed. Staleness is information; a refresh would be reach.
+//
+// `tests/tui-view.test.ts` pins all three.
+//
+// The companion writing to the TUI is a different channel
+// (`/alerts/tui-actions/`, src/tui/actions.ts) with its own validation and its
+// own whitelist. Nothing here is a second one: no tool writes anything, anywhere.
+//
+// pi is a dependency of this repo, so the pi API is typechecked against its own
+// declarations; what a live session does with it stays VERIFY-ON-PIN.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionFactory,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** The two files these tools read. Fixed names — never a tool parameter. */
+export const VIEW_FILE = "view.json";
+export const SCREEN_FILE = "screen.txt";
+
+/** Past this, an answer says stale before it says anything else. The TUI
+ * republishes on every repaint and every 3 s poll, so anything older than this
+ * means it is closed, suspended or wedged. */
+export const STALE_AFTER_MS = 30_000;
+
+/** The tools this extension registers. Exported so the test can assert the
+ * surface is exactly these, all reads. */
+export const TOOL_NAMES = ["tui_screen", "tui_deploy", "tui_board"] as const;
+
+export function resolveFeedDir(env: NodeJS.ProcessEnv, cwd: string): string {
+  const explicit = env.QCR_FEED_DIR?.trim();
+  if (explicit) return explicit;
+  const root = env.QCR_ROOT?.trim() || cwd;
+  return join(root, "state", "companion", "feed");
+}
+
+export interface ReadResult {
+  ok: boolean;
+  body?: string;
+  /** Modification time of the file, ms — the fallback freshness stamp. */
+  mtimeMs?: number;
+  error?: string;
+}
+
+/** Read one published file. The only I/O in this module, and it is a read. */
+export function readFeedFile(dir: string, name: string): ReadResult {
+  try {
+    const path = join(dir, name);
+    const body = readFileSync(path, "utf8");
+    return { ok: true, body, mtimeMs: statSync(path).mtimeMs };
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException)?.code;
+    if (code !== undefined && code !== "ENOENT") {
+      return {
+        ok: false,
+        error:
+          `The TUI's ${name} could not be read (${code}: ${join(dir, name)}). ` +
+          `The feed mount is present but unreadable; these tools only read what the TUI already wrote.`,
+      };
+    }
+    return {
+      ok: false,
+      error:
+        `The TUI has published no ${name}. It is probably not running — and I cannot fetch it: ` +
+        `these tools only read what the TUI already wrote. Ask the owner whether their TUI is up.`,
+    };
+  }
+}
+
+/** One line stamping how old the answer is. Unknown age is reported as
+ * unknown; it is never quietly treated as fresh. */
+export function freshness(writtenAt: string | undefined, now: Date, mtimeMs?: number): string {
+  const t = writtenAt ? Date.parse(writtenAt) : mtimeMs !== undefined ? mtimeMs : Number.NaN;
+  if (!Number.isFinite(t)) return "Age unknown — treat as possibly stale.";
+  const ageMs = now.getTime() - t;
+  const stamp = new Date(t).toISOString();
+  const ageS = Math.max(0, Math.round(ageMs / 1000));
+  if (ageMs > STALE_AFTER_MS) {
+    return (
+      `STALE — written ${stamp}, ${ageS}s ago. The TUI is closed, suspended or wedged. ` +
+      `This is what WAS on screen, not what is. Say so rather than presenting it as current.`
+    );
+  }
+  return `Live — as of ${stamp} (${ageS}s ago).`;
+}
+
+const text = (body: string): AgentToolResult<undefined> => ({
+  content: [{ type: "text", text: body }],
+  details: undefined,
+});
+
+/** No parameters, by design (see the header). VERIFY-ON-PIN: a plain JSON
+ * Schema object where the vendored fork passes a TypeBox schema. */
+const NO_PARAMS = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+  required: [] as string[],
+};
+
+interface ViewJson {
+  written_at?: string;
+  deploy?: Record<string, unknown>;
+  board?: Record<string, unknown>;
+  selected?: Record<string, unknown>;
+  pane?: Record<string, unknown>;
+  screen?: Record<string, unknown>;
+  notice?: string;
+  /** status.json `memory` as the TUI read it; `null` = unread. */
+  memory?: Record<string, unknown> | null;
+  /** status.json `daemon` as the TUI read it; `null` = unread. */
+  daemon?: Record<string, unknown> | null;
+  /** The archiver's `qcr status` line and what in it needs a person, as the
+   * TUI rendered them; `null` = unread. */
+  archive?: { line?: unknown; attention?: unknown } | null;
+}
+
+function loadView(dir: string): { view?: ViewJson; mtimeMs?: number; error?: string } {
+  const raw = readFeedFile(dir, VIEW_FILE);
+  if (!raw.ok) return { error: raw.error };
+  try {
+    return { view: JSON.parse(raw.body ?? "{}") as ViewJson, mtimeMs: raw.mtimeMs };
+  } catch {
+    return {
+      error: `${VIEW_FILE} is unreadable (torn or malformed JSON). Nothing about the TUI's view can be said from here.`,
+    };
+  }
+}
+
+/**
+ * One `label: value` line, or nothing when the field is genuinely absent.
+ *
+ * `null` is not absent — it is the producer saying "I could not read this".
+ * A dropped line would make an unread working tree or an unproven dry-run
+ * flag look like nothing worth mentioning, and the companion would answer
+ * with a quiet all-clear built from data the TUI never had. An explicit
+ * unknown is the whole point of the null.
+ */
+function fmt(label: string, value: unknown): string | undefined {
+  if (value === null) return `${label}: UNKNOWN (the TUI has not been able to read this)`;
+  if (value === undefined || value === "") return undefined;
+  return `${label}: ${typeof value === "object" ? JSON.stringify(value) : String(value)}`;
+}
+
+/** The VM's release stamp as `view.json` carries it: its fields, the string
+ * `"absent"` for a VM that runs no release image (never deployed to, or still
+ * on the legacy layout), the string `"unparseable"` for a `qcr-update status`
+ * report the TUI read but that names no build stamp, or `null` for a read that
+ * failed. Four different sentences — a VM with no release image, a VM whose
+ * report is unusable and a VM that could not be asked must not read alike. */
+function deployedLines(value: unknown): Array<string | undefined> {
+  if (value === "absent") {
+    return [
+      "VM is running: no release image — the VM was never deployed to, or is still on the legacy layout (the first release starts a release image)",
+    ];
+  }
+  if (value === "unparseable") {
+    return [
+      "VM is running: UNKNOWN — qcr-update status was read but names no build stamp (unusable report; retry the deploy tab)",
+    ];
+  }
+  if (typeof value !== "object" || value === null) return [fmt("VM is running", null)];
+  const marker = value as { sha?: unknown; at?: unknown; mode?: unknown };
+  return [
+    fmt("VM is running", marker.sha),
+    fmt("deployed at", marker.at),
+    fmt("deploy mode", marker.mode),
+  ];
+}
+
+/** `""` is docker's own answer — it listed no container by that name — and
+ * is said as such rather than dropped like a blank field. */
+function containerLine(status: unknown): string | undefined {
+  if (status === "")
+    return "container: docker lists no container by that name (never created, or removed)";
+  return fmt("container", status);
+}
+
+// ---- the three answers ------------------------------------------------------
+
+export function screenAnswer(dir: string, now: Date): string {
+  const meta = loadView(dir);
+  const raw = readFeedFile(dir, SCREEN_FILE);
+  if (!raw.ok) return raw.error ?? "no screen";
+  const head = freshness(meta.view?.written_at, now, raw.mtimeMs);
+  const body = raw.body ?? "";
+  if (body.trim() === "") {
+    return `${head}\nThe TUI painted no composed frame (a tab that renders as plain text, or it is suspended).`;
+  }
+  return `${head}\nThis is the owner's screen, exactly as painted (ANSI stripped).\n\n${body}`;
+}
+
+export function deployAnswer(dir: string, now: Date): string {
+  const { view, mtimeMs, error } = loadView(dir);
+  if (error !== undefined || !view) return error ?? "no view";
+  const head = freshness(view.written_at, now, mtimeMs);
+  const d = view.deploy ?? {};
+  if (d.loaded !== true) {
+    return `${head}\nThe deploy tab has not loaded its state yet (nobody has opened it this run), so the deployed commit is unknown.`;
+  }
+  const commits = Array.isArray(d.pending_commits) ? (d.pending_commits as string[]) : [];
+  const lines = [
+    ...deployedLines(d.deployed),
+    // A key the producer did not write at all is read as unread, never as
+    // absent: once the tab has loaded, every one of these is a fact the TUI
+    // either fetched or failed to fetch.
+    fmt("local HEAD", d.head ?? null),
+    fmt("dirty files in the local checkout", d.dirty_files),
+    fmt("commits waiting to ship", d.pending_commit_count),
+    fmt("release version the waiting commits are counted up to", d.target_version ?? null),
+    fmt("that version's revision", d.target_rev ?? null),
+    fmt("diffstat", d.diffstat_summary),
+    containerLine(d.container_status ?? null),
+    // Whether the VM runs this machine's config home and profiles.
+    fmt("config home vs the VM", d.config_home ?? null),
+    fmt("run in flight", d.run),
+  ].filter((l): l is string => l !== undefined);
+  const tail =
+    commits.length > 0 ? `\n\nPending commits (newest first):\n${commits.join("\n")}` : "";
+  return `${head}\n${lines.join("\n")}${tail}`;
+}
+
+/**
+ * Reviewer memory as one sentence: its health state, since when, whether it
+ * serves search, the incident if one is open, each credential's verdict and
+ * the day's EOD curation. `null` (the TUI could not read it, or the daemon
+ * reports no block) is an explicit UNKNOWN — a dropped line would hide dead
+ * memory behind a quiet surface. A view written before the field existed
+ * (`undefined`) says so too.
+ */
+export function memoryLine(value: unknown): string {
+  if (value === undefined)
+    return "reviewer memory: UNKNOWN (this TUI build publishes no memory field)";
+  if (value === null || typeof value !== "object")
+    return "reviewer memory: UNKNOWN (the TUI has not been able to read it — the daemon reported no memory block, or there is no snapshot)";
+  const m = value as {
+    enabled?: unknown;
+    state?: unknown;
+    since?: unknown;
+    incident?: { kind?: unknown; since?: unknown } | null;
+    credentials?: Record<string, { result?: unknown; status?: unknown; code?: unknown } | null>;
+    last_error?: { op?: unknown; code?: unknown; message?: unknown } | null;
+    serving?: { ok?: unknown; since?: unknown; reason?: unknown } | null;
+    curation?: {
+      state?: unknown;
+      day?: unknown;
+      offered?: unknown;
+      not_persisted?: unknown;
+      unresolved?: unknown;
+      balance?: { look_for?: unknown; dont_raise?: unknown } | null;
+    } | null;
+  };
+  if (m.enabled === false) return "reviewer memory: not monitored on this daemon";
+  // A scalar as text; anything else (a torn or foreign shape) as the fallback.
+  const txt = (v: unknown, fallback = "?"): string =>
+    typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : fallback;
+  const cred = (name: string, label: string): string => {
+    const c = m.credentials?.[name];
+    if (!c) return `${label} not probed yet`;
+    const status = typeof c.status === "number" && c.status > 0 ? ` ${c.status}` : "";
+    return `${label} ${txt(c.result)}${c.result === "ok" || c.result === "absent" ? "" : `${status} ${txt(c.code, "")}`.trimEnd()}`;
+  };
+  const state = txt(m.state, "unknown").toUpperCase();
+  const incident =
+    m.incident && typeof m.incident.since === "string"
+      ? `; incident (${txt(m.incident.kind)}) open since ${m.incident.since}`
+      : "";
+  const err =
+    m.last_error && m.state !== "healthy"
+      ? `; last error ${txt(m.last_error.op)}: ${txt(m.last_error.code)} ${txt(m.last_error.message, "").slice(0, 120)}`
+      : "";
+  // Memory that authenticates but cannot search says so.
+  const serving =
+    m.serving && (m.serving.ok === false || typeof m.serving.since === "string")
+      ? `; NOT serving search${typeof m.serving.since === "string" ? ` since ${m.serving.since}` : ""}${typeof m.serving.reason === "string" ? ` — ${m.serving.reason.slice(0, 160)}` : ""}`
+      : "";
+  // The day's EOD curation — loud when it did not reach memory,
+  // UNKNOWN when the daemon could not read its ledger; the lessons' balance.
+  const c = m.curation;
+  // Older failures nothing has made good yet ride beside the reported day.
+  const earlierDays =
+    c && Array.isArray(c.unresolved)
+      ? new Set(
+          c.unresolved
+            .map((u: unknown) => (u && typeof u === "object" ? (u as { day?: unknown }).day : null))
+            .filter((d: unknown): d is string => typeof d === "string" && d !== c.day),
+        ).size
+      : 0;
+  const earlier =
+    earlierDays > 0
+      ? ` (+${earlierDays} earlier unresolved day${earlierDays === 1 ? "" : "s"})`
+      : "";
+  const curation =
+    c === null
+      ? "; EOD curation UNKNOWN"
+      : c && typeof c === "object"
+        ? `${
+            c.state === "missing"
+              ? `; EOD CURATION MISSING for ${txt(c.day)} (${txt(c.offered)} candidates, no receipt)${earlier}`
+              : c.state === "not_persisted"
+                ? `; EOD LESSONS NOT PERSISTED for ${txt(c.day)} (${txt(c.not_persisted)})${earlier}`
+                : `; EOD curation ${txt(c.state)}`
+          }${c.balance ? `; lessons look-for:dont-raise ${txt(c.balance.look_for)}:${txt(c.balance.dont_raise)}` : ""}`
+        : "";
+  return `reviewer memory: ${state} since ${txt(m.since)}${incident}${serving}; ${cred("daemon", "daemon key")}; ${cred("sessions", "sessions' key")}${err}${curation}`;
+}
+
+/**
+ * The daemon's own event loop as one sentence: ok / STALLED (with
+ * the cause its evidence names — the container's throttling, the daemon's own
+ * CPU across the stall, or neither) / UNKNOWN, its p50/p99/max
+ * over the window, and the container's throttling beside it. `null` (the TUI
+ * could not read it, or the daemon reports no block) is an explicit UNKNOWN,
+ * so a stalled daemon is never hidden behind a dropped line. A view written
+ * before the field existed says so too.
+ */
+export function daemonLoadLine(value: unknown): string {
+  if (value === undefined)
+    return "daemon event loop: UNKNOWN (this TUI build publishes no daemon field)";
+  if (value === null || typeof value !== "object")
+    return "daemon event loop: UNKNOWN (the TUI has not been able to read it — the daemon reported no event-loop block, or there is no snapshot)";
+  const d = value as {
+    event_loop?: {
+      state?: unknown;
+      since?: unknown;
+      p50_ms?: unknown;
+      p99_ms?: unknown;
+      max_ms?: unknown;
+      covered_s?: unknown;
+      longest_stall?: { ms?: unknown; ended_at?: unknown } | null;
+      stall?: { detail?: unknown } | null;
+    } | null;
+    cpu?: {
+      state?: unknown;
+      reason?: unknown;
+      throttled_ratio?: unknown;
+      throttled_s?: unknown;
+      window_s?: unknown;
+    } | null;
+  };
+  const num = (v: unknown): string =>
+    typeof v === "number" && Number.isFinite(v) ? String(v) : "?";
+  const e = d.event_loop;
+  const c = d.cpu;
+  const cpu =
+    c && c.state === "measured"
+      ? `container CPU throttled in ${typeof c.throttled_ratio === "number" ? Math.round(c.throttled_ratio * 100) : "?"}% of CFS periods (${num(c.throttled_s)}s) over ${num(c.window_s)}s`
+      : `container CPU throttling UNKNOWN${c && typeof c.reason === "string" ? ` (${c.reason.slice(0, 160)})` : ""}`;
+  if (!e || typeof e !== "object")
+    return `daemon event loop: UNKNOWN (the block carries no event_loop); ${cpu}`;
+  const figures = `p50 ${num(e.p50_ms)}ms, p99 ${num(e.p99_ms)}ms, max ${num(e.max_ms)}ms over ${num(e.covered_s)}s`;
+  const longest =
+    e.longest_stall && typeof e.longest_stall.ended_at === "string"
+      ? `; longest ${num(e.longest_stall.ms)}ms ended ${e.longest_stall.ended_at}`
+      : "";
+  if (e.state === "stalled")
+    return `daemon event loop: STALLED since ${typeof e.since === "string" ? e.since : "?"} — ${e.stall && typeof e.stall.detail === "string" ? e.stall.detail.slice(0, 400) : figures}${longest}`;
+  if (e.state === "ok") return `daemon event loop: ok — ${figures}${longest}; ${cpu}`;
+  return `daemon event loop: UNKNOWN (not measured yet)${longest}; ${cpu}`;
+}
+
+/**
+ * The archiver as one line (docs/archiving.md §11): the line the TUI
+ * rendered from status.json, with what needs a person first. Absent (an older
+ * TUI) or `null` (the TUI has no snapshot) is an explicit UNKNOWN — a dropped
+ * line would read as "nothing to report".
+ */
+export function archiveLine(value: unknown): string {
+  if (value === undefined) return "archive: UNKNOWN (this TUI build publishes no archive field)";
+  if (value === null || typeof value !== "object")
+    return "archive: UNKNOWN (the TUI has not been able to read it — there is no snapshot)";
+  const a = value as { line?: unknown; attention?: unknown };
+  const line =
+    typeof a.line === "string" ? a.line.slice(0, 600) : "archive: UNKNOWN (an unreadable line)";
+  const attention = Array.isArray(a.attention)
+    ? a.attention.filter((x): x is string => typeof x === "string")
+    : [];
+  return attention.length > 0 ? `archive NEEDS ATTENTION: ${attention.join(" · ")}\n${line}` : line;
+}
+
+export function boardAnswer(dir: string, now: Date): string {
+  const { view, mtimeMs, error } = loadView(dir);
+  if (error !== undefined || !view) return error ?? "no view";
+  const head = freshness(view.written_at, now, mtimeMs);
+  const b = view.board ?? {};
+  const lines = [
+    fmt("tab on screen", (view.screen ?? {}).tab),
+    fmt("daemon health", b.health),
+    fmt("dry run", b.dry_run),
+    fmt("open PRs", b.total),
+    fmt("by state", b.by_state),
+    fmt("rounds running", b.running_rounds),
+    fmt("max concurrent rounds", b.max_concurrent_rounds),
+    fmt("spend today (USD)", b.today_spend_usd),
+    fmt("snapshot written at", b.snapshot_written_at),
+    memoryLine(view.memory),
+    daemonLoadLine(view.daemon),
+    archiveLine(view.archive),
+    fmt("selected PR", view.selected),
+    fmt("pi pane", view.pane),
+    fmt("notice line", view.notice),
+  ].filter((l): l is string => l !== undefined);
+  return (
+    `${head}\n${lines.join("\n")}\n\n` +
+    `This is a projection, not the whole board — /feed/snapshot.json has every PR row.`
+  );
+}
+
+// ---- registration -----------------------------------------------------------
+
+export function toolDefinitions(dir: string, now: () => Date = () => new Date()): ToolDefinition[] {
+  const READ_ONLY =
+    "Read-only: it reads a file the TUI already wrote; it cannot fetch anything, and it changes nothing.";
+  return [
+    {
+      name: "tui_screen",
+      label: "TUI screen",
+      description:
+        "What is on the owner's qcr TUI screen right now — the last painted frame as plain text, including the companion column. " +
+        "Use it when he says 'this one' / 'what I'm looking at', or to read pi output he can see. " +
+        READ_ONLY,
+      promptSnippet: "Read the operator's TUI screen as plain text",
+      parameters: NO_PARAMS,
+      execute: () => Promise.resolve(text(screenAnswer(dir, now()))),
+    },
+    {
+      name: "tui_deploy",
+      label: "TUI deploy state",
+      description:
+        "What commit the VM is actually running (its BUILD_SHA), local HEAD, whether the checkout is dirty, and the commits waiting to ship. " +
+        READ_ONLY,
+      promptSnippet: "Read the deployed commit and what is waiting to ship",
+      parameters: NO_PARAMS,
+      execute: () => Promise.resolve(text(deployAnswer(dir, now()))),
+    },
+    {
+      name: "tui_board",
+      label: "TUI board state",
+      description:
+        "A small projection of the board behind the screen: tab, daemon health, reviewer-memory health, the daemon's event-loop lag and CPU throttling, the archiver's status (and what in it needs a person), PR counts by state, rounds running, today's spend, and the PR the owner has selected. " +
+        READ_ONLY,
+      promptSnippet: "Read the board summary and the selected PR",
+      parameters: NO_PARAMS,
+      execute: () => Promise.resolve(text(boardAnswer(dir, now()))),
+    },
+  ];
+}
+
+export interface TuiViewConfig {
+  /** The directory the TUI's feed writer fills (view.json, screen.txt). */
+  feedDir: string;
+}
+
+/** The factory that registers the `tui_*` tools over `feedDir`. The env shim
+ * is extensions/cli/tui-view.ts. */
+export function createTuiView(config: TuiViewConfig): ExtensionFactory {
+  return (pi: ExtensionAPI): void => {
+    // A pi without registerTool registers nothing and says nothing — the
+    // companion must still start (it never wedges).
+    if (typeof pi.registerTool !== "function") return;
+    for (const def of toolDefinitions(config.feedDir)) pi.registerTool(def);
+  };
+}