cleveragents/cleveragents-core

Fork 3

fix(tui): add plain text format support to session export command #3303

Merged

freemo merged 1 commit from fix/tui-conversation-export-plain-text into master

2026-04-05 21:10:19 +00:00

freemo commented

2026-04-05 09:27:21 +00:00

Owner

Summary

Adds plain text (.txt) as a supported export format for the TUI /session:export command, resolving a gap identified in UAT where users could export sessions as JSON or Markdown but had no format-agnostic plain text option. The new format produces a clean, human-readable transcript without any Markdown syntax.

Changes

src/cleveragents/domain/models/core/session.py — Added Session.as_export_plain_text() method that renders a session as a plain text transcript. The output begins with a structured header block (Session ID, Actor, Namespace, Created, Updated timestamps), followed by a "-" * 40 separator line, and then each message rendered as [seq] ROLE (timestamp):\ncontent. When the session contains no messages, a (no messages) placeholder line is emitted instead of the Markdown-styled *(no messages)* used by the existing md branch.
src/cleveragents/tui/commands.py — Extended TuiCommandRouter._session_export() to recognise "txt" as a valid format alongside the pre-existing "json" and "md" values. Added an elif fmt == "txt": dispatch branch that calls session.as_export_plain_text() and routes the result through the same file-write / success-message path used by the other formats. Updated the user-facing validation error message from "Use 'json' or 'md'." to "Use 'json', 'md', or 'txt'." so the help text stays accurate.
features/tui_session_export_import.feature — Added 5 new BDD scenarios:
1. /session:export txt returns a success message
2. /session:export txt <file> writes a file containing plain text
3. Exported plain text file contains the session header block and individual messages
4. Exporting a session with no messages produces a (no messages) placeholder
5. The format-validation error message now lists txt as an accepted value
features/steps/tui_session_export_import_steps.py — Added step definitions for all five new BDD scenarios, covering success-message assertions, file-content assertions, and error-message assertions.

Design Decisions

No Markdown in plain text output. The txt format is intentionally free of Markdown syntax so it can be read, diffed, or processed by tools that do not understand Markdown. Separator lines use "-" * 40 dashes rather than --- (which is a Markdown horizontal rule).
Consistent message reconstruction pattern. The as_export_plain_text() method reuses the same message-iteration logic already present in the md export branch, keeping the two implementations easy to compare and maintain.
(no messages) vs *(no messages)*. The plain text branch omits the Markdown emphasis asterisks used by the md branch, keeping the output format-neutral and consistent with the "no Markdown" contract of the txt format.
Minimal surface-area change. The format dispatch in _session_export() is a straightforward elif extension; no existing code paths were altered, reducing regression risk.

Testing

Unit tests (Behave): All existing scenarios pass; 5 new scenarios added and passing
Type checking (nox -e typecheck): 0 errors, 0 warnings
Linting (nox -e lint): All checks passed

Modules Affected

Module	Change
`src/cleveragents/domain/models/core/session.py`	New `as_export_plain_text()` method
`src/cleveragents/tui/commands.py`	`txt` format dispatch + updated error message
`features/tui_session_export_import.feature`	5 new BDD scenarios
`features/steps/tui_session_export_import_steps.py`	Step definitions for new scenarios

Closes #3036

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

