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` |