Skip to content

Commit 4336a7f

Browse files
steipetesteipete
committed
refactor(plugin-sdk): narrow config runtime imports
1 parent f3e8a8a commit 4336a7f

573 files changed

Lines changed: 1066 additions & 860 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/plugins/sdk-migration.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,25 @@ releases.
129129
must receive config from their boundary, and long-lived runtime modules have
130130
zero allowed ambient `loadConfig()` calls.
131131

132+
New plugin code should also avoid importing the broad
133+
`openclaw/plugin-sdk/config-runtime` compatibility barrel. Use the narrow
134+
SDK subpath that matches the job:
135+
136+
| Need | Import |
137+
| --- | --- |
138+
| Config types such as `OpenClawConfig` | `openclaw/plugin-sdk/config-types` |
139+
| Already-loaded config assertions and plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime` |
140+
| Current runtime snapshot reads | `openclaw/plugin-sdk/runtime-config-snapshot` |
141+
| Config writes | `openclaw/plugin-sdk/config-mutation` |
142+
| Session store helpers | `openclaw/plugin-sdk/session-store-runtime` |
143+
| Markdown table config | `openclaw/plugin-sdk/markdown-table-runtime` |
144+
| Group policy runtime helpers | `openclaw/plugin-sdk/runtime-group-policy` |
145+
| Secret input resolution | `openclaw/plugin-sdk/secret-input-runtime` |
146+
| Model/session overrides | `openclaw/plugin-sdk/model-session-runtime` |
147+
148+
Bundled production plugins are scanner-guarded against the broad barrel so
149+
imports stay local to the behavior they need.
150+
132151
</Step>
133152

134153
<Step title="Migrate Pi tool-result extensions to middleware">

‎docs/plugins/sdk-runtime.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ The mutation helpers return `afterWrite` plus a typed `followUp` summary so call
4343

4444
`api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated compatibility helpers under `runtime-config-load-write`. They warn once at runtime, and bundled plugins must not use them; the config boundary guards fail if production plugin code calls them or imports those helpers from plugin SDK subpaths.
4545

46+
For direct SDK imports, use the focused config subpaths instead of the broad
47+
`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-types` for
48+
types, `plugin-config-runtime` for already-loaded config assertions and plugin
49+
entry lookup, `runtime-config-snapshot` for current process snapshots, and
50+
`config-mutation` for writes.
51+
4652
Internal OpenClaw runtime code has the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. Successful mutation writes refresh the process runtime snapshot and advance its internal revision; long-lived caches should key off the runtime-owned cache key instead of serializing config locally. Long-lived runtime modules have a zero-tolerance scanner for ambient `loadConfig()` calls; use a passed `cfg`, a request `context.getRuntimeConfig()`, or `getRuntimeConfig()` at an explicit process boundary.
4753

4854
## Runtime namespaces

