Skip to content

perf(build): reduce plugin SDK declaration package size#98758

Merged
RomneyDa merged 1 commit into
mainfrom
bundle-checkin
Jul 2, 2026
Merged

perf(build): reduce plugin SDK declaration package size#98758
RomneyDa merged 1 commit into
mainfrom
bundle-checkin

Conversation

@RomneyDa

@RomneyDa RomneyDa commented Jul 1, 2026

Copy link
Copy Markdown
Member

Closes #98757

What Problem This Solves

Resolves a package-size problem where every OpenClaw npm artifact carried a second independently bundled plugin SDK declaration graph, adding megabytes without changing runtime behavior.

Why This Change Was Made

Normal package builds now publish the plugin SDK declarations already produced by the unified tsdown graph instead of rebuilding the same entrypoints separately. The standalone declaration fallback remains available for package-boundary workflows, while the release guard now traverses the complete reachable public declaration graph and rejects missing chunks, forbidden dependencies, or excessive size.

User Impact

OpenClaw npm packages are 3,184,932 bytes smaller unpacked and 371,214 bytes smaller compressed on the measured current tree. Public plugin SDK entrypoints and runtime behavior are unchanged.

Evidence

Apples-to-apples npm pack --ignore-scripts --json comparison using identical built runtime artifacts:

  • Before, independent SDK declarations: 88,920,540 bytes unpacked; 19,751,546 bytes compressed.
  • After, canonical unified declarations: 85,735,608 bytes unpacked; 19,380,332 bytes compressed.
  • Reduction: 3,184,932 bytes unpacked; 371,214 bytes compressed.

Validation:

  • node scripts/run-vitest.mjs test/scripts/build-all.test.ts test/scripts/prepare-extension-package-boundary-artifacts.test.ts — 49 tests passed.
  • node scripts/build-all.mjs ciArtifacts — passed from clean dist/dist-runtime.
  • node scripts/check-plugin-sdk-exports.mjs — passed; validates 4,728,262 bytes across 840 reachable declaration files.
  • .agents/skills/autoreview/scripts/autoreview --mode local --engine codex --thinking high ... — clean, no accepted/actionable findings.
  • git diff --check — passed.

@openclaw-barnacle openclaw-barnacle Bot added scripts Repository scripts size: M maintainer Maintainer-authored PR labels Jul 1, 2026
@clawsweeper

clawsweeper Bot commented Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 4:56 PM ET / 20:56 UTC.

Summary
The PR switches normal package artifact builds to reuse tsdown's canonical plugin SDK declarations, keeps the standalone declaration writer fallback, and expands the plugin SDK export guard to traverse and size-check reachable public declarations.

PR surface: Tests -26, Config -2, Other +3. Total -25 across 6 files.

Reproducibility: not applicable. as a bug reproduction; this is a package-build cleanup/performance PR. The current-main duplicate declaration path is source-visible, and the PR body provides terminal package-size and build validation evidence.

Review metrics: 2 noteworthy metrics.

  • Package Size Reduction: -3,184,932 unpacked bytes; -371,214 compressed bytes. The measured npm pack delta is the maintainer-visible payoff for changing the declaration build path.
  • Internal Build Env Surface: 1 added. OPENCLAW_PLUGIN_SDK_CANONICAL_DTS creates a new internal build mode that controls canonical declaration reuse versus standalone declaration rebuilding.

Stored data model
Persistent data-model change detected: persistent cache schema: test/scripts/build-all.test.ts, vector/embedding metadata: test/scripts/build-all.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #98757
Summary: The linked maintainer issue is the canonical request to canonicalize the plugin SDK declaration graph, and this PR is its active implementation candidate.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

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:

  • none.

Risk before merge

  • [P1] Merging changes the published plugin SDK declaration graph consumed by npm TypeScript/plugin users; exact-head package/build gates are green, but maintainers should treat the declaration compatibility outcome as owned packaging risk rather than bypassing those gates.

Maintainer options:

  1. Land With Exact-Head Package Gates (recommended)
    If maintainers are satisfied with the green exact-head package/build checks and PR body pack-size proof, they can land while owning the SDK type-compatibility risk.
  2. Request Extra Package Acceptance Proof
    Maintainers can ask for an additional npm package acceptance or pack inspection artifact if they want more assurance before changing the published declaration graph.

Next step before merge

  • [P2] Manual review is the right path because the PR is protected by the maintainer label and changes a published plugin SDK declaration surface; there is no narrow automated repair to queue.

Security
Cleared: The diff touches CI and build/package scripts but adds no dependency, third-party action, secret access, permission expansion, or downloaded code execution path.

Review details

Best possible solution:

Land through the normal maintainer merge path with the canonical tsdown declaration graph, retained standalone fallback, and expanded export guard, then let the linked issue close with the merged PR.

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

