diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index c6e454602..0273e494c 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
{
"repository": "openclaw/openclaw",
- "sha": "f6b2ba4a10afe7bedf154f1765bc1943748d3c81",
- "syncedAt": "2026-04-27T19:46:34.354Z"
+ "sha": "f0000ab72d0185f375658a7b5ccbe12b945ea980",
+ "syncedAt": "2026-04-27T19:52:09.863Z"
}
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 6ba74fbbd..d4b0ceadd 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -1,2 +1,2 @@
-9a9970607c4ee25d8b493ea1bb1ecef939dc11330c16188251bd69eee7ab6b2d plugin-sdk-api-baseline.json
-e37f1ec7f6a9b19466ab09935f713890f375cc6c8d67647dca701140a989f5f4 plugin-sdk-api-baseline.jsonl
+f826635804fdc28fb6e1725f1c9d7e6aa8486a9085262496445885ad246860f8 plugin-sdk-api-baseline.json
+0467fa5b0ce4060d7e45d5cb76c50136a0923ce19fda3550317d7734124f8af8 plugin-sdk-api-baseline.jsonl
diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md
index df6a4977e..a23aa8d63 100644
--- a/docs/plugins/architecture-internals.md
+++ b/docs/plugins/architecture-internals.md
@@ -605,12 +605,16 @@ Channel plugins pick from a family of narrow seams — `channel-setup`,
on one `approvalCapability` contract rather than mixing across unrelated
plugin fields. See [Channel plugins](/plugins/sdk-channel-plugins).
-Runtime and config helpers live under matching `*-runtime` subpaths
-(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
-`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store`, etc.).
+Runtime and config helpers live under matching focused `*-runtime` subpaths
+(`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`,
+`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`,
+`channel-activity-runtime`, etc.). Prefer `config-types`,
+`plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation`
+instead of the broad `config-runtime` compatibility barrel.
-`openclaw/plugin-sdk/channel-runtime` is deprecated — a compatibility shim for
+`openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime`,
+and `openclaw/plugin-sdk/infra-runtime` are deprecated compatibility shims for
older plugins. New code should import narrower generic primitives instead.
diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md
index 2fcc4e2a7..550829a5a 100644
--- a/docs/plugins/sdk-migration.md
+++ b/docs/plugins/sdk-migration.md
@@ -22,6 +22,12 @@ anything they needed from a single entry point:
- **`openclaw/plugin-sdk/compat`** — a single import that re-exported dozens of
helpers. It was introduced to keep older hook-based plugins working while the
new plugin architecture was being built.
+- **`openclaw/plugin-sdk/infra-runtime`** — a broad runtime helper barrel that
+ mixed system events, heartbeat state, delivery queues, fetch/proxy helpers,
+ file helpers, approval types, and unrelated utilities.
+- **`openclaw/plugin-sdk/config-runtime`** — a broad config compatibility barrel
+ that still carries deprecated direct load/write helpers during the migration
+ window.
- **`openclaw/extension-api`** — a bridge that gave plugins direct access to
host-side helpers like the embedded agent runner.
- **`api.registerEmbeddedExtensionFactory(...)`** — a removed Pi-only bundled
@@ -235,6 +241,7 @@ releases.
```bash
grep -r "plugin-sdk/compat" my-plugin/
+ grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
```
@@ -284,6 +291,37 @@ releases.
+
+ `openclaw/plugin-sdk/infra-runtime` still exists for external
+ compatibility, but new code should import the focused helper surface it
+ actually needs:
+
+ | Need | Import |
+ | --- | --- |
+ | System event queue helpers | `openclaw/plugin-sdk/system-event-runtime` |
+ | Heartbeat event and visibility helpers | `openclaw/plugin-sdk/heartbeat-runtime` |
+ | Pending delivery queue drain | `openclaw/plugin-sdk/delivery-queue-runtime` |
+ | Channel activity telemetry | `openclaw/plugin-sdk/channel-activity-runtime` |
+ | In-memory dedupe caches | `openclaw/plugin-sdk/dedupe-runtime` |
+ | Safe local-file/media path helpers | `openclaw/plugin-sdk/file-access-runtime` |
+ | Dispatcher-aware fetch | `openclaw/plugin-sdk/runtime-fetch` |
+ | Proxy and guarded fetch helpers | `openclaw/plugin-sdk/fetch-runtime` |
+ | SSRF dispatcher policy types | `openclaw/plugin-sdk/ssrf-dispatcher` |
+ | Approval request/resolution types | `openclaw/plugin-sdk/approval-runtime` |
+ | Approval reply payload and command helpers | `openclaw/plugin-sdk/approval-reply-runtime` |
+ | Error formatting helpers | `openclaw/plugin-sdk/error-runtime` |
+ | Transport readiness waits | `openclaw/plugin-sdk/transport-ready-runtime` |
+ | Secure token helpers | `openclaw/plugin-sdk/secure-random-runtime` |
+ | Bounded async task concurrency | `openclaw/plugin-sdk/concurrency-runtime` |
+ | Numeric coercion | `openclaw/plugin-sdk/number-runtime` |
+ | Process-local async lock | `openclaw/plugin-sdk/async-lock-runtime` |
+ | File locks | `openclaw/plugin-sdk/file-lock` |
+
+ Bundled plugins are scanner-guarded against `infra-runtime`, so repo code
+ cannot regress to the broad barrel.
+
+
+
```bash
pnpm build
@@ -338,7 +376,7 @@ releases.
| `plugin-sdk/process-runtime` | Process helpers | Shared exec helpers |
| `plugin-sdk/cli-runtime` | CLI runtime helpers | Command formatting, waits, version helpers |
| `plugin-sdk/gateway-runtime` | Gateway helpers | Gateway client and channel-status patch helpers |
- | `plugin-sdk/config-runtime` | Config helpers | Config load/write helpers |
+ | `plugin-sdk/config-runtime` | Deprecated config compatibility shim | Prefer `config-types`, `plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation` |
| `plugin-sdk/telegram-command-config` | Telegram command helpers | Fallback-stable Telegram command validation helpers when the bundled Telegram contract surface is unavailable |
| `plugin-sdk/approval-runtime` | Approval prompt helpers | Exec/plugin approval payload, approval capability/profile helpers, native approval routing/runtime helpers, and structured approval display path formatting |
| `plugin-sdk/approval-auth-runtime` | Approval auth helpers | Approver resolution, same-chat action auth |
@@ -353,6 +391,13 @@ releases.
| `plugin-sdk/security-runtime` | Security helpers | Shared trust, DM gating, external-content, and secret-collection helpers |
| `plugin-sdk/ssrf-policy` | SSRF policy helpers | Host allowlist and private-network policy helpers |
| `plugin-sdk/ssrf-runtime` | SSRF runtime helpers | Pinned-dispatcher, guarded fetch, SSRF policy helpers |
+ | `plugin-sdk/system-event-runtime` | System event helpers | `enqueueSystemEvent`, `peekSystemEventEntries` |
+ | `plugin-sdk/heartbeat-runtime` | Heartbeat helpers | Heartbeat event and visibility helpers |
+ | `plugin-sdk/delivery-queue-runtime` | Delivery queue helpers | `drainPendingDeliveries` |
+ | `plugin-sdk/channel-activity-runtime` | Channel activity helpers | `recordChannelActivity` |
+ | `plugin-sdk/dedupe-runtime` | Dedupe helpers | In-memory dedupe caches |
+ | `plugin-sdk/file-access-runtime` | File access helpers | Safe local-file/media path helpers |
+ | `plugin-sdk/transport-ready-runtime` | Transport readiness helpers | `waitForTransportReady` |
| `plugin-sdk/collection-runtime` | Bounded cache helpers | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Diagnostic gating helpers | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Error formatting helpers | `formatUncaughtError`, `isApprovalNotFoundError`, error graph helpers |
diff --git a/docs/plugins/sdk-subpaths.md b/docs/plugins/sdk-subpaths.md
index 9fc0f2da9..419a1803a 100644
--- a/docs/plugins/sdk-subpaths.md
+++ b/docs/plugins/sdk-subpaths.md
@@ -205,7 +205,18 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
| `plugin-sdk/native-command-registry` | Native command registry/build/serialize helpers |
| `plugin-sdk/agent-harness` | Experimental trusted-plugin surface for low-level agent harnesses: harness types, active-run steer/abort helpers, OpenClaw tool bridge helpers, runtime-plan tool policy helpers, terminal outcome classification, tool progress formatting/detail helpers, and attempt result utilities |
| `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint detection helpers |
- | `plugin-sdk/infra-runtime` | System event/heartbeat helpers |
+ | `plugin-sdk/async-lock-runtime` | Process-local async lock helper for small runtime state files |
+ | `plugin-sdk/channel-activity-runtime` | Channel activity telemetry helper |
+ | `plugin-sdk/concurrency-runtime` | Bounded async task concurrency helper |
+ | `plugin-sdk/dedupe-runtime` | In-memory dedupe cache helpers |
+ | `plugin-sdk/delivery-queue-runtime` | Outbound pending-delivery drain helper |
+ | `plugin-sdk/file-access-runtime` | Safe local-file and media-source path helpers |
+ | `plugin-sdk/heartbeat-runtime` | Heartbeat event and visibility helpers |
+ | `plugin-sdk/number-runtime` | Numeric coercion helper |
+ | `plugin-sdk/secure-random-runtime` | Secure token/UUID helpers |
+ | `plugin-sdk/system-event-runtime` | System event queue helpers |
+ | `plugin-sdk/transport-ready-runtime` | Transport readiness wait helper |
+ | `plugin-sdk/infra-runtime` | Deprecated compatibility shim; use the focused runtime subpaths above |
| `plugin-sdk/collection-runtime` | Small bounded cache helpers |
| `plugin-sdk/diagnostic-runtime` | Diagnostic flag, event, and trace-context helpers |
| `plugin-sdk/error-runtime` | Error graph, formatting, shared error classification helpers, `isApprovalNotFoundError` |