Skip to content

fix: isolate plugin test helpers from sdk exports #87120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RomneyDa merged 1 commit into from
May 27, 2026
Merged

fix: isolate plugin test helpers from sdk exports #87120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions docs/plugins/sdk-subpaths.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,17 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)

### Deprecated compatibility and test helpers

These subpaths remain package exports for older plugins and OpenClaw test suites,
but new code should not add imports from them: `agent-runtime-test-contracts`,
These subpaths remain package exports for older plugins, but new code should not
add imports from them: `channel-runtime`, `compat`, `config-types`,
`infra-runtime`, `text-runtime`, and `zod`. Import `zod` directly from `zod` in
new plugin code.

OpenClaw's Vitest-backed test-helper subpaths are repo-local only and are no
longer package exports: `agent-runtime-test-contracts`,
`channel-contract-testing`, `channel-target-testing`, `channel-test-helpers`,
`plugin-test-api`, `plugin-test-contracts`, `provider-http-test-mocks`,
`provider-test-contracts`, `test-env`, `test-fixtures`, `test-node-mocks`,
`testing`, `channel-runtime`, `compat`, `config-types`, `infra-runtime`,
`text-runtime`, and `zod`. Import `zod` directly from `zod` in new plugin code.
`plugin-test-runtime` is still an active focused test helper subpath.
`plugin-test-api`, `plugin-test-contracts`, `plugin-test-runtime`,
`provider-http-test-mocks`, `provider-test-contracts`, `test-env`,
`test-fixtures`, `test-node-mocks`, and `testing`.

### Reserved bundled plugin helper subpaths

Expand Down
6 changes: 4 additions & 2 deletions docs/plugins/sdk-testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ plugins.
## Test utilities

These test-helper subpaths are repo-local source entrypoints for OpenClaw's own
bundled plugin tests. They are not package exports for third-party plugins.
bundled plugin tests. They are not package exports for third-party plugins, and
they may import Vitest or other repo-only test dependencies.

**Plugin API mock import:** `openclaw/plugin-sdk/plugin-test-api`

Expand All @@ -46,7 +47,8 @@ bundled plugin tests. They are not package exports for third-party plugins.

**Node builtin mock import:** `openclaw/plugin-sdk/test-node-mocks`

