Add `ConversationState.copy()` method to deduplicate state-cloning logic

[xingyaoww]

Why

The LocalConversation.fork() method (introduced in #2841) contains inline logic for deep-copying conversation state fields (events, agent_state, activated_knowledge_skills, stats, tags). Each field requires different copy semantics:

• events: deep-copied via event.model_copy(deep=True) (mutable Pydantic models)
• agent_state: deep-copied via copy.deepcopy() (arbitrary mutable values)
• activated_knowledge_skills: shallow list copy (immutable str elements)
• stats: model_copy(deep=True) (Pydantic model)
• tags: shallow dict copy (immutable str keys/values)

This knowledge is currently embedded inside fork(). As more operations need to clone or snapshot state (e.g., checkpointing, branching, replay), this logic would be duplicated.

Proposal

Add a copy() (or snapshot()) method on ConversationState that encapsulates the field-by-field copy semantics and returns a new ConversationState with its own identity and independent mutable state. The method should:

1. Accept an optional new ConversationID
2. Deep-copy events, agent_state, and stats
3. Shallow-copy immutable-element collections (activated_knowledge_skills, tags)
4. Handle private attributes (_fs, _events, _lock) appropriately for the new instance
5. Optionally accept reset_metrics=True to start fresh stats

This would let fork() delegate to state.copy(...) instead of managing the details inline.

Context

Raised during review of #2841 by @xingyaoww: #2841 (comment)

This issue was created by an AI assistant (OpenHands) on behalf of the user.

[xingyaoww]

@OpenHands implement this, start a new PR and /iterate

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

The request from issue #2885 has been fully implemented and a PR created with CI passing.

Checklist

• Add snapshot() method to ConversationState — Encapsulates all field-by-field copy semantics (deep-copy for events/agent_state/stats, shallow-copy for immutable-element collections, shared references for immutable models, fresh private attrs)
• Accept optional ConversationID — Auto-generates UUID if None
• Accept file_store parameter — Falls back to InMemoryFileStore
• Accept reset_metrics parameter — Starts fresh ConversationStats when True
• Handle private attributes appropriately — Fresh _lock and _on_state_change; shared _cipher
• Refactor LocalConversation.fork() to delegate to state.snapshot() — Removed inline copy logic and unused import copy
• Named snapshot() instead of copy() — Avoided conflict with Pydantic's BaseModel.copy()
• 18 tests added covering isolation, copy semantics, edge cases
• All 15 existing fork tests still pass
• All CI checks pass (sdk-tests, cross-tests, pre-commit, pyright, API compat)
• PR created: Add ConversationState.snapshot() to deduplicate state-cloning logic #2886 (closes Add ConversationState.copy() method to deduplicate state-cloning logic #2885)
• PR marked as ready for review

Conciseness

The changes are minimal and focused — only 3 files modified:

1. state.py — Added import copy and the snapshot() method
2. local_conversation.py — Replaced inline copy logic in fork() with snapshot() delegation, removed unused import copy
3. test_state_snapshot.py — New test file

No extraneous changes were made.

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?