Skip to content

Commit f0000ab

Browse files
steipetesteipete
committed
refactor(plugin-sdk): split infra runtime barrel
1 parent d7c3a77 commit f0000ab

104 files changed

Lines changed: 405 additions & 165 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
9a9970607c4ee25d8b493ea1bb1ecef939dc11330c16188251bd69eee7ab6b2d plugin-sdk-api-baseline.json
2-
e37f1ec7f6a9b19466ab09935f713890f375cc6c8d67647dca701140a989f5f4 plugin-sdk-api-baseline.jsonl
1+
f826635804fdc28fb6e1725f1c9d7e6aa8486a9085262496445885ad246860f8 plugin-sdk-api-baseline.json
2+
0467fa5b0ce4060d7e45d5cb76c50136a0923ce19fda3550317d7734124f8af8 plugin-sdk-api-baseline.jsonl

‎docs/plugins/architecture-internals.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -605,12 +605,16 @@ Channel plugins pick from a family of narrow seams — `channel-setup`,
605605
on one `approvalCapability` contract rather than mixing across unrelated
606606
plugin fields. See [Channel plugins](/plugins/sdk-channel-plugins).
607607

608-
Runtime and config helpers live under matching `*-runtime` subpaths
609-
(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
610-
`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store`, etc.).
608+
Runtime and config helpers live under matching focused `*-runtime` subpaths
609+
(`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`,
610+
`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`,
611+
`channel-activity-runtime`, etc.). Prefer `config-types`,
612+
`plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation`
613+
instead of the broad `config-runtime` compatibility barrel.
611614

612615
<Info>
613-
`openclaw/plugin-sdk/channel-runtime` is deprecated — a compatibility shim for
616+
`openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime`,
617+
and `openclaw/plugin-sdk/infra-runtime` are deprecated compatibility shims for
614618
older plugins. New code should import narrower generic primitives instead.
615619
</Info>
616620

‎docs/plugins/sdk-migration.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ anything they needed from a single entry point:
2222
- **`openclaw/plugin-sdk/compat`** — a single import that re-exported dozens of
2323
helpers. It was introduced to keep older hook-based plugins working while the
2424
new plugin architecture was being built.
25+
- **`openclaw/plugin-sdk/infra-runtime`** — a broad runtime helper barrel that
26+
mixed system events, heartbeat state, delivery queues, fetch/proxy helpers,
27+
file helpers, approval types, and unrelated utilities.
28+
- **`openclaw/plugin-sdk/config-runtime`** — a broad config compatibility barrel
29+
that still carries deprecated direct load/write helpers during the migration
30+
window.
2531
- **`openclaw/extension-api`** — a bridge that gave plugins direct access to
2632
host-side helpers like the embedded agent runner.
2733
- **`api.registerEmbeddedExtensionFactory(...)`** — a removed Pi-only bundled
@@ -235,6 +241,7 @@ releases.
235241

236242
```bash
237243
grep -r "plugin-sdk/compat" my-plugin/
244+
grep -r "plugin-sdk/infra-runtime" my-plugin/
238245
grep -r "plugin-sdk/config-runtime" my-plugin/
239246
grep -r "openclaw/extension-api" my-plugin/
240247
```
@@ -284,6 +291,37 @@ releases.
284291

285292
</Step>
286293

