PR #77988: fix(matrix): declare bundled Matrix runtime deps on root package

• Repository: openclaw/openclaw
• Author: tmimmanuel
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77988

Description (problem / solution / changelog)

Summary

• Problem: After openclaw update on a host npm install (OpenClaw 2026.5.4), the bundled Matrix channel crash-loops with Cannot find package 'matrix-js-sdk' imported from .../openclaw/dist/logging-*.js. The root npm package ships Matrix runtime code in dist/ but the root package.json does not declare Matrix's runtime dependencies, and the published tarball excludes bundled node_modules while the postinstall script intentionally does not install plugin-local deps.
• Why it matters: Matrix accounts cannot start on host npm installs after every update until the user manually npm installs the missing deps inside the OpenClaw package root. The post-publish verifier currently allow-lists matrix-js-sdk and @matrix-org/matrix-sdk-crypto-nodejs, masking the regression.
• What changed: Root package.json now declares the five Matrix runtime deps (matrix-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, @matrix-org/matrix-sdk-crypto-wasm, fake-indexeddb, music-metadata); the post-publish verifier no longer treats matrix-js-sdk and @matrix-org/matrix-sdk-crypto-nodejs as optional/externalized; and the plugin-package contract guardrail asserts the new bundled-Matrix ownership (deps live in both the plugin manifest and the root manifest).
• What did NOT change (scope boundary): Matrix is still bundled into root (no !dist/extensions/matrix/** exclusion added). The plugin-local extensions/matrix/package.json still declares the same deps. No runtime/loader changes; no externalization; no other plugin's deps moved.

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 #77896
• Related #28370 (older openclaw update removed Matrix extension dependencies)
• Related #31231 (older bundled Matrix extension missing @vector-im/matrix-bot-sdk)
• Related #67936 (Docker 2026.04.15 Matrix channel failed resolving openclaw from bundled Matrix files)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Matrix is bundled into the published root tarball (no exclusion under !dist/extensions/matrix/**), but its runtime deps were declared only in extensions/matrix/package.json. The published tarball omits bundled node_modules and the postinstall script does not install plugin-local deps, so a fresh npm install openclaw or an openclaw update leaves the bundled Matrix entrypoint without a resolvable matrix-js-sdk. Other bundled channel plugins (Slack, Telegram) avoid the same trap because their runtime deps are already declared on the root manifest.
• Missing detection / guardrail: The post-publish verifier in scripts/openclaw-npm-postpublish-verify.ts listed matrix-js-sdk and @matrix-org/matrix-sdk-crypto-nodejs in OPTIONAL_OR_EXTERNALIZED_RUNTIME_IMPORTS, so an installed-package smoke that hit the missing import would skip those packages and stay green. The plugin-package contract guardrail also locked in the inverted invariant ("Matrix deps must be plugin-local only").
• Contributing context (if known): Matrix was kept in the root tarball (not externalized like Discord or WhatsApp), so the root manifest must own its runtime deps the same way it owns Slack and Telegram deps.

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: src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts (now requires bundled-Matrix deps to live in both manifests). scripts/openclaw-npm-postpublish-verify.ts no longer allow-lists Matrix imports.
• Scenario the test should lock in: After this change, a host npm install of openclaw resolves matrix-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, @matrix-org/matrix-sdk-crypto-wasm, fake-indexeddb, and music-metadata from the root package without re-running npm install inside the OpenClaw package root.
• Why this is the smallest reliable guardrail: Package-boundary contract checks already exist for plugin-local vs. root ownership; flipping the assertion direction for bundled Matrix matches the actual published surface and removes the masking allow-list in the post-publish gate.
• Existing test that already covers this (if any): pnpm deps:root-ownership:check accepts root-owned bundled-extension runtime deps.
• If no new test is added, why not: Reused the existing contract guardrail file rather than adding a parallel test.

User-visible / Behavior Changes

After this fix, host npm installs and openclaw update runs no longer leave the Matrix channel without matrix-js-sdk. No config changes; no runtime API changes; no public RPC changes. Five new entries appear in the published openclaw package's dependencies.

Diagram (if applicable)

Before:
  npm install openclaw -> dist/extensions/matrix/* present
                       -> root deps: { ..., markdown-it, typebox, ...}
                       -> matrix-js-sdk, @matrix-org/*, fake-indexeddb,
                          music-metadata: NOT declared
  openclaw start       -> import('matrix-js-sdk') -> ERR_MODULE_NOT_FOUND
                       -> Matrix accounts crash-loop

After:
  npm install openclaw -> dist/extensions/matrix/* present
                       -> root deps: { ..., [email protected],
                          @matrix-org/matrix-sdk-crypto-nodejs@^0.5.1,
                          @matrix-org/[email protected],
                          fake-indexeddb@^6.2.5, music-metadata@^11.12.3 }
  openclaw start       -> import('matrix-js-sdk') resolves
                       -> Matrix logs in normally

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (deps already used by the bundled plugin)
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Ubuntu workstation, Linux 6.8.0-110-generic
• Runtime/container: Node 22.22.0 via nvm, pnpm 10.33.2
• Model/provider: N/A (packaging change)
• Integration/channel (if any): Matrix
• Relevant config (redacted): N/A

Steps

1. Check out the branch on top of upstream/main.
2. Run pnpm install to refresh the lockfile with the new root deps.
3. Run the bot-prescribed acceptance tests: pnpm test test/release-check.test.ts src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts src/infra/tsdown-config.test.ts.
4. Run pnpm deps:root-ownership:check to confirm the new root deps classify as bundled-extension ownership.
5. Run pnpm build.
6. From the repo root, use node -p require.resolve(...) to confirm each new Matrix dep now resolves from the root node_modules, mirroring how npm install openclaw will resolve them on a host install.

Expected

• All three acceptance tests pass.
• deps:root-ownership:check reports ok.
• pnpm build exits 0.
• Each of the five Matrix deps resolves from the root install path.

Actual

• All three acceptance tests pass (15+9+release-check shards green).
• deps:root-ownership:check reports [root-dependency-ownership] ok.
• pnpm build exited 0.
• All five Matrix deps resolve from the root path (live node capture below).

Real behavior proof

• Behavior or issue addressed: Issue #77896 - host npm install of OpenClaw 2026.5.4 ships bundled Matrix runtime in dist/ but the root npm package does not declare matrix-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, @matrix-org/matrix-sdk-crypto-wasm, fake-indexeddb, or music-metadata, so after openclaw update the Matrix channel crash-loops with Cannot find package 'matrix-js-sdk' imported from .../openclaw/dist/logging-*.js.

• Real environment tested: Ubuntu 24.04 workstation, Node 22.22.0, pnpm 10.33.2, branch fix/77896-matrix-runtime-deps at head f2b3e9a311, freshly bootstrapped via pnpm install --config.minimumReleaseAge=0 (workspace minimumReleaseAge policy unrelated to this PR; the minimumReleaseAge=0 flag was needed only because an unrelated upstream package @zed-industries/codex-acp-win32-arm64 was published 42 hours ago).

• Exact steps or command run after this patch:

  1. Checked out the branch on top of upstream/main and confirmed the head SHA via git rev-parse HEAD.
  2. Refreshed the lockfile with pnpm install (installed the five new Matrix deps; lockfile diff shows only those entries added).
  3. Ran node -p require.resolve(...) for each of the five new Matrix runtime deps from the repo root to confirm they resolve from the root node_modules, matching how npm install openclaw resolves bundled-package imports on a host install.
  4. Ran node against the actual root package.json to print the declared specifier for each new Matrix dep, confirming the published manifest will carry them when the next release tarball is built.

• Evidence after fix:

  Live console output captured at branch head f2b3e9a311 (real node invocations against the working tree, not lint/test gates):

  $ git rev-parse HEAD
  f2b3e9a311c0bbecbcb0e1bdf3220e1a6e4c5f88
  
  $ node -e "console.log('matrix-js-sdk -> ' + require.resolve('matrix-js-sdk'))"
  matrix-js-sdk -> /home/ubuntu/projects/tmimmanuel/openclaw/node_modules/matrix-js-sdk/lib/index.js
  
  $ node -e "console.log('matrix-sdk-crypto-nodejs -> ' + require.resolve('@matrix-org/matrix-sdk-crypto-nodejs'))"
  matrix-sdk-crypto-nodejs -> /home/ubuntu/projects/tmimmanuel/openclaw/node_modules/@matrix-org/matrix-sdk-crypto-nodejs/index.js
  
  $ node -e "console.log('matrix-sdk-crypto-wasm -> ' + require.resolve('@matrix-org/matrix-sdk-crypto-wasm'))"
  matrix-sdk-crypto-wasm -> /home/ubuntu/projects/tmimmanuel/openclaw/node_modules/@matrix-org/matrix-sdk-crypto-wasm/node.cjs
  
  $ node -e "console.log('fake-indexeddb -> ' + require.resolve('fake-indexeddb'))"
  fake-indexeddb -> /home/ubuntu/projects/tmimmanuel/openclaw/node_modules/fake-indexeddb/build/cjs/index.js
  
  $ node -e "console.log('music-metadata -> ' + require.resolve('music-metadata'))"
  music-metadata -> /home/ubuntu/projects/tmimmanuel/openclaw/node_modules/music-metadata/lib/index.js
  
  $ node -e "
  const fs = require('fs');
  const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
  const required = ['@matrix-org/matrix-sdk-crypto-nodejs', '@matrix-org/matrix-sdk-crypto-wasm', 'fake-indexeddb', 'matrix-js-sdk', 'music-metadata'];
  for (const dep of required) {
    console.log(dep + ' -> ' + (p.dependencies?.[dep] ?? '<MISSING>'));
  }
  "
  @matrix-org/matrix-sdk-crypto-nodejs -> ^0.5.1
  @matrix-org/matrix-sdk-crypto-wasm -> 18.2.0
  fake-indexeddb -> ^6.2.5
  matrix-js-sdk -> 41.4.0
  music-metadata -> ^11.12.3

• Observed result after fix: The five Matrix runtime packages reported missing in the issue's ERR_MODULE_NOT_FOUND reproduction (matrix-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, @matrix-org/matrix-sdk-crypto-wasm, plus the plugin-local fake-indexeddb and music-metadata) all resolve from the root install path that a host npm install openclaw would populate. The root package.json carries them at the same versions the bundled Matrix plugin manifest already pins, so the lockfile and published tarball stay aligned. With the post-publish verifier no longer allow-listing matrix-js-sdk and @matrix-org/matrix-sdk-crypto-nodejs, a future regression that drops them from root deps will fail the gate.

• What was not tested: A live macOS host npm install openclaw followed by openclaw update and a real Matrix homeserver login (the issue's exact reproduction). Docker image variants (#67936 was a separate Docker-only Matrix packaging regression). The Sparkle/Mintlify release-publish path, which a maintainer-owned release run will exercise via the postpublish verifier on the next 2026.5.5 tarball.

Evidence

• Failing test/log before + passing after - plugin-sdk-package-contract-guardrails.test.ts > "keeps Matrix dependencies local to the Matrix plugin" was the prior assertion; the test now reads "declares Matrix runtime dependencies in both the Matrix plugin and the root package" and passes against the new manifest.
• Trace/log snippets - included above (live node resolution and package.json audit).
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • Each of the five Matrix runtime packages resolves from the root node_modules via node's default resolver, matching what a host npm install openclaw will populate after this lands.
  • The root package.json declares the five deps at the same versions as the plugin-local manifest, so the lockfile reconciles without drift.
  • The postpublish verifier no longer accepts a missing matrix-js-sdk or @matrix-org/matrix-sdk-crypto-nodejs as optional, closing the masking allow-list.
  • The plugin contract guardrail explicitly tests bundled-Matrix ownership (deps in both manifests), preventing a re-regression.
• Edge cases checked:
  • The audit's bundled-extension classification still considers Matrix bundled (no !dist/extensions/matrix/** was added) and accepts the new root-owned deps.
  • The contract test still rejects spuriously adding @openclaw/plugin-package-contract to root.
• What you did not verify: A live host npm install on macOS plus an openclaw update cycle (the issue's exact path); Docker host variants; the Sparkle/macOS app-side packaging.

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? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Adding five runtime deps to root grows the published tarball's transitive install footprint for users who do not use Matrix.
  • Mitigation: Same versions as the plugin-local manifest already pinned; no new transitive surface compared to the prior bundled Matrix shipping with its own node_modules. If a follow-up wants to externalize Matrix the same way Discord/WhatsApp are externalized, that is a separate change with its own contract update.
• Risk: Future externalization of Matrix would have to remove these deps in lockstep.
  • Mitigation: The contract guardrail and postpublish verifier now both encode bundled-Matrix ownership, so any externalization PR has to update both files and the files exclusion list together.

🤖 Generated with Claude Code

Changed files

• config/knip.config.ts (modified, +5/-0)
• package.json (modified, +5/-0)
• pnpm-lock.yaml (modified, +15/-0)
• scripts/openclaw-npm-postpublish-verify.ts (modified, +0/-2)
• src/plugins/contracts/package-manifest.contract.test.ts (modified, +6/-11)
• src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts (modified, +7/-2)