Discord provenance details: markdown-first TRACE sections with debug JSON fallback (Vibe Kanban)

[jbax1899]

What changed

• Reworked Discord trace details rendering to be markdown-first instead of raw JSON-first in packages/discord-bot/src/interactions/button/provenanceButtons.ts.
• Added clear, human-readable sections in the details reply: Summary, TRACE, Sources, and Execution.
• Kept inspectability by appending a bounded Raw JSON (debug) section when space allows.
• Preserved fail-open behavior when trace metadata is missing, invalid, or unavailable by rendering stable fallback sections instead of failing the interaction.
• Added interaction coverage in packages/discord-bot/test/provenanceButtons.test.ts for:
  • markdown-first section rendering,
  • long payload truncation within Discord's 2,000-char limit,
  • backend metadata failure fallback behavior.
• Tightened test typing/casting so strict review checks pass (ButtonInteraction test casting compatibility).

Why this was changed

This aligns the Discord Trace Details UX with the task goal: users should quickly understand why an answer was generated without parsing dense payloads. The update improves readability (especially on mobile), keeps continuity with TRACE/provenance transparency goals, and still supports power-user debugging through optional raw payload visibility.

Important implementation details

• Introduced sectioned markdown formatting helpers for each details block (summary/trace/sources/execution).
• Added compact formatting guards:
  • inline value truncation,
  • citation count limits,
  • execution event limits,
  • final payload hard cap handling for Discord message constraints.
• Reused shared execution timeline summary formatting from contracts for consistency.
• Retained existing metadata extraction + fallback path; only the presentation layer was changed.

This PR was written using Vibe Kanban

Summary by CodeRabbit

Release Notes

• Refactor

  • Details display refactored from JSON format to organized markdown sections (Summary, Trace, Sources, Execution) with improved readability and proper handling of large responses with Discord's message limits.

• Tests

  • Added test coverage for details rendering scenarios.

[coderabbitai]

Warning

Rate limit exceeded

@jbax1899 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 16 minutes and 11 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 16 minutes and 11 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 38cba309-f98f-478c-8243-2ce7bb218d49

📥 Commits

Reviewing files that changed from the base of the PR and between 3929c51 and 94510e0.

📒 Files selected for processing (2)

• packages/discord-bot/src/interactions/button/provenanceButtons.ts
• packages/discord-bot/test/provenanceButtons.test.ts

📝 Walkthrough

Walkthrough

Refactored Discord bot's provenance details rendering from JSON serialization to structured markdown sections (Summary, Trace, Sources, Execution, Raw JSON debug) with truncation support for Discord's 2000-character message limit. Added comprehensive test coverage including happy path, oversized payload truncation, and error handling scenarios.

Changes

Cohort / File(s)	Summary
Discord Details Rendering packages/discord-bot/src/interactions/button/provenanceButtons.ts	Refactored details output from JSON preview to markdown-first sectioned format. Introduced markdown builders for Summary, Trace, Sources (top N citations), and Execution sections. Added truncation logic for 2000-character Discord limit with optional Raw JSON debug block. New constants cap inline field length, citation count, and execution event count.
Test Coverage packages/discord-bot/test/provenanceButtons.test.ts	Added 3 test cases for handleProvenanceButtonInteraction "details" action: happy path with full trace validation, oversized payload truncation verification, and error handling with graceful fallback. Asserts markdown section headings and content length compliance.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Unify execution timeline formatting across web and Discord #204: Adds formatExecutionTimelineSummary helper to the same file, which is integrated by this PR to format execution event summaries in the new markdown rendering flow.

Poem

🐰 Hops through sections, neat and tidy,
Markdown blooms where JSON was—
Summary, Trace, Sources, sideya,
Discord's 2K limit? No pause!
Truncate with grace, debug with jest, 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: refactoring Discord provenance details from JSON-focused to markdown-first with optional debug JSON fallback.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch vk/16fd-discord-trace-de

---

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 and usage tips.}