Skip to content

Commit 827b0de

Browse files
steipetesteipete
committed
refactor: reduce plugin sdk surface
1 parent 273a2e1 commit 827b0de

1,172 files changed

Lines changed: 18292 additions & 2187 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.

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ Docs: https://docs.openclaw.ai
66

77
### Changes
88

9+
- Plugin SDK: deprecate public subpaths that existed for at least one month and have no bundled extension production imports, keep legacy barrel/test/zod subpath package exports for backwards compatibility, and track both sets in the SDK surface report.
10+
- Plugin SDK: remove the owner-specific `provider-auth-login` public subpath after moving Chutes, GitHub Copilot, and OpenAI Codex auth flows back to provider-owned modules.
11+
- Plugin SDK: remove provider-specific model, stream, and xAI compatibility helpers from public exports after moving bundled callers to provider-owned modules.
912
- QA/Mantis: add Telegram live PR evidence automation with Convex-leased credentials, Crabbox transcript capture, motion GIF previews, and inline PR comments.
1013
- QA/Mantis: add a Telegram desktop scenario builder that leases Crabbox, installs native Telegram Desktop, configures an OpenClaw Telegram gateway with leased bot credentials, and records VNC screenshot/video artifacts.
1114
- Discord/voice: add realtime voice diagnostics for speaker turns, playback resets, barge-in detection, and audio cutoff analysis.

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

Lines changed: 13373 additions & 0 deletions
Large diffs are not rendered by default.

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

Lines changed: 1478 additions & 0 deletions
Large diffs are not rendered by default.

‎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-
32f0b7801c9e5e0b7ec8d7da11cec62713e968abf056560ad6372aac877fdf14 plugin-sdk-api-baseline.json
2-
e26cfb7da5e6e8addd0bd4669bd53a4188c53f8371cb20216d854f7dd0154b1b plugin-sdk-api-baseline.jsonl
1+
dd840593b93b3ee264cef645f7ba65a04c5049fe71d7d0877c29e95e4a6405f7 plugin-sdk-api-baseline.json
2+
bec5bda680942c05400a3d74685202d631682fb6c1b8512da660e5679f65b0e7 plugin-sdk-api-baseline.jsonl

‎docs/plugins/architecture-internals.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -645,7 +645,7 @@ plugin fields. See [Channel plugins](/plugins/sdk-channel-plugins).
645645
Runtime and config helpers live under matching focused `*-runtime` subpaths
646646
(`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`,
647647
`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`,
648-
`channel-activity-runtime`, etc.). Prefer `config-types`,
648+
`channel-activity-runtime`, etc.). Prefer `config-contracts`,
649649
`plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation`
650650
instead of the broad `config-runtime` compatibility barrel.
651651

‎docs/plugins/sdk-migration.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,7 @@ releases.
275275

