@openclaw/plugin-inspector 0.3.11 → 0.3.13

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.3.13 - 2026-06-09
+
+### Changed
+
+- Add `authorRemediation.summary` and `authorRemediation.docsUrl` guidance to author-facing compatibility issues and Markdown reports.
+- Add `--author-facing` for `check`, `ci`, and `batch` reports while keeping default output complete for internal coverage findings.
+- Replace the recent `--include-inspector-gaps` option with a clear error pointing to `--author-facing`.
+
+## 0.3.12 - 2026-06-09
+
+### Changed
+
+- Hide maintainer-facing `inspector-gap` findings from author-facing `check`, `ci`, and `batch` output by default, with `--include-inspector-gaps` for internal coverage reports.
+
 ## 0.3.11 - 2026-05-26
 
 ### Fixed

package/README.md

@@ -170,6 +170,7 @@ Copy-ready examples live in:
 | `plugin-inspector config` | Print resolved plugin-root config as text or JSON. |
 | `plugin-inspector init` | Write starter config, scripts, and optional GitHub Actions workflow. |
 | `plugin-inspector report` | Run a fixture-suite config with many plugins. |
+| `plugin-inspector batch` | Discover plugin roots under a folder and write one aggregate impact report. |
 | `plugin-inspector capture` | Runtime-capture one entrypoint directly. |
 
 Common options:
@@ -186,6 +187,7 @@ Common options:
 | `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
 | `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
 | `--allow-execute` | Permit commands that import plugin code. |
+| `--author-facing` | Limit `check`, `ci`, and `batch` reports to findings with `authorRemediation` guidance. |
 | `--json` | Print machine-readable JSON to stdout. |
 | `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
@@ -305,8 +307,10 @@ Important report sections:
 | `logs` | Informational inventory and coverage rows. |
 | `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
 
-Issue classes currently flow through the reports as live issues, compat gaps,
-deprecation warnings, inspector gaps, upstream metadata, and fixture regressions.
+Default `check`, `ci`, and `batch` reports include both author-facing and
+internal findings. Pass `--author-facing` when producing plugin-author output;
+that filtered view includes only findings with `authorRemediation.summary` and
+`authorRemediation.docsUrl`.
 
 ## CI Policy And Shared Reporting Primitives
 
@@ -404,6 +408,7 @@ Stable grouped facades:
 | `reports` | Render/write reports and classify issue findings. |
 | `contracts` | Build, render, validate, and write contract captures and coverage. |
 | `ci` | Build summaries, policy reports, execution results, SARIF, and JUnit outputs. |
+| `batch` | Discover plugin roots and aggregate compatibility findings across a corpus. |
 | `runtime` | Build runtime profiles, profile diffs, ref diffs, and import-loop profiles. |
 | `synthetic` | Build and run synthetic probe plans. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/advanced.js

