chore: import upstream snapshot with attribution

tests/unit_tests/utils/__init__.py

@@ -0,0 +1 @@
+

tests/unit_tests/utils/test_funcschema.py

@@ -0,0 +1,209 @@
+"""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.'
+
+    def test_missing_parameter_doc_uses_empty_description(self):
+        """Undocumented parameters should not break schema generation."""
+        funcschema = get_funcschema_module()
+
+        def sample_function(documented: str, undocumented: int):
+            """Sample function.
+
+            Args:
+                documented(str): documented parameter description
+            """
+            pass
+
+        result = funcschema.get_func_schema(sample_function)
+
+        assert result['parameters']['properties']['documented']['description'] == 'documented parameter description'
+        assert result['parameters']['properties']['undocumented']['description'] == ''

tests/unit_tests/utils/test_httpclient.py

@@ -0,0 +1,146 @@
+"""
+Unit tests for HTTP client session pool.
+
+Tests session management, reuse, and cleanup.
+"""
+
+from __future__ import annotations
+
+import pytest
+import aiohttp
+from aiohttp import web
+
+from langbot.pkg.utils import httpclient
+
+
+pytestmark = pytest.mark.asyncio
+
+
+class TestGetSession:
+    """Tests for get_session function."""
+
+    async def test_get_session_returns_client_session(self):
+        """get_session returns an aiohttp.ClientSession."""
+        session = httpclient.get_session()
+
+        assert isinstance(session, aiohttp.ClientSession)
+        assert not session.closed
+
+        # Cleanup
+        await session.close()
+
+    async def test_get_session_returns_same_instance(self):
+        """get_session returns the same session for same trust_env."""
+        session1 = httpclient.get_session(trust_env=False)
+        session2 = httpclient.get_session(trust_env=False)
+
+        assert session1 is session2
+
+        # Cleanup
+        await session1.close()
+
+    async def test_get_session_different_trust_env_creates_different(self):
+        """Different trust_env values create different sessions."""
+        session1 = httpclient.get_session(trust_env=False)
+        session2 = httpclient.get_session(trust_env=True)
+
+        assert session1 is not session2
+
+        # Cleanup
+        await session1.close()
+        await session2.close()
+
+    async def test_get_session_recreates_if_closed(self):
+        """get_session creates new session if previous is closed."""
+        session1 = httpclient.get_session()
+        await session1.close()
+
+        session2 = httpclient.get_session()
+
+        assert session2 is not session1
+        assert not session2.closed
+
+        # Cleanup
+        await session2.close()
+
+
+class TestCloseAll:
+    """Tests for close_all function."""
+
+    async def test_close_all_closes_all_sessions(self):
+        """close_all closes all sessions."""
+        # Create multiple sessions
+        session1 = httpclient.get_session(trust_env=False)
+        session2 = httpclient.get_session(trust_env=True)
+
+        await httpclient.close_all()
+
+        assert session1.closed
+        assert session2.closed
+
+    async def test_close_all_clears_pool(self):
+        """close_all clears the session pool."""
+        httpclient.get_session()
+        httpclient.get_session(trust_env=True)
+
+        await httpclient.close_all()
+
+        assert len(httpclient._sessions) == 0
+
+    async def test_close_all_handles_already_closed(self):
+        """close_all handles already closed sessions gracefully."""
+        session = httpclient.get_session()
+        await session.close()
+
+        # Should not raise
+        await httpclient.close_all()
+
+    async def test_close_all_idempotent(self):
+        """close_all can be called multiple times."""
+        httpclient.get_session()
+
+        await httpclient.close_all()
+        await httpclient.close_all()  # Should not raise
+
+        assert len(httpclient._sessions) == 0
+
+
+class TestSessionPoolIntegration:
+    """Integration tests for session pool behavior."""
+
+    async def test_session_can_make_request(self):
+        """Session can be used for HTTP requests without relying on external network."""
+        app = web.Application()
+
+        async def handle_get(request):
+            return web.json_response({'ok': True})
+
+        app.router.add_get('/get', handle_get)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, '127.0.0.1', 0)
+        await site.start()
+        port = site._server.sockets[0].getsockname()[1]
+        session = httpclient.get_session()
+
+        try:
+            async with session.get(
+                f'http://127.0.0.1:{port}/get',
+                timeout=aiohttp.ClientTimeout(total=5),
+            ) as resp:
+                assert resp.status == 200
+                assert await resp.json() == {'ok': True}
+        finally:
+            await httpclient.close_all()
+            await runner.cleanup()
+
+    async def test_multiple_requests_same_session(self):
+        """Multiple requests can use the same session."""
+        session = httpclient.get_session()
+
+        # Both calls return the same session
+        session2 = httpclient.get_session()
+
+        assert session is session2
+
+        await httpclient.close_all()

tests/unit_tests/utils/test_image.py

@@ -0,0 +1,156 @@
+"""
+Unit tests for image utility functions.
+
+Tests URL parsing and base64 extraction without network calls.
+"""
+
+from __future__ import annotations
+
+import pytest
+import base64
+
+from langbot.pkg.utils.image import (
+    get_qq_image_downloadable_url,
+    extract_b64_and_format,
+)
+
+
+class TestGetQQImageDownloadableUrl:
+    """Tests for get_qq_image_downloadable_url function."""
+
+    def test_basic_url(self):
+        """Parse basic image URL."""
+        url = 'http://example.com/image.jpg'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        assert result_url == 'http://example.com/image.jpg'
+        assert query == {}
+
+    def test_url_with_query_params(self):
+        """Parse URL with query parameters."""
+        url = 'http://example.com/image.jpg?param1=value1&param2=value2'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        assert result_url == 'http://example.com/image.jpg'
+        assert query == {'param1': ['value1'], 'param2': ['value2']}
+
+    def test_url_with_port(self):
+        """Parse URL with port number."""
+        url = 'http://example.com:8080/image.jpg'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        assert result_url == 'http://example.com:8080/image.jpg'
+
+    def test_url_with_path(self):
+        """Parse URL with complex path."""
+        url = 'http://example.com/path/to/image.jpg'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        assert result_url == 'http://example.com/path/to/image.jpg'
+
+    def test_url_with_fragment(self):
+        """Parse URL with fragment (fragment is not part of query)."""
+        url = 'http://example.com/image.jpg#fragment'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        # Fragment is not included in query string parsing
+        assert 'http://example.com/image.jpg' in result_url
+
+    def test_https_url(self):
+        """Parse HTTPS URL and preserve its scheme."""
+        url = 'https://example.com/image.jpg'
+        result_url, query = get_qq_image_downloadable_url(url)
+
+        assert result_url == 'https://example.com/image.jpg'
+        assert query == {}
+
+    def test_preserves_qq_https_scheme_and_query(self):
+        """QQ image URLs keep HTTPS and query parameters."""
+        result_url, query = get_qq_image_downloadable_url('https://gchat.qpic.cn/gchatpic_new/abc/0?term=2&is_origin=1')
+
+        assert result_url == 'https://gchat.qpic.cn/gchatpic_new/abc/0'
+        assert query == {'term': ['2'], 'is_origin': ['1']}
+
+    def test_defaults_missing_scheme_to_http(self):
+        """Scheme-less image URLs default to HTTP."""
+        result_url, query = get_qq_image_downloadable_url('gchat.qpic.cn/gchatpic_new/abc/0?term=2')
+
+        assert result_url == 'http://gchat.qpic.cn/gchatpic_new/abc/0'
+        assert query == {'term': ['2']}
+
+
+class TestExtractB64AndFormat:
+    """Tests for extract_b64_and_format function."""
+
+    @pytest.mark.asyncio
+    async def test_jpeg_data_uri(self):
+        """Extract base64 and format from JPEG data URI."""
+        # Create a simple base64 string
+        original_data = b'test image data'
+        b64_data = base64.b64encode(original_data).decode()
+        data_uri = f'data:image/jpeg;base64,{b64_data}'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == b64_data
+        assert result_format == 'jpeg'
+
+    @pytest.mark.asyncio
+    async def test_png_data_uri(self):
+        """Extract base64 and format from PNG data URI."""
+        original_data = b'test png data'
+        b64_data = base64.b64encode(original_data).decode()
+        data_uri = f'data:image/png;base64,{b64_data}'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == b64_data
+        assert result_format == 'png'
+
+    @pytest.mark.asyncio
+    async def test_gif_data_uri(self):
+        """Extract base64 and format from GIF data URI."""
+        original_data = b'test gif data'
+        b64_data = base64.b64encode(original_data).decode()
+        data_uri = f'data:image/gif;base64,{b64_data}'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == b64_data
+        assert result_format == 'gif'
+
+    @pytest.mark.asyncio
+    async def test_webp_data_uri(self):
+        """Extract base64 and format from WebP data URI."""
+        original_data = b'test webp data'
+        b64_data = base64.b64encode(original_data).decode()
+        data_uri = f'data:image/webp;base64,{b64_data}'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == b64_data
+        assert result_format == 'webp'
+
+    @pytest.mark.asyncio
+    async def test_complex_base64(self):
+        """Handle base64 with special characters."""
+        # Base64 can include + and / characters
+        original_data = bytes(range(256))  # All byte values
+        b64_data = base64.b64encode(original_data).decode()
+        data_uri = f'data:image/png;base64,{b64_data}'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == b64_data
+        # Verify we can decode back to original
+        assert base64.b64decode(result_b64) == original_data
+
+    @pytest.mark.asyncio
+    async def test_empty_base64(self):
+        """Handle empty base64 string."""
+        data_uri = 'data:image/png;base64,'
+
+        result_b64, result_format = await extract_b64_and_format(data_uri)
+
+        assert result_b64 == ''
+        assert result_format == 'png'

tests/unit_tests/utils/test_importutil.py

@@ -0,0 +1,192 @@
+"""
+Tests for langbot.pkg.utils.importutil module.
+
+Tests import utility functions:
+- import_dir: imports modules from a directory
+- import_modules_in_pkg: imports all modules in a package
+- import_modules_in_pkgs: imports all modules in multiple packages
+- import_dot_style_dir: imports modules using dot notation path
+- read_resource_file: reads a text resource file
+- read_resource_file_bytes: reads a binary resource file
+- list_resource_files: lists files in a resource directory
+
+Uses mocking for import operations to avoid actual module imports.
+"""
+
+import pytest
+import importlib
+from unittest.mock import patch, MagicMock
+
+
+class TestImportDir:
+    """Test import_dir function."""
+
+    def test_calls_importlib_for_each_python_file(self, tmp_path):
+        """Should call importlib.import_module for each .py file."""
+        module_dir = tmp_path / 'test_modules'
+        module_dir.mkdir()
+
+        (module_dir / '__init__.py').write_text('')
+        (module_dir / 'module_a.py').write_text("VALUE_A = 'a'\n")
+        (module_dir / 'module_b.py').write_text("VALUE_B = 'b'\n")
+        (module_dir / 'readme.txt').write_text('not a module')
+
+        from langbot.pkg.utils import importutil
+
+        with patch.object(importlib, 'import_module') as mock_import:
+            importutil.import_dir(str(module_dir), path_prefix='test_prefix.')
+            # Should call import_module for each .py file (excluding __init__.py)
+            assert mock_import.call_count == 2
+
+    def test_skips_init_py(self, tmp_path):
+        """Should skip __init__.py when importing."""
+        module_dir = tmp_path / 'test_modules'
+        module_dir.mkdir()
+
+        (module_dir / '__init__.py').write_text('')
+        (module_dir / 'regular.py').write_text('VALUE = 1\n')
+
+        from langbot.pkg.utils import importutil
+
+        with patch.object(importlib, 'import_module') as mock_import:
+            importutil.import_dir(str(module_dir), path_prefix='test_prefix.')
+            # __init__.py should be skipped
+            mock_import.assert_called_once()
+            # The call should not include __init__
+            call_args = mock_import.call_args[0][0]
+            assert '__init__' not in call_args
+
+    def test_ignores_non_py_files(self, tmp_path):
+        """Should ignore non-.py files."""
+        module_dir = tmp_path / 'test_modules'
+        module_dir.mkdir()
+
+        (module_dir / 'module.py').write_text('VALUE = 1\n')
+        (module_dir / 'readme.txt').write_text('text')
+        (module_dir / 'data.json').write_text('{}')
+
+        from langbot.pkg.utils import importutil
+
+        with patch.object(importlib, 'import_module') as mock_import:
+            importutil.import_dir(str(module_dir), path_prefix='test_prefix.')
+            # Only .py files should be imported
+            assert mock_import.call_count == 1
+
+
+class TestImportModulesInPkg:
+    """Test import_modules_in_pkg function."""
+
+    def test_imports_modules_from_package(self, tmp_path):
+        """Should import all modules from a package object."""
+        mock_pkg = MagicMock()
+        mock_pkg.__file__ = str(tmp_path / '__init__.py')
+
+        (tmp_path / '__init__.py').write_text('')
+        (tmp_path / 'mod1.py').write_text('MOD1 = 1\n')
+
+        from langbot.pkg.utils import importutil
+
+        with patch.object(importutil, 'import_dir') as mock_import_dir:
+            importutil.import_modules_in_pkg(mock_pkg)
+            mock_import_dir.assert_called_once()
+            call_path = mock_import_dir.call_args[0][0]
+            assert call_path == str(tmp_path)
+
+
+class TestImportModulesInPkgs:
+    """Test import_modules_in_pkgs function."""
+
+    def test_imports_from_multiple_packages(self):
+        """Should call import_modules_in_pkg for each package."""
+        from langbot.pkg.utils import importutil
+
+        mock_pkg1 = MagicMock()
+        mock_pkg1.__file__ = '/path/to/pkg1/__init__.py'
+        mock_pkg2 = MagicMock()
+        mock_pkg2.__file__ = '/path/to/pkg2/__init__.py'
+
+        with patch.object(importutil, 'import_modules_in_pkg') as mock_import:
+            importutil.import_modules_in_pkgs([mock_pkg1, mock_pkg2])
+            assert mock_import.call_count == 2
+
+
+class TestImportDotStyleDir:
+    """Test import_dot_style_dir function."""
+
+    def test_converts_dot_notation_to_path(self, tmp_path):
+        """Should convert dot notation to path and import."""
+        # Create structure matching the dot notation
+        (tmp_path / 'my').mkdir()
+        (tmp_path / 'my' / 'pkg').mkdir()
+        (tmp_path / 'my' / 'pkg' / 'test').mkdir()
+
+        from langbot.pkg.utils import importutil
+
+        with patch.object(importutil, 'import_dir') as mock_import_dir:
+            importutil.import_dot_style_dir('my.pkg.test')
+            # The path should be converted using os.path.join
+            call_path = mock_import_dir.call_args[0][0]
+            # Should contain the path components joined
+            assert 'my' in call_path
+
+
+class TestReadResourceFile:
+    """Test read_resource_file function."""
+
+    def test_reads_resource_file_content(self):
+        """Should read content from a resource file."""
+        from langbot.pkg.utils import importutil
+
+        content = importutil.read_resource_file('templates/config.yaml')
+        assert 'api:' in content
+        assert 'edition: community' in content
+
+    def test_raises_for_nonexistent_file(self):
+        """Should raise exception for non-existent resource file."""
+        from langbot.pkg.utils import importutil
+
+        with pytest.raises((FileNotFoundError, Exception)):
+            importutil.read_resource_file('nonexistent/path/file.txt')
+
+
+class TestReadResourceFileBytes:
+    """Test read_resource_file_bytes function."""
+
+    def test_reads_resource_file_as_bytes(self):
+        """Should read content as bytes from a resource file."""
+        from langbot.pkg.utils import importutil
+
+        content = importutil.read_resource_file_bytes('templates/config.yaml')
+        assert b'api:' in content
+        assert b'edition: community' in content
+
+    def test_raises_for_nonexistent_file_bytes(self):
+        """Should raise exception for non-existent resource file."""
+        from langbot.pkg.utils import importutil
+
+        with pytest.raises((FileNotFoundError, Exception)):
+            importutil.read_resource_file_bytes('nonexistent/path/file.txt')
+
+
+class TestListResourceFiles:
+    """Test list_resource_files function."""
+
+    def test_lists_files_in_resource_directory(self):
+        """Should list files in a resource directory."""
+        from langbot.pkg.utils import importutil
+
+        files = importutil.list_resource_files('templates')
+        assert 'config.yaml' in files
+        assert 'default-pipeline-config.json' in files
+        assert all(isinstance(file, str) for file in files)
+
+    def test_raises_for_nonexistent_directory(self):
+        """Should raise exception for non-existent directory."""
+        from langbot.pkg.utils import importutil
+
+        with pytest.raises((FileNotFoundError, Exception)):
+            importutil.list_resource_files('nonexistent_directory_xyz')
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

tests/unit_tests/utils/test_logcache.py

@@ -0,0 +1,210 @@
+"""
+Unit tests for log cache utilities.
+
+Tests log page management and pointer-based retrieval.
+"""
+
+from __future__ import annotations
+
+
+from langbot.pkg.utils.logcache import LogPage, LogCache, LOG_PAGE_SIZE, MAX_CACHED_PAGES
+
+
+class TestLogPage:
+    """Tests for LogPage class."""
+
+    def test_init_creates_empty_page(self):
+        """LogPage initializes with empty logs list."""
+        page = LogPage(number=0)
+
+        assert page.number == 0
+        assert page.logs == []
+
+    def test_add_log_appends_to_list(self):
+        """add_log appends log to the list."""
+        page = LogPage(number=0)
+
+        page.add_log('log entry 1')
+        page.add_log('log entry 2')
+
+        assert len(page.logs) == 2
+        assert page.logs[0] == 'log entry 1'
+        assert page.logs[1] == 'log entry 2'
+
+    def test_add_log_returns_false_when_not_full(self):
+        """add_log returns False when page is not full."""
+        page = LogPage(number=0)
+
+        for i in range(LOG_PAGE_SIZE - 1):
+            result = page.add_log(f'log {i}')
+            assert result is False
+
+    def test_add_log_returns_true_when_full(self):
+        """add_log returns True when page reaches LOG_PAGE_SIZE."""
+        page = LogPage(number=0)
+
+        for i in range(LOG_PAGE_SIZE - 1):
+            page.add_log(f'log {i}')
+
+        result = page.add_log('last log')
+        assert result is True
+
+    def test_add_log_exactly_page_size(self):
+        """Page contains exactly LOG_PAGE_SIZE logs when full."""
+        page = LogPage(number=0)
+
+        for i in range(LOG_PAGE_SIZE):
+            page.add_log(f'log {i}')
+
+        assert len(page.logs) == LOG_PAGE_SIZE
+
+
+class TestLogCache:
+    """Tests for LogCache class."""
+
+    def test_init_creates_first_page(self):
+        """LogCache initializes with first empty page."""
+        cache = LogCache()
+
+        assert len(cache.log_pages) == 1
+        assert cache.log_pages[0].number == 0
+        assert cache.log_pages[0].logs == []
+
+    def test_add_log_to_first_page(self):
+        """add_log adds to the first page initially."""
+        cache = LogCache()
+
+        cache.add_log('test log')
+
+        assert len(cache.log_pages) == 1
+        assert cache.log_pages[0].logs[0] == 'test log'
+
+    def test_add_log_creates_new_page_when_full(self):
+        """add_log creates new page when current page is full."""
+        cache = LogCache()
+
+        # Fill first page
+        for i in range(LOG_PAGE_SIZE):
+            cache.add_log(f'log {i}')
+
+        # Add one more to trigger new page
+        cache.add_log('overflow log')
+
+        assert len(cache.log_pages) == 2
+        assert cache.log_pages[1].number == 1
+        assert cache.log_pages[1].logs[0] == 'overflow log'
+
+    def test_add_log_removes_oldest_page_when_exceeds_max(self):
+        """Cache removes oldest page when exceeding MAX_CACHED_PAGES."""
+        cache = LogCache()
+
+        # Fill enough pages to exceed MAX_CACHED_PAGES
+        total_logs = (MAX_CACHED_PAGES + 1) * LOG_PAGE_SIZE
+        for i in range(total_logs):
+            cache.add_log(f'log {i}')
+
+        # Should have exactly MAX_CACHED_PAGES pages
+        assert len(cache.log_pages) == MAX_CACHED_PAGES
+
+        # First page should not be page 0
+        assert cache.log_pages[0].number > 0
+
+    def test_get_log_by_pointer_single_page(self):
+        """get_log_by_pointer retrieves logs from single page."""
+        cache = LogCache()
+
+        cache.add_log('log 1')
+        cache.add_log('log 2')
+        cache.add_log('log 3')
+
+        result, page_num, offset = cache.get_log_by_pointer(0, 0)
+
+        assert 'log 1' in result
+        assert 'log 2' in result
+        assert 'log 3' in result
+
+    def test_get_log_by_pointer_with_offset(self):
+        """get_log_by_pointer respects start offset."""
+        cache = LogCache()
+
+        cache.add_log('log 1')
+        cache.add_log('log 2')
+        cache.add_log('log 3')
+
+        result, page_num, offset = cache.get_log_by_pointer(0, 1)
+
+        assert 'log 1' not in result
+        assert 'log 2' in result
+        assert 'log 3' in result
+
+    def test_get_log_by_pointer_across_pages(self):
+        """get_log_by_pointer retrieves logs across pages."""
+        cache = LogCache()
+
+        # Fill first page and add to second
+        for i in range(LOG_PAGE_SIZE):
+            cache.add_log(f'page0 log {i}')
+        cache.add_log('page1 log 0')
+
+        # Get from first page offset 0
+        result, page_num, offset = cache.get_log_by_pointer(0, 0)
+
+        # Should contain all logs from page 0 and page 1
+        assert 'page0 log 0' in result
+        assert 'page1 log 0' in result
+
+    def test_get_log_by_pointer_from_second_page(self):
+        """get_log_by_pointer can start from second page."""
+        cache = LogCache()
+
+        # Fill first page and add to second
+        for i in range(LOG_PAGE_SIZE):
+            cache.add_log(f'page0 log {i}')
+        cache.add_log('page1 log 0')
+
+        # Get from second page
+        result, page_num, offset = cache.get_log_by_pointer(1, 0)
+
+        assert 'page0' not in result
+        assert 'page1 log 0' in result
+
+    def test_page_numbers_sequential(self):
+        """Page numbers are sequential."""
+        cache = LogCache()
+
+        # Create multiple pages
+        for i in range(LOG_PAGE_SIZE * 3):
+            cache.add_log(f'log {i}')
+
+        for i, page in enumerate(cache.log_pages):
+            assert page.number == i
+
+    def test_empty_cache_get_log(self):
+        """get_log_by_pointer works with empty cache."""
+        cache = LogCache()
+
+        result, page_num, offset = cache.get_log_by_pointer(0, 0)
+
+        assert result == ''
+
+    def test_get_log_by_pointer_nonexistent_page(self):
+        """get_log_by_pointer handles nonexistent page number."""
+        cache = LogCache()
+
+        cache.add_log('log 1')
+
+        # Request page that doesn't exist
+        result, page_num, offset = cache.get_log_by_pointer(99, 0)
+
+        # Returns empty or last available
+        # Behavior depends on implementation
+
+    def test_max_cached_pages_constant(self):
+        """MAX_CACHED_PAGES is defined and reasonable."""
+        assert MAX_CACHED_PAGES > 0
+        assert MAX_CACHED_PAGES <= 100  # Reasonable upper bound
+
+    def test_log_page_size_constant(self):
+        """LOG_PAGE_SIZE is defined and reasonable."""
+        assert LOG_PAGE_SIZE > 0
+        assert LOG_PAGE_SIZE <= 1000  # Reasonable upper bound

tests/unit_tests/utils/test_paths.py

@@ -0,0 +1,184 @@
+"""
+Tests for langbot.pkg.utils.paths module.
+
+Tests path utility functions:
+- get_frontend_path: locates frontend build files
+- get_resource_path: locates resource files
+- _check_if_source_install: detects source install mode
+
+Uses tmp_path for file system isolation where applicable.
+"""
+
+import os
+import pytest
+
+
+class TestCheckIfSourceInstall:
+    """Test _check_if_source_install function."""
+
+    def test_returns_true_for_source_install(self, tmp_path, monkeypatch):
+        """Should return True when main.py with LangBot marker exists."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n# This is the entry point')
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths._check_if_source_install()
+        assert result is True
+
+        paths._is_source_install = None
+
+    # Note: ``_check_if_source_install`` was refactored to walk
+    # ``Path(__file__).resolve().parents`` looking for ``pyproject.toml`` +
+    # ``main.py`` instead of relying on the cwd. That makes it robust to where
+    # the process is launched from but also means the old "cwd doesn't have
+    # main.py" / "main.py without marker" / "IOError on read" cases no longer
+    # apply — there's no file read at all. The corresponding negative tests
+    # were removed; ``test_returns_true_for_source_install`` still exercises
+    # the positive path because the repo checkout itself is a source install.
+
+
+class TestGetFrontendPath:
+    """Test get_frontend_path function."""
+
+    def test_returns_web_dist_by_default(self):
+        """Should return a path containing web/dist as default."""
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_frontend_path()
+        # The result should contain web/dist or be an absolute path to it
+        assert 'web/dist' in result or result.endswith('dist')
+
+        paths._is_source_install = None
+
+    def test_finds_dist_directory_in_source_mode(self, tmp_path, monkeypatch):
+        """Should find web/dist when running from source mode."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n')
+
+        web_dist = tmp_path / 'web' / 'dist'
+        web_dist.mkdir(parents=True)
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_frontend_path()
+        assert result == 'web/dist'
+
+        paths._is_source_install = None
+
+    def test_prefers_dist_over_out_in_source_mode(self, tmp_path, monkeypatch):
+        """Should prefer web/dist over web/out when both exist in source mode."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n')
+
+        web_dist = tmp_path / 'web' / 'dist'
+        web_dist.mkdir(parents=True)
+        web_out = tmp_path / 'web' / 'out'
+        web_out.mkdir(parents=True)
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_frontend_path()
+        assert result == 'web/dist'
+
+        paths._is_source_install = None
+
+
+class TestGetResourcePath:
+    """Test get_resource_path function."""
+
+    def test_returns_original_path_when_not_found(self, tmp_path, monkeypatch):
+        """Should return original path when resource not found."""
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_resource_path('nonexistent/file.txt')
+        assert result == 'nonexistent/file.txt'
+
+        paths._is_source_install = None
+
+    def test_finds_resource_in_current_directory_source_mode(self, tmp_path, monkeypatch):
+        """Should find resource in current directory when in source mode."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n')
+
+        resource_file = tmp_path / 'templates' / 'config.yaml'
+        resource_file.parent.mkdir(parents=True, exist_ok=True)
+        resource_file.write_text('test: value')
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_resource_path('templates/config.yaml')
+        assert os.path.exists(result)
+
+        paths._is_source_install = None
+
+    def test_returns_relative_path_in_source_mode(self, tmp_path, monkeypatch):
+        """Should return relative path if resource exists in source mode."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n')
+
+        resource_file = tmp_path / 'test_resource.txt'
+        resource_file.write_text('test content')
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        result = paths.get_resource_path('test_resource.txt')
+        assert result == 'test_resource.txt'
+
+        paths._is_source_install = None
+
+
+class TestPathFunctionsCaching:
+    """Test that path functions use caching correctly."""
+
+    def test_source_install_cache_is_used(self, tmp_path, monkeypatch):
+        """_check_if_source_install should use cached result."""
+        main_py = tmp_path / 'main.py'
+        main_py.write_text('# LangBot/main.py\n')
+
+        monkeypatch.chdir(tmp_path)
+
+        from langbot.pkg.utils import paths
+
+        paths._is_source_install = None
+
+        # First call sets cache
+        result1 = paths._check_if_source_install()
+        assert result1 is True
+        assert paths._is_source_install is True
+
+        # Second call uses cache (no file read needed)
+        result2 = paths._check_if_source_install()
+        assert result2 is True
+
+        paths._is_source_install = None
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

