harnery 0.0.1 → 0.2.0

package/dist/core/hooks/resolve/owner.js

@@ -0,0 +1,140 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+/**
+ * Resolve the canonical `instance_id` for the current hook invocation.
+ *
+ * Precedence:
+ *
+ *   1. `HARNERY_AGENT_COORD_OWNER` env var. Set by harness adapters when they know
+ *      the owner identity at spawn time (Codex's apply_patch tool path uses
+ *      this).
+ *   2. Hook payload fields, in order: `agent_id` → `subagent_id` →
+ *      `session_id` → `conversation_id`. agent_id wins for CC subagent
+ *      events; session_id is the parent-shape default.
+ *   3. PID-map lookup at `.harnery/pid-map/<pid>` for our own pid, then ppid
+ *      chain (up to 20 hops).
+ *
+ * Returns null when nothing resolves. Callers must treat null as "no owner"
+ * and skip the event (Phase 2 fail-safe; Phase 3 will mint a temporary owner
+ * for orphan events).
+ */
+export function resolveOwner(opts) {
+    const env = coordEnv("AGENT_COORD_OWNER");
+    if (env && env.length > 0) {
+        return { instance_id: env, source: "env" };
+    }
+    if (opts.payload) {
+        for (const key of ["agent_id", "subagent_id", "session_id", "conversation_id"]) {
+            const v = opts.payload[key];
+            if (typeof v === "string" && v.length > 0) {
+                return { instance_id: v, source: "payload" };
+            }
+        }
+    }
+    // Pid-map ancestor walk. Start at own pid (the bash wrapper's bun child),
+    // walk up through ppids. The pid-map is stamped keyed by the harness PID, so
+    // we'll usually find it 1-3 hops up.
+    const pidmap = join(opts.coordRoot, ".harnery", "pid-map");
+    if (existsSync(pidmap)) {
+        let pid = process.pid;
+        let hops = 0;
+        while (hops < 20) {
+            const file = join(pidmap, String(pid));
+            if (existsSync(file)) {
+                try {
+                    const row = readFileSync(file, "utf8").trim();
+                    // Row shape: "<instance_id>" or "<instance_id>\t<platform>"
+                    const owner = row.split("\t")[0];
+                    if (owner && owner.length > 0) {
+                        return {
+                            instance_id: owner,
+                            source: hops === 0 ? "pidmap-self" : "pidmap-ancestor",
+                        };
+                    }
+                }
+                catch {
+                    /* keep walking */
+                }
+            }
+            const ppid = readPpid(pid);
+            if (!ppid || ppid === 0 || ppid === 1)
+                break;
+            pid = ppid;
+            hops++;
+        }
+    }
+    return null;
+}
+function readPpid(pid) {
+    // Linux/WSL: /proc/<pid>/status carries `PPid:`. Falls back to null on
+    // macOS or any read failure; ancestor walk just terminates.
+    try {
+        const status = readFileSync(`/proc/${pid}/status`, "utf8");
+        for (const line of status.split("\n")) {
+            if (line.startsWith("PPid:")) {
+                const n = Number(line.split(/\s+/)[1]);
+                return Number.isFinite(n) ? n : null;
+            }
+        }
+    }
+    catch {
+        /* fallthrough */
+    }
+    return null;
+}
+/**
+ * Find the parent owner for a subagent invocation. The per-shell marker at
+ * `.harnery/shells/<pid>` is set by `sub-agent-start` and removed by
+ * `sub-agent-stop`.
+ *
+ * Phase 2 stub: the marker file isn't written yet, so we return null in most
+ * cases. Phase 2 callers can pass through.
+ */
+export function readShellMarker(coordRoot, pid) {
+    const path = join(coordRoot, ".harnery", "shells", String(pid));
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the heartbeat-recorded `agent_id` for an owner if it exists. */
+export function readAgentIdForOwner(coordRoot, instanceId) {
+    const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+    if (!existsSync(path))
+        return null;
+    try {
+        const body = readFileSync(path, "utf8");
+        const data = JSON.parse(body);
+        return data.agent_id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Diagnostic: list of pid-map entries (for debugging). */
+export function listPidmap(coordRoot) {
+    const dir = join(coordRoot, ".harnery", "pid-map");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        const pid = Number(f);
+        if (!Number.isFinite(pid))
+            continue;
+        try {
+            const row = readFileSync(join(dir, f), "utf8").trim();
+            const owner = row.split("\t")[0];
+            if (owner)
+                out.push({ pid, owner });
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}

package/dist/core/hooks/resolve/transcript.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
+ * the most-recent assistant turn. Used by `turn.stop` events to populate
+ * `status_box_present`.
+ *
+ * Cheap by default: caps the read at 256KB tailed from the file, since the
+ * status box (if present) is always near the end of the most-recent turn.
+ * Phase 2 doesn't try to fight the flush race: if the last assistant block
+ * hasn't been written yet at Stop-hook time, status_box_present is `false`
+ * and Phase 5 verdict path catches the race via a single retry.
+ */
+export declare function scanStatusBoxPresent(transcriptPath: string | undefined): boolean;
+/**
+ * Resolve the agent's model from a CC-style JSONL transcript by reading the
+ * most-recent assistant message's `message.model`. Claude Code's SessionStart
+ * payload omits `model` (Codex + Cursor supply it directly), so this is the
+ * fallback that lets `session.start` / `turn.stop` populate the heartbeat's
+ * model field once the transcript has at least one assistant turn.
+ *
+ * Tail-reads the same 256KB window as the status-box scan and walks lines from
+ * the end, returning the first real model id found. Synthetic placeholders
+ * (`<synthetic>`) and empty values are skipped. Returns undefined when the
+ * transcript is missing/empty (e.g. a fresh session's first SessionStart).
+ */
+export declare function scanTranscriptModel(transcriptPath: string | undefined): string | undefined;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/core/hooks/resolve/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/resolve/transcript.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAsB1F"}

package/dist/core/hooks/resolve/transcript.js

@@ -0,0 +1,73 @@
+import { existsSync, statSync } from "node:fs";
+/**
+ * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
+ * the most-recent assistant turn. Used by `turn.stop` events to populate
+ * `status_box_present`.
+ *
+ * Cheap by default: caps the read at 256KB tailed from the file, since the
+ * status box (if present) is always near the end of the most-recent turn.
+ * Phase 2 doesn't try to fight the flush race: if the last assistant block
+ * hasn't been written yet at Stop-hook time, status_box_present is `false`
+ * and Phase 5 verdict path catches the race via a single retry.
+ */
+export function scanStatusBoxPresent(transcriptPath) {
+    if (!transcriptPath || !existsSync(transcriptPath))
+        return false;
+    const text = tailText(transcriptPath);
+    if (text === undefined)
+        return false;
+    // The box is rendered as a text content block by the assistant; we look
+    // for the prefix on any line of the trailing window.
+    return text.includes("┌─ agent-");
+}
+/**
+ * Resolve the agent's model from a CC-style JSONL transcript by reading the
+ * most-recent assistant message's `message.model`. Claude Code's SessionStart
+ * payload omits `model` (Codex + Cursor supply it directly), so this is the
+ * fallback that lets `session.start` / `turn.stop` populate the heartbeat's
+ * model field once the transcript has at least one assistant turn.
+ *
+ * Tail-reads the same 256KB window as the status-box scan and walks lines from
+ * the end, returning the first real model id found. Synthetic placeholders
+ * (`<synthetic>`) and empty values are skipped. Returns undefined when the
+ * transcript is missing/empty (e.g. a fresh session's first SessionStart).
+ */
+export function scanTranscriptModel(transcriptPath) {
+    if (!transcriptPath || !existsSync(transcriptPath))
+        return undefined;
+    const text = tailText(transcriptPath);
+    if (!text)
+        return undefined;
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim();
+        if (!line?.includes('"model"'))
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            const model = obj.message?.model ?? obj.model;
+            if (typeof model === "string" && model.length > 0 && !model.startsWith("<")) {
+                return model;
+            }
+        }
+        catch {
+            // Partial/truncated first line of the tail window; skip it.
+        }
+    }
+    return undefined;
+}
+/** Tail-read up to 256KB from the end of a file as UTF-8, or undefined on error. */
+function tailText(path) {
+    try {
+        const size = statSync(path).size;
+        const start = Math.max(0, size - 256 * 1024);
+        const fd = require("node:fs").openSync(path, "r");
+        const buf = Buffer.alloc(size - start);
+        require("node:fs").readSync(fd, buf, 0, buf.length, start);
+        require("node:fs").closeSync(fd);
+        return buf.toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public library entry. Re-exports the harn-able surface for consumers that
+ * import harnery as a library rather than calling the CLI.
+ *
+ * Examples of intended consumption:
+ *   import { createHarneryProgram } from 'harnery';     // CLI composition
+ *   import { evaluateClaim } from 'harnery/core/agents'; // verdict rule directly
+ *   import type { Heartbeat } from 'harnery/core/agents'; // schema types
+ *
+ * Heavy modules (web UI, hook scripts) are not re-exported from here; they're
+ * reachable via their own subpath entries in package.json#exports.
+ */
+export type { HarneryContextOpts, HarneryProgramContext } from "./commander.js";
+export { createHarneryProgram } from "./commander.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public library entry. Re-exports the harn-able surface for consumers that
+ * import harnery as a library rather than calling the CLI.
+ *
+ * Examples of intended consumption:
+ *   import { createHarneryProgram } from 'harnery';     // CLI composition
+ *   import { evaluateClaim } from 'harnery/core/agents'; // verdict rule directly
+ *   import type { Heartbeat } from 'harnery/core/agents'; // schema types
+ *
+ * Heavy modules (web UI, hook scripts) are not re-exported from here; they're
+ * reachable via their own subpath entries in package.json#exports.
+ */
+export { createHarneryProgram } from "./commander.js";

package/dist/lib/agent-browser/client.d.ts

@@ -0,0 +1,99 @@
+import { type CookieJar } from "../cookies/index.js";
+/**
+ * Thin wrapper over Vercel Labs' `agent-browser` Rust CLI.
+ *
+ * agent-browser is a process that wraps a managed Chrome for Testing
+ * binary and exposes verbs over its own daemon (state persists across
+ * invocations within a shell). This wrapper exec's the binary; it does
+ * **not** manage the daemon itself.
+ *
+ * Optional cookie-jar integration: if a CookieJar is passed in the
+ * options, the wrapper will write the jar contents to a temp state file
+ * and `state load` it before any nav, then `cookies get` and merge the
+ * result back into the jar after work is done. Cookies are best-effort:
+ * the wrapper never fails because a load/save round-trip blew up.
+ *
+ * Canonical for `harn browse-ai` (dev side); ready to be the shared core of
+ * the agent-side `browse` wrapper (sandbox side) when that wrapper gets refactored.
+ */
+export interface AgentBrowserOptions {
+    /** Override the binary path. Default: looks up `agent-browser` on PATH. */
+    binary?: string;
+    /** Cookie jar for cross-tool sharing. Pass `null` to skip. */
+    jar?: CookieJar | null;
+    /** Default per-call timeout in ms. Default 60000. */
+    timeoutMs?: number;
+    /** Extra env vars to merge into every spawn. */
+    env?: Record<string, string>;
+    /**
+     * Path used as the `state load` source when seeding cookies into the
+     * agent-browser session. Defaults to a tmp file derived from the jar.
+     */
+    stateFilePath?: string;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    ok: boolean;
+    exitCode: number | null;
+}
+export declare class AgentBrowser {
+    private readonly opts;
+    private cookiesSeeded;
+    constructor(opts?: AgentBrowserOptions);
+    /**
+     * Run an `agent-browser` subcommand. Returns a structured result.
+     * Throws only on spawn failure (e.g., binary not found); non-zero exit
+     * returns ok=false.
+     */
+    exec(args: string[], timeoutMs?: number): ExecResult;
+    /**
+     * Same as `exec` but throws on non-zero exit code, with stderr in the
+     * error message. Use when the caller can't recover from a failure.
+     */
+    execOrThrow(args: string[], timeoutMs?: number): ExecResult;
+    /**
+     * Seed the jar's cookies into the agent-browser session via `state load`.
+     * Called automatically by `open()`. Safe to call multiple times; only
+     * the first call does work.
+     */
+    seedCookies(): void;
+    open(url: string, timeoutMs?: number): ExecResult;
+    snapshot(opts?: {
+        interactive?: boolean;
+    }): string;
+    screenshot(path: string, opts?: {
+        full?: boolean;
+        annotate?: boolean;
+    }): void;
+    click(refOrSelector: string): ExecResult;
+    fill(refOrSelector: string, value: string): ExecResult;
+    press(key: string): ExecResult;
+    wait(selectorOrMs: string): ExecResult;
+    evaluate(script: string): string;
+    /**
+     * Run a semicolon-separated batch of agent-browser sub-commands in a
+     * single session. Each step is exec'd with the same daemon, so state
+     * persists. Returns one ExecResult per step in order.
+     */
+    batch(steps: string[]): ExecResult[];
+    /** Start HAR recording. Pair with `harStop`. */
+    harStart(path: string): ExecResult;
+    /** Stop HAR recording. Returns the same result for symmetry with start. */
+    harStop(path: string): ExecResult;
+    /**
+     * Pull cookies out of the agent-browser session via `cookies get --json`,
+     * merge them into the jar (if one was provided), and persist. Best-effort:
+     * a parse failure or missing jar returns 0 without raising.
+     */
+    syncCookiesToJar(): {
+        saved: number;
+    };
+    /**
+     * Some shell environments leak XDG_CONFIG_HOME into Chrome's crashpad
+     * lookup, which can cause SIGTRAP if the path is read-only (e.g. in
+     * containerized sandbox environments). Strip it here defensively.
+     */
+    private scrubEnv;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/agent-browser/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-browser/client.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EAIf,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAS;gBAElB,IAAI,GAAE,mBAAwB;IAI1C;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU;IAyBpD;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU;IAc3D;;;;OAIG;IACH,WAAW,IAAI,IAAI;IAwBnB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU;IAKjD,QAAQ,CAAC,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,MAAM;IAMtD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAQjF,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU;IAIxC,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU;IAItD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAI9B,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU;IAItC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIhC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE;IAcpC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAIlC,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAIjC;;;;OAIG;IACH,gBAAgB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAkBrC;;;;OAIG;IACH,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/lib/agent-browser/client.js

@@ -0,0 +1,177 @@
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { mergeCookies, } from "../cookies/index.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+export class AgentBrowser {
+    opts;
+    cookiesSeeded = false;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /**
+     * Run an `agent-browser` subcommand. Returns a structured result.
+     * Throws only on spawn failure (e.g., binary not found); non-zero exit
+     * returns ok=false.
+     */
+    exec(args, timeoutMs) {
+        const binary = this.opts.binary ?? "agent-browser";
+        const env = this.scrubEnv();
+        const result = spawnSync(binary, args, {
+            timeout: timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            encoding: "utf8",
+            env,
+        });
+        if (result.error && result.error.code === "ENOENT") {
+            throw new Error(`agent-browser binary not found at "${binary}". Install once with:\n  curl -fsSL https://github.com/vercel-labs/agent-browser/releases/download/v0.25.4/agent-browser-linux-x64 \\\n    -o ~/.local/bin/agent-browser && chmod +x ~/.local/bin/agent-browser\n  agent-browser install`);
+        }
+        if (result.error) {
+            throw result.error;
+        }
+        return {
+            stdout: (result.stdout ?? "").toString(),
+            stderr: (result.stderr ?? "").toString(),
+            ok: result.status === 0,
+            exitCode: result.status,
+        };
+    }
+    /**
+     * Same as `exec` but throws on non-zero exit code, with stderr in the
+     * error message. Use when the caller can't recover from a failure.
+     */
+    execOrThrow(args, timeoutMs) {
+        const result = this.exec(args, timeoutMs);
+        if (!result.ok) {
+            throw new Error(`agent-browser ${args.join(" ")} failed (exit ${result.exitCode ?? "?"}): ${result.stderr.trim() || result.stdout.trim()}`);
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // High-level verbs
+    // -------------------------------------------------------------------------
+    /**
+     * Seed the jar's cookies into the agent-browser session via `state load`.
+     * Called automatically by `open()`. Safe to call multiple times; only
+     * the first call does work.
+     */
+    seedCookies() {
+        if (this.cookiesSeeded)
+            return;
+        if (!this.opts.jar) {
+            this.cookiesSeeded = true;
+            return;
+        }
+        try {
+            const jarStore = this.opts.jar.load();
+            if (jarStore.cookies.length === 0) {
+                this.cookiesSeeded = true;
+                return;
+            }
+            const stateFile = this.opts.stateFilePath ?? `/tmp/bp-agent-browser-state-${process.pid}.json`;
+            writeFileSync(stateFile, JSON.stringify(jarStore, null, 2));
+            this.exec(["state", "load", stateFile], 10_000);
+            this.cookiesSeeded = true;
+        }
+        catch {
+            // Cookie seeding is best-effort; never fail the session because
+            // the jar couldn't be written/loaded.
+            this.cookiesSeeded = true;
+        }
+    }
+    open(url, timeoutMs) {
+        this.seedCookies();
+        return this.execOrThrow(["open", url], timeoutMs);
+    }
+    snapshot(opts = {}) {
+        const args = ["snapshot"];
+        if (opts.interactive)
+            args.push("-i");
+        return this.execOrThrow(args).stdout.trim();
+    }
+    screenshot(path, opts = {}) {
+        const args = ["screenshot"];
+        if (opts.full)
+            args.push("--full");
+        if (opts.annotate)
+            args.push("--annotate");
+        args.push(path);
+        this.execOrThrow(args);
+    }
+    click(refOrSelector) {
+        return this.execOrThrow(["click", refOrSelector]);
+    }
+    fill(refOrSelector, value) {
+        return this.execOrThrow(["fill", refOrSelector, value]);
+    }
+    press(key) {
+        return this.execOrThrow(["press", key]);
+    }
+    wait(selectorOrMs) {
+        return this.execOrThrow(["wait", selectorOrMs]);
+    }
+    evaluate(script) {
+        return this.execOrThrow(["eval", script]).stdout.trim();
+    }
+    /**
+     * Run a semicolon-separated batch of agent-browser sub-commands in a
+     * single session. Each step is exec'd with the same daemon, so state
+     * persists. Returns one ExecResult per step in order.
+     */
+    batch(steps) {
+        this.seedCookies();
+        const results = [];
+        for (const step of steps) {
+            const trimmed = step.trim();
+            if (!trimmed)
+                continue;
+            // Naive shell-like splitting; agent-browser's own argv parser handles
+            // the actual command; we just split on whitespace for the wrapper.
+            const args = trimmed.split(/\s+/);
+            results.push(this.exec(args));
+        }
+        return results;
+    }
+    /** Start HAR recording. Pair with `harStop`. */
+    harStart(path) {
+        return this.execOrThrow(["network", "har", "start", path]);
+    }
+    /** Stop HAR recording. Returns the same result for symmetry with start. */
+    harStop(path) {
+        return this.execOrThrow(["network", "har", "stop", path]);
+    }
+    /**
+     * Pull cookies out of the agent-browser session via `cookies get --json`,
+     * merge them into the jar (if one was provided), and persist. Best-effort:
+     * a parse failure or missing jar returns 0 without raising.
+     */
+    syncCookiesToJar() {
+        if (!this.opts.jar)
+            return { saved: 0 };
+        try {
+            const result = this.exec(["cookies", "get", "--json"], 10_000);
+            if (!result.ok)
+                return { saved: 0 };
+            const parsed = JSON.parse(result.stdout);
+            const cookies = parsed.data?.cookies ?? parsed.cookies ?? [];
+            if (!Array.isArray(cookies) || cookies.length === 0)
+                return { saved: 0 };
+            const jar = this.opts.jar;
+            const store = jar.load();
+            const merged = mergeCookies(store, cookies);
+            jar.save(merged);
+            return { saved: cookies.length };
+        }
+        catch {
+            return { saved: 0 };
+        }
+    }
+    /**
+     * Some shell environments leak XDG_CONFIG_HOME into Chrome's crashpad
+     * lookup, which can cause SIGTRAP if the path is read-only (e.g. in
+     * containerized sandbox environments). Strip it here defensively.
+     */
+    scrubEnv() {
+        const env = { ...process.env, ...this.opts.env };
+        env.XDG_CONFIG_HOME = undefined;
+        return env;
+    }
+}

package/dist/lib/agent-browser/index.d.ts

@@ -0,0 +1,2 @@
+export { AgentBrowser, type AgentBrowserOptions, type ExecResult } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/agent-browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/agent-browser/index.js

@@ -0,0 +1 @@
+export { AgentBrowser } from "./client.js";