@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/preview/cdp.js

@@ -0,0 +1,167 @@
+import WebSocket from 'ws';
+function createConnection(transport) {
+    let nextId = 0;
+    let isClosed = false;
+    const pending = new Map();
+    const eventFns = new Set();
+    let markClosed;
+    const closed = new Promise(resolve => (markClosed = resolve));
+    transport.onMessage(text => {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id === 'number') {
+            const entry = pending.get(msg.id);
+            pending.delete(msg.id);
+            entry?.resolve(msg);
+        }
+        else if (msg.method) {
+            for (const fn of [...eventFns])
+                fn(msg);
+        }
+    });
+    transport.onClose(() => {
+        if (isClosed)
+            return;
+        isClosed = true;
+        for (const [id, entry] of pending)
+            entry.resolve({ id, error: { message: 'CDP connection closed' } });
+        pending.clear();
+        eventFns.clear();
+        markClosed();
+    });
+    const request = (method, params, sessionId, resolve) => {
+        if (isClosed)
+            return resolve({ error: { message: 'CDP connection closed' } });
+        const id = ++nextId;
+        pending.set(id, { resolve, method });
+        try {
+            transport.send(JSON.stringify({ id, method, params: params ?? {}, ...(sessionId ? { sessionId } : {}) }));
+        }
+        catch (error) {
+            pending.delete(id);
+            resolve({ id, error: { message: error instanceof Error ? error.message : String(error) } });
+        }
+    };
+    const call = (method, params, sessionId) => new Promise(resolve => request(method, params, sessionId, resolve));
+    const onEvent = (fn) => {
+        eventFns.add(fn);
+        return () => void eventFns.delete(fn);
+    };
+    const close = () => transport.close();
+    return {
+        call,
+        request,
+        onEvent,
+        close,
+        closed,
+        session: sessionId => {
+            // A named session's close detaches that session alone: the host streams from several pages
+            // on one pipe (hearsay-tools/cezarion#784). The root session's close ends the connection.
+            const offs = new Set();
+            let detached = false;
+            return {
+                send: async (method, params = {}) => {
+                    if (detached)
+                        throw new Error(`${method}: CDP session detached`);
+                    const reply = await call(method, params, sessionId);
+                    if (reply.error)
+                        throw new Error(`${method}: ${reply.error.message ?? 'CDP error'}`);
+                    return reply.result;
+                },
+                on: (event, fn) => {
+                    const off = onEvent(msg => {
+                        if (msg.method === event && msg.sessionId === sessionId)
+                            fn(msg.params);
+                    });
+                    offs.add(off);
+                    return () => { off(); offs.delete(off); };
+                },
+                close: () => {
+                    if (sessionId === undefined)
+                        return close();
+                    if (detached)
+                        return;
+                    detached = true;
+                    for (const off of offs)
+                        off();
+                    offs.clear();
+                    request('Target.detachFromTarget', { sessionId }, undefined, () => { });
+                },
+                closed,
+            };
+        },
+    };
+}
+/** One page target's WebSocket. The tests' fake CDP servers speak it. */
+export function connectCdp(wsUrl) {
+    return new Promise((resolveConnect, rejectConnect) => {
+        const ws = new WebSocket(wsUrl, { perMessageDeflate: false });
+        const connection = createConnection({
+            send: text => {
+                if (ws.readyState !== WebSocket.OPEN)
+                    throw new Error('CDP connection closed');
+                ws.send(text);
+            },
+            onMessage: fn => ws.on('message', raw => fn(String(raw))),
+            onClose: fn => ws.once('close', fn),
+            close: () => ws.close(),
+        });
+        ws.once('open', () => resolveConnect(connection.session(undefined)));
+        // Before `open` an error is the connect failure; afterwards `close` follows and does the cleanup.
+        ws.once('error', err => rejectConnect(err));
+        ws.on('error', () => { });
+    });
+}
+/**
+ * Chromium's `--remote-debugging-pipe` (hearsay-tools/cezarion#784): commands go into fd 3 and
+ * replies come out of fd 4, each message ended by a NUL byte. No port exists, so only this process
+ * reaches the browser.
+ */
+export function cdpOverPipe(toBrowser, fromBrowser) {
+    let ended = false;
+    const closeFns = [];
+    const end = () => {
+        if (ended)
+            return;
+        ended = true;
+        for (const fn of closeFns)
+            fn();
+    };
+    let buffered = '';
+    const messageFns = [];
+    fromBrowser.setEncoding('utf8');
+    fromBrowser.on('data', (chunk) => {
+        buffered += chunk;
+        for (let at = buffered.indexOf('\0'); at >= 0; at = buffered.indexOf('\0')) {
+            const text = buffered.slice(0, at);
+            buffered = buffered.slice(at + 1);
+            for (const fn of messageFns)
+                fn(text);
+        }
+    });
+    // A browser that exits resets the pipe; that is an ordinary end, never an uncaught error.
+    fromBrowser.on('error', end);
+    toBrowser.on('error', end);
+    fromBrowser.once('close', end);
+    fromBrowser.once('end', end);
+    return createConnection({
+        send: text => {
+            if (ended)
+                throw new Error('CDP connection closed');
+            toBrowser.write(`${text}\0`);
+        },
+        onMessage: fn => messageFns.push(fn),
+        onClose: fn => (ended ? queueMicrotask(fn) : closeFns.push(fn)),
+        close: () => {
+            toBrowser.end();
+            fromBrowser.destroy();
+            end();
+        },
+    });
+}
+//# sourceMappingURL=cdp.js.map

