UAT: JSON/YAML envelope messages[0].text always generic "ok" instead of command-specific messages #4100

New issue

Open

opened 2026-04-06 10:21:01 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-04-06 10:21:01 +00:00

Member

Metadata

Branch: fix/envelope-messages-text-command-specific
Commit Message: fix(output): populate messages[0].text with command-specific strings in JSON/YAML envelope
Milestone: v3.5.0
Parent Epic: #936

Description

Background

The JSON/YAML structured output envelope produced by the CLI includes a messages field
intended to carry command-specific human-readable status text. Per the spec, each command
should emit a distinct message string (e.g. "Version reported", "Environment details ready",
"2 warnings require attention"). Instead, every command emits the generic fallback string
"ok" regardless of context.

Affected files are src/cleveragents/cli/formatting.py (likely build_envelope()) and
callers in src/cleveragents/cli/commands/system.py.

Note: This bug is distinct from #1879, which concerns the messages field being a
dict instead of a list. This issue is specifically about the text content of the
message objects being wrong once the type issue is resolved.

Current Behavior

All commands emit "text": "ok" in the envelope messages field regardless of which
command was run:

agents --format json version      # "messages": [{"level": "ok", "text": "ok"}]
agents --format json info         # "messages": [{"level": "ok", "text": "ok"}]
agents --format json diagnostics  # "messages": [{"level": "ok", "text": "ok"}]

Expected Behavior

Per the spec, each command should emit a command-specific message string:

Command	Expected `messages[0].text`
`version`	`"Version reported"`
`info`	`"Environment details ready"`
`diagnostics`	`"2 warnings require attention"` (or `"N warnings require attention"` where N is the actual count)

Acceptance Criteria

agents --format json version produces messages[0].text == "Version reported"
agents --format json info produces messages[0].text == "Environment details ready"
agents --format json diagnostics (with warnings) produces messages[0].text matching
"<N> warnings require attention" where N reflects the actual warning count
No command produces the generic "ok" string as its message text
YAML output (--format yaml) exhibits the same corrected behaviour

Subtasks

Identify where build_envelope() (or equivalent) sets the message text in
src/cleveragents/cli/formatting.py
Update version, info, and diagnostics command handlers in
src/cleveragents/cli/commands/system.py to pass command-specific message strings
Ensure the diagnostics message text interpolates the actual warning count
Tests: add/update unit tests in tests/ covering each command's message text
Tests: add/update BDD/integration scenarios verifying JSON and YAML envelope
messages[0].text for version, info, and diagnostics
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

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
The commit is pushed to the branch from Metadata
PR submitted to master, reviewed, and merged
All nox stages pass
Coverage >= 97%

## Metadata - **Branch**: `fix/envelope-messages-text-command-specific` - **Commit Message**: `fix(output): populate messages[0].text with command-specific strings in JSON/YAML envelope` - **Milestone**: v3.5.0 - **Parent Epic**: #936 ## Description ### Background The JSON/YAML structured output envelope produced by the CLI includes a `messages` field intended to carry command-specific human-readable status text. Per the spec, each command should emit a distinct message string (e.g. `"Version reported"`, `"Environment details ready"`, `"2 warnings require attention"`). Instead, every command emits the generic fallback string `"ok"` regardless of context. Affected files are `src/cleveragents/cli/formatting.py` (likely `build_envelope()`) and callers in `src/cleveragents/cli/commands/system.py`. > **Note:** This bug is distinct from #1879, which concerns the `messages` field being a > `dict` instead of a `list`. This issue is specifically about the *text content* of the > message objects being wrong once the type issue is resolved. ### Current Behavior All commands emit `"text": "ok"` in the envelope `messages` field regardless of which command was run: ```bash agents --format json version # "messages": [{"level": "ok", "text": "ok"}] agents --format json info # "messages": [{"level": "ok", "text": "ok"}] agents --format json diagnostics # "messages": [{"level": "ok", "text": "ok"}] ``` ### Expected Behavior Per the spec, each command should emit a command-specific message string: | Command | Expected `messages[0].text` | |---------------|------------------------------------------| | `version` | `"Version reported"` | | `info` | `"Environment details ready"` | | `diagnostics` | `"2 warnings require attention"` (or `"N warnings require attention"` where N is the actual count) | ### Acceptance Criteria - `agents --format json version` produces `messages[0].text == "Version reported"` - `agents --format json info` produces `messages[0].text == "Environment details ready"` - `agents --format json diagnostics` (with warnings) produces `messages[0].text` matching `"<N> warnings require attention"` where N reflects the actual warning count - No command produces the generic `"ok"` string as its message text - YAML output (`--format yaml`) exhibits the same corrected behaviour ## Subtasks - [ ] Identify where `build_envelope()` (or equivalent) sets the message text in `src/cleveragents/cli/formatting.py` - [ ] Update `version`, `info`, and `diagnostics` command handlers in `src/cleveragents/cli/commands/system.py` to pass command-specific message strings - [ ] Ensure the `diagnostics` message text interpolates the actual warning count - [ ] Tests: add/update unit tests in `tests/` covering each command's message text - [ ] Tests: add/update BDD/integration scenarios verifying JSON and YAML envelope `messages[0].text` for `version`, `info`, and `diagnostics` - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] 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 - [ ] The commit is pushed to the branch from Metadata - [ ] PR submitted to `master`, reviewed, and merged - [ ] All nox stages pass - [ ] Coverage >= 97%

hurui200320 added this to the v3.5.0 milestone

2026-04-06 10:21:06 +00:00