@@ -77,6 +77,7 @@ export {
   classifyIssueFinding,
   deprecatedCompatRecords,
   issueId,
+  isAuthorFacingFinding,
   issueMetadata,
   issueMetadataByCode,
   knownIssueCodes,

package/src/api.js

@@ -43,6 +43,7 @@ export async function loadPluginConfig(options = {}) {
 export async function inspectPluginRoot(options = {}) {
   const config = await loadPluginConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
@@ -58,6 +59,7 @@ export async function inspectFixtureSetConfig(options = {}) {
 export async function inspectCompatibilityFixtureSetConfig(options = {}) {
   const config = await loadFixtureSetConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
@@ -112,6 +114,7 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
@@ -144,6 +147,7 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,

package/src/batch.js

@@ -0,0 +1,309 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { renderMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { runPluginCheck } from "./api.js";
+
+const ignoredDirs = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "reports",
+  "dist",
+  "build",
+  ".plugin-inspector",
+]);
+
+export async function runBatchAnalysis(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? options.inputDir ?? process.cwd());
+  const outDir = options.outDir ?? "reports";
+  const outRoot = path.resolve(rootDir, outDir);
+  const concurrency = Math.max(1, Math.min(Math.round(options.concurrency ?? 4), 32));
+  const keepPluginReports = options.keepPluginReports === true;
+  const pluginRoots = await discoverPluginRoots(rootDir);
+  const tempRoot = keepPluginReports ? null : await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-batch-"));
+  const entries = [];
+
+  try {
+    await runWithConcurrency(pluginRoots, concurrency, async (pluginRoot) => {
+      const reportsRoot = keepPluginReports
+        ? path.join(outRoot, "plugins", slugForPath(path.relative(rootDir, pluginRoot)))
+        : path.join(tempRoot, slugForPath(path.relative(rootDir, pluginRoot)));
+      entries.push(
+        await inspectBatchPlugin(pluginRoot, {
+          ...options,
+          rootDir,
+          outDir: reportsRoot,
+          openclawPath: options.openclawPath,
+        }),
+      );
+    });
+  } finally {
+    if (tempRoot) await rm(tempRoot, { recursive: true, force: true });
+  }
+
+  entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const report = buildBatchReport({
+    rootDir,
+    entries,
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+  });
+  const paths = await writeBatchReport(report, { outDir: outRoot, check: options.checkArtifacts });
+  return { report, paths };
+}
+
+export async function discoverPluginRoots(rootDir) {
+  const roots = [];
+  await walk(path.resolve(rootDir));
+  roots.sort();
+  return roots;
+
+  async function walk(dir) {
+    if (await isPluginRoot(dir)) {
+      roots.push(dir);
+      return;
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || ignoredDirs.has(entry.name)) continue;
+      await walk(path.join(dir, entry.name));
+    }
+  }
+}
+
+export async function writeBatchReport(report, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.json"),
+    markdownPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.md"),
+    json: report,
+    markdown: renderBatchMarkdown(report),
+    check: options.check,
+  });
+}
+
+function buildBatchReport({ rootDir, entries, generatedAt }) {
+  const findingFrequency = findingFrequencyRows(entries);
+  const summary = {
+    pluginCount: entries.length,
+    passed: entries.filter((entry) => entry.status === "pass").length,
+    failed: entries.filter((entry) => entry.status !== "pass").length,
+    pluginsWithErrors: entries.filter((entry) => entry.errorCount > 0).length,
+    pluginsWithWarnings: entries.filter((entry) => entry.warningCount > 0).length,
+    errorCount: entries.reduce((sum, entry) => sum + entry.errorCount, 0),
+    warningCount: entries.reduce((sum, entry) => sum + entry.warningCount, 0),
+    findingCodeCount: findingFrequency.length,
+  };
+  return {
+    generatedAt,
+    rootDir,
+    summary,
+    findingFrequency,
+    plugins: entries,
+  };
+}
+
+async function inspectBatchPlugin(pluginRoot, options) {
+  try {
+    const { report } = await runPluginCheck({
+      allowExecution: options.allowExecution,
+      authorFacing: options.authorFacing,
+      capture: options.capture,
+      configPath: options.configPath,
+      mockSdk: options.mockSdk,
+      openclawPath: options.openclawPath,
+      outDir: options.outDir,
+      pluginRoot,
+    });
+    const findings = normalizeReportFindings(report);
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: report.status,
+      packageName: packageNameFromReport(report),
+      targetOpenClaw: report.targetOpenClaw,
+      errorCount: findings.filter((finding) => finding.kind === "error").length,
+      warningCount: findings.filter((finding) => finding.kind === "warning").length,
+      findings,
+    };
+  } catch (error) {
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: "error",
+      packageName: path.basename(pluginRoot),
+      targetOpenClaw: null,
+      errorCount: 1,
+      warningCount: 0,
+      findings: [
+        {
+          kind: "error",
+          code: "plugin-inspector-batch-failure",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+function normalizeReportFindings(report) {
+  const issueFindings = (report.issues ?? []).map((finding) =>
+    normalizeFinding(
+      finding,
+      finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
+    ),
+  );
+  const issueKeys = new Set(issueFindings.map(findingKey));
+  const rawFindings = [
+    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
+    ...(report.warnings ?? []).map((finding) => normalizeFinding(finding, "warning")),
+    ...(report.suggestions ?? []).map((finding) => normalizeFinding(finding, "warning")),
+  ].filter((finding) => !issueKeys.has(findingKey(finding)));
+
+  return [...issueFindings, ...rawFindings];
+}
+
+function normalizeFinding(finding, kind) {
+  return {
+    kind,
+    code: finding.code ?? "plugin-inspector-finding",
+    severity: finding.severity,
+    issueClass: finding.issueClass,
+    message: finding.message ?? finding.title ?? "See plugin report.",
+    evidence: finding.evidence,
+    ...(finding.authorRemediation ? { authorRemediation: finding.authorRemediation } : {}),
+  };
+}
+
+function findingKey(finding) {
+  return [
+    finding.fixture ?? "",
+    finding.code ?? "",
+    ...(Array.isArray(finding.evidence) ? finding.evidence : []),
+  ].join("\n");
+}
+
+function findingFrequencyRows(entries) {
+  const byCode = new Map();
+  for (const entry of entries) {
+    const seenForPlugin = new Set();
+    for (const finding of entry.findings) {
+      const current = byCode.get(finding.code) ?? {
+        code: finding.code,
+        count: 0,
+        plugins: 0,
+        errors: 0,
+        warnings: 0,
+      };
+      current.count += 1;
+      if (!seenForPlugin.has(finding.code)) {
+        current.plugins += 1;
+        seenForPlugin.add(finding.code);
+      }
+      if (finding.kind === "error") current.errors += 1;
+      else current.warnings += 1;
+      byCode.set(finding.code, current);
+    }
+  }
+  return [...byCode.values()].sort((a, b) => b.plugins - a.plugins || b.count - a.count);
+}
+
+function renderBatchMarkdown(report) {
+  return [
+    "# Plugin Inspector Batch Report",
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Root: ${report.rootDir}`,
+    "",
+    "## Summary",
+    "",
+    renderMarkdownTable(
+      [
+        ["Plugins", report.summary.pluginCount],
+        ["Passed", report.summary.passed],
+        ["Failed", report.summary.failed],
+        ["Plugins with errors", report.summary.pluginsWithErrors],
+        ["Plugins with warnings", report.summary.pluginsWithWarnings],
+        ["Errors", report.summary.errorCount],
+        ["Warnings", report.summary.warningCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Finding Frequency",
+    "",
+    report.findingFrequency.length
+      ? renderMarkdownTable(
+          report.findingFrequency.map((row) => [
+            row.code,
+            row.plugins,
+            row.count,
+            row.errors,
+            row.warnings,
+          ]),
+          ["Code", "Plugins", "Findings", "Errors", "Warnings"],
+        )
+      : "_No findings._",
+    "",
+    "## Plugins",
+    "",
+    report.plugins.length
+      ? renderMarkdownTable(
+          report.plugins.map((plugin) => [
+            plugin.packageName,
+            plugin.relativePath,
+            plugin.status,
+            plugin.errorCount,
+            plugin.warningCount,
+          ]),
+          ["Package", "Path", "Status", "Errors", "Warnings"],
+        )
+      : "_No plugin roots discovered._",
+  ].join("\n");
+}
+
+async function runWithConcurrency(items, concurrency, worker) {
+  let index = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (index < items.length) {
+      const item = items[index];
+      index += 1;
+      await worker(item);
+    }
+  });
+  await Promise.all(runners);
+}
+
+async function isPluginRoot(dir) {
+  if (existsSync(path.join(dir, "plugin-inspector.config.json"))) return true;
+  if (existsSync(path.join(dir, ".plugin-inspector.json"))) return true;
+  if (existsSync(path.join(dir, "openclaw.plugin.json"))) return true;
+  const packageJsonPath = path.join(dir, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return Boolean(packageJson.openclaw || packageJson.pluginInspector || packageJson["plugin-inspector"]);
+  } catch {
+    return false;
+  }
+}
+
+function packageNameFromReport(report) {
+  return (
+    report.fixtures?.[0]?.package?.packageJson?.name ??
+    report.fixtures?.[0]?.package?.name ??
+    report.fixtures?.[0]?.name ??
+    report.fixtures?.[0]?.id ??
+    "plugin"
+  );
+}
+
+function slugForPath(value) {
+  return (
+    String(value)
+      .replaceAll(path.sep, "-")
+      .replace(/[^a-zA-Z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "plugin"
+  );
+}

package/src/cli.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import {
   loadPluginConfig,
   renderTextSummary,
+  runBatchAnalysis,
   sanitizeReportArtifact,
   runPluginCheck,
 } from "./index.js";
@@ -43,6 +44,8 @@ try {
     }
   } else if (command === "ci") {
     await runCi(commandArgs);
+  } else if (command === "batch") {
+    await runBatch(commandArgs);
   } else if (command === "capture") {
     await runCapture(commandArgs);
   } else {
@@ -53,6 +56,38 @@ try {
   process.exitCode = 1;
 }
 
+async function runBatch(commandArgs) {
+  const inputDir = readFirstPositional(commandArgs, new Set(["--out", "--openclaw", "--concurrency"]));
+  const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
+  const concurrency = Number(readFlag(commandArgs, "--concurrency") ?? "4");
+  const json = commandArgs.includes("--json");
+  const check = commandArgs.includes("--check");
+  const keepPluginReports = commandArgs.includes("--keep-plugin-reports");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
+  if (!inputDir) {
+    throw new Error("batch requires a folder of plugin roots");
+  }
+  const { report, paths } = await runBatchAnalysis({
+    rootDir: inputDir,
+    outDir,
+    openclawPath,
+    concurrency,
+    authorFacing,
+    keepPluginReports,
+  });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderBatchTextSummary(report, paths));
+  }
+
+  if (check && report.summary.pluginsWithErrors > 0) {
+    throw new Error(`plugin-inspector batch found ${report.summary.pluginsWithErrors} plugin(s) with errors`);
+  }
+}
+
 async function runConfig(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
@@ -75,8 +110,10 @@ async function runCheck(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs);
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, paths } = await runPluginCheck({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
     mockSdk,
@@ -131,12 +168,18 @@ async function runInit(commandArgs) {
 async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
   const ciOutputs = readCiOutputFlags(commandArgs);
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const config = await loadInspectorConfig(configPath);
-  const report = await inspectFixtureSet(config);
-  const paths = await writeReport(report, { outDir });
+  const report = authorFacing
+    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath })
+    : await inspectFixtureSet(config);
+  const paths = authorFacing
+    ? await writeCompatibilityReport(report, { cwd: config.rootDir, outDir })
+    : await writeReport(report, { outDir });
   await writeCiOutputArtifacts(report, {
     ...ciOutputs,
     cwd: path.dirname(paths.jsonPath),
@@ -164,8 +207,10 @@ async function runCi(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, reportDir } = await runCiCompatibilityReport({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
     mockSdk,
@@ -204,10 +249,19 @@ async function runCi(commandArgs) {
   }
 }
 
-async function runCiCompatibilityReport({ allowExecution, capture, configPath, mockSdk, openclawPath, outDir, pluginRoot }) {
+async function runCiCompatibilityReport({
+  allowExecution,
+  authorFacing,
+  capture,
+  configPath,
+  mockSdk,
+  openclawPath,
+  outDir,
+  pluginRoot,
+}) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -215,7 +269,15 @@ async function runCiCompatibilityReport({ allowExecution, capture, configPath, m
     };
   }
 
-  const { report } = await runPluginCheck({ allowExecution, capture, mockSdk, openclawPath, outDir, pluginRoot });
+  const { report } = await runPluginCheck({
+    allowExecution,
+    authorFacing,
+    capture,
+    mockSdk,
+    openclawPath,
+    outDir,
+    pluginRoot,
+  });
   return {
     report,
     reportDir: path.resolve(pluginRoot ?? process.cwd(), outDir),
@@ -317,6 +379,15 @@ function readAllowExecutionFlag(commandArgs) {
   return commandArgs.includes("--allow-execute");
 }
 
+function readAuthorFacingFlag(commandArgs) {
+  if (commandArgs.includes("--include-inspector-gaps")) {
+    throw new Error(
+      "--include-inspector-gaps has been replaced by --author-facing; default output now includes internal findings.",
+    );
+  }
+  return commandArgs.includes("--author-facing");
+}
+
 function renderCiTextSummary(summary) {
   return [
     `Status: ${summary.status.toUpperCase()}`,
@@ -326,6 +397,34 @@ function renderCiTextSummary(summary) {
   ].join("\n");
 }
 
+function renderBatchTextSummary(report, paths) {
+  const lines = [
+    "Plugin Inspector Batch",
+    `Plugins: ${report.summary.pluginCount}`,
+    `Plugins with errors: ${report.summary.pluginsWithErrors}`,
+    `Plugins with warnings: ${report.summary.pluginsWithWarnings}`,
+    `Finding codes: ${report.summary.findingCodeCount}`,
+    "",
+    "Reports:",
+    `- JSON: ${paths.jsonPath}`,
+    `- Markdown: ${paths.markdownPath}`,
+  ];
+  const topFinding = report.findingFrequency[0];
+  if (topFinding) {
+    lines.push("", `Top finding: ${topFinding.code} (${topFinding.plugins} plugin(s))`);
+  }
+  return lines.join("\n");
+}
+
+function readFirstPositional(args, valueFlags = new Set()) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("-")) return arg;
+    if (valueFlags.has(arg)) index += 1;
+  }
+  return undefined;
+}
+
 function initCommandSummary(result) {
   return {
     dryRun: result.dryRun,
@@ -353,16 +452,18 @@ function printHelp() {
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
   plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
-  plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
   plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.
 CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
 Runtime capture is opt-in because it imports plugin code; use --runtime with --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
+Default output includes author-facing and internal findings; pass --author-facing to show only findings with author remediation docs.
 `);
 }

package/src/compatibility-report.js

@@ -250,10 +250,23 @@ function issueBlock(issue, options) {
     `  - state: ${issueState(issue)}`,
     "  - evidence:",
     ...evidenceList(issue.evidence, options).map((item) => `    - ${item}`),
+    ...remediationList(issue),
     ...runtimeCoverageList(issue, options),
   ].join("\n");
 }
 
+function remediationList(issue) {
+  const remediation = issue.authorRemediation;
+  if (!remediation?.summary) {
+    return [];
+  }
+  return [
+    "  - author remediation:",
+    `    - ${remediation.summary}`,
+    `    - docs: ${remediation.docsUrl}`,
+  ];
+}
+
 function issueState(issue) {
   const flags = [
     issue.status,

package/src/index.js

@@ -17,6 +17,7 @@ import * as runtimeReconciliationApi from "./runtime-reconciliation.js";
 import * as syntheticEntrypointApi from "./synthetic-entrypoint.js";
 import * as syntheticProbeSuiteApi from "./synthetic-probe-suite.js";
 import * as syntheticProbesApi from "./synthetic-probes.js";
+import * as batchApi from "./batch.js";
 
 export const pluginRoot = Object.freeze({
   loadConfig: pluginApi.loadPluginConfig,
@@ -26,6 +27,12 @@ export const pluginRoot = Object.freeze({
   setup: pluginApi.setupPluginInspector,
 });
 
+export const batch = Object.freeze({
+  discoverPluginRoots: batchApi.discoverPluginRoots,
+  run: batchApi.runBatchAnalysis,
+  writeReport: batchApi.writeBatchReport,
+});
+
 export const fixtureSuites = Object.freeze({
   loadConfig: configApi.loadInspectorConfig,
   inspect: pluginApi.inspectCompatibilityFixtureSetConfig,
@@ -131,6 +138,11 @@ export const synthetic = Object.freeze({
   defaultRegistrationArguments: syntheticProbesApi.defaultSyntheticRegistrationArguments,
 });
 
+export {
+  discoverPluginRoots,
+  runBatchAnalysis,
+  writeBatchReport,
+} from "./batch.js";
 export {
   capturePluginEntrypoint,
   buildFixtureSetColdImportReadiness,
@@ -205,7 +217,7 @@ export {
   validateImportLoopProfile,
   writeImportLoopProfile,
 } from "./import-loop-profile.js";
-export { classifyIssueFinding, issueId, knownIssueCodes } from "./issues.js";
+export { classifyIssueFinding, issueId, isAuthorFacingFinding, knownIssueCodes } from "./issues.js";
 export { inspectFixtureSet, inspectPlugin, inspectSourceText } from "./inspector.js";
 export { openClawTargetPathCandidates, readOpenClawTargetSurface } from "./openclaw-target.js";
 export {

package/src/inspector.js

@@ -35,6 +35,7 @@ export async function inspectCompatibilityFixtureSet(config, options = {}) {
     config,
     inspections,
     failures,
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     executionResults: options.executionResults,
     targetOpenClaw,

package/src/issues.js

@@ -45,6 +45,12 @@ export const knownIssueCodes = new Set([
   "unrecognized-security-manifest",
 ]);
 
+const authorRemediationDocsUrl = (code) => `https://docs.openclaw.ai/clawhub/plugin-validation-fixes#${code}`;
+
+const authorRemediation = (summary) => ({ summary });
+
+const migrationRemediation = authorRemediation;
+
 export const issueMetadataByCode = {
   "before-tool-call-probe": {
     severity: "P1",
@@ -63,6 +69,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "channelEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy channel environment variable metadata into the current setup/config metadata while keeping the old field until your supported OpenClaw range no longer needs it.",
+      [
+        "Mirror each channel environment variable into the current setup or provider configuration metadata.",
+        "Keep channelEnvVars only as backwards compatibility for older OpenClaw versions you still support.",
+      ],
+    ),
   },
   "conversation-access-hook": {
     severity: "P1",
@@ -75,12 +88,27 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "legacy before_agent_start hook compatibility is still used",
+    authorRemediation: migrationRemediation(
+      "Replace the legacy before_agent_start hook with the current prompt/model hooks.",
+      [
+        "Move model-selection work to before_model_resolve when possible.",
+        "Move prompt mutation work to before_prompt_build.",
+        "Keep before_agent_start only if your declared compatibility range still includes OpenClaw versions that require it.",
+      ],
+    ),
   },
   "legacy-root-sdk-import": {
     severity: "P2",
     owner: "core",
     decision: "core-compat-adapter",
     title: "root plugin SDK barrel is still used by fixtures",
+    authorRemediation: migrationRemediation(
+      "Prefer focused public plugin SDK subpath imports instead of the legacy root barrel.",
+      [
+        "Replace imports from openclaw/plugin-sdk with the documented subpath for the API you use.",
+        "Keep the root import only while supporting older OpenClaw versions that do not expose the subpath.",
+      ],
+    ),
   },
   "sdk-export-missing": {
     severity: "P1",
@@ -93,12 +121,26 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin imports reserved bundled-plugin SDK compatibility subpaths",
+    authorRemediation: authorRemediation(
+      "Stop importing reserved bundled-plugin SDK compatibility paths.",
+      [
+        "Replace reserved OpenClaw internal SDK imports with documented public openclaw/plugin-sdk subpaths.",
+        "If no public API exists for the behavior, vendor a plugin-local helper or request a public OpenClaw API.",
+      ],
+    ),
   },
   "security-manifest-schema-unavailable": {
     severity: "P3",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin security manifest references an unavailable schema",
+    authorRemediation: authorRemediation(
+      "Remove or update the unsupported security manifest schema reference.",
+      [
+        "Delete the schema URL from openclaw.security.json if it is advisory-only.",
+        "Use a documented versioned schema once OpenClaw publishes one.",
+      ],
+    ),
   },
   "missing-compat-record": {
     severity: "P1",
@@ -117,18 +159,37 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest display name is missing",
+    authorRemediation: authorRemediation(
+      "Add a display name to the plugin manifest.",
+      ["Set a non-empty name field in openclaw.plugin.json."],
+      '{\n  "name": "My Plugin"\n}',
+    ),
   },
   "manifest-unknown-contracts": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest declares unsupported contract keys",
+    authorRemediation: authorRemediation(
+      "Remove unsupported manifest contract keys or move them to a documented OpenClaw contract field.",
+      [
+        "Compare the contracts object to the OpenClaw manifest fields supported by your target version.",
+        "Delete custom contract keys unless OpenClaw has a versioned schema for them.",
+      ],
+    ),
   },
   "manifest-unknown-fields": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest uses unsupported top-level fields",
+    authorRemediation: authorRemediation(
+      "Move unsupported top-level manifest fields into supported package metadata or remove them.",
+      [
+        "Keep openclaw.plugin.json limited to fields supported by the target OpenClaw manifest schema.",
+        "Move package-level metadata into package.json openclaw metadata when that field is supported.",
+      ],
+    ),
   },
   "package-build-artifact-entrypoint": {
     severity: "P2",
@@ -147,72 +208,159 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint is missing",
+    authorRemediation: authorRemediation(
+      "Publish the entrypoint declared in OpenClaw package metadata or update the metadata to point at an existing file.",
+      [
+        "Check package.json openclaw.extensions and openclaw.runtimeExtensions.",
+        "Ensure the referenced file exists in the published artifact, usually under dist/ after build.",
+      ],
+    ),
   },
   "package-install-metadata-incomplete": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package install metadata is incomplete",
+    authorRemediation: authorRemediation(
+      "Complete the OpenClaw install metadata so ClawHub can identify the install target.",
+      [
+        "Fill package.json openclaw.install with the supported release target.",
+        "Align clawhubSpec, npmSpec, and defaultChoice with the package you publish.",
+      ],
+    ),
   },
   "package-json-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add a package.json to the plugin package.",
+      [
+        "Include the package name and version.",
+        "Add an openclaw metadata block describing extensions, compatibility, and install details.",
+      ],
+    ),
   },
   "package-manifest-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package and manifest versions drift",
+    authorRemediation: authorRemediation(
+      "Align the plugin version declared in package.json and openclaw.plugin.json.",
+      [
+        "Use the same version in both files, or remove stale manifest version metadata if package.json is authoritative.",
+        "Republish with a new package version after changing published metadata.",
+      ],
+    ),
   },
   "package-min-host-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package minimum host version drifts from build target",
+    authorRemediation: authorRemediation(
+      "Set the package minimum host version to the OpenClaw version range the plugin was built and tested against.",
+      [
+        "Update package.json openclaw.install.minHostVersion or compatibility metadata.",
+        "Keep it semver-compatible with the target OpenClaw build version.",
+      ],
+    ),
   },
   "package-npm-pack-entrypoint-missing": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw entrypoints",
+    authorRemediation: authorRemediation(
+      "Include the declared OpenClaw entrypoints in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect the tarball contents.",
+        "Update package.json files so dist files and manifests are included.",
+        "Build before packing if the entrypoint is generated.",
+      ],
+    ),
   },
   "package-npm-pack-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Include OpenClaw metadata files in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect package.json and OpenClaw manifest files.",
+        "Update package.json files so required metadata is not excluded.",
+      ],
+    ),
   },
   "package-npm-pack-unavailable": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact cannot be packed",
