[duharry0915]

What was broken

0.2.2 (the SecretRef fix from #14) cannot be published to ClawHub from main. A ClawHub dry run of the tarball npm pack builds fails:

Error: ClawPack unpacked archive exceeds 64MB limit

The ClawHub CLI rejects a package whose files total more than 50 MiB (MAX_UNPACKED_BYTES in its clawpack.js), or whose gunzipped tar exceeds 64 MiB. Each bundled AgentMail CLI executable is about 12 MiB, so the eight-target package #15 requires is 100.5 MB unpacked. At most three targets fit; four would leave about 100 KB of headroom, and the next CLI release would break it.

This blocks the fix customers are waiting on: the channel's SecretRef apiKey fails on 0.2.1 (#13, plus support tickets).

What changed

• Three bundled targets: agentmail-cli-release.json now declares darwin-arm64, linux-arm64, and linux-x64, the common OpenClaw gateway hosts. The package is 35.7 MiB unpacked (13.4 MB packed).
• Clear message on other hosts: resolveAgentMailCliTarget now names the bundled targets, says the email channel does not use the CLI, and links to the CLI releases, instead of a bare "does not support". The channel has no dependency on the CLI, so it works on every platform.
• Size guard: pack:verify fails when a package exceeds ClawHub's 50 MiB limit, in addition to checking for missing targets. It reads sizes from the .tgz itself (new listTarballEntries, which reads the archive the way ClawHub does) or from the npm pack file list.
• npm 12 fix: pack:verify without a tarball crashed on npm 12, which prints pack results as an object keyed by package name rather than an array. parseNpmPackEntries accepts both shapes.
• Stale vendor guard: plugin:validate fails when vendor/ still holds targets that are no longer declared. cli:prepare never deletes targets, so a machine that prepared all eight would otherwise pack them again.
• README: documents the bundled platforms, and says to publish the verified .tgz, not the folder. The ClawHub CLI packs a folder with npm pack --ignore-scripts, which skips prepack; that is how 0.2.1 shipped only the darwin-arm64 CLI.

Verification

• npm test: 239 passed. New tests: tarball parsing against a real npm pack output (including a path longer than the 100-byte ustar name field), both npm pack JSON shapes, and the unsupported-host message.
• From a clean vendor/: plugin:check, plugin:validate (3 targets prepared), and pack:verify all pass. The same steps run in CI.
• pack:verify on the old eight-target tarball fails with 95.8 MiB unpacked; ClawHub rejects packages over 50.0 MiB.
• plugin:validate with a stale eight-target vendor/ fails and names the five undeclared targets.
• clawhub package publish ./agentmail-agentmail-0.2.2.tgz --dry-run passes: 78 files, 35.7 MB.

Not in this PR

• CLI on Windows and Intel macOS. Covering every platform means either downloading the pinned, checksum-verified CLI on first use or asking users to install it. Both change the current "installation never downloads executables" design, so that is a separate decision.
• plugin:build on a non-bundled developer machine (Intel Mac, Windows) now fails in cli:prepare with "no packaged target". CI (linux-x64) and Apple silicon machines are unaffected.

After merge

Publish 0.2.2 from the merge commit:

npm ci && npm pack
npm run pack:verify -- agentmail-agentmail-0.2.2.tgz
npx clawhub@0.23.3 package publish ./agentmail-agentmail-0.2.2.tgz --family code-plugin --owner agentmail --version 0.2.2 --source-repo agentmail-to/openclaw-plugin --source-commit <merge sha> --source-ref main

Then open a PR on openclaw/openclaw to move the official catalog pin (added in openclaw/openclaw#155097) from clawhub:@agentmail/agentmail@0.2.1 to 0.2.2 and its sha256. Existing ClawHub installs are trusted by package name and clawhubChannel, not by version, so 0.2.2 installs stay trusted before that PR lands.

🤖 Generated with Claude Code