@specship/specship 0.11.0

package/dist/designer/cdp-trace.js

@@ -0,0 +1,599 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CdpTraceRecorder = exports.CdpSession = void 0;
+exports.scrubSecrets = scrubSecrets;
+exports.asRec = asRec;
+exports.redact = redact;
+exports.listTargets = listTargets;
+exports.findDesignTarget = findDesignTarget;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const cdp_ensure_1 = require("./cdp-ensure");
+// CDP network trace recorder — spike-grade groundwork for the future
+// network-first run-state observer (RUNNING/FINISHED/STALLED/BLOCKED).
+//
+// Attaches a second CDP client directly to the design tab's page target
+// (agent-browser keeps driving the page through its own client; CDP allows
+// multiple simultaneous clients) and streams Network/Page events to JSONL.
+//
+// Uses the native global WebSocket (stable since Node 22.4). The package
+// declares engines >=22 so runtime code can use it without a `ws` dependency.
+//
+// Known blind spot: the claudeusercontent.com preview iframe is an
+// out-of-process frame — its document fetches never reach this page target's
+// Network domain. Generation API traffic originates in the main frame, which
+// is what we're here for. Upgrade path if traces show a gap:
+// Target.setAutoAttach({flatten:true}) + per-session Network.enable; send()
+// and event handling already tolerate a sessionId field for that reason.
+const DEFAULT_PORT = process.env.DESIGNER_CDP || '9222';
+const DESIGN_URL_PATTERN = /^https:\/\/claude\.ai\/design/;
+const REDACT_KEY_PATTERN = /^(cookie|set-cookie|authorization|proxy-authorization|x-api-key)$/i;
+const STREAMABLE_RESOURCE_TYPES = new Set(['XHR', 'Fetch', 'EventSource']);
+// URLs whose request/response bodies we never capture — auth/session exchanges
+// can carry credentials as plaintext JSON values that header-key redaction
+// can't see. The generation traffic we care about (OmeletteService) is not here.
+const AUTH_URL_DENYLIST = /\/(oauth|auth|login|logout|sign[_-]?in|sign[_-]?out|sign[_-]?up|register|token|sessions?|account|credential|password|mfa|totp|verify)\b/i;
+// Value-level secret scrub for captured *bodies* (postData, response bodies, WS
+// frame payloads). redact() only matches header *key names*; a token sitting in
+// a JSON value or form field is a value blob it can't reach. Best-effort: catch
+// the common token shapes before they hit disk. Exported for testability.
+function scrubSecrets(s) {
+    return s
+        .replace(/eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, '[redacted-jwt]')
+        .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[redacted-key]')
+        .replace(/(["']?(?:access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?key|sessionKey|api[_-]?key|client[_-]?secret|secret|password|passwd|pwd)["']?\s*[:=]\s*["']?)[^"'&,;\s}]+/gi, '$1[redacted]')
+        .replace(/\bsessionKey=[^;"'\s&]+/gi, 'sessionKey=[redacted]')
+        .replace(/\b([Bb]earer)\s+[A-Za-z0-9._~+/=-]{12,}/g, '$1 [redacted]');
+}
+// Events persisted verbatim (post-redaction). Everything else — notably the
+// Network.*ExtraInfo pair, which carries real Cookie/Set-Cookie headers — is
+// only counted in droppedByMethod.
+const PERSIST_METHODS = new Set([
+    'Network.requestWillBeSent',
+    'Network.responseReceived',
+    'Network.dataReceived',
+    'Network.loadingFinished',
+    'Network.loadingFailed',
+    'Network.requestServedFromCache',
+    'Network.eventSourceMessageReceived',
+    'Network.webSocketCreated',
+    'Network.webSocketWillSendHandshakeRequest',
+    'Network.webSocketHandshakeResponseReceived',
+    'Network.webSocketFrameSent',
+    'Network.webSocketFrameReceived',
+    'Network.webSocketClosed',
+    'Page.frameNavigated',
+    'Page.frameStartedLoading',
+    'Page.frameStoppedLoading',
+    'Page.lifecycleEvent'
+]);
+// Narrow an unknown CDP payload to a record before keyed access. Shared by the
+// CDP subclasses (run-state, oopif-reader) that parse event/response shapes.
+function asRec(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function isCdpTarget(v) {
+    const r = asRec(v);
+    return (typeof r.id === 'string' &&
+        typeof r.type === 'string' &&
+        typeof r.title === 'string' &&
+        typeof r.url === 'string' &&
+        typeof r.webSocketDebuggerUrl === 'string');
+}
+/** Deep-walk redaction of sensitive header keys. Exported for testability. */
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = REDACT_KEY_PATTERN.test(k) ? '[redacted]' : redact(v);
+        }
+        return out;
+    }
+    return value;
+}
+async function listTargets(port = DEFAULT_PORT) {
+    const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok)
+        throw new Error(`CDP /json/list on :${port} returned ${res.status}`);
+    const body = await res.json();
+    if (!Array.isArray(body))
+        throw new Error(`CDP /json/list on :${port} returned a non-array payload`);
+    return body.filter(isCdpTarget);
+}
+async function findDesignTarget({ port = DEFAULT_PORT, urlPattern = DESIGN_URL_PATTERN, preferUrlPrefix = null } = {}) {
+    const targets = await listTargets(port);
+    const candidates = targets.filter((t) => t.type === 'page' && urlPattern.test(t.url) && t.webSocketDebuggerUrl);
+    if (candidates.length === 0) {
+        throw new Error(`No page target matching ${urlPattern} on CDP :${port}. Open claude.ai/design first.`);
+    }
+    if (preferUrlPrefix) {
+        // Exact URL first: the home URL (https://claude.ai/design) is a *prefix* of
+        // every /design/p/<uuid> tab, so a startsWith match alone could bind to an
+        // arbitrary project tab instead of the exact tab the caller is on (#66).
+        const exactMatches = candidates.filter((t) => t.url === preferUrlPrefix);
+        const onlyExact = exactMatches[0];
+        if (exactMatches.length === 1 && onlyExact)
+            return onlyExact;
+        if (exactMatches.length > 1) {
+            // An exact URL match still isn't an exact TAB match: two tabs at the same
+            // URL (e.g. duplicate claude.ai/design home tabs) can't be told apart by
+            // URL, so fail rather than bind an arbitrary (possibly idle) one (#66).
+            // Callers that tolerate it (RunStateObserver.attach) degrade to null.
+            throw new Error(`Multiple tabs open at exactly ${preferUrlPrefix} — close the duplicate(s) so the right tab can be identified.`);
+        }
+        const preferred = candidates.find((t) => t.url.startsWith(preferUrlPrefix));
+        if (preferred)
+            return preferred;
+    }
+    const only = candidates[0];
+    if (candidates.length === 1 && only)
+        return only;
+    throw new Error(`Multiple design tabs match — pass --target-url to disambiguate:\n` +
+        candidates.map((t) => `  ${t.url}`).join('\n'));
+}
+class CdpSession {
+    ws;
+    target;
+    sessionOpts;
+    stopped = false;
+    reconnects = 0;
+    pending = new Map();
+    socketClosed = false;
+    nextId = 0;
+    constructor(ws, target, opts = {}) {
+        this.ws = ws;
+        this.target = target;
+        this.sessionOpts = {
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern ?? DESIGN_URL_PATTERN,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null,
+            reconnect: opts.reconnect ?? true
+        };
+        this.wire(ws);
+    }
+    static async connectTarget(opts = {}) {
+        await (0, cdp_ensure_1.ensureCdpUp)();
+        const target = await findDesignTarget({
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null
+        });
+        const ws = await this.openSocket(target.webSocketDebuggerUrl);
+        return { ws, target };
+    }
+    static openSocket(url, timeoutMs = 5000) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            // A half-open WS (e.g. a wedged debug Chrome) would otherwise leave this
+            // pending forever — attach() never resolves/rejects, defeating callers'
+            // "degrade, don't hang" contract (#67 review). Bound the open and close the
+            // socket on timeout. Reject is handled by every caller (attach -> null /
+            // throw; the reconnect loop keeps polling).
+            const timer = setTimeout(() => {
+                cleanup();
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* already closing */
+                }
+                reject(new Error(`CDP WebSocket open timed out after ${timeoutMs}ms: ${url}`));
+            }, timeoutMs);
+            const onOpen = () => {
+                cleanup();
+                resolve(ws);
+            };
+            const onError = () => {
+                cleanup();
+                reject(new Error(`Failed to open CDP WebSocket ${url}`));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                ws.removeEventListener('open', onOpen);
+                ws.removeEventListener('error', onError);
+            };
+            ws.addEventListener('open', onOpen);
+            ws.addEventListener('error', onError);
+        });
+    }
+    targetInfo() {
+        return { url: this.target.url, wsUrl: this.target.webSocketDebuggerUrl, port: this.sessionOpts.port };
+    }
+    async enableDomains() {
+        await this.send('Network.enable', { maxTotalBufferSize: 100_000_000, maxResourceBufferSize: 50_000_000 });
+    }
+    send(method, params, sessionId) {
+        const id = ++this.nextId;
+        const msg = { id, method };
+        if (params !== undefined)
+            msg.params = params;
+        if (sessionId)
+            msg.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.ws.send(JSON.stringify(msg));
+            }
+            catch (e) {
+                this.pending.delete(id);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    }
+    close() {
+        this.closeSocket();
+    }
+    closeSocket() {
+        if (this.socketClosed)
+            return false;
+        this.socketClosed = true;
+        this.stopped = true;
+        this.rejectPending(new Error('CDP WebSocket closed'));
+        try {
+            this.ws.close();
+        }
+        catch {
+            /* already closed */
+        }
+        return true;
+    }
+    onSocketGap(_detail) { }
+    onSocketReconnected(_target) { }
+    onSocketReconnectFailed(_detail) { }
+    wire(ws) {
+        ws.addEventListener('message', (ev) => {
+            this.onMessage(typeof ev.data === 'string' ? ev.data : String(ev.data));
+        });
+        ws.addEventListener('close', () => {
+            void this.handleClose();
+        });
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!msg || typeof msg !== 'object' || Array.isArray(msg))
+            return;
+        const rec = msg;
+        if (typeof rec.id === 'number') {
+            const p = this.pending.get(rec.id);
+            if (!p)
+                return;
+            this.pending.delete(rec.id);
+            if (rec.error)
+                p.reject(new Error(`CDP ${JSON.stringify(rec.error)}`));
+            else
+                p.resolve(rec.result);
+            return;
+        }
+        const method = typeof rec.method === 'string' ? rec.method : '';
+        if (!method)
+            return;
+        this.onEvent(method, rec.params, typeof rec.sessionId === 'string' ? rec.sessionId : undefined);
+    }
+    rejectPending(error) {
+        for (const [, p] of this.pending)
+            p.reject(error);
+        this.pending.clear();
+    }
+    async handleClose() {
+        this.rejectPending(new Error('CDP WebSocket closed'));
+        if (this.stopped)
+            return;
+        this.onSocketGap({ reason: 'socket-closed' });
+        if (!this.sessionOpts.reconnect)
+            return;
+        for (let i = 0; i < 30 && !this.stopped; i++) {
+            await new Promise((r) => setTimeout(r, 1000));
+            try {
+                const target = await findDesignTarget({
+                    port: this.sessionOpts.port,
+                    urlPattern: this.sessionOpts.urlPattern,
+                    preferUrlPrefix: this.sessionOpts.preferUrlPrefix
+                });
+                const ws = await CdpSession.openSocket(target.webSocketDebuggerUrl);
+                this.ws = ws;
+                this.target = target;
+                this.wire(ws);
+                await this.enableDomains();
+                this.reconnects++;
+                this.onSocketReconnected(target);
+                return;
+            }
+            catch {
+                // target not back yet — keep polling
+            }
+        }
+        if (!this.stopped)
+            this.onSocketReconnectFailed({ gaveUpAfterMs: 30_000 });
+    }
+}
+exports.CdpSession = CdpSession;
+class CdpTraceRecorder extends CdpSession {
+    opts;
+    out;
+    requests = new Map();
+    wsSocketUrls = new Map();
+    pendingBodies = new Set();
+    startedAt = Date.now();
+    total = 0;
+    bodyCaptures = 0;
+    ended = false;
+    byMethod = {};
+    droppedByMethod = {};
+    constructor(ws, target, opts) {
+        super(ws, target, opts);
+        this.opts = {
+            outFile: opts.outFile,
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern ?? DESIGN_URL_PATTERN,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null,
+            captureBodiesFor: opts.captureBodiesFor ?? /^https:\/\/claude\.ai\//,
+            maxBodyBytesPerRequest: opts.maxBodyBytesPerRequest ?? 2 * 1024 * 1024,
+            reconnect: opts.reconnect ?? true
+        };
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(opts.outFile), { recursive: true });
+        this.out = node_fs_1.default.createWriteStream(opts.outFile, { flags: 'a' });
+        // Swallow stream errors (disk full, write-after-end races) — an unhandled
+        // 'error' event on the stream would otherwise crash the process.
+        this.out.on('error', () => { });
+    }
+    static async attach(opts) {
+        if (typeof WebSocket === 'undefined') {
+            throw new Error('Native WebSocket unavailable — cdp-trace requires Node >= 22.');
+        }
+        const { ws, target } = await CdpTraceRecorder.connectTarget(opts);
+        return new CdpTraceRecorder(ws, target, opts);
+    }
+    async start() {
+        this.startedAt = Date.now();
+        await this.enableDomains();
+        this.writeLine({
+            ts: Date.now(),
+            kind: 'recorder',
+            event: 'attach',
+            detail: { targetUrl: this.target.url, wsUrl: this.target.webSocketDebuggerUrl }
+        });
+    }
+    async enableDomains() {
+        await super.enableDomains();
+        await this.send('Page.enable');
+        await this.send('Page.setLifecycleEventsEnabled', { enabled: true });
+    }
+    marker(name, detail) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'marker', detail: { name, ...asRec(detail) } });
+    }
+    record(ev) {
+        this.writeLine({ ...ev, ts: ev.ts || Date.now() });
+    }
+    async stop() {
+        this.stopped = true;
+        // Give in-flight body fetches a moment to land, then move on.
+        await Promise.race([
+            Promise.allSettled([...this.pendingBodies]),
+            new Promise((r) => setTimeout(r, 3000))
+        ]);
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'detach' });
+        this.close();
+        // Mark ended before end() so any late body-fetch .catch (rejected by close())
+        // is a no-op in writeLine rather than a write-after-end stream error.
+        this.ended = true;
+        await new Promise((resolve) => this.out.end(resolve));
+        return {
+            durationMs: Date.now() - this.startedAt,
+            total: this.total,
+            byMethod: this.byMethod,
+            droppedByMethod: this.droppedByMethod,
+            reconnects: this.reconnects,
+            bodyCaptures: this.bodyCaptures
+        };
+    }
+    onEvent(method, rawParams, sessionId) {
+        if (!PERSIST_METHODS.has(method)) {
+            this.droppedByMethod[method] = (this.droppedByMethod[method] || 0) + 1;
+            return;
+        }
+        const params = asRec(rawParams);
+        this.trackRequest(method, params);
+        const shaped = this.shapePayloads(method, params);
+        const ev = { ts: Date.now(), kind: 'cdp', method, params: redact(shaped) };
+        if (sessionId)
+            ev.sessionId = sessionId;
+        this.writeLine(ev);
+        this.byMethod[method] = (this.byMethod[method] || 0) + 1;
+        if (method === 'Network.responseReceived')
+            this.maybeStreamContent(params);
+        if (method === 'Network.loadingFinished')
+            this.maybeFetchBody(params);
+    }
+    trackRequest(method, params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId)
+            return;
+        if (method === 'Network.requestWillBeSent') {
+            const req = asRec(params.request);
+            this.requests.set(requestId, {
+                url: String(req.url || ''),
+                resourceType: typeof params.type === 'string' ? params.type : null,
+                mimeType: null,
+                streamed: false,
+                bodyBytes: 0,
+                bodyFetched: false
+            });
+        }
+        else if (method === 'Network.responseReceived') {
+            const info = this.requests.get(requestId);
+            if (info) {
+                const resp = asRec(params.response);
+                info.mimeType = typeof resp.mimeType === 'string' ? resp.mimeType : null;
+                if (typeof params.type === 'string')
+                    info.resourceType = params.type;
+            }
+        }
+        else if (method === 'Network.webSocketCreated') {
+            this.wsSocketUrls.set(requestId, String(params.url || ''));
+        }
+    }
+    /** Strip or size-cap payload-bearing fields before persistence. */
+    shapePayloads(method, params) {
+        if (method === 'Network.requestWillBeSent') {
+            const req = asRec(params.request);
+            if (typeof req.postData === 'string') {
+                // Off-origin: strip entirely. Kept (claude.ai) bodies are value-scrubbed
+                // so a credential in a sign-in/token POST body never lands verbatim.
+                if (!this.opts.captureBodiesFor.test(String(req.url || ''))) {
+                    return { ...params, request: { ...req, postData: undefined, postDataBytes: req.postData.length } };
+                }
+                return { ...params, request: { ...req, postData: scrubSecrets(req.postData) } };
+            }
+            return params;
+        }
+        if (method === 'Network.webSocketFrameSent' || method === 'Network.webSocketFrameReceived') {
+            const requestId = String(params.requestId || '');
+            const socketUrl = this.wsSocketUrls.get(requestId) || '';
+            const resp = asRec(params.response);
+            if (typeof resp.payloadData === 'string') {
+                if (!this.opts.captureBodiesFor.test(socketUrl)) {
+                    return { ...params, response: { ...resp, payloadData: undefined, payloadBytes: resp.payloadData.length } };
+                }
+                return { ...params, response: { ...resp, payloadData: scrubSecrets(resp.payloadData) } };
+            }
+            return params;
+        }
+        if (method === 'Network.dataReceived' && typeof params.data === 'string') {
+            const requestId = String(params.requestId || '');
+            const info = this.requests.get(requestId);
+            const bytes = Math.floor((params.data.length * 3) / 4);
+            if (info) {
+                if (info.bodyBytes + bytes > this.opts.maxBodyBytesPerRequest) {
+                    return { ...params, data: undefined, dataDroppedBytes: bytes, truncated: true };
+                }
+                info.bodyBytes += bytes;
+            }
+            return params;
+        }
+        return params;
+    }
+    // Streaming responses (SSE / chunked fetch with no Content-Length) lose
+    // their bodies once the stream is consumed — getResponseBody after the
+    // fact usually fails. Network.streamResourceContent (experimental) asks
+    // Chrome to buffer + forward chunks as base64 on dataReceived. Best-effort:
+    // on older Chrome the command just rejects and chunk timing remains the
+    // primary record.
+    maybeStreamContent(params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId)
+            return;
+        const info = this.requests.get(requestId);
+        if (!info || info.streamed)
+            return;
+        if (!this.opts.captureBodiesFor.test(info.url))
+            return;
+        if (AUTH_URL_DENYLIST.test(info.url))
+            return;
+        if (!info.resourceType || !STREAMABLE_RESOURCE_TYPES.has(info.resourceType))
+            return;
+        const resp = asRec(params.response);
+        const headers = asRec(resp.headers);
+        const hasContentLength = Object.keys(headers).some((k) => k.toLowerCase() === 'content-length');
+        const isSse = info.mimeType === 'text/event-stream';
+        if (!isSse && hasContentLength)
+            return;
+        info.streamed = true;
+        const p = this.send('Network.streamResourceContent', { requestId })
+            .then((result) => {
+            const buffered = String(asRec(result).bufferedData || '');
+            const bytes = Math.floor((buffered.length * 3) / 4);
+            const truncated = bytes > this.opts.maxBodyBytesPerRequest;
+            info.bodyBytes += Math.min(bytes, this.opts.maxBodyBytesPerRequest);
+            this.bodyCaptures++;
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'body',
+                requestId,
+                url: info.url,
+                source: 'streamBuffered',
+                base64: truncated ? buffered.slice(0, Math.ceil((this.opts.maxBodyBytesPerRequest * 4) / 3)) : buffered,
+                truncated,
+                bytes
+            });
+        })
+            .catch(() => {
+            info.streamed = false; // let loadingFinished try getResponseBody instead
+        })
+            .finally(() => this.pendingBodies.delete(p));
+        this.pendingBodies.add(p);
+    }
+    maybeFetchBody(params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId || this.stopped)
+            return;
+        const info = this.requests.get(requestId);
+        if (!info || info.streamed || info.bodyFetched)
+            return;
+        if (!this.opts.captureBodiesFor.test(info.url))
+            return;
+        if (AUTH_URL_DENYLIST.test(info.url))
+            return;
+        if (!info.resourceType || !STREAMABLE_RESOURCE_TYPES.has(info.resourceType))
+            return;
+        info.bodyFetched = true;
+        const p = this.send('Network.getResponseBody', { requestId })
+            .then((result) => {
+            const r = asRec(result);
+            const isB64 = r.base64Encoded === true;
+            // Text bodies are value-scrubbed before persistence; base64 (binary)
+            // bodies are opaque, so the auth-URL denylist above is their guard.
+            const body = isB64 ? String(r.body || '') : scrubSecrets(String(r.body || ''));
+            const bytes = isB64 ? Math.floor((body.length * 3) / 4) : body.length;
+            const truncated = bytes > this.opts.maxBodyBytesPerRequest;
+            const cap = isB64 ? Math.ceil((this.opts.maxBodyBytesPerRequest * 4) / 3) : this.opts.maxBodyBytesPerRequest;
+            this.bodyCaptures++;
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'body',
+                requestId,
+                url: info.url,
+                source: 'getResponseBody',
+                base64: isB64 ? (truncated ? body.slice(0, cap) : body) : Buffer.from(truncated ? body.slice(0, cap) : body).toString('base64'),
+                truncated,
+                bytes
+            });
+        })
+            .catch((e) => {
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'recorder',
+                event: 'error',
+                detail: { op: 'getResponseBody', requestId, url: info.url, message: e.message }
+            });
+        })
+            .finally(() => this.pendingBodies.delete(p));
+        this.pendingBodies.add(p);
+    }
+    onSocketGap() {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'gap', detail: { reason: 'socket-closed' } });
+    }
+    onSocketReconnected(target) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'reconnect', detail: { targetUrl: target.url } });
+    }
+    onSocketReconnectFailed(detail) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'error', detail: { op: 'reconnect', ...detail } });
+    }
+    writeLine(ev) {
+        if (this.ended)
+            return; // a late body-fetch .catch can fire after stop() ended the stream
+        this.out.write(JSON.stringify(ev) + '\n');
+        this.total++;
+    }
+}
+exports.CdpTraceRecorder = CdpTraceRecorder;

