chore: import upstream snapshot with attribution

tests/unit_tests/plugin/__init__.py

@@ -0,0 +1 @@
+# Plugin connector unit tests

tests/unit_tests/plugin/test_connector_methods.py

@@ -0,0 +1,616 @@
+"""Unit tests for plugin connector methods.
+
+Tests cover:
+- list_plugins() with filtering and sorting
+- list_knowledge_engines() and list_parsers()
+- RAG methods (ingest, retrieve, schema)
+- Disabled plugin early returns
+"""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+from importlib import import_module
+
+from tests.factories import text_query
+
+
+def get_connector_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.plugin.connector')
+
+
+def create_mock_app():
+    """Create mock Application for testing."""
+    mock_app = Mock()
+    mock_app.logger = Mock()
+    mock_app.instance_config = Mock()
+    mock_app.instance_config.data = {'plugin': {'enable': True}}
+    mock_app.persistence_mgr = AsyncMock()
+    mock_app.persistence_mgr.execute_async = AsyncMock()
+    return mock_app
+
+
+def create_mock_connector():
+    """Create mock PluginRuntimeConnector instance for testing."""
+    connector = get_connector_module()
+
+    async def mock_disconnect_callback(conn):
+        pass
+
+    return connector.PluginRuntimeConnector(create_mock_app(), mock_disconnect_callback)
+
+
+class TestListPlugins:
+    """Tests for list_plugins method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_when_plugin_disabled(self):
+        """Test returns empty list when plugin system disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.list_plugins()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_list_plugins(self):
+        """Test that handler.list_plugins is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.list_plugins = AsyncMock(
+            return_value=[{'manifest': {'manifest': {'metadata': {'author': 'test', 'name': 'plugin'}}}}]
+        )
+
+        result = await connector.list_plugins()
+
+        connector.handler.list_plugins.assert_called_once()
+        assert result == [{'manifest': {'manifest': {'metadata': {'author': 'test', 'name': 'plugin'}}}}]
+
+    @pytest.mark.asyncio
+    async def test_filters_by_component_kinds(self):
+        """Test that plugins are filtered by component kinds."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.list_plugins = AsyncMock(
+            return_value=[
+                {
+                    'manifest': {'manifest': {'metadata': {'author': 'a', 'name': 'p1'}}},
+                    'components': [{'manifest': {'manifest': {'kind': 'Command'}}}],
+                    'debug': False,
+                },
+                {
+                    'manifest': {'manifest': {'metadata': {'author': 'b', 'name': 'p2'}}},
+                    'components': [{'manifest': {'manifest': {'kind': 'Tool'}}}],
+                    'debug': False,
+                },
+            ]
+        )
+
+        result = await connector.list_plugins(component_kinds=['Command'])
+
+        assert len(result) == 1
+        assert result[0]['manifest']['manifest']['metadata']['name'] == 'p1'
+
+    @pytest.mark.asyncio
+    async def test_sorts_debug_plugins_first(self):
+        """Test that debug plugins are sorted first."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.list_plugins = AsyncMock(
+            return_value=[
+                {
+                    'manifest': {'manifest': {'metadata': {'author': 'a', 'name': 'normal'}}},
+                    'components': [],
+                    'debug': False,
+                },
+                {
+                    'manifest': {'manifest': {'metadata': {'author': 'b', 'name': 'debug'}}},
+                    'components': [],
+                    'debug': True,
+                },
+            ]
+        )
+        connector.ap.persistence_mgr.execute_async = AsyncMock(return_value=Mock(__iter__=lambda self: iter([])))
+
+        result = await connector.list_plugins()
+
+        # Debug plugin should be first
+        assert result[0]['debug'] is True
+
+
+class TestPluginDiagnostics:
+    @pytest.mark.asyncio
+    async def test_emit_event_preserves_response_sources(self):
+        connector = create_mock_connector()
+        query = text_query('hello')
+        event = query.message_event
+        object.__setattr__(event, 'query', query)
+        connector_module = get_connector_module()
+        original_from_event = connector_module.context.EventContext.from_event
+        original_model_validate = connector_module.context.EventContext.model_validate
+        response_sources = [
+            {
+                'kind': 'reply_message_chain',
+                'plugin': {'author': 'tester', 'name': 'demo'},
+            }
+        ]
+
+        async def emit_event_response(event_context, include_plugins=None):
+            return {
+                'event_context': event_context,
+                'emitted_plugins': [],
+                'response_sources': response_sources,
+            }
+
+        connector.handler = AsyncMock()
+        connector.handler.emit_event = AsyncMock(side_effect=emit_event_response)
+
+        fake_event_ctx = Mock()
+        event_dump = event.model_dump()
+        event_dump['event_name'] = 'FriendMessage'
+        fake_event_ctx.model_dump.return_value = {
+            'query_id': query.query_id,
+            'eid': 0,
+            'event_name': 'FriendMessage',
+            'event': event_dump,
+            'is_prevent_default': False,
+            'is_prevent_postorder': False,
+        }
+        connector_module.context.EventContext.from_event = Mock(return_value=fake_event_ctx)
+        parsed_event_ctx = Mock()
+        connector_module.context.EventContext.model_validate = Mock(return_value=parsed_event_ctx)
+        try:
+            event_ctx = await connector.emit_event(event)
+        finally:
+            connector_module.context.EventContext.from_event = original_from_event
+            connector_module.context.EventContext.model_validate = original_model_validate
+
+        assert event_ctx is parsed_event_ctx
+        assert event_ctx._response_sources == response_sources
+
+    @pytest.mark.asyncio
+    async def test_emit_event_leaves_response_sources_absent_for_old_runtime(self):
+        connector = create_mock_connector()
+        query = text_query('hello')
+        event = query.message_event
+        object.__setattr__(event, 'query', query)
+        connector_module = get_connector_module()
+        original_from_event = connector_module.context.EventContext.from_event
+        original_model_validate = connector_module.context.EventContext.model_validate
+
+        async def emit_event_response(event_context, include_plugins=None):
+            return {
+                'event_context': event_context,
+                'emitted_plugins': [
+                    {'manifest': {'metadata': {'author': 'tester', 'name': 'demo'}}},
+                ],
+            }
+
+        connector.handler = AsyncMock()
+        connector.handler.emit_event = AsyncMock(side_effect=emit_event_response)
+
+        fake_event_ctx = Mock()
+        event_dump = event.model_dump()
+        event_dump['event_name'] = 'FriendMessage'
+        fake_event_ctx.model_dump.return_value = {
+            'query_id': query.query_id,
+            'eid': 0,
+            'event_name': 'FriendMessage',
+            'event': event_dump,
+            'is_prevent_default': False,
+            'is_prevent_postorder': False,
+        }
+        connector_module.context.EventContext.from_event = Mock(return_value=fake_event_ctx)
+        parsed_event_ctx = Mock()
+        connector_module.context.EventContext.model_validate = Mock(return_value=parsed_event_ctx)
+        try:
+            event_ctx = await connector.emit_event(event)
+        finally:
+            connector_module.context.EventContext.from_event = original_from_event
+            connector_module.context.EventContext.model_validate = original_model_validate
+
+        assert '_response_sources' not in vars(event_ctx)
+        assert event_ctx._emitted_plugins == [
+            {'manifest': {'metadata': {'author': 'tester', 'name': 'demo'}}},
+        ]
+
+    @pytest.mark.asyncio
+    async def test_notify_plugin_diagnostic_skips_when_disabled(self):
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+        connector.handler = AsyncMock()
+
+        await connector.notify_plugin_diagnostic({'code': 'response_delivery_failed'})
+
+        connector.handler.notify_plugin_diagnostic.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_notify_plugin_diagnostic_is_best_effort(self):
+        connector = create_mock_connector()
+        connector.handler = AsyncMock()
+        connector.handler.notify_plugin_diagnostic = AsyncMock(side_effect=RuntimeError('action not found'))
+
+        await connector.notify_plugin_diagnostic({'code': 'response_delivery_failed'})
+
+        connector.handler.notify_plugin_diagnostic.assert_awaited_once()
+        connector.ap.logger.debug.assert_called_once()
+
+
+class TestListKnowledgeEngines:
+    """Tests for list_knowledge_engines method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_when_plugin_disabled(self):
+        """Test returns empty list when plugin system disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.list_knowledge_engines()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_list_knowledge_engines(self):
+        """Test that handler method is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine'}]
+        )
+
+        result = await connector.list_knowledge_engines()
+
+        connector.handler.list_knowledge_engines.assert_called_once()
+        assert result == [{'plugin_id': 'author/engine', 'name': 'Engine'}]
+
+
+class TestListParsers:
+    """Tests for list_parsers method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_when_plugin_disabled(self):
+        """Test returns empty list when plugin system disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.list_parsers()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_list_parsers(self):
+        """Test that handler method is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.list_parsers = AsyncMock(
+            return_value=[{'plugin_id': 'author/parser', 'supported_mime_types': ['text/plain']}]
+        )
+
+        result = await connector.list_parsers()
+
+        connector.handler.list_parsers.assert_called_once()
+        assert result == [{'plugin_id': 'author/parser', 'supported_mime_types': ['text/plain']}]
+
+
+class TestCallParser:
+    """Tests for call_parser method."""
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_parse_document(self):
+        """Test that handler.parse_document is called with correct args."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.parse_document = AsyncMock(return_value={'content': 'parsed'})
+
+        result = await connector.call_parser(
+            'author/parser',
+            {'mime_type': 'text/plain', 'filename': 'test.txt'},
+            b'file content',
+        )
+
+        connector.handler.parse_document.assert_called_once_with(
+            'author',
+            'parser',
+            {'mime_type': 'text/plain', 'filename': 'test.txt'},
+            b'file content',
+        )
+        assert result['content'] == 'parsed'
+
+
+class TestRAGMethods:
+    """Tests for RAG-related methods."""
+
+    @pytest.mark.asyncio
+    async def test_call_rag_ingest(self):
+        """Test call_rag_ingest calls handler with parsed plugin ID."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.rag_ingest_document = AsyncMock(return_value={'status': 'success'})
+
+        result = await connector.call_rag_ingest('author/engine', {'file': 'test.pdf'})
+
+        connector.handler.rag_ingest_document.assert_called_once_with('author', 'engine', {'file': 'test.pdf'})
+        assert result['status'] == 'success'
+
+    @pytest.mark.asyncio
+    async def test_call_rag_retrieve(self):
+        """Test call_rag_retrieve calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.retrieve_knowledge = AsyncMock(
+            return_value={
+                'results': [
+                    {'id': 'doc1', 'content': [{'type': 'text', 'text': 'test'}], 'metadata': {}, 'distance': 0.1}
+                ]
+            }
+        )
+
+        result = await connector.call_rag_retrieve('author/engine', {'query': 'test'})
+
+        connector.handler.retrieve_knowledge.assert_called_once_with('author', 'engine', '', {'query': 'test'})
+        assert result == {
+            'results': [
+                {
+                    'id': 'doc1',
+                    'content': [{'type': 'text', 'text': 'test'}],
+                    'metadata': {},
+                    'distance': 0.1,
+                }
+            ]
+        }
+
+    @pytest.mark.asyncio
+    async def test_get_rag_creation_schema(self):
+        """Test get_rag_creation_schema calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.get_rag_creation_schema = AsyncMock(return_value={'properties': {'name': {'type': 'string'}}})
+
+        result = await connector.get_rag_creation_schema('author/engine')
+
+        connector.handler.get_rag_creation_schema.assert_called_once_with('author', 'engine')
+        assert result == {'properties': {'name': {'type': 'string'}}}
+
+    @pytest.mark.asyncio
+    async def test_get_rag_retrieval_schema(self):
+        """Test get_rag_retrieval_schema calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.get_rag_retrieval_schema = AsyncMock(
+            return_value={'properties': {'top_k': {'type': 'integer'}}}
+        )
+
+        result = await connector.get_rag_retrieval_schema('author/engine')
+
+        connector.handler.get_rag_retrieval_schema.assert_called_once_with('author', 'engine')
+        assert result == {'properties': {'top_k': {'type': 'integer'}}}
+
+    @pytest.mark.asyncio
+    async def test_rag_on_kb_create(self):
+        """Test rag_on_kb_create calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.rag_on_kb_create = AsyncMock(return_value={'status': 'ok'})
+
+        await connector.rag_on_kb_create('author/engine', 'kb-uuid', {'model': 'test'})
+
+        connector.handler.rag_on_kb_create.assert_called_once_with('author', 'engine', 'kb-uuid', {'model': 'test'})
+
+    @pytest.mark.asyncio
+    async def test_rag_on_kb_delete(self):
+        """Test rag_on_kb_delete calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.rag_on_kb_delete = AsyncMock(return_value={'status': 'ok'})
+
+        await connector.rag_on_kb_delete('author/engine', 'kb-uuid')
+
+        connector.handler.rag_on_kb_delete.assert_called_once_with('author', 'engine', 'kb-uuid')
+
+    @pytest.mark.asyncio
+    async def test_call_rag_delete_document(self):
+        """Test call_rag_delete_document calls handler."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.rag_delete_document = AsyncMock(return_value=True)
+
+        result = await connector.call_rag_delete_document('author/engine', 'doc-uuid', 'kb-uuid')
+
+        connector.handler.rag_delete_document.assert_called_once_with('author', 'engine', 'doc-uuid', 'kb-uuid')
+        assert result is True
+
+
+class TestRetrieveKnowledge:
+    """Tests for retrieve_knowledge method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_results_when_plugin_disabled(self):
+        """Test returns empty when plugin disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.retrieve_knowledge('author', 'engine', 'retriever', {})
+
+        assert result == {'results': []}
+
+
+class TestDisabledPluginEarlyReturns:
+    """Tests for early returns when plugin system is disabled."""
+
+    @pytest.mark.asyncio
+    async def test_list_tools_returns_empty(self):
+        """Test list_tools returns empty when disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.list_tools()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_list_commands_returns_empty(self):
+        """Test list_commands returns empty when disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.list_commands()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_get_debug_info_returns_empty(self):
+        """Test get_debug_info returns empty dict when disabled."""
+        connector_module = get_connector_module()
+
+        async def mock_disconnect(conn):
+            pass
+
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'plugin': {'enable': False}}
+
+        connector = connector_module.PluginRuntimeConnector(mock_app, mock_disconnect)
+
+        result = await connector.get_debug_info()
+
+        assert result == {}
+
+
+class TestGetPluginInfo:
+    """Tests for get_plugin_info method."""
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_get_plugin_info(self):
+        """Test that handler.get_plugin_info is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.get_plugin_info = AsyncMock(return_value={'manifest': {'metadata': {'name': 'plugin'}}})
+
+        result = await connector.get_plugin_info('author', 'plugin')
+
+        connector.handler.get_plugin_info.assert_called_once_with('author', 'plugin')
+        assert result == {'manifest': {'metadata': {'name': 'plugin'}}}
+
+
+class TestSetPluginConfig:
+    """Tests for set_plugin_config method."""
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_set_plugin_config(self):
+        """Test that handler.set_plugin_config is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.set_plugin_config = AsyncMock(return_value={'status': 'ok'})
+
+        await connector.set_plugin_config('author', 'plugin', {'setting': 'value'})
+
+        connector.handler.set_plugin_config.assert_called_once_with('author', 'plugin', {'setting': 'value'})
+
+
+class TestPingPluginRuntime:
+    """Tests for ping_plugin_runtime method."""
+
+    @pytest.mark.asyncio
+    async def test_raises_when_handler_not_set(self):
+        """Test that exception is raised when handler not initialized."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        # handler is not set
+        with pytest.raises(Exception, match='Plugin runtime is not connected') as exc_info:
+            await connector.ping_plugin_runtime()
+
+        assert 'not connected' in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_calls_handler_ping(self):
+        """Test that handler.ping is called."""
+        get_connector_module()
+        connector = create_mock_connector()
+
+        connector.handler = AsyncMock()
+        connector.handler.ping = AsyncMock(return_value={'status': 'ok'})
+
+        await connector.ping_plugin_runtime()
+
+        connector.handler.ping.assert_called_once()

