@openclaw/plugin-inspector 0.3.24 → 0.3.26

package/src/sdk-mock.js

@@ -1,5 +1,8 @@
-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";
+import { collectRuntimeModuleImports } from "./runtime-imports.js";
 
 const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]);
 const SKIP_DIRS = new Set([".git", "coverage", "node_modules", "reports"]);
@@ -162,6 +165,14 @@ export const mockSdkSubpathExports = {
     "normalizeSecretInputString",
   ],
   "plugin-runtime": ["createLoggerBackedRuntime", "createSubsystemLogger"],
+  "lazy-runtime": [
+    "createLazyRuntimeModule",
+    "createLazyRuntimeMethod",
+    "createLazyRuntimeMethodBinder",
+    "createLazyRuntimeNamedExport",
+    "createLazyRuntimeSurface",
+  ],
+  "error-runtime": ["formatErrorMessage"],
   "secret-input": [
     "buildOptionalSecretInputSchema",
     "buildSecretInputArraySchema",
@@ -305,18 +316,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 +365,7 @@ function emptyRuntimeImports() {
     bySpecifier: new Map(),
     openclawSdkSpecifiers: new Set(["openclaw/plugin-sdk"]),
     bareSpecifiers: new Set(),
+    requireFiles: new Set(),
   };
 }
 
@@ -331,6 +373,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 +384,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 +395,7 @@ async function collectRuntimeImports(pluginRoot) {
       bySpecifier.set(entry.specifier, names);
     }
   }