+    authorRemediation: authorRemediation(
+      "Make the package packable before publishing it through ClawHub.",
+      [
+        "Remove private:true if this package is intended to publish.",
+        "Ensure package.json has a valid name and version.",
+        "Fix package scripts or files entries that make npm pack fail.",
+      ],
+    ),
   },
   "package-openclaw-entry-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint metadata is missing",
+    authorRemediation: authorRemediation(
+      "Declare the plugin runtime entrypoint in package.json OpenClaw metadata.",
+      [
+        "Add openclaw.extensions for extension entrypoints.",
+        "Add openclaw.runtimeExtensions when the plugin has runtime-side code.",
+      ],
+    ),
   },
   "package-openclaw-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add the package.json openclaw metadata block.",
+      [
+        "Describe extension entrypoints, plugin API compatibility, and install metadata.",
+        "Keep package metadata in sync with openclaw.plugin.json when both files are present.",
+      ],
+    ),
   },
   "package-openclaw-unsupported-metadata": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package declares unsupported OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Remove unsupported OpenClaw package metadata fields.",
+      [
+        "Delete openclaw.bundle and other fields not accepted by the current package schema.",
+        "Move bundle-specific data to documented manifest fields when available.",
+      ],
+    ),
   },
   "package-plugin-api-compat-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin API compatibility range is missing",
