cleveragents/cleveragents-core

Fork 3

UAT: PR #2629 — session list --format json uses inconsistent structure for empty list (top-level total vs summary.total) #2784

New issue

Open

opened 2026-04-04 19:27:47 +00:00 by freemo · 4 comments

freemo commented

2026-04-04 19:27:47 +00:00

Owner

Bug Report

PR Under Test: #2629 (branch fix/master-ci-quality-gates, HEAD 938ea8194c6a)
Feature Area: Session CLI output format changes
Severity: Medium

What Was Tested

The agents session list --format json command was tested for JSON output structure consistency between empty and non-empty session lists.

Expected Behavior (from spec / PR description)

The PR description states that the fix includes:

Session list JSON: top-level total → nested summary.total

All JSON output from agents session list should use the nested summary.total structure:

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

Actual Behavior

Non-empty list (correct): Uses summary.total:

{
  "sessions": [...],
  "summary": {
    "total": 2,
    "most_recent": "...",
    "oldest": "...",
    "total_messages": 1,
    "storage": "0 KB"
  }
}

Empty list (INCORRECT): Uses top-level total:

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

Code Location

src/cleveragents/cli/commands/session.py, line 295, in the list_sessions command:

# Empty sessions path — WRONG: uses top-level total
if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value):
    typer.echo(format_output({"sessions": [], "total": 0}, fmt))
    return

The non-empty path correctly uses _session_list_dict() which returns {"sessions": items, "summary": {"total": ...}}.

Steps to Reproduce

from unittest.mock import MagicMock
from typer.testing import CliRunner
from cleveragents.cli.commands import session as session_mod
from cleveragents.cli.commands.session import app as session_app
import json

runner = CliRunner()
svc = MagicMock()
svc.list.return_value = []
session_mod._service = svc
result = runner.invoke(session_app, ['list', '--format', 'json'])
session_mod._service = None
data = json.loads(result.output)
print(data)  # {'sessions': [], 'total': 0}  ← top-level total, not summary.total

Impact

Any caller parsing agents session list --format json output will get different structures depending on whether sessions exist
The tdd_session_create_persist_steps.py already has a workaround for this inconsistency (line 86-87): data["total"] if "total" in data else data.get("summary", {}).get("total")
The session_list_error.feature "Empty session list with plain format" test asserts "total: 0" which relies on the inconsistent top-level structure

Fix Required

Change line 295 in session.py from:

typer.echo(format_output({"sessions": [], "total": 0}, fmt))

to:

typer.echo(format_output({"sessions": [], "summary": {"total": 0}}, fmt))

And update session_list_error.feature to assert "total: 0" under summary: in the plain format test.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Bug Report **PR Under Test**: #2629 (branch `fix/master-ci-quality-gates`, HEAD `938ea8194c6a`) **Feature Area**: Session CLI output format changes **Severity**: Medium ## What Was Tested The `agents session list --format json` command was tested for JSON output structure consistency between empty and non-empty session lists. ## Expected Behavior (from spec / PR description) The PR description states that the fix includes: > Session list JSON: top-level `total` → nested `summary.total` All JSON output from `agents session list` should use the nested `summary.total` structure: ```json { "sessions": [...], "summary": { "total": 0, ... } } ``` ## Actual Behavior **Non-empty list** (correct): Uses `summary.total`: ```json { "sessions": [...], "summary": { "total": 2, "most_recent": "...", "oldest": "...", "total_messages": 1, "storage": "0 KB" } } ``` **Empty list** (INCORRECT): Uses top-level `total`: ```json { "sessions": [], "total": 0 } ``` ## Code Location `src/cleveragents/cli/commands/session.py`, line 295, in the `list_sessions` command: ```python # Empty sessions path — WRONG: uses top-level total if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value): typer.echo(format_output({"sessions": [], "total": 0}, fmt)) return ``` The non-empty path correctly uses `_session_list_dict()` which returns `{"sessions": items, "summary": {"total": ...}}`. ## Steps to Reproduce ```python from unittest.mock import MagicMock from typer.testing import CliRunner from cleveragents.cli.commands import session as session_mod from cleveragents.cli.commands.session import app as session_app import json runner = CliRunner() svc = MagicMock() svc.list.return_value = [] session_mod._service = svc result = runner.invoke(session_app, ['list', '--format', 'json']) session_mod._service = None data = json.loads(result.output) print(data) # {'sessions': [], 'total': 0} ← top-level total, not summary.total ``` ## Impact - Any caller parsing `agents session list --format json` output will get different structures depending on whether sessions exist - The `tdd_session_create_persist_steps.py` already has a workaround for this inconsistency (line 86-87): `data["total"] if "total" in data else data.get("summary", {}).get("total")` - The `session_list_error.feature` "Empty session list with plain format" test asserts `"total: 0"` which relies on the inconsistent top-level structure ## Fix Required Change line 295 in `session.py` from: ```python typer.echo(format_output({"sessions": [], "total": 0}, fmt)) ``` to: ```python typer.echo(format_output({"sessions": [], "summary": {"total": 0}}, fmt)) ``` And update `session_list_error.feature` to assert `"total: 0"` under `summary:` in the plain format test. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo referenced this issue

