tags for single-paragraph messages. + if html.count("
") == 1: + html = html.replace("
", "").replace("
", "") + return html + except ImportError: + pass + + # Minimal fallback: just handle bold, italic, code. + html = text + html = re.sub(r"\*\*(.+?)\*\*", r"\1", html) + html = re.sub(r"\*(.+?)\*", r"\1", html) + html = re.sub(r"`([^`]+)`", r"\1", html)
+ html = re.sub(r"\n", r" tags."""
+ result = self.adapter._markdown_to_html("`code`")
+ assert "" in result
+
+ def test_plain_text_returns_html(self):
+ """Plain text should still be returned (possibly with
or )."""
+ result = self.adapter._markdown_to_html("Hello world")
+ assert "Hello world" in result
+
+
+# ---------------------------------------------------------------------------
+# Helper: display name extraction
+# ---------------------------------------------------------------------------
+
+class TestMatrixDisplayName:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+
+ def test_get_display_name_from_room_users(self):
+ """Should get display name from room's users dict."""
+ mock_room = MagicMock()
+ mock_user = MagicMock()
+ mock_user.display_name = "Alice"
+ mock_room.users = {"@alice:ex.org": mock_user}
+
+ name = self.adapter._get_display_name(mock_room, "@alice:ex.org")
+ assert name == "Alice"
+
+ def test_get_display_name_fallback_to_localpart(self):
+ """Should extract localpart from @user:server format."""
+ mock_room = MagicMock()
+ mock_room.users = {}
+
+ name = self.adapter._get_display_name(mock_room, "@bob:example.org")
+ assert name == "bob"
+
+ def test_get_display_name_no_room(self):
+ """Should handle None room gracefully."""
+ name = self.adapter._get_display_name(None, "@charlie:ex.org")
+ assert name == "charlie"
+
+
+# ---------------------------------------------------------------------------
+# Requirements check
+# ---------------------------------------------------------------------------
+
+class TestMatrixRequirements:
+ def test_check_requirements_with_token(self, monkeypatch):
+ monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "syt_test")
+ monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+ from gateway.platforms.matrix import check_matrix_requirements
+ try:
+ import nio # noqa: F401
+ assert check_matrix_requirements() is True
+ except ImportError:
+ assert check_matrix_requirements() is False
+
+ def test_check_requirements_without_creds(self, monkeypatch):
+ monkeypatch.delenv("MATRIX_ACCESS_TOKEN", raising=False)
+ monkeypatch.delenv("MATRIX_PASSWORD", raising=False)
+ monkeypatch.delenv("MATRIX_HOMESERVER", raising=False)
+ from gateway.platforms.matrix import check_matrix_requirements
+ assert check_matrix_requirements() is False
+
+ def test_check_requirements_without_homeserver(self, monkeypatch):
+ monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "syt_test")
+ monkeypatch.delenv("MATRIX_HOMESERVER", raising=False)
+ from gateway.platforms.matrix import check_matrix_requirements
+ assert check_matrix_requirements() is False
diff --git a/tests/gateway/test_mattermost.py b/tests/gateway/test_mattermost.py
new file mode 100644
index 000000000..6b0fbd899
--- /dev/null
+++ b/tests/gateway/test_mattermost.py
@@ -0,0 +1,574 @@
+"""Tests for Mattermost platform adapter."""
+import json
+import time
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock
+
+from gateway.config import Platform, PlatformConfig
+
+
+# ---------------------------------------------------------------------------
+# Platform & Config
+# ---------------------------------------------------------------------------
+
+class TestMattermostPlatformEnum:
+ def test_mattermost_enum_exists(self):
+ assert Platform.MATTERMOST.value == "mattermost"
+
+ def test_mattermost_in_platform_list(self):
+ platforms = [p.value for p in Platform]
+ assert "mattermost" in platforms
+
+
+class TestMattermostConfigLoading:
+ def test_apply_env_overrides_mattermost(self, monkeypatch):
+ monkeypatch.setenv("MATTERMOST_TOKEN", "mm-tok-abc123")
+ monkeypatch.setenv("MATTERMOST_URL", "https://mm.example.com")
+
+ from gateway.config import GatewayConfig, _apply_env_overrides
+ config = GatewayConfig()
+ _apply_env_overrides(config)
+
+ assert Platform.MATTERMOST in config.platforms
+ mc = config.platforms[Platform.MATTERMOST]
+ assert mc.enabled is True
+ assert mc.token == "mm-tok-abc123"
+ assert mc.extra.get("url") == "https://mm.example.com"
+
+ def test_mattermost_not_loaded_without_token(self, monkeypatch):
+ monkeypatch.delenv("MATTERMOST_TOKEN", raising=False)
+ monkeypatch.delenv("MATTERMOST_URL", raising=False)
+
+ from gateway.config import GatewayConfig, _apply_env_overrides
+ config = GatewayConfig()
+ _apply_env_overrides(config)
+
+ assert Platform.MATTERMOST not in config.platforms
+
+ def test_connected_platforms_includes_mattermost(self, monkeypatch):
+ monkeypatch.setenv("MATTERMOST_TOKEN", "mm-tok-abc123")
+ monkeypatch.setenv("MATTERMOST_URL", "https://mm.example.com")
+
+ from gateway.config import GatewayConfig, _apply_env_overrides
+ config = GatewayConfig()
+ _apply_env_overrides(config)
+
+ connected = config.get_connected_platforms()
+ assert Platform.MATTERMOST in connected
+
+ def test_mattermost_home_channel(self, monkeypatch):
+ monkeypatch.setenv("MATTERMOST_TOKEN", "mm-tok-abc123")
+ monkeypatch.setenv("MATTERMOST_URL", "https://mm.example.com")
+ monkeypatch.setenv("MATTERMOST_HOME_CHANNEL", "ch_abc123")
+ monkeypatch.setenv("MATTERMOST_HOME_CHANNEL_NAME", "General")
+
+ from gateway.config import GatewayConfig, _apply_env_overrides
+ config = GatewayConfig()
+ _apply_env_overrides(config)
+
+ home = config.get_home_channel(Platform.MATTERMOST)
+ assert home is not None
+ assert home.chat_id == "ch_abc123"
+ assert home.name == "General"
+
+ def test_mattermost_url_warning_without_url(self, monkeypatch):
+ """MATTERMOST_TOKEN set but MATTERMOST_URL missing should still load."""
+ monkeypatch.setenv("MATTERMOST_TOKEN", "mm-tok-abc123")
+ monkeypatch.delenv("MATTERMOST_URL", raising=False)
+
+ from gateway.config import GatewayConfig, _apply_env_overrides
+ config = GatewayConfig()
+ _apply_env_overrides(config)
+
+ assert Platform.MATTERMOST in config.platforms
+ assert config.platforms[Platform.MATTERMOST].extra.get("url") == ""
+
+
+# ---------------------------------------------------------------------------
+# Adapter format / truncate
+# ---------------------------------------------------------------------------
+
+def _make_adapter():
+ """Create a MattermostAdapter with mocked config."""
+ from gateway.platforms.mattermost import MattermostAdapter
+ config = PlatformConfig(
+ enabled=True,
+ token="test-token",
+ extra={"url": "https://mm.example.com"},
+ )
+ adapter = MattermostAdapter(config)
+ return adapter
+
+
+class TestMattermostFormatMessage:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+
+ def test_image_markdown_to_url(self):
+ """ should be converted to just the URL."""
+ result = self.adapter.format_message("")
+ assert result == "https://img.example.com/cat.png"
+
+ def test_image_markdown_strips_alt_text(self):
+ result = self.adapter.format_message("Here:  done")
+ assert ""
+ assert self.adapter.format_message(content) == content
+
+ def test_plain_text_unchanged(self):
+ content = "Hello, world!"
+ assert self.adapter.format_message(content) == content
+
+ def test_multiple_images(self):
+ content = " text "
+ result = self.adapter.format_message(content)
+ assert "![" not in result
+ assert "http://a.com/1.png" in result
+ assert "http://b.com/2.png" in result
+
+
+class TestMattermostTruncateMessage:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+
+ def test_short_message_single_chunk(self):
+ msg = "Hello, world!"
+ chunks = self.adapter.truncate_message(msg, 4000)
+ assert len(chunks) == 1
+ assert chunks[0] == msg
+
+ def test_long_message_splits(self):
+ msg = "a " * 2500 # 5000 chars
+ chunks = self.adapter.truncate_message(msg, 4000)
+ assert len(chunks) >= 2
+ for chunk in chunks:
+ assert len(chunk) <= 4000
+
+ def test_custom_max_length(self):
+ msg = "Hello " * 20
+ chunks = self.adapter.truncate_message(msg, max_length=50)
+ assert all(len(c) <= 50 for c in chunks)
+
+ def test_exactly_at_limit(self):
+ msg = "x" * 4000
+ chunks = self.adapter.truncate_message(msg, 4000)
+ assert len(chunks) == 1
+
+
+# ---------------------------------------------------------------------------
+# Send
+# ---------------------------------------------------------------------------
+
+class TestMattermostSend:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+ self.adapter._session = MagicMock()
+
+ @pytest.mark.asyncio
+ async def test_send_calls_api_post(self):
+ """send() should POST to /api/v4/posts with channel_id and message."""
+ mock_resp = AsyncMock()
+ mock_resp.status = 200
+ mock_resp.json = AsyncMock(return_value={"id": "post123"})
+ mock_resp.text = AsyncMock(return_value="")
+ mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+ mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+ self.adapter._session.post = MagicMock(return_value=mock_resp)
+
+ result = await self.adapter.send("channel_1", "Hello!")
+
+ assert result.success is True
+ assert result.message_id == "post123"
+
+ # Verify post was called with correct URL
+ call_args = self.adapter._session.post.call_args
+ assert "/api/v4/posts" in call_args[0][0]
+ # Verify payload
+ payload = call_args[1]["json"]
+ assert payload["channel_id"] == "channel_1"
+ assert payload["message"] == "Hello!"
+
+ @pytest.mark.asyncio
+ async def test_send_empty_content_succeeds(self):
+ """Empty content should return success without calling the API."""
+ result = await self.adapter.send("channel_1", "")
+ assert result.success is True
+
+ @pytest.mark.asyncio
+ async def test_send_with_thread_reply(self):
+ """When reply_mode is 'thread', reply_to should become root_id."""
+ self.adapter._reply_mode = "thread"
+
+ mock_resp = AsyncMock()
+ mock_resp.status = 200
+ mock_resp.json = AsyncMock(return_value={"id": "post456"})
+ mock_resp.text = AsyncMock(return_value="")
+ mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+ mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+ self.adapter._session.post = MagicMock(return_value=mock_resp)
+
+ result = await self.adapter.send("channel_1", "Reply!", reply_to="root_post")
+
+ assert result.success is True
+ payload = self.adapter._session.post.call_args[1]["json"]
+ assert payload["root_id"] == "root_post"
+
+ @pytest.mark.asyncio
+ async def test_send_without_thread_no_root_id(self):
+ """When reply_mode is 'off', reply_to should NOT set root_id."""
+ self.adapter._reply_mode = "off"
+
+ mock_resp = AsyncMock()
+ mock_resp.status = 200
+ mock_resp.json = AsyncMock(return_value={"id": "post789"})
+ mock_resp.text = AsyncMock(return_value="")
+ mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+ mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+ self.adapter._session.post = MagicMock(return_value=mock_resp)
+
+ result = await self.adapter.send("channel_1", "Reply!", reply_to="root_post")
+
+ assert result.success is True
+ payload = self.adapter._session.post.call_args[1]["json"]
+ assert "root_id" not in payload
+
+ @pytest.mark.asyncio
+ async def test_send_api_failure(self):
+ """When API returns error, send should return failure."""
+ mock_resp = AsyncMock()
+ mock_resp.status = 500
+ mock_resp.json = AsyncMock(return_value={})
+ mock_resp.text = AsyncMock(return_value="Internal Server Error")
+ mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+ mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+ self.adapter._session.post = MagicMock(return_value=mock_resp)
+
+ result = await self.adapter.send("channel_1", "Hello!")
+
+ assert result.success is False
+
+
+# ---------------------------------------------------------------------------
+# WebSocket event parsing
+# ---------------------------------------------------------------------------
+
+class TestMattermostWebSocketParsing:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+ self.adapter._bot_user_id = "bot_user_id"
+ # Mock handle_message to capture the MessageEvent without processing
+ self.adapter.handle_message = AsyncMock()
+
+ @pytest.mark.asyncio
+ async def test_parse_posted_event(self):
+ """'posted' events should extract message from double-encoded post JSON."""
+ post_data = {
+ "id": "post_abc",
+ "user_id": "user_123",
+ "channel_id": "chan_456",
+ "message": "Hello from Matrix!",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data), # double-encoded JSON string
+ "channel_type": "O",
+ "sender_name": "@alice",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert self.adapter.handle_message.called
+ msg_event = self.adapter.handle_message.call_args[0][0]
+ assert msg_event.text == "Hello from Matrix!"
+ assert msg_event.message_id == "post_abc"
+
+ @pytest.mark.asyncio
+ async def test_ignore_own_messages(self):
+ """Messages from the bot's own user_id should be ignored."""
+ post_data = {
+ "id": "post_self",
+ "user_id": "bot_user_id", # same as bot
+ "channel_id": "chan_456",
+ "message": "Bot echo",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "O",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert not self.adapter.handle_message.called
+
+ @pytest.mark.asyncio
+ async def test_ignore_non_posted_events(self):
+ """Non-'posted' events should be ignored."""
+ event = {
+ "event": "typing",
+ "data": {"user_id": "user_123"},
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert not self.adapter.handle_message.called
+
+ @pytest.mark.asyncio
+ async def test_ignore_system_posts(self):
+ """Posts with a 'type' field (system messages) should be ignored."""
+ post_data = {
+ "id": "sys_post",
+ "user_id": "user_123",
+ "channel_id": "chan_456",
+ "message": "user joined",
+ "type": "system_join_channel",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "O",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert not self.adapter.handle_message.called
+
+ @pytest.mark.asyncio
+ async def test_channel_type_mapping(self):
+ """channel_type 'D' should map to 'dm'."""
+ post_data = {
+ "id": "post_dm",
+ "user_id": "user_123",
+ "channel_id": "chan_dm",
+ "message": "DM message",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "D",
+ "sender_name": "@bob",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert self.adapter.handle_message.called
+ msg_event = self.adapter.handle_message.call_args[0][0]
+ assert msg_event.source.chat_type == "dm"
+
+ @pytest.mark.asyncio
+ async def test_thread_id_from_root_id(self):
+ """Post with root_id should have thread_id set."""
+ post_data = {
+ "id": "post_reply",
+ "user_id": "user_123",
+ "channel_id": "chan_456",
+ "message": "Thread reply",
+ "root_id": "root_post_123",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "O",
+ "sender_name": "@alice",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert self.adapter.handle_message.called
+ msg_event = self.adapter.handle_message.call_args[0][0]
+ assert msg_event.source.thread_id == "root_post_123"
+
+ @pytest.mark.asyncio
+ async def test_invalid_post_json_ignored(self):
+ """Invalid JSON in data.post should be silently ignored."""
+ event = {
+ "event": "posted",
+ "data": {
+ "post": "not-valid-json{{{",
+ "channel_type": "O",
+ },
+ }
+
+ await self.adapter._handle_ws_event(event)
+ assert not self.adapter.handle_message.called
+
+
+# ---------------------------------------------------------------------------
+# File upload (send_image)
+# ---------------------------------------------------------------------------
+
+class TestMattermostFileUpload:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+ self.adapter._session = MagicMock()
+
+ @pytest.mark.asyncio
+ async def test_send_image_downloads_and_uploads(self):
+ """send_image should download the URL, upload via /api/v4/files, then post."""
+ # Mock the download (GET)
+ mock_dl_resp = AsyncMock()
+ mock_dl_resp.status = 200
+ mock_dl_resp.read = AsyncMock(return_value=b"\x89PNG\x00fake-image-data")
+ mock_dl_resp.content_type = "image/png"
+ mock_dl_resp.__aenter__ = AsyncMock(return_value=mock_dl_resp)
+ mock_dl_resp.__aexit__ = AsyncMock(return_value=False)
+
+ # Mock the upload (POST to /files)
+ mock_upload_resp = AsyncMock()
+ mock_upload_resp.status = 200
+ mock_upload_resp.json = AsyncMock(return_value={
+ "file_infos": [{"id": "file_abc123"}]
+ })
+ mock_upload_resp.text = AsyncMock(return_value="")
+ mock_upload_resp.__aenter__ = AsyncMock(return_value=mock_upload_resp)
+ mock_upload_resp.__aexit__ = AsyncMock(return_value=False)
+
+ # Mock the post (POST to /posts)
+ mock_post_resp = AsyncMock()
+ mock_post_resp.status = 200
+ mock_post_resp.json = AsyncMock(return_value={"id": "post_with_file"})
+ mock_post_resp.text = AsyncMock(return_value="")
+ mock_post_resp.__aenter__ = AsyncMock(return_value=mock_post_resp)
+ mock_post_resp.__aexit__ = AsyncMock(return_value=False)
+
+ # Route calls: first GET (download), then POST (upload), then POST (create post)
+ self.adapter._session.get = MagicMock(return_value=mock_dl_resp)
+ post_call_count = 0
+ original_post_returns = [mock_upload_resp, mock_post_resp]
+
+ def post_side_effect(*args, **kwargs):
+ nonlocal post_call_count
+ resp = original_post_returns[min(post_call_count, len(original_post_returns) - 1)]
+ post_call_count += 1
+ return resp
+
+ self.adapter._session.post = MagicMock(side_effect=post_side_effect)
+
+ result = await self.adapter.send_image(
+ "channel_1", "https://img.example.com/cat.png", caption="A cat"
+ )
+
+ assert result.success is True
+ assert result.message_id == "post_with_file"
+
+
+# ---------------------------------------------------------------------------
+# Dedup cache
+# ---------------------------------------------------------------------------
+
+class TestMattermostDedup:
+ def setup_method(self):
+ self.adapter = _make_adapter()
+ self.adapter._bot_user_id = "bot_user_id"
+ # Mock handle_message to capture calls without processing
+ self.adapter.handle_message = AsyncMock()
+
+ @pytest.mark.asyncio
+ async def test_duplicate_post_ignored(self):
+ """The same post_id within the TTL window should be ignored."""
+ post_data = {
+ "id": "post_dup",
+ "user_id": "user_123",
+ "channel_id": "chan_456",
+ "message": "Hello!",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "O",
+ "sender_name": "@alice",
+ },
+ }
+
+ # First time: should process
+ await self.adapter._handle_ws_event(event)
+ assert self.adapter.handle_message.call_count == 1
+
+ # Second time (same post_id): should be deduped
+ await self.adapter._handle_ws_event(event)
+ assert self.adapter.handle_message.call_count == 1 # still 1
+
+ @pytest.mark.asyncio
+ async def test_different_post_ids_both_processed(self):
+ """Different post IDs should both be processed."""
+ for i, pid in enumerate(["post_a", "post_b"]):
+ post_data = {
+ "id": pid,
+ "user_id": "user_123",
+ "channel_id": "chan_456",
+ "message": f"Message {i}",
+ }
+ event = {
+ "event": "posted",
+ "data": {
+ "post": json.dumps(post_data),
+ "channel_type": "O",
+ "sender_name": "@alice",
+ },
+ }
+ await self.adapter._handle_ws_event(event)
+
+ assert self.adapter.handle_message.call_count == 2
+
+ def test_prune_seen_clears_expired(self):
+ """_prune_seen should remove entries older than _SEEN_TTL."""
+ now = time.time()
+ # Fill with enough expired entries to trigger pruning
+ for i in range(self.adapter._SEEN_MAX + 10):
+ self.adapter._seen_posts[f"old_{i}"] = now - 600 # 10 min ago
+
+ # Add a fresh one
+ self.adapter._seen_posts["fresh"] = now
+
+ self.adapter._prune_seen()
+
+ # Old entries should be pruned, fresh one kept
+ assert "fresh" in self.adapter._seen_posts
+ assert len(self.adapter._seen_posts) < self.adapter._SEEN_MAX
+
+ def test_seen_cache_tracks_post_ids(self):
+ """Posts are tracked in _seen_posts dict."""
+ self.adapter._seen_posts["test_post"] = time.time()
+ assert "test_post" in self.adapter._seen_posts
+
+
+# ---------------------------------------------------------------------------
+# Requirements check
+# ---------------------------------------------------------------------------
+
+class TestMattermostRequirements:
+ def test_check_requirements_with_token_and_url(self, monkeypatch):
+ monkeypatch.setenv("MATTERMOST_TOKEN", "test-token")
+ monkeypatch.setenv("MATTERMOST_URL", "https://mm.example.com")
+ from gateway.platforms.mattermost import check_mattermost_requirements
+ assert check_mattermost_requirements() is True
+
+ def test_check_requirements_without_token(self, monkeypatch):
+ monkeypatch.delenv("MATTERMOST_TOKEN", raising=False)
+ monkeypatch.delenv("MATTERMOST_URL", raising=False)
+ from gateway.platforms.mattermost import check_mattermost_requirements
+ assert check_mattermost_requirements() is False
+
+ def test_check_requirements_without_url(self, monkeypatch):
+ monkeypatch.setenv("MATTERMOST_TOKEN", "test-token")
+ monkeypatch.delenv("MATTERMOST_URL", raising=False)
+ from gateway.platforms.mattermost import check_mattermost_requirements
+ assert check_mattermost_requirements() is False
diff --git a/tests/gateway/test_session.py b/tests/gateway/test_session.py
index e29a9583d..afe436870 100644
--- a/tests/gateway/test_session.py
+++ b/tests/gateway/test_session.py
@@ -703,5 +703,15 @@ class TestLastPromptTokens:
store.update_session("k1", model="openai/gpt-5.4")
store._db.update_token_counts.assert_called_once_with(
- "s1", 0, 0, model="openai/gpt-5.4"
+ "s1",
+ input_tokens=0,
+ output_tokens=0,
+ cache_read_tokens=0,
+ cache_write_tokens=0,
+ estimated_cost_usd=None,
+ cost_status=None,
+ cost_source=None,
+ billing_provider=None,
+ billing_base_url=None,
+ model="openai/gpt-5.4",
)
diff --git a/tests/gateway/test_sms.py b/tests/gateway/test_sms.py
index e3d927bb3..54c1edf23 100644
--- a/tests/gateway/test_sms.py
+++ b/tests/gateway/test_sms.py
@@ -1,240 +1,215 @@
-"""Tests for SMS (Telnyx) platform adapter."""
-import json
+"""Tests for SMS (Twilio) platform integration.
+
+Covers config loading, format/truncate, echo prevention,
+requirements check, and toolset verification.
+"""
+
+import os
+from unittest.mock import patch
+
import pytest
-from unittest.mock import MagicMock, patch, AsyncMock
-from gateway.config import Platform, PlatformConfig
+from gateway.config import Platform, PlatformConfig, HomeChannel
-# ---------------------------------------------------------------------------
-# Platform & Config
-# ---------------------------------------------------------------------------
-
-class TestSmsPlatformEnum:
- def test_sms_enum_exists(self):
- assert Platform.SMS.value == "sms"
-
- def test_sms_in_platform_list(self):
- platforms = [p.value for p in Platform]
- assert "sms" in platforms
-
+# ── Config loading ──────────────────────────────────────────────────
class TestSmsConfigLoading:
- def test_apply_env_overrides_sms(self, monkeypatch):
- monkeypatch.setenv("TELNYX_API_KEY", "KEY_test123")
+ """Verify _apply_env_overrides wires SMS correctly."""
- from gateway.config import GatewayConfig, _apply_env_overrides
- config = GatewayConfig()
- _apply_env_overrides(config)
+ def test_sms_platform_enum_exists(self):
+ assert Platform.SMS.value == "sms"
- assert Platform.SMS in config.platforms
- sc = config.platforms[Platform.SMS]
- assert sc.enabled is True
- assert sc.api_key == "KEY_test123"
+ def test_env_overrides_create_sms_config(self):
+ from gateway.config import load_gateway_config
- def test_sms_not_loaded_without_key(self, monkeypatch):
- monkeypatch.delenv("TELNYX_API_KEY", raising=False)
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest123",
+ "TWILIO_AUTH_TOKEN": "token_abc",
+ "TWILIO_PHONE_NUMBER": "+15551234567",
+ }
+ with patch.dict(os.environ, env, clear=False):
+ config = load_gateway_config()
+ assert Platform.SMS in config.platforms
+ pc = config.platforms[Platform.SMS]
+ assert pc.enabled is True
+ assert pc.api_key == "token_abc"
- from gateway.config import GatewayConfig, _apply_env_overrides
- config = GatewayConfig()
- _apply_env_overrides(config)
+ def test_env_overrides_set_home_channel(self):
+ from gateway.config import load_gateway_config
- assert Platform.SMS not in config.platforms
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest123",
+ "TWILIO_AUTH_TOKEN": "token_abc",
+ "TWILIO_PHONE_NUMBER": "+15551234567",
+ "SMS_HOME_CHANNEL": "+15559876543",
+ "SMS_HOME_CHANNEL_NAME": "My Phone",
+ }
+ with patch.dict(os.environ, env, clear=False):
+ config = load_gateway_config()
+ hc = config.platforms[Platform.SMS].home_channel
+ assert hc is not None
+ assert hc.chat_id == "+15559876543"
+ assert hc.name == "My Phone"
+ assert hc.platform == Platform.SMS
- def test_connected_platforms_includes_sms(self, monkeypatch):
- monkeypatch.setenv("TELNYX_API_KEY", "KEY_test123")
+ def test_sms_in_connected_platforms(self):
+ from gateway.config import load_gateway_config
- from gateway.config import GatewayConfig, _apply_env_overrides
- config = GatewayConfig()
- _apply_env_overrides(config)
-
- connected = config.get_connected_platforms()
- assert Platform.SMS in connected
-
- def test_sms_home_channel(self, monkeypatch):
- monkeypatch.setenv("TELNYX_API_KEY", "KEY_test123")
- monkeypatch.setenv("SMS_HOME_CHANNEL", "+15559876543")
- monkeypatch.setenv("SMS_HOME_CHANNEL_NAME", "Owner")
-
- from gateway.config import GatewayConfig, _apply_env_overrides
- config = GatewayConfig()
- _apply_env_overrides(config)
-
- home = config.get_home_channel(Platform.SMS)
- assert home is not None
- assert home.chat_id == "+15559876543"
- assert home.name == "Owner"
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest123",
+ "TWILIO_AUTH_TOKEN": "token_abc",
+ }
+ with patch.dict(os.environ, env, clear=False):
+ config = load_gateway_config()
+ connected = config.get_connected_platforms()
+ assert Platform.SMS in connected
-# ---------------------------------------------------------------------------
-# Adapter format / truncate
-# ---------------------------------------------------------------------------
+# ── Format / truncate ───────────────────────────────────────────────
-class TestSmsFormatMessage:
- def setup_method(self):
+class TestSmsFormatAndTruncate:
+ """Test SmsAdapter.format_message strips markdown."""
+
+ def _make_adapter(self):
from gateway.platforms.sms import SmsAdapter
- config = PlatformConfig(enabled=True, api_key="test_key")
- with patch.dict("os.environ", {"TELNYX_API_KEY": "test_key"}):
- self.adapter = SmsAdapter(config)
- def test_strip_bold(self):
- assert self.adapter.format_message("**bold**") == "bold"
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest",
+ "TWILIO_AUTH_TOKEN": "tok",
+ "TWILIO_PHONE_NUMBER": "+15550001111",
+ }
+ with patch.dict(os.environ, env):
+ pc = PlatformConfig(enabled=True, api_key="tok")
+ adapter = object.__new__(SmsAdapter)
+ adapter.config = pc
+ adapter._platform = Platform.SMS
+ adapter._account_sid = "ACtest"
+ adapter._auth_token = "tok"
+ adapter._from_number = "+15550001111"
+ return adapter
- def test_strip_italic(self):
- assert self.adapter.format_message("*italic*") == "italic"
+ def test_strips_bold(self):
+ adapter = self._make_adapter()
+ assert adapter.format_message("**hello**") == "hello"
- def test_strip_code_block(self):
- result = self.adapter.format_message("```python\ncode\n```")
+ def test_strips_italic(self):
+ adapter = self._make_adapter()
+ assert adapter.format_message("*world*") == "world"
+
+ def test_strips_code_blocks(self):
+ adapter = self._make_adapter()
+ result = adapter.format_message("```python\nprint('hi')\n```")
assert "```" not in result
- assert "code" in result
+ assert "print('hi')" in result
- def test_strip_inline_code(self):
- assert self.adapter.format_message("`code`") == "code"
+ def test_strips_inline_code(self):
+ adapter = self._make_adapter()
+ assert adapter.format_message("`code`") == "code"
- def test_strip_headers(self):
- assert self.adapter.format_message("## Header") == "Header"
+ def test_strips_headers(self):
+ adapter = self._make_adapter()
+ assert adapter.format_message("## Title") == "Title"
- def test_strip_links(self):
- assert self.adapter.format_message("[click](http://example.com)") == "click"
+ def test_strips_links(self):
+ adapter = self._make_adapter()
+ assert adapter.format_message("[click](https://example.com)") == "click"
- def test_collapse_newlines(self):
- result = self.adapter.format_message("a\n\n\n\nb")
+ def test_collapses_newlines(self):
+ adapter = self._make_adapter()
+ result = adapter.format_message("a\n\n\n\nb")
assert result == "a\n\nb"
-class TestSmsTruncateMessage:
- def setup_method(self):
+# ── Echo prevention ────────────────────────────────────────────────
+
+class TestSmsEchoPrevention:
+ """Adapter should ignore messages from its own number."""
+
+ def test_own_number_detection(self):
+ """The adapter stores _from_number for echo prevention."""
from gateway.platforms.sms import SmsAdapter
- config = PlatformConfig(enabled=True, api_key="test_key")
- with patch.dict("os.environ", {"TELNYX_API_KEY": "test_key"}):
- self.adapter = SmsAdapter(config)
- def test_short_message_single_chunk(self):
- msg = "Hello, world!"
- chunks = self.adapter.truncate_message(msg)
- assert len(chunks) == 1
- assert chunks[0] == msg
-
- def test_long_message_splits(self):
- msg = "a " * 1000 # 2000 chars
- chunks = self.adapter.truncate_message(msg)
- assert len(chunks) >= 2
- for chunk in chunks:
- assert len(chunk) <= 1600
-
- def test_custom_max_length(self):
- msg = "Hello " * 20
- chunks = self.adapter.truncate_message(msg, max_length=50)
- assert all(len(c) <= 50 for c in chunks)
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest",
+ "TWILIO_AUTH_TOKEN": "tok",
+ "TWILIO_PHONE_NUMBER": "+15550001111",
+ }
+ with patch.dict(os.environ, env):
+ pc = PlatformConfig(enabled=True, api_key="tok")
+ adapter = SmsAdapter(pc)
+ assert adapter._from_number == "+15550001111"
-# ---------------------------------------------------------------------------
-# Echo loop prevention
-# ---------------------------------------------------------------------------
-
-class TestSmsEchoLoop:
- def test_own_number_ignored(self):
- from gateway.platforms.sms import SmsAdapter
- config = PlatformConfig(enabled=True, api_key="test_key")
- with patch.dict("os.environ", {
- "TELNYX_API_KEY": "test_key",
- "TELNYX_FROM_NUMBERS": "+15551234567,+15559876543",
- }):
- adapter = SmsAdapter(config)
- assert "+15551234567" in adapter._from_numbers
- assert "+15559876543" in adapter._from_numbers
-
-
-# ---------------------------------------------------------------------------
-# Auth maps
-# ---------------------------------------------------------------------------
-
-class TestSmsAuthMaps:
- def test_sms_in_allowed_users_map(self):
- """SMS should be in the platform auth maps in run.py."""
- # Verify the env var names are consistent
- import os
- os.environ.setdefault("SMS_ALLOWED_USERS", "+15551234567")
- assert os.getenv("SMS_ALLOWED_USERS") == "+15551234567"
-
- def test_sms_allow_all_env_var(self):
- """SMS_ALLOW_ALL_USERS should be recognized."""
- import os
- os.environ.setdefault("SMS_ALLOW_ALL_USERS", "true")
- assert os.getenv("SMS_ALLOW_ALL_USERS") == "true"
-
-
-# ---------------------------------------------------------------------------
-# Requirements check
-# ---------------------------------------------------------------------------
+# ── Requirements check ─────────────────────────────────────────────
class TestSmsRequirements:
- def test_check_sms_requirements_with_key(self, monkeypatch):
- monkeypatch.setenv("TELNYX_API_KEY", "KEY_test123")
+ def test_check_sms_requirements_missing_sid(self):
from gateway.platforms.sms import check_sms_requirements
- # aiohttp is available in test environment
- assert check_sms_requirements() is True
- def test_check_sms_requirements_without_key(self, monkeypatch):
- monkeypatch.delenv("TELNYX_API_KEY", raising=False)
+ env = {"TWILIO_AUTH_TOKEN": "tok"}
+ with patch.dict(os.environ, env, clear=True):
+ assert check_sms_requirements() is False
+
+ def test_check_sms_requirements_missing_token(self):
from gateway.platforms.sms import check_sms_requirements
- assert check_sms_requirements() is False
+
+ env = {"TWILIO_ACCOUNT_SID": "ACtest"}
+ with patch.dict(os.environ, env, clear=True):
+ assert check_sms_requirements() is False
+
+ def test_check_sms_requirements_both_set(self):
+ from gateway.platforms.sms import check_sms_requirements
+
+ env = {
+ "TWILIO_ACCOUNT_SID": "ACtest",
+ "TWILIO_AUTH_TOKEN": "tok",
+ }
+ with patch.dict(os.environ, env, clear=False):
+ # Only returns True if aiohttp is also importable
+ result = check_sms_requirements()
+ try:
+ import aiohttp # noqa: F401
+ assert result is True
+ except ImportError:
+ assert result is False
-# ---------------------------------------------------------------------------
-# Toolset & integration points
-# ---------------------------------------------------------------------------
+# ── Toolset verification ───────────────────────────────────────────
class TestSmsToolset:
def test_hermes_sms_toolset_exists(self):
from toolsets import get_toolset
+
ts = get_toolset("hermes-sms")
assert ts is not None
- assert "hermes-sms" in ts.get("description", "").lower() or "sms" in ts.get("description", "").lower()
+ assert "tools" in ts
- def test_hermes_gateway_includes_sms(self):
+ def test_hermes_sms_in_gateway_includes(self):
from toolsets import get_toolset
+
gw = get_toolset("hermes-gateway")
+ assert gw is not None
assert "hermes-sms" in gw["includes"]
-
-class TestSmsPlatformHints:
- def test_sms_in_platform_hints(self):
+ def test_sms_platform_hint_exists(self):
from agent.prompt_builder import PLATFORM_HINTS
+
assert "sms" in PLATFORM_HINTS
- assert "SMS" in PLATFORM_HINTS["sms"] or "sms" in PLATFORM_HINTS["sms"].lower()
+ assert "concise" in PLATFORM_HINTS["sms"].lower()
-
-class TestSmsCronDelivery:
- def test_sms_in_cron_platform_map(self):
- """Verify the cron scheduler can resolve 'sms' platform."""
- # The platform_map in _deliver_result should include sms
- from gateway.config import Platform
+ def test_sms_in_scheduler_platform_map(self):
+ """Verify cron scheduler recognizes 'sms' as a valid platform."""
+ # Just check the Platform enum has SMS — the scheduler imports it dynamically
assert Platform.SMS.value == "sms"
-
-class TestSmsSendMessageTool:
def test_sms_in_send_message_platform_map(self):
- """The send_message tool should recognize 'sms' as a valid platform."""
- # We verify by checking that SMS is in the Platform enum
- # and the code path exists
- from gateway.config import Platform
+ """Verify send_message_tool recognizes 'sms'."""
+ # The platform_map is built inside _handle_send; verify SMS enum exists
assert hasattr(Platform, "SMS")
-
-class TestSmsChannelDirectory:
- def test_sms_in_session_discovery(self):
- """Verify SMS is included in session-based channel discovery."""
- import inspect
- from gateway.channel_directory import build_channel_directory
- source = inspect.getsource(build_channel_directory)
- assert '"sms"' in source
-
-
-class TestSmsStatus:
- def test_sms_in_status_platforms(self):
- """Verify SMS appears in the status command platforms dict."""
- import inspect
- from hermes_cli.status import show_status
- source = inspect.getsource(show_status)
- assert '"SMS"' in source or "'SMS'" in source
+ def test_sms_in_cronjob_deliver_description(self):
+ """Verify cronjob_tools mentions sms in deliver description."""
+ from tools.cronjob_tools import CRONJOB_SCHEMA
+ deliver_desc = CRONJOB_SCHEMA["parameters"]["properties"]["deliver"]["description"]
+ assert "sms" in deliver_desc.lower()
diff --git a/tests/gateway/test_status_command.py b/tests/gateway/test_status_command.py
index 1c22543f7..1378ff1cb 100644
--- a/tests/gateway/test_status_command.py
+++ b/tests/gateway/test_status_command.py
@@ -128,6 +128,13 @@ async def test_handle_message_persists_agent_token_counts(monkeypatch):
session_entry.session_key,
input_tokens=120,
output_tokens=45,
+ cache_read_tokens=0,
+ cache_write_tokens=0,
last_prompt_tokens=80,
model="openai/test-model",
+ estimated_cost_usd=None,
+ cost_status=None,
+ cost_source=None,
+ provider=None,
+ base_url=None,
)
diff --git a/tests/hermes_cli/test_config.py b/tests/hermes_cli/test_config.py
index ba4f5c844..82cb99c64 100644
--- a/tests/hermes_cli/test_config.py
+++ b/tests/hermes_cli/test_config.py
@@ -316,6 +316,38 @@ class TestSanitizeEnvLines:
assert fixes == 0
+class TestOptionalEnvVarsRegistry:
+ """Verify that key env vars are registered in OPTIONAL_ENV_VARS."""
+
+ def test_tavily_api_key_registered(self):
+ """TAVILY_API_KEY is listed in OPTIONAL_ENV_VARS."""
+ from hermes_cli.config import OPTIONAL_ENV_VARS
+ assert "TAVILY_API_KEY" in OPTIONAL_ENV_VARS
+
+ def test_tavily_api_key_is_tool_category(self):
+ """TAVILY_API_KEY is in the 'tool' category."""
+ from hermes_cli.config import OPTIONAL_ENV_VARS
+ assert OPTIONAL_ENV_VARS["TAVILY_API_KEY"]["category"] == "tool"
+
+ def test_tavily_api_key_is_password(self):
+ """TAVILY_API_KEY is marked as password."""
+ from hermes_cli.config import OPTIONAL_ENV_VARS
+ assert OPTIONAL_ENV_VARS["TAVILY_API_KEY"]["password"] is True
+
+ def test_tavily_api_key_has_url(self):
+ """TAVILY_API_KEY has a URL."""
+ from hermes_cli.config import OPTIONAL_ENV_VARS
+ assert OPTIONAL_ENV_VARS["TAVILY_API_KEY"]["url"] == "https://app.tavily.com/home"
+
+ def test_tavily_in_env_vars_by_version(self):
+ """TAVILY_API_KEY is listed in ENV_VARS_BY_VERSION."""
+ from hermes_cli.config import ENV_VARS_BY_VERSION
+ all_vars = []
+ for vars_list in ENV_VARS_BY_VERSION.values():
+ all_vars.extend(vars_list)
+ assert "TAVILY_API_KEY" in all_vars
+
+
class TestAnthropicTokenMigration:
"""Test that config version 8→9 clears ANTHROPIC_TOKEN."""
diff --git a/tests/hermes_cli/test_mcp_tools_config.py b/tests/hermes_cli/test_mcp_tools_config.py
new file mode 100644
index 000000000..d7be938ad
--- /dev/null
+++ b/tests/hermes_cli/test_mcp_tools_config.py
@@ -0,0 +1,291 @@
+"""Tests for MCP tools interactive configuration in hermes_cli.tools_config."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from hermes_cli.tools_config import _configure_mcp_tools_interactive
+
+# Patch targets: imports happen inside the function body, so patch at source
+_PROBE = "tools.mcp_tool.probe_mcp_server_tools"
+_CHECKLIST = "hermes_cli.curses_ui.curses_checklist"
+_SAVE = "hermes_cli.tools_config.save_config"
+
+
+def test_no_mcp_servers_prints_info(capsys):
+ """Returns immediately when no MCP servers are configured."""
+ config = {}
+ _configure_mcp_tools_interactive(config)
+ captured = capsys.readouterr()
+ assert "No MCP servers configured" in captured.out
+
+
+def test_all_servers_disabled_prints_info(capsys):
+ """Returns immediately when all configured servers have enabled=false."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx", "enabled": False},
+ "slack": {"command": "npx", "enabled": "false"},
+ }
+ }
+ _configure_mcp_tools_interactive(config)
+ captured = capsys.readouterr()
+ assert "disabled" in captured.out
+
+
+def test_probe_failure_shows_warning(capsys):
+ """Shows warning when probe returns no tools."""
+ config = {"mcp_servers": {"github": {"command": "npx"}}}
+ with patch(_PROBE, return_value={}):
+ _configure_mcp_tools_interactive(config)
+ captured = capsys.readouterr()
+ assert "Could not discover" in captured.out
+
+
+def test_probe_exception_shows_error(capsys):
+ """Shows error when probe raises an exception."""
+ config = {"mcp_servers": {"github": {"command": "npx"}}}
+ with patch(_PROBE, side_effect=RuntimeError("MCP not installed")):
+ _configure_mcp_tools_interactive(config)
+ captured = capsys.readouterr()
+ assert "Failed to probe" in captured.out
+
+
+def test_no_changes_when_checklist_cancelled(capsys):
+ """No config changes when user cancels (ESC) the checklist."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx", "args": ["-y", "server-github"]},
+ }
+ }
+ tools = [("create_issue", "Create an issue"), ("search_repos", "Search repos")]
+
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, return_value={0, 1}), \
+ patch(_SAVE) as mock_save:
+ _configure_mcp_tools_interactive(config)
+ mock_save.assert_not_called()
+ captured = capsys.readouterr()
+ assert "no changes" in captured.out.lower()
+
+
+def test_disabling_tool_writes_exclude_list(capsys):
+ """Unchecking a tool adds it to the exclude list."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx"},
+ }
+ }
+ tools = [
+ ("create_issue", "Create an issue"),
+ ("delete_repo", "Delete a repo"),
+ ("search_repos", "Search repos"),
+ ]
+
+ # User unchecks delete_repo (index 1)
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, return_value={0, 2}), \
+ patch(_SAVE) as mock_save:
+ _configure_mcp_tools_interactive(config)
+
+ mock_save.assert_called_once()
+ tools_cfg = config["mcp_servers"]["github"]["tools"]
+ assert tools_cfg["exclude"] == ["delete_repo"]
+ assert "include" not in tools_cfg
+
+
+def test_enabling_all_clears_filters(capsys):
+ """Checking all tools clears both include and exclude lists."""
+ config = {
+ "mcp_servers": {
+ "github": {
+ "command": "npx",
+ "tools": {"exclude": ["delete_repo"], "include": ["create_issue"]},
+ },
+ }
+ }
+ tools = [("create_issue", "Create"), ("delete_repo", "Delete")]
+
+ # User checks all tools — pre_selected would be {0} (include mode),
+ # so returning {0, 1} is a change
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, return_value={0, 1}), \
+ patch(_SAVE) as mock_save:
+ _configure_mcp_tools_interactive(config)
+
+ mock_save.assert_called_once()
+ tools_cfg = config["mcp_servers"]["github"]["tools"]
+ assert "exclude" not in tools_cfg
+ assert "include" not in tools_cfg
+
+
+def test_pre_selection_respects_existing_exclude(capsys):
+ """Tools in exclude list start unchecked."""
+ config = {
+ "mcp_servers": {
+ "github": {
+ "command": "npx",
+ "tools": {"exclude": ["delete_repo"]},
+ },
+ }
+ }
+ tools = [("create_issue", "Create"), ("delete_repo", "Delete"), ("search", "Search")]
+ captured_pre_selected = {}
+
+ def fake_checklist(title, labels, pre_selected, **kwargs):
+ captured_pre_selected["value"] = set(pre_selected)
+ return pre_selected # No changes
+
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, side_effect=fake_checklist), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ # create_issue (0) and search (2) should be pre-selected, delete_repo (1) should not
+ assert captured_pre_selected["value"] == {0, 2}
+
+
+def test_pre_selection_respects_existing_include(capsys):
+ """Only tools in include list start checked."""
+ config = {
+ "mcp_servers": {
+ "github": {
+ "command": "npx",
+ "tools": {"include": ["search"]},
+ },
+ }
+ }
+ tools = [("create_issue", "Create"), ("delete_repo", "Delete"), ("search", "Search")]
+ captured_pre_selected = {}
+
+ def fake_checklist(title, labels, pre_selected, **kwargs):
+ captured_pre_selected["value"] = set(pre_selected)
+ return pre_selected # No changes
+
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, side_effect=fake_checklist), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ # Only search (2) should be pre-selected
+ assert captured_pre_selected["value"] == {2}
+
+
+def test_multiple_servers_each_get_checklist(capsys):
+ """Each server gets its own checklist."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx"},
+ "slack": {"url": "https://mcp.example.com"},
+ }
+ }
+ checklist_calls = []
+
+ def fake_checklist(title, labels, pre_selected, **kwargs):
+ checklist_calls.append(title)
+ return pre_selected # No changes
+
+ with patch(
+ _PROBE,
+ return_value={
+ "github": [("create_issue", "Create")],
+ "slack": [("send_message", "Send")],
+ },
+ ), patch(_CHECKLIST, side_effect=fake_checklist), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ assert len(checklist_calls) == 2
+ assert any("github" in t for t in checklist_calls)
+ assert any("slack" in t for t in checklist_calls)
+
+
+def test_failed_server_shows_warning(capsys):
+ """Servers that fail to connect show warnings."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx"},
+ "broken": {"command": "nonexistent"},
+ }
+ }
+
+ # Only github succeeds
+ with patch(
+ _PROBE, return_value={"github": [("create_issue", "Create")]},
+ ), patch(_CHECKLIST, return_value={0}), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ captured = capsys.readouterr()
+ assert "broken" in captured.out
+
+
+def test_description_truncation_in_labels():
+ """Long descriptions are truncated in checklist labels."""
+ config = {
+ "mcp_servers": {
+ "github": {"command": "npx"},
+ }
+ }
+ long_desc = "A" * 100
+ captured_labels = {}
+
+ def fake_checklist(title, labels, pre_selected, **kwargs):
+ captured_labels["value"] = labels
+ return pre_selected
+
+ with patch(
+ _PROBE, return_value={"github": [("my_tool", long_desc)]},
+ ), patch(_CHECKLIST, side_effect=fake_checklist), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ label = captured_labels["value"][0]
+ assert "..." in label
+ assert len(label) < len(long_desc) + 30 # truncated + tool name + parens
+
+
+def test_switching_from_include_to_exclude(capsys):
+ """When user modifies selection, include list is replaced by exclude list."""
+ config = {
+ "mcp_servers": {
+ "github": {
+ "command": "npx",
+ "tools": {"include": ["create_issue"]},
+ },
+ }
+ }
+ tools = [("create_issue", "Create"), ("search", "Search"), ("delete", "Delete")]
+
+ # User selects create_issue and search (deselects delete)
+ # pre_selected would be {0} (only create_issue from include), so {0, 1} is a change
+ with patch(_PROBE, return_value={"github": tools}), \
+ patch(_CHECKLIST, return_value={0, 1}), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ tools_cfg = config["mcp_servers"]["github"]["tools"]
+ assert tools_cfg["exclude"] == ["delete"]
+ assert "include" not in tools_cfg
+
+
+def test_empty_tools_server_skipped(capsys):
+ """Server with no tools shows info message and skips checklist."""
+ config = {
+ "mcp_servers": {
+ "empty": {"command": "npx"},
+ }
+ }
+ checklist_calls = []
+
+ def fake_checklist(title, labels, pre_selected, **kwargs):
+ checklist_calls.append(title)
+ return pre_selected
+
+ with patch(_PROBE, return_value={"empty": []}), \
+ patch(_CHECKLIST, side_effect=fake_checklist), \
+ patch(_SAVE):
+ _configure_mcp_tools_interactive(config)
+
+ assert len(checklist_calls) == 0
+ captured = capsys.readouterr()
+ assert "no tools found" in captured.out
diff --git a/tests/hermes_cli/test_setup.py b/tests/hermes_cli/test_setup.py
index 11e633306..bc19e7bbf 100644
--- a/tests/hermes_cli/test_setup.py
+++ b/tests/hermes_cli/test_setup.py
@@ -5,6 +5,13 @@ from hermes_cli.config import load_config, save_config
from hermes_cli.setup import setup_model_provider
+def _maybe_keep_current_tts(question, choices):
+ if question != "Select TTS provider:":
+ return None
+ assert choices[-1].startswith("Keep current (")
+ return len(choices) - 1
+
+
def _clear_provider_env(monkeypatch):
for key in (
"NOUS_API_KEY",
@@ -25,16 +32,22 @@ def test_nous_oauth_setup_keeps_current_model_when_syncing_disk_provider(
config = load_config()
- # Provider selection always comes first. Depending on available vision
- # backends, setup may either skip the optional vision step or prompt for
- # it before the default-model choice. Provide enough selections for both
- # paths while still ending on "keep current model".
- prompt_choices = iter([0, 2, 2])
- monkeypatch.setattr(
- "hermes_cli.setup.prompt_choice",
- lambda *args, **kwargs: next(prompt_choices),
- )
+ def fake_prompt_choice(question, choices, default=0):
+ if question == "Select your inference provider:":
+ return 0
+ if question == "Configure vision:":
+ return len(choices) - 1
+ if question == "Select default model:":
+ assert choices[-1] == "Keep current (anthropic/claude-opus-4.6)"
+ return len(choices) - 1
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
+
+ monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", lambda *args, **kwargs: "")
+ monkeypatch.setattr("hermes_cli.auth.detect_external_credentials", lambda: [])
def _fake_login_nous(*args, **kwargs):
auth_path = tmp_path / "auth.json"
@@ -53,7 +66,6 @@ def test_nous_oauth_setup_keeps_current_model_when_syncing_disk_provider(
"hermes_cli.auth.fetch_nous_models",
lambda *args, **kwargs: ["gemini-3-flash"],
)
- monkeypatch.setattr("hermes_cli.setup._setup_tts_provider", lambda config: None)
setup_model_provider(config)
save_config(config)
@@ -75,21 +87,29 @@ def test_custom_setup_clears_active_oauth_provider(tmp_path, monkeypatch):
config = load_config()
- monkeypatch.setattr("hermes_cli.setup.prompt_choice", lambda *args, **kwargs: 3)
+ def fake_prompt_choice(question, choices, default=0):
+ if question == "Select your inference provider:":
+ return 3
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
+
+ monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
prompt_values = iter(
[
"https://custom.example/v1",
"custom-api-key",
"custom/model",
- "",
]
)
monkeypatch.setattr(
"hermes_cli.setup.prompt",
lambda *args, **kwargs: next(prompt_values),
)
- monkeypatch.setattr("hermes_cli.setup._setup_tts_provider", lambda config: None)
+ monkeypatch.setattr("hermes_cli.setup.prompt_yes_no", lambda *args, **kwargs: False)
+ monkeypatch.setattr("hermes_cli.auth.detect_external_credentials", lambda: [])
setup_model_provider(config)
save_config(config)
@@ -111,11 +131,17 @@ def test_codex_setup_uses_runtime_access_token_for_live_model_list(tmp_path, mon
config = load_config()
- prompt_choices = iter([1, 0])
- monkeypatch.setattr(
- "hermes_cli.setup.prompt_choice",
- lambda *args, **kwargs: next(prompt_choices),
- )
+ def fake_prompt_choice(question, choices, default=0):
+ if question == "Select your inference provider:":
+ return 1
+ if question == "Select default model:":
+ return 0
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
+
+ monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", lambda *args, **kwargs: "")
monkeypatch.setattr("hermes_cli.auth.detect_external_credentials", lambda: [])
monkeypatch.setattr("hermes_cli.auth._login_openai_codex", lambda *args, **kwargs: None)
@@ -137,7 +163,6 @@ def test_codex_setup_uses_runtime_access_token_for_live_model_list(tmp_path, mon
"hermes_cli.codex_models.get_codex_model_ids",
_fake_get_codex_model_ids,
)
- monkeypatch.setattr("hermes_cli.setup._setup_tts_provider", lambda config: None)
setup_model_provider(config)
save_config(config)
diff --git a/tests/hermes_cli/test_setup_model_provider.py b/tests/hermes_cli/test_setup_model_provider.py
index 9b44f6bcd..671bb9ba3 100644
--- a/tests/hermes_cli/test_setup_model_provider.py
+++ b/tests/hermes_cli/test_setup_model_provider.py
@@ -6,6 +6,13 @@ from hermes_cli.config import load_config, save_config, save_env_value
from hermes_cli.setup import _print_setup_summary, setup_model_provider
+def _maybe_keep_current_tts(question, choices):
+ if question != "Select TTS provider:":
+ return None
+ assert choices[-1].startswith("Keep current (")
+ return len(choices) - 1
+
+
def _read_env(home):
env_path = home / ".env"
data = {}
@@ -50,19 +57,18 @@ def test_setup_keep_current_custom_from_config_does_not_fall_through(tmp_path, m
}
save_config(config)
- calls = {"count": 0}
-
def fake_prompt_choice(question, choices, default=0):
- calls["count"] += 1
- if calls["count"] == 1:
+ if question == "Select your inference provider:":
assert choices[-1] == "Keep current (Custom: https://example.invalid/v1)"
return len(choices) - 1
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
raise AssertionError("Model menu should not appear for keep-current custom")
monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", lambda *args, **kwargs: "")
monkeypatch.setattr("hermes_cli.setup.prompt_yes_no", lambda *args, **kwargs: False)
- monkeypatch.setattr("hermes_cli.setup._setup_tts_provider", lambda config: None)
monkeypatch.setattr("hermes_cli.auth.get_active_provider", lambda: None)
monkeypatch.setattr("hermes_cli.auth.detect_external_credentials", lambda: [])
@@ -73,7 +79,6 @@ def test_setup_keep_current_custom_from_config_does_not_fall_through(tmp_path, m
assert reloaded["model"]["provider"] == "custom"
assert reloaded["model"]["default"] == "custom/model"
assert reloaded["model"]["base_url"] == "https://example.invalid/v1"
- assert calls["count"] == 1
def test_setup_custom_endpoint_saves_working_v1_base_url(tmp_path, monkeypatch):
@@ -87,8 +92,9 @@ def test_setup_custom_endpoint_saves_working_v1_base_url(tmp_path, monkeypatch):
return 3 # Custom endpoint
if question == "Configure vision:":
return len(choices) - 1 # Skip
- if question == "Select TTS provider:":
- return len(choices) - 1 # Keep current
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
raise AssertionError(f"Unexpected prompt_choice call: {question}")
def fake_prompt(message, current=None, **kwargs):
@@ -103,7 +109,6 @@ def test_setup_custom_endpoint_saves_working_v1_base_url(tmp_path, monkeypatch):
monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", fake_prompt)
monkeypatch.setattr("hermes_cli.setup.prompt_yes_no", lambda *args, **kwargs: False)
- monkeypatch.setattr("hermes_cli.setup._setup_tts_provider", lambda config: None)
monkeypatch.setattr("hermes_cli.auth.get_active_provider", lambda: None)
monkeypatch.setattr("hermes_cli.auth.detect_external_credentials", lambda: [])
monkeypatch.setattr("agent.auxiliary_client.get_available_vision_backends", lambda: [])
@@ -144,25 +149,23 @@ def test_setup_keep_current_config_provider_uses_provider_specific_model_menu(tm
save_config(config)
captured = {"provider_choices": None, "model_choices": None}
- calls = {"count": 0}
def fake_prompt_choice(question, choices, default=0):
- calls["count"] += 1
- if calls["count"] == 1:
+ if question == "Select your inference provider:":
captured["provider_choices"] = list(choices)
assert choices[-1] == "Keep current (Anthropic)"
return len(choices) - 1
- if calls["count"] == 2:
+ if question == "Configure vision:":
assert question == "Configure vision:"
assert choices[-1] == "Skip for now"
return len(choices) - 1
- if calls["count"] == 3:
+ if question == "Select default model:":
captured["model_choices"] = list(choices)
return len(choices) - 1 # keep current model
- if calls["count"] == 4:
- assert question == "Select TTS provider:"
- return len(choices) - 1 # Keep current
- raise AssertionError("Unexpected extra prompt_choice call")
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", lambda *args, **kwargs: "")
@@ -179,7 +182,6 @@ def test_setup_keep_current_config_provider_uses_provider_specific_model_menu(tm
assert captured["model_choices"] is not None
assert captured["model_choices"][0] == "claude-opus-4-6"
assert "anthropic/claude-opus-4.6 (recommended)" not in captured["model_choices"]
- assert calls["count"] == 4 # provider, vision, model, TTS
def test_setup_keep_current_anthropic_can_configure_openai_vision_default(tmp_path, monkeypatch):
@@ -193,15 +195,24 @@ def test_setup_keep_current_anthropic_can_configure_openai_vision_default(tmp_pa
}
save_config(config)
- picks = iter([
- 10, # keep current provider (shifted +1 by kilocode insertion)
- 1, # configure vision with OpenAI
- 5, # use default gpt-4o-mini vision model
- 4, # keep current Anthropic model
- 4, # TTS: Keep current
- ])
+ def fake_prompt_choice(question, choices, default=0):
+ if question == "Select your inference provider:":
+ assert choices[-1] == "Keep current (Anthropic)"
+ return len(choices) - 1
+ if question == "Configure vision:":
+ return 1
+ if question == "Select vision model:":
+ assert choices[-1] == "Use default (gpt-4o-mini)"
+ return len(choices) - 1
+ if question == "Select default model:":
+ assert choices[-1] == "Keep current (claude-opus-4-6)"
+ return len(choices) - 1
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
- monkeypatch.setattr("hermes_cli.setup.prompt_choice", lambda *args, **kwargs: next(picks))
+ monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr(
"hermes_cli.setup.prompt",
lambda message, *args, **kwargs: "sk-openai" if "OpenAI API key" in message else "",
@@ -237,8 +248,17 @@ def test_setup_switch_custom_to_codex_clears_custom_endpoint_and_updates_config(
}
save_config(config)
- picks = iter([1, 0, 4]) # provider, model; 4 = TTS Keep current
- monkeypatch.setattr("hermes_cli.setup.prompt_choice", lambda *args, **kwargs: next(picks))
+ def fake_prompt_choice(question, choices, default=0):
+ if question == "Select your inference provider:":
+ return 1
+ if question == "Select default model:":
+ return 0
+ tts_idx = _maybe_keep_current_tts(question, choices)
+ if tts_idx is not None:
+ return tts_idx
+ raise AssertionError(f"Unexpected prompt_choice call: {question}")
+
+ monkeypatch.setattr("hermes_cli.setup.prompt_choice", fake_prompt_choice)
monkeypatch.setattr("hermes_cli.setup.prompt", lambda *args, **kwargs: "")
monkeypatch.setattr("hermes_cli.setup.prompt_yes_no", lambda *args, **kwargs: False)
monkeypatch.setattr("hermes_cli.auth.get_active_provider", lambda: None)
diff --git a/tests/hermes_cli/test_status.py b/tests/hermes_cli/test_status.py
new file mode 100644
index 000000000..374e57b29
--- /dev/null
+++ b/tests/hermes_cli/test_status.py
@@ -0,0 +1,14 @@
+from types import SimpleNamespace
+
+from hermes_cli.status import show_status
+
+
+def test_show_status_includes_tavily_key(monkeypatch, capsys, tmp_path):
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+ monkeypatch.setenv("TAVILY_API_KEY", "tvly-1234567890abcdef")
+
+ show_status(SimpleNamespace(all=False, deep=False))
+
+ output = capsys.readouterr().out
+ assert "Tavily" in output
+ assert "tvly...cdef" in output
diff --git a/tests/hermes_cli/test_update_autostash.py b/tests/hermes_cli/test_update_autostash.py
index 85523e8df..c03b6bf37 100644
--- a/tests/hermes_cli/test_update_autostash.py
+++ b/tests/hermes_cli/test_update_autostash.py
@@ -4,6 +4,7 @@ from types import SimpleNamespace
import pytest
+from hermes_cli import config as hermes_config
from hermes_cli import main as hermes_main
@@ -235,3 +236,82 @@ def test_stash_local_changes_if_needed_raises_when_stash_ref_missing(monkeypatch
with pytest.raises(CalledProcessError):
hermes_main._stash_local_changes_if_needed(["git"], Path(tmp_path))
+
+
+# ---------------------------------------------------------------------------
+# Update uses .[all] with fallback to .
+# ---------------------------------------------------------------------------
+
+def _setup_update_mocks(monkeypatch, tmp_path):
+ """Common setup for cmd_update tests."""
+ (tmp_path / ".git").mkdir()
+ monkeypatch.setattr(hermes_main, "PROJECT_ROOT", tmp_path)
+ monkeypatch.setattr(hermes_main, "_stash_local_changes_if_needed", lambda *a, **kw: None)
+ monkeypatch.setattr(hermes_main, "_restore_stashed_changes", lambda *a, **kw: True)
+ monkeypatch.setattr(hermes_config, "get_missing_env_vars", lambda required_only=True: [])
+ monkeypatch.setattr(hermes_config, "get_missing_config_fields", lambda: [])
+ monkeypatch.setattr(hermes_config, "check_config_version", lambda: (5, 5))
+ monkeypatch.setattr(hermes_config, "migrate_config", lambda **kw: {"env_added": [], "config_added": []})
+
+
+def test_cmd_update_tries_extras_first_then_falls_back(monkeypatch, tmp_path):
+ """When .[all] fails, update should fall back to . instead of aborting."""
+ _setup_update_mocks(monkeypatch, tmp_path)
+ monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/uv" if name == "uv" else None)
+
+ recorded = []
+
+ def fake_run(cmd, **kwargs):
+ recorded.append(cmd)
+ if cmd == ["git", "fetch", "origin"]:
+ return SimpleNamespace(stdout="", stderr="", returncode=0)
+ if cmd == ["git", "rev-parse", "--abbrev-ref", "HEAD"]:
+ return SimpleNamespace(stdout="main\n", stderr="", returncode=0)
+ if cmd == ["git", "rev-list", "HEAD..origin/main", "--count"]:
+ return SimpleNamespace(stdout="1\n", stderr="", returncode=0)
+ if cmd == ["git", "pull", "origin", "main"]:
+ return SimpleNamespace(stdout="Updating\n", stderr="", returncode=0)
+ # .[all] fails
+ if ".[all]" in cmd:
+ raise CalledProcessError(returncode=1, cmd=cmd)
+ # bare . succeeds
+ if cmd == ["/usr/bin/uv", "pip", "install", "-e", ".", "--quiet"]:
+ return SimpleNamespace(returncode=0)
+ return SimpleNamespace(returncode=0)
+
+ monkeypatch.setattr(hermes_main.subprocess, "run", fake_run)
+
+ hermes_main.cmd_update(SimpleNamespace())
+
+ install_cmds = [c for c in recorded if "pip" in c and "install" in c]
+ assert len(install_cmds) == 2
+ assert ".[all]" in install_cmds[0]
+ assert "." in install_cmds[1] and ".[all]" not in install_cmds[1]
+
+
+def test_cmd_update_succeeds_with_extras(monkeypatch, tmp_path):
+ """When .[all] succeeds, no fallback should be attempted."""
+ _setup_update_mocks(monkeypatch, tmp_path)
+ monkeypatch.setattr("shutil.which", lambda name: "/usr/bin/uv" if name == "uv" else None)
+
+ recorded = []
+
+ def fake_run(cmd, **kwargs):
+ recorded.append(cmd)
+ if cmd == ["git", "fetch", "origin"]:
+ return SimpleNamespace(stdout="", stderr="", returncode=0)
+ if cmd == ["git", "rev-parse", "--abbrev-ref", "HEAD"]:
+ return SimpleNamespace(stdout="main\n", stderr="", returncode=0)
+ if cmd == ["git", "rev-list", "HEAD..origin/main", "--count"]:
+ return SimpleNamespace(stdout="1\n", stderr="", returncode=0)
+ if cmd == ["git", "pull", "origin", "main"]:
+ return SimpleNamespace(stdout="Updating\n", stderr="", returncode=0)
+ return SimpleNamespace(returncode=0)
+
+ monkeypatch.setattr(hermes_main.subprocess, "run", fake_run)
+
+ hermes_main.cmd_update(SimpleNamespace())
+
+ install_cmds = [c for c in recorded if "pip" in c and "install" in c]
+ assert len(install_cmds) == 1
+ assert ".[all]" in install_cmds[0]
diff --git a/tests/honcho_integration/test_client.py b/tests/honcho_integration/test_client.py
index d779d9a63..b1ae29c54 100644
--- a/tests/honcho_integration/test_client.py
+++ b/tests/honcho_integration/test_client.py
@@ -63,11 +63,13 @@ class TestFromEnv:
class TestFromGlobalConfig:
def test_missing_config_falls_back_to_env(self, tmp_path):
- config = HonchoClientConfig.from_global_config(
- config_path=tmp_path / "nonexistent.json"
- )
+ with patch.dict(os.environ, {}, clear=True):
+ config = HonchoClientConfig.from_global_config(
+ config_path=tmp_path / "nonexistent.json"
+ )
# Should fall back to from_env
- assert config.enabled is True or config.api_key is None # depends on env
+ assert config.enabled is False
+ assert config.api_key is None
def test_reads_full_config(self, tmp_path):
config_file = tmp_path / "config.json"
diff --git a/tests/integration/test_web_tools.py b/tests/integration/test_web_tools.py
index fb2ea9da0..fe96b3adb 100644
--- a/tests/integration/test_web_tools.py
+++ b/tests/integration/test_web_tools.py
@@ -3,7 +3,7 @@
Comprehensive Test Suite for Web Tools Module
This script tests all web tools functionality to ensure they work correctly.
-Run this after any updates to the web_tools.py module or Firecrawl library.
+Run this after any updates to the web_tools.py module or backend libraries.
Usage:
python test_web_tools.py # Run all tests
@@ -11,7 +11,7 @@ Usage:
python test_web_tools.py --verbose # Show detailed output
Requirements:
- - FIRECRAWL_API_KEY environment variable must be set
+ - PARALLEL_API_KEY or FIRECRAWL_API_KEY environment variable must be set
- An auxiliary LLM provider (OPENROUTER_API_KEY or Nous Portal auth) (optional, for LLM tests)
"""
@@ -28,12 +28,14 @@ from typing import List
# Import the web tools to test (updated path after moving tools/)
from tools.web_tools import (
- web_search_tool,
- web_extract_tool,
+ web_search_tool,
+ web_extract_tool,
web_crawl_tool,
check_firecrawl_api_key,
+ check_web_api_key,
check_auxiliary_model,
- get_debug_session_info
+ get_debug_session_info,
+ _get_backend,
)
@@ -121,12 +123,13 @@ class WebToolsTester:
"""Test environment setup and API keys"""
print_section("Environment Check")
- # Check Firecrawl API key
- if not check_firecrawl_api_key():
- self.log_result("Firecrawl API Key", "failed", "FIRECRAWL_API_KEY not set")
+ # Check web backend API key (Parallel or Firecrawl)
+ if not check_web_api_key():
+ self.log_result("Web Backend API Key", "failed", "PARALLEL_API_KEY or FIRECRAWL_API_KEY not set")
return False
else:
- self.log_result("Firecrawl API Key", "passed", "Found")
+ backend = _get_backend()
+ self.log_result("Web Backend API Key", "passed", f"Using {backend} backend")
# Check auxiliary LLM provider (optional)
if not check_auxiliary_model():
@@ -578,7 +581,9 @@ class WebToolsTester:
},
"results": self.test_results,
"environment": {
+ "web_backend": _get_backend() if check_web_api_key() else None,
"firecrawl_api_key": check_firecrawl_api_key(),
+ "parallel_api_key": bool(os.getenv("PARALLEL_API_KEY")),
"auxiliary_model": check_auxiliary_model(),
"debug_mode": get_debug_session_info()["enabled"]
}
diff --git a/tests/run_interrupt_test.py b/tests/run_interrupt_test.py
index 845060ffa..a539c6ca9 100644
--- a/tests/run_interrupt_test.py
+++ b/tests/run_interrupt_test.py
@@ -24,6 +24,7 @@ def main() -> int:
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
parent.model = "test/model"
parent.base_url = "http://localhost:1"
diff --git a/tests/test_agent_guardrails.py b/tests/test_agent_guardrails.py
new file mode 100644
index 000000000..706b1daf8
--- /dev/null
+++ b/tests/test_agent_guardrails.py
@@ -0,0 +1,263 @@
+"""Unit tests for AIAgent pre/post-LLM-call guardrails.
+
+Covers three static methods on AIAgent (inspired by PR #1321 — @alireza78a):
+ - _sanitize_api_messages() — Phase 1: orphaned tool pair repair
+ - _cap_delegate_task_calls() — Phase 2a: subagent concurrency limit
+ - _deduplicate_tool_calls() — Phase 2b: identical call deduplication
+"""
+
+import types
+
+from run_agent import AIAgent
+from tools.delegate_tool import MAX_CONCURRENT_CHILDREN
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def make_tc(name: str, arguments: str = "{}") -> types.SimpleNamespace:
+ """Create a minimal tool_call SimpleNamespace mirroring the OpenAI SDK object."""
+ tc = types.SimpleNamespace()
+ tc.function = types.SimpleNamespace(name=name, arguments=arguments)
+ return tc
+
+
+def tool_result(call_id: str, content: str = "ok") -> dict:
+ return {"role": "tool", "tool_call_id": call_id, "content": content}
+
+
+def assistant_dict_call(call_id: str, name: str = "terminal") -> dict:
+ """Dict-style tool_call (as stored in message history)."""
+ return {"id": call_id, "function": {"name": name, "arguments": "{}"}}
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — _sanitize_api_messages
+# ---------------------------------------------------------------------------
+
+class TestSanitizeApiMessages:
+
+ def test_orphaned_result_removed(self):
+ msgs = [
+ {"role": "assistant", "tool_calls": [assistant_dict_call("c1")]},
+ tool_result("c1"),
+ tool_result("c_ORPHAN"),
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ assert len(out) == 2
+ assert all(m.get("tool_call_id") != "c_ORPHAN" for m in out)
+
+ def test_orphaned_call_gets_stub_result(self):
+ msgs = [
+ {"role": "assistant", "tool_calls": [assistant_dict_call("c2")]},
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ assert len(out) == 2
+ stub = out[1]
+ assert stub["role"] == "tool"
+ assert stub["tool_call_id"] == "c2"
+ assert stub["content"]
+
+ def test_clean_messages_pass_through(self):
+ msgs = [
+ {"role": "user", "content": "hello"},
+ {"role": "assistant", "tool_calls": [assistant_dict_call("c3")]},
+ tool_result("c3"),
+ {"role": "assistant", "content": "done"},
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ assert out == msgs
+
+ def test_mixed_orphaned_result_and_orphaned_call(self):
+ msgs = [
+ {"role": "assistant", "tool_calls": [
+ assistant_dict_call("c4"),
+ assistant_dict_call("c5"),
+ ]},
+ tool_result("c4"),
+ tool_result("c_DANGLING"),
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ ids = [m.get("tool_call_id") for m in out if m.get("role") == "tool"]
+ assert "c_DANGLING" not in ids
+ assert "c4" in ids
+ assert "c5" in ids
+
+ def test_empty_list_is_safe(self):
+ assert AIAgent._sanitize_api_messages([]) == []
+
+ def test_no_tool_messages(self):
+ msgs = [
+ {"role": "user", "content": "hi"},
+ {"role": "assistant", "content": "hello"},
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ assert out == msgs
+
+ def test_sdk_object_tool_calls(self):
+ tc_obj = types.SimpleNamespace(id="c6", function=types.SimpleNamespace(
+ name="terminal", arguments="{}"
+ ))
+ msgs = [
+ {"role": "assistant", "tool_calls": [tc_obj]},
+ ]
+ out = AIAgent._sanitize_api_messages(msgs)
+ assert len(out) == 2
+ assert out[1]["tool_call_id"] == "c6"
+
+
+# ---------------------------------------------------------------------------
+# Phase 2a — _cap_delegate_task_calls
+# ---------------------------------------------------------------------------
+
+class TestCapDelegateTaskCalls:
+
+ def test_excess_delegates_truncated(self):
+ tcs = [make_tc("delegate_task") for _ in range(MAX_CONCURRENT_CHILDREN + 2)]
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ delegate_count = sum(1 for tc in out if tc.function.name == "delegate_task")
+ assert delegate_count == MAX_CONCURRENT_CHILDREN
+
+ def test_non_delegate_calls_preserved(self):
+ tcs = (
+ [make_tc("delegate_task") for _ in range(MAX_CONCURRENT_CHILDREN + 1)]
+ + [make_tc("terminal"), make_tc("web_search")]
+ )
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ names = [tc.function.name for tc in out]
+ assert "terminal" in names
+ assert "web_search" in names
+
+ def test_at_limit_passes_through(self):
+ tcs = [make_tc("delegate_task") for _ in range(MAX_CONCURRENT_CHILDREN)]
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ assert out is tcs
+
+ def test_below_limit_passes_through(self):
+ tcs = [make_tc("delegate_task") for _ in range(MAX_CONCURRENT_CHILDREN - 1)]
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ assert out is tcs
+
+ def test_no_delegate_calls_unchanged(self):
+ tcs = [make_tc("terminal"), make_tc("web_search")]
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ assert out is tcs
+
+ def test_empty_list_safe(self):
+ assert AIAgent._cap_delegate_task_calls([]) == []
+
+ def test_original_list_not_mutated(self):
+ tcs = [make_tc("delegate_task") for _ in range(MAX_CONCURRENT_CHILDREN + 2)]
+ original_len = len(tcs)
+ AIAgent._cap_delegate_task_calls(tcs)
+ assert len(tcs) == original_len
+
+ def test_interleaved_order_preserved(self):
+ delegates = [make_tc("delegate_task", f'{{"task":"{i}"}}')
+ for i in range(MAX_CONCURRENT_CHILDREN + 1)]
+ t1 = make_tc("terminal", '{"cmd":"ls"}')
+ w1 = make_tc("web_search", '{"q":"x"}')
+ tcs = [delegates[0], t1, delegates[1], w1] + delegates[2:]
+ out = AIAgent._cap_delegate_task_calls(tcs)
+ expected = [delegates[0], t1, delegates[1], w1] + delegates[2:MAX_CONCURRENT_CHILDREN]
+ assert len(out) == len(expected)
+ for i, (actual, exp) in enumerate(zip(out, expected)):
+ assert actual is exp, f"mismatch at index {i}"
+
+
+# ---------------------------------------------------------------------------
+# Phase 2b — _deduplicate_tool_calls
+# ---------------------------------------------------------------------------
+
+class TestDeduplicateToolCalls:
+
+ def test_duplicate_pair_deduplicated(self):
+ tcs = [
+ make_tc("web_search", '{"query":"foo"}'),
+ make_tc("web_search", '{"query":"foo"}'),
+ ]
+ out = AIAgent._deduplicate_tool_calls(tcs)
+ assert len(out) == 1
+
+ def test_multiple_duplicates(self):
+ tcs = [
+ make_tc("web_search", '{"q":"a"}'),
+ make_tc("web_search", '{"q":"a"}'),
+ make_tc("terminal", '{"cmd":"ls"}'),
+ make_tc("terminal", '{"cmd":"ls"}'),
+ make_tc("terminal", '{"cmd":"pwd"}'),
+ ]
+ out = AIAgent._deduplicate_tool_calls(tcs)
+ assert len(out) == 3
+
+ def test_same_tool_different_args_kept(self):
+ tcs = [
+ make_tc("terminal", '{"cmd":"ls"}'),
+ make_tc("terminal", '{"cmd":"pwd"}'),
+ ]
+ out = AIAgent._deduplicate_tool_calls(tcs)
+ assert out is tcs
+
+ def test_different_tools_same_args_kept(self):
+ tcs = [
+ make_tc("tool_a", '{"x":1}'),
+ make_tc("tool_b", '{"x":1}'),
+ ]
+ out = AIAgent._deduplicate_tool_calls(tcs)
+ assert out is tcs
+
+ def test_clean_list_unchanged(self):
+ tcs = [
+ make_tc("web_search", '{"q":"x"}'),
+ make_tc("terminal", '{"cmd":"ls"}'),
+ ]
+ out = AIAgent._deduplicate_tool_calls(tcs)
+ assert out is tcs
+
+ def test_empty_list_safe(self):
+ assert AIAgent._deduplicate_tool_calls([]) == []
+
+ def test_first_occurrence_kept(self):
+ tc1 = make_tc("terminal", '{"cmd":"ls"}')
+ tc2 = make_tc("terminal", '{"cmd":"ls"}')
+ out = AIAgent._deduplicate_tool_calls([tc1, tc2])
+ assert len(out) == 1
+ assert out[0] is tc1
+
+ def test_original_list_not_mutated(self):
+ tcs = [
+ make_tc("web_search", '{"q":"dup"}'),
+ make_tc("web_search", '{"q":"dup"}'),
+ ]
+ original_len = len(tcs)
+ AIAgent._deduplicate_tool_calls(tcs)
+ assert len(tcs) == original_len
+
+
+# ---------------------------------------------------------------------------
+# _get_tool_call_id_static
+# ---------------------------------------------------------------------------
+
+class TestGetToolCallIdStatic:
+
+ def test_dict_with_valid_id(self):
+ assert AIAgent._get_tool_call_id_static({"id": "call_123"}) == "call_123"
+
+ def test_dict_with_none_id(self):
+ assert AIAgent._get_tool_call_id_static({"id": None}) == ""
+
+ def test_dict_without_id_key(self):
+ assert AIAgent._get_tool_call_id_static({"function": {}}) == ""
+
+ def test_object_with_valid_id(self):
+ tc = types.SimpleNamespace(id="call_456")
+ assert AIAgent._get_tool_call_id_static(tc) == "call_456"
+
+ def test_object_with_none_id(self):
+ tc = types.SimpleNamespace(id=None)
+ assert AIAgent._get_tool_call_id_static(tc) == ""
+
+ def test_object_without_id_attr(self):
+ tc = types.SimpleNamespace()
+ assert AIAgent._get_tool_call_id_static(tc) == ""
diff --git a/tests/test_api_key_providers.py b/tests/test_api_key_providers.py
index deb55734d..98f27d103 100644
--- a/tests/test_api_key_providers.py
+++ b/tests/test_api_key_providers.py
@@ -98,11 +98,14 @@ class TestProviderRegistry:
# =============================================================================
PROVIDER_ENV_VARS = (
- "OPENROUTER_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY",
+ "OPENROUTER_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN",
+ "CLAUDE_CODE_OAUTH_TOKEN",
"GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY",
"KIMI_API_KEY", "KIMI_BASE_URL", "MINIMAX_API_KEY", "MINIMAX_CN_API_KEY",
"AI_GATEWAY_API_KEY", "AI_GATEWAY_BASE_URL",
"KILOCODE_API_KEY", "KILOCODE_BASE_URL",
+ "DASHSCOPE_API_KEY", "OPENCODE_ZEN_API_KEY", "OPENCODE_GO_API_KEY",
+ "NOUS_API_KEY",
"OPENAI_BASE_URL",
)
@@ -111,6 +114,7 @@ PROVIDER_ENV_VARS = (
def _clear_provider_env(monkeypatch):
for key in PROVIDER_ENV_VARS:
monkeypatch.delenv(key, raising=False)
+ monkeypatch.setattr("hermes_cli.auth._load_auth_store", lambda: {})
class TestResolveProvider:
diff --git a/tests/test_cli_interrupt_subagent.py b/tests/test_cli_interrupt_subagent.py
index b91a7b654..f4322ea6b 100644
--- a/tests/test_cli_interrupt_subagent.py
+++ b/tests/test_cli_interrupt_subagent.py
@@ -43,6 +43,7 @@ class TestCLISubagentInterrupt(unittest.TestCase):
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
parent.model = "test/model"
parent.base_url = "http://localhost:1"
@@ -112,21 +113,21 @@ class TestCLISubagentInterrupt(unittest.TestCase):
mock_instance._interrupt_requested = False
mock_instance._interrupt_message = None
mock_instance._active_children = []
+ mock_instance._active_children_lock = threading.Lock()
mock_instance.quiet_mode = True
mock_instance.run_conversation = mock_child_run_conversation
mock_instance.interrupt = lambda msg=None: setattr(mock_instance, '_interrupt_requested', True) or setattr(mock_instance, '_interrupt_message', msg)
mock_instance.tools = []
MockAgent.return_value = mock_instance
-
+
+ # Register child manually (normally done by _build_child_agent)
+ parent._active_children.append(mock_instance)
+
result = _run_single_child(
task_index=0,
goal="Do something slow",
- context=None,
- toolsets=["terminal"],
- model=None,
- max_iterations=50,
+ child=mock_instance,
parent_agent=parent,
- task_count=1,
)
delegate_result[0] = result
except Exception as e:
diff --git a/tests/test_cli_status_bar.py b/tests/test_cli_status_bar.py
index 4e281ffa8..c1dd4b35b 100644
--- a/tests/test_cli_status_bar.py
+++ b/tests/test_cli_status_bar.py
@@ -16,6 +16,10 @@ def _make_cli(model: str = "anthropic/claude-sonnet-4-20250514"):
def _attach_agent(
cli_obj,
*,
+ input_tokens: int | None = None,
+ output_tokens: int | None = None,
+ cache_read_tokens: int = 0,
+ cache_write_tokens: int = 0,
prompt_tokens: int,
completion_tokens: int,
total_tokens: int,
@@ -26,6 +30,12 @@ def _attach_agent(
):
cli_obj.agent = SimpleNamespace(
model=cli_obj.model,
+ provider="anthropic" if cli_obj.model.startswith("anthropic/") else None,
+ base_url="",
+ session_input_tokens=input_tokens if input_tokens is not None else prompt_tokens,
+ session_output_tokens=output_tokens if output_tokens is not None else completion_tokens,
+ session_cache_read_tokens=cache_read_tokens,
+ session_cache_write_tokens=cache_write_tokens,
session_prompt_tokens=prompt_tokens,
session_completion_tokens=completion_tokens,
session_total_tokens=total_tokens,
@@ -68,20 +78,19 @@ class TestCLIStatusBar:
assert "$0.06" not in text # cost hidden by default
assert "15m" in text
- def test_build_status_bar_text_shows_cost_when_enabled(self):
+ def test_build_status_bar_text_no_cost_in_status_bar(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10000,
- completion_tokens=2400,
- total_tokens=12400,
+ completion_tokens=5000,
+ total_tokens=15000,
api_calls=7,
- context_tokens=12400,
+ context_tokens=50000,
context_length=200_000,
)
- cli_obj.show_cost = True
text = cli_obj._build_status_bar_text(width=120)
- assert "$" in text # cost is shown when enabled
+ assert "$" not in text # cost is never shown in status bar
def test_build_status_bar_text_collapses_for_narrow_terminal(self):
cli_obj = _attach_agent(
@@ -128,8 +137,8 @@ class TestCLIUsageReport:
output = capsys.readouterr().out
assert "Model:" in output
- assert "Input cost:" in output
- assert "Output cost:" in output
+ assert "Cost status:" in output
+ assert "Cost source:" in output
assert "Total cost:" in output
assert "$" in output
assert "0.064" in output
diff --git a/tests/test_hermes_state.py b/tests/test_hermes_state.py
index d77247936..01d9c37ca 100644
--- a/tests/test_hermes_state.py
+++ b/tests/test_hermes_state.py
@@ -657,7 +657,7 @@ class TestSchemaInit:
def test_schema_version(self, db):
cursor = db._conn.execute("SELECT version FROM schema_version")
version = cursor.fetchone()[0]
- assert version == 4
+ assert version == 5
def test_title_column_exists(self, db):
"""Verify the title column was created in the sessions table."""
@@ -713,12 +713,12 @@ class TestSchemaInit:
conn.commit()
conn.close()
- # Open with SessionDB — should migrate to v4
+ # Open with SessionDB — should migrate to v5
migrated_db = SessionDB(db_path=db_path)
# Verify migration
cursor = migrated_db._conn.execute("SELECT version FROM schema_version")
- assert cursor.fetchone()[0] == 4
+ assert cursor.fetchone()[0] == 5
# Verify title column exists and is NULL for existing sessions
session = migrated_db.get_session("existing")
diff --git a/tests/test_insights.py b/tests/test_insights.py
index 6f6280a1d..af4f59829 100644
--- a/tests/test_insights.py
+++ b/tests/test_insights.py
@@ -123,28 +123,16 @@ def populated_db(db):
# =========================================================================
class TestPricing:
- def test_exact_match(self):
- pricing = _get_pricing("gpt-4o")
- assert pricing["input"] == 2.50
- assert pricing["output"] == 10.00
-
def test_provider_prefix_stripped(self):
pricing = _get_pricing("anthropic/claude-sonnet-4-20250514")
assert pricing["input"] == 3.00
assert pricing["output"] == 15.00
- def test_prefix_match(self):
- pricing = _get_pricing("claude-3-5-sonnet-20241022")
- assert pricing["input"] == 3.00
-
- def test_keyword_heuristic_opus(self):
+ def test_unknown_models_do_not_use_heuristics(self):
pricing = _get_pricing("some-new-opus-model")
- assert pricing["input"] == 15.00
- assert pricing["output"] == 75.00
-
- def test_keyword_heuristic_haiku(self):
+ assert pricing == _DEFAULT_PRICING
pricing = _get_pricing("anthropic/claude-haiku-future")
- assert pricing["input"] == 0.80
+ assert pricing == _DEFAULT_PRICING
def test_unknown_model_returns_zero_cost(self):
"""Unknown/custom models should NOT have fabricated costs."""
@@ -168,40 +156,12 @@ class TestPricing:
pricing = _get_pricing("")
assert pricing == _DEFAULT_PRICING
- def test_deepseek_heuristic(self):
- pricing = _get_pricing("deepseek-v3")
- assert pricing["input"] == 0.14
-
- def test_gemini_heuristic(self):
- pricing = _get_pricing("gemini-3.0-ultra")
- assert pricing["input"] == 0.15
-
- def test_dated_model_gpt4o_mini(self):
- """gpt-4o-mini-2024-07-18 should match gpt-4o-mini, NOT gpt-4o."""
- pricing = _get_pricing("gpt-4o-mini-2024-07-18")
- assert pricing["input"] == 0.15 # gpt-4o-mini price, not gpt-4o's 2.50
-
- def test_dated_model_o3_mini(self):
- """o3-mini-2025-01-31 should match o3-mini, NOT o3."""
- pricing = _get_pricing("o3-mini-2025-01-31")
- assert pricing["input"] == 1.10 # o3-mini price, not o3's 10.00
-
- def test_dated_model_gpt41_mini(self):
- """gpt-4.1-mini-2025-04-14 should match gpt-4.1-mini, NOT gpt-4.1."""
- pricing = _get_pricing("gpt-4.1-mini-2025-04-14")
- assert pricing["input"] == 0.40 # gpt-4.1-mini, not gpt-4.1's 2.00
-
- def test_dated_model_gpt41_nano(self):
- """gpt-4.1-nano-2025-04-14 should match gpt-4.1-nano, NOT gpt-4.1."""
- pricing = _get_pricing("gpt-4.1-nano-2025-04-14")
- assert pricing["input"] == 0.10 # gpt-4.1-nano, not gpt-4.1's 2.00
-
class TestHasKnownPricing:
def test_known_commercial_model(self):
- assert _has_known_pricing("gpt-4o") is True
+ assert _has_known_pricing("gpt-4o", provider="openai") is True
assert _has_known_pricing("anthropic/claude-sonnet-4-20250514") is True
- assert _has_known_pricing("deepseek-chat") is True
+ assert _has_known_pricing("gpt-4.1", provider="openai") is True
def test_unknown_custom_model(self):
assert _has_known_pricing("FP16_Hermes_4.5") is False
@@ -210,26 +170,39 @@ class TestHasKnownPricing:
assert _has_known_pricing("") is False
assert _has_known_pricing(None) is False
- def test_heuristic_matched_models(self):
- """Models matched by keyword heuristics should be considered known."""
- assert _has_known_pricing("some-opus-model") is True
- assert _has_known_pricing("future-sonnet-v2") is True
+ def test_heuristic_matched_models_are_not_considered_known(self):
+ assert _has_known_pricing("some-opus-model") is False
+ assert _has_known_pricing("future-sonnet-v2") is False
class TestEstimateCost:
def test_basic_cost(self):
- # gpt-4o: 2.50/M input, 10.00/M output
- cost = _estimate_cost("gpt-4o", 1_000_000, 1_000_000)
- assert cost == pytest.approx(12.50, abs=0.01)
+ cost, status = _estimate_cost(
+ "anthropic/claude-sonnet-4-20250514",
+ 1_000_000,
+ 1_000_000,
+ provider="anthropic",
+ )
+ assert status == "estimated"
+ assert cost == pytest.approx(18.0, abs=0.01)
def test_zero_tokens(self):
- cost = _estimate_cost("gpt-4o", 0, 0)
+ cost, status = _estimate_cost("gpt-4o", 0, 0, provider="openai")
+ assert status == "estimated"
assert cost == 0.0
- def test_small_usage(self):
- cost = _estimate_cost("gpt-4o", 1000, 500)
- # 1000 * 2.50/1M + 500 * 10.00/1M = 0.0025 + 0.005 = 0.0075
- assert cost == pytest.approx(0.0075, abs=0.0001)
+ def test_cache_aware_usage(self):
+ cost, status = _estimate_cost(
+ "anthropic/claude-sonnet-4-20250514",
+ 1000,
+ 500,
+ cache_read_tokens=2000,
+ cache_write_tokens=400,
+ provider="anthropic",
+ )
+ assert status == "estimated"
+ expected = (1000 * 3.0 + 500 * 15.0 + 2000 * 0.30 + 400 * 3.75) / 1_000_000
+ assert cost == pytest.approx(expected, abs=0.0001)
# =========================================================================
@@ -660,8 +633,13 @@ class TestEdgeCases:
def test_mixed_commercial_and_custom_models(self, db):
"""Mix of commercial and custom models: only commercial ones get costs."""
- db.create_session(session_id="s1", source="cli", model="gpt-4o")
- db.update_token_counts("s1", input_tokens=10000, output_tokens=5000)
+ db.create_session(session_id="s1", source="cli", model="anthropic/claude-sonnet-4-20250514")
+ db.update_token_counts(
+ "s1",
+ input_tokens=10000,
+ output_tokens=5000,
+ billing_provider="anthropic",
+ )
db.create_session(session_id="s2", source="cli", model="my-local-llama")
db.update_token_counts("s2", input_tokens=10000, output_tokens=5000)
db._conn.commit()
@@ -672,13 +650,13 @@ class TestEdgeCases:
# Cost should only come from gpt-4o, not from the custom model
overview = report["overview"]
assert overview["estimated_cost"] > 0
- assert "gpt-4o" in overview["models_with_pricing"] # list now, not set
+ assert "claude-sonnet-4-20250514" in overview["models_with_pricing"] # list now, not set
assert "my-local-llama" in overview["models_without_pricing"]
# Verify individual model entries
- gpt = next(m for m in report["models"] if m["model"] == "gpt-4o")
- assert gpt["has_pricing"] is True
- assert gpt["cost"] > 0
+ claude = next(m for m in report["models"] if m["model"] == "claude-sonnet-4-20250514")
+ assert claude["has_pricing"] is True
+ assert claude["cost"] > 0
llama = next(m for m in report["models"] if m["model"] == "my-local-llama")
assert llama["has_pricing"] is False
diff --git a/tests/test_interactive_interrupt.py b/tests/test_interactive_interrupt.py
index c01404e1c..8c0d328c2 100644
--- a/tests/test_interactive_interrupt.py
+++ b/tests/test_interactive_interrupt.py
@@ -57,6 +57,7 @@ def main() -> int:
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
parent.model = "test/model"
parent.base_url = "http://localhost:1"
diff --git a/tests/test_interrupt_propagation.py b/tests/test_interrupt_propagation.py
index ff1cafdc8..7f8cb01c3 100644
--- a/tests/test_interrupt_propagation.py
+++ b/tests/test_interrupt_propagation.py
@@ -30,12 +30,14 @@ class TestInterruptPropagationToChild(unittest.TestCase):
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
child = AIAgent.__new__(AIAgent)
child._interrupt_requested = False
child._interrupt_message = None
child._active_children = []
+ child._active_children_lock = threading.Lock()
child.quiet_mode = True
parent._active_children.append(child)
@@ -60,6 +62,7 @@ class TestInterruptPropagationToChild(unittest.TestCase):
child._interrupt_message = "msg"
child.quiet_mode = True
child._active_children = []
+ child._active_children_lock = threading.Lock()
# Global is set
set_interrupt(True)
@@ -78,6 +81,7 @@ class TestInterruptPropagationToChild(unittest.TestCase):
child._interrupt_requested = False
child._interrupt_message = None
child._active_children = []
+ child._active_children_lock = threading.Lock()
child.quiet_mode = True
child.api_mode = "chat_completions"
child.log_prefix = ""
@@ -119,12 +123,14 @@ class TestInterruptPropagationToChild(unittest.TestCase):
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
child = AIAgent.__new__(AIAgent)
child._interrupt_requested = False
child._interrupt_message = None
child._active_children = []
+ child._active_children_lock = threading.Lock()
child.quiet_mode = True
# Register child (simulating what _run_single_child does)
diff --git a/tests/test_quick_commands.py b/tests/test_quick_commands.py
index 9708b1fb3..7a89d4ca2 100644
--- a/tests/test_quick_commands.py
+++ b/tests/test_quick_commands.py
@@ -47,6 +47,28 @@ class TestCLIQuickCommands:
args = cli.console.print.call_args[0][0]
assert "no output" in args.lower()
+ def test_alias_command_routes_to_target(self):
+ """Alias quick commands rewrite to the target command."""
+ cli = self._make_cli({"shortcut": {"type": "alias", "target": "/help"}})
+ with patch.object(cli, "process_command", wraps=cli.process_command) as spy:
+ cli.process_command("/shortcut")
+ # Should recursively call process_command with /help
+ spy.assert_any_call("/help")
+
+ def test_alias_command_passes_args(self):
+ """Alias quick commands forward user arguments to the target."""
+ cli = self._make_cli({"sc": {"type": "alias", "target": "/context"}})
+ with patch.object(cli, "process_command", wraps=cli.process_command) as spy:
+ cli.process_command("/sc some args")
+ spy.assert_any_call("/context some args")
+
+ def test_alias_no_target_shows_error(self):
+ cli = self._make_cli({"broken": {"type": "alias", "target": ""}})
+ cli.process_command("/broken")
+ cli.console.print.assert_called_once()
+ args = cli.console.print.call_args[0][0]
+ assert "no target defined" in args.lower()
+
def test_unsupported_type_shows_error(self):
cli = self._make_cli({"bad": {"type": "prompt", "command": "echo hi"}})
cli.process_command("/bad")
diff --git a/tests/test_real_interrupt_subagent.py b/tests/test_real_interrupt_subagent.py
index f1a16753a..e0e681cdf 100644
--- a/tests/test_real_interrupt_subagent.py
+++ b/tests/test_real_interrupt_subagent.py
@@ -55,6 +55,7 @@ class TestRealSubagentInterrupt(unittest.TestCase):
parent._interrupt_requested = False
parent._interrupt_message = None
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
parent.quiet_mode = True
parent.model = "test/model"
parent.base_url = "http://localhost:1"
@@ -103,19 +104,28 @@ class TestRealSubagentInterrupt(unittest.TestCase):
return original_run(self_agent, *args, **kwargs)
with patch.object(AIAgent, 'run_conversation', patched_run):
+ # Build a real child agent (AIAgent is NOT patched here,
+ # only run_conversation and _build_system_prompt are)
+ child = AIAgent(
+ base_url="http://localhost:1",
+ api_key="test-key",
+ model="test/model",
+ provider="test",
+ api_mode="chat_completions",
+ max_iterations=5,
+ enabled_toolsets=["terminal"],
+ quiet_mode=True,
+ skip_context_files=True,
+ skip_memory=True,
+ platform="cli",
+ )
+ child._delegate_depth = 1
+ parent._active_children.append(child)
result = _run_single_child(
task_index=0,
goal="Test task",
- context=None,
- toolsets=["terminal"],
- model="test/model",
- max_iterations=5,
+ child=child,
parent_agent=parent,
- task_count=1,
- override_provider="test",
- override_base_url="http://localhost:1",
- override_api_key="test",
- override_api_mode="chat_completions",
)
result_holder[0] = result
except Exception as e:
diff --git a/tests/tools/test_delegate.py b/tests/tools/test_delegate.py
index a29560b2c..476a2401b 100644
--- a/tests/tools/test_delegate.py
+++ b/tests/tools/test_delegate.py
@@ -12,6 +12,7 @@ Run with: python -m pytest tests/test_delegate.py -v
import json
import os
import sys
+import threading
import unittest
from unittest.mock import MagicMock, patch
@@ -44,6 +45,7 @@ def _make_mock_parent(depth=0):
parent._session_db = None
parent._delegate_depth = depth
parent._active_children = []
+ parent._active_children_lock = threading.Lock()
return parent
@@ -722,7 +724,12 @@ class TestDelegationProviderIntegration(unittest.TestCase):
}
parent = _make_mock_parent(depth=0)
- with patch("tools.delegate_tool._run_single_child") as mock_run:
+ # Patch _build_child_agent since credentials are now passed there
+ # (agents are built in the main thread before being handed to workers)
+ with patch("tools.delegate_tool._build_child_agent") as mock_build, \
+ patch("tools.delegate_tool._run_single_child") as mock_run:
+ mock_child = MagicMock()
+ mock_build.return_value = mock_child
mock_run.return_value = {
"task_index": 0, "status": "completed",
"summary": "Done", "api_calls": 1, "duration_seconds": 1.0
@@ -731,7 +738,8 @@ class TestDelegationProviderIntegration(unittest.TestCase):
tasks = [{"goal": "Task A"}, {"goal": "Task B"}]
delegate_task(tasks=tasks, parent_agent=parent)
- for call in mock_run.call_args_list:
+ self.assertEqual(mock_build.call_count, 2)
+ for call in mock_build.call_args_list:
self.assertEqual(call.kwargs.get("model"), "meta-llama/llama-4-scout")
self.assertEqual(call.kwargs.get("override_provider"), "openrouter")
self.assertEqual(call.kwargs.get("override_base_url"), "https://openrouter.ai/api/v1")
diff --git a/tests/tools/test_mcp_probe.py b/tests/tools/test_mcp_probe.py
new file mode 100644
index 000000000..a592c5dca
--- /dev/null
+++ b/tests/tools/test_mcp_probe.py
@@ -0,0 +1,210 @@
+"""Tests for probe_mcp_server_tools() in tools.mcp_tool."""
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _reset_mcp_state():
+ """Ensure clean MCP module state before/after each test."""
+ import tools.mcp_tool as mcp
+ old_loop = mcp._mcp_loop
+ old_thread = mcp._mcp_thread
+ old_servers = dict(mcp._servers)
+ yield
+ mcp._servers.clear()
+ mcp._servers.update(old_servers)
+ mcp._mcp_loop = old_loop
+ mcp._mcp_thread = old_thread
+
+
+class TestProbeMcpServerTools:
+ """Tests for the lightweight probe_mcp_server_tools function."""
+
+ def test_returns_empty_when_mcp_not_available(self):
+ with patch("tools.mcp_tool._MCP_AVAILABLE", False):
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+ assert result == {}
+
+ def test_returns_empty_when_no_config(self):
+ with patch("tools.mcp_tool._load_mcp_config", return_value={}):
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+ assert result == {}
+
+ def test_returns_empty_when_all_servers_disabled(self):
+ config = {
+ "github": {"command": "npx", "enabled": False},
+ "slack": {"command": "npx", "enabled": "off"},
+ }
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config):
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+ assert result == {}
+
+ def test_returns_tools_from_successful_server(self):
+ """Successfully probed server returns its tools list."""
+ config = {
+ "github": {"command": "npx", "connect_timeout": 5},
+ }
+ mock_tool_1 = SimpleNamespace(name="create_issue", description="Create a new issue")
+ mock_tool_2 = SimpleNamespace(name="search_repos", description="Search repositories")
+
+ mock_server = MagicMock()
+ mock_server._tools = [mock_tool_1, mock_tool_2]
+ mock_server.shutdown = AsyncMock()
+
+ async def fake_connect(name, cfg):
+ return mock_server
+
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config), \
+ patch("tools.mcp_tool._connect_server", side_effect=fake_connect), \
+ patch("tools.mcp_tool._ensure_mcp_loop"), \
+ patch("tools.mcp_tool._run_on_mcp_loop") as mock_run, \
+ patch("tools.mcp_tool._stop_mcp_loop"):
+
+ # Simulate running the async probe
+ def run_coro(coro, timeout=120):
+ loop = asyncio.new_event_loop()
+ try:
+ return loop.run_until_complete(coro)
+ finally:
+ loop.close()
+
+ mock_run.side_effect = run_coro
+
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+
+ assert "github" in result
+ assert len(result["github"]) == 2
+ assert result["github"][0] == ("create_issue", "Create a new issue")
+ assert result["github"][1] == ("search_repos", "Search repositories")
+ mock_server.shutdown.assert_awaited_once()
+
+ def test_failed_server_omitted_from_results(self):
+ """Servers that fail to connect are silently skipped."""
+ config = {
+ "github": {"command": "npx", "connect_timeout": 5},
+ "broken": {"command": "nonexistent", "connect_timeout": 5},
+ }
+ mock_tool = SimpleNamespace(name="create_issue", description="Create")
+ mock_server = MagicMock()
+ mock_server._tools = [mock_tool]
+ mock_server.shutdown = AsyncMock()
+
+ async def fake_connect(name, cfg):
+ if name == "broken":
+ raise ConnectionError("Server not found")
+ return mock_server
+
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config), \
+ patch("tools.mcp_tool._connect_server", side_effect=fake_connect), \
+ patch("tools.mcp_tool._ensure_mcp_loop"), \
+ patch("tools.mcp_tool._run_on_mcp_loop") as mock_run, \
+ patch("tools.mcp_tool._stop_mcp_loop"):
+
+ def run_coro(coro, timeout=120):
+ loop = asyncio.new_event_loop()
+ try:
+ return loop.run_until_complete(coro)
+ finally:
+ loop.close()
+
+ mock_run.side_effect = run_coro
+
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+
+ assert "github" in result
+ assert "broken" not in result
+
+ def test_handles_tool_without_description(self):
+ """Tools without descriptions get empty string."""
+ config = {"github": {"command": "npx", "connect_timeout": 5}}
+ mock_tool = SimpleNamespace(name="my_tool") # no description attribute
+
+ mock_server = MagicMock()
+ mock_server._tools = [mock_tool]
+ mock_server.shutdown = AsyncMock()
+
+ async def fake_connect(name, cfg):
+ return mock_server
+
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config), \
+ patch("tools.mcp_tool._connect_server", side_effect=fake_connect), \
+ patch("tools.mcp_tool._ensure_mcp_loop"), \
+ patch("tools.mcp_tool._run_on_mcp_loop") as mock_run, \
+ patch("tools.mcp_tool._stop_mcp_loop"):
+
+ def run_coro(coro, timeout=120):
+ loop = asyncio.new_event_loop()
+ try:
+ return loop.run_until_complete(coro)
+ finally:
+ loop.close()
+
+ mock_run.side_effect = run_coro
+
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+
+ assert result["github"][0] == ("my_tool", "")
+
+ def test_cleanup_called_even_on_failure(self):
+ """_stop_mcp_loop is called even when probe fails."""
+ config = {"github": {"command": "npx", "connect_timeout": 5}}
+
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config), \
+ patch("tools.mcp_tool._ensure_mcp_loop"), \
+ patch("tools.mcp_tool._run_on_mcp_loop", side_effect=RuntimeError("boom")), \
+ patch("tools.mcp_tool._stop_mcp_loop") as mock_stop:
+
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+
+ assert result == {}
+ mock_stop.assert_called_once()
+
+ def test_skips_disabled_servers(self):
+ """Disabled servers are not probed."""
+ config = {
+ "github": {"command": "npx", "connect_timeout": 5},
+ "disabled_one": {"command": "npx", "enabled": False},
+ }
+ mock_tool = SimpleNamespace(name="create_issue", description="Create")
+ mock_server = MagicMock()
+ mock_server._tools = [mock_tool]
+ mock_server.shutdown = AsyncMock()
+
+ connect_calls = []
+
+ async def fake_connect(name, cfg):
+ connect_calls.append(name)
+ return mock_server
+
+ with patch("tools.mcp_tool._load_mcp_config", return_value=config), \
+ patch("tools.mcp_tool._connect_server", side_effect=fake_connect), \
+ patch("tools.mcp_tool._ensure_mcp_loop"), \
+ patch("tools.mcp_tool._run_on_mcp_loop") as mock_run, \
+ patch("tools.mcp_tool._stop_mcp_loop"):
+
+ def run_coro(coro, timeout=120):
+ loop = asyncio.new_event_loop()
+ try:
+ return loop.run_until_complete(coro)
+ finally:
+ loop.close()
+
+ mock_run.side_effect = run_coro
+
+ from tools.mcp_tool import probe_mcp_server_tools
+ result = probe_mcp_server_tools()
+
+ assert "github" in result
+ assert "disabled_one" not in result
+ assert "disabled_one" not in connect_calls
diff --git a/tests/tools/test_mcp_tool.py b/tests/tools/test_mcp_tool.py
index 3796d8ced..9c49bd2c2 100644
--- a/tests/tools/test_mcp_tool.py
+++ b/tests/tools/test_mcp_tool.py
@@ -2596,17 +2596,19 @@ class TestMCPSelectiveToolLoading:
async def run():
with patch("tools.mcp_tool._connect_server", side_effect=fake_connect), \
+ patch.dict("tools.mcp_tool._servers", {}, clear=True), \
patch("tools.registry.registry", mock_registry), \
patch("toolsets.create_custom_toolset"):
- return await _discover_and_register_server(
+ registered = await _discover_and_register_server(
"ink_existing",
{"url": "https://mcp.example.com", "tools": {"include": ["create_service"]}},
)
+ return registered, _existing_tool_names()
try:
- registered = asyncio.run(run())
+ registered, existing = asyncio.run(run())
assert registered == ["mcp_ink_existing_create_service"]
- assert _existing_tool_names() == ["mcp_ink_existing_create_service"]
+ assert existing == ["mcp_ink_existing_create_service"]
finally:
_servers.pop("ink_existing", None)
diff --git a/tests/tools/test_process_registry.py b/tests/tools/test_process_registry.py
index 7ebe94c04..e6cfa40e7 100644
--- a/tests/tools/test_process_registry.py
+++ b/tests/tools/test_process_registry.py
@@ -294,6 +294,61 @@ class TestCheckpoint:
recovered = registry.recover_from_checkpoint()
assert recovered == 0
+ def test_write_checkpoint_includes_watcher_metadata(self, registry, tmp_path):
+ with patch("tools.process_registry.CHECKPOINT_PATH", tmp_path / "procs.json"):
+ s = _make_session()
+ s.watcher_platform = "telegram"
+ s.watcher_chat_id = "999"
+ s.watcher_thread_id = "42"
+ s.watcher_interval = 60
+ registry._running[s.id] = s
+ registry._write_checkpoint()
+
+ data = json.loads((tmp_path / "procs.json").read_text())
+ assert len(data) == 1
+ assert data[0]["watcher_platform"] == "telegram"
+ assert data[0]["watcher_chat_id"] == "999"
+ assert data[0]["watcher_thread_id"] == "42"
+ assert data[0]["watcher_interval"] == 60
+
+ def test_recover_enqueues_watchers(self, registry, tmp_path):
+ checkpoint = tmp_path / "procs.json"
+ checkpoint.write_text(json.dumps([{
+ "session_id": "proc_live",
+ "command": "sleep 999",
+ "pid": os.getpid(), # current process — guaranteed alive
+ "task_id": "t1",
+ "session_key": "sk1",
+ "watcher_platform": "telegram",
+ "watcher_chat_id": "123",
+ "watcher_thread_id": "42",
+ "watcher_interval": 60,
+ }]))
+ with patch("tools.process_registry.CHECKPOINT_PATH", checkpoint):
+ recovered = registry.recover_from_checkpoint()
+ assert recovered == 1
+ assert len(registry.pending_watchers) == 1
+ w = registry.pending_watchers[0]
+ assert w["session_id"] == "proc_live"
+ assert w["platform"] == "telegram"
+ assert w["chat_id"] == "123"
+ assert w["thread_id"] == "42"
+ assert w["check_interval"] == 60
+
+ def test_recover_skips_watcher_when_no_interval(self, registry, tmp_path):
+ checkpoint = tmp_path / "procs.json"
+ checkpoint.write_text(json.dumps([{
+ "session_id": "proc_live",
+ "command": "sleep 999",
+ "pid": os.getpid(),
+ "task_id": "t1",
+ "watcher_interval": 0,
+ }]))
+ with patch("tools.process_registry.CHECKPOINT_PATH", checkpoint):
+ recovered = registry.recover_from_checkpoint()
+ assert recovered == 1
+ assert len(registry.pending_watchers) == 0
+
# =========================================================================
# Kill process
diff --git a/tests/tools/test_send_message_tool.py b/tests/tools/test_send_message_tool.py
index 7ef9b149d..2b03847e5 100644
--- a/tests/tools/test_send_message_tool.py
+++ b/tests/tools/test_send_message_tool.py
@@ -25,7 +25,7 @@ def _make_config():
def _install_telegram_mock(monkeypatch, bot):
- parse_mode = SimpleNamespace(MARKDOWN_V2="MarkdownV2")
+ parse_mode = SimpleNamespace(MARKDOWN_V2="MarkdownV2", HTML="HTML")
constants_mod = SimpleNamespace(ParseMode=parse_mode)
telegram_mod = SimpleNamespace(Bot=lambda token: bot, constants=constants_mod)
monkeypatch.setitem(sys.modules, "telegram", telegram_mod)
@@ -391,3 +391,97 @@ class TestSendToPlatformChunking:
assert len(sent_calls) >= 3
assert all(call == [] for call in sent_calls[:-1])
assert sent_calls[-1] == media
+
+
+# ---------------------------------------------------------------------------
+# HTML auto-detection in Telegram send
+# ---------------------------------------------------------------------------
+
+
+class TestSendTelegramHtmlDetection:
+ """Verify that messages containing HTML tags are sent with parse_mode=HTML
+ and that plain / markdown messages use MarkdownV2."""
+
+ def _make_bot(self):
+ bot = MagicMock()
+ bot.send_message = AsyncMock(return_value=SimpleNamespace(message_id=1))
+ bot.send_photo = AsyncMock()
+ bot.send_video = AsyncMock()
+ bot.send_voice = AsyncMock()
+ bot.send_audio = AsyncMock()
+ bot.send_document = AsyncMock()
+ return bot
+
+ def test_html_message_uses_html_parse_mode(self, monkeypatch):
+ bot = self._make_bot()
+ _install_telegram_mock(monkeypatch, bot)
+
+ asyncio.run(
+ _send_telegram("tok", "123", "Hello world")
+ )
+
+ bot.send_message.assert_awaited_once()
+ kwargs = bot.send_message.await_args.kwargs
+ assert kwargs["parse_mode"] == "HTML"
+ assert kwargs["text"] == "Hello world"
+
+ def test_plain_text_uses_markdown_v2(self, monkeypatch):
+ bot = self._make_bot()
+ _install_telegram_mock(monkeypatch, bot)
+
+ asyncio.run(
+ _send_telegram("tok", "123", "Just plain text, no tags")
+ )
+
+ bot.send_message.assert_awaited_once()
+ kwargs = bot.send_message.await_args.kwargs
+ assert kwargs["parse_mode"] == "MarkdownV2"
+
+ def test_html_with_code_and_pre_tags(self, monkeypatch):
+ bot = self._make_bot()
+ _install_telegram_mock(monkeypatch, bot)
+
+ html = "
code block
and inline"
+ asyncio.run(_send_telegram("tok", "123", html))
+
+ kwargs = bot.send_message.await_args.kwargs
+ assert kwargs["parse_mode"] == "HTML"
+
+ def test_closing_tag_detected(self, monkeypatch):
+ bot = self._make_bot()
+ _install_telegram_mock(monkeypatch, bot)
+
+ asyncio.run(_send_telegram("tok", "123", "text more"))
+
+ kwargs = bot.send_message.await_args.kwargs
+ assert kwargs["parse_mode"] == "HTML"
+
+ def test_angle_brackets_in_math_not_detected(self, monkeypatch):
+ """Expressions like 'x < 5' or '3 > 2' should not trigger HTML mode."""
+ bot = self._make_bot()
+ _install_telegram_mock(monkeypatch, bot)
+
+ asyncio.run(_send_telegram("tok", "123", "if x < 5 then y > 2"))
+
+ kwargs = bot.send_message.await_args.kwargs
+ assert kwargs["parse_mode"] == "MarkdownV2"
+
+ def test_html_parse_failure_falls_back_to_plain(self, monkeypatch):
+ """If Telegram rejects the HTML, fall back to plain text."""
+ bot = self._make_bot()
+ bot.send_message = AsyncMock(
+ side_effect=[
+ Exception("Bad Request: can't parse entities: unsupported html tag"),
+ SimpleNamespace(message_id=2), # plain fallback succeeds
+ ]
+ )
+ _install_telegram_mock(monkeypatch, bot)
+
+ result = asyncio.run(
+ _send_telegram("tok", "123", "broken html ")
+ )
+
+ assert result["success"] is True
+ assert bot.send_message.await_count == 2
+ second_call = bot.send_message.await_args_list[1].kwargs
+ assert second_call["parse_mode"] is None
diff --git a/tests/tools/test_web_tools_config.py b/tests/tools/test_web_tools_config.py
index 4bc49166f..d291a005b 100644
--- a/tests/tools/test_web_tools_config.py
+++ b/tests/tools/test_web_tools_config.py
@@ -1,8 +1,11 @@
-"""Tests for Firecrawl client configuration and singleton behavior.
+"""Tests for web backend client configuration and singleton behavior.
Coverage:
_get_firecrawl_client() — configuration matrix, singleton caching,
constructor failure recovery, return value verification, edge cases.
+ _get_backend() — backend selection logic with env var combinations.
+ _get_parallel_client() — Parallel client configuration, singleton caching.
+ check_web_api_key() — unified availability check.
"""
import os
@@ -117,3 +120,212 @@ class TestFirecrawlClientConfig:
from tools.web_tools import _get_firecrawl_client
with pytest.raises(ValueError):
_get_firecrawl_client()
+
+
+class TestBackendSelection:
+ """Test suite for _get_backend() backend selection logic.
+
+ The backend is configured via config.yaml (web.backend), set by
+ ``hermes tools``. Falls back to key-based detection for legacy/manual
+ setups.
+ """
+
+ _ENV_KEYS = ("PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL", "TAVILY_API_KEY")
+
+ def setup_method(self):
+ for key in self._ENV_KEYS:
+ os.environ.pop(key, None)
+
+ def teardown_method(self):
+ for key in self._ENV_KEYS:
+ os.environ.pop(key, None)
+
+ # ── Config-based selection (web.backend in config.yaml) ───────────
+
+ def test_config_parallel(self):
+ """web.backend=parallel in config → 'parallel' regardless of keys."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "parallel"}):
+ assert _get_backend() == "parallel"
+
+ def test_config_firecrawl(self):
+ """web.backend=firecrawl in config → 'firecrawl' even if Parallel key set."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "firecrawl"}), \
+ patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ assert _get_backend() == "firecrawl"
+
+ def test_config_tavily(self):
+ """web.backend=tavily in config → 'tavily' regardless of other keys."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "tavily"}):
+ assert _get_backend() == "tavily"
+
+ def test_config_tavily_overrides_env_keys(self):
+ """web.backend=tavily in config → 'tavily' even if Firecrawl key set."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "tavily"}), \
+ patch.dict(os.environ, {"FIRECRAWL_API_KEY": "fc-test"}):
+ assert _get_backend() == "tavily"
+
+ def test_config_case_insensitive(self):
+ """web.backend=Parallel (mixed case) → 'parallel'."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "Parallel"}):
+ assert _get_backend() == "parallel"
+
+ def test_config_tavily_case_insensitive(self):
+ """web.backend=Tavily (mixed case) → 'tavily'."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "Tavily"}):
+ assert _get_backend() == "tavily"
+
+ # ── Fallback (no web.backend in config) ───────────────────────────
+
+ def test_fallback_parallel_only_key(self):
+ """Only PARALLEL_API_KEY set → 'parallel'."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ assert _get_backend() == "parallel"
+
+ def test_fallback_tavily_only_key(self):
+ """Only TAVILY_API_KEY set → 'tavily'."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}):
+ assert _get_backend() == "tavily"
+
+ def test_fallback_tavily_with_firecrawl_prefers_firecrawl(self):
+ """Tavily + Firecrawl keys, no config → 'firecrawl' (backward compat)."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test", "FIRECRAWL_API_KEY": "fc-test"}):
+ assert _get_backend() == "firecrawl"
+
+ def test_fallback_tavily_with_parallel_prefers_parallel(self):
+ """Tavily + Parallel keys, no config → 'parallel' (Parallel takes priority over Tavily)."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test", "PARALLEL_API_KEY": "par-test"}):
+ # Parallel + no Firecrawl → parallel
+ assert _get_backend() == "parallel"
+
+ def test_fallback_both_keys_defaults_to_firecrawl(self):
+ """Both keys set, no config → 'firecrawl' (backward compat)."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key", "FIRECRAWL_API_KEY": "fc-test"}):
+ assert _get_backend() == "firecrawl"
+
+ def test_fallback_firecrawl_only_key(self):
+ """Only FIRECRAWL_API_KEY set → 'firecrawl'."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}), \
+ patch.dict(os.environ, {"FIRECRAWL_API_KEY": "fc-test"}):
+ assert _get_backend() == "firecrawl"
+
+ def test_fallback_no_keys_defaults_to_firecrawl(self):
+ """No keys, no config → 'firecrawl' (will fail at client init)."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={}):
+ assert _get_backend() == "firecrawl"
+
+ def test_invalid_config_falls_through_to_fallback(self):
+ """web.backend=invalid → ignored, uses key-based fallback."""
+ from tools.web_tools import _get_backend
+ with patch("tools.web_tools._load_web_config", return_value={"backend": "nonexistent"}), \
+ patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ assert _get_backend() == "parallel"
+
+
+class TestParallelClientConfig:
+ """Test suite for Parallel client initialization."""
+
+ def setup_method(self):
+ import tools.web_tools
+ tools.web_tools._parallel_client = None
+ os.environ.pop("PARALLEL_API_KEY", None)
+
+ def teardown_method(self):
+ import tools.web_tools
+ tools.web_tools._parallel_client = None
+ os.environ.pop("PARALLEL_API_KEY", None)
+
+ def test_creates_client_with_key(self):
+ """PARALLEL_API_KEY set → creates Parallel client."""
+ with patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ from tools.web_tools import _get_parallel_client
+ from parallel import Parallel
+ client = _get_parallel_client()
+ assert client is not None
+ assert isinstance(client, Parallel)
+
+ def test_no_key_raises_with_helpful_message(self):
+ """No PARALLEL_API_KEY → ValueError with guidance."""
+ from tools.web_tools import _get_parallel_client
+ with pytest.raises(ValueError, match="PARALLEL_API_KEY"):
+ _get_parallel_client()
+
+ def test_singleton_returns_same_instance(self):
+ """Second call returns cached client."""
+ with patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ from tools.web_tools import _get_parallel_client
+ client1 = _get_parallel_client()
+ client2 = _get_parallel_client()
+ assert client1 is client2
+
+
+class TestCheckWebApiKey:
+ """Test suite for check_web_api_key() unified availability check."""
+
+ _ENV_KEYS = ("PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL", "TAVILY_API_KEY")
+
+ def setup_method(self):
+ for key in self._ENV_KEYS:
+ os.environ.pop(key, None)
+
+ def teardown_method(self):
+ for key in self._ENV_KEYS:
+ os.environ.pop(key, None)
+
+ def test_parallel_key_only(self):
+ with patch.dict(os.environ, {"PARALLEL_API_KEY": "test-key"}):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
+
+ def test_firecrawl_key_only(self):
+ with patch.dict(os.environ, {"FIRECRAWL_API_KEY": "fc-test"}):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
+
+ def test_firecrawl_url_only(self):
+ with patch.dict(os.environ, {"FIRECRAWL_API_URL": "http://localhost:3002"}):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
+
+ def test_tavily_key_only(self):
+ with patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
+
+ def test_no_keys_returns_false(self):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is False
+
+ def test_both_keys_returns_true(self):
+ with patch.dict(os.environ, {
+ "PARALLEL_API_KEY": "test-key",
+ "FIRECRAWL_API_KEY": "fc-test",
+ }):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
+
+ def test_all_three_keys_returns_true(self):
+ with patch.dict(os.environ, {
+ "PARALLEL_API_KEY": "test-key",
+ "FIRECRAWL_API_KEY": "fc-test",
+ "TAVILY_API_KEY": "tvly-test",
+ }):
+ from tools.web_tools import check_web_api_key
+ assert check_web_api_key() is True
diff --git a/tests/tools/test_web_tools_tavily.py b/tests/tools/test_web_tools_tavily.py
new file mode 100644
index 000000000..2e49b72f1
--- /dev/null
+++ b/tests/tools/test_web_tools_tavily.py
@@ -0,0 +1,255 @@
+"""Tests for Tavily web backend integration.
+
+Coverage:
+ _tavily_request() — API key handling, endpoint construction, error propagation.
+ _normalize_tavily_search_results() — search response normalization.
+ _normalize_tavily_documents() — extract/crawl response normalization, failed_results.
+ web_search_tool / web_extract_tool / web_crawl_tool — Tavily dispatch paths.
+"""
+
+import json
+import os
+import asyncio
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+# ─── _tavily_request ─────────────────────────────────────────────────────────
+
+class TestTavilyRequest:
+ """Test suite for the _tavily_request helper."""
+
+ def test_raises_without_api_key(self):
+ """No TAVILY_API_KEY → ValueError with guidance."""
+ with patch.dict(os.environ, {}, clear=False):
+ os.environ.pop("TAVILY_API_KEY", None)
+ from tools.web_tools import _tavily_request
+ with pytest.raises(ValueError, match="TAVILY_API_KEY"):
+ _tavily_request("search", {"query": "test"})
+
+ def test_posts_with_api_key_in_body(self):
+ """api_key is injected into the JSON payload."""
+ mock_response = MagicMock()
+ mock_response.json.return_value = {"results": []}
+ mock_response.raise_for_status = MagicMock()
+
+ with patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test-key"}):
+ with patch("tools.web_tools.httpx.post", return_value=mock_response) as mock_post:
+ from tools.web_tools import _tavily_request
+ result = _tavily_request("search", {"query": "hello"})
+
+ mock_post.assert_called_once()
+ call_kwargs = mock_post.call_args
+ payload = call_kwargs.kwargs.get("json") or call_kwargs[1].get("json")
+ assert payload["api_key"] == "tvly-test-key"
+ assert payload["query"] == "hello"
+ assert "api.tavily.com/search" in call_kwargs.args[0]
+
+ def test_raises_on_http_error(self):
+ """Non-2xx responses propagate as httpx.HTTPStatusError."""
+ import httpx as _httpx
+ mock_response = MagicMock()
+ mock_response.raise_for_status.side_effect = _httpx.HTTPStatusError(
+ "401 Unauthorized", request=MagicMock(), response=mock_response
+ )
+
+ with patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-bad-key"}):
+ with patch("tools.web_tools.httpx.post", return_value=mock_response):
+ from tools.web_tools import _tavily_request
+ with pytest.raises(_httpx.HTTPStatusError):
+ _tavily_request("search", {"query": "test"})
+
+
+# ─── _normalize_tavily_search_results ─────────────────────────────────────────
+
+class TestNormalizeTavilySearchResults:
+ """Test search result normalization."""
+
+ def test_basic_normalization(self):
+ from tools.web_tools import _normalize_tavily_search_results
+ raw = {
+ "results": [
+ {"title": "Python Docs", "url": "https://docs.python.org", "content": "Official docs", "score": 0.9},
+ {"title": "Tutorial", "url": "https://example.com", "content": "A tutorial", "score": 0.8},
+ ]
+ }
+ result = _normalize_tavily_search_results(raw)
+ assert result["success"] is True
+ web = result["data"]["web"]
+ assert len(web) == 2
+ assert web[0]["title"] == "Python Docs"
+ assert web[0]["url"] == "https://docs.python.org"
+ assert web[0]["description"] == "Official docs"
+ assert web[0]["position"] == 1
+ assert web[1]["position"] == 2
+
+ def test_empty_results(self):
+ from tools.web_tools import _normalize_tavily_search_results
+ result = _normalize_tavily_search_results({"results": []})
+ assert result["success"] is True
+ assert result["data"]["web"] == []
+
+ def test_missing_fields(self):
+ from tools.web_tools import _normalize_tavily_search_results
+ result = _normalize_tavily_search_results({"results": [{}]})
+ web = result["data"]["web"]
+ assert web[0]["title"] == ""
+ assert web[0]["url"] == ""
+ assert web[0]["description"] == ""
+
+
+# ─── _normalize_tavily_documents ──────────────────────────────────────────────
+
+class TestNormalizeTavilyDocuments:
+ """Test extract/crawl document normalization."""
+
+ def test_basic_document(self):
+ from tools.web_tools import _normalize_tavily_documents
+ raw = {
+ "results": [{
+ "url": "https://example.com",
+ "title": "Example",
+ "raw_content": "Full page content here",
+ }]
+ }
+ docs = _normalize_tavily_documents(raw)
+ assert len(docs) == 1
+ assert docs[0]["url"] == "https://example.com"
+ assert docs[0]["title"] == "Example"
+ assert docs[0]["content"] == "Full page content here"
+ assert docs[0]["raw_content"] == "Full page content here"
+ assert docs[0]["metadata"]["sourceURL"] == "https://example.com"
+
+ def test_falls_back_to_content_when_no_raw_content(self):
+ from tools.web_tools import _normalize_tavily_documents
+ raw = {"results": [{"url": "https://example.com", "content": "Snippet"}]}
+ docs = _normalize_tavily_documents(raw)
+ assert docs[0]["content"] == "Snippet"
+
+ def test_failed_results_included(self):
+ from tools.web_tools import _normalize_tavily_documents
+ raw = {
+ "results": [],
+ "failed_results": [
+ {"url": "https://fail.com", "error": "timeout"},
+ ],
+ }
+ docs = _normalize_tavily_documents(raw)
+ assert len(docs) == 1
+ assert docs[0]["url"] == "https://fail.com"
+ assert docs[0]["error"] == "timeout"
+ assert docs[0]["content"] == ""
+
+ def test_failed_urls_included(self):
+ from tools.web_tools import _normalize_tavily_documents
+ raw = {
+ "results": [],
+ "failed_urls": ["https://bad.com"],
+ }
+ docs = _normalize_tavily_documents(raw)
+ assert len(docs) == 1
+ assert docs[0]["url"] == "https://bad.com"
+ assert docs[0]["error"] == "extraction failed"
+
+ def test_fallback_url(self):
+ from tools.web_tools import _normalize_tavily_documents
+ raw = {"results": [{"content": "data"}]}
+ docs = _normalize_tavily_documents(raw, fallback_url="https://fallback.com")
+ assert docs[0]["url"] == "https://fallback.com"
+
+
+# ─── web_search_tool (Tavily dispatch) ────────────────────────────────────────
+
+class TestWebSearchTavily:
+ """Test web_search_tool dispatch to Tavily."""
+
+ def test_search_dispatches_to_tavily(self):
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [{"title": "Result", "url": "https://r.com", "content": "desc", "score": 0.9}]
+ }
+ mock_response.raise_for_status = MagicMock()
+
+ with patch("tools.web_tools._get_backend", return_value="tavily"), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}), \
+ patch("tools.web_tools.httpx.post", return_value=mock_response), \
+ patch("tools.interrupt.is_interrupted", return_value=False):
+ from tools.web_tools import web_search_tool
+ result = json.loads(web_search_tool("test query", limit=3))
+ assert result["success"] is True
+ assert len(result["data"]["web"]) == 1
+ assert result["data"]["web"][0]["title"] == "Result"
+
+
+# ─── web_extract_tool (Tavily dispatch) ───────────────────────────────────────
+
+class TestWebExtractTavily:
+ """Test web_extract_tool dispatch to Tavily."""
+
+ def test_extract_dispatches_to_tavily(self):
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [{"url": "https://example.com", "raw_content": "Extracted content", "title": "Page"}]
+ }
+ mock_response.raise_for_status = MagicMock()
+
+ with patch("tools.web_tools._get_backend", return_value="tavily"), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}), \
+ patch("tools.web_tools.httpx.post", return_value=mock_response), \
+ patch("tools.web_tools.process_content_with_llm", return_value=None):
+ from tools.web_tools import web_extract_tool
+ result = json.loads(asyncio.get_event_loop().run_until_complete(
+ web_extract_tool(["https://example.com"], use_llm_processing=False)
+ ))
+ assert "results" in result
+ assert len(result["results"]) == 1
+ assert result["results"][0]["url"] == "https://example.com"
+
+
+# ─── web_crawl_tool (Tavily dispatch) ─────────────────────────────────────────
+
+class TestWebCrawlTavily:
+ """Test web_crawl_tool dispatch to Tavily."""
+
+ def test_crawl_dispatches_to_tavily(self):
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [
+ {"url": "https://example.com/page1", "raw_content": "Page 1 content", "title": "Page 1"},
+ {"url": "https://example.com/page2", "raw_content": "Page 2 content", "title": "Page 2"},
+ ]
+ }
+ mock_response.raise_for_status = MagicMock()
+
+ with patch("tools.web_tools._get_backend", return_value="tavily"), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}), \
+ patch("tools.web_tools.httpx.post", return_value=mock_response), \
+ patch("tools.web_tools.check_website_access", return_value=None), \
+ patch("tools.interrupt.is_interrupted", return_value=False):
+ from tools.web_tools import web_crawl_tool
+ result = json.loads(asyncio.get_event_loop().run_until_complete(
+ web_crawl_tool("https://example.com", use_llm_processing=False)
+ ))
+ assert "results" in result
+ assert len(result["results"]) == 2
+ assert result["results"][0]["title"] == "Page 1"
+
+ def test_crawl_sends_instructions(self):
+ """Instructions are included in the Tavily crawl payload."""
+ mock_response = MagicMock()
+ mock_response.json.return_value = {"results": []}
+ mock_response.raise_for_status = MagicMock()
+
+ with patch("tools.web_tools._get_backend", return_value="tavily"), \
+ patch.dict(os.environ, {"TAVILY_API_KEY": "tvly-test"}), \
+ patch("tools.web_tools.httpx.post", return_value=mock_response) as mock_post, \
+ patch("tools.web_tools.check_website_access", return_value=None), \
+ patch("tools.interrupt.is_interrupted", return_value=False):
+ from tools.web_tools import web_crawl_tool
+ asyncio.get_event_loop().run_until_complete(
+ web_crawl_tool("https://example.com", instructions="Find docs", use_llm_processing=False)
+ )
+ call_kwargs = mock_post.call_args
+ payload = call_kwargs.kwargs.get("json") or call_kwargs[1].get("json")
+ assert payload["instructions"] == "Find docs"
+ assert payload["url"] == "https://example.com"
diff --git a/tests/tools/test_website_policy.py b/tests/tools/test_website_policy.py
new file mode 100644
index 000000000..9d620b59a
--- /dev/null
+++ b/tests/tools/test_website_policy.py
@@ -0,0 +1,495 @@
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+
+from tools.website_policy import WebsitePolicyError, check_website_access, load_website_blocklist
+
+
+def test_load_website_blocklist_merges_config_and_shared_file(tmp_path):
+ shared = tmp_path / "community-blocklist.txt"
+ shared.write_text("# comment\nexample.org\nsub.bad.net\n", encoding="utf-8")
+
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": ["example.com", "https://www.evil.test/path"],
+ "shared_files": [str(shared)],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ policy = load_website_blocklist(config_path)
+
+ assert policy["enabled"] is True
+ assert {rule["pattern"] for rule in policy["rules"]} == {
+ "example.com",
+ "evil.test",
+ "example.org",
+ "sub.bad.net",
+ }
+
+
+def test_check_website_access_matches_parent_domain_subdomains(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": ["example.com"],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ blocked = check_website_access("https://docs.example.com/page", config_path=config_path)
+
+ assert blocked is not None
+ assert blocked["host"] == "docs.example.com"
+ assert blocked["rule"] == "example.com"
+
+
+def test_check_website_access_supports_wildcard_subdomains_only(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": ["*.tracking.example"],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ assert check_website_access("https://a.tracking.example", config_path=config_path) is not None
+ assert check_website_access("https://www.tracking.example", config_path=config_path) is not None
+ assert check_website_access("https://tracking.example", config_path=config_path) is None
+
+
+def test_default_config_exposes_website_blocklist_shape():
+ from hermes_cli.config import DEFAULT_CONFIG
+
+ website_blocklist = DEFAULT_CONFIG["security"]["website_blocklist"]
+ assert website_blocklist["enabled"] is False
+ assert website_blocklist["domains"] == []
+ assert website_blocklist["shared_files"] == []
+
+
+def test_load_website_blocklist_uses_enabled_default_when_section_missing(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(yaml.safe_dump({"display": {"tool_progress": "all"}}, sort_keys=False), encoding="utf-8")
+
+ policy = load_website_blocklist(config_path)
+
+ assert policy == {"enabled": False, "rules": []}
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_domains_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": "example.com",
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(WebsitePolicyError, match="security.website_blocklist.domains must be a list"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_shared_files_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "shared_files": "community-blocklist.txt",
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(WebsitePolicyError, match="security.website_blocklist.shared_files must be a list"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_top_level_config_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(yaml.safe_dump(["not", "a", "mapping"], sort_keys=False), encoding="utf-8")
+
+ with pytest.raises(WebsitePolicyError, match="config root must be a mapping"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_security_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(yaml.safe_dump({"security": []}, sort_keys=False), encoding="utf-8")
+
+ with pytest.raises(WebsitePolicyError, match="security must be a mapping"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_website_blocklist_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": "block everything",
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(WebsitePolicyError, match="security.website_blocklist must be a mapping"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_invalid_enabled_type(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": "false",
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(WebsitePolicyError, match="security.website_blocklist.enabled must be a boolean"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_raises_clean_error_for_malformed_yaml(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text("security: [oops\n", encoding="utf-8")
+
+ with pytest.raises(WebsitePolicyError, match="Invalid config YAML"):
+ load_website_blocklist(config_path)
+
+
+def test_load_website_blocklist_wraps_shared_file_read_errors(tmp_path, monkeypatch):
+ shared = tmp_path / "community-blocklist.txt"
+ shared.write_text("example.org\n", encoding="utf-8")
+
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "shared_files": [str(shared)],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ def failing_read_text(self, *args, **kwargs):
+ raise PermissionError("no permission")
+
+ monkeypatch.setattr(Path, "read_text", failing_read_text)
+
+ # Unreadable shared files are now warned and skipped (not raised),
+ # so the blocklist loads successfully but without those rules.
+ result = load_website_blocklist(config_path)
+ assert result["enabled"] is True
+ assert result["rules"] == [] # shared file rules skipped
+
+
+def test_check_website_access_uses_dynamic_hermes_home(monkeypatch, tmp_path):
+ hermes_home = tmp_path / "hermes-home"
+ hermes_home.mkdir()
+ (hermes_home / "config.yaml").write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": ["dynamic.example"],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+ blocked = check_website_access("https://dynamic.example/path")
+
+ assert blocked is not None
+ assert blocked["rule"] == "dynamic.example"
+
+
+def test_check_website_access_blocks_scheme_less_urls(tmp_path):
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "domains": ["blocked.test"],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ blocked = check_website_access("www.blocked.test/path", config_path=config_path)
+
+ assert blocked is not None
+ assert blocked["host"] == "www.blocked.test"
+ assert blocked["rule"] == "blocked.test"
+
+
+def test_browser_navigate_returns_policy_block(monkeypatch):
+ from tools import browser_tool
+
+ monkeypatch.setattr(
+ browser_tool,
+ "check_website_access",
+ lambda url: {
+ "host": "blocked.test",
+ "rule": "blocked.test",
+ "source": "config",
+ "message": "Blocked by website policy",
+ },
+ )
+ monkeypatch.setattr(
+ browser_tool,
+ "_run_browser_command",
+ lambda *args, **kwargs: pytest.fail("browser command should not run for blocked URL"),
+ )
+
+ result = json.loads(browser_tool.browser_navigate("https://blocked.test"))
+
+ assert result["success"] is False
+ assert result["blocked_by_policy"]["rule"] == "blocked.test"
+
+
+def test_browser_navigate_allows_when_shared_file_missing(monkeypatch, tmp_path):
+ """Missing shared blocklist files are warned and skipped, not fatal."""
+ from tools import browser_tool
+
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text(
+ yaml.safe_dump(
+ {
+ "security": {
+ "website_blocklist": {
+ "enabled": True,
+ "shared_files": ["missing-blocklist.txt"],
+ }
+ }
+ },
+ sort_keys=False,
+ ),
+ encoding="utf-8",
+ )
+
+ # check_website_access should return None (allow) — missing file is skipped
+ result = check_website_access("https://allowed.test", config_path=config_path)
+ assert result is None
+
+
+@pytest.mark.asyncio
+async def test_web_extract_short_circuits_blocked_url(monkeypatch):
+ from tools import web_tools
+
+ monkeypatch.setattr(
+ web_tools,
+ "check_website_access",
+ lambda url: {
+ "host": "blocked.test",
+ "rule": "blocked.test",
+ "source": "config",
+ "message": "Blocked by website policy",
+ },
+ )
+ monkeypatch.setattr(
+ web_tools,
+ "_get_firecrawl_client",
+ lambda: pytest.fail("firecrawl should not run for blocked URL"),
+ )
+ monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+ result = json.loads(await web_tools.web_extract_tool(["https://blocked.test"], use_llm_processing=False))
+
+ assert result["results"][0]["url"] == "https://blocked.test"
+ assert "Blocked by website policy" in result["results"][0]["error"]
+
+
+def test_check_website_access_fails_open_on_malformed_config(tmp_path, monkeypatch):
+ """Malformed config with default path should fail open (return None), not crash."""
+ config_path = tmp_path / "config.yaml"
+ config_path.write_text("security: [oops\n", encoding="utf-8")
+
+ # With explicit config_path (test mode), errors propagate
+ with pytest.raises(WebsitePolicyError):
+ check_website_access("https://example.com", config_path=config_path)
+
+ # Simulate default path by pointing HERMES_HOME to tmp_path
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+ from tools import website_policy
+ website_policy.invalidate_cache()
+
+ # With default path, errors are caught and fail open
+ result = check_website_access("https://example.com")
+ assert result is None # allowed, not crashed
+
+
+@pytest.mark.asyncio
+async def test_web_extract_blocks_redirected_final_url(monkeypatch):
+ from tools import web_tools
+
+ def fake_check(url):
+ if url == "https://allowed.test":
+ return None
+ if url == "https://blocked.test/final":
+ return {
+ "host": "blocked.test",
+ "rule": "blocked.test",
+ "source": "config",
+ "message": "Blocked by website policy",
+ }
+ pytest.fail(f"unexpected URL checked: {url}")
+
+ class FakeFirecrawlClient:
+ def scrape(self, url, formats):
+ return {
+ "markdown": "secret content",
+ "metadata": {
+ "title": "Redirected",
+ "sourceURL": "https://blocked.test/final",
+ },
+ }
+
+ monkeypatch.setattr(web_tools, "check_website_access", fake_check)
+ monkeypatch.setattr(web_tools, "_get_firecrawl_client", lambda: FakeFirecrawlClient())
+ monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+ result = json.loads(await web_tools.web_extract_tool(["https://allowed.test"], use_llm_processing=False))
+
+ assert result["results"][0]["url"] == "https://blocked.test/final"
+ assert result["results"][0]["content"] == ""
+ assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
+
+
+@pytest.mark.asyncio
+async def test_web_crawl_short_circuits_blocked_url(monkeypatch):
+ from tools import web_tools
+
+ # web_crawl_tool checks for Firecrawl env before website policy
+ monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+ monkeypatch.setattr(
+ web_tools,
+ "check_website_access",
+ lambda url: {
+ "host": "blocked.test",
+ "rule": "blocked.test",
+ "source": "config",
+ "message": "Blocked by website policy",
+ },
+ )
+ monkeypatch.setattr(
+ web_tools,
+ "_get_firecrawl_client",
+ lambda: pytest.fail("firecrawl should not run for blocked crawl URL"),
+ )
+ monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+ result = json.loads(await web_tools.web_crawl_tool("https://blocked.test", use_llm_processing=False))
+
+ assert result["results"][0]["url"] == "https://blocked.test"
+ assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
+
+
+@pytest.mark.asyncio
+async def test_web_crawl_blocks_redirected_final_url(monkeypatch):
+ from tools import web_tools
+
+ # web_crawl_tool checks for Firecrawl env before website policy
+ monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+
+ def fake_check(url):
+ if url == "https://allowed.test":
+ return None
+ if url == "https://blocked.test/final":
+ return {
+ "host": "blocked.test",
+ "rule": "blocked.test",
+ "source": "config",
+ "message": "Blocked by website policy",
+ }
+ pytest.fail(f"unexpected URL checked: {url}")
+
+ class FakeCrawlClient:
+ def crawl(self, url, **kwargs):
+ return {
+ "data": [
+ {
+ "markdown": "secret crawl content",
+ "metadata": {
+ "title": "Redirected crawl page",
+ "sourceURL": "https://blocked.test/final",
+ },
+ }
+ ]
+ }
+
+ monkeypatch.setattr(web_tools, "check_website_access", fake_check)
+ monkeypatch.setattr(web_tools, "_get_firecrawl_client", lambda: FakeCrawlClient())
+ monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+ result = json.loads(await web_tools.web_crawl_tool("https://allowed.test", use_llm_processing=False))
+
+ assert result["results"][0]["content"] == ""
+ assert result["results"][0]["error"] == "Blocked by website policy"
+ assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
diff --git a/tools/browser_tool.py b/tools/browser_tool.py
index d57eedee8..9760cf302 100644
--- a/tools/browser_tool.py
+++ b/tools/browser_tool.py
@@ -65,6 +65,11 @@ import requests
from typing import Dict, Any, Optional, List
from pathlib import Path
from agent.auxiliary_client import call_llm
+
+try:
+ from tools.website_policy import check_website_access
+except Exception:
+ check_website_access = lambda url: None # noqa: E731 — fail-open if policy module unavailable
from tools.browser_providers.base import CloudBrowserProvider
from tools.browser_providers.browserbase import BrowserbaseProvider
from tools.browser_providers.browser_use import BrowserUseProvider
@@ -550,6 +555,11 @@ def _get_session_info(task_id: Optional[str] = None) -> Dict[str, str]:
session_info = provider.create_session(task_id)
with _cleanup_lock:
+ # Double-check: another thread may have created a session while we
+ # were doing the network call. Use the existing one to avoid leaking
+ # orphan cloud sessions.
+ if task_id in _active_sessions:
+ return _active_sessions[task_id]
_active_sessions[task_id] = session_info
return session_info
@@ -901,6 +911,15 @@ def browser_navigate(url: str, task_id: Optional[str] = None) -> str:
Returns:
JSON string with navigation result (includes stealth features info on first nav)
"""
+ # Website policy check — block before navigating
+ blocked = check_website_access(url)
+ if blocked:
+ return json.dumps({
+ "success": False,
+ "error": blocked["message"],
+ "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]},
+ })
+
effective_task_id = task_id or "default"
# Get session info to check if this is a new session
diff --git a/tools/delegate_tool.py b/tools/delegate_tool.py
index 1ac75ea88..2ef505dab 100644
--- a/tools/delegate_tool.py
+++ b/tools/delegate_tool.py
@@ -16,13 +16,10 @@ The parent's context only sees the delegation call and the summary result,
never the child's intermediate tool calls or reasoning.
"""
-import contextlib
-import io
import json
import logging
logger = logging.getLogger(__name__)
import os
-import sys
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from typing import Any, Dict, List, Optional
@@ -150,7 +147,7 @@ def _build_child_progress_callback(task_index: int, parent_agent, task_count: in
return _callback
-def _run_single_child(
+def _build_child_agent(
task_index: int,
goal: str,
context: Optional[str],
@@ -158,16 +155,15 @@ def _run_single_child(
model: Optional[str],
max_iterations: int,
parent_agent,
- task_count: int = 1,
# Credential overrides from delegation config (provider:model resolution)
override_provider: Optional[str] = None,
override_base_url: Optional[str] = None,
override_api_key: Optional[str] = None,
override_api_mode: Optional[str] = None,
-) -> Dict[str, Any]:
+):
"""
- Spawn and run a single child agent. Called from within a thread.
- Returns a structured result dict.
+ Build a child AIAgent on the main thread (thread-safe construction).
+ Returns the constructed child agent without running it.
When override_* params are set (from delegation config), the child uses
those credentials instead of inheriting from the parent. This enables
@@ -176,8 +172,6 @@ def _run_single_child(
"""
from run_agent import AIAgent
- child_start = time.monotonic()
-
# When no explicit toolsets given, inherit from parent's enabled toolsets
# so disabled tools (e.g. web) don't leak to subagents.
if toolsets:
@@ -188,65 +182,84 @@ def _run_single_child(
child_toolsets = _strip_blocked_tools(DEFAULT_TOOLSETS)
child_prompt = _build_child_system_prompt(goal, context)
+ # Extract parent's API key so subagents inherit auth (e.g. Nous Portal).
+ parent_api_key = getattr(parent_agent, "api_key", None)
+ if (not parent_api_key) and hasattr(parent_agent, "_client_kwargs"):
+ parent_api_key = parent_agent._client_kwargs.get("api_key")
- try:
- # Extract parent's API key so subagents inherit auth (e.g. Nous Portal).
- parent_api_key = getattr(parent_agent, "api_key", None)
- if (not parent_api_key) and hasattr(parent_agent, "_client_kwargs"):
- parent_api_key = parent_agent._client_kwargs.get("api_key")
+ # Build progress callback to relay tool calls to parent display
+ child_progress_cb = _build_child_progress_callback(task_index, parent_agent)
- # Build progress callback to relay tool calls to parent display
- child_progress_cb = _build_child_progress_callback(task_index, parent_agent, task_count)
+ # Share the parent's iteration budget so subagent tool calls
+ # count toward the session-wide limit.
+ shared_budget = getattr(parent_agent, "iteration_budget", None)
- # Share the parent's iteration budget so subagent tool calls
- # count toward the session-wide limit.
- shared_budget = getattr(parent_agent, "iteration_budget", None)
+ # Resolve effective credentials: config override > parent inherit
+ effective_model = model or parent_agent.model
+ effective_provider = override_provider or getattr(parent_agent, "provider", None)
+ effective_base_url = override_base_url or parent_agent.base_url
+ effective_api_key = override_api_key or parent_api_key
+ effective_api_mode = override_api_mode or getattr(parent_agent, "api_mode", None)
- # Resolve effective credentials: config override > parent inherit
- effective_model = model or parent_agent.model
- effective_provider = override_provider or getattr(parent_agent, "provider", None)
- effective_base_url = override_base_url or parent_agent.base_url
- effective_api_key = override_api_key or parent_api_key
- effective_api_mode = override_api_mode or getattr(parent_agent, "api_mode", None)
+ child = AIAgent(
+ base_url=effective_base_url,
+ api_key=effective_api_key,
+ model=effective_model,
+ provider=effective_provider,
+ api_mode=effective_api_mode,
+ max_iterations=max_iterations,
+ max_tokens=getattr(parent_agent, "max_tokens", None),
+ reasoning_config=getattr(parent_agent, "reasoning_config", None),
+ prefill_messages=getattr(parent_agent, "prefill_messages", None),
+ enabled_toolsets=child_toolsets,
+ quiet_mode=True,
+ ephemeral_system_prompt=child_prompt,
+ log_prefix=f"[subagent-{task_index}]",
+ platform=parent_agent.platform,
+ skip_context_files=True,
+ skip_memory=True,
+ clarify_callback=None,
+ session_db=getattr(parent_agent, '_session_db', None),
+ providers_allowed=parent_agent.providers_allowed,
+ providers_ignored=parent_agent.providers_ignored,
+ providers_order=parent_agent.providers_order,
+ provider_sort=parent_agent.provider_sort,
+ tool_progress_callback=child_progress_cb,
+ iteration_budget=shared_budget,
+ )
- child = AIAgent(
- base_url=effective_base_url,
- api_key=effective_api_key,
- model=effective_model,
- provider=effective_provider,
- api_mode=effective_api_mode,
- max_iterations=max_iterations,
- max_tokens=getattr(parent_agent, "max_tokens", None),
- reasoning_config=getattr(parent_agent, "reasoning_config", None),
- prefill_messages=getattr(parent_agent, "prefill_messages", None),
- enabled_toolsets=child_toolsets,
- quiet_mode=True,
- ephemeral_system_prompt=child_prompt,
- log_prefix=f"[subagent-{task_index}]",
- platform=parent_agent.platform,
- skip_context_files=True,
- skip_memory=True,
- clarify_callback=None,
- session_db=getattr(parent_agent, '_session_db', None),
- providers_allowed=parent_agent.providers_allowed,
- providers_ignored=parent_agent.providers_ignored,
- providers_order=parent_agent.providers_order,
- provider_sort=parent_agent.provider_sort,
- tool_progress_callback=child_progress_cb,
- iteration_budget=shared_budget,
- )
+ # Set delegation depth so children can't spawn grandchildren
+ child._delegate_depth = getattr(parent_agent, '_delegate_depth', 0) + 1
- # Set delegation depth so children can't spawn grandchildren
- child._delegate_depth = getattr(parent_agent, '_delegate_depth', 0) + 1
-
- # Register child for interrupt propagation
- if hasattr(parent_agent, '_active_children'):
+ # Register child for interrupt propagation
+ if hasattr(parent_agent, '_active_children'):
+ lock = getattr(parent_agent, '_active_children_lock', None)
+ if lock:
+ with lock:
+ parent_agent._active_children.append(child)
+ else:
parent_agent._active_children.append(child)
- # Run with stdout/stderr suppressed to prevent interleaved output
- devnull = io.StringIO()
- with contextlib.redirect_stdout(devnull), contextlib.redirect_stderr(devnull):
- result = child.run_conversation(user_message=goal)
+ return child
+
+def _run_single_child(
+ task_index: int,
+ goal: str,
+ child=None,
+ parent_agent=None,
+ **_kwargs,
+) -> Dict[str, Any]:
+ """
+ Run a pre-built child agent. Called from within a thread.
+ Returns a structured result dict.
+ """
+ child_start = time.monotonic()
+
+ # Get the progress callback from the child agent
+ child_progress_cb = getattr(child, 'tool_progress_callback', None)
+
+ try:
+ result = child.run_conversation(user_message=goal)
# Flush any remaining batched progress to gateway
if child_progress_cb and hasattr(child_progress_cb, '_flush'):
@@ -355,11 +368,15 @@ def _run_single_child(
# Unregister child from interrupt propagation
if hasattr(parent_agent, '_active_children'):
try:
- parent_agent._active_children.remove(child)
+ lock = getattr(parent_agent, '_active_children_lock', None)
+ if lock:
+ with lock:
+ parent_agent._active_children.remove(child)
+ else:
+ parent_agent._active_children.remove(child)
except (ValueError, UnboundLocalError) as e:
logger.debug("Could not remove child from active_children: %s", e)
-
def delegate_task(
goal: Optional[str] = None,
context: Optional[str] = None,
@@ -428,51 +445,38 @@ def delegate_task(
# Track goal labels for progress display (truncated for readability)
task_labels = [t["goal"][:40] for t in task_list]
- if n_tasks == 1:
- # Single task -- run directly (no thread pool overhead)
- t = task_list[0]
- result = _run_single_child(
- task_index=0,
- goal=t["goal"],
- context=t.get("context"),
- toolsets=t.get("toolsets") or toolsets,
- model=creds["model"],
- max_iterations=effective_max_iter,
- parent_agent=parent_agent,
- task_count=1,
- override_provider=creds["provider"],
- override_base_url=creds["base_url"],
+ # Build all child agents on the main thread (thread-safe construction)
+ children = []
+ for i, t in enumerate(task_list):
+ child = _build_child_agent(
+ task_index=i, goal=t["goal"], context=t.get("context"),
+ toolsets=t.get("toolsets") or toolsets, model=creds["model"],
+ max_iterations=effective_max_iter, parent_agent=parent_agent,
+ override_provider=creds["provider"], override_base_url=creds["base_url"],
override_api_key=creds["api_key"],
override_api_mode=creds["api_mode"],
)
+ children.append((i, t, child))
+
+ if n_tasks == 1:
+ # Single task -- run directly (no thread pool overhead)
+ _i, _t, child = children[0]
+ result = _run_single_child(0, _t["goal"], child, parent_agent)
results.append(result)
else:
# Batch -- run in parallel with per-task progress lines
completed_count = 0
spinner_ref = getattr(parent_agent, '_delegate_spinner', None)
- # Save stdout/stderr before the executor — redirect_stdout in child
- # threads races on sys.stdout and can leave it as devnull permanently.
- _saved_stdout = sys.stdout
- _saved_stderr = sys.stderr
-
with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_CHILDREN) as executor:
futures = {}
- for i, t in enumerate(task_list):
+ for i, t, child in children:
future = executor.submit(
_run_single_child,
task_index=i,
goal=t["goal"],
- context=t.get("context"),
- toolsets=t.get("toolsets") or toolsets,
- model=creds["model"],
- max_iterations=effective_max_iter,
+ child=child,
parent_agent=parent_agent,
- task_count=n_tasks,
- override_provider=creds["provider"],
- override_base_url=creds["base_url"],
- override_api_key=creds["api_key"],
- override_api_mode=creds["api_mode"],
)
futures[future] = i
@@ -515,10 +519,6 @@ def delegate_task(
except Exception as e:
logger.debug("Spinner update_text failed: %s", e)
- # Restore stdout/stderr in case redirect_stdout race left them as devnull
- sys.stdout = _saved_stdout
- sys.stderr = _saved_stderr
-
# Sort by task_index so results match input order
results.sort(key=lambda r: r["task_index"])
diff --git a/tools/environments/local.py b/tools/environments/local.py
index dc753b410..914192f2d 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -82,6 +82,9 @@ def _build_provider_env_blocklist() -> frozenset:
"FIREWORKS_API_KEY", # Fireworks AI
"XAI_API_KEY", # xAI (Grok)
"HELICONE_API_KEY", # LLM Observability proxy
+ "PARALLEL_API_KEY",
+ "FIRECRAWL_API_KEY",
+ "FIRECRAWL_API_URL",
# Gateway/runtime config not represented in OPTIONAL_ENV_VARS.
"TELEGRAM_HOME_CHANNEL",
"TELEGRAM_HOME_CHANNEL_NAME",
diff --git a/tools/file_operations.py b/tools/file_operations.py
index 7f39a0277..56ed1319f 100644
--- a/tools/file_operations.py
+++ b/tools/file_operations.py
@@ -94,7 +94,7 @@ def _get_safe_write_root() -> Optional[str]:
def _is_write_denied(path: str) -> bool:
"""Return True if path is on the write deny list."""
- resolved = os.path.realpath(os.path.expanduser(path))
+ resolved = os.path.realpath(os.path.expanduser(str(path)))
# 1) Static deny list
if resolved in WRITE_DENIED_PATHS:
diff --git a/tools/fuzzy_match.py b/tools/fuzzy_match.py
index f53451c63..ddcdf4274 100644
--- a/tools/fuzzy_match.py
+++ b/tools/fuzzy_match.py
@@ -254,10 +254,9 @@ def _strategy_trimmed_boundary(content: str, pattern: str) -> List[Tuple[int, in
if '\n'.join(check_lines) == modified_pattern:
# Found match - calculate original positions
- start_pos = sum(len(line) + 1 for line in content_lines[:i])
- end_pos = sum(len(line) + 1 for line in content_lines[:i + pattern_line_count]) - 1
- if end_pos >= len(content):
- end_pos = len(content)
+ start_pos, end_pos = _calculate_line_positions(
+ content_lines, i, i + pattern_line_count, len(content)
+ )
matches.append((start_pos, end_pos))
return matches
@@ -309,9 +308,10 @@ def _strategy_block_anchor(content: str, pattern: str) -> List[Tuple[int, int]]:
if similarity >= threshold:
# Calculate positions using ORIGINAL lines to ensure correct character offsets in the file
- start_pos = sum(len(line) + 1 for line in orig_content_lines[:i])
- end_pos = sum(len(line) + 1 for line in orig_content_lines[:i + pattern_line_count]) - 1
- matches.append((start_pos, min(end_pos, len(content))))
+ start_pos, end_pos = _calculate_line_positions(
+ orig_content_lines, i, i + pattern_line_count, len(content)
+ )
+ matches.append((start_pos, end_pos))
return matches
@@ -343,10 +343,9 @@ def _strategy_context_aware(content: str, pattern: str) -> List[Tuple[int, int]]
# Need at least 50% of lines to have high similarity
if high_similarity_count >= len(pattern_lines) * 0.5:
- start_pos = sum(len(line) + 1 for line in content_lines[:i])
- end_pos = sum(len(line) + 1 for line in content_lines[:i + pattern_line_count]) - 1
- if end_pos >= len(content):
- end_pos = len(content)
+ start_pos, end_pos = _calculate_line_positions(
+ content_lines, i, i + pattern_line_count, len(content)
+ )
matches.append((start_pos, end_pos))
return matches
@@ -356,6 +355,26 @@ def _strategy_context_aware(content: str, pattern: str) -> List[Tuple[int, int]]
# Helper Functions
# =============================================================================
+def _calculate_line_positions(content_lines: List[str], start_line: int,
+ end_line: int, content_length: int) -> Tuple[int, int]:
+ """Calculate start and end character positions from line indices.
+
+ Args:
+ content_lines: List of lines (without newlines)
+ start_line: Starting line index (0-based)
+ end_line: Ending line index (exclusive, 0-based)
+ content_length: Total length of the original content string
+
+ Returns:
+ Tuple of (start_pos, end_pos) in the original content
+ """
+ start_pos = sum(len(line) + 1 for line in content_lines[:start_line])
+ end_pos = sum(len(line) + 1 for line in content_lines[:end_line]) - 1
+ if end_pos >= content_length:
+ end_pos = content_length
+ return start_pos, end_pos
+
+
def _find_normalized_matches(content: str, content_lines: List[str],
content_normalized_lines: List[str],
pattern: str, pattern_normalized: str) -> List[Tuple[int, int]]:
@@ -383,13 +402,9 @@ def _find_normalized_matches(content: str, content_lines: List[str],
if block == pattern_normalized:
# Found a match - calculate original positions
- start_pos = sum(len(line) + 1 for line in content_lines[:i])
- end_pos = sum(len(line) + 1 for line in content_lines[:i + num_pattern_lines]) - 1
-
- # Handle case where end is past content
- if end_pos >= len(content):
- end_pos = len(content)
-
+ start_pos, end_pos = _calculate_line_positions(
+ content_lines, i, i + num_pattern_lines, len(content)
+ )
matches.append((start_pos, end_pos))
return matches
diff --git a/tools/mcp_tool.py b/tools/mcp_tool.py
index 7294e8be5..7ff8103b2 100644
--- a/tools/mcp_tool.py
+++ b/tools/mcp_tool.py
@@ -1624,6 +1624,72 @@ def get_mcp_status() -> List[dict]:
return result
+def probe_mcp_server_tools() -> Dict[str, List[tuple]]:
+ """Temporarily connect to configured MCP servers and list their tools.
+
+ Designed for ``hermes tools`` interactive configuration — connects to each
+ enabled server, grabs tool names and descriptions, then disconnects.
+ Does NOT register tools in the Hermes registry.
+
+ Returns:
+ Dict mapping server name to list of (tool_name, description) tuples.
+ Servers that fail to connect are omitted from the result.
+ """
+ if not _MCP_AVAILABLE:
+ return {}
+
+ servers_config = _load_mcp_config()
+ if not servers_config:
+ return {}
+
+ enabled = {
+ k: v for k, v in servers_config.items()
+ if _parse_boolish(v.get("enabled", True), default=True)
+ }
+ if not enabled:
+ return {}
+
+ _ensure_mcp_loop()
+
+ result: Dict[str, List[tuple]] = {}
+ probed_servers: List[MCPServerTask] = []
+
+ async def _probe_all():
+ names = list(enabled.keys())
+ coros = []
+ for name, cfg in enabled.items():
+ ct = cfg.get("connect_timeout", _DEFAULT_CONNECT_TIMEOUT)
+ coros.append(asyncio.wait_for(_connect_server(name, cfg), timeout=ct))
+
+ outcomes = await asyncio.gather(*coros, return_exceptions=True)
+
+ for name, outcome in zip(names, outcomes):
+ if isinstance(outcome, Exception):
+ logger.debug("Probe: failed to connect to '%s': %s", name, outcome)
+ continue
+ probed_servers.append(outcome)
+ tools = []
+ for t in outcome._tools:
+ desc = getattr(t, "description", "") or ""
+ tools.append((t.name, desc))
+ result[name] = tools
+
+ # Shut down all probed connections
+ await asyncio.gather(
+ *(s.shutdown() for s in probed_servers),
+ return_exceptions=True,
+ )
+
+ try:
+ _run_on_mcp_loop(_probe_all(), timeout=120)
+ except Exception as exc:
+ logger.debug("MCP probe failed: %s", exc)
+ finally:
+ _stop_mcp_loop()
+
+ return result
+
+
def shutdown_mcp_servers():
"""Close all MCP server connections and stop the background loop.
diff --git a/tools/memory_tool.py b/tools/memory_tool.py
index d7950d38c..241c17f8f 100644
--- a/tools/memory_tool.py
+++ b/tools/memory_tool.py
@@ -23,11 +23,13 @@ Design:
- Frozen snapshot pattern: system prompt is stable, tool responses show live state
"""
+import fcntl
import json
import logging
import os
import re
import tempfile
+from contextlib import contextmanager
from pathlib import Path
from typing import Dict, Any, List, Optional
@@ -120,14 +122,43 @@ class MemoryStore:
"user": self._render_block("user", self.user_entries),
}
+ @staticmethod
+ @contextmanager
+ def _file_lock(path: Path):
+ """Acquire an exclusive file lock for read-modify-write safety.
+
+ Uses a separate .lock file so the memory file itself can still be
+ atomically replaced via os.replace().
+ """
+ lock_path = path.with_suffix(path.suffix + ".lock")
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
+ fd = open(lock_path, "w")
+ try:
+ fcntl.flock(fd, fcntl.LOCK_EX)
+ yield
+ finally:
+ fcntl.flock(fd, fcntl.LOCK_UN)
+ fd.close()
+
+ @staticmethod
+ def _path_for(target: str) -> Path:
+ if target == "user":
+ return MEMORY_DIR / "USER.md"
+ return MEMORY_DIR / "MEMORY.md"
+
+ def _reload_target(self, target: str):
+ """Re-read entries from disk into in-memory state.
+
+ Called under file lock to get the latest state before mutating.
+ """
+ fresh = self._read_file(self._path_for(target))
+ fresh = list(dict.fromkeys(fresh)) # deduplicate
+ self._set_entries(target, fresh)
+
def save_to_disk(self, target: str):
"""Persist entries to the appropriate file. Called after every mutation."""
MEMORY_DIR.mkdir(parents=True, exist_ok=True)
-
- if target == "memory":
- self._write_file(MEMORY_DIR / "MEMORY.md", self.memory_entries)
- elif target == "user":
- self._write_file(MEMORY_DIR / "USER.md", self.user_entries)
+ self._write_file(self._path_for(target), self._entries_for(target))
def _entries_for(self, target: str) -> List[str]:
if target == "user":
@@ -162,33 +193,37 @@ class MemoryStore:
if scan_error:
return {"success": False, "error": scan_error}
- entries = self._entries_for(target)
- limit = self._char_limit(target)
+ with self._file_lock(self._path_for(target)):
+ # Re-read from disk under lock to pick up writes from other sessions
+ self._reload_target(target)
- # Reject exact duplicates
- if content in entries:
- return self._success_response(target, "Entry already exists (no duplicate added).")
+ entries = self._entries_for(target)
+ limit = self._char_limit(target)
- # Calculate what the new total would be
- new_entries = entries + [content]
- new_total = len(ENTRY_DELIMITER.join(new_entries))
+ # Reject exact duplicates
+ if content in entries:
+ return self._success_response(target, "Entry already exists (no duplicate added).")
- if new_total > limit:
- current = self._char_count(target)
- return {
- "success": False,
- "error": (
- f"Memory at {current:,}/{limit:,} chars. "
- f"Adding this entry ({len(content)} chars) would exceed the limit. "
- f"Replace or remove existing entries first."
- ),
- "current_entries": entries,
- "usage": f"{current:,}/{limit:,}",
- }
+ # Calculate what the new total would be
+ new_entries = entries + [content]
+ new_total = len(ENTRY_DELIMITER.join(new_entries))
- entries.append(content)
- self._set_entries(target, entries)
- self.save_to_disk(target)
+ if new_total > limit:
+ current = self._char_count(target)
+ return {
+ "success": False,
+ "error": (
+ f"Memory at {current:,}/{limit:,} chars. "
+ f"Adding this entry ({len(content)} chars) would exceed the limit. "
+ f"Replace or remove existing entries first."
+ ),
+ "current_entries": entries,
+ "usage": f"{current:,}/{limit:,}",
+ }
+
+ entries.append(content)
+ self._set_entries(target, entries)
+ self.save_to_disk(target)
return self._success_response(target, "Entry added.")
@@ -206,44 +241,47 @@ class MemoryStore:
if scan_error:
return {"success": False, "error": scan_error}
- entries = self._entries_for(target)
- matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
+ with self._file_lock(self._path_for(target)):
+ self._reload_target(target)
- if len(matches) == 0:
- return {"success": False, "error": f"No entry matched '{old_text}'."}
+ entries = self._entries_for(target)
+ matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
- if len(matches) > 1:
- # If all matches are identical (exact duplicates), operate on the first one
- unique_texts = set(e for _, e in matches)
- if len(unique_texts) > 1:
- previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
+ if len(matches) == 0:
+ return {"success": False, "error": f"No entry matched '{old_text}'."}
+
+ if len(matches) > 1:
+ # If all matches are identical (exact duplicates), operate on the first one
+ unique_texts = set(e for _, e in matches)
+ if len(unique_texts) > 1:
+ previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
+ return {
+ "success": False,
+ "error": f"Multiple entries matched '{old_text}'. Be more specific.",
+ "matches": previews,
+ }
+ # All identical -- safe to replace just the first
+
+ idx = matches[0][0]
+ limit = self._char_limit(target)
+
+ # Check that replacement doesn't blow the budget
+ test_entries = entries.copy()
+ test_entries[idx] = new_content
+ new_total = len(ENTRY_DELIMITER.join(test_entries))
+
+ if new_total > limit:
return {
"success": False,
- "error": f"Multiple entries matched '{old_text}'. Be more specific.",
- "matches": previews,
+ "error": (
+ f"Replacement would put memory at {new_total:,}/{limit:,} chars. "
+ f"Shorten the new content or remove other entries first."
+ ),
}
- # All identical -- safe to replace just the first
- idx = matches[0][0]
- limit = self._char_limit(target)
-
- # Check that replacement doesn't blow the budget
- test_entries = entries.copy()
- test_entries[idx] = new_content
- new_total = len(ENTRY_DELIMITER.join(test_entries))
-
- if new_total > limit:
- return {
- "success": False,
- "error": (
- f"Replacement would put memory at {new_total:,}/{limit:,} chars. "
- f"Shorten the new content or remove other entries first."
- ),
- }
-
- entries[idx] = new_content
- self._set_entries(target, entries)
- self.save_to_disk(target)
+ entries[idx] = new_content
+ self._set_entries(target, entries)
+ self.save_to_disk(target)
return self._success_response(target, "Entry replaced.")
@@ -253,28 +291,31 @@ class MemoryStore:
if not old_text:
return {"success": False, "error": "old_text cannot be empty."}
- entries = self._entries_for(target)
- matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
+ with self._file_lock(self._path_for(target)):
+ self._reload_target(target)
- if len(matches) == 0:
- return {"success": False, "error": f"No entry matched '{old_text}'."}
+ entries = self._entries_for(target)
+ matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
- if len(matches) > 1:
- # If all matches are identical (exact duplicates), remove the first one
- unique_texts = set(e for _, e in matches)
- if len(unique_texts) > 1:
- previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
- return {
- "success": False,
- "error": f"Multiple entries matched '{old_text}'. Be more specific.",
- "matches": previews,
- }
- # All identical -- safe to remove just the first
+ if len(matches) == 0:
+ return {"success": False, "error": f"No entry matched '{old_text}'."}
- idx = matches[0][0]
- entries.pop(idx)
- self._set_entries(target, entries)
- self.save_to_disk(target)
+ if len(matches) > 1:
+ # If all matches are identical (exact duplicates), remove the first one
+ unique_texts = set(e for _, e in matches)
+ if len(unique_texts) > 1:
+ previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
+ return {
+ "success": False,
+ "error": f"Multiple entries matched '{old_text}'. Be more specific.",
+ "matches": previews,
+ }
+ # All identical -- safe to remove just the first
+
+ idx = matches[0][0]
+ entries.pop(idx)
+ self._set_entries(target, entries)
+ self.save_to_disk(target)
return self._success_response(target, "Entry removed.")
diff --git a/tools/process_registry.py b/tools/process_registry.py
index ceb45ab27..c6ee9ceb6 100644
--- a/tools/process_registry.py
+++ b/tools/process_registry.py
@@ -78,6 +78,11 @@ class ProcessSession:
output_buffer: str = "" # Rolling output (last MAX_OUTPUT_CHARS)
max_output_chars: int = MAX_OUTPUT_CHARS
detached: bool = False # True if recovered from crash (no pipe)
+ # Watcher/notification metadata (persisted for crash recovery)
+ watcher_platform: str = ""
+ watcher_chat_id: str = ""
+ watcher_thread_id: str = ""
+ watcher_interval: int = 0 # 0 = no watcher configured
_lock: threading.Lock = field(default_factory=threading.Lock)
_reader_thread: Optional[threading.Thread] = field(default=None, repr=False)
_pty: Any = field(default=None, repr=False) # ptyprocess handle (when use_pty=True)
@@ -709,6 +714,10 @@ class ProcessRegistry:
"started_at": s.started_at,
"task_id": s.task_id,
"session_key": s.session_key,
+ "watcher_platform": s.watcher_platform,
+ "watcher_chat_id": s.watcher_chat_id,
+ "watcher_thread_id": s.watcher_thread_id,
+ "watcher_interval": s.watcher_interval,
})
# Atomic write to avoid corruption on crash
@@ -755,12 +764,27 @@ class ProcessRegistry:
cwd=entry.get("cwd"),
started_at=entry.get("started_at", time.time()),
detached=True, # Can't read output, but can report status + kill
+ watcher_platform=entry.get("watcher_platform", ""),
+ watcher_chat_id=entry.get("watcher_chat_id", ""),
+ watcher_thread_id=entry.get("watcher_thread_id", ""),
+ watcher_interval=entry.get("watcher_interval", 0),
)
with self._lock:
self._running[session.id] = session
recovered += 1
logger.info("Recovered detached process: %s (pid=%d)", session.command[:60], pid)
+ # Re-enqueue watcher so gateway can resume notifications
+ if session.watcher_interval > 0:
+ self.pending_watchers.append({
+ "session_id": session.id,
+ "check_interval": session.watcher_interval,
+ "session_key": session.session_key,
+ "platform": session.watcher_platform,
+ "chat_id": session.watcher_chat_id,
+ "thread_id": session.watcher_thread_id,
+ })
+
# Clear the checkpoint (will be rewritten as processes finish)
try:
from utils import atomic_json_write
diff --git a/tools/send_message_tool.py b/tools/send_message_tool.py
index 2f0f014ab..4b0c4815f 100644
--- a/tools/send_message_tool.py
+++ b/tools/send_message_tool.py
@@ -355,20 +355,31 @@ async def _send_telegram(token, chat_id, message, media_files=None, thread_id=No
"""Send via Telegram Bot API (one-shot, no polling needed).
Applies markdown→MarkdownV2 formatting (same as the gateway adapter)
- so that bold, links, and headers render correctly.
+ so that bold, links, and headers render correctly. If the message
+ already contains HTML tags, it is sent with ``parse_mode='HTML'``
+ instead, bypassing MarkdownV2 conversion.
"""
try:
from telegram import Bot
from telegram.constants import ParseMode
- # Reuse the gateway adapter's format_message for markdown→MarkdownV2
- try:
- from gateway.platforms.telegram import TelegramAdapter, _escape_mdv2, _strip_mdv2
- _adapter = TelegramAdapter.__new__(TelegramAdapter)
- formatted = _adapter.format_message(message)
- except Exception:
- # Fallback: send as-is if formatting unavailable
+ # Auto-detect HTML tags — if present, skip MarkdownV2 and send as HTML.
+ # Inspired by github.com/ashaney — PR #1568.
+ _has_html = bool(re.search(r'<[a-zA-Z/][^>]*>', message))
+
+ if _has_html:
formatted = message
+ send_parse_mode = ParseMode.HTML
+ else:
+ # Reuse the gateway adapter's format_message for markdown→MarkdownV2
+ try:
+ from gateway.platforms.telegram import TelegramAdapter, _escape_mdv2, _strip_mdv2
+ _adapter = TelegramAdapter.__new__(TelegramAdapter)
+ formatted = _adapter.format_message(message)
+ except Exception:
+ # Fallback: send as-is if formatting unavailable
+ formatted = message
+ send_parse_mode = ParseMode.MARKDOWN_V2
bot = Bot(token=token)
int_chat_id = int(chat_id)
@@ -384,16 +395,19 @@ async def _send_telegram(token, chat_id, message, media_files=None, thread_id=No
try:
last_msg = await bot.send_message(
chat_id=int_chat_id, text=formatted,
- parse_mode=ParseMode.MARKDOWN_V2, **thread_kwargs
+ parse_mode=send_parse_mode, **thread_kwargs
)
except Exception as md_error:
- # MarkdownV2 failed, fall back to plain text
- if "parse" in str(md_error).lower() or "markdown" in str(md_error).lower():
- logger.warning("MarkdownV2 parse failed in _send_telegram, falling back to plain text: %s", md_error)
- try:
- from gateway.platforms.telegram import _strip_mdv2
- plain = _strip_mdv2(formatted)
- except Exception:
+ # Parse failed, fall back to plain text
+ if "parse" in str(md_error).lower() or "markdown" in str(md_error).lower() or "html" in str(md_error).lower():
+ logger.warning("Parse mode %s failed in _send_telegram, falling back to plain text: %s", send_parse_mode, md_error)
+ if not _has_html:
+ try:
+ from gateway.platforms.telegram import _strip_mdv2
+ plain = _strip_mdv2(formatted)
+ except Exception:
+ plain = message
+ else:
plain = message
last_msg = await bot.send_message(
chat_id=int_chat_id, text=plain,
@@ -565,50 +579,55 @@ async def _send_email(extra, chat_id, message):
return {"error": f"Email send failed: {e}"}
-async def _send_sms(api_key, chat_id, message):
- """Send via Telnyx SMS REST API (one-shot, no persistent connection needed)."""
+async def _send_sms(auth_token, chat_id, message):
+ """Send a single SMS via Twilio REST API.
+
+ Uses HTTP Basic auth (Account SID : Auth Token) and form-encoded POST.
+ Chunking is handled by _send_to_platform() before this is called.
+ """
try:
import aiohttp
except ImportError:
return {"error": "aiohttp not installed. Run: pip install aiohttp"}
+
+ import base64
+
+ account_sid = os.getenv("TWILIO_ACCOUNT_SID", "")
+ from_number = os.getenv("TWILIO_PHONE_NUMBER", "")
+ if not account_sid or not auth_token or not from_number:
+ return {"error": "SMS not configured (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER required)"}
+
+ # Strip markdown — SMS renders it as literal characters
+ message = re.sub(r"\*\*(.+?)\*\*", r"\1", message, flags=re.DOTALL)
+ message = re.sub(r"\*(.+?)\*", r"\1", message, flags=re.DOTALL)
+ message = re.sub(r"__(.+?)__", r"\1", message, flags=re.DOTALL)
+ message = re.sub(r"_(.+?)_", r"\1", message, flags=re.DOTALL)
+ message = re.sub(r"```[a-z]*\n?", "", message)
+ message = re.sub(r"`(.+?)`", r"\1", message)
+ message = re.sub(r"^#{1,6}\s+", "", message, flags=re.MULTILINE)
+ message = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", message)
+ message = re.sub(r"\n{3,}", "\n\n", message)
+ message = message.strip()
+
try:
- from_number = os.getenv("TELNYX_FROM_NUMBERS", "").split(",")[0].strip()
- if not from_number:
- return {"error": "TELNYX_FROM_NUMBERS not configured"}
- if not api_key:
- api_key = os.getenv("TELNYX_API_KEY", "")
- if not api_key:
- return {"error": "TELNYX_API_KEY not configured"}
+ creds = f"{account_sid}:{auth_token}"
+ encoded = base64.b64encode(creds.encode("ascii")).decode("ascii")
+ url = f"https://api.twilio.com/2010-04-01/Accounts/{account_sid}/Messages.json"
+ headers = {"Authorization": f"Basic {encoded}"}
- # Strip markdown for SMS
- text = re.sub(r"\*\*(.+?)\*\*", r"\1", message, flags=re.DOTALL)
- text = re.sub(r"\*(.+?)\*", r"\1", text, flags=re.DOTALL)
- text = re.sub(r"```[a-z]*\n?", "", text)
- text = re.sub(r"`(.+?)`", r"\1", text)
- text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
- text = text.strip()
-
- # Chunk to 1600 chars
- chunks = [text[i:i+1600] for i in range(0, len(text), 1600)] if len(text) > 1600 else [text]
-
- headers = {
- "Authorization": f"Bearer {api_key}",
- "Content-Type": "application/json",
- }
- message_ids = []
async with aiohttp.ClientSession() as session:
- for chunk in chunks:
- payload = {"from": from_number, "to": chat_id, "text": chunk}
- async with session.post(
- "https://api.telnyx.com/v2/messages",
- json=payload,
- headers=headers,
- ) as resp:
- body = await resp.json()
- if resp.status >= 400:
- return {"error": f"Telnyx API error ({resp.status}): {body}"}
- message_ids.append(body.get("data", {}).get("id", ""))
- return {"success": True, "platform": "sms", "chat_id": chat_id, "message_ids": message_ids}
+ form_data = aiohttp.FormData()
+ form_data.add_field("From", from_number)
+ form_data.add_field("To", chat_id)
+ form_data.add_field("Body", message)
+
+ async with session.post(url, data=form_data, headers=headers) as resp:
+ body = await resp.json()
+ if resp.status >= 400:
+ error_msg = body.get("message", str(body))
+ return {"error": f"Twilio API error ({resp.status}): {error_msg}"}
+ msg_sid = body.get("sid", "")
+ return {"success": True, "platform": "sms", "chat_id": chat_id, "message_id": msg_sid}
except Exception as e:
return {"error": f"SMS send failed: {e}"}
diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py
index 3cc541b58..424bf6514 100644
--- a/tools/terminal_tool.py
+++ b/tools/terminal_tool.py
@@ -1082,13 +1082,23 @@ def terminal_tool(
result_data["check_interval_note"] = (
f"Requested {check_interval}s raised to minimum 30s"
)
+ watcher_platform = os.getenv("HERMES_SESSION_PLATFORM", "")
+ watcher_chat_id = os.getenv("HERMES_SESSION_CHAT_ID", "")
+ watcher_thread_id = os.getenv("HERMES_SESSION_THREAD_ID", "")
+
+ # Store on session for checkpoint persistence
+ proc_session.watcher_platform = watcher_platform
+ proc_session.watcher_chat_id = watcher_chat_id
+ proc_session.watcher_thread_id = watcher_thread_id
+ proc_session.watcher_interval = effective_interval
+
process_registry.pending_watchers.append({
"session_id": proc_session.id,
"check_interval": effective_interval,
"session_key": session_key,
- "platform": os.getenv("HERMES_SESSION_PLATFORM", ""),
- "chat_id": os.getenv("HERMES_SESSION_CHAT_ID", ""),
- "thread_id": os.getenv("HERMES_SESSION_THREAD_ID", ""),
+ "platform": watcher_platform,
+ "chat_id": watcher_chat_id,
+ "thread_id": watcher_thread_id,
})
return json.dumps(result_data, ensure_ascii=False)
diff --git a/tools/web_tools.py b/tools/web_tools.py
index ede1adb03..79444d72b 100644
--- a/tools/web_tools.py
+++ b/tools/web_tools.py
@@ -3,16 +3,16 @@
Standalone Web Tools Module
This module provides generic web tools that work with multiple backend providers.
-Currently uses Firecrawl as the backend, and the interface makes it easy to swap
-providers without changing the function signatures.
+Backend is selected during ``hermes tools`` setup (web.backend in config.yaml).
Available tools:
- web_search_tool: Search the web for information
- web_extract_tool: Extract content from specific web pages
-- web_crawl_tool: Crawl websites with specific instructions
+- web_crawl_tool: Crawl websites with specific instructions (Firecrawl only)
Backend compatibility:
-- Firecrawl: https://docs.firecrawl.dev/introduction
+- Firecrawl: https://docs.firecrawl.dev/introduction (search, extract, crawl)
+- Parallel: https://docs.parallel.ai (search, extract)
LLM Processing:
- Uses OpenRouter API with Gemini 3 Flash Preview for intelligent content extraction
@@ -46,12 +46,50 @@ import os
import re
import asyncio
from typing import List, Dict, Any, Optional
+import httpx
from firecrawl import Firecrawl
from agent.auxiliary_client import async_call_llm
from tools.debug_helpers import DebugSession
+from tools.website_policy import check_website_access
logger = logging.getLogger(__name__)
+
+# ─── Backend Selection ────────────────────────────────────────────────────────
+
+def _load_web_config() -> dict:
+ """Load the ``web:`` section from ~/.hermes/config.yaml."""
+ try:
+ from hermes_cli.config import load_config
+ return load_config().get("web", {})
+ except (ImportError, Exception):
+ return {}
+
+
+def _get_backend() -> str:
+ """Determine which web backend to use.
+
+ Reads ``web.backend`` from config.yaml (set by ``hermes tools``).
+ Falls back to whichever API key is present for users who configured
+ keys manually without running setup.
+ """
+ configured = _load_web_config().get("backend", "").lower().strip()
+ if configured in ("parallel", "firecrawl", "tavily"):
+ return configured
+ # Fallback for manual / legacy config — use whichever key is present.
+ has_firecrawl = bool(os.getenv("FIRECRAWL_API_KEY") or os.getenv("FIRECRAWL_API_URL"))
+ has_parallel = bool(os.getenv("PARALLEL_API_KEY"))
+ has_tavily = bool(os.getenv("TAVILY_API_KEY"))
+ if has_tavily and not has_firecrawl and not has_parallel:
+ return "tavily"
+ if has_parallel and not has_firecrawl:
+ return "parallel"
+ # Default to firecrawl (backward compat, or when both are set)
+ return "firecrawl"
+
+
+# ─── Firecrawl Client ────────────────────────────────────────────────────────
+
_firecrawl_client = None
def _get_firecrawl_client():
@@ -80,6 +118,129 @@ def _get_firecrawl_client():
_firecrawl_client = Firecrawl(**kwargs)
return _firecrawl_client
+
+# ─── Parallel Client ─────────────────────────────────────────────────────────
+
+_parallel_client = None
+_async_parallel_client = None
+
+def _get_parallel_client():
+ """Get or create the Parallel sync client (lazy initialization).
+
+ Requires PARALLEL_API_KEY environment variable.
+ """
+ from parallel import Parallel
+ global _parallel_client
+ if _parallel_client is None:
+ api_key = os.getenv("PARALLEL_API_KEY")
+ if not api_key:
+ raise ValueError(
+ "PARALLEL_API_KEY environment variable not set. "
+ "Get your API key at https://parallel.ai"
+ )
+ _parallel_client = Parallel(api_key=api_key)
+ return _parallel_client
+
+
+def _get_async_parallel_client():
+ """Get or create the Parallel async client (lazy initialization).
+
+ Requires PARALLEL_API_KEY environment variable.
+ """
+ from parallel import AsyncParallel
+ global _async_parallel_client
+ if _async_parallel_client is None:
+ api_key = os.getenv("PARALLEL_API_KEY")
+ if not api_key:
+ raise ValueError(
+ "PARALLEL_API_KEY environment variable not set. "
+ "Get your API key at https://parallel.ai"
+ )
+ _async_parallel_client = AsyncParallel(api_key=api_key)
+ return _async_parallel_client
+
+# ─── Tavily Client ───────────────────────────────────────────────────────────
+
+_TAVILY_BASE_URL = "https://api.tavily.com"
+
+
+def _tavily_request(endpoint: str, payload: dict) -> dict:
+ """Send a POST request to the Tavily API.
+
+ Auth is provided via ``api_key`` in the JSON body (no header-based auth).
+ Raises ``ValueError`` if ``TAVILY_API_KEY`` is not set.
+ """
+ api_key = os.getenv("TAVILY_API_KEY")
+ if not api_key:
+ raise ValueError(
+ "TAVILY_API_KEY environment variable not set. "
+ "Get your API key at https://app.tavily.com/home"
+ )
+ payload["api_key"] = api_key
+ url = f"{_TAVILY_BASE_URL}/{endpoint.lstrip('/')}"
+ logger.info("Tavily %s request to %s", endpoint, url)
+ response = httpx.post(url, json=payload, timeout=60)
+ response.raise_for_status()
+ return response.json()
+
+
+def _normalize_tavily_search_results(response: dict) -> dict:
+ """Normalize Tavily /search response to the standard web search format.
+
+ Tavily returns ``{results: [{title, url, content, score, ...}]}``.
+ We map to ``{success, data: {web: [{title, url, description, position}]}}``.
+ """
+ web_results = []
+ for i, result in enumerate(response.get("results", [])):
+ web_results.append({
+ "title": result.get("title", ""),
+ "url": result.get("url", ""),
+ "description": result.get("content", ""),
+ "position": i + 1,
+ })
+ return {"success": True, "data": {"web": web_results}}
+
+
+def _normalize_tavily_documents(response: dict, fallback_url: str = "") -> List[Dict[str, Any]]:
+ """Normalize Tavily /extract or /crawl response to the standard document format.
+
+ Maps results to ``{url, title, content, raw_content, metadata}`` and
+ includes any ``failed_results`` / ``failed_urls`` as error entries.
+ """
+ documents: List[Dict[str, Any]] = []
+ for result in response.get("results", []):
+ url = result.get("url", fallback_url)
+ raw = result.get("raw_content", "") or result.get("content", "")
+ documents.append({
+ "url": url,
+ "title": result.get("title", ""),
+ "content": raw,
+ "raw_content": raw,
+ "metadata": {"sourceURL": url, "title": result.get("title", "")},
+ })
+ # Handle failed results
+ for fail in response.get("failed_results", []):
+ documents.append({
+ "url": fail.get("url", fallback_url),
+ "title": "",
+ "content": "",
+ "raw_content": "",
+ "error": fail.get("error", "extraction failed"),
+ "metadata": {"sourceURL": fail.get("url", fallback_url)},
+ })
+ for fail_url in response.get("failed_urls", []):
+ url_str = fail_url if isinstance(fail_url, str) else str(fail_url)
+ documents.append({
+ "url": url_str,
+ "title": "",
+ "content": "",
+ "raw_content": "",
+ "error": "extraction failed",
+ "metadata": {"sourceURL": url_str},
+ })
+ return documents
+
+
DEFAULT_MIN_LENGTH_FOR_SUMMARIZATION = 5000
# Allow per-task override via env var
@@ -427,13 +588,89 @@ def clean_base64_images(text: str) -> str:
return cleaned_text
+# ─── Parallel Search & Extract Helpers ────────────────────────────────────────
+
+def _parallel_search(query: str, limit: int = 5) -> dict:
+ """Search using the Parallel SDK and return results as a dict."""
+ from tools.interrupt import is_interrupted
+ if is_interrupted():
+ return {"error": "Interrupted", "success": False}
+
+ mode = os.getenv("PARALLEL_SEARCH_MODE", "agentic").lower().strip()
+ if mode not in ("fast", "one-shot", "agentic"):
+ mode = "agentic"
+
+ logger.info("Parallel search: '%s' (mode=%s, limit=%d)", query, mode, limit)
+ response = _get_parallel_client().beta.search(
+ search_queries=[query],
+ objective=query,
+ mode=mode,
+ max_results=min(limit, 20),
+ )
+
+ web_results = []
+ for i, result in enumerate(response.results or []):
+ excerpts = result.excerpts or []
+ web_results.append({
+ "url": result.url or "",
+ "title": result.title or "",
+ "description": " ".join(excerpts) if excerpts else "",
+ "position": i + 1,
+ })
+
+ return {"success": True, "data": {"web": web_results}}
+
+
+async def _parallel_extract(urls: List[str]) -> List[Dict[str, Any]]:
+ """Extract content from URLs using the Parallel async SDK.
+
+ Returns a list of result dicts matching the structure expected by the
+ LLM post-processing pipeline (url, title, content, metadata).
+ """
+ from tools.interrupt import is_interrupted
+ if is_interrupted():
+ return [{"url": u, "error": "Interrupted", "title": ""} for u in urls]
+
+ logger.info("Parallel extract: %d URL(s)", len(urls))
+ response = await _get_async_parallel_client().beta.extract(
+ urls=urls,
+ full_content=True,
+ )
+
+ results = []
+ for result in response.results or []:
+ content = result.full_content or ""
+ if not content:
+ content = "\n\n".join(result.excerpts or [])
+ url = result.url or ""
+ title = result.title or ""
+ results.append({
+ "url": url,
+ "title": title,
+ "content": content,
+ "raw_content": content,
+ "metadata": {"sourceURL": url, "title": title},
+ })
+
+ for error in response.errors or []:
+ results.append({
+ "url": error.url or "",
+ "title": "",
+ "content": "",
+ "error": error.content or error.error_type or "extraction failed",
+ "metadata": {"sourceURL": error.url or ""},
+ })
+
+ return results
+
+
def web_search_tool(query: str, limit: int = 5) -> str:
"""
Search the web for information using available search API backend.
-
+
This function provides a generic interface for web search that can work
- with multiple backends. Currently uses Firecrawl.
-
+ with multiple backends (Parallel or Firecrawl).
+
Note: This function returns search result metadata only (URLs, titles, descriptions).
Use web_extract_tool to get full content from specific URLs.
@@ -477,17 +714,44 @@ def web_search_tool(query: str, limit: int = 5) -> str:
if is_interrupted():
return json.dumps({"error": "Interrupted", "success": False})
+ # Dispatch to the configured backend
+ backend = _get_backend()
+ if backend == "parallel":
+ response_data = _parallel_search(query, limit)
+ debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", []))
+ result_json = json.dumps(response_data, indent=2, ensure_ascii=False)
+ debug_call_data["final_response_size"] = len(result_json)
+ _debug.log_call("web_search_tool", debug_call_data)
+ _debug.save()
+ return result_json
+
+ if backend == "tavily":
+ logger.info("Tavily search: '%s' (limit: %d)", query, limit)
+ raw = _tavily_request("search", {
+ "query": query,
+ "max_results": min(limit, 20),
+ "include_raw_content": False,
+ "include_images": False,
+ })
+ response_data = _normalize_tavily_search_results(raw)
+ debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", []))
+ result_json = json.dumps(response_data, indent=2, ensure_ascii=False)
+ debug_call_data["final_response_size"] = len(result_json)
+ _debug.log_call("web_search_tool", debug_call_data)
+ _debug.save()
+ return result_json
+
logger.info("Searching the web for: '%s' (limit: %d)", query, limit)
-
+
response = _get_firecrawl_client().search(
query=query,
limit=limit
)
-
+
# The response is a SearchData object with web, news, and images attributes
# When not scraping, the results are directly in these attributes
web_results = []
-
+
# Check if response has web attribute (SearchData object)
if hasattr(response, 'web'):
# Response is a SearchData object with web attribute
@@ -595,100 +859,137 @@ async def web_extract_tool(
try:
logger.info("Extracting content from %d URL(s)", len(urls))
-
- # Determine requested formats for Firecrawl v2
- formats: List[str] = []
- if format == "markdown":
- formats = ["markdown"]
- elif format == "html":
- formats = ["html"]
- else:
- # Default: request markdown for LLM-readiness and include html as backup
- formats = ["markdown", "html"]
-
- # Always use individual scraping for simplicity and reliability
- # Batch scraping adds complexity without much benefit for small numbers of URLs
- results: List[Dict[str, Any]] = []
-
- from tools.interrupt import is_interrupted as _is_interrupted
- for url in urls:
- if _is_interrupted():
- results.append({"url": url, "error": "Interrupted", "title": ""})
- continue
- try:
- logger.info("Scraping: %s", url)
- scrape_result = _get_firecrawl_client().scrape(
- url=url,
- formats=formats
- )
-
- # Process the result - properly handle object serialization
- metadata = {}
- title = ""
- content_markdown = None
- content_html = None
-
- # Extract data from the scrape result
- if hasattr(scrape_result, 'model_dump'):
- # Pydantic model - use model_dump to get dict
- result_dict = scrape_result.model_dump()
- content_markdown = result_dict.get('markdown')
- content_html = result_dict.get('html')
- metadata = result_dict.get('metadata', {})
- elif hasattr(scrape_result, '__dict__'):
- # Regular object with attributes
- content_markdown = getattr(scrape_result, 'markdown', None)
- content_html = getattr(scrape_result, 'html', None)
-
- # Handle metadata - convert to dict if it's an object
- metadata_obj = getattr(scrape_result, 'metadata', {})
- if hasattr(metadata_obj, 'model_dump'):
- metadata = metadata_obj.model_dump()
- elif hasattr(metadata_obj, '__dict__'):
- metadata = metadata_obj.__dict__
- elif isinstance(metadata_obj, dict):
- metadata = metadata_obj
- else:
- metadata = {}
- elif isinstance(scrape_result, dict):
- # Already a dictionary
- content_markdown = scrape_result.get('markdown')
- content_html = scrape_result.get('html')
- metadata = scrape_result.get('metadata', {})
-
- # Ensure metadata is a dict (not an object)
- if not isinstance(metadata, dict):
- if hasattr(metadata, 'model_dump'):
- metadata = metadata.model_dump()
- elif hasattr(metadata, '__dict__'):
- metadata = metadata.__dict__
- else:
- metadata = {}
-
- # Get title from metadata
- title = metadata.get("title", "")
-
- # Choose content based on requested format
- chosen_content = content_markdown if (format == "markdown" or (format is None and content_markdown)) else content_html or content_markdown or ""
-
- results.append({
- "url": metadata.get("sourceURL", url),
- "title": title,
- "content": chosen_content,
- "raw_content": chosen_content,
- "metadata": metadata # Now guaranteed to be a dict
- })
-
- except Exception as scrape_err:
- logger.debug("Scrape failed for %s: %s", url, scrape_err)
- results.append({
- "url": url,
- "title": "",
- "content": "",
- "raw_content": "",
- "error": str(scrape_err)
- })
+ # Dispatch to the configured backend
+ backend = _get_backend()
+
+ if backend == "parallel":
+ results = await _parallel_extract(urls)
+ elif backend == "tavily":
+ logger.info("Tavily extract: %d URL(s)", len(urls))
+ raw = _tavily_request("extract", {
+ "urls": urls,
+ "include_images": False,
+ })
+ results = _normalize_tavily_documents(raw, fallback_url=urls[0] if urls else "")
+ else:
+ # ── Firecrawl extraction ──
+ # Determine requested formats for Firecrawl v2
+ formats: List[str] = []
+ if format == "markdown":
+ formats = ["markdown"]
+ elif format == "html":
+ formats = ["html"]
+ else:
+ # Default: request markdown for LLM-readiness and include html as backup
+ formats = ["markdown", "html"]
+
+ # Always use individual scraping for simplicity and reliability
+ # Batch scraping adds complexity without much benefit for small numbers of URLs
+ results: List[Dict[str, Any]] = []
+
+ from tools.interrupt import is_interrupted as _is_interrupted
+ for url in urls:
+ if _is_interrupted():
+ results.append({"url": url, "error": "Interrupted", "title": ""})
+ continue
+
+ # Website policy check — block before fetching
+ blocked = check_website_access(url)
+ if blocked:
+ logger.info("Blocked web_extract for %s by rule %s", blocked["host"], blocked["rule"])
+ results.append({
+ "url": url, "title": "", "content": "",
+ "error": blocked["message"],
+ "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]},
+ })
+ continue
+
+ try:
+ logger.info("Scraping: %s", url)
+ scrape_result = _get_firecrawl_client().scrape(
+ url=url,
+ formats=formats
+ )
+
+ # Process the result - properly handle object serialization
+ metadata = {}
+ title = ""
+ content_markdown = None
+ content_html = None
+
+ # Extract data from the scrape result
+ if hasattr(scrape_result, 'model_dump'):
+ # Pydantic model - use model_dump to get dict
+ result_dict = scrape_result.model_dump()
+ content_markdown = result_dict.get('markdown')
+ content_html = result_dict.get('html')
+ metadata = result_dict.get('metadata', {})
+ elif hasattr(scrape_result, '__dict__'):
+ # Regular object with attributes
+ content_markdown = getattr(scrape_result, 'markdown', None)
+ content_html = getattr(scrape_result, 'html', None)
+
+ # Handle metadata - convert to dict if it's an object
+ metadata_obj = getattr(scrape_result, 'metadata', {})
+ if hasattr(metadata_obj, 'model_dump'):
+ metadata = metadata_obj.model_dump()
+ elif hasattr(metadata_obj, '__dict__'):
+ metadata = metadata_obj.__dict__
+ elif isinstance(metadata_obj, dict):
+ metadata = metadata_obj
+ else:
+ metadata = {}
+ elif isinstance(scrape_result, dict):
+ # Already a dictionary
+ content_markdown = scrape_result.get('markdown')
+ content_html = scrape_result.get('html')
+ metadata = scrape_result.get('metadata', {})
+
+ # Ensure metadata is a dict (not an object)
+ if not isinstance(metadata, dict):
+ if hasattr(metadata, 'model_dump'):
+ metadata = metadata.model_dump()
+ elif hasattr(metadata, '__dict__'):
+ metadata = metadata.__dict__
+ else:
+ metadata = {}
+
+ # Get title from metadata
+ title = metadata.get("title", "")
+
+ # Re-check final URL after redirect
+ final_url = metadata.get("sourceURL", url)
+ final_blocked = check_website_access(final_url)
+ if final_blocked:
+ logger.info("Blocked redirected web_extract for %s by rule %s", final_blocked["host"], final_blocked["rule"])
+ results.append({
+ "url": final_url, "title": title, "content": "", "raw_content": "",
+ "error": final_blocked["message"],
+ "blocked_by_policy": {"host": final_blocked["host"], "rule": final_blocked["rule"], "source": final_blocked["source"]},
+ })
+ continue
+
+ # Choose content based on requested format
+ chosen_content = content_markdown if (format == "markdown" or (format is None and content_markdown)) else content_html or content_markdown or ""
+
+ results.append({
+ "url": final_url,
+ "title": title,
+ "content": chosen_content,
+ "raw_content": chosen_content,
+ "metadata": metadata # Now guaranteed to be a dict
+ })
+
+ except Exception as scrape_err:
+ logger.debug("Scrape failed for %s: %s", url, scrape_err)
+ results.append({
+ "url": url,
+ "title": "",
+ "content": "",
+ "raw_content": "",
+ "error": str(scrape_err)
+ })
response = {"results": results}
@@ -778,6 +1079,7 @@ async def web_extract_tool(
"title": r.get("title", ""),
"content": r.get("content", ""),
"error": r.get("error"),
+ **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {}),
}
for r in response.get("results", [])
]
@@ -862,6 +1164,91 @@ async def web_crawl_tool(
}
try:
+ backend = _get_backend()
+
+ # Tavily supports crawl via its /crawl endpoint
+ if backend == "tavily":
+ # Ensure URL has protocol
+ if not url.startswith(('http://', 'https://')):
+ url = f'https://{url}'
+
+ # Website policy check
+ blocked = check_website_access(url)
+ if blocked:
+ logger.info("Blocked web_crawl for %s by rule %s", blocked["host"], blocked["rule"])
+ return json.dumps({"results": [{"url": url, "title": "", "content": "", "error": blocked["message"],
+ "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}}]}, ensure_ascii=False)
+
+ from tools.interrupt import is_interrupted as _is_int
+ if _is_int():
+ return json.dumps({"error": "Interrupted", "success": False})
+
+ logger.info("Tavily crawl: %s", url)
+ payload: Dict[str, Any] = {
+ "url": url,
+ "limit": 20,
+ "extract_depth": depth,
+ }
+ if instructions:
+ payload["instructions"] = instructions
+ raw = _tavily_request("crawl", payload)
+ results = _normalize_tavily_documents(raw, fallback_url=url)
+
+ response = {"results": results}
+ # Fall through to the shared LLM processing and trimming below
+ # (skip the Firecrawl-specific crawl logic)
+ pages_crawled = len(response.get('results', []))
+ logger.info("Crawled %d pages", pages_crawled)
+ debug_call_data["pages_crawled"] = pages_crawled
+ debug_call_data["original_response_size"] = len(json.dumps(response))
+
+ # Process each result with LLM if enabled
+ if use_llm_processing:
+ logger.info("Processing crawled content with LLM (parallel)...")
+ debug_call_data["processing_applied"].append("llm_processing")
+
+ async def _process_tavily_crawl(result):
+ page_url = result.get('url', 'Unknown URL')
+ title = result.get('title', '')
+ content = result.get('content', '')
+ if not content:
+ return result, None, "no_content"
+ original_size = len(content)
+ processed = await process_content_with_llm(content, page_url, title, model, min_length)
+ if processed:
+ result['raw_content'] = content
+ result['content'] = processed
+ metrics = {"url": page_url, "original_size": original_size, "processed_size": len(processed),
+ "compression_ratio": len(processed) / original_size if original_size else 1.0, "model_used": model}
+ return result, metrics, "processed"
+ metrics = {"url": page_url, "original_size": original_size, "processed_size": original_size,
+ "compression_ratio": 1.0, "model_used": None, "reason": "content_too_short"}
+ return result, metrics, "too_short"
+
+ tasks = [_process_tavily_crawl(r) for r in response.get('results', [])]
+ processed_results = await asyncio.gather(*tasks)
+ for result, metrics, status in processed_results:
+ if status == "processed":
+ debug_call_data["compression_metrics"].append(metrics)
+ debug_call_data["pages_processed_with_llm"] += 1
+
+ trimmed_results = [{"url": r.get("url", ""), "title": r.get("title", ""), "content": r.get("content", ""), "error": r.get("error"),
+ **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {})} for r in response.get("results", [])]
+ result_json = json.dumps({"results": trimmed_results}, indent=2, ensure_ascii=False)
+ cleaned_result = clean_base64_images(result_json)
+ debug_call_data["final_response_size"] = len(cleaned_result)
+ _debug.log_call("web_crawl_tool", debug_call_data)
+ _debug.save()
+ return cleaned_result
+
+ # web_crawl requires Firecrawl — Parallel has no crawl API
+ if not (os.getenv("FIRECRAWL_API_KEY") or os.getenv("FIRECRAWL_API_URL")):
+ return json.dumps({
+ "error": "web_crawl requires Firecrawl. Set FIRECRAWL_API_KEY, "
+ "or use web_search + web_extract instead.",
+ "success": False,
+ }, ensure_ascii=False)
+
# Ensure URL has protocol
if not url.startswith(('http://', 'https://')):
url = f'https://{url}'
@@ -870,6 +1257,13 @@ async def web_crawl_tool(
instructions_text = f" with instructions: '{instructions}'" if instructions else ""
logger.info("Crawling %s%s", url, instructions_text)
+ # Website policy check — block before crawling
+ blocked = check_website_access(url)
+ if blocked:
+ logger.info("Blocked web_crawl for %s by rule %s", blocked["host"], blocked["rule"])
+ return json.dumps({"results": [{"url": url, "title": "", "content": "", "error": blocked["message"],
+ "blocked_by_policy": {"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]}}]}, ensure_ascii=False)
+
# Use Firecrawl's v2 crawl functionality
# Docs: https://docs.firecrawl.dev/features/crawl
# The crawl() method automatically waits for completion and returns all data
@@ -975,6 +1369,17 @@ async def web_crawl_tool(
page_url = metadata.get("sourceURL", metadata.get("url", "Unknown URL"))
title = metadata.get("title", "")
+ # Re-check crawled page URL against policy
+ page_blocked = check_website_access(page_url)
+ if page_blocked:
+ logger.info("Blocked crawled page %s by rule %s", page_blocked["host"], page_blocked["rule"])
+ pages.append({
+ "url": page_url, "title": title, "content": "", "raw_content": "",
+ "error": page_blocked["message"],
+ "blocked_by_policy": {"host": page_blocked["host"], "rule": page_blocked["rule"], "source": page_blocked["source"]},
+ })
+ continue
+
# Choose content (prefer markdown)
content = content_markdown or content_html or ""
@@ -1070,9 +1475,11 @@ async def web_crawl_tool(
# Trim output to minimal fields per entry: title, content, error
trimmed_results = [
{
+ "url": r.get("url", ""),
"title": r.get("title", ""),
"content": r.get("content", ""),
- "error": r.get("error")
+ "error": r.get("error"),
+ **({ "blocked_by_policy": r["blocked_by_policy"]} if "blocked_by_policy" in r else {}),
}
for r in response.get("results", [])
]
@@ -1106,13 +1513,23 @@ async def web_crawl_tool(
def check_firecrawl_api_key() -> bool:
"""
Check if the Firecrawl API key is available in environment variables.
-
+
Returns:
bool: True if API key is set, False otherwise
"""
return bool(os.getenv("FIRECRAWL_API_KEY"))
+def check_web_api_key() -> bool:
+ """Check if any web backend API key is available (Parallel, Firecrawl, or Tavily)."""
+ return bool(
+ os.getenv("PARALLEL_API_KEY")
+ or os.getenv("FIRECRAWL_API_KEY")
+ or os.getenv("FIRECRAWL_API_URL")
+ or os.getenv("TAVILY_API_KEY")
+ )
+
+
def check_auxiliary_model() -> bool:
"""Check if an auxiliary text model is available for LLM content processing."""
try:
@@ -1139,26 +1556,32 @@ if __name__ == "__main__":
print("=" * 40)
# Check if API keys are available
- firecrawl_available = check_firecrawl_api_key()
+ web_available = check_web_api_key()
nous_available = check_auxiliary_model()
-
- if not firecrawl_available:
- print("❌ FIRECRAWL_API_KEY environment variable not set")
- print("Please set your API key: export FIRECRAWL_API_KEY='your-key-here'")
- print("Get API key at: https://firecrawl.dev/")
+
+ if web_available:
+ backend = _get_backend()
+ print(f"✅ Web backend: {backend}")
+ if backend == "parallel":
+ print(" Using Parallel API (https://parallel.ai)")
+ elif backend == "tavily":
+ print(" Using Tavily API (https://tavily.com)")
+ else:
+ print(" Using Firecrawl API (https://firecrawl.dev)")
else:
- print("✅ Firecrawl API key found")
-
+ print("❌ No web search backend configured")
+ print("Set PARALLEL_API_KEY, TAVILY_API_KEY, or FIRECRAWL_API_KEY")
+
if not nous_available:
print("❌ No auxiliary model available for LLM content processing")
print("Set OPENROUTER_API_KEY, configure Nous Portal, or set OPENAI_BASE_URL + OPENAI_API_KEY")
print("⚠️ Without an auxiliary model, LLM content processing will be disabled")
else:
print(f"✅ Auxiliary model available: {DEFAULT_SUMMARIZER_MODEL}")
-
- if not firecrawl_available:
+
+ if not web_available:
exit(1)
-
+
print("🛠️ Web tools ready for use!")
if nous_available:
@@ -1256,8 +1679,8 @@ registry.register(
toolset="web",
schema=WEB_SEARCH_SCHEMA,
handler=lambda args, **kw: web_search_tool(args.get("query", ""), limit=5),
- check_fn=check_firecrawl_api_key,
- requires_env=["FIRECRAWL_API_KEY"],
+ check_fn=check_web_api_key,
+ requires_env=["PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
emoji="🔍",
)
registry.register(
@@ -1266,8 +1689,8 @@ registry.register(
schema=WEB_EXTRACT_SCHEMA,
handler=lambda args, **kw: web_extract_tool(
args.get("urls", [])[:5] if isinstance(args.get("urls"), list) else [], "markdown"),
- check_fn=check_firecrawl_api_key,
- requires_env=["FIRECRAWL_API_KEY"],
+ check_fn=check_web_api_key,
+ requires_env=["PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
is_async=True,
emoji="📄",
)
diff --git a/tools/website_policy.py b/tools/website_policy.py
new file mode 100644
index 000000000..2a3d2470f
--- /dev/null
+++ b/tools/website_policy.py
@@ -0,0 +1,285 @@
+"""Website access policy helpers for URL-capable tools.
+
+This module loads a user-managed website blocklist from ~/.hermes/config.yaml
+and optional shared list files. It is intentionally lightweight so web/browser
+tools can enforce URL policy without pulling in the heavier CLI config stack.
+
+Policy is cached in memory with a short TTL so config changes take effect
+quickly without re-reading the file on every URL check.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_WEBSITE_BLOCKLIST = {
+ "enabled": False,
+ "domains": [],
+ "shared_files": [],
+}
+
+# Cache: parsed policy + timestamp. Avoids re-reading config.yaml on every
+# URL check (a web_crawl with 50 pages would otherwise mean 51 YAML parses).
+_CACHE_TTL_SECONDS = 30.0
+_cache_lock = threading.Lock()
+_cached_policy: Optional[Dict[str, Any]] = None
+_cached_policy_path: Optional[str] = None
+_cached_policy_time: float = 0.0
+
+
+def _get_hermes_home() -> Path:
+ return Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+
+
+def _get_default_config_path() -> Path:
+ return _get_hermes_home() / "config.yaml"
+
+
+class WebsitePolicyError(Exception):
+ """Raised when a website policy file is malformed."""
+
+
+def _normalize_host(host: str) -> str:
+ return (host or "").strip().lower().rstrip(".")
+
+
+def _normalize_rule(rule: Any) -> Optional[str]:
+ if not isinstance(rule, str):
+ return None
+ value = rule.strip().lower()
+ if not value or value.startswith("#"):
+ return None
+ if "://" in value:
+ parsed = urlparse(value)
+ value = parsed.netloc or parsed.path
+ value = value.split("/", 1)[0].strip().rstrip(".")
+ if value.startswith("www."):
+ value = value[4:]
+ return value or None
+
+
+def _iter_blocklist_file_rules(path: Path) -> List[str]:
+ """Load rules from a shared blocklist file.
+
+ Missing or unreadable files log a warning and return an empty list
+ rather than raising — a bad file path should not disable all web tools.
+ """
+ try:
+ raw = path.read_text(encoding="utf-8")
+ except FileNotFoundError:
+ logger.warning("Shared blocklist file not found (skipping): %s", path)
+ return []
+ except (OSError, UnicodeDecodeError) as exc:
+ logger.warning("Failed to read shared blocklist file %s (skipping): %s", path, exc)
+ return []
+
+ rules: List[str] = []
+ for line in raw.splitlines():
+ stripped = line.strip()
+ if not stripped or stripped.startswith("#"):
+ continue
+ normalized = _normalize_rule(stripped)
+ if normalized:
+ rules.append(normalized)
+ return rules
+
+
+def _load_policy_config(config_path: Optional[Path] = None) -> Dict[str, Any]:
+ config_path = config_path or _get_default_config_path()
+ if not config_path.exists():
+ return dict(_DEFAULT_WEBSITE_BLOCKLIST)
+
+ try:
+ import yaml
+ except ImportError:
+ logger.debug("PyYAML not installed — website blocklist disabled")
+ return dict(_DEFAULT_WEBSITE_BLOCKLIST)
+
+ try:
+ with open(config_path, encoding="utf-8") as f:
+ config = yaml.safe_load(f) or {}
+ except yaml.YAMLError as exc:
+ raise WebsitePolicyError(f"Invalid config YAML at {config_path}: {exc}") from exc
+ except OSError as exc:
+ raise WebsitePolicyError(f"Failed to read config file {config_path}: {exc}") from exc
+ if not isinstance(config, dict):
+ raise WebsitePolicyError("config root must be a mapping")
+
+ security = config.get("security", {})
+ if security is None:
+ security = {}
+ if not isinstance(security, dict):
+ raise WebsitePolicyError("security must be a mapping")
+
+ website_blocklist = security.get("website_blocklist", {})
+ if website_blocklist is None:
+ website_blocklist = {}
+ if not isinstance(website_blocklist, dict):
+ raise WebsitePolicyError("security.website_blocklist must be a mapping")
+
+ policy = dict(_DEFAULT_WEBSITE_BLOCKLIST)
+ policy.update(website_blocklist)
+ return policy
+
+
+def load_website_blocklist(config_path: Optional[Path] = None) -> Dict[str, Any]:
+ """Load and return the parsed website blocklist policy.
+
+ Results are cached for ``_CACHE_TTL_SECONDS`` to avoid re-reading
+ config.yaml on every URL check. Pass an explicit ``config_path``
+ to bypass the cache (used by tests).
+ """
+ global _cached_policy, _cached_policy_path, _cached_policy_time
+
+ resolved_path = str(config_path) if config_path else "__default__"
+ now = time.monotonic()
+
+ # Return cached policy if still fresh and same path
+ if config_path is None:
+ with _cache_lock:
+ if (
+ _cached_policy is not None
+ and _cached_policy_path == resolved_path
+ and (now - _cached_policy_time) < _CACHE_TTL_SECONDS
+ ):
+ return _cached_policy
+
+ config_path = config_path or _get_default_config_path()
+ policy = _load_policy_config(config_path)
+
+ raw_domains = policy.get("domains", []) or []
+ if not isinstance(raw_domains, list):
+ raise WebsitePolicyError("security.website_blocklist.domains must be a list")
+
+ raw_shared_files = policy.get("shared_files", []) or []
+ if not isinstance(raw_shared_files, list):
+ raise WebsitePolicyError("security.website_blocklist.shared_files must be a list")
+
+ enabled = policy.get("enabled", True)
+ if not isinstance(enabled, bool):
+ raise WebsitePolicyError("security.website_blocklist.enabled must be a boolean")
+
+ rules: List[Dict[str, str]] = []
+ seen: set[Tuple[str, str]] = set()
+
+ for raw_rule in raw_domains:
+ normalized = _normalize_rule(raw_rule)
+ if normalized and ("config", normalized) not in seen:
+ rules.append({"pattern": normalized, "source": "config"})
+ seen.add(("config", normalized))
+
+ for shared_file in raw_shared_files:
+ if not isinstance(shared_file, str) or not shared_file.strip():
+ continue
+ path = Path(shared_file).expanduser()
+ if not path.is_absolute():
+ path = (_get_hermes_home() / path).resolve()
+ for normalized in _iter_blocklist_file_rules(path):
+ key = (str(path), normalized)
+ if key in seen:
+ continue
+ rules.append({"pattern": normalized, "source": str(path)})
+ seen.add(key)
+
+ result = {"enabled": enabled, "rules": rules}
+
+ # Cache the result (only for the default path — explicit paths are tests)
+ if config_path == _get_default_config_path():
+ with _cache_lock:
+ _cached_policy = result
+ _cached_policy_path = "__default__"
+ _cached_policy_time = now
+
+ return result
+
+
+def invalidate_cache() -> None:
+ """Force the next ``check_website_access`` call to re-read config."""
+ global _cached_policy
+ with _cache_lock:
+ _cached_policy = None
+
+
+def _match_host_against_rule(host: str, pattern: str) -> bool:
+ if not host or not pattern:
+ return False
+ if pattern.startswith("*."):
+ return fnmatch.fnmatch(host, pattern)
+ return host == pattern or host.endswith(f".{pattern}")
+
+
+def _extract_host_from_urlish(url: str) -> str:
+ parsed = urlparse(url)
+ host = _normalize_host(parsed.hostname or parsed.netloc)
+ if host:
+ return host
+
+ if "://" not in url:
+ schemeless = urlparse(f"//{url}")
+ host = _normalize_host(schemeless.hostname or schemeless.netloc)
+ if host:
+ return host
+
+ return ""
+
+
+def check_website_access(url: str, config_path: Optional[Path] = None) -> Optional[Dict[str, str]]:
+ """Check whether a URL is allowed by the website blocklist policy.
+
+ Returns ``None`` if access is allowed, or a dict with block metadata
+ (``host``, ``rule``, ``source``, ``message``) if blocked.
+
+ Never raises on policy errors — logs a warning and returns ``None``
+ (fail-open) so a config typo doesn't break all web tools. Pass
+ ``config_path`` explicitly (tests) to get strict error propagation.
+ """
+ # Fast path: if no explicit config_path and the cached policy is disabled
+ # or empty, skip all work (no YAML read, no host extraction).
+ if config_path is None:
+ with _cache_lock:
+ if _cached_policy is not None and not _cached_policy.get("enabled"):
+ return None
+
+ host = _extract_host_from_urlish(url)
+ if not host:
+ return None
+
+ try:
+ policy = load_website_blocklist(config_path)
+ except WebsitePolicyError as exc:
+ if config_path is not None:
+ raise # Tests pass explicit paths — let errors propagate
+ logger.warning("Website policy config error (failing open): %s", exc)
+ return None
+ except Exception as exc:
+ logger.warning("Unexpected error loading website policy (failing open): %s", exc)
+ return None
+
+ if not policy.get("enabled"):
+ return None
+
+ for rule in policy.get("rules", []):
+ pattern = rule.get("pattern", "")
+ if _match_host_against_rule(host, pattern):
+ logger.info("Blocked URL %s — matched rule '%s' from %s",
+ url, pattern, rule.get("source", "config"))
+ return {
+ "url": url,
+ "host": host,
+ "rule": pattern,
+ "source": rule.get("source", "config"),
+ "message": (
+ f"Blocked by website policy: '{host}' matched rule '{pattern}'"
+ f" from {rule.get('source', 'config')}"
+ ),
+ }
+ return None
diff --git a/toolsets.py b/toolsets.py
index b7b2e48fb..212b6ea22 100644
--- a/toolsets.py
+++ b/toolsets.py
@@ -130,6 +130,12 @@ TOOLSETS = {
"includes": []
},
+ "messaging": {
+ "description": "Cross-platform messaging: send messages to Telegram, Discord, Slack, SMS, etc.",
+ "tools": ["send_message"],
+ "includes": []
+ },
+
"rl": {
"description": "RL training tools for running reinforcement learning on Tinker-Atropos",
"tools": [
@@ -293,7 +299,7 @@ TOOLSETS = {
},
"hermes-sms": {
- "description": "SMS bot toolset - interact with Hermes via SMS (Telnyx)",
+ "description": "SMS bot toolset - interact with Hermes via SMS (Twilio)",
"tools": _HERMES_CORE_TOOLS,
"includes": []
},
diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md
index 66be25fd6..0418d473c 100644
--- a/website/docs/getting-started/quickstart.md
+++ b/website/docs/getting-started/quickstart.md
@@ -49,6 +49,9 @@ hermes setup # Or configure everything at once
| **Kimi / Moonshot** | Moonshot-hosted coding and chat models | Set `KIMI_API_KEY` |
| **MiniMax** | International MiniMax endpoint | Set `MINIMAX_API_KEY` |
| **MiniMax China** | China-region MiniMax endpoint | Set `MINIMAX_CN_API_KEY` |
+| **Alibaba Cloud** | Qwen models via DashScope | Set `DASHSCOPE_API_KEY` |
+| **Kilo Code** | KiloCode-hosted models | Set `KILOCODE_API_KEY` |
+| **Vercel AI Gateway** | Vercel AI Gateway routing | Set `AI_GATEWAY_API_KEY` |
| **Custom Endpoint** | VLLM, SGLang, or any OpenAI-compatible API | Set base URL + API key |
:::tip
diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md
index 0b5afa4b8..a594b7a60 100644
--- a/website/docs/reference/environment-variables.md
+++ b/website/docs/reference/environment-variables.md
@@ -32,6 +32,8 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
| `KILOCODE_BASE_URL` | Override Kilo Code base URL (default: `https://api.kilo.ai/api/gateway`) |
| `ANTHROPIC_API_KEY` | Anthropic Console API key ([console.anthropic.com](https://console.anthropic.com/)) |
| `ANTHROPIC_TOKEN` | Manual or legacy Anthropic OAuth/setup-token override |
+| `DASHSCOPE_API_KEY` | Alibaba Cloud DashScope API key for Qwen models ([modelstudio.console.alibabacloud.com](https://modelstudio.console.alibabacloud.com/)) |
+| `DASHSCOPE_BASE_URL` | Custom DashScope base URL (default: international endpoint) |
| `CLAUDE_CODE_OAUTH_TOKEN` | Explicit Claude Code token override if you export one manually |
| `HERMES_MODEL` | Preferred model name (checked before `LLM_MODEL`, used by gateway) |
| `LLM_MODEL` | Default model name (fallback when not set in config.yaml) |
@@ -46,7 +48,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
| Variable | Description |
|----------|-------------|
-| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode` (default: `auto`) |
+| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`, `alibaba` (default: `auto`) |
| `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) |
| `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL |
| `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) |
@@ -59,10 +61,13 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
| Variable | Description |
|----------|-------------|
+| `PARALLEL_API_KEY` | AI-native web search ([parallel.ai](https://parallel.ai/)) |
| `FIRECRAWL_API_KEY` | Web scraping ([firecrawl.dev](https://firecrawl.dev/)) |
| `FIRECRAWL_API_URL` | Custom Firecrawl API endpoint for self-hosted instances (optional) |
| `BROWSERBASE_API_KEY` | Browser automation ([browserbase.com](https://browserbase.com/)) |
| `BROWSERBASE_PROJECT_ID` | Browserbase project ID |
+| `BROWSER_USE_API_KEY` | Browser Use cloud browser API key ([browser-use.com](https://browser-use.com/)) |
+| `BROWSER_CDP_URL` | Chrome DevTools Protocol URL for local browser (set via `/browser connect`, e.g. `ws://localhost:9222`) |
| `BROWSER_INACTIVITY_TIMEOUT` | Browser session inactivity timeout in seconds |
| `FAL_KEY` | Image generation ([fal.ai](https://fal.ai/)) |
| `GROQ_API_KEY` | Groq Whisper STT API key ([groq.com](https://groq.com/)) |
@@ -151,6 +156,14 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
| `SIGNAL_HOME_CHANNEL_NAME` | Display name for the Signal home channel |
| `SIGNAL_IGNORE_STORIES` | Ignore Signal stories/status updates |
| `SIGNAL_ALLOW_ALL_USERS` | Allow all Signal users without an allowlist |
+| `TWILIO_ACCOUNT_SID` | Twilio Account SID (shared with telephony skill) |
+| `TWILIO_AUTH_TOKEN` | Twilio Auth Token (shared with telephony skill) |
+| `TWILIO_PHONE_NUMBER` | Twilio phone number in E.164 format (shared with telephony skill) |
+| `SMS_WEBHOOK_PORT` | Webhook listener port for inbound SMS (default: `8080`) |
+| `SMS_ALLOWED_USERS` | Comma-separated E.164 phone numbers allowed to chat |
+| `SMS_ALLOW_ALL_USERS` | Allow all SMS senders without an allowlist |
+| `SMS_HOME_CHANNEL` | Phone number for cron job / notification delivery |
+| `SMS_HOME_CHANNEL_NAME` | Display name for the SMS home channel |
| `EMAIL_ADDRESS` | Email address for the Email gateway adapter |
| `EMAIL_PASSWORD` | Password or app password for the email account |
| `EMAIL_IMAP_HOST` | IMAP hostname for the email adapter |
@@ -162,6 +175,21 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
| `EMAIL_HOME_ADDRESS_NAME` | Display name for the email home target |
| `EMAIL_POLL_INTERVAL` | Email polling interval in seconds |
| `EMAIL_ALLOW_ALL_USERS` | Allow all inbound email senders |
+| `DINGTALK_CLIENT_ID` | DingTalk bot AppKey from developer portal ([open.dingtalk.com](https://open.dingtalk.com)) |
+| `DINGTALK_CLIENT_SECRET` | DingTalk bot AppSecret from developer portal |
+| `DINGTALK_ALLOWED_USERS` | Comma-separated DingTalk user IDs allowed to message the bot |
+| `MATTERMOST_URL` | Mattermost server URL (e.g. `https://mm.example.com`) |
+| `MATTERMOST_TOKEN` | Bot token or personal access token for Mattermost |
+| `MATTERMOST_ALLOWED_USERS` | Comma-separated Mattermost user IDs allowed to message the bot |
+| `MATTERMOST_HOME_CHANNEL` | Channel ID for proactive message delivery (cron, notifications) |
+| `MATTERMOST_REPLY_MODE` | Reply style: `thread` (threaded replies) or `off` (flat messages, default) |
+| `MATRIX_HOMESERVER` | Matrix homeserver URL (e.g. `https://matrix.org`) |
+| `MATRIX_ACCESS_TOKEN` | Matrix access token for bot authentication |
+| `MATRIX_USER_ID` | Matrix user ID (e.g. `@hermes:matrix.org`) — required for password login, optional with access token |
+| `MATRIX_PASSWORD` | Matrix password (alternative to access token) |
+| `MATRIX_ALLOWED_USERS` | Comma-separated Matrix user IDs allowed to message the bot (e.g. `@alice:matrix.org`) |
+| `MATRIX_HOME_ROOM` | Room ID for proactive message delivery (e.g. `!abc123:matrix.org`) |
+| `MATRIX_ENCRYPTION` | Enable end-to-end encryption (`true`/`false`, default: `false`) |
| `HASS_TOKEN` | Home Assistant Long-Lived Access Token (enables HA platform + tools) |
| `HASS_URL` | Home Assistant URL (default: `http://homeassistant.local:8123`) |
| `MESSAGING_CWD` | Working directory for terminal commands in messaging mode (default: `~`) |
diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index c3de04697..3c8ee77d3 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -52,8 +52,9 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
| Command | Description |
|---------|-------------|
-| `/tools` | List available tools |
+| `/tools [list\|disable\|enable] [name...]` | Manage tools: list available tools, or disable/enable specific tools for the current session. Disabling a tool removes it from the agent's toolset and triggers a session reset. |
| `/toolsets` | List available toolsets |
+| `/browser [connect\|disconnect\|status]` | Manage local Chrome CDP connection. `connect` attaches browser tools to a running Chrome instance (default: `ws://localhost:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches Chrome if no debugger is detected. |
| `/skills` | Search, install, inspect, or manage skills from online registries |
| `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) |
| `/reload-mcp` | Reload MCP servers from config.yaml |
@@ -118,7 +119,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
## Notes
-- `/skin`, `/tools`, `/toolsets`, `/config`, `/prompt`, `/cron`, `/skills`, `/platforms`, `/paste`, and `/verbose` are **CLI-only** commands.
+- `/skin`, `/tools`, `/toolsets`, `/browser`, `/config`, `/prompt`, `/cron`, `/skills`, `/platforms`, `/paste`, and `/verbose` are **CLI-only** commands.
- `/status`, `/stop`, `/sethome`, `/resume`, and `/update` are **messaging-only** commands.
- `/background`, `/voice`, `/reload-mcp`, and `/rollback` work in **both** the CLI and the messaging gateway.
- `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord.
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index f18d803d4..032b46179 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -70,7 +70,9 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro
| **Kimi / Moonshot** | `KIMI_API_KEY` in `~/.hermes/.env` (provider: `kimi-coding`) |
| **MiniMax** | `MINIMAX_API_KEY` in `~/.hermes/.env` (provider: `minimax`) |
| **MiniMax China** | `MINIMAX_CN_API_KEY` in `~/.hermes/.env` (provider: `minimax-cn`) |
+| **Alibaba Cloud** | `DASHSCOPE_API_KEY` in `~/.hermes/.env` (provider: `alibaba`, aliases: `dashscope`, `qwen`) |
| **Kilo Code** | `KILOCODE_API_KEY` in `~/.hermes/.env` (provider: `kilocode`) |
+| **Alibaba Cloud** | `DASHSCOPE_API_KEY` in `~/.hermes/.env` (provider: `alibaba`) |
| **Custom Endpoint** | `hermes model` (saved in `config.yaml`) or `OPENAI_BASE_URL` + `OPENAI_API_KEY` in `~/.hermes/.env` |
:::info Codex Note
@@ -135,16 +137,20 @@ hermes chat --provider minimax --model MiniMax-Text-01
# MiniMax (China endpoint)
hermes chat --provider minimax-cn --model MiniMax-Text-01
# Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env
+
+# Alibaba Cloud / DashScope (Qwen models)
+hermes chat --provider alibaba --model qwen-plus
+# Requires: DASHSCOPE_API_KEY in ~/.hermes/.env
```
Or set the provider permanently in `config.yaml`:
```yaml
model:
- provider: "zai" # or: kimi-coding, minimax, minimax-cn
+ provider: "zai" # or: kimi-coding, minimax, minimax-cn, alibaba
default: "glm-4-plus"
```
-Base URLs can be overridden with `GLM_BASE_URL`, `KIMI_BASE_URL`, `MINIMAX_BASE_URL`, or `MINIMAX_CN_BASE_URL` environment variables.
+Base URLs can be overridden with `GLM_BASE_URL`, `KIMI_BASE_URL`, `MINIMAX_BASE_URL`, `MINIMAX_CN_BASE_URL`, or `DASHSCOPE_BASE_URL` environment variables.
## Custom & Self-Hosted LLM Providers
@@ -872,6 +878,7 @@ This controls both the `text_to_speech` tool and spoken replies in voice mode (`
display:
tool_progress: all # off | new | all | verbose
skin: default # Built-in or custom CLI skin (see user-guide/features/skins)
+ theme_mode: auto # auto | light | dark — color scheme for skin-aware rendering
personality: "kawaii" # Legacy cosmetic field still surfaced in some summaries
compact: false # Compact output mode (less whitespace)
resume_display: full # full (show previous messages on resume) | minimal (one-liner only)
@@ -881,6 +888,18 @@ display:
background_process_notifications: all # all | result | error | off (gateway only)
```
+### Theme mode
+
+The `theme_mode` setting controls whether skins render in light or dark mode:
+
+| Mode | Behavior |
+|------|----------|
+| `auto` (default) | Detects your terminal's background color automatically. Falls back to `dark` if detection fails. |
+| `light` | Forces light-mode skin colors. Skins that define a `colors_light` override use those colors instead of the default dark-mode palette. |
+| `dark` | Forces dark-mode skin colors. |
+
+This works with any skin — built-in or custom. Skin authors can provide `colors_light` in their skin definition for optimal light-terminal appearance.
+
| Mode | What you see |
|------|-------------|
| `off` | Silent — just the final response |
@@ -1055,6 +1074,54 @@ browser:
record_sessions: false # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/
```
+The browser toolset supports multiple providers. See the [Browser feature page](/docs/user-guide/features/browser) for details on Browserbase, Browser Use, and local Chrome CDP setup.
+
+## Website Blocklist
+
+Block specific domains from being accessed by the agent's web and browser tools:
+
+```yaml
+website_blocklist:
+ enabled: false # Enable URL blocking (default: false)
+ domains: # List of blocked domain patterns
+ - "*.internal.company.com"
+ - "admin.example.com"
+ - "*.local"
+ shared_files: # Load additional rules from external files
+ - "/etc/hermes/blocked-sites.txt"
+```
+
+When enabled, any URL matching a blocked domain pattern is rejected before the web or browser tool executes. This applies to `web_search`, `web_extract`, `browser_navigate`, and any tool that accesses URLs.
+
+Domain rules support:
+- Exact domains: `admin.example.com`
+- Wildcard subdomains: `*.internal.company.com` (blocks all subdomains)
+- TLD wildcards: `*.local`
+
+Shared files contain one domain rule per line (blank lines and `#` comments are ignored). Missing or unreadable files log a warning but don't disable other web tools.
+
+The policy is cached for 30 seconds, so config changes take effect quickly without restart.
+
+## Smart Approvals
+
+Control how Hermes handles potentially dangerous commands:
+
+```yaml
+approval_mode: ask # ask | smart | off
+```
+
+| Mode | Behavior |
+|------|----------|
+| `ask` (default) | Prompt the user before executing any flagged command. In the CLI, shows an interactive approval dialog. In messaging, queues a pending approval request. |
+| `smart` | Use an auxiliary LLM to assess whether a flagged command is actually dangerous. Low-risk commands are auto-approved with session-level persistence. Genuinely risky commands are escalated to the user. |
+| `off` | Skip all approval checks. Equivalent to `HERMES_YOLO_MODE=true`. **Use with caution.** |
+
+Smart mode is particularly useful for reducing approval fatigue — it lets the agent work more autonomously on safe operations while still catching genuinely destructive commands.
+
+:::warning
+Setting `approval_mode: off` disables all safety checks for terminal commands. Only use this in trusted, sandboxed environments.
+:::
+
## Checkpoints
Automatic filesystem snapshots before destructive file operations. See the [Checkpoints feature page](/docs/user-guide/features/checkpoints) for details.
diff --git a/website/docs/user-guide/features/browser.md b/website/docs/user-guide/features/browser.md
index ad6e6df81..0f7b2570c 100644
--- a/website/docs/user-guide/features/browser.md
+++ b/website/docs/user-guide/features/browser.md
@@ -1,27 +1,30 @@
---
title: Browser Automation
-description: Control cloud browsers with Browserbase integration for web interaction, form filling, scraping, and more.
+description: Control browsers with multiple providers, local Chrome via CDP, or cloud browsers for web interaction, form filling, scraping, and more.
sidebar_label: Browser
sidebar_position: 5
---
# Browser Automation
-Hermes Agent includes a full browser automation toolset that can run in two modes:
+Hermes Agent includes a full browser automation toolset with multiple backend options:
- **Browserbase cloud mode** via [Browserbase](https://browserbase.com) for managed cloud browsers and anti-bot tooling
+- **Browser Use cloud mode** via [Browser Use](https://browser-use.com) as an alternative cloud browser provider
+- **Local Chrome via CDP** — connect browser tools to your own Chrome instance using `/browser connect`
- **Local browser mode** via the `agent-browser` CLI and a local Chromium installation
-In both modes, the agent can navigate websites, interact with page elements, fill forms, and extract information.
+In all modes, the agent can navigate websites, interact with page elements, fill forms, and extract information.
## Overview
-The browser tools use the `agent-browser` CLI. In Browserbase mode, `agent-browser` connects to Browserbase cloud sessions. In local mode, it drives a local Chromium installation. Pages are represented as **accessibility trees** (text-based snapshots), making them ideal for LLM agents. Interactive elements get ref IDs (like `@e1`, `@e2`) that the agent uses for clicking and typing.
+Pages are represented as **accessibility trees** (text-based snapshots), making them ideal for LLM agents. Interactive elements get ref IDs (like `@e1`, `@e2`) that the agent uses for clicking and typing.
Key capabilities:
-- **Cloud execution** — no local browser needed
-- **Built-in stealth** — random fingerprints, CAPTCHA solving, residential proxies
+- **Multi-provider cloud execution** — Browserbase or Browser Use, no local browser needed
+- **Local Chrome integration** — attach to your running Chrome via CDP for hands-on browsing
+- **Built-in stealth** — random fingerprints, CAPTCHA solving, residential proxies (Browserbase)
- **Session isolation** — each task gets its own browser session
- **Automatic cleanup** — inactive sessions are closed after a timeout
- **Vision analysis** — screenshot + AI analysis for visual understanding
@@ -40,9 +43,48 @@ BROWSERBASE_PROJECT_ID=your-project-id-here
Get your credentials at [browserbase.com](https://browserbase.com).
+### Browser Use cloud mode
+
+To use Browser Use as your cloud browser provider, add:
+
+```bash
+# Add to ~/.hermes/.env
+BROWSER_USE_API_KEY=***
+```
+
+Get your API key at [browser-use.com](https://browser-use.com). Browser Use provides a cloud browser via its REST API. If both Browserbase and Browser Use credentials are set, Browserbase takes priority.
+
+### Local Chrome via CDP (`/browser connect`)
+
+Instead of a cloud provider, you can attach Hermes browser tools to your own running Chrome instance via the Chrome DevTools Protocol (CDP). This is useful when you want to see what the agent is doing in real-time, interact with pages that require your own cookies/sessions, or avoid cloud browser costs.
+
+In the CLI, use:
+
+```
+/browser connect # Connect to Chrome at ws://localhost:9222
+/browser connect ws://host:port # Connect to a specific CDP endpoint
+/browser status # Check current connection
+/browser disconnect # Detach and return to cloud/local mode
+```
+
+If Chrome isn't already running with remote debugging, Hermes will attempt to auto-launch it with `--remote-debugging-port=9222`.
+
+:::tip
+To start Chrome manually with CDP enabled:
+```bash
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+```
+:::
+
+When connected via CDP, all browser tools (`browser_navigate`, `browser_click`, etc.) operate on your live Chrome instance instead of spinning up a cloud session.
+
### Local browser mode
-If you do **not** set Browserbase credentials, Hermes can still use the browser tools through a local Chromium install driven by `agent-browser`.
+If you do **not** set any cloud credentials and don't use `/browser connect`, Hermes can still use the browser tools through a local Chromium install driven by `agent-browser`.
### Optional Environment Variables
@@ -232,10 +274,8 @@ If paid features aren't available on your plan, Hermes automatically falls back
## Limitations
-- **Requires Browserbase account** — no local browser fallback
-- **Requires `agent-browser` CLI** — must be installed via npm
- **Text-based interaction** — relies on accessibility tree, not pixel coordinates
- **Snapshot size** — large pages may be truncated or LLM-summarized at 8000 characters
-- **Session timeout** — sessions expire based on your Browserbase plan settings
-- **Cost** — each session consumes Browserbase credits; use `browser_close` when done
+- **Session timeout** — cloud sessions expire based on your provider's plan settings
+- **Cost** — cloud sessions consume provider credits; use `browser_close` when done. Use `/browser connect` for free local browsing.
- **No file downloads** — cannot download files from the browser
diff --git a/website/docs/user-guide/messaging/dingtalk.md b/website/docs/user-guide/messaging/dingtalk.md
new file mode 100644
index 000000000..f7f5a00d2
--- /dev/null
+++ b/website/docs/user-guide/messaging/dingtalk.md
@@ -0,0 +1,192 @@
+---
+sidebar_position: 10
+title: "DingTalk"
+description: "Set up Hermes Agent as a DingTalk chatbot"
+---
+
+# DingTalk Setup
+
+Hermes Agent integrates with DingTalk (钉钉) as a chatbot, letting you chat with your AI assistant through direct messages or group chats. The bot connects via DingTalk's Stream Mode — a long-lived WebSocket connection that requires no public URL or webhook server — and replies using markdown-formatted messages through DingTalk's session webhook API.
+
+Before setup, here's the part most people want to know: how Hermes behaves once it's in your DingTalk workspace.
+
+## How Hermes Behaves
+
+| Context | Behavior |
+|---------|----------|
+| **DMs (1:1 chat)** | Hermes responds to every message. No `@mention` needed. Each DM has its own session. |
+| **Group chats** | Hermes responds when you `@mention` it. Without a mention, Hermes ignores the message. |
+| **Shared groups with multiple users** | By default, Hermes isolates session history per user inside the group. Two people talking in the same group do not share one transcript unless you explicitly disable that. |
+
+### Session Model in DingTalk
+
+By default:
+
+- each DM gets its own session
+- each user in a shared group chat gets their own session inside that group
+
+This is controlled by `config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+Set it to `false` only if you explicitly want one shared conversation for the entire group:
+
+```yaml
+group_sessions_per_user: false
+```
+
+This guide walks you through the full setup process — from creating your DingTalk bot to sending your first message.
+
+## Prerequisites
+
+Install the required Python packages:
+
+```bash
+pip install dingtalk-stream httpx
+```
+
+- `dingtalk-stream` — DingTalk's official SDK for Stream Mode (WebSocket-based real-time messaging)
+- `httpx` — async HTTP client used for sending replies via session webhooks
+
+## Step 1: Create a DingTalk App
+
+1. Go to the [DingTalk Developer Console](https://open-dev.dingtalk.com/).
+2. Log in with your DingTalk admin account.
+3. Click **Application Development** → **Custom Apps** → **Create App via H5 Micro-App** (or **Robot** depending on your console version).
+4. Fill in:
+ - **App Name**: e.g., `Hermes Agent`
+ - **Description**: optional
+5. After creating, navigate to **Credentials & Basic Info** to find your **Client ID** (AppKey) and **Client Secret** (AppSecret). Copy both.
+
+:::warning[Credentials shown only once]
+The Client Secret is only displayed once when you create the app. If you lose it, you'll need to regenerate it. Never share these credentials publicly or commit them to Git.
+:::
+
+## Step 2: Enable the Robot Capability
+
+1. In your app's settings page, go to **Add Capability** → **Robot**.
+2. Enable the robot capability.
+3. Under **Message Reception Mode**, select **Stream Mode** (recommended — no public URL needed).
+
+:::tip
+Stream Mode is the recommended setup. It uses a long-lived WebSocket connection initiated from your machine, so you don't need a public IP, domain name, or webhook endpoint. This works behind NAT, firewalls, and on local machines.
+:::
+
+## Step 3: Find Your DingTalk User ID
+
+Hermes Agent uses your DingTalk User ID to control who can interact with the bot. DingTalk User IDs are alphanumeric strings set by your organization's admin.
+
+To find yours:
+
+1. Ask your DingTalk organization admin — User IDs are configured in the DingTalk admin console under **Contacts** → **Members**.
+2. Alternatively, the bot logs the `sender_id` for each incoming message. Start the gateway, send the bot a message, then check the logs for your ID.
+
+## Step 4: Configure Hermes Agent
+
+### Option A: Interactive Setup (Recommended)
+
+Run the guided setup command:
+
+```bash
+hermes gateway setup
+```
+
+Select **DingTalk** when prompted, then paste your Client ID, Client Secret, and allowed user IDs when asked.
+
+### Option B: Manual Configuration
+
+Add the following to your `~/.hermes/.env` file:
+
+```bash
+# Required
+DINGTALK_CLIENT_ID=your-app-key
+DINGTALK_CLIENT_SECRET=your-app-secret
+
+# Security: restrict who can interact with the bot
+DINGTALK_ALLOWED_USERS=user-id-1
+
+# Multiple allowed users (comma-separated)
+# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2
+```
+
+Optional behavior settings in `~/.hermes/config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+- `group_sessions_per_user: true` keeps each participant's context isolated inside shared group chats
+
+### Start the Gateway
+
+Once configured, start the DingTalk gateway:
+
+```bash
+hermes gateway
+```
+
+The bot should connect to DingTalk's Stream Mode within a few seconds. Send it a message — either a DM or in a group where it's been added — to test.
+
+:::tip
+You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details.
+:::
+
+## Troubleshooting
+
+### Bot is not responding to messages
+
+**Cause**: The robot capability isn't enabled, or `DINGTALK_ALLOWED_USERS` doesn't include your User ID.
+
+**Fix**: Verify the robot capability is enabled in your app settings and that Stream Mode is selected. Check that your User ID is in `DINGTALK_ALLOWED_USERS`. Restart the gateway.
+
+### "dingtalk-stream not installed" error
+
+**Cause**: The `dingtalk-stream` Python package is not installed.
+
+**Fix**: Install it:
+
+```bash
+pip install dingtalk-stream httpx
+```
+
+### "DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"
+
+**Cause**: The credentials aren't set in your environment or `.env` file.
+
+**Fix**: Verify `DINGTALK_CLIENT_ID` and `DINGTALK_CLIENT_SECRET` are set correctly in `~/.hermes/.env`. The Client ID is your AppKey, and the Client Secret is your AppSecret from the DingTalk Developer Console.
+
+### Stream disconnects / reconnection loops
+
+**Cause**: Network instability, DingTalk platform maintenance, or credential issues.
+
+**Fix**: The adapter automatically reconnects with exponential backoff (2s → 5s → 10s → 30s → 60s). Check that your credentials are valid and your app hasn't been deactivated. Verify your network allows outbound WebSocket connections.
+
+### Bot is offline
+
+**Cause**: The Hermes gateway isn't running, or it failed to connect.
+
+**Fix**: Check that `hermes gateway` is running. Look at the terminal output for error messages. Common issues: wrong credentials, app deactivated, `dingtalk-stream` or `httpx` not installed.
+
+### "No session_webhook available"
+
+**Cause**: The bot tried to reply but doesn't have a session webhook URL. This typically happens if the webhook expired or the bot was restarted between receiving the message and sending the reply.
+
+**Fix**: Send a new message to the bot — each incoming message provides a fresh session webhook for replies. This is a normal DingTalk limitation; the bot can only reply to messages it has received recently.
+
+## Security
+
+:::warning
+Always set `DINGTALK_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.
+:::
+
+For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md).
+
+## Notes
+
+- **Stream Mode**: No public URL, domain name, or webhook server needed. The connection is initiated from your machine via WebSocket, so it works behind NAT and firewalls.
+- **Markdown responses**: Replies are formatted in DingTalk's markdown format for rich text display.
+- **Message deduplication**: The adapter deduplicates messages with a 5-minute window to prevent processing the same message twice.
+- **Auto-reconnection**: If the stream connection drops, the adapter automatically reconnects with exponential backoff.
+- **Message length limit**: Responses are capped at 20,000 characters per message. Longer responses are truncated.
diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md
index 0c17e65e6..c969b451d 100644
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -1,12 +1,12 @@
---
sidebar_position: 1
title: "Messaging Gateway"
-description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or your browser — architecture and setup overview"
+description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, or your browser — architecture and setup overview"
---
# Messaging Gateway
-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/docs/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-hermes).
@@ -21,8 +21,12 @@ flowchart TB
wa[WhatsApp]
sl[Slack]
sig[Signal]
+ sms[SMS]
em[Email]
ha[Home Assistant]
+ mm[Mattermost]
+ mx[Matrix]
+ dt[DingTalk]
end
store["Session store
per chat"]
@@ -35,8 +39,12 @@ flowchart TB
wa --> store
sl --> store
sig --> store
+ sms --> store
em --> store
ha --> store
+ mm --> store
+ mx --> store
+ dt --> store
store --> agent
cron --> store
```
@@ -129,7 +137,11 @@ Configure per-platform overrides in `~/.hermes/gateway.json`:
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
+SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
+MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
+MATRIX_ALLOWED_USERS=@alice:matrix.org
+DINGTALK_ALLOWED_USERS=user-id-1
# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321
@@ -288,8 +300,12 @@ Each platform has its own toolset:
| WhatsApp | `hermes-whatsapp` | Full tools including terminal |
| Slack | `hermes-slack` | Full tools including terminal |
| Signal | `hermes-signal` | Full tools including terminal |
+| SMS | `hermes-sms` | Full tools including terminal |
| Email | `hermes-email` | Full tools including terminal |
| Home Assistant | `hermes-homeassistant` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) |
+| Mattermost | `hermes-mattermost` | Full tools including terminal |
+| Matrix | `hermes-matrix` | Full tools including terminal |
+| DingTalk | `hermes-dingtalk` | Full tools including terminal |
## Next Steps
@@ -298,5 +314,9 @@ Each platform has its own toolset:
- [Slack Setup](slack.md)
- [WhatsApp Setup](whatsapp.md)
- [Signal Setup](signal.md)
+- [SMS Setup (Twilio)](sms.md)
- [Email Setup](email.md)
- [Home Assistant Integration](homeassistant.md)
+- [Mattermost Setup](mattermost.md)
+- [Matrix Setup](matrix.md)
+- [DingTalk Setup](dingtalk.md)
diff --git a/website/docs/user-guide/messaging/matrix.md b/website/docs/user-guide/messaging/matrix.md
new file mode 100644
index 000000000..020e15bd6
--- /dev/null
+++ b/website/docs/user-guide/messaging/matrix.md
@@ -0,0 +1,354 @@
+---
+sidebar_position: 9
+title: "Matrix"
+description: "Set up Hermes Agent as a Matrix bot"
+---
+
+# Matrix Setup
+
+Hermes Agent integrates with Matrix, the open, federated messaging protocol. Matrix lets you run your own homeserver or use a public one like matrix.org — either way, you keep control of your communications. The bot connects via the `matrix-nio` Python SDK, processes messages through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, file attachments, images, audio, video, and optional end-to-end encryption (E2EE).
+
+Hermes works with any Matrix homeserver — Synapse, Conduit, Dendrite, or matrix.org.
+
+Before setup, here's the part most people want to know: how Hermes behaves once it's connected.
+
+## How Hermes Behaves
+
+| Context | Behavior |
+|---------|----------|
+| **DMs** | Hermes responds to every message. No `@mention` needed. Each DM has its own session. |
+| **Rooms** | Hermes responds to all messages in rooms it has joined. Room invites are auto-accepted. |
+| **Threads** | Hermes supports Matrix threads (MSC3440). If you reply in a thread, Hermes keeps the thread context isolated from the main room timeline. |
+| **Shared rooms with multiple users** | By default, Hermes isolates session history per user inside the room. Two people talking in the same room do not share one transcript unless you explicitly disable that. |
+
+:::tip
+The bot automatically joins rooms when invited. Just invite the bot's Matrix user to any room and it will join and start responding.
+:::
+
+### Session Model in Matrix
+
+By default:
+
+- each DM gets its own session
+- each thread gets its own session namespace
+- each user in a shared room gets their own session inside that room
+
+This is controlled by `config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+Set it to `false` only if you explicitly want one shared conversation for the entire room:
+
+```yaml
+group_sessions_per_user: false
+```
+
+Shared sessions can be useful for a collaborative room, but they also mean:
+
+- users share context growth and token costs
+- one person's long tool-heavy task can bloat everyone else's context
+- one person's in-flight run can interrupt another person's follow-up in the same room
+
+This guide walks you through the full setup process — from creating your bot account to sending your first message.
+
+## Step 1: Create a Bot Account
+
+You need a Matrix user account for the bot. There are several ways to do this:
+
+### Option A: Register on Your Homeserver (Recommended)
+
+If you run your own homeserver (Synapse, Conduit, Dendrite):
+
+1. Use the admin API or registration tool to create a new user:
+
+```bash
+# Synapse example
+register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
+```
+
+2. Choose a username like `hermes` — the full user ID will be `@hermes:your-server.org`.
+
+### Option B: Use matrix.org or Another Public Homeserver
+
+1. Go to [Element Web](https://app.element.io) and create a new account.
+2. Pick a username for your bot (e.g., `hermes-bot`).
+
+### Option C: Use Your Own Account
+
+You can also run Hermes as your own user. This means the bot posts as you — useful for personal assistants.
+
+## Step 2: Get an Access Token
+
+Hermes needs an access token to authenticate with the homeserver. You have two options:
+
+### Option A: Access Token (Recommended)
+
+The most reliable way to get a token:
+
+**Via Element:**
+1. Log in to [Element](https://app.element.io) with the bot account.
+2. Go to **Settings** → **Help & About**.
+3. Scroll down and expand **Advanced** — the access token is displayed there.
+4. **Copy it immediately.**
+
+**Via the API:**
+
+```bash
+curl -X POST https://your-server/_matrix/client/v3/login \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "m.login.password",
+ "user": "@hermes:your-server.org",
+ "password": "your-password"
+ }'
+```
+
+The response includes an `access_token` field — copy it.
+
+:::warning[Keep your access token safe]
+The access token gives full access to the bot's Matrix account. Never share it publicly or commit it to Git. If compromised, revoke it by logging out all sessions for that user.
+:::
+
+### Option B: Password Login
+
+Instead of providing an access token, you can give Hermes the bot's user ID and password. Hermes will log in automatically on startup. This is simpler but means the password is stored in your `.env` file.
+
+```bash
+MATRIX_USER_ID=@hermes:your-server.org
+MATRIX_PASSWORD=your-password
+```
+
+## Step 3: Find Your Matrix User ID
+
+Hermes Agent uses your Matrix User ID to control who can interact with the bot. Matrix User IDs follow the format `@username:server`.
+
+To find yours:
+
+1. Open [Element](https://app.element.io) (or your preferred Matrix client).
+2. Click your avatar → **Settings**.
+3. Your User ID is displayed at the top of the profile (e.g., `@alice:matrix.org`).
+
+:::tip
+Matrix User IDs always start with `@` and contain a `:` followed by the server name. For example: `@alice:matrix.org`, `@bob:your-server.com`.
+:::
+
+## Step 4: Configure Hermes Agent
+
+### Option A: Interactive Setup (Recommended)
+
+Run the guided setup command:
+
+```bash
+hermes gateway setup
+```
+
+Select **Matrix** when prompted, then provide your homeserver URL, access token (or user ID + password), and allowed user IDs when asked.
+
+### Option B: Manual Configuration
+
+Add the following to your `~/.hermes/.env` file:
+
+**Using an access token:**
+
+```bash
+# Required
+MATRIX_HOMESERVER=https://matrix.example.org
+MATRIX_ACCESS_TOKEN=***
+
+# Optional: user ID (auto-detected from token if omitted)
+# MATRIX_USER_ID=@hermes:matrix.example.org
+
+# Security: restrict who can interact with the bot
+MATRIX_ALLOWED_USERS=@alice:matrix.example.org
+
+# Multiple allowed users (comma-separated)
+# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org
+```
+
+**Using password login:**
+
+```bash
+# Required
+MATRIX_HOMESERVER=https://matrix.example.org
+MATRIX_USER_ID=@hermes:matrix.example.org
+MATRIX_PASSWORD=***
+
+# Security
+MATRIX_ALLOWED_USERS=@alice:matrix.example.org
+```
+
+Optional behavior settings in `~/.hermes/config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+- `group_sessions_per_user: true` keeps each participant's context isolated inside shared rooms
+
+### Start the Gateway
+
+Once configured, start the Matrix gateway:
+
+```bash
+hermes gateway
+```
+
+The bot should connect to your homeserver and start syncing within a few seconds. Send it a message — either a DM or in a room it has joined — to test.
+
+:::tip
+You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details.
+:::
+
+## End-to-End Encryption (E2EE)
+
+Hermes supports Matrix end-to-end encryption, so you can chat with your bot in encrypted rooms.
+
+### Requirements
+
+E2EE requires the `matrix-nio` library with encryption extras and the `libolm` C library:
+
+```bash
+# Install matrix-nio with E2EE support
+pip install 'matrix-nio[e2e]'
+
+# Or install with hermes extras
+pip install 'hermes-agent[matrix]'
+```
+
+You also need `libolm` installed on your system:
+
+```bash
+# Debian/Ubuntu
+sudo apt install libolm-dev
+
+# macOS
+brew install libolm
+
+# Fedora
+sudo dnf install libolm-devel
+```
+
+### Enable E2EE
+
+Add to your `~/.hermes/.env`:
+
+```bash
+MATRIX_ENCRYPTION=true
+```
+
+When E2EE is enabled, Hermes:
+
+- Stores encryption keys in `~/.hermes/matrix/store/`
+- Uploads device keys on first connection
+- Decrypts incoming messages and encrypts outgoing messages automatically
+- Auto-joins encrypted rooms when invited
+
+:::warning
+If you delete the `~/.hermes/matrix/store/` directory, the bot loses its encryption keys. You'll need to verify the device again in your Matrix client. Back up this directory if you want to preserve encrypted sessions.
+:::
+
+:::info
+If `matrix-nio[e2e]` is not installed or `libolm` is missing, the bot falls back to a plain (unencrypted) client automatically. You'll see a warning in the logs.
+:::
+
+## Home Room
+
+You can designate a "home room" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it:
+
+### Using the Slash Command
+
+Type `/sethome` in any Matrix room where the bot is present. That room becomes the home room.
+
+### Manual Configuration
+
+Add this to your `~/.hermes/.env`:
+
+```bash
+MATRIX_HOME_ROOM=!abc123def456:matrix.example.org
+```
+
+:::tip
+To find a Room ID: in Element, go to the room → **Settings** → **Advanced** → the **Internal room ID** is shown there (starts with `!`).
+:::
+
+## Troubleshooting
+
+### Bot is not responding to messages
+
+**Cause**: The bot hasn't joined the room, or `MATRIX_ALLOWED_USERS` doesn't include your User ID.
+
+**Fix**: Invite the bot to the room — it auto-joins on invite. Verify your User ID is in `MATRIX_ALLOWED_USERS` (use the full `@user:server` format). Restart the gateway.
+
+### "Failed to authenticate" / "whoami failed" on startup
+
+**Cause**: The access token or homeserver URL is incorrect.
+
+**Fix**: Verify `MATRIX_HOMESERVER` points to your homeserver (include `https://`, no trailing slash). Check that `MATRIX_ACCESS_TOKEN` is valid — try it with curl:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+ https://your-server/_matrix/client/v3/account/whoami
+```
+
+If this returns your user info, the token is valid. If it returns an error, generate a new token.
+
+### "matrix-nio not installed" error
+
+**Cause**: The `matrix-nio` Python package is not installed.
+
+**Fix**: Install it:
+
+```bash
+pip install 'matrix-nio[e2e]'
+```
+
+Or with Hermes extras:
+
+```bash
+pip install 'hermes-agent[matrix]'
+```
+
+### Encryption errors / "could not decrypt event"
+
+**Cause**: Missing encryption keys, `libolm` not installed, or the bot's device isn't trusted.
+
+**Fix**:
+1. Verify `libolm` is installed on your system (see the E2EE section above).
+2. Make sure `MATRIX_ENCRYPTION=true` is set in your `.env`.
+3. In your Matrix client (Element), go to the bot's profile → **Sessions** → verify/trust the bot's device.
+4. If the bot just joined an encrypted room, it can only decrypt messages sent *after* it joined. Older messages are inaccessible.
+
+### Sync issues / bot falls behind
+
+**Cause**: Long-running tool executions can delay the sync loop, or the homeserver is slow.
+
+**Fix**: The sync loop automatically retries every 5 seconds on error. Check the Hermes logs for sync-related warnings. If the bot consistently falls behind, ensure your homeserver has adequate resources.
+
+### Bot is offline
+
+**Cause**: The Hermes gateway isn't running, or it failed to connect.
+
+**Fix**: Check that `hermes gateway` is running. Look at the terminal output for error messages. Common issues: wrong homeserver URL, expired access token, homeserver unreachable.
+
+### "User not allowed" / Bot ignores you
+
+**Cause**: Your User ID isn't in `MATRIX_ALLOWED_USERS`.
+
+**Fix**: Add your User ID to `MATRIX_ALLOWED_USERS` in `~/.hermes/.env` and restart the gateway. Use the full `@user:server` format.
+
+## Security
+
+:::warning
+Always set `MATRIX_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.
+:::
+
+For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md).
+
+## Notes
+
+- **Any homeserver**: Works with Synapse, Conduit, Dendrite, matrix.org, or any spec-compliant Matrix homeserver. No specific homeserver software required.
+- **Federation**: If you're on a federated homeserver, the bot can communicate with users from other servers — just add their full `@user:server` IDs to `MATRIX_ALLOWED_USERS`.
+- **Auto-join**: The bot automatically accepts room invites and joins. It starts responding immediately after joining.
+- **Media support**: Hermes can send and receive images, audio, video, and file attachments. Media is uploaded to your homeserver using the Matrix content repository API.
diff --git a/website/docs/user-guide/messaging/mattermost.md b/website/docs/user-guide/messaging/mattermost.md
new file mode 100644
index 000000000..f959bb872
--- /dev/null
+++ b/website/docs/user-guide/messaging/mattermost.md
@@ -0,0 +1,277 @@
+---
+sidebar_position: 8
+title: "Mattermost"
+description: "Set up Hermes Agent as a Mattermost bot"
+---
+
+# Mattermost Setup
+
+Hermes Agent integrates with Mattermost as a bot, letting you chat with your AI assistant through direct messages or team channels. Mattermost is a self-hosted, open-source Slack alternative — you run it on your own infrastructure, keeping full control of your data. The bot connects via Mattermost's REST API (v4) and WebSocket for real-time events, processes messages through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, file attachments, images, and slash commands.
+
+No external Mattermost library is required — the adapter uses `aiohttp`, which is already a Hermes dependency.
+
+Before setup, here's the part most people want to know: how Hermes behaves once it's in your Mattermost instance.
+
+## How Hermes Behaves
+
+| Context | Behavior |
+|---------|----------|
+| **DMs** | Hermes responds to every message. No `@mention` needed. Each DM has its own session. |
+| **Public/private channels** | Hermes responds when you `@mention` it. Without a mention, Hermes ignores the message. |
+| **Threads** | If `MATTERMOST_REPLY_MODE=thread`, Hermes replies in a thread under your message. Thread context stays isolated from the parent channel. |
+| **Shared channels with multiple users** | By default, Hermes isolates session history per user inside the channel. Two people talking in the same channel do not share one transcript unless you explicitly disable that. |
+
+:::tip
+If you want Hermes to reply as threaded conversations (nested under your original message), set `MATTERMOST_REPLY_MODE=thread`. The default is `off`, which sends flat messages in the channel.
+:::
+
+### Session Model in Mattermost
+
+By default:
+
+- each DM gets its own session
+- each thread gets its own session namespace
+- each user in a shared channel gets their own session inside that channel
+
+This is controlled by `config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+Set it to `false` only if you explicitly want one shared conversation for the entire channel:
+
+```yaml
+group_sessions_per_user: false
+```
+
+Shared sessions can be useful for a collaborative channel, but they also mean:
+
+- users share context growth and token costs
+- one person's long tool-heavy task can bloat everyone else's context
+- one person's in-flight run can interrupt another person's follow-up in the same channel
+
+This guide walks you through the full setup process — from creating your bot on Mattermost to sending your first message.
+
+## Step 1: Enable Bot Accounts
+
+Bot accounts must be enabled on your Mattermost server before you can create one.
+
+1. Log in to Mattermost as a **System Admin**.
+2. Go to **System Console** → **Integrations** → **Bot Accounts**.
+3. Set **Enable Bot Account Creation** to **true**.
+4. Click **Save**.
+
+:::info
+If you don't have System Admin access, ask your Mattermost administrator to enable bot accounts and create one for you.
+:::
+
+## Step 2: Create a Bot Account
+
+1. In Mattermost, click the **☰** menu (top-left) → **Integrations** → **Bot Accounts**.
+2. Click **Add Bot Account**.
+3. Fill in the details:
+ - **Username**: e.g., `hermes`
+ - **Display Name**: e.g., `Hermes Agent`
+ - **Description**: optional
+ - **Role**: `Member` is sufficient
+4. Click **Create Bot Account**.
+5. Mattermost will display the **bot token**. **Copy it immediately.**
+
+:::warning[Token shown only once]
+The bot token is only displayed once when you create the bot account. If you lose it, you'll need to regenerate it from the bot account settings. Never share your token publicly or commit it to Git — anyone with this token has full control of the bot.
+:::
+
+Store the token somewhere safe (a password manager, for example). You'll need it in Step 5.
+
+:::tip
+You can also use a **personal access token** instead of a bot account. Go to **Profile** → **Security** → **Personal Access Tokens** → **Create Token**. This is useful if you want Hermes to post as your own user rather than a separate bot user.
+:::
+
+## Step 3: Add the Bot to Channels
+
+The bot needs to be a member of any channel where you want it to respond:
+
+1. Open the channel where you want the bot.
+2. Click the channel name → **Add Members**.
+3. Search for your bot username (e.g., `hermes`) and add it.
+
+For DMs, simply open a direct message with the bot — it will be able to respond immediately.
+
+## Step 4: Find Your Mattermost User ID
+
+Hermes Agent uses your Mattermost User ID to control who can interact with the bot. To find it:
+
+1. Click your **avatar** (top-left corner) → **Profile**.
+2. Your User ID is displayed in the profile dialog — click it to copy.
+
+Your User ID is a 26-character alphanumeric string like `3uo8dkh1p7g1mfk49ear5fzs5c`.
+
+:::warning
+Your User ID is **not** your username. The username is what appears after `@` (e.g., `@alice`). The User ID is a long alphanumeric identifier that Mattermost uses internally.
+:::
+
+**Alternative**: You can also get your User ID via the API:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+ https://your-mattermost-server/api/v4/users/me | jq .id
+```
+
+:::tip
+To get a **Channel ID**: click the channel name → **View Info**. The Channel ID is shown in the info panel. You'll need this if you want to set a home channel manually.
+:::
+
+## Step 5: Configure Hermes Agent
+
+### Option A: Interactive Setup (Recommended)
+
+Run the guided setup command:
+
+```bash
+hermes gateway setup
+```
+
+Select **Mattermost** when prompted, then paste your server URL, bot token, and user ID when asked.
+
+### Option B: Manual Configuration
+
+Add the following to your `~/.hermes/.env` file:
+
+```bash
+# Required
+MATTERMOST_URL=https://mm.example.com
+MATTERMOST_TOKEN=***
+MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
+
+# Multiple allowed users (comma-separated)
+# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e
+
+# Optional: reply mode (thread or off, default: off)
+# MATTERMOST_REPLY_MODE=thread
+```
+
+Optional behavior settings in `~/.hermes/config.yaml`:
+
+```yaml
+group_sessions_per_user: true
+```
+
+- `group_sessions_per_user: true` keeps each participant's context isolated inside shared channels and threads
+
+### Start the Gateway
+
+Once configured, start the Mattermost gateway:
+
+```bash
+hermes gateway
+```
+
+The bot should connect to your Mattermost server within a few seconds. Send it a message — either a DM or in a channel where it's been added — to test.
+
+:::tip
+You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details.
+:::
+
+## Home Channel
+
+You can designate a "home channel" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it:
+
+### Using the Slash Command
+
+Type `/sethome` in any Mattermost channel where the bot is present. That channel becomes the home channel.
+
+### Manual Configuration
+
+Add this to your `~/.hermes/.env`:
+
+```bash
+MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn
+```
+
+Replace the ID with the actual channel ID (click the channel name → View Info → copy the ID).
+
+## Reply Mode
+
+The `MATTERMOST_REPLY_MODE` setting controls how Hermes posts responses:
+
+| Mode | Behavior |
+|------|----------|
+| `off` (default) | Hermes posts flat messages in the channel, like a normal user. |
+| `thread` | Hermes replies in a thread under your original message. Keeps channels clean when there's lots of back-and-forth. |
+
+Set it in your `~/.hermes/.env`:
+
+```bash
+MATTERMOST_REPLY_MODE=thread
+```
+
+## Troubleshooting
+
+### Bot is not responding to messages
+
+**Cause**: The bot is not a member of the channel, or `MATTERMOST_ALLOWED_USERS` doesn't include your User ID.
+
+**Fix**: Add the bot to the channel (channel name → Add Members → search for the bot). Verify your User ID is in `MATTERMOST_ALLOWED_USERS`. Restart the gateway.
+
+### 403 Forbidden errors
+
+**Cause**: The bot token is invalid, or the bot doesn't have permission to post in the channel.
+
+**Fix**: Check that `MATTERMOST_TOKEN` in your `.env` file is correct. Make sure the bot account hasn't been deactivated. Verify the bot has been added to the channel. If using a personal access token, ensure your account has the required permissions.
+
+### WebSocket disconnects / reconnection loops
+
+**Cause**: Network instability, Mattermost server restarts, or firewall/proxy issues with WebSocket connections.
+
+**Fix**: The adapter automatically reconnects with exponential backoff (2s → 60s). Check your server's WebSocket configuration — reverse proxies (nginx, Apache) need WebSocket upgrade headers configured. Verify no firewall is blocking WebSocket connections on your Mattermost server.
+
+For nginx, ensure your config includes:
+
+```nginx
+location /api/v4/websocket {
+ proxy_pass http://mattermost-backend;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "upgrade";
+ proxy_read_timeout 600s;
+}
+```
+
+### "Failed to authenticate" on startup
+
+**Cause**: The token or server URL is incorrect.
+
+**Fix**: Verify `MATTERMOST_URL` points to your Mattermost server (include `https://`, no trailing slash). Check that `MATTERMOST_TOKEN` is valid — try it with curl:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+ https://your-server/api/v4/users/me
+```
+
+If this returns your bot's user info, the token is valid. If it returns an error, regenerate the token.
+
+### Bot is offline
+
+**Cause**: The Hermes gateway isn't running, or it failed to connect.
+
+**Fix**: Check that `hermes gateway` is running. Look at the terminal output for error messages. Common issues: wrong URL, expired token, Mattermost server unreachable.
+
+### "User not allowed" / Bot ignores you
+
+**Cause**: Your User ID isn't in `MATTERMOST_ALLOWED_USERS`.
+
+**Fix**: Add your User ID to `MATTERMOST_ALLOWED_USERS` in `~/.hermes/.env` and restart the gateway. Remember: the User ID is a 26-character alphanumeric string, not your `@username`.
+
+## Security
+
+:::warning
+Always set `MATTERMOST_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.
+:::
+
+For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md).
+
+## Notes
+
+- **Self-hosted friendly**: Works with any self-hosted Mattermost instance. No Mattermost Cloud account or subscription required.
+- **No extra dependencies**: The adapter uses `aiohttp` for HTTP and WebSocket, which is already included with Hermes Agent.
+- **Team Edition compatible**: Works with both Mattermost Team Edition (free) and Enterprise Edition.
diff --git a/website/docs/user-guide/messaging/sms.md b/website/docs/user-guide/messaging/sms.md
new file mode 100644
index 000000000..0aa835ffe
--- /dev/null
+++ b/website/docs/user-guide/messaging/sms.md
@@ -0,0 +1,175 @@
+---
+sidebar_position: 8
+title: "SMS (Twilio)"
+description: "Set up Hermes Agent as an SMS chatbot via Twilio"
+---
+
+# SMS Setup (Twilio)
+
+Hermes connects to SMS through the [Twilio](https://www.twilio.com/) API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages.
+
+:::info Shared Credentials
+The SMS gateway shares credentials with the optional [telephony skill](/docs/reference/skills-catalog). If you've already set up Twilio for voice calls or one-off SMS, the gateway works with the same `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER`.
+:::
+
+---
+
+## Prerequisites
+
+- **Twilio account** — [Sign up at twilio.com](https://www.twilio.com/try-twilio) (free trial available)
+- **A Twilio phone number** with SMS capability
+- **A publicly accessible server** — Twilio sends webhooks to your server when SMS arrives
+- **aiohttp** — `pip install 'hermes-agent[sms]'`
+
+---
+
+## Step 1: Get Your Twilio Credentials
+
+1. Go to the [Twilio Console](https://console.twilio.com/)
+2. Copy your **Account SID** and **Auth Token** from the dashboard
+3. Go to **Phone Numbers → Manage → Active Numbers** — note your phone number in E.164 format (e.g., `+15551234567`)
+
+---
+
+## Step 2: Configure Hermes
+
+### Interactive setup (recommended)
+
+```bash
+hermes gateway setup
+```
+
+Select **SMS (Twilio)** from the platform list. The wizard will prompt for your credentials.
+
+### Manual setup
+
+Add to `~/.hermes/.env`:
+
+```bash
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=your_auth_token_here
+TWILIO_PHONE_NUMBER=+15551234567
+
+# Security: restrict to specific phone numbers (recommended)
+SMS_ALLOWED_USERS=+15559876543,+15551112222
+
+# Optional: set a home channel for cron job delivery
+SMS_HOME_CHANNEL=+15559876543
+```
+
+---
+
+## Step 3: Configure Twilio Webhook
+
+Twilio needs to know where to send incoming messages. In the [Twilio Console](https://console.twilio.com/):
+
+1. Go to **Phone Numbers → Manage → Active Numbers**
+2. Click your phone number
+3. Under **Messaging → A MESSAGE COMES IN**, set:
+ - **Webhook**: `https://your-server:8080/webhooks/twilio`
+ - **HTTP Method**: `POST`
+
+:::tip Exposing Your Webhook
+If you're running Hermes locally, use a tunnel to expose the webhook:
+
+```bash
+# Using cloudflared
+cloudflared tunnel --url http://localhost:8080
+
+# Using ngrok
+ngrok http 8080
+```
+
+Set the resulting public URL as your Twilio webhook.
+:::
+
+The webhook port defaults to `8080`. Override with:
+
+```bash
+SMS_WEBHOOK_PORT=3000
+```
+
+---
+
+## Step 4: Start the Gateway
+
+```bash
+hermes gateway
+```
+
+You should see:
+
+```
+[sms] Twilio webhook server listening on port 8080, from: +1555***4567
+```
+
+Text your Twilio number — Hermes will respond via SMS.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TWILIO_ACCOUNT_SID` | Yes | Twilio Account SID (starts with `AC`) |
+| `TWILIO_AUTH_TOKEN` | Yes | Twilio Auth Token |
+| `TWILIO_PHONE_NUMBER` | Yes | Your Twilio phone number (E.164 format) |
+| `SMS_WEBHOOK_PORT` | No | Webhook listener port (default: `8080`) |
+| `SMS_ALLOWED_USERS` | No | Comma-separated E.164 phone numbers allowed to chat |
+| `SMS_ALLOW_ALL_USERS` | No | Set to `true` to allow anyone (not recommended) |
+| `SMS_HOME_CHANNEL` | No | Phone number for cron job / notification delivery |
+| `SMS_HOME_CHANNEL_NAME` | No | Display name for the home channel (default: `Home`) |
+
+---
+
+## SMS-Specific Behavior
+
+- **Plain text only** — Markdown is automatically stripped since SMS renders it as literal characters
+- **1600 character limit** — Longer responses are split across multiple messages at natural boundaries (newlines, then spaces)
+- **Echo prevention** — Messages from your own Twilio number are ignored to prevent loops
+- **Phone number redaction** — Phone numbers are redacted in logs for privacy
+
+---
+
+## Security
+
+**The gateway denies all users by default.** Configure an allowlist:
+
+```bash
+# Recommended: restrict to specific phone numbers
+SMS_ALLOWED_USERS=+15559876543,+15551112222
+
+# Or allow all (NOT recommended for bots with terminal access)
+SMS_ALLOW_ALL_USERS=true
+```
+
+:::warning
+SMS has no built-in encryption. Don't use SMS for sensitive operations unless you understand the security implications. For sensitive use cases, prefer Signal or Telegram.
+:::
+
+---
+
+## Troubleshooting
+
+### Messages not arriving
+
+1. Check your Twilio webhook URL is correct and publicly accessible
+2. Verify `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are correct
+3. Check the Twilio Console → **Monitor → Logs → Messaging** for delivery errors
+4. Ensure your phone number is in `SMS_ALLOWED_USERS` (or `SMS_ALLOW_ALL_USERS=true`)
+
+### Replies not sending
+
+1. Check `TWILIO_PHONE_NUMBER` is set correctly (E.164 format with `+`)
+2. Verify your Twilio account has SMS-capable numbers
+3. Check Hermes gateway logs for Twilio API errors
+
+### Webhook port conflicts
+
+If port 8080 is already in use, change it:
+
+```bash
+SMS_WEBHOOK_PORT=3001
+```
+
+Update the webhook URL in Twilio Console to match.
diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md
index d31cc1757..d6d14db8d 100644
--- a/website/docs/user-guide/security.md
+++ b/website/docs/user-guide/security.md
@@ -277,6 +277,25 @@ Error messages from MCP tools are sanitized before being returned to the LLM. Th
- Bearer tokens
- `token=`, `key=`, `API_KEY=`, `password=`, `secret=` parameters
+### Website Access Policy
+
+You can restrict which websites the agent can access through its web and browser tools. This is useful for preventing the agent from accessing internal services, admin panels, or other sensitive URLs.
+
+```yaml
+# In ~/.hermes/config.yaml
+website_blocklist:
+ enabled: true
+ domains:
+ - "*.internal.company.com"
+ - "admin.example.com"
+ shared_files:
+ - "/etc/hermes/blocked-sites.txt"
+```
+
+When a blocked URL is requested, the tool returns an error explaining the domain is blocked by policy. The blocklist is enforced across `web_search`, `web_extract`, `browser_navigate`, and all URL-capable tools.
+
+See [Website Blocklist](/docs/user-guide/configuration#website-blocklist) in the configuration guide for full details.
+
### Context File Injection Protection
Context files (AGENTS.md, .cursorrules, SOUL.md) are scanned for prompt injection before being included in the system prompt. The scanner checks for:
diff --git a/website/sidebars.ts b/website/sidebars.ts
index ac46028b4..935cdaffe 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -48,6 +48,9 @@ const sidebars: SidebarsConfig = {
'user-guide/messaging/signal',
'user-guide/messaging/email',
'user-guide/messaging/homeassistant',
+ 'user-guide/messaging/mattermost',
+ 'user-guide/messaging/matrix',
+ 'user-guide/messaging/dingtalk',
],
},
{