pi-browser-harness 0.12.0 → 0.14.0

package/src/profile/bind.ts

@@ -1,20 +1,37 @@
 import type { BrowserClient } from "../client";
 import type { ResultOf } from "../cdp/commands";
 import { type CdpError, cdpError } from "../cdp/errors";
-import { type Result, err, ok } from "../util/result";
-import { detectRunningBrowser, resolveBrowserExecutable } from "./browser-process";
-import { openProfileWindow } from "./launch";
+import { borrowSession } from "../cdp/target-factory";
+import { type Result, err, map, ok, unwrapOr } from "../util/result";
+import { sleep as sleepMs } from "../util/sleep";
+import { detectRunningBrowser, resolveBrowserExecutable, type RunningBrowser } from "./browser-process";
+import { openProfileWindow, type ProfileWindowHandle, type ProfileWindowRequest } from "./launch";
 import type { ProfilePin } from "./store";
 
 const SEED_DEADLINE_MS = 15_000;
 const SEED_POLL_MS = 500;
 
+// The machine-facing steps of seeding: process detection, executable lookup, the window launch
+// and the sentinel poll's clock. Each defaults to the real implementation.
+export type SeedDeps = {
+  readonly detectRunningBrowser?: (preferUserDataDir?: string) => Promise<RunningBrowser>;
+  readonly resolveBrowserExecutable?: (running?: RunningBrowser) => Promise<string | undefined>;
+  readonly openProfileWindow?: (req: ProfileWindowRequest) => Promise<Result<ProfileWindowHandle, string>>;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly now?: () => number;
+  readonly deadlineMs?: number;
+  readonly pollMs?: number;
+};
+
+
 type PageTarget = ResultOf<"Target.getTargets">["targetInfos"][number];
 
 const pageTargets = async (client: BrowserClient): Promise<ReadonlyArray<PageTarget>> => {
   const r = await client.session().callBrowser("Target.getTargets");
-  if (!r.success) return [];
-  return r.data.targetInfos.filter((t) => t.type === "page");
+  return unwrapOr(
+    map(r, (d): ReadonlyArray<PageTarget> => d.targetInfos.filter((t) => t.type === "page")),
+    [],
+  );
 };
 
 const manualFallbackHint = (pin: ProfilePin): string =>