tests/unit_tests/utils/test_pkgmgr.py

@@ -0,0 +1,157 @@
+"""
+Unit tests for package manager utilities.
+
+Tests pip command generation without actual installation.
+"""
+
+from __future__ import annotations
+
+import inspect
+from unittest.mock import patch
+
+from langbot.pkg.utils import pkgmgr
+
+
+class TestPkgMgr:
+    """Tests for package manager functions."""
+
+    def test_install_calls_pipmain(self):
+        """install calls pipmain with correct arguments."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install('requests')
+
+            mock_pipmain.assert_called_once_with(['install', 'requests'])
+
+    def test_install_with_version(self):
+        """install handles package with version specifier."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install('requests>=2.0.0')
+
+            mock_pipmain.assert_called_once_with(['install', 'requests>=2.0.0'])
+
+    def test_install_upgrade_calls_pipmain(self):
+        """install_upgrade calls pipmain with upgrade and mirror."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install_upgrade('requests')
+
+            expected_args = [
+                'install',
+                '--upgrade',
+                'requests',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ]
+            mock_pipmain.assert_called_once_with(expected_args)
+
+    def test_run_pip_with_params(self):
+        """run_pip passes params to pipmain."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.run_pip(['list', '--outdated'])
+
+            mock_pipmain.assert_called_once_with(['list', '--outdated'])
+
+    def test_run_pip_empty_params(self):
+        """run_pip handles empty params."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.run_pip([])
+
+            mock_pipmain.assert_called_once_with([])
+
+    def test_install_requirements_calls_pipmain(self):
+        """install_requirements calls pipmain with requirements file."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install_requirements('requirements.txt')
+
+            expected_args = [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ]
+            mock_pipmain.assert_called_once_with(expected_args)
+
+    def test_install_requirements_defaults_extra_params_to_none(self):
+        """install_requirements should not use a mutable default for extra_params."""
+        signature = inspect.signature(pkgmgr.install_requirements)
+
+        assert signature.parameters['extra_params'].default is None
+
+    def test_install_requirements_omitted_extra_params_uses_independent_base_commands(self, monkeypatch):
+        """Omitted extra_params should not share mutable state across calls."""
+        calls = []
+        monkeypatch.setattr(pkgmgr, 'pipmain', calls.append)
+
+        pkgmgr.install_requirements('requirements.txt')
+        pkgmgr.install_requirements('requirements-dev.txt')
+
+        assert calls == [
+            [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ],
+            [
+                'install',
+                '-r',
+                'requirements-dev.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+            ],
+        ]
+
+    def test_install_requirements_preserves_explicit_extra_params(self, monkeypatch):
+        """Explicit extra_params should be appended to the generated pip command."""
+        calls = []
+        monkeypatch.setattr(pkgmgr, 'pipmain', calls.append)
+
+        pkgmgr.install_requirements('requirements.txt', extra_params=['--no-deps'])
+
+        assert calls == [
+            [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+                '--no-deps',
+            ]
+        ]
+
+    def test_install_requirements_with_extra_params(self):
+        """install_requirements handles extra params."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install_requirements('requirements.txt', ['--no-cache-dir'])
+
+            expected_args = [
+                'install',
+                '-r',
+                'requirements.txt',
+                '-i',
+                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                '--trusted-host',
+                'pypi.tuna.tsinghua.edu.cn',
+                '--no-cache-dir',
+            ]
+            mock_pipmain.assert_called_once_with(expected_args)
+
+    def test_install_requirements_multiple_extra_params(self):
+        """install_requirements handles multiple extra params."""
+        with patch('langbot.pkg.utils.pkgmgr.pipmain') as mock_pipmain:
+            pkgmgr.install_requirements('requirements.txt', ['--no-cache-dir', '--verbose'])
+
+            call_args = mock_pipmain.call_args[0][0]
+            assert '--no-cache-dir' in call_args
+            assert '--verbose' in call_args

tests/unit_tests/utils/test_platform.py

@@ -0,0 +1,90 @@
+"""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

tests/unit_tests/utils/test_proxy.py

@@ -0,0 +1,173 @@
+"""
+Unit tests for ProxyManager.
+
+Tests proxy configuration from environment and config.
+"""
+
+from __future__ import annotations
+
+import pytest
+import os
+from unittest.mock import Mock, patch
+
+from langbot.pkg.utils.proxy import ProxyManager
+
+
+pytestmark = pytest.mark.asyncio
+
+
+class TestProxyManager:
+    """Tests for ProxyManager class."""
+
+    def _create_mock_app(self, proxy_config: dict = None):
+        """Create mock app with proxy config."""
+        mock_app = Mock()
+        mock_app.instance_config = Mock()
+        mock_app.instance_config.data = {'proxy': proxy_config or {}}
+        return mock_app
+
+    def test_init_creates_empty_proxies(self):
+        """ProxyManager initializes with empty forward_proxies."""
+        mock_app = self._create_mock_app()
+        pm = ProxyManager(mock_app)
+
+        assert pm.forward_proxies == {}
+
+    async def test_initialize_reads_env_variables(self):
+        """initialize reads HTTP_PROXY from environment."""
+        mock_app = self._create_mock_app()
+
+        with patch.dict(os.environ, {'HTTP_PROXY': 'http://env-proxy:8080', 'HTTPS_PROXY': 'https://env-proxy:8443'}):
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] == 'http://env-proxy:8080'
+            assert pm.forward_proxies['https://'] == 'https://env-proxy:8443'
+
+    async def test_initialize_reads_lower_case_env(self):
+        """initialize reads lower case http_proxy from environment."""
+        mock_app = self._create_mock_app()
+
+        with patch.dict(os.environ, {'http_proxy': 'http://lower-proxy:8080'}, clear=True):
+            # Clear HTTP_PROXY to test fallback
+            if 'HTTP_PROXY' in os.environ:
+                del os.environ['HTTP_PROXY']
+
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] == 'http://lower-proxy:8080'
+
+    async def test_initialize_config_overrides_env(self):
+        """Config proxy overrides environment variables."""
+        mock_app = self._create_mock_app(
+            proxy_config={
+                'http': 'http://config-proxy:8080',
+                'https': 'https://config-proxy:8443',
+            }
+        )
+
+        with patch.dict(os.environ, {'HTTP_PROXY': 'http://env-proxy:8080'}):
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] == 'http://config-proxy:8080'
+            assert pm.forward_proxies['https://'] == 'https://config-proxy:8443'
+
+    async def test_initialize_sets_env_variables(self):
+        """initialize sets proxy to environment variables."""
+        mock_app = self._create_mock_app(
+            proxy_config={
+                'http': 'http://test-proxy:8080',
+                'https': 'https://test-proxy:8443',
+            }
+        )
+
+        pm = ProxyManager(mock_app)
+        await pm.initialize()
+
+        assert os.environ.get('HTTP_PROXY') == 'http://test-proxy:8080'
+        assert os.environ.get('HTTPS_PROXY') == 'https://test-proxy:8443'
+
+    async def test_initialize_handles_empty_config(self):
+        """initialize handles empty proxy config."""
+        mock_app = self._create_mock_app(proxy_config={})
+
+        with patch.dict(os.environ, clear=True):
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] is None
+            assert pm.forward_proxies['https://'] is None
+
+    async def test_initialize_handles_no_env_no_config(self):
+        """initialize handles no env and no config."""
+        mock_app = self._create_mock_app(proxy_config={})
+
+        # Clear proxy env vars
+        env_backup = {}
+        for key in ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']:
+            env_backup[key] = os.environ.get(key)
+            if key in os.environ:
+                del os.environ[key]
+
+        try:
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] is None
+            assert pm.forward_proxies['https://'] is None
+        finally:
+            # Restore env
+            for key, value in env_backup.items():
+                if value is not None:
+                    os.environ[key] = value
+
+    def test_get_forward_proxies_returns_copy(self):
+        """get_forward_proxies returns a copy of the dict."""
+        mock_app = self._create_mock_app()
+        pm = ProxyManager(mock_app)
+        pm.forward_proxies = {'http://': 'http://test:8080'}
+
+        result = pm.get_forward_proxies()
+
+        assert result == pm.forward_proxies
+        assert result is not pm.forward_proxies  # Different object
+
+    def test_get_forward_proxies_modification_safe(self):
+        """Modifying returned dict doesn't affect internal state."""
+        mock_app = self._create_mock_app()
+        pm = ProxyManager(mock_app)
+        pm.forward_proxies = {'http://': 'http://test:8080'}
+
+        result = pm.get_forward_proxies()
+        result['http://'] = 'http://modified:9999'
+
+        assert pm.forward_proxies['http://'] == 'http://test:8080'
+
+    async def test_initialize_http_only_config(self):
+        """initialize handles http-only config."""
+        mock_app = self._create_mock_app(
+            proxy_config={
+                'http': 'http://http-only:8080',
+            }
+        )
+
+        # Clear any existing proxy env vars
+        env_backup = {}
+        for key in ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy']:
+            env_backup[key] = os.environ.get(key)
+            if key in os.environ:
+                del os.environ[key]
+
+        try:
+            pm = ProxyManager(mock_app)
+            await pm.initialize()
+
+            assert pm.forward_proxies['http://'] == 'http://http-only:8080'
+            assert pm.forward_proxies['https://'] is None
+        finally:
+            # Restore env
+            for key, value in env_backup.items():
+                if value is not None:
+                    os.environ[key] = value

