UAT: JSON output format missing spec-required envelope structure (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) #3618

New issue

Open

opened 2026-04-05 20:40:32 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 20:40:32 +00:00

Owner

Metadata

Branch: fix/json-output-envelope-structure
Commit Message: fix(cli): wrap JSON output in spec-required envelope with command, status, exit_code, data, timing, and messages fields
Milestone: (none — backlog, see note below)
Parent Epic: #3374

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.

Background

The specification (docs/specification.md, "Global Options" section and all command examples) defines a specific JSON envelope format for all commands when --format json is used:

{
  "command": "agents actor add --config ./actors/reviewer.yaml",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "actor_added": { }
  },
  "timing": {
    "duration_ms": 12
  },
  "messages": [
    { "level": "ok", "text": "Actor added" }
  ]
}

Every command's JSON output must be wrapped in this envelope with command, status, exit_code, data, timing, and messages fields.

Bug Description

The format_output function in src/cleveragents/cli/formatting.py (lines 162–218) outputs raw data without any envelope. For example, agents actor list --format json currently outputs:

[
  {
    "name": "local/my-actor",
    "provider": "openai"
  }
]

There is no command, status, exit_code, data, timing, or messages wrapper — a direct violation of the specification.

Code location: src/cleveragents/cli/formatting.py, format_output function (lines 162–218)

Impact

Any script or tool that parses the JSON output expecting the spec-defined envelope will fail. This breaks programmatic consumption of CLI output, which is a primary use case for the JSON format option.

Subtasks

Audit all call sites of format_output in src/cleveragents/cli/ to identify every command that emits JSON
Design and implement a JsonEnvelope Pydantic model with fields: command, status, exit_code, data, timing (with duration_ms), and messages (list of {level, text})
Refactor format_output (and any related helpers) in src/cleveragents/cli/formatting.py to wrap all JSON output in the envelope
Capture the invoked command string (argv) and inject it into the command field
Implement timing capture (start time at CLI entry, duration_ms computed before output)
Ensure status and exit_code are propagated correctly from command handlers (ok/error + 0/non-zero)
Ensure messages list is populated from any info/warning/error messages emitted during the command
Update all affected Behave unit test scenarios in features/ to assert the envelope structure
Update or add Robot Framework integration tests in robot/ to validate envelope on real CLI invocations
Verify all nox stages pass with coverage ≥ 97%

Definition of Done

All commands using --format json produce output wrapped in the spec-required envelope (command, status, exit_code, data, timing, messages)
JsonEnvelope model is statically typed and passes nox -e typecheck without errors
Behave unit tests cover the envelope wrapping logic with ≥ 97% coverage
Robot Framework integration tests validate the envelope on at least 3 representative commands
No # type: ignore suppressions introduced
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/json-output-envelope-structure` - **Commit Message**: `fix(cli): wrap JSON output in spec-required envelope with command, status, exit_code, data, timing, and messages fields` - **Milestone**: (none — backlog, see note below) - **Parent Epic**: #3374 > **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. ## Background The specification (`docs/specification.md`, "Global Options" section and all command examples) defines a specific JSON envelope format for **all** commands when `--format json` is used: ```json { "command": "agents actor add --config ./actors/reviewer.yaml", "status": "ok", "exit_code": 0, "data": { "actor_added": { } }, "timing": { "duration_ms": 12 }, "messages": [ { "level": "ok", "text": "Actor added" } ] } ``` Every command's JSON output must be wrapped in this envelope with `command`, `status`, `exit_code`, `data`, `timing`, and `messages` fields. ## Bug Description The `format_output` function in `src/cleveragents/cli/formatting.py` (lines 162–218) outputs raw data without any envelope. For example, `agents actor list --format json` currently outputs: ```json [ { "name": "local/my-actor", "provider": "openai" } ] ``` There is no `command`, `status`, `exit_code`, `data`, `timing`, or `messages` wrapper — a direct violation of the specification. **Code location**: `src/cleveragents/cli/formatting.py`, `format_output` function (lines 162–218) ## Impact Any script or tool that parses the JSON output expecting the spec-defined envelope will fail. This breaks programmatic consumption of CLI output, which is a primary use case for the JSON format option. ## Subtasks - [ ] Audit all call sites of `format_output` in `src/cleveragents/cli/` to identify every command that emits JSON - [ ] Design and implement a `JsonEnvelope` Pydantic model with fields: `command`, `status`, `exit_code`, `data`, `timing` (with `duration_ms`), and `messages` (list of `{level, text}`) - [ ] Refactor `format_output` (and any related helpers) in `src/cleveragents/cli/formatting.py` to wrap all JSON output in the envelope - [ ] Capture the invoked command string (argv) and inject it into the `command` field - [ ] Implement timing capture (start time at CLI entry, `duration_ms` computed before output) - [ ] Ensure `status` and `exit_code` are propagated correctly from command handlers (ok/error + 0/non-zero) - [ ] Ensure `messages` list is populated from any info/warning/error messages emitted during the command - [ ] Update all affected Behave unit test scenarios in `features/` to assert the envelope structure - [ ] Update or add Robot Framework integration tests in `robot/` to validate envelope on real CLI invocations - [ ] Verify all nox stages pass with coverage ≥ 97% ## Definition of Done - [ ] All commands using `--format json` produce output wrapped in the spec-required envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] `JsonEnvelope` model is statically typed and passes `nox -e typecheck` without errors - [ ] Behave unit tests cover the envelope wrapping logic with ≥ 97% coverage - [ ] Robot Framework integration tests validate the envelope on at least 3 representative commands - [ ] No `# type: ignore` suppressions introduced - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 20:40:41 +00:00

#3374 Epic: E2E Workflow Specification Tests & Code Review Tool Examples

freemo added this to the v3.7.0 milestone

2026-04-05 20:42:21 +00:00

freemo referenced this issue

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

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

freemo referenced this issue

2026-04-05 20:43:01 +00:00

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

freemo referenced this issue