cleveragents/cleveragents-core

Fork 3

UAT: `agents session create` JSON/YAML output deviates from spec — uses `session_id` instead of `id`, missing `settings` and `actor_details` keys #2978

New issue

Open

opened 2026-04-05 03:02:02 +00:00 by freemo · 4 comments

freemo commented

2026-04-05 03:02:02 +00:00

Owner

Metadata

Branch: fix/session-create-json-yaml-output-spec-deviation
Commit Message: fix(cli): align agents session create JSON/YAML output envelope with spec — use id, add settings and actor_details keys
Milestone: v3.2.0
Parent Epic: #868

Background and Context

The agents session create command's JSON and YAML output format deviates from the specification. The spec defines a structured envelope with session, settings, and actor_details keys nested under data, but the implementation returns a flat dict using different field names.

Per docs/specification.md (section "agents session create"), the specification is the authoritative source of truth. When the codebase deviates from the specification, the code must be updated to match it.

Code Location: src/cleveragents/cli/commands/session.py, _session_summary_dict() function and create() command (lines ~110–130, ~190–250)

Expected Behaviour (from spec)

{
  "data": {
    "session": {
      "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
      "actor": "local/orchestrator",
      "created": "2026-02-08T12:44:00Z",
      "namespace": "local"
    },
    "settings": {
      "automation": "review",
      "streaming": "off",
      "context": "default",
      "memory": "enabled",
      "max_history": 50
    },
    "actor_details": {
      "provider": "anthropic",
      "model": "claude-3.5",
      "temperature": 0.7,
      "context_window": "200K tokens"
    }
  }
}

Actual Behaviour

The implementation returns _session_summary_dict() which produces a flat, non-conforming structure:

{
  "session_id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
  "actor": "(none)",
  "namespace": "local",
  "messages": 0,
  "created": "2026-02-08T12:44:00Z",
  "updated": "2026-02-08T12:44:00Z"
}

Deviations from Spec

Uses session_id instead of id (spec uses id nested under a session key)
Missing settings key with automation, streaming, context, memory, max_history
Missing actor_details key with provider, model, temperature, context_window
Includes messages and updated fields which are not part of the spec's create output
The session fields are not nested under a session key inside a data envelope

Severity: High — the JSON/YAML output format is a spec contract used by scripts and integrations.

Subtasks

