JSON/YAML envelope `command` field always empty string — callers don't pass command name to `format_output()` #4099

New issue

Open

opened 2026-04-06 10:20:59 +00:00 by hurui200320 · 0 comments

hurui200320 commented

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

Member

Metadata

Branch: fix/cli-envelope-command-field-empty
Commit Message: fix(cli): pass command name to format_output() in all system command handlers
Milestone: None (backlog)
Parent Epic: TBD - requires manual linking

Description

Background

Issue #3431 (closed, State/Completed) added the spec-required JSON/YAML output envelope to format_output() in src/cleveragents/cli/formatting.py. As part of that work, a command parameter was added to format_output() / build_envelope() so callers could supply the command name for the envelope's command field. However, the callers in src/cleveragents/cli/commands/system.py (and potentially other command handlers) were never updated to pass the actual command name — they rely on the default empty string, causing "command": "" in all structured output.

Current Behavior

Every CLI command that uses --format json or --format yaml emits an envelope with an empty command field:

$ agents --format json version
{"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...}

$ agents --format json info
{"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...}

$ agents --format json diagnostics
{"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...}

Expected Behavior

Per the spec, the command field must contain the name of the command that was run:

$ agents --format json version
{"command": "version", "status": "ok", "exit_code": 0, "data": {...}, ...}

$ agents --format json info
{"command": "info", "status": "ok", "exit_code": 0, "data": {...}, ...}

$ agents --format json diagnostics
{"command": "diagnostics", "status": "ok", "exit_code": 0, "data": {...}, ...}

Acceptance Criteria

agents --format json version outputs "command": "version" in the envelope
agents --format json info outputs "command": "info" in the envelope
agents --format json diagnostics outputs "command": "diagnostics" in the envelope
agents --format yaml <cmd> likewise populates the command field correctly for all affected commands
No other envelope fields are regressed by this change

Subtasks

Audit all callers of format_output() in src/cleveragents/cli/commands/system.py and identify every call site missing the command argument
Audit any other command handler files that call format_output() without passing command
Update each call site to pass the correct command name string
Tests (Behave): add/update BDD scenarios verifying the command field is populated correctly for version, info, and diagnostics in JSON and YAML output
Tests (Robot): add/update integration test asserting "command" field is non-empty for structured output
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off
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%

## Metadata - **Branch**: `fix/cli-envelope-command-field-empty` - **Commit Message**: `fix(cli): pass command name to format_output() in all system command handlers` - **Milestone**: None (backlog) - **Parent Epic**: TBD - requires manual linking ## Description ### Background Issue #3431 (closed, `State/Completed`) added the spec-required JSON/YAML output envelope to `format_output()` in `src/cleveragents/cli/formatting.py`. As part of that work, a `command` parameter was added to `format_output()` / `build_envelope()` so callers could supply the command name for the envelope's `command` field. However, the callers in `src/cleveragents/cli/commands/system.py` (and potentially other command handlers) were never updated to pass the actual command name — they rely on the default empty string, causing `"command": ""` in all structured output. ### Current Behavior Every CLI command that uses `--format json` or `--format yaml` emits an envelope with an empty `command` field: ``` $ agents --format json version {"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...} $ agents --format json info {"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...} $ agents --format json diagnostics {"command": "", "status": "ok", "exit_code": 0, "data": {...}, ...} ``` ### Expected Behavior Per the spec, the `command` field must contain the name of the command that was run: ``` $ agents --format json version {"command": "version", "status": "ok", "exit_code": 0, "data": {...}, ...} $ agents --format json info {"command": "info", "status": "ok", "exit_code": 0, "data": {...}, ...} $ agents --format json diagnostics {"command": "diagnostics", "status": "ok", "exit_code": 0, "data": {...}, ...} ``` ### Acceptance Criteria - `agents --format json version` outputs `"command": "version"` in the envelope - `agents --format json info` outputs `"command": "info"` in the envelope - `agents --format json diagnostics` outputs `"command": "diagnostics"` in the envelope - `agents --format yaml <cmd>` likewise populates the `command` field correctly for all affected commands - No other envelope fields are regressed by this change ## Subtasks - [ ] Audit all callers of `format_output()` in `src/cleveragents/cli/commands/system.py` and identify every call site missing the `command` argument - [ ] Audit any other command handler files that call `format_output()` without passing `command` - [ ] Update each call site to pass the correct command name string - [ ] Tests (Behave): add/update BDD scenarios verifying the `command` field is populated correctly for `version`, `info`, and `diagnostics` in JSON and YAML output - [ ] Tests (Robot): add/update integration test asserting `"command"` field is non-empty for structured output - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off - 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%