cleveragents/cleveragents-core

Fork 3

UAT: `agents session show` JSON output uses wrong field names and wrong data types for recent_messages and linked_plans #3440

New issue

Closed

opened 2026-04-05 16:50:46 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 16:50:46 +00:00

Owner

Metadata

Branch: bugfix/session-show-as-cli-dict-field-names
Commit Message: fix(session): correct field names and data types in Session.as_cli_dict() for spec compliance
Milestone: (none — backlog)
Parent Epic: #397

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

Background and Context

Code-level analysis of src/cleveragents/domain/models/core/session.py (as_cli_dict() method, lines 330–371) against docs/specification.md §"agents session show" JSON example (lines 1798–1835) revealed that the method returns incorrect field names and incorrect data structures throughout.

This is a spec compliance failure: the JSON output of agents session show is the primary machine-readable interface for automation and tooling. Incorrect field names and data types break any downstream consumer relying on the documented contract.

Related issue: #3402 covers the broader JSON envelope compliance problem (missing command, status, exit_code, data, timing, messages wrapper) across all session subcommands. This issue is specifically scoped to the field-level violations inside as_cli_dict() itself.

Expected Behavior (from spec §"agents session show", lines 1798–1835)

{
  "data": {
    "session_summary": {
      "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
      "actor": "local/orchestrator",
      "messages": 6,
      "created": "2026-02-08T12:30:00Z",
      "updated": "2026-02-08T12:44:00Z",
      "automation": "review"
    },
    "recent_messages": [
      { "role": "user", "text": "Create an action to refresh dependency locks" }
    ],
    "linked_plans": [
      {
        "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
        "phase": "execute",
        "state": "complete"
      }
    ],
    "token_usage": {
      "input_tokens": 3420,
      "output_tokens": 1185,
      "estimated_cost": "$0.0184"
    }
  }
}

Actual Behavior

Session.as_cli_dict() in src/cleveragents/domain/models/core/session.py (lines 330–371) currently returns:

result["session_id"] = self.session_id          # ❌ should be "id"
result["actor_name"] = self.actor_name          # ❌ should be "actor"
result["namespace"] = self.namespace            # ❌ not in spec's session_summary
result["message_count"] = self.message_count    # ❌ should be "messages"
result["created_at"] = self.created_at.isoformat()  # ❌ should be "created"
result["updated_at"] = self.updated_at.isoformat()  # ❌ should be "updated"
# ❌ Missing: "automation" field entirely
result["recent_messages"] = [
    {"role": m.role.value, "content": m.content}  # ❌ "content" should be "text"
    for m in recent
]
result["linked_plan_ids"] = list(self.linked_plan_ids)  # ❌ should be "linked_plans" with objects
# linked_plan_ids is a flat list of strings, not objects with plan_id/phase/state
result["token_usage"] = {
    "input_tokens": ...,
    "output_tokens": ...,
    "estimated_cost": ...,  # ❌ spec shows "$0.0184" (string), code stores float
}

Specific Violations

#	Current key / value	Spec-required key / value
1	`session_id`	`id`
2	`actor_name`	`actor`
3	`message_count`	`messages`
4	`created_at`	`created`
5	`updated_at`	`updated`
6	(missing)	`automation` field in `session_summary`
7	`recent_messages[].content`	`recent_messages[].text`
8	`linked_plan_ids` (flat `list[str]`)	`linked_plans` (list of objects: `{plan_id, phase, state}`)
9	`estimated_cost` as `float`	`estimated_cost` as formatted string e.g. `"$0.0184"`

Architectural Note

The linked_plan_ids domain model field (line 200 of session.py) stores only plan ULIDs as a flat list. To produce linked_plans objects with phase and state, either:

The domain model must be extended to store LinkedPlan value objects (with plan_id, phase, state), or
The show command must look up plan details from the plan service at display time.

This architectural decision must be made before implementing the fix. See also #3413 which has the same dependency.

Code Location

src/cleveragents/domain/models/core/session.py, as_cli_dict() method, lines 330–371

Subtasks

