@jshookmcp/jshook 0.2.8 → 0.3.0

package/dist/TraceRecorder-B41Z5XBj.mjs

@@ -0,0 +1,1286 @@
+import { n as __require } from "./chunk-CjcI7cDX.mjs";
+import { i as resolveArtifactPath } from "./artifacts-DkfosXH3.mjs";
+import { t as formatBetterSqlite3Error } from "./betterSqlite3-DLSBZodi.mjs";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+//#region src/modules/trace/TraceRecorder.internal.ts
+const CDP_EVENTS_BY_DOMAIN = {
+	Debugger: [
+		"Debugger.paused",
+		"Debugger.resumed",
+		"Debugger.scriptParsed"
+	],
+	Runtime: ["Runtime.consoleAPICalled", "Runtime.exceptionThrown"],
+	Network: [
+		"Network.requestWillBeSent",
+		"Network.requestServedFromCache",
+		"Network.responseReceived",
+		"Network.dataReceived",
+		"Network.loadingFinished",
+		"Network.loadingFailed",
+		"Network.eventSourceMessageReceived",
+		"Network.webSocketCreated",
+		"Network.webSocketWillSendHandshakeRequest",
+		"Network.webSocketHandshakeResponseReceived",
+		"Network.webSocketFrameReceived",
+		"Network.webSocketFrameSent",
+		"Network.webSocketFrameError",
+		"Network.webSocketClosed"
+	],
+	Page: ["Page.navigatedWithinDocument", "Page.loadEventFired"]
+};
+const DEFAULT_CDP_DOMAINS = [
+	"Debugger",
+	"Runtime",
+	"Network",
+	"Page"
+];
+const DEFAULT_NETWORK_CAPTURE = {
+	recordResponseBodies: true,
+	streamResponseChunks: true,
+	maxBodyBytes: 10 * 1024 * 1024,
+	inlineBodyBytes: 256 * 1024
+};
+const MAX_INLINE_EVENT_FIELD_BYTES = 16 * 1024;
+const isObjectRecord = (value) => typeof value === "object" && value !== null;
+const asString = (value) => typeof value === "string" ? value : null;
+const asFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+const toCdpMilliseconds = (value) => {
+	const num = asFiniteNumber(value);
+	if (num === null) return null;
+	return num > 0xe8d4a51000 ? num : num * 1e3;
+};
+const isResponseBodyPayload = (value) => isObjectRecord(value) && typeof value.body === "string" && typeof value.base64Encoded === "boolean";
+const extractEventTiming = (params) => {
+	const receivedAt = Date.now();
+	if (!isObjectRecord(params)) return {
+		timestamp: receivedAt,
+		wallTime: receivedAt,
+		monotonicTime: null
+	};
+	const wallTime = toCdpMilliseconds(params["wallTime"]);
+	const monotonicTime = toCdpMilliseconds(params["timestamp"]);
+	return {
+		timestamp: wallTime ?? receivedAt,
+		wallTime: wallTime ?? receivedAt,
+		monotonicTime
+	};
+};
+const extractRequestId = (params) => {
+	if (!isObjectRecord(params)) return null;
+	return typeof params["requestId"] === "string" ? params["requestId"] : null;
+};
+const extractScriptLocation = (eventName, params) => {
+	let scriptId = null;
+	let lineNumber = null;
+	if (!isObjectRecord(params)) return {
+		scriptId,
+		lineNumber
+	};
+	if ("scriptId" in params) scriptId = String(params["scriptId"]);
+	if ("lineNumber" in params) lineNumber = Number(params["lineNumber"]) || null;
+	if (eventName === "Debugger.paused" && Array.isArray(params["callFrames"])) {
+		const frame = params["callFrames"][0];
+		if (frame) {
+			const location = frame["location"];
+			if (location) {
+				scriptId = String(location["scriptId"] ?? scriptId);
+				lineNumber = Number(location["lineNumber"] ?? lineNumber) || null;
+			}
+		}
+	}
+	return {
+		scriptId,
+		lineNumber
+	};
+};
+const sanitizeTracePayload = (eventName, params) => {
+	if (!isObjectRecord(params)) return params ?? {};
+	const cloned = { ...params };
+	if (eventName === "Network.dataReceived" && typeof cloned["data"] === "string") {
+		const chunk = cloned["data"];
+		cloned["hasChunkData"] = true;
+		cloned["chunkDataBytes"] = Buffer.byteLength(chunk, "utf8");
+		cloned["data"] = "[captured in network_chunks]";
+	}
+	if (eventName === "Network.eventSourceMessageReceived" && typeof cloned["data"] === "string" && Buffer.byteLength(cloned["data"], "utf8") > MAX_INLINE_EVENT_FIELD_BYTES) {
+		cloned["data"] = `${cloned["data"].slice(0, MAX_INLINE_EVENT_FIELD_BYTES)}...[truncated]`;
+		cloned["truncatedData"] = true;
+	}
+	if ((eventName === "Network.webSocketFrameReceived" || eventName === "Network.webSocketFrameSent") && isObjectRecord(cloned["response"]) && typeof cloned["response"]["payloadData"] === "string") {
+		const response = { ...cloned["response"] };
+		const payload = response["payloadData"];
+		if (Buffer.byteLength(payload, "utf8") > MAX_INLINE_EVENT_FIELD_BYTES) {
+			response["payloadData"] = `${payload.slice(0, MAX_INLINE_EVENT_FIELD_BYTES)}...[truncated]`;
+			response["truncatedPayloadData"] = true;
+			cloned["response"] = response;
+		}
+	}
+	return cloned;
+};
+const extractRemoteAddress = (response) => {
+	const ip = asString(response["remoteIPAddress"]);
+	const port = asFiniteNumber(response["remotePort"]);
+	if (!ip) return null;
+	return port !== null ? `${ip}:${port}` : ip;
+};
+const createNetworkTraceResource = (requestId) => ({
+	requestId,
+	url: null,
+	method: null,
+	resourceType: null,
+	requestHeaders: "{}",
+	requestPostData: null,
+	status: null,
+	statusText: null,
+	responseHeaders: "{}",
+	mimeType: null,
+	protocol: null,
+	remoteAddress: null,
+	fromDiskCache: false,
+	fromServiceWorker: false,
+	startedWallTime: null,
+	responseWallTime: null,
+	finishedWallTime: null,
+	startedMonotonicTime: null,
+	responseMonotonicTime: null,
+	finishedMonotonicTime: null,
+	encodedDataLength: null,
+	receivedDataLength: 0,
+	receivedEncodedDataLength: 0,
+	chunkCount: 0,
+	streamingEnabled: false,
+	streamingSupported: null,
+	streamingError: null,
+	bodyCaptureState: "none",
+	bodyInline: null,
+	bodyArtifactPath: null,
+	bodyBase64Encoded: false,
+	bodySize: null,
+	bodyTruncated: false,
+	bodyError: null,
+	failed: false,
+	errorText: null
+});
+//#endregion
+//#region src/modules/trace/TraceRecorder.network.ts
+var TraceNetworkCapture = class {
+	resources = /* @__PURE__ */ new Map();
+	options = { ...DEFAULT_NETWORK_CAPTURE };
+	counts = {
+		networkRequestCount: 0,
+		networkChunkCount: 0,
+		networkBodyCount: 0
+	};
+	constructor(deps) {
+		this.deps = deps;
+	}
+	configure(options) {
+		this.resources.clear();
+		this.counts = {
+			networkRequestCount: 0,
+			networkChunkCount: 0,
+			networkBodyCount: 0
+		};
+		this.options = {
+			...DEFAULT_NETWORK_CAPTURE,
+			...options
+		};
+		return this.getOptions();
+	}
+	clear() {
+		this.resources.clear();
+		this.counts = {
+			networkRequestCount: 0,
+			networkChunkCount: 0,
+			networkBodyCount: 0
+		};
+	}
+	getOptions() {
+		return { ...this.options };
+	}
+	getCounts() {
+		return { ...this.counts };
+	}
+	handleEvent(eventName, params, timing) {
+		const requestId = extractRequestId(params);
+		if (!requestId) return;
+		switch (eventName) {
+			case "Network.requestWillBeSent":
+				this.handleRequestWillBeSent(requestId, params, timing);
+				return;
+			case "Network.requestServedFromCache":
+				this.handleRequestServedFromCache(requestId);
+				return;
+			case "Network.responseReceived":
+				this.handleResponseReceived(requestId, params, timing);
+				return;
+			case "Network.dataReceived":
+				this.handleDataReceived(requestId, params, timing);
+				return;
+			case "Network.loadingFinished":
+				this.handleLoadingFinished(requestId, params, timing);
+				return;
+			case "Network.loadingFailed":
+				this.handleLoadingFailed(requestId, params, timing);
+				return;
+			default: return;
+		}
+	}
+	handleRequestWillBeSent(requestId, params, timing) {
+		const resource = this.getOrCreateResource(requestId);
+		const request = isObjectRecord(params) && isObjectRecord(params["request"]) ? params["request"] : null;
+		resource.url = request ? asString(request["url"]) : resource.url;
+		resource.method = request ? asString(request["method"]) : resource.method;
+		resource.resourceType = isObjectRecord(params) && typeof params["type"] === "string" ? params["type"] : resource.resourceType;
+		resource.requestHeaders = request ? JSON.stringify(request["headers"] ?? {}) : resource.requestHeaders;
+		resource.requestPostData = request ? asString(request["postData"]) : resource.requestPostData;
+		resource.startedWallTime = timing.wallTime ?? resource.startedWallTime ?? timing.timestamp;
+		resource.startedMonotonicTime = timing.monotonicTime ?? resource.startedMonotonicTime;
+		this.syncResource(resource);
+	}
+	handleRequestServedFromCache(requestId) {
+		const resource = this.getOrCreateResource(requestId);
+		resource.fromDiskCache = true;
+		this.syncResource(resource);
+	}
+	handleResponseReceived(requestId, params, timing) {
+		const resource = this.getOrCreateResource(requestId);
+		const response = isObjectRecord(params) && isObjectRecord(params["response"]) ? params["response"] : null;
+		resource.url = response ? asString(response["url"]) ?? resource.url : resource.url;
+		resource.status = response ? asFiniteNumber(response["status"]) : resource.status;
+		resource.statusText = response ? asString(response["statusText"]) : resource.statusText;
+		resource.responseHeaders = response ? JSON.stringify(response["headers"] ?? {}) : resource.responseHeaders;
+		resource.mimeType = response ? asString(response["mimeType"]) : resource.mimeType;
+		resource.protocol = response ? asString(response["protocol"]) : resource.protocol;
+		resource.remoteAddress = response ? extractRemoteAddress(response) : resource.remoteAddress;
+		resource.fromDiskCache = response ? Boolean(response["fromDiskCache"]) : resource.fromDiskCache;
+		resource.fromServiceWorker = response ? Boolean(response["fromServiceWorker"]) : resource.fromServiceWorker;
+		resource.responseWallTime = timing.wallTime ?? resource.responseWallTime ?? timing.timestamp;
+		resource.responseMonotonicTime = timing.monotonicTime ?? resource.responseMonotonicTime;
+		this.syncResource(resource);
+		if (this.options.streamResponseChunks && resource.streamingSupported === null) this.deps.trackOperation(this.enableStreamingForRequest(requestId));
+	}
+	handleDataReceived(requestId, params, timing) {
+		const resource = this.getOrCreateResource(requestId);
+		const payload = isObjectRecord(params) ? params : null;
+		const dataLength = payload ? asFiniteNumber(payload["dataLength"]) ?? 0 : 0;
+		const encodedDataLength = payload ? asFiniteNumber(payload["encodedDataLength"]) ?? 0 : 0;
+		const rawChunk = payload ? asString(payload["data"]) : null;
+		resource.receivedDataLength += dataLength;
+		resource.receivedEncodedDataLength += encodedDataLength;
+		resource.chunkCount += 1;
+		const allowChunkData = resource.receivedDataLength <= this.options.maxBodyBytes;
+		const chunk = {
+			requestId,
+			sequence: resource.chunkCount,
+			timestamp: timing.timestamp,
+			monotonicTime: timing.monotonicTime,
+			dataLength,
+			encodedDataLength,
+			chunkData: allowChunkData ? rawChunk : null,
+			chunkIsBase64: rawChunk !== null
+		};
+		try {
+			this.deps.getDb()?.insertNetworkChunk(chunk);
+			this.counts.networkChunkCount++;
+		} catch {}
+		this.syncResource(resource);
+	}
+	handleLoadingFinished(requestId, params, timing) {
+		const resource = this.getOrCreateResource(requestId);
+		resource.finishedWallTime = timing.wallTime ?? timing.timestamp;
+		resource.finishedMonotonicTime = timing.monotonicTime ?? resource.finishedMonotonicTime;
+		if (isObjectRecord(params)) resource.encodedDataLength = asFiniteNumber(params["encodedDataLength"]) ?? resource.encodedDataLength;
+		this.syncResource(resource);
+		if (this.options.recordResponseBodies) this.deps.trackOperation(this.captureResponseBody(requestId));
+	}
+	handleLoadingFailed(requestId, params, timing) {
+		const resource = this.getOrCreateResource(requestId);
+		resource.finishedWallTime = timing.wallTime ?? timing.timestamp;
+		resource.finishedMonotonicTime = timing.monotonicTime ?? resource.finishedMonotonicTime;
+		resource.failed = true;
+		resource.errorText = isObjectRecord(params) ? asString(params["errorText"]) : null;
+		this.syncResource(resource);
+	}
+	async enableStreamingForRequest(requestId) {
+		const cdpSession = this.deps.getCdpSession();
+		const db = this.deps.getDb();
+		if (!cdpSession || !db || !this.options.streamResponseChunks) return;
+		const resource = this.resources.get(requestId);
+		if (!resource || resource.streamingSupported !== null) return;
+		try {
+			const result = await cdpSession.send("Network.streamResourceContent", { requestId });
+			resource.streamingEnabled = true;
+			resource.streamingSupported = true;
+			resource.streamingError = null;
+			if (isObjectRecord(result)) {
+				const bufferedData = asString(result["bufferedData"]);
+				if (bufferedData) {
+					const dataLength = Buffer.from(bufferedData, "base64").length;
+					const bufferedChunk = {
+						requestId,
+						sequence: resource.chunkCount + 1,
+						timestamp: Date.now(),
+						monotonicTime: resource.responseMonotonicTime,
+						dataLength,
+						encodedDataLength: dataLength,
+						chunkData: resource.receivedDataLength + dataLength <= this.options.maxBodyBytes ? bufferedData : null,
+						chunkIsBase64: true
+					};
+					resource.chunkCount += 1;
+					resource.receivedDataLength += dataLength;
+					resource.receivedEncodedDataLength += dataLength;
+					db.insertNetworkChunk(bufferedChunk);
+					this.counts.networkChunkCount++;
+				}
+			}
+		} catch (error) {
+			resource.streamingEnabled = false;
+			resource.streamingSupported = false;
+			resource.streamingError = error instanceof Error ? error.message : String(error);
+		} finally {
+			this.syncResource(resource);
+		}
+	}
+	async captureResponseBody(requestId) {
+		const cdpSession = this.deps.getCdpSession();
+		if (!cdpSession || !this.deps.getDb() || !this.options.recordResponseBodies) return;
+		const resource = this.resources.get(requestId);
+		if (!resource) return;
+		try {
+			const rawResult = await cdpSession.send("Network.getResponseBody", { requestId });
+			if (!isResponseBodyPayload(rawResult)) return;
+			resource.bodyBase64Encoded = rawResult.base64Encoded;
+			resource.bodySize = rawResult.base64Encoded ? Buffer.from(rawResult.body, "base64").length : Buffer.byteLength(rawResult.body, "utf8");
+			resource.bodyTruncated = resource.bodySize > this.options.maxBodyBytes;
+			if (resource.bodyTruncated) {
+				resource.bodyCaptureState = "truncated";
+				resource.bodyInline = rawResult.body.slice(0, this.options.inlineBodyBytes);
+				resource.bodyArtifactPath = null;
+				resource.bodyError = `Body exceeded configured maxBodyBytes (${this.options.maxBodyBytes})`;
+			} else if (resource.bodySize <= this.options.inlineBodyBytes) {
+				resource.bodyCaptureState = "inline";
+				resource.bodyInline = rawResult.body;
+				resource.bodyArtifactPath = null;
+				resource.bodyError = null;
+			} else {
+				const ext = rawResult.base64Encoded ? "b64" : "txt";
+				const { absolutePath } = await resolveArtifactPath({
+					category: "traces",
+					toolName: "trace_body",
+					target: requestId.slice(0, 32),
+					ext
+				});
+				await writeFile(absolutePath, rawResult.body, "utf8");
+				resource.bodyCaptureState = "artifact";
+				resource.bodyInline = null;
+				resource.bodyArtifactPath = absolutePath;
+				resource.bodyError = null;
+			}
+			this.counts.networkBodyCount++;
+		} catch (error) {
+			resource.bodyCaptureState = resource.bodyCaptureState === "none" ? "error" : resource.bodyCaptureState;
+			resource.bodyError = error instanceof Error ? error.message : String(error);
+		} finally {
+			this.syncResource(resource);
+		}
+	}
+	getOrCreateResource(requestId) {
+		const existing = this.resources.get(requestId);
+		if (existing) return existing;
+		const created = createNetworkTraceResource(requestId);
+		this.resources.set(requestId, created);
+		this.counts.networkRequestCount++;
+		return created;
+	}
+	syncResource(resource) {
+		try {
+			this.deps.getDb()?.upsertNetworkResource(resource);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/modules/trace/TraceDB.internal.ts
+function initializeTraceSchema(db) {
+	db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp REAL NOT NULL,
+        category TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        data TEXT NOT NULL DEFAULT '{}',
+        script_id TEXT,
+        line_number INTEGER,
+        wall_time REAL,
+        monotonic_time REAL,
+        request_id TEXT,
+        sequence INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_events_category_type ON events(category, event_type);
+      CREATE INDEX IF NOT EXISTS idx_events_script_id ON events(script_id);
+      CREATE INDEX IF NOT EXISTS idx_events_request_id ON events(request_id);
+
+      CREATE TABLE IF NOT EXISTS memory_deltas (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp REAL NOT NULL,
+        address TEXT NOT NULL,
+        old_value TEXT NOT NULL,
+        new_value TEXT NOT NULL,
+        size INTEGER NOT NULL,
+        value_type TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_memory_timestamp ON memory_deltas(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_memory_address ON memory_deltas(address);
+
+      CREATE TABLE IF NOT EXISTS heap_snapshots (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp REAL NOT NULL,
+        snapshot_data BLOB,
+        summary TEXT NOT NULL DEFAULT '{}'
+      );
+
+      CREATE TABLE IF NOT EXISTS metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS network_resources (
+        request_id TEXT PRIMARY KEY,
+        url TEXT,
+        method TEXT,
+        resource_type TEXT,
+        request_headers TEXT NOT NULL DEFAULT '{}',
+        request_post_data TEXT,
+        status INTEGER,
+        status_text TEXT,
+        response_headers TEXT NOT NULL DEFAULT '{}',
+        mime_type TEXT,
+        protocol TEXT,
+        remote_address TEXT,
+        from_disk_cache INTEGER NOT NULL DEFAULT 0,
+        from_service_worker INTEGER NOT NULL DEFAULT 0,
+        started_wall_time REAL,
+        response_wall_time REAL,
+        finished_wall_time REAL,
+        started_monotonic_time REAL,
+        response_monotonic_time REAL,
+        finished_monotonic_time REAL,
+        encoded_data_length INTEGER,
+        received_data_length INTEGER NOT NULL DEFAULT 0,
+        received_encoded_data_length INTEGER NOT NULL DEFAULT 0,
+        chunk_count INTEGER NOT NULL DEFAULT 0,
+        streaming_enabled INTEGER NOT NULL DEFAULT 0,
+        streaming_supported INTEGER,
+        streaming_error TEXT,
+        body_capture_state TEXT NOT NULL DEFAULT 'none',
+        body_inline TEXT,
+        body_artifact_path TEXT,
+        body_base64_encoded INTEGER NOT NULL DEFAULT 0,
+        body_size INTEGER,
+        body_truncated INTEGER NOT NULL DEFAULT 0,
+        body_error TEXT,
+        failed INTEGER NOT NULL DEFAULT 0,
+        error_text TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_network_resources_started_wall_time
+      ON network_resources(started_wall_time);
+
+      CREATE TABLE IF NOT EXISTS network_chunks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        request_id TEXT NOT NULL,
+        sequence INTEGER NOT NULL,
+        timestamp REAL NOT NULL,
+        monotonic_time REAL,
+        data_length INTEGER NOT NULL,
+        encoded_data_length INTEGER NOT NULL,
+        chunk_data TEXT,
+        chunk_is_base64 INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS idx_network_chunks_request_sequence
+      ON network_chunks(request_id, sequence);
+      CREATE INDEX IF NOT EXISTS idx_network_chunks_timestamp
+      ON network_chunks(timestamp);
+    `);
+	ensureColumn(db, "events", "wall_time", "REAL");
+	ensureColumn(db, "events", "monotonic_time", "REAL");
+	ensureColumn(db, "events", "request_id", "TEXT");
+	ensureColumn(db, "events", "sequence", "INTEGER");
+}
+function prepareTraceStatements(db) {
+	return {
+		insertEventStmt: db.prepare(`
+      INSERT INTO events (
+        timestamp,
+        category,
+        event_type,
+        data,
+        script_id,
+        line_number,
+        wall_time,
+        monotonic_time,
+        request_id,
+        sequence
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `),
+		insertDeltaStmt: db.prepare(`
+      INSERT INTO memory_deltas (timestamp, address, old_value, new_value, size, value_type)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `),
+		insertSnapshotStmt: db.prepare(`
+      INSERT INTO heap_snapshots (timestamp, snapshot_data, summary)
+      VALUES (?, ?, ?)
+    `),
+		upsertMetadataStmt: db.prepare(`
+      INSERT INTO metadata (key, value) VALUES (?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `),
+		upsertNetworkResourceStmt: db.prepare(`
+      INSERT INTO network_resources (
+        request_id,
+        url,
+        method,
+        resource_type,
+        request_headers,
+        request_post_data,
+        status,
+        status_text,
+        response_headers,
+        mime_type,
+        protocol,
+        remote_address,
+        from_disk_cache,
+        from_service_worker,
+        started_wall_time,
+        response_wall_time,
+        finished_wall_time,
+        started_monotonic_time,
+        response_monotonic_time,
+        finished_monotonic_time,
+        encoded_data_length,
+        received_data_length,
+        received_encoded_data_length,
+        chunk_count,
+        streaming_enabled,
+        streaming_supported,
+        streaming_error,
+        body_capture_state,
+        body_inline,
+        body_artifact_path,
+        body_base64_encoded,
+        body_size,
+        body_truncated,
+        body_error,
+        failed,
+        error_text
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(request_id) DO UPDATE SET
+        url = excluded.url,
+        method = excluded.method,
+        resource_type = excluded.resource_type,
+        request_headers = excluded.request_headers,
+        request_post_data = excluded.request_post_data,
+        status = excluded.status,
+        status_text = excluded.status_text,
+        response_headers = excluded.response_headers,
+        mime_type = excluded.mime_type,
+        protocol = excluded.protocol,
+        remote_address = excluded.remote_address,
+        from_disk_cache = excluded.from_disk_cache,
+        from_service_worker = excluded.from_service_worker,
+        started_wall_time = excluded.started_wall_time,
+        response_wall_time = excluded.response_wall_time,
+        finished_wall_time = excluded.finished_wall_time,
+        started_monotonic_time = excluded.started_monotonic_time,
+        response_monotonic_time = excluded.response_monotonic_time,
+        finished_monotonic_time = excluded.finished_monotonic_time,
+        encoded_data_length = excluded.encoded_data_length,
+        received_data_length = excluded.received_data_length,
+        received_encoded_data_length = excluded.received_encoded_data_length,
+        chunk_count = excluded.chunk_count,
+        streaming_enabled = excluded.streaming_enabled,
+        streaming_supported = excluded.streaming_supported,
+        streaming_error = excluded.streaming_error,
+        body_capture_state = excluded.body_capture_state,
+        body_inline = excluded.body_inline,
+        body_artifact_path = excluded.body_artifact_path,
+        body_base64_encoded = excluded.body_base64_encoded,
+        body_size = excluded.body_size,
+        body_truncated = excluded.body_truncated,
+        body_error = excluded.body_error,
+        failed = excluded.failed,
+        error_text = excluded.error_text
+    `),
+		insertNetworkChunkStmt: db.prepare(`
+      INSERT INTO network_chunks (
+        request_id,
+        sequence,
+        timestamp,
+        monotonic_time,
+        data_length,
+        encoded_data_length,
+        chunk_data,
+        chunk_is_base64
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+	};
+}
+function mapEventRow(row) {
+	return {
+		id: row["id"],
+		timestamp: row["timestamp"],
+		category: row["category"],
+		eventType: row["event_type"],
+		data: row["data"],
+		scriptId: row["script_id"] ?? null,
+		lineNumber: row["line_number"] ?? null,
+		wallTime: row["wall_time"] ?? null,
+		monotonicTime: row["monotonic_time"] ?? null,
+		requestId: row["request_id"] ?? null,
+		sequence: row["sequence"] ?? null
+	};
+}
+function mapNetworkChunkRow(row, fromSqliteBoolean) {
+	return {
+		id: row["id"],
+		requestId: row["request_id"],
+		sequence: row["sequence"],
+		timestamp: row["timestamp"],
+		monotonicTime: row["monotonic_time"] ?? null,
+		dataLength: row["data_length"],
+		encodedDataLength: row["encoded_data_length"],
+		chunkData: row["chunk_data"] ?? null,
+		chunkIsBase64: fromSqliteBoolean(row["chunk_is_base64"])
+	};
+}
+function mapNetworkResourceRow(row, fromSqliteBoolean) {
+	return {
+		requestId: row["request_id"],
+		url: row["url"] ?? null,
+		method: row["method"] ?? null,
+		resourceType: row["resource_type"] ?? null,
+		requestHeaders: row["request_headers"] ?? "{}",
+		requestPostData: row["request_post_data"] ?? null,
+		status: row["status"] ?? null,
+		statusText: row["status_text"] ?? null,
+		responseHeaders: row["response_headers"] ?? "{}",
+		mimeType: row["mime_type"] ?? null,
+		protocol: row["protocol"] ?? null,
+		remoteAddress: row["remote_address"] ?? null,
+		fromDiskCache: fromSqliteBoolean(row["from_disk_cache"]),
+		fromServiceWorker: fromSqliteBoolean(row["from_service_worker"]),
+		startedWallTime: row["started_wall_time"] ?? null,
+		responseWallTime: row["response_wall_time"] ?? null,
+		finishedWallTime: row["finished_wall_time"] ?? null,
+		startedMonotonicTime: row["started_monotonic_time"] ?? null,
+		responseMonotonicTime: row["response_monotonic_time"] ?? null,
+		finishedMonotonicTime: row["finished_monotonic_time"] ?? null,
+		encodedDataLength: row["encoded_data_length"] ?? null,
+		receivedDataLength: row["received_data_length"] ?? 0,
+		receivedEncodedDataLength: row["received_encoded_data_length"] ?? 0,
+		chunkCount: row["chunk_count"] ?? 0,
+		streamingEnabled: fromSqliteBoolean(row["streaming_enabled"]),
+		streamingSupported: row["streaming_supported"] === null || row["streaming_supported"] === void 0 ? null : fromSqliteBoolean(row["streaming_supported"]),
+		streamingError: row["streaming_error"] ?? null,
+		bodyCaptureState: row["body_capture_state"] ?? "none",
+		bodyInline: row["body_inline"] ?? null,
+		bodyArtifactPath: row["body_artifact_path"] ?? null,
+		bodyBase64Encoded: fromSqliteBoolean(row["body_base64_encoded"]),
+		bodySize: row["body_size"] ?? null,
+		bodyTruncated: fromSqliteBoolean(row["body_truncated"]),
+		bodyError: row["body_error"] ?? null,
+		failed: fromSqliteBoolean(row["failed"]),
+		errorText: row["error_text"] ?? null
+	};
+}
+function ensureColumn(db, tableName, columnName, definition) {
+	if (db.prepare(`PRAGMA table_info(${tableName})`).all().some((column) => column.name === columnName)) return;
+	db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${definition}`);
+}
+//#endregion
+//#region src/modules/trace/TraceDB.ts
+let Database;
+try {
+	Database = __require("better-sqlite3");
+} catch {}
+/** Write-modify SQL keywords rejected by the safety filter. */
+const WRITE_SQL_PATTERN = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|ATTACH|DETACH|REPLACE|PRAGMA)\b/i;
+var TraceDB = class {
+	db;
+	batchSize;
+	eventBuffer = [];
+	memoryBuffer = [];
+	networkChunkBuffer = [];
+	closed = false;
+	insertEventStmt;
+	insertDeltaStmt;
+	insertSnapshotStmt;
+	upsertMetadataStmt;
+	upsertNetworkResourceStmt;
+	insertNetworkChunkStmt;
+	constructor(options) {
+		this.options = options;
+		if (!Database) throw new Error(formatBetterSqlite3Error(/* @__PURE__ */ new Error("Cannot find package 'better-sqlite3'")));
+		try {
+			this.db = new Database(options.dbPath);
+		} catch (error) {
+			throw new Error(formatBetterSqlite3Error(error), { cause: error });
+		}
+		this.batchSize = options.batchSize ?? 200;
+		this.db.pragma("journal_mode = WAL");
+		this.db.pragma("synchronous = NORMAL");
+		initializeTraceSchema(this.db);
+		const statements = prepareTraceStatements(this.db);
+		this.insertEventStmt = statements.insertEventStmt;
+		this.insertDeltaStmt = statements.insertDeltaStmt;
+		this.insertSnapshotStmt = statements.insertSnapshotStmt;
+		this.upsertMetadataStmt = statements.upsertMetadataStmt;
+		this.upsertNetworkResourceStmt = statements.upsertNetworkResourceStmt;
+		this.insertNetworkChunkStmt = statements.insertNetworkChunkStmt;
+	}
+	/** Database file path. */
+	get dbPath() {
+		return this.options.dbPath;
+	}
+	insertEvent(event) {
+		this.ensureOpen();
+		this.eventBuffer.push(event);
+		if (this.eventBuffer.length >= this.batchSize) this.flush();
+	}
+	insertMemoryDelta(delta) {
+		this.ensureOpen();
+		this.memoryBuffer.push(delta);
+		if (this.memoryBuffer.length >= this.batchSize) this.flush();
+	}
+	insertNetworkChunk(chunk) {
+		this.ensureOpen();
+		this.networkChunkBuffer.push(chunk);
+		if (this.networkChunkBuffer.length >= this.batchSize) this.flush();
+	}
+	upsertNetworkResource(resource) {
+		this.ensureOpen();
+		this.upsertNetworkResourceStmt.run(resource.requestId, resource.url, resource.method, resource.resourceType, resource.requestHeaders, resource.requestPostData, resource.status, resource.statusText, resource.responseHeaders, resource.mimeType, resource.protocol, resource.remoteAddress, resource.fromDiskCache ? 1 : 0, resource.fromServiceWorker ? 1 : 0, resource.startedWallTime, resource.responseWallTime, resource.finishedWallTime, resource.startedMonotonicTime, resource.responseMonotonicTime, resource.finishedMonotonicTime, resource.encodedDataLength, resource.receivedDataLength, resource.receivedEncodedDataLength, resource.chunkCount, resource.streamingEnabled ? 1 : 0, resource.streamingSupported === null ? null : resource.streamingSupported ? 1 : 0, resource.streamingError, resource.bodyCaptureState, resource.bodyInline, resource.bodyArtifactPath, resource.bodyBase64Encoded ? 1 : 0, resource.bodySize, resource.bodyTruncated ? 1 : 0, resource.bodyError, resource.failed ? 1 : 0, resource.errorText);
+	}
+	insertHeapSnapshot(snapshot) {
+		this.ensureOpen();
+		this.insertSnapshotStmt.run(snapshot.timestamp, snapshot.snapshotData, snapshot.summary);
+	}
+	setMetadata(key, value) {
+		this.ensureOpen();
+		this.upsertMetadataStmt.run(key, value);
+	}
+	flush() {
+		if (this.closed) return;
+		this.db.transaction(() => {
+			for (const event of this.eventBuffer) this.insertEventStmt.run(event.timestamp, event.category, event.eventType, event.data, event.scriptId, event.lineNumber, event.wallTime ?? null, event.monotonicTime ?? null, event.requestId ?? null, event.sequence ?? null);
+			for (const delta of this.memoryBuffer) this.insertDeltaStmt.run(delta.timestamp, delta.address, delta.oldValue, delta.newValue, delta.size, delta.valueType);
+			for (const chunk of this.networkChunkBuffer) this.insertNetworkChunkStmt.run(chunk.requestId, chunk.sequence, chunk.timestamp, chunk.monotonicTime, chunk.dataLength, chunk.encodedDataLength, chunk.chunkData, chunk.chunkIsBase64 ? 1 : 0);
+		})();
+		this.eventBuffer = [];
+		this.memoryBuffer = [];
+		this.networkChunkBuffer = [];
+	}
+	query(sql) {
+		this.ensureOpen();
+		if (WRITE_SQL_PATTERN.test(sql)) throw new Error(`Write operations are not allowed in trace queries. Rejected SQL: ${sql.slice(0, 100)}`);
+		const stmt = this.db.prepare(sql);
+		const rows = stmt.all();
+		if (rows.length === 0) return {
+			columns: stmt.columns().map((column) => column.name),
+			rows: [],
+			rowCount: 0
+		};
+		const columns = Object.keys(rows[0]);
+		return {
+			columns,
+			rows: rows.map((row) => columns.map((column) => row[column])),
+			rowCount: rows.length
+		};
+	}
+	getEventsByTimeRange(start, end) {
+		this.ensureOpen();
+		this.flush();
+		return this.db.prepare(`
+      SELECT
+        id,
+        timestamp,
+        category,
+        event_type,
+        data,
+        script_id,
+        line_number,
+        wall_time,
+        monotonic_time,
+        request_id,
+        sequence
+      FROM events
+      WHERE timestamp >= ? AND timestamp <= ?
+      ORDER BY timestamp ASC, sequence ASC, id ASC
+    `).all(start, end).map(mapEventRow);
+	}
+	getEventsByRequestId(requestId) {
+		this.ensureOpen();
+		this.flush();
+		return this.db.prepare(`
+      SELECT
+        id,
+        timestamp,
+        category,
+        event_type,
+        data,
+        script_id,
+        line_number,
+        wall_time,
+        monotonic_time,
+        request_id,
+        sequence
+      FROM events
+      WHERE request_id = ?
+      ORDER BY COALESCE(monotonic_time, timestamp) ASC, sequence ASC, id ASC
+    `).all(requestId).map(mapEventRow);
+	}
+	getNetworkResource(requestId) {
+		this.ensureOpen();
+		this.flush();
+		const row = this.db.prepare(`
+      SELECT *
+      FROM network_resources
+      WHERE request_id = ?
+      LIMIT 1
+    `).get(requestId);
+		return row ? mapNetworkResourceRow(row, this.fromSqliteBoolean) : null;
+	}
+	getNetworkChunks(requestId, limit) {
+		this.ensureOpen();
+		this.flush();
+		const sql = `
+      SELECT
+        id,
+        request_id,
+        sequence,
+        timestamp,
+        monotonic_time,
+        data_length,
+        encoded_data_length,
+        chunk_data,
+        chunk_is_base64
+      FROM network_chunks
+      WHERE request_id = ?
+      ORDER BY sequence ASC
+      ${typeof limit === "number" ? "LIMIT ?" : ""}
+    `;
+		const stmt = this.db.prepare(sql);
+		return (typeof limit === "number" ? stmt.all(requestId, limit) : stmt.all(requestId)).map((row) => mapNetworkChunkRow(row, this.fromSqliteBoolean));
+	}
+	getMemoryDeltasByAddress(address) {
+		this.ensureOpen();
+		this.flush();
+		return this.db.prepare(`
+      SELECT id, timestamp, address, old_value, new_value, size, value_type
+      FROM memory_deltas
+      WHERE address = ?
+      ORDER BY timestamp ASC
+    `).all(address).map((row) => ({
+			id: row["id"],
+			timestamp: row["timestamp"],
+			address: row["address"],
+			oldValue: row["old_value"],
+			newValue: row["new_value"],
+			size: row["size"],
+			valueType: row["value_type"]
+		}));
+	}
+	getHeapSnapshots() {
+		this.ensureOpen();
+		return this.db.prepare(`
+      SELECT id, timestamp, snapshot_data, summary
+      FROM heap_snapshots
+      ORDER BY timestamp ASC
+    `).all().map((row) => ({
+			id: row["id"],
+			timestamp: row["timestamp"],
+			snapshotData: row["snapshot_data"],
+			summary: row["summary"]
+		}));
+	}
+	getMetadata() {
+		this.ensureOpen();
+		const rows = this.db.prepare("SELECT key, value FROM metadata").all();
+		const result = {};
+		for (const row of rows) result[row.key] = row.value;
+		return result;
+	}
+	close() {
+		if (this.closed) return;
+		this.flush();
+		this.db.close();
+		this.closed = true;
+	}
+	get isClosed() {
+		return this.closed;
+	}
+	fromSqliteBoolean(value) {
+		return value === 1 || value === true;
+	}
+	ensureOpen() {
+		if (this.closed) throw new Error("TraceDB is closed");
+	}
+};
+//#endregion
+//#region src/modules/trace/TraceRecorder.ts
+/**
+* TraceRecorder — Event capture engine for time-travel debugging.
+*
+* Subscribes to EventBus and CDP events and persists them into TraceDB.
+*/
+var TraceRecorder = class {
+	db = null;
+	state = "idle";
+	session = null;
+	eventBusUnsub = null;
+	cdpListeners = /* @__PURE__ */ new Map();
+	enabledCdpDomains = /* @__PURE__ */ new Set();
+	cdpSession = null;
+	eventCount = 0;
+	memoryDeltaCount = 0;
+	heapSnapshotCount = 0;
+	eventSequence = 0;
+	pendingOperations = /* @__PURE__ */ new Set();
+	networkCapture = new TraceNetworkCapture({
+		getDb: () => this.db,
+		getCdpSession: () => this.cdpSession,
+		trackOperation: (operation) => this.trackOperation(operation)
+	});
+	/**
+	* Start recording events into a new trace database.
+	*
+	* @param eventBus The server EventBus to subscribe to
+	* @param cdpSession Optional CDP session for browser event recording
+	* @param options Recording configuration
+	* @returns The recording session details
+	*/
+	async start(eventBus, cdpSession, options) {
+		if (this.state === "recording") throw new Error("Recording already in progress");
+		const sessionId = randomUUID();
+		const { absolutePath } = await resolveArtifactPath({
+			category: "traces",
+			toolName: "trace_recorder",
+			target: sessionId.slice(0, 8),
+			ext: "db"
+		});
+		const selectedDomains = cdpSession ? (options?.cdpDomains ?? DEFAULT_CDP_DOMAINS).filter((domain) => CDP_EVENTS_BY_DOMAIN[domain]) : [];
+		this.db = new TraceDB({ dbPath: absolutePath });
+		this.eventCount = 0;
+		this.memoryDeltaCount = 0;
+		this.heapSnapshotCount = 0;
+		this.eventSequence = 0;
+		this.pendingOperations.clear();
+		this.cdpListeners.clear();
+		this.enabledCdpDomains.clear();
+		this.cdpSession = cdpSession;
+		try {
+			const networkOptions = this.networkCapture.configure(options?.network);
+			if (cdpSession) for (const domain of selectedDomains) {
+				await cdpSession.send(`${domain}.enable`);
+				this.enabledCdpDomains.add(domain);
+			}
+			const startedAt = Date.now();
+			this.db.setMetadata("sessionId", sessionId);
+			this.db.setMetadata("platform", process.platform);
+			this.db.setMetadata("startedAt", String(startedAt));
+			this.db.setMetadata("nodeVersion", process.version);
+			this.db.setMetadata("network.recordResponseBodies", String(networkOptions.recordResponseBodies));
+			this.db.setMetadata("network.streamResponseChunks", String(networkOptions.streamResponseChunks));
+			this.db.setMetadata("network.maxBodyBytes", String(networkOptions.maxBodyBytes));
+			this.db.setMetadata("network.inlineBodyBytes", String(networkOptions.inlineBodyBytes));
+			this.eventBusUnsub = eventBus.onAny((wrapped) => {
+				if (this.state !== "recording") return;
+				try {
+					const now = Date.now();
+					this.db?.insertEvent({
+						timestamp: now,
+						wallTime: now,
+						monotonicTime: null,
+						category: this.mapEventCategory(String(wrapped.event)),
+						eventType: String(wrapped.event),
+						data: JSON.stringify(wrapped.payload ?? {}),
+						scriptId: null,
+						lineNumber: null,
+						requestId: null,
+						sequence: this.nextSequence()
+					});
+					this.eventCount++;
+				} catch {}
+			});
+			if (cdpSession) for (const domain of selectedDomains) {
+				const events = CDP_EVENTS_BY_DOMAIN[domain] ?? [];
+				for (const eventName of events) {
+					const handler = (params) => {
+						if (this.state !== "recording" || !this.db) return;
+						try {
+							const timing = extractEventTiming(params);
+							const requestId = extractRequestId(params);
+							const { scriptId, lineNumber } = extractScriptLocation(eventName, params);
+							const data = JSON.stringify(sanitizeTracePayload(eventName, params));
+							this.db.insertEvent({
+								timestamp: timing.timestamp,
+								wallTime: timing.wallTime,
+								monotonicTime: timing.monotonicTime,
+								category: domain.toLowerCase(),
+								eventType: eventName,
+								data,
+								scriptId,
+								lineNumber,
+								requestId,
+								sequence: this.nextSequence()
+							});
+							this.eventCount++;
+							if (domain === "Network") this.networkCapture.handleEvent(eventName, params, timing);
+						} catch {}
+					};
+					cdpSession.on(eventName, handler);
+					this.cdpListeners.set(eventName, handler);
+				}
+			}
+			this.session = {
+				sessionId,
+				dbPath: absolutePath,
+				startedAt,
+				eventCount: 0,
+				memoryDeltaCount: 0,
+				heapSnapshotCount: 0,
+				...this.networkCapture.getCounts()
+			};
+			this.state = "recording";
+			return { ...this.session };
+		} catch (error) {
+			await this.cleanupFailedStart();
+			throw error;
+		}
+	}
+	/**
+	* Record a memory write delta.
+	* Silently ignored if not currently recording.
+	*/
+	recordMemoryDelta(delta) {
+		if (this.state !== "recording" || !this.db) return;
+		try {
+			this.db.insertMemoryDelta(delta);
+			this.memoryDeltaCount++;
+		} catch {}
+	}
+	/**
+	* Capture a heap snapshot via CDP HeapProfiler.
+	* Requires an active CDP session and recording in progress.
+	*/
+	async captureActiveHeapSnapshot() {
+		if (!this.cdpSession) throw new Error("Cannot capture heap snapshot: no active CDP session");
+		return await this.captureHeapSnapshot(this.cdpSession);
+	}
+	async captureHeapSnapshot(cdpSession) {
+		if (this.state !== "recording" || !this.db) throw new Error("Cannot capture heap snapshot: not recording");
+		const chunks = [];
+		let chunkListenerAttached = false;
+		const chunkHandler = (params) => {
+			if (typeof params === "object" && params !== null) {
+				const chunk = params["chunk"];
+				if (typeof chunk === "string") chunks.push(chunk);
+			}
+		};
+		try {
+			await cdpSession.send("HeapProfiler.enable");
+			cdpSession.on("HeapProfiler.addHeapSnapshotChunk", chunkHandler);
+			chunkListenerAttached = true;
+			await cdpSession.send("HeapProfiler.takeHeapSnapshot", { reportProgress: false });
+			const snapshotStr = chunks.join("");
+			const snapshotBuffer = Buffer.from(snapshotStr, "utf-8");
+			const summary = this.extractHeapSummary(snapshotStr);
+			this.db.insertHeapSnapshot({
+				timestamp: Date.now(),
+				snapshotData: snapshotBuffer,
+				summary: JSON.stringify(summary)
+			});
+			this.heapSnapshotCount++;
+			return snapshotBuffer.byteLength;
+		} finally {
+			if (chunkListenerAttached) cdpSession.off("HeapProfiler.addHeapSnapshotChunk", chunkHandler);
+			await cdpSession.send("HeapProfiler.disable").catch(() => {});
+		}
+	}
+	/**
+	* Stop recording and finalize the trace database.
+	* @returns Final session summary with event counts
+	*/
+	async stop() {
+		if (this.state !== "recording") throw new Error("GRACEFUL: Cannot stop: not currently recording");
+		if (this.eventBusUnsub) {
+			this.eventBusUnsub();
+			this.eventBusUnsub = null;
+		}
+		if (this.cdpSession) for (const [event, handler] of this.cdpListeners) this.cdpSession.off(event, handler);
+		this.cdpListeners.clear();
+		await this.waitForPendingOperations();
+		let cleanupErrors;
+		if (this.cdpSession) {
+			if (this.enabledCdpDomains.size > 0) {
+				const enabledDomains = Array.from(this.enabledCdpDomains);
+				cleanupErrors = (await Promise.allSettled(enabledDomains.map((domain) => this.cdpSession.send(`${domain}.disable`)))).flatMap((result, index) => result.status === "rejected" ? [`${enabledDomains[index]}.disable failed: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`] : []);
+			}
+			this.enabledCdpDomains.clear();
+			this.cdpSession = null;
+		}
+		if (this.db) {
+			const stoppedAt = Date.now();
+			const networkCounts = this.networkCapture.getCounts();
+			this.db.setMetadata("stoppedAt", String(stoppedAt));
+			this.db.setMetadata("eventCount", String(this.eventCount));
+			this.db.setMetadata("memoryDeltaCount", String(this.memoryDeltaCount));
+			this.db.setMetadata("heapSnapshotCount", String(this.heapSnapshotCount));
+			this.db.setMetadata("networkRequestCount", String(networkCounts.networkRequestCount));
+			this.db.setMetadata("networkChunkCount", String(networkCounts.networkChunkCount));
+			this.db.setMetadata("networkBodyCount", String(networkCounts.networkBodyCount));
+			this.db.close();
+			if (this.session) {
+				this.session.stoppedAt = stoppedAt;
+				this.session.eventCount = this.eventCount;
+				this.session.memoryDeltaCount = this.memoryDeltaCount;
+				this.session.heapSnapshotCount = this.heapSnapshotCount;
+				this.session.networkRequestCount = networkCounts.networkRequestCount;
+				this.session.networkChunkCount = networkCounts.networkChunkCount;
+				this.session.networkBodyCount = networkCounts.networkBodyCount;
+				if (cleanupErrors && cleanupErrors.length > 0) this.session.cleanupErrors = cleanupErrors;
+				else delete this.session.cleanupErrors;
+			}
+		}
+		this.state = "stopped";
+		const finalSession = this.session ? { ...this.session } : this.createEmptySession();
+		this.db = null;
+		this.networkCapture.clear();
+		return finalSession;
+	}
+	/** Get the current recording state. */
+	getState() {
+		return this.state;
+	}
+	/** Get the current session details (null if not recording). */
+	getSession() {
+		return this.session ? { ...this.session } : null;
+	}
+	/** Get the active TraceDB instance (null if not recording). */
+	getDB() {
+		return this.db;
+	}
+	trackOperation(operation) {
+		this.pendingOperations.add(operation);
+		operation.finally(() => {
+			this.pendingOperations.delete(operation);
+		});
+	}
+	async waitForPendingOperations() {
+		while (this.pendingOperations.size > 0) await Promise.allSettled(Array.from(this.pendingOperations));
+	}
+	async cleanupFailedStart() {
+		if (this.eventBusUnsub) {
+			this.eventBusUnsub();
+			this.eventBusUnsub = null;
+		}
+		if (this.cdpSession) for (const [event, handler] of this.cdpListeners) this.cdpSession.off(event, handler);
+		this.cdpListeners.clear();
+		if (this.cdpSession && this.enabledCdpDomains.size > 0) await Promise.allSettled(Array.from(this.enabledCdpDomains).map((domain) => this.cdpSession.send(`${domain}.disable`)));
+		this.enabledCdpDomains.clear();
+		this.cdpSession = null;
+		if (this.db) {
+			try {
+				this.db.close();
+			} catch {}
+			this.db = null;
+		}
+		this.session = null;
+		this.state = "idle";
+		this.eventCount = 0;
+		this.memoryDeltaCount = 0;
+		this.heapSnapshotCount = 0;
+		this.eventSequence = 0;
+		this.pendingOperations.clear();
+		this.networkCapture.clear();
+	}
+	nextSequence() {
+		this.eventSequence += 1;
+		return this.eventSequence;
+	}
+	/**
+	* Map an EventBus event name to a trace category.
+	* E.g., 'tool:called' → 'tool', 'debugger:breakpoint_hit' → 'debugger'
+	*/
+	mapEventCategory(event) {
+		const colonIdx = event.indexOf(":");
+		return colonIdx > 0 ? event.substring(0, colonIdx) : "other";
+	}
+	/**
+	* Extract a lightweight summary from a V8 heap snapshot.
+	* Only parses the minimal structure needed for diffing.
+	*/
+	extractHeapSummary(snapshotStr) {
+		try {
+			const snapshot = JSON.parse(snapshotStr);
+			const snapshotInfo = snapshot["snapshot"];
+			if (!snapshotInfo) return {
+				totalSize: 0,
+				nodeCount: 0,
+				objectCounts: {}
+			};
+			const meta = snapshotInfo["meta"];
+			const nodeCount = snapshotInfo["node_count"] ?? 0;
+			const nodeFields = meta?.["node_fields"];
+			const nodeTypes = meta?.["node_types"];
+			const nodes = snapshot["nodes"];
+			const objectCounts = {};
+			let totalSize = 0;
+			if (nodeFields && nodes && nodeTypes) {
+				const fieldCount = nodeFields.length;
+				const typeIndex = nodeFields.indexOf("type");
+				const nameIndex = nodeFields.indexOf("name");
+				const selfSizeIndex = nodeFields.indexOf("self_size");
+				const strings = snapshot["strings"] ?? [];
+				for (let i = 0; i < nodes.length; i += fieldCount) {
+					const selfSize = selfSizeIndex >= 0 ? nodes[i + selfSizeIndex] ?? 0 : 0;
+					totalSize += selfSize;
+					if (nameIndex >= 0) {
+						const name = strings[nodes[i + nameIndex] ?? 0] ?? `type_${nodes[i + (typeIndex >= 0 ? typeIndex : 0)]}`;
+						if (name) objectCounts[name] = (objectCounts[name] ?? 0) + 1;
+					}
+				}
+			}
+			return {
+				totalSize,
+				nodeCount,
+				objectCounts
+			};
+		} catch {
+			return {
+				totalSize: 0,
+				nodeCount: 0,
+				objectCounts: {}
+			};
+		}
+	}
+	createEmptySession() {
+		return {
+			sessionId: "",
+			dbPath: "",
+			startedAt: 0,
+			eventCount: 0,
+			memoryDeltaCount: 0,
+			heapSnapshotCount: 0,
+			networkRequestCount: 0,
+			networkChunkCount: 0,
+			networkBodyCount: 0
+		};
+	}
+};
+//#endregion
+export { TraceRecorder, TraceDB as t };