276276
| Need | Import |
277277
| --- | --- |
278-
| Config types such as `OpenClawConfig` | `openclaw/plugin-sdk/config-types` |
278+
| Config types such as `OpenClawConfig` | `openclaw/plugin-sdk/config-contracts` |
279279
| Already-loaded config assertions and plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime` |
280280
| Current runtime snapshot reads | `openclaw/plugin-sdk/runtime-config-snapshot` |
281281
| Config writes | `openclaw/plugin-sdk/config-mutation` |
@@ -535,7 +535,7 @@ releases.
535535
| `plugin-sdk/process-runtime` | Process helpers | Shared exec helpers |
536536
| `plugin-sdk/cli-runtime` | CLI runtime helpers | Command formatting, waits, version helpers |
537537
| `plugin-sdk/gateway-runtime` | Gateway helpers | Gateway client, event-loop-ready start helper, and channel-status patch helpers |
538-
| `plugin-sdk/config-runtime` | Deprecated config compatibility shim | Prefer `config-types`, `plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation` |
538+
| `plugin-sdk/config-runtime` | Deprecated config compatibility shim | Prefer `config-contracts`, `plugin-config-runtime`, `runtime-config-snapshot`, and `config-mutation` |
539539
| `plugin-sdk/telegram-command-config` | Telegram command helpers | Fallback-stable Telegram command validation helpers when the bundled Telegram contract surface is unavailable |
540540
| `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 |
541541
| `plugin-sdk/approval-auth-runtime` | Approval auth helpers | Approver resolution, same-chat action auth |
@@ -595,7 +595,6 @@ releases.
595595
| `plugin-sdk/provider-auth-runtime` | Provider runtime auth helpers | Runtime API-key resolution helpers |
596596
| `plugin-sdk/provider-auth-api-key` | Provider API-key setup helpers | API-key onboarding/profile-write helpers |
597597
| `plugin-sdk/provider-auth-result` | Provider auth-result helpers | Standard OAuth auth-result builder |
598-
| `plugin-sdk/provider-auth-login` | Provider interactive login helpers | Shared interactive login helpers |
599598
| `plugin-sdk/provider-selection-runtime` | Provider selection helpers | Configured-or-auto provider selection and raw provider config merging |
600599
| `plugin-sdk/provider-env-vars` | Provider env-var helpers | Provider auth env-var lookup helpers |
601600
| `plugin-sdk/provider-model-shared` | Shared provider model/replay helpers | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, shared replay-policy builders, provider-endpoint helpers, and model-id normalization helpers |
@@ -606,15 +605,15 @@ releases.
606605
| `plugin-sdk/provider-web-search-config-contract` | Provider web-search config helpers | Narrow web-search config/credential helpers for providers that do not need plugin-enable wiring |
607606
| `plugin-sdk/provider-web-search-contract` | Provider web-search contract helpers | Narrow web-search config/credential contract helpers such as `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, and scoped credential setters/getters |
608607
| `plugin-sdk/provider-web-search` | Provider web-search helpers | Web-search provider registration/cache/runtime helpers |
609-
| `plugin-sdk/provider-tools` | Provider tool/schema compat helpers | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema cleanup + diagnostics, and xAI compat helpers such as `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
608+
| `plugin-sdk/provider-tools` | Provider tool/schema compat helpers | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, and Gemini schema cleanup + diagnostics |
610609
| `plugin-sdk/provider-usage` | Provider usage helpers | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, and other provider usage helpers |
611610
| `plugin-sdk/provider-stream` | Provider stream wrapper helpers | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper types, and shared Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helpers |
612611
| `plugin-sdk/provider-transport-runtime` | Provider transport helpers | Native provider transport helpers such as guarded fetch, transport message transforms, and writable transport event streams |
613612
| `plugin-sdk/keyed-async-queue` | Ordered async queue | `KeyedAsyncQueue` |
614613
| `plugin-sdk/media-runtime` | Shared media helpers | Media fetch/transform/store helpers, ffprobe-backed video dimension probing, and media payload builders |
615614
| `plugin-sdk/media-generation-runtime` | Shared media-generation helpers | Shared failover helpers, candidate selection, and missing-model messaging for image/video/music generation |
616615
| `plugin-sdk/media-understanding` | Media-understanding helpers | Media understanding provider types plus provider-facing image/audio helper exports |
617-
| `plugin-sdk/text-runtime` | Shared text helpers | Assistant-visible-text stripping, markdown render/chunking/table helpers, redaction helpers, directive-tag helpers, safe-text utilities, and related text/logging helpers |
616+
| `plugin-sdk/text-runtime` | Deprecated broad text compatibility export | Use `string-coerce-runtime`, `text-chunking`, `text-utility-runtime`, and `logging-core` |
618617
| `plugin-sdk/text-chunking` | Text chunking helpers | Outbound text chunking helper |
619618
| `plugin-sdk/speech` | Speech helpers | Speech provider types plus provider-facing directive, registry, validation helpers, and OpenAI-compatible TTS builder |
620619
| `plugin-sdk/speech-core` | Shared speech core | Speech provider types, registry, directives, normalization |
@@ -638,7 +637,7 @@ releases.
638637
| `plugin-sdk/webhook-targets` | Webhook target helpers | Webhook target registry and route-install helpers |
639638
| `plugin-sdk/webhook-path` | Webhook path helpers | Webhook path normalization helpers |
640639
| `plugin-sdk/web-media` | Shared web media helpers | Remote/local media loading helpers |
641-
| `plugin-sdk/zod` | Zod re-export | Re-exported `zod` for plugin SDK consumers |
640+
| `plugin-sdk/zod` | Deprecated Zod compatibility re-export | Import `zod` from `zod` directly |
642641
| `plugin-sdk/memory-core` | Bundled memory-core helpers | Memory manager/config/file/CLI helper surface |
643642
| `plugin-sdk/memory-core-engine-runtime` | Memory engine runtime facade | Memory index/search runtime facade |
644643
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine | Memory host foundation engine exports |
@@ -659,12 +658,13 @@ releases.
659658
| `plugin-sdk/memory-host-markdown` | Managed markdown helpers | Shared managed-markdown helpers for memory-adjacent plugins |
660659
| `plugin-sdk/memory-host-search` | Active memory search facade | Lazy active-memory search-manager runtime facade |
661660
| `plugin-sdk/memory-host-status` | Memory host status alias | Vendor-neutral alias for memory host status helpers |
662-
| `plugin-sdk/testing` | Test utilities | Legacy broad compatibility barrel; prefer focused test subpaths such as `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env`, and `plugin-sdk/test-fixtures` |
661+
| `plugin-sdk/testing` | Test utilities | Repo-local deprecated compatibility barrel; use focused repo-local test subpaths such as `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env`, and `plugin-sdk/test-fixtures` |
663662
</Accordion>
664663

