fix(plugins): explain source-only package diagnostics (#77835) (#77842)

CHANGELOG.md

@@ -92,6 +92,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Plugins/diagnostics: make source-only TypeScript package warnings actionable by explaining that missing compiled runtime output is a publisher packaging issue and pointing users to update/reinstall or disable/uninstall the plugin. Fixes #77835. Thanks @googlerest.
 - TUI: skip the generic CLI respawn wrapper for interactive launches, exit cleanly on terminal loss, and refuse to restore heartbeat sessions as the remembered chat session, preventing stale heartbeat history and orphaned `openclaw-tui` processes on first boot. Thanks @vincentkoc.
 - Doctor/sessions: move heartbeat-poisoned default main session store entries to recovery keys and clear stale TUI restore pointers, so `doctor --fix` can repair instances already stuck on `agent:main:main` heartbeat history. Thanks @vincentkoc.
 - Agents/context engines: keep hidden OpenClaw runtime-context custom messages out of context-engine assemble, afterTurn, and ingest hooks so transcript reconstruction plugins only see conversation messages. Thanks @vincentkoc.

docs/channels/wechat.md

@@ -149,6 +149,11 @@ openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
 openclaw gateway restart
 ```
 
+If startup reports that the installed plugin package `requires compiled runtime
+output for TypeScript entry`, the npm package was published without the compiled
+JavaScript runtime files OpenClaw needs. Update/reinstall after the plugin
+publisher ships a fixed package, or temporarily disable/uninstall the plugin.
+
 Temporary disable:
 
 ```bash

docs/tools/plugin.md

@@ -164,6 +164,12 @@ Packaged installs must ship that JavaScript runtime output. The TypeScript
 source fallback is for source checkouts and local development paths, not for
 npm packages installed into OpenClaw's managed plugin root.
 
+If a managed package warning says it `requires compiled runtime output for
+TypeScript entry ...`, the package was published without the JavaScript files
+OpenClaw needs at runtime. That is a plugin packaging issue, not a local config
+problem. Update or reinstall the plugin after the publisher republishes compiled
+JavaScript, or disable/uninstall that plugin until a fixed package is available.
+
 Use `openclaw.runtimeExtensions` when published runtime files do not live at the
 same paths as the source entries. When present, `runtimeExtensions` must contain
 exactly one entry for every `extensions` entry. Mismatched lists fail install and

src/cli/plugins-install-config.test.ts

@@ -163,7 +163,7 @@ describe("loadConfigForInstall", () => {
           {
             path: "plugins",
             message:
-              "plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs",
+              "plugin: installed plugin package requires compiled runtime output for TypeScript entry index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, index.js, index.mjs, index.cjs. This is a plugin packaging issue, not a local config problem; update or reinstall the plugin after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then. TypeScript source fallback is only supported for source checkouts and local development paths.",
           },
         ],
       }),

src/plugins/discovery.test.ts

@@ -769,7 +769,9 @@ describe("discoverOpenClawPlugins", () => {
           entry.level === "warn" &&
           entry.pluginId === "source-only-pack" &&
           entry.message.includes("requires compiled runtime output") &&
-          entry.message.includes("./dist/index.js"),
+          entry.message.includes("./dist/index.js") &&
+          entry.message.includes("plugin packaging issue") &&
+          entry.message.includes("disable/uninstall the plugin"),
       ),
     ).toBe(true);
   });

src/plugins/install.test.ts

@@ -949,6 +949,8 @@ describe("installPluginFromArchive", () => {
       expect(result.code).toBe(PLUGIN_INSTALL_ERROR_CODE.INVALID_OPENCLAW_EXTENSIONS);
       expect(result.error).toContain("requires compiled runtime output");
       expect(result.error).toContain("./dist/index.js");
+      expect(result.error).toContain("plugin packaging issue");
+      expect(result.error).toContain("disable/uninstall the plugin");
     }
   });
 

src/plugins/package-entry-resolution.ts

@@ -87,7 +87,7 @@ function missingCompiledRuntimeEntryMessage(params: {
   entry: string;
   candidates: readonly string[];
 }): string {
-  return `${params.label} requires compiled runtime output for TypeScript entry ${params.entry}: expected ${params.candidates.join(", ")}`;
+  return `${params.label} requires compiled runtime output for TypeScript entry ${params.entry}: expected ${params.candidates.join(", ")}. This is a plugin packaging issue, not a local config problem; update or reinstall the plugin after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then. TypeScript source fallback is only supported for source checkouts and local development paths.`;
 }
 
 async function validatePackageExtensionEntry(params: {