fix(runtime): preserve explicit replies and report bot configuration errors

src/langbot/pkg/api/http/controller/groups/platform/bots.py

@@ -3,11 +3,20 @@ from sqlalchemy.exc import IntegrityError
 
 from ....authz import Permission, has_permission
 from ....context import RequestContext
+from ....service.bot_errors import BotApplyError, bot_error_message
 from ... import group
 
 
 @group.group_class('bots', '/api/v1/platform/bots')
 class BotsRouterGroup(group.RouterGroup):
+    def _apply_error_response(self, exc: BotApplyError):
+        request_id = self.request_id()
+        logger = getattr(self.ap, 'logger', self.quart_app.logger)
+        logger.error(f'Bot configuration apply failed request_id={request_id} bot_uuid={exc.bot_uuid}', exc_info=True)
+        return quart.jsonify(
+            code='bot_apply_failed', msg=str(exc), data={'uuid': exc.bot_uuid}, request_id=request_id
+        ), 400
+
     async def initialize(self) -> None:
         @self.route(
             '',
@@ -34,7 +43,14 @@ class BotsRouterGroup(group.RouterGroup):
         )
         async def _(request_context: RequestContext) -> str:
             json_data = await quart.request.json
-            bot_uuid = await self.ap.bot_service.create_bot(request_context, json_data)
+            if not isinstance(json_data, dict):
+                return self.http_status(400, 'invalid_bot_config', 'Bot configuration must be an object')
+            try:
+                bot_uuid = await self.ap.bot_service.create_bot(request_context, json_data)
+            except BotApplyError as exc:
+                return self._apply_error_response(exc)
+            except ValueError as exc:
+                return self.http_status(400, 'invalid_bot_config', bot_error_message(exc, json_data))
             return self.success(data={'uuid': bot_uuid})
 
         @self.route(
@@ -63,7 +79,14 @@ class BotsRouterGroup(group.RouterGroup):
         async def _(bot_uuid: str, request_context: RequestContext) -> str:
             if quart.request.method == 'PUT':
                 json_data = await quart.request.json
-                await self.ap.bot_service.update_bot(request_context, bot_uuid, json_data)
+                if not isinstance(json_data, dict):
+                    return self.http_status(400, 'invalid_bot_config', 'Bot configuration must be an object')
+                try:
+                    await self.ap.bot_service.update_bot(request_context, bot_uuid, json_data)
+                except BotApplyError as exc:
+                    return self._apply_error_response(exc)
+                except ValueError as exc:
+                    return self.http_status(400, 'invalid_bot_config', bot_error_message(exc, json_data))
             else:
                 await self.ap.bot_service.delete_bot(request_context, bot_uuid)
             return self.success()

src/langbot/pkg/api/http/service/bot.py

@@ -11,6 +11,7 @@ from ....entity.persistence import agent as persistence_agent
 from ....entity.persistence import bot as persistence_bot
 from ....entity.persistence import pipeline as persistence_pipeline
 from ....workspace.errors import WorkspaceNotFoundError
+from .bot_errors import BotApplyError, bot_error_message
 from .tenant import TenantContext, require_workspace_uuid, scope_statement
 from ....utils import httpclient
 from ....platform.sources import http_bot_signing
@@ -664,7 +665,10 @@ class BotService:
 
         bot = await self.get_bot(context, bot_data['uuid'], include_secret=True)
 
-        await self.ap.platform_mgr.load_bot(context, bot)
+        try:
+            await self.ap.platform_mgr.load_bot(context, bot)
+        except Exception as exc:
+            raise BotApplyError(bot_error_message(exc, bot), bot['uuid']) from exc
 
         return bot_data['uuid']
 
@@ -694,17 +698,17 @@ class BotService:
                     runtime_bot.bot_entity.description = update_data['description']
             return
 
-        await self.ap.platform_mgr.remove_bot(context, bot_uuid)
-
-        # select from db
+        # Persisted configuration is distinct from applying it to the running adapter.
         bot = await self.get_bot(context, bot_uuid, include_secret=True)
+        try:
+            await self.ap.platform_mgr.remove_bot(context, bot_uuid)
+            runtime_bot = await self.ap.platform_mgr.load_bot(context, bot)
+            if runtime_bot.enable:
+                await runtime_bot.run()
+        except Exception as exc:
+            raise BotApplyError(bot_error_message(exc, bot), bot['uuid']) from exc
 
-        runtime_bot = await self.ap.platform_mgr.load_bot(context, bot)
-
-        if runtime_bot.enable:
-            await runtime_bot.run()
-
-        # update all conversation that use this bot
+        # Reset conversations using this bot after its configuration is applied.
         for session in self.ap.sess_mgr.session_list:
             if (
                 session.using_conversation is not None

src/langbot/pkg/api/http/service/bot_errors.py

@@ -0,0 +1,43 @@
+"""User-facing bot configuration errors without credentials or validation inputs."""
+
+import json
+
+import pydantic
+
+from .secrets import redact_secrets
+
+
+class BotApplyError(Exception):
+    """Configuration was persisted, but the runtime could not apply it."""
+
+    def __init__(self, message: str, bot_uuid: str | None = None):
+        super().__init__(message)
+        self.bot_uuid = bot_uuid
+
+
+def bot_error_message(error: Exception, configuration: dict) -> str:
+    if isinstance(error, pydantic.ValidationError):
+        text = '; '.join(
+            f'{".".join(map(str, item["loc"]))}: {item["msg"]}'
+            for item in error.errors(include_input=False, include_context=False, include_url=False)
+        )
+    else:
+        text = str(error).strip() or type(error).__name__
+
+    replacements = []
+
+    def collect(original, masked):
+        if isinstance(original, dict) and isinstance(masked, dict):
+            for key, value in original.items():
+                collect(value, masked.get(key))
+        elif isinstance(original, (list, tuple)) and isinstance(masked, (list, tuple)):
+            for value, replacement in zip(original, masked):
+                collect(value, replacement)
+        elif isinstance(original, str) and original and original != masked:
+            for representation in {original, repr(original)[1:-1], json.dumps(original, ensure_ascii=False)[1:-1]}:
+                replacements.append((representation, str(masked)))
+
+    collect(configuration, redact_secrets(configuration))
+    for original, masked in sorted(replacements, key=lambda item: len(item[0]), reverse=True):
+        text = text.replace(original, masked)
+    return text[:2000]