pi-autoresearch-vkf 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.7.0
+
+Turn the live widget into a tabular experiment view and add a one-key browser open.
+
+- The above-editor widget now shows a **table of the recent runs** — truncated
+  7-char commit, a column per recorded metric, status (keep/discard/outcome), and
+  a short description — above run/kept/discarded counts and the memory tally.
+  Columns are data-driven from each run's `METRIC name=value` lines (no metric
+  names are hardcoded; the session's configured metric is pinned first), capped at
+  5 columns for readability — the browser page still has every metric.
+- Experiments now persist **all** parsed metrics and the capturing commit (the
+  working dir's `HEAD` by default), not just the primary metric value.
+- **Open in browser**: press **Ctrl+O** (configurable via
+  `PI_AUTORESEARCH_OPEN_SHORTCUT`) or run **`/research-open`** to launch the live
+  `progress.html` in your default browser. The widget footer advertises the keys.
+
 ## 0.6.0
 
 Add keyless web access so the gather step works on stock pi.

package/README.md

@@ -218,12 +218,14 @@ novelty), then synthesis unlocks the combo.
 
 Three live views, in increasing detail:
 
-- **Widget** (always on, above the editor) — win/loss counts, best metric, memory
-  state tally; refreshes after every tool call.
+- **Widget** (always on, above the editor) — run/kept/discarded counts, best
+  metric, memory tally, and a table of the recent runs (commit · every metric ·
+  status · change); refreshes after every tool call.
 - **Fullscreen overlay** — press **Ctrl+G** (or call `research_status`) for the
   full experiment list, memory lifecycle, and verified claims.
