@oharness/engine 0.7.1 → 0.9.0

package/dist/browser/host.js

@@ -0,0 +1,311 @@
+import { createServer } from "node:net";
+import { mkdir, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { extensionSocketPath } from "./socket.js";
+/**
+ * The native messaging host: a relay, and deliberately nothing more.
+ *
+ * Chrome starts this process when the extension connects to it, hands it the
+ * extension's messages on stdin, and reads replies from stdout. The harness is
+ * somewhere else entirely and may not be running yet, so this end listens on a
+ * local socket and the harness connects when a browser tool is first called.
+ * That direction matters: Chrome decides when the host exists, so the host
+ * cannot be the one doing the connecting.
+ *
+ * It knows CDP only as envelopes. The relay itself stays in the extension; what
+ * lives here is the one thing the extension cannot do, which is tell several
+ * harnesses apart. A desktop window, a web server and a terminal can each have
+ * conversations driving the same browser, and each numbers its requests from
+ * one. So every request is renumbered on the way in and put back on the way
+ * out, and a tab's events go to the harnesses attached to that tab. Nothing
+ * else about a message is read.
+ *
+ * Framing differs on the two sides and that is the whole of the work here.
+ * Chrome uses a four-byte little-endian length ahead of each UTF-8 JSON
+ * document; the socket side uses newline-delimited JSON, because a socket
+ * consumer in the harness is already reading lines.
+ *
+ * The streams are arguments rather than `process.stdin`/`process.stdout`, and
+ * that is not a testing convenience. stdout here *is* the protocol, and the
+ * engine is not allowed to own a process's standard streams — a library that
+ * printed to them could not be driven by a web UI or a scheduled run. So the
+ * binary in the CLI package hands its own streams in, and this stays mechanism.
+ */
+/** Chrome refuses anything larger, in either direction. */
+const MAX_MESSAGE = 64 * 1024 * 1024;
+/** What Chrome itself accepts from a host. Frames have to fit inside it. */
+const CHROME_LIMIT = 1024 * 1024;
+/** Split Chrome's length-prefixed stream into messages. */
+export class NativeMessageFramer {
+    buffer = Buffer.alloc(0);
+    push(chunk, onMessage, onError) {
+        this.buffer = this.buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buffer, chunk]);
+        for (;;) {
+            if (this.buffer.length < 4)
+                return;
+            const length = this.buffer.readUInt32LE(0);
+            if (length > MAX_MESSAGE) {
+                // Unrecoverable: the stream position is no longer trustworthy.
+                onError?.(`native message of ${length} bytes is beyond anything Chrome sends`);
+                this.buffer = Buffer.alloc(0);
+                return;
+            }
+            if (this.buffer.length < 4 + length)
+                return;
+            const body = this.buffer.subarray(4, 4 + length).toString("utf8");
+            this.buffer = this.buffer.subarray(4 + length);
+            try {
+                onMessage(JSON.parse(body));
+            }
+            catch {
+                onError?.("the extension sent something that is not JSON");
+            }
+        }
+    }
+}
+export function encodeNativeMessage(message) {
+    const body = Buffer.from(JSON.stringify(message), "utf8");
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+export async function runBrowserHost(opts) {
+    const socketPath = opts.socketPath ?? extensionSocketPath();
+    const { input, output } = opts;
+    const warn = opts.warn ?? (() => { });
+    // A socket left behind by a host that was killed would refuse to bind. It is
+    // safe to remove: only one host can be useful at a time, and Chrome starts a
+    // fresh one each time the extension connects.
+    if (!socketPath.startsWith("\\\\")) {
+        await unlink(socketPath).catch(() => { });
+        // Chrome may start the host before OHarness has ever run and made its
+        // directory, and a socket cannot be created in a directory that is not there.
+        await mkdir(path.dirname(socketPath), { recursive: true });
+    }
+    const clients = new Set();
+    /**
+     * The OHarness servers that said where they are (see presence.ts), for the
+     * extension's side panel. Held only in memory, like the tokens in them.
+     */
+    const servers = new Map();
+    /** Keyed by the id the extension sees, which is never one a harness chose. */
+    const inFlight = new Map();
+    /** Which harnesses are attached to which tab, so a tab's events reach them all. */
+    const tabs = new Map();
+    let nextId = 1;
+    const framer = new NativeMessageFramer();
+    const toExtension = (message) => {
+        const encoded = encodeNativeMessage(message);
+        if (encoded.length > CHROME_LIMIT) {
+            warn(`dropping a ${encoded.length} byte message: Chrome's limit is ${CHROME_LIMIT}`);
+            return;
+        }
+        output.write(encoded);
+    };
+    const toClient = (client, message) => {
+        if (!client.destroyed)
+            client.write(`${JSON.stringify(message)}\n`);
+    };
+    // So the extension can say whether anything is using it, and where the
+    // OHarness pages are. Informational: an extension that predates it ignores
+    // a message type it does not know.
+    const announce = () => toExtension({ t: "host", clients: clients.size, servers: [...servers.values()] });
+    const holders = (tabId) => {
+        let set = tabs.get(tabId);
+        if (!set)
+            tabs.set(tabId, (set = new Set()));
+        return set;
+    };
+    /** Let go of a tab for one harness; the debugger stays while anyone still holds it. */
+    const release = (client, tabId) => {
+        const set = tabs.get(tabId);
+        if (!set)
+            return true;
+        set.delete(client);
+        if (set.size > 0)
+            return false;
+        tabs.delete(tabId);
+        return true;
+    };
+    const fromClient = (client, message) => {
+        if (typeof message !== "object" || message === null)
+            return;
+        const envelope = message;
+        const { t, id } = envelope;
+        if (t === "register") {
+            const { url, token, kind, pid } = envelope;
+            if (typeof url !== "string" || typeof token !== "string")
+                return;
+            // Loopback only: this is a page the extension will open with a token
+            // in it, and nothing but this machine's own OHarness belongs there.
+            if (!/^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?\/?$/.test(url))
+                return;
+            servers.set(client, {
+                url: url.replace(/\/$/, ""),
+                token,
+                kind: kind === "desktop" ? "desktop" : "web",
+                ...(typeof pid === "number" ? { pid } : {}),
+            });
+            announce();
+            return;
+        }
+        if (t !== "cdp" && t !== "ctl")
+            return;
+        if (t === "ctl") {
+            const op = typeof envelope["op"] === "string" ? envelope["op"] : "";
+            const tabId = envelope["tabId"] === undefined ? undefined : String(envelope["tabId"]);
+            // A tab another harness already attached needs no second debugger —
+            // Chrome would refuse one anyway. This harness just starts hearing it.
+            if (op === "attach" && tabId && (tabs.get(tabId)?.size ?? 0) > 0) {
+                holders(tabId).add(client);
+                toClient(client, { t: "ctl", id, result: { ok: true } });
+                return;
+            }
+            if (op === "detach" && tabId && !release(client, tabId)) {
+                toClient(client, { t: "ctl", id, result: { ok: true } });
+                return;
+            }
+            if (op === "closeTab" && tabId)
+                tabs.delete(tabId);
+            const hostId = nextId++;
+            inFlight.set(hostId, { client, id, op, ...(tabId ? { tabId } : {}) });
+            toExtension({ ...envelope, id: hostId });
+            return;
+        }
+        // CDP without an id is an event, and harnesses do not send events.
+        if (id === undefined)
+            return;
+        const hostId = nextId++;
+        inFlight.set(hostId, { client, id });
+        toExtension({ ...envelope, id: hostId });
+    };
+    const fromExtension = (message) => {
+        if (typeof message !== "object" || message === null)
+            return;
+        const envelope = message;
+        const { t, id } = envelope;
+        if (typeof id === "number" && (t === "cdp" || t === "ctl")) {
+            const request = inFlight.get(id);
+            if (!request)
+                return;
+            inFlight.delete(id);
+            const { client } = request;
+            if (!client)
+                return;
+            if (t === "ctl" && request.op === "attach" && request.tabId && envelope["error"] === undefined) {
+                holders(request.tabId).add(client);
+            }
+            toClient(client, { ...envelope, id: request.id });
+            return;
+        }
+        if (t === "cdp") {
+            const sessionId = envelope["sessionId"];
+            if (sessionId === undefined) {
+                for (const client of clients)
+                    toClient(client, envelope);
+                return;
+            }
+            const tabId = String(sessionId);
+            const set = tabs.get(tabId);
+            if (!set)
+                return;
+            for (const client of set)
+                toClient(client, envelope);
+            // The debugger is gone — the person closed the banner or the tab — so
+            // nobody holds this tab any more.
+            if (envelope["method"] === "Inspector.detached")
+                tabs.delete(tabId);
+        }
+    };
+    input.on("data", (chunk) => framer.push(chunk, fromExtension, warn));
+    const server = createServer((socket) => {
+        clients.add(socket);
+        announce();
+        let buffer = "";
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            let newline;
+            while ((newline = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line === "")
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    warn("the harness sent something that is not JSON");
+                    continue;
+                }
+                fromClient(socket, parsed);
+            }
+        });
+        let gone = false;
+        const drop = () => {
+            if (gone)
+                return;
+            gone = true;
+            clients.delete(socket);
+            servers.delete(socket);
+            for (const [hostId, request] of inFlight) {
+                if (request.client === socket)
+                    inFlight.delete(hostId);
+            }
+            // A harness that went away without detaching — killed, crashed, its
+            // laptop lid shut — must not leave a banner on the person's tabs.
+            for (const tabId of [...tabs.keys()]) {
+                if (!tabs.get(tabId)?.has(socket))
+                    continue;
+                if (!release(socket, tabId))
+                    continue;
+                const hostId = nextId++;
+                inFlight.set(hostId, { client: undefined, id: undefined });
+                toExtension({ t: "ctl", id: hostId, op: "detach", tabId: Number(tabId) });
+            }
+            announce();
+        };
+        socket.on("close", drop);
+        socket.on("error", drop);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    // Which file is ours. Chrome starts a new host whenever the extension's
+    // worker restarts, often before the old one has noticed its stdin close; the
+    // new one takes the path over, and the old one must not delete it on the way
+    // out, or the host that is still running becomes one nobody can reach.
+    const ours = socketPath.startsWith("\\\\") ? undefined : await stat(socketPath).then((s) => s.ino, () => undefined);
+    // The first thing the extension hears, and its sign the host really started:
+    // connecting a native port succeeds even when the host then fails to launch.
+    announce();
+    // Chrome closing stdin is how a host is told the extension went away.
+    let stopping;
+    const shutdown = () => (stopping ??= (async () => {
+        for (const client of clients)
+            client.end();
+        const current = ours === undefined ? undefined : await stat(socketPath).then((s) => s.ino, () => undefined);
+        if (ours !== undefined && current !== ours) {
+            // Closing a unix socket server unlinks its path, and the path is now
+            // the newer host's. Stop listening without closing; the process running
+            // this exits explicitly (see RunningHost.closed), which leaves it be.
+            server.unref();
+            return;
+        }
+        await new Promise((resolve) => server.close(() => resolve()));
+        if (ours !== undefined)
+            await unlink(socketPath).catch(() => { });
+    })());
+    let settle;
+    const closed = new Promise((resolve) => (settle = resolve));
+    const close = () => shutdown().then(settle);
+    input.on("end", () => void close());
+    input.on("close", () => void close());
+    return { socketPath, closed, close };
+}
+//# sourceMappingURL=host.js.map

package/dist/browser/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/browser/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACrC,4EAA4E;AAC5E,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;AAwBjC,2DAA2D;AAC3D,MAAM,OAAO,mBAAmB;IACtB,MAAM,GAAW,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEzC,IAAI,CAAC,KAAa,EAAE,SAAqC,EAAE,OAAkC;QAC3F,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAClG,SAAS,CAAC;YACR,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO;YACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,MAAM,GAAG,WAAW,EAAE,CAAC;gBACzB,+DAA+D;gBAC/D,OAAO,EAAE,CAAC,qBAAqB,MAAM,wCAAwC,CAAC,CAAC;gBAC/E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM;gBAAE,OAAO;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;YAC/C,IAAI,CAAC;gBACH,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC,+CAA+C,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC;AAWD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAiB;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,EAAE,CAAC;IAC5D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAErC,6EAA6E;IAC7E,6EAA6E;IAC7E,8CAA8C;IAC9C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACzC,sEAAsE;QACtE,8EAA8E;QAC9E,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC;;;OAGG;IACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsE,CAAC;IAC9F,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,mFAAmF;IACnF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC5C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAC7C,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YAClC,IAAI,CAAC,cAAc,OAAO,CAAC,MAAM,oCAAoC,YAAY,EAAE,CAAC,CAAC;YACrF,OAAO;QACT,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,OAAgB,EAAQ,EAAE;QAC1D,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC,CAAC;IACF,uEAAuE;IACvE,2EAA2E;IAC3E,mCAAmC;IACnC,MAAM,QAAQ,GAAG,GAAS,EAAE,CAC1B,WAAW,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAEpF,MAAM,OAAO,GAAG,CAAC,KAAa,EAAe,EAAE;QAC7C,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,uFAAuF;IACvF,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,KAAa,EAAW,EAAE;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACnB,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,OAAgB,EAAQ,EAAE;QAC5D,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAC5D,MAAM,QAAQ,GAAG,OAAkC,CAAC;QACpD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAAC;QAC3B,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YACrB,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC;YAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO;YACjE,qEAAqE;YACrE,oEAAoE;YACpE,IAAI,CAAC,2DAA2D,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,OAAO;YACnF,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;gBAClB,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;gBAC3B,KAAK;gBACL,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK;gBAC5C,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5C,CAAC,CAAC;YACH,QAAQ,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK;YAAE,OAAO;QAEvC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAChB,MAAM,EAAE,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YACtF,oEAAoE;YACpE,uEAAuE;YACvE,IAAI,EAAE,KAAK,QAAQ,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjE,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC3B,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;gBACzD,OAAO;YACT,CAAC;YACD,IAAI,EAAE,KAAK,QAAQ,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;gBACxD,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;gBACzD,OAAO;YACT,CAAC;YACD,IAAI,EAAE,KAAK,UAAU,IAAI,KAAK;gBAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;YACxB,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACtE,WAAW,CAAC,EAAE,GAAG,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QAED,mEAAmE;QACnE,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO;QAC7B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QACxB,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QACrC,WAAW,CAAC,EAAE,GAAG,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAC/C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAC5D,MAAM,QAAQ,GAAG,OAAkC,CAAC;QACpD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAAC;QAE3B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YAC3D,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpB,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;YAC3B,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,IAAI,CAAC,KAAK,KAAK,IAAI,OAAO,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC/F,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;YACD,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAChB,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;YACxC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,KAAK,MAAM,MAAM,IAAI,OAAO;oBAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACzD,OAAO;YACT,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,CAAC,GAAG;gBAAE,OAAO;YACjB,KAAK,MAAM,MAAM,IAAI,GAAG;gBAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACrD,sEAAsE;YACtE,kCAAkC;YAClC,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,oBAAoB;gBAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC;IAE7E,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QAC7C,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,QAAQ,EAAE,CAAC;QACX,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,OAAe,CAAC;YACpB,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC7C,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBACnC,IAAI,IAAI,KAAK,EAAE;oBAAE,SAAS;gBAC1B,IAAI,MAAe,CAAC;gBACpB,IAAI,CAAC;oBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC5B,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,CAAC,6CAA6C,CAAC,CAAC;oBACpD,SAAS;gBACX,CAAC;gBACD,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,GAAG,IAAI,CAAC;YACZ,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACzC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;oBAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzD,CAAC;YACD,oEAAoE;YACpE,kEAAkE;YAClE,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC;oBAAE,SAAS;gBAC5C,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC;oBAAE,SAAS;gBACtC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;gBACxB,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC3D,WAAW,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5E,CAAC;YACD,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC;QACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE;YAC7B,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,wEAAwE;IACxE,6EAA6E;IAC7E,6EAA6E;IAC7E,uEAAuE;IACvE,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAEpH,6EAA6E;IAC7E,6EAA6E;IAC7E,QAAQ,EAAE,CAAC;IAEX,sEAAsE;IACtE,IAAI,QAAmC,CAAC;IACxC,MAAM,QAAQ,GAAG,GAAkB,EAAE,CACnC,CAAC,QAAQ,KAAK,CAAC,KAAK,IAAI,EAAE;QACxB,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,MAAM,CAAC,GAAG,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5G,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,qEAAqE;YACrE,wEAAwE;YACxE,sEAAsE;YACtE,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACpE,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnE,CAAC,CAAC,EAAE,CAAC,CAAC;IAER,IAAI,MAAmB,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,GAAkB,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3D,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/browser/index.d.ts

