@openclaw/plugin-inspector 0.3.24 → 0.3.25

package/src/inspector.js

@@ -1,20 +1,19 @@
 import { existsSync } from "node:fs";
-import { execFile } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import * as nodeModule from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { promisify } from "node:util";
 import { createCaptureApi } from "./capture-api.js";
 import { captureApiOptionsForPlugin } from "./capture-config.js";
 import { fixtureCheckoutPath, fixtureSourceRoot } from "./config.js";
 import { buildCompatibilityFixtureReport } from "./fixture-summary.js";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
 import { prepareOpenClawTarget, resolveOpenClawTargetVersion } from "./openclaw-version.js";
+import { resolveProcessLimits, startOwnedProcess } from "./process-profile.js";
 import { buildCompatibilityReport, buildReport } from "./report.js";
 import { inspectSdkDeprecations } from "./sdk-deprecation-rules.js";
+import { collectCommonJsRequires } from "./sdk-mock.js";
 
-const execFileAsync = promisify(execFile);
 const pluginFactoryNames = "defineBundledChannelEntry|defineChannelPluginEntry|createChatChannelPlugin|definePluginEntry";
 // Bundlers emit unbound calls as (0, sdk.factory)(...), including inline require receivers.
 const compiledFactoryCall = new RegExp(String.raw`\(\s*0\s*,\s*(?:require\s*\(\s*(?:"[^"\r\n]*"|'[^'\r\n]*')\s*\)|[$A-Z_a-z][$\w]*)(?:\s*\.\s*[$A-Z_a-z][$\w]*)*\s*\.\s*(${pluginFactoryNames})\s*\)\s*\(`, "dg");
@@ -185,14 +184,23 @@ export async function captureEntrypoint(entrypoint, options = {}) {
   if (options.mockSdk === true) {
     return captureEntrypointWithMockSdk(entrypoint, options);
   }
+  if (options.isolateCapture === true) {
+    return captureEntrypointInChild(entrypoint, { ...options, mockSdk: false });
+  }
+  return invokeWithTimeout((signal) => captureInProcess(entrypoint, options, signal), options);
+}
 
