feat(search): capture bounded manual plugin-search observations

[Patrick-Erichsen]

Capture bounded manual plugin-search observations

Problem

Record manual search demand at the response boundary so counts describe exactly what the user receives.

Change

Record only bounded manual-source plugin searches. Official counts use exact returned packages with authoritative isOfficial === true; ordinary authorization and private visibility remain unchanged. No request, user, or device identity is stored.

Validation

491 focused boundary/retention tests passed. Real web and Control UI requests were paired with persisted observations, including community-only and zero-result searches.

Review status

Draft for human review. This is a dedicated search-intelligence stack, independent of the plugin-page/category work. No merge or production deployment is authorized.

The full integrated stack at ca843a963a passed bun run ci:unit (6,582 passed, 3 skipped), bun run ci:types-build, package/HTTP/browser checks, and the non-audit static constituents. bun run ci:static remains red on seven dependency advisories in the unchanged baseline lockfile; that repair is deliberately outside this stack. These results are from the saved reviewed head, not a claim that CI on this PR has passed.

The official gap is exactly zero authoritative official results in the returned response. The model never assigns provenance. Unknown/unmarked traffic and non-plugin responses are excluded.

Related draft PRs

Review ClawHub bottom-to-top: capture → web attribution → dashboard/API/CLI → weekly producer.

Separate-repository companions: OpenClaw Control UI and Hermit receiver. The producer requires the Hermit receiver; the Control UI source marker requires the capture boundary. No plugin-page/category stack branches are included.

[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 8, 2026 11:14pm UTC

[clawsweeper]

Codex review: blocked before merge. Reviewed September 8, 2026, 7:18 PM ET / 23:18 UTC.

ClawSweeper review

What this changes

Record bounded, attributed plugin searches and their returned result counts in Convex, with automatic cleanup after 30 days.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep open: current main lacks this capture capability, and the related drafts build on it rather than replace it. No blocking code findings were identified; the collaborator-authored draft explicitly reserves landing for human review.

Priority: P2
Reviewed head: 61c8e1d86beafc2a656bad6c673699c80288413c

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with substantial boundary coverage and no blocking code findings; runtime rollout validation remains necessary.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored backend PR is exempt from the ordinary external-contributor proof gate. Reported real capture runs are acknowledged; inspected companion screenshots do not independently establish persistence or cleanup, which remains a repository rollout-validation concern.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored backend PR is exempt from the ordinary external-contributor proof gate. Reported real capture runs are acknowledged; inspected companion screenshots do not independently establish persistence or cleanup, which remains a repository rollout-validation concern.
Evidence reviewed	8 items	Applicable repository policy: Read the full root AGENTS.md and the ClawHub maintainer, Convex, generated framework, and retention guidance. No applicable nested AGENTS.md or maintainer-notes directory was found. Current main still lacks capture: The main search handler returns assembled results directly, without the introduced observation write. The inspected main tree had no matching observation owner or source marker. Latest-release source inspection could not complete because a required Git object was unavailable; no shipped implementation is claimed. Response-boundary capture: Capture follows result assembly, sorting, limiting, and public projection. It requires a recognized source, excludes non-plugin families and already-aborted requests, and catches persistence errors without logging query text. Existing viewer resolution and package access checks remain intact.
Findings	None	None.
Security	None	None.

How this fits together

ClawHub’s plugin search API combines visible package results before returning them to clients. This change records selected search facts at that boundary for later analytics, without changing package access checks.

flowchart TD
  A[Plugin search request] --> B[Rate limits and package visibility]
  B --> C[Combine and limit results]
  C --> D[Return search response]
  C --> E[Check source and text bounds]
  E --> F[Store search observation]
  F --> G[Daily expiration cleanup]

Loading

Before merge

• Resolve merge risk (P1) - The inspected evidence does not establish fresh-deployment and upgrade behavior for the new persistent table, or completion of its real Convex cleanup continuation.
• Complete next step (P2) - Document the additive schema rollout and provide real Convex capture and prune-continuation validation for fresh and existing deployments before requesting landing approval.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff size	+626/-3 across 12 files	The scope includes capture, persistence, retention, generated declarations, tests, and a durable specification.
Production versus tests	Production +197/-3; tests +371/-0; generated +4; specification +54	Production growth supports the stated capture and cleanup capability, with most added lines devoted to regression coverage.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Keep capture at the assembled-response boundary, with an additive rollout that preserves existing data and verifies bounded retention before client attribution is enabled.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Keep capture at the assembled-response boundary, with an additive rollout that preserves existing data and verifies bounded retention before client attribution is enabled.

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

Not applicable: this adds an analytics capability rather than repairing a reported existing-behavior defect.

Is this the best way to solve the issue?

Yes, the response boundary is the appropriate capture layer: per-family collection could count discarded results, while client-only collection cannot independently establish authoritative returned counts. Deployment and retention validation remain outstanding.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 651a7641a204.

Labels

Label changes:

• add P2: This is a bounded analytics improvement with no demonstrated urgent user-facing regression.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored backend PR is exempt from the ordinary external-contributor proof gate. Reported real capture runs are acknowledged; inspected companion screenshots do not independently establish persistence or cleanup, which remains a repository rollout-validation concern.

Label justifications:

• P2: This is a bounded analytics improvement with no demonstrated urgent user-facing regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool 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 collaborator-authored backend PR is exempt from the ordinary external-contributor proof gate. Reported real capture runs are acknowledged; inspected companion screenshots do not independently establish persistence or cleanup, which remains a repository rollout-validation concern.

Evidence

What I checked:

• Applicable repository policy: Read the full root AGENTS.md and the ClawHub maintainer, Convex, generated framework, and retention guidance. No applicable nested AGENTS.md or maintainer-notes directory was found. (AGENTS.md:1, 61c8e1d86bea)
• Current main still lacks capture: The main search handler returns assembled results directly, without the introduced observation write. The inspected main tree had no matching observation owner or source marker. Latest-release source inspection could not complete because a required Git object was unavailable; no shipped implementation is claimed. (convex/httpApiV1/packagesV1.ts:3943, 651a7641a204)
• Response-boundary capture: Capture follows result assembly, sorting, limiting, and public projection. It requires a recognized source, excludes non-plugin families and already-aborted requests, and catches persistence errors without logging query text. Existing viewer resolution and package access checks remain intact. (convex/httpApiV1/packagesV1.ts:3954, 61c8e1d86bea)
• Persistence and retention: The new internal mutation validates normalized text and integer counts before insertion. Cleanup uses the observation-time index, bounded batches, and scheduled continuation with a fixed cutoff; the new table is classified in the retention registry. Existing stored schemas are not rewritten. (convex/pluginSearchObservations.ts:21, 61c8e1d86bea)
• Focused regression coverage: Read all introduced test hunks covering source selection, exact result counts, oversized input, excluded traffic, cancellation, storage failure, row shape, cutoff behavior, and prune continuation. Tests were not executed during this read-only review. (convex/pluginSearchObservations.test.ts:26, 61c8e1d86bea)
• Draft scope and reported validation: The live REST response confirms the pinned head remains open, draft, and unmerged; its body matches the supplied snapshot. It reports real requests paired with observations and integrated-stack validation, explicitly withholding merge/deployment authorization. The related capture consumers are still open drafts. (61c8e1d86bea)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rank-up moves

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

• Provide an additive rollout note and real Convex evidence covering capture and prune continuation on fresh and existing deployments.

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.