-- **Browser dashboards** — `export_dashboard` writes two self-contained pages to
-  `.autoresearch-vkf/session/`:
+- **Browser dashboards** — press **Ctrl+O** (or run `/research-open`) to open the
+  live progress page in your default browser. `export_dashboard` writes two
+  self-contained pages to `.autoresearch-vkf/session/`:
   - `progress.html` — metric-over-time chart, experiment timeline, and memory
     lifecycle; auto-refreshes so an open tab tracks the run live.
   - `dashboard.html` — the interactive **idea-lineage graph** (paper → claim →
@@ -242,6 +244,8 @@ Three live views, in increasing detail:
   (default `~`, i.e. the bundle lives at `~/.autoresearch-vkf/memory/`).
 - `PI_AUTORESEARCH_SHORTCUT` — key for the fullscreen dashboard (default `ctrl+g`;
   set to `none` to disable).
+- `PI_AUTORESEARCH_OPEN_SHORTCUT` — key to open the progress page in the browser
+  (default `ctrl+o`; set to `none` to disable — `/research-open` still works).
 
 ## Development
 

package/extensions/pi-autoresearch-vkf/dashboard.ts

@@ -15,11 +15,26 @@ import {
   type MemoryState,
 } from "./cards.ts";
 import {
+  experimentMetrics,
   OUTCOME_GLYPH,
   readExperiments,
   summarize,
+  type Experiment,
 } from "./experiments.ts";
 import { hasMemory, sessionPaths } from "./paths.ts";
+import { loadShortcuts } from "./shortcuts.ts";
+
+/** How many recent runs the live widget table shows. */
+const WIDGET_ROWS = 7;
+
+/** A one-line footer advertising the configured shortcuts (the "buttons"). */
+function shortcutHint(): string | undefined {
+  const s = loadShortcuts();
+  const parts: string[] = [];
+  if (s.openBrowser) parts.push(`${s.openBrowser} open in browser`);
+  if (s.fullscreenDashboard) parts.push(`${s.fullscreenDashboard} dashboard`);
+  return parts.length ? parts.join(" · ") : undefined;
+}
 
 const trimNum = (v: number): string =>
   Number.isInteger(v) ? String(v) : String(Number(v.toFixed(4)));
@@ -52,11 +67,74 @@ function memoryLine(root: string): string {
   return `memory: ${c.candidate} candidate · ${verified} verified · ${c.contradicted} contradicted`;
 }
 
+/** keep / discard if decided, otherwise the raw outcome (win/loss/…). */
+function statusLabel(e: Experiment): string {
+  const word = e.kept === true ? "keep" : e.kept === false ? "discard" : e.outcome;
+  return `${OUTCOME_GLYPH[e.outcome]} ${word}`;
+}
+
+/**
+ * Render a fixed-width text table: header row, a rule, then the body rows.
+ * `align[i]` controls per-column justification ("r" right-justifies numbers).
+ */
+function renderTable(headers: string[], rows: string[][], align: ("l" | "r")[]): string[] {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)),
+  );
+  const fmt = (cells: string[]): string =>
+    cells
+      .map((c, i) => (align[i] === "r" ? c.padStart(widths[i]!) : c.padEnd(widths[i]!)))
+      .join("  ")
+      .trimEnd();
+  return [fmt(headers), widths.map((w) => "─".repeat(w)).join("  "), ...rows.map(fmt)];
+}
+
+/** The recent-runs table: commit · each metric · status · description. */
+function runsTable(root: string, metricName: string): string[] {
+  const experiments = readExperiments(sessionPaths(root).experiments);
+  if (experiments.length === 0) return ["(no experiments yet)"];
+
+  const recent = experiments.slice(-WIDGET_ROWS).reverse(); // newest first
+  const perRow = recent.map((e) => experimentMetrics(e, metricName));
+
+  // Metric columns: the primary metric first, then any others seen, sorted.
+  // Cap at 5 columns total to keep the widget readable (the web page has them all).
+  const others = new Set<string>();
+  for (const m of perRow) for (const k of Object.keys(m)) if (k !== metricName) others.add(k);
+  const metricCols = [metricName, ...[...others].sort()].slice(0, 5);
+
+  const headers = ["commit", ...metricCols, "status", "change"];
+  const align: ("l" | "r")[] = ["l", ...metricCols.map((): "r" => "r"), "l", "l"];
+  const rows = recent.map((e, i) => {
+    const m = perRow[i]!;
+    return [
+      e.commit ?? "—",
+      ...metricCols.map((c) => (m[c] === undefined ? "—" : trimNum(m[c]!))),
+      statusLabel(e),
+      e.description.length > 40 ? e.description.slice(0, 39) + "…" : e.description,
+    ];
+  });
+  return renderTable(headers, rows, align);
+}
+
 /** Compact widget shown above the editor. Returns `[]` when there is no session. */
 export function buildWidgetLines(root: string): string[] {
   const config = readConfig(sessionPaths(root).config);
   if (!config) return [];
-  return [`pi-autoresearch-vkf · ${config.name}`, experimentLine(root), memoryLine(root)];
+  const s = summarize(readExperiments(sessionPaths(root).experiments), config.direction);
+  const best = s.best === undefined ? "—" : trimNum(s.best);
+  const runsLine =
+    `runs: ${s.total} · kept: ${s.kept} · discarded: ${s.discarded} · ` +
+    `inconclusive: ${s.inconclusive} · best ${config.metricName}: ${best}`;
+  const hint = shortcutHint();
+  return [
+    `pi-autoresearch-vkf · ${config.name}`,
+    runsLine,
+    memoryLine(root),
+    "",
+    ...runsTable(root, config.metricName),
+    ...(hint ? ["", hint] : []),
+  ];
 }
 
 /** Full status for the fullscreen overlay. */

package/extensions/pi-autoresearch-vkf/experiments.ts

