Merge remote-tracking branch 'origin/main'

# Conflicts:
#	nanobot/agent/loop.py
#	nanobot/agent/tools/message.py
#	nanobot/agent/tools/shell.py
#	nanobot/channels/whatsapp.py
#	nanobot/cli/commands.py
#	tests/test_channel_plugins.py
#	tests/test_commands.py

tests/test_channel_plugins.py

@@ -0,0 +1,265 @@
+"""Tests for channel plugin discovery, merging, and config compatibility."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+from nanobot.channels.manager import ChannelManager
+from nanobot.config.schema import ChannelsConfig
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+class _FakePlugin(BaseChannel):
+    name = "fakeplugin"
+    display_name = "Fake Plugin"
+
+    def __init__(self, config, bus):
+        super().__init__(config, bus)
+        self.login_calls: list[bool] = []
+
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    async def send(self, msg: OutboundMessage) -> None:
+        pass
+
+    async def login(self, force: bool = False) -> bool:
+        self.login_calls.append(force)
+        return True
+
+
+class _FakeTelegram(BaseChannel):
+    """Plugin that tries to shadow built-in telegram."""
+    name = "telegram"
+    display_name = "Fake Telegram"
+
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    async def send(self, msg: OutboundMessage) -> None:
+        pass
+
+
+def _make_entry_point(name: str, cls: type):
+    """Create a mock entry point that returns *cls* on load()."""
+    ep = SimpleNamespace(name=name, load=lambda _cls=cls: _cls)
+    return ep
+
+
+# ---------------------------------------------------------------------------
+# ChannelsConfig extra="allow"
+# ---------------------------------------------------------------------------
+
+def test_channels_config_accepts_unknown_keys():
+    cfg = ChannelsConfig.model_validate({
+        "myplugin": {"enabled": True, "token": "abc"},
+    })
+    extra = cfg.model_extra
+    assert extra is not None
+    assert extra["myplugin"]["enabled"] is True
+    assert extra["myplugin"]["token"] == "abc"
+
+
+def test_channels_config_getattr_returns_extra():
+    cfg = ChannelsConfig.model_validate({"myplugin": {"enabled": True}})
+    section = getattr(cfg, "myplugin", None)
+    assert isinstance(section, dict)
+    assert section["enabled"] is True
+
+
+def test_channels_config_builtin_fields_and_defaults_are_available():
+    """Built-in channel defaults still coexist with extra plugin channel keys."""
+    cfg = ChannelsConfig()
+    assert hasattr(cfg, "telegram")
+    assert cfg.telegram.enabled is False
+    assert cfg.send_progress is True
+    assert cfg.send_tool_hints is False
+
+
+# ---------------------------------------------------------------------------
+# discover_plugins
+# ---------------------------------------------------------------------------
+
+_EP_TARGET = "importlib.metadata.entry_points"
+
+
+def test_discover_plugins_loads_entry_points():
+    from nanobot.channels.registry import discover_plugins
+
+    ep = _make_entry_point("line", _FakePlugin)
+    with patch(_EP_TARGET, return_value=[ep]):
+        result = discover_plugins()
+
+    assert "line" in result
+    assert result["line"] is _FakePlugin
+
+
+def test_discover_plugins_handles_load_error():
+    from nanobot.channels.registry import discover_plugins
+
+    def _boom():
+        raise RuntimeError("broken")
+
+    ep = SimpleNamespace(name="broken", load=_boom)
+    with patch(_EP_TARGET, return_value=[ep]):
+        result = discover_plugins()
+
+    assert "broken" not in result
+
+
+# ---------------------------------------------------------------------------
+# discover_all — merge & priority
+# ---------------------------------------------------------------------------
+
+def test_discover_all_includes_builtins():
+    from nanobot.channels.registry import discover_all, discover_channel_names
+
+    with patch(_EP_TARGET, return_value=[]):
+        result = discover_all()
+
+    # discover_all() only returns channels that are actually available (dependencies installed)
+    # discover_channel_names() returns all built-in channel names
+    # So we check that all actually loaded channels are in the result
+    for name in result:
+        assert name in discover_channel_names()
+
+
+def test_discover_all_includes_external_plugin():
+    from nanobot.channels.registry import discover_all
+
+    ep = _make_entry_point("line", _FakePlugin)
+    with patch(_EP_TARGET, return_value=[ep]):
+        result = discover_all()
+
+    assert "line" in result
+    assert result["line"] is _FakePlugin
+
+
+def test_discover_all_builtin_shadows_plugin():
+    from nanobot.channels.registry import discover_all
+
+    ep = _make_entry_point("telegram", _FakeTelegram)
+    with patch(_EP_TARGET, return_value=[ep]):
+        result = discover_all()
+
+    assert "telegram" in result
+    assert result["telegram"] is not _FakeTelegram
+
+
+# ---------------------------------------------------------------------------
+# Manager _init_channels with dict config (plugin scenario)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_manager_loads_plugin_from_dict_config():
+    """ChannelManager should instantiate a plugin channel from a raw dict config."""
+    from nanobot.channels.manager import ChannelManager
+
+    fake_config = SimpleNamespace(
+        channels=ChannelsConfig.model_validate({
+            "fakeplugin": {"enabled": True, "allowFrom": ["*"]},
+        }),
+        providers=SimpleNamespace(groq=SimpleNamespace(api_key="")),
+    )
+
+    with patch(
+        "nanobot.channels.registry.discover_all",
+        return_value={"fakeplugin": _FakePlugin},
+    ):
+        mgr = ChannelManager.__new__(ChannelManager)
+        mgr.config = fake_config
+        mgr.bus = MessageBus()
+        mgr.channels = {}
+        mgr._dispatch_task = None
+        mgr._init_channels()
+
+    assert "fakeplugin" in mgr.channels
+    assert isinstance(mgr.channels["fakeplugin"], _FakePlugin)
+
+
+def test_channels_login_uses_discovered_plugin_class(monkeypatch):
+    from typer.testing import CliRunner
+
+    from nanobot.cli.commands import app
+    from nanobot.config.schema import Config
+
+    runner = CliRunner()
+    seen: dict[str, object] = {}
+
+    class _LoginPlugin(_FakePlugin):
+        display_name = "Login Plugin"
+
+        async def login(self, force: bool = False) -> bool:
+            seen["force"] = force
+            seen["config"] = self.config
+            return True
+
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda: Config())
+    monkeypatch.setattr(
+        "nanobot.channels.registry.discover_all",
+        lambda: {"fakeplugin": _LoginPlugin},
+    )
+
+    result = runner.invoke(app, ["channels", "login", "fakeplugin", "--force"])
+
+    assert result.exit_code == 0
+    assert seen["force"] is True
+
+
+@pytest.mark.asyncio
+async def test_manager_skips_disabled_plugin():
+    fake_config = SimpleNamespace(
+        channels=ChannelsConfig.model_validate({
+            "fakeplugin": {"enabled": False},
+        }),
+        providers=SimpleNamespace(groq=SimpleNamespace(api_key="")),
+    )
+
+    with patch(
+        "nanobot.channels.registry.discover_all",
+        return_value={"fakeplugin": _FakePlugin},
+    ):
+        mgr = ChannelManager.__new__(ChannelManager)
+        mgr.config = fake_config
+        mgr.bus = MessageBus()
+        mgr.channels = {}
+        mgr._dispatch_task = None
+        mgr._init_channels()
+
+    assert "fakeplugin" not in mgr.channels
+
+
+# ---------------------------------------------------------------------------
+# Built-in channel default_config() and dict->Pydantic conversion
+# ---------------------------------------------------------------------------
+
+def test_builtin_channel_default_config():
+    """Built-in channels expose default_config() returning a dict with 'enabled': False."""
+    from nanobot.channels.telegram import TelegramChannel
+    cfg = TelegramChannel.default_config()
+    assert isinstance(cfg, dict)
+    assert cfg["enabled"] is False
+    assert "token" in cfg
+
+
+def test_builtin_channel_init_from_dict():
+    """Built-in channels accept a raw dict and convert to Pydantic internally."""
+    from nanobot.channels.telegram import TelegramChannel
+    bus = MessageBus()
+    ch = TelegramChannel({"enabled": False, "token": "test-tok", "allowFrom": ["*"]}, bus)
+    assert ch.config.token == "test-tok"
+    assert ch.config.allow_from == ["*"]

tests/test_commands.py

@@ -134,10 +134,10 @@ def test_onboard_help_shows_workspace_and_config_options():
 def test_onboard_interactive_discard_does_not_save_or_create_workspace(mock_paths, monkeypatch):
     config_file, workspace_dir, _ = mock_paths
 
-    from nanobot.cli.onboard_wizard import OnboardResult
+    from nanobot.cli.onboard import OnboardResult
 
     monkeypatch.setattr(
-        "nanobot.cli.onboard_wizard.run_onboard",
+        "nanobot.cli.onboard.run_onboard",
         lambda initial_config: OnboardResult(config=initial_config, should_save=False),
     )
 
@@ -175,10 +175,10 @@ def test_onboard_wizard_preserves_explicit_config_in_next_steps(tmp_path, monkey
     config_path = tmp_path / "instance" / "config.json"
     workspace_path = tmp_path / "workspace"
 
-    from nanobot.cli.onboard_wizard import OnboardResult
+    from nanobot.cli.onboard import OnboardResult
 
     monkeypatch.setattr(
-        "nanobot.cli.onboard_wizard.run_onboard",
+        "nanobot.cli.onboard.run_onboard",
         lambda initial_config: OnboardResult(config=initial_config, should_save=True),
     )
     monkeypatch.setattr("nanobot.channels.registry.discover_all", lambda: {})
@@ -471,7 +471,6 @@ def test_agent_hints_about_deprecated_memory_window(mock_agent_runtime, tmp_path
     assert "memoryWindow" in result.stdout
     assert "no longer used" in result.stdout
 
-
 def test_agent_passes_web_search_config_to_agent_loop(mock_agent_runtime) -> None:
     mock_agent_runtime["config"].tools.web.search.provider = "searxng"
     mock_agent_runtime["config"].tools.web.search.base_url = "http://localhost:8080"
@@ -486,6 +485,12 @@ def test_agent_passes_web_search_config_to_agent_loop(mock_agent_runtime) -> Non
     assert kwargs["web_search_max_results"] == 7
 
 
+def test_heartbeat_retains_recent_messages_by_default():
+    config = Config()
+
+    assert config.gateway.heartbeat.keep_recent_messages == 8
+
+
 def test_gateway_uses_workspace_from_config_by_default(monkeypatch, tmp_path: Path) -> None:
     config_file = tmp_path / "instance" / "config.json"
     config_file.parent.mkdir(parents=True)
@@ -567,6 +572,8 @@ def test_gateway_warns_about_deprecated_memory_window(monkeypatch, tmp_path: Pat
     assert isinstance(result.exception, _StopGatewayError)
     assert "memoryWindow" in result.stdout
     assert "contextWindowTokens" in result.stdout
+
+
 def test_gateway_uses_config_directory_for_cron_store(monkeypatch, tmp_path: Path) -> None:
     config_file = tmp_path / "instance" / "config.json"
     config_file.parent.mkdir(parents=True)
@@ -640,7 +647,6 @@ def test_gateway_cli_port_overrides_configured_port(monkeypatch, tmp_path: Path)
     assert isinstance(result.exception, _StopGatewayError)
     assert "port 18792" in result.stdout
 
-
 def test_gateway_constructs_http_server_without_public_file_options(monkeypatch, tmp_path: Path) -> None:
     config_file = tmp_path / "instance" / "config.json"
     config_file.parent.mkdir(parents=True)
@@ -689,3 +695,9 @@ def test_gateway_constructs_http_server_without_public_file_options(monkeypatch,
     assert seen["port"] == config.gateway.port
     assert seen["http_server_ctor"] is True
     assert "public_files_enabled" not in seen["agent_kwargs"]
+
+
+def test_channels_login_requires_channel_name() -> None:
+    result = runner.invoke(app, ["channels", "login"])
+
+    assert result.exit_code == 2

tests/test_onboard_logic.py

@@ -12,11 +12,11 @@ from typing import Any, cast
 import pytest
 from pydantic import BaseModel, Field
 
-from nanobot.cli import onboard_wizard
+from nanobot.cli import onboard as onboard_wizard
 
 # Import functions to test
 from nanobot.cli.commands import _merge_missing_defaults
-from nanobot.cli.onboard_wizard import (
+from nanobot.cli.onboard import (
     _BACK_PRESSED,
     _configure_pydantic_model,
     _format_value,
@@ -352,7 +352,7 @@ class TestProviderChannelInfo:
     """Tests for provider and channel info retrieval."""
 
     def test_get_provider_names_returns_dict(self):
-        from nanobot.cli.onboard_wizard import _get_provider_names
+        from nanobot.cli.onboard import _get_provider_names
 
         names = _get_provider_names()
         assert isinstance(names, dict)
@@ -363,7 +363,7 @@ class TestProviderChannelInfo:
         assert "github_copilot" not in names
 
     def test_get_channel_names_returns_dict(self):
-        from nanobot.cli.onboard_wizard import _get_channel_names
+        from nanobot.cli.onboard import _get_channel_names
 
         names = _get_channel_names()
         assert isinstance(names, dict)
@@ -371,7 +371,7 @@ class TestProviderChannelInfo:
         assert len(names) >= 0
 
     def test_get_provider_info_returns_valid_structure(self):
-        from nanobot.cli.onboard_wizard import _get_provider_info
+        from nanobot.cli.onboard import _get_provider_info
 
         info = _get_provider_info()
         assert isinstance(info, dict)

tests/test_restart_command.py

@@ -34,12 +34,15 @@ class TestRestartCommand:
 
     @pytest.mark.asyncio
     async def test_restart_sends_message_and_calls_execv(self):
+        from nanobot.command.builtin import cmd_restart
+        from nanobot.command.router import CommandContext
+
         loop, bus = _make_loop()
         msg = InboundMessage(channel="cli", sender_id="user", chat_id="direct", content="/restart")
+        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/restart", loop=loop)
 
-        with patch("nanobot.agent.loop.os.execv") as mock_execv:
-            await loop._handle_restart(msg)
-            out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        with patch("nanobot.command.builtin.os.execv") as mock_execv:
+            out = await cmd_restart(ctx)
             assert "Restarting" in out.content
 
             await asyncio.sleep(1.5)
@@ -51,8 +54,8 @@ class TestRestartCommand:
         loop, bus = _make_loop()
         msg = InboundMessage(channel="telegram", sender_id="u1", chat_id="c1", content="/restart")
 
-        with patch.object(loop, "_handle_restart") as mock_handle:
-            mock_handle.return_value = None
+        with patch.object(loop, "_dispatch", new_callable=AsyncMock) as mock_dispatch, \
+             patch("nanobot.command.builtin.os.execv"):
             await bus.publish_inbound(msg)
 
             loop._running = True
@@ -65,7 +68,9 @@ class TestRestartCommand:
             except asyncio.CancelledError:
                 pass
 
-            mock_handle.assert_called_once()
+            mock_dispatch.assert_not_called()
+            out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+            assert "Restarting" in out.content
 
     @pytest.mark.asyncio
     async def test_status_intercepted_in_run_loop(self):
@@ -73,10 +78,7 @@ class TestRestartCommand:
         loop, bus = _make_loop()
         msg = InboundMessage(channel="telegram", sender_id="u1", chat_id="c1", content="/status")
 
-        with patch.object(loop, "_status_response") as mock_status:
-            mock_status.return_value = OutboundMessage(
-                channel="telegram", chat_id="c1", content="status ok"
-            )
+        with patch.object(loop, "_dispatch", new_callable=AsyncMock) as mock_dispatch:
             await bus.publish_inbound(msg)
 
             loop._running = True
@@ -89,9 +91,9 @@ class TestRestartCommand:
             except asyncio.CancelledError:
                 pass
 
-            mock_status.assert_called_once()
+            mock_dispatch.assert_not_called()
             out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
-            assert out.content == "status ok"
+            assert "nanobot" in out.content.lower() or "Model" in out.content
 
     @pytest.mark.asyncio
     async def test_run_propagates_external_cancellation(self):

tests/test_session_manager_history.py

@@ -64,6 +64,58 @@ def test_legitimate_tool_pairs_preserved_after_trim():
     assert history[0]["role"] == "user"
 
 
+def test_retain_recent_legal_suffix_keeps_recent_messages():
+    session = Session(key="test:trim")
+    for i in range(10):
+        session.messages.append({"role": "user", "content": f"msg{i}"})
+
+    session.retain_recent_legal_suffix(4)
+
+    assert len(session.messages) == 4
+    assert session.messages[0]["content"] == "msg6"
+    assert session.messages[-1]["content"] == "msg9"
+
+
+def test_retain_recent_legal_suffix_adjusts_last_consolidated():
+    session = Session(key="test:trim-cons")
+    for i in range(10):
+        session.messages.append({"role": "user", "content": f"msg{i}"})
+    session.last_consolidated = 7
+
+    session.retain_recent_legal_suffix(4)
+
+    assert len(session.messages) == 4
+    assert session.last_consolidated == 1
+
+
+def test_retain_recent_legal_suffix_zero_clears_session():
+    session = Session(key="test:trim-zero")
+    for i in range(10):
+        session.messages.append({"role": "user", "content": f"msg{i}"})
+    session.last_consolidated = 5
+
+    session.retain_recent_legal_suffix(0)
+
+    assert session.messages == []
+    assert session.last_consolidated == 0
+
+
+def test_retain_recent_legal_suffix_keeps_legal_tool_boundary():
+    session = Session(key="test:trim-tools")
+    session.messages.append({"role": "user", "content": "old"})
+    session.messages.extend(_tool_turn("old", 0))
+    session.messages.append({"role": "user", "content": "keep"})
+    session.messages.extend(_tool_turn("keep", 0))
+    session.messages.append({"role": "assistant", "content": "done"})
+
+    session.retain_recent_legal_suffix(4)
+
+    history = session.get_history(max_messages=500)
+    _assert_no_orphans(history)
+    assert history[0]["role"] == "user"
+    assert history[0]["content"] == "keep"
+
+
 # --- last_consolidated > 0 ---
 
 def test_orphan_trim_with_last_consolidated():

tests/test_task_cancel.py

@@ -31,16 +31,20 @@ class TestHandleStop:
     @pytest.mark.asyncio
     async def test_stop_no_active_task(self):
         from nanobot.bus.events import InboundMessage
+        from nanobot.command.builtin import cmd_stop
+        from nanobot.command.router import CommandContext
 
         loop, bus = _make_loop()
         msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
-        await loop._handle_stop(msg)
-        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/stop", loop=loop)
+        out = await cmd_stop(ctx)
         assert "No active task" in out.content
 
     @pytest.mark.asyncio
     async def test_stop_cancels_active_task(self):
         from nanobot.bus.events import InboundMessage
+        from nanobot.command.builtin import cmd_stop
+        from nanobot.command.router import CommandContext
 
         loop, bus = _make_loop()
         cancelled = asyncio.Event()
@@ -57,15 +61,17 @@ class TestHandleStop:
         loop._active_tasks["test:c1"] = [task]
 
         msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
-        await loop._handle_stop(msg)
+        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/stop", loop=loop)
+        out = await cmd_stop(ctx)
 
         assert cancelled.is_set()
-        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
         assert "stopped" in out.content.lower()
 
     @pytest.mark.asyncio
     async def test_stop_cancels_multiple_tasks(self):
         from nanobot.bus.events import InboundMessage
+        from nanobot.command.builtin import cmd_stop
+        from nanobot.command.router import CommandContext
 
         loop, bus = _make_loop()
         events = [asyncio.Event(), asyncio.Event()]
@@ -82,10 +88,10 @@ class TestHandleStop:
         loop._active_tasks["test:c1"] = tasks
 
         msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
-        await loop._handle_stop(msg)
+        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/stop", loop=loop)
+        out = await cmd_stop(ctx)
 
         assert all(e.is_set() for e in events)
-        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
         assert "2 task" in out.content
 
 

tests/test_weixin_channel.py

@@ -0,0 +1,127 @@
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.weixin import (
+    ITEM_IMAGE,
+    ITEM_TEXT,
+    MESSAGE_TYPE_BOT,
+    WeixinChannel,
+    WeixinConfig,
+)
+
+
+def _make_channel() -> tuple[WeixinChannel, MessageBus]:
+    bus = MessageBus()
+    channel = WeixinChannel(
+        WeixinConfig(enabled=True, allow_from=["*"]),
+        bus,
+    )
+    return channel, bus
+
+
+@pytest.mark.asyncio
+async def test_process_message_deduplicates_inbound_ids() -> None:
+    channel, bus = _make_channel()
+    msg = {
+        "message_type": 1,
+        "message_id": "m1",
+        "from_user_id": "wx-user",
+        "context_token": "ctx-1",
+        "item_list": [
+            {"type": ITEM_TEXT, "text_item": {"text": "hello"}},
+        ],
+    }
+
+    await channel._process_message(msg)
+    first = await asyncio.wait_for(bus.consume_inbound(), timeout=1.0)
+    await channel._process_message(msg)
+
+    assert first.sender_id == "wx-user"
+    assert first.chat_id == "wx-user"
+    assert first.content == "hello"
+    assert bus.inbound_size == 0
+
+
+@pytest.mark.asyncio
+async def test_process_message_caches_context_token_and_send_uses_it() -> None:
+    channel, _bus = _make_channel()
+    channel._client = object()
+    channel._token = "token"
+    channel._send_text = AsyncMock()
+
+    await channel._process_message(
+        {
+            "message_type": 1,
+            "message_id": "m2",
+            "from_user_id": "wx-user",
+            "context_token": "ctx-2",
+            "item_list": [
+                {"type": ITEM_TEXT, "text_item": {"text": "ping"}},
+            ],
+        }
+    )
+
+    await channel.send(
+        type("Msg", (), {"chat_id": "wx-user", "content": "pong", "media": [], "metadata": {}})()
+    )
+
+    channel._send_text.assert_awaited_once_with("wx-user", "pong", "ctx-2")
+
+
+@pytest.mark.asyncio
+async def test_process_message_extracts_media_and_preserves_paths() -> None:
+    channel, bus = _make_channel()
+    channel._download_media_item = AsyncMock(return_value="/tmp/test.jpg")
+
+    await channel._process_message(
+        {
+            "message_type": 1,
+            "message_id": "m3",
+            "from_user_id": "wx-user",
+            "context_token": "ctx-3",
+            "item_list": [
+                {"type": ITEM_IMAGE, "image_item": {"media": {"encrypt_query_param": "x"}}},
+            ],
+        }
+    )
+
+    inbound = await asyncio.wait_for(bus.consume_inbound(), timeout=1.0)
+
+    assert "[image]" in inbound.content
+    assert "/tmp/test.jpg" in inbound.content
+    assert inbound.media == ["/tmp/test.jpg"]
+
+
+@pytest.mark.asyncio
+async def test_send_without_context_token_does_not_send_text() -> None:
+    channel, _bus = _make_channel()
+    channel._client = object()
+    channel._token = "token"
+    channel._send_text = AsyncMock()
+
+    await channel.send(
+        type("Msg", (), {"chat_id": "unknown-user", "content": "pong", "media": [], "metadata": {}})()
+    )
+
+    channel._send_text.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_process_message_skips_bot_messages() -> None:
+    channel, bus = _make_channel()
+
+    await channel._process_message(
+        {
+            "message_type": MESSAGE_TYPE_BOT,
+            "message_id": "m4",
+            "from_user_id": "wx-user",
+            "item_list": [
+                {"type": ITEM_TEXT, "text_item": {"text": "hello"}},
+            ],
+        }
+    )
+
+    assert bus.inbound_size == 0

tests/test_whatsapp_channel.py

@@ -0,0 +1,108 @@
+"""Tests for WhatsApp channel outbound media support."""
+
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.channels.whatsapp import WhatsAppChannel
+
+
+def _make_channel() -> WhatsAppChannel:
+    bus = MagicMock()
+    ch = WhatsAppChannel({"enabled": True}, bus)
+    ch._ws = AsyncMock()
+    ch._connected = True
+    return ch
+
+
+@pytest.mark.asyncio
+async def test_send_text_only():
+    ch = _make_channel()
+    msg = OutboundMessage(channel="whatsapp", chat_id="123@s.whatsapp.net", content="hello")
+
+    await ch.send(msg)
+
+    ch._ws.send.assert_called_once()
+    payload = json.loads(ch._ws.send.call_args[0][0])
+    assert payload["type"] == "send"
+    assert payload["text"] == "hello"
+
+
+@pytest.mark.asyncio
+async def test_send_media_dispatches_send_media_command():
+    ch = _make_channel()
+    msg = OutboundMessage(
+        channel="whatsapp",
+        chat_id="123@s.whatsapp.net",
+        content="check this out",
+        media=["/tmp/photo.jpg"],
+    )
+
+    await ch.send(msg)
+
+    assert ch._ws.send.call_count == 2
+    text_payload = json.loads(ch._ws.send.call_args_list[0][0][0])
+    media_payload = json.loads(ch._ws.send.call_args_list[1][0][0])
+
+    assert text_payload["type"] == "send"
+    assert text_payload["text"] == "check this out"
+
+    assert media_payload["type"] == "send_media"
+    assert media_payload["filePath"] == "/tmp/photo.jpg"
+    assert media_payload["mimetype"] == "image/jpeg"
+    assert media_payload["fileName"] == "photo.jpg"
+
+
+@pytest.mark.asyncio
+async def test_send_media_only_no_text():
+    ch = _make_channel()
+    msg = OutboundMessage(
+        channel="whatsapp",
+        chat_id="123@s.whatsapp.net",
+        content="",
+        media=["/tmp/doc.pdf"],
+    )
+
+    await ch.send(msg)
+
+    ch._ws.send.assert_called_once()
+    payload = json.loads(ch._ws.send.call_args[0][0])
+    assert payload["type"] == "send_media"
+    assert payload["mimetype"] == "application/pdf"
+
+
+@pytest.mark.asyncio
+async def test_send_multiple_media():
+    ch = _make_channel()
+    msg = OutboundMessage(
+        channel="whatsapp",
+        chat_id="123@s.whatsapp.net",
+        content="",
+        media=["/tmp/a.png", "/tmp/b.mp4"],
+    )
+
+    await ch.send(msg)
+
+    assert ch._ws.send.call_count == 2
+    p1 = json.loads(ch._ws.send.call_args_list[0][0][0])
+    p2 = json.loads(ch._ws.send.call_args_list[1][0][0])
+    assert p1["mimetype"] == "image/png"
+    assert p2["mimetype"] == "video/mp4"
+
+
+@pytest.mark.asyncio
+async def test_send_when_disconnected_is_noop():
+    ch = _make_channel()
+    ch._connected = False
+
+    msg = OutboundMessage(
+        channel="whatsapp",
+        chat_id="123@s.whatsapp.net",
+        content="hello",
+        media=["/tmp/x.jpg"],
+    )
+    await ch.send(msg)
+
+    ch._ws.send.assert_not_called()