tests/unit_tests/utils/test_runner.py

@@ -0,0 +1,308 @@
+"""
+Tests for langbot.pkg.utils.runner module.
+
+Tests runner category detection functions:
+- get_runner_category: categorizes runner URLs as local, cloud, or unknown
+- is_cloud_runner / is_local_runner: helper functions
+- extract_runner_url: extracts URL from runner config
+- get_runner_info: returns runner info dict
+"""
+
+import pytest
+from unittest.mock import Mock, patch
+
+from langbot.pkg.utils.runner import (
+    RunnerCategory,
+    CLOUD_DOMAINS,
+    LOCAL_PATTERNS,
+    get_runner_category,
+    get_runner_info,
+    is_cloud_runner,
+    is_local_runner,
+    extract_runner_url,
+    get_runner_category_from_runner,
+)
+
+
+class TestGetRunnerCategory:
+    """Test runner category detection from URL."""
+
+    def test_empty_url_returns_unknown(self):
+        """Empty or None URL should return UNKNOWN."""
+        assert get_runner_category('test', '') == RunnerCategory.UNKNOWN
+        assert get_runner_category('test', None) == RunnerCategory.UNKNOWN
+
+    def test_localhost_returns_local(self):
+        """localhost URL should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://localhost:3000') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'https://localhost') == RunnerCategory.LOCAL
+
+    def test_127_0_0_1_returns_local(self):
+        """127.0.0.1 URL should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://127.0.0.1:8080') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'https://127.0.0.1') == RunnerCategory.LOCAL
+
+    def test_0_0_0_0_returns_local(self):
+        """0.0.0.0 URL should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://0.0.0.0:8080') == RunnerCategory.LOCAL
+
+    def test_private_ip_192_168_returns_local(self):
+        """192.168.x.x private IP should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://192.168.1.1:3000') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'http://192.168.0.100') == RunnerCategory.LOCAL
+
+    def test_private_ip_10_returns_local(self):
+        """10.x.x.x private IP should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://10.0.0.1:8080') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'http://10.255.255.255') == RunnerCategory.LOCAL
+
+    def test_private_ip_172_16_31_returns_local(self):
+        """172.16.x.x - 172.31.x.x private IP range should be categorized as LOCAL."""
+        assert get_runner_category('test', 'http://172.16.0.1:8080') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'http://172.20.0.1') == RunnerCategory.LOCAL
+        assert get_runner_category('test', 'http://172.31.255.255') == RunnerCategory.LOCAL
+
+    def test_n8n_cloud_returns_cloud(self):
+        """n8n.cloud domain should be categorized as CLOUD."""
+        assert get_runner_category('test', 'https://myinstance.n8n.cloud') == RunnerCategory.CLOUD
+        assert get_runner_category('test', 'https://test.n8n.io') == RunnerCategory.CLOUD
+
+    def test_dify_cloud_returns_cloud(self):
+        """Dify cloud domains should be categorized as CLOUD."""
+        assert get_runner_category('test', 'https://api.dify.ai/v1') == RunnerCategory.CLOUD
+        assert get_runner_category('test', 'https://cloud.dify.ai') == RunnerCategory.CLOUD
+
+    def test_coze_cloud_returns_cloud(self):
+        """Coze domains should be categorized as CLOUD."""
+        assert get_runner_category('test', 'https://api.coze.com') == RunnerCategory.CLOUD
+        assert get_runner_category('test', 'https://api.coze.cn') == RunnerCategory.CLOUD
+
+    def test_langflow_cloud_returns_cloud(self):
+        """Langflow domains should be categorized as CLOUD."""
+        assert get_runner_category('test', 'https://cloud.langflow.ai') == RunnerCategory.CLOUD
+        assert get_runner_category('test', 'https://test.langflow.org') == RunnerCategory.CLOUD
+
+    def test_other_url_returns_cloud(self):
+        """Other URLs should default to CLOUD category."""
+        assert get_runner_category('test', 'https://example.com') == RunnerCategory.CLOUD
+        assert get_runner_category('test', 'https://myserver.example.org') == RunnerCategory.CLOUD
+
+    @pytest.mark.parametrize(
+        'runner_url',
+        [
+            'api.dify.ai/v1',
+            'localhost:7860',
+            'https:///v1',
+            'https://',
+            'https://exa mple.com',
+            'http://[::1',
+            'http://localhost:bad',
+        ],
+    )
+    def test_invalid_urls_return_unknown(self, runner_url):
+        """Invalid or incomplete URLs should return UNKNOWN."""
+        assert get_runner_category('test', runner_url) == RunnerCategory.UNKNOWN
+
+    def test_urlparse_exception_returns_unknown(self):
+        """Exception during URL parsing should return UNKNOWN."""
+        # Test by mocking urlparse to raise an exception
+        from langbot.pkg.utils import runner
+
+        def mock_urlparse(url):
+            raise Exception('URL parsing failed')
+
+        with patch('langbot.pkg.utils.runner.urlparse', side_effect=mock_urlparse):
+            result = runner.get_runner_category('test', 'http://example.com')
+            assert result == RunnerCategory.UNKNOWN
+
+    def test_url_without_scheme_returns_unknown(self):
+        """URL without scheme should return UNKNOWN."""
+        assert get_runner_category('test', 'example.com') == RunnerCategory.UNKNOWN
+
+    @pytest.mark.parametrize(
+        'runner_url',
+        [
+            'http://localhost:7860',
+            'http://127.0.0.1:7860',
+            'http://10.0.0.1:7860',
+            'http://172.16.0.1:7860',
+            'http://172.31.255.255:7860',
+            'http://192.168.1.20:7860',
+            'http://[::1]:7860',
+        ],
+    )
+    def test_detects_local_hosts_with_ipaddress(self, runner_url):
+        """Local hostnames and private IPs should be categorized as LOCAL."""
+        assert get_runner_category('langflow-api', runner_url) == RunnerCategory.LOCAL
+
+    @pytest.mark.parametrize(
+        'runner_url',
+        [
+            'http://10.evil.com',
+            'http://192.168.example.com',
+        ],
+    )
+    def test_private_ip_prefix_domains_are_not_local(self, runner_url):
+        """Domain names that only look like private IP prefixes should not be LOCAL."""
+        assert get_runner_category('langflow-api', runner_url) == RunnerCategory.CLOUD
+
+
+class TestIsCloudRunner:
+    """Test is_cloud_runner helper function."""
+
+    def test_cloud_runner_returns_true(self):
+        """Cloud URL should return True."""
+        assert is_cloud_runner('test', 'https://api.dify.ai') is True
+
+    def test_local_runner_returns_false(self):
+        """Local URL should return False."""
+        assert is_cloud_runner('test', 'http://localhost:3000') is False
+
+    def test_unknown_returns_false(self):
+        """Unknown category should return False."""
+        assert is_cloud_runner('test', None) is False
+
+
+class TestIsLocalRunner:
+    """Test is_local_runner helper function."""
+
+    def test_local_runner_returns_true(self):
+        """Local URL should return True."""
+        assert is_local_runner('test', 'http://localhost:3000') is True
+
+    def test_cloud_runner_returns_false(self):
+        """Cloud URL should return False."""
+        assert is_local_runner('test', 'https://api.dify.ai') is False
+
+    def test_unknown_returns_false(self):
+        """Unknown category should return False."""
+        assert is_local_runner('test', None) is False
+
+
+class TestGetRunnerInfo:
+    """Test get_runner_info function."""
+
+    def test_returns_dict_with_expected_keys(self):
+        """Should return dict with name, url, and category keys."""
+        info = get_runner_info('my-runner', 'http://localhost:3000')
+        assert 'name' in info
+        assert 'url' in info
+        assert 'category' in info
+
+    def test_includes_correct_values(self):
+        """Should include correct values in dict."""
+        info = get_runner_info('my-runner', 'http://localhost:3000')
+        assert info['name'] == 'my-runner'
+        assert info['url'] == 'http://localhost:3000'
+        assert info['category'] == RunnerCategory.LOCAL
+
+
+class TestExtractRunnerUrl:
+    """Test extract_runner_url function."""
+
+    def test_dify_service_api_extracts_url(self):
+        """Should extract base-url from dify-service-api config."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {'ai': {'dify-service-api': {'base-url': 'https://api.dify.ai'}}}
+        url = extract_runner_url('dify-service-api', runner, pipeline_config)
+        assert url == 'https://api.dify.ai'
+
+    def test_n8n_service_api_extracts_url(self):
+        """Should extract webhook-url from n8n-service-api config."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {'ai': {'n8n-service-api': {'webhook-url': 'https://my.n8n.cloud/webhook'}}}
+        url = extract_runner_url('n8n-service-api', runner, pipeline_config)
+        assert url == 'https://my.n8n.cloud/webhook'
+
+    def test_coze_api_extracts_url(self):
+        """Should extract api-base from coze-api config."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {'ai': {'coze-api': {'api-base': 'https://api.coze.com'}}}
+        url = extract_runner_url('coze-api', runner, pipeline_config)
+        assert url == 'https://api.coze.com'
+
+    def test_langflow_api_extracts_url(self):
+        """Should extract base-url from langflow-api config."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {'ai': {'langflow-api': {'base-url': 'https://cloud.langflow.ai'}}}
+        url = extract_runner_url('langflow-api', runner, pipeline_config)
+        assert url == 'https://cloud.langflow.ai'
+
+    def test_unknown_runner_returns_none(self):
+        """Unknown runner name should return None."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {}
+        url = extract_runner_url('unknown-runner', runner, pipeline_config)
+        assert url is None
+
+    def test_none_runner_returns_none(self):
+        """None runner should return None."""
+        url = extract_runner_url('test', None, {})
+        assert url is None
+
+    def test_runner_without_pipeline_config_returns_none(self):
+        """Runner without pipeline_config attribute should return None."""
+        runner = Mock(spec=[])  # Empty spec means no attributes
+        url = extract_runner_url('test', runner, {})
+        assert url is None
+
+    def test_none_pipeline_config_returns_none(self):
+        """None pipeline_config should return None."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        url = extract_runner_url('dify-service-api', runner, None)
+        assert url is None
+
+    def test_missing_ai_config_returns_none(self):
+        """Missing ai config should return None."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {}
+        url = extract_runner_url('dify-service-api', runner, pipeline_config)
+        assert url is None
+
+
+class TestGetRunnerCategoryFromRunner:
+    """Test get_runner_category_from_runner function."""
+
+    def test_extracts_and_categorizes(self):
+        """Should extract URL and return correct category."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        pipeline_config = {'ai': {'dify-service-api': {'base-url': 'https://api.dify.ai'}}}
+        category = get_runner_category_from_runner('dify-service-api', runner, pipeline_config)
+        assert category == RunnerCategory.CLOUD
+
+    def test_returns_unknown_for_missing_url(self):
+        """Should return UNKNOWN when URL cannot be extracted."""
+        runner = Mock()
+        runner.pipeline_config = {}
+        category = get_runner_category_from_runner('unknown', runner, {})
+        assert category == RunnerCategory.UNKNOWN
+
+
+class TestConstants:
+    """Test that constants are properly defined."""
+
+    def test_runner_category_constants(self):
+        """RunnerCategory should have LOCAL, CLOUD, UNKNOWN."""
+        assert RunnerCategory.LOCAL == 'local'
+        assert RunnerCategory.CLOUD == 'cloud'
+        assert RunnerCategory.UNKNOWN == 'unknown'
+
+    def test_cloud_domains_not_empty(self):
+        """CLOUD_DOMAINS should not be empty."""
+        assert len(CLOUD_DOMAINS) > 0
+
+    def test_local_patterns_not_empty(self):
+        """LOCAL_PATTERNS should not be empty."""
+        assert len(LOCAL_PATTERNS) > 0
+
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])