refactor(plugins): move Plugin to dedicated module with PluginRegistry

- Move Plugin Protocol from hooks/registry.py to plugins/plugin.py
- Create PluginRegistry class for tracking plugins attached to agents
- Create dedicated src/strands/plugins/ module with proper exports
- Update top-level strands package to export Plugin from new location
- Move Plugin tests to tests/strands/plugins/
- Add PluginRegistry tests for add, get, has, and list operations
- Remove accidentally committed install.log build artifact
- Update AGENTS.md with new plugins directory structure

Author: strands-agent

AGENTS.md

@@ -126,6 +126,10 @@ strands-agents/
 │   │   ├── events.py                     # Hook event definitions
 │   │   └── registry.py                   # Hook registration
 │   │
+│   ├── plugins/                          # Plugin system
+│   │   ├── plugin.py                     # Plugin Protocol definition
+│   │   └── registry.py                   # PluginRegistry for tracking plugins
+│   │
 │   ├── handlers/                         # Event handlers
 │   │   └── callback_handler.py           # Callback handling
 │   │
@@ -171,6 +175,7 @@ strands-agents/
 │       ├── session/
 │       ├── telemetry/
 │       ├── hooks/
+│       ├── plugins/
 │       ├── handlers/
 │       ├── experimental/
 │       └── utils/

install.log

@@ -4,7 +4,7 @@
 from .agent.agent import Agent
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
-from .hooks.registry import Plugin
+from .plugins import Plugin
 from .tools.decorator import tool
 from .types.tools import ToolContext
 

src/strands/__init__.py

@@ -45,7 +45,7 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     MessageAddedEvent,
     MultiAgentInitializedEvent,
 )
-from .registry import BaseHookEvent, HookCallback, HookEvent, HookProvider, HookRegistry, Plugin
+from .registry import BaseHookEvent, HookCallback, HookEvent, HookProvider, HookRegistry
 
 __all__ = [
     "AgentInitializedEvent",
@@ -67,5 +67,4 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     "BeforeMultiAgentInvocationEvent",
     "BeforeNodeCallEvent",
     "MultiAgentInitializedEvent",
-    "Plugin",
 ]

src/strands/hooks/__init__.py

@@ -122,35 +122,6 @@ def register_hooks(self, registry: "HookRegistry", **kwargs: Any) -> None:
         ...
 
 
-@runtime_checkable
-class Plugin(Protocol):
-    """Protocol for objects that extend agent functionality.
-
-    Plugins provide a composable way to add behavior changes to agents.
-    They are initialized with an agent instance and can register hooks,
-    modify agent attributes, or perform other setup tasks.
-
-    Example:
-        ```python
-        class MyPlugin:
-            name = "my-plugin"
-
-            def init_plugin(self, agent: Agent) -> None:
-                agent.add_hook(self.on_model_call, BeforeModelCallEvent)
-        ```
-    """
-
-    name: str
-
-    def init_plugin(self, agent: "Agent") -> None | Awaitable[None]:
-        """Initialize the plugin with an agent instance.
-
-        Args:
-            agent: The agent instance to extend.
-        """
-        ...
-
-
 class HookCallback(Protocol, Generic[TEvent]):
     """Protocol for callback functions that handle hook events.
 

src/strands/hooks/registry.py

@@ -0,0 +1,32 @@
+"""Plugin system for extending agent functionality.
+
+This module provides a composable mechanism for building objects that can
+extend agent behavior through a standardized initialization pattern.
+
+Example Usage:
+    ```python
+    from strands.plugins import Plugin, PluginRegistry
+
+    class LoggingPlugin:
+        name = "logging"
+
+        def init_plugin(self, agent: Agent) -> None:
+            agent.add_hook(self.on_model_call, BeforeModelCallEvent)
+
+        def on_model_call(self, event: BeforeModelCallEvent) -> None:
+            print(f"Model called for {event.agent.name}")
+
+    # Use with registry
+    registry = PluginRegistry()
+    plugin = LoggingPlugin()
+    registry.add_plugin(plugin, agent)
+    ```
+"""
+
+from .plugin import Plugin
+from .registry import PluginRegistry
+
+__all__ = [
+    "Plugin",
+    "PluginRegistry",
+]

src/strands/plugins/__init__.py

@@ -0,0 +1,40 @@
+"""Plugin protocol for extending agent functionality.
+
+This module defines the Plugin Protocol, which provides a composable way to
+add behavior changes to agents through a standardized initialization pattern.
+"""
+
+from collections.abc import Awaitable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Protocol for objects that extend agent functionality.
+
+    Plugins provide a composable way to add behavior changes to agents.
+    They are initialized with an agent instance and can register hooks,
+    modify agent attributes, or perform other setup tasks.
+
+    Example:
+        ```python
+        class MyPlugin:
+            name = "my-plugin"
+
+            def init_plugin(self, agent: Agent) -> None:
+                agent.add_hook(self.on_model_call, BeforeModelCallEvent)
+        ```
+    """
+
+    name: str
+
+    def init_plugin(self, agent: "Agent") -> None | Awaitable[None]:
+        """Initialize the plugin with an agent instance.
+
+        Args:
+            agent: The agent instance to extend.
+        """
+        ...

