feat(api/mcp): add heatmap tile schema for hyperdx_save_dashboard

[alex-fedotyev]

Summary

Adds a heatmap display type to the MCP mcpTilesParam schema so AI agents
can author heatmap tiles via hyperdx_save_dashboard.

The new mcpHeatmapSelectItemSchema mirrors the heatmap fields persisted in
DerivedColumnSchema (common-utils):

• aggFn: literal "heatmap" (not part of AggregateFunctionSchema)
• valueExpression: required column to bucket on the Y axis
• countExpression: optional normalization expression
• alias: optional display label
• heatmapScaleType: optional "log" | "linear"

The new mcpHeatmapTileSchema adds numberFormat so AI agents can format
durations/bytes on the value axis. groupBy is intentionally omitted because
heatmap tiles don't group, and per-select where/whereLanguage is omitted
because heatmap doesn't filter per-item (filtering happens at the chart level).

Stacked on #2200

This PR is stacked on #2200 ([HDX-4120] external dashboards API heatmap support).
Without #2200, calls to hyperdx_save_dashboard with a heatmap tile would
return a cryptic Zod validation error from the external-API discriminated
union. #2200 should merge first, then this PR rebases on main and an
integration round-trip test can be added in dashboards.test.ts (extending
the existing "create a dashboard with multiple tile types" pattern).

Marking this PR draft until #2200 lands.

What's in this PR

• mcpHeatmapSelectItemSchema and mcpHeatmapTileSchema in mcp/tools/dashboards/schemas.ts
• Heatmap added to the mcpTileSchema z.union(...)
• One few-shot example for heatmap added to the mcpTilesParam.describe(...) block
• Schema-validation unit tests at mcp/tools/dashboards/__tests__/schemas.test.ts covering accept and reject cases
• Minor changeset

What's NOT in this PR

• Raw-SQL heatmap. Heatmap is builder-only across the codebase, so the
  mcpSqlTileSchema.config.displayType enum is intentionally untouched.
• Integration round-trip test in dashboards.test.ts. Will be added once
  [HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 merges and this branch rebases on main.

Drive-by

The pre-existing en-dashes (used as em-dashes) in seven describe() strings
on this file were replaced with regular punctuation to match the team's
writing style. No semantic change.

Test plan

• yarn lint clean
• yarn tsc --noEmit clean
• jest src/mcp/tools/dashboards/__tests__/schemas.test.ts (5/5 passing)
• prose-lint --staged clean
• Tier predictor reports Tier 2
• After [HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 merges: rebase, add round-trip integration test, mark ready for review

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 5, 2026 7:39pm

[changeset-bot]

🦋 Changeset detected

Latest commit: b5d68f7

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

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/app	Minor
@hyperdx/otel-collector	Minor

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

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 1
• Production lines changed: 98 (+ 124 in test files, excluded from tier calculation)
• Branch: alex/HDX-mcp-heatmap-schema
• Author: alex-fedotyev

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

• ⚠️ Heatmap tiles silently fail on save — externalDashboardBuilderTileConfigSchema (in packages/api/src/utils/zod.ts) does not include a 'heatmap' discriminant, so any agent call to hyperdx_save_dashboard with a heatmap tile will return a Validation error to the agent with no useful message. PR description acknowledges this is intentional pending a sister PR, but there's no guard or clear error message surfaced to the caller. → Consider adding a descriptive error or returning a not yet supported message in the MCP save path until the sister PR lands.

• ⚠️ schemas.ts exceeds the 300-line guideline — file grows to ~401 lines (was ~330 pre-PR). AGENTS.md calls this out explicitly. → Consider splitting heatmap schemas into a separate file and re-exporting.

✅ No critical bugs or security issues. Schema fields (valueExpression, countExpression, heatmapScaleType, alias) correctly mirror DerivedColumnSchema. select: z.array(...).length(1) constraint is properly tested with both valid and rejection cases. Changeset targets the correct package at minor.

[github-actions]

E2E Test Results

✅ All tests passed • 159 passed • 3 skipped • 1191s

Status	Count
✅ Passed	159
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →