PR #28735: fix(cli): render markdown tables with visible column borders (#28714)

• Repository: NousResearch/hermes-agent
• Author: xxxigm
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/28735

Description (problem / solution / changelog)

What does this PR do?

Upstream rich.markdown.Markdown (v14.x) hard-codes box=box.SIMPLE inside TableElement.__rich_console__, so when display.final_response_markdown: render is enabled, Hermes draws markdown tables with only a header underline — no vertical column dividers. On any multi-column data this collapses into an unreadable wall of text, forcing users to hand-edit the vendored Rich source inside ~/.hermes/.../venv/lib/python3.11/site-packages/rich/markdown.py to recover sane output (a hack that gets blown away on every upgrade or venv rebuild).

This PR fixes that without touching the third-party library:

• Subclass rich.markdown.Markdown with a TableElement whose box= argument is resolved from display.markdown_table_box_style at render time (so /reload-config and tests pick up changes without rebuilding the class).
• Default to heavy_head — heavy header rule + light cell borders. This adds the missing vertical dividers while preserving the visual hierarchy of the old SIMPLE style.
• Accept any Rich box constant name (case-insensitive, whitespace-tolerated). Unknown / blank / non-string values fall back to the default rather than silently regressing to borderless output.
• Setting markdown_table_box_style: simple restores the pre-PR borderless behaviour for operators who prefer it.

Related Issue

Fixes #28714

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• cli.py — Introduce _resolve_markdown_table_box(), _get_hermes_bordered_markdown_cls() (lazy, cached), and a _HermesBorderedTableElement / _HermesBorderedMarkdown pair that mirror upstream Rich line-for-line except for the configurable box= argument. Switch _render_final_assistant_content() to use the new class.
• hermes_cli/config.py — Register display.markdown_table_box_style: heavy_head as the new default.
• cli-config.yaml.example — Document the new key (and the long-undocumented final_response_markdown neighbour) so operators find it via the canonical commented example.
• website/docs/user-guide/cli.md — Add a one-paragraph user-guide note next to the existing "markdown stripping" guidance.
• tests/cli/test_cli_markdown_rendering.py — 18 new tests covering: default-bordered rendering, the simple opt-out, unknown-value fallback, empty/None values, case-insensitive box name lookup, the documented bordered-style allowlist (heavy, heavy_head, square, rounded, double), Markdown subclass identity, lazy caching, and the contract that only table_open is overridden (so future Rich element additions aren't silently shadowed).

How to Test

1. Set in ~/.hermes/config.yaml:

   display:
     streaming: false
     final_response_markdown: render

2. Restart Hermes CLI.
3. Ask the agent to output a markdown table, e.g. "Show me a table with columns Module/Status/Priority".
4. Observe vertical column dividers between every cell (┃ under the header, │ elsewhere). Previously this would render as a single header rule with no column dividers.
5. To verify the opt-out: add display.markdown_table_box_style: simple, restart, repeat — the legacy borderless layout returns.
6. To verify unknown-value safety: set display.markdown_table_box_style: not-a-real-style — the CLI must not crash, and tables must still render with dividers.

Automated coverage:

scripts/run_tests.sh tests/cli/test_cli_markdown_rendering.py -q
# 32 passed (14 existing + 18 new) in 1.5s

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(cli):, test(cli):, docs(cli):, docs(config):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix (no unrelated commits)
• I've run the relevant test suite locally and it passes
• I've added tests for my changes (18 new regression tests)
• Tested on my platform: macOS 15.2 (Darwin 24.6.0)

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/user-guide/cli.md)
• I've updated cli-config.yaml.example with the new config key
• N/A — no architecture or workflow changes
• N/A — pure terminal-output change, identical on every platform
• N/A — no tool descriptions / schemas changed

Screenshots / Logs

Before (default config, final_response_markdown: render):

           ──────────────────────
   Module     Status     Priority
           ──────────────────────
  User Mgmt    Done        P0
  Role Mgmt    Done        P0

After (default config, same input):

┏━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
┃ Module    ┃ Status ┃ Priority ┃
┡━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
│ User Mgmt │ Done   │ P0       │
│ Role Mgmt │ Done   │ P0       │
└───────────┴────────┴──────────┘

Opt out (display.markdown_table_box_style: simple) — legacy behaviour preserved verbatim.

Changed files

• cli-config.yaml.example (modified, +20/-0)
• cli.py (modified, +96/-2)
• hermes_cli/config.py (modified, +9/-0)
• tests/cli/test_cli_markdown_rendering.py (modified, +210/-3)
• website/docs/user-guide/cli.md (modified, +2/-0)