fix: handling of weakrefs and non copieable objects

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

.coveragerc

@@ -0,0 +1,9 @@
+[run]
+omit =
+    *__init__.py
+    */templates/*
+
+[report]
+omit =
+    *__init__.py
+    */templates/*

cpex/framework/__init__.py

@@ -19,7 +19,7 @@
 # First-Party
 from cpex.framework.base import Plugin
 from cpex.framework.decorator import hook
-from cpex.framework.errors import PluginError, PluginViolationError
+from cpex.framework.errors import PluginError, PluginFrameworkError, PluginViolationError
 from cpex.framework.external.mcp.server import ExternalPluginServer
 from cpex.framework.hooks.agents import (
     AgentHookType,
@@ -163,6 +163,7 @@ def get_plugin_manager(
     "PluginContextTable",
     "PluginError",
     "PluginErrorModel",
+    "PluginFrameworkError",
     "PluginLoader",
     "PluginManager",
     "PluginMode",

cpex/framework/errors.py

@@ -13,6 +13,32 @@
 from cpex.framework.models import PluginErrorModel, PluginViolation
 
 
+class PluginFrameworkError(Exception):
+    """An error originating from the plugin framework itself (not from a plugin).
+
+    Raised when an internal framework operation fails — for example, when
+    payload isolation cannot deep-copy a value.
+
+    Attributes:
+        message (str): Description of the framework error.
+    """
+
+    def __init__(self, message: str):
+        """Initialize a plugin framework error.
+
+        Args:
+            message: Description of what went wrong.
+
+        Examples:
+            >>> from cpex.framework.errors import PluginFrameworkError
+            >>> err = PluginFrameworkError("cannot isolate payload")
+            >>> str(err)
+            'cannot isolate payload'
+        """
+        self.message = message
+        super().__init__(self.message)
+
+
 class PluginViolationError(Exception):
     """A plugin violation error.
 

cpex/framework/manager.py

@@ -29,7 +29,6 @@
 
 # Standard
 import asyncio
-import copy
 import logging
 import threading
 from typing import Any, Literal, Optional, Union
@@ -43,7 +42,7 @@
 from cpex.framework.hooks.policies import DefaultHookPolicy, HookPayloadPolicy, apply_policy
 from cpex.framework.loader.config import ConfigLoader
 from cpex.framework.loader.plugin import PluginLoader
-from cpex.framework.memory import copyonwrite, wrap_payload_for_isolation
+from cpex.framework.memory import _safe_deepcopy, copyonwrite, wrap_payload_for_isolation
 from cpex.framework.models import (
     Config,
     GlobalContext,
@@ -496,7 +495,7 @@ def _isolate_payload(
             return effective_payload
         if isinstance(effective_payload, BaseModel):
             return wrap_payload_for_isolation(effective_payload)
-        return copy.deepcopy(effective_payload)
+        return _safe_deepcopy(effective_payload)
 
     def _build_halt_result(
         self,
@@ -558,7 +557,7 @@ def _fire_and_forget_tasks(
                 # Already scheduled — skip to avoid double-scheduling
                 continue
             task_input = (
-                wrap_payload_for_isolation(payload) if isinstance(payload, BaseModel) else copy.deepcopy(payload)
+                wrap_payload_for_isolation(payload) if isinstance(payload, BaseModel) else _safe_deepcopy(payload)
             )
             tmp_gc = GlobalContext(
                 request_id=global_context.request_id,

cpex/framework/memory.py

@@ -12,12 +12,18 @@
 
 # Standard
 import copy
+import logging
+import weakref
 from typing import Any, Iterator, Optional, TypeVar
 
 # Third-Party
 from pydantic import BaseModel, RootModel
 
+# First-Party
+from cpex.framework.errors import PluginFrameworkError
+
 T = TypeVar("T")
+logger = logging.getLogger(__name__)
 
 
 class CopyOnWriteDict(dict):
@@ -517,6 +523,21 @@ def copyonwrite(o: T) -> T:
 _PRIMITIVE_TYPES = (str, int, float, bool, bytes, type(None))
 
 
+def _safe_deepcopy(value: Any) -> Any:
+    """Deep-copy *value* with diagnostic context on failure.
+
+    Wraps :func:`copy.deepcopy` so that failures surface the concrete type and
+    a truncated repr, making it much easier to identify which field or object
+    caused the issue (e.g. file handles, C extensions, locks).
+    """
+    try:
+        return copy.deepcopy(value)
+    except Exception as e:
+        raise PluginFrameworkError(
+            f"Cannot deep-copy value of type {type(value).__qualname__} (repr={repr(value)!s:.200}): {e}"
+        ) from e
+
+
 def _wrap_value(value: Any) -> Any:
     """Wrap a single value with the appropriate CoW wrapper.
 
@@ -536,16 +557,20 @@ def _wrap_value(value: Any) -> Any:
         elif isinstance(root, list):
             wrapped_root = CopyOnWriteList(root)
         else:
-            wrapped_root = copy.deepcopy(root)
+            wrapped_root = _safe_deepcopy(root)
         return value.model_construct(root=wrapped_root)
     if isinstance(value, BaseModel):
         return wrap_payload_for_isolation(value)
     if isinstance(value, dict):
         return CopyOnWriteDict(value)
     if isinstance(value, list):
         return CopyOnWriteList(value)
+    # Weak-reference proxies wrap live objects that must not be
+    # copied — pass them through as-is so plugins see the same proxy.
+    if isinstance(value, (weakref.ProxyType, weakref.CallableProxyType)):
+        return value
     # Other mutable types — fallback to deep copy
-    return copy.deepcopy(value)
+    return _safe_deepcopy(value)
 
 
 def wrap_payload_for_isolation(payload: BaseModel) -> BaseModel:
@@ -570,7 +595,7 @@ def wrap_payload_for_isolation(payload: BaseModel) -> BaseModel:
         elif isinstance(root, list):
             wrapped_root = CopyOnWriteList(root)
         else:
-            wrapped_root = copy.deepcopy(root)
+            wrapped_root = _safe_deepcopy(root)
         return payload.model_construct(root=wrapped_root)
 
     updates = {}

tests/pytest.ini

@@ -12,6 +12,3 @@ pythonpath = .
 filterwarnings =
     ignore::DeprecationWarning:pydantic.*
     ignore::DeprecationWarning:pythonjsonlogger.*
-
-[coverage:run]
-omit = *__init__.py

tests/unit/cpex/framework/loader/test_plugin_loader.py

@@ -193,6 +193,7 @@ async def test_plugin_loader_shutdown_with_existing_types():
     """Test shutdown clears existing plugin types."""
     config = ConfigLoader.load_config(config="./tests/unit/cpex/fixtures/configs/valid_single_plugin.yaml")
     loader = PluginLoader()
+    loader.append_to_search_path(config.plugin_dirs)
 
     # Load a plugin to populate _plugin_types
     plugin = await loader.load_and_instantiate_plugin(config.plugins[0])
@@ -224,6 +225,9 @@ async def test_plugin_loader_registration_branch_coverage():
         config={"words": [{"search": "test", "replace": "example"}]},
     )
 
+    # Add plugin dirs to search path so importlib can resolve the kind
+    loader.append_to_search_path(["tests/unit/cpex/fixtures"])
+
     # First load - should register the plugin type (lines 85-87)
     assert config.kind not in loader._plugin_types  # Verify it's not registered yet
     plugin1 = await loader.load_and_instantiate_plugin(config)