package/dist/preview/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/preview/cdp.ts"],"names":[],"mappings":"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"}

package/dist/preview/chromium-launch-progress.d.ts

@@ -0,0 +1,10 @@
+/** The final hang guard, even when a broken browser keeps producing output. */
+export declare const LAUNCH_HANG_GUARD_MS = 120000;
+/** Linux CPU ticks and page faults expose cold binary loading before the first stderr byte.
+ * Unavailable procfs (including other platforms) falls back to pipe and stderr progress. */
+export declare function chromiumProcessProgress(pid: number): string | undefined;
+export declare function watchChromiumLaunch(pid: number | undefined, silenceMs: number, readProgress?: typeof chromiumProcessProgress): {
+    expired: Promise<"hard" | "stall">;
+    progress: () => void;
+    stop(): void;
+};

package/dist/preview/chromium-launch-progress.js

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+/** The final hang guard, even when a broken browser keeps producing output. */
+export const LAUNCH_HANG_GUARD_MS = 120_000;
+const PROCESS_SAMPLE_MS = 1_000;
+/** Linux CPU ticks and page faults expose cold binary loading before the first stderr byte.
+ * Unavailable procfs (including other platforms) falls back to pipe and stderr progress. */
+export function chromiumProcessProgress(pid) {
+    if (process.platform !== 'linux')
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        // comm may contain spaces and parentheses; fields after its final ')' start at field 3.
+        const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+        const counters = [fields[7], fields[9], fields[11], fields[12]]; // minflt, majflt, utime, stime
+        return counters.every(value => value !== undefined && /^\d+$/.test(value)) ? counters.join(':') : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function watchChromiumLaunch(pid, silenceMs, readProgress = chromiumProcessProgress) {
+    let silenceTimer;
+    let hardTimer;
+    let sampleTimer;
+    let lastProgress = Date.now();
+    let previous = pid === undefined ? undefined : readProgress(pid);
+    const expired = new Promise(resolve => {
+        silenceTimer = setTimeout(() => resolve('stall'), silenceMs);
+        hardTimer = setTimeout(() => resolve('hard'), LAUNCH_HANG_GUARD_MS);
+    });
+    const progress = () => { lastProgress = Date.now(); silenceTimer.refresh(); };
+    if (pid !== undefined)
+        sampleTimer = setInterval(() => {
+            if (Date.now() - lastProgress < PROCESS_SAMPLE_MS)
+                return;
+            const current = readProgress(pid);
+            if (current !== undefined && previous !== undefined && current !== previous)
+                progress();
+            if (current !== undefined)
+                previous = current;
+        }, PROCESS_SAMPLE_MS);
+    return {
+        expired,
+        progress,
+        stop() { clearTimeout(silenceTimer); clearTimeout(hardTimer); clearInterval(sampleTimer); },
+    };
+}
+//# sourceMappingURL=chromium-launch-progress.js.map

package/dist/preview/chromium-launch-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chromium-launch-progress.js","sourceRoot":"","sources":["../../src/preview/chromium-launch-progress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAC5C,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;4FAC4F;AAC5F,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,wFAAwF;QACxF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,+BAA+B;QAChG,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9G,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAuB,EAAE,SAAiB,EAAE,YAAY,GAAG,uBAAuB;IACpH,IAAI,YAA4B,CAAC;IACjC,IAAI,SAAyB,CAAC;IAC9B,IAAI,WAAuC,CAAC;IAC5C,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9B,IAAI,QAAQ,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAmB,OAAO,CAAC,EAAE;QACtD,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;QAC7D,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9E,IAAI,GAAG,KAAK,SAAS;QAAE,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;YACpD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,iBAAiB;gBAAE,OAAO;YAC1D,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,OAAO,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ;gBAAE,QAAQ,EAAE,CAAC;YACxF,IAAI,OAAO,KAAK,SAAS;gBAAE,QAAQ,GAAG,OAAO,CAAC;QAChD,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtB,OAAO;QACL,OAAO;QACP,QAAQ;QACR,IAAI,KAAK,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;KAC5F,CAAC;AACJ,CAAC"}

package/dist/preview/chromium.d.ts

@@ -0,0 +1,91 @@
+import type { Home } from '../home/home.ts';
+import { type ChildProcess } from 'node:child_process';
+import { type CdpConnection } from './cdp.ts';
+import { type chromiumProcessProgress } from './chromium-launch-progress.ts';
+/**
+ * The preview's Chromium: find one, download Chrome for Testing when there is none, launch it
+ * headless with a per-task profile (#781, spec 2026-10-02-live-preview-v1). Sandboxing is never
+ * relaxed here on its own: `--no-sandbox` is added only for `CEZ_PREVIEW_NO_SANDBOX=1`.
+ */
+export type ChromiumFs = {
+    existsSync(path: string): boolean;
+    /** Entry names of a directory; empty when it does not exist. */
+    readdirSync(path: string): string[];
+    /** Where a path really points; the input when it cannot be resolved. Optional for test fakes. */
+    realpathSync?(path: string): string;
+};
+export declare const realFs: ChromiumFs;
+/** `~/.cache/cez`: the root the skills cache already uses. */
+export declare function cezCacheDir(home: string | Home): string;
+/**
+ * The first usable Chromium, most deliberate source first: PATH, macOS app bundles, Playwright's
+ * cache, agent-browser's Chrome for Testing cache, then the copy `downloadChromium` keeps.
+ */
+export declare function resolveChromium(fs: ChromiumFs | undefined, env: NodeJS.ProcessEnv | undefined, platform: string | undefined, _arch: string | undefined, paths: Home): string | undefined;
+export type PlatformKey = 'linux64' | 'mac-arm64' | 'mac-x64' | 'win64';
+/** The Chrome for Testing build for this machine. Google publishes none for linux-arm64. */
+export declare function downloadTarget(platform: string, arch: string): {
+    platformKey: PlatformKey;
+} | undefined;
+/** The command that installs Chromium on this OS, or '' when cezar does not know one. `osRelease` is /etc/os-release. */
+export declare function installCommand(platform: string, osRelease: string): string;
+export type DownloadChromiumOptions = {
+    signal: AbortSignal;
+    onProgress(received: number, total: number): void;
+    fetchImpl?: typeof fetch;
+    /** Defaults to `~/.cache/cez`. */
+    cacheDir: string;
+    platform?: string;
+    arch?: string;
+    /** Unpacks `zip` into `dest`. Defaults to `unzip -q` (POSIX) or `tar -xf` (Windows). */
+    extract?: (zip: string, dest: string, platform: string, signal?: AbortSignal) => Promise<void>;
+    /** Waits out a retry backoff; rejects when the signal aborts. Tests replace it. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+};
+/**
+ * Downloads the Stable `chrome-headless-shell` build into `<cache>/chromium` and returns its binary.
+ * Each download stages in its own `.partial-*` directory (two cezar processes in different repos
+ * share the cache) and is renamed into place only once unpacked, so an abort or a crash never
+ * leaves a half-installed Chromium for `resolveChromium` to find. A copy another process already
+ * published wins; ours is discarded. Only the network
+ * phase gets three attempts; a failed extraction fails at once, since re-downloading would not help.
+ */
+export declare function downloadChromium(opts: DownloadChromiumOptions): Promise<string>;
+export declare class ChromiumError extends Error {
+    readonly kind: 'not-installed' | 'sandbox' | 'timeout' | 'exited';
+    readonly stderrTail: string;
+    /** How the process ended, when it ended on its own: its exit code, or the signal that stopped it. */
+    readonly exitCode?: number;
+    readonly signal?: string;
+    constructor(kind: 'not-installed' | 'sandbox' | 'timeout' | 'exited', stderrTail: string, message: string, exit?: {
+        exitCode?: number;
+        signal?: string;
+    });
+}
+/** Chromium discovers usable host graphics; `--enable-gpu` opts headless into that discovery.
+ *  Keep its driver blocklist and software fallback; never pin a vendor or graphics backend.
+ *  `--proxy-server=direct://` so Linux Chrome does not inherit HTTP(S)_PROXY: it will not send
+ *  proxy auth the way curl does, and a render-blocking third-party stylesheet then never paints.
+ *  `--remote-debugging-pipe` opens no port: only cezar reaches the browser, and an agent drives it
+ *  through cezar's CDP proxy alone (hearsay-tools/cezarion#784). */
+export declare function chromiumArgs(profileDir: string, env: NodeJS.ProcessEnv): string[];
+/**
+ * The task's Chromium pid record, `<runDir>/chromium.pid.json` beside its profile: `{ pid, startToken }`.
+ * A crashed cezar leaves the browser running; the boot sweep kills it by this record (#781).
+ */
+export declare const CHROMIUM_PID_FILE = "chromium.pid.json";
+/**
+ * Starts headless Chromium with its DevTools on a pipe and resolves once the browser answers
+ * `Browser.getVersion` on it. A launch that stalls without progress is killed and tried once more
+ * (`LAUNCH_ATTEMPTS`); any other failure kills the process and says why at once. While it runs,
+ * `CHROMIUM_PID_FILE` in the profile's parent names it. Leak detection is turned off in the profile
+ * Preferences before spawn so Chrome's leaked-password dialog cannot freeze preview input
+ * (hearsay-tools/cezarion#972).
+ */
+export declare function launchChromium(bin: string, profileDir: string, env: NodeJS.ProcessEnv, opts?: {
+    timeoutMs?: number;
+    readProgress?: typeof chromiumProcessProgress;
+}): Promise<{
+    proc: ChildProcess;
+    browser: CdpConnection;
+}>;