@agentuity/browzer 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Agentuity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# Browzer
+
+`browzer` is [agent-browser](https://agent-browser.dev) with a trace. Same commands, same snapshot-and-click loop. Each session is saved so you can inspect it later or open a local HTML replay.
+
+Live watching stays with `agent-browser dashboard`. Browzer is the bundle you keep after `close`.
+
+![Replay of a 31-step session](docs/replay.png)
+
+## Install
+
+Needs Node 18+, [agent-browser](https://agent-browser.dev) on `PATH`, and [ffmpeg](https://ffmpeg.org/) on `PATH` (for video).
+
+```bash
+npm i -g @agentuity/browzer
+```
+
+Confirm:
+
+```bash
+browzer help
+agent-browser --version
+ffmpeg -version
+```
+
+Install the Agent Skill so Claude Code, Cursor, Codex, Grok, and others treat `browzer` as the browser CLI when a recording is wanted:
+
+```bash
+browzer skills install
+```
+
+## Quick start
+
+```bash
+export AGENT_BROWSER_SESSION=demo
+export AGENT_BROWSER_IDLE_TIMEOUT_MS=0
+
+browzer --session demo open https://example.com
+browzer --session demo snapshot -i
+browzer --session demo find text "Learn more" click
+browzer --session demo close
+
+browzer traces
+browzer inspect demo
+browzer replay demo
+```
+
+Every `browzer` invocation except `dashboard`, `mcp`, `doctor`, `install`, `upgrade`, and `session` metadata is the same argv you would have passed to `agent-browser`. Do not also run `agent-browser` on that `--session`.
+
+## How a trace is captured
+
+On the first successful command for a session, Browzer starts:
+
+- `record start` → `session.mp4`
+- `network har start --content text` → `network.har`
+
+While commands run, it appends:
+
+- `commands.jsonl` — argv, duration, exit, stdout/stderr
+- `events.jsonl` — stream `command` / `result` / `url` / `tabs`
+- `console.jsonl` — console and page errors from the stream
+
+On `close` it dumps `console.json`, `errors.json`, `snapshot.txt`, `poster.jpg`, stops recording and HAR, and writes `summary.md`.
+
+Traces are written under the current directory as `<id>/` unless you pass `--output` / `-o` or set `BROWZER_OUTPUT`. Session bookkeeping still uses `~/.browzer/active` (override the home with `BROWZER_HOME`). Override the wrapped binary with `AGENT_BROWSER_BIN`.
+
+```bash
+browzer --output ./artifacts --session demo open https://example.com
+browzer --output ./artifacts traces
+browzer --output ./artifacts replay demo
+```
+
+## Commands Browzer adds
+
+| Command | What it does |
+|---|---|
+| `browzer traces` | List traces |
+| `browzer traces --json` | Same, JSON |
+| `browzer inspect [id]` | Print `summary.md` (latest if omitted) |
+| `browzer replay [id\|path]` | Write `replay.html` next to the video and open it |
+| `browzer skills` | List the bundled skill |
+| `browzer skills get` | Print `SKILL.md` matching this CLI |
+| `browzer skills install` | Copy the skill into `~/.agents`, plus Claude / Cursor / Codex / Grok if those dirs exist |
+| `browzer skills install --project` | Copy into this repo’s agent skill folders |
+
+Everything else is forwarded to `agent-browser`.
+
+## Replay
+
+```bash
+browzer replay                 # latest
+browzer replay demo            # id, prefix, or session suffix
+browzer replay ./20260917-185027-long-demo
+```
+
+The page is a static HTML file beside `session.mp4`. No app server. The URL bar follows the playhead. Steps seek the video. Console, network, errors, and snapshot sit behind **Show details**.
+
+## After a failure
+
+Agents should read `browzer inspect` first (failed commands, HAR 4xx/5xx, console errors). Humans open `browzer replay`. Live CDP-style inspection during a run is `agent-browser dashboard start` at http://localhost:4848.
+
+## Skill
+
+Canonical file: [`skills/browzer/SKILL.md`](skills/browzer/SKILL.md). Same Agent Skills format used by Claude Code, Cursor, Codex, and Grok. It is a prefix swap: same commands as agent-browser, invoke `browzer`. Snapshot/click/fill details stay in the agent-browser core skill.

package/dist/cli/agent.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_BROWSER_BIN = void 0;
+exports.runAgentBrowser = runAgentBrowser;
+exports.parseWrappedJson = parseWrappedJson;
+const node_child_process_1 = require("node:child_process");
+exports.AGENT_BROWSER_BIN = process.env.AGENT_BROWSER_BIN ?? "agent-browser";
+function runAgentBrowser(args, opts) {
+    const tee = opts?.tee ?? false;
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(exports.AGENT_BROWSER_BIN, args, {
+            env: process.env,
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code, stdout, stderr, durationMs: Date.now() - started });
+        };
+        const timer = opts?.timeoutMs != null
+            ? setTimeout(() => {
+                child.kill("SIGTERM");
+                reject(new Error(`agent-browser timed out: ${args.join(" ")}`));
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (tee)
+                process.stdout.write(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+            if (tee)
+                process.stderr.write(chunk);
+        });
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                reject(new Error("agent-browser not found on PATH. Install it globally (npm i -g agent-browser) or set AGENT_BROWSER_BIN."));
+                return;
+            }
+            reject(err);
+        });
+        child.on("close", (code) => finish(code ?? 1));
+    });
+}
+function parseWrappedJson(text) {
+    const start = text.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        return JSON.parse(text.slice(start));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/argv.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOSE_COMMANDS = exports.SESSION_META_COMMANDS = exports.PASSTHROUGH_COMMANDS = exports.BROWZER_COMMANDS = void 0;
+exports.parseArgv = parseArgv;
+exports.isPassthrough = isPassthrough;
+const FLAGS_WITH_VALUE = new Set([
+    "--session",
+    "--cdp",
+    "--profile",
+    "--idle-timeout",
+    "--config",
+    "--allowed-domains",
+    "--executable-path",
+    "--user-agent",
+    "--proxy",
+    "--proxy-bypass",
+    "--headers",
+    "--storage-state",
+    "--init-script",
+    "--tools",
+    "--port",
+    "--allowed-origins",
+    "--output",
+    "-o",
+    "--provider",
+]);
+exports.BROWZER_COMMANDS = new Set(["traces", "inspect", "replay", "help", "skills"]);
+exports.PASSTHROUGH_COMMANDS = new Set([
+    "dashboard",
+    "mcp",
+    "doctor",
+    "install",
+    "upgrade",
+    "plugin",
+    "help",
+    "--help",
+    "-h",
+    "--version",
+    "-V",
+    "-v",
+]);
+exports.SESSION_META_COMMANDS = new Set(["session"]);
+exports.CLOSE_COMMANDS = new Set(["close", "quit", "exit"]);
+function parseArgv(argv) {
+    const forwarded = [];
+    let session = process.env.AGENT_BROWSER_SESSION?.trim() || "default";
+    let json = false;
+    let command = null;
+    let output = process.env.BROWZER_OUTPUT?.trim() || undefined;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? "";
+        if ((token === "--output" || token === "-o") && argv[i + 1]) {
+            output = argv[i + 1];
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--output=")) {
+            output = token.slice("--output=".length);
+            continue;
+        }
+        if (token === "--session" && argv[i + 1]) {
+            session = argv[i + 1];
+            forwarded.push(token, argv[i + 1]);
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--session=")) {
+            session = token.slice("--session=".length);
+            forwarded.push(token);
+            continue;
+        }
+        if (token === "--json") {
+            json = true;
+            forwarded.push(token);
+            continue;
+        }
+        if (token === "--headed" && (argv[i + 1] === "true" || argv[i + 1] === "false")) {
+            forwarded.push(token, argv[i + 1]);
+            i += 1;
+            continue;
+        }
+        forwarded.push(token);
+        if (token.startsWith("-")) {
+            if (FLAGS_WITH_VALUE.has(token) && argv[i + 1] && !argv[i + 1].startsWith("-")) {
+                forwarded.push(argv[i + 1]);
+                i += 1;
+            }
+            continue;
+        }
+        if (!command)
+            command = token;
+    }
+    return { session, command, forwarded, json, output };
+}
+function isPassthrough(command) {
+    if (!command)
+        return true;
+    if (exports.PASSTHROUGH_COMMANDS.has(command))
+        return true;
+    if (exports.SESSION_META_COMMANDS.has(command))
+        return true;
+    return false;
+}

