UAT: `agents session show` JSON/YAML output deviates from spec — uses `session_id` instead of `id`, missing `automation` field, wrong key names #2997

New issue

Open

opened 2026-04-05 03:24:26 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 03:24:26 +00:00

Owner

Metadata

Branch: fix/session-show-json-yaml-output-spec-deviation
Commit Message: fix(cli): align agents session show JSON/YAML output envelope with spec — use id, add automation field, fix all key names
Milestone: v3.2.0
Parent Epic: #868

Background and Context

The agents session show command's JSON and YAML output format deviates from the specification. The spec defines a structured envelope with session_summary, recent_messages, linked_plans, and token_usage keys nested under data, but the implementation's as_cli_dict() method returns different field names and a structurally incorrect shape.

Per docs/specification.md (section "agents session show"), the specification is the authoritative source of truth. When the codebase deviates from the specification, the code must be updated to match it.

Code Location: src/cleveragents/domain/models/core/session.py, as_cli_dict() method (lines ~320–370)

Expected Behaviour (from spec)

{
  "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" },
      { "role": "assistant", "text": "Plan created, running commands..." }
    ],
    "linked_plans": [
      { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "phase": "execute", "state": "complete" }
    ],
    "token_usage": {
      "input_tokens": 3420,
      "output_tokens": 1185,
      "estimated_cost": "$0.0184"
    }
  }
}

Actual Behaviour

The as_cli_dict() method 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 in session_summary
# recent_messages uses "content" key instead of "text"
# linked_plans is a flat list of ULID strings, not objects with plan_id/phase/state

Deviations from Spec

#	Field / Structure	Actual	Expected
1	Session ID key	`session_id`	`id`
2	Actor key	`actor_name`	`actor`
3	Message count key	`message_count`	`messages`
4	Created timestamp key	`created_at`	`created`
5	Updated timestamp key	`updated_at`	`updated`
6	Automation field	Missing	`"automation": "<profile-name>"`
7	Message text key	`content`	`text`
8	`linked_plans` shape	Flat list of ULID strings	List of `{ plan_id, phase, state }` objects

Severity: Medium — the JSON/YAML output format is a spec contract consumed by scripts and integrations.

Subtasks

Audit as_cli_dict() in src/cleveragents/domain/models/core/session.py against the spec's agents session show JSON schema
Rename session_id → id in the session_summary sub-dict
Rename actor_name → actor in the session_summary sub-dict
Remove the non-spec namespace field from session_summary
Rename message_count → messages in the session_summary sub-dict
Rename created_at → created in the session_summary sub-dict
Rename updated_at → updated in the session_summary sub-dict
Add the missing automation field to session_summary
Fix recent_messages entries to use text key instead of content
Fix linked_plans to return a list of { plan_id, phase, state } objects instead of flat ULID strings
Write/update Behave BDD scenarios in features/ covering all corrected field names and structures
Ensure all nox quality gates pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report)
Open a PR, link it to this issue, and obtain two approving reviews

Definition of Done

as_cli_dict() output exactly matches the spec's agents session show JSON envelope for all fields: id, actor, messages, created, updated, automation in session_summary
recent_messages entries use text key (not content)
linked_plans entries are objects with plan_id, phase, and state keys
The non-spec namespace field is removed from session_summary
Behave BDD scenarios cover all eight deviations listed above
All nox stages pass
Coverage >= 97%
PR merged and this issue closed

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

## Metadata - **Branch**: `fix/session-show-json-yaml-output-spec-deviation` - **Commit Message**: `fix(cli): align agents session show JSON/YAML output envelope with spec — use id, add automation field, fix all key names` - **Milestone**: v3.2.0 - **Parent Epic**: #868 ## Background and Context The `agents session show` command's JSON and YAML output format deviates from the specification. The spec defines a structured envelope with `session_summary`, `recent_messages`, `linked_plans`, and `token_usage` keys nested under `data`, but the implementation's `as_cli_dict()` method returns different field names and a structurally incorrect shape. Per `docs/specification.md` (section "agents session show"), the specification is the authoritative source of truth. When the codebase deviates from the specification, the code must be updated to match it. **Code Location**: `src/cleveragents/domain/models/core/session.py`, `as_cli_dict()` method (lines ~320–370) ## Expected Behaviour (from spec) ```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" }, { "role": "assistant", "text": "Plan created, running commands..." } ], "linked_plans": [ { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "phase": "execute", "state": "complete" } ], "token_usage": { "input_tokens": 3420, "output_tokens": 1185, "estimated_cost": "$0.0184" } } } ``` ## Actual Behaviour The `as_cli_dict()` method 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 in session_summary # recent_messages uses "content" key instead of "text" # linked_plans is a flat list of ULID strings, not objects with plan_id/phase/state ``` ## Deviations from Spec | # | Field / Structure | Actual | Expected | |---|---|---|---| | 1 | Session ID key | `session_id` | `id` | | 2 | Actor key | `actor_name` | `actor` | | 3 | Message count key | `message_count` | `messages` | | 4 | Created timestamp key | `created_at` | `created` | | 5 | Updated timestamp key | `updated_at` | `updated` | | 6 | Automation field | Missing | `"automation": "<profile-name>"` | | 7 | Message text key | `content` | `text` | | 8 | `linked_plans` shape | Flat list of ULID strings | List of `{ plan_id, phase, state }` objects | **Severity**: Medium — the JSON/YAML output format is a spec contract consumed by scripts and integrations. ## Subtasks - [ ] Audit `as_cli_dict()` in `src/cleveragents/domain/models/core/session.py` against the spec's `agents session show` JSON schema - [ ] Rename `session_id` → `id` in the `session_summary` sub-dict - [ ] Rename `actor_name` → `actor` in the `session_summary` sub-dict - [ ] Remove the non-spec `namespace` field from `session_summary` - [ ] Rename `message_count` → `messages` in the `session_summary` sub-dict - [ ] Rename `created_at` → `created` in the `session_summary` sub-dict - [ ] Rename `updated_at` → `updated` in the `session_summary` sub-dict - [ ] Add the missing `automation` field to `session_summary` - [ ] Fix `recent_messages` entries to use `text` key instead of `content` - [ ] Fix `linked_plans` to return a list of `{ plan_id, phase, state }` objects instead of flat ULID strings - [ ] Write/update Behave BDD scenarios in `features/` covering all corrected field names and structures - [ ] Ensure all nox quality gates pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report`) - [ ] Open a PR, link it to this issue, and obtain two approving reviews ## Definition of Done - [ ] `as_cli_dict()` output exactly matches the spec's `agents session show` JSON envelope for all fields: `id`, `actor`, `messages`, `created`, `updated`, `automation` in `session_summary` - [ ] `recent_messages` entries use `text` key (not `content`) - [ ] `linked_plans` entries are objects with `plan_id`, `phase`, and `state` keys - [ ] The non-spec `namespace` field is removed from `session_summary` - [ ] Behave BDD scenarios cover all eight deviations listed above - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR merged and this issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.2.0 milestone

2026-04-05 03:25:14 +00:00

freemo added a new dependency

2026-04-05 03:26:37 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo commented

2026-04-05 03:43:12 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo modified the milestone from v3.2.0 to v3.3.0

2026-04-06 20:38:10 +00:00

freemo removed this from the v3.3.0 milestone

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

freemo added this to the v3.2.0 milestone

2026-04-06 20:38:33 +00:00

freemo removed this from the v3.2.0 milestone

2026-04-06 20:50:36 +00:00