2026-04-04 19:28:30 +00:00

fix(ci): restore all CI quality gates to passing on master #2629

freemo referenced this issue

2026-04-04 19:31:54 +00:00

[CA-AUTO] UAT Pool Supervisor — PR #2629 Validation — Session Tracker #2752

freemo referenced this issue

2026-04-04 19:32:11 +00:00

fix(ci): restore all CI quality gates to passing on master #2629

freemo referenced this issue

2026-04-04 19:35:08 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue

2026-04-04 19:36:21 +00:00

[CA-AUTO] UAT Pool Supervisor — PR #2629 Validation — Session Tracker #2752

freemo added the

MoSCoW

Could have

label

2026-04-04 19:37:03 +00:00

freemo commented

2026-04-04 19:37:18 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified | MoSCoW: Could Have — Inconsistent JSON structure for empty vs non-empty session lists is a minor API consistency issue.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified | **MoSCoW**: Could Have — Inconsistent JSON structure for empty vs non-empty session lists is a minor API consistency issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-04 19:42:22 +00:00

[CA-AUTO] System Watchdog Session State (watchdog-1) #2756

freemo referenced this issue

2026-04-04 20:42:57 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo commented

2026-04-04 20:43:42 +00:00

Author

Owner

⚠️ Milestone compliance — this issue is in State/Verified but has no milestone assigned.

Per CONTRIBUTING.md, non-Epic/non-Legendary issues in State/Verified or later MUST have a milestone. Please assign this issue to the appropriate milestone (likely v3.2.0 since it's a UAT bug related to PR #2629 which targets v3.2.0).

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

⚠️ **Milestone compliance** — this issue is in `State/Verified` but has no milestone assigned. Per CONTRIBUTING.md, non-Epic/non-Legendary issues in `State/Verified` or later MUST have a milestone. Please assign this issue to the appropriate milestone (likely v3.2.0 since it's a UAT bug related to PR #2629 which targets v3.2.0). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-04 20:43:57 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue

2026-04-04 21:08:24 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo added this to the v3.2.0 milestone

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

freemo commented

2026-04-05 04:50:55 +00:00

Author

Owner

Milestone compliance fix applied:

Assigned to milestone: v3.2.0
Reason: Issue is State/Verified (ready for implementation) but had no milestone. This is a session CLI bug that should be addressed in the earliest active milestone.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Milestone compliance fix applied: - Assigned to milestone: `v3.2.0` - Reason: Issue is `State/Verified` (ready for implementation) but had no milestone. This is a session CLI bug that should be addressed in the earliest active milestone. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 04:51:28 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo removed this from the v3.2.0 milestone

2026-04-06 22:29:20 +00:00

freemo commented

2026-04-06 22:29:37 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.