Add custom state field reducers (append vs. replace) support

[MadaraUchiha-314]

Summary

This PR adds support for custom reducer semantics on state fields, allowing YAML authors to explicitly choose between append and replace behavior for list fields in agent state schemas.

Changes

• Schema Enhancement: Added optional reducer field to StateFieldDef with values "append" or "replace"

  • None (default) uses intelligent defaults: "append" for messages list fields, "replace" for everything else
  • Non-list fields ignore the reducer setting (always use replace semantics)

• State Class Builder Refactor: Updated _build_state_class() to respect per-field reducer settings

  • Removed special-casing of MessagesState base class
  • Now builds a single TypedDict with explicit Annotated types for all fields
  • Fields with reducer: append on list types get Annotated[list, add_messages] (LangGraph's smart message reducer)
  • All other fields use plain type annotations (replace semantics)

• Documentation & Tests: Added comprehensive plan for:

  • Unit tests for schema validation and default reducer resolution
  • Integration tests verifying append/replace behavior on actual state updates
  • Documentation updates explaining the new reducer field and its semantics

Implementation Details

The key insight is that MessagesState is just a TypedDict with Annotated[list, add_messages] on the messages field. By switching to explicit annotations on all fields, we gain full control over reducer behavior while maintaining backward compatibility—existing YAML without reducer settings continues to work identically.

The append reducer uses LangGraph's add_messages function (smart deduplication by message ID) rather than simple list concatenation, making it suitable for message-heavy agent state patterns.

Backward Compatibility

✅ Fully backward compatible. Existing agent definitions without reducer fields maintain current behavior:

• messages list field → append (unchanged)
• All other fields → replace (unchanged)

https://claude.ai/code/session_01R7PWjTfJ943jkev5DmAWV2