perf(plugins) refactor plugin SDK declarations for flat package types by RomneyDa · Pull Request #87165 · openclaw/openclaw

RomneyDa · 2026-05-27T04:52:48Z

Summary

Generate bundled Plugin SDK declarations as flat package entries under dist/plugin-sdk/*.d.ts instead of shipping public declarations through the old dist/plugin-sdk/src/** tree.
Move extension package-boundary aliases to the flat declaration layout while preserving private local QA aliases that intentionally stay source-shaped.
Exclude dist/plugin-sdk/src/** from the npm package, keep dist/postinstall-inventory.json aligned with that exclusion, and add installed-tarball TypeScript consumer proof to release-check.

#87120 already removed the public Vitest-backed test-helper SDK subpaths from main; this PR is the follow-up package-layout refactor for the remaining public SDK declarations.

Size Impact

Measured against current origin/main (b01c6d4eaa) after:

pnpm build
node --import tsx scripts/write-package-dist-inventory.ts
npm --silent pack --json --ignore-scripts --pack-destination <tmp>

Results:

Current main: tarball 17,763,047 bytes; unpacked 78,966,685 bytes; 12,513 files; dist/plugin-sdk 4,623 files / 7,046,401 bytes.
This PR: tarball 16,982,245 bytes; unpacked 75,532,340 bytes; 9,043 files; dist/plugin-sdk 1,154 files / 3,823,484 bytes.
Net: tarball -780,802 bytes; unpacked -3,434,345 bytes; file count -3,470; dist/plugin-sdk -3,469 files / -3,222,917 bytes.

The packed artifact now has 0 dist/plugin-sdk/src/** files, down from 3,908 on current main. The generated dist/postinstall-inventory.json also has 0 dist/plugin-sdk/src/** entries, down from 3,908. The removed deep tree is partially offset by 846 flat root declaration chunks totaling 3,383,030 bytes, which keep public openclaw/plugin-sdk/* TypeScript imports resolving from the installed package.

Verification

pnpm build
node --import tsx scripts/write-package-dist-inventory.ts
npm --silent pack --json --ignore-scripts --pack-destination <tmp>
OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-smoke-fixture node scripts/run-vitest.mjs test/release-check.test.ts test/scripts/check-openclaw-package-tarball.test.ts src/infra/package-dist-inventory.test.ts
OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-conflict-fix node scripts/run-vitest.mjs src/infra/package-dist-inventory.test.ts test/release-check.test.ts test/scripts/check-openclaw-package-tarball.test.ts src/plugins/contracts/extension-package-project-boundaries.test.ts
node --import tsx scripts/release-check.ts
node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox --blacksmith-org openclaw --blacksmith-workflow .github/workflows/ci-check-testbox.yml --blacksmith-job check --blacksmith-ref main --idle-timeout 90m --ttl 240m --timing-json -- corepack pnpm run test:extensions:package-boundary:compile
- provider: blacksmith-testbox through Crabbox
- Testbox id: tbx_01kskzc6gzwvnxa2zy0e4fbr90
- Result: 108 plugins compiled; exit 0

Real behavior proof

Behavior addressed: Installed package no longer ships the unnecessary deep dist/plugin-sdk/src/** declaration tree while public openclaw/plugin-sdk/* TypeScript imports continue resolving, and package inventory no longer references omitted deep SDK declarations.
Real environment tested: Local macOS Node 24 build/package checks plus Blacksmith Testbox Linux package-boundary compile through Crabbox.
Exact steps or command run after this patch: See Verification above.
Evidence after fix: npm pack measurement shows dist/plugin-sdk/src/** count 0; generated dist/postinstall-inventory.json has 0 dist/plugin-sdk/src/** entries; release-check installs a packed tarball into temporary consumer projects and runs TypeScript against representative SDK imports; Testbox compiled 108 plugin package-boundary projects.
Observed result after fix: Build, pack measurement, release-check, focused Vitest/tarball/inventory tests, and Testbox package-boundary compile passed.
What was not tested: Full pnpm check/full test suite was not run locally; package-boundary broad proof was run remotely instead.

github-actions · 2026-05-27T04:52:56Z

Dependency Changes Detected

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

package.json

Maintainer follow-up:

Review whether the dependency changes are intentional.
Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

clawsweeper · 2026-05-27T04:55:43Z

Codex review: needs maintainer review before merge. Reviewed May 27, 2026, 10:18 PM ET / 02:18 UTC.

Summary
This PR refactors generated Plugin SDK declarations from deep dist/plugin-sdk/src/** package paths to flat dist/plugin-sdk/*.d.ts entries, updates package-boundary aliases, excludes the old declaration tree from packed output and inventory, and adds installed-package TypeScript smoke coverage.

PR surface: Source -19, Tests +124, Config +10, Other +142. Total +257 across 14 files.

Reproducibility: not applicable. This PR is a package-layout refactor, not a bug report with a failing current-main reproduction path. The relevant evidence is package/build proof from the PR body and CI/check-run state.

Review metrics: 2 noteworthy metrics.

Published SDK layout: 1 package exclusion added; deep declaration subtree omitted. This is the compatibility-sensitive package surface maintainers need to notice before merge.
Installed consumer proof: 1 release-check TypeScript smoke added. The new smoke verifies representative public Plugin SDK imports from an installed tarball rather than only from the source checkout.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Get explicit maintainer acceptance of the flat Plugin SDK declaration package layout before merge.

Risk before merge

Merging intentionally removes the old packed dist/plugin-sdk/src/** declaration tree, so consumers reaching into unpacked dist internals can break even though documented openclaw/plugin-sdk/* imports are preserved.
The declaration generator, package inventory, and release-check installed-package smoke are release automation surfaces; maintainers should accept that package-layout tradeoff before merge.

Maintainer options:

Land after SDK package-layout signoff (recommended)
Accept the PR if maintainers agree that documented openclaw/plugin-sdk/* imports are the supported contract and deep dist/plugin-sdk/src/** internals may stop shipping.
Pause for compatibility policy
Hold the PR if maintainers want to preserve the deep declaration tree as an intentional installed-package compatibility surface.

Next step before merge
Protected maintainer PR with a compatibility-sensitive Plugin SDK package-layout change; the remaining action is human maintainer signoff, not an automated repair.

Security
Cleared: The diff touches package publishing and release-check automation, but I found no concrete security or supply-chain regression; Socket reports prior alerts resolved and no lockfile or executable dependency source change is in the PR diff.

Review details

Best possible solution:

Land only after maintainer signoff that the flat Plugin SDK package layout is the desired contract and the exact head keeps build, pack, release-check, inventory, and package-boundary proof green.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR is a package-layout refactor, not a bug report with a failing current-main reproduction path. The relevant evidence is package/build proof from the PR body and CI/check-run state.

Is this the best way to solve the issue?

Yes, conditionally; the implementation is a coherent narrow path for shipping flat public SDK declarations while preserving package-boundary proof. The remaining question is maintainer acceptance of dropping the deep dist internals from the packed package.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against d1577a2ff283.

Label changes

Label justifications:

P1: Plugin SDK package types affect installed plugin consumers and release/package validation, so a regression can break real external workflows.
merge-risk: 🚨 compatibility: The PR removes the old packed deep declaration tree and relies on flat public openclaw/plugin-sdk/* declaration entries instead.
merge-risk: 🚨 automation: The PR changes declaration generation, package inventory, and release-check automation that gate release artifacts.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix real package proof: npm pack measurements, installed-tarball TypeScript consumer checks, and Crabbox/Testbox package-boundary compile output.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix real package proof: npm pack measurements, installed-tarball TypeScript consumer checks, and Crabbox/Testbox package-boundary compile output.

Evidence reviewed

PR surface:

Source -19, Tests +124, Config +10, Other +142. Total +257 across 14 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	4	38	57	-19
Tests	3	125	1	+124
Docs	0	0	0	0
Config	2	24	14	+10
Generated	0	0	0	0
Other	5	191	49	+142
Total	14	378	121	+257

What I checked:

Protected live PR state: The live issue API reports author RomneyDa, author association MEMBER, state open, and labels including maintainer, proof: sufficient, P1, merge-risk: 🚨 compatibility, and merge-risk: 🚨 automation. (39973675c501)
Mergeability: The live PR API reports head 39973675c5015b415119f2ca0a857e885daebe77, base d1577a2ff2830bb151cb820af5ebbb9323ef685e, mergeable: true, and mergeable_state: clean. (39973675c501)
Repository policy: Root policy marks Plugin APIs and fallback/setup surfaces as compatibility-sensitive and requires full root plus scoped AGENTS.md review before judging. (AGENTS.md:24, d1577a2ff283)
Plugin SDK scope: The scoped Plugin SDK guide says src/plugin-sdk is the public contract between plugins and core and can affect bundled and third-party plugins. (src/plugin-sdk/AGENTS.md:3, d1577a2ff283)
Patch surface: The PR diff adds !dist/plugin-sdk/src/**, changes package-boundary aliases to flat declarations, replaces entry declaration generation with tsdown flat declaration output, and adds installed-package TypeScript smoke coverage. (package.json, 39973675c501)
Current generator baseline: Current main generates flat root .d.ts files as re-export shims pointing back into ./src/plugin-sdk/*, which explains why replacing the packed deep tree is a compatibility-sensitive packaging refactor rather than a runtime behavior change. (scripts/write-plugin-sdk-entry-dts.ts:40, d1577a2ff283)

Likely related people:

RomneyDa: Authored the merged follow-up context PR that stopped exporting Vitest-backed Plugin SDK test helpers, the immediately related package-boundary cleanup this PR builds on. (role: recent package-boundary contributor; confidence: high; commits: 780bc791470c; files: package.json, test/release-check.test.ts, src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts)
steipete: Recent history includes package exclusion and release-check work for private QA package contents and broader Plugin SDK import-surface narrowing. (role: adjacent release/package owner; confidence: medium; commits: 229eb72cf6bf, 418056f7a0c8; files: package.json, scripts/release-check.ts, src/infra/package-dist-inventory.ts)
Mariano: The shallow/grafted checkout blames the current generator and inventory baselines to this commit, but the commit title is broad so ownership confidence is limited. (role: current-main source provenance; confidence: low; commits: 7299c5695317; files: scripts/write-plugin-sdk-entry-dts.ts, src/infra/package-dist-inventory.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

clawsweeper · 2026-05-27T05:02:42Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Velvet Lint Imp

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: sparkles near resolved comments.
Image traits: location workflow harbor; accessory rollback rope; palette pearl, teal, and neon green; mood patient; pose stepping out of a freshly hatched shell; shell matte ceramic shell; lighting moonlit rim light; background small green status lights.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Velvet Lint Imp in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

RomneyDa · 2026-05-27T05:46:41Z

@clawsweeper re-review

clawsweeper · 2026-05-27T05:46:43Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Failed
Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26493337833
Updated: 2026-05-27T05:49:09.013Z

RomneyDa · 2026-05-27T19:56:44Z

@clawsweeper re-review

Rebased onto current origin/main so the session-lock self-wait fix from #86123 is now in the branch base. Current PR diff has no src/agents/embedded-agent-runner/** or attempt.session-lock changes.

clawsweeper · 2026-05-27T19:56:47Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26535271946
Updated: 2026-05-27T20:05:12.651Z

RomneyDa · 2026-05-27T20:11:17Z

@clawsweeper re-review

Rebased onto latest origin/main and pushed CI fixes for the SDK boundary tooling. Current PR diff still has no src/agents/embedded-agent-runner/** or attempt.session-lock changes.

clawsweeper · 2026-05-27T20:11:20Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26536015019
Updated: 2026-05-27T20:19:02.360Z

RomneyDa · 2026-05-28T01:45:43Z

@clawsweeper re-review

clawsweeper · 2026-05-28T01:45:46Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Superseded
Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26549596338
Updated: 2026-05-28T01:57:50.287Z

Co-authored-by: Peter Steinberger <steipete@gmail.com>

RomneyDa · 2026-05-28T02:11:34Z

@clawsweeper re-review

clawsweeper · 2026-05-28T02:11:37Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26550404388
Updated: 2026-05-28T02:18:46.972Z

RomneyDa requested a review from a team as a code owner May 27, 2026 04:52

github-actions Bot added the dependencies-changed PR changes dependency-related files label May 27, 2026

openclaw-barnacle Bot added scripts Repository scripts extensions: xai size: M maintainer Maintainer-authored PR labels May 27, 2026

RomneyDa force-pushed the flat-declaration-refactor branch from d97def9 to e319c16 Compare May 27, 2026 05:09

openclaw-barnacle Bot added docs Improvements or additions to documentation and removed size: M labels May 27, 2026

RomneyDa changed the base branch from main to vitest-dev-dep-import-issue May 27, 2026 05:09

openclaw-barnacle Bot added size: L size: M and removed docs Improvements or additions to documentation size: L labels May 27, 2026

RomneyDa force-pushed the vitest-dev-dep-import-issue branch from 1f67ce5 to d55d2af Compare May 27, 2026 05:32

RomneyDa force-pushed the flat-declaration-refactor branch from e319c16 to 10aebfb Compare May 27, 2026 05:32

clawsweeper Bot mentioned this pull request May 27, 2026

fix: isolate plugin test helpers from sdk exports #87120

Merged

RomneyDa force-pushed the vitest-dev-dep-import-issue branch from d55d2af to a907668 Compare May 27, 2026 05:47

RomneyDa force-pushed the flat-declaration-refactor branch from daac11c to d465d76 Compare May 27, 2026 05:48

RomneyDa force-pushed the flat-declaration-refactor branch from ebf5194 to 3cb59da Compare May 27, 2026 19:56

RomneyDa force-pushed the flat-declaration-refactor branch from 3cb59da to b35824f Compare May 27, 2026 20:11

steipete self-assigned this May 27, 2026

This comment has been minimized.

Sign in to view

RomneyDa added 6 commits May 27, 2026 18:34

refactor: flatten plugin sdk declarations

2815ac0

fix: align package inventory with flat sdk declarations

ed2c6be

refactor: move packed sdk smoke to fixture

3cda9be

test: simplify packed sdk type smoke

ca61f66

fix(canvas): use focused number runtime helpers

59a4ab4

fix(ci): stabilize sdk boundary checks

a974fd2

test: guard private sdk declaration leaks

3997367

Co-authored-by: Peter Steinberger <steipete@gmail.com>

github-actions Bot mentioned this pull request May 28, 2026

📡 Upstream Digest — 2026-05-28 02:26 UTC curtismercier/openclaw-mods#961

Open

dygg2001 mentioned this pull request Jun 3, 2026

[Bug]: 5.28 regression — reasoning/thinking content leaks into QQBot replies (regression of #6470) #89913

Closed

Uh oh!

Conversation

RomneyDa commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Size Impact

Verification

Real behavior proof

Uh oh!

github-actions Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Changes Detected

Uh oh!

clawsweeper Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hatch command

Uh oh!

RomneyDa commented May 27, 2026

Uh oh!

clawsweeper Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented May 27, 2026

Uh oh!

clawsweeper Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented May 27, 2026

Uh oh!

clawsweeper Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

RomneyDa commented May 28, 2026

Uh oh!

clawsweeper Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RomneyDa commented May 28, 2026

Uh oh!

clawsweeper Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RomneyDa commented May 27, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 27, 2026 •

edited

Loading

clawsweeper Bot commented May 28, 2026 •

edited

Loading

clawsweeper Bot commented May 28, 2026 •

edited

Loading