feat: Site Diagnostics agent with HAR capture

[vibegui]

Summary

• Adds a built-in Site Diagnostics agent that performs blackbox testing on storefronts — analyzing TTFB, cache headers, dead links, third-party scripts, and page weight
• Adds capture_har and screenshot as built-in tools (run in-process via puppeteer-core + Browserless API, no MCP proxy)
• Agent appears on the home page alongside Site Editor, uses well-known virtual MCP pattern (synthetic, no DB migration needed)
• Requires BROWSERLESS_TOKEN env var to function

Example report

https://github.com/decocms/context/issues/60

Changes

• packages/mesh-sdk/src/lib/constants.ts — Site Diagnostics virtual MCP definition + agent instructions
• apps/mesh/src/api/routes/decopilot/built-in-tools/capture-har.ts — HAR capture tool (compact analysis output, no raw HAR)
• apps/mesh/src/api/routes/decopilot/built-in-tools/screenshot.ts — Screenshot tool (saves to /tmp, no base64 in context)
• apps/mesh/src/storage/virtual.ts — Inject Site Diagnostics into virtual MCP list + findById
• apps/mesh/src/storage/connection.ts — Handle Site Diagnostics connection entity lookup
• apps/mesh/src/web/components/home/agents-list.tsx — Add Site Diagnostics button to home page
• apps/mesh/src/web/components/chat/context.tsx — Support fallback for synthetic agents in setVirtualMcpId

Test plan

• Set BROWSERLESS_TOKEN in .env, run bun run dev
• Click "Site Diagnostics" on home page — agent should activate with cyan border
• Ask it to diagnose a site (e.g. www.farmrio.com.br) — should capture HARs and produce report
• Verify no context overflow (HAR returns compact summary, screenshot saves to disk)
• Verify other agents still work (Decopilot, custom agents)

🤖 Generated with Claude Code

[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

Suggested: Minor (2.234.0) — based on feat: prefix

React with an emoji to override the release type:

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

Current version: 2.233.3

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).

[cubic-dev-ai]

1 issue found across 12 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/src/api/routes/decopilot/built-in-tools/screenshot.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/screenshot.ts:15">
P1: Restrict screenshot URLs to `http`/`https` before calling `page.goto` to prevent non-web scheme navigation.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 8 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/browserless.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts:41">
P1: URL validation allows private/local hosts, enabling SSRF-like internal network access through Browserless navigation.</violation>
</file>

<file name="packages/mesh-sdk/src/lib/constants.ts">

<violation number="1" location="packages/mesh-sdk/src/lib/constants.ts:340">
P2: The prompt tells the agent to extract links from `capture_har` output, but `capture_har` does not return page/sitemap body content. This creates an unexecutable discovery step.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/capture-har.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/capture-har.ts:312">
P2: CDP session leaks if `page.goto()` throws (e.g. navigation timeout). Wrap the body in `try/finally` to ensure `client.detach()` is always called, preventing lingering event listeners from polluting subsequent passes on the same page.</violation>

<violation number="2" location="apps/mesh/src/api/routes/decopilot/built-in-tools/capture-har.ts:450">
P2: Inconsistent property name for partial results: the error path returns `passResults` while the success path returns `passes: passResults`. Use the same key in both paths so partial results are discoverable under a consistent name.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

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/src/api/routes/decopilot/stream-core.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/stream-core.ts:373">
P1: Claude Code diagnostics currently constructs the full built-in toolset with a null provider; this can crash tool execution and exposes non-diagnostics built-ins unintentionally.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/fetch-page.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/fetch-page.ts:14">
P0: Validate and block private/internal target hosts before calling `fetch`; current input validation allows SSRF to internal network resources.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

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/src/web/components/home/agents-list.tsx">

