PR #70138: fix(plugins): eagerly install bundled runtime deps

• Repository: openclaw/openclaw
• Author: ngutman
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/70138

Description (problem / solution / changelog)

Summary

• Problem: packaged installs could ship bundled channel/plugin entrypoints without their runtime dependencies installed, so bootstrap paths failed with Cannot find module ... before openclaw doctor --fix could help.
• Why it matters: fresh installs and updates could look successful while openclaw status, onboarding, or bundled channel entry loading immediately crashed.
• What changed: packaged postinstall now eagerly installs bundled plugin runtime dependencies by default, and packaged installs fail fast if that nested install fails.
• What did NOT change (scope boundary): source checkouts still skip eager bundled-runtime installation, and this PR does not change the config-recovery half of #70096.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #70008
• Closes #70093
• Closes #70099
• Related #70096
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: packaged installs excluded dist/extensions/*/node_modules/**, and normal postinstall runs skipped bundled runtime dependency installation unless an eager-install env var was set.
• Missing detection / guardrail: user installs did not fail when the nested install path failed, so packaged installs could silently continue with missing bundled runtime deps.
• Contributing context (if known): release-check already forces eager install under a dedicated env flag, which masked the mismatch between release validation and normal end-user installs.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • test/scripts/postinstall-bundled-plugins.test.ts
  • src/plugins/stage-bundled-plugin-runtime-deps.test.ts
• Scenario the test should lock in:
  • packaged installs eagerly install bundled runtime deps by default
  • packaged installs fail fast when that install step fails
  • explicit opt-out via OPENCLAW_EAGER_BUNDLED_PLUGIN_DEPS=0 still works
• Why this is the smallest reliable guardrail:
  • these tests exercise the actual postinstall decision boundary without needing a full publish/release lane.
• Existing test that already covers this (if any):
  • the packed install smoke and bundled channel entry smoke cover the installed layout verification path.
• If no new test is added, why not:
  • N/A

User-visible / Behavior Changes

• Fresh packaged installs and updates now install bundled plugin runtime deps by default.
• If that nested install fails, the packaged install now fails immediately with a clear postinstall error instead of warning and continuing into a broken runtime state.

Diagram (if applicable)

Before:
install package -> skip bundled runtime dep install by default -> bootstrap loads bundled entry -> Cannot find module

After:
install package -> install bundled runtime deps -> bundled entry loads successfully
               \-> install fails -> postinstall throws immediately

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (Yes)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:
  • Packaged install already runs postinstall. This change makes the bundled runtime dependency install path the default packaged-install behavior, using the existing npm runner and failing fast on errors instead of silently continuing.

Repro + Verification

Environment

• OS: macOS host verifying packaged tarball install
• Runtime/container: Node/npm packaged install smoke
• Model/provider: N/A
• Integration/channel (if any): bundled channel entry smoke (Feishu, Slack, Nostr, WhatsApp, Telegram, bundled diffs)
• Relevant config (redacted): none

Steps

1. pnpm test test/scripts/postinstall-bundled-plugins.test.ts src/plugins/stage-bundled-plugin-runtime-deps.test.ts
2. npm pack --ignore-scripts then npm install the tarball into a temp prefix
3. Verify bundled runtime dep sentinels exist and run node scripts/test-built-bundled-channel-entry-smoke.mjs --package-root <installed package root>

Expected

• packaged installs eagerly install bundled runtime deps
• packaged installs fail on nested bundled-runtime install failure
• bundled channel entry smoke passes from the installed layout

Actual

• targeted tests pass
• real packed-install smoke passes
• bundled channel entry smoke passes from the installed package root

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test test/scripts/postinstall-bundled-plugins.test.ts src/plugins/stage-bundled-plugin-runtime-deps.test.ts
  • packed tarball install now materializes bundled runtime dep sentinels for Feishu/Slack/Nostr/WhatsApp/Telegram/diffs deps
  • OPENCLAW_DISABLE_BUNDLED_ENTRY_SOURCE_FALLBACK=1 node scripts/test-built-bundled-channel-entry-smoke.mjs --package-root <installed package root> passes
• Edge cases checked:
  • explicit opt-out via OPENCLAW_EAGER_BUNDLED_PLUGIN_DEPS=0
  • packaged install failure path now throws with context instead of warning and continuing
• What you did not verify:
  • full pnpm check:changed is still blocked on unrelated existing tsgo:core:test failures in src/agents/pi-embedded-runner/*

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)
• If yes, exact upgrade steps:
  • OPENCLAW_EAGER_BUNDLED_PLUGIN_DEPS=0|false|off now explicitly disables the default eager packaged-install behavior.

Risks and Mitigations

• Risk: offline/air-gapped installs that cannot reach the registry now fail during packaged postinstall instead of appearing successful.
  • Mitigation: this is intentional fail-fast behavior because bundled entrypoints are expected to work immediately after install; silent success left users in a broken runtime state.

Changed files

• scripts/postinstall-bundled-plugins.mjs (modified, +103/-52)
• src/plugins/stage-bundled-plugin-runtime-deps.test.ts (modified, +130/-0)
• test/scripts/postinstall-bundled-plugins.test.ts (modified, +86/-3)