style: format valkey error message

fix: skip valkey-glide on Windows
fix(mcp): harden remote SSE fallback (#2324 )
2026-07-17 09:56:06 +00:00 · 2026-07-13 00:17:51 +08:00 · 2026-07-13 00:11:34 +08:00 · 2026-07-11 22:08:37 +08:00 · 2026-07-09 14:13:04 -04:00 · 2026-07-08 06:59:16 +08:00
41 changed files with 2967 additions and 93 deletions
@@ -51,7 +51,7 @@ LangBot is an **open-source, production-grade platform** for building AI-powered

 [→ Learn more about all features](https://link.langbot.app/en/docs/features)

-📍 Practical guides: [deploy a multi-platform AI bot in 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connect DeepSeek to WeChat, Discord, and Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [run a Dify Agent in Discord, Telegram, and Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), and [build an n8n-powered chatbot](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 Practical guides: [deploy a multi-platform AI bot in 5 minutes](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connect DeepSeek to WeChat, Discord, and Telegram](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [run a Dify Agent in Discord, Telegram, and Slack](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/), and [build an n8n-powered chatbot](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -51,7 +51,7 @@ LangBot 是一个**开源的生产级平台**，用于构建 AI 驱动的即时

 [→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)

-📍 实践指南：[5 分钟部署多平台 AI 机器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[将 DeepSeek 接入微信、企业微信与 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[让 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 构建多平台 AI 聊天机器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+📍 实践指南：[5 分钟部署多平台 AI 机器人](https://langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[将 DeepSeek 接入微信、企业微信与 Discord](https://langbot.app/zh/blog/connect-deepseek-to-wechat/)、[让 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 构建多平台 AI 聊天机器人](https://langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。

 ---

@@ -50,7 +50,7 @@ LangBot es una **plataforma de código abierto y grado de producción** para con

 [→ Conocer más sobre todas las funcionalidades](https://link.langbot.app/en/docs/features)

-📍 Guías prácticas: [desplegar un bot de IA multiplataforma en 5 minutos](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [conectar DeepSeek a WeChat, Discord y Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [ejecutar un Dify Agent en Discord, Telegram y Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) y [crear un chatbot con n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 Guías prácticas: [desplegar un bot de IA multiplataforma en 5 minutos](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [conectar DeepSeek a WeChat, Discord y Telegram](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [ejecutar un Dify Agent en Discord, Telegram y Slack](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/) y [crear un chatbot con n8n](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -50,7 +50,7 @@ LangBot est une **plateforme open-source de niveau production** pour créer des

 [→ En savoir plus sur toutes les fonctionnalités](https://link.langbot.app/en/docs/features)

-📍 Guides pratiques : [déployer un bot IA multiplateforme en 5 minutes](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connecter DeepSeek à WeChat, Discord et Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [exécuter un Dify Agent dans Discord, Telegram et Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) et [créer un chatbot avec n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 Guides pratiques : [déployer un bot IA multiplateforme en 5 minutes](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [connecter DeepSeek à WeChat, Discord et Telegram](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [exécuter un Dify Agent dans Discord, Telegram et Slack](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/) et [créer un chatbot avec n8n](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -50,7 +50,7 @@ LangBot は、AI搭載のインスタントメッセージングボットを構

 [→ すべての機能について詳しく見る](https://link.langbot.app/ja/docs/features)

-📍 実践ガイド: [5分でマルチプラットフォームAIボットをデプロイ](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/)、[DeepSeekをWeChat・Discord・Telegramに接続](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/)、[Dify AgentをDiscord・Telegram・Slackで動かす](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/)、[n8n連携チャットボットを構築](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/)。
+📍 実践ガイド: [5分でマルチプラットフォームAIボットをデプロイ](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/)、[DeepSeekをWeChat・Discord・Telegramに接続](https://langbot.app/en/blog/connect-deepseek-to-wechat/)、[Dify AgentをDiscord・Telegram・Slackで動かす](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/)、[n8n連携チャットボットを構築](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/)。

 ---

@@ -50,7 +50,7 @@ LangBot은 AI 기반 인스턴트 메시징 봇을 구축하기 위한 **오픈

 [→ 모든 기능 자세히 보기](https://link.langbot.app/en/docs/features)

-📍 실전 가이드: [5분 만에 멀티 플랫폼 AI 봇 배포하기](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [DeepSeek를 WeChat, Discord, Telegram에 연결하기](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [Dify Agent를 Discord, Telegram, Slack에서 실행하기](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/), [n8n 기반 챗봇 만들기](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 실전 가이드: [5분 만에 멀티 플랫폼 AI 봇 배포하기](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [DeepSeek를 WeChat, Discord, Telegram에 연결하기](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [Dify Agent를 Discord, Telegram, Slack에서 실행하기](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/), [n8n 기반 챗봇 만들기](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -50,7 +50,7 @@ LangBot — это **платформа с открытым исходным к

 [→ Подробнее обо всех возможностях](https://link.langbot.app/en/docs/features)

-📍 Практические руководства: [развернуть мультиплатформенного ИИ-бота за 5 минут](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [подключить DeepSeek к WeChat, Discord и Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [запустить Dify Agent в Discord, Telegram и Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) и [создать чат-бота на n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 Практические руководства: [развернуть мультиплатформенного ИИ-бота за 5 минут](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [подключить DeepSeek к WeChat, Discord и Telegram](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [запустить Dify Agent в Discord, Telegram и Slack](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/) и [создать чат-бота на n8n](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -52,7 +52,7 @@ LangBot 是一個**開源的生產級平台**，用於建構 AI 驅動的即時

 [→ 了解更多功能特性](https://link.langbot.app/zh/docs/features)

-📍 實踐指南：[5 分鐘部署多平台 AI 機器人](https://blog.langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[將 DeepSeek 接入微信、企業微信與 Discord](https://blog.langbot.app/zh/blog/connect-deepseek-to-wechat/)、[讓 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://blog.langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 建構多平台 AI 聊天機器人](https://blog.langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。
+📍 實踐指南：[5 分鐘部署多平台 AI 機器人](https://langbot.app/zh/blog/deploy-ai-bot-in-5-minutes/)、[將 DeepSeek 接入微信、企業微信與 Discord](https://langbot.app/zh/blog/connect-deepseek-to-wechat/)、[讓 Dify Agent 跑在 Discord、Telegram 和 Slack 上](https://langbot.app/zh/blog/dify-agent-discord-telegram-slack/)，以及[用 n8n 建構多平台 AI 聊天機器人](https://langbot.app/zh/blog/n8n-multi-platform-ai-chatbot/)。

 ---

@@ -50,7 +50,7 @@ LangBot là một **nền tảng mã nguồn mở, cấp sản xuất** để x

 [→ Tìm hiểu thêm về tất cả tính năng](https://link.langbot.app/en/docs/features)

-📍 Hướng dẫn thực hành: [triển khai bot AI đa nền tảng trong 5 phút](https://blog.langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [kết nối DeepSeek với WeChat, Discord và Telegram](https://blog.langbot.app/en/blog/connect-deepseek-to-wechat/), [chạy Dify Agent trên Discord, Telegram và Slack](https://blog.langbot.app/en/blog/dify-agent-discord-telegram-slack/) và [xây dựng chatbot với n8n](https://blog.langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).
+📍 Hướng dẫn thực hành: [triển khai bot AI đa nền tảng trong 5 phút](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes/), [kết nối DeepSeek với WeChat, Discord và Telegram](https://langbot.app/en/blog/connect-deepseek-to-wechat/), [chạy Dify Agent trên Discord, Telegram và Slack](https://langbot.app/en/blog/dify-agent-discord-telegram-slack/) và [xây dựng chatbot với n8n](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot/).

 ---

@@ -0,0 +1,171 @@
+# Valkey Search Vector Database Integration
+
+This document describes how to use **Valkey Search** (the search/vector module bundled in
+`valkey/valkey-bundle`) as the vector database backend for LangBot's knowledge base (RAG)
+feature.
+
+## What is Valkey Search?
+
+**Valkey Search** is a module that adds vector similarity search and full-text search to
+[Valkey](https://valkey.io/), the open-source, BSD-licensed in-memory data store forked from
+Redis OSS. It is distributed in the `valkey/valkey-bundle` image alongside other modules
+(JSON, Bloom, LDAP).
+
+LangBot talks to Valkey through the official [`valkey-glide`](https://pypi.org/project/valkey-glide/)
+client (Rust core + async Python wrapper), using its native `ft` (search) command namespace.
+
+### Key Features
+
+- **Vector search**: ANN via HNSW or exact via FLAT, with COSINE / L2 / IP distance metrics
+- **Full-text search**: term, prefix and phrase matching over indexed text fields
+- **Hybrid search**: a metadata/text filter pre-selects candidates, then KNN ranks them
+- **In-memory speed**: vectors and documents are stored as Valkey HASH keys
+- **Auth + TLS**: optional username/password and TLS for production (toB / SaaS) deployments
+
+### Licensing
+
+- Valkey core and the Search module are **BSD-3-Clause**.
+- The `valkey-glide` client is **Apache-2.0**.
+
+Both are compatible with LangBot.
+
+## Installation
+
+Valkey Search support is included automatically on Linux and macOS. The official `valkey-glide`
+client does not currently publish a Windows package, so LangBot skips this optional dependency on
+Windows; LangBot remains usable there, but the Valkey Search backend is unavailable. To install the
+client manually on a supported platform:
+
+```bash
+pip install 'valkey-glide>=2.4.1,<3.0.0'
+```
+
+You also need a running Valkey server with the Search module loaded. The simplest way is the
+bundled image:
+
+```bash
+# Run valkey-bundle (includes the Search module) on host port 6380
+podman run -d --name valkey-test-langbot -p 6380:6379 valkey/valkey-bundle:9.1.0
+# (docker run ... works identically)
+```
+
+`valkey-bundle` ships multi-arch images (linux/amd64 + linux/arm64), so it runs on both CI
+(x86_64) and Apple-silicon dev machines.
+
+## Configuration
+
+Valkey Search is **opt-in and disabled by default** — the default `vdb.use` stays `chroma`,
+so existing single-process deployments are unaffected. To enable it, edit your `config.yaml`:
+
+```yaml
+vdb:
+  use: valkey_search
+  valkey_search:
+    host: 'localhost'
+    port: 6379            # use 6380 if you started the container as shown above
+    db: 0
+    password: ''          # optional (ACL / requirepass) — never logged
+    username: ''          # optional (ACL user)
+    tls: false            # optional (toB / SaaS)
+    index_algorithm: 'HNSW'   # HNSW | FLAT
+    distance_metric: 'COSINE' # COSINE | L2 | IP
+    request_timeout: 5000     # per-request timeout in ms
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `host` | `localhost` | Valkey host |
+| `port` | `6379` | Valkey port |
+| `db` | `0` | Logical database id |
+| `password` | `''` | Optional auth password (empty = no auth). Never logged. |
+| `username` | `''` | Optional ACL username. Configuring a username without a password fails closed (raises) rather than connecting unauthenticated. |
+| `tls` | `false` | Enable TLS for the connection |
+| `index_algorithm` | `HNSW` | `HNSW` (approximate) or `FLAT` (exact) |
+| `distance_metric` | `COSINE` | `COSINE`, `L2`, or `IP` |
+| `request_timeout` | `5000` | Per-request timeout in milliseconds. The valkey-glide default (250ms) is too low for vector KNN under load; raise it further for remote/cross-AZ Valkey. |
+
+### Connection behavior
+
+The backend uses a **lazy** connection (`lazy_connect=True`): the client is created on first
+use and the connection is deferred to the first command. A misconfigured or unreachable Valkey
+server therefore does **not** block LangBot from booting — knowledge-base operations will error
+at call time instead, and you can recover by switching `vdb.use` back to another backend.
+
+The connection sets a fixed `client_name` of `langbot_vector_client` so it is identifiable in
+`CLIENT LIST` and monitoring dashboards.
+
+## Supported search types
+
+| Type | Behavior |
+|------|----------|
+| `vector` | Pure KNN over the embedding field |
+| `full_text` | Term/phrase match over the indexed `document` text field |
+| `hybrid` | Metadata/text filter **pre-selects** candidates, then KNN ranks them |
+
+### ⚠️ Important: `vector_weight` is NOT honored
+
+Valkey Search hybrid queries follow a **filter-then-KNN** model: the filter (and/or full-text
+clause) narrows the candidate set, and the KNN stage ranks the survivors by vector distance.
+There is **no native weighted score fusion** (unlike, e.g., SeekDB's RRF boost).
+
+For interface compatibility the backend still accepts a `vector_weight` argument, but it is
+**ignored** — passing different weights does not change result ordering. The first time a
+non-default weight is supplied, the backend logs a one-time warning.
+
+If weighted hybrid ranking is needed in the future, it can be added **application-side** (run
+vector KNN and full-text search separately and blend the scores). That is intentionally out of
+scope for this integration.
+
+## Metadata & filtering
+
+Documents are stored as Valkey HASH keys under the prefix `kb:{collection}:{id}` with fields:
+
+- `vector` — the embedding, packed as little-endian FLOAT32
+- `document` — the raw text (indexed as TEXT for full-text/hybrid search)
+- `file_id` — promoted to an indexed TAG field so it is filterable
+- `metadata_json` — the full metadata dict, preserved verbatim as JSON
+
+Only **indexed** fields are filterable. Currently that is `file_id`. Filters referencing
+non-indexed metadata keys are dropped with a warning (the same pragmatism used by the Milvus
+and pgvector backends). All other metadata still round-trips intact via `metadata_json`.
+
+Supported filter operators (canonical Chroma-style `where` syntax): `$eq`, `$ne`, `$gt`,
+`$gte`, `$lt`, `$lte`, `$in`, `$nin`. Multiple top-level keys are AND-ed.
+
+## Testing
+
+Unit tests (filter mapping, float32 packing, reply parsing, import guard) run in the fast lane
+with no server:
+
+```bash
+uv run pytest tests/unit_tests/vector/test_valkey_search_filter.py -q
+```
+
+Integration tests are **slow-gated** on `TEST_VALKEY_URL` and require a running server:
+
+```bash
+podman run -d --name valkey-test-langbot -p 6380:6379 valkey/valkey-bundle:9.1.0
+TEST_VALKEY_URL=valkey://localhost:6380 \
+    uv run pytest tests/integration/vector/test_valkey_search.py -m slow -q
+```
+
+The default upstream fast CI lane (`-m "not slow"`) skips these, matching the existing
+PostgreSQL migration-test precedent.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---------|-------------|
+| Tests skip with "Valkey Search module not available" | The server is plain Valkey without the Search module. Use the `valkey/valkey-bundle` image. |
+| `ConnectionError` at call time | Check `host`/`port`/auth; remember `lazy_connect` defers errors to first use. |
+| Empty search results right after insert | The Search indexer is asynchronous; results become visible within a short delay. The integration tests poll/retry to account for this. |
+| Hybrid ranking ignores `vector_weight` | Expected — see the caveat above. |
+
+## Production considerations
+
+- **Cluster mode**: Valkey Search in cluster mode uses an additional coordination port. This
+  integration targets standalone mode; cluster support is a future consideration.
+- **Persistence**: configure Valkey RDB/AOF persistence if the knowledge base must survive
+  restarts; otherwise an in-memory store is ephemeral.
+- **Security**: set `password`/`username` and `tls: true` for any non-local deployment.
+  Credentials are never written to logs.
@@ -70,7 +70,7 @@ dependencies = [
    "chromadb>=1.0.0,<2.0.0",
    "qdrant-client (>=1.15.1,<2.0.0)",
    "pyseekdb==1.1.0.post3",
-    "langbot-plugin==0.4.7",
+    "langbot-plugin==0.4.13",
    "asyncpg>=0.30.0",
    "line-bot-sdk>=3.19.0",
    "matrix-nio>=0.25.2",
@@ -80,6 +80,7 @@ dependencies = [
    "pgvector>=0.4.1",
    "botocore>=1.42.39",
    "litellm>=1.0.0",
+    "valkey-glide>=2.4.1,<3.0.0; sys_platform != 'win32'", # No Windows wheels are published
 ]
 keywords = [
    "bot",
@@ -96,6 +96,19 @@ class MCPRouterGroup(group.RouterGroup):
            except Exception as e:
                return self.http_status(500, -1, f'Failed to get resource templates: {str(e)}')

+        @self.route('/servers/<path:server_name>/logs', methods=['GET'], auth_type=group.AuthType.USER_TOKEN)
+        async def _(server_name: str) -> str:
+            """Get logs from an MCP server"""
+            server_name = unquote(server_name)
+            try:
+                limit = int(quart.request.args.get('limit', 200))
+            except (TypeError, ValueError):
+                limit = 200
+            limit = min(limit, 500)
+            level = quart.request.args.get('level') or None
+            logs = await self.ap.mcp_service.get_mcp_server_logs(server_name, limit=limit, level=level)
+            return self.success(data={'logs': logs})
+
        @self.route('/servers/<path:server_name>/resources/read', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
        async def _(server_name: str) -> str:
            """Read a resource from an MCP server"""
@@ -188,10 +188,22 @@ class MCPService:
            persisted_session = runtime_mcp_session

            async def _refresh_and_report() -> None:
-                if persisted_session.status == MCPSessionStatus.ERROR:
+                # Testing a persisted server should REUSE its live shared-session
+                # process, not rebuild it. Try a lightweight refresh (a real
+                # list_tools probe over the existing connection) first; only fall
+                # back to a full start() when the session has no live connection
+                # to probe (never connected, or the process is actually gone).
+                needs_start = persisted_session.status == MCPSessionStatus.ERROR or persisted_session.session is None
+                if needs_start:
                    await persisted_session.start()
                else:
-                    await persisted_session.refresh()
+                    try:
+                        await persisted_session.refresh()
+                    except Exception:
+                        # The live connection was stale/dropped: reconnect once
+                        # (reusing the live managed process where possible) and
+                        # re-probe, instead of reporting a false failure.
+                        await persisted_session.start()
                # Surface the discovered tools so the config page can render them
                # even for an already-hosted server.
                ctx.metadata['runtime_info'] = persisted_session.get_runtime_info_dict()
@@ -232,3 +244,19 @@ class MCPService:
            context=ctx,
        )
        return wrapper.id
+
+    async def get_mcp_server_logs(self, server_name: str, limit: int = 200, level: str | None = None) -> list[dict]:
+        """Get recent log lines captured from the MCP server's stderr."""
+        session = self.ap.tool_mgr.mcp_tool_loader.get_session(server_name)
+        if not session:
+            return []
+
+        # Get logs from the session's buffer
+        logs = list(session._log_buffer)
+
+        # Filter by level if specified
+        if level:
+            logs = [log for log in logs if log.get('level') == level]
+
+        # Return the most recent 'limit' logs
+        return logs[-limit:]
@@ -6,7 +6,7 @@ import json
 import re
 import time
 import typing
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 import traceback
 from langbot_plugin.api.entities.events import pipeline_query
 import sqlalchemy
@@ -18,6 +18,7 @@ from mcp import ClientSession, StdioServerParameters, types as mcp_types
 from mcp.client.stdio import stdio_client
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.exceptions import McpError
 from pydantic import AnyUrl

 from .. import loader
@@ -25,7 +26,7 @@ from ....core import app
 import langbot_plugin.api.entities.builtin.resource.tool as resource_tool
 import langbot_plugin.api.entities.builtin.provider.message as provider_message
 from ....entity.persistence import mcp as persistence_mcp
-from .mcp_stdio import BoxStdioSessionRuntime, MCPServerBoxConfig, MCPSessionErrorPhase  # noqa: F401
+from .mcp_stdio import BoxStdioSessionRuntime, MCPServerBoxConfig, MCPSessionErrorPhase, _ColdStartRetry  # noqa: F401

 # Synthesized LLM tools for MCP resources (not from server tools/list).
 # Dispatched in MCPLoader.invoke_tool; placeholder func on LLMTool is never used.
@@ -185,6 +186,16 @@ class MCPSessionStatus(enum.Enum):
    ERROR = 'error'


+class _TransportReconnect(Exception):
+    """Internal signal: the Box stdio WS transport dropped but the managed
+    process is still alive. Triggers a lightweight transport reconnect that
+    reuses the live process, instead of a full process rebuild.
+
+    Reconnect attempts are NOT counted toward the fatal retry budget, so a
+    long-lived session can survive arbitrarily many transient drops.
+    """
+
+
 class RuntimeMCPSession:
    """运行时 MCP 会话"""

@@ -254,6 +265,16 @@ class RuntimeMCPSession:
        self._lifecycle_task = None
        self._shutdown_event = asyncio.Event()
        self._ready_event = asyncio.Event()
+        # Set transiently when a WS transport drop should NOT stop the managed
+        # process (it will be re-attached on the next initialize()).
+        self._preserve_managed_process = False
+
+        # Log buffer for capturing stderr from Box managed process (maxlen=500 keeps
+        # recent lines without unbounded memory growth)
+        import collections as _collections
+
+        self._log_buffer: _collections.deque = _collections.deque(maxlen=500)
+        self._last_stderr_text: str = ''

        self._box_stdio_runtime = BoxStdioSessionRuntime(self)
        self.box_config = self._box_stdio_runtime.config
@@ -315,23 +336,34 @@ class RuntimeMCPSession:

        await self.session.initialize()

-    async def _init_streamable_http_server(self):
-        transport = await self.exit_stack.enter_async_context(
-            streamable_http_client(
+    @asynccontextmanager
+    async def _streamable_http_session(self) -> typing.AsyncIterator[ClientSession]:
+        """Enter a fully initialized Streamable HTTP session as one context.
+
+        Initialization must happen inside the same context manager that owns the
+        MCP transport. The SDK reports request failures by cancelling the host
+        task and raises the real HTTP error from its TaskGroup during context
+        exit. Keeping these nested contexts together guarantees a failed
+        ``__aenter__`` unwinds immediately, so callers see the HTTPStatusError
+        instead of a detached CancelledError. It also owns the injected HTTPX
+        client, which the MCP SDK deliberately does not close for callers.
+        """
+        async with httpx.AsyncClient(
+            headers=self.server_config.get('headers', {}),
+            timeout=self.server_config.get('timeout', 10),
+            follow_redirects=True,
+        ) as http_client:
+            async with streamable_http_client(
                self.server_config['url'],
-                http_client=httpx.AsyncClient(
-                    headers=self.server_config.get('headers', {}),
-                    timeout=self.server_config.get('timeout', 10),
-                    follow_redirects=True,
-                ),
-            )
-        )
+                http_client=http_client,
+            ) as transport:
+                read, write, _ = transport
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    yield session

-        read, write, _ = transport
-
-        self.session = await self.exit_stack.enter_async_context(ClientSession(read, write))
-
-        await self.session.initialize()
+    async def _init_streamable_http_server(self):
+        self.session = await self.exit_stack.enter_async_context(self._streamable_http_session())

    async def _init_remote_server(self):
        """Connect to a remote MCP server, auto-detecting the transport.
@@ -346,9 +378,15 @@ class RuntimeMCPSession:
            await self._init_streamable_http_server()
            return
        except Exception as e:
+            if not self._should_fallback_to_sse(e):
+                self.ap.logger.info(
+                    f'MCP server {self.server_name}: Streamable HTTP transport failed '
+                    f'({self._describe_exception(e)}); not falling back to SSE'
+                )
+                raise
            self.ap.logger.info(
-                f'MCP server {self.server_name}: Streamable HTTP transport failed '
-                f'({self._describe_exception(e)}), falling back to SSE'
+                f'MCP server {self.server_name}: Streamable HTTP initialize failed with a compatible HTTP status '
+                f'({self._describe_exception(e)}), falling back to legacy SSE'
            )

        # The Streamable HTTP attempt may have partially entered the transport /
@@ -399,11 +437,39 @@ class RuntimeMCPSession:
                    task.cancel()
                for task in done:
                    if task is monitor_task and not self._shutdown_event.is_set():
+                        # The monitor completed. This is EITHER the managed
+                        # process actually exiting OR just the WS transport
+                        # dropping while the process stays alive in the Box
+                        # runtime. Re-check the real process state so a
+                        # transient transport drop reconnects (reusing the live
+                        # process) instead of tearing the process down and
+                        # running a full rebuild+backoff cycle.
+                        process_still_running = False
+                        try:
+                            process_still_running = await self._box_stdio_runtime._managed_process_is_running()
+                        except Exception:
+                            process_still_running = False
+                        if process_still_running:
+                            self.ap.logger.info(
+                                f'MCP server {self.server_name}: transport dropped but '
+                                f'managed process is still running; reconnecting transport'
+                            )
+                            self.error_phase = MCPSessionErrorPhase.RELAY_CONNECT
+                            # Preserve the live process across the finally-block
+                            # cleanup: only the WS transport should be torn down.
+                            self._preserve_managed_process = True
+                            raise _TransportReconnect('Box managed process transport dropped; reconnecting')
                        self.error_phase = MCPSessionErrorPhase.RUNTIME
                        raise Exception('Box managed process exited unexpectedly')
            else:
                await self._shutdown_event.wait()

+        except _ColdStartRetry:
+            # Cold-start in progress: set the preserve flag BEFORE the finally
+            # block runs so it does not stop the live managed process. The outer
+            # _lifecycle_loop_with_retry will reuse it on the next attempt.
+            self._preserve_managed_process = True
+            raise
        except Exception as e:
            self.status = MCPSessionStatus.ERROR
            self.error_message = str(e)
@@ -424,14 +490,55 @@ class RuntimeMCPSession:
            except Exception as e:
                self.ap.logger.error(f'Error cleaning up MCP session {self.server_name}: {e}\n{traceback.format_exc()}')
            finally:
-                await self._cleanup_box_stdio_session()
+                # On a transport-only reconnect the managed process is healthy
+                # and will be re-attached on the next initialize(); do NOT stop
+                # it. Any other exit path fully tears the session down.
+                if getattr(self, '_preserve_managed_process', False):
+                    self._preserve_managed_process = False
+                else:
+                    await self._cleanup_box_stdio_session()

    async def _lifecycle_loop_with_retry(self):
        """Wrap _lifecycle_loop with retry and exponential backoff."""
-        for attempt in range(self._MAX_RETRIES + 1):
+        attempt = 0
+        while attempt <= self._MAX_RETRIES:
            try:
                await self._lifecycle_loop()
                return  # Normal shutdown, don't retry
+            except _TransportReconnect as e:
+                # Transient WS transport drop while the managed process is still
+                # alive. Reconnect promptly WITHOUT consuming the fatal retry
+                # budget and WITHOUT stopping the process — initialize() will
+                # re-attach to the live process. This is what lets a long-lived
+                # stdio MCP survive repeated brief event-loop stalls / pings.
+                if self._shutdown_event.is_set():
+                    return
+                self.ap.logger.info(
+                    f'MCP session {self.server_name}: reconnecting transport ({self._describe_exception(e)})'
+                )
+                self.status = MCPSessionStatus.CONNECTING
+                self.error_message = None
+                self.error_phase = None
+                await asyncio.sleep(1)
+                continue
+            except _ColdStartRetry as e:
+                # The managed process is alive but still cold-starting (e.g.
+                # `npx -y <pkg>` is still installing) and cannot yet answer the
+                # handshake. Reuse the live process and retry the attach WITHOUT
+                # consuming the fatal retry budget or stopping the process, so a
+                # slow cold start is waited out instead of failing. Preserve the
+                # process across the finally-block cleanup.
+                if self._shutdown_event.is_set():
+                    return
+                self._preserve_managed_process = True
+                self.ap.logger.debug(
+                    f'MCP session {self.server_name}: waiting for cold start ({self._describe_exception(e)})'
+                )
+                self.status = MCPSessionStatus.CONNECTING
+                self.error_message = None
+                self.error_phase = None
+                await asyncio.sleep(2)
+                continue
            except Exception as e:
                self.retry_count = attempt + 1
                if self._shutdown_event.is_set():
@@ -460,6 +567,7 @@ class RuntimeMCPSession:
                self.error_message = None
                self.error_phase = None
                await asyncio.sleep(delay)
+                attempt += 1

    @staticmethod
    def _describe_exception(exc: BaseException) -> str:
@@ -485,6 +593,36 @@ class RuntimeMCPSession:
        unique = [m for m in leaves if not (m in seen or seen.add(m))]
        return '; '.join(unique) if unique else f'{type(exc).__name__}: {exc}'

+    @staticmethod
+    def _iter_exception_leaves(exc: BaseException) -> typing.Iterator[BaseException]:
+        sub = getattr(exc, 'exceptions', None)
+        if sub:  # ExceptionGroup / BaseExceptionGroup
+            for child in sub:
+                yield from RuntimeMCPSession._iter_exception_leaves(child)
+        else:
+            yield exc
+
+    @staticmethod
+    def _should_fallback_to_sse(exc: BaseException) -> bool:
+        """Whether a Streamable HTTP failure matches legacy-SSE fallback.
+
+        Only protocol-compatibility responses trigger fallback. Authentication,
+        authorization, throttling, and server failures must remain visible
+        instead of being retried against a different transport.
+
+        MCP SDK 1.26 translates an HTTP 404 initialize response into a synthetic
+        ``McpError(32600, 'Session terminated')`` rather than preserving the
+        HTTPStatusError, so recognize that exact SDK sentinel as 404-compatible.
+        """
+        fallback_statuses = {400, 404, 405}
+        for leaf in RuntimeMCPSession._iter_exception_leaves(exc):
+            if isinstance(leaf, httpx.HTTPStatusError):
+                if leaf.response.status_code in fallback_statuses:
+                    return True
+            elif isinstance(leaf, McpError) and leaf.error.code == 32600 and leaf.error.message == 'Session terminated':
+                return True
+        return False
+
    _MONITOR_POLL_INTERVAL = 5
    _MONITOR_MAX_CONSECUTIVE_ERRORS = 3

@@ -927,11 +1065,14 @@ class RuntimeMCPSession:
        return self._box_stdio_runtime.uses_box_stdio()

    def _build_box_session_id(self) -> str:
-        # Transient test sessions get their own isolated Box session so a
-        # failing/short-lived test can never disturb the shared session that
-        # hosts live, already-connected MCP servers.
-        if self.is_transient:
-            return f'mcp-test-{self.server_uuid}'
+        # Both live servers and transient config-page tests share ONE Box
+        # session ('mcp-shared'). A test therefore reuses the already-running
+        # container (and, for an existing server, its live managed process)
+        # instead of paying a full per-test session cold-start + dependency
+        # bootstrap. Isolation between a test and the live servers is provided
+        # at the *process* level: each server/test has its own process_id and a
+        # test only ever stops its own process_id (see cleanup_session), so it
+        # never disturbs another server's process or the shared session itself.
        return 'mcp-shared'

    def _rewrite_path(self, path: str, host_path: str | None) -> str:
@@ -6,7 +6,7 @@ import os
 import shutil
 import shlex
 import threading
-from contextlib import suppress
+from contextlib import suppress, AsyncExitStack
 from typing import TYPE_CHECKING, Any

 import pydantic
@@ -57,6 +57,23 @@ class MCPSessionErrorPhase(enum.Enum):
    BOX_UNAVAILABLE = 'box_unavailable'


+def _get_default_memory_mb(ap) -> int:
+    """Read box.default_memory_mb from instance config (env: BOX__DEFAULT_MEMORY_MB).
+
+    Falls back to 1536 MB — a safe floor for Node.js V8 + WASM under nsjail.
+    Operators running memory-constrained hosts can lower this; those with large
+    machines can raise it.  Individual MCP servers can still override via their
+    own box.memory_mb setting.
+    """
+    try:
+        data = getattr(getattr(ap, 'instance_config', None), 'data', None)
+        if isinstance(data, dict):
+            return int(data.get('box', {}).get('default_memory_mb', 1536))
+    except (TypeError, ValueError):
+        pass
+    return 1536
+
+
 class MCPServerBoxConfig(pydantic.BaseModel):
    """Structured configuration for running an MCP server inside a Box container."""

@@ -74,6 +91,35 @@ class MCPServerBoxConfig(pydantic.BaseModel):
    model_config = pydantic.ConfigDict(extra='ignore')


+_HANDSHAKE_ATTEMPT_TIMEOUT_SEC = 10.0
+
+
+class _TransferredStack:
+    """Adapts an already-populated AsyncExitStack into an async context manager
+    so ownership of its resources can be transferred into another exit stack.
+    Entering is a no-op; exiting closes the wrapped stack (and thus the live WS
+    transport + ClientSession) when the owning session shuts down."""
+
+    def __init__(self, stack: AsyncExitStack):
+        self._stack = stack
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self._stack.aclose()
+        return False
+
+
+class _ColdStartRetry(Exception):
+    """Signal: the managed process is alive but not yet answering the MCP
+    handshake because it is still cold-starting (e.g. `npx -y <pkg>` is still
+    installing). The outer lifecycle retry treats this like a transient
+    reconnect: it reuses the live process and does not count toward the fatal
+    retry budget, so a slow cold start is waited out rather than failing.
+    """
+
+
 class BoxStdioSessionRuntime:
    """Encapsulate Box-backed stdio MCP session orchestration."""

@@ -113,7 +159,17 @@ class BoxStdioSessionRuntime:
            read_only_rootfs=self.config.read_only_rootfs if self.config.read_only_rootfs is not None else False,
            image=self.config.image,
            cpus=self.config.cpus,
-            memory_mb=self.config.memory_mb,
+            # Node.js runtimes (npx/bunx) reserve large virtual address space and
+            # load WebAssembly modules (llhttp) on startup; the default 512 MB
+            # cgroup_mem_max is too small and causes OOM kills (return_code=137).
+            # Auto-bump to 1024 MB when the runner is npx/bunx/pnpm dlx.
+            # Per-server override wins; global default comes from
+            # config.yaml box.default_memory_mb (env: BOX__DEFAULT_MEMORY_MB).
+            # Hard floor of 1536 MB: enough for Node.js V8 + WASM without OOM.
+            # Per-server override wins; global default from config.yaml
+            # box.default_memory_mb (env: BOX__DEFAULT_MEMORY_MB), hard floor
+            # of 1536 MB so Node.js V8 + WASM never OOM under nsjail.
+            memory_mb=(self.config.memory_mb or _get_default_memory_mb(self.ap)),
            pids_limit=self.config.pids_limit,
            persistent=True,
        )
@@ -173,28 +229,55 @@ class BoxStdioSessionRuntime:
                    stderr_preview = (result.stderr or '')[:500]
                    raise Exception(f'Dependency install failed (exit code {result.exit_code}): {stderr_preview}')

-        try:
-            process_workspace = (
-                self._build_workspace(host_path=host_path, workdir=process_cwd, mount_path=process_cwd)
-                if host_path
-                else workspace
+        # Reuse an already-running managed process instead of rebuilding it.
+        # The Box runtime keeps the managed process alive across a transient
+        # WebSocket transport drop, so on a reconnect we only need to re-attach
+        # the WS below. Rebuilding here would needlessly stop a healthy process
+        # and re-run the (slow, network-touching) dependency bootstrap.
+        if not await self._managed_process_is_running():
+            try:
+                process_workspace = (
+                    self._build_workspace(host_path=host_path, workdir=process_cwd, mount_path=process_cwd)
+                    if host_path
+                    else workspace
+                )
+                payload = process_workspace.build_process_payload(
+                    self.server_config['command'],
+                    self.server_config.get('args', []),
+                    env=self.server_config.get('env', {}),
+                    cwd=process_cwd,
+                )
+                if install_cmd:
+                    payload = self._wrap_process_payload_with_python_env(payload, process_cwd)
+                payload['process_id'] = self.process_id
+                await workspace.box_service.start_managed_process(workspace.session_id, payload)
+            except Exception:
+                self.owner.error_phase = MCPSessionErrorPhase.PROCESS_START
+                raise
+        else:
+            self.ap.logger.info(
+                f'MCP server {self.server_name}: reusing live managed process '
+                f'process_id={self.process_id} (transport reconnect)'
            )
-            payload = process_workspace.build_process_payload(
-                self.server_config['command'],
-                self.server_config.get('args', []),
-                env=self.server_config.get('env', {}),
-                cwd=process_cwd,
-            )
-            if install_cmd:
-                payload = self._wrap_process_payload_with_python_env(payload, process_cwd)
-            payload['process_id'] = self.process_id
-            await workspace.box_service.start_managed_process(workspace.session_id, payload)
-        except Exception:
-            self.owner.error_phase = MCPSessionErrorPhase.PROCESS_START
-            raise

+        websocket_url = workspace.get_managed_process_websocket_url(self.process_id)
+
+        # Attach the WS transport + MCP session ONCE, on the owner's exit stack,
+        # in the same task as the serve loop that follows. websocket_client and
+        # ClientSession use anyio task groups whose cancel scope is bound to the
+        # frame/stack that entered them, so they must live on the owner exit
+        # stack (not a deferred/transferred one) or the streams close the moment
+        # initialize() returns and the next request fails with "Connection
+        # closed".
+        #
+        # A slow (`npx -y <pkg>`) cold start makes this single attempt fail
+        # while the process is still alive — the package is still installing and
+        # cannot answer the handshake. We surface that to the outer retry loop
+        # as a _ColdStartRetry: it must NOT stop the process (it is healthy and
+        # will be reused) and must NOT consume the fatal retry budget. The next
+        # attempt re-attaches to the same live process; once it has finished
+        # cold start the handshake succeeds and stays healthy.
        try:
-            websocket_url = workspace.get_managed_process_websocket_url(self.process_id)
            transport = await self.owner.exit_stack.enter_async_context(websocket_client(websocket_url))
            read_stream, write_stream = transport
            self.owner.session = await self.owner.exit_stack.enter_async_context(
@@ -202,12 +285,19 @@ class BoxStdioSessionRuntime:
            )
        except Exception:
            self.owner.error_phase = MCPSessionErrorPhase.RELAY_CONNECT
+            if not await self._managed_process_has_exited():
+                # Process is alive but not yet serving (cold start) — reconnect.
+                raise _ColdStartRetry(f'{self.server_name}: transport not ready during cold start')
            raise

        try:
-            await self.owner.session.initialize()
-        except Exception:
+            await asyncio.wait_for(self.owner.session.initialize(), timeout=_HANDSHAKE_ATTEMPT_TIMEOUT_SEC)
+        except Exception as exc:
            self.owner.error_phase = MCPSessionErrorPhase.MCP_INIT
+            if not await self._managed_process_has_exited():
+                raise _ColdStartRetry(
+                    f'{self.server_name}: handshake not ready during cold start ({type(exc).__name__})'
+                )
            raise

    async def monitor_process_health(self) -> None:
@@ -234,8 +324,74 @@ class BoxStdioSessionRuntime:
                )
                if consecutive_errors >= self.owner._MONITOR_MAX_CONSECUTIVE_ERRORS:
                    return
+
+            # Capture stderr logs from the managed process
+            if isinstance(info, dict):
+                stderr_text = info.get('stderr', '') or info.get('stderr_preview', '')
+            else:
+                stderr_text = getattr(info, 'stderr', '') or getattr(info, 'stderr_preview', '')
+
+            if stderr_text and stderr_text != self.owner._last_stderr_text:
+                # Find new lines not in the previous snapshot
+                old_lines = set(self.owner._last_stderr_text.splitlines()) if self.owner._last_stderr_text else set()
+                new_lines = [l for l in stderr_text.splitlines() if l and l not in old_lines]
+                self.owner._last_stderr_text = stderr_text
+
+                import time as _time
+
+                for line in new_lines:
+                    level = (
+                        'error'
+                        if any(k in line.upper() for k in ('ERROR', 'CRITICAL'))
+                        else 'warning'
+                        if 'WARNING' in line.upper()
+                        else 'debug'
+                        if 'DEBUG' in line.upper()
+                        else 'info'
+                    )
+                    self.owner._log_buffer.append({'ts': _time.time(), 'level': level, 'text': line})
+
            await asyncio.sleep(self.owner._MONITOR_POLL_INTERVAL)

+    async def _managed_process_is_running(self) -> bool:
+        """Return True if this server's managed process exists and is running.
+
+        Used to decide whether initialize() must (re)start the process or can
+        simply re-attach the WebSocket transport to a process the Box runtime
+        kept alive across a transient transport drop.
+        """
+        from langbot_plugin.box.models import BoxManagedProcessStatus
+
+        workspace = self._build_workspace()
+        try:
+            info = await workspace.get_managed_process(self.process_id)
+        except Exception:
+            return False
+        status = info.get('status', '') if isinstance(info, dict) else getattr(info, 'status', '')
+        return status in (BoxManagedProcessStatus.RUNNING.value, BoxManagedProcessStatus.RUNNING)
+
+    async def _managed_process_has_exited(self) -> bool:
+        """Return True only if the process is DEFINITIVELY gone (reports EXITED).
+
+        Distinct from ``not _managed_process_is_running()``: a process that has
+        just been spawned may not yet report RUNNING, and a transient query
+        error is not proof of exit. During the cold-start handshake retry we
+        must NOT treat 'not yet running' or 'query failed' as a terminal
+        failure, or we bail out to the outer rebuild path and churn the
+        process (relay then rejects the early re-attach with HTTP 400). Only a
+        successful query that reports EXITED stops the retry loop.
+        """
+        from langbot_plugin.box.models import BoxManagedProcessStatus
+
+        workspace = self._build_workspace()
+        try:
+            info = await workspace.get_managed_process(self.process_id)
+        except Exception:
+            # Unknown — treat as 'still coming up', not exited.
+            return False
+        status = info.get('status', '') if isinstance(info, dict) else getattr(info, 'status', '')
+        return status in (BoxManagedProcessStatus.EXITED.value, BoxManagedProcessStatus.EXITED)
+
    async def _stage_host_path_to_shared_workspace(self, host_path: str) -> str:
        source_path = normalize_host_path(host_path)
        if not source_path:
@@ -342,16 +498,20 @@ class BoxStdioSessionRuntime:

        workspace = self._build_workspace(host_path=None)

-        # Transient test sessions own their isolated Box session, so tear the
-        # whole session down rather than leaking it. This cannot affect live
-        # servers because they live in the separate shared session.
+        # Transient config-page tests now share the same 'mcp-shared' Box
+        # session as live servers, so we must NOT tear the session down here —
+        # that would kill every other MCP server in the container. A test is
+        # isolated at the process level: it ran under its own process_id, so we
+        # stop only that process, exactly like a live server does below. The
+        # shared session and all other servers' live processes are untouched.
+        # (Staged per-test workspace files are still cleaned up.)
        if getattr(self.owner, 'is_transient', False):
            try:
-                await workspace.cleanup()
+                await workspace.stop_managed_process(self.process_id)
            except Exception as exc:
                self.ap.logger.warning(
-                    f'MCP server {self.server_name}: failed to delete transient test session '
-                    f'{self.owner._build_box_session_id()}: {type(exc).__name__}: {exc}'
+                    f'MCP server {self.server_name}: failed to stop transient test process '
+                    f'process_id={self.process_id}: {type(exc).__name__}: {exc}'
                )
            await self._cleanup_staged_workspace()
            return
@@ -33,6 +33,12 @@ class VectorDBManager:
                self.vector_db = SeekDBVectorDatabase(self.ap)
                self.ap.logger.info('Initialized SeekDB vector database backend.')

+            elif vdb_type == 'valkey_search':
+                from .vdbs.valkey_search import ValkeySearchVectorDatabase
+
+                self.vector_db = ValkeySearchVectorDatabase(self.ap)
+                self.ap.logger.info('Initialized Valkey Search vector database backend.')
+
            elif vdb_type == 'milvus':
                from .vdbs.milvus import MilvusVectorDatabase

@@ -0,0 +1,829 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import struct
+from typing import Any
+
+from langbot.pkg.core import app
+from langbot.pkg.vector.vdb import VectorDatabase, SearchType
+from langbot.pkg.vector.filter_utils import normalize_filter, strip_unsupported_fields
+
+try:
+    from glide import (
+        Batch,
+        GlideClient,
+        GlideClientConfiguration,
+        NodeAddress,
+        RequestError,
+        ServerCredentials,
+        ft,
+        VectorField,
+        VectorFieldAttributesHnsw,
+        VectorFieldAttributesFlat,
+        VectorAlgorithm,
+        VectorType,
+        DistanceMetricType,
+        TagField,
+        TextField,
+        FtCreateOptions,
+        DataType,
+        FtSearchOptions,
+        FtSearchLimit,
+        ReturnField,
+    )
+
+    VALKEY_SEARCH_AVAILABLE = True
+except ImportError:
+    VALKEY_SEARCH_AVAILABLE = False
+
+# Default per-request timeout (ms) for the glide client.  The glide library
+# default is 250ms, which is too low for vector KNN (``FT.SEARCH ... =>[KNN]``)
+# under moderate load or with large indexes and yields spurious TimeoutErrors.
+# Overridable via the ``vdb.valkey_search.request_timeout`` config option.
+_DEFAULT_REQUEST_TIMEOUT_MS = 5000
+
+# Safety cap on the number of SCAN rounds when purging a collection's keys, so
+# a cursor-handling bug or pathological keyspace can never spin forever.
+_MAX_SCAN_ROUNDS = 100000
+
+
+# Mandatory client name for production observability (CLIENT LIST / dashboards).
+VALKEY_CLIENT_NAME = 'langbot_vector_client'
+
+# Fixed, indexed metadata schema.  LangBot's RAG layer stores ``file_id`` on
+# every chunk; it is the only metadata field we promote to a first-class
+# (filterable) index field.  All other metadata is preserved verbatim inside
+# the ``metadata_json`` field so it survives a round-trip, but is NOT
+# filterable (the established Milvus / pgvector pragmatism).
+_INDEXED_TAG_FIELDS = {'file_id'}
+_SUPPORTED_FILTER_FIELDS = set(_INDEXED_TAG_FIELDS)
+
+# Hash field names used for stored documents.
+_FIELD_VECTOR = 'vector'
+_FIELD_DOCUMENT = 'document'
+_FIELD_FILE_ID = 'file_id'
+_FIELD_METADATA = 'metadata_json'
+_VEC_SCORE_ALIAS = '__vec_score'
+
+# Valkey Search has no bare "match everything" token for non-vector queries
+# (a standalone ``*`` is a syntax error).  A negated match on a sentinel tag
+# value that can never exist matches every key, which is the canonical
+# match-all idiom for FT.SEARCH.
+_MATCH_ALL = '-@file_id:{__langbot_match_all_sentinel__}'
+
+# Page size used when enumerating matching keys for deletion.  Deletes
+# paginate through the full result set in batches of this size so that
+# files/filters matching more than one page of chunks are fully removed
+# (no silent truncation / orphaned vectors).
+_DELETE_SCAN_BATCH = 10000
+
+# Characters Valkey Search's TAG query parser cannot handle even when
+# backslash-escaped (the brace delimiters and the wildcard).  file_id TAG
+# values are percent-encoded over this set (plus '%' itself, so the encoding
+# is reversible/unambiguous) before being stored or queried, so an arbitrary
+# file_id round-trips instead of producing an unparseable query.  For normal
+# UUID/hash file_ids none of these characters occur, so the encoding is a
+# no-op and the stored value is unchanged.  The original file_id is always
+# preserved verbatim inside ``metadata_json``.
+_FT_UNSAFE_TAG_CHARS = frozenset('{}*%')
+
+
+class ValkeySearchVectorDatabase(VectorDatabase):
+    """Valkey Search (valkey-bundle) vector database adapter for LangBot.
+
+    Backed by the Valkey Search module shipped in ``valkey/valkey-bundle``,
+    accessed through the official ``valkey-glide`` client's native ``ft``
+    (search) command namespace.  Documents are stored as Valkey HASH keys
+    under a per-collection prefix and indexed by one ``FT.CREATE`` index per
+    collection.
+
+    Supported search types: ``VECTOR``, ``FULL_TEXT`` and ``HYBRID``.
+
+    Hybrid search semantics (IMPORTANT)
+    -----------------------------------
+    Valkey Search hybrid queries follow a *filter-then-KNN* model: the text /
+    metadata filter pre-selects candidate keys and the KNN stage ranks them by
+    vector distance.  This backend does **NOT** implement application-side
+    weighted score fusion.  The ``vector_weight`` argument is therefore
+    accepted for interface compatibility but is **not honored** — passing
+    different weights does not change result ordering.  A one-time warning is
+    emitted the first time a non-default weight is supplied.  App-side score
+    fusion can be layered on later if weighted hybrid ranking is required.
+    """
+
+    @classmethod
+    def supported_search_types(cls) -> list[SearchType]:
+        return [SearchType.VECTOR, SearchType.FULL_TEXT, SearchType.HYBRID]
+
+    def __init__(self, ap: app.Application):
+        if not VALKEY_SEARCH_AVAILABLE:
+            raise ImportError(
+                'valkey-glide is not installed or is unavailable on this platform. '
+                "On Linux or macOS, install it with: pip install 'valkey-glide>=2.4.1,<3.0.0'"
+            )
+
+        self.ap = ap
+        config = self.ap.instance_config.data['vdb']['valkey_search']
+
+        self._host = config.get('host', 'localhost')
+        self._port = int(config.get('port', 6379))
+        self._db = int(config.get('db', 0))
+        # Auth / TLS are optional (toB / SaaS).  Never logged.
+        self._password = config.get('password', '') or None
+        self._username = config.get('username', '') or None
+        self._tls = bool(config.get('tls', False))
+        self._request_timeout = int(config.get('request_timeout', _DEFAULT_REQUEST_TIMEOUT_MS))
+
+        algorithm = str(config.get('index_algorithm', 'HNSW')).upper()
+        self._algorithm = VectorAlgorithm.FLAT if algorithm == 'FLAT' else VectorAlgorithm.HNSW
+
+        metric = str(config.get('distance_metric', 'COSINE')).upper()
+        self._distance_metric = {
+            'COSINE': DistanceMetricType.COSINE,
+            'L2': DistanceMetricType.L2,
+            'IP': DistanceMetricType.IP,
+        }.get(metric, DistanceMetricType.COSINE)
+
+        # Lazily-created client (created on first use so a down Valkey does not
+        # block LangBot boot).
+        self._client: GlideClient | None = None
+        # Serializes lazy client creation so concurrent first-use callers do not
+        # each construct (and leak) a separate GlideClient.
+        self._client_lock = asyncio.Lock()
+        # Index names we have already ensured this process lifetime.
+        self._ensured_indexes: set[str] = set()
+        # Whether we have already warned about the non-honored vector_weight.
+        self._vector_weight_warned = False
+
+    # ------------------------------------------------------------------ #
+    # Client lifecycle
+    # ------------------------------------------------------------------ #
+    async def _ensure_client(self) -> GlideClient:
+        """Create the glide client on first use (lazy, non-blocking boot)."""
+        if self._client is not None:
+            return self._client
+        # Double-checked locking: serialize creation so two concurrent
+        # first-use callers don't both build a client and leak one.
+        async with self._client_lock:
+            if self._client is not None:
+                return self._client
+
+            credentials = None
+            if self._password is not None:
+                # username is optional alongside a password (ACL "user" vs default user).
+                credentials = ServerCredentials(password=self._password, username=self._username)
+            elif self._username is not None:
+                # A username without a password is not a valid credential pair, and silently
+                # connecting unauthenticated to a potentially shared Valkey instance is a
+                # security footgun (e.g. an env var that failed to resolve). Fail closed.
+                raise ValueError(
+                    'Valkey Search: a username was configured without a password. '
+                    'Set both username and password to use ACL authentication, or remove both.'
+                )
+
+            conf = GlideClientConfiguration(
+                addresses=[NodeAddress(self._host, self._port)],
+                client_name=VALKEY_CLIENT_NAME,
+                database_id=self._db,
+                use_tls=self._tls,
+                lazy_connect=True,
+                credentials=credentials,
+                request_timeout=self._request_timeout,
+            )
+            self._client = await GlideClient.create(conf)
+            self.ap.logger.info(
+                f'Initialized Valkey Search client to {self._host}:{self._port} (db={self._db}, tls={self._tls})'
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the glide client and reset state.
+
+        Safe to call when no client was created. After ``close`` the next
+        operation transparently re-creates the client (``_ensure_client``
+        guards on ``self._client is None``).
+        """
+        if self._client is not None:
+            try:
+                await self._client.close()
+            except Exception:
+                self.ap.logger.warning('Valkey Search: error while closing client (ignored)')
+            finally:
+                self._client = None
+                self._ensured_indexes.clear()
+
+    # ------------------------------------------------------------------ #
+    # Naming helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _index_name(collection: str) -> str:
+        return f'idx:{collection}'
+
+    @staticmethod
+    def _key_prefix(collection: str) -> str:
+        return f'kb:{collection}:'
+
+    @staticmethod
+    def _pack_vector(vec: list[float]) -> bytes:
+        """Pack a float vector into little-endian float32 bytes.
+
+        Valkey Search stores and queries vectors as FLOAT32 little-endian
+        blobs (per the search query-language spec).
+        """
+        return struct.pack(f'<{len(vec)}f', *[float(x) for x in vec])
+
+    @staticmethod
+    def _escape_tag(value: str) -> str:
+        """Escape characters that are special inside a TAG ``{...}`` clause.
+
+        The backslash is escaped first so it cannot consume a following
+        escape. This neutralises injection-style values (quotes, parens,
+        ``|``, ``@``, ``:``, spaces, dashes) so a crafted ``file_id`` cannot
+        break out of the clause.
+
+        Note: Valkey Search's TAG query parser cannot handle a literal brace
+        (``{`` / ``}``) or ``*`` even when backslash-escaped.  Callers that pass
+        a ``file_id`` route it through ``_encode_and_escape_tag`` /
+        ``_encode_file_id`` first, which percent-encodes exactly those
+        characters, so an arbitrary ``file_id`` round-trips safely. This raw
+        escaper is still correct for all other special characters.
+        """
+        out = []
+        for ch in str(value):
+            if ch in '\\,.<>{}[]"\':;!@#$%^&*()-+=~| ':
+                out.append('\\')
+            out.append(ch)
+        return ''.join(out)
+
+    @staticmethod
+    def _encode_file_id(value: str) -> str:
+        """Make a ``file_id`` safe to use as an FT TAG token AND query value.
+
+        Percent-encodes the characters Valkey Search's TAG parser cannot handle
+        even when backslash-escaped (``{``, ``}``, ``*``) plus ``%`` itself for
+        reversibility.  Applied identically at write time (the stored TAG field)
+        and query time (filters / ``delete_by_file_id``) so any value matches
+        itself.  For normal UUID/hash ids none of these characters occur, so
+        this is a no-op.  The original value is always kept verbatim in
+        ``metadata_json``; this encoded form is only ever used for the indexed
+        TAG.
+        """
+        out = []
+        for ch in str(value):
+            if ch in _FT_UNSAFE_TAG_CHARS:
+                out.append('%{:02X}'.format(ord(ch)))
+            else:
+                out.append(ch)
+        return ''.join(out)
+
+    def _encode_and_escape_tag(self, value: str) -> str:
+        """Encode an FT-unsafe ``file_id`` then escape TAG special chars."""
+        return self._escape_tag(self._encode_file_id(value))
+
+    # ------------------------------------------------------------------ #
+    # Filter mapping (canonical triples -> FT query fragment)
+    # ------------------------------------------------------------------ #
+    def _triples_to_ft(self, filter: dict[str, Any] | None) -> str:
+        """Translate a canonical filter dict into an FT filter expression.
+
+        Only indexed fields (``file_id``) are filterable; unsupported fields
+        are dropped with a warning (matching the Milvus / pgvector pattern).
+        Returns an empty string when there is no usable filter.
+        """
+        triples = normalize_filter(filter)
+        if not triples:
+            return ''
+        triples = strip_unsupported_fields(triples, _SUPPORTED_FILTER_FIELDS)
+
+        fragments: list[str] = []
+        for field, op, value in triples:
+            # All currently-indexed fields are TAG fields; file_id values are
+            # encoded (FT-unsafe chars) then escaped so any value round-trips.
+            if op == '$eq':
+                fragments.append(f'@{field}:{{{self._encode_and_escape_tag(value)}}}')
+            elif op == '$ne':
+                fragments.append(f'-@{field}:{{{self._encode_and_escape_tag(value)}}}')
+            elif op == '$in':
+                joined = '|'.join(self._encode_and_escape_tag(v) for v in value)
+                fragments.append(f'@{field}:{{{joined}}}')
+            elif op == '$nin':
+                joined = '|'.join(self._encode_and_escape_tag(v) for v in value)
+                fragments.append(f'-@{field}:{{{joined}}}')
+            elif op == '$gt':
+                fragments.append(f'@{field}:[({float(value)} +inf]')
+            elif op == '$gte':
+                fragments.append(f'@{field}:[{float(value)} +inf]')
+            elif op == '$lt':
+                fragments.append(f'@{field}:[-inf ({float(value)}]')
+            elif op == '$lte':
+                fragments.append(f'@{field}:[-inf {float(value)}]')
+            else:
+                # normalize_filter() already rejects unknown operators, so this
+                # only triggers if SUPPORTED_OPS grows without this chain being
+                # updated. Fail closed (rather than silently dropping the
+                # condition, which would widen delete_by_filter's match set).
+                raise ValueError(f'Valkey Search: unhandled filter operator {op!r} on field {field!r}')
+
+        return ' '.join(fragments)
+
+    @staticmethod
+    def _build_text_clause(text: str) -> str:
+        """Build a field-scoped full-text clause for the ``document`` field.
+
+        Each whitespace-delimited word becomes a ``@document:<term>`` term and
+        the terms are AND-ed (space separated).  FT special characters in each
+        term are escaped.  Returns an empty string when *text* has no words.
+        """
+        words = [w for w in str(text).split() if w]
+        if not words:
+            return ''
+        terms = [f'@{_FIELD_DOCUMENT}:{ValkeySearchVectorDatabase._escape_text(w)}' for w in words]
+        return ' '.join(terms)
+
+    @staticmethod
+    def _escape_text(text: str) -> str:
+        """Escape FT full-text special characters in a single term."""
+        out = []
+        for ch in str(text):
+            if ch in '@!{}[]()|-"~*:\\':
+                out.append('\\')
+            out.append(ch)
+        return ''.join(out)
+
+    # ------------------------------------------------------------------ #
+    # Index management
+    # ------------------------------------------------------------------ #
+    async def _ensure_index(self, client: GlideClient, collection: str, dim: int) -> None:
+        index = self._index_name(collection)
+        if index in self._ensured_indexes:
+            return
+
+        # ft.info is O(1) and raises RequestError when the index is absent —
+        # cheaper than ft.list (O(n) over all indexes) and it closes the
+        # check-then-create TOCTOU window.
+        try:
+            await ft.info(client, index)
+            self._ensured_indexes.add(index)
+            return
+        except RequestError:
+            pass
+
+        if self._algorithm == VectorAlgorithm.FLAT:
+            vector_attrs = VectorFieldAttributesFlat(
+                dimensions=dim,
+                distance_metric=self._distance_metric,
+                type=VectorType.FLOAT32,
+            )
+        else:
+            vector_attrs = VectorFieldAttributesHnsw(
+                dimensions=dim,
+                distance_metric=self._distance_metric,
+                type=VectorType.FLOAT32,
+            )
+
+        schema = [
+            VectorField(name=_FIELD_VECTOR, algorithm=self._algorithm, attributes=vector_attrs),
+            TagField(name=_FIELD_FILE_ID),
+            TextField(name=_FIELD_DOCUMENT),
+        ]
+        options = FtCreateOptions(data_type=DataType.HASH, prefixes=[self._key_prefix(collection)])
+        await ft.create(client, index, schema, options)
+        self._ensured_indexes.add(index)
+        self.ap.logger.info(
+            f"Valkey Search index '{index}' created (dim={dim}, algo={self._algorithm.value}, "
+            f'metric={self._distance_metric.value})'
+        )
+
+    @staticmethod
+    def _decode(value: Any) -> str:
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            return bytes(value).decode('utf-8', errors='replace')
+        return str(value)
+
+    # ------------------------------------------------------------------ #
+    # VectorDatabase ABC implementation
+    # ------------------------------------------------------------------ #
+    async def get_or_create_collection(self, collection: str):
+        """Ensure a client exists.
+
+        The index itself requires the vector dimension, which is only known at
+        first ``add_embeddings`` (same constraint as Qdrant / SeekDB), so this
+        is a best-effort no-op when the index does not yet exist.
+        """
+        await self._ensure_client()
+
+    async def add_embeddings(
+        self,
+        collection: str,
+        ids: list[str],
+        embeddings_list: list[list[float]],
+        metadatas: list[dict[str, Any]],
+        documents: list[str] | None = None,
+    ) -> None:
+        if not embeddings_list:
+            return
+
+        client = await self._ensure_client()
+        dim = len(embeddings_list[0])
+        # The index schema is fixed to the first embedding's dimension. A later
+        # embedding of a different length would be packed into a wrong-sized
+        # blob that Valkey stores silently but that yields garbage KNN
+        # distances, so reject mixed dimensions up-front.
+        if any(len(e) != dim for e in embeddings_list[1:]):
+            raise ValueError(f'All embeddings must have dimension {dim}; got mixed lengths')
+        await self._ensure_index(client, collection, dim)
+
+        prefix = self._key_prefix(collection)
+
+        batch = Batch(is_atomic=False)
+        for i, _id in enumerate(ids):
+            key = prefix + str(_id)
+            metadata = metadatas[i] if i < len(metadatas) else {}
+            mapping: dict[str, Any] = {
+                _FIELD_VECTOR: self._pack_vector(embeddings_list[i]),
+                _FIELD_METADATA: json.dumps(metadata, ensure_ascii=False),
+            }
+            file_id = metadata.get('file_id')
+            if file_id is not None:
+                mapping[_FIELD_FILE_ID] = self._encode_file_id(str(file_id))
+            if documents is not None and i < len(documents) and documents[i] is not None:
+                mapping[_FIELD_DOCUMENT] = documents[i]
+
+            batch.hset(key, mapping)
+
+        # Pipeline all HSETs into a single round-trip (non-atomic) instead of
+        # one await per embedding, which is N sequential round-trips for N
+        # chunks.
+        await client.exec(batch, raise_on_error=True)
+
+        self.ap.logger.info(f"Added {len(ids)} embeddings to Valkey Search collection '{collection}'")
+
+    async def search(
+        self,
+        collection: str,
+        query_embedding: list[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+        vector_weight: float | None = None,
+    ) -> dict[str, Any]:
+        client = await self._ensure_client()
+        index = self._index_name(collection)
+
+        if not await self._index_exists(client, index):
+            return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+
+        # vector_weight is accepted for interface parity but NOT honored by this
+        # backend (filter-then-KNN, no weighted fusion).  Warn once.
+        if vector_weight is not None and not self._vector_weight_warned:
+            self.ap.logger.warning(
+                'Valkey Search backend does not honor vector_weight: hybrid search uses '
+                'filter-then-KNN without weighted score fusion. The vector_weight value '
+                'is ignored. See docs/VALKEY_SEARCH_INTEGRATION.md.'
+            )
+            self._vector_weight_warned = True
+
+        filter_expr = self._triples_to_ft(filter)
+
+        if search_type == SearchType.FULL_TEXT:
+            if not query_text:
+                return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+            text_clause = self._build_text_clause(query_text)
+            if not text_clause:
+                return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+            query = f'{filter_expr} {text_clause}'.strip() if filter_expr else text_clause
+            return await self._run_text_search(client, index, query, k)
+
+        if search_type == SearchType.HYBRID:
+            # Filter / text pre-selects candidates; KNN ranks. No fusion.
+            pre = filter_expr
+            if query_text:
+                text_clause = self._build_text_clause(query_text)
+                if text_clause:
+                    pre = f'{pre} {text_clause}'.strip() if pre else text_clause
+            pre = pre or '*'
+            query = f'{self._wrap_pre(pre)}=>[KNN {k} @{_FIELD_VECTOR} $BLOB AS {_VEC_SCORE_ALIAS}]'
+            return await self._run_knn_search(client, index, query, query_embedding, k)
+
+        # Default: pure VECTOR search.
+        pre = filter_expr or '*'
+        query = f'{self._wrap_pre(pre)}=>[KNN {k} @{_FIELD_VECTOR} $BLOB AS {_VEC_SCORE_ALIAS}]'
+        return await self._run_knn_search(client, index, query, query_embedding, k)
+
+    @staticmethod
+    def _wrap_pre(pre: str) -> str:
+        """Parenthesize a multi-condition pre-filter before the ``=>`` KNN clause.
+
+        When ``pre`` combines several terms (e.g. ``@file_id:{x} @document:term``)
+        the Valkey Search parser can otherwise mis-associate only the last term
+        with the KNN clause. Wrapping the whole expression forces correct
+        grouping. A bare ``*`` (match-all) and single-term expressions are left
+        untouched.
+        """
+        if pre and pre != '*' and ' ' in pre.strip():
+            return f'({pre})'
+        return pre
+
+    async def _run_knn_search(
+        self,
+        client: GlideClient,
+        index: str,
+        query: str,
+        query_embedding: list[float],
+        k: int,
+    ) -> dict[str, Any]:
+        options = FtSearchOptions(
+            params={'BLOB': self._pack_vector(list(query_embedding))},
+            return_fields=[
+                ReturnField(field_identifier=_VEC_SCORE_ALIAS, alias='distance'),
+                ReturnField(field_identifier=_FIELD_DOCUMENT),
+                ReturnField(field_identifier=_FIELD_METADATA),
+            ],
+            limit=FtSearchLimit(0, k),
+            dialect=2,
+        )
+        try:
+            reply = await ft.search(client, index, query, options)
+        except Exception as exc:
+            if self._is_missing_index_error(exc):
+                return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+            raise
+        return self._reply_to_chroma(index, reply, has_distance=True)
+
+    async def _run_text_search(
+        self,
+        client: GlideClient,
+        index: str,
+        query: str,
+        k: int,
+    ) -> dict[str, Any]:
+        options = FtSearchOptions(
+            return_fields=[
+                ReturnField(field_identifier=_FIELD_DOCUMENT),
+                ReturnField(field_identifier=_FIELD_METADATA),
+            ],
+            limit=FtSearchLimit(0, k),
+            dialect=2,
+        )
+        try:
+            reply = await ft.search(client, index, query, options)
+        except Exception as exc:
+            if self._is_missing_index_error(exc):
+                return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+            raise
+        return self._reply_to_chroma(index, reply, has_distance=False)
+
+    @staticmethod
+    def _is_missing_index_error(exc: Exception) -> bool:
+        """Return True if *exc* indicates the FT index does not exist.
+
+        ``FT.DROPINDEX`` is applied eventually, so an index can briefly still
+        appear in ``FT._LIST`` after being dropped; a follow-up search then
+        fails with a "not found" error which we treat as an empty result.
+        """
+        message = str(exc).lower()
+        return 'not found' in message and 'index' in message
+
+    def _iter_reply_docs(self, reply: Any, prefix: str):
+        """Yield ``(doc_id, decoded_fields)`` pairs from an FT.SEARCH reply.
+
+        glide returns ``[total, {key: {field: value}, ...}]``. This shared
+        iterator decodes each key, strips the per-collection prefix to recover
+        the original document id, and decodes the field map — the logic both
+        ``_reply_to_chroma`` and ``list_by_filter`` need.
+        """
+        docs = reply[1] if reply and len(reply) >= 2 and isinstance(reply[1], dict) else {}
+        for key, fields in docs.items():
+            key_str = self._decode(key)
+            doc_id = key_str[len(prefix) :] if prefix and key_str.startswith(prefix) else key_str
+            decoded_fields = {self._decode(fk): fv for fk, fv in fields.items()} if isinstance(fields, dict) else {}
+            yield doc_id, decoded_fields
+
+    def _reply_to_chroma(self, index: str, reply: Any, has_distance: bool) -> dict[str, Any]:
+        """Convert an FT.SEARCH reply into Chroma-style nested lists.
+
+        The KNN score field (aliased ``distance``) is a COSINE/L2 distance
+        directly, so no inversion is needed (unlike Qdrant).
+        """
+        ids: list[str] = []
+        distances: list[float] = []
+        metadatas: list[dict[str, Any]] = []
+
+        if not reply or len(reply) < 2:
+            return {'ids': [ids], 'metadatas': [metadatas], 'distances': [distances]}
+
+        prefix = self._key_prefix(index[len('idx:') :]) if index.startswith('idx:') else ''
+
+        for doc_id, decoded_fields in self._iter_reply_docs(reply, prefix):
+            ids.append(doc_id)
+
+            if has_distance and 'distance' in decoded_fields:
+                try:
+                    distances.append(float(self._decode(decoded_fields['distance'])))
+                except (TypeError, ValueError):
+                    distances.append(0.0)
+            else:
+                distances.append(0.0)
+
+            metadata: dict[str, Any] = {}
+            raw_meta = decoded_fields.get(_FIELD_METADATA)
+            if raw_meta is not None:
+                try:
+                    metadata = json.loads(self._decode(raw_meta))
+                except (TypeError, ValueError):
+                    metadata = {}
+            metadatas.append(metadata)
+
+        return {'ids': [ids], 'metadatas': [metadatas], 'distances': [distances]}
+
+    async def delete_by_file_id(self, collection: str, file_id: str) -> None:
+        client = await self._ensure_client()
+        index = self._index_name(collection)
+        if not await self._index_exists(client, index):
+            self.ap.logger.warning(f"Valkey Search collection '{collection}' not found for deletion")
+            return
+
+        query = f'@{_FIELD_FILE_ID}:{{{self._encode_and_escape_tag(file_id)}}}'
+        keys = await self._search_keys(client, index, query)
+        if keys:
+            await client.delete(keys)
+        self.ap.logger.info(
+            f"Deleted {len(keys)} embeddings from Valkey Search collection '{collection}' with file_id: {file_id}"
+        )
+
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        client = await self._ensure_client()
+        index = self._index_name(collection)
+        if not await self._index_exists(client, index):
+            self.ap.logger.warning(f"Valkey Search collection '{collection}' not found for deletion")
+            return 0
+
+        # Guard against accidental mass deletion: a non-empty filter that maps
+        # to no usable (indexed) conditions must NOT fall back to match-all and
+        # wipe the whole collection.  Skip instead (matching Milvus / pgvector).
+        query = self._triples_to_ft(filter)
+        if not query:
+            self.ap.logger.warning(
+                "Valkey Search delete_by_filter on '%s': filter produced no usable conditions, skipping",
+                collection,
+            )
+            return 0
+        keys = await self._search_keys(client, index, query)
+        if keys:
+            await client.delete(keys)
+        self.ap.logger.info(f"Deleted {len(keys)} embeddings from Valkey Search collection '{collection}' by filter")
+        return len(keys)
+
+    async def list_by_filter(
+        self,
+        collection: str,
+        filter: dict[str, Any] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> tuple[list[dict[str, Any]], int]:
+        client = await self._ensure_client()
+        index = self._index_name(collection)
+        if not await self._index_exists(client, index):
+            return [], 0
+
+        query = self._triples_to_ft(filter) or _MATCH_ALL
+        options = FtSearchOptions(
+            return_fields=[
+                ReturnField(field_identifier=_FIELD_DOCUMENT),
+                ReturnField(field_identifier=_FIELD_METADATA),
+            ],
+            limit=FtSearchLimit(offset, limit),
+            dialect=2,
+        )
+        try:
+            reply = await ft.search(client, index, query, options)
+        except Exception as exc:
+            if self._is_missing_index_error(exc):
+                return [], 0
+            raise
+
+        total = 0
+        if reply:
+            try:
+                total = int(reply[0])
+            except (TypeError, ValueError):
+                total = 0
+
+        prefix = self._key_prefix(collection)
+        items: list[dict[str, Any]] = []
+        for doc_id, decoded_fields in self._iter_reply_docs(reply, prefix):
+            document = decoded_fields.get(_FIELD_DOCUMENT)
+            metadata: dict[str, Any] = {}
+            raw_meta = decoded_fields.get(_FIELD_METADATA)
+            if raw_meta is not None:
+                try:
+                    metadata = json.loads(self._decode(raw_meta))
+                except (TypeError, ValueError):
+                    metadata = {}
+
+            items.append(
+                {
+                    'id': doc_id,
+                    'document': self._decode(document) if document is not None else None,
+                    'metadata': metadata,
+                }
+            )
+
+        return items, total
+
+    async def delete_collection(self, collection: str):
+        client = await self._ensure_client()
+        index = self._index_name(collection)
+        self._ensured_indexes.discard(index)
+
+        if await self._index_exists(client, index):
+            try:
+                await ft.dropindex(client, index)
+            except RequestError:
+                # The index was already dropped (e.g. by a concurrent process)
+                # between the existence check and this call — benign. Other
+                # errors (connection / auth) must propagate so the caller knows
+                # the operation failed rather than silently SCAN-deleting next.
+                pass
+
+        # DROPINDEX does not remove the underlying hashes; delete them too.
+        prefix = self._key_prefix(collection)
+        cursor = b'0'
+        deleted = 0
+        for _ in range(_MAX_SCAN_ROUNDS):
+            cursor, keys = await client.scan(cursor, match=f'{prefix}*', count=500)
+            if keys:
+                await client.delete(keys)
+                deleted += len(keys)
+            if cursor in (b'0', '0', 0):
+                break
+        self.ap.logger.info(f"Valkey Search collection '{collection}' deleted ({deleted} keys removed)")
+
+    # ------------------------------------------------------------------ #
+    # Internal search helpers
+    # ------------------------------------------------------------------ #
+    async def _index_exists(self, client: GlideClient, index: str) -> bool:
+        if index in self._ensured_indexes:
+            return True
+        # ft.info is O(1) and raises RequestError when the index does not
+        # exist, vs ft.list which is O(n) over every index on the server and
+        # was being paid on the first query to each collection.
+        try:
+            await ft.info(client, index)
+            self._ensured_indexes.add(index)
+            return True
+        except RequestError:
+            return False
+
+    async def _search_keys(self, client: GlideClient, index: str, query: str) -> list[str]:
+        """Return all matching document keys for a query (NOCONTENT).
+
+        Paginates through the full result set in pages of ``_DELETE_SCAN_BATCH``
+        so that queries matching more than one page of chunks are fully
+        enumerated (avoids silently truncating deletes and leaving orphaned
+        vectors).
+        """
+        keys: list[str] = []
+        offset = 0
+        while True:
+            options = FtSearchOptions(
+                nocontent=True,
+                limit=FtSearchLimit(offset, _DELETE_SCAN_BATCH),
+                dialect=2,
+            )
+            try:
+                reply = await ft.search(client, index, query, options)
+            except Exception as exc:
+                if self._is_missing_index_error(exc):
+                    return keys
+                raise
+
+            if not reply or len(reply) < 2:
+                break
+
+            # reply[0] is the total match count; reply[1] holds this page.
+            total = 0
+            try:
+                total = int(reply[0])
+            except (TypeError, ValueError):
+                total = 0
+
+            docs = reply[1]
+            if isinstance(docs, dict):
+                page = [self._decode(k) for k in docs.keys()]
+            elif isinstance(docs, (list, tuple)):
+                page = [self._decode(k) for k in docs]
+            else:
+                page = []
+
+            if not page:
+                break
+            keys.extend(page)
+
+            offset += len(page)
+            if offset >= total or len(page) < _DELETE_SCAN_BATCH:
+                break
+
+        return keys
@@ -87,6 +87,16 @@ vdb:
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
+    valkey_search:
+        host: 'localhost'
+        port: 6379            # integration tests use 6380 -> valkey/valkey-bundle:9.1.0
+        db: 0
+        password: ''          # optional (toB auth)
+        username: ''          # optional (ACL user, toB)
+        tls: false            # optional (toB/SaaS)
+        index_algorithm: 'HNSW'   # HNSW | FLAT
+        distance_metric: 'COSINE' # COSINE | L2 | IP
+        request_timeout: 5000     # per-request timeout in ms (glide default 250ms is too low for KNN)
 storage:
    use: local
    cleanup:
@@ -143,6 +153,15 @@ box:
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null  # Optional disk quota override (>= 0). null = profile default.
+    # Default nsjail cgroup memory limit for each MCP stdio server process, in MB.
+    # Node.js MCP servers (npx/bunx) need more memory than Python ones because V8
+    # and WebAssembly modules (e.g. undici llhttp) reserve large virtual address
+    # space at startup. Setting this too low causes processes to be killed with
+    # return_code=137 (OOM kill); the symptom is "Box managed process exited
+    # unexpectedly" in the logs.  Raise on machines with ample RAM; lower only if
+    # you run exclusively Python (uvx) MCP servers.
+    # Can also be set via BOX__DEFAULT_MEMORY_MB. Default: 1536.
+    default_memory_mb: 1536
    docker:
        cpu_limit_enabled: true  # When false, Docker sandbox containers are started without --cpus. Memory and PID limits still apply.
    e2b:
@@ -104,6 +104,17 @@ def create_minimal_config(tmpdir: Path, port: int = 15300) -> Path:
                'user': 'postgres',
                'password': 'postgres',
            },
+            'valkey_search': {
+                'host': 'localhost',
+                'port': 6379,
+                'db': 0,
+                'password': '',
+                'username': '',
+                'tls': False,
+                'index_algorithm': 'HNSW',
+                'distance_metric': 'COSINE',
+                'request_timeout': 5000,
+            },
        },
        'storage': {
            'use': 'local',
@@ -0,0 +1,344 @@
+"""Integration tests for the Valkey Search VDB backend.
+
+These are SLOW, real-server tests.  They are gated on ``TEST_VALKEY_URL`` and
+skipped when it is unset (same precedent as the PostgreSQL migration tests).
+
+Run locally against valkey/valkey-bundle:9.1.0::
+
+    podman run -d --name valkey-test-langbot -p 6380:6379 valkey/valkey-bundle:9.1.0
+    TEST_VALKEY_URL=valkey://localhost:6380 \\
+        uv run pytest tests/integration/vector/test_valkey_search.py -m slow -q
+
+The default upstream fast CI lane (``-m "not slow"``) skips these; the local
+supervisor validator MUST run them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+from types import SimpleNamespace
+from urllib.parse import urlparse
+
+import pytest
+
+pytestmark = [pytest.mark.integration, pytest.mark.slow]
+
+
+def _parse_valkey_url(url: str) -> tuple[str, int, int]:
+    """Parse ``valkey://host:port/db`` into ``(host, port, db)``."""
+    parsed = urlparse(url)
+    host = parsed.hostname or 'localhost'
+    port = parsed.port or 6379
+    db = 0
+    if parsed.path and parsed.path.strip('/'):
+        try:
+            db = int(parsed.path.strip('/'))
+        except ValueError:
+            db = 0
+    return host, port, db
+
+
+@pytest.fixture
+def valkey_config():
+    url = os.environ.get('TEST_VALKEY_URL')
+    if not url:
+        pytest.skip('TEST_VALKEY_URL not set')
+    host, port, db = _parse_valkey_url(url)
+    return {
+        'host': host,
+        'port': port,
+        'db': db,
+        'password': '',
+        'username': '',
+        'tls': False,
+        'index_algorithm': 'HNSW',
+        'distance_metric': 'COSINE',
+    }
+
+
+def _make_ap(valkey_config):
+    """Build a minimal fake ``ap`` with the config + a no-op logger."""
+    logger = SimpleNamespace(
+        info=lambda *a, **k: None,
+        warning=lambda *a, **k: None,
+        error=lambda *a, **k: None,
+        debug=lambda *a, **k: None,
+    )
+    instance_config = SimpleNamespace(data={'vdb': {'valkey_search': valkey_config}})
+    return SimpleNamespace(instance_config=instance_config, logger=logger)
+
+
+@pytest.fixture
+async def backend(valkey_config):
+    """Create a Valkey Search backend, skip if module/server unavailable."""
+    from langbot.pkg.vector.vdbs.valkey_search import (
+        ValkeySearchVectorDatabase,
+        VALKEY_SEARCH_AVAILABLE,
+    )
+
+    if not VALKEY_SEARCH_AVAILABLE:
+        pytest.skip('valkey-glide not installed')
+
+    from glide import ft
+
+    ap = _make_ap(valkey_config)
+    db = ValkeySearchVectorDatabase(ap)
+    client = await db._ensure_client()
+
+    # Module-presence gate: FT.LIST must be available (Search module loaded).
+    try:
+        await ft.list(client)
+    except Exception as exc:  # noqa: BLE001
+        await client.close()
+        pytest.skip(f'Valkey Search module not available: {exc}')
+
+    collection = f'test_{uuid.uuid4().hex[:12]}'
+    yield db, collection
+
+    # Cleanup
+    try:
+        await db.delete_collection(collection)
+    except Exception:
+        pass
+    if db._client is not None:
+        await db._client.close()
+
+
+async def _poll_until(coro_factory, predicate, timeout=5.0, interval=0.2):
+    """Poll an async result until predicate is true (indexer is async)."""
+    deadline = asyncio.get_event_loop().time() + timeout
+    result = await coro_factory()
+    while not predicate(result) and asyncio.get_event_loop().time() < deadline:
+        await asyncio.sleep(interval)
+        result = await coro_factory()
+    return result
+
+
+def _sample_docs():
+    ids = ['d1', 'd2', 'd3']
+    embeddings = [
+        [1.0, 0.0, 0.0, 0.0],
+        [0.0, 1.0, 0.0, 0.0],
+        [0.9, 0.1, 0.0, 0.0],
+    ]
+    metadatas = [
+        {'file_id': 'fileA', 'topic': 'cats'},
+        {'file_id': 'fileB', 'topic': 'dogs'},
+        {'file_id': 'fileA', 'topic': 'cats'},
+    ]
+    documents = [
+        'the quick brown fox',
+        'lazy dogs sleeping',
+        'foxes and cats playing',
+    ]
+    return ids, embeddings, metadatas, documents
+
+
+@pytest.mark.asyncio
+async def test_add_and_vector_search(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+
+    result = await _poll_until(
+        lambda: db.search(collection, [1.0, 0.0, 0.0, 0.0], k=3, search_type='vector'),
+        lambda r: len(r['ids'][0]) >= 1,
+    )
+    assert len(result['ids'][0]) >= 1
+    # Closest to [1,0,0,0] should be d1.
+    assert result['ids'][0][0] == 'd1'
+    assert all(isinstance(d, float) for d in result['distances'][0])
+
+
+@pytest.mark.asyncio
+async def test_full_text_search(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+
+    result = await _poll_until(
+        lambda: db.search(collection, [0.0, 0.0, 0.0, 0.0], k=5, search_type='full_text', query_text='dogs'),
+        lambda r: len(r['ids'][0]) >= 1,
+    )
+    assert 'd2' in result['ids'][0]
+
+
+@pytest.mark.asyncio
+async def test_hybrid_filter_then_knn(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+
+    result = await _poll_until(
+        lambda: db.search(
+            collection,
+            [1.0, 0.0, 0.0, 0.0],
+            k=5,
+            search_type='hybrid',
+            query_text='cats',
+            filter={'file_id': 'fileA'},
+        ),
+        lambda r: len(r['ids'][0]) >= 1,
+    )
+    # Only fileA docs (d1, d3) should be candidates.
+    assert set(result['ids'][0]).issubset({'d1', 'd3'})
+
+
+@pytest.mark.asyncio
+async def test_vector_weight_not_honored(backend):
+    """Passing different vector_weight values must NOT change ranking."""
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+
+    common = dict(
+        collection=collection, query_embedding=[1.0, 0.0, 0.0, 0.0], k=3, search_type='hybrid', query_text='cats'
+    )
+    await _poll_until(lambda: db.search(**common), lambda r: len(r['ids'][0]) >= 1)
+
+    r_low = await db.search(**common, vector_weight=0.1)
+    r_high = await db.search(**common, vector_weight=0.9)
+    assert r_low['ids'][0] == r_high['ids'][0]
+
+
+@pytest.mark.asyncio
+async def test_filter_operators(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+
+    # Wait for indexing.
+    await _poll_until(
+        lambda: db.list_by_filter(collection, limit=10),
+        lambda r: r[1] >= 3,
+    )
+
+    # $eq
+    items, total = await db.list_by_filter(collection, filter={'file_id': 'fileA'})
+    assert total == 2
+    assert {it['id'] for it in items} == {'d1', 'd3'}
+
+    # $ne
+    items, total = await db.list_by_filter(collection, filter={'file_id': {'$ne': 'fileA'}})
+    assert {it['id'] for it in items} == {'d2'}
+
+    # $in
+    items, total = await db.list_by_filter(collection, filter={'file_id': {'$in': ['fileA', 'fileB']}})
+    assert total == 3
+
+    # $nin
+    items, total = await db.list_by_filter(collection, filter={'file_id': {'$nin': ['fileB']}})
+    assert {it['id'] for it in items} == {'d1', 'd3'}
+
+
+@pytest.mark.asyncio
+async def test_delete_by_file_id(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+    await _poll_until(lambda: db.list_by_filter(collection, limit=10), lambda r: r[1] >= 3)
+
+    await db.delete_by_file_id(collection, 'fileA')
+    items, total = await _poll_until(
+        lambda: db.list_by_filter(collection, limit=10),
+        lambda r: r[1] <= 1,
+    )
+    assert {it['id'] for it in items} == {'d2'}
+
+
+@pytest.mark.asyncio
+async def test_delete_by_filter_returns_count(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+    await _poll_until(lambda: db.list_by_filter(collection, limit=10), lambda r: r[1] >= 3)
+
+    deleted = await db.delete_by_filter(collection, filter={'file_id': 'fileA'})
+    assert deleted == 2
+
+
+@pytest.mark.asyncio
+async def test_list_by_filter_pagination(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+    await _poll_until(lambda: db.list_by_filter(collection, limit=10), lambda r: r[1] >= 3)
+
+    page1, total = await db.list_by_filter(collection, limit=2, offset=0)
+    assert total == 3
+    assert len(page1) == 2
+
+    page2, total = await db.list_by_filter(collection, limit=2, offset=2)
+    assert total == 3
+    assert len(page2) == 1
+
+
+@pytest.mark.asyncio
+async def test_delete_collection(backend):
+    db, collection = backend
+    ids, embeddings, metadatas, documents = _sample_docs()
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+    await _poll_until(lambda: db.list_by_filter(collection, limit=10), lambda r: r[1] >= 3)
+
+    await db.delete_collection(collection)
+
+    # After dropping, search on a missing index returns empty.
+    result = await db.search(collection, [1.0, 0.0, 0.0, 0.0], k=3, search_type='vector')
+    assert result['ids'][0] == []
+
+
+@pytest.mark.asyncio
+async def test_adversarial_filter_and_query_input(backend):
+    """Crafted FT special chars in file_id / query_text must not break out.
+
+    Guarantees locked in here:
+    * A file_id full of injection-style chars (quotes, parens, ``|``, ``@``,
+      ``:``, spaces, dashes) only ever matches its own row — the payload is
+      escaped to literal TAG content, never interpreted as extra clauses.
+    * A query_text full of FT operators does not raise and does not widen the
+      result set.
+    * A file_id containing FT-unsafe chars (``{`` / ``}`` / ``*``) is
+      percent-encoded, so it round-trips correctly: an exact match returns ONLY
+      its own row and never widens to an unrelated row, and the query does not
+      raise.
+    """
+    db, collection = backend
+
+    # Injection-style file_id WITHOUT FT-unsafe chars (the realistic surface).
+    injection_fid = 'evil") @file_id (".id|x-y:z'
+    # file_id WITH FT-unsafe chars that previously could not be queried.
+    brace_fid = 'x} @file_id:{*'
+    ids = ['adv1', 'benign2', 'brace3']
+    embeddings = [[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0]]
+    metadatas = [{'file_id': injection_fid}, {'file_id': 'plainB'}, {'file_id': brace_fid}]
+    documents = ['payload row content', 'unrelated benign content', 'brace row content']
+    await db.add_embeddings(collection, ids, embeddings, metadatas, documents)
+    await _poll_until(lambda: db.list_by_filter(collection, limit=10), lambda r: r[1] >= 3)
+
+    # Exact-match on the crafted file_id returns ONLY its own row.
+    items, total = await db.list_by_filter(collection, filter={'file_id': injection_fid})
+    assert total == 1
+    assert {it['id'] for it in items} == {'adv1'}
+
+    # A query_text packed with FT operators must not raise and must not match
+    # the benign row (escaped to literal terms, none of which it contains).
+    result = await db.search(
+        collection,
+        [0.0, 0.0, 0.0, 0.0],
+        k=5,
+        search_type='full_text',
+        query_text='@document:{*} | -()~ "evil"',
+    )
+    assert 'benign2' not in result['ids'][0]
+
+    # The brace/star-bearing file_id is encoded, so it round-trips: exact match
+    # returns ONLY its own row and never widens. No RequestError is raised.
+    b_items, b_total = await db.list_by_filter(collection, filter={'file_id': brace_fid})
+    assert b_total == 1
+    assert {it['id'] for it in b_items} == {'brace3'}
+
+    # And deletion by that file_id removes exactly its own row.
+    deleted = await db.delete_by_filter(collection, filter={'file_id': brace_fid})
+    assert deleted == 1
@@ -27,7 +27,7 @@

 ### 4. 向量数据库 (`vector/vdbs/`)
 - **路径**: `src/langbot/pkg/vector/vdbs/`
- **模块**: chroma, milvus, pgvector, qdrant, seekdb
+- **模块**: chroma, milvus, pgvector, qdrant, seekdb, valkey_search
 - **排除原因**: 需要真实向量数据库实例运行
 - **测试方式**: 需要 Docker 启动测试数据库或 mock
 - **状态**: 后续可补充 mock 测试
@@ -417,7 +417,7 @@ class TestBuildBoxSessionPayload:
        payload = s._build_box_session_payload('session-123')
        assert payload['image'] == 'node:20'
        assert payload['cpus'] == 2.0
-        assert payload['memory_mb'] == 1024
+        assert payload["memory_mb"] == 1024
        assert payload['pids_limit'] == 256

    def test_none_fields_excluded(self, mcp_module):
@@ -639,10 +639,13 @@ class TestGetRuntimeInfoDict:
        assert info['box_session_id'] == 'mcp-shared'
        assert info['box_enabled'] is True

-    def test_transient_test_session_is_isolated_from_shared(self, mcp_module):
-        """A transient test session (config-page "test", no persisted UUID)
-        must NOT share the live "mcp-shared" Box session. Regression: a failing
-        test churned the shared session and tore down healthy live servers."""
+    def test_transient_test_shares_session_but_isolated_by_process(self, mcp_module):
+        """A transient config-page "test" now shares the same 'mcp-shared' Box
+        session as live servers (so a test reuses the running container / live
+        process instead of a cold per-test session bootstrap). Isolation is at
+        the PROCESS level: the test runs under its own process_id and only ever
+        stops that process_id, so it cannot disturb another server's live
+        process or the shared session itself."""
        ap = _make_ap()
        ap.box_service.available = True
        transient = _make_session(
@@ -670,10 +673,12 @@ class TestGetRuntimeInfoDict:
        )
        assert transient.is_transient is True
        assert live.is_transient is False
-        # Isolated session id for the test, shared for the live server.
-        assert transient._build_box_session_id() == 'mcp-test-gen-uuid-123'
+        # Both share ONE Box session ...
+        assert transient._build_box_session_id() == 'mcp-shared'
        assert live._build_box_session_id() == 'mcp-shared'
-        assert transient._build_box_session_id() != live._build_box_session_id()
+        assert transient._build_box_session_id() == live._build_box_session_id()
+        # ... but are isolated by distinct process_ids within that session.
+        assert transient._box_stdio_runtime.process_id != live._box_stdio_runtime.process_id

    def test_stdio_session_refuses_when_box_unavailable(self, mcp_module):
        """Policy: when Box is configured but unavailable (disabled in config
@@ -824,3 +829,129 @@ async def test_init_box_stdio_server_stages_host_path_in_shared_workspace(mcp_mo
    assert process_payload['command'] == 'python'
    assert process_payload['args'] == ['/workspace/.mcp/u1/workspace/server.py']
    assert process_payload['cwd'] == '/workspace/.mcp/u1/workspace'
+
+
+@pytest.mark.asyncio
+async def test_stdio_handshake_raises_coldstart_retry_while_process_alive(mcp_module, tmp_path, monkeypatch):
+    """During a slow (npx) cold start the handshake fails while the managed
+    process is still alive. initialize() must raise _ColdStartRetry (so the
+    outer lifecycle loop reuses the live process and retries without stopping it
+    or consuming the fatal budget), NOT a fatal error."""
+    from contextlib import asynccontextmanager
+
+    mcp_stdio_module = sys.modules['langbot.pkg.provider.tools.loaders.mcp_stdio']
+
+    class ColdClientSession:
+        def __init__(self, *_args):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return False
+
+        async def initialize(self):
+            # Process still cold-starting: handshake fails.
+            raise Exception('Connection closed')
+
+    @asynccontextmanager
+    async def fake_websocket_client(_url: str):
+        yield ('read-stream', 'write-stream')
+
+    monkeypatch.setattr(mcp_stdio_module, 'ClientSession', ColdClientSession)
+    monkeypatch.setattr(mcp_stdio_module, 'websocket_client', fake_websocket_client)
+    monkeypatch.setattr(mcp_stdio_module, '_HANDSHAKE_ATTEMPT_TIMEOUT_SEC', 1.0, raising=False)
+
+    ap = _make_ap()
+    ap.box_service.available = True
+    ap.box_service.create_session = AsyncMock(return_value={})
+    ap.box_service.start_managed_process = AsyncMock(return_value={})
+    ap.box_service.get_managed_process_websocket_url = Mock(return_value='ws://box/p')
+
+    session = _make_session(
+        mcp_module,
+        {
+            'name': 'slow',
+            'uuid': 'slow-uuid',
+            'mode': 'stdio',
+            'command': 'npx',
+            'args': ['-y', 'some-mcp'],
+        },
+        ap=ap,
+    )
+
+    # Process is NOT exited (still cold-starting) and not yet running for reuse.
+    async def _not_exited():
+        return False
+
+    session._box_stdio_runtime._managed_process_has_exited = _not_exited
+
+    async def _not_running():
+        return False
+
+    session._box_stdio_runtime._managed_process_is_running = _not_running
+
+    with pytest.raises(mcp_stdio_module._ColdStartRetry):
+        await session._init_box_stdio_server()
+
+    # Process was started exactly once (the retry will reuse it, not rebuild).
+    assert ap.box_service.start_managed_process.await_count == 1
+    await session.exit_stack.aclose()
+
+
+@pytest.mark.asyncio
+async def test_stdio_handshake_raises_fatal_when_process_exited(mcp_module, tmp_path, monkeypatch):
+    """If the handshake fails AND the process has definitively exited, that is a
+    real failure — initialize() must NOT swallow it as a cold-start retry."""
+    from contextlib import asynccontextmanager
+
+    mcp_stdio_module = sys.modules['langbot.pkg.provider.tools.loaders.mcp_stdio']
+
+    class DeadClientSession:
+        def __init__(self, *_args):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb):
+            return False
+
+        async def initialize(self):
+            raise Exception('Connection closed')
+
+    @asynccontextmanager
+    async def fake_websocket_client(_url: str):
+        yield ('read-stream', 'write-stream')
+
+    monkeypatch.setattr(mcp_stdio_module, 'ClientSession', DeadClientSession)
+    monkeypatch.setattr(mcp_stdio_module, 'websocket_client', fake_websocket_client)
+    monkeypatch.setattr(mcp_stdio_module, '_HANDSHAKE_ATTEMPT_TIMEOUT_SEC', 1.0, raising=False)
+
+    ap = _make_ap()
+    ap.box_service.available = True
+    ap.box_service.create_session = AsyncMock(return_value={})
+    ap.box_service.start_managed_process = AsyncMock(return_value={})
+    ap.box_service.get_managed_process_websocket_url = Mock(return_value='ws://box/p')
+
+    session = _make_session(
+        mcp_module,
+        {'name': 'dead', 'uuid': 'dead-uuid', 'mode': 'stdio', 'command': 'npx', 'args': ['-y', 'x']},
+        ap=ap,
+    )
+
+    async def _exited():
+        return True
+
+    session._box_stdio_runtime._managed_process_has_exited = _exited
+
+    async def _not_running():
+        return False
+
+    session._box_stdio_runtime._managed_process_is_running = _not_running
+
+    with pytest.raises(Exception) as ei:
+        await session._init_box_stdio_server()
+    assert not isinstance(ei.value, mcp_stdio_module._ColdStartRetry)
+    await session.exit_stack.aclose()
@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock, Mock
+
+import httpx
+import pytest
+from aiohttp import web
+from mcp import types as mcp_types
+
+from langbot.pkg.provider.tools.loaders.mcp import RuntimeMCPSession
+
+
+class _TransportProbe:
+    def __init__(self, streamable_status: int | None) -> None:
+        self.streamable_status = streamable_status
+        self.streamable_posts = 0
+        self.streamable_messages: list[str] = []
+        self.sse_gets = 0
+        self.sse_messages: list[str] = []
+        self.streamable_request_started = asyncio.Event()
+        self.release_streamable_request = asyncio.Event()
+        self._sse_response: web.StreamResponse | None = None
+
+    async def handle_mcp_endpoint(self, request: web.Request) -> web.StreamResponse:
+        if request.method == 'POST':
+            self.streamable_posts += 1
+            self.streamable_request_started.set()
+            if self.streamable_status is None:
+                await self.release_streamable_request.wait()
+                return web.Response(status=204)
+            if self.streamable_status == 200:
+                message = await request.json()
+                method = message.get('method', '')
+                self.streamable_messages.append(method)
+                if method == 'initialize':
+                    return web.json_response(
+                        {
+                            'jsonrpc': '2.0',
+                            'id': message['id'],
+                            'result': {
+                                'protocolVersion': mcp_types.LATEST_PROTOCOL_VERSION,
+                                'capabilities': {'tools': {}},
+                                'serverInfo': {'name': 'streamable-test', 'version': '1.0.0'},
+                            },
+                        }
+                    )
+                if method == 'tools/list':
+                    return web.json_response(
+                        {
+                            'jsonrpc': '2.0',
+                            'id': message['id'],
+                            'result': {
+                                'tools': [
+                                    {
+                                        'name': 'echo',
+                                        'description': 'Echo test input',
+                                        'inputSchema': {'type': 'object'},
+                                    }
+                                ]
+                            },
+                        }
+                    )
+                return web.Response(status=202)
+            return web.Response(status=self.streamable_status)
+
+        self.sse_gets += 1
+        response = web.StreamResponse(
+            status=200,
+            headers={
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+            },
+        )
+        await response.prepare(request)
+        self._sse_response = response
+        await response.write(b'event: endpoint\ndata: /messages?session_id=test-session\n\n')
+        try:
+            while request.transport is not None and not request.transport.is_closing():
+                await asyncio.sleep(0.05)
+        except asyncio.CancelledError:
+            raise
+        return response
+
+    async def handle_sse_message(self, request: web.Request) -> web.Response:
+        message = await request.json()
+        method = message.get('method', '')
+        self.sse_messages.append(method)
+
+        if method == 'initialize':
+            response_message = {
+                'jsonrpc': '2.0',
+                'id': message['id'],
+                'result': {
+                    'protocolVersion': mcp_types.LATEST_PROTOCOL_VERSION,
+                    'capabilities': {},
+                    'serverInfo': {'name': 'legacy-sse-test', 'version': '1.0.0'},
+                },
+            }
+            assert self._sse_response is not None
+            payload = json.dumps(response_message, separators=(',', ':'))
+            await self._sse_response.write(f'event: message\ndata: {payload}\n\n'.encode())
+
+        return web.Response(status=202)
+
+
+@asynccontextmanager
+async def _transport_server(streamable_status: int | None):
+    probe = _TransportProbe(streamable_status)
+    application = web.Application()
+    application.router.add_route('*', '/mcp', probe.handle_mcp_endpoint)
+    application.router.add_post('/messages', probe.handle_sse_message)
+    runner = web.AppRunner(application, shutdown_timeout=0.1)
+    await runner.setup()
+    site = web.TCPSite(runner, '127.0.0.1', 0)
+    await site.start()
+    server = cast(asyncio.Server, site._server)
+    port = server.sockets[0].getsockname()[1]
+    try:
+        yield probe, f'http://127.0.0.1:{port}/mcp'
+    finally:
+        await runner.cleanup()
+
+
+def _session(url: str, *, timeout: float = 2) -> RuntimeMCPSession:
+    app = cast(Any, SimpleNamespace(logger=Mock()))
+    return RuntimeMCPSession(
+        'remote-transport-test',
+        {'uuid': 'srv-1', 'mode': 'remote', 'url': url, 'timeout': timeout},
+        True,
+        app,
+    )
+
+
+def _contains_http_status(exc: BaseException, status_code: int) -> bool:
+    return any(
+        isinstance(leaf, httpx.HTTPStatusError) and leaf.response.status_code == status_code
+        for leaf in RuntimeMCPSession._iter_exception_leaves(exc)
+    )
+
+
+async def _close_session(session: RuntimeMCPSession) -> None:
+    await session.exit_stack.aclose()
+
+
+@pytest.mark.asyncio
+async def test_remote_transport_real_streamable_http_success_keeps_session_usable():
+    async with _transport_server(200) as (probe, url):
+        session = _session(url)
+        try:
+            await session._init_remote_server()
+            assert session.session is not None
+            tools = await session.session.list_tools()
+            assert [tool.name for tool in tools.tools] == ['echo']
+            assert probe.streamable_posts >= 2
+            assert probe.streamable_messages[:2] == ['initialize', 'notifications/initialized']
+            assert 'tools/list' in probe.streamable_messages
+            assert probe.sse_gets == 0
+        finally:
+            await _close_session(session)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('status_code', [400, 404, 405])
+async def test_remote_transport_real_streamable_http_error_falls_back_to_legacy_sse(status_code: int):
+    async with _transport_server(status_code) as (probe, url):
+        session = _session(url)
+        try:
+            await session._init_remote_server()
+            assert session.session is not None
+            assert probe.streamable_posts == 1
+            assert probe.sse_gets == 1
+            assert 'initialize' in probe.sse_messages
+        finally:
+            await _close_session(session)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('status_code', [401, 403, 406, 415, 429, 500])
+async def test_remote_transport_real_non_compatibility_error_does_not_fallback(status_code: int):
+    async with _transport_server(status_code) as (probe, url):
+        session = _session(url)
+        try:
+            with pytest.raises(BaseException) as exc_info:
+                await session._init_remote_server()
+            assert _contains_http_status(exc_info.value, status_code)
+            assert probe.streamable_posts == 1
+            assert probe.sse_gets == 0
+        finally:
+            await _close_session(session)
+
+
+@pytest.mark.asyncio
+async def test_remote_transport_real_timeout_does_not_fallback():
+    async with _transport_server(None) as (probe, url):
+        session = _session(url, timeout=0.05)
+        try:
+            with pytest.raises(BaseException) as exc_info:
+                await session._init_remote_server()
+            assert any(
+                isinstance(leaf, httpx.TimeoutException)
+                for leaf in RuntimeMCPSession._iter_exception_leaves(exc_info.value)
+            )
+            assert probe.streamable_posts == 1
+            assert probe.sse_gets == 0
+        finally:
+            probe.release_streamable_request.set()
+            await _close_session(session)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('error_type', [httpx.ConnectError, httpx.ConnectTimeout])
+async def test_remote_transport_connection_errors_do_not_fallback(error_type: type[httpx.RequestError]):
+    request = httpx.Request('POST', 'https://unreachable.invalid/mcp')
+    error = error_type('connection failed', request=request)
+    session = _session(str(request.url))
+    session._init_streamable_http_server = AsyncMock(side_effect=error)
+    session._init_sse_server = AsyncMock()
+
+    with pytest.raises(type(error)) as exc_info:
+        await session._init_remote_server()
+
+    assert exc_info.value is error
+    session._init_sse_server.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_remote_transport_external_cancellation_is_not_converted_to_sse_fallback():
+    async with _transport_server(None) as (probe, url):
+        session = _session(url)
+        task = asyncio.create_task(session._init_remote_server())
+        await asyncio.wait_for(probe.streamable_request_started.wait(), timeout=2)
+        task.cancel()
+        try:
+            with pytest.raises(asyncio.CancelledError):
+                await task
+            assert probe.sse_gets == 0
+        finally:
+            probe.release_streamable_request.set()
+            await _close_session(session)
@@ -4,6 +4,7 @@ import base64
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, Mock

+import httpx
 import pytest
 from mcp import types as mcp_types

@@ -54,6 +55,50 @@ def _query() -> SimpleNamespace:
    return SimpleNamespace(variables={})


+def _http_status_error(status_code: int) -> httpx.HTTPStatusError:
+    request = httpx.Request('POST', 'https://example.com/mcp')
+    response = httpx.Response(status_code, request=request)
+    return httpx.HTTPStatusError(f'HTTP {status_code}', request=request, response=response)
+
+
+@pytest.mark.asyncio
+async def test_remote_transport_falls_back_to_sse_for_compatible_http_status_in_exception_group():
+    session = RuntimeMCPSession(
+        'remote',
+        {'uuid': 'srv-1', 'mode': 'remote', 'url': 'https://example.com/mcp'},
+        True,
+        _app(),
+    )
+    session._init_streamable_http_server = AsyncMock(
+        side_effect=ExceptionGroup('transport failed', [_http_status_error(405)])
+    )
+    session._init_sse_server = AsyncMock()
+
+    await session._init_remote_server()
+
+    session._init_streamable_http_server.assert_awaited_once()
+    session._init_sse_server.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_remote_transport_does_not_fallback_for_auth_http_status():
+    session = RuntimeMCPSession(
+        'remote',
+        {'uuid': 'srv-1', 'mode': 'remote', 'url': 'https://example.com/mcp'},
+        True,
+        _app(),
+    )
+    error = _http_status_error(403)
+    session._init_streamable_http_server = AsyncMock(side_effect=error)
+    session._init_sse_server = AsyncMock()
+
+    with pytest.raises(httpx.HTTPStatusError):
+        await session._init_remote_server()
+
+    session._init_streamable_http_server.assert_awaited_once()
+    session._init_sse_server.assert_not_awaited()
+
+
@pytest.mark.asyncio
 async def test_read_resource_envelope_truncates_caches_and_records_trace():
    session = _connected_session()
@@ -33,7 +33,7 @@ class TestVectorDBManagerInitialization:
        mocks['langbot.pkg.core.app'] = MagicMock()

        # Mock all VDB backend implementations
-        for backend in ['chroma', 'qdrant', 'seekdb', 'milvus', 'pgvector_db']:
+        for backend in ['chroma', 'qdrant', 'seekdb', 'milvus', 'pgvector_db', 'valkey_search']:
            mocks[f'langbot.pkg.vector.vdbs.{backend}'] = MagicMock()

        return mocks
@@ -123,6 +123,25 @@ class TestVectorDBManagerInitialization:

            mock_seekdb_class.assert_called_once_with(mock_app)

+    def test_initialize_valkey_search_backend(self):
+        """Valkey Search config uses ValkeySearchVectorDatabase backend."""
+        vdb_config = {'use': 'valkey_search'}
+        mock_app = self._create_mock_app(vdb_config)
+
+        mocks = self._make_vector_import_mocks()
+        mock_valkey_class = MagicMock()
+        mocks['langbot.pkg.vector.vdbs.valkey_search'].ValkeySearchVectorDatabase = mock_valkey_class
+
+        with isolated_sys_modules(mocks):
+            from langbot.pkg.vector.mgr import VectorDBManager
+
+            mgr = VectorDBManager(mock_app)
+
+            import asyncio
+            asyncio.get_event_loop().run_until_complete(mgr.initialize())
+
+            mock_valkey_class.assert_called_once_with(mock_app)
+
    def test_initialize_milvus_backend_with_uri(self):
        """Milvus config with custom URI."""
        vdb_config = {
@@ -0,0 +1,391 @@
+"""Unit tests for the Valkey Search VDB backend's pure helpers.
+
+These tests exercise the filter-to-FT mapping, float32 packing, tag/text
+escaping, FT.SEARCH reply parsing and the import guard.  They run in the fast
+CI lane and require NO running Valkey server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+from importlib import import_module
+from unittest.mock import AsyncMock
+
+import pytest
+
+
+def get_valkey_module():
+    """Lazy import of the valkey_search backend module."""
+    return import_module('langbot.pkg.vector.vdbs.valkey_search')
+
+
+def make_backend():
+    """Construct a backend instance without running its __init__.
+
+    The constructor needs a live ``ap`` + config; for pure-helper tests we
+    only need a bare instance with the attributes the helpers touch.
+    """
+    mod = get_valkey_module()
+    backend = object.__new__(mod.ValkeySearchVectorDatabase)
+    # _ensure_client serializes creation through this lock; set it here since
+    # __init__ (which normally creates it) is bypassed.
+    backend._client_lock = asyncio.Lock()
+    return backend
+
+
+class TestFloat32Packing:
+    """Tests for _pack_vector little-endian float32 packing."""
+
+    def test_pack_round_trips(self):
+        mod = get_valkey_module()
+        vec = [0.1, -2.5, 3.0, 4.25]
+        packed = mod.ValkeySearchVectorDatabase._pack_vector(vec)
+        assert isinstance(packed, bytes)
+        assert len(packed) == 4 * len(vec)
+        unpacked = list(struct.unpack(f'<{len(vec)}f', packed))
+        for original, restored in zip(vec, unpacked):
+            assert restored == pytest.approx(original, rel=1e-6)
+
+    def test_pack_is_little_endian(self):
+        mod = get_valkey_module()
+        packed = mod.ValkeySearchVectorDatabase._pack_vector([1.0])
+        assert packed == struct.pack('<f', 1.0)
+
+
+class TestTagEscaping:
+    """Tests for _escape_tag."""
+
+    def test_escapes_special_chars(self):
+        mod = get_valkey_module()
+        escaped = mod.ValkeySearchVectorDatabase._escape_tag('a-b c.d')
+        assert '\\-' in escaped
+        assert '\\ ' in escaped
+        assert '\\.' in escaped
+
+    def test_plain_value_unchanged(self):
+        mod = get_valkey_module()
+        assert mod.ValkeySearchVectorDatabase._escape_tag('abc123') == 'abc123'
+
+
+class TestFileIdEncoding:
+    """Tests for _encode_file_id (FT-unsafe char percent-encoding)."""
+
+    def test_uuid_is_noop(self):
+        mod = get_valkey_module()
+        fid = '550e8400-e29b-41d4-a716-446655440000'
+        assert mod.ValkeySearchVectorDatabase._encode_file_id(fid) == fid
+
+    def test_encodes_braces_star_and_percent(self):
+        mod = get_valkey_module()
+        enc = mod.ValkeySearchVectorDatabase._encode_file_id('a{b}c*d%e')
+        # '{'=7B '}'=7D '*'=2A '%'=25
+        assert enc == 'a%7Bb%7Dc%2Ad%25e'
+        # No raw FT-unsafe char survives.
+        assert all(ch not in enc for ch in '{}*') or '%' in enc
+
+    def test_encoding_is_deterministic_and_collision_safe(self):
+        mod = get_valkey_module()
+        enc = mod.ValkeySearchVectorDatabase._encode_file_id
+        # A literal "%7B" must not collide with an encoded "{".
+        assert enc('{') != enc('%7B')
+        assert enc('{') == '%7B'
+        assert enc('%7B') == '%257B'
+
+    def test_filter_encodes_unsafe_chars_in_tag_query(self):
+        backend = make_backend()
+        # The emitted TAG query must contain the encoded form, never raw braces.
+        frag = backend._triples_to_ft({'file_id': 'x}y{z*'})
+        assert '7D' in frag and '7B' in frag and '2A' in frag
+        # No raw '*' from the value, and exactly one opening/closing brace (the
+        # TAG-clause delimiters) — the value's own braces were encoded away.
+        assert '*' not in frag
+        assert frag.count('{') == 1 and frag.count('}') == 1
+        assert frag.startswith('@file_id:{') and frag.endswith('}')
+
+    def test_filter_in_operator_encodes_each_value(self):
+        backend = make_backend()
+        frag = backend._triples_to_ft({'file_id': {'$in': ['a*b', 'c}d']}})
+        assert '2A' in frag and '7D' in frag
+        assert '*' not in frag
+
+
+class TestFilterToFt:
+    """Tests for _triples_to_ft filter mapping (all 8 operators)."""
+
+    def test_empty_filter_returns_empty_string(self):
+        backend = make_backend()
+        assert backend._triples_to_ft(None) == ''
+        assert backend._triples_to_ft({}) == ''
+
+    def test_eq_tag(self):
+        backend = make_backend()
+        assert backend._triples_to_ft({'file_id': 'abc'}) == '@file_id:{abc}'
+
+    def test_explicit_eq_tag(self):
+        backend = make_backend()
+        assert backend._triples_to_ft({'file_id': {'$eq': 'abc'}}) == '@file_id:{abc}'
+
+    def test_ne_tag(self):
+        backend = make_backend()
+        assert backend._triples_to_ft({'file_id': {'$ne': 'abc'}}) == '-@file_id:{abc}'
+
+    def test_in_tag(self):
+        backend = make_backend()
+        assert backend._triples_to_ft({'file_id': {'$in': ['a', 'b']}}) == '@file_id:{a|b}'
+
+    def test_nin_tag(self):
+        backend = make_backend()
+        assert backend._triples_to_ft({'file_id': {'$nin': ['a', 'b']}}) == '-@file_id:{a|b}'
+
+    def test_numeric_range_operators(self):
+        backend = make_backend()
+        # file_id is the only indexed field; numeric ops still render via the
+        # generic range fragment, so use file_id to keep the field supported.
+        # Values are cast to float (defensive against non-numeric input and a
+        # future NUMERIC field becoming an injection surface).
+        assert backend._triples_to_ft({'file_id': {'$gt': 5}}) == '@file_id:[(5.0 +inf]'
+        assert backend._triples_to_ft({'file_id': {'$gte': 5}}) == '@file_id:[5.0 +inf]'
+        assert backend._triples_to_ft({'file_id': {'$lt': 5}}) == '@file_id:[-inf (5.0]'
+        assert backend._triples_to_ft({'file_id': {'$lte': 5}}) == '@file_id:[-inf 5.0]'
+
+    def test_numeric_range_rejects_non_numeric(self):
+        backend = make_backend()
+        # A non-numeric range value fails closed rather than interpolating raw.
+        with pytest.raises((ValueError, TypeError)):
+            backend._triples_to_ft({'file_id': {'$gt': 'not-a-number'}})
+
+    def test_unsupported_field_dropped(self):
+        backend = make_backend()
+        # Non-indexed fields are dropped (returns empty expression).
+        assert backend._triples_to_ft({'some_other_field': 'x'}) == ''
+
+    def test_multiple_supported_keys_anded(self):
+        backend = make_backend()
+        # Two conditions on the same indexed field are joined with a space (AND).
+        result = backend._triples_to_ft({'file_id': {'$in': ['a', 'b']}})
+        assert result == '@file_id:{a|b}'
+
+
+class TestTextEscaping:
+    """Tests for _escape_text full-text escaping."""
+
+    def test_escapes_ft_special_chars(self):
+        mod = get_valkey_module()
+        escaped = mod.ValkeySearchVectorDatabase._escape_text('hello@world|test')
+        assert '\\@' in escaped
+        assert '\\|' in escaped
+
+
+class TestReplyToChroma:
+    """Tests for _reply_to_chroma FT.SEARCH reply parsing."""
+
+    def test_parses_knn_reply(self):
+        backend = make_backend()
+        # glide returns [total, {key: {field: value}}]
+        reply = [
+            2,
+            {
+                b'kb:col1:id1': {
+                    b'distance': b'0.10',
+                    b'document': b'hello',
+                    b'metadata_json': b'{"file_id": "f1"}',
+                },
+                b'kb:col1:id2': {
+                    b'distance': b'0.25',
+                    b'document': b'world',
+                    b'metadata_json': b'{"file_id": "f2"}',
+                },
+            },
+        ]
+        result = backend._reply_to_chroma('idx:col1', reply, has_distance=True)
+        assert result['ids'][0] == ['id1', 'id2']
+        assert result['distances'][0] == [pytest.approx(0.10), pytest.approx(0.25)]
+        assert result['metadatas'][0][0] == {'file_id': 'f1'}
+        assert result['metadatas'][0][1] == {'file_id': 'f2'}
+
+    def test_empty_reply(self):
+        backend = make_backend()
+        result = backend._reply_to_chroma('idx:col1', [0, {}], has_distance=True)
+        assert result == {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+
+    def test_malformed_reply(self):
+        backend = make_backend()
+        result = backend._reply_to_chroma('idx:col1', [], has_distance=True)
+        assert result == {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
+
+    def test_text_search_reply_no_distance(self):
+        backend = make_backend()
+        reply = [
+            1,
+            {
+                b'kb:col1:id1': {
+                    b'document': b'hello',
+                    b'metadata_json': b'{"file_id": "f1"}',
+                },
+            },
+        ]
+        result = backend._reply_to_chroma('idx:col1', reply, has_distance=False)
+        assert result['ids'][0] == ['id1']
+        assert result['distances'][0] == [0.0]
+
+
+class TestImportGuard:
+    """Tests for the ImportError guard when glide is unavailable."""
+
+    def test_constructor_raises_when_unavailable(self, monkeypatch):
+        mod = get_valkey_module()
+        monkeypatch.setattr(mod, 'VALKEY_SEARCH_AVAILABLE', False)
+        with pytest.raises(ImportError, match='valkey-glide'):
+            mod.ValkeySearchVectorDatabase(ap=None)
+
+
+class TestSupportedSearchTypes:
+    """Tests for supported_search_types."""
+
+    def test_supports_vector_full_text_hybrid(self):
+        mod = get_valkey_module()
+        from langbot.pkg.vector.vdb import SearchType
+
+        types = mod.ValkeySearchVectorDatabase.supported_search_types()
+        assert SearchType.VECTOR in types
+        assert SearchType.FULL_TEXT in types
+        assert SearchType.HYBRID in types
+
+
+class TestDeleteByFilterGuard:
+    """Regression tests for the delete_by_filter mass-deletion guard.
+
+    A non-empty filter referencing only non-indexed fields must NOT fall back
+    to match-all and wipe the whole collection: it must skip and return 0.
+    """
+
+    async def test_unsupported_only_filter_skips_and_returns_zero(self):
+        backend = make_backend()
+        # Make the client/index lookups succeed without a real server.
+        backend._client = AsyncMock()
+        backend.ap = type('Ap', (), {'logger': AsyncMock()})()
+        backend._ensure_client = AsyncMock(return_value=backend._client)
+        backend._index_exists = AsyncMock(return_value=True)
+        # _search_keys must never be reached for an unusable filter.
+        backend._search_keys = AsyncMock(
+            side_effect=AssertionError('_search_keys must not be called for an unusable filter')
+        )
+
+        # Filter references only a non-indexed field -> maps to no FT conditions.
+        deleted = await backend.delete_by_filter('col1', {'some_other_field': 'x'})
+
+        assert deleted == 0
+        backend._client.delete.assert_not_called()
+
+    async def test_supported_filter_deletes_matching_keys(self):
+        backend = make_backend()
+        backend._client = AsyncMock()
+        backend.ap = type('Ap', (), {'logger': AsyncMock()})()
+        backend._ensure_client = AsyncMock(return_value=backend._client)
+        backend._index_exists = AsyncMock(return_value=True)
+        backend._search_keys = AsyncMock(return_value=['kb:col1:id1', 'kb:col1:id2'])
+
+        deleted = await backend.delete_by_filter('col1', {'file_id': 'f1'})
+
+        assert deleted == 2
+        backend._client.delete.assert_awaited_once_with(['kb:col1:id1', 'kb:col1:id2'])
+
+
+class TestClose:
+    """Tests for the close() teardown."""
+
+    async def test_close_resets_client_and_indexes(self):
+        backend = make_backend()
+        client = AsyncMock()
+        backend._client = client
+        backend.ap = type('Ap', (), {'logger': AsyncMock()})()
+        backend._ensured_indexes = {'idx:col1'}
+
+        await backend.close()
+
+        client.close.assert_awaited_once()
+        assert backend._client is None
+        assert backend._ensured_indexes == set()
+
+    async def test_close_is_noop_when_no_client(self):
+        backend = make_backend()
+        backend._client = None
+        backend.ap = type('Ap', (), {'logger': AsyncMock()})()
+        backend._ensured_indexes = set()
+        # Should not raise.
+        await backend.close()
+        assert backend._client is None
+
+
+class TestCredentialsBuild:
+    """Tests for the auth-credential construction in _ensure_client."""
+
+    def _prep_backend(self, mod, monkeypatch, *, username, password):
+        backend = make_backend()
+        backend._client = None
+        backend._host = 'localhost'
+        backend._port = 6379
+        backend._db = 0
+        backend._tls = False
+        backend._username = username
+        backend._password = password
+        backend._request_timeout = 5000
+        backend._ensured_indexes = set()
+        warnings: list[str] = []
+        backend.ap = type(
+            'Ap',
+            (),
+            {
+                'logger': type(
+                    'L', (), {'info': lambda self, *a, **k: None, 'warning': lambda s, m, *a, **k: warnings.append(m)}
+                )()
+            },
+        )()
+
+        created = {}
+
+        class _FakeClient:
+            @staticmethod
+            async def create(conf):
+                created['conf'] = conf
+                return AsyncMock()
+
+        cred_calls: list[dict] = []
+
+        def _fake_credentials(**kwargs):
+            cred_calls.append(kwargs)
+            return ('CRED', kwargs)
+
+        # These names are absent when the optional valkey-glide dependency is
+        # unavailable (for example, on Windows), so allow the test doubles to
+        # create them on the module.
+        monkeypatch.setattr(mod, 'GlideClient', _FakeClient, raising=False)
+        monkeypatch.setattr(mod, 'ServerCredentials', _fake_credentials, raising=False)
+        monkeypatch.setattr(mod, 'GlideClientConfiguration', lambda **kw: kw, raising=False)
+        monkeypatch.setattr(mod, 'NodeAddress', lambda *a, **k: ('node', a, k), raising=False)
+        return backend, created, cred_calls, warnings
+
+    async def test_username_without_password_fails_closed(self, monkeypatch):
+        mod = get_valkey_module()
+        backend, created, cred_calls, warnings = self._prep_backend(mod, monkeypatch, username='acluser', password=None)
+
+        # A username without a password must fail closed rather than silently
+        # connecting unauthenticated to a (potentially shared) Valkey instance.
+        with pytest.raises(ValueError, match='without a password'):
+            await backend._ensure_client()
+
+        assert cred_calls == []  # ServerCredentials NOT constructed
+        assert 'conf' not in created  # client never created
+
+    async def test_password_builds_credentials(self, monkeypatch):
+        mod = get_valkey_module()
+        backend, created, cred_calls, warnings = self._prep_backend(
+            mod, monkeypatch, username='acluser', password='secret'
+        )
+
+        await backend._ensure_client()
+
+        assert len(cred_calls) == 1
+        assert cred_calls[0] == {'password': 'secret', 'username': 'acluser'}
+        assert created['conf']['credentials'] == ('CRED', {'password': 'secret', 'username': 'acluser'})
@@ -2084,6 +2084,7 @@ dependencies = [
    { name = "tiktoken" },
    { name = "urllib3" },
    { name = "uv" },
+    { name = "valkey-glide", marker = "sys_platform != 'win32'" },
    { name = "websockets" },
 ]

@@ -2123,7 +2124,7 @@ requires-dist = [
    { name = "ebooklib", specifier = ">=0.18" },
    { name = "gewechat-client", specifier = ">=0.1.5" },
    { name = "html2text", specifier = ">=2024.2.26" },
-    { name = "langbot-plugin", specifier = "==0.4.7" },
+    { name = "langbot-plugin", specifier = "==0.4.13" },
    { name = "langchain", specifier = ">=1.3.9" },
    { name = "langchain-core", specifier = ">=1.3.3" },
    { name = "langchain-text-splitters", specifier = ">=1.1.2" },
@@ -2172,6 +2173,7 @@ requires-dist = [
    { name = "tiktoken", specifier = ">=0.9.0" },
    { name = "urllib3", specifier = ">=2.7.0" },
    { name = "uv", specifier = ">=0.11.15" },
+    { name = "valkey-glide", marker = "sys_platform != 'win32'", specifier = ">=2.4.1,<3.0.0" },
    { name = "websockets", specifier = ">=15.0.1" },
 ]

@@ -2187,7 +2189,7 @@ dev = [

 [[package]]
 name = "langbot-plugin"
-version = "0.4.7"
+version = "0.4.13"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "aiofiles" },
@@ -2208,9 +2210,9 @@ dependencies = [
    { name = "watchdog" },
    { name = "websockets" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/00/6c/850a92cc05583ab71e6ac527ff50fa5f3db43cc16e86f4f6d5ac684da9a8/langbot_plugin-0.4.7.tar.gz", hash = "sha256:16b24d79fc55c0a6b15d901b1134de9e298e2cadab9a9b25c9231f731333ebe9", size = 333867, upload-time = "2026-07-02T16:49:46.258Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/40/a6/1eaf77c3b81e9de3390c504c5f627dc41f43bff6df9aff0e1e31d796b6f0/langbot_plugin-0.4.13.tar.gz", hash = "sha256:f936340e67679c21f1e7e7f1447339f31a0a2c965db060ecfbd9d0c51bb0d6fe", size = 334887, upload-time = "2026-07-04T05:38:59.942Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c6/f5/a00a929ffb4dcbd958e5f5249516f19ecc720f25f072c9bfda8bbb56851c/langbot_plugin-0.4.7-py3-none-any.whl", hash = "sha256:1364f80fcf448f4503e87d1367af60438abd2cf16e78be6807032cbdb4710a56", size = 220999, upload-time = "2026-07-02T16:49:44.868Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/bf/fc9671a7afbd933440c38403c84d918c1022fdeed16e22a6ab3b2aec83ff/langbot_plugin-0.4.13-py3-none-any.whl", hash = "sha256:9d45ebc7a7ee0413d6db9baa009fcbf0ad07e2e1753a6f0a27f37b8b665cd1ee", size = 221884, upload-time = "2026-07-04T05:38:58.525Z" },
 ]

 [[package]]
@@ -5984,6 +5986,39 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/e4/16/c1fd27e9549f3c4baf1dc9c20c456cd2f822dbf8de9f463824b0c0357e06/uvloop-0.22.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6cde23eeda1a25c75b2e07d39970f3374105d5eafbaab2a4482be82f272d5a5e", size = 4296730, upload-time = "2025-10-16T22:17:00.744Z" },
 ]

+[[package]]
+name = "valkey-glide"
+version = "2.4.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio", marker = "sys_platform != 'win32'" },
+    { name = "protobuf", marker = "sys_platform != 'win32'" },
+    { name = "sniffio", marker = "sys_platform != 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/a2/582b34c6acc8dc857c537f6007459cba48dfa0dc404789a657e5c1a998c0/valkey_glide-2.4.1.tar.gz", hash = "sha256:f1155d84156d11b90488aa67e90102f0bf98a45314f5b99308ac9074c05f7241", size = 898030, upload-time = "2026-05-28T21:41:55.881Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/60/961ce40492a56ef831a905dfe03df4a81c0705152f6a8e49c541c634f49e/valkey_glide-2.4.1-cp311-cp311-macosx_10_7_x86_64.whl", hash = "sha256:d7285d03c2df040f26874b7f4ae96f040da2daecc9a34fa99da6f4e6ce5149c8", size = 7482152, upload-time = "2026-05-28T21:41:02.205Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/b2/5a05567f0fc385dcbbbf6ab1061f0bc00443d51c2996e95eed45feaedda9/valkey_glide-2.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5d2e82b74127897ccb7a957ad455787816a75fdc8c60a5e8004aef65ea93e99c", size = 6928601, upload-time = "2026-05-28T21:41:04.543Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/d9/7ea2b47cff0a2f99921eb0db404215f828ced7814bd09ede9c93b65d20bc/valkey_glide-2.4.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4094128cb07e06e87013b7afab1e9388f8f5aeebe48ea6cbd54de15bd772e644", size = 7236977, upload-time = "2026-05-28T21:41:06.055Z" },
+    { url = "https://files.pythonhosted.org/packages/00/7a/6cda6b42156ed260e765e4ad2d6ab831607775e218a00fbb0d93411c4e8f/valkey_glide-2.4.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9f8dc0f3a36adb1cbe4e167972ca4758acdfed6baf58a4db94bbb713df56c8f5", size = 7691446, upload-time = "2026-05-28T21:41:07.833Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/b4/da8c058baaee414a6bb2450742359f3b3b6993b23281bf227c5089f0099c/valkey_glide-2.4.1-cp312-cp312-macosx_10_7_x86_64.whl", hash = "sha256:5f8df64f6a4f0fd7203113103101fdf0aaa7ff0e7557312611de11ab89c6db75", size = 7472646, upload-time = "2026-05-28T21:41:09.451Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/94/e1e311cb56597272b9cb69afb3fe8e2e7dd3371f88c92836015deddc6f49/valkey_glide-2.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b45e35f44c17e88f8cd8082f8d8061a9763238c44ef20b11b615f6d87235864a", size = 6943375, upload-time = "2026-05-28T21:41:11.079Z" },
+    { url = "https://files.pythonhosted.org/packages/76/00/0e42e2f6866ebf0de552e076dc585a487b488b5b818c52460d28b50de65b/valkey_glide-2.4.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cf812b498925a30abab6e1a9f82f5eb821e967904fe7724729b2c82c47e29edf", size = 7237469, upload-time = "2026-05-28T21:41:12.733Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/4c/c5dd9a1ed995453b0d9ca75a5af87e881c14e6eebdbf5a5fa78c3bae23fc/valkey_glide-2.4.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:214e2faca98966eea3eaf9e09de616862423815a5059843a9884125e2427a344", size = 7678744, upload-time = "2026-05-28T21:41:14.634Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/2f/3df5702fc68684cef3e09f9cb6ed85578ddb08dc43593b1694c977f396fa/valkey_glide-2.4.1-cp313-cp313-macosx_10_7_x86_64.whl", hash = "sha256:c18976553ba663c03f7cc18c7e6075f4cbd2236c18b051e3d55bb213c6c44cb4", size = 7472972, upload-time = "2026-05-28T21:41:16.063Z" },
+    { url = "https://files.pythonhosted.org/packages/54/a3/6a74c6f996fa9e411e66b6f0e645fead2e0a341f1371e4cf3212efa54412/valkey_glide-2.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:43006e19cd63d66051263fa34a8ad47ba7d08a199585689b3f12f56ed6c9a005", size = 6943012, upload-time = "2026-05-28T21:41:17.492Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/e7/d10ec41dca703f8c5dcbcba2b905e660c1cf56be53c4d5e368d7aa23d220/valkey_glide-2.4.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b652a2a62aad87738e8f0e0aa5bf660ba91449c9fdb88550ccbc42e5fec08fe7", size = 7237842, upload-time = "2026-05-28T21:41:18.995Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/a3/8916a9ed9e871686db444c86e601773245852ba1ad451ce1bb06f7aed91d/valkey_glide-2.4.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fbd27d26947fd9f1b6e9eaf0abce4bccfde779c1e618b310c4d725424b609793", size = 7678919, upload-time = "2026-05-28T21:41:20.502Z" },
+    { url = "https://files.pythonhosted.org/packages/05/35/6d39ec3cbd24d85ad8e1051e29e6509c0999f760aff5af7851c1a1981471/valkey_glide-2.4.1-cp314-cp314-macosx_10_7_x86_64.whl", hash = "sha256:91fb7ff97acdabc8f641255b548a48627bb731e65037b1126745bf8a0022e87d", size = 7471906, upload-time = "2026-05-28T21:41:22.135Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/fc/3c28f794b7d35e13101598669c1d249c0a9f0408c545c87212e364c6ee4e/valkey_glide-2.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d49a2537c2de44b0fc57691b1ae6c3d6f481e6f7f7eb879c0d28921d0aaec67d", size = 6943495, upload-time = "2026-05-28T21:41:23.783Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/15/fb884631f5df78dc538c56bca9391165e40906b9b63ca65633d1be5bf980/valkey_glide-2.4.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cded9f14e448da5a96f61c066395f2c7e2846f2afe74cacc8634da0ae0c3425f", size = 7257720, upload-time = "2026-05-28T21:41:25.361Z" },
+    { url = "https://files.pythonhosted.org/packages/73/79/0b881017194386d21812b929a81dd8afd51d6b8d92280895b45913854785/valkey_glide-2.4.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5f249ab5bd0d69befe35897cf51a8fc9e01e9c8c9fe03087a68e6fe6d3e31d0d", size = 7682318, upload-time = "2026-05-28T21:41:26.996Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/4d/f2b4e508692fcd21e76c7cbdc4f988bec7f4675e60f4f35ef482a826f6ae/valkey_glide-2.4.1-pp311-pypy311_pp73-macosx_10_7_x86_64.whl", hash = "sha256:775df9c7421a187c41caf003e4af5f073ed7e4b8abe50f8b9bec712cb03e12bf", size = 7479155, upload-time = "2026-05-28T21:41:42.399Z" },
+    { url = "https://files.pythonhosted.org/packages/52/d8/8a3495f5582dccb4c8e7faf6a73baf3dbc4580701923f06d8abf210ff22d/valkey_glide-2.4.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:0d87f21c77004240189cc3c5aab156966487afd81ffdee04225a52c7bd7132e4", size = 6938571, upload-time = "2026-05-28T21:41:44.078Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/5a/a70077f76c2f18e94ec4309857b248beb7a8c7a3a50e30242abde2c3827d/valkey_glide-2.4.1-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:44376ef5fe7a25287095b073d8abde510a50b1ead0143662394b3da9717863ef", size = 7260021, upload-time = "2026-05-28T21:41:45.837Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/12/72d31522e06fcc9b391118c1f69a09002224e78114b1db0d01b96008dc59/valkey_glide-2.4.1-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a59cc0a21d7a8b1b3caeb299f23817429b5fe6579bd4cb016382e6b7a10de984", size = 7693093, upload-time = "2026-05-28T21:41:47.617Z" },
+]
+
 [[package]]
 name = "virtualenv"
 version = "20.36.1"
@@ -264,6 +264,48 @@ function saveListExpansionState(state: SidebarListExpansionState) {

 // Maximum number of entity sub-items visible before "More" toggle
 const MAX_VISIBLE_ITEMS = 5;
+const MCP_REFRESH_POLL_INTERVAL_MS = 1000;
+const MCP_REFRESH_TIMEOUT_MS = 60000;
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForMCPRefreshTask(taskId: number) {
+  const deadline = Date.now() + MCP_REFRESH_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    const task = await httpClient.getAsyncTask(taskId);
+    if (task.runtime.done) return task;
+    await sleep(MCP_REFRESH_POLL_INTERVAL_MS);
+  }
+
+  throw new Error(`Timed out waiting for MCP refresh task ${taskId}`);
+}
+
+async function refreshEnabledMCPConnections() {
+  const resp = await httpClient.getMCPServers();
+  const enabledServers = resp.servers.filter((server) => server.enable);
+  if (enabledServers.length === 0) return;
+
+  const taskResults = await Promise.allSettled(
+    enabledServers.map((server) => httpClient.testMCPServer(server.name, {})),
+  );
+  const taskIds: number[] = [];
+
+  for (const result of taskResults) {
+    if (
+      result.status === 'fulfilled' &&
+      typeof result.value.task_id === 'number'
+    ) {
+      taskIds.push(result.value.task_id);
+    } else if (result.status === 'rejected') {
+      console.error('Failed to start MCP refresh task:', result.reason);
+    }
+  }
+
+  await Promise.allSettled(taskIds.map(waitForMCPRefreshTask));
+}

 // Sort entity items by updatedAt descending (most recent first), items without updatedAt go last
 function sortByRecent(items: SidebarEntityItem[]): SidebarEntityItem[] {
@@ -352,11 +394,19 @@ function NavItems({
    if (extRefreshing) return;
    setExtRefreshing(true);
    try {
-      await Promise.all([
+      const results = await Promise.allSettled([
        sidebarData.refreshPlugins(),
-        sidebarData.refreshMCPServers(),
        sidebarData.refreshSkills(),
+        refreshEnabledMCPConnections(),
      ]);
+      const mcpRefreshResult = results[2];
+      if (mcpRefreshResult.status === 'rejected') {
+        console.error(
+          'Failed to refresh MCP connections:',
+          mcpRefreshResult.reason,
+        );
+      }
+      await sidebarData.refreshMCPServers();
    } finally {
      setExtRefreshing(false);
    }
@@ -157,6 +157,10 @@ export default function MCPDetailContent({ id }: { id: string }) {
    navigate(`/home/mcp?id=${encodeURIComponent(serverName)}`);
  }

+  const handlePersistedTestComplete = useCallback(async () => {
+    await refreshMCPServers();
+  }, [refreshMCPServers]);
+
  function confirmDelete() {
    httpClient
      .deleteMCPServer(id)
@@ -364,6 +368,7 @@ export default function MCPDetailContent({ id }: { id: string }) {
            onRuntimeInfoChange={(runtimeInfo) =>
              setDetailRuntimeStatus(runtimeInfo?.status ?? null)
            }
+            onPersistedTestComplete={handlePersistedTestComplete}
          />
        </div>
      </div>
@@ -41,6 +41,7 @@ import {
 } from '@/components/ui/card';
 import { httpClient } from '@/app/infra/http/HttpClient';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import MCPLogs from '@/app/home/mcp/components/mcp-form/MCPLogs';
 import MCPReadme from '@/app/home/mcp/components/mcp-form/MCPReadme';
 import {
  MCPServerRuntimeInfo,
@@ -487,6 +488,7 @@ interface MCPFormProps {
  onDirtyChange?: (dirty: boolean) => void;
  onTestingChange?: (testing: boolean) => void;
  onRuntimeInfoChange?: (runtimeInfo: MCPServerRuntimeInfo | null) => void;
+  onPersistedTestComplete?: (serverName: string) => void | Promise<void>;
  /** Reported when the form cannot be saved because the current mode is
   * ``stdio`` and the Box sandbox is disabled/unavailable. Parents that
   * render the Save button outside this component should disable it. */
@@ -511,6 +513,7 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
    onDirtyChange,
    onTestingChange,
    onRuntimeInfoChange,
+    onPersistedTestComplete,
    onSaveBlockedChange,
    layout = 'stacked',
    sideHeader,
@@ -822,6 +825,8 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
      // are always current.
      const serverName =
        isEditMode && initServerName ? initServerName : form.getValues('name');
+      const shouldTestPersistedServer =
+        isEditMode && !!initServerName && !form.formState.isDirty;
      const formExtraArgs = form.getValues('extra_args') ?? [];
      const formStdioArgs = form.getValues('args') ?? [];
      let extraArgsData: MCPServerExtraArgsRemote | MCPServerExtraArgsStdio;
@@ -844,12 +849,20 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
        };
      }

-      const { task_id } = await httpClient.testMCPServer('_', {
-        name: serverName,
-        mode,
-        enable: true,
-        extra_args: extraArgsData,
-      } as MCPServer);
+      const testTarget = shouldTestPersistedServer ? serverName : '_';
+      const testPayload = shouldTestPersistedServer
+        ? {}
+        : ({
+            name: serverName,
+            mode,
+            enable: true,
+            extra_args: extraArgsData,
+          } as MCPServer);
+
+      const { task_id } = await httpClient.testMCPServer(
+        testTarget,
+        testPayload,
+      );

      if (!task_id) {
        throw new Error(t('mcp.noTaskId'));
@@ -875,14 +888,18 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
                resource_count: 0,
                resources: [],
              });
+              if (shouldTestPersistedServer) {
+                await onPersistedTestComplete?.(serverName);
+              }
            } else {
-              if (isEditMode) {
+              if (shouldTestPersistedServer) {
                await loadServerForEdit(serverName);
+                await onPersistedTestComplete?.(serverName);
              } else {
-                // Create mode has no persisted server to reload tools from.
+                // Transient tests have no persisted server to reload tools from.
                // The backend stashes the discovered runtime info (status +
-                // tools) in the test task's metadata before tearing the
-                // transient session down — surface it so a successful test
+                // tools) in the task metadata before tearing the transient
+                // session down — surface it so a successful test
                // shows the tool list instead of "no tools found".
                const runtimeInfoFromTest = taskResp.task_context?.metadata
                  ?.runtime_info as MCPServerRuntimeInfo | undefined;
@@ -1207,6 +1224,9 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
        <TabsTrigger value="resources" className="flex-none px-4">
          {resourcesTabLabel}
        </TabsTrigger>
+        <TabsTrigger value="logs" className="flex-none px-4">
+          {t('mcp.tabLogs')}
+        </TabsTrigger>
      </TabsList>
      <TabsContent value="docs" className="mt-4 min-h-0 flex-1 overflow-y-auto">
        <MCPReadme readme={readme} />
@@ -1235,6 +1255,9 @@ const MCPForm = forwardRef<MCPFormHandle, MCPFormProps>(function MCPForm(
          t={t}
        />
      </TabsContent>
+      <TabsContent value="logs" className="mt-4 min-h-0 flex-1 overflow-y-auto">
+        {persistedServerName && <MCPLogs serverName={persistedServerName} />}
+      </TabsContent>
    </Tabs>
  ) : (
    runtimePanel
@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { httpClient } from '@/app/infra/http/HttpClient';
+import { useTranslation } from 'react-i18next';
+import { PluginLogEntry } from '@/app/infra/entities/plugin';
+import { Button } from '@/components/ui/button';
+import { Switch } from '@/components/ui/switch';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { RefreshCw } from 'lucide-react';
+
+const LEVEL_OPTIONS = ['ALL', 'DEBUG', 'INFO', 'WARNING', 'ERROR'] as const;
+
+function levelClassName(level: string): string {
+  switch (level) {
+    case 'ERROR':
+    case 'CRITICAL':
+      return 'text-red-500';
+    case 'WARNING':
+      return 'text-amber-500';
+    case 'DEBUG':
+      return 'text-gray-400 dark:text-gray-500';
+    default:
+      return 'text-gray-700 dark:text-gray-300';
+  }
+}
+
+export default function MCPLogs({ serverName }: { serverName: string }) {
+  const { t } = useTranslation();
+  const [logs, setLogs] = useState<PluginLogEntry[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [level, setLevel] = useState<string>('ALL');
+  const [autoRefresh, setAutoRefresh] = useState(true);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const atBottomRef = useRef(true);
+
+  const fetchLogs = useCallback(() => {
+    setIsLoading(true);
+    httpClient
+      .getMcpServerLogs(serverName, 500, level === 'ALL' ? undefined : level)
+      .then((res) => {
+        setLogs(res.logs ?? []);
+      })
+      .catch(() => {
+        setLogs([]);
+      })
+      .finally(() => {
+        setIsLoading(false);
+      });
+  }, [serverName, level]);
+
+  useEffect(() => {
+    fetchLogs();
+  }, [fetchLogs]);
+
+  // Auto-refresh poll loop.
+  useEffect(() => {
+    if (!autoRefresh) return;
+    const timer = setInterval(fetchLogs, 3000);
+    return () => clearInterval(timer);
+  }, [autoRefresh, fetchLogs]);
+
+  // Keep view pinned to bottom when the user is already at the bottom.
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el && atBottomRef.current) {
+      el.scrollTop = el.scrollHeight;
+    }
+  }, [logs]);
+
+  function handleScroll() {
+    const el = scrollRef.current;
+    if (!el) return;
+    atBottomRef.current = el.scrollHeight - el.scrollTop - el.clientHeight < 40;
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex shrink-0 flex-wrap items-center gap-2 px-1 pb-3 sm:px-6">
+        <Select value={level} onValueChange={setLevel}>
+          <SelectTrigger className="h-8 w-[130px]">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {LEVEL_OPTIONS.map((opt) => (
+              <SelectItem key={opt} value={opt}>
+                {opt === 'ALL' ? t('mcp.logsLevelAll') : opt}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8"
+          onClick={fetchLogs}
+          disabled={isLoading}
+        >
+          <RefreshCw
+            className={`mr-1.5 size-3.5 ${isLoading ? 'animate-spin' : ''}`}
+          />
+          {t('mcp.logsRefresh')}
+        </Button>
+        <div className="flex items-center gap-2">
+          <Switch
+            id="mcp-logs-auto-refresh"
+            checked={autoRefresh}
+            onCheckedChange={setAutoRefresh}
+          />
+          <Label
+            htmlFor="mcp-logs-auto-refresh"
+            className="cursor-pointer text-sm font-normal text-muted-foreground"
+          >
+            {t('mcp.logsAutoRefresh')}
+          </Label>
+        </div>
+      </div>
+
+      <div
+        ref={scrollRef}
+        onScroll={handleScroll}
+        className="min-h-0 flex-1 overflow-auto bg-gray-50 px-3 py-3 font-mono text-xs leading-relaxed dark:bg-gray-900/40 sm:px-6"
+      >
+        {logs.length === 0 ? (
+          <div className="py-8 text-center text-sm text-gray-500 dark:text-gray-400">
+            {t('mcp.logsEmpty')}
+          </div>
+        ) : (
+          logs.map((entry, idx) => (
+            <div
+              key={`${entry.ts}-${idx}`}
+              className={`whitespace-pre-wrap break-all ${levelClassName(
+                entry.level,
+              )}`}
+            >
+              {entry.text}
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
@@ -671,6 +671,21 @@ export class BackendClient extends BaseHttpClient {
    );
  }

+  public getMcpServerLogs(
+    serverName: string,
+    limit: number = 200,
+    level?: string,
+  ): Promise<{ logs: PluginLogEntry[] }> {
+    const params = new URLSearchParams();
+    params.set('limit', String(limit));
+    if (level) {
+      params.set('level', level);
+    }
+    return this.get(
+      `/api/v1/mcp/servers/${encodeURIComponent(serverName)}/logs?${params.toString()}`,
+    );
+  }
+
  public getPluginAssetURL(
    author: string,
    name: string,
@@ -828,6 +828,12 @@ const enUS = {
    tabTools: 'Tools',
    tabResources: 'Resources',
    tabDocs: 'Docs',
+    tabLogs: 'Logs',
+    logsLevelAll: 'All levels',
+    logsRefresh: 'Refresh',
+    logsAutoRefresh: 'Auto refresh',
+    logsEmpty:
+      'No logs yet. Runtime logs from the MCP server will appear here.',
    noReadme: 'No documentation available',
    parseResultFailed: 'Failed to parse test result',
    noResultReturned: 'Test returned no result',
@@ -842,6 +842,12 @@ const esES = {
    tabTools: 'Herramientas',
    tabResources: 'Recursos',
    tabDocs: 'Documentación',
+    tabLogs: 'Registros',
+    logsLevelAll: 'Todos los niveles',
+    logsRefresh: 'Actualizar',
+    logsAutoRefresh: 'Actualización automática',
+    logsEmpty:
+      'Aún no hay registros. Los registros de ejecución del servidor MCP aparecerán aquí.',
    noReadme: 'No hay documentación disponible',
    parseResultFailed: 'Error al analizar el resultado de la prueba',
    noResultReturned: 'La prueba no devolvió resultados',
@@ -834,6 +834,11 @@ const jaJP = {
    tabTools: 'ツール',
    tabResources: 'リソース',
    tabDocs: 'ドキュメント',
+    tabLogs: 'ログ',
+    logsLevelAll: 'すべてのレベル',
+    logsRefresh: '更新',
+    logsAutoRefresh: '自動更新',
+    logsEmpty: 'ログはありません。MCPサーバーの実行ログがここに表示されます。',
    noReadme: 'ドキュメントがありません',
    parseResultFailed: 'テスト結果の解析に失敗しました',
    noResultReturned: 'テスト結果が返されませんでした',
@@ -839,6 +839,12 @@ const ruRU = {
    tabTools: 'Инструменты',
    tabResources: 'Ресурсы',
    tabDocs: 'Документация',
+    tabLogs: 'Журнал',
+    logsLevelAll: 'Все уровни',
+    logsRefresh: 'Обновить',
+    logsAutoRefresh: 'Автообновление',
+    logsEmpty:
+      'Журналов пока нет. Здесь будут отображаться журналы выполнения MCP-сервера.',
    noReadme: 'Документация отсутствует',
    parseResultFailed: 'Не удалось разобрать результат теста',
    noResultReturned: 'Тест не вернул результат',
@@ -817,6 +817,11 @@ const thTH = {
    tabTools: 'เครื่องมือ',
    tabResources: 'ทรัพยากร',
    tabDocs: 'เอกสาร',
+    tabLogs: 'บันทึก',
+    logsLevelAll: 'ทุกระดับ',
+    logsRefresh: 'รีเฟรช',
+    logsAutoRefresh: 'รีเฟรชอัตโนมัติ',
+    logsEmpty: 'ยังไม่มีบันทึก บันทึกการทำงานของ MCP Server จะแสดงที่นี่',
    noReadme: 'ไม่มีเอกสาร',
    parseResultFailed: 'ไม่สามารถแยกวิเคราะห์ผลการทดสอบได้',
    noResultReturned: 'การทดสอบไม่ส่งผลลัพธ์กลับมา',
@@ -832,6 +832,12 @@ const viVN = {
    tabTools: 'Công cụ',
    tabResources: 'Tài nguyên',
    tabDocs: 'Tài liệu',
+    tabLogs: 'Nhật ký',
+    logsLevelAll: 'Tất cả cấp độ',
+    logsRefresh: 'Làm mới',
+    logsAutoRefresh: 'Tự động làm mới',
+    logsEmpty:
+      'Chưa có nhật ký. Nhật ký chạy của MCP Server sẽ hiển thị ở đây.',
    noReadme: 'Không có tài liệu',
    parseResultFailed: 'Phân tích kết quả kiểm tra thất bại',
    noResultReturned: 'Kiểm tra không trả về kết quả',
@@ -794,6 +794,11 @@ const zhHans = {
    tabTools: '工具',
    tabResources: '资源',
    tabDocs: '文档',
+    tabLogs: '日志',
+    logsLevelAll: '全部级别',
+    logsRefresh: '刷新',
+    logsAutoRefresh: '自动刷新',
+    logsEmpty: '暂无日志。MCP 服务器的运行日志会显示在这里。',
    noReadme: '暂无文档',
    parseResultFailed: '解析测试结果失败',
    noResultReturned: '测试未返回结果',
@@ -793,6 +793,11 @@ const zhHant = {
    tabTools: '工具',
    tabResources: '資源',
    tabDocs: '文件',
+    tabLogs: '日誌',
+    logsLevelAll: '全部級別',
+    logsRefresh: '重新整理',
+    logsAutoRefresh: '自動重新整理',
+    logsEmpty: '暫無日誌。MCP 服務器的運行日誌會顯示在這裡。',
    noReadme: '暫無文件',
    parseResultFailed: '解析測試結果失敗',
    noResultReturned: '測試未返回結果',
Author	SHA1	Message	Date
Hyu	1b096167f4	style: format valkey error message	2026-07-13 00:17:51 +08:00
Hyu	578565dbe2	fix: skip valkey-glide on Windows	2026-07-13 00:11:34 +08:00
Guanchao Wang	2a3f7f8059	fix(mcp): harden remote SSE fallback (#2324 ) * fix(mcp): harden remote SSE fallback * fix(mcp): preserve transport errors during fallback --------- Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>	2026-07-11 22:08:37 +08:00
RockChinQ	940234a0d8	docs: update blog links to main site	2026-07-09 14:13:04 -04:00
Daria Korenieva	0c405901d2	feat(vector): add Valkey Search vector database backend (#2276 ) * feat(vector): add Valkey Search vector database backend Add a new opt-in VectorDatabase backend backed by the Valkey Search module (valkey/valkey-bundle), accessed via the official valkey-glide client's native ft command namespace. - Implements the full VectorDatabase ABC: VECTOR, FULL_TEXT and HYBRID search, all 8 metadata filter operators, and pagination with exact totals. - HYBRID uses filter-then-KNN (no app-side weighted fusion); vector_weight is accepted for interface parity but NOT honored (docstring + one-time warning + docs caveat). - Lazy connect so a down Valkey never blocks boot; mandatory client_name=langbot_vector_client; optional auth + TLS (never logged). - Registered via a single elif branch in vector/mgr.py; disabled by default (vdb.use stays chroma) for toC compatibility. - Adds valkey-glide>=2.4.1,<3.0.0; no protobuf/pydantic downgrade; no ORM change so no Alembic migration. - Unit tests (fast lane, no server) + slow-gated integration tests (TEST_VALKEY_URL, valkey/valkey-bundle:9.1.0) + integration doc. * fix(vector): paginate Valkey Search deletes and guard delete_by_filter Address self-review follow-ups for the Valkey Search VDB backend: - _search_keys now paginates through the full result set in batches of _DELETE_SCAN_BATCH instead of capping at a single hard-coded 10000-key page, so delete_by_file_id / delete_by_filter fully remove files and filters that match more than one page of chunks (no orphaned vectors). - Add unit regression tests for the delete_by_filter mass-deletion guard: a filter referencing only non-indexed fields must skip and return 0 (never fall back to match-all), and a supported filter still deletes matching keys. * refactor(vector): harden Valkey Search backend and add adversarial tests Address the self-review NICE-TO-HAVE items for the Valkey Search VDB backend: - Guard the username-without-password credential edge (skip auth + warn instead of building ServerCredentials(password=None, ...), which glide rejects). - Add an async close() teardown that closes the glide client and resets cached state (re-init is safe via the existing None guard). - Hoist 'import json' to module top (was imported inside three methods). - Document the FT TAG literal-brace limitation in _escape_tag (fails closed, never widens). Tests: - Add an adversarial-input integration test proving crafted file_id / query_text cannot break out of or widen a query (fail-closed on braces). - Add unit tests for close() and the credential-build guard. Signed-off-by: Daria Korenieva <daric2612@gmail.com> * fix(vector): make Valkey Search file_id TAG support arbitrary characters Valkey Search's FT TAG query parser cannot handle '{', '}' or '' even when backslash-escaped, so a file_id containing those characters previously produced an unparseable query (it failed closed / raised). Percent-encode exactly those FT-unsafe characters (plus '%' for reversibility) in the file_id TAG value, applied identically at write time and query time, so an arbitrary file_id round-trips. For normal UUID/hash ids this is a no-op and the stored value is unchanged; the original file_id is always preserved verbatim in metadata_json. Strengthen the adversarial integration test to assert a brace/star-bearing file_id matches and deletes exactly its own row (no widening, no raise), and add unit tests for _encode_file_id and the filter encoding. Signed-off-by: Daria Korenieva <daric2612@gmail.com> refactor(vector): address Valkey Search review feedback - Add configurable request_timeout (default 5000ms; glide default 250ms is too low for KNN); expose in config.yaml + docs table - Validate embedding dimension consistency in add_embeddings (fail fast on mixed lengths to avoid silent KNN corruption) - Use ft.info (O(1)) instead of ft.list (O(n)) for index existence checks in the query hot path; also closes the check-then-create TOCTOU window - Pipeline HSETs via a non-atomic Batch instead of N sequential awaits - Extract shared _iter_reply_docs to deduplicate reply parsing between _reply_to_chroma and list_by_filter - Parenthesize multi-condition pre-filters before the => KNN clause - Fail closed when a username is configured without a password - Catch only RequestError on ft.dropindex (let connection/auth errors surface) - Bound the delete_collection SCAN loop with a safety cap - Add VectorDatabase.close() (no-op default) + VectorDBManager.shutdown() - Simplify _MATCH_ALL literal; normalize typing to builtin generics * fix(vector/valkey_search): address round-2 review feedback - Serialize lazy client creation with an asyncio.Lock (double-checked) so concurrent first-use callers don't construct and leak duplicate clients. - Make the filter operator chain exhaustive: raise on an unhandled op rather than silently dropping the condition (which could widen delete_by_filter). - Cast numeric range (///) values to float, failing closed on non-numeric input and pre-empting a future NUMERIC-field injection surface. * refactor(vector): remove shutdown/close from base ABC per maintainer feedback Per maintainer request, interface changes to VectorDatabase ABC and VectorDBManager should be in a separate PR with implementation across all backends. The ValkeySearchVectorDatabase.close() method remains but does not override an ABC method. Signed-off-by: Daria Korenieva <daric2612@gmail.com> * docs(test): list valkey_search in vdb coverage exclusions Add valkey_search to the documented vector/vdbs/ coverage-exclusion list, matching the existing chroma/milvus/pgvector/qdrant/seekdb entries. These adapters require a live database instance and are covered by env-gated integration tests instead of unit tests. Signed-off-by: Daria Korenieva <daric2612@gmail.com> --------- Signed-off-by: Daria Korenieva <daric2612@gmail.com>	2026-07-08 06:59:16 +08:00
Hyu	00e2103873	docs(config): add box.default_memory_mb to config.yaml template (#2319 ) Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 15:18:27 +08:00
Hyu	209706b0b9	feat(mcp): add box.default_memory_mb config for nsjail memory limit (#2318 ) Operators can now set a global default memory limit for all stdio MCP servers in config.yaml or via environment variable: config.yaml: box: default_memory_mb: 2048 # default: 1536 env: BOX__DEFAULT_MEMORY_MB=2048 The default is raised from 1024 to 1536 MB — a safer floor for Node.js V8 + WASM (undici llhttp) under nsjail cgroup limits. Individual MCP servers can still override via their own box.memory_mb. Previously the fallback was hardcoded to 1024 MB, causing OOM kills (return_code=137) on node/npx MCP servers that need more RAM. Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 14:24:06 +08:00
Hyu	205404e3da	fix(deps): pin langbot-plugin 0.4.13 (memory_mb removed from _COMPAT_FIELDS) (#2317 ) Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 13:45:13 +08:00
Hyu	3e93ccfb45	fix(mcp): use uniform session memory_mb=1024 to avoid BoxSessionConflictError (#2316 ) All MCPs share one Box session (mcp-shared). When session memory_mb differed by command type (512 for python, 1024 for node), the second MCP to call create_session raised BoxSessionConflictError. Fix: always use 1024 MB for the shared session so python and node MCPs coexist without conflict. Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 09:55:49 +08:00
Hyu	c5d7e3dcb1	fix(deps): pin langbot-plugin 0.4.12 (BoxManagedProcessSpec.memory_mb fix) (#2315 ) Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 09:31:09 +08:00
Hyu	cd6d5d9c2f	fix(mcp): pin langbot-plugin 0.4.10 - per-process memory_mb for node OOM fix (#2314 ) * fix(mcp): bump default memory to 1024MB for node (npx) stdio MCP servers Node.js MCP servers (npx/bunx) were being OOM-killed (return_code=137) by the default 512MB nsjail cgroup_mem_max. Node V8 reserves large virtual address space and instantiates WebAssembly modules (undici llhttp) on startup, easily exceeding 512MB resident. This caused every node-based MCP (memory, sequential-thinking, filesystem, weather, docker, excel) to crash-loop. Fix: when the stdio command is npx/bunx/pnpm, default memory_mb to 1024 unless the operator explicitly set a value. Python/uvx servers keep the 512MB default. * chore(deps): pin langbot-plugin 0.4.10 (per-process memory_mb fix) * chore: update uv.lock for langbot-plugin 0.4.10 --------- Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 09:03:43 +08:00
Hyu	1f7d9339fc	fix(mcp): bump default memory to 1024MB for node (npx) stdio MCP servers (#2313 ) Node.js MCP servers (npx/bunx) were being OOM-killed (return_code=137) by the default 512MB nsjail cgroup_mem_max. Node V8 reserves large virtual address space and instantiates WebAssembly modules (undici llhttp) on startup, easily exceeding 512MB resident. This caused every node-based MCP (memory, sequential-thinking, filesystem, weather, docker, excel) to crash-loop. Fix: when the stdio command is npx/bunx/pnpm, default memory_mb to 1024 unless the operator explicitly set a value. Python/uvx servers keep the 512MB default. Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-04 08:31:08 +08:00
RockChinQ	f3b5fcfb7c	fix mcp sidebar status sync (#2312 ) Co-authored-by: Hyu <chenhyu@proton.me>	2026-07-03 20:23:12 +08:00
Hyu	ffabb91bfe	fix(mcp): add missing MCPLogs import to MCPForm (#2311 ) Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 17:59:02 +08:00
Hyu	96c84740db	feat(mcp): add logs tab to MCP server detail panel (frontend) (#2310 ) * feat(mcp): add logs tab to MCP server detail panel - Add MCPLogs component mirroring PluginLogs functionality - Add getMcpServerLogs API method to BackendClient - Add logs tab to MCPForm detail panel (edit mode only) - Add i18n keys (tabLogs, logsLevelAll, logsRefresh, logsAutoRefresh, logsEmpty) to all 8 locales - Auto-refresh logs every 3s with toggle - Filter logs by level (ALL/DEBUG/INFO/WARNING/ERROR) * style: fix prettier formatting in MCPForm.tsx logs tab * style: fix prettier in i18n locale files --------- Co-authored-by: dadachann <dadachann@users.noreply.github.com> Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 16:52:15 +08:00
Hyu	85b5b5b54b	feat(mcp): add MCP server log panel backend (#2308 ) - Add log buffer (_log_buffer: deque with maxlen=500) to RuntimeMCPSession - Capture stderr from Box managed process in monitor_process_health loop - Add get_mcp_server_logs service method with limit and level filtering - Add GET /servers/<server_name>/logs HTTP endpoint - Parse log level from stderr lines (error/warning/debug/info) - Tests passing: 211 passed, 12 skipped Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 16:05:23 +08:00
Hyu	28bffdef21	fix(mcp): set _preserve_managed_process before finally in cold-start path (#2309 ) _ColdStartRetry was caught in _lifecycle_loop_with_retry which set _preserve_managed_process = True — but by then the finally block inside _lifecycle_loop had already run and called _cleanup_box_stdio_session(), stopping the live managed process (return_code=143 SIGTERM). The cold-start retry then restarted a fresh process, eliminating the warm-up advantage. Fix: add an explicit except _ColdStartRetry in _lifecycle_loop that sets _preserve_managed_process = True before re-raising. The finally block then sees the flag and skips stop_managed_process, leaving the live process untouched for the next handshake attempt. Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 15:26:18 +08:00
Hyu	bf3c96026b	fix(mcp): fix cold-start connection drop by using lexically-intact owner exit stack (#2307 ) The previous _TransferredStack approach broke anyio lexical context: websocket_client/ClientSession use anyio task groups whose cancel scope is bound to the frame that entered them. Deferring their aclose via a transferred exit stack left the underlying memory streams closed once initialize() returned, so the very next request (refresh -> list_tools) failed with Connection closed. New design: - Attach on the owner exit stack (same task as the serve loop, lexically intact) - A cold-starting process makes initialize() fail; signal _ColdStartRetry up to the outer retry loop, which reuses the live process without consuming retry budget - _lifecycle_loop_with_retry handles _ColdStartRetry like _TransportReconnect: preserves process, no fatal budget, backs off 2s and retries - Two new unit tests: cold-start raises _ColdStartRetry (not fatal) when process is alive; raises fatal error when process has actually exited Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 14:58:40 +08:00
Hyu	ed9343c686	fix(mcp): retry the stdio handshake during slow (npx) cold starts (#2306 ) A node/npx stdio MCP server (e.g. firecrawl-mcp via npx -y) failed on first connect with Connection closed / Failed after 4 attempts, even though the process was fine. An npx cold start downloads+installs the package before the server can answer the MCP handshake (measured ~27s for a simple official server; longer for heavier ones). The old code attached the WS and called session.initialize() the instant the process was started, so the handshake ran before the process could answer and failed; the outer lifecycle retry then rebuilt the process, churning it in a loop. Verified decisively: attaching + initialize() against a mid-cold-start process times out on attempt 1 (process still installing) but SUCCEEDS at t+0.6s on attempt 2 once the process is ready. So the fix is to retry the handshake in place, not to rebuild the process. Changes (mcp_stdio.initialize): - Start the managed process ONCE, then loop attach WS -> ClientSession -> initialize() within the startup_timeout budget, tearing down each failed attempt cleanly, until the handshake succeeds or the budget elapses. A successful transport/session is transferred into the owner exit stack via a small _TransferredStack adapter. - Bound each attempt with asyncio.wait_for(initialize, _HANDSHAKE_ATTEMPT_TIMEOUT_SEC=10s) so a cold-starting process fails fast and retries instead of hanging until the transport drops. - Stop retrying ONLY when the process has DEFINITIVELY exited: new _managed_process_has_exited() (checks EXITED status) replaces the previous not-_managed_process_is_running() test, which false-negatived on a just-spawned process that had not yet reported RUNNING and made the loop bail to the outer rebuild path (relay then rejected the early re-attach with HTTP 400). Adds a unit test that fails the first two handshakes with the process alive and asserts the loop retries to success while starting the process exactly once. Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 14:16:57 +08:00
Hyu	9a8cdde86c	refactor(mcp): make MCP test reuse the shared Box session (near-instant tests) (#2304 ) * refactor(mcp): make MCP test reuse the shared Box session instead of a per-test session Testing an MCP server (config-page "test" button) previously spun up a fresh isolated mcp-test-<uuid> Box session every time: cold-start the container, run the dependency bootstrap, probe, then tear the whole session down. That is slow (tens of seconds) and, on an already-hosted server, wasteful — the server is already running in the shared session. Change the test to reuse the shared session / live process: - _build_box_session_id: transient tests now use mcp-shared, the same Box session as live servers, so a test reuses the running container (and, for an existing server, its live managed process) instead of a cold per-test session. - cleanup_session: a transient test no longer deletes the whole session (which under the shared model would kill every other MCP server in the container). It stops only its own process_id, exactly like a live server. Isolation is now at the process level (distinct process_id per server/test), not the session level. - test_mcp_server (persisted server): reuse the live connection with a real list_tools refresh/probe; only fall back to a full start() when there is no live connection to probe or the refresh fails, instead of an ERROR->start() rebuild. Trade-off: a failing test now shares the container with live servers rather than a throwaway session. Accepted deliberately in favour of near-instant tests; process-level isolation keeps a test from stopping another server's process. * chore(deps): pin langbot-plugin 0.4.9 for the nsjail RLIMIT_AS node/npx MCP fix --------- Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 13:14:14 +08:00
Hyu	a2655e16f8	fix(mcp): survive transient WS transport drops for Box stdio MCP servers (#2303 ) * fix(mcp): survive transient WS transport drops for Box stdio MCP servers A Box-backed stdio MCP server (e.g. pab1it0/prometheus) would periodically error on the frontend with Box managed process exited unexpectedly / Failed after 4 attempts once the session had been alive for a while. Root cause: the managed MCP process lives in the Box runtime and SURVIVES a WebSocket transport drop, but _lifecycle_loop treated any monitor completion as a fatal process death. It then ran the finally-block cleanup — which STOPS the still-healthy managed process — and did a full 4-attempt exponential backoff rebuild. Under an occasionally-stalled single-worker event loop the mcp websocket client misses a ping/pong, the transport drops, and this self-inflicted teardown loop is what the user sees. Fixes: - _lifecycle_loop: when the health monitor completes, re-check the real managed-process state. If the process is still running, the transport merely dropped: raise an internal _TransportReconnect signal instead of Box managed process exited unexpectedly. - _lifecycle_loop_with_retry: handle _TransportReconnect as a free, uncounted reconnect (does not consume the fatal retry budget), so a long-lived session survives arbitrarily many transient drops. - finally-block: gate managed-process teardown on a _preserve_managed_process flag so a transport-only reconnect closes just the WS, not the process. - BoxStdioSessionRuntime.initialize: reuse an already-running managed process instead of stopping+rebuilding it (which also re-ran the slow dependency bootstrap); only (re)start when none is running. Adds _managed_process_is_running() helper. Pairs with langbot-plugin-sdk fix adding a server-driven WS heartbeat to the managed-process relay, which prevents most drops in the first place. * style(mcp): ruff format * chore(deps): pin langbot-plugin 0.4.8 for the managed-process WS heartbeat fix --------- Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>	2026-07-03 12:24:24 +08:00