@@ -0,0 +1,26 @@
+export { BrowserSession, originOf } from "./session.ts";
+export type { BrowserSessionOptions, ConsoleEntry, NetworkEntry } from "./session.ts";
+export { createBrowserTools } from "./tools.ts";
+export { findChrome, launchChrome } from "./chrome.ts";
+export type { LaunchChromeOptions } from "./chrome.ts";
+export { CdpConnection, NulFramer } from "./cdp.ts";
+export type { CdpMessage } from "./cdp.ts";
+export { buildSnapshot } from "./snapshot.ts";
+export type { AxNode, Snapshot, SnapshotOptions } from "./snapshot.ts";
+export type { BrowserInputEvent, BrowserPage, BrowserTarget, BrowserTargetFactory, FrameOptions, BrowserTargetContext, } from "./target.ts";
+export { createBrowserUsePlugin } from "./plugin.ts";
+export type { BrowserUsePlugin, BrowserUseSession, BrowserUseSessionContext, DefaultBrowserUsePluginOptions } from "./plugin.ts";
+export { browserProviderFor, builtinBrowserProvider, extensionBrowserProvider } from "./provider.ts";
+export type { BrowserProviderPlugin } from "./provider.ts";
+export { connectExtensionChannel, extensionTarget } from "./extension.ts";
+export { extensionHostReachable, extensionSocketPath } from "./socket.ts";
+export { announcePresence } from "./presence.ts";
+export type { Presence, PresenceInfo } from "./presence.ts";
+export type { ExtensionChannel } from "./extension.ts";
+export { NativeMessageFramer, encodeNativeMessage, runBrowserHost } from "./host.ts";
+export type { HostOptions, RunningHost } from "./host.ts";
+export { EXTENSION_ID, EXTENSION_INSTALL_URL, HOST_NAME, hostLauncher, installNativeHost, nativeHostManifest, nativeHostTargets, windowsRegistryKeys, } from "./host-manifest.ts";
+export type { InstallOptions, InstallResult, NativeHostManifest } from "./host-manifest.ts";
+export { ScreencastHub } from "./screencast.ts";
+export { LoginImportMemory, cookieInSite, cookieParam, groupSites, hostInSite, normalizeSite, readSiteLoginState } from "./login-import.ts";
+export type { CookieParam, ExternalSite, ImportedSite, SiteLoginState } from "./login-import.ts";

