pi-autoresearch-vkf 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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.
+
+- New tools **`WebSearch`** (DuckDuckGo HTML, no API key) and **`WebFetch`**
+  (JSON/text verbatim, HTML reduced to readable text). The pi host ships no web
+  tools, but `autoresearch-vkf-knowledge-gather` assumed they existed — the agent
+  reported it had no web search. These supply the named tools the skill already
+  references, against the free literature APIs (arXiv, OpenAlex, Crossref,
+  Semantic Scholar). No session required; no setup or keys.
+- Tool names match Claude-Code casing so `pi-ai`'s tool-name table keeps prompt
+  caching aligned. `WebSearch` degrades gracefully to a WebFetch-an-API hint when
+  the search backend rate-limits or changes layout.
+
+Make the browser progress dashboard automatic and live.
+
+- `progress.html` is now written on `init_research` (so it exists from iteration
+  zero) and refreshed after every `remember_claim`, `verify_claim`, and
+  `vkf_log_experiment`. Previously it was only written when the agent explicitly
+  called `export_dashboard`, which most runs never did — so the dashboard was
+  effectively never created and never updated during a run.
+- The page already meta-refreshes itself, so an open browser tab now tracks the
+  loop live with no manual step. `export_dashboard` is now for the heavier
+  vkf-CLI idea-lineage graph (`dashboard.html`), a custom refresh interval, or
+  opening the page in a browser.
+
 ## 0.5.2
 
 Prefixed all skill names with `autoresearch-vkf-` to avoid namespace conflicts

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 {
@@ -136,6 +137,9 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
       const fresh = scaffoldMemoryBundle(root, params.name, config.memoryProfile);
       appendLog(sp.log, { event: "init", name: config.name, goal: config.goal });
 
+      // Create the progress dashboard up front so it exists from iteration zero;
+      // it then refreshes automatically as experiments are logged.
+      writeProgressDashboard(root);
       refreshWidget(ctx, root);
       return textResult(
         [
@@ -249,6 +253,7 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
       });
       appendLog(sp.log, { event: "remember", claim_id: claim.id, paper_id: paperId });
 
+      writeProgressDashboard(root);
       refreshWidget(ctx, root);
       return textResult(
         [
@@ -319,6 +324,7 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
       });
       appendLog(sp.log, { event: "verify", claim_id: params.id, decision: params.decision });
 
+      writeProgressDashboard(root);
       refreshWidget(ctx, root);
       return textResult(
         [
@@ -677,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({
@@ -695,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 = {
@@ -702,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,
@@ -774,6 +788,8 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
         writeConfig(sp.config, config);
       }
 
+      // Refresh the browser progress page so an open tab tracks the loop live.
+      writeProgressDashboard(root);
       refreshWidget(ctx, root);
       const summary = summarize(readExperiments(sp.experiments), config.direction);
       return textResult(
@@ -853,7 +869,7 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
     name: "export_dashboard",
     label: "Export dashboard",
     description:
-      "Write browser dashboards for the run: a self-contained progress page (.auto/progress.html — metric-over-time chart, experiment timeline, memory lifecycle) and, via the vkf CLI, the interactive idea-lineage graph (.auto/dashboard.html — paper → claim → experiment). Re-run any time to refresh; open progress.html in a browser to watch progress as it goes.",
+      "Build the interactive idea-lineage graph (.autoresearch-vkf/session/dashboard.html — paper → claim → experiment, via the vkf CLI) and refresh the progress page. The progress page (progress.html — metric-over-time chart, experiment timeline, memory lifecycle) is also written automatically on init and after each remember/verify/experiment, and meta-refreshes itself, so an open browser tab tracks the loop live without re-running this. Use this tool for the lineage graph, a custom refresh interval, or to open the page in a browser.",
     parameters: ExportParams,
     async execute(_id, params: Static<typeof ExportParams>, _signal, _onUpdate, ctx): Promise<AgentToolResult<{ progress: string; lineage?: string }>> {
       const root = resolveRoot(ctx);
@@ -861,42 +877,9 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
       requireSession(root);
       const config = readConfig(sp.config)!;
 
-      // Progress page (self-contained, no CLI needed).
-      const experiments: ProgressExperiment[] = readExperiments(sp.experiments).map((e) => ({
-        id: e.id,
-        description: e.description,
-        value: e.value,
-        outcome: e.outcome,
-        kept: e.kept,
-        claim_id: e.claim_id,
-        ts: e.ts,
-      }));
-      const memory: Record<string, number> = Object.fromEntries(MEMORY_STATES.map((s) => [s, 0]));
-      for (const c of listCards(root, { type: "claim" })) {
-        const st = c.meta["memory_state"] as MemoryState | undefined;
-        if (st && st in memory) memory[st]! += 1;
-      }
-      const claims = listCards(root, { bucket: "verified", type: "claim" })
-        .slice(0, 12)
-        .map((c) => ({
-          title: String(c.meta["title"] ?? c.meta["id"]),
-          confidence: String(c.meta["confidence"] ?? "—"),
-          state: String(c.meta["memory_state"] ?? "—"),
-        }));
-
-      const progressHtml = renderProgressHtml({
-        name: config.name,
-        goal: config.goal,
-        metricName: config.metricName,
-        direction: config.direction,
-        baseline: config.baseline,
-        experiments,
-        memory,
-        claims,
-        generatedAt: new Date().toISOString(),
-        refreshSeconds: params.refresh_seconds,
-      });
-      writeFileSync(sp.progressHtml, progressHtml, "utf8");
+      // Progress page (self-contained, no CLI needed). Same generator the loop
+      // calls automatically on init and after each experiment.
+      writeProgressDashboard(root, params.refresh_seconds);
 
       // Lineage graph via the vkf CLI (best-effort).
       const lineage = vkf.html(memoryPaths(root).dir, sp.dashboardHtml, `Research memory — ${config.name}`);
@@ -942,6 +925,75 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
     },
   });
 
+  // ── WebSearch ────────────────────────────────────────────────────────────────
+  // The pi host ships no web tools, but the gather skill needs them. These two
+  // tools give the agent keyless web access: WebSearch (DuckDuckGo HTML) to
+  // discover sources, WebFetch to read pages and hit free APIs (arXiv, OpenAlex,
+  // Crossref, Semantic Scholar). Named to match the skill text and pi-ai's
+  // Claude-Code tool-name table so prompt caching stays aligned.
+  const WebSearchParams = Type.Object({
+    query: Type.String({ description: "Search query. Prefer the mechanism of the problem over bare keywords." }),
+    max_results: Type.Optional(Type.Number({ description: "Max results to return (default 8, capped at 25)." })),
+  });
+
+  pi.registerTool({
+    name: "WebSearch",
+    label: "Web search",
+    description:
+      "Search the web with no API key (via DuckDuckGo) and return result titles, URLs, and snippets. Discovery step for the autoresearch gather skill — then read the hits with WebFetch.",
+    parameters: WebSearchParams,
+    async execute(_id, params: Static<typeof WebSearchParams>, signal): Promise<AgentToolResult<{ results: WebSearchHit[] }>> {
+      const limit = Math.max(1, Math.min(params.max_results ?? 8, 25));
+      const endpoint = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(params.query)}`;
+      let fetched: FetchedText;
+      try {
+        fetched = await fetchText(endpoint, signal ?? undefined, 20_000);
+      } catch (e) {
+        return textResult(`Web search failed: ${(e as Error).message}`, { results: [] });
+      }
+      const results = parseDdgResults(fetched.body, limit);
+      if (results.length === 0) {
+        return textResult(
+          `No results parsed for "${params.query}" (HTTP ${fetched.status}). The search backend may be rate-limiting; fall back to WebFetch against a known API (arXiv, OpenAlex, Crossref, Semantic Scholar).`,
+          { results: [] },
+        );
+      }
+      const body = results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`).join("\n\n");
+      return textResult(truncate(body), { results });
+    },
+  });
+
+  // ── WebFetch ─────────────────────────────────────────────────────────────────
+  const WebFetchParams = Type.Object({
+    url: Type.String({ description: "http(s) URL to fetch. JSON/text is returned verbatim; HTML is reduced to readable text." }),
+    max_chars: Type.Optional(Type.Number({ description: `Max characters of content to return (default ${MAX_OUTPUT_CHARS}).` })),
+  });
+
+  pi.registerTool({
+    name: "WebFetch",
+    label: "Web fetch",
+    description:
+      "Fetch a URL with no API key — JSON/text verbatim, HTML reduced to readable text. Use for the free literature APIs (arXiv, OpenAlex, Crossref, Semantic Scholar) and for reading pages found via WebSearch.",
+    parameters: WebFetchParams,
+    async execute(_id, params: Static<typeof WebFetchParams>, signal): Promise<AgentToolResult<{ status: number; url: string; content_type: string }>> {
+      if (!/^https?:\/\//i.test(params.url)) {
+        return textResult(`Refusing to fetch non-http(s) URL: ${params.url}`, { status: 0, url: params.url, content_type: "" });
+      }
+      let fetched: FetchedText;
+      try {
+        fetched = await fetchText(params.url, signal ?? undefined, 30_000);
+      } catch (e) {
+        return textResult(`Fetch failed for ${params.url}: ${(e as Error).message}`, { status: 0, url: params.url, content_type: "" });
+      }
+      const isHtml = /text\/html|application\/xhtml/i.test(fetched.contentType);
+      const text = isHtml ? htmlToText(fetched.body) : fetched.body;
+      const cap = Math.max(500, params.max_chars ?? MAX_OUTPUT_CHARS);
+      const capped = text.length <= cap ? text : text.slice(0, cap) + `\n…[truncated ${text.length - cap} chars]`;
+      const header = `GET ${fetched.finalUrl}\n(HTTP ${fetched.status} · ${fetched.contentType || "unknown"} · ${isHtml ? "html→text" : "raw"})\n\n`;
+      return textResult(header + capped, { status: fetched.status, url: fetched.finalUrl, content_type: fetched.contentType });
+    },
+  });
+
   // ── shortcut: fullscreen dashboard ───────────────────────────────────────────
   const shortcuts = loadShortcuts();
   if (shortcuts.fullscreenDashboard) {
@@ -964,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));
@@ -974,8 +1062,172 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
   });
 }
 
