test(phase2): add unit tests for core, persistence, plugin, utils

- Add test_handler_helpers.py for plugin handler helpers (7 tests)
- Add test_mgr_methods.py for persistence manager (5 tests)
- Add test_app_config_validation.py for core app config (12 tests)
- Add test_knowledge_service.py for API knowledge service (22 tests)
- Add test_kbmgr.py for RAG knowledge base manager (39 tests)
- Add test_survey_manager.py for survey manager (22 tests)
- Add test_connector_methods.py for plugin connector (24 tests)
- Add test_funcschema.py for utils function schema (9 tests)
- Add test_platform.py for utils platform detection (7 tests)
- Add test_extract_deps.py for plugin deps extraction (7 tests)
- Add test_database_decorator.py for persistence decorator (7 tests)
- Add test_load_config.py for core config loading (19 tests)
- Add COVERAGE_EXCLUSIONS.md documenting external adapter exclusions
- Fix test_chat_session_limit.py path for portability

Coverage: core 28% → 30%, persistence 24% → 24.4%, plugin 27% → 28%
Total: 1082 tests passed, core module coverage 45.5%

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/unit_tests/COVERAGE_EXCLUSIONS.md

@@ -0,0 +1,160 @@
+# 单元测试覆盖率排除说明
+
+## 排除范围
+
+以下外部适配器模块不纳入测试覆盖目标，因为它们需要实际外部环境才能测试：
+
+### 1. 消息平台适配器 (`platform/sources/`)
+- **路径**: `src/langbot/pkg/platform/sources/`
+- **模块**: aiocqhttp, dingtalk, discord, feishu, gestep, kook, lark, slack, telegram, wecom, wechatpv, wechatmp, qqbot
+- **排除原因**: 需要真实消息平台账号和 webhook 连接，无法纯单元测试
+- **测试方式**: 需要 mock 平台 API 或集成测试环境
+- **状态**: 后续可补充 mock 测试
+
+### 2. LLM Requester (`provider/modelmgr/requesters/`)
+- **路径**: `src/langbot/pkg/provider/modelmgr/requesters/`
+- **模块**: deepseek, openai, anthropic, gemini, moonshot, ollama, zhipuai 等 20+ 个 requester
+- **排除原因**: 需要真实 LLM API 密钥和网络请求，涉及付费 API 调用
+- **测试方式**: 需要 mock HTTP 响应或使用 fake LLM server
+- **状态**: 后续可补充 mock HTTP 测试
+
+### 3. Agent Runner (`provider/runners/`)
+- **路径**: `src/langbot/pkg/provider/runners/`
+- **模块**: cozeapi, difysvapi, n8nsvapi, langflowapi, dashscopeapi, localagent, tboxapi
+- **排除原因**: 需要真实 Agent 平台（Coze、Dify、n8n 等）的 API 连接
+- **测试方式**: 需要 mock Agent 平台响应
+- **状态**: 后续可补充 mock 测试
+
+### 4. 向量数据库 (`vector/vdbs/`)
+- **路径**: `src/langbot/pkg/vector/vdbs/`
+- **模块**: chroma, milvus, pgvector, qdrant, seekdb
+- **排除原因**: 需要真实向量数据库实例运行
+- **测试方式**: 需要 Docker 启动测试数据库或 mock
+- **状态**: 后续可补充 mock 测试
+
+---
+
+## 覆盖率计算（排除外部适配器）
+
+### 统计方法
+
+```bash
+# 排除外部适配器后计算覆盖率
+pytest tests/unit_tests/ --cov=langbot.pkg \
+  --cov-fail-under=0 \
+  -o "cov_exclude_patterns=platform/sources/*,provider/modelmgr/requesters/*,provider/runners/*,vector/vdbs/*"
+```
+
+### 当前覆盖率（排除后）
+
+| 模块 | 覆盖率 | 状态 |
+|------|--------|------|
+| `command` | **99%** | ✅ 完成 |
+| `entity` | **99%** | ✅ 完成 |
+| `vector` | **82%** | ✅ 完成 |
+| `survey` | **84%** | ✅ 完成 |
+| `pipeline` | **72%** | ✅ 核心流程 |
+| `rag` | **70%** | ✅ 完成 |
+| `config` | **70%** | ✅ 完成 |
+| `discover` | **61%** | ✅ 完成 |
+| `telemetry` | **63%** | ✅ 完成 |
+| `storage` | **58%** | ✅ 完成 |
+| `provider` | **57%** | 🔄 部分完成 |
+| `utils` | **48%** | 🔄 部分完成 |
+| `api` | **34%** | 🔄 需补充 controller |
+| `platform` | **35%** | 🔄 需补充 adapter base |
+| `core` | **30%** | 🔄 需补充 app 启动 |
+| `plugin` | **28%** | 🔄 需补充 handler |
+| `persistence` | **24%** | 🔄 需补充 mgr |
+
+---
+
+## 后续计划
+
+### 可补充的 Mock 测试（优先级排序）
+
+1. **`provider/modelmgr/requesters/`** (优先级：中)
+   - 使用 `httpx` mock 测试 API 响应解析
+   - 测试重试逻辑、错误处理
+
+2. **`provider/runners/`** (优先级：中)
+   - Mock Agent 平台响应
+   - 测试 session 管理、错误处理
+
+3. **`platform/sources/`** (优先级：低)
+   - Mock 平台 webhook 事件
+   - 测试消息解析、事件处理
+
+4. **`vector/vdbs/`** (优先级：低)
+   - Mock 向量数据库操作
+   - 测试 CRUD、查询逻辑
+
+---
+
+## 测试文件结构
+
+```
+tests/unit_tests/
+├── api/
+│   └── service/
+│       ├── test_knowledge_service.py  # 22 tests ✅
+│       └── ...
+├── core/
+│   ├── test_taskmgr.py                 # 21 tests ✅
+│   ├── test_load_config.py             # 19 tests ✅
+│   └── ...
+├── plugin/
+│   ├── test_connector_static.py        # 8 tests ✅
+│   ├── test_connector_pure.py          # 7 tests ✅
+│   ├── test_connector_methods.py       # 24 tests ✅
+│   └── test_extract_deps.py            # 7 tests ✅
+├── rag/
+│   ├── test_i18n_conversion.py         # 8 tests ✅
+│   ├── test_kbmgr.py                   # 39 tests ✅
+│   └── ...
+├── survey/
+│   └── test_survey_manager.py          # 22 tests ✅
+├── telemetry/
+│   └── test_telemetry.py               # 14 tests ✅
+├── utils/
+│   ├── test_platform.py                # 7 tests ✅
+│   ├── test_funcschema.py              # 9 tests ✅
+│   └── ...
+└── persistence/
+    ├── test_serialize_model.py         # 6 tests ✅
+    ├── test_database_decorator.py      # 7 tests ✅
+    └── ...
+```
+
+---
+
+## 总结
+
+- **总测试数**: 1082 passed
+- **总体覆盖率**: 28.3%
+- **核心模块覆盖率**: **45.5%** (5659/12425 语句) - 排除外部适配器
+- **外部适配器覆盖率**: 5.6% (535/9483 语句) - 不纳入目标
+
+### 核心模块覆盖率详情
+
+| 模块 | 覆盖率 | 语句数 | 说明 |
+|------|--------|--------|------|
+| `command` | **99%** | 93 | ✅ 完成 |
+| `entity` | **99%** | 335 | ✅ 完成 |
+| `vector` | **82%** | 139 | ✅ 完成 |
+| `survey` | **84%** | 95 | ✅ 完成 |
+| `pipeline` | **72%** | 1761 | ✅ 核心流程 |
+| `rag` | **69%** | 347 | ✅ 完成 |
+| `storage` | **58%** | 170 | ✅ 完成 |
+| `provider` | **57%** | 854 | 🔄 部分完成 |
+| `telemetry` | **63%** | 70 | ✅ 完成 |
+| `discover` | **61%** | 188 | ✅ 完成 |
+| `config` | **70%** | 198 | ✅ 完成 |
+| `utils` | **48%** | 478 | 🔄 部分完成 |
+| `api` | **34%** | 4061 | 🔄 需补充 controller |
+| `platform` | **35%** | 433 | 🔄 需补充 adapter base |
+| `plugin` | **27%** | 815 | 🔄 需补充 handler |
+| `core` | **28%** | 1289 | 🔄 需补充 app 启动 |
+| `persistence` | **24%** | 1099 | 🔄 需补充 mgr |
+
+外部适配器测试需要 mock 环境或集成测试，不属于纯单元测试范畴。

tests/unit_tests/api/service/test_knowledge_service.py