+async function captureInProcess(entrypoint, options, signal) {
+  signal.throwIfAborted();
   const resolvedEntrypoint = path.resolve(options.cwd ?? process.cwd(), entrypoint);
   let module;
   try {
     module = await import(pathToFileURL(resolvedEntrypoint).href);
   } catch (error) {
+    signal.throwIfAborted();
     throw classifyCapturePhaseError(error, "entrypoint-import-error");
   }
+  signal.throwIfAborted();
   const register = findRegisterExport(module);
 
   if (!register) {
@@ -207,13 +215,17 @@ export async function captureEntrypoint(entrypoint, options = {}) {
     pluginRoot: options.pluginRoot
       ? path.resolve(options.cwd ?? process.cwd(), options.pluginRoot)
       : path.dirname(resolvedEntrypoint),
+    signal,
   });
+  signal.throwIfAborted();
   const api = createCaptureApi(apiOptions);
   try {
     await register(api);
   } catch (error) {
+    signal.throwIfAborted();
     throw classifyCapturePhaseError(error, "registration-execution-error");
   }
+  signal.throwIfAborted();
   const result = {
     status: "captured",
     entrypoint: resolvedEntrypoint,
@@ -226,60 +238,68 @@ export async function captureEntrypoint(entrypoint, options = {}) {
 }
 
 export async function captureEntrypointWithMockSdk(entrypoint, options = {}) {
+  return captureEntrypointInChild(entrypoint, { ...options, mockSdk: true });
+}
+
+async function captureEntrypointInChild(entrypoint, options) {
+  const label = options.mockSdk ? "Mock SDK" : "Real SDK";
   const runnerPath = fileURLToPath(new URL("./mock-sdk-capture-runner.js", import.meta.url));
   const payload = {
     entrypoint,
+    mockSdk: options.mockSdk,
     cwd: options.cwd ?? process.cwd(),
     pluginRoot: options.pluginRoot,
     apiOptions: options.apiOptions,
+    maxOutputBytes: options.maxOutputBytes,
   };
+  const { result } = startOwnedProcess({
+    command: process.execPath,
+    args: ["--no-warnings", ...(options.mockSdk ? ["--preserve-symlinks"] : []), runnerPath, JSON.stringify(payload)],
+    cwd: options.cwd ?? process.cwd(),
+    env: { ...process.env, ...options.env },
+    timeoutMs: options.timeoutMs,
+    killGraceMs: options.killGraceMs,
+    maxOutputBytes: options.maxOutputBytes,
+    signal: options.signal,
+  }, "CAPTURE");
+  const outcome = await result;
+  if (outcome.exitCode !== 0 || outcome.outputTruncated) {
+    const message = outcome.cancelled ? `${label} capture cancelled`
+      : outcome.outputTruncated ? `${label} capture output exceeded its byte limit`
+      : `${label} capture child failed`;
+    const { error: childError, ...details } = outcome;
+    throw classifyChildCaptureError(Object.assign(childError ?? new Error(message), details), options.mockSdk);
+  }
   try {
-    const { stdout } = await execFileAsync(
-      process.execPath,
-      ["--no-warnings", "--preserve-symlinks", runnerPath, JSON.stringify(payload)],
-      {
-        cwd: options.cwd ?? process.cwd(),
-        env: {
-          ...process.env,
-          ...(options.env ?? {}),
-        },
-        maxBuffer: 1024 * 1024 * 10,
-      },
-    );
-    return JSON.parse(stdout);
+    return JSON.parse(outcome.stdout);
   } catch (error) {
-    const captured = parseCaptureResultFromStdout(error?.stdout);
-    if (captured) {
-      return captured;
-    }
-    throw classifyMockSdkCaptureError(error);
+    throw classifyChildCaptureError(error, options.mockSdk);
   }
 }
 
-function parseCaptureResultFromStdout(stdout) {
-  if (!stdout) {
-    return null;
+export function classifyMockSdkCaptureError(error) {
+  return classifyChildCaptureError(error, true);
+}
+
+function classifyChildCaptureError(error, mockSdk) {
+  const label = mockSdk ? "Mock SDK" : "Real SDK";
+  const fallbackClass = mockSdk ? "mock-sdk-capture-error" : "capture-error";
+  if (error?.timedOut === true) {
+    return enrichCaptureError(error, {
+      message: `${label} capture timed out after ${error.timeoutMs}ms`,
+      failureClass: "capture-timeout",
+    });
   }
-  try {
-    const parsed = JSON.parse(stdout);
-    if (
-      parsed &&
-      typeof parsed === "object" &&
-      typeof parsed.status === "string" &&
-      Array.isArray(parsed.captured)
-    ) {
-      return parsed;
-    }
-  } catch {
-    return null;
+  if (error?.cancelled || error?.outputTruncated) {
+    return enrichCaptureError(error, {
+      message: error.message,
+      failureClass: fallbackClass,
+    });
   }
-  return null;
-}
 
-export function classifyMockSdkCaptureError(error) {
   const rawMessage = [error?.stderr, error?.stdout, error?.message].filter(Boolean).join("\n");
   const missingExport = rawMessage.match(/does not provide an export named ['"]([^'"]+)['"]/)?.[1];
-  if (missingExport) {
+  if (mockSdk && missingExport) {
     return enrichCaptureError(error, {
       message: `Mock SDK import failed: openclaw/plugin-sdk is missing export ${missingExport}`,
       failureClass: "missing-sdk-export",
@@ -290,9 +310,9 @@ export function classifyMockSdkCaptureError(error) {
   const missingModule =
     rawMessage.match(/Cannot find (?:package|module) ['"]([^'"]*openclaw\/plugin-sdk[^'"]*)['"]/)?.[1] ??
     rawMessage.match(/Package subpath ['"](\.\/plugin-sdk\/[^'"]+)['"]/)?.[1];
-  if (missingModule || rawMessage.includes("openclaw/plugin-sdk")) {
+  if (mockSdk && missingModule) {
     return enrichCaptureError(error, {
-      message: `Mock SDK import failed: ${missingModule ?? "openclaw/plugin-sdk module could not be resolved"}`,
+      message: `Mock SDK import failed: ${missingModule}`,
       failureClass: "missing-sdk-module",
       missingModule,
     });
@@ -301,17 +321,52 @@ export function classifyMockSdkCaptureError(error) {
   const failureClass = rawMessage.match(/\[plugin-inspector:([^\]]+)\]/)?.[1];
   if (failureClass) {
     return enrichCaptureError(error, {
-      message: firstMeaningfulErrorLine(rawMessage.replace(/\[plugin-inspector:[^\]]+\]/, "")) ?? "Mock SDK capture failed",
+      message: firstMeaningfulErrorLine(rawMessage.replace(/\[plugin-inspector:[^\]]+\]/, "")) ?? `${label} capture failed`,
       failureClass,
     });
   }
+  if (mockSdk && rawMessage.includes("openclaw/plugin-sdk")) {
+    return enrichCaptureError(error, {
+      message: "Mock SDK import failed: openclaw/plugin-sdk module could not be resolved",
+      failureClass: "missing-sdk-module",
+    });
+  }
 
   return enrichCaptureError(error, {
-    message: firstMeaningfulErrorLine(rawMessage) ?? "Mock SDK capture failed",
-    failureClass: "mock-sdk-capture-error",
+    message: firstMeaningfulErrorLine(rawMessage) ?? `${label} capture failed`,
+    failureClass: fallbackClass,
   });
 }
 
+function invokeWithTimeout(invoke, options) {
+  const { timeoutMs } = resolveProcessLimits(options, "CAPTURE");
+  const controller = new AbortController();
+  let rejectAborted;
+  const aborted = new Promise((_, reject) => { rejectAborted = reject; });
+  const onAbort = () => rejectAborted(controller.signal.reason);
+  const onCancel = () => controller.abort(classifyCapturePhaseError(
+    new Error("In-process capture cancelled"), "capture-error",
+  ));
+  controller.signal.addEventListener("abort", onAbort, { once: true });
+  const timeoutId = setTimeout(() => controller.abort(classifyCapturePhaseError(
+    new Error(`In-process capture timed out after ${timeoutMs}ms`), "capture-timeout",
+  )), timeoutMs);
+  // Observe late settlement, but stop inspector-owned phases after the deadline.
+  // Arbitrary plugin JavaScript is only preemptable in the supervised CLI child.
+  const run = Promise.resolve().then(() => {
+    controller.signal.throwIfAborted();
+    return invoke(controller.signal);
+  });
+  const result = Promise.race([run, aborted]).finally(() => {
+    clearTimeout(timeoutId);
+    controller.signal.removeEventListener("abort", onAbort);
+    options.signal?.removeEventListener("abort", onCancel);
+  });
+  options.signal?.addEventListener("abort", onCancel, { once: true });
+  if (options.signal?.aborted) onCancel();
+  return result;
+}
+
 export function classifyCapturePhaseError(error, failureClass) {
   return enrichCaptureError(error, {
     message: error instanceof Error ? error.message : String(error),
@@ -414,6 +469,16 @@ function collectSdkImports(text, filePath) {
       ref: `${filePath}:${line}`,
     });
   }
+  for (const { specifier, index } of collectCommonJsRequires(text)) {
+    if (specifier !== "openclaw/plugin-sdk" && !specifier.startsWith("openclaw/plugin-sdk/")) continue;
+    const line = lineForOffset(text, index);
+    details.push({
+      specifier,
+      file: filePath,
+      line,
+      ref: `${filePath}:${line}`,
+    });
+  }
   return details.sort((left, right) => left.line - right.line || left.specifier.localeCompare(right.specifier));
 }
 

package/src/mock-sdk-capture-runner.js

@@ -1,37 +1,56 @@
 #!/usr/bin/env node
 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 { writeArtifacts } from "./artifacts.js";
 import { createCaptureApi } from "./capture-api.js";
 import { captureApiOptionsForPlugin } from "./capture-config.js";
-import { createMockSdkPackage } from "./sdk-mock.js";
+import { createCappedCollector, resolveProcessLimits } from "./process-profile.js";
+import { createMockSdkPackage, installMockSdkLoader } from "./sdk-mock.js";
 
 const options = JSON.parse(process.argv[2] ?? "{}");
 let activeOutputCapture = null;
 
 try {
   const result = await run(options);
-  writeRunnerStdout(`${JSON.stringify(result, null, 2)}\n`);
+  const json = `${JSON.stringify(result, null, 2)}\n`;
+  const { maxOutputBytes } = resolveProcessLimits(options, options.syntheticProbes ? "PROBE" : "CAPTURE");
+  if (Buffer.byteLength(json) > maxOutputBytes) {
+    const label = options.syntheticProbes ? "Synthetic probe" : `${options.mockSdk === false ? "Real SDK" : "Mock SDK"} capture`;
+    throw new Error(`${label} result exceeded its ${maxOutputBytes}-byte limit`);
+  }
+  if (options.outputPath) {
+    await writeArtifacts([{ path: options.outputPath, content: json }]);
+  } else {
+    await writeRunnerStdout(json);
+  }
+  process.exit(0);
 } catch (error) {
   if (error.failureClass) {
-    writeRunnerStderr(`[plugin-inspector:${error.failureClass}]\n`);
+    await writeRunnerStderr(`[plugin-inspector:${error.failureClass}]\n`);
   }
-  writeRunnerStderr(`${error.stack ?? error.message}\n`);
-  process.exitCode = 1;
+  await writeRunnerStderr(`${options.outputPath ? error.message : (error.stack ?? error.message)}\n`);
+  process.exit(1);
 }
 
 async function run(options) {
   const entrypoint = path.resolve(options.cwd ?? process.cwd(), options.entrypoint);
   const pluginRoot = path.resolve(options.cwd ?? process.cwd(), options.pluginRoot ?? path.dirname(entrypoint));
+  if (options.mockSdk === false) {
+    return await captureLinkedEntrypoint(entrypoint, { ...options, pluginRoot });
+  }
   const workspace = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-mock-sdk-"));
 
   cleanupTempDirOnExit(workspace);
-  const { loaderPath } = await createMockSdkPackage(workspace, { pluginRoot });
-  register(pathToFileURL(loaderPath));
-  return await captureLinkedEntrypoint(entrypoint, { ...options, pluginRoot });
+  const mockPackage = await createMockSdkPackage(workspace, { pluginRoot });
+  const stopLoader = await installMockSdkLoader(mockPackage);
+  try {
+    return await captureLinkedEntrypoint(entrypoint, { ...options, pluginRoot });
+  } finally {
+    stopLoader();
+  }
 }
 
 function cleanupTempDirOnExit(dir) {
@@ -55,14 +74,15 @@ async function captureLinkedEntrypoint(entrypoint, options) {
 
   if (!register) {
     await drainAsyncOutput();
-    return withProcessOutput(
+    return finishCapture(
       {
         status: "no-register-export",
-        entrypoint: options.entrypoint,
-        mockSdk: true,
+        entrypoint: options.mockSdk === false ? entrypoint : options.entrypoint,
+        mockSdk: options.mockSdk !== false,
         captured: [],
       },
       outputCapture,
+      options,
     );
   }
 
@@ -80,13 +100,22 @@ async function captureLinkedEntrypoint(entrypoint, options) {
 
   const result = {
     status: "captured",
-    entrypoint: options.entrypoint,
-    mockSdk: true,
+    entrypoint: options.mockSdk === false ? entrypoint : options.entrypoint,
+    mockSdk: options.mockSdk !== false,
     captured: api.getCapturedContracts(),
   };
   if (apiOptions?.retainHandlers === true) {
     result.retained = api.getRetainedContracts();
   }
+  return finishCapture(result, outputCapture, options);
+}
+
+async function finishCapture(result, outputCapture, options) {
+  if (options.syntheticProbes) {
+    const { runCapturedSyntheticProbes } = await import("./synthetic-probes.js");
+    result = await runCapturedSyntheticProbes(result, options);
+    await drainAsyncOutput();
+  }
   return withProcessOutput(result, outputCapture);
 }
 
@@ -124,18 +153,18 @@ function findRegisterExport(module) {
 }
 
 function installProcessOutputCapture() {
-  const stdoutChunks = [];
-  const stderrChunks = [];
+  const stdout = createCappedCollector(1024 * 1024);
+  const stderr = createCappedCollector(1024 * 1024);
   const originalStdoutWrite = process.stdout.write.bind(process.stdout);
   const originalStderrWrite = process.stderr.write.bind(process.stderr);
 
   process.stdout.write = (chunk, encoding, callback) => {
-    stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+    stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), typeof encoding === "string" ? encoding : "utf8"));
     invokeWriteCallback(encoding, callback);
     return true;
   };
   process.stderr.write = (chunk, encoding, callback) => {
-    stderrChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+    stderr.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), typeof encoding === "string" ? encoding : "utf8"));
     invokeWriteCallback(encoding, callback);
     return true;
   };
@@ -143,8 +172,8 @@ function installProcessOutputCapture() {
   return {
     originalStdoutWrite,
     originalStderrWrite,
-    stdout: () => stdoutChunks.join(""),
-    stderr: () => stderrChunks.join(""),
+    stdout: () => stdout.text(),
+    stderr: () => stderr.text(),
   };
 }
 
@@ -162,9 +191,19 @@ async function drainAsyncOutput() {
 }
 
 function writeRunnerStdout(text) {
-  (activeOutputCapture?.originalStdoutWrite ?? process.stdout.write.bind(process.stdout))(text);
+  const write = activeOutputCapture?.originalStdoutWrite ?? process.stdout.write.bind(process.stdout);
+  return flushWrite(write, text);
 }
 
 function writeRunnerStderr(text) {
-  (activeOutputCapture?.originalStderrWrite ?? process.stderr.write.bind(process.stderr))(text);
+  const write = activeOutputCapture?.originalStderrWrite ?? process.stderr.write.bind(process.stderr);
+  return flushWrite(write, text);
+}
+
+// The runner exits deliberately to shed plugin timers, but only after the
+// complete protocol response has reached its pipe.
+function flushWrite(write, text) {
+  return new Promise((resolve, reject) => {
+    write(text, (error) => error ? reject(error) : resolve());
+  });
 }

package/src/openclaw-version.js

@@ -8,6 +8,9 @@ import { x as extractTar } from "tar";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
 
 const defaultRegistryUrl = "https://registry.npmjs.org";
+const defaultFetchTimeoutMs = 30_000;
+const defaultMaxArchiveBytes = 256 * 1024 * 1024;
+const defaultMaxMetadataBytes = 16 * 1024 * 1024;
 const supportedTags = new Set(["latest", "beta"]);
 const downloadUrls = new WeakMap();
 
@@ -25,8 +28,8 @@ export async function resolveOpenClawTargetVersion(requestedVersion, options = {
   let distTag = null;
 
   if (supportedTags.has(requested)) {
-    const metadata = await fetchJson(`${registryUrl}/openclaw`, fetchImpl);
-    version = metadata["dist-tags"]?.[requested];
+    const distTags = await fetchJson(`${registryUrl}/-/package/openclaw/dist-tags`, fetchImpl, options);
+    version = distTags?.[requested];
     if (typeof version !== "string" || version.length === 0) {
       throw new Error(`OpenClaw npm dist-tag ${requested} did not resolve to an exact version`);
     }
@@ -38,7 +41,7 @@ export async function resolveOpenClawTargetVersion(requestedVersion, options = {
     throw new Error("--openclaw-version must be latest, beta, or an exact OpenClaw version");
   }
 
-  const versionMetadata = await fetchJson(`${registryUrl}/openclaw/${encodeURIComponent(version)}`, fetchImpl);
+  const versionMetadata = await fetchJson(`${registryUrl}/openclaw/${encodeURIComponent(version)}`, fetchImpl, options);
   if (versionMetadata.version !== version || typeof versionMetadata.dist?.tarball !== "string") {
     throw new Error(`OpenClaw npm metadata for ${version} is incomplete`);
   }
@@ -137,11 +140,12 @@ export function satisfiesOpenClawCompatibilityRange({ targetVersion, eligibility
 
 async function preparePackageArchive(resolvedTarget, options) {
   const fetchImpl = options.fetch ?? globalThis.fetch;
-  const response = await fetchImpl(downloadUrlFor(resolvedTarget));
+  const response = await fetchWithTimeout(fetchImpl, downloadUrlFor(resolvedTarget), {}, options, "npm archive");
   if (!response.ok) {
+    await cancelBody(response.body);
     throw new Error(`failed to download OpenClaw ${resolvedTarget.version}: HTTP ${response.status}`);
   }
-  const archive = Buffer.from(await response.arrayBuffer());
+  const archive = await readLimitedBody(response, maxArchiveBytes(options), "npm archive");
   verifyArchive(archive, resolvedTarget.source);
 
   await mkdir(path.dirname(options.targetDir), { recursive: true });
@@ -191,10 +195,118 @@ function verifyArchive(archive, source) {
   throw new Error("OpenClaw npm archive has no supported integrity metadata");
 }
 
-async function fetchJson(url, fetchImpl) {
-  const response = await fetchImpl(url, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new Error(`failed to resolve OpenClaw npm metadata: HTTP ${response.status}`);
-  return response.json();
+async function fetchJson(url, fetchImpl, options = {}) {
+  const response = await fetchWithTimeout(
+    fetchImpl,
+    url,
+    { headers: { accept: "application/json" } },
+    options,
+    "npm metadata",
+  );
+  if (!response.ok) {
+    await cancelBody(response.body);
+    throw new Error(`failed to resolve OpenClaw npm metadata: HTTP ${response.status}`);
+  }
+  const body = await readLimitedBody(response, maxMetadataBytes(options), "npm metadata");
+  return JSON.parse(body.toString("utf8"));
+}
+
+async function fetchWithTimeout(fetchImpl, url, init, options, what) {
+  try {
+    return await fetchImpl(url, { ...init, signal: AbortSignal.timeout(fetchTimeoutMs(options)) });
+  } catch (error) {
+    throw mapTargetFetchError(error, what);
+  }
+}
+
+async function readLimitedBody(response, maxBytes, what) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await cancelBody(response.body);
+    throw targetDownloadLimitError(what, maxBytes);
+  }
+
+  let reader;
+  try {
+    if (!response.body || typeof response.body.getReader !== "function") {
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (buffer.length > maxBytes) throw targetDownloadLimitError(what, maxBytes);
+      return buffer;
+    }
+
+    reader = response.body.getReader();
+    const chunks = [];
+    let received = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.byteLength;
+      if (received > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {}
+        throw targetDownloadLimitError(what, maxBytes);
+      }
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+  } catch (error) {
+    throw mapTargetFetchError(error, what);
+  } finally {
+    reader?.releaseLock();
+  }
+}
+
+async function cancelBody(body) {
+  try {
+    await body?.cancel?.();
+  } catch {}
+}
+
+function fetchTimeoutMs(options) {
+  const timeout = positiveInteger(
+    options.fetchTimeoutMs ?? process.env.PLUGIN_INSPECTOR_TARGET_FETCH_TIMEOUT_MS,
+    defaultFetchTimeoutMs,
+  );
+  // Node clamps overflowing timer delays to 1ms instead of honoring the budget.
+  return timeout <= 2_147_483_647 ? timeout : defaultFetchTimeoutMs;
+}
+
+function maxArchiveBytes(options) {
+  return positiveInteger(options.maxArchiveBytes ?? process.env.PLUGIN_INSPECTOR_TARGET_ARCHIVE_MAX_BYTES, defaultMaxArchiveBytes);
+}
+
+function maxMetadataBytes(options) {
+  return positiveInteger(options.maxMetadataBytes ?? process.env.PLUGIN_INSPECTOR_TARGET_METADATA_MAX_BYTES, defaultMaxMetadataBytes);
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function mapTargetFetchError(error, what) {
+  if (error?.failureClass) return error;
+  if (isTimeoutError(error)) {
+    const wrapped = new Error(`OpenClaw ${what} download timed out`);
+    wrapped.failureClass = "target-download-timeout";
+    wrapped.cause = error;
+    return wrapped;
+  }
+  return error;
+}
+
+function isTimeoutError(error) {
+  for (let current = error; current; current = current.cause) {
+    if (current.name === "TimeoutError" || current.name === "AbortError") return true;
+  }
+  return false;
+}
+
+function targetDownloadLimitError(what, maxBytes) {
+  const error = new Error(`OpenClaw ${what} exceeds the ${maxBytes} byte download limit`);
+  error.failureClass = "target-download-too-large";
+  return error;
 }
 
 function cacheKeyFor(target) {