vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-03 01:29:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 29

fix(plugins): queue compatibility removals pending reader migration (#163127) (#163363)

Browse source 
(cherry picked from commit ec1fb60ba6)

Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>
This commit is contained in:
Dallin Romney 2026-10-02 00:38:11 -07:00 • committed by GitHub
parent 373a207231
commit 7d877e7713
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 84 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/plugins/compatibility.md
View file

@ -97,7 +97,10 @@ and the generated channel-config fallback.
The annotation-only compatibility audit added these dated records. Their
`removeAfter` date is an earliest review date, not permission to remove a
surface while its stated reader or migration condition remains unmet.
surface while its stated reader or migration condition remains unmet. The ten
October 1 annotation families are now `removal-pending`, with the original dates
and the per-family removal conditions below preserved in the review queue.
This does not authorize removal or claim a completed published-reader sweep.
| Compatibility code | Removal condition | `removeAfter` |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------- |

98
src/plugins/compat/deprecation-marking.ts
View file

@ -1,19 +1,22 @@
import type { PluginCompatRecord } from "./types.js";
const MARKING_DATE = "2026-07-25";
const DEFAULT_REMOVE_AFTER = "2026-10-01";
const DEPRECATION_MARKING = {
status: "removal-pending",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: "2026-10-01",
} as const;
/** Dated metadata for shipped deprecated surfaces that previously had annotations only. */
/** The elapsed window does not replace each family's required reader-migration proof. */
export const DEPRECATION_MARKING_COMPAT_RECORDS = [
{
code: "plugin-sdk-channel-setup-input-fields",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "channel",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "plugin-local setup input intersections that declare each owning channel field",
replacement:
"plugin-local setup input intersections that declare each owning channel field; retain each field until a new published-plugin artifact sweep finds no reader",
docsPath: "/plugins/sdk-migration#published-channel-setup-compatibility",
surfaces: [
"ChannelSetupInput.privateKey",
@ -49,13 +52,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "plugin-sdk-broad-runtime-barrels",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "sdk",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "focused plugin SDK subpaths for each runtime capability",
replacement:
"focused plugin SDK subpaths for each runtime capability; retain until bundled and published plugins no longer import any of the seven broad barrels",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"openclaw/plugin-sdk/agent-runtime",
@ -84,13 +84,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "plugin-sdk-provider-owned-helper-shims",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "provider",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "provider-local auth, model, replay, OAuth, and stream helper APIs",
replacement:
"provider-local auth, model, replay, OAuth, and stream helper APIs; retain until every helper is migrated in official providers and absent from published plugins",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"openclaw/plugin-sdk/provider-stream GOOGLE_THINKING_STREAM_HOOKS",
@ -138,13 +135,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "message-presentation-legacy-bridges",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "channel",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "MessagePresentation values and channel presentation renderers",
replacement:
"MessagePresentation values and channel presentation renderers; retain until reply producers and official channel packages no longer emit or read legacy interactive replies",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"InteractiveReplyButton.value",
@ -183,13 +177,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "plugin-sdk-focused-compat-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "sdk",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "the focused replacement named by each TypeScript @deprecated annotation",
replacement:
"the focused replacement named by each TypeScript @deprecated annotation; retain until every enumerated alias has zero bundled and published readers",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"openclaw/plugin-sdk/acp-runtime __testing",
@ -231,14 +222,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "agent-harness-terminal-result-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "agent-runtime",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement:
"AgentHarnessAttemptResult.terminal and AgentHarnessDeliveryDefaults.visibleReplies",
"AgentHarnessAttemptResult.terminal and AgentHarnessDeliveryDefaults.visibleReplies; retain until harness migration verifies that legacy terminal fields and sourceVisibleReplies are unread",
docsPath: "/plugins/sdk-agent-harness",
surfaces: [
"AgentHarnessAttemptResult.aborted",
@ -265,14 +252,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "official-plugin-export-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "channel",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement:
"the canonical testing export, MessagePresentation renderers, and host-owned timeout/runtime behavior",
"the canonical testing export, MessagePresentation renderers, and host-owned timeout/runtime behavior; retain until minimum supported official plugin packages no longer import these aliases",
docsPath: "/plugins/compatibility#current-compatibility-areas",
surfaces: [
"@openclaw/google-meet __testing",
@ -296,13 +279,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "memory-host-compatibility-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "sdk",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "canonical memory cache/FTS tables and getRuntimeConfig or caller-provided config",
replacement:
"canonical memory cache/FTS tables and getRuntimeConfig or caller-provided config; retain until memory integrations are verified to use canonical tables and prepared runtime config without these aliases",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"@openclaw/memory-host-sdk ensureMemoryIndexSchema.embeddingCacheTable",
@ -323,13 +303,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "plugin-runtime-api-compat-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "plugin-execution",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "the namespaced plugin API and focused runtime methods named per surface",
replacement:
"the namespaced plugin API and focused runtime methods named per surface; retain until all enumerated flat API and runtime aliases have no readers",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"OpenClawPluginApi.registerSessionExtension",
@ -374,13 +351,10 @@ export const DEPRECATION_MARKING_COMPAT_RECORDS = [
},
{
code: "plugin-provider-manifest-compat-aliases",
status: "deprecated",
...DEPRECATION_MARKING,
owner: "provider",
introduced: MARKING_DATE,
deprecated: MARKING_DATE,
warningStarts: MARKING_DATE,
removeAfter: DEFAULT_REMOVE_AFTER,
replacement: "manifest-owned plugin kind/setup metadata and model catalog registration",
replacement:
"manifest-owned plugin kind/setup metadata and model catalog registration; retain until providers no longer publish runtime kind or legacy catalog hooks",
docsPath: "/plugins/sdk-migration#compatibility-policy",
surfaces: [
"DefinePluginEntryOptions.kind",

4
src/plugins/compat/media-legacy-projection.ts
View file

@ -3,7 +3,7 @@ import type { PluginCompatRecord } from "./types.js";
/** Named compatibility contract for the shipped parallel media projection. */
export const MEDIA_LEGACY_PROJECTION_COMPAT_RECORD = {
code: "media-legacy-projection",
status: "deprecated",
status: "removal-pending",
owner: "sdk",
introduced: "2026-07-24",
deprecated: "2026-07-24",
@ -13,7 +13,7 @@ export const MEDIA_LEGACY_PROJECTION_COMPAT_RECORD = {
// published-plugin artifact sweep at removal time.
removeAfter: "2026-10-01",
replacement:
"ordered `MsgContext.media` / `InboundMediaFacts[]`; typed hook `media` and `originalMedia`; `Attachment*` template variables; and `openclaw/plugin-sdk/media-local-roots`",
"ordered `MsgContext.media` / `InboundMediaFacts[]`; typed hook `media` and `originalMedia`; `Attachment*` template variables; and `openclaw/plugin-sdk/media-local-roots`; retain until a clean published-plugin artifact sweep verifies that the legacy media surfaces have no readers",
docsPath: "/plugins/sdk-migration#media-legacy-projection",
surfaces: [
"MsgContext MediaPath/MediaUrl/MediaType and plural/staging fields",

10
src/plugins/compat/registry.test.ts
View file

@ -151,7 +151,7 @@ describe("plugin compatibility registry", () => {
}
});
it("tracks the deprecation-marking families through the approved window", () => {
it("keeps elapsed annotation windows pending their reader migrations", () => {
const records = new Map(listPluginCompatRecords().map((record) => [record.code, record]));
expect(deprecationMarkingCodes.map((code) => records.get(code)?.code)).toEqual(
@ -159,13 +159,19 @@ describe("plugin compatibility registry", () => {
);
for (const code of deprecationMarkingCodes) {
expect(records.get(code)).toMatchObject({
status: "deprecated",
status: "removal-pending",
deprecated: "2026-07-25",
warningStarts: "2026-07-25",
removeAfter: "2026-10-01",
});
expect(records.get(code)?.replacement, code).toMatch(/retain (?:each field )?until/u);
expect(records.get(code)?.surfaces, code).toHaveLength(deprecationMarkingSurfaceCounts[code]);
}
expect(records.get("media-legacy-projection")).toMatchObject({
status: "removal-pending",
removeAfter: "2026-10-01",
replacement: expect.stringContaining("clean published-plugin artifact sweep"),
});
expect(records.get("plugin-sdk-broad-runtime-barrels")?.surfaces).toEqual(
expect.arrayContaining([
"openclaw/plugin-sdk/agent-runtime",

37
test/scripts/plugin-boundary-report.test.ts
View file

@ -6,6 +6,18 @@ import {
type PluginBoundaryReportResult,
} from "../../scripts/plugin-boundary-report.js";
const existingPendingCodes = new Set([
"sdk-untrusted-context-identifier-aliases",
"plugin-sdk-media-understanding-public-demotion",
"plugin-sdk-memory-host-core-public-demotion",
"plugin-sdk-channel-lifecycle-subpath",
"plugin-sdk-channel-message-subpath",
"plugin-sdk-channel-reply-pipeline-subpath",
"plugin-sdk-config-runtime-subpath",
"plugin-sdk-infra-runtime-subpath",
"plugin-sdk-plugin-config-runtime-public-demotion",
]);
describe("plugin-boundary-report", () => {
let summaryResult: PluginBoundaryReportResult;
@ -34,16 +46,27 @@ describe("plugin-boundary-report", () => {
expect(summaryResult.exitCode).toBe(0);
expect(summaryResult.stderr).toBe("");
expect(summary.compat?.removalPendingCount).toBe(9);
expect(summary.compat?.removalPendingCount).toBe(20);
expect(summary.compat?.removalPendingDueCount).toEqual(expect.any(Number));
expect(summary.compat?.removalPending?.map((record) => record.code)).toEqual([
"sdk-untrusted-context-identifier-aliases",
"plugin-sdk-media-understanding-public-demotion",
"plugin-sdk-memory-host-core-public-demotion",
"agent-harness-terminal-result-aliases",
"message-presentation-legacy-bridges",
"official-plugin-export-aliases",
"plugin-sdk-channel-lifecycle-subpath",
"plugin-sdk-channel-message-subpath",
"plugin-sdk-channel-reply-pipeline-subpath",
"plugin-sdk-channel-setup-input-fields",
"plugin-sdk-config-runtime-subpath",
"plugin-runtime-api-compat-aliases",
"plugin-provider-manifest-compat-aliases",
"plugin-sdk-provider-owned-helper-shims",
"media-legacy-projection",
"memory-host-compatibility-aliases",
"plugin-sdk-broad-runtime-barrels",
"plugin-sdk-focused-compat-aliases",
"plugin-sdk-infra-runtime-subpath",
"plugin-sdk-plugin-config-runtime-public-demotion",
]);
@ -51,7 +74,15 @@ describe("plugin-boundary-report", () => {
expect(record.removeAfter).toMatch(/^\d{4}-\d{2}-\d{2}$/u);
expect(record.blocker).toEqual(expect.stringMatching(/retain|replacement/iu));
expect(record.readerCount).toEqual(expect.any(Number));
expect(record.readerSample).toEqual(expect.arrayContaining([expect.any(String)]));
if (existingPendingCodes.has(String(record.code))) {
expect(record.readerSample).toEqual(expect.arrayContaining([expect.any(String)]));
} else {
expect(record.removeAfter).toBe("2026-10-01");
expect(Array.isArray(record.readerSample)).toBe(true);
for (const reader of record.readerSample as unknown[]) {
expect(reader).toEqual(expect.any(String));
}
}
expect((record.readerSample as unknown[]).length).toBeLessThanOrEqual(5);
expect(record.dueForReview).toEqual(expect.any(Boolean));
}
@ -77,7 +108,7 @@ describe("plugin-boundary-report", () => {
expect(result.exitCode).toBe(0);
expect(result.stderr).toBe("");
expect(result.stdout).toContain("removalPending=9");
expect(result.stdout).toContain("removalPending=20");
expect(result.stdout).not.toContain("agent-harness-sdk-alias");
expect(result.stdout).toMatch(/blocker=.*retain the public/iu);
expect(result.stdout).toMatch(/readerRefs=\d+ readers=/u);