@jshookmcp/jshook 0.2.9 → 0.3.0

package/dist/handlers-HujRKC3b.mjs

@@ -0,0 +1,661 @@
+import { i as resolveArtifactPath } from "./artifacts-DkfosXH3.mjs";
+import { t as TraceDB } from "./TraceRecorder-B41Z5XBj.mjs";
+import { n as argEnum } from "./parse-args-B4cY5Vx5.mjs";
+import { t as R } from "./ResponseBuilder-CJXWmWNw.mjs";
+import { readFile, writeFile } from "node:fs/promises";
+//#region src/server/domains/trace/handler-utils.ts
+const TRACE_DETAIL_THRESHOLD_BYTES = 25600;
+const asBoolean = (value, defaultValue) => typeof value === "boolean" ? value : defaultValue;
+const asNumber = (value, options) => {
+	let parsed = typeof value === "number" && Number.isFinite(value) ? value : options.defaultValue;
+	if (options.integer) parsed = Math.trunc(parsed);
+	if (typeof options.min === "number") parsed = Math.max(options.min, parsed);
+	if (typeof options.max === "number") parsed = Math.min(options.max, parsed);
+	return parsed;
+};
+const rowToObject = (columns, row) => {
+	const obj = {};
+	for (let i = 0; i < columns.length; i++) obj[columns[i]] = row[i];
+	return obj;
+};
+const safeParseJSON = (str) => {
+	try {
+		return JSON.parse(str);
+	} catch {
+		return str;
+	}
+};
+const formatTraceEvent = (event) => ({
+	timestamp: event.timestamp,
+	wallTime: event.wallTime ?? null,
+	monotonicTime: event.monotonicTime ?? null,
+	category: event.category,
+	eventType: event.eventType,
+	data: typeof event.data === "string" ? safeParseJSON(event.data) : event.data,
+	scriptId: event.scriptId,
+	lineNumber: event.lineNumber,
+	requestId: event.requestId ?? null,
+	sequence: event.sequence ?? null
+});
+const formatNetworkResource = (resource) => ({
+	requestId: resource.requestId,
+	url: resource.url,
+	method: resource.method,
+	resourceType: resource.resourceType,
+	requestHeaders: safeParseJSON(resource.requestHeaders),
+	requestPostDataPresent: resource.requestPostData !== null,
+	status: resource.status,
+	statusText: resource.statusText,
+	responseHeaders: safeParseJSON(resource.responseHeaders),
+	mimeType: resource.mimeType,
+	protocol: resource.protocol,
+	remoteAddress: resource.remoteAddress,
+	fromDiskCache: resource.fromDiskCache,
+	fromServiceWorker: resource.fromServiceWorker,
+	startedWallTime: resource.startedWallTime,
+	responseWallTime: resource.responseWallTime,
+	finishedWallTime: resource.finishedWallTime,
+	startedMonotonicTime: resource.startedMonotonicTime,
+	responseMonotonicTime: resource.responseMonotonicTime,
+	finishedMonotonicTime: resource.finishedMonotonicTime,
+	encodedDataLength: resource.encodedDataLength,
+	receivedDataLength: resource.receivedDataLength,
+	receivedEncodedDataLength: resource.receivedEncodedDataLength,
+	chunkCount: resource.chunkCount,
+	streamingEnabled: resource.streamingEnabled,
+	streamingSupported: resource.streamingSupported,
+	streamingError: resource.streamingError,
+	bodyCaptureState: resource.bodyCaptureState,
+	bodySize: resource.bodySize,
+	bodyBase64Encoded: resource.bodyBase64Encoded,
+	bodyTruncated: resource.bodyTruncated,
+	bodyArtifactPath: resource.bodyArtifactPath,
+	bodyError: resource.bodyError,
+	failed: resource.failed,
+	errorText: resource.errorText
+});
+const formatNetworkChunk = (chunk) => ({
+	sequence: chunk.sequence,
+	timestamp: chunk.timestamp,
+	monotonicTime: chunk.monotonicTime,
+	dataLength: chunk.dataLength,
+	encodedDataLength: chunk.encodedDataLength,
+	hasChunkData: chunk.chunkData !== null,
+	chunkPreview: chunk.chunkData !== null ? `${chunk.chunkData.slice(0, 120)}${chunk.chunkData.length > 120 ? "..." : ""}` : null,
+	chunkIsBase64: chunk.chunkIsBase64
+});
+const readTraceBody = async (resource, options) => {
+	if (resource.bodyCaptureState === "none" && resource.bodyInline === null && resource.bodyArtifactPath === null) return null;
+	const body = await readPersistedBody(resource);
+	if (body === null) return {
+		state: resource.bodyCaptureState,
+		error: resource.bodyError ?? "Body content is not available",
+		truncated: resource.bodyTruncated
+	};
+	const size = resource.bodySize ?? body.length;
+	if (options.returnSummary || size > options.maxBodyBytes) return {
+		state: resource.bodyCaptureState,
+		summary: {
+			size,
+			sizeKB: (size / 1024).toFixed(2),
+			base64Encoded: resource.bodyBase64Encoded,
+			preview: `${body.slice(0, 500)}${body.length > 500 ? "..." : ""}`,
+			truncated: resource.bodyTruncated || size > options.maxBodyBytes,
+			reason: options.returnSummary ? "Summary mode enabled" : `Response too large (${(size / 1024).toFixed(2)} KB > ${(options.maxBodyBytes / 1024).toFixed(2)} KB)`
+		}
+	};
+	return {
+		state: resource.bodyCaptureState,
+		body,
+		base64Encoded: resource.bodyBase64Encoded,
+		size,
+		sizeKB: (size / 1024).toFixed(2),
+		truncated: resource.bodyTruncated,
+		...resource.bodyError ? { warning: resource.bodyError } : {}
+	};
+};
+const readEventsByExpression = (db, timeExpr, start, end) => {
+	return db.query(`
+      SELECT
+        timestamp,
+        category,
+        event_type,
+        data,
+        script_id,
+        line_number,
+        wall_time,
+        monotonic_time,
+        request_id,
+        sequence
+      FROM events
+      WHERE ${timeExpr} >= ${start} AND ${timeExpr} <= ${end}
+      ORDER BY ${timeExpr} ASC, sequence ASC
+    `).rows.map((row) => ({
+		timestamp: row[0],
+		category: row[1],
+		eventType: row[2],
+		data: row[3],
+		scriptId: row[4] ?? null,
+		lineNumber: row[5] ?? null,
+		wallTime: row[6] ?? null,
+		monotonicTime: row[7] ?? null,
+		requestId: row[8] ?? null,
+		sequence: row[9] ?? null
+	}));
+};
+const smartHandleDetailed = (ctx, payload) => {
+	const detailedData = ctx.detailedData;
+	return detailedData ? detailedData.smartHandle(payload, TRACE_DETAIL_THRESHOLD_BYTES) : payload;
+};
+const getDbForReading = (recorder, dbPath) => {
+	if (dbPath) return new TraceDB({ dbPath });
+	const activeDb = recorder.getDB();
+	if (!activeDb) throw new Error("GRACEFUL: No active recording and no dbPath specified. Start a recording or provide a dbPath.");
+	activeDb.flush();
+	return activeDb;
+};
+const readPersistedBody = async (resource) => {
+	if (typeof resource.bodyInline === "string") return resource.bodyInline;
+	if (resource.bodyArtifactPath) return readFile(resource.bodyArtifactPath, "utf8");
+	return null;
+};
+//#endregion
+//#region src/server/domains/trace/TraceSummarizer.ts
+/**
+* Summarize trace events at the specified detail level.
+*/
+function summarizeEvents(events, detail = "balanced") {
+	if (events.length === 0) return {
+		detail,
+		totalEvents: 0,
+		timeRange: {
+			start: 0,
+			end: 0,
+			durationMs: 0
+		},
+		categories: [],
+		keyMoments: detail !== "compact" ? [] : void 0
+	};
+	const timestamps = events.map((e) => e.timestamp);
+	const start = Math.min(...timestamps);
+	const end = Math.max(...timestamps);
+	const catMap = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		let cat = catMap.get(event.category);
+		if (!cat) {
+			cat = {
+				count: 0,
+				first: event.timestamp,
+				last: event.timestamp,
+				types: /* @__PURE__ */ new Map()
+			};
+			catMap.set(event.category, cat);
+		}
+		cat.count++;
+		cat.first = Math.min(cat.first, event.timestamp);
+		cat.last = Math.max(cat.last, event.timestamp);
+		cat.types.set(event.eventType, (cat.types.get(event.eventType) ?? 0) + 1);
+	}
+	const categories = [...catMap.entries()].toSorted((a, b) => b[1].count - a[1].count).map(([category, info]) => ({
+		category,
+		count: info.count,
+		firstTimestamp: info.first,
+		lastTimestamp: info.last,
+		topEventTypes: [...info.types.entries()].toSorted((a, b) => b[1] - a[1]).slice(0, 5).map(([type, count]) => ({
+			type,
+			count
+		}))
+	}));
+	const summary = {
+		detail,
+		totalEvents: events.length,
+		timeRange: {
+			start,
+			end,
+			durationMs: end - start
+		},
+		categories
+	};
+	if (detail === "balanced" || detail === "full") summary.keyMoments = extractKeyMoments(events);
+	return summary;
+}
+/**
+* Extract key moments from a trace event stream.
+*
+* Identifies:
+* - Debugger pauses (breakpoint hits)
+* - Network request completions
+* - Runtime exceptions
+* - Page navigations
+*/
+function extractKeyMoments(events) {
+	const moments = [];
+	for (const event of events) if (event.eventType === "Debugger.paused") moments.push({
+		timestamp: event.timestamp,
+		type: "breakpoint",
+		description: `Debugger paused${event.scriptId ? ` at script ${event.scriptId}` : ""}${event.lineNumber ? `:${event.lineNumber}` : ""}`,
+		data: event.data
+	});
+	else if (event.eventType === "Network.loadingFinished") moments.push({
+		timestamp: event.timestamp,
+		type: "network_complete",
+		description: "Network request completed",
+		data: event.data
+	});
+	else if (event.eventType === "Runtime.exceptionThrown") moments.push({
+		timestamp: event.timestamp,
+		type: "exception",
+		description: "Runtime exception thrown",
+		data: event.data
+	});
+	else if (event.eventType === "Page.frameNavigated" || event.eventType === "Page.navigatedWithinDocument") moments.push({
+		timestamp: event.timestamp,
+		type: "navigation",
+		description: "Page navigation",
+		data: event.data
+	});
+	return moments;
+}
+/**
+* Summarize memory deltas, detecting anomalies.
+*
+* An anomaly is defined as an address that receives significantly more
+* writes than the average (> 3× the mean write count).
+*/
+function summarizeMemoryDeltas(deltas) {
+	if (deltas.length === 0) return {
+		totalDeltas: 0,
+		uniqueAddresses: 0,
+		anomalies: [],
+		topAddresses: []
+	};
+	const writeMap = /* @__PURE__ */ new Map();
+	for (const delta of deltas) writeMap.set(delta.address, (writeMap.get(delta.address) ?? 0) + 1);
+	const uniqueAddresses = writeMap.size;
+	const totalWrites = deltas.length;
+	const meanWrites = totalWrites / uniqueAddresses;
+	const sorted = [...writeMap.entries()].toSorted((a, b) => b[1] - a[1]);
+	const topAddresses = sorted.slice(0, 10).map(([address, writeCount]) => ({
+		address,
+		writeCount
+	}));
+	const anomalyThreshold = meanWrites * 3;
+	return {
+		totalDeltas: totalWrites,
+		uniqueAddresses,
+		anomalies: sorted.filter(([, count]) => count > anomalyThreshold).map(([address, writeCount]) => ({
+			address,
+			writeCount,
+			description: `${writeCount} writes (${(writeCount / meanWrites).toFixed(1)}× average)`
+		})),
+		topAddresses
+	};
+}
+//#endregion
+//#region src/server/domains/trace/handlers.ts
+/**
+* Trace domain tool handlers.
+*
+* Implements recording lifecycle, SQL query, timestamp seek,
+* request-scoped network flow retrieval, heap diffing, and export.
+*/
+var TraceToolHandlers = class {
+	constructor(recorder, ctx) {
+		this.recorder = recorder;
+		this.ctx = ctx;
+	}
+	async handleTraceRecording(args) {
+		return argEnum(args, "action", new Set(["start", "stop"])) === "stop" ? this.handleStopTraceRecording() : this.handleStartTraceRecording(args);
+	}
+	async handleStartTraceRecording(args) {
+		const cdpDomains = args["cdpDomains"];
+		const recordMemoryDeltas = args["recordMemoryDeltas"];
+		const recordResponseBodies = args["recordResponseBodies"];
+		const streamResponseChunks = args["streamResponseChunks"];
+		const networkBodyMaxBytes = args["networkBodyMaxBytes"];
+		const networkInlineBodyBytes = args["networkInlineBodyBytes"];
+		const eventBus = this.ctx.eventBus;
+		if (!eventBus) throw new Error("EventBus not available on server context");
+		let cdpSession = null;
+		try {
+			if (this.ctx.collector) {
+				const pageAny = await this.ctx.collector.getActivePage();
+				if (typeof pageAny.createCDPSession === "function") cdpSession = await pageAny.createCDPSession();
+			}
+		} catch {}
+		const session = await this.recorder.start(eventBus, cdpSession, {
+			cdpDomains,
+			recordMemoryDeltas: recordMemoryDeltas ?? true,
+			network: {
+				recordResponseBodies,
+				streamResponseChunks,
+				maxBodyBytes: networkBodyMaxBytes,
+				inlineBodyBytes: networkInlineBodyBytes
+			}
+		});
+		return R.ok().merge({
+			status: "recording",
+			sessionId: session.sessionId,
+			dbPath: session.dbPath,
+			network: {
+				recordResponseBodies: recordResponseBodies ?? true,
+				streamResponseChunks: streamResponseChunks ?? true,
+				maxBodyBytes: networkBodyMaxBytes ?? 10 * 1024 * 1024,
+				inlineBodyBytes: networkInlineBodyBytes ?? 256 * 1024
+			},
+			message: `Recording started. CDP session: ${cdpSession ? "active" : "not available"}`
+		}).json();
+	}
+	async handleStopTraceRecording() {
+		const session = await this.recorder.stop();
+		const duration = session.stoppedAt ? session.stoppedAt - session.startedAt : 0;
+		const cleanupErrors = session.cleanupErrors ?? [];
+		const status = cleanupErrors.length > 0 ? "stopped_with_errors" : "stopped";
+		return R.ok().merge({
+			status,
+			sessionId: session.sessionId,
+			dbPath: session.dbPath,
+			eventCount: session.eventCount,
+			memoryDeltaCount: session.memoryDeltaCount,
+			heapSnapshotCount: session.heapSnapshotCount,
+			networkRequestCount: session.networkRequestCount ?? 0,
+			networkChunkCount: session.networkChunkCount ?? 0,
+			networkBodyCount: session.networkBodyCount ?? 0,
+			durationMs: duration,
+			...cleanupErrors.length > 0 ? { cleanupErrors } : {},
+			message: cleanupErrors.length > 0 ? `Recording stopped with cleanup errors. ${session.eventCount} events, ${session.memoryDeltaCount} memory deltas, ${session.heapSnapshotCount} heap snapshots, ${session.networkRequestCount ?? 0} network requests, ${session.networkChunkCount ?? 0} network chunks, ${session.networkBodyCount ?? 0} response bodies recorded.` : `Recording stopped. ${session.eventCount} events, ${session.memoryDeltaCount} memory deltas, ${session.heapSnapshotCount} heap snapshots, ${session.networkRequestCount ?? 0} network requests, ${session.networkChunkCount ?? 0} network chunks, ${session.networkBodyCount ?? 0} response bodies recorded.`
+		}).json();
+	}
+	async handleQueryTraceSql(args) {
+		const sql = args["sql"];
+		const dbPath = args["dbPath"];
+		if (!sql) throw new Error("sql parameter is required");
+		let result;
+		let tempDb = null;
+		try {
+			if (dbPath) {
+				tempDb = new TraceDB({ dbPath });
+				result = tempDb.query(sql);
+			} else {
+				const activeDb = this.recorder.getDB();
+				if (!activeDb) throw new Error("GRACEFUL: No active recording and no dbPath specified. Start a recording or provide a dbPath.");
+				activeDb.flush();
+				result = activeDb.query(sql);
+			}
+			return R.ok().merge({
+				columns: result.columns,
+				rows: result.rows,
+				rowCount: result.rowCount
+			}).json();
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleSeekToTimestamp(args) {
+		const timestamp = args["timestamp"];
+		const dbPath = args["dbPath"];
+		const windowMs = args["windowMs"] ?? 100;
+		const timeDomain = args["timeDomain"] ?? "wall";
+		if (!timestamp) throw new Error("timestamp parameter is required");
+		let tempDb = null;
+		try {
+			const db = getDbForReading(this.recorder, dbPath);
+			if (dbPath) tempDb = db;
+			const eventTimeExpr = timeDomain === "monotonic" ? "COALESCE(monotonic_time, timestamp)" : "timestamp";
+			const networkTimeExpr = timeDomain === "monotonic" ? "COALESCE(finished_monotonic_time, response_monotonic_time, started_monotonic_time)" : "COALESCE(finished_wall_time, response_wall_time, started_wall_time)";
+			const events = timeDomain === "wall" ? db.getEventsByTimeRange(timestamp - windowMs, timestamp + windowMs) : readEventsByExpression(db, eventTimeExpr, timestamp - windowMs, timestamp + windowMs);
+			const debuggerEventsResult = db.query(`SELECT * FROM events WHERE category = 'debugger' AND ${eventTimeExpr} <= ${timestamp} ORDER BY ${eventTimeExpr} DESC, sequence DESC LIMIT 5`);
+			const memoryStateResult = timeDomain === "wall" ? db.query(`SELECT m1.* FROM memory_deltas m1
+               INNER JOIN (SELECT address, MAX(timestamp) as max_ts FROM memory_deltas WHERE timestamp <= ${timestamp} GROUP BY address) m2
+               ON m1.address = m2.address AND m1.timestamp = m2.max_ts
+               ORDER BY m1.address`) : null;
+			let networkResult = db.query(`SELECT * FROM network_resources
+         WHERE ${networkTimeExpr} IS NOT NULL AND ${networkTimeExpr} <= ${timestamp}
+         ORDER BY ${networkTimeExpr} DESC
+         LIMIT 20`);
+			if (networkResult.rowCount === 0) networkResult = db.query(`SELECT * FROM events
+           WHERE category = 'network'
+             AND event_type = 'Network.loadingFinished'
+             AND ${eventTimeExpr} <= ${timestamp}
+           ORDER BY ${eventTimeExpr} DESC
+           LIMIT 20`);
+			const snapshotResult = timeDomain === "wall" ? db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 1`) : null;
+			return R.ok().merge({
+				seekTimestamp: timestamp,
+				timeDomain,
+				windowMs,
+				events: events.map(formatTraceEvent),
+				debuggerState: { recentEvents: debuggerEventsResult.rows.map((row) => rowToObject(debuggerEventsResult.columns, row)) },
+				memoryState: {
+					addressValues: memoryStateResult?.rows.map((row) => rowToObject(memoryStateResult.columns, row)) ?? [],
+					...timeDomain === "monotonic" ? { omittedReason: "Memory state is only indexed by wall-clock timestamps and is omitted for monotonic seeks." } : {}
+				},
+				networkState: { completedRequests: networkResult.rows.map((row) => rowToObject(networkResult.columns, row)) },
+				nearestHeapSnapshot: snapshotResult && snapshotResult.rows.length > 0 ? rowToObject(snapshotResult.columns, snapshotResult.rows[0]) : null,
+				...timeDomain === "monotonic" ? { nearestHeapSnapshotOmittedReason: "Heap snapshots are only indexed by wall-clock timestamps and are omitted for monotonic seeks." } : {}
+			}).json();
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleGetTraceNetworkFlow(args) {
+		const requestId = typeof args["requestId"] === "string" ? args["requestId"] : "";
+		const dbPath = args["dbPath"];
+		const includeBody = asBoolean(args["includeBody"], true);
+		const includeChunks = asBoolean(args["includeChunks"], true);
+		const includeEvents = asBoolean(args["includeEvents"], true);
+		const chunkLimit = asNumber(args["chunkLimit"], {
+			defaultValue: 200,
+			min: 1,
+			max: 5e3,
+			integer: true
+		});
+		const maxBodyBytes = asNumber(args["maxBodyBytes"], {
+			defaultValue: 1e5,
+			min: 1024,
+			max: 50 * 1024 * 1024,
+			integer: true
+		});
+		const returnSummary = asBoolean(args["returnSummary"], false);
+		if (!requestId) throw new Error("requestId parameter is required");
+		let tempDb = null;
+		try {
+			const db = getDbForReading(this.recorder, dbPath);
+			if (dbPath) tempDb = db;
+			const resource = db.getNetworkResource(requestId);
+			if (!resource) throw new Error(`No recorded network flow found for requestId: ${requestId}`);
+			const chunks = includeChunks ? db.getNetworkChunks(requestId, chunkLimit) : [];
+			const events = includeEvents ? db.getEventsByRequestId(requestId) : [];
+			const body = includeBody ? await readTraceBody(resource, {
+				maxBodyBytes,
+				returnSummary
+			}) : null;
+			const flowData = smartHandleDetailed(this.ctx, {
+				requestId,
+				request: formatNetworkResource(resource),
+				body,
+				chunks: includeChunks ? {
+					total: resource.chunkCount,
+					returned: chunks.length,
+					limit: chunkLimit,
+					hasMore: resource.chunkCount > chunks.length,
+					items: chunks.map(formatNetworkChunk)
+				} : null,
+				events: includeEvents ? events.map(formatTraceEvent) : null
+			});
+			return R.ok().merge(flowData).json();
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleDiffHeapSnapshots(args) {
+		const snapshotId1 = args["snapshotId1"];
+		const snapshotId2 = args["snapshotId2"];
+		const dbPath = args["dbPath"];
+		if (!snapshotId1 || !snapshotId2) throw new Error("snapshotId1 and snapshotId2 are required");
+		let tempDb = null;
+		try {
+			const db = getDbForReading(this.recorder, dbPath);
+			if (dbPath) tempDb = db;
+			const snap1Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId1}`);
+			const snap2Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId2}`);
+			if (snap1Result.rowCount === 0) throw new Error(`Snapshot with id ${snapshotId1} not found`);
+			if (snap2Result.rowCount === 0) throw new Error(`Snapshot with id ${snapshotId2} not found`);
+			const snap1Row = rowToObject(snap1Result.columns, snap1Result.rows[0]);
+			const snap2Row = rowToObject(snap2Result.columns, snap2Result.rows[0]);
+			const summary1 = safeParseJSON(snap1Row["summary"]);
+			const summary2 = safeParseJSON(snap2Row["summary"]);
+			const counts1 = summary1["objectCounts"] ?? {};
+			const counts2 = summary2["objectCounts"] ?? {};
+			const allKeys = new Set([...Object.keys(counts1), ...Object.keys(counts2)]);
+			const added = [];
+			const removed = [];
+			const changed = [];
+			for (const key of allKeys) {
+				const c1 = counts1[key] ?? 0;
+				const c2 = counts2[key] ?? 0;
+				if (c1 === 0 && c2 > 0) added.push({
+					name: key,
+					count: c2
+				});
+				else if (c1 > 0 && c2 === 0) removed.push({
+					name: key,
+					count: c1
+				});
+				else if (c1 !== c2) changed.push({
+					name: key,
+					countBefore: c1,
+					countAfter: c2,
+					delta: c2 - c1
+				});
+			}
+			changed.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+			const totalSize1 = summary1["totalSize"] ?? 0;
+			const totalSize2 = summary2["totalSize"] ?? 0;
+			return R.ok().merge({
+				snapshot1: {
+					id: snap1Row["id"],
+					timestamp: snap1Row["timestamp"],
+					totalSize: totalSize1,
+					nodeCount: summary1["nodeCount"] ?? 0
+				},
+				snapshot2: {
+					id: snap2Row["id"],
+					timestamp: snap2Row["timestamp"],
+					totalSize: totalSize2,
+					nodeCount: summary2["nodeCount"] ?? 0
+				},
+				diff: {
+					added: added.slice(0, 50),
+					removed: removed.slice(0, 50),
+					changed: changed.slice(0, 100),
+					totalSizeDelta: totalSize2 - totalSize1,
+					addedCount: added.length,
+					removedCount: removed.length,
+					changedCount: changed.length
+				}
+			}).json();
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleExportTrace(args) {
+		const dbPath = args["dbPath"];
+		const outputPath = args["outputPath"];
+		let tempDb = null;
+		try {
+			const db = getDbForReading(this.recorder, dbPath);
+			if (dbPath) tempDb = db;
+			const allEvents = db.query("SELECT timestamp, category, event_type, data, script_id, line_number FROM events ORDER BY timestamp ASC, sequence ASC");
+			const pairedBegin = new Set(["Debugger.paused"]);
+			const pairedEnd = new Set(["Debugger.resumed"]);
+			const traceEvents = allEvents.rows.map((row) => {
+				const ts = row[0] * 1e3;
+				const cat = row[1];
+				const name = row[2];
+				const dataStr = row[3];
+				let ph = "i";
+				if (pairedBegin.has(name)) ph = "B";
+				else if (pairedEnd.has(name)) ph = "E";
+				return {
+					name,
+					cat,
+					ph,
+					ts,
+					pid: 1,
+					tid: 1,
+					args: safeParseJSON(dataStr),
+					...ph === "i" ? { s: "g" } : {}
+				};
+			});
+			const finalOutputPath = outputPath ? outputPath : (await resolveArtifactPath({
+				category: "traces",
+				toolName: "trace_export",
+				ext: "json"
+			})).absolutePath;
+			await writeFile(finalOutputPath, JSON.stringify(traceEvents, null, 2), "utf-8");
+			return R.ok().merge({
+				exportedPath: finalOutputPath,
+				eventCount: traceEvents.length,
+				format: "Chrome Trace Event JSON",
+				message: `Exported ${traceEvents.length} events to ${finalOutputPath}. Open in chrome://tracing or ui.perfetto.dev`
+			}).json();
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleSummarizeTrace(args) {
+		const detail = args["detail"] ?? "balanced";
+		const dbPath = args["dbPath"];
+		let db;
+		let shouldClose = false;
+		if (dbPath) {
+			db = new TraceDB({ dbPath });
+			shouldClose = true;
+		} else if (this.recorder.getState() === "recording") {
+			const activeDb = this.recorder.getDB();
+			if (!activeDb) throw new Error("Active recording has no database");
+			db = activeDb;
+		} else throw new Error("GRACEFUL: No trace database specified and no active recording");
+		try {
+			const events = db.query("SELECT timestamp, category, event_type, data, script_id, line_number, wall_time, monotonic_time, request_id, sequence FROM events ORDER BY timestamp, sequence").rows.map((row) => ({
+				timestamp: row[0],
+				category: row[1],
+				eventType: row[2],
+				data: typeof row[3] === "string" ? safeParseJSON(row[3]) : row[3],
+				scriptId: row[4] ?? void 0,
+				lineNumber: row[5] ?? void 0
+			}));
+			const deltas = db.query("SELECT timestamp, address, old_value, new_value, size, value_type FROM memory_deltas ORDER BY timestamp").rows.map((row) => ({
+				timestamp: row[0],
+				address: row[1],
+				oldValue: row[2],
+				newValue: row[3],
+				size: row[4],
+				valueType: row[5]
+			}));
+			const networkSummary = db.query(`SELECT
+            COUNT(*) as requestCount,
+            COALESCE(SUM(chunk_count), 0) as chunkCount,
+            SUM(CASE WHEN body_capture_state IN ('inline', 'artifact', 'truncated') THEN 1 ELSE 0 END) as bodyCount
+         FROM network_resources`);
+			return R.ok().merge({
+				events: summarizeEvents(events, detail),
+				memory: summarizeMemoryDeltas(deltas),
+				network: networkSummary.rows.length > 0 ? rowToObject(networkSummary.columns, networkSummary.rows[0]) : {
+					requestCount: 0,
+					chunkCount: 0,
+					bodyCount: 0
+				},
+				metadata: {
+					dbPath: dbPath ?? "active recording",
+					generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			}).json();
+		} finally {
+			if (shouldClose) db.close();
+		}
+	}
+};
+//#endregion
+export { TraceToolHandlers };