package/dist/browser/index.js

@@ -0,0 +1,15 @@
+export { BrowserSession, originOf } from "./session.js";
+export { createBrowserTools } from "./tools.js";
+export { findChrome, launchChrome } from "./chrome.js";
+export { CdpConnection, NulFramer } from "./cdp.js";
+export { buildSnapshot } from "./snapshot.js";
+export { createBrowserUsePlugin } from "./plugin.js";
+export { browserProviderFor, builtinBrowserProvider, extensionBrowserProvider } from "./provider.js";
+export { connectExtensionChannel, extensionTarget } from "./extension.js";
+export { extensionHostReachable, extensionSocketPath } from "./socket.js";
+export { announcePresence } from "./presence.js";
+export { NativeMessageFramer, encodeNativeMessage, runBrowserHost } from "./host.js";
+export { EXTENSION_ID, EXTENSION_INSTALL_URL, HOST_NAME, hostLauncher, installNativeHost, nativeHostManifest, nativeHostTargets, windowsRegistryKeys, } from "./host-manifest.js";
+export { ScreencastHub } from "./screencast.js";
+export { LoginImportMemory, cookieInSite, cookieParam, groupSites, hostInSite, normalizeSite, readSiteLoginState } from "./login-import.js";
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAU9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAErG,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAErF,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/browser/login-import.d.ts

