feat: add the /report health report (get_report MCP tool + CLI + API)

[kathiekiwi]

Overview

Adds the first Report — health. The server computes a deterministic verdict and renders it as text + unicode sparklines. health separates flow (is work starting?), execution (are the runs that start succeeding?), and liveness (is the telemetry fresh?), each with a headline verdict and a suggested next action — no LLM in the verdict, so there's nothing to hallucinate.

Surfaces:

• get_report MCP tool — markdown with sparklines + 🟢/🟡/🔴 status markers (or ANSI via color).
• report MCP prompt — a slash command in hosts that support prompts.
• trigger report [key] CLI — colourised in a real terminal, plain markdown when piped.
• GET /api/v1/reports/:key — format=markdown|ansi|json.

Flow is diagnosed by a cause tree (env-limit saturation, queue throttling, key starvation, trigger spike, dequeue stall) off measured queue metrics, with a runs-snapshot fallback. One ReportViewModel, rendered to markdown / ANSI / JSON.

Also: trigger mcp now always starts the server — the interactive install wizard is gated behind trigger mcp --install. Previously a TTY dropped into the wizard, so MCP hosts that spawn the server over a PTY never got a server and timed out.

---

Screenshots

Degraded — env concurrency-limit saturation:

/report health        prod · last 1h · vs your 7d normal

🟡 Flow slowing  ·  🟢 Execution healthy  ·  🟢 data fresh

FLOW        🟡 at your env concurrency limit (last 40 min)
  concurrency     100/100           ▁▅▆█████   pinned 40 of last 60 min

  pending         1,910     ↑ 16×   ▁▁▂▃▅▅▇█   (normal ~120)

  start latency   p95 42s   ↑ 6×    ▁▁▂▄▆▆▇█   (normal ~7s)

  worst queue     email-sends — 82% of pending

  read: limit saturated → starts lag → backlog grows
        not workers, not platform — dequeue keeps pace at ~820/min
        nothing dead-lettered

EXECUTION   🟢 the runs that DO start are fine
  failures 1.3% (normal ~1.1%) · durations normal
  read: NOT a code problem

LIVENESS    🟢 fresh — last completion 4s ago

→ Raise the env concurrency limit
  or do nothing — backlog drains in ~2.3 min once triggers ease

Healthy:

/report health        prod · last 1h · vs your 7d normal

🟢 Flow healthy  ·  🟢 Execution healthy  ·  🟢 data fresh

FLOW        🟢 starting normally — pending 84 (normal ~120) · starts p95 6s

EXECUTION   🟢 completing normally — failures 0.9% (normal ~1.1%) · durations normal

LIVENESS    🟢 fresh — last completion 2s ago

→ nothing to do

Testing

Automated (apps/webapp/test/*)

reportHealth.test.ts — 14 tests. interpret() is pure (fixed fixtures, no IO / clock / LLM):

• Golden A — degraded (env-limit saturation): cause + evidence, anomaly window (last 40 min), queue attribution, exclusions (incl. nothing dead-lettered), read chain, driving-metric annotation, footer (raise limit + "do nothing, drains in ~2.3 min"), full markdown snapshot.
• Golden B — healthy: per-finding severities, nothing_to_do footer, full markdown snapshot.
• Cause tree — every branch: dequeue_stall, env_limit_saturation, queue_limit_throttling, key_starvation, trigger_spike, and the v1-symptom fallback each select the correct cause.
• Liveness trust guard: stale telemetry forces execution unknown + a crit summary (never a false-green from a silent feed).
• ANSI render: the terminal surface uses glyphs (✓/⚠/✕) + ANSI colour, never the markdown status emoji.
• isPendingIncreasing trend helper.

reportHealthData.test.ts — 5 tests. Drives loadHealthInput through its query seam (HealthDeps) — source selection, snapshot fallback on empty and on throw (the query-concurrency 500 guard), dlq parsing (0 vs unmeasured null), and windowMinutes from the resolved (clipped) time range. The SQL/TRQL translation is owned + tested by the query service; the ClickHouse MV aggregation by the @internal/clickhouse package tests.

[changeset-bot]

🦋 Changeset detected

Latest commit: 59a8ebd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 27 packages

Name	Type
@trigger.dev/core	Patch
trigger.dev	Patch
@trigger.dev/build	Patch
@trigger.dev/python	Patch
@trigger.dev/redis-worker	Patch
@trigger.dev/schema-to-json	Patch
@trigger.dev/sdk	Patch
@internal/cache	Patch
@internal/clickhouse	Patch
@internal/llm-model-catalog	Patch
@internal/metrics-pipeline	Patch
@trigger.dev/rbac	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/run-store	Patch
@internal/schedule-engine	Patch
@trigger.dev/sso	Patch
@internal/testcontainers	Patch
@internal/tracing	Patch
@internal/tsql	Patch
@internal/dashboard-agent	Patch
@internal/sdk-compat-tests	Patch
@trigger.dev/react-hooks	Patch
@trigger.dev/rsc	Patch
@trigger.dev/database	Patch
@trigger.dev/otlp-importer	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 985060e8-c412-472e-9818-41fd53cbfccf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Adds a deterministic health report pipeline that loads operational metrics, interprets flow, execution, and liveness verdicts, and renders aligned markdown or ANSI output. Exposes reports through a new authenticated API route, core and CLI API clients, a trigger report command, and the get_report MCP tool. Adds an MCP report prompt and changes MCP installation to require --install. Tests cover cause selection, liveness guarding, healthy and degraded snapshots, and ANSI rendering.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	Clear, specific title that matches the new health report, MCP tool, CLI, and API work.
Description check	✅ Passed	Detailed overview, testing, and screenshots cover the change, but it omits the Closes #issue line and template checklist/changelog headings.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/report-health

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@59a8ebd

trigger.dev

npm i https://pkg.pr.new/trigger.dev@59a8ebd

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@59a8ebd

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@59a8ebd

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@59a8ebd

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@59a8ebd

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@59a8ebd

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@59a8ebd

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@59a8ebd

commit: 59a8ebd

[devin-ai-integration]

Devin Review found 0 new potential issues.

[devin-ai-integration]

Devin Review found 0 new potential issues.

[devin-ai-integration]

Devin Review found 1 new potential issue.