@agentuity/browzer 0.1.0

package/dist/cli/summary.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSummary = writeSummary;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+async function writeSummary(trace, extras) {
+    const commands = await readJsonl(node_path_1.default.join(trace.dir, "commands.jsonl"));
+    const failed = commands.filter((row) => row.exitCode !== 0);
+    const errorsRaw = await readOptional(node_path_1.default.join(trace.dir, "errors.json"));
+    const consoleRaw = await readOptional(node_path_1.default.join(trace.dir, "console.json"));
+    const harIssues = await harFailures(node_path_1.default.join(trace.dir, "network.har"));
+    const errorCount = countErrors(errorsRaw);
+    const consoleErrors = countConsoleErrors(consoleRaw);
+    const endedAt = Date.now();
+    const durationSec = ((endedAt - trace.startedAt) / 1000).toFixed(1);
+    const lines = [
+        `# ${trace.id}`,
+        "",
+        `- session: \`${trace.session}\``,
+        `- duration: ${durationSec}s`,
+        extras.url ? `- url: ${extras.url}` : null,
+        extras.title ? `- title: ${extras.title}` : null,
+        `- commands: ${commands.length} (${failed.length} failed)`,
+        `- page errors: ${errorCount}`,
+        `- console errors: ${consoleErrors}`,
+        `- har failures: ${harIssues.length}`,
+        "",
+        "## Failed commands",
+        failed.length === 0
+            ? "_none_"
+            : failed
+                .map((row) => `- \`${row.argv.join(" ")}\` (exit ${row.exitCode})`)
+                .join("\n"),
+        "",
+        "## Network failures",
+        harIssues.length === 0 ? "_none_" : harIssues.map((item) => `- ${item}`).join("\n"),
+        "",
+        "## Files",
+        ...[
+            "session.mp4",
+            "network.har",
+            "commands.jsonl",
+            "events.jsonl",
+            "console.json",
+            "errors.json",
+            "snapshot.txt",
+            "poster.jpg",
+        ]
+            .filter((name) => (0, node_fs_1.existsSync)(node_path_1.default.join(trace.dir, name)))
+            .map((name) => `- ${name}`),
+        "",
+    ].filter((line) => line != null);
+    await (0, promises_1.writeFile)(node_path_1.default.join(trace.dir, "summary.md"), `${lines.join("\n")}\n`);
+}
+async function readJsonl(file) {
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    const text = await (0, promises_1.readFile)(file, "utf8");
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+async function readOptional(file) {
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    try {
+        return JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function countErrors(raw) {
+    if (!raw || typeof raw !== "object")
+        return 0;
+    const data = raw.data ?? raw;
+    const errors = data.errors;
+    return Array.isArray(errors) ? errors.length : 0;
+}
+function countConsoleErrors(raw) {
+    if (!raw || typeof raw !== "object")
+        return 0;
+    const data = raw.data ?? raw;
+    const messages = data.messages;
+    if (!Array.isArray(messages))
+        return 0;
+    return messages.filter((msg) => msg.type === "error" || msg.type === "warning").length;
+}
+async function harFailures(file) {
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    try {
+        const har = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+        const entries = har.log?.entries ?? [];
+        return entries
+            .filter((entry) => (entry.response?.status ?? 0) >= 400)
+            .slice(0, 20)
+            .map((entry) => `${entry.response?.status} ${entry.request?.method} ${entry.request?.url}`);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/trace-store.js

@@ -0,0 +1,227 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertTraceId = assertTraceId;
+exports.commandLabel = commandLabel;
+exports.listTraces = listTraces;
+exports.getTrace = getTrace;
+exports.getTraceFromDir = getTraceFromDir;
+exports.traceFile = traceFile;
+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("../cli/paths");
+const ID_RE = /^[a-zA-Z0-9._-]+$/;
+function assertTraceId(id) {
+    if (!ID_RE.test(id))
+        throw new Error("Invalid trace id");
+}
+function commandLabel(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? "";
+        if (token === "--session" || token === "--headed" || token === "--idle-timeout") {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--session=") || token === "--json")
+            continue;
+        out.push(token);
+    }
+    return out.join(" ") || argv.join(" ");
+}
+async function listTraces() {
+    const root = (0, paths_1.tracesDir)();
+    if (!(0, node_fs_1.existsSync)(root))
+        return [];
+    const names = await (0, promises_1.readdir)(root);
+    const traces = [];
+    for (const id of names) {
+        if (!ID_RE.test(id))
+            continue;
+        const meta = await readMeta(id);
+        if (meta)
+            traces.push(meta);
+    }
+    traces.sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0));
+    return traces;
+}
+async function getTrace(id) {
+    assertTraceId(id);
+    return getTraceFromDir(node_path_1.default.join((0, paths_1.tracesDir)(), id));
+}
+async function getTraceFromDir(dir) {
+    const resolved = node_path_1.default.resolve(dir);
+    const id = node_path_1.default.basename(resolved);
+    const meta = await readMetaAt(resolved, id);
+    if (!meta)
+        return null;
+    const commands = await readCommands(resolved);
+    return {
+        ...meta,
+        commands,
+        console: await readConsole(resolved),
+        errors: await readErrors(resolved),
+        network: await readNetwork(resolved),
+        snapshot: await readText(node_path_1.default.join(resolved, "snapshot.txt")),
+        urls: await readUrls(resolved, commands, meta),
+    };
+}
+function traceFile(id, name) {
+    assertTraceId(id);
+    return node_path_1.default.join((0, paths_1.tracesDir)(), id, name);
+}
+async function readMeta(id) {
+    return readMetaAt(node_path_1.default.join((0, paths_1.tracesDir)(), id), id);
+}
+async function readMetaAt(dir, id) {
+    const file = node_path_1.default.join(dir, "meta.json");
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    try {
+        const raw = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+        const info = await (0, promises_1.stat)(dir);
+        return {
+            id,
+            session: raw.session || id,
+            startedAt: raw.startedAt || info.mtimeMs,
+            endedAt: raw.endedAt,
+            startUrl: raw.startUrl,
+            lastUrl: raw.lastUrl,
+            title: raw.title,
+            status: raw.status || "unknown",
+            dir,
+            hasVideo: (0, node_fs_1.existsSync)(node_path_1.default.join(dir, "session.mp4")),
+            hasPoster: (0, node_fs_1.existsSync)(node_path_1.default.join(dir, "poster.jpg")),
+            hasHar: (0, node_fs_1.existsSync)(node_path_1.default.join(dir, "network.har")),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function readCommands(dir) {
+    const file = node_path_1.default.join(dir, "commands.jsonl");
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    const lines = (await (0, promises_1.readFile)(file, "utf8")).split("\n").filter(Boolean);
+    return lines.flatMap((line, index) => {
+        try {
+            const row = JSON.parse(line);
+            return [
+                {
+                    id: `c${index + 1}`,
+                    ts: row.ts,
+                    argv: row.argv,
+                    label: commandLabel(row.argv),
+                    durationMs: row.durationMs,
+                    exitCode: row.exitCode,
+                    stdout: row.stdout || "",
+                    stderr: row.stderr || "",
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+async function readConsole(dir) {
+    const file = node_path_1.default.join(dir, "console.json");
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    try {
+        const raw = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+        return (raw.data?.messages ?? []).map((msg) => ({
+            type: msg.type || "log",
+            text: msg.text || "",
+            timestamp: msg.timestamp,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readErrors(dir) {
+    const file = node_path_1.default.join(dir, "errors.json");
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    try {
+        const raw = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+        return (raw.data?.errors ?? []).map((err) => ({
+            text: err.text || err.message || JSON.stringify(err),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readNetwork(dir) {
+    const file = node_path_1.default.join(dir, "network.har");
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    try {
+        const har = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+        return (har.log?.entries ?? []).slice(0, 400).map((entry) => ({
+            method: entry.request?.method || "GET",
+            url: entry.request?.url || "",
+            status: entry.response?.status || 0,
+            time: entry.time,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readText(file) {
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    return (0, promises_1.readFile)(file, "utf8");
+}
+async function readUrls(dir, commands, meta) {
+    const points = [];
+    if (meta.startUrl)
+        points.push({ ts: meta.startedAt, url: meta.startUrl });
+    for (const cmd of commands) {
+        const url = openUrlFromArgv(cmd.argv);
+        if (url)
+            points.push({ ts: cmd.ts, url });
+    }
+    const eventsFile = node_path_1.default.join(dir, "events.jsonl");
+    if ((0, node_fs_1.existsSync)(eventsFile)) {
+        const lines = (await (0, promises_1.readFile)(eventsFile, "utf8")).split("\n").filter(Boolean);
+        for (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                const ts = event.timestamp ?? 0;
+                if (event.type === "url" && event.url)
+                    points.push({ ts, url: event.url });
+                if (event.type === "tabs") {
+                    const active = event.tabs?.find((tab) => tab.active) ?? event.tabs?.[0];
+                    if (active?.url)
+                        points.push({ ts, url: active.url });
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    points.sort((a, b) => a.ts - b.ts);
+    const deduped = [];
+    for (const point of points) {
+        const prev = deduped[deduped.length - 1];
+        if (!prev || prev.url !== point.url)
+            deduped.push(point);
+    }
+    return deduped;
+}
+function openUrlFromArgv(argv) {
+    const index = argv.findIndex((token) => token === "open" || token === "goto" || token === "navigate");
+    if (index < 0)
+        return null;
+    const url = argv.slice(index + 1).find((token) => !token.startsWith("-"));
+    return url || null;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentuity/browzer",
+  "version": "0.1.0",
+  "private": false,
+  "description": "agent-browser wrapper that records a replayable debug trace",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "browzer": "./dist/cli/browzer.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "browzer": "node dist/cli/browzer.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agent-browser",
+    "browser",
+    "trace",
+    "replay",
+    "har",
+    "agent",
+    "cli"
+  ],
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}

package/skills/browzer/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: browzer
+description: >
+  Record a replayable agent-browser session by invoking the same CLI as
+  agent-browser through the browzer wrapper. Use instead of agent-browser when
+  the user wants a trace, recording, HAR, console dump, replay, inspect, or
+  post-mortem of a browser run. Triggers: browzer, replay the session, record
+  this browser run, debug the agent browser session, trace, inspect the
+  recording. Use when the user runs /browzer.
+allowed-tools: Bash(browzer:*), Bash(./bin/browzer:*)
+---
+
+# Browzer
+
+`browzer` is `agent-browser` with a trace. Same argv, same snapshot/click loop.
+
+The command is `browzer` on PATH. In the browzer git checkout, use `./bin/browzer` if PATH is not set. Refresh this skill from the installed CLI with `browzer skills get` so instructions match the binary.
+
+Do not run `agent-browser` in the same `--session`. Live watching is `agent-browser dashboard`, not Browzer. For how to snapshot, click, fill, and wait, follow the agent-browser core skill; every process you spawn is `browzer`.
+
+## Session
+
+Before the first command:
+
+```bash
+export AGENT_BROWSER_SESSION="$(browzer session id --scope worktree --prefix task)"
+export AGENT_BROWSER_IDLE_TIMEOUT_MS=0
+```
+
+Then pass `--session "$AGENT_BROWSER_SESSION"` on every `browzer` command, or rely on the env var. Pass `--output <dir>` (or `BROWZER_OUTPUT`) to choose where the trace folder is written; default is the current working directory.
+
+## Drive the browser
+
+```bash
+browzer --session "$AGENT_BROWSER_SESSION" open https://example.com
+browzer --session "$AGENT_BROWSER_SESSION" snapshot -i
+browzer --session "$AGENT_BROWSER_SESSION" click @e1
+browzer --session "$AGENT_BROWSER_SESSION" close
+```
+
+`close` finalizes the trace (video, HAR, console, errors, snapshot, `summary.md`). If inspect is empty, the session was never closed.
+
+`dashboard`, `mcp`, `doctor`, `install`, and `upgrade` pass through and do not create a trace.
+
+## After the run
+
+- Agent: `browzer inspect [id]` (latest if omitted). Read `summary.md` first, then HAR/console/errors in the trace directory (`./<id>/` or `--output`).
+- Human: `browzer replay [id|path]`.
+- List: `browzer traces`.