## Summary Adds plain text (`.txt`) as a supported export format for the TUI `/session:export` command, resolving a gap identified in UAT where users could export sessions as JSON or Markdown but had no format-agnostic plain text option. The new format produces a clean, human-readable transcript without any Markdown syntax. ## Changes - **`src/cleveragents/domain/models/core/session.py`** — Added `Session.as_export_plain_text()` method that renders a session as a plain text transcript. The output begins with a structured header block (Session ID, Actor, Namespace, Created, Updated timestamps), followed by a `"-" * 40` separator line, and then each message rendered as `[seq] ROLE (timestamp):\ncontent`. When the session contains no messages, a `(no messages)` placeholder line is emitted instead of the Markdown-styled `*(no messages)*` used by the existing `md` branch. - **`src/cleveragents/tui/commands.py`** — Extended `TuiCommandRouter._session_export()` to recognise `"txt"` as a valid format alongside the pre-existing `"json"` and `"md"` values. Added an `elif fmt == "txt":` dispatch branch that calls `session.as_export_plain_text()` and routes the result through the same file-write / success-message path used by the other formats. Updated the user-facing validation error message from `"Use 'json' or 'md'."` to `"Use 'json', 'md', or 'txt'."` so the help text stays accurate. - **`features/tui_session_export_import.feature`** — Added 5 new BDD scenarios: 1. `/session:export txt` returns a success message 2. `/session:export txt <file>` writes a file containing plain text 3. Exported plain text file contains the session header block and individual messages 4. Exporting a session with no messages produces a `(no messages)` placeholder 5. The format-validation error message now lists `txt` as an accepted value - **`features/steps/tui_session_export_import_steps.py`** — Added step definitions for all five new BDD scenarios, covering success-message assertions, file-content assertions, and error-message assertions. ## Design Decisions - **No Markdown in plain text output.** The `txt` format is intentionally free of Markdown syntax so it can be read, diffed, or processed by tools that do not understand Markdown. Separator lines use `"-" * 40` dashes rather than `---` (which is a Markdown horizontal rule). - **Consistent message reconstruction pattern.** The `as_export_plain_text()` method reuses the same message-iteration logic already present in the `md` export branch, keeping the two implementations easy to compare and maintain. - **`(no messages)` vs `*(no messages)*`.** The plain text branch omits the Markdown emphasis asterisks used by the `md` branch, keeping the output format-neutral and consistent with the "no Markdown" contract of the `txt` format. - **Minimal surface-area change.** The format dispatch in `_session_export()` is a straightforward `elif` extension; no existing code paths were altered, reducing regression risk. ## Testing - **Unit tests (Behave):** All existing scenarios pass; 5 new scenarios added and passing - **Type checking (`nox -e typecheck`):** 0 errors, 0 warnings - **Linting (`nox -e lint`):** All checks passed ## Modules Affected | Module | Change | |---|---| | `src/cleveragents/domain/models/core/session.py` | New `as_export_plain_text()` method | | `src/cleveragents/tui/commands.py` | `txt` format dispatch + updated error message | | `features/tui_session_export_import.feature` | 5 new BDD scenarios | | `features/steps/tui_session_export_import_steps.py` | Step definitions for new scenarios | Closes #3036 --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo added this to the v3.7.0 milestone

2026-04-05 09:31:23 +00:00

freemo referenced this pull request

2026-04-05 09:42:43 +00:00

UAT: TUI Conversation Export missing plain text format — spec requires Markdown, JSON, and plain text; only JSON and Markdown are implemented #3036

freemo reviewed

2026-04-05 16:22:51 +00:00

freemo left a comment

Review Summary

Reviewed PR #3303 with focus on performance-implications, resource-usage, and scalability.

