@jshookmcp/jshook 0.3.0 → 0.3.2

package/dist/handlers-4jmR0nMs.mjs

@@ -1,898 +0,0 @@
-import { fr as SYSCALL_TRACE_DURATION_DEFAULT_SEC, mr as SYSCALL_TRACE_DURATION_MIN_SEC, pr as SYSCALL_TRACE_DURATION_MAX_SEC } from "./constants-CDZLOoVv.mjs";
-//#region src/modules/syscall-hook/SyscallMonitor.ts
-const SUPPORTED_BACKENDS = [
-	"etw",
-	"strace",
-	"dtrace"
-];
-const TRACE_SPAWN_TIMEOUT_MS = 3e3;
-const SYNTHETIC_EVENT_SEEDS = {
-	etw: [
-		{
-			syscall: "NtCreateFile",
-			args: ["C:\\Windows\\Temp\\jshookmcp.log", "GENERIC_READ"],
-			returnValue: 0,
-			duration: .7
-		},
-		{
-			syscall: "NtReadFile",
-			args: ["handle=0x90", "buffer=4096"],
-			returnValue: 512,
-			duration: .2
-		},
-		{
-			syscall: "NtWriteFile",
-			args: ["handle=0x90", "buffer=128"],
-			returnValue: 128,
-			duration: .3
-		},
-		{
-			syscall: "NtDeviceIoControlFile",
-			args: ["handle=0x44", "code=0x222004"],
-			returnValue: 0,
-			duration: 1.1
-		}
-	],
-	strace: [
-		{
-			syscall: "openat",
-			args: ["/tmp/jshookmcp.log", "O_RDONLY"],
-			returnValue: 3,
-			duration: .4
-		},
-		{
-			syscall: "read",
-			args: ["fd=3", "count=4096"],
-			returnValue: 256,
-			duration: .1
-		},
-		{
-			syscall: "write",
-			args: ["fd=3", "count=128"],
-			returnValue: 128,
-			duration: .2
-		},
-		{
-			syscall: "connect",
-			args: ["fd=18", "127.0.0.1:9222"],
-			returnValue: 0,
-			duration: 1.4
-		}
-	],
-	dtrace: [
-		{
-			syscall: "open_nocancel",
-			args: ["/private/tmp/jshookmcp.log", "O_RDONLY"],
-			returnValue: 3,
-			duration: .5
-		},
-		{
-			syscall: "read_nocancel",
-			args: ["fd=3", "count=4096"],
-			returnValue: 320,
-			duration: .1
-		},
-		{
-			syscall: "write_nocancel",
-			args: ["fd=3", "count=128"],
-			returnValue: 128,
-			duration: .2
-		},
-		{
-			syscall: "connect",
-			args: ["fd=21", "127.0.0.1:9222"],
-			returnValue: 0,
-			duration: 1.3
-		}
-	]
-};
-function isBackendSupportedOnCurrentPlatform(backend) {
-	if (backend === "etw") return process.platform === "win32";
-	if (backend === "strace") return process.platform === "linux";
-	if (backend === "dtrace") return process.platform === "darwin";
-	return false;
-}
-function chooseDefaultBackend() {
-	if (process.platform === "win32") return "etw";
-	if (process.platform === "linux") return "strace";
-	if (process.platform === "darwin") return "dtrace";
-	return "etw";
-}
-function cloneEvent(event) {
-	return {
-		timestamp: event.timestamp,
-		pid: event.pid,
-		syscall: event.syscall,
-		args: [...event.args],
-		returnValue: event.returnValue,
-		duration: event.duration
-	};
-}
-function createSpawnReadyGuard(label, resolve, reject, terminate) {
-	let settled = false;
-	const timer = setTimeout(() => {
-		if (settled) return;
-		settled = true;
-		try {
-			terminate?.();
-		} catch {}
-		reject(/* @__PURE__ */ new Error(`${label} did not signal readiness within ${TRACE_SPAWN_TIMEOUT_MS}ms`));
-	}, TRACE_SPAWN_TIMEOUT_MS);
-	return {
-		resolveReady(process) {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			resolve(process);
-		},
-		rejectReady(error) {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			reject(error);
-		}
-	};
-}
-function matchesFilter(event, filter) {
-	if (!filter) return true;
-	if (filter.pid !== void 0 && event.pid !== filter.pid) return false;
-	if (filter.name && filter.name.length > 0 && !filter.name.includes(event.syscall)) return false;
-	return true;
-}
-/**
-* Parse a strace output line into a SyscallEvent.
-*
-* Example strace line:
-*   12345 14:30:00.123456 openat(AT_FDCWD, "/tmp/foo", O_RDONLY) = 3 <0.000123>
-*/
-function parseStraceLine(line, targetPid, startedAt) {
-	const match = /^(\d+)\s+([\d:.]+)\s+(\w+)\(([^)]*)\)\s*=\s*(-?\d+)(?:\s+<([\d.]+)>)?$/u.exec(line.trim());
-	if (!match) return null;
-	const syscall = match[3] ?? "unknown";
-	const rawArgs = match[4] ?? "";
-	const returnValue = Number(match[5]);
-	const duration = match[6] ? Number(match[6]) : void 0;
-	const args = rawArgs.split(",").map((a) => a.trim()).filter((a) => a.length > 0);
-	return {
-		timestamp: Date.now() - startedAt,
-		pid: targetPid,
-		syscall,
-		args,
-		returnValue: Number.isFinite(returnValue) ? returnValue : void 0,
-		duration: duration !== void 0 && Number.isFinite(duration) ? duration * 1e3 : void 0
-	};
-}
-/**
-* Parse an ETW trace line (simplified from logman/wpr output).
-*
-* Example ETW line:
-*   [2024-01-15 14:30:00.123] PID=1234 NtCreateFile Handle=0x90 Status=0x00000000
-*/
-function parseETWLine(line, targetPid, startedAt) {
-	const match = /^\[([^\]]+)\]\s+PID=(\d+)\s+(\w+)\s+(.*)$/u.exec(line.trim());
-	if (!match) return null;
-	const syscall = match[3] ?? "unknown";
-	const rawArgs = match[4] ?? "";
-	const pid = Number(match[2]);
-	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
-	return {
-		timestamp: Date.now() - startedAt,
-		pid: Number.isFinite(pid) ? pid : targetPid,
-		syscall,
-		args
-	};
-}
-/**
-* Parse a dtrace output line.
-*
-* Example dtrace line:
-*   1234   0  12345  open_nocancel:entry  /private/tmp/foo O_RDONLY
-*/
-function parseDTraceLine(line, targetPid, startedAt) {
-	const match = /^\s*(\d+)\s+\d+\s+(\d+)\s+(\w+):\w+\s+(.*)$/u.exec(line.trim());
-	if (!match) return null;
-	const syscall = match[3] ?? "unknown";
-	const rawArgs = match[4] ?? "";
-	const pid = Number(match[2]);
-	const args = rawArgs.split(/\s+/u).filter((a) => a.length > 0);
-	return {
-		timestamp: Date.now() - startedAt,
-		pid: Number.isFinite(pid) ? pid : targetPid,
-		syscall,
-		args
-	};
-}
-var SyscallMonitor = class {
-	activeState;
-	capturedEvents = [];
-	lastBackend = chooseDefaultBackend();
-	subprocessError;
-	async start(options) {
-		const requestedBackend = options?.backend ?? chooseDefaultBackend();
-		const startedAt = Date.now();
-		if (!isBackendSupportedOnCurrentPlatform(requestedBackend)) throw new Error(`Backend "${requestedBackend}" is not available on platform "${process.platform}"`);
-		if (options?.simulate ?? process.env["JSHOOK_SIMULATE"] === "1") {
-			this.activeState = {
-				backend: requestedBackend,
-				pid: options?.pid,
-				startedAt,
-				generatedEvents: 0
-			};
-			this.lastBackend = requestedBackend;
-			this.capturedEvents.length = 0;
-			this.generateSyntheticEvents();
-			return;
-		}
-		const pid = options?.pid ?? process.pid;
-		let subprocess;
-		try {
-			if (requestedBackend === "strace") subprocess = await this.captureWithStrace(pid, startedAt);
-			else if (requestedBackend === "etw") subprocess = await this.captureWithETW(pid, startedAt);
-			else if (requestedBackend === "dtrace") subprocess = await this.captureWithDTrace(pid, startedAt);
-		} catch (error) {
-			this.subprocessError = error instanceof Error ? error.message : String(error);
-			this.activeState = {
-				backend: requestedBackend,
-				pid: options?.pid,
-				startedAt,
-				generatedEvents: 0
-			};
-			this.lastBackend = requestedBackend;
-			this.capturedEvents.length = 0;
-			this.generateSyntheticEvents();
-			return;
-		}
-		this.activeState = {
-			backend: requestedBackend,
-			pid: options?.pid,
-			startedAt,
-			generatedEvents: 0,
-			subprocess
-		};
-		this.lastBackend = requestedBackend;
-		this.capturedEvents.length = 0;
-		this.subprocessError = void 0;
-	}
-	async stop() {
-		if (this.activeState?.subprocess) {
-			this.activeState.subprocess.kill("SIGTERM");
-			this.activeState.subprocess = void 0;
-		}
-		this.activeState = void 0;
-	}
-	async captureEvents(filter) {
-		if (this.activeState && !this.activeState.subprocess) this.generateSyntheticEvents();
-		return this.capturedEvents.filter((event) => matchesFilter(event, filter)).map(cloneEvent);
-	}
-	getStats() {
-		const backend = this.activeState?.backend ?? this.lastBackend;
-		const uptime = this.activeState ? Date.now() - this.activeState.startedAt : 0;
-		return {
-			eventsCaptured: this.capturedEvents.length,
-			uptime,
-			backend,
-			subprocessActive: !!this.activeState?.subprocess,
-			subprocessError: this.subprocessError
-		};
-	}
-	getSupportedBackends() {
-		return SUPPORTED_BACKENDS.filter((backend) => isBackendSupportedOnCurrentPlatform(backend));
-	}
-	isRunning() {
-		return this.activeState !== void 0;
-	}
-	/**
-	* Spawn strace for syscall tracing on Linux.
-	* Parses stdout into SyscallEvent objects.
-	*/
-	async captureWithStrace(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
-		const { spawn } = await import("node:child_process");
-		return new Promise((resolve, reject) => {
-			const subprocess = spawn("strace", [
-				"-p",
-				String(pid),
-				"-f",
-				"-e",
-				"trace=all",
-				"-t"
-			], { stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			] });
-			const ready = createSpawnReadyGuard("strace process", resolve, reject, () => subprocess.kill("SIGTERM"));
-			let stderrBuffer = "";
-			let lineAccumulator = "";
-			subprocess.stdout?.on("data", (chunk) => {
-				lineAccumulator += chunk.toString();
-				this.processLineBuffer(lineAccumulator, pid, "strace");
-			});
-			subprocess.stderr?.on("data", (chunk) => {
-				stderrBuffer += chunk.toString();
-				const lines = stderrBuffer.split(/\r?\n/u);
-				stderrBuffer = lines.pop() ?? "";
-				for (const line of lines) if (line.length > 0) {
-					const event = parseStraceLine(line, pid, startedAt);
-					if (event) this.capturedEvents.push(event);
-				}
-			});
-			subprocess.on("error", (error) => {
-				ready.rejectReady(/* @__PURE__ */ new Error(`strace process error: ${error.message}. Is strace installed?`));
-			});
-			subprocess.on("spawn", () => {
-				ready.resolveReady(subprocess);
-			});
-		});
-	}
-	/**
-	* Spawn ETW tracing on Windows using logman.
-	* Parses ETW trace output into SyscallEvent objects.
-	*/
-	async captureWithETW(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
-		const { spawn } = await import("node:child_process");
-		return new Promise((resolve, reject) => {
-			const logman = spawn("logman", [
-				"create",
-				"trace",
-				`JSHookETW_${pid}`,
-				"-p",
-				"NT Kernel Logger",
-				"0x10000",
-				"-o",
-				`jshook_etw_${pid}.etl`,
-				"-ets"
-			], {
-				stdio: [
-					"ignore",
-					"pipe",
-					"pipe"
-				],
-				windowsHide: true
-			});
-			const ready = createSpawnReadyGuard("ETW trace session", resolve, reject, () => logman.kill("SIGTERM"));
-			let outputBuffer = "";
-			logman.stdout?.on("data", (chunk) => {
-				outputBuffer += chunk.toString();
-				const lines = outputBuffer.split(/\r?\n/u);
-				outputBuffer = lines.pop() ?? "";
-				for (const line of lines) {
-					const event = parseETWLine(line, pid, startedAt);
-					if (event) this.capturedEvents.push(event);
-				}
-			});
-			logman.stderr?.on("data", (chunk) => {
-				const msg = chunk.toString().trim();
-				if (msg.length > 0 && !msg.startsWith("The command completed successfully")) {}
-			});
-			logman.on("error", (error) => {
-				ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace error: ${error.message}. Run as Administrator.`));
-			});
-			logman.on("exit", (code) => {
-				if (code !== 0 && code !== void 0) ready.rejectReady(/* @__PURE__ */ new Error(`ETW trace session ended (code ${code}). Check permissions.`));
-			});
-			logman.on("spawn", () => {
-				ready.resolveReady(logman);
-			});
-		});
-	}
-	/**
-	* Spawn dtrace for syscall tracing on macOS.
-	* Parses dtrace output into SyscallEvent objects.
-	*/
-	async captureWithDTrace(pid, startedAt = this.activeState?.startedAt ?? Date.now()) {
-		const { spawn } = await import("node:child_process");
-		return new Promise((resolve, reject) => {
-			const dtrace = spawn("dtrace", ["-n", `
-        syscall:::entry
-        /pid == ${pid}/
-        {
-          printf("%d %d %s:entry %s", pid, probeproc, probefunc, copyinstr(arg0));
-        }
-      `], { stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			] });
-			const ready = createSpawnReadyGuard("dtrace process", resolve, reject, () => dtrace.kill("SIGTERM"));
-			let outputBuffer = "";
-			dtrace.stdout?.on("data", (chunk) => {
-				outputBuffer += chunk.toString();
-				const lines = outputBuffer.split(/\r?\n/u);
-				outputBuffer = lines.pop() ?? "";
-				for (const line of lines) {
-					const event = parseDTraceLine(line, pid, startedAt);
-					if (event) this.capturedEvents.push(event);
-				}
-			});
-			dtrace.stderr?.on("data", () => {});
-			dtrace.on("error", (error) => {
-				ready.rejectReady(/* @__PURE__ */ new Error(`dtrace error: ${error.message}. Run with sudo.`));
-			});
-			dtrace.on("spawn", () => {
-				ready.resolveReady(dtrace);
-			});
-		});
-	}
-	generateSyntheticEvents() {
-		if (!this.activeState) return;
-		const seeds = SYNTHETIC_EVENT_SEEDS[this.activeState.backend];
-		if (!seeds) return;
-		const elapsed = Date.now() - this.activeState.startedAt;
-		const targetEventCount = Math.max(1, Math.min(seeds.length * 3, Math.floor(elapsed / 150) + 1));
-		const pid = this.activeState.pid ?? process.pid;
-		while (this.activeState.generatedEvents < targetEventCount) {
-			const seed = seeds[this.activeState.generatedEvents % seeds.length];
-			if (!seed) break;
-			const timestamp = this.activeState.generatedEvents * 75;
-			this.capturedEvents.push({
-				timestamp,
-				pid,
-				syscall: seed.syscall,
-				args: [...seed.args],
-				returnValue: seed.returnValue,
-				duration: seed.duration
-			});
-			this.activeState.generatedEvents += 1;
-		}
-	}
-	processLineBuffer(_buffer, _pid, _parser) {}
-};
-//#endregion
-//#region src/modules/syscall-hook/SyscallToJSMapper.ts
-const CORRELATION_RULES = [
-	{
-		syscallNames: [
-			"NtCreateFile",
-			"openat",
-			"open_nocancel"
-		],
-		jsFunction: "fs.open",
-		baseConfidence: .8,
-		explanation: "File open syscalls commonly originate from Node.js file-system entry points."
-	},
-	{
-		syscallNames: [
-			"NtReadFile",
-			"read",
-			"read_nocancel"
-		],
-		jsFunction: "fs.readFile",
-		baseConfidence: .78,
-		explanation: "Read-oriented syscalls usually map back to file or stream reads in JavaScript."
-	},
-	{
-		syscallNames: [
-			"NtWriteFile",
-			"write",
-			"write_nocancel"
-		],
-		jsFunction: "fs.writeFile",
-		baseConfidence: .78,
-		explanation: "Write-oriented syscalls are strongly associated with Node.js file writes."
-	},
-	{
-		syscallNames: ["NtDeviceIoControlFile", "ioctl"],
-		jsFunction: "child_process.spawn",
-		baseConfidence: .55,
-		explanation: "Device and control syscalls are often triggered by child processes or native helpers."
-	},
-	{
-		syscallNames: [
-			"connect",
-			"sendto",
-			"recvfrom"
-		],
-		jsFunction: "fetch",
-		baseConfidence: .7,
-		explanation: "Socket syscalls generally indicate outbound network activity from fetch-like APIs."
-	}
-];
-function findRuleBySyscallName(syscallName) {
-	return CORRELATION_RULES.find((rule) => rule.syscallNames.includes(syscallName));
-}
-function clampConfidence(confidence) {
-	if (confidence < 0) return 0;
-	if (confidence > 1) return 1;
-	return confidence;
-}
-function hasArgContaining(args, fragments) {
-	return args.some((arg) => fragments.some((fragment) => arg.toLowerCase().includes(fragment)));
-}
-var SyscallToJSMapper = class {
-	map(syscall) {
-		const jsFunction = this.findJSFunction(syscall.syscall);
-		if (!jsFunction) return null;
-		const rule = findRuleBySyscallName(syscall.syscall);
-		if (!rule) return null;
-		let confidence = rule.baseConfidence;
-		if (jsFunction.startsWith("fs.") && hasArgContaining(syscall.args, [
-			".js",
-			".json",
-			".node"
-		])) confidence += .08;
-		if (jsFunction === "fetch" && hasArgContaining(syscall.args, [
-			"80",
-			"443",
-			"http",
-			"https"
-		])) confidence += .1;
-		return {
-			syscall: {
-				timestamp: syscall.timestamp,
-				pid: syscall.pid,
-				syscall: syscall.syscall,
-				args: [...syscall.args],
-				returnValue: syscall.returnValue,
-				duration: syscall.duration
-			},
-			jsFunction,
-			confidence: clampConfidence(confidence),
-			reasoning: this.getCorrelationReason(syscall, jsFunction)
-		};
-	}
-	findJSFunction(syscallName) {
-		const rule = findRuleBySyscallName(syscallName);
-		if (!rule) return null;
-		return rule.jsFunction;
-	}
-	getCorrelationReason(syscall, jsFunc) {
-		const rule = findRuleBySyscallName(syscall.syscall);
-		const detailParts = [];
-		if (rule) detailParts.push(rule.explanation);
-		if (jsFunc.startsWith("fs.") && hasArgContaining(syscall.args, [
-			".js",
-			".json",
-			".node"
-		])) detailParts.push("The syscall arguments reference module-like file extensions, which strengthens the fs correlation.");
-		if (jsFunc === "fetch" && hasArgContaining(syscall.args, [
-			"80",
-			"443",
-			"http",
-			"https"
-		])) detailParts.push("The syscall arguments look like network endpoints, which aligns with fetch or low-level HTTP clients.");
-		if (detailParts.length === 0) detailParts.push(`Mapped ${syscall.syscall} to ${jsFunc} using the default syscall-to-JS heuristic table.`);
-		return detailParts.join(" ");
-	}
-};
-//#endregion
-//#region src/server/domains/syscall-hook/handlers.impl.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function readNumber(value) {
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-}
-function readBoolean(value) {
-	if (typeof value === "boolean") return value;
-}
-function readString(value) {
-	if (typeof value === "string") return value;
-}
-function readStringArray(value) {
-	if (!Array.isArray(value)) return;
-	const strings = [];
-	for (const item of value) {
-		if (typeof item !== "string") return;
-		strings.push(item);
-	}
-	return strings;
-}
-const SYSCALL_NAME_RE = /^[a-z][a-z0-9_]*$/;
-function isValidSyscallName(name) {
-	return SYSCALL_NAME_RE.test(name) && name.length <= 64;
-}
-function readBackend(value) {
-	if (value === "etw" || value === "strace" || value === "dtrace") return value;
-}
-function readFilter(value) {
-	if (!isRecord(value)) return;
-	const filter = {};
-	const names = readStringArray(value["name"]);
-	const pid = readNumber(value["pid"]);
-	if (names) filter.name = names;
-	if (pid !== void 0) filter.pid = pid;
-	return filter;
-}
-function isSyscallEvent(value) {
-	if (!isRecord(value)) return false;
-	const timestamp = readNumber(value["timestamp"]);
-	const pid = readNumber(value["pid"]);
-	const syscall = readString(value["syscall"]);
-	const args = readStringArray(value["args"]);
-	const returnValue = value["returnValue"];
-	const duration = value["duration"];
-	const returnValueValid = returnValue === void 0 || readNumber(returnValue) !== void 0;
-	const durationValid = duration === void 0 || readNumber(duration) !== void 0;
-	return timestamp !== void 0 && pid !== void 0 && syscall !== void 0 && args !== void 0 && returnValueValid && durationValid;
-}
-function cloneSyscallEvent(event) {
-	return {
-		timestamp: event.timestamp,
-		pid: event.pid,
-		syscall: event.syscall,
-		args: [...event.args],
-		returnValue: event.returnValue,
-		duration: event.duration
-	};
-}
-function toErrorMessage(error) {
-	if (error instanceof Error) return error.message;
-	return "Unknown syscall-hook error";
-}
-var SyscallHookHandlers = class {
-	constructor(monitor, mapper, eventBus) {
-		this.monitor = monitor;
-		this.mapper = mapper;
-		this.eventBus = eventBus;
-	}
-	async handleSyscallStartMonitor(args) {
-		const backend = readBackend(args["backend"]);
-		if (!backend) return {
-			ok: false,
-			error: "backend must be one of: etw, strace, dtrace"
-		};
-		const rawMonitorPid = readNumber(args["pid"]);
-		const simulate = readBoolean(args["simulate"]) ?? false;
-		if (args["pid"] !== void 0 && args["pid"] !== null) {
-			if (rawMonitorPid === void 0 || !Number.isInteger(rawMonitorPid) || rawMonitorPid < 0) return {
-				ok: false,
-				error: "pid must be a non-negative integer when provided"
-			};
-		}
-		const pid = rawMonitorPid;
-		const monitor = this.ensureMonitor();
-		try {
-			await monitor.start({
-				backend,
-				pid,
-				simulate
-			});
-			this.eventBus?.emit("syscall:trace_started", {
-				backend,
-				pid,
-				simulate,
-				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			});
-			return {
-				ok: true,
-				started: true,
-				backend,
-				pid,
-				simulate,
-				stats: monitor.getStats()
-			};
-		} catch (error) {
-			return {
-				ok: false,
-				error: toErrorMessage(error),
-				requestedBackend: backend,
-				supportedBackends: monitor.getSupportedBackends()
-			};
-		}
-	}
-	async handleSyscallStopMonitor() {
-		const monitor = this.ensureMonitor();
-		try {
-			await monitor.stop();
-			return {
-				ok: true,
-				stopped: true,
-				stats: monitor.getStats()
-			};
-		} catch (error) {
-			return {
-				ok: false,
-				error: toErrorMessage(error)
-			};
-		}
-	}
-	async handleSyscallCaptureEvents(args) {
-		const monitor = this.ensureMonitor();
-		const filter = readFilter(args["filter"]);
-		const events = await monitor.captureEvents(filter);
-		return {
-			ok: true,
-			events,
-			count: events.length,
-			stats: monitor.getStats()
-		};
-	}
-	async handleSyscallCorrelateJs(args) {
-		const rawEvents = args["syscallEvents"];
-		if (!Array.isArray(rawEvents) || !rawEvents.every((item) => isSyscallEvent(item))) return {
-			ok: false,
-			error: "syscallEvents must be an array of valid SyscallEvent objects"
-		};
-		const mapper = this.ensureMapper();
-		const correlations = [];
-		const unmatched = [];
-		for (const event of rawEvents) {
-			const clonedEvent = cloneSyscallEvent(event);
-			const correlated = mapper.map(clonedEvent);
-			if (correlated) correlations.push(correlated);
-			else unmatched.push(clonedEvent);
-		}
-		return {
-			ok: true,
-			correlations,
-			matched: correlations.length,
-			unmatched
-		};
-	}
-	async handleSyscallFilter(args) {
-		const names = readStringArray(args["names"]);
-		if (args["names"] !== void 0 && names === void 0) return {
-			ok: false,
-			error: "names must be an array of strings when provided"
-		};
-		const events = await this.ensureMonitor().captureEvents(names && names.length > 0 ? { name: names } : void 0);
-		return {
-			ok: true,
-			names,
-			events,
-			count: events.length
-		};
-	}
-	async handleSyscallGetStats() {
-		const monitor = this.ensureMonitor();
-		return {
-			ok: true,
-			...monitor.getStats(),
-			running: monitor.isRunning(),
-			supportedBackends: monitor.getSupportedBackends()
-		};
-	}
-	async handleSyscallEbpfTrace(args) {
-		const rawPid = readNumber(args["pid"]);
-		const syscalls = readStringArray(args["syscalls"]);
-		const durationSec = readNumber(args["durationSec"]) ?? SYSCALL_TRACE_DURATION_DEFAULT_SEC;
-		const simulate = readBoolean(args["simulate"]) ?? false;
-		if (args["pid"] !== void 0 && args["pid"] !== null) {
-			if (rawPid === void 0 || !Number.isInteger(rawPid) || rawPid < 0) return {
-				ok: false,
-				error: "pid must be a non-negative integer (0 for all processes)"
-			};
-		}
-		const pid = rawPid ?? 0;
-		if (durationSec < SYSCALL_TRACE_DURATION_MIN_SEC || durationSec > SYSCALL_TRACE_DURATION_MAX_SEC) return {
-			ok: false,
-			error: `durationSec must be between ${SYSCALL_TRACE_DURATION_MIN_SEC} and ${SYSCALL_TRACE_DURATION_MAX_SEC}`
-		};
-		if (syscalls?.length) {
-			const invalid = syscalls.filter((s) => !isValidSyscallName(s));
-			if (invalid.length > 0) return {
-				ok: false,
-				error: `Invalid syscall names (must be lowercase alphanumeric with underscores): ${invalid.join(", ")}`
-			};
-		}
-		if (simulate) {
-			const simulatedEvents = [];
-			const syscallPool = syscalls?.length ? syscalls : [
-				"read",
-				"write",
-				"openat",
-				"close",
-				"fstat",
-				"mmap",
-				"mprotect",
-				"munmap",
-				"brk",
-				"ioctl"
-			];
-			const simulatedTimestampStepMs = durationSec * 50;
-			for (let i = 0; i < 20; i++) simulatedEvents.push({
-				timestamp: i * simulatedTimestampStepMs,
-				pid: pid || 1234,
-				syscall: syscallPool[i % syscallPool.length] ?? "read",
-				args: [`fd=${i % 5 + 3}`, `count=${(i + 1) * 64}`],
-				returnValue: i % 3 === 0 ? -1 : (i + 1) * 64,
-				duration: Math.random() * 2
-			});
-			return {
-				ok: true,
-				backend: "ebpf",
-				simulated: true,
-				pid,
-				durationSec,
-				events: simulatedEvents,
-				count: simulatedEvents.length,
-				syscallsTraced: syscallPool
-			};
-		}
-		const targetSyscalls = syscalls?.length ? syscalls : [
-			"read",
-			"write",
-			"openat",
-			"close",
-			"fstat",
-			"mmap",
-			"mprotect",
-			"munmap",
-			"brk",
-			"ioctl",
-			"connect",
-			"sendto",
-			"recvfrom",
-			"clone",
-			"execve"
-		];
-		const pidFilter = pid > 0 ? `/pid == ${pid}/` : "";
-		const tracepoints = targetSyscalls.map((sc) => `tracepoint:syscalls:sys_enter_${sc}`).join(", ");
-		const exitTracepoints = targetSyscalls.map((sc) => `tracepoint:syscalls:sys_exit_${sc}`).join(", ");
-		const script = `#!/usr/bin/env bpftrace
-// Generated by jshookmcp syscall_ebpf_trace
-// Target PID: ${pid || "all"} | Duration: ${durationSec}s | Syscalls: ${targetSyscalls.join(", ")}
-
-BEGIN {
-  printf("=== eBPF syscall trace started (pid=${pid || "all"}, duration=${durationSec}s) ===\\n");
-}
-
-${tracepoints} ${pidFilter}
-{
-  @enter_ts[tid] = nsecs;
-  printf("{\\"timestamp\\": %llu, \\"pid\\": %d, \\"tid\\": %d, \\"syscall\\": \\"%s\\", \\"phase\\": \\"enter\\", \\"args\\": {",
-    elapsed / 1000000, pid, tid, probe);
-  // Log key arguments based on syscall
-  if (probe == "tracepoint:syscalls:sys_enter_openat" || probe == "tracepoint:syscalls:sys_enter_open") {
-    printf("\\"pathname\\": \\"%s\\", \\"flags\\": %d, \\"mode\\": %d", args->pathname, args->flags, args->mode);
-  } else if (probe == "tracepoint:syscalls:sys_enter_read" || probe == "tracepoint:syscalls:sys_enter_write") {
-    printf("\\"fd\\": %d, \\"count\\": %d", args->fd, args->count);
-  } else if (probe == "tracepoint:syscalls:sys_enter_connect") {
-    printf("\\"fd\\": %d", args->fd);
-  } else if (probe == "tracepoint:syscalls:sys_enter_mmap") {
-    printf("\\"addr\\": %llu, \\"length\\": %llu, \\"prot\\": %d, \\"flags\\": %d, \\"fd\\": %d", args->addr, args->length, args->prot, args->flags, args->fd);
-  } else if (probe == "tracepoint:syscalls:sys_enter_execve") {
-    printf("\\"filename\\": \\"%s\\"", args->filename);
-  } else {
-    printf("\\"raw_args\\": \\"(see bpftrace -v output)\\"");
-  }
-  printf("}}\\n");
-}
-
-${exitTracepoints} ${pidFilter}
-{
-  $elapsed_ns = nsecs - @enter_ts[tid];
-  printf("{\\"timestamp\\": %llu, \\"pid\\": %d, \\"tid\\": %d, \\"syscall\\": \\"%s\\", \\"phase\\": \\"exit\\", \\"ret\\": %d, \\"duration_us\\": %llu}\\n",
-    elapsed / 1000000, pid, tid, probe, args->ret, $elapsed_ns / 1000);
-  delete(@enter_ts[tid]);
-}
-
-interval:s:${durationSec} {
-  printf("=== Trace duration (${durationSec}s) elapsed, exiting ===\\n");
-  exit();
-}
-
-END {
-  printf("=== eBPF syscall trace complete ===\\n");
-  clear(@enter_ts);
-}
-`;
-		return {
-			ok: true,
-			backend: "ebpf",
-			mode: "script",
-			pid,
-			durationSec,
-			syscallCount: targetSyscalls.length,
-			syscallsTraced: targetSyscalls,
-			script,
-			usage: `bpftrace -e '${script.replace(/'/g, "'\\''")}'`,
-			note: "Run the generated bpftrace script on a Linux system with bpftrace installed and CAP_BPF/root privileges.",
-			requiredCapabilities: [
-				"CAP_BPF",
-				"root",
-				"bpftrace"
-			]
-		};
-	}
-	ensureMonitor() {
-		if (!this.monitor) this.monitor = new SyscallMonitor();
-		return this.monitor;
-	}
-	ensureMapper() {
-		if (!this.mapper) this.mapper = new SyscallToJSMapper();
-		return this.mapper;
-	}
-};
-//#endregion
-export { SyscallHookHandlers };