Not applicable as a bug reproduction; this is a package-build cleanup/performance PR. The current-main duplicate declaration path is source-visible, and the PR body provides terminal package-size and build validation evidence.

Is this the best way to solve the issue?

Yes; reusing the existing unified tsdown declaration output is the narrow owner-boundary fix, while retaining the standalone writer fallback covers package-boundary workflows. Redirecting or byte-deduplicating chunks would add a more fragile second ownership path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 44e88f550b69.

Label changes

Label justifications:

  • P3: This is a low-urgency package-size/build cleanup with no runtime behavior change claimed.
  • merge-risk: 🚨 compatibility: The PR changes the published plugin SDK declaration graph consumed by npm TypeScript/plugin users, so upgrade compatibility depends on package artifact proof.
  • 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. Not applicable: The external-contributor proof gate does not apply to this maintainer-labeled member PR; the body still includes terminal pack-size and build validation evidence.
Evidence reviewed

PR surface:

Tests -26, Config -2, Other +3. Total -25 across 6 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 1 21 47 -26
Docs 0 0 0 0
Config 2 2 4 -2
Generated 0 0 0 0
Other 3 86 83 +3
Total 6 109 134 -25

What I checked:

  • Repository policy applied: Read the full root AGENTS.md plus scoped scripts/test guides; the root policy makes plugin SDK public contracts, package/build artifacts, CI scripts, and env/config surfaces compatibility-sensitive review areas. (AGENTS.md:1, 44e88f550b69)
  • PR diff inspected: The single PR commit changes 6 files across CI, package scripts, build orchestration, SDK declaration writing, SDK export checking, and build-all tests. (481a0219fc7c)
  • Build profile uses canonical declarations: The PR removes the separate build:plugin-sdk:dts step from ciArtifacts and leaves tsdown DTS enabled for ciArtifacts before write-plugin-sdk-entry-dts and check-plugin-sdk-exports run. (scripts/build-all.mjs:123, 481a0219fc7c)
  • Fallback retained: In canonical mode the writer verifies expected flat declarations already exist; without the env flag it still builds and copies the standalone declaration graph, preserving package-boundary fallback behavior. (scripts/write-plugin-sdk-entry-dts.ts:92, 481a0219fc7c)
  • Declaration graph guard expanded: The export guard now starts from public plugin SDK entrypoints, follows relative declaration imports under dist, reports missing reachable declarations, checks forbidden public specifiers, and enforces a 5 MB declaration budget. (scripts/check-plugin-sdk-exports.mjs:119, 481a0219fc7c)
  • Current build contract supports the approach: Current main already builds plugin SDK entrypoints in the unified tsdown dist graph, with DTS controlled by OPENCLAW_RUN_NODE_SKIP_DTS_BUILD; the PR makes ciArtifacts stop opting out of that canonical declaration output. (tsdown.config.ts:653, 44e88f550b69)

Likely related people:

  • steipete: Peter Steinberger centralized the plugin SDK entrypoint manifest and authored follow-up SDK export/declaration guard work that this PR builds on. (role: feature-history owner; confidence: high; commits: 59940cb3ee30, e6116769b415; files: scripts/lib/plugin-sdk-entries.mjs, scripts/write-plugin-sdk-entry-dts.ts, scripts/check-plugin-sdk-exports.mjs)
  • Glucksberg: Glucksberg added the original plugin SDK export verification script and release guard now being expanded to traverse the declaration graph. (role: introduced guard; confidence: high; commits: 61d14e8a8a7c; files: scripts/check-plugin-sdk-exports.mjs, scripts/release-check.ts, src/plugin-sdk/index.test.ts)
  • vincentkoc: Vincent Koc previously changed the build-artifacts profile and has recent history on build output and plugin SDK declaration-related build surfaces. (role: build profile contributor; confidence: medium; commits: f1c2be7d3212, e085fa1a3ffd; files: scripts/build-all.mjs, test/scripts/build-all.test.ts, .github/workflows/ci.yml)
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 clawsweeper Bot mentioned this pull request Jul 1, 2026
Closed
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jul 1, 2026
@RomneyDa
RomneyDa merged commit d32c4cf into main Jul 2, 2026
138 of 147 checks passed
@RomneyDa
RomneyDa deleted the bundle-checkin branch July 2, 2026 07:21
@github-actions github-actions Bot mentioned this pull request Jul 2, 2026
Open
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 3, 2026
@RomneyDa
perf(build): canonicalize plugin SDK declarations (openclaw#98758)
a557bed
chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 3, 2026
@RomneyDa @chenyangjun-xy
perf(build): canonicalize plugin SDK declarations (openclaw#98758)
39ce284
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. scripts Repository scripts size: M status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Canonicalize plugin SDK declaration graph

1 participant

@RomneyDa