tests/unit_tests/plugin/test_connector_ping.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from langbot.pkg.plugin.connector import PluginRuntimeConnector, PluginRuntimeNotConnectedError
+
+
+def make_connector() -> PluginRuntimeConnector:
+    app = SimpleNamespace(instance_config=SimpleNamespace(data={'plugin': {'enable': True}}))
+    return PluginRuntimeConnector(app, AsyncMock())
+
+
+@pytest.mark.asyncio
+async def test_ping_plugin_runtime_raises_specific_error_when_not_connected():
+    connector = make_connector()
+
+    with pytest.raises(PluginRuntimeNotConnectedError, match='Plugin runtime is not connected'):
+        await connector.ping_plugin_runtime()
+
+
+@pytest.mark.asyncio
+async def test_ping_plugin_runtime_delegates_to_connected_handler():
+    connector = make_connector()
+    connector.handler = SimpleNamespace(ping=AsyncMock(return_value='pong'))
+
+    result = await connector.ping_plugin_runtime()
+
+    assert result == 'pong'
+    connector.handler.ping.assert_awaited_once()

tests/unit_tests/plugin/test_connector_pure.py

@@ -0,0 +1,143 @@
+"""Tests for PluginRuntimeConnector pure logic methods.
+
+Tests methods that don't require real plugin runtime processes:
+- _inspect_plugin_package: identity and deps extraction from zip files
+- _parse_plugin_id: plugin ID string parsing
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+
+class TestExtractDepsMetadata:
+    """Tests for dependency metadata extraction from plugin packages."""
+
+    def _create_connector(self):
+        """Create a connector instance for testing."""
+        from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+        mock_app = MagicMock()
+        mock_app.instance_config.data.get.return_value = {'enable': True}
+        mock_app.logger = MagicMock()
+
+        connector = PluginRuntimeConnector(mock_app, MagicMock())
+        return connector
+
+    def test_extract_deps_with_requirements_txt(self):
+        """Extract dependency count from requirements.txt in plugin zip."""
+        connector = self._create_connector()
+
+        # Create a mock zip file with requirements.txt
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, 'w') as zf:
+            zf.writestr('requirements.txt', 'requests>=2.0\nflask\n# comment\n\nnumpy')
+
+        zip_bytes = zip_buffer.getvalue()
+
+        task_context = SimpleNamespace(metadata={})
+        connector._inspect_plugin_package(zip_bytes, task_context)
+
+        assert task_context.metadata['deps_total'] == 3  # requests>=2.0, flask, numpy
+        # deps_list contains full requirement lines including version specifiers
+        assert 'requests>=2.0' in task_context.metadata['deps_list']
+        assert 'flask' in task_context.metadata['deps_list']
+        assert 'numpy' in task_context.metadata['deps_list']
+
+    def test_extract_deps_empty_requirements(self):
+        """Handle empty requirements.txt."""
+        connector = self._create_connector()
+
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, 'w') as zf:
+            zf.writestr('requirements.txt', '# only comments\n\n')
+
+        zip_bytes = zip_buffer.getvalue()
+
+        task_context = SimpleNamespace(metadata={})
+        connector._inspect_plugin_package(zip_bytes, task_context)
+
+        assert task_context.metadata['deps_total'] == 0
+        assert task_context.metadata['deps_list'] == []
+
+    def test_extract_deps_no_requirements_txt(self):
+        """Handle zip without requirements.txt."""
+        connector = self._create_connector()
+
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, 'w') as zf:
+            zf.writestr('plugin.py', 'print("hello")')
+
+        zip_bytes = zip_buffer.getvalue()
+
+        task_context = SimpleNamespace(metadata={})
+        connector._inspect_plugin_package(zip_bytes, task_context)
+
+        # No requirements.txt found, metadata unchanged
+        assert 'deps_total' not in task_context.metadata
+
+    def test_extract_deps_none_task_context(self):
+        """Handle None task_context gracefully."""
+        connector = self._create_connector()
+
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, 'w') as zf:
+            zf.writestr('requirements.txt', 'requests')
+
+        zip_bytes = zip_buffer.getvalue()
+
+        # Should return early without error
+        connector._inspect_plugin_package(zip_bytes, None)
+
+    def test_extract_deps_invalid_zip(self):
+        """Handle invalid zip file gracefully."""
+        connector = self._create_connector()
+
+        # Not a valid zip
+        invalid_bytes = b'not a zip file'
+
+        task_context = SimpleNamespace(metadata={})
+        connector._inspect_plugin_package(invalid_bytes, task_context)
+
+        # Should catch exception and pass silently
+        assert 'deps_total' not in task_context.metadata
+
+    def test_extract_deps_nested_requirements(self):
+        """Handle requirements.txt in nested directory."""
+        connector = self._create_connector()
+
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, 'w') as zf:
+            zf.writestr('subdir/requirements.txt', 'pytest\nblack')
+
+        zip_bytes = zip_buffer.getvalue()
+
+        task_context = SimpleNamespace(metadata={})
+        connector._inspect_plugin_package(zip_bytes, task_context)
+
+        # Should find requirements.txt in subdirectory
+        assert task_context.metadata['deps_total'] == 2
+
+
+class TestParsePluginId:
+    """Tests for _parse_plugin_id static method."""
+
+    def test_parse_valid_plugin_id(self):
+        """Parse valid plugin ID format 'author/name'."""
+        from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+        author, name = PluginRuntimeConnector._parse_plugin_id('myauthor/myplugin')
+        assert author == 'myauthor'
+        assert name == 'myplugin'
+
+    def test_parse_plugin_id_empty(self):
+        """Empty plugin ID is invalid."""
+        from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+        with pytest.raises(ValueError):
+            PluginRuntimeConnector._parse_plugin_id('')

tests/unit_tests/plugin/test_connector_static.py

@@ -0,0 +1,55 @@
+"""Unit tests for plugin connector static methods.
+
+Tests cover:
+- _parse_plugin_id() parsing and validation
+"""
+
+from __future__ import annotations
+
+import pytest
+from importlib import import_module
+
+
+def get_connector_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.plugin.connector')
+
+
+class TestParsePluginId:
+    """Tests for _parse_plugin_id static method."""
+
+    def test_valid_plugin_id_simple(self):
+        """Test parsing valid plugin ID with simple format."""
+        connector = get_connector_module()
+        author, name = connector.PluginRuntimeConnector._parse_plugin_id('langbot/rag-engine')
+        assert author == 'langbot'
+        assert name == 'rag-engine'
+
+    def test_invalid_plugin_id_no_slash(self):
+        """Test that ValueError is raised when no slash present."""
+        connector = get_connector_module()
+        with pytest.raises(ValueError) as exc_info:
+            connector.PluginRuntimeConnector._parse_plugin_id('invalid-plugin-id')
+        assert 'Invalid plugin_id format' in str(exc_info.value)
+        assert 'invalid-plugin-id' in str(exc_info.value)
+
+    def test_invalid_plugin_id_empty_string(self):
+        """Test that ValueError is raised for empty string."""
+        connector = get_connector_module()
+        with pytest.raises(ValueError) as exc_info:
+            connector.PluginRuntimeConnector._parse_plugin_id('')
+        assert 'Invalid plugin_id format' in str(exc_info.value)
+
+    def test_valid_plugin_id_single_character_parts(self):
+        """Test parsing plugin ID with single character author and name."""
+        connector = get_connector_module()
+        author, name = connector.PluginRuntimeConnector._parse_plugin_id('a/b')
+        assert author == 'a'
+        assert name == 'b'
+
+    def test_valid_plugin_id_with_hyphens_and_underscores(self):
+        """Test parsing plugin ID with hyphens and underscores."""
+        connector = get_connector_module()
+        author, name = connector.PluginRuntimeConnector._parse_plugin_id('lang-bot/my_rag_engine')
+        assert author == 'lang-bot'
+        assert name == 'my_rag_engine'

tests/unit_tests/plugin/test_extract_deps.py

@@ -0,0 +1,211 @@
+"""Unit tests for plugin connector _inspect_plugin_package method.
+
+Tests cover:
+- Extracting requirements.txt from ZIP
+- Parsing dependency lines
+- Handling missing requirements.txt
+- Handling empty/malformed requirements.txt
+"""
+
+from __future__ import annotations
+
+import zipfile
+import io
+from unittest.mock import Mock
+from importlib import import_module
+
+
+def get_connector_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.plugin.connector')
+
+
+def create_mock_connector():
+    """Create a mock PluginRuntimeConnector instance for testing."""
+    connector = get_connector_module()
+    mock_app = Mock()
+    mock_app.logger = Mock()
+    mock_app.instance_config = Mock()
+    mock_app.instance_config.data = {'plugin': {'enable': True}}
+
+    # Mock disconnect callback
+    async def mock_disconnect_callback(connector):
+        pass
+
+    return connector.PluginRuntimeConnector(mock_app, mock_disconnect_callback)
+
+
+def create_zip_with_requirements(requirements_content: str) -> bytes:
+    """Create a ZIP file containing requirements.txt with given content."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, 'w') as zf:
+        zf.writestr('requirements.txt', requirements_content)
+    return buf.getvalue()
+
+
+def create_zip_with_nested_requirements(requirements_content: str) -> bytes:
+    """Create a ZIP file with requirements.txt in nested directory."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, 'w') as zf:
+        zf.writestr('plugin/requirements.txt', requirements_content)
+    return buf.getvalue()
+
+
+def create_zip_without_requirements() -> bytes:
+    """Create a ZIP file without requirements.txt."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, 'w') as zf:
+        zf.writestr('main.py', 'print("hello")')
+        zf.writestr('manifest.yaml', 'name: test')
+    return buf.getvalue()
+
+
+class TestExtractDepsMetadata:
+    """Tests for dependency metadata extraction from plugin packages."""
+
+    def test_extract_simple_requirements(self):
+        """Test extracting simple requirements.txt."""
+        connector_instance = create_mock_connector()
+
+        # Create test ZIP
+        zip_bytes = create_zip_with_requirements('requests>=2.0\nflask==1.0\nnumpy')
+
+        # Create task context
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        assert task_context.metadata.get('deps_total') == 3
+        assert task_context.metadata.get('deps_list') == ['requests>=2.0', 'flask==1.0', 'numpy']
+
+    def test_extract_requirements_with_comments_and_empty_lines(self):
+        """Test that comments and empty lines are filtered."""
+        connector_instance = create_mock_connector()
+
+        requirements = """# This is a comment
+requests>=2.0
+
+# Another comment
+flask==1.0
+
+numpy"""
+        zip_bytes = create_zip_with_requirements(requirements)
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        assert task_context.metadata.get('deps_total') == 3
+        assert '# This is a comment' not in task_context.metadata.get('deps_list', [])
+
+    def test_extract_nested_requirements(self):
+        """Test extracting requirements.txt from nested directory."""
+        connector_instance = create_mock_connector()
+
+        zip_bytes = create_zip_with_nested_requirements('requests\nflask')
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        # Should find nested requirements.txt (ends with 'requirements.txt')
+        assert task_context.metadata.get('deps_total') == 2
+
+    def test_no_requirements_in_zip(self):
+        """Test handling ZIP without requirements.txt."""
+        connector_instance = create_mock_connector()
+
+        zip_bytes = create_zip_without_requirements()
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        # metadata should remain empty (no deps found)
+        assert task_context.metadata.get('deps_total') is None
+        assert task_context.metadata.get('deps_list') is None
+
+    def test_empty_requirements_file(self):
+        """Test handling empty requirements.txt."""
+        connector_instance = create_mock_connector()
+
+        zip_bytes = create_zip_with_requirements('')
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        # deps_total should be 0 (empty list after filtering)
+        assert task_context.metadata.get('deps_total') == 0
+        assert task_context.metadata.get('deps_list') == []
+
+    def test_requirements_only_comments(self):
+        """Test handling requirements.txt with only comments."""
+        connector_instance = create_mock_connector()
+
+        requirements = """# Comment 1
+# Comment 2
+# Comment 3"""
+        zip_bytes = create_zip_with_requirements(requirements)
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        assert task_context.metadata.get('deps_total') == 0
+        assert task_context.metadata.get('deps_list') == []
+
+    def test_task_context_none_returns_early(self):
+        """Test that method returns early when task_context is None."""
+        connector_instance = create_mock_connector()
+
+        zip_bytes = create_zip_with_requirements('requests')
+
+        # Should return without error when task_context is None
+        connector_instance._inspect_plugin_package(zip_bytes, None)
+
+        # No exception should be raised
+
+    def test_malformed_zip_handling(self):
+        """Test handling malformed ZIP bytes."""
+        connector_instance = create_mock_connector()
+
+        # Invalid ZIP bytes
+        invalid_bytes = b'not a valid zip file'
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        # Should silently handle exception (pass in try/except)
+        connector_instance._inspect_plugin_package(invalid_bytes, task_context)
+
+        # metadata should remain unchanged
+        assert task_context.metadata == {}
+
+    def test_requirements_with_unicode_decode_error(self):
+        """Test handling requirements.txt with non-UTF8 content."""
+        connector_instance = create_mock_connector()
+
+        # Create ZIP with non-UTF8 content in requirements.txt
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, 'w') as zf:
+            # Write bytes that will cause decode issues
+            # \x80 is invalid UTF-8, but errors='ignore' will skip it
+            zf.writestr('requirements.txt', b'requests\nflask\n\x80invalid')
+        zip_bytes = buf.getvalue()
+
+        task_context = Mock()
+        task_context.metadata = {}
+
+        # errors='ignore' will decode \x80invalid as 'invalid' (skipping \x80)
+        connector_instance._inspect_plugin_package(zip_bytes, task_context)
+
+        # All 3 lines will be parsed (requests, flask, invalid)
+        assert task_context.metadata.get('deps_total') == 3
+        assert 'invalid' in task_context.metadata.get('deps_list', [])

