Merge branch 'main' into feat/streaming-tui

tests/agent/test_auxiliary_client.py

@@ -176,14 +176,18 @@ class TestVisionClientFallback:
         assert isinstance(client, CodexAuxiliaryClient)
         assert model == "gpt-5.3-codex"
 
-    def test_vision_auto_skips_custom_endpoint(self, monkeypatch):
-        """Custom endpoint is skipped in vision auto mode."""
+    def test_vision_auto_falls_back_to_custom_endpoint(self, monkeypatch):
+        """Custom endpoint is used as fallback in vision auto mode.
+
+        Many local models (Qwen-VL, LLaVA, etc.) support vision.
+        When no OpenRouter/Nous/Codex is available, try the custom endpoint.
+        """
         monkeypatch.setenv("OPENAI_BASE_URL", "http://localhost:1234/v1")
         monkeypatch.setenv("OPENAI_API_KEY", "local-key")
-        with patch("agent.auxiliary_client._read_nous_auth", return_value=None):
+        with patch("agent.auxiliary_client._read_nous_auth", return_value=None), \
+             patch("agent.auxiliary_client.OpenAI") as mock_openai:
             client, model = get_vision_auxiliary_client()
-        assert client is None
-        assert model is None
+        assert client is not None  # Custom endpoint picked up as fallback
 
     def test_vision_uses_openrouter_when_available(self, monkeypatch):
         monkeypatch.setenv("OPENROUTER_API_KEY", "or-key")

tests/gateway/test_slack.py