+// ── web helpers ───────────────────────────────────────────────────────────────
+
+const WEB_USER_AGENT = "pi-autoresearch-vkf (+https://github.com/EricJahns/pi-autoresearch-vkf)";
+
+interface FetchedText {
+  status: number;
+  contentType: string;
+  body: string;
+  finalUrl: string;
+}
+
+interface WebSearchHit {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/** Fetch a URL as text, following redirects, aborting on the tool signal or timeout. */
+async function fetchText(url: string, signal: AbortSignal | undefined, timeoutMs: number): Promise<FetchedText> {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const composed = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  const res = await fetch(url, {
+    redirect: "follow",
+    signal: composed,
+    headers: { "user-agent": WEB_USER_AGENT, accept: "*/*" },
+  });
+  const body = await res.text();
+  return { status: res.status, contentType: res.headers.get("content-type") ?? "", body, finalUrl: res.url || url };
+}
+
+/** Reduce an HTML document to readable plain text (best-effort, no DOM). */
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|li|tr|h[1-6]|section|article)\s*>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#0*39;|&#x27;/gi, "'")
+    .replace(/&#(\d+);/g, (_m, n) => String.fromCodePoint(Number(n)))
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/[ \t]{2,}/g, " ")
+    .trim();
+}
+
+/** DuckDuckGo HTML wraps result links as //duckduckgo.com/l/?uddg=<encoded>. Unwrap them. */
+function decodeDdgHref(href: string): string {
+  const m = href.match(/[?&]uddg=([^&]+)/);
+  if (m && m[1]) {
+    try {
+      return decodeURIComponent(m[1]);
+    } catch {
+      /* fall through to raw href */
+    }
+  }
+  return href.startsWith("//") ? "https:" + href : href;
+}
+
+/** Parse titles/urls/snippets out of a DuckDuckGo HTML results page. */
+function parseDdgResults(html: string, limit: number): WebSearchHit[] {
+  const snippets: string[] = [];
+  const snippetRe = /<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+  let s: RegExpExecArray | null;
+  while ((s = snippetRe.exec(html)) !== null) snippets.push(htmlToText(s[1] ?? ""));
+
+  const hits: WebSearchHit[] = [];
+  const linkRe = /<a[^>]+class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+  let m: RegExpExecArray | null;
+  let i = 0;
+  while ((m = linkRe.exec(html)) !== null && hits.length < limit) {
+    hits.push({ title: htmlToText(m[2] ?? ""), url: decodeDdgHref(m[1] ?? ""), snippet: snippets[i] ?? "" });
+    i++;
+  }
+  return hits;
+}
+
 // ── helpers ───────────────────────────────────────────────────────────────────
 