package/dist/designer/cross-platform.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeSpawnSync = exports.nodeSpawn = exports.QUIT_CHROME_HINT = exports.WHICH = exports.xspawnSync = exports.xspawn = exports.IS_MAC = exports.IS_WIN = void 0;
+exports.defaultChromeBin = defaultChromeBin;
+exports.isChromeRunning = isChromeRunning;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+Object.defineProperty(exports, "nodeSpawn", { enumerable: true, get: function () { return node_child_process_1.spawn; } });
+Object.defineProperty(exports, "nodeSpawnSync", { enumerable: true, get: function () { return node_child_process_1.spawnSync; } });
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+exports.IS_WIN = process.platform === 'win32';
+exports.IS_MAC = process.platform === 'darwin';
+// Drop-in replacements for `child_process.spawn` / `spawnSync`.
+//
+// On Windows, npm-installed CLIs are `<name>.cmd` shims (sometimes `.ps1`)
+// that Node ≥ 21 refuses to spawn directly (security policy: `EINVAL`), and
+// that misbehave under `shell: true` when args contain shell metacharacters
+// (parens, quotes, redirects — common in JS code passed to `agent-browser eval`).
+//
+// `cross-spawn` resolves shim paths and invokes them via `cmd /c` with proper
+// argv quoting. Used by 100M+ npm packages; this is the standard fix.
+//
+// On macOS/Linux it's a passthrough to `child_process` — no behavior change.
+exports.xspawn = cross_spawn_1.default;
+exports.xspawnSync = cross_spawn_1.default.sync;
+// Returns the `which` / `where` command name for the current OS.
+exports.WHICH = exports.IS_WIN ? 'where' : 'which';
+// Default Chrome binary path per OS. Override with the CHROME_BIN env var.
+function defaultChromeBin() {
+    if (exports.IS_WIN) {
+        const candidates = [
+            node_path_1.default.join(process.env['ProgramFiles'] || 'C:\\Program Files', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            node_path_1.default.join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            node_path_1.default.join(process.env['LOCALAPPDATA'] || '', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+        ];
+        for (const c of candidates)
+            if (c && node_fs_1.default.existsSync(c))
+                return c;
+        return candidates[0] ?? 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
+    }
+    if (exports.IS_MAC)
+        return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+    for (const c of ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser']) {
+        if (node_fs_1.default.existsSync(c))
+            return c;
+    }
+    return '/usr/bin/google-chrome';
+}
+// Cross-platform "is a non-debug Chrome currently running?" check.
+function isChromeRunning() {
+    if (exports.IS_WIN) {
+        const r = (0, node_child_process_1.spawnSync)('tasklist', ['/FI', 'IMAGENAME eq chrome.exe', '/NH', '/FO', 'CSV'], { stdio: 'pipe' });
+        if (r.status !== 0)
+            return false;
+        const out = r.stdout?.toString() || '';
+        return out.toLowerCase().includes('chrome.exe');
+    }
+    if (exports.IS_MAC) {
+        const r = (0, node_child_process_1.spawnSync)('pgrep', ['-f', 'Google Chrome.app/Contents/MacOS/Google Chrome'], { stdio: 'pipe' });
+        return r.status === 0 && (r.stdout?.toString().trim().length ?? 0) > 0;
+    }
+    const r = (0, node_child_process_1.spawnSync)('pgrep', ['-f', 'chrome'], { stdio: 'pipe' });
+    return r.status === 0 && (r.stdout?.toString().trim().length ?? 0) > 0;
+}
+// User-friendly "press X to quit Chrome" hint per OS.
+exports.QUIT_CHROME_HINT = exports.IS_WIN
+    ? 'Close all Chrome windows (or end chrome.exe in Task Manager).'
+    : exports.IS_MAC
+        ? 'Cmd+Q on the Chrome menu, then close Activity Monitor entries if any.'
+        : 'Close all Chrome windows or `pkill chrome`.';