src/strands/plugins/plugin.py

@@ -0,0 +1,91 @@
+"""Plugin registry for managing plugins attached to an agent.
+
+This module provides the PluginRegistry class for tracking and managing
+plugins that have been initialized with an agent instance.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from .plugin import Plugin
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class PluginRegistry:
+    """Registry for managing plugins attached to an agent.
+
+    The PluginRegistry tracks plugins that have been initialized with an agent,
+    providing methods to add, retrieve, and check for plugins by name.
+
+    Example:
+        ```python
+        registry = PluginRegistry()
+
+        class MyPlugin:
+            name = "my-plugin"
+
+            def init_plugin(self, agent: Agent) -> None:
+                pass
+
+        plugin = MyPlugin()
+        registry.add_plugin(plugin, agent)
+
+        # Check if plugin is registered
+        if registry.has_plugin("my-plugin"):
+            retrieved = registry.get_plugin("my-plugin")
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty plugin registry."""
+        self._plugins: dict[str, Plugin] = {}
+
+    def add_plugin(self, plugin: Plugin, agent: "Agent") -> None:
+        """Add and initialize a plugin with the given agent.
+
+        Args:
+            plugin: The plugin to add and initialize.
+            agent: The agent instance to initialize the plugin with.
+
+        Raises:
+            ValueError: If a plugin with the same name is already registered.
+        """
+        if plugin.name in self._plugins:
+            raise ValueError(f"plugin_name=<{plugin.name}> | plugin already registered")
+
+        logger.debug("plugin_name=<%s> | registering plugin", plugin.name)
+        self._plugins[plugin.name] = plugin
+
+    def get_plugin(self, name: str) -> Plugin | None:
+        """Get a plugin by name.
+
+        Args:
+            name: The name of the plugin to retrieve.
+
+        Returns:
+            The plugin if found, None otherwise.
+        """
+        return self._plugins.get(name)
+
+    def has_plugin(self, name: str) -> bool:
+        """Check if a plugin with the given name is registered.
+
+        Args:
+            name: The name of the plugin to check.
+
+        Returns:
+            True if the plugin is registered, False otherwise.
+        """
+        return name in self._plugins
+
+    def list_plugins(self) -> list[str]:
+        """Get a list of all registered plugin names.
+
+        Returns:
+            A list of plugin names in registration order.
+        """
+        return list(self._plugins.keys())

src/strands/plugins/registry.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from strands.hooks import AgentInitializedEvent, BeforeInvocationEvent, BeforeToolCallEvent, HookRegistry, Plugin
+from strands.hooks import AgentInitializedEvent, BeforeInvocationEvent, BeforeToolCallEvent, HookRegistry
 from strands.interrupt import Interrupt, _InterruptState
 
 
@@ -168,115 +168,3 @@ def __call__(self, event: "NonExistentType") -> None:  # noqa: F821
 
     with pytest.raises(ValueError, match="failed to get type hints for callback"):
         registry.add_callback(None, callback)
-
-
-# Plugin Protocol Tests
-
-
-def test_plugin_protocol_is_runtime_checkable():
-    """Test that Plugin Protocol is runtime checkable with isinstance."""
-
-    class MyPlugin:
-        name = "my-plugin"
-
-        def init_plugin(self, agent):
-            pass
-
-    plugin = MyPlugin()
-    assert isinstance(plugin, Plugin)
-
-
-def test_plugin_protocol_sync_implementation():
-    """Test Plugin Protocol works with synchronous init_plugin."""
-
-    class SyncPlugin:
-        name = "sync-plugin"
-
-        def init_plugin(self, agent):
-            agent.custom_attribute = "initialized by plugin"
-
-    plugin = SyncPlugin()
-    mock_agent = unittest.mock.Mock()
-
-    # Verify the plugin matches the protocol
-    assert isinstance(plugin, Plugin)
-    assert plugin.name == "sync-plugin"
-
-    # Execute init_plugin synchronously
-    plugin.init_plugin(mock_agent)
-    assert mock_agent.custom_attribute == "initialized by plugin"
-
-
-@pytest.mark.asyncio
-async def test_plugin_protocol_async_implementation():
-    """Test Plugin Protocol works with asynchronous init_plugin."""
-
-    class AsyncPlugin:
-        name = "async-plugin"
-
-        async def init_plugin(self, agent):
-            agent.custom_attribute = "initialized by async plugin"
-
-    plugin = AsyncPlugin()
-    mock_agent = unittest.mock.Mock()
-
-    # Verify the plugin matches the protocol
-    assert isinstance(plugin, Plugin)
-    assert plugin.name == "async-plugin"
-
-    # Execute init_plugin asynchronously
-    await plugin.init_plugin(mock_agent)
-    assert mock_agent.custom_attribute == "initialized by async plugin"
-
-
-def test_plugin_protocol_requires_name():
-    """Test that Plugin Protocol requires a name property."""
-
-    class PluginWithoutName:
-        def init_plugin(self, agent):
-            pass
-
-    plugin = PluginWithoutName()
-    # A class without 'name' should not pass isinstance check
-    assert not isinstance(plugin, Plugin)
-
-
-def test_plugin_protocol_requires_init_plugin_method():
-    """Test that Plugin Protocol requires an init_plugin method."""
-
-    class PluginWithoutInitPlugin:
-        name = "incomplete-plugin"
-
-    plugin = PluginWithoutInitPlugin()
-    # A class without 'init_plugin' should not pass isinstance check
-    assert not isinstance(plugin, Plugin)
-
-
-def test_plugin_protocol_with_class_attribute_name():
-    """Test Plugin Protocol works when name is a class attribute."""
-
-    class PluginWithClassAttribute:
-        name: str = "class-attr-plugin"
-
-        def init_plugin(self, agent):
-            pass
-
-    plugin = PluginWithClassAttribute()
-    assert isinstance(plugin, Plugin)
-    assert plugin.name == "class-attr-plugin"
-
-
-def test_plugin_protocol_with_property_name():
-    """Test Plugin Protocol works when name is a property."""
-
-    class PluginWithProperty:
-        @property
-        def name(self):
-            return "property-plugin"
-
-        def init_plugin(self, agent):
-            pass
-
-    plugin = PluginWithProperty()
-    assert isinstance(plugin, Plugin)
-    assert plugin.name == "property-plugin"

tests/strands/hooks/test_registry.py

@@ -0,0 +1 @@
+"""Tests for the plugins module."""