<violation number="1" location="apps/mesh/src/web/components/home/agents-list.tsx:232">
P2: `hasDiagnostics` is computed from the top-5 `agents` list, so an existing Site Diagnostics agent that isn’t in the top 5 will be treated as missing and the recruit CTA will reappear. Check the full `virtualMcps` list instead.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

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/src/web/components/details/virtual-mcp/agent-capabilities.tsx">

<violation number="1" location="apps/mesh/src/web/components/details/virtual-mcp/agent-capabilities.tsx:202">
P2: The `screenshot` native capability description says it returns base64 image data, but the tool only returns a presigned URL and metadata.</violation>

<violation number="2" location="apps/mesh/src/web/components/details/virtual-mcp/agent-capabilities.tsx:320">
P1: `metadata.type` is used to index `NATIVE_TOOLS` without validating it is an own key, which can crash `NativeToolRows` on inherited object keys.</violation>
</file>

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

[cubic-dev-ai]

3 issues found across 11 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/registration.test.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/registration.test.ts:78">
P2: This test is environment-dependent and only validates one token state per run. Set/unset `BROWSERLESS_TOKEN` inside the test so both behaviors are asserted deterministically.</violation>
</file>

<file name="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts:122">
P1: The connect timeout race can leak a late Browserless connection because timed-out `connectPromise` is not canceled or cleaned up.</violation>
</file>

<file name="apps/mesh/src/api/routes/decopilot/built-in-tools/index.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/index.ts:71">
P1: The Claude Code fallback registers `subtask` with a null-cast provider, which causes a runtime failure when the tool is invoked.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 12 files (changes from recent commits).

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/src/tools/index.ts">

<violation number="1" location="apps/mesh/src/tools/index.ts:301">
P2: Avoid logging raw diagnostics tool arguments because they can contain cookies/headers and leak sensitive data into logs.</violation>
</file>

<file name="apps/mesh/src/api/app.ts">

<violation number="1" location="apps/mesh/src/api/app.ts:323">
P2: Avoid awaiting NATS-backed cache purges during startup, and re-run the purge when NATS becomes ready. As written, this await can delay startup/HMR when JetStream is slow, and it will silently skip purging if NATS isn’t ready (no onReady retry).