+/**
+ * (Re)generate the self-contained progress dashboard (progress.html) from the
+ * current session + memory state. Pure-JS and cheap (no CLI), so it is safe to
+ * call on every state change — an open browser tab meta-refreshes itself live.
+ * No-op (returns undefined) when there is no session/config yet. The interactive
+ * idea-lineage graph (dashboard.html) is heavier and stays in export_dashboard.
+ */
+function writeProgressDashboard(root: string, refreshSeconds?: number): string | undefined {
+  const sp = sessionPaths(root);
+  const config = readConfig(sp.config);
+  if (!config) return undefined;
+
+  const experiments: ProgressExperiment[] = readExperiments(sp.experiments).map((e) => ({
+    id: e.id,
+    description: e.description,
+    value: e.value,
+    outcome: e.outcome,
+    kept: e.kept,
+    claim_id: e.claim_id,
+    ts: e.ts,
+  }));
+  const memory: Record<string, number> = Object.fromEntries(MEMORY_STATES.map((s) => [s, 0]));
+  for (const c of listCards(root, { type: "claim" })) {
+    const st = c.meta["memory_state"] as MemoryState | undefined;
+    if (st && st in memory) memory[st]! += 1;
+  }
+  const claims = listCards(root, { bucket: "verified", type: "claim" })
+    .slice(0, 12)
+    .map((c) => ({
+      title: String(c.meta["title"] ?? c.meta["id"]),
+      confidence: String(c.meta["confidence"] ?? "—"),
+      state: String(c.meta["memory_state"] ?? "—"),
+    }));
+
+  const html = renderProgressHtml({
+    name: config.name,
+    goal: config.goal,
+    metricName: config.metricName,
+    direction: config.direction,
+    baseline: config.baseline,
+    experiments,
+    memory,
+    claims,
+    generatedAt: new Date().toISOString(),
+    refreshSeconds,
+  });
+  writeFileSync(sp.progressHtml, html, "utf8");
+  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.5.2",
+  "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": [