+    authorRemediation: authorRemediation(
+      "Declare the OpenClaw plugin API range this package supports.",
+      [
+        "Add package.json `openclaw.compat.pluginApi` with the OpenClaw plugin API range you tested.",
+        "If known, include the OpenClaw build/version used to produce the package metadata.",
+      ],
+      '"openclaw": {\n  "compat": {\n    "pluginApi": ">=0.1.0"\n  }\n}',
+    ),
   },
   "package-typescript-source-entrypoint": {
     severity: "P2",
@@ -225,6 +373,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "providerAuthEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy provider authentication environment variables into current provider setup metadata.",
+      [
+        "Mirror providerAuthEnvVars into setup.providers[].envVars or the current provider-choice metadata.",
+        "Keep the legacy field only while supporting older OpenClaw versions that still read it.",
+      ],
+    ),
   },
   "registration-capture-gap": {
     severity: "P2",
@@ -255,6 +410,13 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin ships an unsupported security manifest",
+    authorRemediation: authorRemediation(
+      "Remove unsupported security manifest files until OpenClaw documents a versioned security manifest schema.",
+      [
+        "Delete openclaw.security.json if it is advisory-only and not consumed by OpenClaw.",
+        "Reintroduce it only when the schema and ClawHub behavior are documented.",
+      ],
+    ),
   },
 };
 