(Based on your team's feedback about treating NATS/JetStream as a soft dependency during startup.) [FEEDBACK_USED]</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

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/src/mcp-clients/virtual-mcp/index.ts">

<violation number="1" location="apps/mesh/src/mcp-clients/virtual-mcp/index.ts:161">
P2: Avoid logging connection_url values; they can include credentials or tokens. Keep the log to connection name/type or explicitly redact sensitive parts before logging.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/capture-har.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/capture-har.ts:59">
P3: Changing `passes` default to 2 makes the tool behavior inconsistent with its in-file description that still says default is 3 per device.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/capture-har.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/capture-har.ts:503">
P2: Returning a JSON string here changes the tool’s output type from object to string. Downstream consumers and the LLM will receive a quoted JSON blob instead of structured fields, which is inconsistent with other built-in tools.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 1 file (changes from recent commits).

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="packages/mesh-sdk/src/lib/constants.ts">

<violation number="1" location="packages/mesh-sdk/src/lib/constants.ts:341">
P2: The new `NEVER fetch_page` rule conflicts with the two-phase workflow that fetches and then HAR-captures the same pages.</violation>

<violation number="2" location="packages/mesh-sdk/src/lib/constants.ts:390">
P2: Phase 2 currently makes `?__d` capture unconditional, but debug capture should only run when Deco indicators are detected.</violation>
</file>

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

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

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/src/tools/index.ts">

<violation number="1" location="apps/mesh/src/tools/index.ts:299">
P1: Registering diagnostics with `dt.schema.shape` makes defaulted inputs effectively required for MCP clients; use a partial input schema so omitted defaulted fields still pass validation.</violation>
</file>

<file name="apps/mesh/src/api/routes/decopilot/built-in-tools/screenshot.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/screenshot.ts:59">
P1: If `encryptionKey` is missing outside localMode, the HMAC key becomes an empty string, making presigned URLs forgeable. Fail fast when no secret is configured.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/browserless.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts:39">
P1: SSRF bypass via IPv4-mapped IPv6 addresses. An attacker can reach private networks using URLs like `http://[::ffff:127.0.0.1]/` because Node's `URL` parser normalises them to `[::ffff:7f00:1]`, which doesn't match the regex. IPv6 unique-local (`fc00::/7`) and link-local (`fe80::/10`) ranges are also unblocked.

Add a catch-all for IPv6 private ranges, or parse the hostname into a numeric representation and check the range numerically.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/browserless.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts:41">
P2: The `::ffff:` pattern blocks ALL IPv6-mapped IPv4 addresses, including public ones. Since Node.js normalizes `::ffff:8.8.8.8` to `[::ffff:808:808]`, this regex matches any mapped address — not just private ranges. To only block private IPs in mapped form, the pattern should enumerate the specific private hex ranges (e.g., `::ffff:7f00:`–`::ffff:7fff:` for 127.x, `::ffff:a00:`–`::ffff:aff:` for 10.x, etc.), or better yet, parse the mapped address and check it against the IPv4 rules.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

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/src/api/routes/decopilot/built-in-tools/browserless.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/browserless.ts:107">
P2: `require("node:fs")` in this ESM file breaks local Chromium auto-discovery on Node, so local mode can incorrectly report no browser available.</violation>
</file>

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

[cubic-dev-ai]

3 issues found across 2 files (changes from recent commits).

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="packages/mesh-sdk/src/lib/constants.ts">

<violation number="1" location="packages/mesh-sdk/src/lib/constants.ts:333">
P2: Requiring a preflight `capture_har` before every diagnostic conflicts with the fetch-only Phase 1 flow and adds avoidable browser overhead.</violation>

<violation number="2" location="packages/mesh-sdk/src/lib/constants.ts:344">
P2: The new browser setup instructions contradict actual behavior by saying local mode cannot run Lighthouse audits. This can cause the agent to skip valid local audits and give incomplete diagnostics.</violation>
</file>

<file name="apps/mesh/src/api/routes/decopilot/built-in-tools/lighthouse.ts">

<violation number="1" location="apps/mesh/src/api/routes/decopilot/built-in-tools/lighthouse.ts:205">
P1: Avoid building a shell command with user-provided URLs. `execSync(args.join(" ")` allows shell injection. Use execFileSync/spawn with an аргs array (shell: false) or properly escape the URL before execution.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

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/src/storage/virtual.ts">

<violation number="1" location="apps/mesh/src/storage/virtual.ts:248">
P2: `pinnedOnly` filtering is bypassed by always prepending Site Diagnostics, so pinned-only lists can include an unpinned agent.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

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="packages/mesh-sdk/src/lib/constants.ts">

<violation number="1" location="packages/mesh-sdk/src/lib/constants.ts:691">
P2: SITE_DIAGNOSTICS_MCP_URL points to a different host than the existing Site Diagnostics connection URL, so UI paths will connect to different services. Align the constant with the canonical endpoint used by getWellKnownSiteDiagnosticsConnection (or update both if the endpoint changed).</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 7 files (changes from recent commits).

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/src/web/components/home/agents-list.tsx">

<violation number="1" location="apps/mesh/src/web/components/home/agents-list.tsx:252">
P2: Use the persisted diagnostics metadata type when checking for an existing agent. Matching against the registry item ID can miss existing Site Diagnostics agents and re-open the recruit path.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 8 files (changes from recent commits).

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/src/web/components/home/site-diagnostics-recruit-modal.tsx">

<violation number="1" location="apps/mesh/src/web/components/home/site-diagnostics-recruit-modal.tsx:212">
P2: Guard against missing registry remote URLs before creating the HTTP connection. `remoteUrl ?? ""` can create an invalid connection with a blank URL, which violates the HTTP connection URL requirement and will fail validation later.</violation>
</file>

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