Skip to content

Commit 62ddc9d

Browse files
steipetesteipete
committed
refactor: consolidate plugin sdk surface
1 parent 46854a8 commit 62ddc9d

294 files changed

Lines changed: 2066 additions & 1263 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/architecture.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -933,25 +933,31 @@ authoring plugins:
933933
- `openclaw/plugin-sdk/core` for the generic shared plugin-facing contract.
934934
- Stable channel primitives such as `openclaw/plugin-sdk/channel-setup`,
935935
`openclaw/plugin-sdk/channel-pairing`,
936+
`openclaw/plugin-sdk/channel-contract`,
937+
`openclaw/plugin-sdk/channel-feedback`,
938+
`openclaw/plugin-sdk/channel-inbound`,
939+
`openclaw/plugin-sdk/channel-lifecycle`,
936940
`openclaw/plugin-sdk/channel-reply-pipeline`,
941+
`openclaw/plugin-sdk/command-auth`,
937942
`openclaw/plugin-sdk/secret-input`, and
938943
`openclaw/plugin-sdk/webhook-ingress` for shared setup/auth/reply/webhook
939-
wiring.
944+
wiring. `channel-inbound` is the shared home for debounce, mention matching,
945+
envelope formatting, and inbound envelope context helpers.
940946
- Domain subpaths such as `openclaw/plugin-sdk/channel-config-helpers`,
947+
`openclaw/plugin-sdk/allow-from`,
941948
`openclaw/plugin-sdk/channel-config-schema`,
942949
`openclaw/plugin-sdk/channel-policy`,
943-
`openclaw/plugin-sdk/channel-runtime`,
944950
`openclaw/plugin-sdk/config-runtime`,
951+
`openclaw/plugin-sdk/infra-runtime`,
945952
`openclaw/plugin-sdk/agent-runtime`,
946953
`openclaw/plugin-sdk/lazy-runtime`,
947954
`openclaw/plugin-sdk/reply-history`,
948955
`openclaw/plugin-sdk/routing`,
956+
`openclaw/plugin-sdk/status-helpers`,
949957
`openclaw/plugin-sdk/runtime-store`, and
950958
`openclaw/plugin-sdk/directory-runtime` for shared runtime/config helpers.
951-
- Narrow channel-core subpaths such as `openclaw/plugin-sdk/discord-core`,
952-
`openclaw/plugin-sdk/telegram-core`, and `openclaw/plugin-sdk/whatsapp-core`
953-
for channel-specific primitives that should stay smaller than the full
954-
channel helper barrels.
959+
- `openclaw/plugin-sdk/channel-runtime` remains only as a compatibility shim.
960+
New code should import the narrower primitives instead.
955961
- Bundled extension internals remain private. External plugins should use only
956962
`openclaw/plugin-sdk/*` subpaths. OpenClaw core/test code may use the repo
957963
public entry points under `extensions/<id>/index.js`, `api.js`, `runtime-api.js`,
@@ -962,26 +968,25 @@ authoring plugins:
962968
`extensions/<id>/runtime-api.js` is the runtime-only barrel,
963969
`extensions/<id>/index.js` is the bundled plugin entry,
964970
and `extensions/<id>/setup-entry.js` is the setup plugin entry.
965-
- `openclaw/plugin-sdk/telegram` for Telegram channel plugin types and shared channel-facing helpers. Built-in Telegram implementation internals stay private to the bundled extension.
966-
- `openclaw/plugin-sdk/discord` for Discord channel plugin types and shared channel-facing helpers. Built-in Discord implementation internals stay private to the bundled extension.
967-
- `openclaw/plugin-sdk/slack` for Slack channel plugin types and shared channel-facing helpers. Built-in Slack implementation internals stay private to the bundled extension.
968-
- `openclaw/plugin-sdk/imessage` for iMessage channel plugin types and shared channel-facing helpers. Built-in iMessage implementation internals stay private to the bundled extension.
969-
- `openclaw/plugin-sdk/whatsapp` for WhatsApp channel plugin types and shared channel-facing helpers. Built-in WhatsApp implementation internals stay private to the bundled extension.
970-
- `openclaw/plugin-sdk/bluebubbles` remains public because it carries a small
971-
focused helper surface that is shared intentionally.
971+
- No bundled channel-branded public subpaths remain. Channel-specific helper and
972+
runtime seams live under `extensions/<id>/api.js` and `extensions/<id>/runtime-api.js`;
973+
the public SDK contract is the generic shared primitives instead.
972974

973975
Compatibility note:
974976

975977
- Avoid the root `openclaw/plugin-sdk` barrel for new code.
976978
- Prefer the narrow stable primitives first. The newer setup/pairing/reply/
977-
secret-input/webhook subpaths are the intended contract for new bundled and
978-
external plugin work.
979+
feedback/contract/inbound/threading/command/secret-input/webhook/infra/
980+
allowlist/status/message-tool subpaths are the intended contract for new
981+
bundled and external plugin work.
982+
Target parsing/matching belongs on `openclaw/plugin-sdk/channel-targets`.
983+
Message action gates and reaction message-id helpers belong on
984+
`openclaw/plugin-sdk/channel-actions`.
979985
- Bundled extension-specific helper barrels are not stable by default. If a
980986
helper is only needed by a bundled extension, keep it behind the extension's
981987
local `api.js` or `runtime-api.js` seam instead of promoting it into
982988
`openclaw/plugin-sdk/<extension>`.
983-
- Channel-branded bundled bars such as `feishu`, `googlechat`, `irc`, `line`,
984-
`nostr`, `twitch`, and `zalo` stay private unless they are explicitly added
989+
- Channel-branded bundled bars stay private unless they are explicitly added
985990
back to the public contract.
986991
- Capability-specific subpaths such as `image-generation`,
987992
`media-understanding`, and `speech` exist because bundled/native plugins use
@@ -994,7 +999,7 @@ Plugins should own channel-specific `describeMessageTool(...)` schema
994999
contributions. Keep provider-specific fields in the plugin, not in shared core.
9951000

9961001
For shared portable schema fragments, reuse the generic helpers exported through
997-
`openclaw/plugin-sdk/channel-runtime`:
1002+
`openclaw/plugin-sdk/channel-actions`:
9981003

9991004
- `createMessageToolButtonsSchema()` for button-grid style payloads
10001005
- `createMessageToolCardSchema()` for structured card payloads

‎extensions/bluebubbles/src/actions.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
21
import { describe, expect, it, vi, beforeEach } from "vitest";
32
import { bluebubblesMessageActions } from "./actions.js";
43
import { sendBlueBubblesAttachment } from "./attachments.js";
54
import { editBlueBubblesMessage, setGroupIconBlueBubbles } from "./chat.js";
65
import { resolveBlueBubblesMessageId } from "./monitor.js";
76
import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
87
import { sendBlueBubblesReaction } from "./reactions.js";
8+
import type { OpenClawConfig } from "./runtime-api.js";
99
import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
1010

1111
vi.mock("./accounts.js", async () => {

‎extensions/bluebubbles/src/attachments.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
21
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
3-
import "./test-mocks.js";
42
import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
3+
import "./test-mocks.js";
54
import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
5+
import type { PluginRuntime } from "./runtime-api.js";
66
import { setBlueBubblesRuntime } from "./runtime.js";
77
import {
88
BLUE_BUBBLES_PRIVATE_API_STATUS,

‎extensions/bluebubbles/src/channel.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ import {
44
createScopedDmSecurityResolver,
55
} from "openclaw/plugin-sdk/channel-config-helpers";
66
import { createAccountStatusSink } from "openclaw/plugin-sdk/channel-lifecycle";
7+
import {
8+
createPairingPrefixStripper,
9+
createTextPairingAdapter,
10+
} from "openclaw/plugin-sdk/channel-pairing";
711
import {
812
createOpenGroupPolicyRestrictSendersWarningCollector,
913
projectWarningCollector,
1014
} from "openclaw/plugin-sdk/channel-policy";
11-
import {
12-
createAttachedChannelResultAdapter,
13-
createPairingPrefixStripper,
14-
createTextPairingAdapter,
15-
} from "openclaw/plugin-sdk/channel-runtime";
15+
import { createAttachedChannelResultAdapter } from "openclaw/plugin-sdk/channel-send-result";
1616
import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
1717
import {
1818
listBlueBubblesAccountIds,

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ import fs from "node:fs/promises";
22
import os from "node:os";
33
import path from "node:path";
44
import { pathToFileURL } from "node:url";
5-
import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
65
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
76
import { sendBlueBubblesMedia } from "./media-send.js";
7+
import type { OpenClawConfig, PluginRuntime } from "./runtime-api.js";
88
import { setBlueBubblesRuntime } from "./runtime.js";
99

1010
const sendBlueBubblesAttachmentMock = vi.hoisted(() => vi.fn());

‎extensions/bluebubbles/src/monitor.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
import { EventEmitter } from "node:events";
22
import type { IncomingMessage, ServerResponse } from "node:http";
3-
import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
43
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
54
import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js";
65
import type { ResolvedBlueBubblesAccount } from "./accounts.js";
@@ -12,6 +11,7 @@ import {
1211
resolveBlueBubblesMessageId,
1312
_resetBlueBubblesShortIdState,
1413
} from "./monitor.js";
14+
import type { OpenClawConfig, PluginRuntime } from "./runtime-api.js";
1515
import { setBlueBubblesRuntime } from "./runtime.js";
1616

1717
// Mock dependencies

‎extensions/bluebubbles/src/monitor.webhook-auth.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
import { EventEmitter } from "node:events";
22
import type { IncomingMessage, ServerResponse } from "node:http";
3-
import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
43
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
54
import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js";
65
import type { ResolvedBlueBubblesAccount } from "./accounts.js";
@@ -11,6 +10,7 @@ import {
1110
resolveBlueBubblesMessageId,
1211
_resetBlueBubblesShortIdState,
1312
} from "./monitor.js";
13+
import type { OpenClawConfig, PluginRuntime } from "./runtime-api.js";
1414
import { setBlueBubblesRuntime } from "./runtime.js";
1515

1616
// Mock dependencies

‎extensions/bluebubbles/src/monitor.webhook-route.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
21
import { afterEach, describe, expect, it } from "vitest";
32
import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js";
43
import { setActivePluginRegistry } from "../../../src/plugins/runtime.js";
54
import type { WebhookTarget } from "./monitor-shared.js";
65
import { registerBlueBubblesWebhookTarget } from "./monitor.js";
6+
import type { OpenClawConfig } from "./runtime-api.js";
77

88
function createTarget(): WebhookTarget {
99
return {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
export * from "openclaw/plugin-sdk/bluebubbles";
1+
export * from "../../../src/plugin-sdk/bluebubbles.js";

‎extensions/bluebubbles/src/send.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
21
import { beforeEach, describe, expect, it, vi } from "vitest";
3-
import "./test-mocks.js";
42
import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
3+
import "./test-mocks.js";
4+
import type { PluginRuntime } from "./runtime-api.js";
55
import { clearBlueBubblesRuntime, setBlueBubblesRuntime } from "./runtime.js";
66
import { sendMessageBlueBubbles, resolveChatGuidForTarget, createChatForHandle } from "./send.js";
77
import {

0 commit comments

Comments
 (0)