package/dist/cli/browzer.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const argv_1 = require("./argv");
+const agent_1 = require("./agent");
+const commands_1 = require("./commands");
+const replay_1 = require("./replay");
+const skills_1 = require("./skills");
+const collect_1 = require("./collect");
+const state_1 = require("./state");
+async function main() {
+    const argv = process.argv.slice(2);
+    const parsed = (0, argv_1.parseArgv)(argv);
+    if (parsed.command && argv_1.BROWZER_COMMANDS.has(parsed.command)) {
+        if (parsed.command === "help") {
+            process.stdout.write((0, commands_1.helpText)());
+            return;
+        }
+        if (parsed.command === "traces") {
+            await (0, commands_1.tracesCommand)(parsed.json, parsed.output);
+            return;
+        }
+        if (parsed.command === "inspect") {
+            const index = argv.indexOf("inspect");
+            const id = argv.slice(index + 1).find((token) => !token.startsWith("-"));
+            await (0, commands_1.inspectCommand)(id, parsed.output);
+            return;
+        }
+        if (parsed.command === "replay") {
+            const index = argv.indexOf("replay");
+            const target = argv.slice(index + 1).find((token) => !token.startsWith("-"));
+            await (0, replay_1.replayCommand)(target, parsed.output);
+            return;
+        }
+        if (parsed.command === "skills") {
+            await (0, skills_1.skillsCommand)(argv, parsed.json);
+            return;
+        }
+    }
+    if ((0, argv_1.isPassthrough)(parsed.command)) {
+        const result = await (0, agent_1.runAgentBrowser)(parsed.forwarded, { tee: true });
+        process.exit(result.code);
+    }
+    const startUrl = commandUrl(parsed.forwarded, parsed.command);
+    const closing = argv_1.CLOSE_COMMANDS.has(parsed.command ?? "");
+    if (closing && parsed.forwarded.includes("--all")) {
+        for (const active of await (0, state_1.listActive)()) {
+            try {
+                await (0, collect_1.finalize)(active);
+            }
+            catch (err) {
+                process.stderr.write(`browzer: failed to finalize ${active.id}: ${String(err)}\n`);
+            }
+        }
+        const result = await (0, agent_1.runAgentBrowser)(parsed.forwarded, { tee: true });
+        process.exit(result.code);
+    }
+    if (closing) {
+        const active = await (0, state_1.loadActive)(parsed.session);
+        if (active) {
+            try {
+                await (0, collect_1.finalize)(active);
+            }
+            catch (err) {
+                process.stderr.write(`browzer: finalize failed: ${String(err)}\n`);
+            }
+        }
+        const result = await (0, agent_1.runAgentBrowser)(parsed.forwarded, { tee: true });
+        process.exit(result.code);
+    }
+    const trace = await (0, collect_1.ensureTrace)(parsed.session, startUrl, parsed.output);
+    const result = await (0, collect_1.wrapCommand)(trace, parsed.forwarded);
+    if (result.code === 0) {
+        const current = (await (0, state_1.loadActive)(parsed.session)) ?? trace;
+        try {
+            await (0, collect_1.startCapture)(current);
+        }
+        catch (err) {
+            process.stderr.write(`browzer: capture not started: ${String(err)}\n`);
+        }
+    }
+    process.exit(result.code);
+}
+function commandUrl(argv, command) {
+    if (command !== "open" && command !== "goto" && command !== "navigate")
+        return undefined;
+    const index = argv.findIndex((token) => token === command);
+    if (index < 0)
+        return undefined;
+    return argv.slice(index + 1).find((token) => !token.startsWith("-"));
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/cli/collect.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTrace = ensureTrace;
+exports.logCommand = logCommand;
+exports.startCapture = startCapture;
+exports.wrapCommand = wrapCommand;
+exports.finalize = finalize;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const agent_1 = require("./agent");
+const paths_1 = require("./paths");
+const summary_1 = require("./summary");
+const stream_1 = require("./stream");
+const state_1 = require("./state");
+const MAX_CAPTURE = 24_000;
+async function ensureTrace(session, startUrl, output) {
+    const existing = await (0, state_1.loadActive)(session);
+    if (existing)
+        return existing;
+    const id = (0, paths_1.newTraceId)(session);
+    const dir = node_path_1.default.join((0, paths_1.tracesDir)(output), id);
+    await (0, promises_1.mkdir)(dir, { recursive: true });
+    const trace = {
+        id,
+        dir,
+        session,
+        startedAt: Date.now(),
+        recording: false,
+        har: false,
+        streamPort: null,
+        startUrl,
+    };
+    await (0, state_1.saveActive)(trace);
+    await (0, promises_1.writeFile)(node_path_1.default.join(dir, "meta.json"), JSON.stringify({ id, session, startedAt: trace.startedAt, startUrl, status: "active" }, null, 2));
+    return trace;
+}
+async function logCommand(trace, row) {
+    const line = {
+        ts: Date.now(),
+        session: trace.session,
+        argv: row.argv,
+        durationMs: row.durationMs,
+        exitCode: row.exitCode,
+        stdout: clip(row.stdout),
+        stderr: clip(row.stderr),
+    };
+    await (0, promises_1.appendFile)(node_path_1.default.join(trace.dir, "commands.jsonl"), `${JSON.stringify(line)}\n`);
+}
+async function startCapture(trace) {
+    const status = await abJson(trace.session, [
+        "stream",
+        "status",
+    ]);
+    if (status?.port) {
+        trace.streamPort = status.port;
+    }
+    if (!trace.recording && !trace.recordAttempted) {
+        const video = node_path_1.default.join(trace.dir, "session.mp4");
+        const started = await abJson(trace.session, ["record", "start", video, "--fps", "12"]);
+        trace.recording = Boolean(started);
+        trace.recordAttempted = true;
+    }
+    if (!trace.har && !trace.harAttempted) {
+        const started = await runSilent(trace.session, ["network", "har", "start", "--content", "text"]);
+        trace.har = started.code === 0;
+        trace.harAttempted = true;
+    }
+    await (0, state_1.saveActive)(trace);
+    return trace;
+}
+async function wrapCommand(trace, forwarded) {
+    const writes = [];
+    const run = () => (0, agent_1.runAgentBrowser)(forwarded, { tee: true });
+    const result = await (0, stream_1.collectDuring)(trace.streamPort, run, (event) => {
+        writes.push((0, promises_1.appendFile)(node_path_1.default.join(trace.dir, "events.jsonl"), `${JSON.stringify(event)}\n`));
+        if (event.type === "url" && typeof event.url === "string") {
+            trace.lastUrl = event.url;
+        }
+        if (event.type === "console" || event.type === "page_error") {
+            writes.push((0, promises_1.appendFile)(node_path_1.default.join(trace.dir, "console.jsonl"), `${JSON.stringify(event)}\n`));
+        }
+    });
+    await Promise.all(writes);
+    await logCommand(trace, {
+        argv: forwarded,
+        durationMs: result.durationMs,
+        exitCode: result.code,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    });
+    await (0, state_1.saveActive)(trace);
+    return result;
+}
+async function finalize(trace) {
+    const url = await textOut(trace.session, ["get", "url"]);
+    const title = await textOut(trace.session, ["get", "title"]);
+    if (url)
+        trace.lastUrl = url;
+    await dumpJson(trace.session, ["--json", "console"], node_path_1.default.join(trace.dir, "console.json"));
+    await dumpJson(trace.session, ["--json", "errors"], node_path_1.default.join(trace.dir, "errors.json"));
+    await dumpText(trace.session, ["snapshot", "-i"], node_path_1.default.join(trace.dir, "snapshot.txt"));
+    await runSilent(trace.session, [
+        "screenshot",
+        "--screenshot-format",
+        "jpeg",
+        "--screenshot-quality",
+        "70",
+        node_path_1.default.join(trace.dir, "poster.jpg"),
+    ]);
+    if (trace.recording) {
+        await runSilent(trace.session, ["record", "stop"]);
+        trace.recording = false;
+    }
+    if (trace.har) {
+        await runSilent(trace.session, ["network", "har", "stop", node_path_1.default.join(trace.dir, "network.har")]);
+        trace.har = false;
+    }
+    await (0, summary_1.writeSummary)(trace, { title, url: trace.lastUrl || trace.startUrl });
+    await (0, promises_1.writeFile)(node_path_1.default.join(trace.dir, "meta.json"), JSON.stringify({
+        id: trace.id,
+        session: trace.session,
+        startedAt: trace.startedAt,
+        endedAt: Date.now(),
+        startUrl: trace.startUrl,
+        lastUrl: trace.lastUrl || url,
+        title,
+        status: "complete",
+        dir: trace.dir,
+    }, null, 2));
+    await (0, state_1.clearActive)(trace.session);
+}
+async function abJson(session, args) {
+    const result = await runSilent(session, ["--json", ...args]);
+    const parsed = (0, agent_1.parseWrappedJson)(result.stdout || result.stderr);
+    if (!parsed?.success)
+        return null;
+    return parsed.data ?? null;
+}
+async function dumpJson(session, args, file) {
+    const result = await runSilent(session, args);
+    const text = result.stdout.trim() || result.stderr.trim();
+    if (text)
+        await (0, promises_1.writeFile)(file, text);
+}
+async function dumpText(session, args, file) {
+    const result = await runSilent(session, args);
+    const text = result.stdout.trim() || result.stderr.trim();
+    if (text)
+        await (0, promises_1.writeFile)(file, `${text}\n`);
+}
+async function textOut(session, args) {
+    const result = await runSilent(session, args);
+    const text = result.stdout.trim();
+    return text || undefined;
+}
+async function runSilent(session, args) {
+    return (0, agent_1.runAgentBrowser)(["--session", session, ...args], { tee: false, timeoutMs: 30_000 });
+}
+function clip(text) {
+    if (text.length <= MAX_CAPTURE)
+        return text;
+    return `${text.slice(0, MAX_CAPTURE)}\n…truncated`;
+}

package/dist/cli/commands.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tracesCommand = tracesCommand;
+exports.inspectCommand = inspectCommand;
+exports.helpText = helpText;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+async function tracesCommand(json, output) {
+    const dir = (0, paths_1.tracesDir)(output);
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        if (json) {
+            process.stdout.write(`${JSON.stringify({ traces: [] })}\n`);
+            return;
+        }
+        process.stdout.write("No traces yet. Run a session with browzer <agent-browser command>.\n");
+        return;
+    }
+    const ids = (await (0, promises_1.readdir)(dir)).filter((name) => (0, node_fs_1.existsSync)(node_path_1.default.join(dir, name, "meta.json")));
+    const traces = await Promise.all(ids.map(async (id) => {
+        const meta = JSON.parse(await (0, promises_1.readFile)(node_path_1.default.join(dir, id, "meta.json"), "utf8"));
+        const info = await (0, promises_1.stat)(node_path_1.default.join(dir, id));
+        return { ...meta, id, mtime: info.mtimeMs, dir: node_path_1.default.join(dir, id) };
+    }));
+    traces.sort((a, b) => (b.startedAt ?? b.mtime) - (a.startedAt ?? a.mtime));
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ traces }, null, 2)}\n`);
+        return;
+    }
+    if (traces.length === 0) {
+        process.stdout.write("No traces yet.\n");
+        return;
+    }
+    for (const trace of traces) {
+        const when = trace.startedAt ? new Date(trace.startedAt).toISOString() : "";
+        process.stdout.write(`${trace.id}  ${trace.status ?? "?"}  ${trace.session ?? ""}  ${trace.lastUrl ?? ""}  ${when}\n`);
+    }
+}
+async function inspectCommand(idArg, output) {
+    const root = (0, paths_1.tracesDir)(output);
+    const id = idArg || (await latestId(root));
+    if (!id) {
+        process.stderr.write("No traces found.\n");
+        process.exitCode = 1;
+        return;
+    }
+    const dir = node_path_1.default.join(root, id);
+    const matches = (0, node_fs_1.existsSync)(dir) ? [id] : await matchPrefix(id, root);
+    const resolved = matches.length <= 1 ? matches[0] : await newest(matches, root);
+    if (!resolved) {
+        process.stderr.write(`Trace not found: ${id}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const resolvedDir = node_path_1.default.join(root, resolved);
+    const summaryPath = node_path_1.default.join(resolvedDir, "summary.md");
+    const metaPath = node_path_1.default.join(resolvedDir, "meta.json");
+    process.stdout.write(`trace: ${resolved}\n`);
+    process.stdout.write(`dir: ${resolvedDir}\n\n`);
+    if ((0, node_fs_1.existsSync)(summaryPath)) {
+        process.stdout.write(await (0, promises_1.readFile)(summaryPath, "utf8"));
+        return;
+    }
+    if ((0, node_fs_1.existsSync)(metaPath)) {
+        process.stdout.write(`${await (0, promises_1.readFile)(metaPath, "utf8")}\n`);
+    }
+}
+async function latestId(dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return null;
+    const ids = await (0, promises_1.readdir)(dir);
+    let best = null;
+    for (const id of ids) {
+        try {
+            const info = await (0, promises_1.stat)(node_path_1.default.join(dir, id));
+            if (!best || info.mtimeMs > best.mtime)
+                best = { id, mtime: info.mtimeMs };
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return best?.id ?? null;
+}
+async function matchPrefix(prefix, dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const ids = await (0, promises_1.readdir)(dir);
+    return ids.filter((id) => id === prefix || id.startsWith(prefix) || id.endsWith(`-${prefix}`));
+}
+async function newest(ids, dir) {
+    let best;
+    for (const id of ids) {
+        try {
+            const info = await (0, promises_1.stat)(node_path_1.default.join(dir, id));
+            if (!best || info.mtimeMs > best.mtime)
+                best = { id, mtime: info.mtimeMs };
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return best?.id;
+}
+function helpText() {
+    return `browzer — agent-browser wrapper that records a debug trace
+
+Usage:
+  browzer [--output <dir>] <agent-browser args...>
+  browzer traces [--output <dir>]
+  browzer inspect [id] [--output <dir>]
+  browzer replay [id|path] [--output <dir>]
+  browzer skills [list|get|path|install] [--project]
+  browzer help
+
+--output / -o   Directory for traces. Default: current working directory.
+                Also BROWZER_OUTPUT.
+
+On first successful command, browzer starts video recording and HAR capture.
+On close, it dumps console, errors, a snapshot, and a poster.
+
+Use agent-browser dashboard for live observation. Browzer is the saved bundle.
+`;
+}