Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: create sys event types and handler
Greyson LaLonde2355ec073310
diff --git a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.pyindex f8cc43572..c8f7000cd 100644--- a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py+++ b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py@@ -71,6 +71,7 @@ from crewai.events.types.reasoning_events import (AgentReasoningFailedEvent,AgentReasoningStartedEvent,)+from crewai.events.types.system_events import SignalEvent, on_signalfrom crewai.events.types.task_events import (TaskCompletedEvent,TaskFailedEvent,@@ -159,6 +160,7 @@ class TraceCollectionListener(BaseEventListener):self._register_flow_event_handlers(crewai_event_bus)self._register_context_event_handlers(crewai_event_bus)self._register_action_event_handlers(crewai_event_bus)+ self._register_system_event_handlers(crewai_event_bus)self._listeners_setup = True@@ -458,6 +460,15 @@ class TraceCollectionListener(BaseEventListener):) -> None:self._handle_action_event("knowledge_query_failed", source, event)+ def _register_system_event_handlers(self, event_bus: CrewAIEventsBus) -> None:+ """Register handlers for system signal events (SIGTERM, SIGINT, etc.)."""++ @on_signal+ def handle_signal(source: Any, event: SignalEvent) -> None:+ """Flush trace batch on system signals to prevent data loss."""+ if self.batch_manager.is_batch_initialized():+ self.batch_manager.finalize_batch()+def _initialize_crew_batch(self, source: Any, event: Any) -> None:"""Initialize trace batch.diff --git a/lib/crewai/src/crewai/events/types/system_events.py b/lib/crewai/src/crewai/events/types/system_events.pynew file mode 100644index 000000000..b17b14c04--- /dev/null+++ b/lib/crewai/src/crewai/events/types/system_events.py@@ -0,0 +1,102 @@+"""System signal event types for CrewAI.++This module contains event types for system-level signals like SIGTERM,+allowing listeners to perform cleanup operations before process termination.+"""++from collections.abc import Callable+from enum import IntEnum+import signal+from typing import Annotated, Literal, TypeVar++from pydantic import Field, TypeAdapter++from crewai.events.base_events import BaseEvent+++class SignalType(IntEnum):+ """Enumeration of supported system signals."""++ SIGTERM = signal.SIGTERM+ SIGINT = signal.SIGINT+ SIGHUP = signal.SIGHUP+ SIGTSTP = signal.SIGTSTP+ SIGCONT = signal.SIGCONT+++class SigTermEvent(BaseEvent):+ """Event emitted when SIGTERM is received."""++ type: Literal["SIGTERM"] = "SIGTERM"+ signal_number: SignalType = SignalType.SIGTERM+ reason: str | None = None+++class SigIntEvent(BaseEvent):+ """Event emitted when SIGINT is received."""++ type: Literal["SIGINT"] = "SIGINT"+ signal_number: SignalType = SignalType.SIGINT+ reason: str | None = None+++class SigHupEvent(BaseEvent):+ """Event emitted when SIGHUP is received."""++ type: Literal["SIGHUP"] = "SIGHUP"+ signal_number: SignalType = SignalType.SIGHUP+ reason: str | None = None+++class SigTStpEvent(BaseEvent):+ """Event emitted when SIGTSTP is received.++ Note: SIGSTOP cannot be caught - it immediately suspends the process.+ """++ type: Literal["SIGTSTP"] = "SIGTSTP"+ signal_number: SignalType = SignalType.SIGTSTP+ reason: str | None = None+++class SigContEvent(BaseEvent):+ """Event emitted when SIGCONT is received."""++ type: Literal["SIGCONT"] = "SIGCONT"+ signal_number: SignalType = SignalType.SIGCONT+ reason: str | None = None+++SignalEvent = Annotated[+ SigTermEvent | SigIntEvent | SigHupEvent | SigTStpEvent | SigContEvent,+ Field(discriminator="type"),+]++signal_event_adapter: TypeAdapter[SignalEvent] = TypeAdapter(SignalEvent)++SIGNAL_EVENT_TYPES: tuple[type[BaseEvent], ...] = (+ SigTermEvent,+ SigIntEvent,+ SigHupEvent,+ SigTStpEvent,+ SigContEvent,+)+++T = TypeVar("T", bound=Callable[[object, SignalEvent], None])+++def on_signal(func: T) -> T:+ """Decorator to register a handler for all signal events.++ Args:+ func: Handler function that receives (source, event) arguments.++ Returns:+ The original function, registered for all signal event types.+ """+ from crewai.events.event_bus import crewai_event_bus++ for event_type in SIGNAL_EVENT_TYPES:+ crewai_event_bus.on(event_type)(func)+ return funcdiff --git a/lib/crewai/src/crewai/telemetry/telemetry.py b/lib/crewai/src/crewai/telemetry/telemetry.pyindex e07fe1577..848ba1133 100644--- a/lib/crewai/src/crewai/telemetry/telemetry.py+++ b/lib/crewai/src/crewai/telemetry/telemetry.py@@ -9,12 +9,14 @@ data is collected. Users can opt-in to share more complete data using thefrom __future__ import annotationsimport asyncio+import atexitfrom collections.abc import Callablefrom importlib.metadata import versionimport jsonimport loggingimport osimport platform+import signalimport threadingfrom typing import TYPE_CHECKING, Any@@ -31,6 +33,14 @@ from opentelemetry.sdk.trace.export import (from opentelemetry.trace import Spanfrom typing_extensions import Self+from crewai.events.event_bus import crewai_event_bus+from crewai.events.types.system_events import (+ SigContEvent,+ SigHupEvent,+ SigIntEvent,+ SigTStpEvent,+ SigTermEvent,+)from crewai.telemetry.constants import (CREWAI_TELEMETRY_BASE_URL,CREWAI_TELEMETRY_SERVICE_NAME,@@ -121,6 +131,7 @@ class Telemetry:)self.provider.add_span_processor(processor)+ self._register_shutdown_handlers()self.ready = Trueexcept Exception as e:if isinstance(@@ -155,6 +166,71 @@ class Telemetry:self.ready = Falseself.trace_set = False+ def _register_shutdown_handlers(self) -> None:+ """Register handlers for graceful shutdown on process exit and signals."""+ atexit.register(self._shutdown)++ self._original_handlers: dict[int, Any] = {}++ self._register_signal_handler(signal.SIGTERM, SigTermEvent, shutdown=True)+ self._register_signal_handler(signal.SIGINT, SigIntEvent, shutdown=True)+ self._register_signal_handler(signal.SIGHUP, SigHupEvent, shutdown=False)+ self._register_signal_handler(signal.SIGTSTP, SigTStpEvent, shutdown=False)+ self._register_signal_handler(signal.SIGCONT, SigContEvent, shutdown=False)++ def _register_signal_handler(+ self,+ sig: signal.Signals,+ event_class: type,+ shutdown: bool = False,+ ) -> None:+ """Register a signal handler that emits an event.++ Args:+ sig: The signal to handle.+ event_class: The event class to instantiate and emit.+ shutdown: Whether to trigger shutdown on this signal.+ """+ try:+ original_handler = signal.getsignal(sig)+ self._original_handlers[sig] = original_handler++ def handler(signum: int, frame: Any) -> None:+ crewai_event_bus.emit(self, event_class())++ if shutdown:+ self._shutdown()++ if original_handler not in (signal.SIG_DFL, signal.SIG_IGN, None):+ if callable(original_handler):+ original_handler(signum, frame)+ elif shutdown:+ raise SystemExit(0)++ signal.signal(sig, handler)+ except ValueError as e:+ logger.warning(+ f"Cannot register {sig.name} handler: not running in main thread",+ exc_info=e,+ )+ except OSError as e:+ logger.warning(f"Cannot register {sig.name} handler: {e}", exc_info=e)++ def _shutdown(self) -> None:+ """Flush and shutdown the telemetry provider on process exit.++ Uses a short timeout to avoid blocking process shutdown.+ """+ if not self.ready:+ return++ try:+ self.provider.force_flush(timeout_millis=5000)+ self.provider.shutdown()+ self.ready = False+ except Exception as e:+ logger.debug(f"Telemetry shutdown failed: {e}")+def _safe_telemetry_operation(self, operation: Callable[[], Span | None]) -> Span | None:diff --git a/lib/crewai/tests/events/types/test_system_events.py b/lib/crewai/tests/events/types/test_system_events.pynew file mode 100644index 000000000..2109d428b--- /dev/null+++ b/lib/crewai/tests/events/types/test_system_events.py@@ -0,0 +1,197 @@+"""Tests for system signal events."""++import signal+from unittest.mock import MagicMock, patch++import pytest++from crewai.events.event_bus import crewai_event_bus+from crewai.events.types.system_events import (+ SIGNAL_EVENT_TYPES,+ SignalEvent,+ SignalType,+ SigContEvent,+ SigHupEvent,+ SigIntEvent,+ SigTermEvent,+ SigTStpEvent,+ on_signal,+ signal_event_adapter,+)+++class TestSignalType:+ """Tests for SignalType enum."""++ def test_signal_type_values(self) -> None:+ """Verify SignalType maps to correct signal numbers."""+ assert SignalType.SIGTERM == signal.SIGTERM+ assert SignalType.SIGINT == signal.SIGINT+ assert SignalType.SIGHUP == signal.SIGHUP+ assert SignalType.SIGTSTP == signal.SIGTSTP+ assert SignalType.SIGCONT == signal.SIGCONT+++class TestSignalEvents:+ """Tests for individual signal event classes."""++ def test_sigterm_event_defaults(self) -> None:+ """Test SigTermEvent has correct defaults."""+ event = SigTermEvent()+ assert event.type == "SIGTERM"+ assert event.signal_number == SignalType.SIGTERM+ assert event.reason is None++ def test_sigterm_event_with_reason(self) -> None:+ """Test SigTermEvent can be created with a reason."""+ event = SigTermEvent(reason="graceful shutdown")+ assert event.reason == "graceful shutdown"++ def test_sigint_event_defaults(self) -> None:+ """Test SigIntEvent has correct defaults."""+ event = SigIntEvent()+ assert event.type == "SIGINT"+ assert event.signal_number == SignalType.SIGINT++ def test_sighup_event_defaults(self) -> None:+ """Test SigHupEvent has correct defaults."""+ event = SigHupEvent()+ assert event.type == "SIGHUP"+ assert event.signal_number == SignalType.SIGHUP++ def test_sigtstp_event_defaults(self) -> None:+ """Test SigTStpEvent has correct defaults."""+ event = SigTStpEvent()+ assert event.type == "SIGTSTP"+ assert event.signal_number == SignalType.SIGTSTP++ def test_sigcont_event_defaults(self) -> None:+ """Test SigContEvent has correct defaults."""+ event = SigContEvent()+ assert event.type == "SIGCONT"+ assert event.signal_number == SignalType.SIGCONT+++class TestSignalEventAdapter:+ """Tests for the Pydantic discriminated union adapter."""++ def test_adapter_parses_sigterm(self) -> None:+ """Test adapter correctly parses SIGTERM event."""+ data = {"type": "SIGTERM", "reason": "test"}+ event = signal_event_adapter.validate_python(data)+ assert isinstance(event, SigTermEvent)+ assert event.reason == "test"++ def test_adapter_parses_sigint(self) -> None:+ """Test adapter correctly parses SIGINT event."""+ data = {"type": "SIGINT"}+ event = signal_event_adapter.validate_python(data)+ assert isinstance(event, SigIntEvent)++ def test_adapter_parses_sighup(self) -> None:+ """Test adapter correctly parses SIGHUP event."""+ data = {"type": "SIGHUP"}+ event = signal_event_adapter.validate_python(data)+ assert isinstance(event, SigHupEvent)++ def test_adapter_parses_sigtstp(self) -> None:+ """Test adapter correctly parses SIGTSTP event."""+ data = {"type": "SIGTSTP"}+ event = signal_event_adapter.validate_python(data)+ assert isinstance(event, SigTStpEvent)++ def test_adapter_parses_sigcont(self) -> None:+ """Test adapter correctly parses SIGCONT event."""+ data = {"type": "SIGCONT"}+ event = signal_event_adapter.validate_python(data)+ assert isinstance(event, SigContEvent)++ def test_adapter_rejects_invalid_type(self) -> None:+ """Test adapter rejects unknown signal type."""+ data = {"type": "SIGKILL"}+ with pytest.raises(Exception):+ signal_event_adapter.validate_python(data)+++class TestSignalEventTypes:+ """Tests for SIGNAL_EVENT_TYPES constant."""++ def test_contains_all_event_types(self) -> None:+ """Verify SIGNAL_EVENT_TYPES contains all signal events."""+ assert SigTermEvent in SIGNAL_EVENT_TYPES+ assert SigIntEvent in SIGNAL_EVENT_TYPES+ assert SigHupEvent in SIGNAL_EVENT_TYPES+ assert SigTStpEvent in SIGNAL_EVENT_TYPES+ assert SigContEvent in SIGNAL_EVENT_TYPES+ assert len(SIGNAL_EVENT_TYPES) == 5+++class TestOnSignalDecorator:+ """Tests for the @on_signal decorator."""++ def test_decorator_registers_for_all_signals(self) -> None:+ """Test that @on_signal registers handler for all signal event types."""+ import threading++ received_types: set[str] = set()+ condition = threading.Condition()+ expected_count = len(SIGNAL_EVENT_TYPES)++ @on_signal+ def test_handler(source: object, event: SignalEvent) -> None:+ with condition:+ received_types.add(event.type)+ condition.notify_all()++ for event_class in SIGNAL_EVENT_TYPES:+ crewai_event_bus.emit(self, event_class())++ with condition:+ condition.wait_for(lambda: len(received_types) >= expected_count, timeout=5.0)++ assert "SIGTERM" in received_types+ assert "SIGINT" in received_types+ assert "SIGHUP" in received_types+ assert "SIGTSTP" in received_types+ assert "SIGCONT" in received_types++ def test_decorator_returns_original_function(self) -> None:+ """Test that @on_signal returns the original function."""++ def my_handler(source: object, event: SignalEvent) -> None:+ pass++ decorated = on_signal(my_handler)+ assert decorated is my_handler++ def test_decorator_preserves_function_name(self) -> None:+ """Test that @on_signal preserves function metadata."""++ @on_signal+ def my_named_handler(source: object, event: SignalEvent) -> None:+ """My docstring."""+ pass++ assert my_named_handler.__name__ == "my_named_handler"+ assert my_named_handler.__doc__ == "My docstring."+++class TestSignalEventSerialization:+ """Tests for event serialization."""++ def test_sigterm_to_dict(self) -> None:+ """Test SigTermEvent serializes correctly."""+ event = SigTermEvent(reason="test reason")+ data = event.model_dump()+ assert data["type"] == "SIGTERM"+ assert data["signal_number"] == signal.SIGTERM+ assert data["reason"] == "test reason"++ def test_roundtrip_serialization(self) -> None:+ """Test events can be serialized and deserialized."""+ original = SigTermEvent(reason="roundtrip test")+ serialized = original.model_dump()+ restored = signal_event_adapter.validate_python(serialized)+ assert isinstance(restored, SigTermEvent)+ assert restored.reason == original.reason+ assert restored.type == original.type\ No newline at end of file