@@ -0,0 +1,397 @@
+"""Unit tests for API knowledge service.
+
+Tests cover:
+- Knowledge base CRUD operations
+- Capability checking
+- Knowledge engine discovery
+- File operations
+"""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+from importlib import import_module
+
+
+def get_knowledge_service_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.api.http.service.knowledge')
+
+
+def create_mock_app():
+    """Create mock Application for testing."""
+    mock_app = Mock()
+    mock_app.logger = Mock()
+    mock_app.rag_mgr = AsyncMock()
+    mock_app.persistence_mgr = AsyncMock()
+    mock_app.persistence_mgr.execute_async = AsyncMock()
+    mock_app.persistence_mgr.serialize_model = Mock(return_value={})
+    mock_app.plugin_connector = AsyncMock()
+    mock_app.plugin_connector.is_enable_plugin = True
+    return mock_app
+
+
+class TestKnowledgeServiceInit:
+    """Tests for KnowledgeService initialization."""
+
+    def test_init_stores_app_reference(self):
+        """Test that __init__ stores Application reference."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        assert service.ap is mock_app
+
+
+class TestGetKnowledgeBases:
+    """Tests for get_knowledge_bases method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_all_kb_details(self):
+        """Test that it returns all knowledge base details."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_all_knowledge_base_details = AsyncMock(
+            return_value=[{'uuid': 'kb1', 'name': 'KB1'}]
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_knowledge_bases()
+
+        assert len(result) == 1
+        assert result[0]['uuid'] == 'kb1'
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_list_when_no_kbs(self):
+        """Test that it returns empty list when no knowledge bases."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_all_knowledge_base_details = AsyncMock(return_value=[])
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_knowledge_bases()
+
+        assert result == []
+
+
+class TestGetKnowledgeBase:
+    """Tests for get_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_kb_details_by_uuid(self):
+        """Test that it returns specific KB details."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(
+            return_value={'uuid': 'kb1', 'name': 'KB1'}
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_knowledge_base('kb1')
+
+        assert result['uuid'] == 'kb1'
+
+    @pytest.mark.asyncio
+    async def test_returns_none_when_not_found(self):
+        """Test that it returns None when KB not found."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(return_value=None)
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_knowledge_base('nonexistent')
+
+        assert result is None
+
+
+class TestCreateKnowledgeBase:
+    """Tests for create_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_creates_kb_with_required_fields(self):
+        """Test creating KB with required plugin ID."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_kb = Mock()
+        mock_kb.uuid = 'new_kb_uuid'
+        mock_app.rag_mgr.create_knowledge_base = AsyncMock(return_value=mock_kb)
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        kb_data = {
+            'name': 'Test KB',
+            'knowledge_engine_plugin_id': 'author/engine',
+            'description': 'Test description',
+        }
+
+        result = await service.create_knowledge_base(kb_data)
+
+        assert result == 'new_kb_uuid'
+        mock_app.rag_mgr.create_knowledge_base.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_raises_when_missing_plugin_id(self):
+        """Test that ValueError is raised when plugin ID missing."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        with pytest.raises(ValueError) as exc_info:
+            await service.create_knowledge_base({'name': 'Test'})
+
+        assert 'knowledge_engine_plugin_id is required' in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_creates_with_default_name(self):
+        """Test that KB is created with default name if not provided."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_kb = Mock()
+        mock_kb.uuid = 'new_kb_uuid'
+        mock_app.rag_mgr.create_knowledge_base = AsyncMock(return_value=mock_kb)
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        result = await service.create_knowledge_base({
+            'knowledge_engine_plugin_id': 'author/engine'
+        })
+
+        # Check that default name 'Untitled' was used
+        call_args = mock_app.rag_mgr.create_knowledge_base.call_args
+        assert call_args.kwargs['name'] == 'Untitled'
+
+
+class TestUpdateKnowledgeBase:
+    """Tests for update_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_updates_mutable_fields_only(self):
+        """Test that only mutable fields are updated."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(
+            return_value={'uuid': 'kb1', 'name': 'Updated'}
+        )
+        mock_app.rag_mgr.remove_knowledge_base_from_runtime = AsyncMock()
+        mock_app.rag_mgr.load_knowledge_base = AsyncMock()
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        # Pass both mutable and immutable fields
+        await service.update_knowledge_base('kb1', {
+            'name': 'New Name',
+            'description': 'New desc',
+            'uuid': 'should_be_filtered',  # immutable
+        })
+
+        # Check that only mutable fields were passed to update
+        call_args = mock_app.persistence_mgr.execute_async.call_args
+        assert call_args is not None
+
+    @pytest.mark.asyncio
+    async def test_returns_early_when_no_mutable_fields(self):
+        """Test that update returns early when no mutable fields provided."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        # Pass only immutable fields
+        await service.update_knowledge_base('kb1', {'uuid': 'should_be_filtered'})
+
+        # No DB update should be called
+        mock_app.persistence_mgr.execute_async.assert_not_called()
+
+
+class TestCheckDocCapability:
+    """Tests for _check_doc_capability method."""
+
+    @pytest.mark.asyncio
+    async def test_passes_when_capability_supported(self):
+        """Test that check passes when doc_ingestion capability exists."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(
+            return_value={'knowledge_engine': {'capabilities': ['doc_ingestion']}}
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        await service._check_doc_capability('kb1', 'document upload')
+
+        # No exception raised means success
+
+    @pytest.mark.asyncio
+    async def test_raises_when_kb_not_found(self):
+        """Test that Exception is raised when KB not found."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(return_value=None)
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        with pytest.raises(Exception) as exc_info:
+            await service._check_doc_capability('nonexistent', 'test operation')
+
+        assert 'Knowledge base not found' in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_raises_when_capability_not_supported(self):
+        """Test that Exception is raised when doc_ingestion not in capabilities."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.rag_mgr.get_knowledge_base_details = AsyncMock(
+            return_value={'knowledge_engine': {'capabilities': ['other_capability']}}
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+
+        with pytest.raises(Exception) as exc_info:
+            await service._check_doc_capability('kb1', 'document upload')
+
+        assert 'does not support document upload' in str(exc_info.value)
+
+
+class TestListKnowledgeEngines:
+    """Tests for list_knowledge_engines method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_engines_from_plugin_connector(self):
+        """Test that it returns knowledge engines from plugin connector."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'id': 'engine1', 'name': 'Engine 1'}]
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_knowledge_engines()
+
+        assert len(result) == 1
+        assert result[0]['id'] == 'engine1'
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_when_plugin_disabled(self):
+        """Test that it returns empty list when plugin disabled."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.is_enable_plugin = False
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_knowledge_engines()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_on_exception(self):
+        """Test that it returns empty list and logs warning on exception."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            side_effect=Exception('Connection error')
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_knowledge_engines()
+
+        assert result == []
+        mock_app.logger.warning.assert_called_once()
+
+
+class TestListParsers:
+    """Tests for list_parsers method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_all_parsers(self):
+        """Test that it returns all parsers when no MIME type filter."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.list_parsers = AsyncMock(
+            return_value=[
+                {'id': 'parser1', 'supported_mime_types': ['text/plain']},
+                {'id': 'parser2', 'supported_mime_types': ['application/pdf']},
+            ]
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_parsers()
+
+        assert len(result) == 2
+
+    @pytest.mark.asyncio
+    async def test_filters_by_mime_type(self):
+        """Test that it filters parsers by MIME type."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.list_parsers = AsyncMock(
+            return_value=[
+                {'id': 'parser1', 'supported_mime_types': ['text/plain']},
+                {'id': 'parser2', 'supported_mime_types': ['application/pdf']},
+            ]
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_parsers(mime_type='application/pdf')
+
+        assert len(result) == 1
+        assert result[0]['id'] == 'parser2'
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_when_plugin_disabled(self):
+        """Test that it returns empty list when plugin disabled."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.is_enable_plugin = False
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.list_parsers()
+
+        assert result == []
+
+
+class TestGetEngineSchemas:
+    """Tests for get_engine_creation_schema and get_engine_retrieval_schema."""
+
+    @pytest.mark.asyncio
+    async def test_returns_creation_schema(self):
+        """Test that it returns creation schema for engine."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.get_rag_creation_schema = AsyncMock(
+            return_value={'properties': {'name': {'type': 'string'}}}
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_engine_creation_schema('author/engine')
+
+        assert 'properties' in result
+
+    @pytest.mark.asyncio
+    async def test_returns_retrieval_schema(self):
+        """Test that it returns retrieval schema for engine."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.get_rag_retrieval_schema = AsyncMock(
+            return_value={'properties': {'top_k': {'type': 'integer'}}}
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_engine_retrieval_schema('author/engine')
+
+        assert 'properties' in result
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_dict_on_exception(self):
+        """Test that it returns empty dict and logs warning on exception."""
+        knowledge_module = get_knowledge_service_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.get_rag_creation_schema = AsyncMock(
+            side_effect=Exception('Plugin error')
+        )
+
+        service = knowledge_module.KnowledgeService(mock_app)
+        result = await service.get_engine_creation_schema('author/engine')
+
+        assert result == {}
+        mock_app.logger.warning.assert_called_once()

tests/unit_tests/core/test_app_config_validation.py

@@ -0,0 +1,192 @@
+"""Unit tests for core app config validation methods.
+
+Tests cover:
+- _get_positive_int_config() validation
+- _get_positive_float_config() validation
+"""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock
+from importlib import import_module
+
+
+def get_app_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.core.app')
+
+
+class TestGetPositiveIntConfig:
+    """Tests for _get_positive_int_config method."""
+
+    def test_returns_value_when_valid_positive_int(self):
+        """Test returns parsed int for valid positive value."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config(10, default=30, name='test.config')
+
+        assert result == 10
+        mock_logger.warning.assert_not_called()
+
+    def test_returns_value_when_valid_string_int(self):
+        """Test returns parsed int for string value."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config('50', default=30, name='test.config')
+
+        assert result == 50
+        mock_logger.warning.assert_not_called()
+
+    def test_returns_default_for_zero(self):
+        """Test returns default when value is zero."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config(0, default=30, name='test.config')
+
+        assert result == 30
+        mock_logger.warning.assert_called_once()
+
+    def test_returns_default_for_negative(self):
+        """Test returns default when value is negative."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config(-5, default=30, name='test.config')
+
+        assert result == 30
+        mock_logger.warning.assert_called_once()
+
+    def test_returns_default_for_invalid_string(self):
+        """Test returns default when value is invalid string."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config('invalid', default=30, name='test.config')
+
+        assert result == 30
+        mock_logger.warning.assert_called_once()
+
+    def test_returns_default_for_none(self):
+        """Test returns default when value is None."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_int_config(None, default=30, name='test.config')
+
+        assert result == 30
+        mock_logger.warning.assert_called_once()
+
+
+class TestGetPositiveFloatConfig:
+    """Tests for _get_positive_float_config method."""
+
+    def test_returns_value_when_valid_positive_float(self):
+        """Test returns parsed float for valid positive value."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config(1.5, default=2.0, name='test.config')
+
+        assert result == 1.5
+        mock_logger.warning.assert_not_called()
+
+    def test_returns_value_when_valid_int(self):
+        """Test returns float for valid int value."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config(2, default=1.0, name='test.config')
+
+        assert result == 2.0
+        mock_logger.warning.assert_not_called()
+
+    def test_returns_value_when_valid_string_float(self):
+        """Test returns parsed float for string value."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config('0.5', default=1.0, name='test.config')
+
+        assert result == 0.5
+        mock_logger.warning.assert_not_called()
+
+    def test_returns_default_for_zero(self):
+        """Test returns default when value is zero."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config(0.0, default=1.0, name='test.config')
+
+        assert result == 1.0
+        mock_logger.warning.assert_called_once()
+
+    def test_returns_default_for_negative(self):
+        """Test returns default when value is negative."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config(-1.0, default=2.0, name='test.config')
+
+        assert result == 2.0
+        mock_logger.warning.assert_called_once()
+
+    def test_returns_default_for_invalid_string(self):
+        """Test returns default when value is invalid string."""
+        app_module = get_app_module()
+
+        mock_logger = Mock()
+
+        app = app_module.Application()
+        app.logger = mock_logger
+
+        result = app._get_positive_float_config('not-a-number', default=1.5, name='test.config')
+
+        assert result == 1.5
+        mock_logger.warning.assert_called_once()

tests/unit_tests/core/test_load_config.py

