@openclaw/plugin-inspector 0.3.24 → 0.3.25

package/src/process-profile.js

@@ -1,6 +1,147 @@
 import { spawn } from "node:child_process";
 import { performance } from "node:perf_hooks";
 
+const defaultTimeoutMs = 30_000;
+const defaultKillGraceMs = 1_000;
+const maxTimerMs = 2 ** 31 - 1;
+const killWaitMs = 1_000;
+
+// Shared by capture and profiling, not a package entrypoint. Each spawn owns
+// its POSIX process group; never signal the inspector's inherited group.
+export function startOwnedProcess(options, kind = "PROFILE") {
+  const env = options.env ?? process.env;
+  const { timeoutMs, killGraceMs, maxOutputBytes } = resolveProcessLimits(options, kind);
+  const stdout = createCappedCollector(maxOutputBytes);
+  const stderr = createCappedCollector(maxOutputBytes);
+  let timedOut = false;
+  let cancelled = options.signal?.aborted === true;
+  let error;
+  let closed = false;
+  let stopping = false;
+  let escalated = false;
+  let settled = false;
+  let code;
+  let exitSignal;
+  let timeoutId;
+  let forceKillId;
+  let closeDeadlineId;
+  let child;
+  let resolveResult;
+  const result = new Promise((resolve) => { resolveResult = resolve; });
+
+  const finish = () => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timeoutId);
+    clearTimeout(forceKillId);
+    clearTimeout(closeDeadlineId);
+    options.signal?.removeEventListener("abort", cancel);
+    resolveResult({
+      exitCode: timedOut || cancelled || error ? 1 : (code ?? 1),
+      timedOut,
+      cancelled,
+      timeoutMs,
+      signal: exitSignal,
+      pid: child?.pid,
+      error,
+      stdout: stdout.text(),
+      stderr: stderr.text(),
+      outputTruncated: stdout.truncated || stderr.truncated,
+    });
+  };
+  const groupExists = () => {
+    if (!child?.pid) return false;
+    if (process.platform === "win32") return child.exitCode === null && child.signalCode === null;
+    try {
+      process.kill(-child.pid, 0);
+      return true;
+    } catch (cause) {
+      if (cause.code === "ESRCH") return false;
+      error ??= cause;
+      return true;
+    }
+  };
+  const signalGroup = (signal) => {
+    if (!child?.pid) return;
+    try {
+      if (process.platform === "win32") child.kill(signal);
+      else process.kill(-child.pid, signal);
+    } catch (cause) {
+      if (cause.code !== "ESRCH") error ??= cause;
+    }
+  };
+  const stop = () => {
+    if (stopping || settled) return;
+    stopping = true;
+    signalGroup("SIGTERM");
+    forceKillId = setTimeout(() => {
+      // The leader may already be reaped while its descendants hold the pipes.
+      signalGroup("SIGKILL");
+      escalated = true;
+      if (closed) {
+        finish();
+        return;
+      }
+      closeDeadlineId = setTimeout(() => {
+        error ??= new Error("Owned child stdio did not close after SIGKILL");
+        child?.stdout?.destroy();
+        child?.stderr?.destroy();
+        child?.stdin?.destroy();
+        child?.unref();
+        finish();
+      }, killWaitMs);
+    }, killGraceMs);
+  };
+  const cancel = () => {
+    cancelled = true;
+    stop();
+  };
+
+  if (cancelled) {
+    finish();
+    return { child, result };
+  }
+  try {
+    child = spawn(options.command, options.args ?? [], {
+      cwd: options.cwd,
+      env,
+      detached: process.platform !== "win32",
+      stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+    });
+  } catch (cause) {
+    error = cause;
+    finish();
+    return { child, result };
+  }
+  child.stdout?.on("data", (chunk) => stdout.push(chunk));
+  child.stderr?.on("data", (chunk) => stderr.push(chunk));
+  const fail = (cause) => {
+    error ??= cause;
+    stop();
+  };
+  child.stdout?.on("error", fail);
+  child.stderr?.on("error", fail);
+  child.once("error", fail);
+  child.once("exit", () => {
+    // Clean descendants even after a successful leader exit or closed pipes.
+    if (groupExists()) stop();
+  });
+  child.once("close", (exitCode, signal) => {
+    closed = true;
+    code = exitCode;
+    exitSignal = signal;
+    if (!escalated && groupExists()) stop();
+    else finish();
+  });
+  timeoutId = setTimeout(() => {
+    timedOut = true;
+    stop();
+  }, timeoutMs);
+  options.signal?.addEventListener("abort", cancel, { once: true });
+  if (options.signal?.aborted) cancel();
+  return { child, result };
+}
+
 export async function runProfiledProcess(options) {
   const start = performance.now();
   const heapStartMb = heapUsedMb();
@@ -10,129 +151,136 @@ export async function runProfiledProcess(options) {
   let statSampleCount = 0;
   let rssSampleCount = 0;
   let cpuSampleCount = 0;
-  const cpuSamples = [];
-  let pollInFlight = false;
-  const pendingStats = new Set();
-
-  const child = spawn(options.command, options.args ?? [], {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
-  });
-  const stdout = [];
-  const stderr = [];
-  child.stdout?.on("data", (chunk) => stdout.push(chunk));
-  child.stderr?.on("data", (chunk) => stderr.push(chunk));
-
-  const recordStats = (stats) => {
-    if (stats.rssAvailable || stats.cpuAvailable) {
-      statSampleCount += 1;
-    }
-    if (stats.rssAvailable) {
-      rssSampleCount += 1;
-    }
-    if (stats.cpuAvailable) {
-      cpuSampleCount += 1;
-    }
-    if (stats.rssAvailable && stats.rssKb > 0 && firstRssKb === 0) {
-      firstRssKb = stats.rssKb;
-    }
-    if (stats.rssAvailable) {
-      peakRssKb = Math.max(peakRssKb, stats.rssKb);
-    }
-    if (stats.cpuAvailable) {
-      peakCpuPercent = Math.max(peakCpuPercent, stats.cpuPercent);
-      cpuSamples.push(stats.cpuPercent);
-    }
-  };
-
+  let cpuTotal = 0;
+  let pendingStats;
+  let stopped = false;
+  const statsController = new AbortController();
+  const running = startOwnedProcess(options);
   const sampleStats = () => {
-    if (pollInFlight) {
-      return;
-    }
-    pollInFlight = true;
-    const pending = readProcessStats(child.pid)
-      .then(recordStats)
-      .finally(() => {
-        pollInFlight = false;
-        pendingStats.delete(pending);
-      });
-    pendingStats.add(pending);
+    if (pendingStats || stopped || !running.child?.pid) return;
+    pendingStats = readProcessStats(running.child.pid, options.env, statsController.signal)
+      .then((stats) => {
+        if (stopped) return;
+        if (stats.rssAvailable || stats.cpuAvailable) statSampleCount += 1;
+        if (stats.rssAvailable) {
+          rssSampleCount += 1;
+          if (stats.rssKb > 0 && firstRssKb === 0) firstRssKb = stats.rssKb;
+          peakRssKb = Math.max(peakRssKb, stats.rssKb);
+        }
+        if (stats.cpuAvailable) {
+          cpuSampleCount += 1;
+          peakCpuPercent = Math.max(peakCpuPercent, stats.cpuPercent);
+          cpuTotal += stats.cpuPercent;
+        }
+      })
+      .finally(() => { pendingStats = undefined; });
   };
-
+  const poll = setInterval(sampleStats, positiveLimit(options.pollMs, undefined, 25));
+  const stopSampling = () => {
+    stopped = true;
+    clearInterval(poll);
+    statsController.abort();
+  };
+  running.child?.once("exit", stopSampling);
+  running.child?.once("error", stopSampling);
   sampleStats();
-  const poll = setInterval(sampleStats, options.pollMs ?? 25);
-
-  const exitCode = await new Promise((resolve, reject) => {
-    child.on("error", (error) => {
-      clearInterval(poll);
-      reject(error);
-    });
-    child.on("exit", (code) => resolve(code ?? 1));
-  });
-  clearInterval(poll);
-  await Promise.allSettled([...pendingStats]);
-
-  const finalStats = await readProcessStats(child.pid);
-  recordStats(finalStats);
 
-  const wallMs = Math.round(performance.now() - start);
-  const averageCpuPercent =
-    cpuSamples.length > 0
-      ? cpuSamples.reduce((sum, value) => sum + value, 0) / cpuSamples.length
-      : 0;
-  const cpuPercentForEstimate =
-    options.roundAverageCpuPercent === true
+  try {
+    const outcome = await running.result;
+    stopSampling();
+    await pendingStats;
+    if (outcome.error) throw outcome.error;
+    const wallMs = Math.round(performance.now() - start);
+    const averageCpuPercent = cpuSampleCount > 0 ? cpuTotal / cpuSampleCount : 0;
+    const cpuPercentForEstimate = options.roundAverageCpuPercent === true
       ? Math.round(averageCpuPercent * 10) / 10
       : averageCpuPercent;
+    return {
+      wallMs,
+      peakRssMb: Math.round((peakRssKb / 1024) * 10) / 10,
+      rssDeltaMb: Math.round(((peakRssKb - firstRssKb) / 1024) * 10) / 10,
+      peakCpuPercent: Math.round(peakCpuPercent * 10) / 10,
+      cpuMsEstimate: Math.round((wallMs * cpuPercentForEstimate) / 100),
+      harnessHeapDeltaMb: Math.round((heapUsedMb() - heapStartMb) * 10) / 10,
+      statSampleCount,
+      rssSampleCount,
+      cpuSampleCount,
+      exitCode: outcome.exitCode,
+      timedOut: outcome.timedOut,
+      cancelled: outcome.cancelled,
+      pid: outcome.pid,
+      stdoutPreview: previewLines(outcome.stdout),
+      stderrPreview: previewLines(outcome.stderr),
+    };
+  } finally {
+    stopSampling();
+  }
+}
 
+export function resolveProcessLimits(options, kind = "PROFILE") {
+  const env = options.env ?? process.env;
+  const setting = (name) => env[`PLUGIN_INSPECTOR_${kind}_${name}`] ?? process.env[`PLUGIN_INSPECTOR_${kind}_${name}`];
   return {
-    wallMs,
-    peakRssMb: Math.round((peakRssKb / 1024) * 10) / 10,
-    rssDeltaMb: Math.round(((peakRssKb - firstRssKb) / 1024) * 10) / 10,
-    peakCpuPercent: Math.round(peakCpuPercent * 10) / 10,
-    cpuMsEstimate: Math.round((wallMs * cpuPercentForEstimate) / 100),
-    harnessHeapDeltaMb: Math.round((heapUsedMb() - heapStartMb) * 10) / 10,
-    statSampleCount,
-    rssSampleCount,
-    cpuSampleCount,
-    exitCode,
-    stdoutPreview: previewLines(stdout),
-    stderrPreview: previewLines(stderr),
+    timeoutMs: positiveLimit(options.timeoutMs, setting("TIMEOUT_MS"), defaultTimeoutMs),
+    killGraceMs: positiveLimit(options.killGraceMs, setting("KILL_GRACE_MS"), defaultKillGraceMs, 30_000),
+    maxOutputBytes: positiveLimit(options.maxOutputBytes, setting("MAX_OUTPUT_BYTES"), (kind === "CAPTURE" || kind === "PROBE" ? 10 : 1) * 1024 * 1024),
   };
 }
 
-async function readProcessStats(pid) {
-  if (!pid || process.platform === "win32") {
-    return { rssAvailable: false, rssKb: 0, cpuAvailable: false, cpuPercent: 0 };
-  }
-  return new Promise((resolve) => {
-    const ps = spawn("ps", ["-o", "rss=", "-o", "%cpu=", "-p", String(pid)], {
-      stdio: ["ignore", "pipe", "ignore"],
-    });
-    const chunks = [];
-    ps.stdout.on("data", (chunk) => chunks.push(chunk));
-    ps.on("error", () => resolve({ rssAvailable: false, rssKb: 0, cpuAvailable: false, cpuPercent: 0 }));
-    ps.on("exit", () => {
-      const [rssRaw, cpuRaw] = Buffer.concat(chunks).toString("utf8").trim().split(/\s+/);
-      const rssKb = Number.parseInt(rssRaw, 10);
-      const cpuPercent = Number.parseFloat(cpuRaw);
-      const rssAvailable = Number.isFinite(rssKb);
-      const cpuAvailable = Number.isFinite(cpuPercent);
-      resolve({
-        rssAvailable,
-        rssKb: rssAvailable ? rssKb : 0,
-        cpuAvailable,
-        cpuPercent: cpuAvailable ? cpuPercent : 0,
-      });
-    });
+function positiveLimit(option, env, fallback, max = maxTimerMs) {
+  const valid = (value) => Number.isFinite(value) && value > 0 && value <= max;
+  if (valid(option)) return Math.ceil(option);
+  const fromEnv = typeof env === "string" ? Number(env) : NaN;
+  return valid(fromEnv) ? Math.ceil(fromEnv) : fallback;
+}
+
+export function createCappedCollector(maxBytes) {
+  const chunks = [];
+  let size = 0;
+  let truncated = false;
+  return {
+    get truncated() { return truncated; },
+    push(chunk) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const length = Math.min(buffer.length, maxBytes - size);
+      if (length < buffer.length) truncated = true;
+      if (length === 0) return;
+      chunks.push(Buffer.from(buffer.subarray(0, length)));
+      size += length;
+    },
+    text: () => Buffer.concat(chunks, size).toString("utf8"),
+  };
+}
+
+async function readProcessStats(pid, env, signal) {
+  const unavailable = { rssAvailable: false, rssKb: 0, cpuAvailable: false, cpuPercent: 0 };
+  if (!pid || process.platform === "win32") return unavailable;
+  const { result } = startOwnedProcess({
+    command: "ps",
+    args: ["-o", "rss=", "-o", "%cpu=", "-p", String(pid)],
+    env,
+    signal,
+    timeoutMs: 250,
+    killGraceMs: 50,
+    maxOutputBytes: 4096,
   });
+  const outcome = await result;
+  if (outcome.exitCode !== 0 || outcome.outputTruncated) return unavailable;
+  const [rssRaw, cpuRaw] = outcome.stdout.trim().split(/\s+/);
+  const rssKb = Number.parseInt(rssRaw, 10);
+  const cpuPercent = Number.parseFloat(cpuRaw);
+  return {
+    rssAvailable: Number.isFinite(rssKb),
+    rssKb: Number.isFinite(rssKb) ? rssKb : 0,
+    cpuAvailable: Number.isFinite(cpuPercent),
+    cpuPercent: Number.isFinite(cpuPercent) ? cpuPercent : 0,
+  };
 }
 
 function heapUsedMb() {
   return Math.round((process.memoryUsage().heapUsed / 1024 / 1024) * 10) / 10;
 }
 
-function previewLines(chunks) {
-  return Buffer.concat(chunks).toString("utf8").trim().split("\n").slice(-2).join("\n");
+function previewLines(text) {
+  return text.trim().split("\n").slice(-2).join("\n");
 }

package/src/runtime-capture-report.js

@@ -12,6 +12,7 @@ export async function buildRuntimeCaptureReport(options = {}) {
   const results = [];
   for (const fixture of report.fixtures) {
     for (const target of captureTargets(fixture, rootDir)) {
+      options.signal?.throwIfAborted();
       results.push(await captureTarget(target, options));
     }
   }
@@ -117,6 +118,11 @@ async function captureTarget(target, options) {
       mockSdk: options.mockSdk !== false,
       apiOptions: options.apiOptions,
       env: options.env,
+      isolateCapture: options.isolateCapture,
+      timeoutMs: options.timeoutMs,
+      killGraceMs: options.killGraceMs,
+      maxOutputBytes: options.maxOutputBytes,
+      signal: options.signal,
     });
     return {
       fixture: target.fixture,

package/src/runtime-profile.js

@@ -333,6 +333,10 @@ async function profileCommand(command, options) {
     env: { ...process.env, ...options.env, ...command.env },
     stdio: ["ignore", "pipe", "pipe"],
     roundAverageCpuPercent: true,
+    timeoutMs: command.timeoutMs ?? options.timeoutMs,
+    maxOutputBytes: command.maxOutputBytes ?? options.maxOutputBytes,
+    killGraceMs: command.killGraceMs ?? options.killGraceMs,
+    signal: options.signal,
   });
 }
 

package/src/sdk-mock.js

@@ -1,5 +1,7 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import * as nodeModule from "node:module";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]);
 const SKIP_DIRS = new Set([".git", "coverage", "node_modules", "reports"]);
@@ -305,18 +307,48 @@ export async function createMockSdkPackage(rootDir, options = {}) {
 
   const fallbackExternalPath = path.join(externalDir, "__fallback__.js");
   await writeFile(fallbackExternalPath, externalMockModuleSource("__fallback__", new Set()), "utf8");
+  const roots = new Set();
+  for (const root of [options.pluginRoot, rootDir].filter(Boolean)) {
+    roots.add(path.resolve(root));
+    roots.add(await realpath(root));
+  }
   const loaderPath = path.join(rootDir, "mock-loader.mjs");
-  await writeFile(
-    loaderPath,
-    mockLoaderSource({
+  const syncLoaderPath = path.join(rootDir, "mock-loader-sync.mjs");
+  for (const [filePath, synchronous] of [[loaderPath, false], [syncLoaderPath, true]]) {
+    await writeFile(filePath, mockLoaderSource({
       externalMap,
       fallbackExternalPath,
       pluginSdkDir,
-    }),
-    "utf8",
-  );
+      roots: [...roots],
+      requireFiles: [...imports.requireFiles],
+      synchronous,
+    }), "utf8");
+  }
 
-  return { packageDir, loaderPath, pluginSdkDir };
+  return { packageDir, loaderPath, syncLoaderPath, pluginSdkDir };
+}
+
+export async function installMockSdkLoader(mockPackage) {
+  const supportsCommonJs = typeof nodeModule.registerHooks === "function";
+  // Async hooks cannot deregister. Shared state makes them inert after this capture.
+  const active = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.store(active, 0, 1);
+  nodeModule.register(pathToFileURL(mockPackage.loaderPath), { data: { active, supportsCommonJs } });
+  let hooks;
+  try {
+    if (supportsCommonJs) {
+      const { resolve } = await import(pathToFileURL(mockPackage.syncLoaderPath).href);
+      // Keep CommonJS loading native; a sync load hook changes its import path on Node 22.15.
+      hooks = nodeModule.registerHooks({ resolve });
+    }
+  } catch (error) {
+    Atomics.store(active, 0, 0);
+    throw error;
+  }
+  return () => {
+    hooks?.deregister();
+    Atomics.store(active, 0, 0);
+  };
 }
 
 function emptyRuntimeImports() {
@@ -324,6 +356,7 @@ function emptyRuntimeImports() {
     bySpecifier: new Map(),
     openclawSdkSpecifiers: new Set(["openclaw/plugin-sdk"]),
     bareSpecifiers: new Set(),
+    requireFiles: new Set(),
   };
 }
 
@@ -331,6 +364,7 @@ async function collectRuntimeImports(pluginRoot) {
   const bySpecifier = new Map();
   const openclawSdkSpecifiers = new Set(["openclaw/plugin-sdk"]);
   const bareSpecifiers = new Set();
+  const requireFiles = new Set();
   for (const filePath of await listSourceFiles(pluginRoot)) {
     const text = await readFile(filePath, "utf8");
     for (const entry of parseModuleImports(text)) {
@@ -341,6 +375,10 @@ async function collectRuntimeImports(pluginRoot) {
       } else {
         continue;
       }
+      if (entry.require && !requireFiles.has(path.resolve(filePath))) {
+        requireFiles.add(path.resolve(filePath));
+        requireFiles.add(await realpath(filePath));
+      }
       const names = bySpecifier.get(entry.specifier) ?? new Set();
       for (const name of entry.names) {
         names.add(name);
@@ -348,7 +386,7 @@ async function collectRuntimeImports(pluginRoot) {
       bySpecifier.set(entry.specifier, names);
     }
   }
-  return { bySpecifier, openclawSdkSpecifiers, bareSpecifiers };
+  return { bySpecifier, openclawSdkSpecifiers, bareSpecifiers, requireFiles };
 }
 
 async function listSourceFiles(dir) {
@@ -392,9 +430,62 @@ function parseModuleImports(text) {
   for (const match of text.matchAll(/\bimport\s+["']([^"']+)["']/g)) {
     entries.push({ specifier: match[1], names: new Set() });
   }
+  for (const { specifier, binding, member } of collectCommonJsRequires(text)) {
+    const names = new Set();
+    if (binding?.startsWith("{")) {
+      for (const part of binding.slice(1, -1).split(",")) {
+        const name = part.split(/[:=]/)[0].trim();
+        if (isValidExportName(name)) names.add(name);
+      }
+    } else if (binding) {
+      const escaped = binding.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      for (const access of text.matchAll(new RegExp(`(?<![$\\w])${escaped}\\s*\\.\\s*([$\\w]+)`, "g"))) {
+        names.add(access[1]);
+      }
+    }
+    if (member) names.add(member);
+    entries.push({ specifier, names, require: true });
+  }
   return entries;
 }
 
+export function* collectCommonJsRequires(text) {
+  const code = /\/\/[^\r\n]*|\/\*[\s\S]*?(?:\*\/|$)|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|(?<![$\w.])(?:(?:const|let|var)\s+(\{[^{}]*\}|[$A-Z_a-z][$\w]*)\s*=\s*)?require\s*\(\s*["']([^"']+)["']\s*\)(?:\s*\.\s*([$A-Z_a-z][$\w]*))?|[`{}]/g;
+  const template = /\\[\s\S]|`|\$\{/g;
+  const templateDepths = [];
+  let inTemplateText = false;
+  let cursor = 0;
+  // Skip quoted/comment text, but scan executable template interpolations.
+  while (cursor < text.length) {
+    const pattern = inTemplateText ? template : code;
+    pattern.lastIndex = cursor;
+    const match = pattern.exec(text);
+    if (!match) break;
+    cursor = pattern.lastIndex;
+    if (inTemplateText) {
+      if (match[0] === "`") {
+        templateDepths.pop();
+        inTemplateText = false;
+      } else if (match[0] === "${") {
+        templateDepths[templateDepths.length - 1] = 1;
+        inTemplateText = false;
+      }
+      continue;
+    }
+    if (match[0] === "`") {
+      templateDepths.push(0);
+      inTemplateText = true;
+    } else if (templateDepths.length && match[0] === "{") {
+      templateDepths[templateDepths.length - 1] += 1;
+    } else if (templateDepths.length && match[0] === "}") {
+      inTemplateText = --templateDepths[templateDepths.length - 1] === 0;
+    }
+    if (match[2]) {
+      yield { specifier: match[2], binding: match[1], member: match[3], index: match.index };
+    }
+  }
+}
+
 function isTypeOnlyImportOrExport(statement, clause) {
   return /^\s*import\s+type\b/u.test(statement) || /^\s*export\s+type\b/u.test(statement) || /^\s*type\b/u.test(clause);
 }
@@ -417,6 +508,7 @@ function parseNamedImports(clause) {
 
 function isMockableBareSpecifier(specifier) {
   return (
+    !nodeModule.isBuiltin(specifier) &&
     !specifier.startsWith(".") &&
     !specifier.startsWith("/") &&
     !specifier.startsWith("node:") &&
@@ -429,7 +521,9 @@ function safeModuleFileName(specifier) {
   return specifier.replace(/[^A-Za-z0-9._-]+/gu, "__");
 }
 
-function mockLoaderSource({ externalMap, fallbackExternalPath, pluginSdkDir }) {
+function mockLoaderSource({ externalMap, fallbackExternalPath, pluginSdkDir, roots, requireFiles, synchronous }) {
+  const asyncKeyword = synchronous ? "" : "async ";
+  const awaitKeyword = synchronous ? "" : "await ";
   return `import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { builtinModules, stripTypeScriptTypes } from "node:module";
@@ -439,9 +533,30 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const externalMap = new Map(Object.entries(${JSON.stringify(externalMap)}));
 const fallbackExternalPath = ${JSON.stringify(fallbackExternalPath)};
 const pluginSdkDir = ${JSON.stringify(pluginSdkDir)};
+const roots = ${JSON.stringify(roots)};
+const requireFiles = new Set(${JSON.stringify(requireFiles)});
 const builtins = new Set([...builtinModules, ...builtinModules.map((name) => \`node:\${name}\`)]);
+let active;
+let supportsCommonJs = false;
+
+export function initialize(data) {
+  active = data?.active;
+  supportsCommonJs = data?.supportsCommonJs === true;
+}
 
-export async function resolve(specifier, context, nextResolve) {
+function owns(url) {
+  if ((active && Atomics.load(active, 0) === 0) || !url?.startsWith("file:")) return false;
+  const filePath = fileURLToPath(url);
+  return roots.some((root) => {
+    const relative = path.relative(root, filePath);
+    return relative === "" || (!relative.startsWith(\`..\${path.sep}\`) && relative !== ".." && !path.isAbsolute(relative));
+  });
+}
+
+export ${asyncKeyword}function resolve(specifier, context, nextResolve) {
+  if (!owns(context.parentURL) || builtins.has(specifier) || specifier.startsWith("node:")) {
+    return nextResolve(specifier, context);
+  }
   if (specifier === "openclaw/plugin-sdk") {
     return moduleUrl(path.join(pluginSdkDir, "index.js"));
   }
@@ -458,7 +573,7 @@ export async function resolve(specifier, context, nextResolve) {
     return moduleUrl(externalMap.get(specifier));
   }
   try {
-    return await nextResolve(specifier, context);
+    return ${awaitKeyword}nextResolve(specifier, context);
   } catch (error) {
     const resolved = resolveExtensionless(specifier, context.parentURL);
     if (resolved) {
@@ -472,11 +587,16 @@ export async function resolve(specifier, context, nextResolve) {
 }
 
 export async function load(url, context, nextLoad) {
+  if (!owns(url)) return nextLoad(url, context);
   if (url.startsWith("file:") && /\\.[cm]?ts$/u.test(fileURLToPath(url))) {
     const rawSource = await readFile(fileURLToPath(url), "utf8");
     return { format: "module", source: stripPluginTypeScript(rawSource), shortCircuit: true };
   }
-  return nextLoad(url, context);
+  const result = await nextLoad(url, context);
+  ${synchronous ? "" : `if (!supportsCommonJs && result.format === "commonjs" && requireFiles.has(fileURLToPath(url))) {
+    throw new Error("CommonJS SDK mocking requires Node.js 22.15 or newer with module.registerHooks(); upgrade Node.js or use an ESM/TypeScript entrypoint.");
+  }`}
+  return result;
 }
 
 function stripPluginTypeScript(source) {