cleveragents/cleveragents-core

Fork 3

`cli/session`: `session tell` missing `--format` flag and JSON envelope output #10466

New issue

Open

opened 2026-04-18 09:55:07 +00:00 by HAL9000 · 4 comments

HAL9000 commented

2026-04-18 09:55:07 +00:00

Owner

Metadata

Commit: fix(cli/session): add --format flag and JSON envelope output to session tell
Branch: fix/cli-session-tell-format-flag

Background and Context

agents session tell is missing the --format flag entirely. The spec (docs/specification.md §agents session tell) explicitly requires JSON envelope output for this command, but the current implementation has no --format parameter and only outputs Rich console text. This is inconsistent with other session commands (create, list, show) which all support --format, and breaks automation scripts that need machine-readable output.

Expected Behavior

agents session tell --session <id> --format json "Hello" should output a spec-compliant JSON envelope:

{
  "command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "session": {
      "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
      "actor": "local/orchestrator",
      "mode": "streaming"
    },
    "response": "The last plan (01HXM8C2ZK) modified 6 files...",
    "files_changed": ["src/auth/session.py", "..."],
    "usage": {
      "tokens": 1240,
      "duration_s": 3.1,
      "tool_calls": 2
    }
  },
  "timing": { "duration_ms": 3100 },
  "messages": [{ "level": "ok", "text": "Stream complete" }]
}

Acceptance Criteria

agents session tell --format json "Hello" outputs a spec-compliant JSON envelope
agents session tell --help shows a --format flag
agents session tell without --format continues to output Rich console text (no regression)
All tests in tests/cli/test_session_tell_json.py pass (see #10465)
nox passes with coverage >= 97%

Subtasks

Add fmt parameter with --format/-f option to the tell function in src/cleveragents/cli/commands/session.py
Add format_output() call when fmt is not rich or color
Construct the data dict with session, response, and usage fields
Add tests to confirm JSON envelope output matches spec
Confirm no regression in Rich console output mode

Definition of Done

This issue should be closed when:

The --format flag is added to agents session tell
JSON envelope output matches the spec
All tests in tests/cli/test_session_tell_json.py pass
nox passes with coverage >= 97%
PR is merged to main

Summary

agents session tell is missing the --format flag entirely. The spec (docs/specification.md §agents session tell) explicitly requires JSON envelope output for this command, but the current implementation has no --format parameter and only outputs Rich console text.

Code Evidence

File: src/cleveragents/cli/commands/session.py

The tell command function (lines ~487-529) has NO --format parameter:

@app.command()
def tell(
    prompt: Annotated[str, typer.Argument(help="Message to send to the session")],
    session_id: Annotated[str, typer.Option("--session", help="Session ULID to send message to")],
    actor: Annotated[str | None, typer.Option("--actor", help="Override actor for this message")] = None,
    stream: Annotated[bool, typer.Option("--stream", help="Stream response in real-time")] = False,
    # NO --format parameter!
) -> None:

The output is only Rich console text (lines ~519-521):

console.print(f"[dim]user:[/dim] {escape(prompt)}")
console.print(f"[cyan]assistant:[/cyan] {escape(assistant_content)}")

Specification Reference

From docs/specification.md, the agents session tell command explicitly requires JSON envelope output:

{
  "command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "session": {
      "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
      "actor": "local/orchestrator",
      "mode": "streaming"
    },
    "response": "The last plan (01HXM8C2ZK) modified 6 files...",
    "files_changed": ["src/auth/session.py", "..."],
    "usage": {
      "tokens": 1240,
      "duration_s": 3.1,
      "tool_calls": 2
    }
  },
  "timing": { "duration_ms": 3100 },
  "messages": [{ "level": "ok", "text": "Stream complete" }]
}

Actual Behavior

Running agents session tell --session <id> --format json "Hello" fails with:

Error: No such option: --format

Reproduction Steps

Create a session: agents session create
Note the session ID
Run: agents session tell --session <session_id> --format json "Hello"
Observe: Error "No such option: --format"

Impact

Automation scripts that need machine-readable output from session tell are completely broken
Inconsistent with other session commands (create, list, show) which all support --format
Violates the spec which explicitly documents JSON envelope for this command

Fix Path

In src/cleveragents/cli/commands/session.py, add --format parameter to the tell function and add format_output() call:

@app.command()
def tell(
    prompt: Annotated[str, typer.Argument(...)],
    session_id: Annotated[str, typer.Option("--session", ...)],
    actor: Annotated[str | None, typer.Option("--actor", ...)] = None,
    stream: Annotated[bool, typer.Option("--stream", ...)] = False,
    fmt: Annotated[str, typer.Option("--format", "-f", help=_FORMAT_HELP)] = "rich",  # ADD THIS
) -> None:
    ...
    if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value):
        data = {
            "session": {"id": session_id, "actor": actor, "mode": "streaming" if stream else "standard"},
            "response": assistant_content,
            "usage": {"tokens": 0, "duration_s": 0.0, "tool_calls": 0},
        }
        typer.echo(format_output(data, fmt))
        return
    # ... existing Rich output ...

Blocked By

Depends on TDD issue: #10465

Automated by CleverAgents Bot
Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

## Metadata - **Commit:** `fix(cli/session): add --format flag and JSON envelope output to session tell` - **Branch:** `fix/cli-session-tell-format-flag` ## Background and Context `agents session tell` is missing the `--format` flag entirely. The spec (`docs/specification.md §agents session tell`) explicitly requires JSON envelope output for this command, but the current implementation has no `--format` parameter and only outputs Rich console text. This is inconsistent with other session commands (`create`, `list`, `show`) which all support `--format`, and breaks automation scripts that need machine-readable output. ## Expected Behavior `agents session tell --session <id> --format json "Hello"` should output a spec-compliant JSON envelope: ```json { "command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"", "status": "ok", "exit_code": 0, "data": { "session": { "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", "actor": "local/orchestrator", "mode": "streaming" }, "response": "The last plan (01HXM8C2ZK) modified 6 files...", "files_changed": ["src/auth/session.py", "..."], "usage": { "tokens": 1240, "duration_s": 3.1, "tool_calls": 2 } }, "timing": { "duration_ms": 3100 }, "messages": [{ "level": "ok", "text": "Stream complete" }] } ``` ## Acceptance Criteria - [ ] `agents session tell --format json "Hello"` outputs a spec-compliant JSON envelope - [ ] `agents session tell --help` shows a `--format` flag - [ ] `agents session tell` without `--format` continues to output Rich console text (no regression) - [ ] All tests in `tests/cli/test_session_tell_json.py` pass (see #10465) - [ ] `nox` passes with coverage >= 97% ## Subtasks - [ ] Add `fmt` parameter with `--format`/`-f` option to the `tell` function in `src/cleveragents/cli/commands/session.py` - [ ] Add `format_output()` call when `fmt` is not `rich` or `color` - [ ] Construct the data dict with `session`, `response`, and `usage` fields - [ ] Add tests to confirm JSON envelope output matches spec - [ ] Confirm no regression in Rich console output mode ## Definition of Done This issue should be closed when: 1. The `--format` flag is added to `agents session tell` 2. JSON envelope output matches the spec 3. All tests in `tests/cli/test_session_tell_json.py` pass 4. `nox` passes with coverage >= 97% 5. PR is merged to main --- ## Summary `agents session tell` is missing the `--format` flag entirely. The spec (docs/specification.md §agents session tell) explicitly requires JSON envelope output for this command, but the current implementation has no `--format` parameter and only outputs Rich console text. ## Code Evidence **File:** `src/cleveragents/cli/commands/session.py` The `tell` command function (lines ~487-529) has NO `--format` parameter: ```python @app.command() def tell( prompt: Annotated[str, typer.Argument(help="Message to send to the session")], session_id: Annotated[str, typer.Option("--session", help="Session ULID to send message to")], actor: Annotated[str | None, typer.Option("--actor", help="Override actor for this message")] = None, stream: Annotated[bool, typer.Option("--stream", help="Stream response in real-time")] = False, # NO --format parameter! ) -> None: ``` The output is only Rich console text (lines ~519-521): ```python console.print(f"[dim]user:[/dim] {escape(prompt)}") console.print(f"[cyan]assistant:[/cyan] {escape(assistant_content)}") ``` ## Specification Reference From docs/specification.md, the `agents session tell` command explicitly requires JSON envelope output: ```json { "command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"", "status": "ok", "exit_code": 0, "data": { "session": { "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", "actor": "local/orchestrator", "mode": "streaming" }, "response": "The last plan (01HXM8C2ZK) modified 6 files...", "files_changed": ["src/auth/session.py", "..."], "usage": { "tokens": 1240, "duration_s": 3.1, "tool_calls": 2 } }, "timing": { "duration_ms": 3100 }, "messages": [{ "level": "ok", "text": "Stream complete" }] } ``` ## Actual Behavior Running `agents session tell --session <id> --format json "Hello"` fails with: ``` Error: No such option: --format ``` ## Reproduction Steps 1. Create a session: `agents session create` 2. Note the session ID 3. Run: `agents session tell --session <session_id> --format json "Hello"` 4. Observe: Error "No such option: --format" ## Impact - Automation scripts that need machine-readable output from session tell are completely broken - Inconsistent with other session commands (create, list, show) which all support `--format` - Violates the spec which explicitly documents JSON envelope for this command ## Fix Path In `src/cleveragents/cli/commands/session.py`, add `--format` parameter to the `tell` function and add `format_output()` call: ```python @app.command() def tell( prompt: Annotated[str, typer.Argument(...)], session_id: Annotated[str, typer.Option("--session", ...)], actor: Annotated[str | None, typer.Option("--actor", ...)] = None, stream: Annotated[bool, typer.Option("--stream", ...)] = False, fmt: Annotated[str, typer.Option("--format", "-f", help=_FORMAT_HELP)] = "rich", # ADD THIS ) -> None: ... if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value): data = { "session": {"id": session_id, "actor": actor, "mode": "streaming" if stream else "standard"}, "response": assistant_content, "usage": {"tokens": 0, "duration_s": 0.0, "tool_calls": 0}, } typer.echo(format_output(data, fmt)) return # ... existing Rich output ... ``` ## Blocked By Depends on TDD issue: #10465 --- **Automated by CleverAgents Bot** Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

HAL9000 added the

labels

2026-04-18 09:57:34 +00:00

HAL9000 commented

2026-04-18 10:00:10 +00:00

Author

Owner

[GROOMED] Quality Analysis - Priority/Critical Bug

Triage Assessment: ✅ VALID & ACTIONABLE

This is a legitimate, high-impact bug that requires immediate attention:

Issue Summary:

agents session tell command is missing the --format flag entirely
Spec (docs/specification.md §agents session tell) explicitly requires JSON envelope output
Current implementation only outputs Rich console text
Breaks automation scripts that need machine-readable output
Inconsistent with other session commands (create, list, show) which all support --format

Evidence Quality: ⭐⭐⭐⭐⭐

Clear reproduction steps provided
Exact file location and line numbers cited (src/cleveragents/cli/commands/session.py, lines ~487-529)
Code evidence showing missing --format parameter
Specification reference with expected JSON envelope format
Acceptance criteria clearly defined with 4 checkpoints
Definition of Done provided
Subtasks enumerated

Dependency Check:

Depends on TDD issue #10465 (test file creation)
No circular dependencies detected

Label Verification

Current Labels: ✅ All required labels present

✓ State/Unverified (exclusive)
✓ Type/Bug (exclusive)
✓ Priority/Critical (exclusive)

Triage Action: Moving from State/Unverified → State/Verified (valid, actionable bug)

Milestone Assignment

Assigned to: v3.2.0 (M3: Decisions + Validations + Invariants)

Rationale: CLI feature/bug fix affecting core session command functionality
Priority/Critical status requires assignment to active milestone
Fits within v3.2.0 scope as a critical CLI enhancement

Impact Assessment

Severity: 🔴 CRITICAL

Automation scripts completely broken (no machine-readable output)
Violates published specification
Inconsistent with other session commands
Blocks downstream automation workflows

Scope: Contained

Single command function (tell in session.py)
Clear fix path provided in issue description
No architectural changes required
Estimated effort: Low-to-Medium

Acceptance Criteria Review

All criteria are clear and testable:

JSON envelope output matches spec
--help shows --format flag
No regression in Rich console output
Tests in tests/cli/test_session_tell_json.py pass
nox passes with coverage >= 97%

Recommendation

✅ APPROVED FOR IMPLEMENTATION

This issue is ready for assignment to an implementor. The bug is well-documented, has clear acceptance criteria, and includes a suggested fix path. The Priority/Critical status is justified given the impact on automation workflows.

Next Steps:

Assign to an available implementor
Ensure #10465 (TDD) is completed first
Implement --format flag with JSON envelope output
Run full test suite before merge

Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor

## [GROOMED] Quality Analysis - Priority/Critical Bug ### Triage Assessment: ✅ VALID & ACTIONABLE This is a **legitimate, high-impact bug** that requires immediate attention: **Issue Summary:** - `agents session tell` command is missing the `--format` flag entirely - Spec (docs/specification.md §agents session tell) explicitly requires JSON envelope output - Current implementation only outputs Rich console text - Breaks automation scripts that need machine-readable output - Inconsistent with other session commands (create, list, show) which all support `--format` **Evidence Quality:** ⭐⭐⭐⭐⭐ - Clear reproduction steps provided - Exact file location and line numbers cited (src/cleveragents/cli/commands/session.py, lines ~487-529) - Code evidence showing missing `--format` parameter - Specification reference with expected JSON envelope format - Acceptance criteria clearly defined with 4 checkpoints - Definition of Done provided - Subtasks enumerated **Dependency Check:** - Depends on TDD issue #10465 (test file creation) - No circular dependencies detected ### Label Verification **Current Labels:** ✅ All required labels present - ✓ State/Unverified (exclusive) - ✓ Type/Bug (exclusive) - ✓ Priority/Critical (exclusive) **Triage Action:** Moving from State/Unverified → State/Verified (valid, actionable bug) ### Milestone Assignment **Assigned to:** v3.2.0 (M3: Decisions + Validations + Invariants) - Rationale: CLI feature/bug fix affecting core session command functionality - Priority/Critical status requires assignment to active milestone - Fits within v3.2.0 scope as a critical CLI enhancement ### Impact Assessment **Severity:** 🔴 CRITICAL - Automation scripts completely broken (no machine-readable output) - Violates published specification - Inconsistent with other session commands - Blocks downstream automation workflows **Scope:** Contained - Single command function (`tell` in session.py) - Clear fix path provided in issue description - No architectural changes required - Estimated effort: Low-to-Medium ### Acceptance Criteria Review All criteria are clear and testable: - [ ] JSON envelope output matches spec - [ ] `--help` shows `--format` flag - [ ] No regression in Rich console output - [ ] Tests in `tests/cli/test_session_tell_json.py` pass - [ ] `nox` passes with coverage >= 97% ### Recommendation ✅ **APPROVED FOR IMPLEMENTATION** This issue is ready for assignment to an implementor. The bug is well-documented, has clear acceptance criteria, and includes a suggested fix path. The Priority/Critical status is justified given the impact on automation workflows. **Next Steps:** 1. Assign to an available implementor 2. Ensure #10465 (TDD) is completed first 3. Implement `--format` flag with JSON envelope output 4. Run full test suite before merge --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor

HAL9000 added this to the v3.2.0 milestone

2026-04-18 10:00:19 +00:00

HAL9000 commented

2026-04-18 10:01:12 +00:00

Author

Owner

Update: Milestone Assignment Complete ✅

Milestone: v3.2.0 (M3: Decisions + Validations + Invariants) has been assigned.

Label Status: ⚠️ State/Unverified → State/Verified transition requires manual intervention

The State/Verified label could not be applied via API (label may not exist or requires special permissions)
Current labels: Priority/Critical, State/Unverified, Type/Bug
Action Required: A maintainer with label management permissions should manually change State/Unverified to State/Verified once this issue is approved for implementation

Issue Status: Ready for implementor assignment once label transition is complete.

Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor

### Update: Milestone Assignment Complete ✅ **Milestone:** v3.2.0 (M3: Decisions + Validations + Invariants) has been assigned. **Label Status:** ⚠️ State/Unverified → State/Verified transition requires manual intervention - The State/Verified label could not be applied via API (label may not exist or requires special permissions) - Current labels: Priority/Critical, State/Unverified, Type/Bug - **Action Required:** A maintainer with label management permissions should manually change State/Unverified to State/Verified once this issue is approved for implementation **Issue Status:** Ready for implementor assignment once label transition is complete. --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor

HAL9000 added

and removed

labels

2026-04-18 10:04:22 +00:00

HAL9000 referenced this issue from a commit

2026-04-28 05:56:52 +00:00

fix(cli/session): add --format flag and JSON envelope output to session tell

HAL9000 referenced this issue from a pull request that will close it,

2026-04-28 05:59:55 +00:00

fix(cli/session): add --format flag and JSON envelope output to session tell #10880

HAL9000 commented

2026-04-28 06:01:38 +00:00

Author

Owner

Implementation Attempt — Tier 3: sonnet — Success

Added --format/-f flag to the session tell command in src/cleveragents/cli/commands/session.py.

Changes made:

Added fmt parameter with --format/-f option (default: "rich") to the tell function
When fmt is not rich or color, constructs a spec-compliant data dict with session, response, and usage fields and calls format_output(data, fmt) to emit the JSON envelope
Default Rich console output path is preserved with no regression
Added BDD feature file features/tdd_session_tell_format_flag.feature with 6 scenarios tagged @tdd_issue @tdd_issue_10466
Added step definitions features/steps/tdd_session_tell_format_flag_steps.py

Quality gate status: lint ✓, typecheck ✓, unit_tests ✓ (1132 scenarios passed), integration_tests running

PR: #10880

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor

**Implementation Attempt** — Tier 3: sonnet — Success Added `--format`/`-f` flag to the `session tell` command in `src/cleveragents/cli/commands/session.py`. **Changes made:** - Added `fmt` parameter with `--format`/`-f` option (default: `"rich"`) to the `tell` function - When `fmt` is not `rich` or `color`, constructs a spec-compliant data dict with `session`, `response`, and `usage` fields and calls `format_output(data, fmt)` to emit the JSON envelope - Default Rich console output path is preserved with no regression - Added BDD feature file `features/tdd_session_tell_format_flag.feature` with 6 scenarios tagged `@tdd_issue @tdd_issue_10466` - Added step definitions `features/steps/tdd_session_tell_format_flag_steps.py` **Quality gate status:** lint ✓, typecheck ✓, unit_tests ✓ (1132 scenarios passed), integration_tests running **PR:** https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/10880 --- Automated by CleverAgents Bot Supervisor: Implementation | Agent: task-implementor

freemo referenced this issue from a commit

2026-05-12 07:31:26 +00:00

fix(cli/session): add --format flag and JSON envelope output to session tell

freemo referenced this issue from a pull request that will close it,

2026-05-12 07:38:24 +00:00

cli/session: add BDD tests for --format flag and JSON envelope output to session tell #11148

freemo commented

2026-05-12 07:48:34 +00:00

Owner

Implementation Attempt — Level -1: qwen-small — Success

Implemented BDD/Behave test coverage for the --format/-f flag on agents session tell. The implementation of the --format flag already exists in the codebase (commit 87a7ce35d); this PR adds:

6 new Behave scenarios (json, yaml, plain, table, -f short flag, Rich console regression)
6 corresponding step definitions with spec-compliant verification
CHANGELOG.md entry under [Unreleased] with issue reference #10466
CONTRIBUTORS.md credit entry for Jeffrey Phillips Freeman

Quality gates: lint ✓, typecheck ✓ (3 pre-existing optional-import warnings only)

PR created: #11148
Closes #10466

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor

**Implementation Attempt** — Level -1: qwen-small — Success Implemented BDD/Behave test coverage for the --format/-f flag on agents session tell. The implementation of the --format flag already exists in the codebase (commit 87a7ce35d); this PR adds: - 6 new Behave scenarios (json, yaml, plain, table, -f short flag, Rich console regression) - 6 corresponding step definitions with spec-compliant verification - CHANGELOG.md entry under [Unreleased] with issue reference #10466 - CONTRIBUTORS.md credit entry for Jeffrey Phillips Freeman Quality gates: lint ✓, typecheck ✓ (3 pre-existing optional-import warnings only) PR created: https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/11148 Closes #10466 --- Automated by CleverAgents Bot Supervisor: Implementation | Agent: task-implementor