Add gated Claw discovery and API projection

[giodl73-repo]

Summary

• Adds feature-gated Claw list, search, package-detail, and version-detail APIs.
• Fails closed while CLAWHUB_EXPERIMENTAL_CLAWS is disabled.
• Projects only bounded clawManifestSummary data.
• Never exposes the full manifest, workspace content, MCP/cron declarations, metadata-addressed profile, or profile policy through discovery.
• Reuses existing visibility, moderation, scan, channel, and viewer-access rules.

This is ClawHub PR 3 of 4 for RFC #27 and its portable package/profile addendum RFC #48.

Stack

1. Add experimental portable Claw package schema #3089: portable schema and storage
2. Add gated Claw publication and profile validation #3090: gated publication and profile validation
3. Add gated Claw discovery and API projection #3091: gated discovery APIs
4. Add gated Claw hosted feed and lifecycle proof #3092: hosted feed and OpenClaw bridge proof

Validation

• 701/701 public package and HTTP API tests pass.
• Schema and ClawHub typechecks pass.
• Type-aware Oxlint and formatting checks pass.
• git diff --check passes.
• Signed head: 177428287cb5.

No live deployed HTTP endpoint was modified.

[vercel]

@giodl73-repo is attempting to deploy a commit to the OpenClaw Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 24, 2026, 1:33 AM ET / 05:33 UTC.

ClawSweeper review

What this changes

This PR adds feature-gated list, search, package-detail, and version-detail discovery for experimental Claw packages, exposing only a bounded manifest summary through the API, CLI, schema, and docs.

Merge readiness

⛔ Blocked until real behavior proof from a real setup is added - 6 items remain

Keep open for maintainer product-direction review and real behavior proof. This is a substantial, gated public registry contract rather than a narrow discovery fix; current main has not adopted the Claw package family, and the stacked implementation remains split across open pull requests.

Priority: P2
Reviewed head: 177428287cb5ea25fa72018a540a5de528b457e6
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The implementation and automated validation are substantial, but the missing real runtime proof remains a merge gate for this public discovery feature.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The PR provides strong automated checks but no after-fix running ClawHub proof of the disabled and enabled HTTP discovery paths; add redacted live output, terminal evidence, or a recording that shows the returned projection and gate behavior, then update the PR body for re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR provides strong automated checks but no after-fix running ClawHub proof of the disabled and enabled HTTP discovery paths; add redacted live output, terminal evidence, or a recording that shows the returned projection and gate behavior, then update the PR body for re-review.
Evidence reviewed	6 items	Feature scope: The branch changes 43 files with 6,176 additions and introduces a new public package family, schema fields, CLI family option, API projections, documentation, and package parsing rules; this needs explicit ownership of the experimental contract before merge. Fail-closed discovery boundary: The proposed discovery code checks the exact deployment gate before making the claw family publicly visible, and the public API adds a bounded clawManifestSummary rather than returning extracted manifest data. Security-sensitive projection: The PR’s stated contract and implementation add a bounded Claw manifest summary while omitting the stored extracted Claw manifest from public release output; that is the right security boundary to preserve, but it deserves maintainer review because it becomes a public API contract.
Findings	None	None.
Security	None	None.

How this fits together

ClawHub’s package registry stores package releases and serves public discovery through Convex queries and the v1 HTTP API. This change introduces an experimental Claw package family into those read paths while filtering visibility through a deployment gate and projecting a safe summary instead of the full stored manifest.

flowchart LR
  A[Package release storage] --> B[Experimental Claw gate]
  B --> C[Visibility and moderation checks]
  C --> D[Bounded Claw summary]
  D --> E[Public package queries]
  D --> F[HTTP package API]
  E --> G[CLI and web discovery]
  F --> G

Loading

Decision needed

Question	Recommendation
Should ClawHub adopt the proposed experimental claw package family and its public discovery/API/CLI contract as part of the RFC-backed four-pull-request stack?	Sponsor the gated registry contract: Accept the experimental Claw package family and review the stacked schema, publication, discovery, and feed slices together after runtime proof is added.

Why: The patch introduces durable public schemas and discovery behavior, not a previously defined bug fix; tests can validate implementation but cannot determine whether this is the intended product boundary or release sequencing.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The PR provides strong automated checks but no after-fix running ClawHub proof of the disabled and enabled HTTP discovery paths; add redacted live output, terminal evidence, or a recording that shows the returned projection and gate behavior, then update the PR body for re-review.
• Resolve merge risk (P1) - Merging establishes a new public claw family and API/CLI schema contract while the surrounding schema, publication, and hosted-feed slices are still open; users and clients could be left with an incomplete or changing experimental surface.
• Resolve merge risk (P1) - The bounded-summary projection is security-sensitive: future edits must not accidentally expose package-local profiles, workspace content, full manifests, MCP declarations, or cron declarations through discovery.
• Resolve merge risk (P1) - The branch lacks after-fix real runtime proof for both disabled and enabled HTTP discovery behavior, so passing in-memory tests do not yet demonstrate the deployment gate and public projection in a running ClawHub setup.
• Complete next step (P2) - The remaining blockers are maintainer acceptance of a new public contract and contributor-provided real runtime proof, neither of which is a narrow automated repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch surface	43 files, 6,176 additions, 158 deletions	The change spans storage-facing schemas, API output, CLI behavior, parsing, generated schema output, tests, and docs rather than a localized discovery endpoint.
Automated validation	30 completed successful checks; 1 external Vercel authorization status	Repository CI covers static, unit, type, package, HTTP, and smoke checks, but the Vercel authorization status is not a code-quality failure and does not replace runtime proof.

Merge-risk options

Maintainer options:

1. Prove and review the complete gated contract (recommended)
   Add redacted running-instance evidence for disabled and enabled discovery, then have maintainers approve the public API/CLI compatibility boundary across the stacked Claw pull requests.
2. Defer discovery until the contract is sponsored
   Pause this slice if maintainers do not yet want to commit to the experimental Claw public discovery contract.

Technical review

Best possible solution:

Approve the experimental Claw registry contract as one coherent, gated stack, then add redacted runtime evidence showing disabled reads fail closed and enabled list/search/detail/version responses expose only the bounded summary before merging the discovery slice.

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

Not applicable: this PR proposes a new gated package-discovery capability rather than reporting a broken existing behavior. The relevant validation is an after-fix runtime demonstration of disabled and enabled discovery paths.

Is this the best way to solve the issue?

Unclear: the bounded projection and fail-closed gate are a coherent implementation direction, but adopting a new public Claw registry contract and its stack sequencing requires maintainer product approval before it can be called the best solution.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 306035cad779.

Labels

Label changes:

• add P2: This is a normal-priority but broad experimental registry and public API improvement that requires product acceptance and runtime proof before merge.
• remove P3: Current review triage priority is P2, so this older priority label is no longer current.

Label justifications:

• P2: This is a normal-priority but broad experimental registry and public API improvement that requires product acceptance and runtime proof before merge.
• merge-risk: 🚨 compatibility: Adding claw to package-family schemas, CLI arguments, and public API responses creates a new client-visible contract with upgrade and maintenance implications.
• merge-risk: 🚨 security-boundary: Discovery projections handle package manifests and must continue to exclude package-local profiles, workspace contents, and operational declarations from public output.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The gated package format could make complete, portable OpenClaw agent setups discoverable without exposing their package-local operational policy, which is an unusually compelling ecosystem capability if maintainers adopt the contract.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides strong automated checks but no after-fix running ClawHub proof of the disabled and enabled HTTP discovery paths; add redacted live output, terminal evidence, or a recording that shows the returned projection and gate behavior, then update the PR body for re-review.

Evidence

What I checked:

• Feature scope: The branch changes 43 files with 6,176 additions and introduces a new public package family, schema fields, CLI family option, API projections, documentation, and package parsing rules; this needs explicit ownership of the experimental contract before merge. (packages/schema/src/packages.ts:29, 177428287cb5)
• Fail-closed discovery boundary: The proposed discovery code checks the exact deployment gate before making the claw family publicly visible, and the public API adds a bounded clawManifestSummary rather than returning extracted manifest data. (convex/packages.ts:1205, 177428287cb5)
• Security-sensitive projection: The PR’s stated contract and implementation add a bounded Claw manifest summary while omitting the stored extracted Claw manifest from public release output; that is the right security boundary to preserve, but it deserves maintainer review because it becomes a public API contract. (convex/schema.ts:642, 177428287cb5)
• Existing proof gate remains unmet: The PR body says no live deployed HTTP endpoint was modified, while its validation consists of tests, typechecks, lint, formatting, and diff checks. The prior ClawSweeper review explicitly requested live runtime HTTP proof for disabled and enabled discovery, and the supplied follow-up comments still describe only test/static validation. (177428287cb5)
• Stack relationship: The PR is the discovery slice between the still-open schema/publication pull requests and the still-open hosted-feed/lifecycle-proof pull request, so it should be reviewed as part of the experimental Claw contract rather than merged as an isolated API addition. (specs/claws.md:25, 177428287cb5)
• Repository policy: Repository guidance requires durable specifications for security-sensitive publication and trust boundaries, real running-instance screenshot/proof for user-visible route or backend behavior, and static/unit/type gates before handoff. The branch includes a focused Claw specification and CI reports the static, unit, types-build, packages, and HTTP checks as successful, but it does not supply the required real runtime discovery proof. (AGENTS.md:13, 306035cad779)

Likely related people:

• giodl73-repo: Authored this discovery proposal and the related open schema, publication, and hosted-feed slices, providing the strongest available evidence of domain context across the four-part design. (role: active contributor for the dependent Claw implementation stack; confidence: medium; commits: bfa2b56d764d, 6ef493fb439e, 177428287cb5; files: packages/schema/src/claws.ts, convex/packages.ts, convex/httpApiV1/packagesV1.ts)

Rank-up moves

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

• Add redacted runtime evidence for disabled list/search/detail requests and enabled list/search/detail/version responses.
• Obtain maintainer sponsorship for the experimental public Claw registry contract and stack sequencing.

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 (3 earlier review cycles)

• reviewed 2026-07-16T11:27:36.436Z sha 9023abd9e3a7f2c84b3b5fa748672f9563969987 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-17T08:39:38.523Z sha 241db0511755bcc724bd77444222f059707f9f70 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-20T02:10:44.285Z sha 3424d29a73cb7cb6598a2fd8a9a0c920345d0359 :: needs real behavior proof before merge. :: none

[giodl73-repo]

Restacked onto the refreshed publication slice (#3090) at 241db05. The fail-closed read/serializer boundary now lives in #3090; this PR is limited to enabled list/search/detail/version discovery and safe clawManifestSummary projection. Focused gate/package/HTTP/schema proof passes 680 tests, ci:types-build and ci:static pass, and Codex review of the effective stacked diff is clean. No reusable local Convex deployment was available, so the body retains that limitation and points to #3092 for the coordinated hosted-package/OpenClaw proof.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

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

[giodl73-repo]

Restacked discovery onto refreshed #3090 at 8774028a. Disabled list/search/named reads fail closed; enabled detail/version APIs expose only the bounded summary and strip the stored full manifest. The refreshed public/API suites pass 680 tests and the proof is in the PR body.

[giodl73-repo]

@clawsweeper re-review

[giodl73-repo]

Final discovery slice is restacked at 3424d29a73cb. Disabled list/search/named reads fail closed; enabled public responses expose only the bounded safe summary and never a full parsed manifest. Public/API tests (2 files, 680 tests), schema build, ClawHub typecheck, diff checks, and the final cumulative Codex review pass.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[giodl73-repo]

Independent three-agent review fixes are applied at c2393ea11b56: version detail now returns the bounded clawManifestSummary for the requested release rather than the package's latest release, while disabled discovery continues to fail closed. Current-head proof: 25 focused Claw discovery/API tests plus typechecks, type-aware lint, format, and diff checks pass. RFC #27 and its sidecars are updated: openclaw/rfcs#27

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

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

[giodl73-repo]

Restacked cleanly onto #3090 exact head with the current Claw schema and publication contract.

Exact head: 8247c36. Focused discovery/API tests pass 25/25; schema build, root typecheck, type-aware lint, format, and diff checks pass. The commit is signed and the PR is mergeable.

@clawsweeper re-review

[clawsweeper]

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

[giodl73-repo]

Restacked cleanly on corrected #3090. Exact signed head: 039ba1200d803730d4a49077c01ed8e660b9c4c2. Focused discovery/API proof passes 25/25 tests, plus schema build, root typecheck, type-aware lint, format, and diff checks.

@clawsweeper re-review

[clawsweeper]

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

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

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

[giodl73-repo]

Restacked on the portable schema/profile publication heads. Discovery continues to expose only the bounded Claw summary; it does not expose the full manifest or package-local harness profile. Signed head 13d0e1537fa1; 302/302 public package tests pass and final Codex review is clean.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	croner@​10.0.1

View full report

[giodl73-repo]

Restacked onto current ClawHub main through #3090. This PR is now at signed head 73565240f67f; 302/302 public package tests remain green. @clawsweeper re-review

[giodl73-repo]

Restacked onto the corrected publication contract at signed head 177428287cb5. Validation includes 701/701 public package/API tests, schema and ClawHub typechecks, type-aware lint, formatting, and diff checks.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[Patrick-Erichsen]

Maintainer restack and behavior proof for exact head 0ca83ea671c040f6c028cae9e8f49befabc6c417:

• Restacked cleanly onto current main at fd610627e0ade1482fb91c0199bc2a149a483b67 (including merged Add experimental portable Claw package schema #3089 and Add gated Claw publication and profile validation #3090).
• Disposable local Convex runtime proof used this exact function code only; no dev or production deployment was changed.
• Enabled gate: HTTP and direct Convex list/search returned triage-claw-proof; detail returned latest 2.0.0 / agent triage-latest; exact version returned 1.0.0 / agent triage-old.
• Bounded projection proof: zero forbidden-key hits across HTTP and direct Convex responses for raw package/Claw manifests, storage ids, publish actors, package coordinates, profiles, workspace content, MCP commands/env, cron payloads, or policy fields. The public release response contains only the explicit allowlist plus clawManifestSummary.
• Disabled gate: explicit HTTP list/search returned 400, detail/version returned 404, unscoped HTTP discovery omitted the Claw, direct Convex named reads returned null, and direct list/search returned empty.
• Local gate was reset to 0 and the disposable backend was stopped after proof.
• Local gates: 713 focused discovery/API tests; full unit/coverage (5,407 tests, one skipped); ci:static; ci:types-build; ci:packages; ci:e2e-http; both required package TypeScript checks. All green.
• Fresh structured autoreview: clean, no accepted/actionable findings.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.