feat: publish provider setup metadata in the plugin feed

[steipete]

What Problem This Solves

OpenClaw can discover installable plugins from ClawHub, but cannot offer a new provider during setup without separately maintained core metadata. This adds provider setup hints and small model previews to the existing plugin feed, generated from each eligible release rather than another provider registry.

Companion consumer change: openclaw/openclaw#135997.

Why This Change Was Made

Publication reads the selected release's original openclaw.plugin.json, verifies its stored size and SHA-256, and projects only declared provider identities, explicit auth choices, environment-variable names, and display-only model fields. The extracted manifest is deliberately not used: its object-key rewriting and depth limit can misattribute or lose model declarations.

Install authority remains the existing exact package/version/artifact-digest candidate. No credentials, endpoint configuration, executable discovery flags, or vendor-authored install coordinates are copied. The v1 feed and route stay unchanged; its optional openclaw namespace is accepted by shipped OpenClaw readers. The strict schema package is private, and ClawHub's CLI does not consume this feed.

Whole provider metadata is capped at 64 KiB per entry, with model previews capped at 16 KiB inside that budget. Normalized URLs are bounded after encoding. A publication-size check leaves room within Convex's document limit and rejects oversize output before replacing the last snapshot. No database schema, configuration, or dependency changes.

User Impact

Eligible official provider plugins can become discoverable through the normal feed publication process once the companion OpenClaw consumer lands. This does not change official-publisher admission or make advertised models runnable before installation. Existing plugin/skill/Claws publication behavior and install pins are preserved.

A nearby test fixture now accepts npm 12's keyed pack --json result, matching the production CLI's existing parser; otherwise the full test gate failed before exercising its scenario.

Evidence

• Regression tests failed before implementation for missing provider metadata, lossy-key collisions, and publication/normalized-URL size limits; all now pass.
• Local Convex runtime test executes release storage → publication action → stored HTTP feed, and proves a tampered manifest fails without replacing the previous publication. This is an emulated runtime test, not a production deployment.
• bun run ci:static, bun run ci:unit, bun run ci:types-build, bun run ci:packages, and bun run ci:e2e-http passed. Full unit suite: 6,327 passed, three existing opt-in skips. Package checks include built CLI/admin artifacts; HTTP checks include public reads and unauthenticated protected-write rejection.
• Independent Codex autoreview: scoped clean at P0; manual source/contract review also completed.

Production delta: +417 lines; tests/test support: +590; generated schema: +260. The growth implements release-bound publication, bounded projection, and validation. This PR does not deploy or publish a release.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clawhub	Ready	Preview	Sep 2, 2026 3:31am UTC

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 12, 2026, 7:30 AM ET / 11:30 UTC (Revision 32).

ClawSweeper review

What this changes

The PR adds release-derived provider setup hints and bounded model previews to ClawHub’s official plugin feed, with schema updates, tests, and contract documentation.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⛔ Blocked before merge - 6 items remain

The contribution remains distinct from current main. The previously reported publication regression is still present, and the supplied evidence does not yet demonstrate the changed producer working with a real backend and consumer.

Priority: P2
Reviewed head: c897b1f4361d6b18eb234a2d39792fc21a6da5fe

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	Focused implementation and useful regression coverage are limited by an unresolved publication defect and emulator-only producer proof.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The changed catalogFeed.publish path is exercised through convex-test storage, publication, and HTTP emulation only. Real-backend publication output and an OpenClaw reader consuming that output are still needed; companion Gateway proof uses an installed provider and does not exercise this producer. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The changed catalogFeed.publish path is exercised through convex-test storage, publication, and HTTP emulation only. Real-backend publication output and an OpenClaw reader consuming that output are still needed; companion Gateway proof uses an installed provider and does not exercise this producer. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	8 items	Pinned introduction and continuity: The introduced delta is 3c9d4f1..c897b1f. The previously reviewed head is identical; comparison of the publication and projection files produced no differences. The prior oversized-manifest finding therefore remains applicable. Accepted releases exceed the new read limit: Package publication explicitly exempts npm-pack artifacts from the 10 MiB individual-file check. ClawPack parsing permits files up to its 50 MiB unpacked limit and applies no smaller plugin-manifest limit. A valid manifest padded with JSON whitespace can exceed 10 MiB without enlarging stored extracted metadata. Publication failure propagates across feeds: The new manifest-size rejection throws before publication mutations. Every selected code-plugin manifest is hydrated, including plugins without provider declarations; one accepted oversized manifest prevents plugin and subsequent skill/Claw refreshes.
Findings	1 actionable finding	[P1] Preserve accepted ClawPack releases above the metadata read limit
Security	None	None.

How this fits together

ClawHub’s catalog publisher selects eligible official releases and stores a snapshot served to OpenClaw clients. The new metadata describes provider setup before installation while existing package, version, and digest pins continue to identify the installable artifact.

flowchart LR
  A[Official package releases] --> B[Eligibility checks]
  B --> C[Read and verify release manifest]
  C --> D[Project bounded setup hints]
  D --> E[Store catalog snapshot]
  E --> F[Public feed endpoint]
  F --> G[OpenClaw provider discovery]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The changed catalogFeed.publish path is exercised through convex-test storage, publication, and HTTP emulation only. Real-backend publication output and an OpenClaw reader consuming that output are still needed; companion Gateway proof uses an installed provider and does not exercise this producer. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Preserve accepted ClawPack releases above the metadata read limit (P1) - An eligible npm-pack release may contain a valid openclaw.plugin.json larger than 10 MiB: package publication explicitly skips this per-file limit for npm-pack artifacts, and ClawPack allows larger files. Even whitespace padding can trigger this without enlarging extracted metadata. The new throw aborts publish before any feed refresh, including for plugins without provider declarations. Preserve the ordinary install entry when optional metadata exceeds its processing budget, and add regression coverage for an accepted oversized manifest. This previously reported blocker remains unchanged.
• Resolve merge risk (P1) - Existing accepted ClawPack releases with manifests over 10 MiB would stop the shared feed refresh after this change.
• Resolve merge risk (P1) - Output caps do not bound all preprocessing: model candidates are fully projected and sorted, setup arrays are repeatedly scanned, and manifest reads accumulate across the publication. Near-limit runtime behavior remains unmeasured.
• Resolve merge risk (P1) - Compatibility of actual emitted provider metadata with shipped and companion OpenClaw readers remains unproven.
• Complete next step (P2) - Repair the oversized-manifest publication regression and add real-backend producer-to-reader proof, including existing-release compatibility and near-limit processing. Terminal output or redacted logs are appropriate; screenshots or recordings are welcome when they show the behavior. Redact keys, private endpoints, IP addresses, and other private details. Update the PR body to trigger review; if needed, ask a maintainer to comment @clawsweeper re-review.

Findings

• [P1] Preserve accepted ClawPack releases above the metadata read limit — convex/catalogFeed.ts:685-687

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff size	+1,381/-59 across 12 files	The change spans publication, schema source and generated artifacts, tests, and the feed contract.
Net code growth	Production +417; tests/test support +590; generated schema +260	The stated production growth implements release verification, bounded metadata projection, and validation.

Merge-risk options

Maintainer options:

1. Preserve accepted releases (recommended)
   Retain install entries when optional metadata exceeds the read budget, then demonstrate successful refresh with existing large releases and compatible readers.
2. Hold publication rollout
   Keep this PR pending until the accepted-release regression and producer-to-consumer proof gaps are resolved.

Technical review

Best possible solution:

Keep release-bound projection, preserve ordinary install entries when optional metadata exceeds its processing budget, retain corruption checks, and establish producer-to-reader compatibility for existing releases.

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

Yes, source establishes the introduced failure: select an otherwise eligible npm-pack release whose valid plugin manifest exceeds 10 MiB, and publication throws before refreshing feeds. This path was not executed during the read-only review.

Is this the best way to solve the issue?

The release-derived projection is an appropriate layer and avoids another provider registry. The current patch is not yet the best solution because optional metadata extraction can invalidate an already accepted release’s publication path.

Full review comments:

• [P1] Preserve accepted ClawPack releases above the metadata read limit — convex/catalogFeed.ts:685-687
  An eligible npm-pack release may contain a valid openclaw.plugin.json larger than 10 MiB: package publication explicitly skips this per-file limit for npm-pack artifacts, and ClawPack allows larger files. Even whitespace padding can trigger this without enlarging extracted metadata. The new throw aborts publish before any feed refresh, including for plugins without provider declarations. Preserve the ordinary install entry when optional metadata exceeds its processing budget, and add regression coverage for an accepted oversized manifest. This previously reported blocker remains unchanged.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.95

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 8c2de6c506bb.

Labels

Label justifications:

• P2: This is a bounded provider-discovery improvement without evidence of an urgent current-user outage.
• merge-risk: 🚨 compatibility: The new manifest limit rejects previously accepted releases, and emitted metadata needs consumer compatibility proof.
• merge-risk: 🚨 availability: One oversized official plugin manifest can abort the shared catalog publication action.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed catalogFeed.publish path is exercised through convex-test storage, publication, and HTTP emulation only. Real-backend publication output and an OpenClaw reader consuming that output are still needed; companion Gateway proof uses an installed provider and does not exercise this producer. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Pinned introduction and continuity: The introduced delta is 3c9d4f1..c897b1f. The previously reviewed head is identical; comparison of the publication and projection files produced no differences. The prior oversized-manifest finding therefore remains applicable. (convex/catalogFeed.ts:686, c897b1f4361d)
• Accepted releases exceed the new read limit: Package publication explicitly exempts npm-pack artifacts from the 10 MiB individual-file check. ClawPack parsing permits files up to its 50 MiB unpacked limit and applies no smaller plugin-manifest limit. A valid manifest padded with JSON whitespace can exceed 10 MiB without enlarging stored extracted metadata. (convex/packages.ts:8621, c897b1f4361d)
• Publication failure propagates across feeds: The new manifest-size rejection throws before publication mutations. Every selected code-plugin manifest is hydrated, including plugins without provider declarations; one accepted oversized manifest prevents plugin and subsequent skill/Claw refreshes. (convex/catalogFeed.ts:686, c897b1f4361d)
• Current main and release still lack the feature: Inspection of fetched main shows ordinary plugin entries without provider-manifest hydration or the optional provider namespace. The new projection file is absent from both main and v0.23.3; release-source inspection likewise shows the older entry builder. The targeted provider-setup PR search returned only this PR. (convex/catalogFeed.ts, 8c2de6c506bb)
• Captured proof covers an emulator: The complete supplied body identifies its storage-to-publication-to-HTTP scenario as convex-test emulation. The runtime test verifies metadata, unchanged install pins, digest rejection, and snapshot preservation. No real-backend output accompanies it. The separate Claws test exercises a different feed. Captured context identity: 119ad5d91ae09211b63bae11e8413c82dddfd65b41ae68c97a78bf19a1a2439f. (convex/catalogFeed.runtime.test.ts:78, c897b1f4361d)
• Explicit consumer dependency: The contract requires compatibility checks against OpenClaw’s reader before publication, and the PR explicitly links feat(plugins): discover provider setup from the ClawHub catalog openclaw#135997. This establishes a real cross-repository wire-contract dependency. (specs/hosted-catalog-feed.md:45, c897b1f4361d)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• Gio Della-Libera: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Preserve publication for accepted oversized ClawPack manifests and add existing-release regression coverage.
• Measure near-limit candidate processing and aggregate manifest hydration through the real backend, tightening budgets where needed.
• Provide redacted publication-to-HTTP output and shipped/companion reader results showing provider hints, unchanged install pins, and rejected manifest tampering.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (31 earlier review cycles; latest 8 shown)

• reviewed 2026-09-03T19:32:35.391Z sha c897b1f :: needs real behavior proof before merge. :: [P1] Exercise emitted metadata through the OpenClaw reader | [P2] Bound raw model candidates before sorting | [P2] Bound raw provider and auth candidates before projection | [P2] Budget manifest hydration across a publication
• reviewed 2026-09-03T21:39:30.371Z sha c897b1f :: needs real behavior proof before merge. :: [P1] Exercise emitted metadata through the OpenClaw reader | [P2] Bound raw model candidates before sorting | [P2] Bound raw provider and auth candidates before projection | [P2] Budget manifest hydration across a publication
• reviewed 2026-09-03T21:48:25.632Z sha c897b1f :: needs real behavior proof before merge. :: [P1] Exercise the new field through the OpenClaw reader | [P2] Add a cumulative manifest-hydration budget | [P2] Cap raw model candidates before sorting | [P2] Bound provider and auth inputs before filtering
• reviewed 2026-09-03T23:42:46.422Z sha c897b1f :: needs real behavior proof before merge. :: [P1] Exercise provider metadata through the OpenClaw reader | [P2] Cap raw model candidates before sorting | [P2] Bound provider and auth inputs before repeated scans | [P2] Budget manifest hydration across the publication
• reviewed 2026-09-04T04:52:44.817Z sha c897b1f :: needs real behavior proof before merge. :: [P2] Keep model preview selection bounded | [P2] Avoid repeated full scans of setup metadata | [P2] Cap aggregate manifest hydration per publication
• reviewed 2026-09-04T05:57:47.535Z sha c897b1f :: needs real behavior proof before merge. :: [P2] Cap raw model candidates before sorting | [P2] Index or bound setup metadata before per-provider scans | [P2] Budget cumulative manifest hydration per publication
• reviewed 2026-09-04T21:01:15.080Z sha c897b1f :: needs real behavior proof before merge. :: [P2] Cap raw model candidates before sorting | [P2] Bound provider setup scans before projection | [P2] Budget cumulative manifest hydration per publication
• reviewed 2026-09-04T23:03:59.940Z sha c897b1f :: needs real behavior proof before merge. :: [P1] Preserve accepted ClawPack releases above the metadata read limit

[github-actions]

This pull request has been automatically marked as stale due to inactivity.
Please update it or it will be closed.