feat(reports): add reports migration and storage implementation

[viniciusventura29]

What is this contribution about?

Adds a Reports system to Mesh — a first-class way for agents, CI pipelines, and external services to publish structured reports (performance audits, security scans, ranking summaries, etc.) that appear in an inbox-style UI inside the Mesh admin panel.

The implementation includes:

• Database: new reports table with org-scoped storage, lifecycle status (unread / read / dismissed), and JSON sections
• Storage layer: KyselyReportsStorage — CRUD operations (list, get, upsert, updateLifecycleStatus)
• MCP Tools: REPORTS_LIST, REPORTS_GET, REPORTS_UPDATE_STATUS, REPORTS_UPSERT — exposed via the management MCP (/mcp/self) and selectable in any Virtual MCP
• Bindings: REPORTS_BINDING in @decocms/bindings — any external MCP that implements REPORTS_LIST + REPORTS_GET is automatically detected as reports-compatible by the UI plugin
• Bug fix: PassthroughClient now detects stale tool caches — if any selected_tools are missing from the DB cache, it falls back to a live fetch instead of returning an empty list

---

Screenshots/Demonstration

Reports inbox with unread / dismissed tabs, report detail with metrics, markdown, table, criteria, note, and ranked-list section types.
(add Loom here)

---

How to Test

1. Run migrations:

   bun run --cwd=apps/mesh migrate

2. Start the dev server:

   bun run dev

3. In any Cursor/Claude session connected to the Mesh Virtual MCP, call REPORTS_UPSERT with a title, category, status, summary, and at least one section
4. Open the Mesh admin UI → Reports plugin → the new report should appear in the Inbox with unread styling
5. Click the report → detail view renders sections in order; lifecycleStatus should auto-update to read
6. Click "Mark as done" → report moves to the Done tab (dismissed)

Testing the cache fix:

1. Configure a Virtual MCP selecting REPORTS_LIST / REPORTS_GET from the Mesh MCP connection
2. Call tools/list on the Virtual MCP URL — all 4 report tools should appear even if the connection's DB cache predates this PR

---

Migration Notes

This PR adds a new Kysely migration (035-reports.ts). Run before starting the server:

bun run --cwd=apps/mesh migrate

No Better Auth migrations required. No breaking changes to existing connections or Virtual MCPs.

---

Review Checklist

• PR title is clear and descriptive
• Changes are tested and working
• Documentation is updated (if needed)
• No breaking changes

---

Summary by cubic

Adds first-class reports storage and tools so plugins and agents can publish and read automated reports via the Reports binding. Includes a DB migration, MCP tools, context wiring, and UI updates (Mesh MCP by default, tool search, smarter virtual MCP caching).

• New Features

  • Added KyselyReportsStorage with list, get, upsert, and lifecycle status update.
  • Implemented REPORTS_LIST, REPORTS_GET, REPORTS_UPDATE_STATUS, and REPORTS_UPSERT; registered in core tools and bindings.
  • Wired reports into Mesh context and storage types; standardized section types via bindings and added an "rpt_" ID prefix.
  • Updated UI to auto-include Mesh MCP (org SELF) for Reports selection; added tool search in the dependency selector.
  • Improved virtual MCP passthrough client to detect stale cached tools based on required selections and fetch live when needed.

• Migration

  • Introduces migration 035-reports. Run app migrations to create the reports table and org_id index; lifecycle_status is non-null with default “unread”.
  • No manual backfill required. Sections and tags are stored as JSON.

^{Written for commit 5309b79. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Should a new version be published when this PR is merged?

React with an emoji to vote on the release type:

Reaction	Type	Next Version
👍	Prerelease	2.115.1-alpha.1
🎉	Patch	2.115.1
❤️	Minor	2.116.0
🚀	Major	3.0.0

Current version: 2.115.0

Deployment

• Deploy to production (triggers ArgoCD sync after Docker image is published)

[cubic-dev-ai]

2 issues found across 21 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/migrations/035-reports.ts">

<violation number="1" location="apps/mesh/migrations/035-reports.ts:23">
P2: `lifecycle_status` is nullable, so rows can end up with NULL and skip the intended lifecycle state. If this column should always represent a report state, enforce `notNull()` along with the default.</violation>
</file>

<file name="packages/bindings/src/well-known/reports.ts">

<violation number="1" location="packages/bindings/src/well-known/reports.ts:331">
P2: Use ReportLifecycleStatusSchema for REPORTS_UPSERT output to keep lifecycleStatus validation consistent with the rest of the reports binding; the current z.string() allows invalid lifecycle status values.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}