fix: align RunState schema policy with release boundaries (#2632)

Author: seratch

.agents/skills/implementation-strategy/SKILL.md

@@ -19,16 +19,17 @@ Use this skill before editing code when the task changes runtime behavior or any
    ```
 3. Judge breaking-change risk against that latest release tag, not against unreleased branch churn or post-tag changes already on `main`.
 4. Prefer the simplest implementation that satisfies the current task. Update callers, tests, docs, and examples directly instead of preserving superseded unreleased interfaces.
-5. Add a compatibility layer only when there is a concrete released consumer or durable external state that requires it, or when the user explicitly asks for a migration path.
+5. Add a compatibility layer only when there is a concrete released consumer or an explicitly supported durable external state boundary that requires it, or when the user explicitly asks for a migration path.
 
 ## Compatibility boundary rules
 
 - Released public API or documented external behavior: preserve compatibility or provide an explicit migration path.
-- Persisted schema, serialized state, wire protocol, CLI flags, environment variables, and externally consumed config: treat as compatibility-sensitive even if the implementation is local.
-- Python-specific durable surfaces such as `RunState`, session persistence, exported dataclass constructor order, and documented model/provider configuration should be treated as compatibility-sensitive when they were part of the latest release tag.
+- Persisted schema, serialized state, wire protocol, CLI flags, environment variables, and externally consumed config: treat as compatibility-sensitive when they are part of the latest release or when the repo explicitly intends to preserve them across commits, processes, or machines.
+- Python-specific durable surfaces such as `RunState`, session persistence, exported dataclass constructor order, and documented model/provider configuration should be treated as compatibility-sensitive when they were part of the latest release tag or are explicitly supported as a shared durability boundary.
 - Interface changes introduced only on the current branch: not a compatibility target. Rewrite them directly.
-- Interface changes present on `main` but added after the latest release tag: not a semver breaking change by themselves. Rewrite them directly unless they already define durable external state.
+- Interface changes present on `main` but added after the latest release tag: not a semver breaking change by themselves. Rewrite them directly unless they already define a released or explicitly supported durable external state boundary.
 - Internal helpers, private types, same-branch tests, fixtures, and examples: update them directly instead of adding adapters.
+- Unreleased persisted schema versions on `main` may be renumbered or squashed before release when intermediate snapshots are intentionally unsupported. When you do that, update the support set and tests together so the boundary is explicit.
 
 ## Default implementation stance
 

AGENTS.md

@@ -32,13 +32,13 @@ When working on OpenAI API or OpenAI platform integrations in this repo (Respons
 
 #### `$implementation-strategy`
 
-Before changing runtime code, exported APIs, external configuration, persisted schemas, wire protocols, or other user-facing behavior, use `$implementation-strategy` to decide the compatibility boundary and implementation shape. Judge breaking changes against the latest release tag, not unreleased branch-local churn. Interfaces introduced or changed after the latest release tag may be rewritten without compatibility shims unless they define durable external state or the user explicitly asks for a migration path.
+Before changing runtime code, exported APIs, external configuration, persisted schemas, wire protocols, or other user-facing behavior, use `$implementation-strategy` to decide the compatibility boundary and implementation shape. Judge breaking changes against the latest release tag, not unreleased branch-local churn. Interfaces introduced or changed after the latest release tag may be rewritten without compatibility shims unless they define a released or explicitly supported durable external state boundary, or the user explicitly asks for a migration path. Unreleased persisted formats on `main` may be renumbered or squashed before release when intermediate snapshots are intentionally unsupported.
 
 ### ExecPlans
 
-Call out compatibility risk early in your plan only when the change affects behavior shipped in the latest release tag or durable external state, and confirm the approach before implementing changes that could impact users.
+Call out compatibility risk early in your plan only when the change affects behavior shipped in the latest release tag or a released or explicitly supported durable external state boundary, and confirm the approach before implementing changes that could impact users.
 
-Use an ExecPlan when work is multi-step, spans several files, involves new features or refactors, or is likely to take more than about an hour. Start with the template and rules in `PLANS.md`, keep milestones and living sections (Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective) up to date as you execute, and rewrite the plan if scope shifts. Call out compatibility risk only when the plan changes behavior shipped in the latest release tag or durable external state. Do not treat branch-local interface churn or unreleased post-tag changes on `main` as breaking by default; prefer direct replacement over compatibility layers in those cases. If you intentionally skip an ExecPlan for a complex task, note why in your response so reviewers understand the choice.
+Use an ExecPlan when work is multi-step, spans several files, involves new features or refactors, or is likely to take more than about an hour. Start with the template and rules in `PLANS.md`, keep milestones and living sections (Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective) up to date as you execute, and rewrite the plan if scope shifts. Call out compatibility risk only when the plan changes behavior shipped in the latest release tag or a released or explicitly supported durable external state boundary. Do not treat branch-local interface churn or unreleased post-tag changes on `main` as breaking by default; prefer direct replacement over compatibility layers in those cases, and renumber or squash unreleased persisted schemas before release when the intermediate snapshots are intentionally unsupported. If you intentionally skip an ExecPlan for a complex task, note why in your response so reviewers understand the choice.
 
 ### Public API Positional Compatibility
 
@@ -84,7 +84,7 @@ The OpenAI Agents Python repository provides the Python Agents SDK, examples, an
   - `src/agents/stream_events.py` (stream event names)
   - `src/agents/run_state.py` (RunState serialization/deserialization)
   - `src/agents/run_internal/session_persistence.py` (session save/rewind)
-- If the serialized RunState shape changes, bump `CURRENT_SCHEMA_VERSION` in `src/agents/run_state.py` and update serialization/deserialization accordingly.
+- If the serialized RunState shape changes, update `CURRENT_SCHEMA_VERSION` in `src/agents/run_state.py` and the related serialization/deserialization logic. Keep released schema versions readable, and feel free to renumber or squash unreleased schema versions before release when those intermediate snapshots are intentionally unsupported.
 
 ## Operation Guide
 
@@ -102,7 +102,7 @@ The OpenAI Agents Python repository provides the Python Agents SDK, examples, an
    ```
 2. If dependencies changed or you are setting up the repo, run `make sync`.
 3. Implement changes and add or update tests alongside code updates.
-4. Highlight compatibility or API risks in your plan before implementing changes that alter the latest released behavior or durable external state.
+4. Highlight compatibility or API risks in your plan before implementing changes that alter the latest released behavior or a released or explicitly supported durable external state boundary.
 5. Build docs when you touch documentation:
    ```bash
    make build-docs

src/agents/run_state.py

@@ -112,14 +112,14 @@
 
 
 # RunState schema policy.
-# 1. Bump CURRENT_SCHEMA_VERSION when serialized shape/semantics change.
-# 2. Keep older readable versions in SUPPORTED_SCHEMA_VERSIONS for backward reads.
+# 1. Keep schema versions shipped in releases readable.
+# 2. Unreleased schema versions may be renumbered or squashed before release when their
+#    intermediate snapshots are intentionally unsupported.
 # 3. to_json() always emits CURRENT_SCHEMA_VERSION.
-# 4. Forward compatibility is intentionally fail-fast (older SDKs reject newer versions).
-CURRENT_SCHEMA_VERSION = "1.7"
-SUPPORTED_SCHEMA_VERSIONS = frozenset(
-    {"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", CURRENT_SCHEMA_VERSION}
-)
+# 4. Forward compatibility is intentionally fail-fast (older SDKs reject newer or unsupported
+#    versions).
+CURRENT_SCHEMA_VERSION = "1.5"
+SUPPORTED_SCHEMA_VERSIONS = frozenset({"1.0", "1.1", "1.2", "1.3", "1.4", CURRENT_SCHEMA_VERSION})
 
 _FUNCTION_OUTPUT_ADAPTER: TypeAdapter[FunctionCallOutput] = TypeAdapter(FunctionCallOutput)
 _COMPUTER_OUTPUT_ADAPTER: TypeAdapter[ComputerCallOutput] = TypeAdapter(ComputerCallOutput)

tests/test_run_state.py

@@ -3849,11 +3849,12 @@ async def test_from_json_missing_schema_version(self):
             await RunState.from_json(agent, state_json)
 
     @pytest.mark.asyncio
-    async def test_from_json_unsupported_schema_version(self):
+    @pytest.mark.parametrize("schema_version", ["1.6", "1.7", "2.0"])
+    async def test_from_json_unsupported_schema_version(self, schema_version: str):
         """Test that from_json raises error when schema version is unsupported."""
         agent = Agent(name="TestAgent")
         state_json = {
-            "$schemaVersion": "2.0",
+            "$schemaVersion": schema_version,
             "original_input": "test",
             "current_agent": {"name": "TestAgent"},
             "context": {
@@ -3867,7 +3868,9 @@ async def test_from_json_unsupported_schema_version(self):
             "generated_items": [],
         }
 
-        with pytest.raises(UserError, match="Run state schema version 2.0 is not supported"):
+        with pytest.raises(
+            UserError, match=f"Run state schema version {schema_version} is not supported"
+        ):
             await RunState.from_json(agent, state_json)
 
     @pytest.mark.asyncio
@@ -3895,6 +3898,12 @@ async def test_from_json_accepts_previous_schema_version(self):
         assert restored._context is not None
         assert restored._context.context == {"foo": "bar"}
 
+    def test_supported_schema_versions_match_released_boundary(self):
+        """The support set should include released versions plus the current unreleased writer."""
+        assert SUPPORTED_SCHEMA_VERSIONS == frozenset(
+            {"1.0", "1.1", "1.2", "1.3", "1.4", CURRENT_SCHEMA_VERSION}
+        )
+
     @pytest.mark.asyncio
     async def test_from_json_agent_not_found(self):
         """Test that from_json raises error when agent is not found in agent map."""