Prefer the focused subpaths below for new plugin tests. The broad
Inside the OpenClaw repo, prefer the focused subpaths below for new bundled
plugin tests. The broad
`openclaw/plugin-sdk/testing` barrel is legacy compatibility only.
Repo guardrails reject new real imports from `plugin-sdk/testing` and
`plugin-sdk/test-utils`; those names remain only as deprecated compatibility
Expand Down
82 changes: 30 additions & 52 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,36 @@
"!dist/.runtime-postbuildstamp",
"!dist/**/*.map",
"!dist/plugin-sdk/.tsbuildinfo",
"!dist/plugin-sdk/agent-runtime-test-contracts.js",
"!dist/plugin-sdk/agent-runtime-test-contracts.d.ts",
"!dist/plugin-sdk/channel-contract-testing.js",
"!dist/plugin-sdk/channel-contract-testing.d.ts",
"!dist/plugin-sdk/channel-target-testing.js",
"!dist/plugin-sdk/channel-target-testing.d.ts",
"!dist/plugin-sdk/channel-test-helpers.js",
"!dist/plugin-sdk/channel-test-helpers.d.ts",
"!dist/plugin-sdk/plugin-test-api.js",
"!dist/plugin-sdk/plugin-test-api.d.ts",
"!dist/plugin-sdk/plugin-test-contracts.js",
"!dist/plugin-sdk/plugin-test-contracts.d.ts",
"!dist/plugin-sdk/plugin-test-runtime.js",
"!dist/plugin-sdk/plugin-test-runtime.d.ts",
"!dist/plugin-sdk/provider-http-test-mocks.js",
"!dist/plugin-sdk/provider-http-test-mocks.d.ts",
"!dist/plugin-sdk/provider-test-contracts.js",
"!dist/plugin-sdk/provider-test-contracts.d.ts",
"!dist/plugin-sdk/test-env.js",
"!dist/plugin-sdk/test-env.d.ts",
"!dist/plugin-sdk/test-fixtures.js",
"!dist/plugin-sdk/test-fixtures.d.ts",
"!dist/plugin-sdk/test-node-mocks.js",
"!dist/plugin-sdk/test-node-mocks.d.ts",
"!dist/plugin-sdk/testing.js",
"!dist/plugin-sdk/testing.d.ts",
"!dist/plugin-sdk/src/agents/test-helpers/**",
"!dist/plugin-sdk/src/test-helpers/**",
"!dist/plugin-sdk/src/test-utils/**",
"!dist/plugin-sdk/src/plugin-sdk/test-helpers/**",
"!dist/extensions/acpx/**",
"!dist/extensions/amazon-bedrock/**",
"!dist/extensions/amazon-bedrock-mantle/**",
Expand Down Expand Up @@ -570,54 +600,6 @@
"types": "./dist/plugin-sdk/lazy-runtime.d.ts",
"default": "./dist/plugin-sdk/lazy-runtime.js"
},
"./plugin-sdk/agent-runtime-test-contracts": {
"types": "./dist/plugin-sdk/agent-runtime-test-contracts.d.ts",
"default": "./dist/plugin-sdk/agent-runtime-test-contracts.js"
},
"./plugin-sdk/channel-target-testing": {
"types": "./dist/plugin-sdk/channel-target-testing.d.ts",
"default": "./dist/plugin-sdk/channel-target-testing.js"
},
"./plugin-sdk/channel-test-helpers": {
"types": "./dist/plugin-sdk/channel-test-helpers.d.ts",
"default": "./dist/plugin-sdk/channel-test-helpers.js"
},
"./plugin-sdk/plugin-test-api": {
"types": "./dist/plugin-sdk/plugin-test-api.d.ts",
"default": "./dist/plugin-sdk/plugin-test-api.js"
},
"./plugin-sdk/plugin-test-contracts": {
"types": "./dist/plugin-sdk/plugin-test-contracts.d.ts",
"default": "./dist/plugin-sdk/plugin-test-contracts.js"
},
"./plugin-sdk/plugin-test-runtime": {
"types": "./dist/plugin-sdk/plugin-test-runtime.d.ts",
"default": "./dist/plugin-sdk/plugin-test-runtime.js"
},
"./plugin-sdk/provider-http-test-mocks": {
"types": "./dist/plugin-sdk/provider-http-test-mocks.d.ts",
"default": "./dist/plugin-sdk/provider-http-test-mocks.js"
},
"./plugin-sdk/provider-test-contracts": {
"types": "./dist/plugin-sdk/provider-test-contracts.d.ts",
"default": "./dist/plugin-sdk/provider-test-contracts.js"
},
"./plugin-sdk/test-env": {
"types": "./dist/plugin-sdk/test-env.d.ts",
"default": "./dist/plugin-sdk/test-env.js"
},
"./plugin-sdk/test-fixtures": {
"types": "./dist/plugin-sdk/test-fixtures.d.ts",
"default": "./dist/plugin-sdk/test-fixtures.js"
},
"./plugin-sdk/test-node-mocks": {
"types": "./dist/plugin-sdk/test-node-mocks.d.ts",
"default": "./dist/plugin-sdk/test-node-mocks.js"
},
"./plugin-sdk/testing": {
"types": "./dist/plugin-sdk/testing.d.ts",
"default": "./dist/plugin-sdk/testing.js"
},
"./plugin-sdk/temp-path": {
"types": "./dist/plugin-sdk/temp-path.d.ts",
"default": "./dist/plugin-sdk/temp-path.js"
Expand Down Expand Up @@ -686,10 +668,6 @@
"types": "./dist/plugin-sdk/boolean-param.d.ts",
"default": "./dist/plugin-sdk/boolean-param.js"
},
"./plugin-sdk/channel-contract-testing": {
"types": "./dist/plugin-sdk/channel-contract-testing.d.ts",
"default": "./dist/plugin-sdk/channel-contract-testing.js"
},
"./plugin-sdk/dangerous-name-runtime": {
"types": "./dist/plugin-sdk/dangerous-name-runtime.d.ts",
"default": "./dist/plugin-sdk/dangerous-name-runtime.js"
Expand Down
12 changes: 0 additions & 12 deletions scripts/lib/plugin-sdk-deprecated-public-subpaths.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
[
"agent-config-primitives",
"agent-runtime-test-contracts",
"channel-config-schema-legacy",
"channel-contract-testing",
"channel-reply-pipeline",
"channel-runtime",
"channel-secret-runtime",
"channel-target-testing",
"channel-test-helpers",
"command-auth",
"compat",
"config-runtime",
Expand All @@ -28,11 +24,7 @@
"memory-host-files",
"memory-host-status",
"music-generation-core",
"plugin-test-api",
"plugin-test-contracts",
"provider-auth-login",
"provider-http-test-mocks",
"provider-test-contracts",
"provider-zai-endpoint",
"reply-dedupe",
"runtime-logger",
Expand All @@ -41,10 +33,6 @@
"setup-adapter-runtime",
"telegram-account",
"telegram-command-config",
"test-env",
"test-fixtures",
"test-node-mocks",
"testing",
"text-runtime",
"webhook-path",
"zalouser",
Expand Down
2 changes: 1 addition & 1 deletion scripts/lib/plugin-sdk-entries.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ export function buildPluginSdkPackageExports() {
}

export function listPluginSdkDistArtifacts() {
return pluginSdkEntrypoints.flatMap((entry) => [
return publicPluginSdkEntrypoints.flatMap((entry) => [
`dist/plugin-sdk/${entry}.js`,
`dist/plugin-sdk/${entry}.d.ts`,
]);
Expand Down
15 changes: 14 additions & 1 deletion scripts/lib/plugin-sdk-private-local-only-subpaths.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,22 @@
[
"agent-runtime-test-contracts",
"channel-contract-testing",
"channel-target-testing",
"channel-test-helpers",
"codex-native-task-runtime",
"plugin-test-api",
"plugin-test-contracts",
"plugin-test-runtime",
"provider-http-test-mocks",
"provider-test-contracts",
"qa-channel",
"qa-channel-protocol",
"qa-lab",
"qa-runtime",
"ssrf-runtime-internal",
"test-utils"
"test-env",
"test-fixtures",
"test-node-mocks",
"test-utils",
"testing"
]
12 changes: 5 additions & 7 deletions scripts/release-check.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,13 +124,11 @@ const laneFloorAdoptionDateKey = 20260227;
const SAFE_UNIX_SMOKE_PATH = "/usr/bin:/bin";
export const MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES = 2 * 1024 * 1024;
export const CRITICAL_PLUGIN_SDK_SIZE_CHECK_SPECIFIERS = [
"openclaw/plugin-sdk/agent-runtime-test-contracts",
"openclaw/plugin-sdk/plugin-test-contracts",
"openclaw/plugin-sdk/provider-test-contracts",
] as const;
export const CRITICAL_PLUGIN_SDK_IMPORT_SMOKE_SPECIFIERS = [
"openclaw/plugin-sdk/plugin-test-contracts",
"openclaw/plugin-sdk/core",
"openclaw/plugin-sdk/provider-entry",
"openclaw/plugin-sdk/runtime",
] as const;
export const CRITICAL_PLUGIN_SDK_IMPORT_SMOKE_SPECIFIERS = ["openclaw/plugin-sdk/core"] as const;
export const PACKED_CLI_SMOKE_COMMANDS = [
["--help"],
["onboard", "--help"],
Expand Down Expand Up @@ -939,7 +937,7 @@ export function collectCriticalPluginSdkEntrypointSizeErrors(rootDir = process.c
}
if (stat.size > MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES) {
errors.push(
`${relativePath} is ${stat.size} bytes, exceeding ${MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES} bytes. Keep public SDK test-contract entrypoints lazy and avoid bundling compiler/runtime internals.`,
`${relativePath} is ${stat.size} bytes, exceeding ${MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES} bytes. Keep public SDK package entrypoints lazy and avoid bundling compiler/runtime internals.`,
);
}
}
Expand Down
4 changes: 3 additions & 1 deletion src/agents/tools/sessions-send-tool.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,9 @@ async function startAgentRun(params: {
} catch (err) {
const queueSummary =
formatEmbeddedPiQueueFailureSummary(queueOutcome) ?? "active run queue rejected";
throw new Error(`${queueSummary}; fallback_failed error=${formatErrorMessage(err)}`);
throw new Error(`${queueSummary}; fallback_failed error=${formatErrorMessage(err)}`, {
cause: err,
});
}
}
const response = await params.callGateway<{ runId: string }>({
Expand Down
2 changes: 1 addition & 1 deletion src/plugin-sdk/entrypoints.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ export function buildPluginSdkPackageExports() {

/** List the dist artifacts expected for every generated plugin SDK entrypoint. */
export function listPluginSdkDistArtifacts() {
return pluginSdkEntrypoints.flatMap((entry) => [
return publicPluginSdkEntrypoints.flatMap((entry) => [
`dist/plugin-sdk/${entry}.js`,
`dist/plugin-sdk/${entry}.d.ts`,
]);
Expand Down
10 changes: 10 additions & 0 deletions src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -692,6 +692,16 @@ describe("plugin-sdk package contract guardrails", () => {
expect(collectPluginSdkPackageExports()).toEqual([...publicPluginSdkEntrypoints].toSorted());
});

it("keeps Vitest-backed SDK test helpers local-only", () => {
const localOnly = new Set(privateLocalOnlyPluginSdkEntrypoints);

expect(
["plugin-test-contracts", "provider-test-contracts", "testing"].every((entrypoint) =>
localOnly.has(entrypoint),
),
).toBe(true);
});

it("keeps configured local-origin fetch helpers out of deprecated infra-runtime", () => {
const source = fs.readFileSync(resolve(REPO_ROOT, "src/plugin-sdk/infra-runtime.ts"), "utf8");

Expand Down
12 changes: 6 additions & 6 deletions test/release-check.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -725,22 +725,22 @@ describe("collectPackUnpackedSizeErrors", () => {
});

describe("collectCriticalPluginSdkEntrypointSizeErrors", () => {
it("flags oversized plugin SDK test-contract entrypoints before publish", () => {
it("flags oversized public plugin SDK entrypoints before publish", () => {
const root = mkdtempSync(join(tmpdir(), "release-check-critical-sdk-"));
try {
const pluginSdkDir = join(root, "dist", "plugin-sdk");
mkdirSync(pluginSdkDir, { recursive: true });
writeFileSync(join(pluginSdkDir, "agent-runtime-test-contracts.js"), "export {};\n");
writeFileSync(join(pluginSdkDir, "provider-test-contracts.js"), "export {};\n");
writeFileSync(join(pluginSdkDir, "core.js"), "export {};\n");
writeFileSync(join(pluginSdkDir, "runtime.js"), "export {};\n");
writeFileSync(
join(pluginSdkDir, "plugin-test-contracts.js"),
join(pluginSdkDir, "provider-entry.js"),
"x".repeat(MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES + 1),
);

expect(collectCriticalPluginSdkEntrypointSizeErrors(root)).toEqual([
`dist/plugin-sdk/plugin-test-contracts.js is ${
`dist/plugin-sdk/provider-entry.js is ${
MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES + 1
} bytes, exceeding ${MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES} bytes. Keep public SDK test-contract entrypoints lazy and avoid bundling compiler/runtime internals.`,
} bytes, exceeding ${MAX_CRITICAL_PLUGIN_SDK_ENTRYPOINT_BYTES} bytes. Keep public SDK package entrypoints lazy and avoid bundling compiler/runtime internals.`,
]);
} finally {
rmSync(root, { recursive: true, force: true });
Expand Down
Loading