fix(tui): session export missing --format md (Markdown) option per spec #1351

New issue

Open

opened 2026-04-02 16:57:11 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 16:57:11 +00:00

Owner

Deviation from Specification

Spec section: TUI → Conversation Export (§ "Conversation Export")

The specification defines two export formats for /session:export:

Format	Command / Trigger	Output
JSON	`/session:export [path]`	Full session data including A2A messages, metadata, timestamps
Markdown	`/session:export --format md [path]`	Human-readable conversation transcript with Markdown formatting

The JSON export format is the canonical format for /session:import — it contains all data needed to fully restore a session. The Markdown format is a lossy export intended for sharing and documentation.

Current Implementation

The CLI agents session export command and the TUI /session:export slash command only support JSON output. There is no --format flag and no Markdown rendering path:

src/cleveragents/cli/commands/session.py — export_session() writes JSON only
src/cleveragents/tui/slash_catalog.py — description says "Export session to JSON" (no mention of Markdown)
src/cleveragents/application/services/session_service.py — export_session() returns dict[str, Any] (JSON only)
src/cleveragents/domain/models/core/session.py — as_export_dict() returns JSON dict only

Required Changes

Metadata

Commit message: feat(tui): add --format md option to session export for Markdown transcript
Branch name: feat/session-export-markdown

Subtasks

Add ExportFormat enum (json, markdown) to session.py
Add Session.as_markdown() method that renders conversation messages as a human-readable Markdown transcript (lossy — no A2A metadata, just content)
Update SessionService.export_session() to accept format: ExportFormat = ExportFormat.JSON parameter
Update CLI agents session export to add --format [json|md] option (default: json)
Update TUI slash catalog description for session:export to reflect both formats
Add Behave scenarios covering Markdown export path
Update Robot Framework integration test for session export

Definition of Done

agents session export <id> --format md produces a Markdown transcript
agents session export <id> (no flag) still produces JSON (backward compatible)
/session:export --format md [path] works in TUI
Coverage gate passes (≥97%)
All nox sessions pass
PR merged and this issue closed

References

Spec: "Conversation Export" section in TUI specification
Merged PR #1269 (session export/import) — closed without merge, may need revisiting

## Deviation from Specification **Spec section**: TUI → Conversation Export (§ "Conversation Export") The specification defines two export formats for `/session:export`: | Format | Command / Trigger | Output | |--------|------------------|--------| | JSON | `/session:export [path]` | Full session data including A2A messages, metadata, timestamps | | Markdown | `/session:export --format md [path]` | Human-readable conversation transcript with Markdown formatting | > The JSON export format is the canonical format for `/session:import` — it contains all data needed to fully restore a session. The Markdown format is a lossy export intended for sharing and documentation. ## Current Implementation The CLI `agents session export` command and the TUI `/session:export` slash command only support JSON output. There is no `--format` flag and no Markdown rendering path: - `src/cleveragents/cli/commands/session.py` — `export_session()` writes JSON only - `src/cleveragents/tui/slash_catalog.py` — description says "Export session to JSON" (no mention of Markdown) - `src/cleveragents/application/services/session_service.py` — `export_session()` returns `dict[str, Any]` (JSON only) - `src/cleveragents/domain/models/core/session.py` — `as_export_dict()` returns JSON dict only ## Required Changes ### Metadata - **Commit message**: `feat(tui): add --format md option to session export for Markdown transcript` - **Branch name**: `feat/session-export-markdown` ### Subtasks - [ ] Add `ExportFormat` enum (`json`, `markdown`) to `session.py` - [ ] Add `Session.as_markdown()` method that renders conversation messages as a human-readable Markdown transcript (lossy — no A2A metadata, just content) - [ ] Update `SessionService.export_session()` to accept `format: ExportFormat = ExportFormat.JSON` parameter - [ ] Update CLI `agents session export` to add `--format [json|md]` option (default: `json`) - [ ] Update TUI slash catalog description for `session:export` to reflect both formats - [ ] Add Behave scenarios covering Markdown export path - [ ] Update Robot Framework integration test for session export ### Definition of Done - [ ] `agents session export <id> --format md` produces a Markdown transcript - [ ] `agents session export <id>` (no flag) still produces JSON (backward compatible) - [ ] `/session:export --format md [path]` works in TUI - [ ] Coverage gate passes (≥97%) - [ ] All nox sessions pass - [ ] PR merged and this issue closed ## References - Spec: "Conversation Export" section in TUI specification - Merged PR #1269 (session export/import) — closed without merge, may need revisiting

Rows
Columns