This PR adds plain text (txt) export format support to the TUI /session:export command, resolving a spec gap identified in UAT (issue #3036). The implementation adds a Session.as_export_plain_text() domain method and extends the TUI command router to dispatch to it.

Standard Criteria

✅ Specification Compliance: The spec states sessions should be exportable to "Markdown, JSON, and plain text." This PR closes the gap by implementing the missing txt format.

✅ Commit Message Format: Single atomic commit following Conventional Changelog format (fix(tui): add plain text format support to session export command) with ISSUES CLOSED: #3036 footer.

✅ PR Metadata: Closes #3036 present, milestone v3.7.0 matches issue, Type/Bug label applied.

✅ Type Safety: No # type: ignore suppressions. All new methods have proper return type annotations. Imports at top of file (deferred imports in _session_export follow the pre-existing pattern for the md branch).

✅ Error Handling: The new txt branch follows the same error handling pattern as the existing md branch, with the broad except Exception catch in _session_export providing user-friendly error messages.

✅ Test Quality: 5 new BDD scenarios covering: TUI command success, file output, content verification (header + messages), empty session placeholder, and error message validation. Step definitions are clean and well-structured.

✅ Code Correctness: The as_export_plain_text() method correctly produces format-neutral output without Markdown syntax. The (no messages) placeholder correctly omits the Markdown emphasis asterisks used by the md branch.

Deep Dive: Performance, Resource Usage, Scalability

Given special attention to performance implications:

1. Redundant Service Calls (Pre-existing, Non-blocking)

Location: src/cleveragents/tui/commands.py, _session_export() method

For md and txt formats, the code makes two service calls where one would suffice:

service.export_session(session_id) — called unconditionally before the format branch
service.get(session_id) — called inside the md/txt branches

The service.get() call returns a Session object that already contains all messages. The code then unnecessarily reconstructs SessionMessage objects from the export_data dict and overwrites session.messages. For md/txt formats, only service.get() is needed — the session object has everything as_export_markdown() and as_export_plain_text() require.

This means 2 database round-trips for md/txt exports where 1 would suffice. For typical session sizes this is negligible, but for sessions with thousands of messages, the redundant serialization/deserialization adds unnecessary overhead.

Note: This is a pre-existing issue from the md branch — the PR correctly follows the established pattern. A follow-up refactor could restructure the method to call export_session() only for json format and get() only for md/txt.

2. String Building Pattern (Acceptable)

The as_export_plain_text() method uses list[str] + "\n".join() for string building, which is the correct O(n) approach. For sessions with very large message counts, this scales linearly. No concerns here.

3. Memory Usage (Acceptable)

The plain text export builds the entire output string in memory before writing. For extremely large sessions (10K+ messages with long content), this could consume significant memory. However, this is the same pattern used by as_export_markdown() and as_export_dict(), so it's consistent. Streaming export would be a separate enhancement if needed.

Non-blocking Suggestions

[DRY] Duplicated message reconstruction (commands.py): The txt branch copies ~15 lines verbatim from the md branch (deferred import, service.get(), message reconstruction loop, session.messages assignment). Consider extracting a shared helper like _get_session_with_export_messages() to reduce duplication. This would also make adding future formats (e.g., csv, html) cleaner.
[TEST] Missing linked plans scenario: The markdown export has a dedicated test for linked plan IDs in the output (Scenario: Markdown export includes linked plan IDs), but the plain text export does not. The as_export_plain_text() method does handle linked plans — consider adding a parallel scenario to verify.
[FILE SIZE] session.py approaching limits: The file grew from ~21KB to ~23KB with this change. The project guideline is files under 500 lines. The export methods (as_export_dict, as_export_markdown, as_export_plain_text) could potentially be extracted to a dedicated session_export.py module in a future refactor, keeping the core domain model leaner.
[MINOR] Separator constant: The "-" * 40 separator string is computed each time as_export_plain_text() is called. While trivially cheap, it could be a module-level constant (like _PLAIN_TEXT_SEPARATOR = "-" * 40) for consistency with the existing EXPORT_SCHEMA_VERSION constant pattern.

Verdict

The implementation is correct, well-tested, and follows established patterns. The performance concerns identified are pre-existing and do not warrant blocking this bug fix. The "minimal surface-area change" design decision is appropriate for a targeted fix.

Decision: APPROVED ✅

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

## Review Summary Reviewed PR #3303 with focus on **performance-implications**, **resource-usage**, and **scalability**. This PR adds plain text (`txt`) export format support to the TUI `/session:export` command, resolving a spec gap identified in UAT (issue #3036). The implementation adds a `Session.as_export_plain_text()` domain method and extends the TUI command router to dispatch to it. ### Standard Criteria ✅ **Specification Compliance**: The spec states sessions should be exportable to "Markdown, JSON, and plain text." This PR closes the gap by implementing the missing `txt` format. ✅ **Commit Message Format**: Single atomic commit following Conventional Changelog format (`fix(tui): add plain text format support to session export command`) with `ISSUES CLOSED: #3036` footer. ✅ **PR Metadata**: `Closes #3036` present, milestone v3.7.0 matches issue, `Type/Bug` label applied. ✅ **Type Safety**: No `# type: ignore` suppressions. All new methods have proper return type annotations. Imports at top of file (deferred imports in `_session_export` follow the pre-existing pattern for the `md` branch). ✅ **Error Handling**: The new `txt` branch follows the same error handling pattern as the existing `md` branch, with the broad `except Exception` catch in `_session_export` providing user-friendly error messages. ✅ **Test Quality**: 5 new BDD scenarios covering: TUI command success, file output, content verification (header + messages), empty session placeholder, and error message validation. Step definitions are clean and well-structured. ✅ **Code Correctness**: The `as_export_plain_text()` method correctly produces format-neutral output without Markdown syntax. The `(no messages)` placeholder correctly omits the Markdown emphasis asterisks used by the `md` branch. ### Deep Dive: Performance, Resource Usage, Scalability Given special attention to performance implications: #### 1. Redundant Service Calls (Pre-existing, Non-blocking) **Location**: `src/cleveragents/tui/commands.py`, `_session_export()` method For `md` and `txt` formats, the code makes **two** service calls where one would suffice: - `service.export_session(session_id)` — called unconditionally before the format branch - `service.get(session_id)` — called inside the `md`/`txt` branches The `service.get()` call returns a `Session` object that **already contains all messages**. The code then unnecessarily reconstructs `SessionMessage` objects from the `export_data` dict and overwrites `session.messages`. For `md`/`txt` formats, only `service.get()` is needed — the session object has everything `as_export_markdown()` and `as_export_plain_text()` require. This means **2 database round-trips** for `md`/`txt` exports where 1 would suffice. For typical session sizes this is negligible, but for sessions with thousands of messages, the redundant serialization/deserialization adds unnecessary overhead. **Note**: This is a pre-existing issue from the `md` branch — the PR correctly follows the established pattern. A follow-up refactor could restructure the method to call `export_session()` only for `json` format and `get()` only for `md`/`txt`. #### 2. String Building Pattern (Acceptable) The `as_export_plain_text()` method uses `list[str]` + `"\n".join()` for string building, which is the correct O(n) approach. For sessions with very large message counts, this scales linearly. No concerns here. #### 3. Memory Usage (Acceptable) The plain text export builds the entire output string in memory before writing. For extremely large sessions (10K+ messages with long content), this could consume significant memory. However, this is the same pattern used by `as_export_markdown()` and `as_export_dict()`, so it's consistent. Streaming export would be a separate enhancement if needed. ### Non-blocking Suggestions 1. **[DRY] Duplicated message reconstruction** (`commands.py`): The `txt` branch copies ~15 lines verbatim from the `md` branch (deferred import, `service.get()`, message reconstruction loop, `session.messages` assignment). Consider extracting a shared helper like `_get_session_with_export_messages()` to reduce duplication. This would also make adding future formats (e.g., `csv`, `html`) cleaner. 2. **[TEST] Missing linked plans scenario**: The markdown export has a dedicated test for linked plan IDs in the output (`Scenario: Markdown export includes linked plan IDs`), but the plain text export does not. The `as_export_plain_text()` method does handle linked plans — consider adding a parallel scenario to verify. 3. **[FILE SIZE] session.py approaching limits**: The file grew from ~21KB to ~23KB with this change. The project guideline is files under 500 lines. The export methods (`as_export_dict`, `as_export_markdown`, `as_export_plain_text`) could potentially be extracted to a dedicated `session_export.py` module in a future refactor, keeping the core domain model leaner. 4. **[MINOR] Separator constant**: The `"-" * 40` separator string is computed each time `as_export_plain_text()` is called. While trivially cheap, it could be a module-level constant (like `_PLAIN_TEXT_SEPARATOR = "-" * 40`) for consistency with the existing `EXPORT_SCHEMA_VERSION` constant pattern. ### Verdict The implementation is correct, well-tested, and follows established patterns. The performance concerns identified are pre-existing and do not warrant blocking this bug fix. The "minimal surface-area change" design decision is appropriate for a targeted fix. **Decision: APPROVED** ✅ --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo added a new dependency

2026-04-05 17:34:50 +00:00

#3036 UAT: TUI Conversation Export missing plain text format — spec requires Markdown, JSON, and plain text; only JSON and Markdown are implemented

freemo referenced this pull request

2026-04-05 17:35:29 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this pull request

2026-04-05 17:51:27 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo force-pushed fix/tui-conversation-export-plain-text from df70ca4c9e

CI / benchmark-publish (pull_request) Waiting to run

Details

CI / lint (pull_request) Failing after 32s

Details

CI / typecheck (pull_request) Successful in 47s

Details

CI / quality (pull_request) Successful in 35s

Details

CI / security (pull_request) Successful in 58s

Details

CI / coverage (pull_request) Has been skipped

Details

CI / benchmark-regression (pull_request) Waiting to run

Details

CI / build (pull_request) Successful in 39s

Details

CI / helm (pull_request) Successful in 23s

Details

CI / unit_tests (pull_request) Successful in 6m53s

Details

CI / docker (pull_request) Has been skipped

Details

CI / e2e_tests (pull_request) Successful in 15m44s

Details

CI / integration_tests (pull_request) Successful in 22m31s

Details

CI / status-check (pull_request) Failing after 1s

Details

to 8d49a3b242

CI / lint (pull_request) Successful in 21s

Details

CI / typecheck (pull_request) Successful in 57s

Details

CI / security (pull_request) Successful in 1m4s

Details

CI / quality (pull_request) Successful in 35s

Details

CI / build (pull_request) Successful in 18s

Details

CI / helm (pull_request) Successful in 23s

Details

CI / unit_tests (pull_request) Successful in 7m0s

Details

CI / e2e_tests (pull_request) Successful in 15m25s

Details

CI / integration_tests (pull_request) Successful in 23m13s

Details

CI / coverage (pull_request) Successful in 11m18s

Details

CI / docker (pull_request) Successful in 1m29s

Details

CI / status-check (pull_request) Successful in 2s

Details

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / benchmark-regression (pull_request) Successful in 56m57s

Details

2026-04-05 17:52:35 +00:00

Compare

freemo commented

2026-04-05 17:52:47 +00:00

Author

Owner

CI Fix: Ruff Format Violation in `session.py`

The CI / lint check was failing due to a ruff format violation in src/cleveragents/domain/models/core/session.py.

Root cause: A multi-line lines.append(...) call in as_export_plain_text() was split across 3 lines but ruff's formatter collapses it to a single line since it fits within the line length limit:

# Before (failing format check):
lines.append(
    f"[{msg.sequence}] {msg.role.value.upper()} ({ts}):"
)

# After (passing format check):
lines.append(f"[{msg.sequence}] {msg.role.value.upper()} ({ts}):")

Fix applied: Ran ruff format on session.py and amended the commit. All checks now pass locally:

ruff check: ✅ All checks passed
ruff format --check: ✅ 3 files already formatted

CI re-triggered on the updated commit. Monitoring until all checks pass and PR is ready to merge.

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

## CI Fix: Ruff Format Violation in `session.py` The `CI / lint` check was failing due to a `ruff format` violation in `src/cleveragents/domain/models/core/session.py`. **Root cause:** A multi-line `lines.append(...)` call in `as_export_plain_text()` was split across 3 lines but ruff's formatter collapses it to a single line since it fits within the line length limit: ```python # Before (failing format check): lines.append( f"[{msg.sequence}] {msg.role.value.upper()} ({ts}):" ) # After (passing format check): lines.append(f"[{msg.sequence}] {msg.role.value.upper()} ({ts}):") ``` **Fix applied:** Ran `ruff format` on `session.py` and amended the commit. All checks now pass locally: - `ruff check`: ✅ All checks passed - `ruff format --check`: ✅ 3 files already formatted CI re-triggered on the updated commit. Monitoring until all checks pass and PR is ready to merge. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo reviewed

2026-04-05 19:44:04 +00:00

freemo left a comment

Review Summary

Reviewed PR #3303 with focus on error-handling-patterns, edge-cases, and boundary-conditions.

This PR adds plain text (txt) export format support to the TUI /session:export command, closing the spec gap identified in issue #3036. The implementation adds a Session.as_export_plain_text() domain method and extends the TUI command router to dispatch to it.

Standard Criteria

✅ Specification Compliance: The spec states sessions should be exportable to "Markdown, JSON, and plain text." This PR implements the missing txt format, closing the gap.

✅ Commit Message Format: Single atomic commit following Conventional Changelog format (fix(tui): add plain text format support to session export command) with ISSUES CLOSED: #3036 footer.

✅ PR Metadata: Closes #3036 present in body, milestone v3.7.0 matches issue, Type/Bug label applied.

✅ Type Safety: No # type: ignore suppressions. All new methods have proper return type annotations (-> str, -> None). Imports at top of file; deferred imports in _session_export follow the pre-existing pattern from the md branch.

Deep Dive: Error Handling Patterns

Given special attention to error handling:

1. `as_export_plain_text()` — Pure Transformation (Correct)

The new domain method is a pure data transformation on a Pydantic model with no I/O or external calls. All accessed fields (session_id, actor_name, namespace, created_at, updated_at, linked_plan_ids, messages) are guaranteed to exist by Pydantic validation at construction time. There are no error paths to handle, which is correct — the fail-fast principle is satisfied by the model validators.

2. TUI Command Handler — Follows Established Pattern (Acceptable)

The txt branch in _session_export() follows the same except Exception as exc: catch pattern as the pre-existing md and json branches. While broad exception catching is generally discouraged by the project's error handling rules, this is a TUI command handler where the recovery action (returning a user-friendly error string) is meaningful. The pattern is pre-existing and consistent.

3. Edge Cases Properly Handled

Empty messages: ✅ if not self.messages: → outputs (no messages) placeholder
No actor_name: ✅ self.actor_name or '(none)' fallback
No linked plans: ✅ Conditional if self.linked_plan_ids: skips the line entirely
Format validation: ✅ Updated to include "txt" in the allowed set; error message updated to list all three formats

4. Boundary Conditions Examined

Format dispatch boundary: The elif fmt == "txt": branch is correctly placed between md and the else (json) branch. No fall-through risk.
File write path: The txt branch correctly reuses the same file-write logic (Path.write_text() with encoding="utf-8") as the other formats.
Message reconstruction from export_data: The export_data.get("messages", []) pattern safely handles missing keys. The m["timestamp"] access is safe because export_session() always produces this field. (Pre-existing pattern from md branch.)

Non-blocking Suggestions

[TEST] Missing linked plans scenario for plain text: The markdown export has a dedicated test (Scenario: Markdown export includes linked plan IDs), but the plain text export does not. The as_export_plain_text() method does handle linked plans — consider adding a parallel scenario to verify the Linked Plans: line appears in plain text output. This would improve edge case coverage parity between the two lossy export formats.
[TEST] Missing actor name scenario for plain text: Similarly, the markdown export has Scenario: Markdown export includes actor and namespace but there's no equivalent for plain text. Consider adding a scenario that verifies Actor: openai/gpt-4 appears in the plain text output.
[TEST] File content verification: The Scenario: TUI session export with --format txt to file writes plain text only asserts the file exists, not that its content is valid plain text. Consider adding a step that reads the file and checks for expected content (e.g., And the tui exported file "/tmp/tui_test_export.txt" should contain "Session:").
[DRY] Duplicated message reconstruction (commands.py): The txt branch copies ~15 lines verbatim from the md branch (deferred import, service.get(), message reconstruction loop, session.messages assignment). Consider extracting a shared helper like _get_session_with_export_messages() to reduce duplication. This would also make adding future formats (e.g., csv, html) cleaner. (Pre-existing issue amplified by this PR.)
[MINOR] Separator constant: The "-" * 40 separator string is computed each time as_export_plain_text() is called. While trivially cheap, it could be a module-level constant (like _PLAIN_TEXT_SEPARATOR = "-" * 40) for consistency with the existing EXPORT_SCHEMA_VERSION constant pattern.

Verdict

The implementation is correct, well-tested, and follows established patterns. The error handling is appropriate for a TUI command handler context. All critical edge cases (empty messages, missing actor, missing plans) are properly handled. The boundary conditions around format validation and dispatch are clean. The non-blocking suggestions above would improve test parity with the markdown export but are not required for this targeted bug fix.

Decision: APPROVED ✅

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

## Review Summary Reviewed PR #3303 with focus on **error-handling-patterns**, **edge-cases**, and **boundary-conditions**. This PR adds plain text (`txt`) export format support to the TUI `/session:export` command, closing the spec gap identified in issue #3036. The implementation adds a `Session.as_export_plain_text()` domain method and extends the TUI command router to dispatch to it. ### Standard Criteria ✅ **Specification Compliance**: The spec states sessions should be exportable to "Markdown, JSON, and plain text." This PR implements the missing `txt` format, closing the gap. ✅ **Commit Message Format**: Single atomic commit following Conventional Changelog format (`fix(tui): add plain text format support to session export command`) with `ISSUES CLOSED: #3036` footer. ✅ **PR Metadata**: `Closes #3036` present in body, milestone v3.7.0 matches issue, `Type/Bug` label applied. ✅ **Type Safety**: No `# type: ignore` suppressions. All new methods have proper return type annotations (`-> str`, `-> None`). Imports at top of file; deferred imports in `_session_export` follow the pre-existing pattern from the `md` branch. ✅ **Code Correctness**: The `as_export_plain_text()` method correctly produces format-neutral output without Markdown syntax. The `(no messages)` placeholder correctly omits the Markdown emphasis asterisks used by the `md` branch. String building uses `list[str]` + `"\n".join()` — the correct O(n) approach. ✅ **Test Quality**: 5 new BDD scenarios covering: TUI command success, file output, content verification (header + messages), empty session placeholder, and error message validation. Step definitions are clean, well-typed, and follow existing patterns. ### Deep Dive: Error Handling Patterns Given special attention to error handling: #### 1. `as_export_plain_text()` — Pure Transformation (Correct) The new domain method is a pure data transformation on a Pydantic model with no I/O or external calls. All accessed fields (`session_id`, `actor_name`, `namespace`, `created_at`, `updated_at`, `linked_plan_ids`, `messages`) are guaranteed to exist by Pydantic validation at construction time. There are no error paths to handle, which is correct — the fail-fast principle is satisfied by the model validators. #### 2. TUI Command Handler — Follows Established Pattern (Acceptable) The `txt` branch in `_session_export()` follows the same `except Exception as exc:` catch pattern as the pre-existing `md` and `json` branches. While broad exception catching is generally discouraged by the project's error handling rules, this is a TUI command handler where the recovery action (returning a user-friendly error string) is meaningful. The pattern is pre-existing and consistent. #### 3. Edge Cases Properly Handled - **Empty messages**: ✅ `if not self.messages:` → outputs `(no messages)` placeholder - **No actor_name**: ✅ `self.actor_name or '(none)'` fallback - **No linked plans**: ✅ Conditional `if self.linked_plan_ids:` skips the line entirely - **Format validation**: ✅ Updated to include `"txt"` in the allowed set; error message updated to list all three formats #### 4. Boundary Conditions Examined - **Format dispatch boundary**: The `elif fmt == "txt":` branch is correctly placed between `md` and the `else` (json) branch. No fall-through risk. - **File write path**: The `txt` branch correctly reuses the same file-write logic (`Path.write_text()` with `encoding="utf-8"`) as the other formats. - **Message reconstruction from export_data**: The `export_data.get("messages", [])` pattern safely handles missing keys. The `m["timestamp"]` access is safe because `export_session()` always produces this field. (Pre-existing pattern from `md` branch.) ### Non-blocking Suggestions 1. **[TEST] Missing linked plans scenario for plain text**: The markdown export has a dedicated test (`Scenario: Markdown export includes linked plan IDs`), but the plain text export does not. The `as_export_plain_text()` method does handle linked plans — consider adding a parallel scenario to verify the `Linked Plans:` line appears in plain text output. This would improve edge case coverage parity between the two lossy export formats. 2. **[TEST] Missing actor name scenario for plain text**: Similarly, the markdown export has `Scenario: Markdown export includes actor and namespace` but there's no equivalent for plain text. Consider adding a scenario that verifies `Actor: openai/gpt-4` appears in the plain text output. 3. **[TEST] File content verification**: The `Scenario: TUI session export with --format txt to file writes plain text` only asserts the file exists, not that its content is valid plain text. Consider adding a step that reads the file and checks for expected content (e.g., `And the tui exported file "/tmp/tui_test_export.txt" should contain "Session:"`). 4. **[DRY] Duplicated message reconstruction** (`commands.py`): The `txt` branch copies ~15 lines verbatim from the `md` branch (deferred import, `service.get()`, message reconstruction loop, `session.messages` assignment). Consider extracting a shared helper like `_get_session_with_export_messages()` to reduce duplication. This would also make adding future formats (e.g., `csv`, `html`) cleaner. (Pre-existing issue amplified by this PR.) 5. **[MINOR] Separator constant**: The `"-" * 40` separator string is computed each time `as_export_plain_text()` is called. While trivially cheap, it could be a module-level constant (like `_PLAIN_TEXT_SEPARATOR = "-" * 40`) for consistency with the existing `EXPORT_SCHEMA_VERSION` constant pattern. ### Verdict The implementation is correct, well-tested, and follows established patterns. The error handling is appropriate for a TUI command handler context. All critical edge cases (empty messages, missing actor, missing plans) are properly handled. The boundary conditions around format validation and dispatch are clean. The non-blocking suggestions above would improve test parity with the markdown export but are not required for this targeted bug fix. **Decision: APPROVED** ✅ --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this pull request

2026-04-05 19:48:58 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this pull request

2026-04-05 20:07:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this pull request

2026-04-05 20:54:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this pull request

2026-04-05 21:00:52 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377