Read docs/specification.md section "agents session create" and confirm all required JSON/YAML envelope fields
Write BDD feature scenarios (.feature file) covering the full JSON output envelope (data.session.id, data.settings.*, data.actor_details.*)
Write BDD feature scenarios covering the YAML output format (same structure, YAML-serialised)
Rename session_id → id and nest session fields under a session key inside a data envelope in _session_summary_dict()
Add settings key to the output dict, populated from the session's configuration (automation, streaming, context, memory, max_history)
Add actor_details key to the output dict, populated from the resolved actor (provider, model, temperature, context_window)
Remove messages and updated fields from the create output (they are not in the spec's create envelope)
Ensure the create() command passes the structured envelope to the JSON/YAML formatter
Run nox (all sessions) and confirm all quality gates pass
Confirm coverage remains ≥ 97%

Definition of Done

agents session create --output json produces the exact envelope structure defined in docs/specification.md
agents session create --output yaml produces the equivalent YAML-serialised structure
data.session.id is used (not session_id)
data.settings is present with all five required keys
data.actor_details is present with all four required keys
messages and updated are absent from the create output
BDD scenarios in features/ cover all output fields for both JSON and YAML modes
No # type: ignore suppressions introduced
All nox stages pass
Coverage >= 97%
PR linked to this issue and merged

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/session-create-json-yaml-output-spec-deviation` - **Commit Message**: `fix(cli): align agents session create JSON/YAML output envelope with spec — use id, add settings and actor_details keys` - **Milestone**: v3.2.0 - **Parent Epic**: #868 ## Background and Context The `agents session create` command's JSON and YAML output format deviates from the specification. The spec defines a structured envelope with `session`, `settings`, and `actor_details` keys nested under `data`, but the implementation returns a flat dict using different field names. Per `docs/specification.md` (section "agents session create"), the specification is the authoritative source of truth. When the codebase deviates from the specification, the code must be updated to match it. **Code Location**: `src/cleveragents/cli/commands/session.py`, `_session_summary_dict()` function and `create()` command (lines ~110–130, ~190–250) ## Expected Behaviour (from spec) ```json { "data": { "session": { "id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", "actor": "local/orchestrator", "created": "2026-02-08T12:44:00Z", "namespace": "local" }, "settings": { "automation": "review", "streaming": "off", "context": "default", "memory": "enabled", "max_history": 50 }, "actor_details": { "provider": "anthropic", "model": "claude-3.5", "temperature": 0.7, "context_window": "200K tokens" } } } ``` ## Actual Behaviour The implementation returns `_session_summary_dict()` which produces a flat, non-conforming structure: ```json { "session_id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z", "actor": "(none)", "namespace": "local", "messages": 0, "created": "2026-02-08T12:44:00Z", "updated": "2026-02-08T12:44:00Z" } ``` ## Deviations from Spec 1. Uses `session_id` instead of `id` (spec uses `id` nested under a `session` key) 2. Missing `settings` key with `automation`, `streaming`, `context`, `memory`, `max_history` 3. Missing `actor_details` key with `provider`, `model`, `temperature`, `context_window` 4. Includes `messages` and `updated` fields which are not part of the spec's create output 5. The session fields are not nested under a `session` key inside a `data` envelope **Severity**: High — the JSON/YAML output format is a spec contract used by scripts and integrations. ## Subtasks - [ ] Read `docs/specification.md` section "agents session create" and confirm all required JSON/YAML envelope fields - [ ] Write BDD feature scenarios (`.feature` file) covering the full JSON output envelope (`data.session.id`, `data.settings.*`, `data.actor_details.*`) - [ ] Write BDD feature scenarios covering the YAML output format (same structure, YAML-serialised) - [ ] Rename `session_id` → `id` and nest session fields under a `session` key inside a `data` envelope in `_session_summary_dict()` - [ ] Add `settings` key to the output dict, populated from the session's configuration (automation, streaming, context, memory, max_history) - [ ] Add `actor_details` key to the output dict, populated from the resolved actor (provider, model, temperature, context_window) - [ ] Remove `messages` and `updated` fields from the create output (they are not in the spec's create envelope) - [ ] Ensure the `create()` command passes the structured envelope to the JSON/YAML formatter - [ ] Run `nox` (all sessions) and confirm all quality gates pass - [ ] Confirm coverage remains ≥ 97% ## Definition of Done - [ ] `agents session create --output json` produces the exact envelope structure defined in `docs/specification.md` - [ ] `agents session create --output yaml` produces the equivalent YAML-serialised structure - [ ] `data.session.id` is used (not `session_id`) - [ ] `data.settings` is present with all five required keys - [ ] `data.actor_details` is present with all four required keys - [ ] `messages` and `updated` are absent from the create output - [ ] BDD scenarios in `features/` cover all output fields for both JSON and YAML modes - [ ] No `# type: ignore` suppressions introduced - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR linked to this issue and merged --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.2.0 milestone

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

freemo added a new dependency

2026-04-05 03:06:18 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo commented

2026-04-05 03:14:59 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 07:21:47 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo commented

2026-04-05 10:13:29 +00:00

Author

Owner

Starting implementation on branch fix/session-create-json-yaml-output-spec-deviation.

Implementation Summary:

Fixed _session_summary_dict() in src/cleveragents/cli/commands/session.py by introducing a new _session_create_dict() function that produces the spec-compliant nested envelope:

data.session.id (was session_id at top level)
data.settings with all 5 required keys
data.actor_details with all 4 required keys
Removed messages and updated from create output

Added BDD feature file features/session_create_json_yaml_output.feature with 9 scenarios covering JSON and YAML output spec compliance.

All quality gates passing: lint ✓, typecheck ✓, unit_tests ✓, security_scan ✓, dead_code ✓

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/session-create-json-yaml-output-spec-deviation`. **Implementation Summary:** Fixed `_session_summary_dict()` in `src/cleveragents/cli/commands/session.py` by introducing a new `_session_create_dict()` function that produces the spec-compliant nested envelope: - `data.session.id` (was `session_id` at top level) - `data.settings` with all 5 required keys - `data.actor_details` with all 4 required keys - Removed `messages` and `updated` from create output Added BDD feature file `features/session_create_json_yaml_output.feature` with 9 scenarios covering JSON and YAML output spec compliance. All quality gates passing: lint ✓, typecheck ✓, unit_tests ✓, security_scan ✓, dead_code ✓ --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo commented

2026-04-05 10:15:19 +00:00

Author

Owner

All subtasks complete. Quality gates passed. Creating PR.

Implementation Summary:

Added _session_create_dict() in src/cleveragents/cli/commands/session.py producing spec-compliant nested envelope
data.session.id (was session_id at top level)
data.settings with all 5 required keys (automation, streaming, context, memory, max_history)
data.actor_details with all 4 required keys (provider, model, temperature, context_window)
Removed messages and updated from create output
Added BDD feature file features/session_create_json_yaml_output.feature with 9 scenarios
Updated features/session_create_error.feature to match new output format

All quality gates: lint ✓, typecheck ✓, unit_tests ✓, security_scan ✓, dead_code ✓

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

All subtasks complete. Quality gates passed. Creating PR. **Implementation Summary:** - Added `_session_create_dict()` in `src/cleveragents/cli/commands/session.py` producing spec-compliant nested envelope - `data.session.id` (was `session_id` at top level) - `data.settings` with all 5 required keys (automation, streaming, context, memory, max_history) - `data.actor_details` with all 4 required keys (provider, model, temperature, context_window) - Removed `messages` and `updated` from create output - Added BDD feature file `features/session_create_json_yaml_output.feature` with 9 scenarios - Updated `features/session_create_error.feature` to match new output format All quality gates: lint ✓, typecheck ✓, unit_tests ✓, security_scan ✓, dead_code ✓ --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo removed this from the v3.2.0 milestone

2026-04-06 22:27:39 +00:00

freemo commented

2026-04-06 22:27:57 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.