‎docs/plugins/sdk-subpaths.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,10 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
161161
| `plugin-sdk/process-runtime` | Process exec helpers |
162162
| `plugin-sdk/cli-runtime` | CLI formatting, wait, version, argument-invocation, and lazy command-group helpers |
163163
| `plugin-sdk/gateway-runtime` | Gateway client, gateway CLI RPC, gateway protocol errors, and channel-status patch helpers |
164-
| `plugin-sdk/config-runtime` | Config load/write helpers and plugin-config lookup helpers |
164+
| `plugin-sdk/config-types` | Type-only config surface for plugin config shapes such as `OpenClawConfig` and channel/provider config types |
165+
| `plugin-sdk/plugin-config-runtime` | Runtime plugin-config lookup helpers such as `requireRuntimeConfig`, `resolvePluginConfigObject`, and `resolveLivePluginConfigObject` |
166+
| `plugin-sdk/config-mutation` | Transactional config mutation helpers such as `mutateConfigFile`, `replaceConfigFile`, and `logConfigUpdated` |
167+
| `plugin-sdk/runtime-config-snapshot` | Current process config snapshot helpers such as `getRuntimeConfig`, `getRuntimeConfigSnapshot`, and test snapshot setters |
165168
| `plugin-sdk/telegram-command-config` | Telegram command-name/description normalization and duplicate/conflict checks, even when the bundled Telegram contract surface is unavailable |
166169
| `plugin-sdk/text-autolink-runtime` | File-reference autolink detection without the broad text-runtime barrel |
167170
| `plugin-sdk/approval-runtime` | Exec/plugin approval helpers, approval-capability builders, auth/profile helpers, native routing/runtime helpers, and structured approval display path formatting |
@@ -170,7 +173,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
170173
| `plugin-sdk/reply-history` | Shared short-window reply-history helpers such as `buildHistoryContext`, `recordPendingHistoryEntry`, and `clearHistoryEntriesIfEnabled` |
171174
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
172175
| `plugin-sdk/reply-chunking` | Narrow text/markdown chunking helpers |
173-
| `plugin-sdk/session-store-runtime` | Session store path + updated-at helpers |
176+
| `plugin-sdk/session-store-runtime` | Session store path, session-key, updated-at, and store mutation helpers |
177+
| `plugin-sdk/cron-store-runtime` | Cron store path/load/save helpers |
174178
| `plugin-sdk/state-paths` | State/OAuth dir path helpers |
175179
| `plugin-sdk/routing` | Route/session-key/account binding helpers such as `resolveAgentRoute`, `buildAgentSessionKey`, and `resolveDefaultAgentBoundAccountId` |
176180
| `plugin-sdk/status-helpers` | Shared channel/account status summary helpers, runtime-state defaults, and issue metadata helpers |
@@ -184,6 +188,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
184188
| `plugin-sdk/temp-path` | Shared temp-download path helpers |
185189
| `plugin-sdk/logging-core` | Subsystem logger and redaction helpers |
186190
| `plugin-sdk/markdown-table-runtime` | Markdown table mode and conversion helpers |
191+
| `plugin-sdk/model-session-runtime` | Model/session override helpers such as `applyModelOverrideToSessionEntry` and `resolveAgentMaxConcurrent` |
192+
| `plugin-sdk/talk-config-runtime` | Talk provider config resolution helpers |
187193
| `plugin-sdk/json-store` | Small JSON state read/write helpers |
188194
| `plugin-sdk/file-lock` | Re-entrant file-lock helpers |
189195
| `plugin-sdk/persistent-dedupe` | Disk-backed dedupe cache helpers |
@@ -207,7 +213,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
207213
| `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch without proxy/guarded-fetch imports |
208214
| `plugin-sdk/response-limit-runtime` | Bounded response-body reader without the broad media runtime surface |
209215
| `plugin-sdk/session-binding-runtime` | Current conversation binding state without configured binding routing or pairing stores |
210-
| `plugin-sdk/session-store-runtime` | Session-store read helpers without broad config writes/maintenance imports |
216+
| `plugin-sdk/session-store-runtime` | Session-store helpers without broad config writes/maintenance imports |
211217
| `plugin-sdk/context-visibility-runtime` | Context visibility resolution and supplemental context filtering without broad config/security imports |
212218
| `plugin-sdk/string-coerce-runtime` | Narrow primitive record/string coercion and normalization helpers without markdown/logging imports |
213219
| `plugin-sdk/host-runtime` | Hostname and SCP host normalization helpers |

‎extensions/active-memory/index.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,16 @@ import {
99
resolveAgentWorkspaceDir,
1010
resolveDefaultModelForAgent,
1111
} from "openclaw/plugin-sdk/agent-runtime";
12+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
1213
import {
1314
resolveLivePluginConfigObject,
1415
resolvePluginConfigObject,
16+
} from "openclaw/plugin-sdk/plugin-config-runtime";
17+
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
18+
import {
1519
resolveSessionStoreEntry,
1620
updateSessionStore,
17-
type OpenClawConfig,
18-
} from "openclaw/plugin-sdk/config-runtime";
19-
import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
21+
} from "openclaw/plugin-sdk/session-store-runtime";
2022
import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
2123

2224
const DEFAULT_TIMEOUT_MS = 15_000;

‎extensions/amazon-bedrock/register.sync.runtime.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { StreamFn } from "@mariozechner/pi-agent-core";
2-
import { resolvePluginConfigObject, type OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
2+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
3+
import { resolvePluginConfigObject } from "openclaw/plugin-sdk/plugin-config-runtime";
34
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
45
import {
56
ANTHROPIC_BY_MODEL_REPLAY_HOOKS,

‎extensions/bluebubbles/src/accounts.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import {
44
resolveMergedAccountConfig,
55
} from "openclaw/plugin-sdk/account-resolution";
66
import { resolveChannelStreamingChunkMode } from "openclaw/plugin-sdk/channel-streaming";
7-
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
7+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
88
import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
99
import {
1010
normalizeBlueBubblesAccountsMap,

‎extensions/bluebubbles/src/config-apply.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
2-
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
2+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
33

44
type BlueBubblesConfigPatch = {
55
serverUrl?: string;

‎extensions/bluebubbles/src/conversation-bindings.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
1+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
22
import {
33
__testing as sessionBindingTesting,
44
getSessionBindingService,

‎extensions/bluebubbles/src/conversation-bindings.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
1+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
22
import {
33
createAccountScopedConversationBindingManager,
44
resetAccountScopedConversationBindingsForTests,

‎extensions/bluebubbles/src/conversation-route.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
1+
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
22
import {
33
__testing as sessionBindingTesting,
44
registerSessionBindingAdapter,

0 commit comments

Comments
 (0)