[BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching

[moonbox3]

Motivation and Context

Refactors the workflow state management system with breaking changes:

• Rename SharedState -> State class and _shared_state.py -> _state.py
• Convert all async methods to sync (Python dicts are thread-safe; async was unnecessary overhead)
• Implement superstep caching: writes go to pending cache, committed at superstep boundary via commit(), which is now consistent with the .NET behavior.
• Add get(key, default=None) API that returns default instead of raising KeyError
• Add has(key) method for existence checks
• Rename WorkflowCheckpoint.shared_state → WorkflowCheckpoint.state
• Remove State from public exports (internal implementation detail)

Breaking Changes

Before	After
SharedState	State
ctx.shared_state	ctx.state
await ctx.get_shared_state(key)	ctx.get_state(key, default=None)
await ctx.set_shared_state(key, value)	ctx.set_state(key, value)
checkpoint.shared_state	checkpoint.state

Description

• Closes Python: Refactor State class - rename, simplify, and implement superstep caching #3525
• Closes Python: Clean up public API surface and kwargs propagation #3526

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	171	23	86%	95, 117, 151, 167–168, 219–220, 222–223, 255–257, 265–267, 277–279, 281, 285, 289, 293–294
_checkpoint.py	121	2	98%	182–183
_checkpoint_summary.py	27	4	85%	36–39
_const.py	6	0	100%
_edge_runner.py	162	13	91%	53, 58, 71, 138–139, 143, 150, 206, 211, 355–356, 360, 401
_executor.py	173	10	94%	212, 334, 336, 345, 365, 368, 475, 480, 490, 649
_runner.py	211	32	84%	124–125, 168–171, 175, 216–218, 243–244, 246, 281–283, 307–311, 315, 350, 354, 356, 362, 370–373, 386, 422
_runner_context.py	168	6	96%	84, 87, 383, 403, 491, 495
_state.py	43	0	100%
_workflow.py	249	17	93%	89, 259–261, 263–264, 282, 310, 412, 689, 723, 728, 731, 750–752, 817
_workflow_context.py	174	21	87%	63–64, 72, 76, 90, 166, 191, 309, 428, 471, 473–474, 476–477, 486–488, 490–492, 494
_workflow_executor.py	173	43	75%	96, 445, 456, 468–471, 474–476, 479–480, 482, 485–487, 490–494, 498–499, 508, 513, 547, 573–578, 581, 584, 592, 597, 608, 618, 622, 628, 632, 642, 646
TOTAL	16332	1981	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3845	221 💤	0 ❌	0 🔥	1m 9s ⏱️

[Copilot]

Pull request overview

This PR implements a breaking refactoring of workflow state management, renaming SharedState to State, converting all async methods to sync, and implementing superstep caching semantics to align with .NET behavior.

Changes:

• Renamed SharedState class to State and file _shared_state.py to _state.py
• Converted all state methods from async to sync (removing asyncio.Lock)
• Implemented superstep caching: writes go to pending buffer, committed at boundaries via commit()
• Added get(key, default=None) API and has(key) method
• Renamed WorkflowCheckpoint.shared_state → WorkflowCheckpoint.state
• Updated all references across codebase (workflow context, runner, executors, tests, samples)

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
_state.py	New State class with sync methods and superstep caching implementation
_workflow.py	Updated to use State with commit() call after kwargs initialization
_runner.py	Integrated commit() at superstep boundaries
_workflow_context.py	Changed to sync get_state/set_state methods
_checkpoint.py	Renamed shared_state field to state
__init__.py	Updated exports (but State still exported - should be removed)
Test files	Updated all test mocks and assertions to use State
Sample files	Updated comments and documentation references
Frontend	Updated TypeScript interfaces and references

[eavanvalkenburg]

is this prefix needed to demonstrate the concept?

[eavanvalkenburg]

maybe clarify that this is committed state only

[eavanvalkenburg]

should we deal with two pending updates for the same key? maybe from two different executors?