@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/audit/log.js

@@ -0,0 +1,177 @@
+/**
+ * Cross-agent, tamper-evident audit log of every dispatched run (issue #347).
+ *
+ * Every run that reaches the single dispatch chokepoint in `agents run`
+ * (src/commands/exec.ts) appends ONE record here. Records form a hash chain:
+ * each record embeds the previous record's `hash` as `prevHash`, and its own
+ * `hash` is `sha256(canonicalJSON(record-without-hash))`. Because `prevHash`
+ * is part of the hashed payload, rewriting or reordering any record breaks the
+ * chain from that point forward — `verifyAuditChain()` reports the first index
+ * that fails to reproduce.
+ *
+ * Storage is append-only JSONL under the durable-runtime bucket
+ * (`~/.agents/.history/audit/log.jsonl`), one record per line. `.history/` is
+ * machine-local, gitignored, and NEVER synced by `agents repo push/pull` — so
+ * the `repo` field (a git remote url that can embed an access token) never
+ * lands in a version-controlled DotAgents repo, and a cross-machine pull can't
+ * splice a foreign chain into this one. The write path is deliberately cheap
+ * and non-fatal: a logging failure must never crash a run (see
+ * `recordDispatchedRun`). Concurrent writers (parallel teams/routines dispatch)
+ * are serialized by an advisory lock file so the chain never forks — see
+ * `appendAuditRecord`.
+ *
+ * Governance context: this is the evidence trail an operator needs to answer
+ * "which agent, at which version, ran against which repo, and did it succeed?"
+ * — the kind of automated-decision logging the EU AI Act (Art. 12) expects of
+ * high-risk systems, kept tamper-evident so the log itself can be trusted.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { sha256 } from '../staleness/fingerprint.js';
+import { getHistoryDir } from '../state.js';
+import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
+/** First record's `prevHash` — a fixed anchor so the chain has a root. */
+export const GENESIS_HASH = 'GENESIS';
+/**
+ * Absolute path to the append-only audit log. Lives under `.history/` — the
+ * durable-but-machine-local runtime bucket that is gitignored and never synced
+ * by `agents repo push/pull`. Keeping it here (not under a top-level, tracked
+ * `~/.agents/` path) means the token-bearing `repo` field can never leak into a
+ * version-controlled DotAgents repo, and no cross-machine pull can fork the chain.
+ */
+export function getAuditLogPath() {
+    return path.join(getHistoryDir(), 'audit', 'log.jsonl');
+}
+/**
+ * Deterministic JSON: object keys sorted recursively so the same logical
+ * record always serializes to the same bytes (hashing must be reproducible
+ * across processes and machines). Values here are all primitives, but the
+ * recursion keeps it correct if the record ever nests.
+ */
+function canonicalJSON(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJSON).join(',') + ']';
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalJSON(obj[k])).join(',') + '}';
+}
+/** Compute the sealing hash for a record whose `prevHash` is already set. */
+function hashRecord(record) {
+    return sha256(canonicalJSON(record));
+}
+/** Read + parse every record in the log, oldest-first. Missing file → []. */
+function readRecords(logPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(logPath, 'utf-8');
+    }
+    catch {
+        return []; // no log yet
+    }
+    const records = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        records.push(JSON.parse(trimmed));
+    }
+    return records;
+}
+/**
+ * Append one record to the hash chain and return it. Links to the previous
+ * record's `hash` (or `GENESIS_HASH` for the first), computes the sealing
+ * hash, and writes a single JSONL line. Synchronous so the record is durable
+ * before the caller proceeds.
+ *
+ * Read-last-hash + append run under the canonical advisory file lock
+ * (`withFileLock`, backed by proper-lockfile). Without it, two concurrent
+ * writers — the norm under parallel teams/routines dispatch — both read the
+ * same last hash and both write `prevHash=H`, forking the chain into a false
+ * "tampered" verdict. The lock forces a total order so every record links off
+ * the genuinely-previous one. `ensureLockTarget` creates the file first because
+ * proper-lockfile locks an existing path.
+ */
+export function appendAuditRecord(entry, logPath = getAuditLogPath()) {
+    ensureLockTarget(logPath);
+    return withFileLock(logPath, () => {
+        const existing = readRecords(logPath);
+        const prevHash = existing.length ? existing[existing.length - 1].hash : GENESIS_HASH;
+        const unsealed = { ...entry, prevHash };
+        const record = { ...unsealed, hash: hashRecord(unsealed) };
+        fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+        return record;
+    });
+}
+/**
+ * Walk the chain and confirm every record reproduces. A record is valid when
+ * (a) its `prevHash` matches the prior record's `hash` (GENESIS for the first)
+ * AND (b) recomputing its sealing hash from its own fields reproduces the
+ * stored `hash`. Returns the first failing index in `brokenAt`.
+ */
+export function verifyAuditChain(logPath = getAuditLogPath()) {
+    let records;
+    try {
+        records = readRecords(logPath);
+    }
+    catch (err) {
+        // A line that won't even parse is itself tamper evidence — the log is corrupt.
+        return { ok: false, brokenAt: 0 };
+    }
+    let expectedPrev = GENESIS_HASH;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.prevHash !== expectedPrev)
+            return { ok: false, brokenAt: i };
+        const { hash, ...unsealed } = r;
+        if (hashRecord(unsealed) !== hash)
+            return { ok: false, brokenAt: i };
+        expectedPrev = r.hash;
+    }
+    return { ok: true };
+}
+/** Read the whole chain, oldest-first. Exposed for `agents audit list`. */
+export function readAuditLog(logPath = getAuditLogPath()) {
+    return readRecords(logPath);
+}
+/**
+ * Resolve a stable repo label for a run: the git remote origin url when the
+ * cwd is inside a repo with one, otherwise the cwd itself. Best-effort — any
+ * failure falls back to the cwd.
+ */
+function repoLabel(cwd) {
+    try {
+        const res = spawnSync('git', ['-C', cwd, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+            timeout: 2000,
+        });
+        const url = res.status === 0 ? res.stdout.trim() : '';
+        return url || cwd;
+    }
+    catch {
+        return cwd;
+    }
+}
+/**
+ * Record ONE dispatched run at the single exec chokepoint. Non-fatal by
+ * contract: any failure is caught and warned, never thrown — an audit-log
+ * hiccup must not crash a run that already finished.
+ */
+export function recordDispatchedRun(run) {
+    try {
+        appendAuditRecord({
+            ts: new Date().toISOString(),
+            agent: run.agent,
+            version: run.version,
+            repo: repoLabel(run.cwd),
+            mode: run.mode,
+            outcome: run.exitCode === 0 ? 'ok' : 'fail',
+            exit: run.exitCode,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`[agents] audit log write failed: ${err.message}\n`);
+    }
+}

package/dist/lib/auto-pull.js

@@ -14,6 +14,7 @@ import * as path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getFetchCacheDir } from './state.js';
+import { backgroundSpawnOptions } from './platform/process.js';
 /** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
     return getFetchCacheDir();
@@ -38,7 +39,7 @@ export function spawnDetachedSync() {
         return;
     try {
         const child = spawn(process.execPath, [workerPath], {
-            detached: true,
+            ...backgroundSpawnOptions(),
             stdio: 'ignore',
             env: process.env,
         });

package/dist/lib/browser/cdp.js

@@ -219,7 +219,11 @@ export function verifyBrowserIdentity(reported, expected, port, host = 'localhos
         // to a Comet instance doesn't trip a false "identity mismatch".
         comet: ['comet', 'chrome'],
         brave: ['brave', 'brave-browser', 'chrome'],
-        edge: ['edge', 'microsoft-edge', 'msedge', 'chrome'],
+        // Windows/Chromium Edge reports its /json/version "Browser" field as
+        // "Edg/<version>" (the `Edg` token, not `Edge`), which normalizeBrowserName
+        // reduces to "edg". Accept it so attaching to a real Edge doesn't trip a
+        // false identity mismatch (the profile enum only allows "edge").
+        edge: ['edge', 'edg', 'microsoft-edge', 'msedge', 'chrome'],
     };
     const accepted = matches[expected] || [expected];
     if (accepted.includes(reported))

package/dist/lib/browser/chrome.d.ts

@@ -36,6 +36,16 @@ export declare function getRunningChromeInfo(profileName: string): {
     pid: number;
     port: number;
 } | null;
+/**
+ * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
+ * (lsof doesn't exist there). Returns false on any tooling error so port
+ * allocation degrades to "assume free" rather than throwing.
+ *
+ * Exported as the canonical cross-platform probe — `findFreeProfilePort`
+ * (profiles.ts) must use this rather than shelling out to lsof directly,
+ * or every port scans as free on Windows.
+ */
+export declare function isPortInUse(port: number): boolean;
 export declare function allocatePort(): number;
 export interface PortOccupant {
     pid: number;

package/dist/lib/browser/chrome.js

@@ -39,7 +39,11 @@ const BROWSER_PATHS = {
             `${WIN_PROGRAMFILES_X86}\\Google\\Chrome\\Application\\chrome.exe`,
             `${WIN_LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
         ],
-        comet: [],
+        comet: [
+            `${WIN_PROGRAMFILES}\\Perplexity\\Comet\\Application\\comet.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Perplexity\\Comet\\Application\\comet.exe`,
+            `${WIN_LOCALAPPDATA}\\Perplexity\\Comet\\Application\\comet.exe`,
+        ],
         chromium: [
             `${WIN_LOCALAPPDATA}\\Chromium\\Application\\chrome.exe`,
         ],
@@ -155,8 +159,8 @@ export function findBrowserPath(browserType, customBinary) {
             return resolveBrowserBinary(p);
         }
     }
-    if (browserType === 'comet' && platform !== 'darwin') {
-        throw new Error('Browser "comet" is macOS-only (Comet is a macOS Chromium fork). Use chrome, chromium, brave, or edge on this platform.');
+    if (browserType === 'comet' && platform === 'linux') {
+        throw new Error('Browser "comet" is not available on Linux (Comet ships macOS and Windows builds only). Use chrome, chromium, brave, or edge on this platform.');
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
@@ -171,7 +175,7 @@ const DEFAULT_BROWSER_PRIORITY = {
     linux: ['chrome', 'chromium', 'brave', 'edge'],
     // Windows: Edge is preinstalled on every supported build, so it's the
     // reliable always-there default.
-    win32: ['edge', 'chrome', 'brave'],
+    win32: ['edge', 'chrome', 'brave', 'comet'],
 };
 /**
  * Walk the per-platform priority list and return the first browser that's
@@ -290,11 +294,11 @@ export function killChrome(pid) {
         // stop first (no /F → posts WM_CLOSE), and only force-kill the tree if that
         // fails or the process is still around.
         try {
-            execFileSync('taskkill', ['/pid', String(pid)], { stdio: 'ignore' });
+            execFileSync('taskkill', ['/pid', String(pid)], { stdio: 'ignore', windowsHide: true });
         }
         catch {
             try {
-                execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' });
+                execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
             }
             catch {
                 // Process already dead
@@ -345,13 +349,18 @@ function sleep(ms) {
  * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
  * (lsof doesn't exist there). Returns false on any tooling error so port
  * allocation degrades to "assume free" rather than throwing.
+ *
+ * Exported as the canonical cross-platform probe — `findFreeProfilePort`
+ * (profiles.ts) must use this rather than shelling out to lsof directly,
+ * or every port scans as free on Windows.
  */
-function isPortInUse(port) {
+export function isPortInUse(port) {
     if (process.platform === 'win32') {
         try {
             const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
                 encoding: 'utf8',
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             });
             // Lines look like: "  TCP    0.0.0.0:9200    0.0.0.0:0    LISTENING    1234"
             return out.split('\n').some((line) => {
@@ -393,6 +402,7 @@ export function getPortOccupant(port) {
             const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], {
                 encoding: 'utf8',
                 stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
             });
             let pid = 0;
             for (const line of out.split('\n')) {
@@ -410,6 +420,7 @@ export function getPortOccupant(port) {
                 const tl = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
                     encoding: 'utf8',
                     stdio: ['ignore', 'pipe', 'ignore'],
+                    windowsHide: true,
                 });
                 const m = tl.match(/^"([^"]+)"/);
                 if (m)

package/dist/lib/browser/drivers/ssh.d.ts

@@ -53,7 +53,15 @@ export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string,
  * (Get-NetTCPConnection → Stop-Process).
  */
 export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
+export declare function ensureRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
 export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
+/**
+ * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
+ * WMI-spawned (Windows) / detached (posix) browser process is not orphaned when
+ * the ssh tunnel is torn down — killing only the tunnel left it running on
+ * win-mini after every `browser stop`. Best-effort: never rejects.
+ */
+export declare function killRemoteBrowser(user: string, host: string, remoteOs: RemoteOs, port: number): Promise<void>;
 /**
  * Identify whether a pid listening on our target local port is an SSH
  * tunnel WE would have spawned for `host:remotePort`. Used so that two

package/dist/lib/browser/drivers/ssh.js

@@ -48,12 +48,12 @@ export async function connectSSH(endpoint, profile) {
             `is already in use by ${occupant.command} (pid ${occupant.pid}). ` +
             `Either kill that process (\`kill ${occupant.pid}\`) or change the profile's port.`);
     }
-    try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
-    }
-    catch {
-        // Browser may already be running, continue
-    }
+    // A non-zero remote exit (missing exe, auth failure, bad launch) now rejects
+    // with the captured stderr and propagates. An already-running browser exits 0
+    // (the launch backgrounds/WMI-spawns regardless), so this does not spuriously
+    // fail the reconnect path — only genuine launch failures reach the caller
+    // instead of being swallowed and mis-reported later as a tunnel timeout.
+    await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
     let tunnel;
     if (occupant) {
         // Reuse the existing tunnel rather than spawning a duplicate.
@@ -102,6 +102,11 @@ export async function connectSSH(endpoint, profile) {
         pid: tunnelPid,
         cleanup: () => {
             cdp.close();
+            // Kill the remote browser BEFORE tearing down the tunnel. It runs on a
+            // separate ssh connection (independent of the tunnel we're about to
+            // kill), so tunnel teardown can't cut it off. Fire-and-forget — cleanup
+            // stays synchronous, and killRemoteBrowser never rejects.
+            killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
             tunnel.kill();
             clearProfileRuntime(profile.name);
         },
@@ -177,9 +182,9 @@ export function encodePowerShell(script) {
  * registry at runtime rather than relying on a bare `msedge` name.
  */
 export function buildWindowsLaunchScript(browserType, port, customBinary) {
-    let exeExpr;
+    let exeStmts;
     if (customBinary) {
-        exeExpr = psSingleQuote(customBinary);
+        exeStmts = [`$exe = ${psSingleQuote(customBinary)}`];
     }
     else if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -188,13 +193,24 @@ export function buildWindowsLaunchScript(browserType, port, customBinary) {
         const exeKey = WIN_BROWSER_APPPATH[browserType];
         if (!exeKey)
             throw new Error(`Unknown browser type for windows remote: ${browserType}`);
-        exeExpr =
-            `(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}').'(default)'`;
+        const appPath = `SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}`;
+        // Per-user installs — the DEFAULT for Edge and Chrome — register App Paths
+        // under HKCU, not HKLM, so an HKLM-only lookup silently missed them and the
+        // launch failed. Resolve from HKLM first, then fall through to HKCU.
+        // Windows PowerShell 5.1 (what `powershell.exe` is) has no `??`, so the
+        // fallback is an explicit `if`. A missing exe `throw`s so the failure rides
+        // out as a non-zero ssh exit (surfaced by ensureRemoteBrowser) instead of a
+        // silent empty launch.
+        exeStmts = [
+            `$exe = (Get-ItemProperty 'HKLM:\\${appPath}' -EA SilentlyContinue).'(default)'`,
+            `if (-not $exe) { $exe = (Get-ItemProperty 'HKCU:\\${appPath}' -EA SilentlyContinue).'(default)' }`,
+            `if (-not $exe) { throw 'browser exe not found in HKLM/HKCU App Paths: ${exeKey}' }`,
+        ];
     }
     // Keep the `--remote-allow-origins=http://127.0.0.1:${port}` literal in
     // source — a test asserts CDP is never opened to `*`.
     return [
-        `$exe = ${exeExpr}`,
+        ...exeStmts,
         `$cl = '"' + $exe + '" --remote-debugging-port=${port}` +
             ` --remote-allow-origins=http://127.0.0.1:${port}` +
             ` --disable-background-timer-throttling --user-data-dir="' + $env:TEMP + '\\agents-browser-${port}"'`,
@@ -242,21 +258,56 @@ export function buildKillCmd(remoteOs, port) {
     }
     return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
 }
-async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+export async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
     const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
+        // Capture stderr so a real launch failure (missing exe, auth denied, bad
+        // CreateProcess) surfaces here as a clear error. Previously stdio was
+        // ignored and this resolved on close regardless of exit code, so failures
+        // were swallowed and only re-emerged 8s later as a generic
+        // "SSH tunnel failed to establish".
         const child = spawn('ssh', [
             `${user}@${host}`,
             '-o',
             'BatchMode=yes',
             remoteCmd,
-        ], { stdio: 'ignore' });
-        child.on('close', () => resolve());
-        child.on('error', reject);
-        setTimeout(() => {
+        ], { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+        let stderr = '';
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            // ssh is still running the backgrounding launch command past our window.
+            // Killing the local ssh client does NOT reap the WMI/detached remote
+            // browser, so treat this as launched and let waitForPort confirm.
             child.kill();
             resolve();
         }, 2000);
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code && code !== 0) {
+                const detail = stderr.trim();
+                reject(new Error(`Remote browser launch failed on ${host} (ssh exit ${code})` +
+                    (detail ? `: ${detail}` : '')));
+            }
+            else {
+                resolve();
+            }
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
     });
 }
 export async function restartRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
