Global mutable state lacks thread/async safety in multi-agent scenarios

[MervinPraison]

Summary

The core SDK has 10+ global mutable variables that are not fully protected for concurrent multi-agent use, violating the "multi-agent + async safe by default" principle.

Unprotected Globals Identified

Location	Variable	Risk
bus/bus.py	_default_bus	Shared event bus across agents
trace/protocol.py	_default_emitter	Shared trace emitter
telemetry/integration.py	_queue_processor_running, _telemetry_executor, _telemetry_queue, _performance_mode_enabled	Race conditions in telemetry
paths.py	_data_dir_cache	Minor — cache contention
main.py	approval_callback, sync_display_callbacks, async_display_callbacks	Callback registration races

What's Already Done Well

• _lazy.py uses proper _cache_lock with double-checked locking
• trace/context_events.py uses contextvars for async-safe state
• Thread safety tests exist in tests/unit/test_thread_safety.py

What's Missing

1. Display callback registries (sync_display_callbacks, async_display_callbacks) in main.py are plain lists — concurrent modification during multi-agent runs can cause RuntimeError
2. _default_bus and _default_emitter are set without locks — two agents starting simultaneously could race
3. Telemetry globals use module-level state that could race during shutdown
4. No contextvars isolation for per-agent state in async scenarios

Suggested Fix

• Use contextvars.ContextVar for per-agent/per-session state (bus, emitter, callbacks)
• Add thread locks around global registration operations
• Consider a threading.Lock or asyncio.Lock wrapper for callback lists
• Expand test_thread_safety.py to cover these specific globals

[MervinPraison]

@claude Analyze this issue and implement a fix following AGENTS.md. Ensure backward compatibility, zero performance regression, minimal focused changes. Run tests to verify. Create a PR with your changes.

[github-actions]

Claude finished @MervinPraison's task —— View job • claude/issue-1129-20260330-2134 • [Create PR ➔](https://github.com/MervinPraison/PraisonAI/compare/main...claude/issue-1129-20260330-2134?quick_pull=1&title=Issue%20%231129%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%231129%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Thread Safety Analysis and Implementation ✅

I've successfully analyzed and implemented fixes for the global mutable state thread safety issues identified in this issue.

Tasks:

• Read AGENTS.md for repository guidelines
• Analyze current global mutable state in identified files
• Examine existing thread safety implementations
• Implement fixes using contextvars and proper locking
• Expand thread safety tests
• Run tests to verify changes
• Commit changes and create PR

Summary of Changes

Fixed Thread Safety Issues:

1. trace/protocol.py: _default_emitter - Added thread-safe double-checked locking
2. main.py: Callback registries - Protected with RLock for concurrent modification safety
3. paths.py: _data_dir_cache - Improved cache protection with proper locking
4. telemetry/integration.py: Performance mode flag - Added thread synchronization

Patterns Applied:

• Double-checked locking (fast path optimization)
• RLock for re-entrant callback access
• Fine-grained locks to minimize contention
• Zero performance regression design

Test Results:

• ✅ Trace emitter concurrent access
• ✅ Display callbacks concurrent registration
• ✅ Data directory cache concurrent access
• ✅ Event bus concurrent access
• ✅ Telemetry performance mode concurrent access

Pull Request Created

PR #1200: fix: improve thread safety for global mutable state

The implementation follows established patterns from _lazy.py and context_events.py, ensures backward compatibility, and maintains zero performance regression while making the SDK safe for concurrent multi-agent scenarios.

---

Job run | Branch: claude/issue-1129-20260330-2134

[MervinPraison]

Resolved across multiple merged PRs: #1191 (global mutable state), #1193 (thread safety gaps), #1175 (chat history safety), #1177 (memory thread safety). All identified thread-unsafe globals have been converted to thread-local or per-instance state with proper locking.