665664
This table is intentionally the common migration subset, not the full SDK
666-
surface. The full list of 200+ entrypoints lives in
667-
`scripts/lib/plugin-sdk-entrypoints.json`.
665+
surface. The compiler entrypoint inventory lives in
666+
`scripts/lib/plugin-sdk-entrypoints.json`; package exports are generated from
667+
the public subset.
668668

669669
Reserved bundled-plugin helper seams have been retired from the public SDK
670670
export map except for explicitly documented compatibility facades such as the

‎docs/plugins/sdk-overview.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,15 @@ entry, channel, provider, auth, runtime, capability, memory, and reserved
7272
bundled-plugin helpers). For the full catalog — grouped and linked — see
7373
[Plugin SDK subpaths](/plugins/sdk-subpaths).
7474

75-
The generated list of 200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`.
75+
The compiler entrypoint inventory lives in
76+
`scripts/lib/plugin-sdk-entrypoints.json`; package exports are generated from
77+
the public subset after subtracting repo-local test/internal subpaths listed in
78+
`scripts/lib/plugin-sdk-private-local-only-subpaths.json`. Run
79+
`pnpm plugin-sdk:surface` to audit the public export count. Deprecated public
80+
subpaths that are old enough and unused by bundled extension production code are
81+
tracked in `scripts/lib/plugin-sdk-deprecated-public-subpaths.json`; broad
82+
deprecated re-export barrels are tracked in
83+
`scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json`.
7684

7785
## Registration API
7886

‎docs/plugins/sdk-provider-plugins.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -367,9 +367,9 @@ API key auth, and dynamic model resolution.
367367
<Accordion title="SDK seams powering the family builders">
368368
Each family builder is composed from lower-level public helpers exported from the same package, which you can reach for when a provider needs to go off the common pattern:
369369

370-
- `openclaw/plugin-sdk/provider-model-shared` - `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)`, and the raw replay builders (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Also exports Gemini replay helpers (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) and endpoint/model helpers (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`).
370+
- `openclaw/plugin-sdk/provider-model-shared` - `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)`, and the raw replay builders (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Also exports Gemini replay helpers (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) and endpoint/model helpers (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`).
371371
- `openclaw/plugin-sdk/provider-stream` - `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, plus the shared OpenAI/Codex wrappers (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), DeepSeek V4 OpenAI-compatible wrapper (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), Anthropic Messages thinking prefill cleanup (`createAnthropicThinkingPrefillPayloadWrapper`), and shared proxy/provider wrappers (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`).
372-
- `openclaw/plugin-sdk/provider-tools` - `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, underlying Gemini schema helpers (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`), and xAI compat helpers (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). The bundled xAI plugin uses `normalizeResolvedModel` + `contributeResolvedModelCompat` with these to keep xAI rules owned by the provider.
372+
- `openclaw/plugin-sdk/provider-tools` - `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, and underlying Gemini schema helpers (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`).
373373

374374
Some stream helpers stay provider-local on purpose. `@openclaw/anthropic-provider` keeps `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, and the lower-level Anthropic wrapper builders in its own public `api.ts` / `contract-api.ts` seam because they encode Claude OAuth beta handling and `context1m` gating. The xAI plugin similarly keeps native xAI Responses shaping in its own `wrapStreamFn` (`/fast` aliases, default `tool_stream`, unsupported strict-tool cleanup, xAI-specific reasoning-payload removal).
375375

‎docs/plugins/sdk-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ The mutation helpers return `afterWrite` plus a typed `followUp` summary so call
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 remain available for old external plugins during the migration window. Bundled plugins must not use them; the config boundary guards fail if plugin code calls them or imports those helpers from plugin SDK subpaths.
4545

4646
For direct SDK imports, use the focused config subpaths instead of the broad
47-
`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-types` for
47+
`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-contracts` for
4848
types, `plugin-config-runtime` for already-loaded config assertions and plugin
4949
entry lookup, `runtime-config-snapshot` for current process snapshots, and
5050
`config-mutation` for writes. Bundled plugin tests should mock these focused

0 commit comments

Comments
 (0)