bladebro 4.5.1 → 4.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bladebro",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "description": "Stealthy and efficient agentic browser driver for AI agents. Few tools, full control, real stealth, max token efficiency.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,9 +37,6 @@
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
-    },
-    "typebox": {
-      "optional": true
     }
   },
   "bin": {
@@ -56,11 +53,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "bladebro-linux-x64": "4.5.1",
-    "bladebro-linux-arm64": "4.5.1",
-    "bladebro-darwin-x64": "4.5.1",
-    "bladebro-darwin-arm64": "4.5.1",
-    "bladebro-windows-x64": "4.5.1"
+    "bladebro-linux-x64": "4.5.2",
+    "bladebro-linux-arm64": "4.5.2",
+    "bladebro-darwin-x64": "4.5.2",
+    "bladebro-darwin-arm64": "4.5.2",
+    "bladebro-windows-x64": "4.5.2"
   },
   "engines": {
     "node": ">=14"

package/pi-extension.ts

@@ -1,37 +1,25 @@
 /**
- * Bladebro pi extension — native pi agent integration.
+ * Bladebro pi extension — the bladebro MCP server, registered with pi.
  *
- * Spawns the bladebro binary as a stdio MCP subprocess, discovers tools
- * via `tools/list`, and registers them natively with pi via
- * `pi.registerTool()`. The agent gets 5 first-class tools (act, see,
- * state, run, vision) with no adapter, no config files, no proxy.
+ * This is the whole extension. It resolves the bladebro binary this package
+ * installed and hands it to pi as a stdio MCP server; pi's own MCP client does
+ * everything else — spawn, handshake, tool-call proxying, shutdown. The five
+ * tools arrive with the binary's full definitions (descriptions, schemas and
+ * the server's `initialize` instructions), so no meaning is copied here and
+ * there is nothing that can drift when the Rust side changes.
  *
- * Tool definitions come from the binary at startup — zero maintenance.
- * When the Rust tool defs change, the extension picks them up automatically.
+ * `exposure: "direct"` declares the tools to the model like any other pi tool,
+ * and the session waits for this server before the first prompt. The timeout
+ * covers the driver's long operations (run/batch/collect), not pi's 60s default.
  *
- * Lifecycle:
- * - session_start → spawn binary, MCP handshake, tools/list, register tools
- * - tool call     → proxy to binary via tools/call, return result
- * - session_shutdown → kill binary (which kills Chrome)
- *
- * Chrome launches lazily inside the binary (first tools/call only).
- * The binary process itself starts in milliseconds.
- *
- * Auto-adapt: tool descriptions, schemas, new tools, removed tools,
- * changed parameters — all fetched from the binary at session start.
- * The extension never hardcodes tool definitions.
+ * No protocol code, no copied schemas, no rendering: a troubleshooting step
+ * belongs at the source — the binary — never in this shim.
  */
-
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { Text } from "@earendil-works/pi-tui";
-import { StringDecoder } from "node:string_decoder";
-import { spawn, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-// ── Binary resolution ─────────────────────────────────────────────────
-
+/** npm platform packages → the binary each one carries. */
 const PLATFORM_MAP: Record<string, string> = {
   "linux-x64": "bladebro-linux-x64",
   "linux-arm64": "bladebro-linux-arm64",
@@ -40,482 +28,36 @@ const PLATFORM_MAP: Record<string, string> = {
   "win32-x64": "bladebro-windows-x64",
 };
 
+/** Absolute path of this platform's binary, or null when it is not installed. */
 function resolveBinary(): string | null {
-  const key = `${process.platform}-${process.arch}`;
-  const pkgName = PLATFORM_MAP[key];
+  const pkgName = PLATFORM_MAP[`${process.platform}-${process.arch}`];
   if (!pkgName) return null;
   try {
     const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
     const pkgJson = require(pkgJsonPath);
-    const binName = pkgJson.main || "bladebro";
-    const binPath = join(dirname(pkgJsonPath), binName);
+    const binPath = join(dirname(pkgJsonPath), pkgJson.main || "bladebro");
     return existsSync(binPath) ? binPath : null;
   } catch {
     return null;
   }
 }
 
-// ── TUI rendering helpers ─────────────────────────────────────────────
-
-/** Extract text from MCP tool result content blocks. */
-function getResultText(result: any): string {
-  if (!result?.content) return "";
-  return result.content
-    .filter((c: any) => c.type === "text")
-    .map((c: any) => c.text)
-    .join("\n");
-}
-
-/** Format the `act` tool call display. */
-function formatActCall(args: any, theme: any): string {
-  const action = args.action || "?";
-  const bold = (s: string) => theme.bold(s);
-  const accent = (s: string) => theme.fg("accent", s);
-  const muted = (s: string) => theme.fg("muted", s);
-  const title = bold("act");
-
-  switch (action) {
-    case "navigate": {
-      const url = args.url || "";
-      return `${title} ${accent("navigate")} ${muted("→")} ${accent(url)}`;
-    }
-    case "click": {
-      const target = args.ref || args.text || args.label || "";
-      return `${title} ${accent("click")} ${muted(target)}`;
-    }
-    case "type": {
-      const target = args.ref || args.label || "";
-      const text = args.text || "";
-      const press = args.press ? ` ${muted("+ " + args.press)}` : "";
-      return `${title} ${accent("type")} ${muted(target ? `${target} ` : "")}${muted(`"${text}"`)}${press}`;
-    }
-    case "scroll": {
-      const dy = args.dy || 0;
-      const dx = args.dx || 0;
-      const arrow = dy > 0 ? "↓" : dy < 0 ? "↑" : dx > 0 ? "→" : "←";
-      const mag = Math.abs(dy || dx);
-      return `${title} ${accent("scroll")} ${muted(`${arrow}${mag}`)}`;
-    }
-    case "fill": {
-      const n = args.fields?.length || 0;
-      const submit = args.submit ? ` ${muted("+ submit")}` : "";
-      return `${title} ${accent("fill")} ${muted(`(${n} field${n !== 1 ? "s" : ""})`)}${submit}`;
-    }
-    case "batch": {
-      const n = args.steps?.length || 0;
-      return `${title} ${accent("batch")} ${muted(`(${n} step${n !== 1 ? "s" : ""})`)}`;
-    }
-    case "hover": {
-      const target = args.ref || args.text || args.label || "";
-      return `${title} ${accent("hover")} ${muted(target)}`;
-    }
-    case "press": {
-      return `${title} ${accent("press")} ${muted(args.key || "")}`;
-    }
-    case "eval": {
-      const js = (args.js || "").slice(0, 50);
-      return `${title} ${accent("eval")} ${muted(`"${js}${js.length >= 50 ? "…" : ""}"`)}`;
-    }
-    case "wait": {
-      const cond = args.condition || "settle";
-      const t = args.timeout || 10;
-      return `${title} ${accent("wait")} ${muted(`${cond} (${t}s)`)}`;
-    }
-    case "read": {
-      return `${title} ${accent("read")} ${muted(args.ref || "")}`;
-    }
-    case "back": return `${title} ${accent("back")}`;
-    case "forward": return `${title} ${accent("forward")}`;
-    case "reload": return `${title} ${accent("reload")}`;
-    case "select": {
-      const target = args.ref || "";
-      const opt = args.option || "";
-      return `${title} ${accent("select")} ${muted(`${target} "${opt}"`)}`;
-    }
-    case "pdf": return `${title} ${accent("pdf")}`;
-    case "download": return `${title} ${accent("download")}`;
-    case "collect": return `${title} ${accent("collect")}`;
-    case "clear": return `${title} ${accent("clear")} ${muted(args.ref || "")}`;
-    case "upload": return `${title} ${accent("upload")} ${muted(args.ref || "")}`;
-    default: return `${title} ${accent(action)}`;
-  }
-}
-
-/** Format the `see` tool call display. */
-function formatSeeCall(args: any, theme: any): string {
-  const bold = (s: string) => theme.bold(s);
-  const accent = (s: string) => theme.fg("accent", s);
-  const muted = (s: string) => theme.fg("muted", s);
-  const title = bold("see");
-
-  const mode = args.mode;
-  if (mode === "content") return `${title} ${accent("content")}`;
-  if (mode === "outline") return `${title} ${accent("outline")}`;
-  if (mode === "model") return `${title} ${accent("model")}`;
-
-  const find = args.find;
-  if (find) return `${title} ${accent("find")} ${muted(`"${find}"`)}`;
-
-  const extract = args.extract;
-  if (extract) return `${title} ${accent(`extract=${extract}`)}`;
-
-  const scope = args.scope;
-  if (scope) return `${title} ${accent("scope")} ${muted(scope)}`;
-
-  const filter = args.filter;
-  if (filter) return `${title} ${accent("model")} ${muted(`[${filter}]`)}`;
-
-  const logs = args.logs;
-  if (logs) return `${title} ${accent("logs")} ${muted(logs)}`;
-
-  return `${title} ${accent("model")}`;
-}
-
-/** Format the `state` tool call display. */
-function formatStateCall(args: any, theme: any): string {
-  const bold = (s: string) => theme.bold(s);
-  const accent = (s: string) => theme.fg("accent", s);
-  const muted = (s: string) => theme.fg("muted", s);
-  const title = bold("state");
-
-  const op = args.op || "?";
-  const extra = args.url || args.name || "";
-  return `${title} ${accent(op)}${extra ? ` ${muted(extra)}` : ""}`;
-}
-
-/** Format the `run` tool call display. */
-function formatRunCall(args: any, theme: any): string {
-  const bold = (s: string) => theme.bold(s);
-  const title = bold("run");
-  return title;
-}
-
-/** Format the `vision` tool call display. */
-function formatVisionCall(args: any, theme: any): string {
-  const bold = (s: string) => theme.bold(s);
-  const title = bold("vision");
-  return title;
-}
-
-/** Format tool result for display. */
-function formatResult(text: string, expanded: boolean, isError: boolean, theme: any): string {
-  const out = (s: string) => theme.fg("toolOutput", s);
-  const warn = (s: string) => theme.fg("warning", s);
-  const muted = (s: string) => theme.fg("muted", s);
-  const accent = (s: string) => theme.fg("accent", s);
-
-  if (!text) return muted("(no output)");
-
-  const lines = text.split("\n");
-
-  if (isError) {
-    // Error: show all lines in warning color
-    return lines.map((l) => warn(l)).join("\n");
-  }
-
-  // Truncate if not expanded
-  const maxLines = expanded ? 9999 : 15;
-  const visible = lines.slice(0, maxLines);
-  const skipped = lines.length - visible.length;
-
-  const formatted = visible.map((line) => {
-    // Outcome lines → accent
-    if (line.startsWith("outcome:")) return accent(line);
-    // Warning lines (⚠) → warning color
-    if (line.includes("\u{26a0}")) return warn(line);
-    // Verdict lines with arrow → toolOutput
-    return out(line);
-  });
-
-  if (skipped > 0) {
-    formatted.push(muted(`  … ${skipped} more line${skipped !== 1 ? "s" : ""} (expand to view)`));
-  }
-
-  return formatted.join("\n");
-}
-
-// ── Minimal MCP stdio client ──────────────────────────────────────────
-
-interface PendingReq {
-  resolve: (v: any) => void;
-  reject: (e: any) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
-
-class McpStdio {
-  private proc: ChildProcess | null = null;
-  private nextId = 1;
-  private pending = new Map<number, PendingReq>();
-  private buffer = "";
-  private alive = false;
-  private decoder = new StringDecoder("utf8");
-
-  start(binaryPath: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-      this.buffer = "";
-      this.decoder = new StringDecoder("utf8");
-      const proc = this.proc = spawn(binaryPath, ["mcp"], {
-        stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env },
-      });
-
-      const onExit = () => {
-        if (this.proc !== proc) return;
-        this.alive = false;
-        this.proc = null;
-        for (const [, p] of this.pending) {
-          clearTimeout(p.timer);
-          p.reject(new Error("bladebro process exited"));
-        }
-        this.pending.clear();
-      };
-
-      proc.on("exit", onExit);
-      proc.stdin!.on("error", (err) => {
-        onExit();
-        proc.kill();
-        reject(err);
-      });
-      this.proc.on("error", (err) => {
-        onExit();
-        reject(err);
-      });
-
-      this.proc.stdout!.on("data", (data: Buffer) => this.onData(data));
-      this.proc.stderr!.on("data", (data: Buffer) => {
-        const text = data.toString();
-        for (const line of text.split("\n")) {
-          const trimmed = line.trim();
-          if (!trimmed) continue;
-          if (/error|panic|fatal|warn|fail/i.test(trimmed)) {
-            process.stderr.write(line + "\n");
-          }
-        }
-      });
-
-      this.request("initialize", {
-        protocolVersion: "2025-06-18",
-        capabilities: {},
-        clientInfo: { name: "pi-bladebro", version: "1.0.0" },
-      }, 10000)
-        .then(() => {
-          this.notify("notifications/initialized", {});
-          this.alive = true;
-          resolve();
-        })
-        .catch((err) => {
-          onExit();
-          proc.kill();
-          reject(err);
-        });
-    });
-  }
-
-  private onData(data: Buffer): void {
-    this.buffer += this.decoder.write(data);
-    if (Buffer.byteLength(this.buffer, "utf8") > 64 * 1024 * 1024) {
-      for (const [, p] of this.pending) {
-        clearTimeout(p.timer);
-        p.reject(new Error("bladebro MCP response exceeds 64 MiB"));
-      }
-      this.pending.clear();
-      this.proc?.kill();
-      return;
-    }
-    let idx: number;
-    while ((idx = this.buffer.indexOf("\n")) >= 0) {
-      const line = this.buffer.slice(0, idx).trim();
-      this.buffer = this.buffer.slice(idx + 1);
-      if (line) this.onMessage(line);
-    }
-  }
-
-  private onMessage(line: string): void {
-    let msg: any;
-    try { msg = JSON.parse(line); } catch {
-      for (const [, p] of this.pending) {
-        clearTimeout(p.timer);
-        p.reject(new Error("Invalid MCP JSON from bladebro"));
-      }
-      this.pending.clear();
-      this.proc?.kill();
-      return;
-    }
-    if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
-      this.proc?.kill();
-      return;
-    }
-    if (msg.id !== undefined && this.pending.has(msg.id)) {
-      const entry = this.pending.get(msg.id)!;
-      this.pending.delete(msg.id);
-      clearTimeout(entry.timer);
-      if (msg.error) entry.reject(new Error(msg.error.message || "MCP request failed"));
-      else if (!("result" in msg)) entry.reject(new Error("MCP response missing result"));
-      else entry.resolve(msg.result);
-    }
-  }
-
-  private request(method: string, params: any, timeoutMs = 180000): Promise<any> {
-    return new Promise((resolve, reject) => {
-      if (!this.proc || this.proc.exitCode !== null || this.proc.signalCode !== null || !this.proc.stdin?.writable) {
-        reject(new Error("bladebro process is not running"));
-        return;
-      }
-      const id = this.nextId++;
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`MCP timeout: ${method} (${timeoutMs}ms)`));
-      }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer });
-      const msg = JSON.stringify({ jsonrpc: "2.0", id, method, params });
-      this.proc?.stdin?.write(msg + "\n");
-    });
-  }
-
-  private notify(method: string, params: any): void {
-    const msg = JSON.stringify({ jsonrpc: "2.0", method, params });
-    this.proc?.stdin?.write(msg + "\n");
-  }
-
-  async listTools(): Promise<any[]> {
-    const result = await this.request("tools/list", {}, 10000);
-    return result.tools || [];
-  }
-
-  async callTool(name: string, args: any): Promise<any> {
-    return this.request("tools/call", { name, arguments: args });
-  }
-
-  isAlive(): boolean { return this.alive && this.proc !== null; }
-
-  async stop(): Promise<void> {
-    const proc = this.proc;
-    if (!proc) return;
-    this.alive = false;
-    for (const [, p] of this.pending) {
-      clearTimeout(p.timer);
-      p.reject(new Error("bladebro session stopped"));
-    }
-    this.pending.clear();
-    if (proc.exitCode === null && proc.signalCode === null) {
-      await new Promise<void>((resolve) => {
-        const t = setTimeout(() => { proc.kill("SIGKILL"); resolve(); }, 5000);
-        proc.once("exit", () => { clearTimeout(t); resolve(); });
-        proc.stdin?.end();
-        proc.kill("SIGTERM");
-      });
-    }
-    if (this.proc === proc) this.proc = null;
-  }
-}
-
-// ── Extension ─────────────────────────────────────────────────────────
-
-const TOOL_FORMATTERS: Record<string, (args: any, theme: any) => string> = {
-  act: formatActCall,
-  see: formatSeeCall,
-  state: formatStateCall,
-  run: formatRunCall,
-  vision: formatVisionCall,
-};
-
 export default function bladebroExtension(pi: ExtensionAPI) {
-  let client: McpStdio | null = null;
-  let binaryPath: string | null = null;
-  let restartPromise: Promise<void> | null = null;
+  const key = `${process.platform}-${process.arch}`;
+  const binary = resolveBinary();
 
-  async function ensureClient(): Promise<McpStdio> {
-    if (client?.isAlive()) return client;
-    if (restartPromise) {
-      await restartPromise;
-      return client!;
-    }
-    if (!binaryPath) throw new Error("Bladebro binary not available");
-    const p = (async () => {
-      const c = new McpStdio();
-      await c.start(binaryPath!);
-      client = c;
-    })();
-    restartPromise = p;
-    try {
-      await p;
-    } finally {
-      restartPromise = null;
-    }
-    return client!;
+  if (!binary || typeof pi.registerMcpServer !== "function") {
+    const why = !binary
+      ? `no binary for ${key} — run: npm install bladebro`
+      : "this pi build has no MCP registration API — update pi";
+    pi.on("session_start", (_event, ctx) => ctx.ui.notify(`Bladebro: ${why}`, "error"));
+    return;
   }
 
-  pi.on("session_start", async (_event, ctx) => {
-    binaryPath = resolveBinary();
-    if (!binaryPath) {
-      const key = `${process.platform}-${process.arch}`;
-      ctx.ui.notify(
-        `Bladebro: no binary for ${key}. Run: npm install bladebro`,
-        "error",
-      );
-      return;
-    }
-
-    try {
-      await ensureClient();
-    } catch (err: any) {
-      ctx.ui.notify(`Bladebro: failed to start: ${err.message}`, "error");
-      client = null;
-      return;
-    }
-
-    let tools: any[];
-    try {
-      tools = await client!.listTools();
-    } catch (err: any) {
-      ctx.ui.notify(`Bladebro: tools/list failed: ${err.message}`, "error");
-      return;
-    }
-
-    for (const tool of tools) {
-      const formatter = TOOL_FORMATTERS[tool.name];
-
-      pi.registerTool({
-        name: tool.name,
-        label: tool.name,
-        description: tool.description,
-        parameters: Type.Unsafe(tool.inputSchema),
-        renderShell: "default",
-        renderCall(args: any, theme: any, context: any) {
-          const text = new Text("", 0, 0);
-          if (formatter) {
-            text.setText(formatter(args, theme));
-          } else {
-            text.setText(theme.bold(tool.name));
-          }
-          return text;
-        },
-        renderResult(result: any, options: any, theme: any, context: any) {
-          const text = context.lastComponent ?? new Text("", 0, 0);
-          const body = getResultText(result);
-          text.setText(formatResult(body, options.expanded, result.isError, theme));
-          return text;
-        },
-        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-          const c = await ensureClient();
-          if (_signal?.aborted) throw new Error("Bladebro tool call cancelled before dispatch");
-          const result = await c.callTool(tool.name, params);
-          return {
-            content: result.content || [],
-            details: {},
-            isError: result.isError || false,
-          };
-        },
-      });
-    }
-
-    ctx.ui.notify(`Bladebro ready (${tools.length} tools)`, "info");
-  });
-
-  pi.on("session_shutdown", async () => {
-    if (client) {
-      await client.stop();
-      client = null;
-    }
+  pi.registerMcpServer("bladebro", {
+    command: binary,
+    args: ["mcp"],
+    exposure: "direct",
+    timeout: 180,
   });
 }

package/skills/bladebro/SKILL.md

@@ -1,45 +1,12 @@
 ---
 name: bladebro
-description: Drive a real browser with the bladebro tools (act, see, state, run, vision) — navigating sites, clicking, typing, filling forms, logging in, reading pages, extracting lists/search results/products, and screenshotting. Use whenever a task needs a live web page rather than a fetch or an API.
+description: Optional house rules for bladebro. Bladebro itself needs no skill — the package registers its MCP server with pi and the five tools arrive complete. Add your own preferences here if you want the agent to use bladebro in a particular way.
 ---
 
-# Bladebro — driving a real browser
+# No skill added by the user.
 
-`act` interacts, `see` reads, `state` manages cookies/tabs/sessions, `run` runs step batches with branching, `vision` screenshots. One long-lived Chrome; refs (`e1`, `e2`, …) address elements.
+Bladebro works without this file: the npm package registers the bladebro MCP server with pi, and the tools come with their full definitions — descriptions, schemas, and the driver's own `initialize` instructions. Nothing needs repeating here.
 
-## The loop
+This file exists so you can tell your agent to use bladebro a specific way — sites to prefer, extraction shapes, pacing, things to avoid. Whatever you write below is read as guidance.
 
-1. `act { "action": "navigate", "url": "…" }` — returns refs + a content preview; often enough to act on without a separate read.
-2. Address by text when you can: `act { "action": "click", "text": "Sign in" }` — no `see` needed. Labels work for form fields.
-3. Refs are page-scoped and short-lived: after a navigation or tab switch use the fresh refs from THAT response. Within a page they self-heal.
-4. Every action returns an observation (verdict + what changed). A `see` after acting is usually unnecessary — read the observation.
-5. Collapse round-trips: `fill` for whole forms, `batch`/`run` for sequences (branching, loops, inline reads).
-
-## Reading
-
-- List, search, product, profile pages: `see { "extract": "auto" }` FIRST — one call returns structured items.
-- Articles and docs: `see { "mode": "content" }` (clean markdown). Cheapest "what's here": `mode: "outline"`.
-- One value or a custom shape: `act { "action": "eval", "js": "…" }`.
-- Machine-readable output: add `format: "json"` — the result is pure JSON. `act eval` in text mode is one line, `result: <compact JSON>`; if the script returned a string containing JSON, a note says so (parse the value once more).
-
-## Trust what the result tells you
-
-- `page_total` with `partial`/`paged` in an extract: the page claims more results than the DOM holds — follow the pagination, or `act { "action": "collect", "url": "…" }` to scroll and dedupe the whole feed.
-- `sponsored: true` items are paid placements — flagged per item and counted in the envelope, left in page order.
-- A note that the URL's range filter does not match the page's own prices means the site ignored its filter — treat those results as unfiltered.
-- `duplicates_removed` / `redirects_unwrapped` explain what was cleaned up; item URLs are canonical, not tracking interstitials.
-- Oversized payloads are written to an artifact file and read back with `see { "artifact": "…" }` (paged). Nothing is truncated silently — a `… (+N chars truncated)` marker always says so.
-
-## Forms, sequences, dialogs
-
-- Whole forms in ONE call: `act { "action": "fill", "fields": [ { "label": "Email", "text": "…" } ], "submit": "Sign in" }`.
-- Multi-step or branching work: `run { "steps": [ … ] }` — `if`/`while`, inline `see`/`extract` steps, one round-trip.
-- A click that dispatches but changes nothing reads "clicked (no observable DOM change)" — it fired ONCE; verify state before re-clicking. "no-effect" means nothing was dispatched, so a retry is safe there.
-- Dialogs (confirm/prompt/alert): arm `act { "action": "dialog", "expect": "confirm" }` BEFORE the action that triggers it.
-
-## When something goes wrong
-
-- Errors carry the current page state — read it instead of guessing, and never blind-retry a submit.
-- `trusted:false` = text landed through an untrusted fallback; treat it as not typed. `degraded:true` = the browser is unhealthy (retry or restart it) — not a page problem.
-- An unknown action name answers with the valid list and the correct step.
-- CAPTCHA / bot walls: the verdict says `blocked:` and the remediation ladder is in the ambient notes. Do not try to solve image grids.
+<!-- Add your rules below this line. -->