feat: AI summarize with extensible subjects, trace context, and security hardening

[alex-fedotyev]

Summary

Replaces the April Fools Easter egg AI Summarize feature with a real LLM-powered summarization system designed to scale to new subjects (alerts, incidents, metrics) without schema churn.

What's in this PR

Backend (packages/api)

• POST /ai/summarize — subject-registry endpoint accepting { kind, content, tone?, messages? }
  • kind is an enum — event | pattern | alert. New kinds are added by registering a system prompt in aiSummarize.ts.
  • messages is an optional conversation history (capped length + size). Not wired to UI yet — ships with the shape fixed so future follow-up-question flows don't need an API change.
  • System prompts warn the model that severity labels can be misleading and instruct it to cross-check against body/attributes.
• Prompt injection defense — user content is passed through redactSecrets() (scrubs password=, token=, Bearer ..., JWTs) and wrapped in <data>...</data> tags. The system prompt explicitly tells the model to treat anything inside <data> as data, not instructions.
• Rate limiting — 30 requests/min/user (in-memory; middleware/rateLimit.ts) to protect the shared LLM API budget from runaway callers.
• .env.development.local override — new scripts/env-local-preload.js so API dev scripts respect a gitignored override file the way Next.js does.

Frontend (packages/app)

• Subject registry — aiSummarize/subjects.ts + per-subject formatters (eventSubject.ts, patternSubject.ts). Adding a new surface (e.g. alerts) = define a subject + render <AISummaryPanel> bound to useAISummarizeState({ subject, input }).
• useAISummarizeState hook — consolidates state machine previously duplicated across both button components. Handles real-AI vs easter-egg branch, tone picker, dismiss, regenerate, input-change abort, and lazy trace-context fetch.
• Shared classifiers (classifiers.ts) — isErrorEvent, isWarnEvent, normalizeSeverity that cross-check multiple signals (severity, status code, HTTP code, exception, body regex). Used to decide what to prioritize in trace context. Raw severity/body always go to the model unchanged so it can draw its own conclusion.
• Trace context enrichment — when summarizing a span in a trace, the client builds a compact context (total spans, error count, span groups with count/errors/sum/p50 durations, up to 10 error spans with exception details) and appends to the prompt. Capped at 4KB. Fetched lazily — only when user clicks Summarize, not on panel open.
• Markdown output — AI replies render via react-markdown with **bold** highlights for key details and `code` for values. Easter egg mode remains plain italic text.
• Tone/style picker — ?smart=true URL flag enables a compact tone selector (Detective Noir / Nature Documentary / Shakespearean Drama) that persists in localStorage and auto-regenerates on change. Tone values are enum-validated server-side; no freeform prompt injection.

Extensibility notes

The architecture is designed so the following changes don't require rethinking shared code:

• Adding a new subject (e.g. alerts): define ALERT_SUBJECT with a formatAlertContent, register a prompt in the backend's SUBJECT_PROMPTS map, render <AISummaryPanel> bound to the hook. No changes to the hook or panel.
• Follow-up questions / conversation: API already accepts messages: ConversationMessage[]. Future UI sends user's follow-up plus prior turns; no server change needed.
• New tone / redaction patterns: add entries to the respective registries — no refactor.

Security

• Enum-only schema on the wire; freeform prompt text cannot come from the client.
• <data> tag delimiters + explicit instruction to ignore embedded instructions.
• Secret redaction before content hits the LLM (password, token, Bearer, JWT).
• Per-user rate limit (30/min).
• db.statement is NOT included in trace context — redacted even post-regex, and span body usually has enough signal.

Test coverage

• 55 client tests covering: classifiers, trace context builder (truncation, error grouping, non-string attributes), format functions, button components, the shared hook, and the panel.
• 20 API tests covering: schema validation, per-kind prompt selection, redaction, <data> wrapping, conversation/messages mode, and error handling.
• All integration tests pass (make dev-int FILE=aiSummarize).

How to test locally

1. Set ANTHROPIC_API_KEY in packages/api/.env.development.local (or AI_API_KEY + AI_PROVIDER=anthropic).
2. yarn dev
3. Click a log row → open side panel → click Summarize. Output renders as formatted markdown.
4. Add ?smart=true to the URL to see the tone picker; changing it regenerates.
5. Without an API key, the Easter egg fallback still shows themed summaries (Apr 1–30 window).

References

• Linear: HDX-3992

[changeset-bot]

⚠️ No Changeset found

Latest commit: bcfae6a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Apr 21, 2026 3:16am

[github-actions]

E2E Test Results

✅ All tests passed • 145 passed • 3 skipped • 1087s

Status	Count
✅ Passed	145
❌ Failed	0
⚠️ Flaky	5
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

Knip - Unused Code Analysis

🔴 24 issues found

Unused exports (12)

• packages/app/src/components/aiSummarize/index.ts:dismissEasterEgg
• packages/app/src/components/aiSummarize/index.ts:getSavedTone
• packages/app/src/components/aiSummarize/index.ts:isEasterEggVisible
• packages/app/src/components/aiSummarize/index.ts:isSmartMode
• packages/app/src/components/aiSummarize/index.ts:saveTone
• packages/app/src/components/aiSummarize/index.ts:TONE_OPTIONS
• packages/app/src/components/aiSummarize/index.ts:buildTraceContext
• packages/app/src/components/aiSummarize/index.ts:isErrorEvent
• packages/app/src/components/aiSummarize/index.ts:isWarnEvent
• packages/app/src/components/aiSummarize/index.ts:normalizeSeverity
• packages/app/src/components/aiSummarize/index.ts:formatEventContent
• packages/app/src/components/aiSummarize/index.ts:formatPatternContent

Unused exported types (12)

• packages/app/src/components/aiSummarize/index.ts:AISummarizeTone
• packages/app/src/components/aiSummarize/index.ts:Theme
• packages/app/src/components/aiSummarize/index.ts:TraceSpan
• packages/app/src/components/aiSummarize/index.ts:ClassifierSignals
• packages/app/src/components/aiSummarize/index.ts:SummarySubject
• packages/app/src/components/aiSummarize/index.ts:SummarySubjectKind
• packages/app/src/components/aiSummarize/index.ts:UseAISummarizeStateResult
• packages/api/src/routers/api/aiSummarize.ts:SummarizeBody
• packages/app/src/hooks/ai.ts:SummarizeKind
• packages/app/src/hooks/ai.ts:AISummarizeTone
• packages/app/src/hooks/ai.ts:ConversationMessage
• packages/app/src/components/aiSummarize/useAISummarizeState.ts:TraceSpan

---

Knip finds unused files, dependencies, and exports in your codebase.
Run yarn knip locally to see full details.