refactor: consolidate byte-size formatting by RomneyDa · Pull Request #99768 · openclaw/openclaw

RomneyDa · 2026-07-04T02:24:45Z

What Problem This Solves

OpenClaw had ten independent byte-size scaling and unit-selection implementations across core, Control UI, agent-core, QQBot, and file-transfer surfaces. Their binary thresholds, SI/IEC labels, precision, spacing, and rounding rules were implicit in local loops, making compatible output changes difficult to review and easy to drift.

Why This Change Was Made

This adds one dependency-free normalization-core formatter whose call sites explicitly select si, iec, or legacy-binary style together with precision, spacing, maximum unit, and floor rounding where required. Owner wrappers retain invalid-input and presentation policy, plugin callers use the existing plugin-sdk/number-runtime entrypoint, and the distinct rounded-MiB promotion contract in src/infra/disk-space.ts remains local.

The exact production TypeScript numstat is +127/-83 (net +44), calculated file-by-file with new files included and tests excluded. The positive LOC is intentional: ten separate scaling/unit-selection algorithms become one 45-line canonical implementation, while explicit style options preserve user-visible compatibility and prevent hidden SI/IEC label drift. Narrowing the migration would keep duplicate algorithms without removing the canonical owner.

Maintained packages such as pretty-bytes and filesize were considered, but normalization-core is intentionally dependency-free and these callers require exact legacy labels plus per-unit precision and rounding contracts.

User Impact

No intended user-visible output changes. Existing byte labels, precision, spacing, unit caps, invalid-value fallbacks, and threshold behavior remain compatible. Plugin and core developers now have one focused formatter contract instead of copying another local loop.

Evidence

Focused compatibility matrix: node scripts/run-vitest.mjs packages/normalization-core/src/format.test.ts src/commands/doctor-disk-space.test.ts packages/agent-core/src/harness/utils/truncate.test.ts ui/src/ui/views/agents-utils.test.ts ui/src/ui/controllers/skill-workshop.test.ts ui/src/ui/control-ui-vite-config.node.test.ts src/agents/tool-images.test.ts extensions/qqbot/src/engine/utils/file-utils.test.ts extensions/file-transfer/src/shared/params.test.ts — passed 7 Vitest shards.
Published/lazy boundary build: pnpm build — passed all phases, including tsdown, Plugin SDK export verification, and Control UI build.
Final changed/build gate after rebase: Blacksmith Testbox tbx_01kwq771m33edvath7eesca3tz, Actions run https://github.com/openclaw/openclaw/actions/runs/28716095276 — passed changed guards, full tsgo typecheck, core/extension/script lint, runtime import-cycle check, and full build; wrapper exitCode=0.
SDK contract checks: generated API baseline, synced exports, verified referenced subpaths, and checked docs formatting.
Structured closeout: .agents/skills/autoreview/scripts/autoreview --mode local --prompt-file /tmp/byte-format-autoreview-context.md --stream-engine-output — clean, no accepted/actionable findings; patch rated correct with 0.94 confidence.

github-actions · 2026-07-04T02:25:15Z

Dependency graph guard cleared

This PR no longer has blocked dependency graph changes. A future dependency graph change requires a fresh /allow-dependencies-change comment after the guard blocks that new head SHA.

Current SHA: af74962d21c08508673e246d9448a6c9af4c00d4

clawsweeper · 2026-07-04T02:27:29Z

Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 11:59 AM ET / 15:59 UTC.

Summary
The PR adds a shared formatByteSize helper in normalization-core, exports it through plugin-sdk/number-runtime, migrates selected core, UI, QQBot, and file-transfer byte-size displays to it, and refreshes SDK surface budget/baseline files.

PR surface: Source +36, Tests +54, Generated 0, Other 0. Total +90 across 18 files.

Reproducibility: not applicable. this is a refactor/API-surface PR, not a bug report. Source inspection compared the duplicated current-main formatting loops with the shared formatter options and added compatibility tests.

Review metrics: 1 noteworthy metric.

Public plugin SDK export: 1 added, 0 removed. The new formatByteSize export is the main maintainer decision because it becomes plugin-facing API after release.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/commands/doctor-disk-space.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Risk before merge

[P1] Merging this PR accepts formatByteSize as a public plugin-sdk/number-runtime API; after release, the helper name and option shape become harder to change without a plugin compatibility plan.

Maintainer options:

Accept the SDK contract before merge (recommended)
Proceed once a maintainer confirms the public helper name and option shape are the intended plugin contract.
Remove the public export first
Keep the shared helper internal and migrate only core/bundled call sites until the SDK API is separately approved.
Pause for API shape review
Defer merge if maintainers want a narrower SDK subpath, SI style support, or a different rounding/precision contract.

Next step before merge

[P2] Human review is needed to accept or reject the additive public plugin SDK export; there is no narrow automated repair to queue.

Maintainer decision needed

Question: Should OpenClaw accept formatByteSize as a public plugin-sdk/number-runtime export with this option shape, or keep byte-size formatting internal for now?
Rationale: The code path looks sound, but public plugin SDK expansion is a stable contract decision that ClawSweeper should not make automatically.
Likely owner: steipete — steipete is assigned on the PR and has recent history owning the normalization-core extraction and plugin SDK boundary preservation work.
Options:
- Accept SDK helper (recommended): Merge after maintainer review confirms this helper belongs in the public plugin SDK and required checks remain green.
- Keep it internal: Remove the plugin SDK export and keep bundled-plugin callers on an internal/core-owned path until a public contract is explicitly designed.
- Pause for API design: Hold the PR if maintainers want SI support, a narrower subpath, or a different option contract before release.

Security
Cleared: No concrete security or supply-chain concern was found; the current diff does not change package managers, lockfiles, workflows, dependency sources, lifecycle hooks, or downloaded artifacts.

Review details

Best possible solution:

Land the refactor after maintainer acceptance of the additive SDK export, preserving the compatibility tests and owner-specific display wrappers around the shared formatter.

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

Not applicable: this is a refactor/API-surface PR, not a bug report. Source inspection compared the duplicated current-main formatting loops with the shared formatter options and added compatibility tests.

Is this the best way to solve the issue?

Yes, with a product/API caveat: centralizing duplicated byte formatting in normalization-core while preserving caller-owned presentation policy is the maintainable shape. The remaining question is whether this should be public plugin SDK API now.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8547682dd6f3.

Label changes

Label justifications:

P2: This is a normal-priority refactor with compatibility-sensitive plugin SDK surface but no urgent user-facing regression.
merge-risk: 🚨 compatibility: The PR adds a public plugin SDK helper whose name and option shape would become a compatibility contract after release.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor real-behavior proof gate does not apply because this is a maintainer-associated PR; the PR body’s Testbox and focused test evidence remains useful supplemental validation.

Evidence reviewed

PR surface:

Source +36, Tests +54, Generated 0, Other 0. Total +90 across 18 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	12	113	77	+36
Tests	4	55	1	+54
Docs	0	0	0	0
Config	0	0	0	0
Generated	1	2	2	0
Other	1	2	2	0
Total	18	172	82	+90

What I checked:

Repository policy applied: Root and scoped AGENTS guidance was read; the plugin SDK guide treats SDK subpaths as public contracts and requires docs/export/baseline alignment when expanding the boundary. (src/plugin-sdk/AGENTS.md:1, 8547682dd6f3)
Shared formatter added on PR head: The PR head defines formatByteSize with explicit style, max unit, separator, precision, and floor-rounding controls. (packages/normalization-core/src/format.ts:19, af74962d21c0)
Public SDK export added: The PR head exports formatByteSize from plugin-sdk/number-runtime, making this an additive plugin-facing API surface. (src/plugin-sdk/number-runtime.ts:3, af74962d21c0)
Compatibility coverage added: The formatter test covers IEC labels, legacy-binary labels, max-unit caps, and floor rounding used by migrated call sites. (packages/normalization-core/src/format.test.ts:5, af74962d21c0)
Current main has duplicated byte formatting: Current main still has local byte-size formatting loops in file-transfer, QQBot, UI, CLI, doctor, and agent paths, so the centralization target is real rather than duplicated existing API. (extensions/file-transfer/src/shared/params.ts:52, 8547682dd6f3)
Current-head CI evidence: Current head check-runs reported 70 success, 26 skipped, and 1 neutral; the current-head CI workflow run completed successfully. (af74962d21c0)

Likely related people:

steipete: GitHub path history shows the normalization-core extraction and plugin SDK preservation work in commit 00d8d7e, and this PR is assigned to steipete for review. (role: SDK and normalization-core history owner; confidence: high; commits: 00d8d7ead059; files: packages/normalization-core/src/index.ts, src/plugin-sdk/number-runtime.ts)
RomneyDa: GitHub path history shows recent normalization-core consolidation work in commits cf14b27 and febc700, and this PR continues that same consolidation theme. (role: recent shared-normalization contributor; confidence: high; commits: cf14b27d81e6, febc70036f29; files: packages/normalization-core/src/index.ts)
vincentkoc: GitHub path history shows recent work on src/agents/tool-images.ts, one of the agent call sites migrated by this PR. (role: adjacent agent-runtime contributor; confidence: medium; commits: 80805ad7a583, 6b2af6c1ee01; files: src/agents/tool-images.ts)
shakkernerd: GitHub path history shows recent Control UI architecture work touching the display surface that this PR migrates. (role: recent UI area contributor; confidence: medium; commits: 65e12328aa20; files: ui/src/lib/agents/display.ts, ui/src/pages/skill-workshop/proposals.ts)
alkor2000: GitHub path history shows the disk-space doctor behavior and formatting contract were introduced in commit 9d97e68. (role: doctor disk-space feature introducer; confidence: medium; commits: 9d97e683d419; files: src/commands/doctor-disk-space.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.

Review history (7 earlier review cycles)

reviewed 2026-07-04T04:02:20.132Z sha 1da8b97 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T19:02:11.973Z sha 06f0758 :: needs changes before merge. :: [P1] Preserve the current agent-core typebox version
reviewed 2026-07-04T19:07:52.417Z sha 06f0758 :: needs changes before merge. :: [P1] Preserve the current agent-core typebox version
reviewed 2026-07-04T20:07:49.660Z sha 8564529 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T20:15:22.483Z sha 8564529 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T23:53:26.375Z sha 63facf6 :: needs maintainer review before merge. :: none
reviewed 2026-07-05T00:11:36.268Z sha 6d1b0e0 :: needs maintainer review before merge. :: none

RomneyDa · 2026-07-04T02:37:43Z

@clawsweeper re-review

Exact head: cc4d850dada78a2c3c612b8aa462bac500ce02f8

The compact-node failure was branch-caused and is fixed by routing tool-images through the existing normalization-core root barrel, avoiding the duplicate subpath import while preserving formatter behavior and the explicit production TypeScript disclosure of +127/-83 (net +44). Focused proof passes 85 tests across formatter, tool-images, and secrets runtime coverage; pnpm build passes; fresh autoreview is clean with no actionable findings.

The dependency graph change remains intentional: agent-core directly imports the shared formatter, so the workspace dependency and lockfile importer change require fresh exact-head admin/secops authorization with /allow-dependencies-change.

clawsweeper · 2026-07-04T02:37:45Z

🦞🧹
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.

RomneyDa · 2026-07-04T02:58:35Z

@clawsweeper re-review

clawsweeper · 2026-07-04T02:58:38Z

🦞🧹
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.

RomneyDa · 2026-07-04T03:56:05Z

@clawsweeper re-review

clawsweeper · 2026-07-04T03:56:08Z

🦞🧹
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.

RomneyDa · 2026-07-06T15:42:44Z

@clawsweeper re-review

clawsweeper · 2026-07-06T15:42: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.

* refactor: consolidate byte-size formatting * fix: stabilize byte formatter import boundary * fix: keep byte formatter within SDK budget * fix: emit byte formatter package entry * refactor: trim byte formatter surface * fix: use narrow byte formatter import * refactor: remove byte formatter dependency changes * fix: refresh rebased byte formatter baseline

RomneyDa requested a review from a team as a code owner July 4, 2026 02:24

openclaw-barnacle Bot added docs Improvements or additions to documentation app: web-ui App: web-ui cli CLI command changes scripts Repository scripts commands Command implementations agents Agent runtime and tooling channel: qqbot plugin: file-transfer labels Jul 4, 2026

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

openclaw-barnacle Bot added size: M maintainer Maintainer-authored PR labels Jul 4, 2026

RomneyDa assigned steipete Jul 4, 2026

clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jul 4, 2026

RomneyDa force-pushed the refactor/byte-format-consolidation branch from cc4d850 to 9ba62ad Compare July 4, 2026 02:57

RomneyDa force-pushed the refactor/byte-format-consolidation branch from 9ba62ad to 1da8b97 Compare July 4, 2026 03:56

github-actions Bot mentioned this pull request Jul 4, 2026

🦞 OpenClaw 生态日报 2026-07-04 litang9/big_model_radar#160

Open

RomneyDa force-pushed the refactor/byte-format-consolidation branch from 8564529 to 63facf6 Compare July 4, 2026 23:47

clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. labels Jul 4, 2026

github-actions Bot removed the dependencies-changed PR changes dependency-related files label Jul 4, 2026

RomneyDa force-pushed the refactor/byte-format-consolidation branch from d86fd53 to 6d1b0e0 Compare July 5, 2026 00:04

RomneyDa added 8 commits July 6, 2026 08:25

refactor: consolidate byte-size formatting

644c127

fix: stabilize byte formatter import boundary

1e1ca29

fix: keep byte formatter within SDK budget

1178d8e

fix: emit byte formatter package entry

1fb5869

refactor: trim byte formatter surface

2bb34d0

fix: use narrow byte formatter import

af2d80d

refactor: remove byte formatter dependency changes

e67fe3e

fix: refresh rebased byte formatter baseline

af74962

RomneyDa force-pushed the refactor/byte-format-consolidation branch from 6d1b0e0 to af74962 Compare July 6, 2026 15:28

RomneyDa merged commit 5af7ba9 into main Jul 6, 2026
98 of 99 checks passed

RomneyDa deleted the refactor/byte-format-consolidation branch July 6, 2026 16:26

github-actions Bot mentioned this pull request Jul 6, 2026

📡 Upstream Digest — 2026-07-06 16:47 UTC curtismercier/openclaw-mods#1223

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor: consolidate byte-size formatting#99768

refactor: consolidate byte-size formatting#99768
RomneyDa merged 8 commits into
mainfrom
refactor/byte-format-consolidation

RomneyDa commented Jul 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

RomneyDa commented Jul 6, 2026

Uh oh!

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

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

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

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

Uh oh!

Dependency graph guard cleared

Uh oh!

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

Uh oh!

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

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

Uh oh!

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

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

Uh oh!

Uh oh!

RomneyDa commented Jul 4, 2026

Uh oh!

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

Uh oh!

Uh oh!

RomneyDa commented Jul 6, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RomneyDa commented Jul 4, 2026 •

edited

Loading

github-actions Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading