diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index fff931761..690839a95 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "7f3dead33564df924b13b7a44f57e1b888dc60f5", - "syncedAt": "2026-04-28T01:51:33.190Z" + "sha": "194538937459187c008e02845fdc1f75875708ad", + "syncedAt": "2026-04-28T01:53:56.080Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index 4aa0fef7c..4f52bb0a5 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -8f23f155251c05cab51ee8926e7a359bd64a0ba34e82a80d93d0ed96d07c8a04 plugin-sdk-api-baseline.json -181fea7f35c49032e6894605a06ca1419e5b6ccc1a3d8987d952a1d24a8154bc plugin-sdk-api-baseline.jsonl +31fd2178f08a4fcb28d6319eaa464b572b1e36a0fab700056f643feaccf95aa8 plugin-sdk-api-baseline.json +65b239e91e4d5f4cac71527058aa53179a8dcf65f8c50f4eabab346def966e74 plugin-sdk-api-baseline.jsonl diff --git a/docs/plugins/compatibility.md b/docs/plugins/compatibility.md index c7b686e1e..e2b50c6d1 100644 --- a/docs/plugins/compatibility.md +++ b/docs/plugins/compatibility.md @@ -67,6 +67,26 @@ Use `--json` for stable machine-readable output in CI annotations. OpenClaw core should expose contracts and fixtures the inspector can consume, but should not publish the inspector binary from the main `openclaw` package. +### Maintainer acceptance lane + +Use Blacksmith Testbox for the installable-package acceptance lane when validating +the external inspector against OpenClaw plugin packages. Run it from a clean +OpenClaw checkout after the package is built: + +```sh +blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 +blacksmith testbox run --id "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json" +blacksmith testbox run --id "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json" +blacksmith testbox run --id "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- --json" +blacksmith testbox stop +``` + +Keep this lane opt-in for maintainers because it installs an external npm +package and may inspect plugin packages cloned outside the repo. The local repo +guards cover the SDK export map, compatibility registry metadata, deprecated +SDK-import burn-down, and bundled extension import boundaries; Testbox inspector +proof covers the package as external plugin authors consume it. + ## Deprecation policy OpenClaw should not remove a documented plugin contract in the same release diff --git a/docs/plugins/sdk-subpaths.md b/docs/plugins/sdk-subpaths.md index 30234aff8..e85865654 100644 --- a/docs/plugins/sdk-subpaths.md +++ b/docs/plugins/sdk-subpaths.md @@ -16,23 +16,24 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) ## Plugin entry -| Subpath | Key exports | -| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | -| `plugin-sdk/testing` | Broad compatibility barrel for legacy plugin tests; prefer focused test subpaths for new extension tests | -| `plugin-sdk/plugin-test-api` | Minimal `OpenClawPluginApi` mock builder for direct plugin registration unit tests | -| `plugin-sdk/channel-test-helpers` | Channel account lifecycle, directory, send-config, runtime mock, hook, and generic channel contract test helpers | -| `plugin-sdk/channel-target-testing` | Shared channel target-resolution error-case test suite | -| `plugin-sdk/plugin-test-contracts` | Plugin registration, package manifest, public artifact, runtime API, import side-effect, and direct import contract helpers | -| `plugin-sdk/plugin-test-runtime` | Plugin runtime, registry, provider-registration, setup-wizard, and runtime task-flow fixtures for tests | -| `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, web-search/fetch, and wizard contract helpers | -| `plugin-sdk/test-env` | Test environment, fetch/network, live-test, temporary filesystem, and time-control fixtures | -| `plugin-sdk/test-fixtures` | Generic CLI, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token, and typed-case test fixtures | -| `plugin-sdk/migration` | Migration provider item helpers such as `createMigrationItem`, reason constants, item status markers, redaction helpers, and `summarizeMigrationItems` | -| `plugin-sdk/migration-runtime` | Runtime migration helpers such as `copyMigrationFileItem` and `writeMigrationReport` | +| Subpath | Key exports | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/testing` | Broad compatibility barrel for legacy plugin tests; prefer focused test subpaths for new extension tests | +| `plugin-sdk/plugin-test-api` | Minimal `OpenClawPluginApi` mock builder for direct plugin registration unit tests | +| `plugin-sdk/channel-test-helpers` | Channel account lifecycle, directory, send-config, runtime mock, hook, and generic channel contract test helpers | +| `plugin-sdk/channel-target-testing` | Shared channel target-resolution error-case test suite | +| `plugin-sdk/plugin-test-contracts` | Plugin registration, package manifest, public artifact, runtime API, import side-effect, and direct import contract helpers | +| `plugin-sdk/plugin-test-runtime` | Plugin runtime, registry, provider-registration, setup-wizard, and runtime task-flow fixtures for tests | +| `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, media capability, web-search/fetch, and wizard contract helpers | +| `plugin-sdk/provider-http-test-mocks` | Opt-in Vitest HTTP/auth mocks for provider tests that exercise `plugin-sdk/provider-http` | +| `plugin-sdk/test-env` | Test environment, fetch/network, live-test, temporary filesystem, and time-control fixtures | +| `plugin-sdk/test-fixtures` | Generic CLI, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token, and typed-case test fixtures | +| `plugin-sdk/migration` | Migration provider item helpers such as `createMigrationItem`, reason constants, item status markers, redaction helpers, and `summarizeMigrationItems` | +| `plugin-sdk/migration-runtime` | Runtime migration helpers such as `copyMigrationFileItem` and `writeMigrationReport` | @@ -274,7 +275,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/channel-test-helpers` | Channel-oriented test helpers for generic actions/setup/status contracts, directory assertions, account startup lifecycle, send-config threading, runtime mocks, status issues, outbound delivery, and hook registration | | `plugin-sdk/channel-target-testing` | Shared target-resolution error-case suite for channel tests | | `plugin-sdk/plugin-test-contracts` | Plugin package, registration, public artifact, direct import, runtime API, and import side-effect contract helpers | - | `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, wizard, web-search/fetch, and stream contract helpers | + | `plugin-sdk/provider-test-contracts` | Provider runtime, auth, discovery, onboard, catalog, wizard, media capability, web-search/fetch, and stream contract helpers | + | `plugin-sdk/provider-http-test-mocks` | Opt-in Vitest HTTP/auth mocks for provider tests that exercise `plugin-sdk/provider-http` | | `plugin-sdk/test-fixtures` | Generic CLI runtime capture, sandbox context, skill writer, agent-message, system-event, terminal-text, chunking, auth-token, and typed-case fixtures | diff --git a/docs/plugins/sdk-testing.md b/docs/plugins/sdk-testing.md index 4009410c0..a4345928c 100644 --- a/docs/plugins/sdk-testing.md +++ b/docs/plugins/sdk-testing.md @@ -33,6 +33,8 @@ plugins. **Provider contract import:** `openclaw/plugin-sdk/provider-test-contracts` +**Provider HTTP mock import:** `openclaw/plugin-sdk/provider-http-test-mocks` + **Environment/network test import:** `openclaw/plugin-sdk/test-env` **Generic fixture import:** `openclaw/plugin-sdk/test-fixtures` @@ -52,6 +54,7 @@ import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-help import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts"; import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime"; import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts"; +import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks"; import { withEnv, withFetchPreconnect } from "openclaw/plugin-sdk/test-env"; import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fixtures"; ``` @@ -76,6 +79,11 @@ import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fi | `createRuntimeEnv` | Build a mocked CLI/plugin runtime environment. Import from `plugin-sdk/plugin-test-runtime` | | `createPluginSetupWizardStatus` | Build setup status helpers for channel plugins. Import from `plugin-sdk/plugin-test-runtime` | | `describeOpenAIProviderRuntimeContract` | Install provider-family runtime contract checks. Import from `plugin-sdk/provider-test-contracts` | +| `expectExplicitVideoGenerationCapabilities` | Assert video providers declare explicit generation mode capabilities. Import from `plugin-sdk/provider-test-contracts` | +| `expectExplicitMusicGenerationCapabilities` | Assert music providers declare explicit generation/edit capabilities. Import from `plugin-sdk/provider-test-contracts` | +| `mockSuccessfulDashscopeVideoTask` | Install a successful DashScope-compatible video task response. Import from `plugin-sdk/provider-test-contracts` | +| `getProviderHttpMocks` | Access opt-in provider HTTP/auth Vitest mocks. Import from `plugin-sdk/provider-http-test-mocks` | +| `installProviderHttpMockCleanup` | Reset provider HTTP/auth mocks after each test. Import from `plugin-sdk/provider-http-test-mocks` | | `installCommonResolveTargetErrorCases` | Shared test cases for target resolution error handling. Import from `plugin-sdk/channel-target-testing` | | `shouldAckReaction` | Check whether a channel should add an ack reaction. Import from `plugin-sdk/channel-feedback` | | `removeAckReactionAfterReply` | Remove ack reaction after reply delivery. Import from `plugin-sdk/channel-feedback` | @@ -112,9 +120,10 @@ Keep new extension tests on a documented focused SDK subpath such as `plugin-sdk/plugin-test-api`, `plugin-sdk/channel-contract-testing`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/plugin-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/provider-test-contracts`, -`plugin-sdk/test-env`, or `plugin-sdk/test-fixtures` rather than importing the -broad `plugin-sdk/testing` compatibility barrel, repo `src/**` files, or repo -`test/helpers/plugins/*` bridges directly. +`plugin-sdk/provider-http-test-mocks`, `plugin-sdk/test-env`, or +`plugin-sdk/test-fixtures` rather than importing the broad `plugin-sdk/testing` +compatibility barrel, repo `src/**` files, or repo `test/helpers/plugins/*` +bridges directly. ### Types