@@ -0,0 +1,532 @@
+"""
+Tests for Slack platform adapter.
+
+Covers: app_mention handler, send_document, send_video,
+        incoming document handling, message routing.
+
+Note: slack-bolt may not be installed in the test environment.
+We mock the slack modules at import time to avoid collection errors.
+"""
+
+import asyncio
+import os
+import sys
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    MessageEvent,
+    MessageType,
+    SendResult,
+    SUPPORTED_DOCUMENT_TYPES,
+)
+
+
+# ---------------------------------------------------------------------------
+# Mock the slack-bolt package if it's not installed
+# ---------------------------------------------------------------------------
+
+def _ensure_slack_mock():
+    """Install mock slack modules so SlackAdapter can be imported."""
+    if "slack_bolt" in sys.modules and hasattr(sys.modules["slack_bolt"], "__file__"):
+        return  # Real library installed
+
+    slack_bolt = MagicMock()
+    slack_bolt.async_app.AsyncApp = MagicMock
+    slack_bolt.adapter.socket_mode.async_handler.AsyncSocketModeHandler = MagicMock
+
+    slack_sdk = MagicMock()
+    slack_sdk.web.async_client.AsyncWebClient = MagicMock
+
+    for name, mod in [
+        ("slack_bolt", slack_bolt),
+        ("slack_bolt.async_app", slack_bolt.async_app),
+        ("slack_bolt.adapter", slack_bolt.adapter),
+        ("slack_bolt.adapter.socket_mode", slack_bolt.adapter.socket_mode),
+        ("slack_bolt.adapter.socket_mode.async_handler", slack_bolt.adapter.socket_mode.async_handler),
+        ("slack_sdk", slack_sdk),
+        ("slack_sdk.web", slack_sdk.web),
+        ("slack_sdk.web.async_client", slack_sdk.web.async_client),
+    ]:
+        sys.modules.setdefault(name, mod)
+
+
+_ensure_slack_mock()
+
+# Patch SLACK_AVAILABLE before importing the adapter
+import gateway.platforms.slack as _slack_mod
+_slack_mod.SLACK_AVAILABLE = True
+
+from gateway.platforms.slack import SlackAdapter  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture()
+def adapter():
+    config = PlatformConfig(enabled=True, token="xoxb-fake-token")
+    a = SlackAdapter(config)
+    # Mock the Slack app client
+    a._app = MagicMock()
+    a._app.client = AsyncMock()
+    a._bot_user_id = "U_BOT"
+    a._running = True
+    # Capture events instead of processing them
+    a.handle_message = AsyncMock()
+    return a
+
+
+@pytest.fixture(autouse=True)
+def _redirect_cache(tmp_path, monkeypatch):
+    """Point document cache to tmp_path so tests don't touch ~/.hermes."""
+    monkeypatch.setattr(
+        "gateway.platforms.base.DOCUMENT_CACHE_DIR", tmp_path / "doc_cache"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TestAppMentionHandler
+# ---------------------------------------------------------------------------
+
+class TestAppMentionHandler:
+    """Verify that the app_mention event handler is registered."""
+
+    def test_app_mention_registered_on_connect(self):
+        """connect() should register both 'message' and 'app_mention' handlers."""
+        config = PlatformConfig(enabled=True, token="xoxb-fake")
+        adapter = SlackAdapter(config)
+
+        # Track which events get registered
+        registered_events = []
+        registered_commands = []
+
+        mock_app = MagicMock()
+
+        def mock_event(event_type):
+            def decorator(fn):
+                registered_events.append(event_type)
+                return fn
+            return decorator
+
+        def mock_command(cmd):
+            def decorator(fn):
+                registered_commands.append(cmd)
+                return fn
+            return decorator
+
+        mock_app.event = mock_event
+        mock_app.command = mock_command
+        mock_app.client = AsyncMock()
+        mock_app.client.auth_test = AsyncMock(return_value={
+            "user_id": "U_BOT",
+            "user": "testbot",
+        })
+
+        with patch.object(_slack_mod, "AsyncApp", return_value=mock_app), \
+             patch.object(_slack_mod, "AsyncSocketModeHandler", return_value=MagicMock()), \
+             patch.dict(os.environ, {"SLACK_APP_TOKEN": "xapp-fake"}), \
+             patch("asyncio.create_task"):
+            asyncio.get_event_loop().run_until_complete(adapter.connect())
+
+        assert "message" in registered_events
+        assert "app_mention" in registered_events
+        assert "/hermes" in registered_commands
+
+
+# ---------------------------------------------------------------------------
+# TestSendDocument
+# ---------------------------------------------------------------------------
+
+class TestSendDocument:
+    @pytest.mark.asyncio
+    async def test_send_document_success(self, adapter, tmp_path):
+        test_file = tmp_path / "report.pdf"
+        test_file.write_bytes(b"%PDF-1.4 fake content")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(return_value={"ok": True})
+
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path=str(test_file),
+            caption="Here's the report",
+        )
+
+        assert result.success
+        adapter._app.client.files_upload_v2.assert_called_once()
+        call_kwargs = adapter._app.client.files_upload_v2.call_args[1]
+        assert call_kwargs["channel"] == "C123"
+        assert call_kwargs["file"] == str(test_file)
+        assert call_kwargs["filename"] == "report.pdf"
+        assert call_kwargs["initial_comment"] == "Here's the report"
+
+    @pytest.mark.asyncio
+    async def test_send_document_custom_name(self, adapter, tmp_path):
+        test_file = tmp_path / "data.csv"
+        test_file.write_bytes(b"a,b,c\n1,2,3")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(return_value={"ok": True})
+
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path=str(test_file),
+            file_name="quarterly-report.csv",
+        )
+
+        assert result.success
+        call_kwargs = adapter._app.client.files_upload_v2.call_args[1]
+        assert call_kwargs["filename"] == "quarterly-report.csv"
+
+    @pytest.mark.asyncio
+    async def test_send_document_missing_file(self, adapter):
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path="/nonexistent/file.pdf",
+        )
+
+        assert not result.success
+        assert "not found" in result.error.lower()
+
+    @pytest.mark.asyncio
+    async def test_send_document_not_connected(self, adapter):
+        adapter._app = None
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path="/some/file.pdf",
+        )
+
+        assert not result.success
+        assert "Not connected" in result.error
+
+    @pytest.mark.asyncio
+    async def test_send_document_api_error_falls_back(self, adapter, tmp_path):
+        test_file = tmp_path / "doc.pdf"
+        test_file.write_bytes(b"content")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(
+            side_effect=RuntimeError("Slack API error")
+        )
+
+        # Should fall back to base class (text message)
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path=str(test_file),
+        )
+
+        # Base class send() is also mocked, so check it was attempted
+        adapter._app.client.chat_postMessage.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_send_document_with_thread(self, adapter, tmp_path):
+        test_file = tmp_path / "notes.txt"
+        test_file.write_bytes(b"some notes")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(return_value={"ok": True})
+
+        result = await adapter.send_document(
+            chat_id="C123",
+            file_path=str(test_file),
+            reply_to="1234567890.123456",
+        )
+
+        assert result.success
+        call_kwargs = adapter._app.client.files_upload_v2.call_args[1]
+        assert call_kwargs["thread_ts"] == "1234567890.123456"
+
+
+# ---------------------------------------------------------------------------
+# TestSendVideo
+# ---------------------------------------------------------------------------
+
+class TestSendVideo:
+    @pytest.mark.asyncio
+    async def test_send_video_success(self, adapter, tmp_path):
+        video = tmp_path / "clip.mp4"
+        video.write_bytes(b"fake video data")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(return_value={"ok": True})
+
+        result = await adapter.send_video(
+            chat_id="C123",
+            video_path=str(video),
+            caption="Check this out",
+        )
+
+        assert result.success
+        call_kwargs = adapter._app.client.files_upload_v2.call_args[1]
+        assert call_kwargs["filename"] == "clip.mp4"
+        assert call_kwargs["initial_comment"] == "Check this out"
+
+    @pytest.mark.asyncio
+    async def test_send_video_missing_file(self, adapter):
+        result = await adapter.send_video(
+            chat_id="C123",
+            video_path="/nonexistent/video.mp4",
+        )
+
+        assert not result.success
+        assert "not found" in result.error.lower()
+
+    @pytest.mark.asyncio
+    async def test_send_video_not_connected(self, adapter):
+        adapter._app = None
+        result = await adapter.send_video(
+            chat_id="C123",
+            video_path="/some/video.mp4",
+        )
+
+        assert not result.success
+        assert "Not connected" in result.error
+
+    @pytest.mark.asyncio
+    async def test_send_video_api_error_falls_back(self, adapter, tmp_path):
+        video = tmp_path / "clip.mp4"
+        video.write_bytes(b"fake video")
+
+        adapter._app.client.files_upload_v2 = AsyncMock(
+            side_effect=RuntimeError("Slack API error")
+        )
+
+        # Should fall back to base class (text message)
+        result = await adapter.send_video(
+            chat_id="C123",
+            video_path=str(video),
+        )
+
+        adapter._app.client.chat_postMessage.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# TestIncomingDocumentHandling
+# ---------------------------------------------------------------------------
+
+class TestIncomingDocumentHandling:
+    def _make_event(self, files=None, text="hello", channel_type="im"):
+        """Build a mock Slack message event with file attachments."""
+        return {
+            "text": text,
+            "user": "U_USER",
+            "channel": "C123",
+            "channel_type": channel_type,
+            "ts": "1234567890.000001",
+            "files": files or [],
+        }
+
+    @pytest.mark.asyncio
+    async def test_pdf_document_cached(self, adapter):
+        """A PDF attachment should be downloaded, cached, and set as DOCUMENT type."""
+        pdf_bytes = b"%PDF-1.4 fake content"
+
+        with patch.object(adapter, "_download_slack_file_bytes", new_callable=AsyncMock) as dl:
+            dl.return_value = pdf_bytes
+            event = self._make_event(files=[{
+                "mimetype": "application/pdf",
+                "name": "report.pdf",
+                "url_private_download": "https://files.slack.com/report.pdf",
+                "size": len(pdf_bytes),
+            }])
+            await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert msg_event.message_type == MessageType.DOCUMENT
+        assert len(msg_event.media_urls) == 1
+        assert os.path.exists(msg_event.media_urls[0])
+        assert msg_event.media_types == ["application/pdf"]
+
+    @pytest.mark.asyncio
+    async def test_txt_document_injects_content(self, adapter):
+        """A .txt file under 100KB should have its content injected into event text."""
+        content = b"Hello from a text file"
+
+        with patch.object(adapter, "_download_slack_file_bytes", new_callable=AsyncMock) as dl:
+            dl.return_value = content
+            event = self._make_event(
+                text="summarize this",
+                files=[{
+                    "mimetype": "text/plain",
+                    "name": "notes.txt",
+                    "url_private_download": "https://files.slack.com/notes.txt",
+                    "size": len(content),
+                }],
+            )
+            await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert "Hello from a text file" in msg_event.text
+        assert "[Content of notes.txt]" in msg_event.text
+        assert "summarize this" in msg_event.text
+
+    @pytest.mark.asyncio
+    async def test_md_document_injects_content(self, adapter):
+        """A .md file under 100KB should have its content injected."""
+        content = b"# Title\nSome markdown content"
+
+        with patch.object(adapter, "_download_slack_file_bytes", new_callable=AsyncMock) as dl:
+            dl.return_value = content
+            event = self._make_event(files=[{
+                "mimetype": "text/markdown",
+                "name": "readme.md",
+                "url_private_download": "https://files.slack.com/readme.md",
+                "size": len(content),
+            }], text="")
+            await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert "# Title" in msg_event.text
+
+    @pytest.mark.asyncio
+    async def test_large_txt_not_injected(self, adapter):
+        """A .txt file over 100KB should be cached but NOT injected."""
+        content = b"x" * (200 * 1024)
+
+        with patch.object(adapter, "_download_slack_file_bytes", new_callable=AsyncMock) as dl:
+            dl.return_value = content
+            event = self._make_event(files=[{
+                "mimetype": "text/plain",
+                "name": "big.txt",
+                "url_private_download": "https://files.slack.com/big.txt",
+                "size": len(content),
+            }], text="")
+            await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert len(msg_event.media_urls) == 1
+        assert "[Content of" not in (msg_event.text or "")
+
+    @pytest.mark.asyncio
+    async def test_unsupported_file_type_skipped(self, adapter):
+        """A .zip file should be silently skipped."""
+        event = self._make_event(files=[{
+            "mimetype": "application/zip",
+            "name": "archive.zip",
+            "url_private_download": "https://files.slack.com/archive.zip",
+            "size": 1024,
+        }])
+        await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert msg_event.message_type == MessageType.TEXT
+        assert len(msg_event.media_urls) == 0
+
+    @pytest.mark.asyncio
+    async def test_oversized_document_skipped(self, adapter):
+        """A document over 20MB should be skipped."""
+        event = self._make_event(files=[{
+            "mimetype": "application/pdf",
+            "name": "huge.pdf",
+            "url_private_download": "https://files.slack.com/huge.pdf",
+            "size": 25 * 1024 * 1024,
+        }])
+        await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert len(msg_event.media_urls) == 0
+
+    @pytest.mark.asyncio
+    async def test_document_download_error_handled(self, adapter):
+        """If document download fails, handler should not crash."""
+        with patch.object(adapter, "_download_slack_file_bytes", new_callable=AsyncMock) as dl:
+            dl.side_effect = RuntimeError("download failed")
+            event = self._make_event(files=[{
+                "mimetype": "application/pdf",
+                "name": "report.pdf",
+                "url_private_download": "https://files.slack.com/report.pdf",
+                "size": 1024,
+            }])
+            await adapter._handle_slack_message(event)
+
+        # Handler should still be called (the exception is caught)
+        adapter.handle_message.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_image_still_handled(self, adapter):
+        """Image attachments should still go through the image path, not document."""
+        with patch.object(adapter, "_download_slack_file", new_callable=AsyncMock) as dl:
+            dl.return_value = "/tmp/cached_image.jpg"
+            event = self._make_event(files=[{
+                "mimetype": "image/jpeg",
+                "name": "photo.jpg",
+                "url_private_download": "https://files.slack.com/photo.jpg",
+                "size": 1024,
+            }])
+            await adapter._handle_slack_message(event)
+
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert msg_event.message_type == MessageType.PHOTO
+
+
+# ---------------------------------------------------------------------------
+# TestMessageRouting
+# ---------------------------------------------------------------------------
+
+class TestMessageRouting:
+    @pytest.mark.asyncio
+    async def test_dm_processed_without_mention(self, adapter):
+        """DM messages should be processed without requiring a bot mention."""
+        event = {
+            "text": "hello",
+            "user": "U_USER",
+            "channel": "D123",
+            "channel_type": "im",
+            "ts": "1234567890.000001",
+        }
+        await adapter._handle_slack_message(event)
+        adapter.handle_message.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_channel_message_requires_mention(self, adapter):
+        """Channel messages without a bot mention should be ignored."""
+        event = {
+            "text": "just talking",
+            "user": "U_USER",
+            "channel": "C123",
+            "channel_type": "channel",
+            "ts": "1234567890.000001",
+        }
+        await adapter._handle_slack_message(event)
+        adapter.handle_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_channel_mention_strips_bot_id(self, adapter):
+        """When mentioned in a channel, the bot mention should be stripped."""
+        event = {
+            "text": "<@U_BOT> what's the weather?",
+            "user": "U_USER",
+            "channel": "C123",
+            "channel_type": "channel",
+            "ts": "1234567890.000001",
+        }
+        await adapter._handle_slack_message(event)
+        msg_event = adapter.handle_message.call_args[0][0]
+        assert msg_event.text == "what's the weather?"
+        assert "<@U_BOT>" not in msg_event.text
+
+    @pytest.mark.asyncio
+    async def test_bot_messages_ignored(self, adapter):
+        """Messages from bots should be ignored."""
+        event = {
+            "text": "bot response",
+            "bot_id": "B_OTHER",
+            "channel": "C123",
+            "channel_type": "im",
+            "ts": "1234567890.000001",
+        }
+        await adapter._handle_slack_message(event)
+        adapter.handle_message.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_message_edits_ignored(self, adapter):
+        """Message edits should be ignored."""
+        event = {
+            "text": "edited message",
+            "user": "U_USER",
+            "channel": "C123",
+            "channel_type": "im",
+            "ts": "1234567890.000001",
+            "subtype": "message_changed",
+        }
+        await adapter._handle_slack_message(event)
+        adapter.handle_message.assert_not_called()

tests/tools/test_file_tools_live.py

@@ -505,6 +505,25 @@ class TestExpandPath:
         assert result == str(Path.home())
         _assert_clean(result)
 
+    def test_tilde_injection_blocked(self, ops):
+        """Paths like ~; rm -rf / must NOT execute shell commands."""
+        malicious = "~; echo PWNED > /tmp/_hermes_injection_test"
+        result = ops._expand_path(malicious)
+        # The invalid username (contains ";") should prevent shell expansion.
+        # The path should be returned as-is (no expansion).
+        assert result == malicious
+        # Verify the injected command did NOT execute
+        import os
+        assert not os.path.exists("/tmp/_hermes_injection_test")
+
+    def test_tilde_username_with_subpath(self, ops):
+        """~root/file.txt should attempt expansion (valid username)."""
+        result = ops._expand_path("~root/file.txt")
+        # On most systems ~root expands to /root
+        if result != "~root/file.txt":
+            assert result.endswith("/file.txt")
+            assert "~" not in result
+
 
 # ── Terminal output cleanliness ──────────────────────────────────────────
 

tests/tools/test_vision_tools.py

@@ -0,0 +1,351 @@
+"""Tests for tools/vision_tools.py — URL validation, type hints, error logging."""
+
+import asyncio
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Awaitable
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from tools.vision_tools import (
+    _validate_image_url,
+    _handle_vision_analyze,
+    _determine_mime_type,
+    _image_to_base64_data_url,
+    vision_analyze_tool,
+    check_vision_requirements,
+    get_debug_session_info,
+)
+
+
+# ---------------------------------------------------------------------------
+# _validate_image_url — urlparse-based validation
+# ---------------------------------------------------------------------------
+
+class TestValidateImageUrl:
+    """Tests for URL validation, including urlparse-based netloc check."""
+
+    def test_valid_https_url(self):
+        assert _validate_image_url("https://example.com/image.jpg") is True
+
+    def test_valid_http_url(self):
+        assert _validate_image_url("http://cdn.example.org/photo.png") is True
+
+    def test_valid_url_without_extension(self):
+        """CDN endpoints that redirect to images should still pass."""
+        assert _validate_image_url("https://cdn.example.com/abcdef123") is True
+
+    def test_valid_url_with_query_params(self):
+        assert _validate_image_url("https://img.example.com/pic?w=200&h=200") is True
+
+    def test_valid_url_with_port(self):
+        assert _validate_image_url("http://localhost:8080/image.png") is True
+
+    def test_valid_url_with_path_only(self):
+        assert _validate_image_url("https://example.com/") is True
+
+    def test_rejects_empty_string(self):
+        assert _validate_image_url("") is False
+
+    def test_rejects_none(self):
+        assert _validate_image_url(None) is False
+
+    def test_rejects_non_string(self):
+        assert _validate_image_url(12345) is False
+
+    def test_rejects_ftp_scheme(self):
+        assert _validate_image_url("ftp://files.example.com/image.jpg") is False
+
+    def test_rejects_file_scheme(self):
+        assert _validate_image_url("file:///etc/passwd") is False
+
+    def test_rejects_no_scheme(self):
+        assert _validate_image_url("example.com/image.jpg") is False
+
+    def test_rejects_javascript_scheme(self):
+        assert _validate_image_url("javascript:alert(1)") is False
+
+    def test_rejects_http_without_netloc(self):
+        """http:// alone has no network location — urlparse catches this."""
+        assert _validate_image_url("http://") is False
+
+    def test_rejects_https_without_netloc(self):
+        assert _validate_image_url("https://") is False
+
+    def test_rejects_http_colon_only(self):
+        assert _validate_image_url("http:") is False
+
+    def test_rejects_data_url(self):
+        assert _validate_image_url("data:image/png;base64,iVBOR") is False
+
+    def test_rejects_whitespace_only(self):
+        assert _validate_image_url("   ") is False
+
+    def test_rejects_boolean(self):
+        assert _validate_image_url(True) is False
+
+    def test_rejects_list(self):
+        assert _validate_image_url(["https://example.com"]) is False
+
+
+# ---------------------------------------------------------------------------
+# _determine_mime_type
+# ---------------------------------------------------------------------------
+
+class TestDetermineMimeType:
+    def test_jpg(self):
+        assert _determine_mime_type(Path("photo.jpg")) == "image/jpeg"
+
+    def test_jpeg(self):
+        assert _determine_mime_type(Path("photo.jpeg")) == "image/jpeg"
+
+    def test_png(self):
+        assert _determine_mime_type(Path("screenshot.png")) == "image/png"
+
+    def test_gif(self):
+        assert _determine_mime_type(Path("anim.gif")) == "image/gif"
+
+    def test_webp(self):
+        assert _determine_mime_type(Path("modern.webp")) == "image/webp"
+
+    def test_unknown_extension_defaults_to_jpeg(self):
+        assert _determine_mime_type(Path("file.xyz")) == "image/jpeg"
+
+
+# ---------------------------------------------------------------------------
+# _image_to_base64_data_url
+# ---------------------------------------------------------------------------
+
+class TestImageToBase64DataUrl:
+    def test_returns_data_url(self, tmp_path):
+        img = tmp_path / "test.png"
+        img.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 8)
+        result = _image_to_base64_data_url(img)
+        assert result.startswith("data:image/png;base64,")
+
+    def test_custom_mime_type(self, tmp_path):
+        img = tmp_path / "test.bin"
+        img.write_bytes(b"\x00" * 16)
+        result = _image_to_base64_data_url(img, mime_type="image/webp")
+        assert result.startswith("data:image/webp;base64,")
+
+    def test_file_not_found_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            _image_to_base64_data_url(tmp_path / "nonexistent.png")
+
+
+# ---------------------------------------------------------------------------
+# _handle_vision_analyze — type signature & behavior
+# ---------------------------------------------------------------------------
+
+class TestHandleVisionAnalyze:
+    """Verify _handle_vision_analyze returns an Awaitable and builds correct prompt."""
+
+    def test_returns_awaitable(self):
+        """The handler must return an Awaitable (coroutine) since it's registered as async."""
+        with patch("tools.vision_tools.vision_analyze_tool", new_callable=AsyncMock) as mock_tool:
+            mock_tool.return_value = json.dumps({"result": "ok"})
+            result = _handle_vision_analyze(
+                {"image_url": "https://example.com/img.png", "question": "What is this?"}
+            )
+            # It should be an Awaitable (coroutine)
+            assert isinstance(result, Awaitable)
+            # Clean up the coroutine to avoid RuntimeWarning
+            result.close()
+
+    def test_prompt_contains_question(self):
+        """The full prompt should incorporate the user's question."""
+        with patch("tools.vision_tools.vision_analyze_tool", new_callable=AsyncMock) as mock_tool:
+            mock_tool.return_value = json.dumps({"result": "ok"})
+            coro = _handle_vision_analyze(
+                {"image_url": "https://example.com/img.png", "question": "Describe the cat"}
+            )
+            # Clean up coroutine
+            coro.close()
+            call_args = mock_tool.call_args
+            full_prompt = call_args[0][1]  # second positional arg
+            assert "Describe the cat" in full_prompt
+            assert "Fully describe and explain" in full_prompt
+
+    def test_uses_auxiliary_vision_model_env(self):
+        """AUXILIARY_VISION_MODEL env var should override DEFAULT_VISION_MODEL."""
+        with patch("tools.vision_tools.vision_analyze_tool", new_callable=AsyncMock) as mock_tool, \
+             patch.dict(os.environ, {"AUXILIARY_VISION_MODEL": "custom/model-v1"}):
+            mock_tool.return_value = json.dumps({"result": "ok"})
+            coro = _handle_vision_analyze(
+                {"image_url": "https://example.com/img.png", "question": "test"}
+            )
+            coro.close()
+            call_args = mock_tool.call_args
+            model = call_args[0][2]  # third positional arg
+            assert model == "custom/model-v1"
+
+    def test_falls_back_to_default_model(self):
+        """Without AUXILIARY_VISION_MODEL, should use DEFAULT_VISION_MODEL or fallback."""
+        with patch("tools.vision_tools.vision_analyze_tool", new_callable=AsyncMock) as mock_tool, \
+             patch.dict(os.environ, {}, clear=False):
+            # Ensure AUXILIARY_VISION_MODEL is not set
+            os.environ.pop("AUXILIARY_VISION_MODEL", None)
+            mock_tool.return_value = json.dumps({"result": "ok"})
+            coro = _handle_vision_analyze(
+                {"image_url": "https://example.com/img.png", "question": "test"}
+            )
+            coro.close()
+            call_args = mock_tool.call_args
+            model = call_args[0][2]
+            # Should be DEFAULT_VISION_MODEL or the hardcoded fallback
+            assert model is not None
+            assert len(model) > 0
+
+    def test_empty_args_graceful(self):
+        """Missing keys should default to empty strings, not raise."""
+        with patch("tools.vision_tools.vision_analyze_tool", new_callable=AsyncMock) as mock_tool:
+            mock_tool.return_value = json.dumps({"result": "ok"})
+            result = _handle_vision_analyze({})
+            assert isinstance(result, Awaitable)
+            result.close()
+
+
+# ---------------------------------------------------------------------------
+# Error logging with exc_info — verify tracebacks are logged
+# ---------------------------------------------------------------------------
+
+class TestErrorLoggingExcInfo:
+    """Verify that exc_info=True is used in error/warning log calls."""
+
+    @pytest.mark.asyncio
+    async def test_download_failure_logs_exc_info(self, tmp_path, caplog):
+        """After max retries, the download error should include exc_info."""
+        from tools.vision_tools import _download_image
+
+        with patch("tools.vision_tools.httpx.AsyncClient") as mock_client_cls:
+            mock_client = AsyncMock()
+            mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+            mock_client.__aexit__ = AsyncMock(return_value=False)
+            mock_client.get = AsyncMock(side_effect=ConnectionError("network down"))
+            mock_client_cls.return_value = mock_client
+
+            dest = tmp_path / "image.jpg"
+            with caplog.at_level(logging.ERROR, logger="tools.vision_tools"), \
+                 pytest.raises(ConnectionError):
+                await _download_image("https://example.com/img.jpg", dest, max_retries=1)
+
+            # Should have logged with exc_info (traceback present)
+            error_records = [r for r in caplog.records if r.levelno >= logging.ERROR]
+            assert len(error_records) >= 1
+            assert error_records[0].exc_info is not None
+
+    @pytest.mark.asyncio
+    async def test_analysis_error_logs_exc_info(self, caplog):
+        """When vision_analyze_tool encounters an error, it should log with exc_info."""
+        with patch("tools.vision_tools._validate_image_url", return_value=True), \
+             patch("tools.vision_tools._download_image", new_callable=AsyncMock,
+                   side_effect=Exception("download boom")), \
+             caplog.at_level(logging.ERROR, logger="tools.vision_tools"):
+
+            result = await vision_analyze_tool(
+                "https://example.com/img.jpg", "describe this", "test/model"
+            )
+            result_data = json.loads(result)
+            # Error response uses "success": False, not an "error" key
+            assert result_data["success"] is False
+
+            error_records = [r for r in caplog.records if r.levelno >= logging.ERROR]
+            assert any(r.exc_info is not None for r in error_records)
+
+    @pytest.mark.asyncio
+    async def test_cleanup_error_logs_exc_info(self, tmp_path, caplog):
+        """Temp file cleanup failure should log warning with exc_info."""
+        # Create a real temp file that will be "downloaded"
+        temp_dir = tmp_path / "temp_vision_images"
+        temp_dir.mkdir()
+
+        async def fake_download(url, dest, max_retries=3):
+            """Simulate download by writing file to the expected destination."""
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(b"\xff\xd8\xff" + b"\x00" * 16)
+            return dest
+
+        with patch("tools.vision_tools._validate_image_url", return_value=True), \
+             patch("tools.vision_tools._download_image", side_effect=fake_download), \
+             patch("tools.vision_tools._image_to_base64_data_url",
+                   return_value="data:image/jpeg;base64,abc"), \
+             patch("agent.auxiliary_client.get_auxiliary_extra_body", return_value=None), \
+             patch("agent.auxiliary_client.auxiliary_max_tokens_param", return_value={"max_tokens": 2000}), \
+             caplog.at_level(logging.WARNING, logger="tools.vision_tools"):
+
+            # Mock the vision client
+            mock_client = AsyncMock()
+            mock_response = MagicMock()
+            mock_choice = MagicMock()
+            mock_choice.message.content = "A test image description"
+            mock_response.choices = [mock_choice]
+            mock_client.chat.completions.create = AsyncMock(return_value=mock_response)
+
+            # Patch module-level _aux_async_client so the tool doesn't bail early
+            with patch("tools.vision_tools._aux_async_client", mock_client), \
+                 patch("tools.vision_tools.DEFAULT_VISION_MODEL", "test/model"):
+
+                # Make unlink fail to trigger cleanup warning
+                original_unlink = Path.unlink
+                def failing_unlink(self, *args, **kwargs):
+                    raise PermissionError("no permission")
+
+                with patch.object(Path, "unlink", failing_unlink):
+                    result = await vision_analyze_tool(
+                        "https://example.com/tempimg.jpg", "describe", "test/model"
+                    )
+
+            warning_records = [r for r in caplog.records if r.levelno == logging.WARNING
+                               and "temporary file" in r.getMessage().lower()]
+            assert len(warning_records) >= 1
+            assert warning_records[0].exc_info is not None
+
+
+# ---------------------------------------------------------------------------
+# check_vision_requirements & get_debug_session_info
+# ---------------------------------------------------------------------------
+
+class TestVisionRequirements:
+    def test_check_requirements_returns_bool(self):
+        result = check_vision_requirements()
+        assert isinstance(result, bool)
+
+    def test_debug_session_info_returns_dict(self):
+        info = get_debug_session_info()
+        assert isinstance(info, dict)
+        # DebugSession.get_session_info() returns these keys
+        assert "enabled" in info
+        assert "session_id" in info
+        assert "total_calls" in info
+
+
+# ---------------------------------------------------------------------------
+# Integration: registry entry
+# ---------------------------------------------------------------------------
+
+class TestVisionRegistration:
+    def test_vision_analyze_registered(self):
+        from tools.registry import registry
+        entry = registry._tools.get("vision_analyze")
+        assert entry is not None
+        assert entry.toolset == "vision"
+        assert entry.is_async is True
+
+    def test_schema_has_required_fields(self):
+        from tools.registry import registry
+        entry = registry._tools.get("vision_analyze")
+        schema = entry.schema
+        assert schema["name"] == "vision_analyze"
+        params = schema.get("parameters", {})
+        props = params.get("properties", {})
+        assert "image_url" in props
+        assert "question" in props
+
+    def test_handler_is_callable(self):
+        from tools.registry import registry
+        entry = registry._tools.get("vision_analyze")
+        assert callable(entry.handler)