@@ -284,6 +446,14 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       evidence: finding.evidence ?? [],
       compatRecord: finding.compatRecord ?? null,
       runtimeCoverage: finding.runtimeCoverage ?? null,
+      ...(finding.authorRemediation
+        ? {
+            authorRemediation: {
+              summary: finding.authorRemediation.summary,
+              docsUrl: authorRemediationDocsUrl(finding.code),
+            },
+          }
+        : {}),
     }));
 }
 
@@ -305,9 +475,18 @@ export function issueMetadata(finding, targetOpenClaw) {
     decision: "inspector-follow-up",
     title: finding.message,
   };
+  const authorMetadata = metadata.authorRemediation
+    ? {
+        authorRemediation: {
+          summary: metadata.authorRemediation.summary,
+          docsUrl: authorRemediationDocsUrl(finding.code),
+        },
+      }
+    : {};
   return {
     ...finding,
     ...metadata,
+    ...authorMetadata,
     ...classifyIssueFinding(finding, targetOpenClaw, metadata),
   };
 }
@@ -333,6 +512,14 @@ export function classifyIssueFinding(finding, targetOpenClaw, metadata = {}) {
   };
 }
 
+export function isInspectorGapFinding(finding, targetOpenClaw) {
+  return issueMetadata(finding, targetOpenClaw).issueClass === "inspector-gap";
+}
+
+export function isAuthorFacingFinding(finding, targetOpenClaw) {
+  return Boolean(issueMetadata(finding, targetOpenClaw).authorRemediation);
+}
+
 export function summarizeIssueClasses(issues) {
   const summary = {
     "compat-gap": 0,

package/src/report.js

@@ -3,7 +3,7 @@ import { renderMarkdownTable, writeArtifacts, writeJsonMarkdownArtifacts } from
 import { renderCompatibilityIssuesReport, renderCompatibilityMarkdownReport } from "./compatibility-report.js";
 import { buildContractProbes } from "./contract-probes.js";
 import { classifyCompatibilityFixture } from "./fixture-summary.js";
-import { buildIssues, summarizeIssueClasses } from "./issues.js";
+import { buildIssues, isAuthorFacingFinding, summarizeIssueClasses } from "./issues.js";
 import { sanitizeReportArtifact } from "./report-sanitizer.js";
 import { applyRuntimeExecutionCoverage } from "./runtime-reconciliation.js";
 
@@ -141,18 +141,26 @@ export async function buildCompatibilityReport(options = {}) {
     decisions,
   });
 
+  const visibleBreakages = filterVisibleFindings(breakages, targetOpenClaw, options);
+  const visibleWarnings = filterVisibleFindings(warnings, targetOpenClaw, options);
+  const visibleSuggestions = filterVisibleFindings(suggestions, targetOpenClaw, options);
+  const visibleDecisions = options.authorFacing === true ? [] : decisions;
   const runtimeCoverage = applyRuntimeExecutionCoverage({
-    findings: [...warnings, ...suggestions],
+    findings: [...visibleWarnings, ...visibleSuggestions],
     executionResults: options.executionResults,
   });
   const issues = buildIssues({
-    breakages,
-    warnings,
-    suggestions,
+    breakages: visibleBreakages,
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
     targetOpenClaw,
     idPrefix: options.issueIdPrefix,
   });
-  const contractProbes = buildContractProbes({ warnings, suggestions, fixtures: fixtureReports });
+  const contractProbes = buildContractProbes({
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
+    fixtures: fixtureReports,
+  });
   const issueSummary = summarizeIssueClasses(issues);
   const openIssues = issues.filter((issue) => issue.status !== "runtime-covered");
   const openIssueSummary = summarizeIssueClasses(openIssues);
@@ -160,14 +168,14 @@ export async function buildCompatibilityReport(options = {}) {
   return {
     generatedAt: options.generatedAt ?? "deterministic",
     targetOpenClaw,
-    status: breakages.length === 0 ? "pass" : "fail",
+    status: visibleBreakages.length === 0 ? "pass" : "fail",
     summary: {
       fixtureCount: fixtureReports.length,
       highPriorityFixtures: fixtureReports.filter((fixture) => fixture.priority === "high").length,
-      breakageCount: breakages.length,
-      warningCount: warnings.length,
-      suggestionCount: suggestions.length,
-      decisionCount: decisions.length,
+      breakageCount: visibleBreakages.length,
+      warningCount: visibleWarnings.length,
+      suggestionCount: visibleSuggestions.length,
+      decisionCount: visibleDecisions.length,
       logCount: logs.length,
       issueCount: issues.length,
       openIssueCount: openIssues.length,
@@ -189,16 +197,23 @@ export async function buildCompatibilityReport(options = {}) {
       contractProbeCount: contractProbes.length,
     },
     fixtures: fixtureReports,
-    breakages,
-    warnings,
-    suggestions,
+    breakages: visibleBreakages,
+    warnings: visibleWarnings,
+    suggestions: visibleSuggestions,
     issues,
     contractProbes,
     logs,
-    decisions,
+    decisions: visibleDecisions,
   };
 }
 
+function filterVisibleFindings(findings, targetOpenClaw, options) {
+  if (options.authorFacing !== true) {
+    return findings;
+  }
+  return findings.filter((finding) => isAuthorFacingFinding(finding, targetOpenClaw));
+}
+
 export function classifyCompatRecordCoverage({ targetOpenClaw, findings, suggestions, logs, decisions }) {
   if (targetOpenClaw.status !== "ok") {
     logs.push({

package/src/sdk-mock.js

@@ -671,6 +671,24 @@ function resolveExistingSourcePath(target) {
 ` : ""}
 function createMockValue(name) {
   function fn(...args) {
+    if (name === "resolveDefaultAgentDir") {
+      return mockAgentDir();
+    }
+    if (name === "resolveAgentDir") {
+      return mockAgentDir(args[1]);
+    }
+    if (name === "resolveUserPath") {
+      return typeof args[0] === "string" ? args[0] : mockAgentDir();
+    }
+    if (name === "resolveAuthProfileOrder") {
+      return [];
+    }
+    if (name === "resolveWindowsSpawnProgram") {
+      return mockWindowsSpawnProgram(args[0]);
+    }
+    if (name === "materializeWindowsSpawnProgram") {
+      return mockWindowsSpawnInvocation(args[0], args[1]);
+    }
     if (name === "resolvePreferredOpenClawTmpDir") {
       return process.env.TMPDIR || "/tmp";
     }
@@ -707,6 +725,80 @@ function createMockValue(name) {
   });
 }
 
+function mockAgentDir(agentId = "main") {
+  const base = process.env.TMPDIR || process.env.TEMP || process.env.TMP || "/tmp";
+  const safeAgentId = String(agentId || "main").replace(/[^a-zA-Z0-9._-]/g, "-");
+  return base.replace(/[\\/]+$/, "") + "/plugin-inspector-openclaw/agents/" + safeAgentId + "/agent";
+}
+
+function mockWindowsSpawnProgram(params = {}) {
+  return {
+    command: typeof params.command === "string" && params.command.trim() ? params.command : process.execPath,
+    leadingArgv: [],
+    resolution: "mock",
+    packageName: typeof params.packageName === "string" ? params.packageName : undefined,
+  };
+}
+
+function mockWindowsSpawnInvocation(program = {}, argv = []) {
+  const command = typeof program.command === "string" && program.command.trim() ? program.command : process.execPath;
+  if (program.packageName === "@openai/codex") {
+    return {
+      command: process.execPath,
+      argv: ["-e", mockCodexAppServerScript()],
+      resolution: program.resolution ?? "mock",
+      windowsHide: true,
+    };
+  }
+  return {
+    command,
+    argv: [...(Array.isArray(program.leadingArgv) ? program.leadingArgv : []), ...(Array.isArray(argv) ? argv : [])],
+    resolution: program.resolution ?? "mock",
+    shell: program.shell,
+    windowsHide: program.windowsHide,
+  };
+}
+
+function mockCodexAppServerScript() {
+  return [
+    "const readline = require('node:readline');",
+    "const rl = readline.createInterface({ input: process.stdin });",
+    "let idleTimer;",
+    "function scheduleIdleExit() {",
+    "  if (idleTimer) clearTimeout(idleTimer);",
+    "  idleTimer = setTimeout(() => process.exit(0), 1000);",
+    "}",
+    "function write(id, result) { process.stdout.write(JSON.stringify({ id, result }) + String.fromCharCode(10)); }",
+    "rl.on('line', (line) => {",
+    "  let message;",
+    "  try { message = JSON.parse(line); } catch { return; }",
+    "  if (message.id === undefined || message.id === null) return;",
+    "  switch (message.method) {",
+    "    case 'initialize':",
+    "      write(message.id, { userAgent: 'openclaw/999.0.0 (plugin-inspector mock)' });",
+    "      break;",
+    "    case 'model/list':",
+    "      write(message.id, { data: [] });",
+    "      break;",
+    "    case 'thread/list':",
+    "    case 'mcpServerStatus/list':",
+    "    case 'skills/list':",
+    "      write(message.id, { data: [] });",
+    "      break;",
+    "    case 'account/read':",
+    "      write(message.id, null);",
+    "      break;",
+    "    case 'account/rateLimits/read':",
+    "      write(message.id, null);",
+    "      break;",
+    "    default:",
+    "      process.stdout.write(JSON.stringify({ id: message.id, error: { code: -32601, message: 'mock method not implemented' } }) + String.fromCharCode(10));",
+    "  }",
+    "  scheduleIdleExit();",
+    "});",
+  ].join("\\n");
+}
+
 function createZNamespace() {
   const namespace = {
     any: () => createSchema(),