@descryy/runtime-orchestrator 0.0.0

package/dist/attach-to-running-node-process.js

@@ -0,0 +1,315 @@
+/**
+ * Retroactive attach to an already-running **Node** process, via its own
+ * inspector protocol — the specific, buildable slice
+ * `documents/decisions-inbox/RT-attach-to-running-process-scope.md`
+ * deliberately did not build. That entry's own "deliberately not built"
+ * list names it directly: "Node's `SIGUSR1` inspector activation + a CDP
+ * WebSocket client — real, but Node-only and a new protocol surface, not
+ * built this pass." This is that pass, for Node only — the other two items
+ * on that list (JVM Attach API, ptrace) remain out of scope, unchanged.
+ *
+ * **What makes this genuinely retroactive, unlike `attachToRunningProcess`
+ * (the file-based sibling in this same package).** That one needs the
+ * target to have already been told, at its own launch time, to write
+ * output somewhere reachable (`> server.log 2>&1`) — narrower than "attach
+ * to anything already running." This one needs nothing declared at launch:
+ * `SIGUSR1` (POSIX only; Node's own signal handler, not something this
+ * process installs) turns on the target's inspector **after the fact**, on
+ * a process that was never started with `--inspect` and never expected to
+ * be debugged. From that moment its debugger discovery endpoint is
+ * reachable at `http://127.0.0.1:<port>/json`, by the target itself, not by
+ * anything this collector primed in advance.
+ *
+ * **The one real limit, disclosed rather than hidden.** `SIGUSR1` does not
+ * report back which port the inspector actually bound — Node prints
+ * `Debugger listening on ws://host:port/<uuid>` to the target's own
+ * *stderr*, which is exactly the channel this module's own doc (and RT-024
+ * before it) says cannot be read for a process we did not spawn. So
+ * discovery is: try the default port (9229, Node's own default and the one
+ * `SIGUSR1` binds to when nothing else is already listening there), and if
+ * a caller already knows the target was configured for a different port
+ * (`--inspect-port`, `NODE_OPTIONS`), they supply it. **If the port is
+ * genuinely unknown and is not 9229, this module cannot discover it** — not
+ * attempted, not guessed at by scanning a port range, which would risk
+ * attaching to the wrong process's inspector entirely.
+ *
+ * **CDP client: written here, not reused, because nothing reusable
+ * exists.** `packages/browser`'s console collector speaks CDP only through
+ * Playwright's own browser-automation abstraction (`page.on("console")`),
+ * which assumes a `Target`/`Page`-domain browser session — a Node inspector
+ * session has neither domain, being a single top-level `Runtime` session
+ * instead. `cdp-client.ts` in this package is the actual reusable piece:
+ * protocol-family-generic, so a future browser-side raw-CDP need could
+ * reuse it too, instead of a third client getting written.
+ *
+ * **Measured: a freshly-spawned target has a brief window, sometimes under
+ * 100ms, before Node installs its own `SIGUSR1` handler** — a signal sent
+ * inside that window hits POSIX's default action for an unhandled
+ * `SIGUSR1` (terminate) instead of toggling the inspector, killing the
+ * target rather than attaching to it. Irrelevant to this module's actual
+ * purpose — attaching to something genuinely already running, which by
+ * definition has been alive far longer than that window — but real, and
+ * worth naming for a caller tempted to attach immediately after spawning
+ * something themselves.
+ *
+ * **Measured side effect: attaching changes the target's crash behaviour.**
+ * Once a CDP client is connected, V8 no longer terminates the process
+ * immediately on an uncaught exception — it prints "Waiting for the
+ * debugger to disconnect..." to stderr and blocks, exactly as it would
+ * under a launched `--inspect-brk` session, so a human debugger gets to
+ * inspect the paused, crashed state before the process actually exits.
+ * Measured directly (a naive test that waited for the child's own `exit`
+ * event after attach hung indefinitely) rather than assumed from docs. This
+ * is standard CDP/V8 behaviour, not a defect this collector introduces, and
+ * not silently worked around: the process resumes its exit exactly when
+ * `stop()` closes the CDP session, which is also when the exception's own
+ * evidence has already been captured, so nothing about the timing costs a
+ * caller the evidence. A caller relying on "did the target exit yet?" as a
+ * signal must call `stop()` first.
+ *
+ * **What is captured, and under which vocabulary.** `Runtime.consoleAPICalled`
+ * → `CONSOLE_MESSAGE`, `Runtime.exceptionThrown` → `EXCEPTION` — the same
+ * two `RuntimeEventType`s `browser-console-collector.ts` already claims for
+ * the analogous browser-page concepts, because they are the same concepts
+ * (console output; an uncaught exception), observed on a different kind of
+ * process. `source: "backend-process"`, not a new source value — this is a
+ * backend process being observed, and `EvidenceSource` already names what
+ * was observed rather than which mechanism did it (`inbound-proxy.ts`'s own
+ * precedent, restated there for exactly this reason). `capabilities()`
+ * reports `backendLogAccess`, not `consoleObservation` — `consoleObservation`
+ * is `browser-console-collector`'s claim on a *browser page's* console,
+ * kept apart from a backend process's console the same way `LogCollector`
+ * already keeps them apart for its own text-based capture.
+ */
+import { connectCdp } from "./cdp-client.js";
+import { isProcessAlive } from "./attach-to-running-process.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/**
+ * Sends `SIGUSR1` to `pid`, then polls `http://<host>:<port>/json` until the
+ * target's inspector answers or `timeoutMs` elapses. Resolves with the
+ * `webSocketDebuggerUrl` of the first entry — an already-running Node
+ * process presents exactly one inspectable target for its main thread,
+ * unlike a browser's `/json`, which lists one entry per open tab.
+ *
+ * Rejects, naming the exact blocker, rather than hanging or guessing: a pid
+ * that was never alive, a POSIX-only signal on a non-POSIX platform, or a
+ * port that never answers (most often because the real inspector bound
+ * somewhere other than `port`, which this function has no way to learn —
+ * see the module doc).
+ */
+export async function discoverNodeInspectorUrl(pid, options = {}) {
+    if (!isProcessAlive(pid)) {
+        throw new Error(`discoverNodeInspectorUrl: pid ${String(pid)} is not running — cannot attach to a target that does not exist.`);
+    }
+    if (process.platform === "win32") {
+        throw new Error("discoverNodeInspectorUrl: SIGUSR1 inspector activation is POSIX-only; not available on win32.");
+    }
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 9229;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const discoveryUrl = `http://${host}:${String(port)}/json`;
+    process.kill(pid, "SIGUSR1");
+    const deadline = Date.now() + timeoutMs;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            throw new Error(`discoverNodeInspectorUrl: pid ${String(pid)} exited while waiting for its inspector to come up.`);
+        }
+        try {
+            const response = await fetch(discoveryUrl);
+            if (response.ok) {
+                const targets = (await response.json());
+                const target = targets.find((candidate) => candidate.webSocketDebuggerUrl !== undefined);
+                if (target?.webSocketDebuggerUrl !== undefined)
+                    return target.webSocketDebuggerUrl;
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+    throw new Error(`discoverNodeInspectorUrl: no inspector answered at ${discoveryUrl} within ${String(timeoutMs)}ms after SIGUSR1${detail}. ` +
+        "Most likely the target's inspector bound to a different port than the one checked here (already in use by another " +
+        "process, or the target was itself configured with --inspect-port/NODE_OPTIONS) — this module cannot discover a " +
+        "non-default port from outside; a caller who knows the real port must supply discoveryPort.");
+}
+/** A `file://` URL is decoded to a plain filesystem path — every other adapter in this repo reports a path, never a URL, and CDP is the only source in this file that starts with one. Anything else (`node:internal/timers`, a bare module specifier) is passed through verbatim, the same "kept, not filtered" treatment `adapter-rust`'s std/core frames get. */
+function pathFromCdpUrl(url) {
+    if (url === undefined || url === "")
+        return null;
+    if (!url.startsWith("file://"))
+        return url;
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** CDP reports 0-based line/column; every other location in this codebase is 1-based (source lines as an editor shows them). Converted here, once, rather than left for a reader to notice CDP is the one odd source. */
+function locationFromCallFrame(frame) {
+    return {
+        file: pathFromCdpUrl(frame.url),
+        line: typeof frame.lineNumber === "number" ? frame.lineNumber + 1 : null,
+        column: typeof frame.columnNumber === "number" ? frame.columnNumber + 1 : null,
+        functionName: frame.functionName !== undefined && frame.functionName !== "" ? frame.functionName : null,
+        // V8's own reported state, captured live off the running process — the
+        // same class a Python traceback or Ruby backtrace gets, never a side
+        // artifact this collector resolved through.
+        reliability: "self-contained",
+        resolvedVia: null,
+    };
+}
+function formatConsoleArgs(args) {
+    return args
+        .map((arg) => {
+        if (arg.value !== undefined)
+            return typeof arg.value === "string" ? arg.value : JSON.stringify(arg.value);
+        if (arg.description !== undefined)
+            return arg.description;
+        return `<${arg.type ?? "unknown"}>`;
+    })
+        .join(" ");
+}
+function notThisCollectorsJob(what) {
+    return { availability: "unavailable", reason: `attachToRunningNodeProcess observes a Node process's Runtime domain (console, exceptions) only, not ${what}.` };
+}
+const CAPABILITIES = {
+    domObservation: notThisCollectorsJob("DOM inspection"),
+    // Reserved for a browser page's console (browser-console-collector.ts's
+    // own claim); this observes a backend process's, reported under
+    // backendLogAccess instead, matching LogCollector's own split.
+    consoleObservation: notThisCollectorsJob("a browser page's console"),
+    networkObservation: notThisCollectorsJob("network traffic"),
+    backendLogAccess: { availability: "available", reason: null },
+    distributedTrace: notThisCollectorsJob("trace-id/request-id correlation — CDP's Runtime domain carries no such fields to extract"),
+    // Self-contained, from V8's own reported call-frame state, the same
+    // standing Go's/Rust's/Ruby's own rows already have — never a side
+    // artifact this collector resolved through. A target running compiled or
+    // bundled output would still report positions in that output verbatim,
+    // the same honest limit every self-contained-reliability adapter in this
+    // repo carries, not something specific to Node inspector observation.
+    sourceMapping: { availability: "available", reason: null },
+    stackCapture: { availability: "available", reason: null },
+    processLifecycle: notThisCollectorsJob("process lifecycle — spawn/ready/exit are ProcessCollector's to observe"),
+    databaseObservation: notThisCollectorsJob("database queries"),
+    externalServiceObservation: notThisCollectorsJob("outbound external requests"),
+};
+/**
+ * Attach to an already-running Node process via `SIGUSR1` + CDP, and start
+ * capturing `CONSOLE_MESSAGE`/`EXCEPTION` evidence from that moment forward.
+ *
+ * **Retroactive, not historical.** Anything the target logged or threw
+ * *before* this attaches is gone — `SIGUSR1` turns the inspector on, it
+ * does not hand over a backlog. `attachToRunningProcess` (the file-based
+ * sibling) is the one that can recover pre-attach lines, and only because a
+ * file on disk already held them; nothing analogous exists for CDP, which
+ * is a live event stream with no buffer of its own.
+ *
+ * Discovery and connection happen inside `start()`, not here — matching
+ * every other `Collector` in this repo (`createBrowserConsoleCollector`,
+ * `createTestRunnerCollector`): a routine failure to attach resolves as
+ * `{ available: false, reason }`, never a thrown exception a caller has to
+ * remember to catch.
+ */
+export function attachToRunningNodeProcess(options) {
+    let session = null;
+    return {
+        collectorId: `attach-node-inspector:${options.processId}`,
+        async start(context) {
+            let webSocketDebuggerUrl;
+            try {
+                webSocketDebuggerUrl = await discoverNodeInspectorUrl(options.pid, {
+                    ...(options.discoveryHost !== undefined ? { host: options.discoveryHost } : {}),
+                    ...(options.discoveryPort !== undefined ? { port: options.discoveryPort } : {}),
+                    ...(options.discoveryTimeoutMs !== undefined ? { timeoutMs: options.discoveryTimeoutMs } : {}),
+                });
+            }
+            catch (error) {
+                return { available: false, reason: error instanceof Error ? error.message : String(error) };
+            }
+            try {
+                session = await connectCdp(webSocketDebuggerUrl);
+            }
+            catch (error) {
+                return {
+                    available: false,
+                    reason: `attachToRunningNodeProcess: found the inspector but could not open a CDP connection to it: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            await session.send("Runtime.enable");
+            session.on("Runtime.consoleAPICalled", (params) => {
+                const p = params;
+                context.emit({
+                    timestamp: new Date().toISOString(),
+                    source: "backend-process",
+                    service: options.service ?? null,
+                    process: options.processId,
+                    eventType: "CONSOLE_MESSAGE",
+                    payload: { level: p.type ?? "log", text: formatConsoleArgs(p.args ?? []) },
+                    traceId: null,
+                    requestId: null,
+                    correlationId: null,
+                    graphNodeId: null,
+                    sourceLocation: null,
+                    stackTrace: null,
+                    confidence: 1,
+                    redactionStatus: "pending-redaction",
+                    collectorVersion: COLLECTOR_VERSION,
+                });
+            });
+            session.on("Runtime.exceptionThrown", (params) => {
+                const p = params;
+                const details = p.exceptionDetails ?? {};
+                const description = details.exception?.description;
+                const message = description !== undefined
+                    ? (description.split("\n")[0] ?? description)
+                    : details.exception?.value !== undefined
+                        ? String(details.exception.value)
+                        : (details.text ?? "Uncaught exception");
+                const callFrames = details.stackTrace?.callFrames ?? [];
+                const frames = callFrames.map((frame) => ({ location: locationFromCallFrame(frame), raw: `${frame.functionName ?? "<anonymous>"} (${frame.url ?? ""}:${String(frame.lineNumber)}:${String(frame.columnNumber)})` }));
+                // No frames from CDP means the throw site itself (url/lineNumber
+                // directly on exceptionDetails) is the only location available —
+                // still real, so it becomes a synthetic one-frame trace rather than
+                // being discarded.
+                const stackTrace = frames.length > 0
+                    ? { fidelity: "synchronous", frames, primaryFrameIndex: 0 }
+                    : {
+                        fidelity: "synchronous",
+                        frames: [{ location: locationFromCallFrame({ url: details.url, lineNumber: details.lineNumber, columnNumber: details.columnNumber }), raw: description ?? message }],
+                        primaryFrameIndex: 0,
+                    };
+                context.emit({
+                    timestamp: new Date().toISOString(),
+                    source: "backend-process",
+                    service: options.service ?? null,
+                    process: options.processId,
+                    eventType: "EXCEPTION",
+                    payload: { message, stack: description ?? null },
+                    traceId: null,
+                    requestId: null,
+                    correlationId: null,
+                    graphNodeId: null,
+                    sourceLocation: stackTrace.frames[stackTrace.primaryFrameIndex]?.location ?? null,
+                    stackTrace,
+                    confidence: 1,
+                    redactionStatus: "pending-redaction",
+                    collectorVersion: COLLECTOR_VERSION,
+                });
+            });
+            return { available: true };
+        },
+        stop() {
+            session?.close();
+            session = null;
+            return Promise.resolve();
+        },
+        capabilities() {
+            return CAPABILITIES;
+        },
+    };
+}
+//# sourceMappingURL=attach-to-running-node-process.js.map

package/dist/attach-to-running-node-process.js.map

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

package/dist/attach-to-running-process.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Attach observation to a process Descry did not spawn (RUNTIME-CHECKLIST.md
+ * §39 item 1's open half — "execute yes; attach: not implemented").
+ *
+ * **What this honestly covers, and what it does not.** Every collector in
+ * this repo reads a `ProcessOutputSource` (`process-output.ts`), and the
+ * only live implementation (`createPollingProcessOutputSource`) is already
+ * source-agnostic — it needs a growing `readOutput(): string` and a boolean
+ * `isFinished()`, nothing that presumes we spawned the process. `execute`
+ * satisfies those from `ManagedProcess`'s in-memory pipe buffer
+ * (`process-manager.ts`), which exists only because `child_process.spawn`
+ * wired the pipes *at spawn time* — Node (and POSIX generally) gives no way
+ * to retroactively attach to another process's stdout/stderr fds after the
+ * fact. So true retroactive attach to an *arbitrary* already-running
+ * process — one that logs to a TTY, or that never wrote its output
+ * anywhere Descry can now reach — is not implemented here and is not a
+ * bounded slice: it would need a per-language debugger/inspector protocol
+ * (e.g. Node's own `SIGUSR1` inspector activation, JVM's Attach API, a
+ * `/proc` ptrace shim on Linux only), each its own multi-week surface,
+ * scoped in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
+ *
+ * What IS real and implemented: attaching to a process that is already
+ * running and was already directed to write its output to a file Descry
+ * can read — e.g. a dev server the user started with
+ * `npm run dev > server.log 2>&1 &`, or any long-lived service whose
+ * stdout/stderr is already redirected to disk. This is candidate (a), not
+ * (b): narrower than generic attach, but a real, testable capability —
+ * `attachToRunningProcess` verifies the target PID is alive, then reuses
+ * the exact same live-tail machinery `execute` uses, catching up on
+ * whatever the file already held *before* attach and then tailing new
+ * writes exactly like a spawned process's buffer.
+ *
+ * **Shares `execute`'s known identity gap (RT-024).** `isProcessAlive`
+ * confirms *a* process with this pid exists, not that it is the one the
+ * caller thinks it is — pids are reused by the OS. `execute`'s own
+ * readiness checks carry the identical caveat (see `readiness.ts`'s own
+ * doc comment) and it is disclosed there rather than solved; the same is
+ * true here, for the same reason: nothing in a bare pid or a bare file
+ * path proves provenance.
+ */
+import type { ProcessOutputSource } from "@descryy/runtime-backend-observation";
+export interface AttachToRunningProcessOptions {
+    readonly processId: string;
+    /** The pid of the already-running target. Verified alive before attaching, and re-checked on every poll to detect exit. */
+    readonly pid: number;
+    /** Path to a file the target process is already writing its stdout/stderr to. Read in full on every poll — same growing-buffer contract `ManagedProcess.readOutput()` has, not a delta. */
+    readonly logFilePath: string;
+    readonly pollIntervalMs?: number;
+}
+/**
+ * `process.kill(pid, 0)` sends no signal — it only asks the kernel whether
+ * delivery would be possible. `ESRCH` means no such pid; `EPERM` means a
+ * pid we don't own but that unambiguously exists, still alive for this
+ * purpose. Any other error is treated as "exists" rather than guessed away.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Attach to an already-running process via a log file it is already
+ * writing to. Throws immediately if the pid is not alive at call time —
+ * refusing rather than returning a source that would silently never emit
+ * anything, the same "loud, not quiet" contract `ProcessCollector` uses for
+ * its own ordering requirement.
+ *
+ * Lines already in `logFilePath` at attach time are yielded first (the
+ * "already running before we attached" evidence this is for), followed by
+ * whatever the target writes afterward — indistinguishable, once attached,
+ * from `execute`'s own live tail.
+ */
+export declare function attachToRunningProcess(options: AttachToRunningProcessOptions): ProcessOutputSource;
+//# sourceMappingURL=attach-to-running-process.d.ts.map

package/dist/attach-to-running-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-to-running-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAIhF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2HAA2H;IAC3H,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2LAA2L;IAC3L,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,mBAAmB,CAuBlG"}

package/dist/attach-to-running-process.js

@@ -0,0 +1,90 @@
+/**
+ * Attach observation to a process Descry did not spawn (RUNTIME-CHECKLIST.md
+ * §39 item 1's open half — "execute yes; attach: not implemented").
+ *
+ * **What this honestly covers, and what it does not.** Every collector in
+ * this repo reads a `ProcessOutputSource` (`process-output.ts`), and the
+ * only live implementation (`createPollingProcessOutputSource`) is already
+ * source-agnostic — it needs a growing `readOutput(): string` and a boolean
+ * `isFinished()`, nothing that presumes we spawned the process. `execute`
+ * satisfies those from `ManagedProcess`'s in-memory pipe buffer
+ * (`process-manager.ts`), which exists only because `child_process.spawn`
+ * wired the pipes *at spawn time* — Node (and POSIX generally) gives no way
+ * to retroactively attach to another process's stdout/stderr fds after the
+ * fact. So true retroactive attach to an *arbitrary* already-running
+ * process — one that logs to a TTY, or that never wrote its output
+ * anywhere Descry can now reach — is not implemented here and is not a
+ * bounded slice: it would need a per-language debugger/inspector protocol
+ * (e.g. Node's own `SIGUSR1` inspector activation, JVM's Attach API, a
+ * `/proc` ptrace shim on Linux only), each its own multi-week surface,
+ * scoped in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
+ *
+ * What IS real and implemented: attaching to a process that is already
+ * running and was already directed to write its output to a file Descry
+ * can read — e.g. a dev server the user started with
+ * `npm run dev > server.log 2>&1 &`, or any long-lived service whose
+ * stdout/stderr is already redirected to disk. This is candidate (a), not
+ * (b): narrower than generic attach, but a real, testable capability —
+ * `attachToRunningProcess` verifies the target PID is alive, then reuses
+ * the exact same live-tail machinery `execute` uses, catching up on
+ * whatever the file already held *before* attach and then tailing new
+ * writes exactly like a spawned process's buffer.
+ *
+ * **Shares `execute`'s known identity gap (RT-024).** `isProcessAlive`
+ * confirms *a* process with this pid exists, not that it is the one the
+ * caller thinks it is — pids are reused by the OS. `execute`'s own
+ * readiness checks carry the identical caveat (see `readiness.ts`'s own
+ * doc comment) and it is disclosed there rather than solved; the same is
+ * true here, for the same reason: nothing in a bare pid or a bare file
+ * path proves provenance.
+ */
+import { readFileSync } from "node:fs";
+import { createPollingProcessOutputSource } from "./polling-output-source.js";
+/**
+ * `process.kill(pid, 0)` sends no signal — it only asks the kernel whether
+ * delivery would be possible. `ESRCH` means no such pid; `EPERM` means a
+ * pid we don't own but that unambiguously exists, still alive for this
+ * purpose. Any other error is treated as "exists" rather than guessed away.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Attach to an already-running process via a log file it is already
+ * writing to. Throws immediately if the pid is not alive at call time —
+ * refusing rather than returning a source that would silently never emit
+ * anything, the same "loud, not quiet" contract `ProcessCollector` uses for
+ * its own ordering requirement.
+ *
+ * Lines already in `logFilePath` at attach time are yielded first (the
+ * "already running before we attached" evidence this is for), followed by
+ * whatever the target writes afterward — indistinguishable, once attached,
+ * from `execute`'s own live tail.
+ */
+export function attachToRunningProcess(options) {
+    if (!isProcessAlive(options.pid)) {
+        throw new Error(`attachToRunningProcess: pid ${options.pid} for "${options.processId}" is not running — attach requires ` +
+            `a target that already exists. Use ExecutionController.run() to spawn a new process instead.`);
+    }
+    return createPollingProcessOutputSource({
+        processId: options.processId,
+        readOutput: () => {
+            try {
+                return readFileSync(options.logFilePath, "utf8");
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new Error(`attachToRunningProcess: could not read log file "${options.logFilePath}" for pid ${options.pid}: ${detail}`);
+            }
+        },
+        isFinished: () => !isProcessAlive(options.pid),
+        ...(options.pollIntervalMs !== undefined ? { pollIntervalMs: options.pollIntervalMs } : {}),
+    });
+}
+//# sourceMappingURL=attach-to-running-process.js.map

package/dist/attach-to-running-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-to-running-process.js","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvC,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAW9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,CAAC,GAAG,SAAS,OAAO,CAAC,SAAS,qCAAqC;YACvG,6FAA6F,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,gCAAgC,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,UAAU,EAAE,GAAG,EAAE;YACf,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtE,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,WAAW,aAAa,OAAO,CAAC,GAAG,KAAK,MAAM,EAAE,CAC7G,CAAC;YACJ,CAAC;QACH,CAAC;QACD,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;QAC9C,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC"}

package/dist/cdp-client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A minimal Chrome DevTools Protocol client over a raw `ws://` URL.
+ *
+ * **Why this exists rather than reusing something already in the repo.**
+ * `packages/browser` speaks CDP too, but only through Playwright's own
+ * `page.on("console"/"pageerror")` API (`browser-console-collector.ts`) —
+ * Playwright owns the actual WebSocket and the Target/Page domain framing
+ * underneath it, and never exposes a bare "connect to an arbitrary `ws://`
+ * endpoint and read raw CDP frames" surface. A Node inspector session has no
+ * `Target`/`Page` domains at all — it is a single top-level session speaking
+ * `Runtime`/`Debugger`/`Console` directly — so Playwright's browser
+ * abstraction does not fit it even if pressed into service. Checked before
+ * writing this: nothing else in the repo opens a WebSocket to a CDP
+ * endpoint directly. This is that client, kept protocol-family-generic (it
+ * knows nothing about "Node" or "browser") so a future CDP target of either
+ * kind can reuse it instead of a third one being written.
+ *
+ * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and
+ * gets exactly one `{id, result}` or `{id, error}` reply; an event has
+ * `method`/`params` and no `id`. This client does nothing more than that
+ * framing — domain-specific method names and event shapes belong to the
+ * caller, not here.
+ */
+export interface CdpSession {
+    /** Sends a CDP command and resolves with its `result` once the matching `id` reply arrives. Rejects on a CDP-reported `error` or if the socket closes first. */
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Subscribes to a CDP event by method name (e.g. `"Runtime.consoleAPICalled"`). Returns an unsubscribe function. */
+    on(method: string, handler: (params: Record<string, unknown>) => void): () => void;
+    /** Closes the underlying WebSocket. Idempotent. Rejects every still-pending `send()`. */
+    close(): void;
+}
+/**
+ * Resolves once the socket is open, or rejects if it errors/closes first —
+ * so a caller never has to race `open` against `error` itself.
+ */
+export declare function connectCdp(webSocketUrl: string): Promise<CdpSession>;
+//# sourceMappingURL=cdp-client.d.ts.map

package/dist/cdp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-client.d.ts","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,UAAU;IACzB,gKAAgK;IAChK,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChF,qHAAqH;IACrH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnF,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACf;AAOD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmFpE"}

package/dist/cdp-client.js

@@ -0,0 +1,111 @@
+/**
+ * A minimal Chrome DevTools Protocol client over a raw `ws://` URL.
+ *
+ * **Why this exists rather than reusing something already in the repo.**
+ * `packages/browser` speaks CDP too, but only through Playwright's own
+ * `page.on("console"/"pageerror")` API (`browser-console-collector.ts`) —
+ * Playwright owns the actual WebSocket and the Target/Page domain framing
+ * underneath it, and never exposes a bare "connect to an arbitrary `ws://`
+ * endpoint and read raw CDP frames" surface. A Node inspector session has no
+ * `Target`/`Page` domains at all — it is a single top-level session speaking
+ * `Runtime`/`Debugger`/`Console` directly — so Playwright's browser
+ * abstraction does not fit it even if pressed into service. Checked before
+ * writing this: nothing else in the repo opens a WebSocket to a CDP
+ * endpoint directly. This is that client, kept protocol-family-generic (it
+ * knows nothing about "Node" or "browser") so a future CDP target of either
+ * kind can reuse it instead of a third one being written.
+ *
+ * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and
+ * gets exactly one `{id, result}` or `{id, error}` reply; an event has
+ * `method`/`params` and no `id`. This client does nothing more than that
+ * framing — domain-specific method names and event shapes belong to the
+ * caller, not here.
+ */
+/**
+ * Resolves once the socket is open, or rejects if it errors/closes first —
+ * so a caller never has to race `open` against `error` itself.
+ */
+export function connectCdp(webSocketUrl) {
+    return new Promise((resolveConnect, rejectConnect) => {
+        const socket = new WebSocket(webSocketUrl);
+        const pending = new Map();
+        const listeners = new Map();
+        let nextId = 1;
+        let settled = false;
+        function failAllPending(error) {
+            for (const { reject } of pending.values())
+                reject(error);
+            pending.clear();
+        }
+        socket.addEventListener("open", () => {
+            settled = true;
+            resolveConnect({
+                send(method, params = {}) {
+                    const id = nextId++;
+                    return new Promise((resolve, reject) => {
+                        pending.set(id, { resolve: resolve, reject });
+                        socket.send(JSON.stringify({ id, method, params }));
+                    });
+                },
+                on(method, handler) {
+                    let set = listeners.get(method);
+                    if (set === undefined) {
+                        set = new Set();
+                        listeners.set(method, set);
+                    }
+                    set.add(handler);
+                    return () => set.delete(handler);
+                },
+                close() {
+                    socket.close();
+                },
+            });
+        });
+        socket.addEventListener("message", (event) => {
+            const raw = typeof event.data === "string" ? event.data : String(event.data);
+            let msg;
+            try {
+                msg = JSON.parse(raw);
+            }
+            catch {
+                // A frame that is not valid JSON is not a valid CDP message from
+                // any target this protocol defines -- dropped rather than thrown,
+                // the same "unparseable stdout is ignorable noise" rule
+                // `test-runner`'s envelope gate applies to its own stream.
+                return;
+            }
+            if (msg.id !== undefined) {
+                const waiting = pending.get(msg.id);
+                if (waiting === undefined)
+                    return;
+                pending.delete(msg.id);
+                if (msg.error !== undefined) {
+                    waiting.reject(new Error(`CDP error for message ${String(msg.id)}: ${msg.error.message}`));
+                }
+                else {
+                    waiting.resolve(msg.result);
+                }
+                return;
+            }
+            if (msg.method !== undefined) {
+                const set = listeners.get(msg.method);
+                if (set === undefined)
+                    return;
+                for (const handler of set)
+                    handler(msg.params ?? {});
+            }
+        });
+        socket.addEventListener("error", () => {
+            const error = new Error(`CDP WebSocket error connecting to ${webSocketUrl}`);
+            if (!settled) {
+                settled = true;
+                rejectConnect(error);
+            }
+            failAllPending(error);
+        });
+        socket.addEventListener("close", () => {
+            failAllPending(new Error(`CDP WebSocket to ${webSocketUrl} closed`));
+        });
+    });
+}
+//# sourceMappingURL=cdp-client.js.map