Decide on architectural approach for surfacing plan phase and state in as_cli_dict() (extend domain model with LinkedPlan objects vs. plan service lookup at display time)
Rename session_id → id in as_cli_dict() output
Rename actor_name → actor in as_cli_dict() output
Remove namespace from as_cli_dict() output (not in spec's session_summary)
Rename message_count → messages in as_cli_dict() output
Rename created_at → created in as_cli_dict() output
Rename updated_at → updated in as_cli_dict() output
Add missing automation field to as_cli_dict() output
Rename recent_messages[].content → recent_messages[].text in as_cli_dict() output
Replace linked_plan_ids (flat list of strings) with linked_plans (list of {plan_id, phase, state} objects) in as_cli_dict() output
Change token_usage.estimated_cost from float to formatted string (e.g. "$0.0184") in as_cli_dict() output
Update or extend the Session domain model if the LinkedPlan storage approach is chosen
Tests (Behave): Add/update scenarios asserting all corrected field names and data types in agents session show --format json output
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

Session.as_cli_dict() returns field names exactly matching the spec: id, actor, messages, created, updated, automation, recent_messages[].text, linked_plans (as objects with plan_id/phase/state), and estimated_cost as a formatted string
The automation field is populated correctly in the output
linked_plans contains objects with plan_id, phase, and state (not a flat list of strings)
estimated_cost is serialized as a formatted string (e.g. "$0.0184") not a raw float
All Behave scenarios for agents session show --format json field compliance pass
Domain model changes (if any) are fully typed and pass nox -e typecheck
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `bugfix/session-show-as-cli-dict-field-names` - **Commit Message**: `fix(session): correct field names and data types in Session.as_cli_dict() for spec compliance` - **Milestone**: *(none — backlog)* - **Parent Epic**: #397 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context Code-level analysis of `src/cleveragents/domain/models/core/session.py` (`as_cli_dict()` method, lines 330–371) against `docs/specification.md` §"agents session show" JSON example (lines 1798–1835) revealed that the method returns incorrect field names and incorrect data structures throughout. This is a spec compliance failure: the JSON output of `agents session show` is the primary machine-readable interface for automation and tooling. Incorrect field names and data types break any downstream consumer relying on the documented contract. **Related issue:** #3402 covers the broader JSON envelope compliance problem (missing `command`, `status`, `exit_code`, `data`, `timing`, `messages` wrapper) across all session subcommands. This issue is specifically scoped to the field-level violations inside `as_cli_dict()` itself. ## Expected Behavior (from spec §"agents session show", lines 1798–1835) ```json { "data": { "session_summary": { "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", "actor": "local/orchestrator", "messages": 6, "created": "2026-02-08T12:30:00Z", "updated": "2026-02-08T12:44:00Z", "automation": "review" }, "recent_messages": [ { "role": "user", "text": "Create an action to refresh dependency locks" } ], "linked_plans": [ { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "phase": "execute", "state": "complete" } ], "token_usage": { "input_tokens": 3420, "output_tokens": 1185, "estimated_cost": "$0.0184" } } } ``` ## Actual Behavior `Session.as_cli_dict()` in `src/cleveragents/domain/models/core/session.py` (lines 330–371) currently returns: ```python result["session_id"] = self.session_id # ❌ should be "id" result["actor_name"] = self.actor_name # ❌ should be "actor" result["namespace"] = self.namespace # ❌ not in spec's session_summary result["message_count"] = self.message_count # ❌ should be "messages" result["created_at"] = self.created_at.isoformat() # ❌ should be "created" result["updated_at"] = self.updated_at.isoformat() # ❌ should be "updated" # ❌ Missing: "automation" field entirely result["recent_messages"] = [ {"role": m.role.value, "content": m.content} # ❌ "content" should be "text" for m in recent ] result["linked_plan_ids"] = list(self.linked_plan_ids) # ❌ should be "linked_plans" with objects # linked_plan_ids is a flat list of strings, not objects with plan_id/phase/state result["token_usage"] = { "input_tokens": ..., "output_tokens": ..., "estimated_cost": ..., # ❌ spec shows "$0.0184" (string), code stores float } ``` ## Specific Violations | # | Current key / value | Spec-required key / value | |---|---|---| | 1 | `session_id` | `id` | | 2 | `actor_name` | `actor` | | 3 | `message_count` | `messages` | | 4 | `created_at` | `created` | | 5 | `updated_at` | `updated` | | 6 | *(missing)* | `automation` field in `session_summary` | | 7 | `recent_messages[].content` | `recent_messages[].text` | | 8 | `linked_plan_ids` (flat `list[str]`) | `linked_plans` (list of objects: `{plan_id, phase, state}`) | | 9 | `estimated_cost` as `float` | `estimated_cost` as formatted string e.g. `"$0.0184"` | ## Architectural Note The `linked_plan_ids` domain model field (line 200 of `session.py`) stores only plan ULIDs as a flat list. To produce `linked_plans` objects with `phase` and `state`, either: - The domain model must be extended to store `LinkedPlan` value objects (with `plan_id`, `phase`, `state`), **or** - The `show` command must look up plan details from the plan service at display time. This architectural decision must be made before implementing the fix. See also #3413 which has the same dependency. ## Code Location `src/cleveragents/domain/models/core/session.py`, `as_cli_dict()` method, lines 330–371 ## Subtasks - [ ] Decide on architectural approach for surfacing plan `phase` and `state` in `as_cli_dict()` (extend domain model with `LinkedPlan` objects vs. plan service lookup at display time) - [ ] Rename `session_id` → `id` in `as_cli_dict()` output - [ ] Rename `actor_name` → `actor` in `as_cli_dict()` output - [ ] Remove `namespace` from `as_cli_dict()` output (not in spec's `session_summary`) - [ ] Rename `message_count` → `messages` in `as_cli_dict()` output - [ ] Rename `created_at` → `created` in `as_cli_dict()` output - [ ] Rename `updated_at` → `updated` in `as_cli_dict()` output - [ ] Add missing `automation` field to `as_cli_dict()` output - [ ] Rename `recent_messages[].content` → `recent_messages[].text` in `as_cli_dict()` output - [ ] Replace `linked_plan_ids` (flat list of strings) with `linked_plans` (list of `{plan_id, phase, state}` objects) in `as_cli_dict()` output - [ ] Change `token_usage.estimated_cost` from `float` to formatted string (e.g. `"$0.0184"`) in `as_cli_dict()` output - [ ] Update or extend the `Session` domain model if the `LinkedPlan` storage approach is chosen - [ ] Tests (Behave): Add/update scenarios asserting all corrected field names and data types in `agents session show --format json` output - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] `Session.as_cli_dict()` returns field names exactly matching the spec: `id`, `actor`, `messages`, `created`, `updated`, `automation`, `recent_messages[].text`, `linked_plans` (as objects with `plan_id`/`phase`/`state`), and `estimated_cost` as a formatted string - [ ] The `automation` field is populated correctly in the output - [ ] `linked_plans` contains objects with `plan_id`, `phase`, and `state` (not a flat list of strings) - [ ] `estimated_cost` is serialized as a formatted string (e.g. `"$0.0184"`) not a raw float - [ ] All Behave scenarios for `agents session show --format json` field compliance pass - [ ] Domain model changes (if any) are fully typed and pass `nox -e typecheck` - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

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

#397 Epic: Server & Autonomy Infrastructure

freemo added this to the v3.7.0 milestone

2026-04-05 17:06:16 +00:00

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Backlog (confirmed) — Session show JSON output uses wrong field names. Spec compliance issue but does not block core functionality.
Milestone: v3.7.0 (assigned — session output formatting is part of the broader CLI/TUI polish)
Story Points: 5 (L) — 9 field name/type violations to fix, plus architectural decision needed for linked_plans (domain model extension vs. service lookup)
MoSCoW: Could Have — Output field names are wrong but the command works. Downstream JSON consumers don't exist yet in production.
Parent Epic: #397 (Server & Autonomy Infrastructure)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (confirmed) — Session show JSON output uses wrong field names. Spec compliance issue but does not block core functionality. - **Milestone**: v3.7.0 (assigned — session output formatting is part of the broader CLI/TUI polish) - **Story Points**: 5 (L) — 9 field name/type violations to fix, plus architectural decision needed for `linked_plans` (domain model extension vs. service lookup) - **MoSCoW**: Could Have — Output field names are wrong but the command works. Downstream JSON consumers don't exist yet in production. - **Parent Epic**: #397 (Server & Autonomy Infrastructure) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 17:07:19 +00:00

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

freemo referenced this issue from a commit

2026-04-05 17:56:09 +00:00

fix(session): correct field names and data types in Session.as_cli_dict() for spec compliance

freemo referenced this issue from a pull request that will close it,

2026-04-05 17:56:28 +00:00

fix(session): correct field names and data types in Session.as_cli_dict() for spec compliance #3461

freemo closed this issue

2026-04-05 18:19:20 +00:00

freemo referenced this issue from a commit

2026-04-05 18:19:20 +00:00

fix(session): correct field names and data types in Session.as_cli_dict() for spec compliance

freemo commented

2026-04-05 18:19:34 +00:00

Author

Owner

PR #3461 has been merged successfully! 🎉

Summary of Changes

All 11 spec violations in Session.as_cli_dict() have been fixed:

#	Was	Now
1	`session_id` (top-level)	`session_summary.id`
2	`actor_name`	`session_summary.actor`
3	`message_count`	`session_summary.messages`
4	`created_at`	`session_summary.created`
5	`updated_at`	`session_summary.updated`
6	`namespace` (present)	removed from output
7	(missing)	`session_summary.automation` added
8	`recent_messages[].content`	`recent_messages[].text`
9	`linked_plan_ids` (flat list)	`linked_plans` (objects with `plan_id`, `phase`, `state`)
10	`estimated_cost` as float	`estimated_cost` as formatted string (e.g. `"$0.0184"`)

Architectural decision: Added LinkedPlan value object to the Session domain model to store plan phase and state alongside the plan ID.

Quality gates: lint ✅, typecheck ✅ (0 errors, 0 warnings)

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

PR #3461 has been merged successfully! 🎉 ## Summary of Changes All 11 spec violations in `Session.as_cli_dict()` have been fixed: | # | Was | Now | |---|---|---| | 1 | `session_id` (top-level) | `session_summary.id` | | 2 | `actor_name` | `session_summary.actor` | | 3 | `message_count` | `session_summary.messages` | | 4 | `created_at` | `session_summary.created` | | 5 | `updated_at` | `session_summary.updated` | | 6 | `namespace` (present) | removed from output | | 7 | *(missing)* | `session_summary.automation` added | | 8 | `recent_messages[].content` | `recent_messages[].text` | | 9 | `linked_plan_ids` (flat list) | `linked_plans` (objects with `plan_id`, `phase`, `state`) | | 10 | `estimated_cost` as float | `estimated_cost` as formatted string (e.g. `"$0.0184"`) | **Architectural decision**: Added `LinkedPlan` value object to the Session domain model to store plan phase and state alongside the plan ID. **Quality gates**: lint ✅, typecheck ✅ (0 errors, 0 warnings) --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo referenced this issue

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

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