Summary

• Problem: after v2026.5.2, enabled external capability providers declared only through manifest contracts (for example contracts.speechProviders) can fail with no provider registered unless they are also startup-loaded.
• Why it matters: docs describe manifest ownership/contract fallback as preserving correctness; missing startup activation should cost performance, not make an installed provider unusable.
• What changed: preserve the v2026.5.2 fast path that reuses an already-loaded runtime registry, but fall back to the scoped manifest-derived runtime load when that registry is missing the provider.
• What did NOT change (scope boundary): this does not change plugin activation policy, startup sidecar selection, bundled provider compatibility capture, or provider config semantics.

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 N/A
• Related N/A
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: commit 8283c5d6cc changed capability provider fallback loading from resolveRuntimePluginRegistry(params.loadOptions) to getLoadedRuntimePluginRegistry(...). That preserved startup-registry reuse, but dropped the cold-load path for enabled external providers that are declared in manifest contracts but absent from the startup registry.
• Missing detection / guardrail: no regression test covered an enabled external manifest-contract provider that is not startup-loaded.
• Contributing context (if known): Fish Audio @conan-scott/openclaw-fish-audio@1.1.0 declares contracts.speechProviders: ["fish-audio"]; without activation.onStartup, v2026.5.2 could discover the contract but failed to register the runtime provider on request.

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/capability-provider-runtime.test.ts
• Scenario the test should lock in: an enabled external speech provider declared via contracts.speechProviders is absent from the startup registry, then resolves through the scoped cold-load path.
• Why this is the smallest reliable guardrail: the regression is in capability-provider runtime selection, before provider-specific TTS behavior matters.
• Existing test that already covers this (if any): none found.
• If no new test is added, why not: N/A; a regression test is added.

User-visible / Behavior Changes

Enabled external capability providers declared through manifest contracts can again resolve on request without requiring activation.onStartup for correctness.

Diagram (if applicable)

Before:
TTS request -> manifest contract identifies external provider -> startup registry missing provider -> no provider registered

After:
TTS request -> manifest contract identifies external provider -> startup registry missing provider -> scoped cold load -> provider registered

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: N/A

Repro + Verification

Environment

• OS: Linux container / OpenShift pod (linux 6.12.0-153.el10.x86_64, Node 24.14.0)
• Runtime/container: OpenClaw 2026.5.2
• Model/provider: N/A
• Integration/channel (if any): TTS via Fish Audio speech provider
• Relevant config (redacted): Fish Audio installed and enabled; installed manifest declares contracts.speechProviders: ["fish-audio"]; activation.onStartup removed for the repro.

Steps

1. Install/enable @conan-scott/openclaw-fish-audio@1.1.0 with contracts.speechProviders: ["fish-audio"] and no activation.onStartup.
2. Hard-restart the OpenClaw pod on unpatched 2026.5.2.
3. Run a TTS request using Fish Audio.
4. Apply this PR's runtime change as a loader monkey patch only; keep the Fish plugin manifest unpatched.
5. Hard-restart the pod again.
6. Run the same TTS request.

Expected

• The enabled provider declared by contracts.speechProviders should be request-loadable and usable.

Actual

• Before patch: TTS failed with fish-audio: no provider registered; microsoft: not configured; minimax: not configured.
• After patch: the same Fish Audio TTS path worked after hard pod restart with no plugin-side activation patch.

Evidence

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

Local automated checks:

• pnpm exec vitest run src/plugins/capability-provider-runtime.test.ts — 37 passed
• pnpm exec oxfmt --check src/plugins/capability-provider-runtime.ts src/plugins/capability-provider-runtime.test.ts — passed
• pnpm exec oxlint src/plugins/capability-provider-runtime.ts src/plugins/capability-provider-runtime.test.ts — 0 warnings / 0 errors

Manual runtime evidence:

• Baseline hard restart, Fish manifest without activation.onStartup, no runtime patch: fish-audio: no provider registered; microsoft: not configured; minimax: not configured.
• Monkey-patched runtime with this PR's code, Fish manifest still without activation.onStartup, hard restarted pod: /tts audio exact reinstall hard restart test after monkey patch worked.

Human Verification (required)

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

• Verified scenarios: baseline failure on unpatched 2026.5.2; success after applying only this runtime fallback as a loader monkey patch; hard pod restart on both sides.
• Edge cases checked: Fish plugin manifest intentionally left without activation.onStartup during the passing test, so success came from runtime fallback rather than plugin startup activation.
• What you did not verify: a full packaged OpenClaw image built from this branch; broader non-speech providers beyond the unit coverage.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: reintroducing cold provider loads could partially reduce the startup-registry reuse optimization from v2026.5.2.
  • Mitigation: the cold load only runs when no compatible loaded registry is available for the scoped provider request; the fast path remains first.