UAT: `agents session export` schema version is "1.0" but spec requires "v3" — causes import validation mismatch #3498

New issue

Open

opened 2026-04-05 18:40:44 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 18:40:44 +00:00

Owner

Metadata

Branch: fix/session-export-schema-version-v3
Commit Message: fix(session): correct export schema version constant from "1.0" to "v3"
Milestone: None (backlog)
Parent Epic: #397

Background and Context

Code-level analysis of src/cleveragents/domain/models/core/session.py and src/cleveragents/application/services/session_service.py against docs/specification.md §"agents session export" (lines 1987–2115) and §"agents session import" (lines 2117–2230).

The export schema version constant is "1.0" but the specification shows "v3" in the export output. This means the exported JSON file will contain "schema_version": "1.0" while the spec shows "Schema Version: v3" in the output panels. Additionally, the import validation checks for "1.0" which would reject any file exported by a spec-compliant implementation using "v3".

Current Behavior (Actual)

In src/cleveragents/domain/models/core/session.py line 58:

EXPORT_SCHEMA_VERSION = "1.0"

The exported JSON file contains:

{
  "schema_version": "1.0",
  ...
}

The import validation in session_service.py line 256:

if schema_version != EXPORT_SCHEMA_VERSION:
    raise SessionImportError(...)

This means only files with schema_version: "1.0" can be imported.

Expected Behavior

Per docs/specification.md §"agents session export" (lines 2019 and 2076), the spec shows:

In the "Contents" panel: Schema Version: v3
In the JSON output: "schema_version": "v3"

The export should use "v3" as the schema version to match the spec.

Impact

The "Contents" panel (once implemented per issue #3493) will show Schema Version: 1.0 instead of v3
Any future spec-compliant implementation using "v3" would produce files that cannot be imported by the current implementation
The spec and implementation are out of sync on the canonical schema version identifier

Steps to Reproduce

Create a session: agents session create
Export: agents session export <SESSION_ID>
Observe: exported JSON contains "schema_version": "1.0" instead of "v3"

Code Location

src/cleveragents/domain/models/core/session.py, line 58: EXPORT_SCHEMA_VERSION = "1.0"
src/cleveragents/application/services/session_service.py, line 256: schema version validation

Subtasks

Update EXPORT_SCHEMA_VERSION constant from "1.0" to "v3" in session.py
Update import validation to accept "v3" (and optionally "1.0" for backward compatibility)
Update any tests that assert on the schema version value
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

EXPORT_SCHEMA_VERSION is "v3" matching the spec
Import validation accepts "v3" schema version
All Behave scenarios pass
All nox stages pass
Coverage >= 97%
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.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0 (Post-MVP Release). It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `fix/session-export-schema-version-v3` - **Commit Message**: `fix(session): correct export schema version constant from "1.0" to "v3"` - **Milestone**: None (backlog) - **Parent Epic**: #397 ## Background and Context Code-level analysis of `src/cleveragents/domain/models/core/session.py` and `src/cleveragents/application/services/session_service.py` against `docs/specification.md` §"agents session export" (lines 1987–2115) and §"agents session import" (lines 2117–2230). The export schema version constant is `"1.0"` but the specification shows `"v3"` in the export output. This means the exported JSON file will contain `"schema_version": "1.0"` while the spec shows `"Schema Version: v3"` in the output panels. Additionally, the import validation checks for `"1.0"` which would reject any file exported by a spec-compliant implementation using `"v3"`. ## Current Behavior (Actual) In `src/cleveragents/domain/models/core/session.py` line 58: ```python EXPORT_SCHEMA_VERSION = "1.0" ``` The exported JSON file contains: ```json { "schema_version": "1.0", ... } ``` The import validation in `session_service.py` line 256: ```python if schema_version != EXPORT_SCHEMA_VERSION: raise SessionImportError(...) ``` This means only files with `schema_version: "1.0"` can be imported. ## Expected Behavior Per `docs/specification.md` §"agents session export" (lines 2019 and 2076), the spec shows: - In the "Contents" panel: `Schema Version: v3` - In the JSON output: `"schema_version": "v3"` The export should use `"v3"` as the schema version to match the spec. ## Impact 1. The "Contents" panel (once implemented per issue #3493) will show `Schema Version: 1.0` instead of `v3` 2. Any future spec-compliant implementation using `"v3"` would produce files that cannot be imported by the current implementation 3. The spec and implementation are out of sync on the canonical schema version identifier ## Steps to Reproduce 1. Create a session: `agents session create` 2. Export: `agents session export <SESSION_ID>` 3. Observe: exported JSON contains `"schema_version": "1.0"` instead of `"v3"` ## Code Location - `src/cleveragents/domain/models/core/session.py`, line 58: `EXPORT_SCHEMA_VERSION = "1.0"` - `src/cleveragents/application/services/session_service.py`, line 256: schema version validation ## Subtasks - [ ] Update `EXPORT_SCHEMA_VERSION` constant from `"1.0"` to `"v3"` in `session.py` - [ ] Update import validation to accept `"v3"` (and optionally `"1.0"` for backward compatibility) - [ ] Update any tests that assert on the schema version value - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - [ ] `EXPORT_SCHEMA_VERSION` is `"v3"` matching the spec - [ ] Import validation accepts `"v3"` schema version - [ ] All Behave scenarios pass - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] 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. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0 (Post-MVP Release). It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-05 18:40:58 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-05 18:43:37 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 18:45:07 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 18:52:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377