-  return { bySpecifier, openclawSdkSpecifiers, bareSpecifiers };
+  return { bySpecifier, openclawSdkSpecifiers, bareSpecifiers, requireFiles };
 }
 
 async function listSourceFiles(dir) {
@@ -392,6 +439,9 @@ function parseModuleImports(text) {
   for (const match of text.matchAll(/\bimport\s+["']([^"']+)["']/g)) {
     entries.push({ specifier: match[1], names: new Set() });
   }
+  for (const { specifier, names, kind } of collectRuntimeModuleImports(text)) {
+    entries.push({ specifier, names, require: kind === "require" });
+  }
   return entries;
 }
 
@@ -417,6 +467,7 @@ function parseNamedImports(clause) {
 
 function isMockableBareSpecifier(specifier) {
   return (
+    !nodeModule.isBuiltin(specifier) &&
     !specifier.startsWith(".") &&
     !specifier.startsWith("/") &&
     !specifier.startsWith("node:") &&
@@ -429,7 +480,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 +492,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 +532,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 +546,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) {
@@ -621,6 +700,11 @@ function isValidExportName(name) {
 }
 
 function genericExportStatement(name) {
+  if (name === "normalizeOptionalString") {
+    // Optional values stay absent; an empty string invents explicit input in
+    // callers that distinguish undefined from a configured policy value.
+    return 'export function normalizeOptionalString(value) { return typeof value === "string" ? value.trim() || undefined : undefined; }';
+  }
   if (name === "isRecord") {
     return "export function isRecord(value) { return isPlainObject(value); }";
   }
@@ -1638,6 +1722,37 @@ export function resolveRuntimeEnv(env = {}) {
   return createRuntimeEnv(env);
 }
 
+export function createLazyRuntimeSurface(importer, select) {
+  let promise;
+  const load = () => {
+    // SDK runtime imports retain the same promise, including rejection, until clear().
+    promise ??= Promise.resolve().then(() => importer().then(select));
+    return promise;
+  };
+  load.peek = () => promise;
+  load.clear = () => { promise = undefined; };
+  return load;
+}
+
+export function createLazyRuntimeModule(importer) {
+  return createLazyRuntimeSurface(importer, (module) => module);
+}
+
+export function createLazyRuntimeNamedExport(importer, key) {
+  return createLazyRuntimeSurface(importer, (module) => module[key]);
+}
+
+export function createLazyRuntimeMethod(load, select) {
+  return async (...args) => {
+    const method = select(await load());
+    return await method(...args);
+  };
+}
+
+export function createLazyRuntimeMethodBinder(load) {
+  return (select) => createLazyRuntimeMethod(load, select);
+}
+
 export function createLoggerBackedRuntime(logger = console) {
   return { logger };
 }

package/src/synthetic-entrypoint.js

@@ -1,27 +1,22 @@
 import { rmSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
-import { register } from "node:module";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { captureEntrypoint } from "./inspector.js";
-import { createMockSdkPackage } from "./sdk-mock.js";
+import { createMockSdkPackage, installMockSdkLoader } from "./sdk-mock.js";
 import { runCapturedSyntheticProbes } from "./synthetic-probes.js";
 
 export async function runEntrypointSyntheticProbes(entrypoint, options = {}) {
-  const capture = await captureEntrypointForSyntheticProbes(entrypoint, {
+  const captureOptions = {
     ...options,
     apiOptions: {
       ...(options.apiOptions ?? {}),
       retainHandlers: true,
     },
-  });
-  return runCapturedSyntheticProbes(capture, options);
-}
-
-async function captureEntrypointForSyntheticProbes(entrypoint, options) {
+  };
   if (options.mockSdk !== true) {
-    return captureEntrypoint(entrypoint, options);
+    const capture = await captureEntrypoint(entrypoint, captureOptions);
+    return runCapturedSyntheticProbes(capture, options);
   }
 
   const cwd = options.cwd ?? process.cwd();
@@ -29,15 +24,20 @@ async function captureEntrypointForSyntheticProbes(entrypoint, options) {
   const pluginRoot = path.resolve(cwd, options.pluginRoot ?? path.dirname(resolvedEntrypoint));
   const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-mock-sdk-"));
   cleanupTempDirOnExit(workspace);
-  const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
-  register(pathToFileURL(loaderPath));
-
-  return captureEntrypoint(entrypoint, {
-    ...options,
-    cwd,
-    mockSdk: false,
-    pluginRoot,
-  });
+  const mockPackage = await createMockSdkPackage(workspace, { pluginRoot });
+  const stopLoader = await installMockSdkLoader(mockPackage);
+  try {
+    const capture = await captureEntrypoint(entrypoint, {
+      ...captureOptions,
+      cwd,
+      mockSdk: false,
+      pluginRoot,
+    });
+    // Retained handlers can require SDK modules lazily during invocation.
+    return await runCapturedSyntheticProbes(capture, options);
+  } finally {
+    stopLoader();
+  }
 }
 
 function cleanupTempDirOnExit(dir) {

package/src/synthetic-probes-cli.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
-import { runEntrypointSyntheticProbes, writeArtifacts } from "./advanced.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readBoundedJsonArtifact, writeArtifacts } from "./artifacts.js";
+import { resolveProcessLimits, startOwnedProcess } from "./process-profile.js";
 
 const args = process.argv.slice(2);
 
@@ -26,7 +31,7 @@ async function run(commandArgs) {
     throw new Error("synthetic probes import plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
   }
 
-  const results = await runEntrypointSyntheticProbes(entrypoint, {
+  const results = await runInChild(entrypoint, {
     mockSdk,
     pluginRoot,
     apiOptions: { retainHandlers: true },
@@ -43,6 +48,78 @@ async function run(commandArgs) {
   }
 }
 
+async function runInChild(entrypoint, options) {
+  const limits = resolveProcessLimits({}, "PROBE");
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-synthetic-cli-"));
+  const outputPath = path.join(workspace, "result.json");
+  const controller = new AbortController();
+  const cancel = () => controller.abort(new Error("Synthetic probes cancelled"));
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  try {
+    const runnerPath = fileURLToPath(new URL("./mock-sdk-capture-runner.js", import.meta.url));
+    const { result } = startOwnedProcess({
+      command: process.execPath,
+      args: [
+        "--no-warnings",
+        ...(options.mockSdk ? ["--preserve-symlinks"] : []),
+        runnerPath,
+        JSON.stringify({
+          ...options, ...limits, entrypoint, outputPath,
+          cwd: process.cwd(), syntheticProbes: true,
+        }),
+      ],
+      ...limits,
+      signal: controller.signal,
+    }, "PROBE");
+    const outcome = await result;
+    if (outcome.exitCode !== 0 || outcome.outputTruncated) {
+      const message = outcome.cancelled ? "Synthetic probes cancelled"
+        : outcome.timedOut ? `Synthetic probes timed out after ${limits.timeoutMs}ms`
+        : outcome.outputTruncated ? "Synthetic probe child output exceeded its byte limit"
+        : outcome.stderr.trim() || outcome.error?.message || "Synthetic probe child failed";
+      throw new Error(message);
+    }
+    controller.signal.throwIfAborted();
+    // The report is separate from plugin stdout, including direct fd writes.
+    // Only accept a fresh complete artifact after successful child cleanup.
+    const results = await readBoundedJsonArtifact(outputPath, limits.maxOutputBytes);
+    validateSyntheticReport(results);
+    controller.signal.throwIfAborted();
+    return results;
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+    await rm(workspace, { recursive: true, force: true });
+  }
+}
+
+function validateSyntheticReport(report) {
+  const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  if (!isObject(report) || typeof report.entrypoint !== "string" ||
+      !["captured", "no-register-export"].includes(report.status) ||
+      !isObject(report.summary) || !Array.isArray(report.results)) {
+    throw new Error("Invalid synthetic probe report: expected entrypoint, status, summary, and results");
+  }
+  const counts = { probeCount: report.results.length, passCount: 0, failCount: 0, blockedCount: 0 };
+  for (const row of report.results) {
+    if (!isObject(row) || !Number.isSafeInteger(row.captureIndex) || row.captureIndex < 0 ||
+        !["kind", "seam", "label"].every((key) => typeof row[key] === "string") ||
+        !["pass", "fail", "blocked"].includes(row.status) ||
+        (row.status === "fail" && typeof row.error !== "string") ||
+        (row.status === "blocked" && typeof row.reason !== "string")) {
+      throw new Error("Invalid synthetic probe report: malformed result row");
+    }
+    counts[`${row.status}Count`] += 1;
+  }
+  for (const [key, expected] of Object.entries(counts)) {
+    if (!Number.isSafeInteger(report.summary[key]) || report.summary[key] < 0 ||
+        report.summary[key] !== expected) {
+      throw new Error(`Invalid synthetic probe report: invalid or inconsistent ${key}`);
+    }
+  }
+}
+
 function readFlag(commandArgs, name) {
   const index = commandArgs.indexOf(name);
   if (index === -1) {