294+
<Step title="Replace broad infra-runtime imports">
295+
`openclaw/plugin-sdk/infra-runtime` still exists for external
296+
compatibility, but new code should import the focused helper surface it
297+
actually needs:
298+
299+
| Need | Import |
300+
| --- | --- |
301+
| System event queue helpers | `openclaw/plugin-sdk/system-event-runtime` |
302+
| Heartbeat event and visibility helpers | `openclaw/plugin-sdk/heartbeat-runtime` |
303+
| Pending delivery queue drain | `openclaw/plugin-sdk/delivery-queue-runtime` |
304+
| Channel activity telemetry | `openclaw/plugin-sdk/channel-activity-runtime` |
305+
| In-memory dedupe caches | `openclaw/plugin-sdk/dedupe-runtime` |
306+
| Safe local-file/media path helpers | `openclaw/plugin-sdk/file-access-runtime` |
307+
| Dispatcher-aware fetch | `openclaw/plugin-sdk/runtime-fetch` |
308+
| Proxy and guarded fetch helpers | `openclaw/plugin-sdk/fetch-runtime` |
309+
| SSRF dispatcher policy types | `openclaw/plugin-sdk/ssrf-dispatcher` |
310+
| Approval request/resolution types | `openclaw/plugin-sdk/approval-runtime` |
311+
| Approval reply payload and command helpers | `openclaw/plugin-sdk/approval-reply-runtime` |
312+
| Error formatting helpers | `openclaw/plugin-sdk/error-runtime` |
313+
| Transport readiness waits | `openclaw/plugin-sdk/transport-ready-runtime` |
314+
| Secure token helpers | `openclaw/plugin-sdk/secure-random-runtime` |
315+
| Bounded async task concurrency | `openclaw/plugin-sdk/concurrency-runtime` |
316+
| Numeric coercion | `openclaw/plugin-sdk/number-runtime` |
317+
| Process-local async lock | `openclaw/plugin-sdk/async-lock-runtime` |
318+
| File locks | `openclaw/plugin-sdk/file-lock` |
319+
320+
Bundled plugins are scanner-guarded against `infra-runtime`, so repo code
321+
cannot regress to the broad barrel.
322+
323+
</Step>
324+
287325
<Step title="Build and test">
288326
```bash
289327
pnpm build
@@ -338,7 +376,7 @@ releases.
338376
| `plugin-sdk/process-runtime` | Process helpers | Shared exec helpers |
339377
| `plugin-sdk/cli-runtime` | CLI runtime helpers | Command formatting, waits, version helpers |
340378
| `plugin-sdk/gateway-runtime` | Gateway helpers | Gateway client and channel-status patch helpers |
341-
| `plugin-sdk/config-runtime` | Config helpers | Config load/write helpers |
379+
| `plugin-sdk/config-runtime` | Deprecated config compatibility shim | Prefer `config-types`, `plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation` |
342380
| `plugin-sdk/telegram-command-config` | Telegram command helpers | Fallback-stable Telegram command validation helpers when the bundled Telegram contract surface is unavailable |
343381
| `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 |
344382
| `plugin-sdk/approval-auth-runtime` | Approval auth helpers | Approver resolution, same-chat action auth |
@@ -353,6 +391,13 @@ releases.
353391
| `plugin-sdk/security-runtime` | Security helpers | Shared trust, DM gating, external-content, and secret-collection helpers |
354392
| `plugin-sdk/ssrf-policy` | SSRF policy helpers | Host allowlist and private-network policy helpers |
355393
| `plugin-sdk/ssrf-runtime` | SSRF runtime helpers | Pinned-dispatcher, guarded fetch, SSRF policy helpers |
394+
| `plugin-sdk/system-event-runtime` | System event helpers | `enqueueSystemEvent`, `peekSystemEventEntries` |
395+
| `plugin-sdk/heartbeat-runtime` | Heartbeat helpers | Heartbeat event and visibility helpers |
396+
| `plugin-sdk/delivery-queue-runtime` | Delivery queue helpers | `drainPendingDeliveries` |
397+
| `plugin-sdk/channel-activity-runtime` | Channel activity helpers | `recordChannelActivity` |
398+
| `plugin-sdk/dedupe-runtime` | Dedupe helpers | In-memory dedupe caches |
399+
| `plugin-sdk/file-access-runtime` | File access helpers | Safe local-file/media path helpers |
400+
| `plugin-sdk/transport-ready-runtime` | Transport readiness helpers | `waitForTransportReady` |
356401
| `plugin-sdk/collection-runtime` | Bounded cache helpers | `pruneMapToMaxSize` |
357402
| `plugin-sdk/diagnostic-runtime` | Diagnostic gating helpers | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
358403
| `plugin-sdk/error-runtime` | Error formatting helpers | `formatUncaughtError`, `isApprovalNotFoundError`, error graph helpers |

‎docs/plugins/sdk-subpaths.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,18 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
205205
| `plugin-sdk/native-command-registry` | Native command registry/build/serialize helpers |
206206
| `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 |
207207
| `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint detection helpers |
208-
| `plugin-sdk/infra-runtime` | System event/heartbeat helpers |
208+
| `plugin-sdk/async-lock-runtime` | Process-local async lock helper for small runtime state files |
209+
| `plugin-sdk/channel-activity-runtime` | Channel activity telemetry helper |
210+
| `plugin-sdk/concurrency-runtime` | Bounded async task concurrency helper |
211+
| `plugin-sdk/dedupe-runtime` | In-memory dedupe cache helpers |
212+
| `plugin-sdk/delivery-queue-runtime` | Outbound pending-delivery drain helper |
213+
| `plugin-sdk/file-access-runtime` | Safe local-file and media-source path helpers |
214+
| `plugin-sdk/heartbeat-runtime` | Heartbeat event and visibility helpers |
215+
| `plugin-sdk/number-runtime` | Numeric coercion helper |
216+
| `plugin-sdk/secure-random-runtime` | Secure token/UUID helpers |
217+
| `plugin-sdk/system-event-runtime` | System event queue helpers |
218+
| `plugin-sdk/transport-ready-runtime` | Transport readiness wait helper |
219+
| `plugin-sdk/infra-runtime` | Deprecated compatibility shim; use the focused runtime subpaths above |
209220
| `plugin-sdk/collection-runtime` | Small bounded cache helpers |
210221
| `plugin-sdk/diagnostic-runtime` | Diagnostic flag, event, and trace-context helpers |
211222
| `plugin-sdk/error-runtime` | Error graph, formatting, shared error classification helpers, `isApprovalNotFoundError` |

