Plugins: prefer current loader root for sdk aliases

[RichardCao]

Summary

• Problem: local TS plugins can resolve SDK aliases from the wrong OpenClaw install root when alias fallback depends on process.cwd() instead of the currently running loader module.
• Why it matters: if multiple installs or mismatched working directories are present, openclaw/plugin-sdk/* imports can point at the wrong package tree and fail to load.
• What changed: threaded moduleUrl hints through plugin SDK alias resolution and passed the current loader/runtime module URL from the plugin loader plus the Matrix/WhatsApp runtime boundaries.
• What did NOT change (scope boundary): no plugin manifest or Jiti dependency changes; this stays inside alias-root selection.

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 [Bug]: local TS extensions importing openclaw/plugin-sdk/plugin-entry fail to load on 2026.3.22 #53002
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: local plugin alias resolution could fall back to process.cwd() and choose a different OpenClaw package root than the one that is actually executing the loader.
• Missing detection / guardrail: there was no regression test covering multiple candidate OpenClaw roots for a local TS plugin load.
• Prior context (git blame, prior PR, issue, or refactor if known): [Bug]: local TS extensions importing openclaw/plugin-sdk/plugin-entry fail to load on 2026.3.22 #53002 reports the failure against a global npm install where the observed failing path did not match the install path described in the issue, which points to root-selection drift.
• Why this regressed now: the loader path already had cwd/package-root fallback logic, but it did not consistently anchor resolution to the currently running loader/runtime module.
• If unknown, what was ruled out: a minimal repro against current main and an unpacked openclaw@2026.3.22 tarball worked when the package root was unambiguous, which ruled out a simple plugin-entry alias omission.

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/sdk-alias.test.ts
• Scenario the test should lock in: when cwd points at one valid OpenClaw root but the current loader module belongs to another, local TS plugin SDK aliases should follow the loader module root.
• Why this is the smallest reliable guardrail: it exercises the real alias builder and Jiti load path without requiring a full gateway restart or multiple real global installs.
• Existing test that already covers this (if any): existing tests covered alias candidate order and scoped alias loading, but not cross-root selection.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Local TS plugins now resolve openclaw/plugin-sdk/* against the currently running OpenClaw install even if process.cwd() points at another valid OpenClaw root.

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 26.3 (local dev machine)
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): plugin loader / Jiti alias boundary
• Relevant config (redacted): N/A

Steps

1. Create two valid fixture OpenClaw roots with different plugin-entry exports.
2. Set process.cwd() to the wrong root and load a local TS plugin outside both roots.
3. Build aliases using the current loader module URL and load the plugin through Jiti.

Expected

• The local plugin resolves SDK aliases from the current loader module root, not the unrelated cwd fallback root.

Actual

• Verified locally after the fix: the plugin resolves from the intended loader root and loads successfully.

Evidence

Attach at least one:

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

Human Verification (required)

• Verified scenarios: ran pnpm exec vitest run src/plugins/sdk-alias.test.ts src/plugin-sdk/root-alias.test.ts.
• Edge cases checked: verified the old fallback still uses cwd when no module hint is provided, and verified the new module hint overrides that fallback for local plugin loading.
• What you did not verify: I did not run a full openclaw gateway restart against a real global multi-install machine.

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/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this commit.
• Files/config to restore: src/plugins/sdk-alias.ts, src/plugins/loader.ts, src/plugins/runtime/runtime-matrix-boundary.ts, src/plugins/runtime/runtime-whatsapp-boundary.ts, src/plugins/sdk-alias.test.ts
• Known bad symptoms reviewers should watch for: local plugins resolve SDK aliases from the wrong install root or Jiti-based plugin loads regress.

Risks and Mitigations

• Risk: other call sites might still rely on cwd fallback if they do not pass a module hint.
  • Mitigation: this PR updates the main plugin loader and the Jiti-based Matrix/WhatsApp runtime boundaries, which are the user-facing entry points for this regression.

[greptile-apps]

Greptile Summary

This PR adds a focused regression test to src/plugins/sdk-alias.test.ts that exercises a local TypeScript plugin importing openclaw/plugin-sdk/plugin-entry through the buildPluginLoaderAliasMap + Jiti load path, which was the reported failure surface in #53002.

• The new test follows the established fixture pattern: it uses createPluginSdkAliasFixture with a plugin-entry.ts/js pair, writes both src and dist root-alias.cjs shims, creates a synthetic local plugin entry at extensions/demo-plugin/index.ts, builds the alias map under NODE_ENV=undefined, asserts both the root alias and scoped plugin-entry alias resolve to source files, then confirms Jiti successfully loads the plugin and returns loadedEntry: "source-plugin-entry".
• No runtime behavior was changed; this is additive test coverage only.
• The test is internally consistent with the rest of the suite: timeout, fixture teardown, use of withEnv, and mkdirSafe match existing conventions.

Confidence Score: 5/5

• This PR is safe to merge — it adds a pure regression test with no production code changes.
• The change is purely additive: one new it(...) block in an existing test file. It correctly follows all established fixture and teardown patterns (createPluginSdkAliasFixture, mkdirSafe, withEnv, the 240 s timeout). All assertions are coherent — the alias map assertions verify both the root alias and the scoped plugin-entry alias point to the source tree, and the Jiti load assertion validates the end-to-end load path. No runtime code was touched.
• No files require special attention.

_{Reviews (1): Last reviewed commit: "Tests: cover local plugin-entry alias lo..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 692b788781

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Load the real plugin-entry source in this regression test

If the reported failure only happens when Jiti has to execute the actual src/plugin-sdk/plugin-entry.ts graph from an installed package, this test will still pass because it replaces both source and dist plugin-entry modules with dependency-free stubs. The real module immediately imports ../plugins/config-schema.js and ../plugins/types.js (src/plugin-sdk/plugin-entry.ts:1-8), so this fixture never exercises the .js-specifier rewriting/resolution path that can break local TS plugins. As written, the test can stay green even while openclaw/plugin-sdk/plugin-entry is still unloadable in production-like installs.

Useful? React with 👍 / 👎.

[openclaw-barnacle]

Closing this PR because the author has more than 10 active PRs in this repo. Please reduce the active PR queue and reopen or resubmit once it is back under the limit. You can close your own PRs to get back under the limit.

[openclaw-barnacle]

Closing this PR because the author has more than 10 active PRs in this repo. Please reduce the active PR queue and reopen or resubmit once it is back under the limit. You can close your own PRs to get back under the limit.