@@ -266,10 +317,20 @@ export async function restartRemoteBrowser(user, host, browserType, port, remote
     await ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary);
     await sleep(1500);
 }
+/**
+ * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
+ * WMI-spawned (Windows) / detached (posix) browser process is not orphaned when
+ * the ssh tunnel is torn down — killing only the tunnel left it running on
+ * win-mini after every `browser stop`. Best-effort: never rejects.
+ */
+export function killRemoteBrowser(user, host, remoteOs, port) {
+    return runSSHCommand(user, host, buildKillCmd(remoteOs, port));
+}
 function runSSHCommand(user, host, cmd) {
     return new Promise((resolve) => {
         const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {
             stdio: 'ignore',
+            windowsHide: true,
         });
         child.on('close', () => resolve());
         child.on('error', () => resolve());

package/dist/lib/browser/har.d.ts

@@ -0,0 +1,84 @@
+import type { NetworkRequest } from './types.js';
+/**
+ * Minimal HAR 1.2 shapes. We only produce what our request buffer can back —
+ * fields the buffer doesn't populate (headers, cookies, bodies, timings) are
+ * emitted with the spec-mandated empty defaults or `-1` sentinels so validators
+ * still accept the document.
+ *
+ * Spec: http://www.softwareishard.com/blog/har-12-spec/
+ */
+export interface HarLog {
+    version: '1.2';
+    creator: {
+        name: string;
+        version: string;
+    };
+    pages: HarPage[];
+    entries: HarEntry[];
+}
+export interface HarPage {
+    startedDateTime: string;
+    id: string;
+    title: string;
+    pageTimings: {
+        onContentLoad: number;
+        onLoad: number;
+    };
+}
+export interface HarEntry {
+    startedDateTime: string;
+    time: number;
+    request: HarRequest;
+    response: HarResponse;
+    cache: Record<string, never>;
+    timings: HarTimings;
+}
+export interface HarRequest {
+    method: string;
+    url: string;
+    httpVersion: string;
+    cookies: never[];
+    headers: never[];
+    queryString: Array<{
+        name: string;
+        value: string;
+    }>;
+    headersSize: number;
+    bodySize: number;
+}
+export interface HarResponse {
+    status: number;
+    statusText: string;
+    httpVersion: string;
+    cookies: never[];
+    headers: never[];
+    content: {
+        size: number;
+        mimeType: string;
+        text?: string;
+    };
+    redirectURL: string;
+    headersSize: number;
+    bodySize: number;
+}
+export interface HarTimings {
+    send: number;
+    wait: number;
+    receive: number;
+}
+export interface BuildHarOptions {
+    creatorName?: string;
+    creatorVersion?: string;
+}
+/**
+ * Serialize a buffered `NetworkRequest[]` into a HAR 1.2 document.
+ *
+ * The buffer only records `url`, `method`, `status`, `mimeType`, `timestamp`.
+ * Everything downstream — cookies, headers, bodies, per-phase timings — is
+ * unknown and must be emitted as the spec's "unknown" sentinels: `-1` for
+ * sizes / timings, empty arrays for cookies / headers. HAR validators accept
+ * this shape (browsers do the same for opaque cross-origin responses).
+ */
+export declare function buildHar(requests: NetworkRequest[], opts?: BuildHarOptions): {
+    log: HarLog;
+};

package/dist/lib/browser/har.js

@@ -0,0 +1,77 @@
+/**
+ * Serialize a buffered `NetworkRequest[]` into a HAR 1.2 document.
+ *
+ * The buffer only records `url`, `method`, `status`, `mimeType`, `timestamp`.
+ * Everything downstream — cookies, headers, bodies, per-phase timings — is
+ * unknown and must be emitted as the spec's "unknown" sentinels: `-1` for
+ * sizes / timings, empty arrays for cookies / headers. HAR validators accept
+ * this shape (browsers do the same for opaque cross-origin responses).
+ */
+export function buildHar(requests, opts = {}) {
+    const creator = {
+        name: opts.creatorName ?? 'agents-cli',
+        version: opts.creatorVersion ?? '',
+    };
+    const startedAt = requests.length > 0 ? Math.min(...requests.map((r) => r.timestamp)) : Date.now();
+    const page = {
+        startedDateTime: new Date(startedAt).toISOString(),
+        id: 'page_1',
+        title: 'agents browser session',
+        pageTimings: { onContentLoad: -1, onLoad: -1 },
+    };
+    const entries = requests.map((r) => {
+        const queryString = extractQueryString(r.url);
+        const mimeType = r.mimeType ?? '';
+        return {
+            startedDateTime: new Date(r.timestamp).toISOString(),
+            time: -1,
+            request: {
+                method: r.method,
+                url: r.url,
+                httpVersion: 'HTTP/1.1',
+                cookies: [],
+                headers: [],
+                queryString,
+                headersSize: -1,
+                bodySize: -1,
+            },
+            response: {
+                status: r.status ?? 0,
+                statusText: '',
+                httpVersion: 'HTTP/1.1',
+                cookies: [],
+                headers: [],
+                content: { size: -1, mimeType },
+                redirectURL: '',
+                headersSize: -1,
+                bodySize: -1,
+            },
+            cache: {},
+            timings: { send: -1, wait: -1, receive: -1 },
+        };
+    });
+    return {
+        log: {
+            version: '1.2',
+            creator,
+            pages: [page],
+            entries,
+        },
+    };
+}
+/**
+ * Pull `?a=1&b=2` off a URL into HAR's `queryString` array. Returns `[]` when
+ * the URL has no query or fails to parse (opaque URLs like `data:` shouldn't
+ * abort the whole HAR).
+ */
+function extractQueryString(url) {
+    try {
+        const u = new URL(url);
+        const out = [];
+        u.searchParams.forEach((value, name) => out.push({ name, value }));
+        return out;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/browser/ipc.d.ts

@@ -8,6 +8,9 @@ export declare class BrowserDaemonNotRunningError extends Error {
 }
 export declare function formatBrowserDaemonNotRunningError(): string;
 export declare function getSocketPath(): string;
+/** Is the daemon reachable? A real connect probe on every platform — a socket
+ * file existing on disk is not proof a daemon is listening on it. */
+export declare function isDaemonReachable(): Promise<boolean>;
 export declare class BrowserIPCServer {
     private server;
     private service;