@@ -0,0 +1,266 @@
+"""Unit tests for core stages load_config _apply_env_overrides_to_config.
+
+Tests cover:
+- Environment variable parsing and path conversion
+- Type conversion (bool, int, float, string)
+- List handling (comma-separated)
+- Dict type skipping
+- Missing key creation
+"""
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+from importlib import import_module
+
+
+def get_load_config_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.core.stages.load_config')
+
+
+class TestApplyEnvOverridesToConfig:
+    """Tests for _apply_env_overrides_to_config function."""
+
+    def test_override_string_value(self):
+        """Test overriding an existing string config value."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'name': 'default'}}
+        env = {'SYSTEM__NAME': 'custom_name'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['name'] == 'custom_name'
+
+    def test_override_int_value(self):
+        """Test overriding an int value with proper conversion."""
+        load_config = get_load_config_module()
+
+        cfg = {'concurrency': {'pipeline': 5}}
+        env = {'CONCURRENCY__PIPELINE': '10'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['concurrency']['pipeline'] == 10
+        assert isinstance(result['concurrency']['pipeline'], int)
+
+    def test_override_int_value_invalid_conversion(self):
+        """Test that invalid int conversion keeps string value."""
+        load_config = get_load_config_module()
+
+        cfg = {'concurrency': {'pipeline': 5}}
+        env = {'CONCURRENCY__PIPELINE': 'not_a_number'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        # Falls back to string when conversion fails
+        assert result['concurrency']['pipeline'] == 'not_a_number'
+
+    def test_override_bool_value_true(self):
+        """Test overriding bool value with 'true' string."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'enable': False}}
+        env = {'SYSTEM__ENABLE': 'true'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['enable'] is True
+
+    def test_override_bool_value_false(self):
+        """Test overriding bool value with 'false' string."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'enable': True}}
+        env = {'SYSTEM__ENABLE': 'false'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['enable'] is False
+
+    def test_override_bool_value_various_true_forms(self):
+        """Test that '1', 'yes', 'on' are treated as true."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'flag': False}}
+
+        for true_val in ['1', 'yes', 'on', 'TRUE']:
+            env = {'SYSTEM__FLAG': true_val}
+            with patch.dict(os.environ, env, clear=True):
+                result = load_config._apply_env_overrides_to_config(cfg.copy())
+                assert result['system']['flag'] is True
+
+    def test_override_float_value(self):
+        """Test overriding float value with proper conversion."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'timeout': 1.5}}
+        env = {'SYSTEM__TIMEOUT': '2.5'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['timeout'] == 2.5
+        assert isinstance(result['system']['timeout'], float)
+
+    def test_override_list_value(self):
+        """Test that comma-separated string converts to list."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'disabled_adapters': ['adapter1']}}
+        env = {'SYSTEM__DISABLED_ADAPTERS': 'aiocqhttp,dingtalk,telegram'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['disabled_adapters'] == ['aiocqhttp', 'dingtalk', 'telegram']
+
+    def test_override_list_value_empty_items(self):
+        """Test that empty items in comma-separated list are filtered."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'disabled_adapters': []}}
+        env = {'SYSTEM__DISABLED_ADAPTERS': 'a,,b,,,c'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        # Empty items should be filtered out
+        assert result['system']['disabled_adapters'] == ['a', 'b', 'c']
+
+    def test_skip_dict_type_override(self):
+        """Test that dict type values are skipped."""
+        load_config = get_load_config_module()
+
+        cfg = {'plugin': {'settings': {'nested': 'value'}}}
+        env = {'PLUGIN__SETTINGS': 'should_not_apply'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        # Dict type should not be overridden
+        assert result['plugin']['settings'] == {'nested': 'value'}
+
+    def test_create_new_key_when_missing(self):
+        """Test that missing keys are created as strings."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {}}
+        env = {'SYSTEM__NEW_KEY': 'new_value'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['new_key'] == 'new_value'
+
+    def test_create_nested_path(self):
+        """Test that intermediate dict is created for nested path."""
+        load_config = get_load_config_module()
+
+        cfg = {}
+        env = {'NEW__SECTION__KEY': 'value'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['new']['section']['key'] == 'value'
+
+    def test_skip_non_uppercase_env_vars(self):
+        """Test that non-uppercase env vars are skipped."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'name': 'default'}}
+        env = {'system__name': 'should_not_apply'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['name'] == 'default'
+
+    def test_skip_env_vars_without_double_underscore(self):
+        """Test that env vars without __ are skipped."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'name': 'default'}}
+        env = {'SYSTEMNAME': 'should_not_apply'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['name'] == 'default'
+
+    def test_nested_config_path(self):
+        """Test overriding deeply nested config."""
+        load_config = get_load_config_module()
+
+        cfg = {'level1': {'level2': {'level3': 'original'}}}
+        env = {'LEVEL1__LEVEL2__LEVEL3': 'overridden'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['level1']['level2']['level3'] == 'overridden'
+
+    def test_non_dict_current_breaks(self):
+        """Test that path navigation stops when current is not dict."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': 'not_a_dict'}
+        env = {'SYSTEM__NAME': 'should_not_apply'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        # Should remain unchanged since 'system' is not a dict
+        assert result == {'system': 'not_a_dict'}
+
+    def test_empty_config(self):
+        """Test that empty config dict is handled."""
+        load_config = get_load_config_module()
+
+        cfg = {}
+        env = {'SOME__KEY': 'value'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['some']['key'] == 'value'
+
+    def test_no_matching_env_vars(self):
+        """Test that config is unchanged when no matching env vars."""
+        load_config = get_load_config_module()
+
+        cfg = {'system': {'name': 'default'}}
+        env = {'OTHER_VAR': 'value'}
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result == cfg
+
+    def test_multiple_env_vars_override(self):
+        """Test multiple env vars applied in order."""
+        load_config = get_load_config_module()
+
+        cfg = {
+            'system': {'name': 'default', 'enable': True},
+            'concurrency': {'pipeline': 5}
+        }
+        env = {
+            'SYSTEM__NAME': 'custom',
+            'SYSTEM__ENABLE': 'false',
+            'CONCURRENCY__PIPELINE': '10'
+        }
+
+        with patch.dict(os.environ, env, clear=True):
+            result = load_config._apply_env_overrides_to_config(cfg)
+
+        assert result['system']['name'] == 'custom'
+        assert result['system']['enable'] is False
+        assert result['concurrency']['pipeline'] == 10

tests/unit_tests/core/test_taskmgr.py

@@ -1,524 +1,506 @@
+"""Unit tests for core TaskContext, TaskWrapper, and AsyncTaskManager.
+
+Tests cover:
+- TaskContext initialization, state tracking, serialization
+- TaskWrapper ID generation, to_dict serialization
+- AsyncTaskManager task creation, stats, pruning
+
+Note: Uses import_isolation to break circular import chains.
 """
-Unit tests for AsyncTaskManager and TaskWrapper.
-
-Tests cover async task lifecycle management:
-- Task scheduling and tracking
-- Task completion
-- Task exception handling
-- Task cancellation
-- Multiple task isolation
-
-Uses module pre-mocking to break circular import chain.
-"""
-
 from __future__ import annotations
 
 import pytest
 import asyncio
 import sys
-import enum
+from unittest.mock import Mock, MagicMock
-from unittest.mock import MagicMock
+from contextlib import contextmanager
-from importlib import import_module
+from typing import Generator
 
 
-# Pre-mock app module BEFORE importing taskmgr to break circular chain:
+class MockLifecycleControlScopeEnum:
-#   taskmgr → app → http_controller → groups/knowledge/migration → taskmgr (partial)
+    """Mock enum value for LifecycleControlScope with .value attribute."""
-class FakeMinimalApp:
+    def __init__(self, value: str):
-    """Minimal app that only provides event_loop."""
+        self.value = value
 
-    def __init__(self, event_loop):
+    def __repr__(self):
-        self.event_loop = event_loop
+        return f"LifecycleControlScope.{self.value.upper()}"
-        self.instance_config = MagicMock()
-        self.instance_config.data = {}
-
-# Pre-register mock app module
-_mock_app_module = MagicMock()
-_mock_app_module.Application = FakeMinimalApp
-sys.modules['langbot.pkg.core.app'] = _mock_app_module
-
-# Pre-register mock entities module - use proper Enum
-class LifecycleControlScope(enum.Enum):
-    APPLICATION = 'application'
-    PLATFORM = 'platform'
-    PLUGIN = 'plugin'
-    PROVIDER = 'provider'
-
-_mock_entities_module = MagicMock()
-_mock_entities_module.LifecycleControlScope = LifecycleControlScope
-sys.modules['langbot.pkg.core.entities'] = _mock_entities_module
 
 
-def get_taskmgr():
+class MockLifecycleControlScope:
-    """Import taskmgr after pre-mocking."""
+    """Mock enum for LifecycleControlScope."""
-    return import_module('langbot.pkg.core.taskmgr')
+    APPLICATION = MockLifecycleControlScopeEnum('application')
+    PLATFORM = MockLifecycleControlScopeEnum('platform')
+    PIPELINE = MockLifecycleControlScopeEnum('pipeline')
+    PLUGIN = MockLifecycleControlScopeEnum('plugin')
 
 
-def get_entities():
+@contextmanager
-    """Get pre-registered mock entities module."""
+def isolated_taskmgr_import() -> Generator[None, None, None]:
-    return sys.modules['langbot.pkg.core.entities']
+    """Context manager to isolate circular imports for taskmgr testing."""
+    # Mock modules that cause circular imports
+    mock_entities = MagicMock()
+    mock_entities.LifecycleControlScope = MockLifecycleControlScope
+    
+    mock_app = MagicMock()
+    
+    mock_importutil = MagicMock()
+    mock_importutil.import_modules_in_pkg = lambda pkg: None
+    mock_importutil.import_modules_in_pkgs = lambda pkgs: None
+    
+    mock_http_controller = MagicMock()
+    
+    mock_rag_mgr = MagicMock()
+    
+    mocks = {
+        'langbot.pkg.core.entities': mock_entities,
+        'langbot.pkg.core.app': mock_app,
+        'langbot.pkg.api.http.controller.main': mock_http_controller,
+        'langbot.pkg.rag.knowledge.kbmgr': mock_rag_mgr,
+        'langbot.pkg.utils.importutil': mock_importutil,
+    }
+    
+    # Save original state
+    saved = {}
+    for name in mocks:
+        if name in sys.modules:
+            saved[name] = sys.modules[name]
+    
+    # Clear taskmgr to force re-import
+    taskmgr_name = 'langbot.pkg.core.taskmgr'
+    if taskmgr_name in sys.modules:
+        saved[taskmgr_name] = sys.modules[taskmgr_name]
+    
+    try:
+        # Apply mocks
+        for name, module in mocks.items():
+            sys.modules[name] = module
+        
+        # Clear taskmgr
+        sys.modules.pop(taskmgr_name, None)
+        
+        yield
+    finally:
+        # Restore
+        for name in mocks:
+            if name in saved:
+                sys.modules[name] = saved[name]
+            else:
+                sys.modules.pop(name, None)
+        
+        if taskmgr_name in saved:
+            sys.modules[taskmgr_name] = saved[taskmgr_name]
+        else:
+            sys.modules.pop(taskmgr_name, None)
 
 
-class TestTaskContextReal:
+def get_taskmgr_classes():
-    """Tests for real TaskContext class (no circular import)."""
+    """Get TaskContext, TaskWrapper, AsyncTaskManager classes."""
+    with isolated_taskmgr_import():
+        from langbot.pkg.core.taskmgr import TaskContext, TaskWrapper, AsyncTaskManager
+        return TaskContext, TaskWrapper, AsyncTaskManager
 
-    @pytest.mark.asyncio
-    async def test_task_context_new(self):
-        """TaskContext.new() creates instance."""
-        taskmgr = get_taskmgr()
 
-        ctx = taskmgr.TaskContext.new()
+def create_mock_app():
+    """Create a mock Application for testing."""
+    mock_app = Mock()
+    mock_app.event_loop = asyncio.get_running_loop()
+    mock_app.instance_config = Mock()
+    mock_app.instance_config.data = {
+        'system': {
+            'task_retention': {
+                'completed_limit': 200,
+            }
+        }
+    }
+    return mock_app
+
+
+class TestTaskContext:
+    """Tests for TaskContext class."""
+
+    def test_init_default_values(self):
+        """Test that TaskContext initializes with default values."""
+        TaskContext, _, _ = get_taskmgr_classes()
+        ctx = TaskContext()
 
         assert ctx.current_action == 'default'
         assert ctx.log == ''
         assert ctx.metadata == {}
 
-    @pytest.mark.asyncio
+    def test_set_current_action(self):
-    async def test_task_context_trace(self):
+        """Test setting current action."""
-        """TaskContext.trace adds formatted log."""
+        TaskContext, _, _ = get_taskmgr_classes()
-        taskmgr = get_taskmgr()
+        ctx = TaskContext()
 
-        ctx = taskmgr.TaskContext.new()
+        ctx.set_current_action('installing_plugin')
-        ctx.trace('test message', action='test_action')
+        assert ctx.current_action == 'installing_plugin'
 
-        assert ctx.current_action == 'test_action'
+    def test_trace_without_action(self):
-        assert 'test message' in ctx.log
+        """Test trace method without action override."""
-        assert 'test_action' in ctx.log
+        TaskContext, _, _ = get_taskmgr_classes()
-        # Contains timestamp format
+        ctx = TaskContext()
-        assert '|' in ctx.log
 
-    @pytest.mark.asyncio
+        ctx.trace('Starting process')
-    async def test_task_context_multiple_traces(self):
+        assert 'Starting process' in ctx.log
-        """TaskContext accumulates multiple traces."""
+        assert ctx.current_action == 'default'
-        taskmgr = get_taskmgr()
 
-        ctx = taskmgr.TaskContext.new()
+    def test_trace_with_action_override(self):
-        ctx.trace('first')
+        """Test trace method with action override."""
-        ctx.trace('second')
+        TaskContext, _, _ = get_taskmgr_classes()
+        ctx = TaskContext()
 
-        assert 'first' in ctx.log
+        ctx.trace('Downloading', action='download')
-        assert 'second' in ctx.log
+        assert 'Downloading' in ctx.log
+        assert ctx.current_action == 'download'
 
-    @pytest.mark.asyncio
+    def test_trace_accumulates_logs(self):
-    async def test_task_context_to_dict(self):
+        """Test that trace accumulates log entries."""
-        """TaskContext.to_dict returns all fields."""
+        TaskContext, _, _ = get_taskmgr_classes()
-        taskmgr = get_taskmgr()
+        ctx = TaskContext()
 
-        ctx = taskmgr.TaskContext.new()
+        ctx.trace('Step 1')
-        ctx.trace('log entry')
+        ctx.trace('Step 2')
+        ctx.trace('Step 3')
+
+        assert 'Step 1' in ctx.log
+        assert 'Step 2' in ctx.log
+        assert 'Step 3' in ctx.log
+        # Each trace adds a newline
+        assert ctx.log.count('\n') == 3
+
+    def test_to_dict_serialization(self):
+        """Test to_dict serialization."""
+        TaskContext, _, _ = get_taskmgr_classes()
+        ctx = TaskContext()
+        ctx.set_current_action('test_action')
+        ctx.trace('Test message')
+        ctx.metadata['key'] = 'value'
 
         result = ctx.to_dict()
 
-        assert 'current_action' in result
+        assert result['current_action'] == 'test_action'
-        assert 'log' in result
+        assert 'Test message' in result['log']
-        assert 'metadata' in result
+        assert result['metadata'] == {'key': 'value'}
-        assert result['log'] == ctx.log
+
+    def test_static_new_factory(self):
+        """Test TaskContext.new() factory method."""
+        TaskContext, _, _ = get_taskmgr_classes()
+        ctx = TaskContext.new()
+
+        assert isinstance(ctx, TaskContext)
+        assert ctx.current_action == 'default'
+
+    def test_static_placeholder_singleton(self):
+        """Test TaskContext.placeholder() returns singleton."""
+        with isolated_taskmgr_import():
+            from langbot.pkg.core.taskmgr import TaskContext
+            
+            # Reset global placeholder
+            import langbot.pkg.core.taskmgr as taskmgr_module
+            taskmgr_module.placeholder_context = None
+
+            ctx1 = TaskContext.placeholder()
+            ctx2 = TaskContext.placeholder()
+
+            assert ctx1 is ctx2
+
+    def test_metadata_is_mutable_dict(self):
+        """Test that metadata is a mutable dict."""
+        TaskContext, _, _ = get_taskmgr_classes()
+        ctx = TaskContext()
+
+        ctx.metadata['count'] = 5
+        ctx.metadata['items'] = ['a', 'b', 'c']
+
+        assert ctx.metadata['count'] == 5
+        assert len(ctx.metadata['items']) == 3
+
+
+class TestTaskWrapper:
+    """Tests for TaskWrapper class."""
 
     @pytest.mark.asyncio
-    async def test_task_context_set_current_action(self):
+    async def test_id_auto_increment(self):
-        """set_current_action updates action."""
+        """Test that task IDs auto-increment."""
-        taskmgr = get_taskmgr()
+        TaskContext, TaskWrapper, _ = get_taskmgr_classes()
 
-        ctx = taskmgr.TaskContext.new()
+        # Reset ID index
-        ctx.set_current_action('new_action')
+        TaskWrapper._id_index = 0
 
-        assert ctx.current_action == 'new_action'
+        mock_app = create_mock_app()
 
-    @pytest.mark.asyncio
+        async def dummy_coro():
-    async def test_task_context_metadata(self):
+            await asyncio.sleep(0.01)
-        """TaskContext metadata can be set."""
-        taskmgr = get_taskmgr()
-
-        ctx = taskmgr.TaskContext.new()
-        ctx.metadata['key'] = 'value'
-
-        assert ctx.metadata['key'] == 'value'
-        assert ctx.to_dict()['metadata']['key'] == 'value'
-
-    def test_task_context_placeholder_singleton(self):
-        """placeholder returns same instance."""
-        taskmgr = get_taskmgr()
-
-        ctx1 = taskmgr.TaskContext.placeholder()
-        ctx2 = taskmgr.TaskContext.placeholder()
-
-        assert ctx1 is ctx2
-
-
-class TestTaskWrapperReal:
-    """Tests for real TaskWrapper class."""
-
-    @pytest.mark.asyncio
-    async def test_task_wrapper_creates_task(self):
-        """TaskWrapper creates and wraps asyncio.Task."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        async def simple_coro():
-            return 42
-
-        wrapper = taskmgr.TaskWrapper(app, simple_coro(), name='test')
-
-        assert wrapper.name == 'test'
-        assert wrapper.task is not None
-        assert isinstance(wrapper.task, asyncio.Task)
-
-        result = await wrapper.task
-        assert result == 42
-
-    @pytest.mark.asyncio
-    async def test_task_wrapper_with_custom_context(self):
-        """TaskWrapper uses provided TaskContext."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        ctx = taskmgr.TaskContext.new()
-        ctx.set_current_action('custom')
-
-        async def coro():
             return 'done'
 
-        wrapper = taskmgr.TaskWrapper(app, coro(), context=ctx)
+        wrapper1 = TaskWrapper(mock_app, dummy_coro())
+        wrapper2 = TaskWrapper(mock_app, dummy_coro())
 
-        assert wrapper.task_context.current_action == 'custom'
+        assert wrapper1.id == 0
+        assert wrapper2.id == 1
 
-        await wrapper.task
+        # Clean up
+        wrapper1.cancel()
+        wrapper2.cancel()
 
     @pytest.mark.asyncio
-    async def test_task_wrapper_exception_capture(self):
+    async def test_default_task_type_and_kind(self):
-        """TaskWrapper captures exception from failed task."""
+        """Test default task_type and kind values."""
-        taskmgr = get_taskmgr()
+        _, TaskWrapper, _ = get_taskmgr_classes()
+        mock_app = create_mock_app()
 
-        loop = asyncio.get_running_loop()
+        async def dummy_coro():
-        app = FakeMinimalApp(loop)
+            return 'done'
+
+        wrapper = TaskWrapper(mock_app, dummy_coro())
+
+        assert wrapper.task_type == 'system'
+        assert wrapper.kind == 'system_task'
+
+        wrapper.cancel()
+
+    @pytest.mark.asyncio
+    async def test_to_dict_serialization(self):
+        """Test TaskWrapper.to_dict serialization."""
+        _, TaskWrapper, _ = get_taskmgr_classes()
+        mock_app = create_mock_app()
+
+        async def immediate_coro():
+            return 'result'
+
+        wrapper = TaskWrapper(
+            mock_app, immediate_coro(),
+            name='test_task',
+            label='Test Task',
+        )
+
+        # Wait for task to complete
+        await wrapper.task
+
+        result = wrapper.to_dict()
+
+        assert result['name'] == 'test_task'
+        assert result['label'] == 'Test Task'
+        assert result['task_type'] == 'system'
+        assert result['runtime']['done'] == True
+        assert result['runtime']['result'] == 'result'
+
+    @pytest.mark.asyncio
+    async def test_to_dict_with_exception(self):
+        """Test TaskWrapper.to_dict when task has exception."""
+        _, TaskWrapper, _ = get_taskmgr_classes()
+        mock_app = create_mock_app()
 
         async def failing_coro():
-            raise ValueError('test error')
+            raise ValueError('Test error')
 
-        wrapper = taskmgr.TaskWrapper(app, failing_coro())
+        wrapper = TaskWrapper(mock_app, failing_coro())
 
-        # Let task complete with exception
+        # Wait for task to complete
-        await asyncio.sleep(0.01)
+        try:
+            await wrapper.task
+        except ValueError:
+            pass
 
-        exception = wrapper.assume_exception()
+        result = wrapper.to_dict()
-        assert exception is not None
+
-        assert isinstance(exception, ValueError)
+        assert result['runtime']['done'] == True
-        assert 'test error' in str(exception)
+        assert result['runtime']['exception'] == 'Test error'
+        assert 'exception_traceback' in result['runtime']
 
     @pytest.mark.asyncio
-    async def test_task_wrapper_result_capture(self):
+    async def test_cancel_task(self):
-        """TaskWrapper captures result from completed task."""
+        """Test cancel method cancels the asyncio task."""
-        taskmgr = get_taskmgr()
+        _, TaskWrapper, _ = get_taskmgr_classes()
-
+        mock_app = create_mock_app()
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        async def coro():
-            return 'result_value'
-
-        wrapper = taskmgr.TaskWrapper(app, coro())
-
-        await wrapper.task
-
-        result = wrapper.assume_result()
-        assert result == 'result_value'
-
-    @pytest.mark.asyncio
-    async def test_task_wrapper_cancel(self):
-        """TaskWrapper.cancel cancels the task."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
 
         async def long_coro():
             await asyncio.sleep(10)
             return 'done'
 
-        wrapper = taskmgr.TaskWrapper(app, long_coro())
+        wrapper = TaskWrapper(mock_app, long_coro())
+
+        # Task should be running
+        assert not wrapper.task.done()
 
         wrapper.cancel()
 
+        # Give it a moment to be cancelled
         await asyncio.sleep(0.01)
 
-        assert wrapper.task.cancelled() or wrapper.task.done()
+        assert wrapper.task.done()
+        assert wrapper.task.cancelled()
+
+
+class TestAsyncTaskManager:
+    """Tests for AsyncTaskManager class."""
 
     @pytest.mark.asyncio
-    async def test_task_wrapper_to_dict(self):
+    async def test_create_task_adds_to_list(self):
-        """TaskWrapper.to_dict serializes task info."""
+        """Test that create_task adds task to tasks list."""
-        taskmgr = get_taskmgr()
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
 
-        loop = asyncio.get_running_loop()
+        manager = AsyncTaskManager(mock_app)
-        app = FakeMinimalApp(loop)
 
-        async def coro():
+        async def dummy_coro():
-            return 42
+            await asyncio.sleep(0.01)
+            return 'done'
 
-        wrapper = taskmgr.TaskWrapper(app, coro(), name='dict_test', label='Test')
+        wrapper = manager.create_task(dummy_coro())
-
-        await wrapper.task
-
-        result = wrapper.to_dict()
-
-        assert result['name'] == 'dict_test'
-        assert result['label'] == 'Test'
-        assert 'runtime' in result
-        assert result['runtime']['done'] is True
-
-    @pytest.mark.asyncio
-    async def test_task_wrapper_id_increment(self):
-        """TaskWrapper IDs increment."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        async def coro():
-            return 1
-
-        wrapper1 = taskmgr.TaskWrapper(app, coro())
-        wrapper2 = taskmgr.TaskWrapper(app, coro())
-
-        assert wrapper2.id > wrapper1.id
-
-
-class TestAsyncTaskManagerReal:
-    """Tests for real AsyncTaskManager class."""
-
-    @pytest.mark.asyncio
-    async def test_manager_create_task(self):
-        """AsyncTaskManager creates and tracks tasks."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def coro():
-            return 'result'
-
-        wrapper = manager.create_task(coro(), name='test')
 
         assert wrapper in manager.tasks
-        assert wrapper.name == 'test'
+        assert len(manager.tasks) == 1
 
-        await wrapper.task
+        wrapper.cancel()
 
     @pytest.mark.asyncio
-    async def test_manager_create_user_task(self):
+    async def test_get_stats_counts_correctly(self):
-        """create_user_task creates user-type task."""
+        """Test get_stats returns correct counts."""
-        taskmgr = get_taskmgr()
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
 
-        loop = asyncio.get_running_loop()
+        manager = AsyncTaskManager(mock_app)
-        app = FakeMinimalApp(loop)
 
-        manager = taskmgr.AsyncTaskManager(app)
+        async def immediate_coro():
+            return 'done'
 
-        async def coro():
+        async def delayed_coro():
-            return 'user_result'
+            await asyncio.sleep(0.1)
+            return 'done'
 
-        wrapper = manager.create_user_task(coro())
+        # Create tasks
+        w1 = manager.create_task(immediate_coro())
+        w2 = manager.create_task(delayed_coro())
+
+        # Wait for first to complete
+        await w1.task
+
+        stats = manager.get_stats()
+
+        assert stats['total'] == 2
+        assert stats['completed'] == 1
+        assert stats['running'] == 1
+
+        w2.cancel()
+
+    @pytest.mark.asyncio
+    async def test_get_tasks_dict_filters_by_type(self):
+        """Test get_tasks_dict filters by type."""
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
+
+        manager = AsyncTaskManager(mock_app)
+
+        async def dummy_coro():
+            await asyncio.sleep(0.01)
+
+        # Create system and user tasks
+        w1 = manager.create_task(dummy_coro(), task_type='system')
+        w2 = manager.create_task(dummy_coro(), task_type='user')
+        w3 = manager.create_task(dummy_coro(), task_type='user')
+
+        result = manager.get_tasks_dict(type='user')
+
+        assert len(result['tasks']) == 2
+        for t in result['tasks']:
+            assert t['task_type'] == 'user'
+
+        w1.cancel()
+        w2.cancel()
+        w3.cancel()
+
+    @pytest.mark.asyncio
+    async def test_cancel_by_scope(self):
+        """Test cancel_by_scope cancels matching tasks."""
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        
+        mock_app = create_mock_app()
+        manager = AsyncTaskManager(mock_app)
+
+        async def long_coro():
+            await asyncio.sleep(10)
+
+        # Create task with APPLICATION scope
+        w1 = manager.create_task(
+            long_coro(),
+            scopes=[MockLifecycleControlScope.APPLICATION]
+        )
+
+        # Create task with different scope
+        w2 = manager.create_task(
+            long_coro(),
+            scopes=[MockLifecycleControlScope.PIPELINE]
+        )
+
+        manager.cancel_by_scope(MockLifecycleControlScope.APPLICATION)
+
+        await asyncio.sleep(0.01)
+
+        assert w1.task.cancelled() or w1.task.done()
+        assert not w2.task.done()
+
+        w2.cancel()
+
+    @pytest.mark.asyncio
+    async def test_cancel_task_by_id(self):
+        """Test cancel_task cancels specific task by ID."""
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
+
+        manager = AsyncTaskManager(mock_app)
+
+        async def long_coro():
+            await asyncio.sleep(10)
+
+        w1 = manager.create_task(long_coro())
+        w2 = manager.create_task(long_coro())
+
+        manager.cancel_task(w1.id)
+
+        await asyncio.sleep(0.01)
+
+        assert w1.task.done()
+        assert not w2.task.done()
+
+        w2.cancel()
+
+    @pytest.mark.asyncio
+    async def test_create_user_task_sets_user_type(self):
+        """Test create_user_task sets task_type to 'user'."""
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
+
+        manager = AsyncTaskManager(mock_app)
+
+        async def dummy_coro():
+            await asyncio.sleep(0.01)
+
+        wrapper = manager.create_user_task(dummy_coro())
 
         assert wrapper.task_type == 'user'
 
-        await wrapper.task
+        wrapper.cancel()
 
     @pytest.mark.asyncio
-    async def test_manager_multiple_tasks_isolated(self):
+    async def test_get_task_by_id(self):
-        """Multiple tasks run independently."""
+        """Test get_task_by_id returns correct task."""
-        taskmgr = get_taskmgr()
+        _, _, AsyncTaskManager = get_taskmgr_classes()
+        mock_app = create_mock_app()
 
-        loop = asyncio.get_running_loop()
+        manager = AsyncTaskManager(mock_app)
-        app = FakeMinimalApp(loop)
 
-        manager = taskmgr.AsyncTaskManager(app)
+        async def dummy_coro():
-
-        results = []
-
-        async def task_a():
-            results.append('a')
-
-        async def task_b():
-            results.append('b')
-
-        w1 = manager.create_task(task_a(), name='a')
-        w2 = manager.create_task(task_b(), name='b')
-
-        await asyncio.gather(w1.task, w2.task)
-
-        assert 'a' in results
-        assert 'b' in results
-
-    @pytest.mark.asyncio
-    async def test_manager_get_task_by_id(self):
-        """get_task_by_id finds task."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def coro():
-            return 1
-
-        wrapper = manager.create_task(coro())
-
-        found = manager.get_task_by_id(wrapper.id)
-        assert found is wrapper
-
-        not_found = manager.get_task_by_id(99999)
-        assert not_found is None
-
-    @pytest.mark.asyncio
-    async def test_manager_cancel_task(self):
-        """cancel_task cancels specific task."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def long():
-            await asyncio.sleep(10)
-
-        wrapper = manager.create_task(long())
-
-        manager.cancel_task(wrapper.id)
-
-        await asyncio.sleep(0.01)
-
-        assert wrapper.task.cancelled() or wrapper.task.done()
-
-    @pytest.mark.asyncio
-    async def test_manager_cancel_by_scope(self):
-        """cancel_by_scope cancels matching scope tasks."""
-        taskmgr = get_taskmgr()
-        entities = get_entities()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def long():
-            await asyncio.sleep(10)
-
-        async def app_long():
-            await asyncio.sleep(10)
-
-        # Create task with PLATFORM scope
-        platform_wrapper = manager.create_task(
-            long(),
-            scopes=[entities.LifecycleControlScope.PLATFORM],
-        )
-
-        # Create task with APPLICATION scope
-        manager.create_task(
-            app_long(),
-            scopes=[entities.LifecycleControlScope.APPLICATION],
-        )
-
-        manager.cancel_by_scope(entities.LifecycleControlScope.PLATFORM)
-
-        await asyncio.sleep(0.01)
-
-        # Platform task cancelled
-        assert platform_wrapper.task.cancelled() or platform_wrapper.task.done()
-
-    @pytest.mark.asyncio
-    async def test_manager_get_stats(self):
-        """get_stats returns task counts."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def quick():
-            return 1
-
-        for _ in range(3):
-            w = manager.create_task(quick())
-            await w.task
-
-        stats = manager.get_stats()
-
-        assert stats['total'] >= 3
-        assert stats['completed'] >= 3
-
-    @pytest.mark.asyncio
-    async def test_manager_get_tasks_dict(self):
-        """get_tasks_dict filters by type."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def coro():
-            return 1
-
-        system_w = manager.create_task(coro(), task_type='system')
-        user_w = manager.create_user_task(coro())
-
-        await asyncio.gather(system_w.task, user_w.task)
-
-        system_tasks = manager.get_tasks_dict(type='system')
-        assert all(t['task_type'] == 'system' for t in system_tasks['tasks'])
-
-    @pytest.mark.asyncio
-    async def test_manager_wait_all(self):
-        """wait_all waits for all tasks."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def delayed():
-            await asyncio.sleep(0.05)
-
-        for _ in range(3):
-            manager.create_task(delayed())
-
-        await manager.wait_all()
-
-        stats = manager.get_stats()
-        assert stats['running'] == 0
-
-
-class TestTaskPruningReal:
-    """Tests for real task pruning behavior."""
-
-    @pytest.mark.asyncio
-    async def test_prune_completed_tasks(self):
-        """Completed tasks are pruned when exceeding limit."""
-        taskmgr = get_taskmgr()
-
-        loop = asyncio.get_running_loop()
-        app = FakeMinimalApp(loop)
-        app.instance_config.data = {'system': {'task_retention': {'completed_limit': 3}}}
-
-        manager = taskmgr.AsyncTaskManager(app)
-
-        async def quick():
-            return 1
-
-        # Create more than limit
-        for _ in range(5):
-            w = manager.create_task(quick())
-            await w.task
             await asyncio.sleep(0.01)
 
-        # Completed count should be <= limit
+        w1 = manager.create_task(dummy_coro())
-        completed = sum(1 for w in manager.tasks if w.task.done())
+        w2 = manager.create_task(dummy_coro())
-        assert completed <= 3
+
+        found = manager.get_task_by_id(w1.id)
+        assert found is w1
+
+        not_found = manager.get_task_by_id(9999)
+        assert not_found is None
+
+        w1.cancel()
+        w2.cancel()

tests/unit_tests/persistence/test_database_decorator.py

@@ -0,0 +1,201 @@
+"""Unit tests for persistence database decorators.
+
+Tests cover:
+- manager_class decorator registration
+- Class attribute setting
+- preregistered_managers list population
+
+Note: Uses import isolation to break circular import chains.
+"""
+from __future__ import annotations
+
+import sys
+from unittest.mock import Mock, MagicMock
+from contextlib import contextmanager
+from typing import Generator
+
+
+@contextmanager
+def isolated_database_import() -> Generator[None, None, None]:
+    """Context manager to isolate circular imports for database testing."""
+    # Mock modules that cause circular imports
+    mock_app = MagicMock()
+
+    mock_importutil = MagicMock()
+    mock_importutil.import_modules_in_pkg = lambda pkg: None
+    mock_importutil.import_modules_in_pkgs = lambda pkgs: None
+
+    mock_mgr = MagicMock()
+
+    mocks = {
+        'langbot.pkg.core.app': mock_app,
+        'langbot.pkg.utils.importutil': mock_importutil,
+        'langbot.pkg.persistence.mgr': mock_mgr,
+    }
+
+    # Save original state
+    saved = {}
+    for name in mocks:
+        if name in sys.modules:
+            saved[name] = sys.modules[name]
+
+    # Clear database module to force re-import
+    database_name = 'langbot.pkg.persistence.database'
+    if database_name in sys.modules:
+        saved[database_name] = sys.modules[database_name]
+
+    # Also clear databases submodules
+    for sub in ['sqlite', 'postgresql']:
+        full_name = f'langbot.pkg.persistence.databases.{sub}'
+        if full_name in sys.modules:
+            saved[full_name] = sys.modules[full_name]
+
+    try:
+        # Apply mocks
+        for name, module in mocks.items():
+            sys.modules[name] = module
+
+        # Clear database and submodules
+        sys.modules.pop(database_name, None)
+        for sub in ['sqlite', 'postgresql']:
+            sys.modules.pop(f'langbot.pkg.persistence.databases.{sub}', None)
+
+        yield
+    finally:
+        # Restore
+        for name in mocks:
+            if name in saved:
+                sys.modules[name] = saved[name]
+            else:
+                sys.modules.pop(name, None)
+
+        if database_name in saved:
+            sys.modules[database_name] = saved[database_name]
+        else:
+            sys.modules.pop(database_name, None)
+
+        for sub in ['sqlite', 'postgresql']:
+            full_name = f'langbot.pkg.persistence.databases.{sub}'
+            if full_name in saved:
+                sys.modules[full_name] = saved[full_name]
+            else:
+                sys.modules.pop(full_name, None)
+
+
+def get_database_module():
+    """Get database module with import isolation."""
+    with isolated_database_import():
+        from langbot.pkg.persistence import database
+        return database
+
+
+class TestManagerClassDecorator:
+    """Tests for manager_class decorator."""
+
+    def test_decorator_sets_name_attribute(self):
+        """Test that decorator sets the 'name' attribute on class."""
+        database = get_database_module()
+
+        # Clear preregistered_managers for this test
+        database.preregistered_managers.clear()
+
+        @database.manager_class('test_db')
+        class TestManager(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        assert TestManager.name == 'test_db'
+
+    def test_decorator_adds_to_preregistered_list(self):
+        """Test that decorator adds class to preregistered_managers."""
+        database = get_database_module()
+
+        # Clear preregistered_managers for this test
+        database.preregistered_managers.clear()
+
+        @database.manager_class('test_db2')
+        class TestManager2(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        assert len(database.preregistered_managers) == 1
+        assert database.preregistered_managers[0] == TestManager2
+
+    def test_decorator_returns_original_class(self):
+        """Test that decorator returns the same class."""
+        database = get_database_module()
+
+        database.preregistered_managers.clear()
+
+        class OriginalClass(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        decorated = database.manager_class('test_db3')(OriginalClass)
+
+        assert decorated is OriginalClass
+
+    def test_multiple_decorators_register_separately(self):
+        """Test that multiple decorated classes register separately."""
+        database = get_database_module()
+
+        database.preregistered_managers.clear()
+
+        @database.manager_class('db_a')
+        class ManagerA(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        @database.manager_class('db_b')
+        class ManagerB(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        assert len(database.preregistered_managers) == 2
+        assert database.preregistered_managers[0].name == 'db_a'
+        assert database.preregistered_managers[1].name == 'db_b'
+
+    def test_base_database_manager_has_name_annotation(self):
+        """Test that BaseDatabaseManager has name as class annotation."""
+        database = get_database_module()
+
+        # BaseDatabaseManager has name annotation (type hint)
+        # Check __annotations__ for the type hint
+        assert 'name' in database.BaseDatabaseManager.__annotations__
+
+    def test_decorated_class_inherits_from_base(self):
+        """Test that decorated class properly inherits BaseDatabaseManager."""
+        database = get_database_module()
+
+        database.preregistered_managers.clear()
+
+        @database.manager_class('test_inherit')
+        class TestChild(database.BaseDatabaseManager):
+            async def initialize(self):
+                pass
+
+        assert issubclass(TestChild, database.BaseDatabaseManager)
+        # Has abstract method requirement satisfied
+        assert hasattr(TestChild, 'initialize')
+
+    def test_decorator_preserves_class_methods(self):
+        """Test that decorator preserves existing class methods."""
+        database = get_database_module()
+
+        database.preregistered_managers.clear()
+
+        @database.manager_class('preserve_test')
+        class ManagerWithMethods(database.BaseDatabaseManager):
+            custom_attr = 'test_value'
+
+            async def initialize(self):
+                pass
+
+            def custom_method(self):
+                return self.custom_attr
+
+        assert ManagerWithMethods.custom_attr == 'test_value'
+        # Create instance to test method (with mock app)
+        mock_app = Mock()
+        instance = ManagerWithMethods(mock_app)
+        assert instance.custom_method() == 'test_value'

tests/unit_tests/persistence/test_mgr_methods.py

@@ -0,0 +1,142 @@
+"""Unit tests for persistence manager methods.
+
+Tests cover:
+- execute_async() with mock database
+- get_db_engine() with mock database manager
+"""
+from __future__ import annotations
+
+import pytest
+from unittest.mock import Mock, AsyncMock, MagicMock
+from importlib import import_module
+import sqlalchemy
+
+
+def get_persistence_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.persistence.mgr')
+
+
+class TestExecuteAsync:
+    """Tests for execute_async method."""
+
+    @pytest.mark.asyncio
+    async def test_execute_async_calls_engine_execute(self):
+        """Test that execute_async calls engine execute."""
+        persistence = get_persistence_module()
+
+        mock_app = Mock()
+        mock_app.persistence_mgr = None
+
+        mgr = persistence.PersistenceManager(mock_app)
+
+        # Mock database manager with async engine
+        mock_engine = MagicMock()
+        mock_conn = AsyncMock()
+        mock_conn.execute = AsyncMock(return_value=Mock())
+        mock_conn.commit = AsyncMock()
+
+        # Setup the async context manager
+        async_cm = AsyncMock()
+        async_cm.__aenter__ = AsyncMock(return_value=mock_conn)
+        async_cm.__aexit__ = AsyncMock(return_value=None)
+        mock_engine.connect = Mock(return_value=async_cm)
+
+        mock_db = Mock()
+        mock_db.get_engine = Mock(return_value=mock_engine)
+        mgr.db = mock_db
+
+        # Execute a simple select
+        result = await mgr.execute_async(sqlalchemy.select(1))
+
+        mock_conn.execute.assert_called_once()
+        mock_conn.commit.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_execute_async_returns_result(self):
+        """Test that execute_async returns the result."""
+        persistence = get_persistence_module()
+
+        mock_app = Mock()
+        mgr = persistence.PersistenceManager(mock_app)
+
+        mock_result = Mock(name='query_result')
+
+        mock_engine = MagicMock()
+        mock_conn = AsyncMock()
+        mock_conn.execute = AsyncMock(return_value=mock_result)
+        mock_conn.commit = AsyncMock()
+
+        async_cm = AsyncMock()
+        async_cm.__aenter__ = AsyncMock(return_value=mock_conn)
+        async_cm.__aexit__ = AsyncMock(return_value=None)
+        mock_engine.connect = Mock(return_value=async_cm)
+
+        mock_db = Mock()
+        mock_db.get_engine = Mock(return_value=mock_engine)
+        mgr.db = mock_db
+
+        result = await mgr.execute_async(sqlalchemy.text("SELECT 1"))
+
+        assert result == mock_result
+
+
+class TestGetDbEngine:
+    """Tests for get_db_engine method."""
+
+    def test_get_db_engine_returns_engine_from_db_manager(self):
+        """Test that get_db_engine returns engine from db manager."""
+        persistence = get_persistence_module()
+
+        mock_app = Mock()
+        mgr = persistence.PersistenceManager(mock_app)
+
+        mock_engine = Mock(name='engine')
+        mock_db = Mock()
+        mock_db.get_engine = Mock(return_value=mock_engine)
+        mgr.db = mock_db
+
+        engine = mgr.get_db_engine()
+
+        assert engine == mock_engine
+        mock_db.get_engine.assert_called_once()
+
+    def test_get_db_engine_without_db_set_raises(self):
+        """Test that get_db_engine raises when db is not set."""
+        persistence = get_persistence_module()
+
+        mock_app = Mock()
+        mgr = persistence.PersistenceManager(mock_app)
+
+        # db is not initialized
+        mgr.db = None
+
+        with pytest.raises(AttributeError):
+            mgr.get_db_engine()
+
+
+class TestSerializeModelEdgeCases:
+    """Tests for serialize_model edge cases."""
+
+    def test_serialize_model_with_all_columns_masked(self):
+        """Test serialize_model when all columns are masked."""
+        persistence = get_persistence_module()
+
+        from sqlalchemy import Column, Integer, String
+        from sqlalchemy.orm import declarative_base
+
+        Base = declarative_base()
+
+        class SimpleModel(Base):
+            __tablename__ = 'simple'
+            id = Column(Integer, primary_key=True)
+            name = Column(String(50))
+
+        mock_app = Mock()
+        mgr = persistence.PersistenceManager(mock_app)
+
+        instance = SimpleModel(id=1, name='test')
+        result = mgr.serialize_model(SimpleModel, instance, masked_columns=['id', 'name'])
+
+        # Result should be empty dict when all columns masked
+        assert result == {}

tests/unit_tests/persistence/test_serialize_model.py

@@ -7,9 +7,7 @@ Tests cover:
 """
 from __future__ import annotations
 
-import pytest
 import datetime
-import sqlalchemy
 from sqlalchemy import Column, Integer, String, DateTime
 from sqlalchemy.orm import declarative_base
 from importlib import import_module

tests/unit_tests/pipeline/test_chat_session_limit.py

@@ -91,7 +91,11 @@ async def test_preprocessor_keeps_conversation_when_last_update_is_not_expired(m
 
 
 def test_expire_time_metadata_lives_under_ai_runner_not_safety():
-    metadata_dir = Path('src/langbot/templates/metadata/pipeline')
+    # Use path relative to test file location for portability
+    # test file: tests/unit_tests/pipeline/test_chat_session_limit.py
+    # project root: 4 levels up
+    project_root = Path(__file__).parent.parent.parent.parent
+    metadata_dir = project_root / 'src' / 'langbot' / 'templates' / 'metadata' / 'pipeline'
 
     ai_meta = yaml.safe_load((metadata_dir / 'ai.yaml').read_text())
     safety_meta = yaml.safe_load((metadata_dir / 'safety.yaml').read_text())

tests/unit_tests/plugin/test_connector_methods.py

@@ -0,0 +1,493 @@
+"""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
+
+
+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 len(result) == 1
+
+    @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 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 len(result) == 1
+
+
+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 len(result) == 1
+
+
+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()
+        assert 'results' in result
+
+    @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 'properties' in result
+
+    @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 'properties' in result
+
+    @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 'manifest' in result
+
+
+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) 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_extract_deps.py

@@ -0,0 +1,210 @@
+"""Unit tests for plugin connector _extract_deps_metadata 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 _extract_deps_metadata method."""
+
+    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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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._extract_deps_metadata(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_helpers.py

@@ -0,0 +1,127 @@
+"""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/rag/test_i18n_conversion.py

@@ -5,7 +5,6 @@ Tests cover:
 """
 from __future__ import annotations
 
-import pytest
 from importlib import import_module
 
 

tests/unit_tests/rag/test_kbmgr.py

@@ -0,0 +1,794 @@
+"""Unit tests for RAG knowledge base manager.
+
+Tests cover:
+- RAGManager CRUD operations
+- RuntimeKnowledgeBase getters
+- Knowledge engine enrichment
+- KB loading and removal
+"""
+from __future__ import annotations
+
+import pytest
+import uuid
+from unittest.mock import Mock, AsyncMock
+from importlib import import_module
+
+
+def get_rag_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.rag.knowledge.kbmgr')
+
+
+def create_mock_app():
+    """Create mock Application for testing."""
+    mock_app = Mock()
+    mock_app.logger = Mock()
+    mock_app.persistence_mgr = AsyncMock()
+    mock_app.persistence_mgr.execute_async = AsyncMock()
+    mock_app.persistence_mgr.serialize_model = Mock(return_value={})
+    mock_app.plugin_connector = AsyncMock()
+    mock_app.plugin_connector.is_enable_plugin = True
+    mock_app.storage_mgr = Mock()
+    mock_app.storage_mgr.storage_provider = AsyncMock()
+    mock_app.task_mgr = AsyncMock()
+    mock_app.task_mgr.create_user_task = Mock(return_value=Mock(id=1))
+    return mock_app
+
+
+def create_mock_kb_entity():
+    """Create mock KnowledgeBase entity."""
+    mock_kb = Mock()
+    mock_kb.uuid = str(uuid.uuid4())
+    mock_kb.name = 'Test KB'
+    mock_kb.description = 'Test description'
+    mock_kb.knowledge_engine_plugin_id = 'author/engine'
+    mock_kb.collection_id = mock_kb.uuid
+    mock_kb.creation_settings = {}
+    mock_kb.retrieval_settings = {}
+    return mock_kb
+
+
+class TestRAGManagerCreateKnowledgeBase:
+    """Tests for create_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_creates_kb_with_valid_engine(self):
+        """Test creates KB when engine plugin exists."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock valid engine list
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine'}]
+        )
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='author/engine',
+            creation_settings={'model': 'test'},
+        )
+
+        assert kb.name == 'Test KB'
+        assert kb.knowledge_engine_plugin_id == 'author/engine'
+
+    @pytest.mark.asyncio
+    async def test_raises_when_engine_not_found(self):
+        """Test raises ValueError when engine plugin not found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock empty engine list
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(return_value=[])
+
+        manager = rag_module.RAGManager(mock_app)
+
+        with pytest.raises(ValueError) as exc_info:
+            await manager.create_knowledge_base(
+                name='Test KB',
+                knowledge_engine_plugin_id='unknown/engine',
+                creation_settings={},
+            )
+
+        assert 'not found' in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_rollback_on_plugin_create_failure(self):
+        """Test that DB entry is rolled back when plugin create fails."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine'}]
+        )
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(
+            side_effect=Exception('Plugin error')
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+
+        with pytest.raises(Exception):
+            await manager.create_knowledge_base(
+                name='Test KB',
+                knowledge_engine_plugin_id='author/engine',
+                creation_settings={},
+            )
+
+        # Should have called delete to rollback
+        # Check that delete was called (for rollback)
+        assert len(manager.knowledge_bases) == 0
+
+    @pytest.mark.asyncio
+    async def test_sets_default_retrieval_settings(self):
+        """Test that empty retrieval_settings defaults to {}."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine'}]
+        )
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='author/engine',
+            creation_settings={},
+            retrieval_settings=None,
+        )
+
+        assert kb.retrieval_settings == {}
+
+    @pytest.mark.asyncio
+    async def test_skips_validation_when_plugin_disabled(self):
+        """Test that engine validation is skipped when plugin disabled."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.plugin_connector.is_enable_plugin = False
+        mock_app.persistence_mgr.execute_async = AsyncMock()
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        # Should not raise even though engine list would be empty
+        kb = await manager.create_knowledge_base(
+            name='Test KB',
+            knowledge_engine_plugin_id='any/engine',
+            creation_settings={},
+        )
+
+        assert kb.knowledge_engine_plugin_id == 'any/engine'
+
+
+class TestRuntimeKnowledgeBaseOnKBCreate:
+    """Tests for _on_kb_create method."""
+
+    @pytest.mark.asyncio
+    async def test_calls_plugin_on_create(self):
+        """Test that plugin is notified on KB create."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.creation_settings = {'model': 'test'}
+
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb._on_kb_create()
+
+        mock_app.plugin_connector.rag_on_kb_create.assert_called_once_with(
+            'author/engine', mock_kb.uuid, {'model': 'test'}
+        )
+
+    @pytest.mark.asyncio
+    async def test_skips_when_no_plugin_id(self):
+        """Test that create notification is skipped when no plugin."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb._on_kb_create()
+
+        mock_app.plugin_connector.rag_on_kb_create.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_raises_on_plugin_error(self):
+        """Test that exception is raised when plugin fails."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(
+            side_effect=Exception('Plugin failed')
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        with pytest.raises(Exception):
+            await runtime_kb._on_kb_create()
+
+
+class TestRuntimeKnowledgeBaseDeleteFile:
+    """Tests for delete_file method."""
+
+    @pytest.mark.asyncio
+    async def test_delete_file_calls_plugin_and_db(self):
+        """Test that delete_file calls plugin and removes DB record."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.call_rag_delete_document = AsyncMock(return_value=True)
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        await runtime_kb.delete_file('file-uuid')
+
+        mock_app.plugin_connector.call_rag_delete_document.assert_called_once()
+        mock_app.persistence_mgr.execute_async.assert_called()
+
+
+class TestRuntimeKnowledgeBaseIngestDocument:
+    """Tests for _ingest_document method."""
+
+    @pytest.mark.asyncio
+    async def test_ingest_calls_plugin(self):
+        """Test that ingest calls plugin connector."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.call_rag_ingest = AsyncMock(
+            return_value={'status': 'success'}
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        result = await runtime_kb._ingest_document(
+            {'filename': 'test.pdf'},
+            'storage/path',
+        )
+
+        assert result['status'] == 'success'
+        mock_app.plugin_connector.call_rag_ingest.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_ingest_raises_when_no_plugin_id(self):
+        """Test that ValueError is raised when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        with pytest.raises(ValueError) as exc_info:
+            await runtime_kb._ingest_document({'filename': 'test.pdf'}, 'path')
+
+        assert 'Plugin ID required' in str(exc_info.value)
+
+
+class TestRAGManagerLoadKnowledgeBasesFromDB:
+    """Tests for load_knowledge_bases_from_db method."""
+
+    @pytest.mark.asyncio
+    async def test_loads_all_kbs_from_db(self):
+        """Test that all KBs are loaded from database."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_kb1 = create_mock_kb_entity()
+        mock_kb2 = create_mock_kb_entity()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(all=Mock(return_value=[mock_kb1, mock_kb2]))
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        await manager.load_knowledge_bases_from_db()
+
+        assert len(manager.knowledge_bases) == 2
+
+    @pytest.mark.asyncio
+    async def test_handles_load_error_gracefully(self):
+        """Test that load errors are logged but not raised."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # KB that will cause initialize to fail
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(all=Mock(return_value=[mock_kb]))
+        )
+
+        # Make initialize fail by having plugin_connector throw error
+        mock_app.plugin_connector.rag_on_kb_create = AsyncMock(
+            side_effect=Exception('Init failed')
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        # Should not raise - errors are caught
+        await manager.load_knowledge_bases_from_db()
+
+        # KB should still be loaded (initialize just passes)
+        # The error would come from runtime_kb.initialize which we can't easily mock
+        # So we just verify it doesn't crash
+
+
+class TestRuntimeKnowledgeBaseGetters:
+    """Tests for RuntimeKnowledgeBase getter methods."""
+
+    def test_get_uuid_returns_entity_uuid(self):
+        """Test get_uuid returns KB entity UUID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_uuid() == mock_kb.uuid
+
+    def test_get_name_returns_entity_name(self):
+        """Test get_name returns KB entity name."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_name() == mock_kb.name
+
+    def test_get_knowledge_engine_plugin_id_returns_plugin_id(self):
+        """Test get_knowledge_engine_plugin_id returns plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_knowledge_engine_plugin_id() == 'author/engine'
+
+    def test_get_knowledge_engine_plugin_id_returns_empty_when_none(self):
+        """Test returns empty string when plugin_id is None."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        assert runtime_kb.get_knowledge_engine_plugin_id() == ''
+
+
+class TestRuntimeKnowledgeBaseRetrieve:
+    """Tests for RuntimeKnowledgeBase retrieve method."""
+
+    @pytest.mark.asyncio
+    async def test_retrieve_merges_settings(self):
+        """Test that retrieve merges stored and request settings."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.retrieval_settings = {'top_k': 10, 'model': 'default'}
+
+        # Mock plugin connector response with valid RetrievalResultEntry fields
+        # content must be list of ContentElement dicts
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(
+            return_value={
+                'results': [
+                    {
+                        'id': 'doc1',
+                        'content': [{'type': 'text', 'text': 'test content'}],
+                        'metadata': {},
+                        'distance': 0.1,
+                    }
+                ]
+            }
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        # Override top_k in request
+        results = await runtime_kb.retrieve('query text', settings={'top_k': 20})
+
+        assert len(results) == 1
+        # Check that merged settings were passed (top_k overridden)
+        call_args = mock_app.plugin_connector.call_rag_retrieve.call_args
+        assert call_args[0][1]['retrieval_settings']['top_k'] == 20
+
+    @pytest.mark.asyncio
+    async def test_retrieve_adds_default_top_k(self):
+        """Test that default top_k=5 is added when not specified."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.retrieval_settings = {}
+
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(
+            return_value={'results': []}
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.retrieve('query text')
+
+        call_args = mock_app.plugin_connector.call_rag_retrieve.call_args
+        assert call_args[0][1]['retrieval_settings']['top_k'] == 5
+
+    @pytest.mark.asyncio
+    async def test_retrieve_converts_dict_to_entry(self):
+        """Test that dict results are converted to RetrievalResultEntry."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        # Mock response with valid RetrievalResultEntry fields
+        # content must be list of ContentElement dicts
+        mock_app.plugin_connector.call_rag_retrieve = AsyncMock(
+            return_value={
+                'results': [
+                    {
+                        'id': 'doc1',
+                        'content': [{'type': 'text', 'text': 'test content'}],
+                        'metadata': {'source': 'file.pdf'},
+                        'distance': 0.15,
+                    }
+                ]
+            }
+        )
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        results = await runtime_kb.retrieve('query')
+
+        assert len(results) == 1
+        # Result should be RetrievalResultEntry
+        assert hasattr(results[0], 'content')
+        assert results[0].id == 'doc1'
+
+
+class TestRuntimeKnowledgeBaseDispose:
+    """Tests for RuntimeKnowledgeBase dispose method."""
+
+    @pytest.mark.asyncio
+    async def test_dispose_calls_on_kb_delete(self):
+        """Test that dispose calls _on_kb_delete."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+
+        mock_app.plugin_connector.rag_on_kb_delete = AsyncMock()
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.dispose()
+
+        mock_app.plugin_connector.rag_on_kb_delete.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_dispose_skips_when_no_plugin_id(self):
+        """Test that dispose skips when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_kb = create_mock_kb_entity()
+        mock_kb.knowledge_engine_plugin_id = None
+
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+
+        await runtime_kb.dispose()
+
+        # Should not call plugin connector
+        mock_app.plugin_connector.rag_on_kb_delete.assert_not_called()
+
+
+class TestRAGManagerInit:
+    """Tests for RAGManager initialization."""
+
+    def test_init_stores_app_reference(self):
+        """Test that __init__ stores Application reference."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        assert manager.ap is mock_app
+
+    def test_init_creates_empty_knowledge_bases_dict(self):
+        """Test that knowledge_bases starts as empty dict."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        assert manager.knowledge_bases == {}
+
+
+class TestRAGManagerGetKnowledgeBase:
+    """Tests for RAGManager get methods."""
+
+    @pytest.mark.asyncio
+    async def test_get_knowledge_base_by_uuid_returns_runtime_kb(self):
+        """Test get_knowledge_base_by_uuid returns loaded KB."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Manually add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        result = await manager.get_knowledge_base_by_uuid(mock_kb.uuid)
+
+        assert result is runtime_kb
+
+    @pytest.mark.asyncio
+    async def test_get_knowledge_base_by_uuid_returns_none_when_not_found(self):
+        """Test returns None when KB not in runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        result = await manager.get_knowledge_base_by_uuid('nonexistent-uuid')
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_remove_knowledge_base_from_runtime(self):
+        """Test remove_knowledge_base_from_runtime removes KB."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        await manager.remove_knowledge_base_from_runtime(mock_kb.uuid)
+
+        assert mock_kb.uuid not in manager.knowledge_bases
+
+
+class TestRAGManagerEnrichKB:
+    """Tests for _enrich_kb_dict method."""
+
+    def test_enrich_adds_engine_info_from_map(self):
+        """Test that engine info is added from engine_map."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'author/engine'}
+        engine_map = {
+            'author/engine': {
+                'plugin_id': 'author/engine',
+                'name': 'Test Engine',
+                'capabilities': ['doc_ingestion', 'search'],
+            }
+        }
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        assert kb_dict['knowledge_engine']['plugin_id'] == 'author/engine'
+        assert kb_dict['knowledge_engine']['capabilities'] == ['doc_ingestion', 'search']
+
+    def test_enrich_uses_fallback_when_engine_not_in_map(self):
+        """Test that fallback info is used when engine not found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'unknown/engine'}
+        engine_map = {}
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        assert kb_dict['knowledge_engine']['plugin_id'] == 'unknown/engine'
+        assert kb_dict['knowledge_engine']['capabilities'] == []
+
+    def test_enrich_uses_fallback_when_no_plugin_id(self):
+        """Test that fallback is used when no plugin ID."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {}
+        engine_map = {}
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        assert 'knowledge_engine' in kb_dict
+        # Should have Internal (Legacy) name
+        assert 'en_US' in kb_dict['knowledge_engine']['name']
+
+    def test_enrich_converts_string_name_to_i18n(self):
+        """Test that engine name is converted to i18n dict."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {'knowledge_engine_plugin_id': 'author/engine'}
+        engine_map = {
+            'author/engine': {
+                'plugin_id': 'author/engine',
+                'name': 'Simple Name',  # String, not dict
+                'capabilities': [],
+            }
+        }
+
+        manager._enrich_kb_dict(kb_dict, engine_map)
+
+        # Name should be converted to i18n dict
+        engine_name = kb_dict['knowledge_engine']['name']
+        assert isinstance(engine_name, dict)
+        assert engine_name['en_US'] == 'Simple Name'
+
+
+class TestRAGManagerDeleteKnowledgeBase:
+    """Tests for delete_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_delete_removes_from_runtime_and_disposes(self):
+        """Test that delete removes KB and calls dispose."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        # Add to knowledge_bases
+        runtime_kb = rag_module.RuntimeKnowledgeBase(mock_app, mock_kb)
+        manager.knowledge_bases[mock_kb.uuid] = runtime_kb
+
+        await manager.delete_knowledge_base(mock_kb.uuid)
+
+        assert mock_kb.uuid not in manager.knowledge_bases
+
+    @pytest.mark.asyncio
+    async def test_delete_logs_warning_when_not_in_runtime(self):
+        """Test that warning is logged when KB not in runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        await manager.delete_knowledge_base('nonexistent-uuid')
+
+        mock_app.logger.warning.assert_called_once()
+
+
+class TestRAGManagerGetAllDetails:
+    """Tests for get_all_knowledge_base_details method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_list_when_no_kbs(self):
+        """Test returns empty list when no knowledge bases."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(all=Mock(return_value=[]))
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_all_knowledge_base_details()
+
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_enriches_each_kb_with_engine_info(self):
+        """Test that each KB is enriched with engine info."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        # Mock DB result
+        mock_kb_row = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(all=Mock(return_value=[mock_kb_row]))
+        )
+        mock_app.persistence_mgr.serialize_model = Mock(
+            return_value={'uuid': 'kb1', 'knowledge_engine_plugin_id': 'author/engine'}
+        )
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine', 'capabilities': ['search']}]
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_all_knowledge_base_details()
+
+        assert len(result) == 1
+        assert 'knowledge_engine' in result[0]
+
+
+class TestRAGManagerGetDetails:
+    """Tests for get_knowledge_base_details method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_none_when_kb_not_found(self):
+        """Test returns None when KB doesn't exist."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(first=Mock(return_value=None))
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_knowledge_base_details('nonexistent')
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_returns_enriched_kb_dict(self):
+        """Test returns enriched KB dict when found."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        mock_kb_row = Mock()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(first=Mock(return_value=mock_kb_row))
+        )
+        mock_app.persistence_mgr.serialize_model = Mock(
+            return_value={'uuid': 'kb1', 'knowledge_engine_plugin_id': 'author/engine'}
+        )
+        mock_app.plugin_connector.list_knowledge_engines = AsyncMock(
+            return_value=[{'plugin_id': 'author/engine', 'name': 'Engine', 'capabilities': []}]
+        )
+
+        manager = rag_module.RAGManager(mock_app)
+        result = await manager.get_knowledge_base_details('kb1')
+
+        assert result is not None
+        assert 'knowledge_engine' in result
+
+
+class TestRAGManagerLoadKnowledgeBase:
+    """Tests for load_knowledge_base method."""
+
+    @pytest.mark.asyncio
+    async def test_loads_kb_entity_into_runtime(self):
+        """Test that KB entity is loaded into runtime."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+        mock_kb = create_mock_kb_entity()
+
+        result = await manager.load_knowledge_base(mock_kb)
+
+        assert mock_kb.uuid in manager.knowledge_bases
+        assert result.get_uuid() == mock_kb.uuid
+
+    @pytest.mark.asyncio
+    async def test_load_handles_dict_entity(self):
+        """Test that dict entity is converted to KB object."""
+        rag_module = get_rag_module()
+        mock_app = create_mock_app()
+
+        manager = rag_module.RAGManager(mock_app)
+
+        kb_dict = {
+            'uuid': 'kb-uuid',
+            'name': 'Test',
+            'knowledge_engine_plugin_id': 'author/engine',
+            'knowledge_engine': {'name': 'should_be_filtered'},  # non-db field
+        }
+
+        await manager.load_knowledge_base(kb_dict)
+
+        assert 'kb-uuid' in manager.knowledge_bases

tests/unit_tests/survey/test_survey_manager.py

@@ -0,0 +1,352 @@
+"""Unit tests for survey manager.
+
+Tests cover:
+- SurveyManager initialization
+- Event triggering and tracking
+- Pending survey fetching
+- Survey response submission
+- Survey dismissal
+"""
+from __future__ import annotations
+
+import pytest
+import json
+from unittest.mock import Mock, AsyncMock, MagicMock
+from importlib import import_module
+
+
+def get_survey_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.survey.manager')
+
+
+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 = {'space': {'url': 'https://space.example.com'}}
+    mock_app.persistence_mgr = AsyncMock()
+    mock_app.persistence_mgr.execute_async = AsyncMock()
+    return mock_app
+
+
+class TestSurveyManagerInit:
+    """Tests for SurveyManager initialization."""
+
+    def test_init_stores_app_reference(self):
+        """Test that __init__ stores Application reference."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+
+        assert manager.ap is mock_app
+
+    def test_init_creates_empty_triggered_events(self):
+        """Test that triggered_events starts as empty set."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+
+        assert manager._triggered_events == set()
+
+    def test_init_pending_survey_is_none(self):
+        """Test that pending_survey starts as None."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+
+        assert manager._pending_survey is None
+
+    @pytest.mark.asyncio
+    async def test_initialize_loads_space_url(self):
+        """Test that initialize loads space URL from config."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(first=Mock(return_value=None)))
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager.initialize()
+
+        assert manager._space_url == 'https://space.example.com'
+
+    @pytest.mark.asyncio
+    async def test_initialize_strips_trailing_slash_from_url(self):
+        """Test that trailing slash is stripped from URL."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'space': {'url': 'https://space.example.com/'}}
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(first=Mock(return_value=None)))
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager.initialize()
+
+        assert manager._space_url == 'https://space.example.com'
+
+    @pytest.mark.asyncio
+    async def test_initialize_handles_empty_space_config(self):
+        """Test that initialize handles empty space config."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {}
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=Mock(first=Mock(return_value=None)))
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager.initialize()
+
+        assert manager._space_url == ''
+
+
+class TestLoadTriggeredEvents:
+    """Tests for _load_triggered_events method."""
+
+    @pytest.mark.asyncio
+    async def test_loads_events_from_metadata(self):
+        """Test that events are loaded from metadata table."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        # Mock existing metadata row
+        mock_row = Mock()
+        mock_row.value = json.dumps(['event1', 'event2'])
+        mock_result = Mock()
+        mock_result.first = Mock(return_value=(mock_row,))
+        mock_app.persistence_mgr.execute_async = AsyncMock(return_value=mock_result)
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager._load_triggered_events()
+
+        assert 'event1' in manager._triggered_events
+        assert 'event2' in manager._triggered_events
+
+    @pytest.mark.asyncio
+    async def test_handles_no_existing_events(self):
+        """Test that empty set is used when no events stored."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(first=Mock(return_value=None))
+        )
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager._load_triggered_events()
+
+        assert manager._triggered_events == set()
+
+    @pytest.mark.asyncio
+    async def test_handles_exception(self):
+        """Test that exception results in empty set."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(side_effect=Exception('DB error'))
+
+        manager = survey_module.SurveyManager(mock_app)
+        await manager._load_triggered_events()
+
+        assert manager._triggered_events == set()
+
+
+class TestIsSpaceConfigured:
+    """Tests for _is_space_configured method."""
+
+    def test_returns_true_when_url_set(self):
+        """Test returns True when space URL is configured."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = 'https://space.example.com'
+
+        assert manager._is_space_configured() is True
+
+    def test_returns_false_when_url_empty(self):
+        """Test returns False when space URL is empty."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = ''
+
+        assert manager._is_space_configured() is False
+
+    def test_returns_false_when_telemetry_disabled(self):
+        """Test returns False when disable_telemetry is True."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.instance_config.data = {'space': {'url': 'https://space.example.com', 'disable_telemetry': True}}
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = 'https://space.example.com'
+
+        assert manager._is_space_configured() is False
+
+
+class TestTriggerEvent:
+    """Tests for trigger_event method."""
+
+    @pytest.mark.asyncio
+    async def test_skips_already_triggered_event(self):
+        """Test that already triggered events are skipped."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._triggered_events.add('event1')
+
+        await manager.trigger_event('event1')
+
+        # Should not call save
+        mock_app.persistence_mgr.execute_async.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_skips_when_space_not_configured(self):
+        """Test that event is skipped when space not configured."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = ''
+
+        await manager.trigger_event('new_event')
+
+        assert 'new_event' not in manager._triggered_events
+
+    @pytest.mark.asyncio
+    async def test_adds_new_event_and_saves(self):
+        """Test that new event is added and saved."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+        mock_app.persistence_mgr.execute_async = AsyncMock(
+            return_value=Mock(first=Mock(return_value=None))
+        )
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = 'https://space.example.com'
+
+        await manager.trigger_event('new_event')
+
+        assert 'new_event' in manager._triggered_events
+
+
+class TestPendingSurvey:
+    """Tests for get_pending_survey and clear_pending_survey."""
+
+    def test_returns_none_when_no_pending(self):
+        """Test returns None when no pending survey."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+
+        assert manager.get_pending_survey() is None
+
+    def test_returns_pending_survey(self):
+        """Test returns the pending survey."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._pending_survey = {'survey_id': '123', 'questions': []}
+
+        result = manager.get_pending_survey()
+
+        assert result['survey_id'] == '123'
+
+    def test_clear_pending_survey(self):
+        """Test that clear_pending_survey sets to None."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._pending_survey = {'survey_id': '123'}
+
+        manager.clear_pending_survey()
+
+        assert manager._pending_survey is None
+
+
+class TestSubmitResponse:
+    """Tests for submit_response method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_false_when_space_not_configured(self):
+        """Test returns False when space not configured."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = ''
+
+        result = await manager.submit_response('survey123', {'q1': 'answer1'})
+
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_clears_pending_on_success(self):
+        """Test that pending survey is cleared on success."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = 'https://space.example.com'
+        manager._pending_survey = {'survey_id': 'survey123'}
+
+        # Mock successful HTTP response
+        import httpx
+        mock_response = Mock()
+        mock_response.status_code = 200
+
+        with pytest.MonkeyPatch().context() as m:
+            m.setattr(httpx, 'AsyncClient', lambda **kwargs: MagicMock(
+                __aenter__=AsyncMock(return_value=Mock(post=AsyncMock(return_value=mock_response))),
+                __aexit__=AsyncMock(return_value=None)
+            ))
+            result = await manager.submit_response('survey123', {'q1': 'answer1'})
+
+        assert result is True
+        assert manager._pending_survey is None
+
+
+class TestDismissSurvey:
+    """Tests for dismiss_survey method."""
+
+    @pytest.mark.asyncio
+    async def test_returns_false_when_space_not_configured(self):
+        """Test returns False when space not configured."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = ''
+
+        result = await manager.dismiss_survey('survey123')
+
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_clears_pending_on_success(self):
+        """Test that pending survey is cleared on success."""
+        survey_module = get_survey_module()
+        mock_app = create_mock_app()
+
+        manager = survey_module.SurveyManager(mock_app)
+        manager._space_url = 'https://space.example.com'
+        manager._pending_survey = {'survey_id': 'survey123'}
+
+        # Mock successful HTTP response
+        import httpx
+        mock_response = Mock()
+        mock_response.status_code = 200
+
+        with pytest.MonkeyPatch().context() as m:
+            m.setattr(httpx, 'AsyncClient', lambda **kwargs: MagicMock(
+                __aenter__=AsyncMock(return_value=Mock(post=AsyncMock(return_value=mock_response))),
+                __aexit__=AsyncMock(return_value=None)
+            ))
+            result = await manager.dismiss_survey('survey123')
+
+        assert result is True
+        assert manager._pending_survey is None

tests/unit_tests/utils/test_funcschema.py

@@ -0,0 +1,191 @@
+"""Unit tests for utils funcschema.
+
+Tests cover:
+- get_func_schema() function
+- Docstring parsing
+- Parameter type extraction
+- Required parameter detection
+
+Note: Do NOT use 'from __future__ import annotations' because
+       funcschema.py expects actual type objects, not string annotations.
+"""
+import pytest
+from importlib import import_module
+
+
+def get_funcschema_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.utils.funcschema')
+
+
+class TestGetFuncSchema:
+    """Tests for get_func_schema function."""
+
+    def test_simple_function_schema(self):
+        """Test schema generation for simple function."""
+        funcschema = get_funcschema_module()
+
+        def simple_func(name: str, count: int):
+            """Simple function description.
+
+            Args:
+                name: The name parameter.
+                count: The count parameter.
+            """
+            pass
+
+        result = funcschema.get_func_schema(simple_func)
+
+        assert result['description'] == 'Simple function description.'
+        assert result['parameters']['type'] == 'object'
+        assert 'name' in result['parameters']['properties']
+        assert 'count' in result['parameters']['properties']
+        assert result['parameters']['properties']['name']['type'] == 'string'
+        assert result['parameters']['properties']['count']['type'] == 'integer'
+
+    def test_parameter_type_mapping(self):
+        """Test that Python types are mapped to JSON schema types."""
+        funcschema = get_funcschema_module()
+
+        def typed_func(a: str, b: int, c: float, d: bool, e: list, f: dict):
+            """Typed function.
+
+            Args:
+                a: String param.
+                b: Int param.
+                c: Float param.
+                d: Bool param.
+                e: List param.
+                f: Dict param.
+            """
+            pass
+
+        result = funcschema.get_func_schema(typed_func)
+
+        props = result['parameters']['properties']
+        assert props['a']['type'] == 'string'
+        assert props['b']['type'] == 'integer'
+        assert props['c']['type'] == 'number'
+        assert props['d']['type'] == 'boolean'
+        assert props['e']['type'] == 'array'
+        assert props['f']['type'] == 'object'
+
+    def test_required_parameters_detection(self):
+        """Test that required parameters are detected correctly."""
+        funcschema = get_funcschema_module()
+
+        def func_with_defaults(name: str, optional: str = 'default'):
+            """Function with default.
+
+            Args:
+                name: Required param.
+                optional: Optional param.
+            """
+            pass
+
+        result = funcschema.get_func_schema(func_with_defaults)
+
+        assert 'name' in result['parameters']['required']
+        assert 'optional' not in result['parameters']['required']
+
+    def test_self_and_query_excluded(self):
+        """Test that self and query parameters are excluded."""
+        funcschema = get_funcschema_module()
+
+        def method_func(self, query, other: str):
+            """Method function.
+
+            Args:
+                self: Self parameter.
+                query: Query parameter.
+                other: Other parameter.
+            """
+            pass
+
+        result = funcschema.get_func_schema(method_func)
+
+        props = result['parameters']['properties']
+        assert 'self' not in props
+        assert 'query' not in props
+        assert 'other' in props
+
+    def test_array_type_extraction(self):
+        """Test that list[T] types extract element type."""
+        funcschema = get_funcschema_module()
+
+        def list_func(items: list[str], numbers: list[int]):
+            """List function.
+
+            Args:
+                items: List of strings.
+                numbers: List of integers.
+            """
+            pass
+
+        result = funcschema.get_func_schema(list_func)
+
+        props = result['parameters']['properties']
+        assert props['items']['type'] == 'array'
+        assert props['items']['items']['type'] == 'string'
+        assert props['numbers']['type'] == 'array'
+        assert props['numbers']['items']['type'] == 'integer'
+
+    def test_function_without_docstring_raises(self):
+        """Test that function without docstring raises exception."""
+        funcschema = get_funcschema_module()
+
+        def no_doc_func(a: str):
+            pass
+
+        with pytest.raises(Exception) as exc_info:
+            funcschema.get_func_schema(no_doc_func)
+
+        assert 'has no docstring' in str(exc_info.value)
+
+    def test_description_extraction(self):
+        """Test that description is extracted from first paragraph."""
+        funcschema = get_funcschema_module()
+
+        def desc_func(a: str):
+            """This is the description.
+
+            Args:
+                a: Param a.
+            """
+            pass
+
+        result = funcschema.get_func_schema(desc_func)
+
+        assert result['description'] == 'This is the description.'
+
+    def test_function_reference_stored(self):
+        """Test that function reference is stored in schema."""
+        funcschema = get_funcschema_module()
+
+        def stored_func(a: str):
+            """Stored function.
+
+            Args:
+                a: Param a.
+            """
+            pass
+
+        result = funcschema.get_func_schema(stored_func)
+
+        assert result['function'] is stored_func
+
+    def test_description_from_args_doc(self):
+        """Test that arg description is extracted from docstring."""
+        funcschema = get_funcschema_module()
+
+        def doc_func(param_name: str):
+            """Function with documented param.
+
+            Args:
+                param_name: This is the param description.
+            """
+            pass
+
+        result = funcschema.get_func_schema(doc_func)
+
+        assert result['parameters']['properties']['param_name']['description'] == 'This is the param description.'

tests/unit_tests/utils/test_platform.py

@@ -0,0 +1,89 @@
+"""Unit tests for utils platform detection.
+
+Tests cover:
+- get_platform() function
+- Docker environment detection
+- WebSocket plugin runtime mode
+"""
+from __future__ import annotations
+
+import os
+import sys
+from unittest.mock import patch
+from importlib import import_module
+
+
+def get_platform_module():
+    """Lazy import to avoid circular import issues."""
+    return import_module('langbot.pkg.utils.platform')
+
+
+class TestGetPlatform:
+    """Tests for get_platform function."""
+
+    def test_returns_docker_when_dockerenv_exists(self):
+        """Test returns 'docker' when /.dockerenv file exists."""
+        platform_module = get_platform_module()
+
+        with patch('os.path.exists', return_value=True):
+            with patch.dict(os.environ, {}, clear=True):
+                result = platform_module.get_platform()
+                assert result == 'docker'
+
+    def test_returns_docker_when_env_var_true(self):
+        """Test returns 'docker' when DOCKER_ENV=true."""
+        platform_module = get_platform_module()
+
+        with patch('os.path.exists', return_value=False):
+            with patch.dict(os.environ, {'DOCKER_ENV': 'true'}, clear=True):
+                result = platform_module.get_platform()
+                assert result == 'docker'
+
+    def test_returns_sys_platform_when_not_docker(self):
+        """Test returns sys.platform when not in Docker."""
+        platform_module = get_platform_module()
+
+        with patch('os.path.exists', return_value=False):
+            with patch.dict(os.environ, {'DOCKER_ENV': 'false'}, clear=True):
+                result = platform_module.get_platform()
+                assert result == sys.platform
+
+    def test_returns_sys_platform_when_no_env_var(self):
+        """Test returns sys.platform when DOCKER_ENV not set."""
+        platform_module = get_platform_module()
+
+        with patch('os.path.exists', return_value=False):
+            # Make sure DOCKER_ENV is not set
+            env_copy = os.environ.copy()
+            if 'DOCKER_ENV' in env_copy:
+                del env_copy['DOCKER_ENV']
+            with patch.dict(os.environ, env_copy, clear=True):
+                result = platform_module.get_platform()
+                assert result == sys.platform
+
+    def test_standalone_runtime_default_false(self):
+        """Test standalone_runtime defaults to False."""
+        platform_module = get_platform_module()
+
+        # Check the module attribute
+        assert platform_module.standalone_runtime is False
+
+    def test_use_websocket_returns_standalone_runtime(self):
+        """Test use_websocket_to_connect_plugin_runtime returns standalone_runtime."""
+        platform_module = get_platform_module()
+
+        result = platform_module.use_websocket_to_connect_plugin_runtime()
+        assert result == platform_module.standalone_runtime
+
+    def test_standalone_runtime_can_be_modified(self):
+        """Test standalone_runtime can be modified."""
+        platform_module = get_platform_module()
+
+        original = platform_module.standalone_runtime
+
+        # Modify
+        platform_module.standalone_runtime = True
+        assert platform_module.use_websocket_to_connect_plugin_runtime() is True
+
+        # Restore
+        platform_module.standalone_runtime = original