backpass 0.1.0 → 0.1.1

package/README.md

@@ -15,6 +15,11 @@
   <a href="https://x.com/kunchenguid"
     ><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
   /></a>
+  <a href="https://discord.gg/Wsy2NpnZDu"
+    ><img
+      alt="Discord"
+      src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
+  /></a>
 </p>
 
 <h3 align="center">Gradient descent for your agent memory.</h3>
@@ -226,12 +231,15 @@ the evidence quotes and their sources, a live budget gauge, and ACCEPT / REJECT.
 
 The surface is a static template shipped in the package - the CLI injects one JSON payload,
 so it is instant, deterministic, and identical every run. Nothing there is model-generated.
+It opens in your default browser when one is available; the URL is always printed too, so
+a headless box or `--no-open` just hands you the link.
 
 There is no DEFER button, and it isn't missing: **rejections are remembered.** A rejected
 edit is not proposed again unless materially new evidence arrives.
 
 ```sh
 backpass apply --no-ui     # same decision, in the terminal
+backpass apply --no-open   # print the surface URL, don't launch a browser
 backpass apply --dry-run   # show what would be written
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/apply/browser.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * The review surface URL is always printed as the fallback, so this must never throw or
+ * block: a missing opener, a headless box, or a crashing helper all degrade to "print the
+ * URL only". Returns true when an opener was launched, false when the environment opted
+ * out or had no display.
+ *
+ * Dependencies are injectable so the decision logic is testable without a real browser.
+ *
+ * @typedef {(bin: string, args: string[], options: object) => { on?: Function, unref?: Function }} Spawner
+ * @param {string | null} url
+ * @param {{ platform?: string, env?: Record<string, string | undefined>, spawnFn?: Spawner }} [deps]
+ */
+export function openInBrowser(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
+  if (!url || !/^https?:\/\//.test(url)) return false;
+  if (!canOpenBrowser({ platform, env })) return false;
+
+  const { bin, args } = openerCommand(url, platform);
+  try {
+    const child = spawnFn(bin, args, { stdio: "ignore", detached: true, windowsHide: true });
+    // A missing or failing opener must not surface as an unhandled error.
+    child.on?.("error", () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Headless detection: honor explicit opt-outs, CI, and display-less Linux.
+ * @param {{ platform?: string, env?: Record<string, string | undefined> }} [deps]
+ */
+export function canOpenBrowser({ platform = process.platform, env = process.env } = {}) {
+  if (env.BACKPASS_NO_BROWSER || env.CI) return false;
+  if (platform === "darwin" || platform === "win32") return true;
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+
+/** @returns {{ bin: string, args: string[] }} */
+function openerCommand(url, platform) {
+  if (platform === "darwin") return { bin: "open", args: [url] };
+  // `start` treats its first quoted argument as the window title; pass an empty one.
+  if (platform === "win32") return { bin: "cmd", args: ["/c", "start", "", url] };
+  return { bin: "xdg-open", args: [url] };
+}

package/src/apply/lavish.js

@@ -88,18 +88,37 @@ export async function openApplySurface(file) {
   if (result.code !== 0) {
     throw new UserError(`${LAVISH_BIN} failed to open the apply surface`, result.stderr.trim().slice(0, 400));
   }
-  const url = /(https?:\/\/\S+)/.exec(`${result.stdout}\n${result.stderr}`);
-  return url ? url[1] : null;
+  return extractUrl(`${result.stdout}\n${result.stderr}`);
 }
 
+/**
+ * Pull the session URL out of lavish-axi's output. The CLI prints it YAML-style as
+ * `url: "http://..."`, so a bare `\S+` would swallow the closing quote; stop at any
+ * quote or bracket and drop trailing punctuation.
+ */
+export function extractUrl(text) {
+  const match = /https?:\/\/[^\s"'<>()[\]]+/.exec(text || "");
+  if (!match) return null;
+  return match[0].replace(/[.,;:!?]+$/, "");
+}
+
+/** Breathing room between polls that came back without a decision vector. */
+export const POLL_RETRY_DELAY_MS = 1000;
+
 /**
  * Long-poll for the human's decision vector. `lavish-axi poll` blocks until the reviewer
  * sends feedback, so this is intentionally a foreground wait.
+ *
+ * Feedback that is not a decision vector (a comment, a queued layout report) keeps the
+ * wait going. Each state is announced once: the wait line on entry, and a single note the
+ * first time non-decision feedback arrives - never one line per poll cycle, which on a
+ * chatty surface floods the terminal.
  */
-export async function pollDecisions(file, editIds) {
+export async function pollDecisions(file, editIds, { delayMs = POLL_RETRY_DELAY_MS } = {}) {
   info(
     `${color.dim("waiting for your decisions in the browser (Ctrl-C to abort; nothing is written until you send)")}`,
   );
+  let notedOtherFeedback = false;
 
   for (;;) {
     const result = await runLavish(["poll", file]);
@@ -118,8 +137,14 @@ export async function pollDecisions(file, editIds) {
       warn("review session ended without a decision vector - nothing applied");
       return null;
     }
-    // Feedback that was not a decision vector (a comment, a layout report): keep waiting.
-    info(`${color.dim("received feedback without a decision vector; still waiting")}`);
+
+    if (!notedOtherFeedback) {
+      notedOtherFeedback = true;
+      info(
+        `${color.dim("feedback arrived without a decision vector - click APPLY in the browser and send from the panel; still waiting")}`,
+      );
+    }
+    if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
   }
 }
 

package/src/cli.js

@@ -53,6 +53,7 @@ const OPTIONS = {
 
   "dry-run": { type: "boolean" },
   "no-ui": { type: "boolean" },
+  "no-open": { type: "boolean" },
   "no-auto-agent": { type: "boolean" },
   force: { type: "boolean" },
   limit: { type: "string" },
@@ -114,6 +115,7 @@ BUDGET AND SHAPE
 
 APPLY
   --no-ui                  terminal accept/reject instead of the Lavish surface
+  --no-open                print the review surface URL without opening a browser
   --dry-run                show what would be written, write nothing
   --force                  re-analyze transcripts that already have fresh evidence,
                            and re-probe agents instead of trusting the probe cache

package/src/commands/apply.js

@@ -2,6 +2,7 @@ import { UserError, color, info, json, out, warn } from "../logger.js";
 import { applyDecisions } from "../apply/writer.js";
 import { closeApplySurface, openApplySurface, pollDecisions, renderApplySurface } from "../apply/lavish.js";
 import { reviewInTerminal } from "../apply/terminal.js";
+import { openInBrowser } from "../apply/browser.js";
 import { budgetBar, formatTokens } from "../tokens.js";
 
 /**
@@ -45,6 +46,8 @@ export async function cmdApply(ctx) {
     surfaceFile = renderApplySurface(proposal, config.state, ctx.version);
     const url = await openApplySurface(surfaceFile);
     info(`${color.cyan("·")} review surface: ${url || surfaceFile}`);
+    // Best effort: the printed URL above is the fallback when nothing opens.
+    if (!ctx.flags["no-open"]) openInBrowser(url);
     decisions = await pollDecisions(surfaceFile, editIds);
   }