tests/unit_tests/plugin/test_handler.py

@@ -0,0 +1,214 @@
+"""Tests for RuntimeConnectionHandler helper functions.
+
+Tests handler helper methods that don't require full handler setup.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, Mock
+import pytest
+
+from langbot_plugin.entities.io.actions.enums import PluginToRuntimeAction
+
+
+def make_handler(app):
+    """Create a RuntimeConnectionHandler with mocked external connection."""
+    from langbot.pkg.plugin.handler import RuntimeConnectionHandler
+
+    return RuntimeConnectionHandler(Mock(), AsyncMock(return_value=True), app)
+
+
+class TestHandlerQueryVariables:
+    """Tests for handler query variable logic."""
+
+    @pytest.fixture
+    def mock_app(self):
+        """Create mock app with query pool."""
+        app = SimpleNamespace()
+
+        app.query_pool = SimpleNamespace()
+        app.query_pool.cached_queries = {}
+
+        app.logger = SimpleNamespace()
+        app.logger.debug = MagicMock()
+
+        return app
+
+    @pytest.mark.asyncio
+    async def test_set_query_var_query_not_found(self, mock_app):
+        """Test set_query_var returns error when query not found."""
+        runtime_handler = make_handler(mock_app)
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.SET_QUERY_VAR.value](
+            {
+                'query_id': 'nonexistent-query',
+                'key': 'test_var',
+                'value': 'test_value',
+            }
+        )
+
+        assert response.code != 0
+        assert 'nonexistent-query' in response.message
+
+    @pytest.mark.asyncio
+    async def test_set_query_var_success(self, mock_app):
+        """Test set_query_var sets variable on existing query."""
+        runtime_handler = make_handler(mock_app)
+        mock_query = SimpleNamespace()
+        mock_query.variables = {}
+
+        mock_app.query_pool.cached_queries['test-query'] = mock_query
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.SET_QUERY_VAR.value](
+            {
+                'query_id': 'test-query',
+                'key': 'test_var',
+                'value': 'test_value',
+            }
+        )
+
+        assert response.code == 0
+        assert mock_query.variables['test_var'] == 'test_value'
+
+    @pytest.mark.asyncio
+    async def test_get_query_var_success(self, mock_app):
+        """Test get_query_var retrieves variable from query."""
+        runtime_handler = make_handler(mock_app)
+        mock_query = SimpleNamespace()
+        mock_query.variables = {'existing_var': 'existing_value'}
+
+        mock_app.query_pool.cached_queries['test-query'] = mock_query
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.GET_QUERY_VAR.value](
+            {
+                'query_id': 'test-query',
+                'key': 'existing_var',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {'value': 'existing_value'}
+
+    @pytest.mark.asyncio
+    async def test_get_query_vars_multiple(self, mock_app):
+        """Test get_query_vars returns the query's variable mapping."""
+        runtime_handler = make_handler(mock_app)
+        mock_query = SimpleNamespace()
+        mock_query.variables = {'var1': 'val1', 'var2': 'val2', 'var3': 'val3'}
+
+        mock_app.query_pool.cached_queries['test-query'] = mock_query
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.GET_QUERY_VARS.value](
+            {
+                'query_id': 'test-query',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {'vars': mock_query.variables}
+
+
+class TestHandlerRagErrorResponse:
+    """Tests for _make_rag_error_response helper."""
+
+    def test_make_rag_error_response_basic(self):
+        """Test basic error response creation."""
+        from langbot.pkg.plugin.handler import _make_rag_error_response
+
+        error = Exception('test error')
+        response = _make_rag_error_response(error, 'TestError')
+
+        # ActionResponse is a pydantic model, check message field
+        assert 'TestError' in response.message
+        assert 'test error' in response.message
+        assert 'Exception' in response.message
+
+    def test_make_rag_error_response_with_context(self):
+        """Test error response with extra context."""
+        from langbot.pkg.plugin.handler import _make_rag_error_response
+
+        error = ValueError('invalid input')
+        response = _make_rag_error_response(error, 'ValidationError', field='name', value='test')
+
+        assert 'ValidationError' in response.message
+        assert 'field=name' in response.message
+        assert 'value=test' in response.message
+        assert 'ValueError' in response.message
+
+    def test_make_rag_error_response_exception_type(self):
+        """Test error response includes exception type."""
+        from langbot.pkg.plugin.handler import _make_rag_error_response
+
+        error = RuntimeError('connection failed')
+        response = _make_rag_error_response(error, 'ConnectionError')
+
+        assert 'RuntimeError' in response.message
+        assert 'ConnectionError' in response.message
+        assert 'connection failed' in response.message
+
+    def test_make_rag_error_response_empty_context(self):
+        """Test error response with no extra context."""
+        from langbot.pkg.plugin.handler import _make_rag_error_response
+
+        error = KeyError('missing_key')
+        response = _make_rag_error_response(error, 'LookupError')
+
+        # No context parts means no brackets
+        assert '[' in response.message  # Still has error type bracket
+        assert 'KeyError' in response.message
+
+
+class TestHandlerPluginDiagnostic:
+    @pytest.mark.asyncio
+    async def test_notify_plugin_diagnostic_falls_back_to_raw_protocol_action(self):
+        """Diagnostic forwarding works before the SDK enum exists."""
+        app = SimpleNamespace()
+        app.logger = SimpleNamespace(debug=MagicMock())
+        runtime_handler = make_handler(app)
+        runtime_handler.call_action = AsyncMock(return_value={})
+
+        payload = {'code': 'response_delivery_failed'}
+        await runtime_handler.notify_plugin_diagnostic(payload)
+
+        action = runtime_handler.call_action.await_args.args[0]
+        assert action.value == 'plugin_diagnostic'
+        assert runtime_handler.call_action.await_args.args[1] is payload
+        assert runtime_handler.call_action.await_args.kwargs['timeout'] == 5
+
+    def test_langbot_to_runtime_action_uses_enum_when_available(self):
+        """The compatibility helper should prefer SDK enums once available."""
+        from langbot.pkg.plugin import handler as plugin_handler
+
+        sentinel = object()
+        original = plugin_handler.LangBotToRuntimeAction
+        plugin_handler.LangBotToRuntimeAction = SimpleNamespace(PLUGIN_DIAGNOSTIC=sentinel)
+        try:
+            assert plugin_handler._langbot_to_runtime_action('PLUGIN_DIAGNOSTIC', 'plugin_diagnostic') is sentinel
+        finally:
+            plugin_handler.LangBotToRuntimeAction = original
+
+
+class TestConstantsSemanticVersion:
+    """Tests for version constant access."""
+
+    def test_semantic_version_exists(self):
+        """Test semantic_version is defined."""
+        from langbot.pkg.utils import constants
+
+        assert hasattr(constants, 'semantic_version')
+        assert constants.semantic_version.startswith('v')
+
+    def test_edition_exists(self):
+        """Test edition constant is defined."""
+        from langbot.pkg.utils import constants
+
+        assert hasattr(constants, 'edition')
+        assert constants.edition == 'community'
+
+    def test_required_database_version_exists(self):
+        """Test database version constant."""
+        from langbot.pkg.utils import constants
+
+        assert hasattr(constants, 'required_database_version')
+        assert isinstance(constants.required_database_version, int)

tests/unit_tests/plugin/test_handler_actions.py

@@ -0,0 +1,425 @@
+"""Unit tests for RuntimeConnectionHandler action handlers."""
+
+from __future__ import annotations
+
+import base64
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from langbot_plugin.entities.io.actions.enums import PluginToRuntimeAction, RuntimeToLangBotAction
+
+
+def make_handler(app):
+    """Create a RuntimeConnectionHandler with mocked external connection."""
+    from langbot.pkg.plugin.handler import RuntimeConnectionHandler
+
+    return RuntimeConnectionHandler(Mock(), AsyncMock(return_value=True), app)
+
+
+def make_result(first_item=None):
+    result = Mock()
+    result.first = Mock(return_value=first_item)
+    return result
+
+
+def compiled_params(statement):
+    return statement.compile().params
+
+
+class TestRagRerankAction:
+    """Tests for RAG rerank action handler."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.model_mgr = Mock()
+        mock_app.logger = Mock()
+        return mock_app
+
+    @pytest.mark.asyncio
+    async def test_invokes_rerank_model_and_sorts_scores(self, app):
+        """Rerank action uses the selected model and returns top scores."""
+        provider = Mock()
+        provider.invoke_rerank = AsyncMock(
+            return_value=[
+                {'index': 0, 'relevance_score': 0.2},
+                {'index': 1, 'relevance_score': 0.9},
+            ]
+        )
+        rerank_model = SimpleNamespace(provider=provider)
+        app.model_mgr.get_rerank_model_by_uuid = AsyncMock(return_value=rerank_model)
+        runtime_handler = make_handler(app)
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.INVOKE_RERANK.value](
+            {
+                'rerank_model_uuid': 'rerank-1',
+                'query': 'hello',
+                'documents': ['a', 'b'],
+                'top_k': 1,
+                'extra_args': {'return_documents': False},
+            }
+        )
+
+        assert response.code == 0
+        assert response.data['results'] == [{'index': 1, 'relevance_score': 0.9}]
+        app.model_mgr.get_rerank_model_by_uuid.assert_awaited_once_with('rerank-1')
+        provider.invoke_rerank.assert_awaited_once_with(
+            model=rerank_model,
+            query='hello',
+            documents=['a', 'b'],
+            extra_args={'return_documents': False},
+        )
+
+    @pytest.mark.asyncio
+    async def test_returns_error_when_rerank_model_missing(self, app):
+        """Missing rerank model returns an action error."""
+        app.model_mgr.get_rerank_model_by_uuid = AsyncMock(side_effect=ValueError('not found'))
+        runtime_handler = make_handler(app)
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.INVOKE_RERANK.value](
+            {
+                'rerank_model_uuid': 'missing',
+                'query': 'hello',
+                'documents': ['a'],
+            }
+        )
+
+        assert response.code != 0
+        assert 'Rerank model with rerank_model_uuid missing not found' in response.message
+
+
+class TestInitializePluginSettings:
+    """Tests for initialize_plugin_settings action handler."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.persistence_mgr = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.logger = Mock()
+        return mock_app
+
+    @pytest.mark.asyncio
+    async def test_creates_new_setting_when_not_exists(self, app):
+        """New plugin settings use default enabled, priority and config values."""
+        runtime_handler = make_handler(app)
+        app.persistence_mgr.execute_async.side_effect = [
+            make_result(),
+            Mock(),
+        ]
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS.value](
+            {
+                'plugin_author': 'test-author',
+                'plugin_name': 'test-plugin',
+                'install_source': 'local',
+                'install_info': {'path': '/test'},
+            }
+        )
+
+        assert response.code == 0
+        assert app.persistence_mgr.execute_async.await_count == 2
+        insert_params = compiled_params(app.persistence_mgr.execute_async.await_args_list[1].args[0])
+        assert insert_params == {
+            'plugin_author': 'test-author',
+            'plugin_name': 'test-plugin',
+            'install_source': 'local',
+            'install_info': {'path': '/test'},
+            'enabled': True,
+            'priority': 0,
+            'config': {},
+        }
+
+    @pytest.mark.asyncio
+    async def test_inherits_values_from_existing_setting(self, app):
+        """Existing settings are replaced while preserving user-controlled values."""
+        runtime_handler = make_handler(app)
+        existing_setting = SimpleNamespace(
+            enabled=False,
+            priority=5,
+            config={'key': 'value'},
+        )
+        app.persistence_mgr.execute_async.side_effect = [
+            make_result(existing_setting),
+            Mock(),
+            Mock(),
+        ]
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS.value](
+            {
+                'plugin_author': 'test-author',
+                'plugin_name': 'test-plugin',
+                'install_source': 'github',
+                'install_info': {'repo': 'author/name'},
+            }
+        )
+
+        assert response.code == 0
+        assert app.persistence_mgr.execute_async.await_count == 3
+        insert_params = compiled_params(app.persistence_mgr.execute_async.await_args_list[2].args[0])
+        assert insert_params['enabled'] is False
+        assert insert_params['priority'] == 5
+        assert insert_params['config'] == {'key': 'value'}
+        assert insert_params['install_source'] == 'github'
+        assert insert_params['install_info'] == {'repo': 'author/name'}
+
+
+class TestSetBinaryStorage:
+    """Tests for set_binary_storage action handler with size limit validation."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.instance_config = Mock()
+        mock_app.instance_config.data = {
+            'plugin': {
+                'binary_storage': {
+                    'max_value_bytes': 1024,
+                },
+            },
+        }
+        mock_app.persistence_mgr = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=make_result())
+        mock_app.logger = Mock()
+        return mock_app
+
+    @staticmethod
+    def payload(value: bytes):
+        return {
+            'key': 'test-key',
+            'owner_type': 'plugin',
+            'owner': 'test-owner',
+            'value_base64': base64.b64encode(value).decode('utf-8'),
+        }
+
+    @pytest.mark.asyncio
+    async def test_rejects_value_exceeding_limit(self, app):
+        """Values larger than max_value_bytes are rejected before persistence writes."""
+        runtime_handler = make_handler(app)
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](
+            self.payload(b'x' * 2048)
+        )
+
+        assert response.code != 0
+        assert '2048 > 1024 bytes' in response.message
+        app.persistence_mgr.execute_async.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_accepts_value_within_limit_and_inserts_storage(self, app):
+        """A new small value is inserted into binary storage."""
+        runtime_handler = make_handler(app)
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](
+            self.payload(b'x' * 512)
+        )
+
+        assert response.code == 0
+        assert app.persistence_mgr.execute_async.await_count == 2
+        insert_params = compiled_params(app.persistence_mgr.execute_async.await_args_list[1].args[0])
+        assert insert_params['unique_key'] == 'plugin:test-owner:test-key'
+        assert insert_params['value'] == b'x' * 512
+
+    @pytest.mark.asyncio
+    async def test_updates_existing_storage(self, app):
+        """An existing binary storage row is updated instead of inserted."""
+        runtime_handler = make_handler(app)
+        app.persistence_mgr.execute_async.return_value = make_result(SimpleNamespace(value=b'old'))
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](self.payload(b'new'))
+
+        assert response.code == 0
+        assert app.persistence_mgr.execute_async.await_count == 2
+        update_params = compiled_params(app.persistence_mgr.execute_async.await_args_list[1].args[0])
+        assert update_params['value'] == b'new'
+
+    @pytest.mark.asyncio
+    async def test_invalid_max_value_bytes_falls_back_to_default_limit(self, app):
+        """Invalid max_value_bytes uses the 10MB default limit."""
+        runtime_handler = make_handler(app)
+        app.instance_config.data['plugin']['binary_storage']['max_value_bytes'] = 'invalid'
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](
+            self.payload(b'x' * (10 * 1024 * 1024 + 1))
+        )
+
+        assert response.code != 0
+        assert '10485761 > 10485760 bytes' in response.message
+        app.persistence_mgr.execute_async.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_negative_limit_disables_size_check(self, app):
+        """Negative max_value_bytes allows values larger than the normal default."""
+        runtime_handler = make_handler(app)
+        app.instance_config.data['plugin']['binary_storage']['max_value_bytes'] = -1
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](
+            self.payload(b'x' * 2048)
+        )
+
+        assert response.code == 0
+        assert app.persistence_mgr.execute_async.await_count == 2
+
+    @pytest.mark.asyncio
+    async def test_zero_limit_rejects_non_empty_values(self, app):
+        """A zero byte limit rejects non-empty values."""
+        runtime_handler = make_handler(app)
+        app.instance_config.data['plugin']['binary_storage']['max_value_bytes'] = 0
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.SET_BINARY_STORAGE.value](self.payload(b'x'))
+
+        assert response.code != 0
+        assert '1 > 0 bytes' in response.message
+        app.persistence_mgr.execute_async.assert_not_awaited()
+
+
+class TestGetPluginSettings:
+    """Tests for get_plugin_settings action handler with defaults."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.persistence_mgr = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        return mock_app
+
+    @pytest.mark.asyncio
+    async def test_returns_defaults_when_setting_not_found(self, app):
+        """Default plugin settings are returned when no persisted row exists."""
+        runtime_handler = make_handler(app)
+        app.persistence_mgr.execute_async.return_value = make_result()
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.GET_PLUGIN_SETTINGS.value](
+            {
+                'plugin_author': 'test-author',
+                'plugin_name': 'test-plugin',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {
+            'enabled': True,
+            'priority': 0,
+            'plugin_config': {},
+            'install_source': 'local',
+            'install_info': {},
+        }
+
+    @pytest.mark.asyncio
+    async def test_returns_actual_values_when_setting_exists(self, app):
+        """Persisted plugin setting values override defaults."""
+        runtime_handler = make_handler(app)
+        setting = SimpleNamespace(
+            enabled=False,
+            priority=10,
+            config={'custom': 'config'},
+            install_source='github',
+            install_info={'repo': 'test/repo'},
+        )
+        app.persistence_mgr.execute_async.return_value = make_result(setting)
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.GET_PLUGIN_SETTINGS.value](
+            {
+                'plugin_author': 'test-author',
+                'plugin_name': 'test-plugin',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {
+            'enabled': False,
+            'priority': 10,
+            'plugin_config': {'custom': 'config'},
+            'install_source': 'github',
+            'install_info': {'repo': 'test/repo'},
+        }
+
+
+class TestGetBinaryStorage:
+    """Tests for get_binary_storage action handler."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.persistence_mgr = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        return mock_app
+
+    @pytest.mark.asyncio
+    async def test_returns_base64_encoded_value(self, app):
+        """Stored bytes are returned as base64."""
+        runtime_handler = make_handler(app)
+        app.persistence_mgr.execute_async.return_value = make_result(SimpleNamespace(value=b'test binary content'))
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.GET_BINARY_STORAGE.value](
+            {
+                'key': 'test-key',
+                'owner_type': 'plugin',
+                'owner': 'test-owner',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {
+            'value_base64': base64.b64encode(b'test binary content').decode('utf-8'),
+        }
+
+    @pytest.mark.asyncio
+    async def test_returns_error_when_not_found(self, app):
+        """Missing binary storage rows return an error response."""
+        runtime_handler = make_handler(app)
+        app.persistence_mgr.execute_async.return_value = make_result()
+
+        response = await runtime_handler.actions[RuntimeToLangBotAction.GET_BINARY_STORAGE.value](
+            {
+                'key': 'test-key',
+                'owner_type': 'plugin',
+                'owner': 'test-owner',
+            }
+        )
+
+        assert response.code != 0
+        assert 'Storage with key test-key not found' in response.message
+
+
+class TestHandlerQueryLookup:
+    """Tests for query lookup in cached_queries."""
+
+    @pytest.fixture
+    def app(self):
+        mock_app = Mock()
+        mock_app.query_pool = Mock()
+        mock_app.query_pool.cached_queries = {}
+        mock_app.logger = Mock()
+        return mock_app
+
+    @pytest.mark.asyncio
+    async def test_query_not_found_returns_error(self, app):
+        """Query-bound actions return error when query_id is not cached."""
+        runtime_handler = make_handler(app)
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.GET_BOT_UUID.value](
+            {
+                'query_id': 'nonexistent-query',
+            }
+        )
+
+        assert response.code != 0
+        assert 'nonexistent-query' in response.message
+
+    @pytest.mark.asyncio
+    async def test_query_found_returns_success(self, app):
+        """Query-bound actions read data from the cached query object."""
+        runtime_handler = make_handler(app)
+        query = SimpleNamespace(variables={}, bot_uuid='test-bot-uuid')
+        app.query_pool.cached_queries['existing-query'] = query
+
+        response = await runtime_handler.actions[PluginToRuntimeAction.GET_BOT_UUID.value](
+            {
+                'query_id': 'existing-query',
+            }
+        )
+
+        assert response.code == 0
+        assert response.data == {'bot_uuid': 'test-bot-uuid'}

tests/unit_tests/plugin/test_handler_helpers.py

@@ -0,0 +1,126 @@
+"""Unit tests for plugin handler helper functions and methods.
+
+Tests cover:
+- _make_rag_error_response() helper function
+- RuntimeConnectionHandler cleanup_plugin_data method
+"""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+from importlib import import_module
+
+
+def get_handler_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.plugin.handler')
+
+
+class TestMakeRagErrorResponse:
+    """Tests for _make_rag_error_response helper function."""
+
+    def test_creates_error_response_with_exception(self):
+        """Test basic error response creation."""
+        handler = get_handler_module()
+
+        error = ValueError('test error message')
+        result = handler._make_rag_error_response(error, 'TestError')
+
+        # ActionResponse.error() returns code=1 (error status)
+        assert result.code == 1
+        assert 'TestError' in result.message
+        assert 'ValueError' in result.message
+        assert 'test error message' in result.message
+
+    def test_includes_error_type_in_message(self):
+        """Test that error type is included in message."""
+        handler = get_handler_module()
+
+        error = RuntimeError('something went wrong')
+        result = handler._make_rag_error_response(error, 'VectorStoreError')
+
+        assert '[VectorStoreError/RuntimeError]' in result.message
+
+    def test_includes_extra_context_in_message(self):
+        """Test that extra context fields are included."""
+        handler = get_handler_module()
+
+        error = Exception('embedding failed')
+        result = handler._make_rag_error_response(
+            error,
+            'EmbeddingError',
+            embedding_model_uuid='test-uuid-123',
+            collection_id='collection-456',
+        )
+
+        assert 'embedding_model_uuid=test-uuid-123' in result.message
+        assert 'collection_id=collection-456' in result.message
+
+    def test_handles_exception_with_no_message(self):
+        """Test handling exception with empty message."""
+        handler = get_handler_module()
+
+        error = Exception()
+        result = handler._make_rag_error_response(error, 'GenericError')
+
+        # ActionResponse.error() returns code=1 (error status)
+        assert result.code == 1
+        assert '[GenericError/Exception]' in result.message
+
+    def test_formats_context_with_multiple_fields(self):
+        """Test multiple context fields are comma separated."""
+        handler = get_handler_module()
+
+        error = IOError('file not found')
+        result = handler._make_rag_error_response(
+            error,
+            'FileServiceError',
+            storage_path='/data/file.pdf',
+            kb_id='kb-001',
+        )
+
+        assert '[storage_path=/data/file.pdf, kb_id=kb-001]' in result.message
+
+
+class TestCleanupPluginData:
+    """Tests for cleanup_plugin_data method."""
+
+    @pytest.mark.asyncio
+    async def test_deletes_plugin_settings(self):
+        """Test that plugin settings are deleted."""
+        handler_module = get_handler_module()
+
+        mock_app = Mock()
+        mock_app.persistence_mgr = AsyncMock()
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+
+        # Mock the handler without connection (we only need ap)
+        handler_instance = Mock(spec=handler_module.RuntimeConnectionHandler)
+        handler_instance.ap = mock_app
+
+        # Call cleanup_plugin_data
+        await handler_module.RuntimeConnectionHandler.cleanup_plugin_data(
+            handler_instance, 'test-author', 'test-plugin'
+        )
+
+        # Verify plugin settings delete was called
+        calls = mock_app.persistence_mgr.execute_async.call_args_list
+        assert len(calls) >= 1
+
+    @pytest.mark.asyncio
+    async def test_deletes_binary_storage(self):
+        """Test that binary storage is deleted."""
+        handler_module = get_handler_module()
+
+        mock_app = Mock()
+        mock_app.persistence_mgr = AsyncMock()
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+
+        handler_instance = Mock(spec=handler_module.RuntimeConnectionHandler)
+        handler_instance.ap = mock_app
+
+        await handler_module.RuntimeConnectionHandler.cleanup_plugin_data(handler_instance, 'author', 'plugin-name')
+
+        # Should have at least 2 calls: one for settings, one for binary storage
+        assert mock_app.persistence_mgr.execute_async.call_count >= 2

tests/unit_tests/plugin/test_plugin_component_filtering.py

@@ -0,0 +1,276 @@
+"""Test plugin list filtering by component kinds."""
+
+from unittest.mock import AsyncMock, MagicMock
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_filter_by_component_kinds():
+    """Test that plugins can be filtered by component kinds."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data with different component kinds
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'plugin_with_tool',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'Tool', 'metadata': {'name': 'tool1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author2',
+                        'name': 'plugin_with_knowledge_engine_only',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author3',
+                        'name': 'plugin_with_command',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'Command', 'metadata': {'name': 'cmd1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author4',
+                        'name': 'plugin_with_event_listener',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'EventListener', 'metadata': {'name': 'listener1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author5',
+                        'name': 'plugin_with_mixed_components',
+                    }
+                }
+            },
+            'components': [
+                {'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever2'}}}},
+                {'manifest': {'manifest': {'kind': 'Tool', 'metadata': {'name': 'tool2'}}}},
+            ],
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+        mock_result.__iter__ = lambda self: iter([])
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Test filtering by pipeline component kinds (Command, EventListener, Tool)
+    pipeline_component_kinds = ['Command', 'EventListener', 'Tool']
+    result = await connector.list_plugins(component_kinds=pipeline_component_kinds)
+
+    # Verify that only plugins with pipeline-related components are returned
+    assert len(result) == 4
+    plugin_names = [p['manifest']['manifest']['metadata']['name'] for p in result]
+    assert 'plugin_with_tool' in plugin_names
+    assert 'plugin_with_command' in plugin_names
+    assert 'plugin_with_event_listener' in plugin_names
+    assert 'plugin_with_mixed_components' in plugin_names
+    # Plugin with only KnowledgeEngine should NOT be included
+    assert 'plugin_with_knowledge_engine_only' not in plugin_names
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_filter_no_filter():
+    """Test that all plugins are returned when no filter is specified."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data with different component kinds
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'plugin1',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'Tool', 'metadata': {'name': 'tool1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author2',
+                        'name': 'plugin2',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+        mock_result.__iter__ = lambda self: iter([])
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Test without filter - should return all plugins
+    result = await connector.list_plugins()
+
+    assert len(result) == 2
+    plugin_names = [p['manifest']['manifest']['metadata']['name'] for p in result]
+    assert 'plugin1' in plugin_names
+    assert 'plugin2' in plugin_names
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_filter_empty_result():
+    """Test that empty list is returned when no plugins match the filter."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data - only KnowledgeEngine plugins
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'plugin1',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+        mock_result.__iter__ = lambda self: iter([])
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Filter by Tool kind - should return empty list
+    result = await connector.list_plugins(component_kinds=['Tool'])
+
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_filter_plugin_without_components():
+    """Test that plugins without components are excluded when filtering."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data - one with components, one without
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'plugin_with_tool',
+                    }
+                }
+            },
+            'components': [{'manifest': {'manifest': {'kind': 'Tool', 'metadata': {'name': 'tool1'}}}}],
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author2',
+                        'name': 'plugin_without_components',
+                    }
+                }
+            },
+            'components': [],
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+        mock_result.__iter__ = lambda self: iter([])
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Filter by Tool kind - should return only plugin with Tool
+    result = await connector.list_plugins(component_kinds=['Tool'])
+
+    assert len(result) == 1
+    assert result[0]['manifest']['manifest']['metadata']['name'] == 'plugin_with_tool'

tests/unit_tests/plugin/test_plugin_id_parsing.py

@@ -0,0 +1,25 @@
+"""Test plugin ID parsing validation."""
+
+import pytest
+
+from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+
+def test_parse_plugin_id_accepts_author_name():
+    assert PluginRuntimeConnector._parse_plugin_id('langbot/rag-engine') == ('langbot', 'rag-engine')
+
+
+@pytest.mark.parametrize(
+    'plugin_id',
+    [
+        '',
+        'author',
+        'author/',
+        '/name',
+        'author/name/extra',
+        '/',
+    ],
+)
+def test_parse_plugin_id_rejects_malformed_ids(plugin_id):
+    with pytest.raises(ValueError, match='Expected'):
+        PluginRuntimeConnector._parse_plugin_id(plugin_id)

tests/unit_tests/plugin/test_plugin_list_sorting.py

@@ -0,0 +1,228 @@
+"""Test plugin list sorting functionality."""
+
+from datetime import datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_sorting_debug_first():
+    """Test that debug plugins appear before non-debug plugins."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data with different debug states and timestamps
+    now = datetime.now()
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'plugin1',
+                    }
+                }
+            },
+        },
+        {
+            'debug': True,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author2',
+                        'name': 'plugin2',
+                    }
+                }
+            },
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author3',
+                        'name': 'plugin3',
+                    }
+                }
+            },
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query to return all timestamps in a single batch
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+
+        # Create mock rows for all plugins with timestamps
+        mock_rows = []
+
+        # plugin1: oldest, plugin2: middle, plugin3: newest
+        mock_row1 = MagicMock()
+        mock_row1.plugin_author = 'author1'
+        mock_row1.plugin_name = 'plugin1'
+        mock_row1.created_at = now - timedelta(days=2)
+        mock_rows.append(mock_row1)
+
+        mock_row2 = MagicMock()
+        mock_row2.plugin_author = 'author2'
+        mock_row2.plugin_name = 'plugin2'
+        mock_row2.created_at = now - timedelta(days=1)
+        mock_rows.append(mock_row2)
+
+        mock_row3 = MagicMock()
+        mock_row3.plugin_author = 'author3'
+        mock_row3.plugin_name = 'plugin3'
+        mock_row3.created_at = now
+        mock_rows.append(mock_row3)
+
+        # Make the result iterable
+        mock_result.__iter__ = lambda self: iter(mock_rows)
+
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Call list_plugins
+    result = await connector.list_plugins()
+
+    # Verify sorting: debug plugin should be first
+    assert len(result) == 3
+    assert result[0]['debug'] is True  # plugin2 (debug)
+    assert result[0]['manifest']['manifest']['metadata']['name'] == 'plugin2'
+
+    # Remaining should be sorted by created_at (newest first)
+    assert result[1]['debug'] is False
+    assert result[1]['manifest']['manifest']['metadata']['name'] == 'plugin3'  # newest non-debug
+    assert result[2]['debug'] is False
+    assert result[2]['manifest']['manifest']['metadata']['name'] == 'plugin1'  # oldest non-debug
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_sorting_by_installation_time():
+    """Test that non-debug plugins are sorted by installation time (newest first)."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock plugin data - all non-debug with different installation times
+    now = datetime.now()
+    mock_plugins = [
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author1',
+                        'name': 'oldest_plugin',
+                    }
+                }
+            },
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author2',
+                        'name': 'middle_plugin',
+                    }
+                }
+            },
+        },
+        {
+            'debug': False,
+            'manifest': {
+                'manifest': {
+                    'metadata': {
+                        'author': 'author3',
+                        'name': 'newest_plugin',
+                    }
+                }
+            },
+        },
+    ]
+
+    connector.handler.list_plugins = AsyncMock(return_value=mock_plugins)
+
+    # Mock database query to return all timestamps in a single batch
+    async def mock_execute_async(query):
+        mock_result = MagicMock()
+
+        # Create mock rows for all plugins with timestamps
+        mock_rows = []
+
+        # oldest_plugin: oldest, middle_plugin: middle, newest_plugin: newest
+        mock_row1 = MagicMock()
+        mock_row1.plugin_author = 'author1'
+        mock_row1.plugin_name = 'oldest_plugin'
+        mock_row1.created_at = now - timedelta(days=10)
+        mock_rows.append(mock_row1)
+
+        mock_row2 = MagicMock()
+        mock_row2.plugin_author = 'author2'
+        mock_row2.plugin_name = 'middle_plugin'
+        mock_row2.created_at = now - timedelta(days=5)
+        mock_rows.append(mock_row2)
+
+        mock_row3 = MagicMock()
+        mock_row3.plugin_author = 'author3'
+        mock_row3.plugin_name = 'newest_plugin'
+        mock_row3.created_at = now
+        mock_rows.append(mock_row3)
+
+        # Make the result iterable
+        mock_result.__iter__ = lambda self: iter(mock_rows)
+
+        return mock_result
+
+    mock_app.persistence_mgr.execute_async = mock_execute_async
+
+    # Call list_plugins
+    result = await connector.list_plugins()
+
+    # Verify sorting: newest first
+    assert len(result) == 3
+    assert result[0]['manifest']['manifest']['metadata']['name'] == 'newest_plugin'
+    assert result[1]['manifest']['manifest']['metadata']['name'] == 'middle_plugin'
+    assert result[2]['manifest']['manifest']['metadata']['name'] == 'oldest_plugin'
+
+
+@pytest.mark.asyncio
+async def test_plugin_list_empty():
+    """Test that empty plugin list is handled correctly."""
+    from langbot.pkg.plugin.connector import PluginRuntimeConnector
+
+    # Mock the application
+    mock_app = MagicMock()
+    mock_app.instance_config.data.get.return_value = {'enable': True}
+    mock_app.logger = MagicMock()
+
+    # Create connector
+    connector = PluginRuntimeConnector(mock_app, AsyncMock())
+    connector.handler = MagicMock()
+
+    # Mock empty plugin list
+    connector.handler.list_plugins = AsyncMock(return_value=[])
+
+    # Call list_plugins
+    result = await connector.list_plugins()
+
+    # Verify empty list
+    assert len(result) == 0