‎extensions/bluebubbles/src/media-send.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@ import { constants as fsConstants } from "node:fs";
22
import fs from "node:fs/promises";
33
import os from "node:os";
44
import path from "node:path";
5-
import { basenameFromMediaSource, safeFileURLToPath } from "openclaw/plugin-sdk/infra-runtime";
5+
import {
6+
basenameFromMediaSource,
7+
safeFileURLToPath,
8+
} from "openclaw/plugin-sdk/file-access-runtime";
69
import { resolveChannelMediaMaxBytes } from "openclaw/plugin-sdk/media-runtime";
710
import { lowercasePreservingWhitespace } from "openclaw/plugin-sdk/text-runtime";
811
import { resolveBlueBubblesAccount } from "./accounts.js";

‎extensions/bluebubbles/src/monitor-normalize.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { parseFiniteNumber } from "openclaw/plugin-sdk/infra-runtime";
1+
import { parseFiniteNumber } from "openclaw/plugin-sdk/number-runtime";
22
import {
33
asNullableRecord,
44
normalizeLowercaseStringOrEmpty,

‎extensions/bluebubbles/src/runtime-api.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export type {
2929
OpenClawConfig,
3030
PluginRuntime,
3131
} from "openclaw/plugin-sdk/channel-core";
32-
export { parseFiniteNumber } from "openclaw/plugin-sdk/infra-runtime";
32+
export { parseFiniteNumber } from "openclaw/plugin-sdk/number-runtime";
3333
export { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
3434
export {
3535
DM_GROUP_ACCESS_REASON,

‎extensions/discord/src/approval-handler.runtime.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,9 @@ import type {
1919
PluginApprovalResolvedView,
2020
} from "openclaw/plugin-sdk/approval-handler-runtime";
2121
import { createChannelApprovalNativeRuntimeAdapter } from "openclaw/plugin-sdk/approval-handler-runtime";
22+
import type { ExecApprovalActionDescriptor } from "openclaw/plugin-sdk/approval-reply-runtime";
23+
import type { ExecApprovalDecision } from "openclaw/plugin-sdk/approval-runtime";
2224
import type { DiscordExecApprovalConfig, OpenClawConfig } from "openclaw/plugin-sdk/config-types";
23-
import type {
24-
ExecApprovalActionDescriptor,
25-
ExecApprovalDecision,
26-
} from "openclaw/plugin-sdk/infra-runtime";
2725
import { logDebug, logError, normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
2826
import { shouldHandleDiscordApprovalRequest } from "./approval-shared.js";
2927
import { isDiscordExecApprovalClientEnabled } from "./exec-approvals.js";

‎extensions/discord/src/approval-shared.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
import { doesApprovalRequestMatchChannelAccount } from "openclaw/plugin-sdk/approval-native-runtime";
2+
import type {
3+
ExecApprovalRequest,
4+
PluginApprovalRequest,
5+
} from "openclaw/plugin-sdk/approval-runtime";
26
import type { DiscordExecApprovalConfig, OpenClawConfig } from "openclaw/plugin-sdk/config-types";
3-
import type { ExecApprovalRequest, PluginApprovalRequest } from "openclaw/plugin-sdk/infra-runtime";
47
import { resolveDiscordAccount } from "./accounts.js";
58
import {
69
isChannelExecApprovalClientEnabledFromConfig,

‎extensions/discord/src/client.proxy.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ import { createDiscordRequestClient } from "./proxy-request-client.js";
77

88
const makeProxyFetchMock = vi.hoisted(() => vi.fn());
99

10-
vi.mock("openclaw/plugin-sdk/infra-runtime", async () => {
11-
const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/infra-runtime")>(
12-
"openclaw/plugin-sdk/infra-runtime",
10+
vi.mock("openclaw/plugin-sdk/fetch-runtime", async () => {
11+
const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/fetch-runtime")>(
12+
"openclaw/plugin-sdk/fetch-runtime",
1313
);
1414
makeProxyFetchMock.mockImplementation((proxyUrl: string) => {
1515
if (proxyUrl === "bad-proxy") {

0 commit comments

Comments
 (0)