@@ -24,7 +41,16 @@ const manualFallbackHint = (pin: ProfilePin): string =>
 export const seedProfileWindow = async (
   client: BrowserClient,
   pin: ProfilePin,
+  deps: SeedDeps = {},
 ): Promise<Result<string, CdpError>> => {
+  const detect = deps.detectRunningBrowser ?? detectRunningBrowser;
+  const resolveExe = deps.resolveBrowserExecutable ?? resolveBrowserExecutable;
+  const launch = deps.openProfileWindow ?? openProfileWindow;
+  const sleep = deps.sleep ?? sleepMs;
+  const now = deps.now ?? Date.now;
+  const deadlineMs = deps.deadlineMs ?? SEED_DEADLINE_MS;
+  const pollMs = deps.pollMs ?? SEED_POLL_MS;
+
   const connectedDir = client.userDataDir();
   if (connectedDir && connectedDir !== pin.userDataDir) {
     return err(cdpError(
@@ -35,8 +61,8 @@ export const seedProfileWindow = async (
   }
 
   const targetUserDataDir = connectedDir ?? pin.userDataDir;
-  const running = await detectRunningBrowser(targetUserDataDir);
-  const exePath = await resolveBrowserExecutable(running);
+  const running = await detect(targetUserDataDir);
+  const exePath = await resolveExe(running);
   if (!exePath) {
     return err(cdpError(
       "discovery_failed",
@@ -44,7 +70,7 @@ export const seedProfileWindow = async (
     ));
   }
 
-  const launched = await openProfileWindow({
+  const launched = await launch({
     exePath,
     profileDir: pin.profileDir,
     // ProcessSingleton keys on the user-data-dir path, so forward only the value the running browser reports: a reconstructed one may differ by case and start a SECOND browser.
@@ -55,10 +81,10 @@ export const seedProfileWindow = async (
   }
 
   const { sentinelUrl, cleanup, kill } = launched.data;
-  const deadline = Date.now() + SEED_DEADLINE_MS;
+  const deadline = now() + deadlineMs;
   let seed: PageTarget | undefined;
-  while (Date.now() < deadline && !seed) {
-    await new Promise((r) => setTimeout(r, SEED_POLL_MS));
+  while (now() < deadline && !seed) {
+    await sleep(pollMs);
     seed = (await pageTargets(client)).find((t) => t.url === sentinelUrl);
   }
 
@@ -80,9 +106,14 @@ export const seedProfileWindow = async (
   const win = await client.session().windowId(seed.targetId);
   if (win.success) ownership.setHarnessWindowId(win.data);
 
-  const attached = await client.session().attach(seed.targetId);
-  if (attached.success) {
-    await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, attached.data);
+  // Clears the sentinel URL from the seed tab. The session is borrowed and released so an untracked attach never outlives this call.
+  const borrowed = await borrowSession(client, seed.targetId);
+  if (borrowed.success) {
+    try {
+      await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, borrowed.data.sessionId);
+    } finally {
+      await borrowed.data.release();
+    }
   }
   await cleanup();
 

package/src/profile/browser-process.ts

@@ -23,6 +23,31 @@ const LINUX_COMMS: ReadonlyArray<string> = [
   "chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge",
   "google-chrome", "brave", "brave-browser",
 ];
+
+// The kernel stores a process name in TASK_COMM_LEN (16) bytes, so `ps -o comm=` prints at most 15
+// characters: "chromium-browser" shows up as "chromium-browse" and would never match in full.
+const LINUX_COMM_MAX = 15;
+
+export const isLinuxBrowserComm = (comm: string): boolean => {
+  const lower = comm.toLowerCase();
+  return LINUX_COMMS.some((name) => name.slice(0, LINUX_COMM_MAX) === lower);
+};
+
+// /proc/<pid>/cmdline separates arguments with NUL, which keeps a space inside argv[0] or a
+// --user-data-dir value intact. A string without NULs (a test fixture, or a zombie's empty
+// cmdline) falls back to whitespace splitting.
+export const parseProcCmdline = (raw: string): ReadonlyArray<string> => {
+  const argv = raw.includes("\0") ? raw.split("\0") : raw.trim().split(/\s+/);
+  return argv.filter((arg) => arg.length > 0);
+};
+
+const USER_DATA_DIR_FLAG = "--user-data-dir=";
+
+export const userDataDirFromArgv = (argv: ReadonlyArray<string>): string | undefined => {
+  const flag = argv.find((arg) => arg.startsWith(USER_DATA_DIR_FLAG));
+  const value = flag?.slice(USER_DATA_DIR_FLAG.length);
+  return value !== undefined && value.length > 0 ? value : undefined;
+};
 const MAC_BROWSER_NAMES: ReadonlyArray<string> = [
   "google chrome", "chromium", "microsoft edge", "brave browser",
 ];
@@ -116,7 +141,7 @@ const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
       .flatMap((line) => {
         const [pid, comm] = line.split(/\s+/, 2);
         if (!pid || !comm) return [];
-        return LINUX_COMMS.includes(comm.toLowerCase()) ? [pid] : [];
+        return isLinuxBrowserComm(comm) ? [pid] : [];
       });
   } catch {
     return [];
@@ -124,22 +149,25 @@ const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
 
   const candidates: BrowserCandidate[] = [];
   for (const pid of pids) {
-    let cmdline: string;
+    let argv: ReadonlyArray<string>;
     try {
-      cmdline = (await readFile(`/proc/${pid}/cmdline`, "utf8")).replace(/\0/g, " ").trim();
+      argv = parseProcCmdline(await readFile(`/proc/${pid}/cmdline`, "utf8"));
     } catch {
       continue;
     }
-    if (!cmdline || hasChildProcessType(cmdline)) continue;
+    const argv0 = argv[0];
+    if (argv0 === undefined || hasChildProcessType(argv.join(" "))) continue;
     let link: string | undefined;
     try {
       link = await readlink(`/proc/${pid}/exe`);
-    } catch {}
+    } catch {
+      // /proc/<pid>/exe is unreadable for processes owned by another user; argv[0] is used instead.
+    }
     // Chrome rewrites its argv to the bare executable path, so argv[0] is the live install location when /proc/<pid>/exe is unreadable or stale.
     const exePath =
       (link ? await spawnableExePath(link) : undefined) ??
-      (await spawnableExePath(cmdline.split(" ")[0] ?? ""));
-    const explicit = parseUserDataDirFlag(cmdline);
+      (await spawnableExePath(argv0));
+    const explicit = userDataDirFromArgv(argv);
     candidates.push({
       ...(exePath ? { exePath } : {}),
       ...(explicit ? { explicitUserDataDir: explicit } : {}),
@@ -172,7 +200,9 @@ const collectDarwin = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
     try {
       const { stdout } = await run("ps", ["-ww", "-o", "args=", "-p", pid], { timeout: EXEC_TIMEOUT_MS });
       args = stdout.trim();
-    } catch {}
+    } catch {
+      // ps can fail for a process that exited meanwhile; the pid is still reported, without args.
+    }
     if (args && hasChildProcessType(args)) continue;
     const explicit = args ? parseUserDataDirFlag(args) : undefined;
     candidates.push({
@@ -227,13 +257,17 @@ const collectWin32 = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
         if (candidates.length > 0) return candidates;
       }
     }
-  } catch {}
+  } catch {
+    // PowerShell is missing or restricted: fall back to tasklist below.
+  }
 
   try {
     const { stdout } = await run("tasklist.exe", [], { timeout: EXEC_TIMEOUT_MS, windowsHide: true });
     const lower = stdout.toLowerCase();
     if (WIN_IMAGE_NAMES.some((n) => lower.includes(n))) return [{}];
-  } catch {}
+  } catch {
+    // tasklist unavailable too: report no running browser rather than failing detection.
+  }
   return [];
 };
 
@@ -266,7 +300,9 @@ const winRegistryExecutable = async (): Promise<string | undefined> => {
         const match = /REG_[A-Z_]+\s+(.+)$/m.exec(stdout.trim());
         const path = match?.[1]?.trim();
         if (path) return path;
-      } catch {}
+      } catch {
+        // Key absent or reg.exe failed: try the next registry location.
+      }
     }
   }
   return undefined;
@@ -314,7 +350,9 @@ export const resolveBrowserExecutable = async (running?: RunningBrowser): Promis
     try {
       await access(candidate);
       return candidate;
-    } catch {}
+    } catch {
+      // Not installed at this location: try the next one.
+    }
   }
   return undefined;
 };

package/src/profile/command.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { BrowserClient } from "../client";
-import { discoverEndpoint } from "../cdp/discovery";
-import { type Result, err, ok } from "../util/result";
+import { type CdpEndpoint, discoverEndpoint } from "../cdp/discovery";
+import type { CdpError } from "../cdp/errors";
+import { type Result, err, mapErr, ok } from "../util/result";
 import { type BrowserProfile, listProfiles } from "./list";
 import { browserNameForUserDataDir, userDataDirCandidates } from "./paths";
 import { clearPin, type ProfilePin, readPin, writePin } from "./store";
@@ -53,15 +54,22 @@ const pinFor = (userDataDir: string, profile: BrowserProfile): ProfilePin => ({
   savedAt: new Date().toISOString(),
 });
 
-const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
+// How the command finds a user-data-dir when the client is not connected: the DevTools endpoint's
+// own report, then a scan of the per-platform candidate directories. Each defaults to the real one.
+export type ProfileCommandDeps = {
+  readonly discoverEndpoint?: () => Promise<Result<CdpEndpoint, CdpError>>;
+  readonly userDataDirCandidates?: () => ReadonlyArray<string>;
+};
+
+const resolveUserDataDir = async (client: BrowserClient, deps: ProfileCommandDeps): Promise<Result<string, string>> => {
   const connected = client.userDataDir();
   if (connected) return ok(connected);
 
-  const endpoint = await discoverEndpoint();
+  const endpoint = await (deps.discoverEndpoint ?? discoverEndpoint)();
   if (endpoint.success && endpoint.data.userDataDir) return ok(endpoint.data.userDataDir);
 
   const withProfiles: string[] = [];
-  for (const dir of userDataDirCandidates()) {
+  for (const dir of (deps.userDataDirCandidates ?? userDataDirCandidates)()) {
     if ((await listProfiles(dir)).length > 0) withProfiles.push(dir);
   }
   const only = withProfiles[0];
@@ -77,8 +85,9 @@ const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string,
 
 const loadProfiles = async (
   client: BrowserClient,
+  deps: ProfileCommandDeps,
 ): Promise<Result<{ userDataDir: string; profiles: ReadonlyArray<BrowserProfile> }, string>> => {
-  const dir = await resolveUserDataDir(client);
+  const dir = await resolveUserDataDir(client, deps);
   if (!dir.success) return dir;
   const profiles = await listProfiles(dir.data);
   if (profiles.length === 0) {
@@ -91,16 +100,14 @@ const applyToLiveSession = async (client: BrowserClient): Promise<Result<void, s
   if (!client.status().alive) return ok(undefined);
   await client.closeOwnedTabs();
   await client.stop();
-  const started = await client.start();
-  if (!started.success) return err(started.error.message);
-  return ok(undefined);
+  return mapErr(await client.start(), (e) => e.message);
 };
 
-export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient): void {
+export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient, deps: ProfileCommandDeps = {}): void {
   pi.registerCommand("browser-profile", {
     description: "Choose which browser profile the agent uses",
     handler: async (_args, ctx) => {
-      const loaded = await loadProfiles(client);
+      const loaded = await loadProfiles(client, deps);
       if (!loaded.success) {
         ctx.ui.notify(loaded.error, "error");
         return;
@@ -156,6 +163,7 @@ export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient):
 export const promptForProfileIfUnset = async (
   client: BrowserClient,
   ctx: ExtensionContext | undefined,
+  deps: ProfileCommandDeps = {},
 ): Promise<string | undefined> => {
   if (client.profilePin()) return undefined;
 
@@ -168,7 +176,7 @@ export const promptForProfileIfUnset = async (
     return "No browser profile selected — using whichever window is focused. Run /browser-profile to pin one.";
   }
 
-  const loaded = await loadProfiles(client);
+  const loaded = await loadProfiles(client, deps);
   if (!loaded.success) return loaded.error;
 
   const choice = await promptForProfile(

package/src/profile/launch.ts

@@ -41,25 +41,27 @@ export const openProfileWindow = async (
   if (req.explicitUserDataDir) args.push(`--user-data-dir=${req.explicitUserDataDir}`);
   args.push(`--profile-directory=${req.profileDir}`, "--new-window", sentinelUrl);
 
+  const discardSentinel = (): Promise<void> => rm(file, { force: true }).catch(() => undefined);
+
   let child: ChildProcess;
   try {
     child = spawn(req.exePath, args, { detached: true, stdio: "ignore" });
   } catch (e) {
-    await rm(file, { force: true }).catch(() => {});
+    await discardSentinel();
     return err(`could not launch ${req.exePath}: ${e instanceof Error ? e.message : String(e)}`);
   }
 
   // spawn() reports a bad binary asynchronously as an 'error' event rather than throwing; unhandled, an ENOENT looked like the 15s sentinel timeout.
   const spawnFailure = await new Promise<string | undefined>((resolve) => {
-    child.once("spawn", () => resolve(undefined));
-    child.once("error", (e: Error) => resolve(e.message));
+    child.once("spawn", () => { resolve(undefined); });
+    child.once("error", (e: Error) => { resolve(e.message); });
   });
   // A later 'error' event with no listener would throw, so keep one attached for the detached launcher's lifetime.
-  child.on("error", () => {});
+  child.on("error", () => undefined);
   child.unref();
 
   if (spawnFailure) {
-    await rm(file, { force: true }).catch(() => {});
+    await discardSentinel();
     return err(`could not launch ${req.exePath}: ${spawnFailure}`);
   }
 
@@ -67,12 +69,14 @@ export const openProfileWindow = async (
 
   return ok({
     sentinelUrl,
-    cleanup: async () => {
-      await rm(file, { force: true }).catch(() => {});
-    },
+    cleanup: discardSentinel,
     kill: () => {
       if (live) {
-        try { live.kill("SIGTERM"); } catch {}
+        try {
+          live.kill("SIGTERM");
+        } catch {
+          // The process already exited; there is nothing left to kill.
+        }
         live = null;
       }
     },

package/src/profile/list.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { Type } from "typebox";
 import { Compile } from "typebox/compile";
 import { parseJson } from "../schemas/parse";
+// Chrome writes "" for an unnamed profile and an unsigned-in account, so an empty string must read as absent.
+import { asNonEmptyString, asRecord } from "../util/guards";
 
 export type BrowserProfile = {
   readonly dir: string;
@@ -35,12 +37,6 @@ const readJsonFile = async (path: string): Promise<Record<string, unknown> | nul
   return parsed.success ? parsed.data : null;
 };
 
-const asRecord = (v: unknown): Record<string, unknown> | null =>
-  jsonObjectValidator.Check(v) ? v : null;
-
-const asString = (v: unknown): string | undefined =>
-  typeof v === "string" && v.length > 0 ? v : undefined;
-
 const orderDirs = (dirs: ReadonlyArray<string>, order: ReadonlyArray<string>): ReadonlyArray<string> => {
   const known = order.filter((d) => dirs.includes(d));
   const rest = dirs.filter((d) => !known.includes(d)).sort((a, b) => a.localeCompare(b));
@@ -73,9 +69,9 @@ const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<Br
 
   const rawOrder = profileNode["profiles_order"];
   const order = Array.isArray(rawOrder) ? rawOrder.filter((v): v is string => typeof v === "string") : [];
-  const lastUsed = asString(profileNode["last_used"]);
+  const lastUsed = asNonEmptyString(profileNode["last_used"]);
 
-  const entries: Array<{ dir: string; entry: Record<string, unknown> }> = [];
+  const entries: Array<{ dir: string; entry: Readonly<Record<string, unknown>> }> = [];
   for (const [dir, value] of Object.entries(infoCache)) {
     if (NON_PROFILE_DIRS.has(dir)) continue;
     const entry = asRecord(value);
@@ -91,8 +87,8 @@ const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<Br
   return ordered.flatMap((dir) => {
     const entry = byDir.get(dir);
     if (!entry) return [];
-    const name = asString(entry["name"]) ?? asString(entry["gaia_name"]);
-    const email = asString(entry["user_name"]);
+    const name = asNonEmptyString(entry["name"]) ?? asNonEmptyString(entry["gaia_name"]);
+    const email = asNonEmptyString(entry["user_name"]);
     return [buildProfile(dir, name, email, dir === lastUsed)];
   });
 };
@@ -115,10 +111,10 @@ const listFromPreferencesScan = async (userDataDir: string): Promise<ReadonlyArr
     const prefs = await readJsonFile(join(userDataDir, dir, "Preferences"));
     if (!prefs) continue;
     const profileNode = asRecord(prefs["profile"]);
-    const name = profileNode ? asString(profileNode["name"]) : undefined;
+    const name = profileNode ? asNonEmptyString(profileNode["name"]) : undefined;
     const accounts = prefs["account_info"];
-    const firstAccount = Array.isArray(accounts) ? asRecord(accounts[0]) : null;
-    const email = firstAccount ? asString(firstAccount["email"]) : undefined;
+    const firstAccount = Array.isArray(accounts) ? asRecord(accounts[0]) : undefined;
+    const email = firstAccount ? asNonEmptyString(firstAccount["email"]) : undefined;
     profiles.push(buildProfile(dir, name, email, false));
   }
   return profiles;

package/src/profile/store.ts

@@ -74,7 +74,8 @@ const writePinFile = async (profile: ProfilePin | null): Promise<Result<void, st
     await rename(tmp, target);
     return ok(undefined);
   } catch (e) {
-    await unlink(tmp).catch(() => {});
+    // The temp file may never have been created; the write error below is the one that matters.
+    await unlink(tmp).catch(() => undefined);
     return err(`could not save profile selection to ${target}: ${e instanceof Error ? e.message : String(e)}`);
   }
 };

package/src/prompt.ts

@@ -1,7 +1,35 @@
-export function getBrowserSystemPrompt(connected = true): string {
+import { ALL_TOOLS } from "./registry";
+import type { BrowserTool, ToolConcurrency } from "./util/tool";
+
+// The lane text is derived from each tool's own `concurrency`, so a tool can never
+// be mis-described as observational while actually taking the mutation mutex.
+export type PromptTool = Pick<BrowserTool, "name" | "concurrency">;
+
+export type LaneNames = {
+  readonly serialized: ReadonlyArray<string>;
+  readonly parallel: ReadonlyArray<string>;
+};
+
+const TOOL_PREFIX = "browser_";
+
+// Lane lists use the short form (click, not browser_click) to keep the prompt compact; the
+// prefix is universal and stated once in the prose above the list.
+export const shortToolName = (name: string): string =>
+  name.startsWith(TOOL_PREFIX) ? name.slice(TOOL_PREFIX.length) : name;
+
+export const laneNames = (tools: ReadonlyArray<PromptTool>): LaneNames => {
+  const lane = (c: ToolConcurrency): ReadonlyArray<string> => tools.filter((t) => t.concurrency === c).map((t) => t.name);
+  return { serialized: lane("serialized"), parallel: lane("parallel") };
+};
+
+const joinShort = (names: ReadonlyArray<string>): string => names.map(shortToolName).join(", ");
+
+export function getBrowserSystemPrompt(connected = true, tools: ReadonlyArray<PromptTool> = ALL_TOOLS): string {
   const connectionNotice = connected
     ? ""
-    : "Browser is not connected. Run browser_setup or /browser-setup to connect.\n\n";
+    : // "Not connected" alone read to some models as "no browser tools", and they fell back to curl.
+      "The browser_* tools are available in this session; the browser is just not connected yet. Call browser_setup first to connect (the user can also run /browser-setup), then use the browser_* tools. When the user asks for the browser, do not swap in curl, another fetch tool or another browser tool.\n\n";
+  const lanes = laneNames(tools);
   return `
 ## Browser Control
 
@@ -11,12 +39,10 @@ and tool-specific guidelines.
 
 - Operate only inside this session's owned Chrome window. Never reach into the
   user's other tabs or windows. Close owned tabs once no later step needs them.
-- Mutating tools (click, type, fill, press_key, scroll, navigate, history, tab
-  switch/new/close, upload, download, headers, viewport, drag, web_search) are
-  serialized. Observations (snapshot, screenshot, page_info, current_tab, list_tabs,
-  console, network_requests, http_get, read_page, execute_js, wait, wait_for) may run
-  concurrently with them. \`browser_run_script\` bypasses that lane: keep mutating
-  scripts sequential with other browser calls. Parallelize only independent calls.
+- Tools in the serialized lane (${joinShort(lanes.serialized)}) run one at a time.
+  Tools in the parallel lane (${joinShort(lanes.parallel)}) may run concurrently
+  with them. \`browser_run_script\` bypasses that lane: keep mutating scripts
+  sequential with other browser calls. Parallelize only independent calls.
 - Agents sharing a session share its active tab. Check \`browser_current_tab\`
   before a mutation to confirm the expected tab when another agent may switch it.
 - Read any appended "Page changes" diff to confirm an interaction. Tools without a

package/src/recipes/command.ts

@@ -0,0 +1,96 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { BrowserClient } from "../client";
+import { missingParams, runRecipe, unknownParams, unknownParamsMessage } from "./replay";
+import { formatFailureHandoff, formatOutputs, listText } from "./run-tool";
+import { findRecipe, listRecipes, recordRun } from "./store";
+import { approveProjectRecipe, trustWritten } from "./trust";
+
+const TOKEN = /([^\s=]+)="([^"]*)"|(\S+)/g;
+
+// `NAME key=value key="two words"`: the first bare word is the name, a double-quoted value stays whole, and the
+// bare words after an unquoted value join it, so `topic=Grace Hopper` is "Grace Hopper", not "Grace".
+export const parseCommandArgs = (raw: string): { readonly name: string | undefined; readonly params: Readonly<Record<string, string>> } => {
+  let name: string | undefined;
+  let open: string | undefined;
+  const params: Record<string, string> = {};
+  for (const m of raw.matchAll(TOKEN)) {
+    const [, quotedKey, quotedValue, bare] = m;
+    if (quotedKey !== undefined && quotedValue !== undefined) {
+      params[quotedKey] = quotedValue;
+      open = undefined;
+    } else if (bare?.includes("=") === true) {
+      const at = bare.indexOf("=");
+      open = bare.slice(0, at);
+      params[open] = bare.slice(at + 1);
+    } else if (bare !== undefined && name === undefined) {
+      name = bare;
+    } else if (bare !== undefined && open !== undefined) {
+      params[open] = `${params[open] ?? ""} ${bare}`;
+    }
+  }
+  return { name, params };
+};
+
+// Runs the replay engine directly, so a command run never starts a model turn.
+export const registerRecipeCommand = (pi: Pick<ExtensionAPI, "registerCommand" | "sendUserMessage" | "sendMessage">, client: BrowserClient): void => {
+  pi.registerCommand("browser-recipe", {
+    description: "Replay a saved browser recipe with no model calls: /browser-recipe NAME key=value. No name lists recipes.",
+    getArgumentCompletions: async (prefix) => {
+      const all = await listRecipes(process.cwd());
+      return all
+        .map((s) => s.recipe.name)
+        .filter((n) => n.startsWith(prefix))
+        .map((n) => ({ value: n, label: n }));
+    },
+    handler: async (raw, ctx) => {
+      const { name, params } = parseCommandArgs(raw);
+      if (name === undefined) {
+        ctx.ui.notify(await listText(ctx.cwd), "info");
+        return;
+      }
+      const alive = await client.ensureAlive();
+      if (!alive.success) {
+        ctx.ui.notify(`Browser not connected: ${alive.error.message}. Run /browser-setup first.`, "error");
+        return;
+      }
+      const stored = await findRecipe(ctx.cwd, name);
+      if (!stored.success) {
+        ctx.ui.notify(stored.error, "error");
+        return;
+      }
+      const unknown = unknownParams(stored.data.recipe, params);
+      if (unknown.length > 0) {
+        ctx.ui.notify(unknownParamsMessage(stored.data.recipe, unknown), "error");
+        return;
+      }
+      const missing = missingParams(stored.data.recipe, params);
+      if (missing.length > 0) {
+        ctx.ui.notify(`Recipe ${name} needs: ${missing.map((p) => `${p}=… (e.g. ${stored.data.recipe.params[p]?.example ?? ""})`).join(" ")}`, "error");
+        return;
+      }
+      const approved = await approveProjectRecipe(ctx, stored.data, params);
+      if (!approved.success) {
+        ctx.ui.notify(approved.error, "error");
+        return;
+      }
+      ctx.ui.notify(`Running recipe ${name}…`, "info");
+      const outcome = await runRecipe({ client, extensionCtx: ctx, recipe: stored.data.recipe, params });
+      const at = new Date().toISOString();
+      if (outcome.ok) {
+        await recordRun(stored.data, { at, result: "ok" });
+        await trustWritten(stored.data, ctx.cwd);
+        ctx.ui.notify(`Recipe ${name} done: ${outcome.steps} steps ✓`, "info");
+        // Shown in the session without starting a model turn; the agent sees it with the user's next message.
+        const data = formatOutputs(outcome.outputs);
+        if (data !== "") pi.sendMessage({ customType: "browser-recipe-output", content: `/browser-recipe ${name}\n${data}`, display: true }, { triggerTurn: false });
+        return;
+      }
+      await recordRun(stored.data, { at, result: "failed", step: outcome.failure.step });
+      await trustWritten(stored.data, ctx.cwd);
+      ctx.ui.notify(`Recipe ${name} failed at step ${outcome.failure.step}; handing it to the agent to finish the task and repair the recipe.`, "warning");
+      const report = `/browser-recipe ${name} failed. ${formatFailureHandoff(stored.data.recipe, params, outcome.failure)}`;
+      if (ctx.isIdle()) pi.sendUserMessage(report);
+      else pi.sendUserMessage(report, { deliverAs: "followUp" });
+    },
+  });
+};