@@ -23,8 +23,12 @@ export interface Experiment {
   description: string;
   /** Claim/idea this experiment tested (a VKF id, e.g. "claim:adagc"). */
   claim_id?: string;
-  /** Metric value obtained. */
+  /** Primary metric value obtained (the session's configured metric). */
   value?: number;
+  /** All `METRIC name=value` pairs recorded for this run, primary metric included. */
+  metrics?: Record<string, number>;
+  /** Short (7-char) commit hash capturing the change, if known. */
+  commit?: string;
   /** Baseline this run was compared against. */
   baseline?: number;
   /** Outcome relative to the baseline and metric direction. */
@@ -92,6 +96,10 @@ export interface ExperimentSummary {
   loss: number;
   inconclusive: number;
   pending: number;
+  /** Runs whose change was kept (`kept === true`). */
+  kept: number;
+  /** Runs whose change was reverted (`kept === false`). */
+  discarded: number;
   /** Best metric value seen, respecting direction. */
   best?: number;
 }
@@ -100,9 +108,19 @@ export function summarize(
   experiments: Experiment[],
   direction: MetricDirection,
 ): ExperimentSummary {
-  const s: ExperimentSummary = { total: experiments.length, win: 0, loss: 0, inconclusive: 0, pending: 0 };
+  const s: ExperimentSummary = {
+    total: experiments.length,
+    win: 0,
+    loss: 0,
+    inconclusive: 0,
+    pending: 0,
+    kept: 0,
+    discarded: 0,
+  };
   for (const e of experiments) {
     s[e.outcome] += 1;
+    if (e.kept === true) s.kept += 1;
+    else if (e.kept === false) s.discarded += 1;
     if (e.value !== undefined) {
       if (s.best === undefined) s.best = e.value;
       else s.best = direction === "higher" ? Math.max(s.best, e.value) : Math.min(s.best, e.value);
@@ -110,3 +128,9 @@ export function summarize(
   }
   return s;
 }
+
+/** The metrics map for a run, falling back to the primary value for older records. */
+export function experimentMetrics(e: Experiment, primaryMetric: string): Record<string, number> {
+  if (e.metrics && Object.keys(e.metrics).length > 0) return e.metrics;
+  return e.value === undefined ? {} : { [primaryMetric]: e.value };
+}

package/extensions/pi-autoresearch-vkf/index.ts

@@ -15,9 +15,10 @@
  * as a VKF *candidate* with a transaction record; promotion to a trusted state is
  * an explicit, audited step — never silent.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
-import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
 import {
@@ -682,7 +683,8 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
     kept: Type.Optional(Type.Boolean({ description: "Whether the change was kept (vs reverted)." })),
     conditions: Type.Optional(Type.String({ description: "Conditions under which this holds (model size, dataset, etc.) — recorded on the memory card." })),
     notes: Type.Optional(Type.String({ description: "Deviations, surprises, next tests." })),
-    commit: Type.Optional(Type.String({ description: "Git commit capturing the change, if any." })),
+    commit: Type.Optional(Type.String({ description: "Git commit capturing the change, if any. Defaults to the current HEAD of the working dir." })),
+    metrics: Type.Optional(Type.Record(Type.String(), Type.Number(), { description: "All `METRIC name=value` pairs from the run (from vkf_run_experiment), so the dashboard can show every metric — not just the primary one." })),
   });
 
   pi.registerTool({
@@ -700,6 +702,11 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
       const baseline = params.baseline ?? config.baseline;
       const outcome: Outcome = params.outcome ?? deriveOutcome(baseline, params.value, config.direction);
 
+      // Record every metric (primary included), and the commit that captured the change.
+      const metrics = { ...(params.metrics ?? {}) };
+      if (metrics[config.metricName] === undefined) metrics[config.metricName] = params.value;
+      const commit = shortCommit(params.commit, config.workingDir ?? root);
+
       const experiments = readExperiments(sp.experiments);
       const seq = String(experiments.length + 1).padStart(3, "0");
       const expEntry: Experiment = {
@@ -707,6 +714,8 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
         description: params.description,
         claim_id: params.claim_id,
         value: params.value,
+        metrics,
+        commit,
         baseline,
         outcome,
         kept: params.kept,
@@ -1007,6 +1016,42 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
     });
   }
 
+  // ── open the live progress page in the default browser ───────────────────────
+  const openProgress = async (ctx: ExtensionContext): Promise<void> => {
+    const root = resolveRoot(ctx);
+    if (!hasSession(root)) {
+      if (ctx.hasUI) ctx.ui.notify("No pi-autoresearch-vkf session in this directory yet.", "warning");
+      return;
+    }
+    // Make sure the file exists/is current before handing it to the browser.
+    const file = writeProgressDashboard(root);
+    if (!file) {
+      if (ctx.hasUI) ctx.ui.notify("Could not generate the progress page.", "error");
+      return;
+    }
+    const [cmd, args] = browserOpenCommand(file);
+    try {
+      await pi.exec(cmd, args, { timeout: 10_000 });
+      if (ctx.hasUI) ctx.ui.notify(`Opened progress page in your browser (${cmd}).`, "info");
+    } catch (e) {
+      if (ctx.hasUI) ctx.ui.notify(`Couldn't launch a browser — open ${file} manually. (${(e as Error).message})`, "error");
+    }
+  };
+
+  if (shortcuts.openBrowser) {
+    pi.registerShortcut(shortcuts.openBrowser, {
+      description: "Open the pi-autoresearch-vkf progress page in the browser",
+      handler: openProgress,
+    });
+  }
+
+  pi.registerCommand("research-open", {
+    description: "Open the pi-autoresearch-vkf progress page in your browser",
+    handler: async (_args, ctx) => {
+      await openProgress(ctx);
+    },
+  });
+
   // ── lifecycle ────────────────────────────────────────────────────────────────
   pi.on("session_start", async (_event, ctx) => {
     refreshWidget(ctx, resolveRoot(ctx));
@@ -1152,6 +1197,37 @@ function writeProgressDashboard(root: string, refreshSeconds?: number): string |
   return sp.progressHtml;
 }
 
+/**
+ * Normalize a commit reference to a 7-char short hash. Uses the explicit value
+ * if given, otherwise best-effort reads the working dir's current HEAD. Returns
+ * `undefined` when there is no resolvable commit (not a repo, git missing, …).
+ */
+function shortCommit(explicit: string | undefined, cwd: string): string | undefined {
+  const trim = (s: string): string | undefined => {
+    const h = s.trim().replace(/^[^0-9a-f]*/i, "");
+    return /^[0-9a-f]{7,}$/i.test(h) ? h.slice(0, 7) : undefined;
+  };
+  if (explicit) return trim(explicit) ?? (explicit.trim().slice(0, 7) || undefined);
+  try {
+    return trim(execFileSync("git", ["rev-parse", "--short=7", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }));
+  } catch {
+    return undefined;
+  }
+}
+
+/** The platform command that opens a file/URL in the user's default browser. */
+function browserOpenCommand(target: string): [string, string[]] {
+  switch (process.platform) {
+    case "darwin":
+      return ["open", [target]];
+    case "win32":
+      // `start` is a cmd builtin; the empty "" is the window-title placeholder.
+      return ["cmd", ["/c", "start", "", target]];
+    default:
+      return ["xdg-open", [target]];
+  }
+}
+
 function writeFileIfAbsent(path: string, contents: string): void {
   if (!existsSync(path)) writeFileSync(path, contents, "utf8");
 }

package/extensions/pi-autoresearch-vkf/shortcuts.ts

@@ -10,13 +10,23 @@ import type { KeyId } from "@earendil-works/pi-tui";
 export interface ShortcutConfig {
   /** Open the fullscreen research dashboard. `undefined` disables it. */
   fullscreenDashboard?: KeyId;
+  /** Open the live progress HTML in the default browser. `undefined` disables it. */
+  openBrowser?: KeyId;
 }
 
 const DEFAULT_FULLSCREEN: KeyId = "ctrl+g";
+const DEFAULT_OPEN_BROWSER: KeyId = "ctrl+o";
+
+function resolve(envVar: string, fallback: KeyId): KeyId | undefined {
+  const override = process.env[envVar]?.trim();
+  if (override === undefined) return fallback;
+  if (override === "" || override.toLowerCase() === "none") return undefined;
+  return override as KeyId;
+}
 
 export function loadShortcuts(): ShortcutConfig {
-  const override = process.env.PI_AUTORESEARCH_SHORTCUT?.trim();
-  if (override === undefined) return { fullscreenDashboard: DEFAULT_FULLSCREEN };
-  if (override === "" || override.toLowerCase() === "none") return {};
-  return { fullscreenDashboard: override as KeyId };
+  return {
+    fullscreenDashboard: resolve("PI_AUTORESEARCH_SHORTCUT", DEFAULT_FULLSCREEN),
+    openBrowser: resolve("PI_AUTORESEARCH_OPEN_SHORTCUT", DEFAULT_OPEN_BROWSER),
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-autoresearch-vkf",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Autoresearch with verifiable long-term scientific memory. A pi extension that gathers literature, stores it as VKF claims, runs experiments, and writes verified results back to a git-native knowledge bundle so future runs build on what was learned instead of rediscovering it.",
   "keywords": [