cleveragents/cleveragents-core

Fork 3

UAT: Session CLI commands produce non-spec-compliant JSON/YAML output — missing envelope structure #3402

New issue

Open

opened 2026-04-05 16:29:43 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 16:29:43 +00:00

Owner

Metadata

Branch: bugfix/session-cli-json-envelope-compliance
Commit Message: fix(cli): add spec-required JSON/YAML envelope to all agents session subcommands
Milestone: None (Backlog — see note below)
Parent Epic: #933

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

Background and Context

All agents session subcommands (create, list, show, delete) produce JSON/YAML output that is missing the required top-level envelope structure defined in docs/specification.md §"agents session" (lines 1456–2390).

The format_output() function in src/cleveragents/cli/formatting.py receives a flat dict and serializes it directly without wrapping in the required envelope. Additionally, field names in src/cleveragents/domain/models/core/session.py's as_cli_dict() method differ from the spec-required names.

This is a critical compliance failure: machine-readable output is the primary integration interface for automation and tooling. Non-compliant JSON breaks any downstream consumer.

Expected Behavior (from spec §"agents session")

All session commands must produce JSON output with the following top-level envelope:

{
  "command": "<the command that was run>",
  "status": "ok",
  "exit_code": 0,
  "data": { ... },
  "timing": { "duration_ms": 120 },
  "messages": [{ "level": "ok", "text": "Session created" }]
}

For session create, data must contain:

{
  "session": { "id": "...", "actor": "...", "created": "...", "namespace": "..." },
  "settings": { "automation": "review", "streaming": "off", "context": "default", "memory": "enabled", "max_history": 50 },
  "actor_details": { "provider": "...", "model": "...", "temperature": 0.7, "context_window": "200K tokens" }
}

For session list, data must contain:

{
  "sessions": [{ "id": "...", "name": "...", "actor": "...", "messages": 6, "updated": "..." }],
  "summary": { "total": 2, "most_recent": "...", "oldest": "...", "total_messages": 20, "storage": "42 KB" }
}

For session show, data must contain:

{
  "session_summary": { "id": "...", "actor": "...", "messages": 6, "created": "...", "updated": "...", "automation": "review" },
  "recent_messages": [{ "role": "user", "text": "..." }],
  "linked_plans": [{ "plan_id": "...", "phase": "execute", "state": "complete" }],
  "token_usage": { "input_tokens": 3420, "output_tokens": 1185, "estimated_cost": "$0.0184" }
}

For session delete, data must contain:

{
  "deletion_summary": { "session": "...", "id": "...", "messages_removed": 6, "storage_freed": "18 KB", "plans_orphaned": 0 },
  "cleanup": { "backups": "none", "logs": "preserved", "context": "cleared", "checkpoints": "none" }
}

Actual Behavior (from code)

session create outputs a flat dict with session_id, actor, namespace, messages, created, updated — no command, status, exit_code, data, timing, or messages envelope.
session list outputs {"sessions": [...], "summary": {...}} — missing the outer envelope.
session show outputs the result of session.as_cli_dict() directly — missing the outer envelope.
session delete for non-rich formats outputs only a console message, not structured JSON/YAML at all.

Additional Field Name Violations

Current field name	Spec-required field name
`session_id`	`id`
`actor_name`	`actor`
`message_count`	`messages`
`created_at`	`created`
`updated_at`	`updated`
`recent_messages[].content`	`recent_messages[].text`
`linked_plan_ids` (flat list of strings)	`linked_plans` (list of objects with `plan_id`, `phase`, `state`)
(missing)	`automation` field in `session_summary`

Code Locations

src/cleveragents/cli/commands/session.py: create() line 210, list_sessions() line 304, show() line 373, delete() lines 524–526
src/cleveragents/cli/formatting.py: format_output() — does not add envelope
src/cleveragents/domain/models/core/session.py: as_cli_dict() — field names differ from spec

Steps to Reproduce

Run agents session create --format json
Observe output lacks command, status, exit_code, data, timing, messages envelope
Run agents session list --format json
Same issue
Run agents session show <ID> --format json
Same issue, plus field name mismatches
Run agents session delete <ID> --format json
Observe no structured output at all

Subtasks

