UAT: `agents session list --format json` returns inconsistent structure for empty vs non-empty session lists #3876

New issue

Open

opened 2026-04-06 07:05:44 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 07:05:44 +00:00

Owner

Metadata

Branch: fix/session-list-json-empty-inconsistent-structure
Commit Message: fix(cli): normalise session list JSON output structure for empty session lists
Milestone: (backlog — see note below)
Parent Epic: #362

Bug Report

Feature Area: Session Management CLI — JSON Output
Severity: Medium
Found by: UAT automated testing

What Was Tested

agents session list --format json with both empty and non-empty session lists.

Expected Behavior (from spec)

Per session_list_summary_dedup.feature, the JSON output should have a consistent structure regardless of whether sessions exist, with a summary key containing total, most_recent, oldest, total_messages, and storage fields.

Actual Behavior

When sessions exist:

{
  "sessions": [
    {"id": "...", "name": null, "actor": "openai/gpt-4", "messages": 0, "updated": "..."}
  ],
  "summary": {
    "total": 2,
    "most_recent": "...",
    "oldest": "...",
    "total_messages": 0,
    "storage": "0 KB"
  }
}

When no sessions exist:

{
  "sessions": [],
  "total": 0
}

Problems

The empty case has total at the top level, but the non-empty case has it inside summary
The empty case is missing the summary key entirely
The empty case is missing most_recent, oldest, total_messages, and storage fields

Code Location

src/cleveragents/cli/commands/session.py, list_sessions() function, around line 281:

if not sessions:
    if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value):
        typer.echo(format_output({"sessions": [], "total": 0}, fmt))
        return

Recommended Fix

The empty case should return the same structure as the non-empty case:

if not sessions:
    if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value):
        typer.echo(format_output({
            "sessions": [],
            "summary": {
                "total": 0,
                "most_recent": None,
                "oldest": None,
                "total_messages": 0,
                "storage": "0 KB"
            }
        }, fmt))
        return

Steps to Reproduce

Ensure no sessions exist (or use a fresh database)
Run: agents session list --format json
Observe the output structure is different from when sessions exist

Impact

Programmatic consumers that parse agents session list --format json output need to handle two different JSON structures. This is a usability issue for automation scripts and CI/CD pipelines.

Subtasks

Write a failing Behave scenario tagged @tdd_expected_fail in features/ that asserts the empty-list JSON response contains a summary key with total, most_recent, oldest, total_messages, and storage fields
Fix list_sessions() in src/cleveragents/cli/commands/session.py (~line 281) to return the full summary structure when the session list is empty
Remove the @tdd_expected_fail tag once the fix is in place and the scenario passes
Run nox -e lint and nox -e typecheck to confirm no regressions
Run nox -e unit_tests to confirm all tests pass
Run nox -e coverage_report to confirm coverage >= 97%

Definition of Done

agents session list --format json returns identical top-level JSON structure whether sessions exist or not
The empty-list response contains {"sessions": [], "summary": {"total": 0, "most_recent": null, "oldest": null, "total_messages": 0, "storage": "0 KB"}}
A Behave scenario covers both the empty and non-empty cases and asserts structural consistency
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/session-list-json-empty-inconsistent-structure` - **Commit Message**: `fix(cli): normalise session list JSON output structure for empty session lists` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: #362 ## Bug Report **Feature Area:** Session Management CLI — JSON Output **Severity:** Medium **Found by:** UAT automated testing ### What Was Tested `agents session list --format json` with both empty and non-empty session lists. ### Expected Behavior (from spec) Per `session_list_summary_dedup.feature`, the JSON output should have a **consistent structure** regardless of whether sessions exist, with a `summary` key containing `total`, `most_recent`, `oldest`, `total_messages`, and `storage` fields. ### Actual Behavior **When sessions exist:** ```json { "sessions": [ {"id": "...", "name": null, "actor": "openai/gpt-4", "messages": 0, "updated": "..."} ], "summary": { "total": 2, "most_recent": "...", "oldest": "...", "total_messages": 0, "storage": "0 KB" } } ``` **When no sessions exist:** ```json { "sessions": [], "total": 0 } ``` ### Problems 1. The empty case has `total` at the top level, but the non-empty case has it inside `summary` 2. The empty case is missing the `summary` key entirely 3. The empty case is missing `most_recent`, `oldest`, `total_messages`, and `storage` fields ### Code Location `src/cleveragents/cli/commands/session.py`, `list_sessions()` function, around line 281: ```python if not sessions: if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value): typer.echo(format_output({"sessions": [], "total": 0}, fmt)) return ``` ### Recommended Fix The empty case should return the same structure as the non-empty case: ```python if not sessions: if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value): typer.echo(format_output({ "sessions": [], "summary": { "total": 0, "most_recent": None, "oldest": None, "total_messages": 0, "storage": "0 KB" } }, fmt)) return ``` ### Steps to Reproduce 1. Ensure no sessions exist (or use a fresh database) 2. Run: `agents session list --format json` 3. Observe the output structure is different from when sessions exist ### Impact Programmatic consumers that parse `agents session list --format json` output need to handle two different JSON structures. This is a usability issue for automation scripts and CI/CD pipelines. ## Subtasks - [ ] Write a failing Behave scenario tagged `@tdd_expected_fail` in `features/` that asserts the empty-list JSON response contains a `summary` key with `total`, `most_recent`, `oldest`, `total_messages`, and `storage` fields - [ ] Fix `list_sessions()` in `src/cleveragents/cli/commands/session.py` (~line 281) to return the full `summary` structure when the session list is empty - [ ] Remove the `@tdd_expected_fail` tag once the fix is in place and the scenario passes - [ ] Run `nox -e lint` and `nox -e typecheck` to confirm no regressions - [ ] Run `nox -e unit_tests` to confirm all tests pass - [ ] Run `nox -e coverage_report` to confirm coverage >= 97% ## Definition of Done - [ ] `agents session list --format json` returns identical top-level JSON structure whether sessions exist or not - [ ] The empty-list response contains `{"sessions": [], "summary": {"total": 0, "most_recent": null, "oldest": null, "total_messages": 0, "storage": "0 KB"}}` - [ ] A Behave scenario covers both the empty and non-empty cases and asserts structural consistency - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 07:05:57 +00:00

#362 Epic: Security & Safety Hardening

freemo added the

Points

label

2026-04-06 07:09:31 +00:00

freemo referenced this issue

2026-04-06 07:13:52 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:21:26 +00:00