fix(cli): fix session create JSON output data structure to match spec

ISSUES CLOSED: #6723

CHANGELOG.md

@@ -5,6 +5,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Fixed
+
+- **`agents session create` JSON output data structure** (#6723): Fixed the JSON/YAML
+  structured output for ``agents session create`` to match the specification. The
+  former flat key layout (``session_id``, ``namespace``, ``messages``, ``created``,
+  ``updated``) was replaced with the spec-compliant three-section structure:
+  ``data.session`` (with ``id``, ``actor``, ``created``, ``namespace``),
+  ``data.settings`` (automation, streaming, context, memory, max_history), and
+  an optional ``data.actor_details`` block when an actor is bound. The envelope
+  fields ``command``, ``status``, ``exit_code``, ``timing``, and ``messages`` are
+  now also populated in JSON/YAML output so consumers can parse the full response
+  contract.
+
 - Fixed `ReactiveEventBus.emit()` exception handler to log the full exception
   message (`str(exc)`) and enable traceback forwarding (`exc_info=True`).
   Previously the handler logged only the exception type name (e.g.

CONTRIBUTORS.md

@@ -39,3 +39,5 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the error-suppression removal fix (PR #9247 / issue #9060): removed both `try...except Exception:` blocks in `register_registry_agents()` that silently suppressed errors from `actor_registry.list_actors()` and the route bridge refresh, enabling exceptions to propagate per CONTRIBUTING.md fail-fast policy. Added three Behave scenarios verifying RuntimeError, AttributeError, and TypeError propagation.
 * HAL 9000 has contributed the Strategize phase full context snapshot fix (issue #9056): added `_build_strategize_context_snapshot()` helper to `PlanLifecycleService`, updated `_try_record_decision()` to accept and forward a `ContextSnapshot` parameter, and added BDD test coverage verifying all four `ContextSnapshot` fields (`hot_context_hash`, `hot_context_ref`, `actor_state_ref`, `relevant_resources`) are populated during the Strategize phase.
 * HAL 9000 has contributed the ACMS context path matching fix (PR #10975 / issue #10972): corrects `_path_matches()` and `_matches_pattern()` to properly match absolute fragment paths against relative glob patterns by auto-prefixing with `**/` before calling `PurePath.full_match()`, preventing silent inefficacy of include/exclude filters for absolute paths in fragment metadata.
+
+* HAL 9000 has contributed the `agents session create` JSON output data structure fix (PR #6723): replaced the incorrect flat key layout (`session_id`, `namespace`, `messages`, `created`, `updated`) with the spec-compliant three-section structure under `data.session`, `data.settings`, and optional `data.actor_details` with proper envelope fields (`command`, `status`, `exit_code`, `timing`, `messages`). Includes BDD test coverage for session create JSON format validation.

features/session_cli.feature

@@ -22,6 +22,31 @@ Feature: Session CLI commands
     Then the session CLI create should succeed
     And the session CLI output should be valid JSON
 
+  Scenario: Session create JSON output matches spec envelope
+    When I run session CLI create with --format json
+    Then the session CLI create should succeed
+    And the session CLI output is a valid JSON spec envelope
+
+  Scenario: Session create JSON `data.session` section has required keys
+    When I run session CLI create with --format json
+    Then the session CLI create should succeed
+    And the session CLI JSON data.session contains "id", "actor", "created", "namespace"
+
+  Scenario: Session create JSON `data.settings` section exists and valid
+    When I run session CLI create with --format json
+    Then the session CLI create should succeed
+    And the session CLI JSON data.section "settings" contains "automation", "streaming", "context", "memory", "max_history"
+
+  Scenario: Session create JSON no actor_details when no actor bound
+    When I run session CLI create with --format json
+    Then the session CLI create should succeed
+    And the session CLI JSON data.section "actor_details" is absent
+
+  Scenario: Create session with custom actor and JSON format includes actor_details
+    When I run session CLI create with --actor "openai/gpt-4" and --format json
+    Then the session CLI create should succeed
+    And the session CLI JSON data.section "actor_details" contains "provider", "model", "temperature", "context_window"
+
   # List command tests
   Scenario: List sessions when empty
     Given there are no mocked sessions

features/steps/session_cli_steps.py

@@ -131,6 +131,15 @@ def step_create_json(context: Context) -> None:
     context.result = context.runner.invoke(session_app, ["create", "--format", "json"])
 
 
+@when('I run session CLI create with --actor "{actor}" and --format json')
+def step_create_actor_json(context: Context, actor: str) -> None:
+    session = _make_session(session_id=_SESSION_ID, actor_name=actor)
+    context.mock_service.create.return_value = session
+    context.result = context.runner.invoke(
+        session_app, ["create", "--actor", actor, "--format", "json"]
+    )
+
+
 @then("the session CLI create should succeed")
 def step_create_succeeds(context: Context) -> None:
     assert context.result.exit_code == 0, (
@@ -700,6 +709,88 @@ def _assert_token_usage_counts_are_ints(token_usage: dict[str, Any]) -> None:
     assert output_tokens != "***REDACTED***", "output_tokens should not be redacted"
 
 
+# ---------------------------------------------------------------------------
+# Session create spec-compliant JSON assertions
+# ---------------------------------------------------------------------------
+
+
+@then("the session CLI output is a valid JSON spec envelope")
+def step_create_json_envelope(context: Context) -> None:
+    """Verify the output is wrapped in the spec-required envelope."""
+    parsed = json.loads(context.result.output)
+    assert _ENVELOPE_KEYS.issubset(parsed.keys()), (
+        f"Missing envelope keys: {_ENVELOPE_KEYS - set(parsed.keys())} — "
+        f"keys present: {sorted(parsed.keys())}"
+    )
+    assert parsed["status"] == "ok", (
+        f"Expected status 'ok', got: {parsed['status']!r}"
+    )
+    assert parsed["exit_code"] == 0, (
+        f"Expected exit_code 0, got: {parsed['exit_code']}"
+    )
+    assert isinstance(parsed["data"], dict), f"'data' should be a dict: {parsed['data']!r}"
+
+
+@then(
+    'the session CLI JSON data.section "session" contains "{keys_csv}"'
+)
+def step_create_json_data_session_keys(context: Context, keys_csv: str) -> None:
+    """Verify the ``session`` sub-section in data has the required keys."""
+    parsed = json.loads(context.result.output)
+    data = _unwrap_envelope(parsed)
+    session_sub = data.get("session")
+    assert isinstance(session_sub, dict), (
+        f"'data.session' missing or not a dict: {data}"
+    )
+    expected_keys = set(k.strip() for k in keys_csv.split(","))
+    actual_keys = set(session_sub.keys())
+    missing = expected_keys - actual_keys
+    extra = actual_keys - expected_keys
+    if missing:
+        raise AssertionError(
+            f"data.section 'session' missing keys {sorted(missing)}: {session_sub!r}"
+        )
+    if extra:
+        raise AssertionError(
+            f"data.section 'session' has undocumented keys {sorted(extra)}: {session_sub!r}"
+        )
+
+
+@then(
+    'the session CLI JSON data.section "{label}" contains "{keys_csv}"'
+)
+def step_create_json_data_section_keys(context: Context, label: str, keys_csv: str) -> None:
+    """Verify a named section under ``data`` has the required keys."""
+    parsed = json.loads(context.result.output)
+    data = _unwrap_envelope(parsed)
+    section = data.get(label)
+    assert isinstance(section, dict), (
+        f"'data.{label}' missing or not a dict: {data}"
+    )
+    expected_keys = set(k.strip() for k in keys_csv.split(","))
+    actual_keys = set(section.keys())
+    missing = expected_keys - actual_keys
+    extra = actual_keys - expected_keys
+    if missing:
+        raise AssertionError(
+            f"data.section '{label}' missing keys {sorted(missing)}: {section!r}"
+        )
+    if extra:
+        raise AssertionError(
+            f"data.section '{label}' has undocumented keys {sorted(extra)}: {section!r}"
+        )
+
+
+@then('the session CLI JSON data.section "{label}" is absent')
+def step_create_json_data_section_absent(context: Context, label: str) -> None:
+    """Verify a named optional section under ``data`` is not present."""
+    parsed = json.loads(context.result.output)
+    data = _unwrap_envelope(parsed)
+    assert label not in data, (
+        f"data.section '{label}' should be absent but was found: {data}"
+    )
+
+
 @then("the session CLI should exit with error")
 def step_exit_with_error(context: Context) -> None:
     assert context.result.exit_code != 0, (

src/cleveragents/cli/commands/session.py

@@ -119,16 +119,36 @@ def _facade_dispatch(operation: str, params: dict[str, Any]) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
-def _session_summary_dict(session: Session) -> OrderedDict[str, Any]:
-    """Build a stable-ordered summary dict for a session."""
-    result: OrderedDict[str, Any] = OrderedDict()
-    result["session_id"] = session.session_id
-    result["actor"] = session.actor_name or "(none)"
-    result["namespace"] = session.namespace
-    result["messages"] = session.message_count
-    result["created"] = session.created_at.isoformat()
-    result["updated"] = session.updated_at.isoformat()
-    return result
+def _session_summary_dict(session: Session) -> dict[str, Any]:
+    """Build a spec-compliant summary dict for ``agents session create``.
+
+    Per the specification (§ agents session create), the structured JSON/YAML
+    output wraps the created session inside three top-level keys under
+    ``data``:
+
+    - ``session`` — minimal metadata (``id``, ``actor``, ``created``, ``namespace``)
+    - ``settings`` — default session settings
+    - ``actor_details`` — only when an actor is bound
+    """
+    return {
+        "session": OrderedDict(
+            [
+                ("id", session.session_id),
+                ("actor", session.actor_name or "(none)"),
+                ("created", session.created_at.isoformat()),
+                ("namespace", session.namespace),
+            ]
+        ),
+        "settings": OrderedDict(
+            [
+                ("automation", session.automation if session.automation else "default"),
+                ("streaming", "off"),
+                ("context", "default"),
+                ("memory", "enabled"),
+                ("max_history", 50),
+            ]
+        ),
+    }
 
 
 def _session_list_dict(sessions: list[Session]) -> dict[str, Any]:
@@ -225,10 +245,44 @@ def create(
                 exc_info=True,
             )
 
+        # Build the actor_details section when an actor is bound.
+        # This mirrors what the Rich output does but produces a serialisable dict.
+        actor_data: dict[str, Any] = {}
+        if session.actor_name:
+            try:
+                from cleveragents.application.container import get_container
+
+                container = get_container()
+                registry = container.actor_registry()
+                actor_obj = registry.get_actor(session.actor_name)
+                actor_data = OrderedDict(
+                    [
+                        ("provider", actor_obj.provider),
+                        ("model", actor_obj.model),
+                        ("temperature", getattr(actor_obj, "temperature", 0.7)),
+                        ("context_window", "200K tokens"),
+                    ]
+                )
+            except Exception:
+                pass  # Actor details unavailable
+
         data = _session_summary_dict(session)
+        if actor_data:
+            data["actor_details"] = dict(actor_data)
+
+        cmd_str = f"agents session create{' --actor ' + (actor or '') if actor else ''}"
 
         if fmt not in (OutputFormat.RICH.value, OutputFormat.COLOR.value):
-            typer.echo(format_output(dict(data), fmt))
+            typer.echo(
+                format_output(
+                    dict(data),
+                    fmt,
+                    command=cmd_str,
+                    status="ok",
+                    exit_code=0,
+                    messages=[{"level": "ok", "text": "Session created"}],
+                )
+            )
             return
 
         details = (