Add spec-required top-level envelope (command, status, exit_code, data, timing, messages) to format_output() in src/cleveragents/cli/formatting.py, or wrap at the call site in each session command
Fix session create output: wrap result in envelope with correct data structure (session, settings, actor_details keys)
Fix session list output: wrap result in envelope; verify data.sessions and data.summary keys are correct
Fix session show output: wrap result in envelope; fix field names in as_cli_dict() (session_id→id, actor_name→actor, message_count→messages, created_at→created, updated_at→updated)
Fix session show output: rename recent_messages[].content → recent_messages[].text
Fix session show output: convert linked_plan_ids (flat list) → linked_plans (list of objects with plan_id, phase, state)
Fix session show output: add missing automation field to session_summary
Fix session delete output: produce structured JSON/YAML with envelope and deletion_summary + cleanup data keys (currently outputs only a console message for non-rich formats)
Tests (Behave): Add/update scenarios asserting envelope presence for all four commands in JSON and YAML formats
Tests (Behave): Add/update scenarios asserting correct field names in session show JSON output
Tests (Behave): Add scenario asserting session delete produces structured JSON output
Tests (Robot): Add integration tests verifying JSON envelope compliance end-to-end
Verify coverage ≥97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

All four agents session subcommands (create, list, show, delete) produce JSON/YAML output with the spec-required top-level envelope (command, status, exit_code, data, timing, messages)
session show JSON output uses spec-required field names: id, actor, messages, created, updated, text, linked_plans (as objects), automation
session delete produces structured JSON/YAML output (not just a console message) for --format json and --format yaml
All Behave scenarios for envelope and field name compliance pass
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-cli-json-envelope-compliance` - **Commit Message**: `fix(cli): add spec-required JSON/YAML envelope to all agents session subcommands` - **Milestone**: None (Backlog — see note below) - **Parent Epic**: #933 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context All `agents session` subcommands (`create`, `list`, `show`, `delete`) produce JSON/YAML output that is missing the required top-level envelope structure defined in `docs/specification.md` §"agents session" (lines 1456–2390). The `format_output()` function in `src/cleveragents/cli/formatting.py` receives a flat dict and serializes it directly without wrapping in the required envelope. Additionally, field names in `src/cleveragents/domain/models/core/session.py`'s `as_cli_dict()` method differ from the spec-required names. This is a critical compliance failure: machine-readable output is the primary integration interface for automation and tooling. Non-compliant JSON breaks any downstream consumer. ## Expected Behavior (from spec §"agents session") All session commands must produce JSON output with the following top-level envelope: ```json { "command": "<the command that was run>", "status": "ok", "exit_code": 0, "data": { ... }, "timing": { "duration_ms": 120 }, "messages": [{ "level": "ok", "text": "Session created" }] } ``` For `session create`, `data` must contain: ```json { "session": { "id": "...", "actor": "...", "created": "...", "namespace": "..." }, "settings": { "automation": "review", "streaming": "off", "context": "default", "memory": "enabled", "max_history": 50 }, "actor_details": { "provider": "...", "model": "...", "temperature": 0.7, "context_window": "200K tokens" } } ``` For `session list`, `data` must contain: ```json { "sessions": [{ "id": "...", "name": "...", "actor": "...", "messages": 6, "updated": "..." }], "summary": { "total": 2, "most_recent": "...", "oldest": "...", "total_messages": 20, "storage": "42 KB" } } ``` For `session show`, `data` must contain: ```json { "session_summary": { "id": "...", "actor": "...", "messages": 6, "created": "...", "updated": "...", "automation": "review" }, "recent_messages": [{ "role": "user", "text": "..." }], "linked_plans": [{ "plan_id": "...", "phase": "execute", "state": "complete" }], "token_usage": { "input_tokens": 3420, "output_tokens": 1185, "estimated_cost": "$0.0184" } } ``` For `session delete`, `data` must contain: ```json { "deletion_summary": { "session": "...", "id": "...", "messages_removed": 6, "storage_freed": "18 KB", "plans_orphaned": 0 }, "cleanup": { "backups": "none", "logs": "preserved", "context": "cleared", "checkpoints": "none" } } ``` ## Actual Behavior (from code) - `session create` outputs a flat dict with `session_id`, `actor`, `namespace`, `messages`, `created`, `updated` — no `command`, `status`, `exit_code`, `data`, `timing`, or `messages` envelope. - `session list` outputs `{"sessions": [...], "summary": {...}}` — missing the outer envelope. - `session show` outputs the result of `session.as_cli_dict()` directly — missing the outer envelope. - `session delete` for non-rich formats outputs only a console message, not structured JSON/YAML at all. ## Additional Field Name Violations | Current field name | Spec-required field name | |---|---| | `session_id` | `id` | | `actor_name` | `actor` | | `message_count` | `messages` | | `created_at` | `created` | | `updated_at` | `updated` | | `recent_messages[].content` | `recent_messages[].text` | | `linked_plan_ids` (flat list of strings) | `linked_plans` (list of objects with `plan_id`, `phase`, `state`) | | *(missing)* | `automation` field in `session_summary` | ## Code Locations - `src/cleveragents/cli/commands/session.py`: `create()` line 210, `list_sessions()` line 304, `show()` line 373, `delete()` lines 524–526 - `src/cleveragents/cli/formatting.py`: `format_output()` — does not add envelope - `src/cleveragents/domain/models/core/session.py`: `as_cli_dict()` — field names differ from spec ## Steps to Reproduce 1. Run `agents session create --format json` 2. Observe output lacks `command`, `status`, `exit_code`, `data`, `timing`, `messages` envelope 3. Run `agents session list --format json` 4. Same issue 5. Run `agents session show <ID> --format json` 6. Same issue, plus field name mismatches 7. Run `agents session delete <ID> --format json` 8. Observe no structured output at all ## Subtasks - [ ] Add spec-required top-level envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) to `format_output()` in `src/cleveragents/cli/formatting.py`, or wrap at the call site in each session command - [ ] Fix `session create` output: wrap result in envelope with correct `data` structure (`session`, `settings`, `actor_details` keys) - [ ] Fix `session list` output: wrap result in envelope; verify `data.sessions` and `data.summary` keys are correct - [ ] Fix `session show` output: wrap result in envelope; fix field names in `as_cli_dict()` (`session_id`→`id`, `actor_name`→`actor`, `message_count`→`messages`, `created_at`→`created`, `updated_at`→`updated`) - [ ] Fix `session show` output: rename `recent_messages[].content` → `recent_messages[].text` - [ ] Fix `session show` output: convert `linked_plan_ids` (flat list) → `linked_plans` (list of objects with `plan_id`, `phase`, `state`) - [ ] Fix `session show` output: add missing `automation` field to `session_summary` - [ ] Fix `session delete` output: produce structured JSON/YAML with envelope and `deletion_summary` + `cleanup` data keys (currently outputs only a console message for non-rich formats) - [ ] Tests (Behave): Add/update scenarios asserting envelope presence for all four commands in JSON and YAML formats - [ ] Tests (Behave): Add/update scenarios asserting correct field names in `session show` JSON output - [ ] Tests (Behave): Add scenario asserting `session delete` produces structured JSON output - [ ] Tests (Robot): Add integration tests verifying JSON envelope compliance end-to-end - [ ] Verify coverage ≥97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] All four `agents session` subcommands (`create`, `list`, `show`, `delete`) produce JSON/YAML output with the spec-required top-level envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] `session show` JSON output uses spec-required field names: `id`, `actor`, `messages`, `created`, `updated`, `text`, `linked_plans` (as objects), `automation` - [ ] `session delete` produces structured JSON/YAML output (not just a console message) for `--format json` and `--format yaml` - [ ] All Behave scenarios for envelope and field name compliance pass - [ ] 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:29:59 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo referenced this issue

2026-04-05 16:32:21 +00:00

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

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — Session CLI commands produce non-spec-compliant JSON/YAML output. Missing envelope structure means programmatic consumers cannot parse the output correctly.
Milestone: Assigning to v3.5.0 — Session CLI is part of the Server & Autonomy Infrastructure scope.
Story Points: 3 — M — Requires updating output serialization for session CLI commands. Estimated 4-8 hours.
MoSCoW: Should Have — The commands work but output format is non-compliant. Important for API consumers but not blocking core functionality.
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**: Critical — Session CLI commands produce non-spec-compliant JSON/YAML output. Missing envelope structure means programmatic consumers cannot parse the output correctly. - **Milestone**: Assigning to v3.5.0 — Session CLI is part of the Server & Autonomy Infrastructure scope. - **Story Points**: 3 — M — Requires updating output serialization for session CLI commands. Estimated 4-8 hours. - **MoSCoW**: Should Have — The commands work but output format is non-compliant. Important for API consumers but not blocking core functionality. - **Parent Epic**: #397 (Server & Autonomy Infrastructure) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.5.0 milestone

2026-04-05 16:35:57 +00:00

freemo added a new dependency

2026-04-05 16:36:03 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-05 16:36:59 +00:00

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

freemo referenced this issue

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

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

freemo removed this from the v3.5.0 milestone