@@ -0,0 +1,98 @@
+import type { BrowserTarget } from "./target.ts";
+/**
+ * Moving a site's sign-in from the person's own browser into the built-in one.
+ *
+ * The external browser is only ever reached through the OHarness extension —
+ * the same sanctioned relay extension mode drives — so nothing here reads
+ * another browser's cookie database off disk or asks the keychain for its key.
+ * Chrome shows its "being debugged" banner while a tab is read, which is the
+ * disclosure this deserves.
+ *
+ * The unit is a site, not a browser. Copying a whole cookie jar would hand the
+ * agent every account the person has, for the sake of the one it needed; a site
+ * is what the person can reason about in a confirmation dialog, and what the
+ * dialog names. Nothing in this module runs without that confirmation: the
+ * server only calls `readSiteLoginState` from the dialog's import action.
+ */
+/** A cookie as `Network.setCookies` accepts it. */
+export type CookieParam = Record<string, unknown> & {
+    name: string;
+    value: string;
+};
+export interface SiteLoginState {
+    site: string;
+    cookies: CookieParam[];
+    /** localStorage per origin, read from the site's open tabs. */
+    origins: Array<{
+        origin: string;
+        url: string;
+        localStorage: Array<[string, string]>;
+    }>;
+}
+export interface ExternalSite {
+    site: string;
+    /** The most useful page to reopen in the built-in browser. */
+    url: string;
+    title?: string;
+    tabs: number;
+}
+export interface ImportedSite {
+    site: string;
+    cookies: number;
+    localStorage: number;
+    url?: string;
+}
+/**
+ * The site a URL or typed domain names: lower-case host, `www.` dropped so
+ * `github.com` and `www.github.com` are one choice in the dialog.
+ */
+export declare function normalizeSite(input: string): string | undefined;
+/** Whether a host belongs to a site: the site itself or any subdomain of it. */
+export declare function hostInSite(host: string, site: string): boolean;
+/**
+ * Whether a cookie is part of signing in to `site`.
+ *
+ * Its own and its subdomains' cookies, and the parent domain's too: signing in
+ * to `mail.example.com` often lives in a cookie set on `.example.com`. A public
+ * suffix can never carry a cookie, so the parent walk cannot reach `.com`.
+ */
+export declare function cookieInSite(domain: string, site: string): boolean;
+/** The http(s) sites open in a browser, grouped the way the dialog lists them. */
+export declare function groupSites(tabs: Array<{
+    url: string;
+    title?: string;
+}>): ExternalSite[];
+/** Which browser the extension lives in, for the dialog. Older extensions cannot say. */
+export declare function externalBrowserName(target: BrowserTarget): Promise<string>;
+export declare function listExternalSites(target: BrowserTarget): Promise<ExternalSite[]>;
+/**
+ * Read one site's cookies and localStorage from the external browser.
+ *
+ * Cookies come from the browser-wide store, so any attached tab can answer;
+ * localStorage only exists inside a page of its own origin, so it is read from
+ * the site's open tabs and is simply absent for a site with none.
+ */
+export declare function readSiteLoginState(target: BrowserTarget, site: string): Promise<SiteLoginState>;
+/**
+ * A read cookie, rewritten as one `Network.setCookies` will store identically.
+ *
+ * A host-only cookie is reported with a bare domain, and passing that back as
+ * `domain` would widen it to every subdomain (and make a `__Host-` cookie
+ * invalid). So host-only cookies are set by `url`, domain cookies by `domain`.
+ * Partitioning and source-port fields are left out: their shapes differ across
+ * Chromium versions, and the embedded one rejects what it does not know.
+ */
+export declare function cookieParam(cookie: Record<string, unknown>): CookieParam | undefined;
+/**
+ * Sites the person already answered for — imported, or told the suggestion to
+ * go away. The built-in profile is shared and persistent, so the answer is too:
+ * asking again in the next conversation would be asking the same question.
+ */
+export declare class LoginImportMemory {
+    private readonly file;
+    private loaded?;
+    constructor(file?: string);
+    private sites;
+    has(site: string): Promise<boolean>;
+    add(site: string): Promise<void>;
+}