refactor(agent): extract agent+shared into standalone packages with full GRACE semantic markup

- Move agent code from backend/src/agent/ to agent/src/ss_tools/agent/
- Extract shared stdlib-only utilities to shared/src/ss_tools/shared/
- Add #region/#endregion contracts to all ~140 functions (INV_1 compliance)
- Update docker files, entrypoint, build scripts for new package layout
- Backend now imports ss_tools.shared._llm_health (no gradio/langchain deps)
- Add specs for 036-039 feature plans

agent/tests/test_agent/test_middleware.py

@@ -0,0 +1,88 @@
+# #region Test.AgentChat.Middleware [C:3] [TYPE Module] [SEMANTICS test,agent,middleware,audit]
+# @BRIEF Tests for agent/middleware.py — log_tool_event.
+# @RELATION BINDS_TO -> [AgentChat.Middleware]
+
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+from unittest.mock import MagicMock, patch
+import pytest
+
+
+# #region test_log_tool_event [C:2] [TYPE Function]
+# @BRIEF Test log_tool_event for various event types.
+class TestLogToolEvent:
+    @pytest.mark.asyncio
+    async def test_logs_tool_start(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {
+            "event": "on_tool_start",
+            "name": "migrate",
+            "data": {"input": {"dashboard_id": "42"}},
+        }
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value="user-token"):
+            await log_tool_event(event, "conv-1")
+            # No exception = success
+
+    @pytest.mark.asyncio
+    async def test_logs_tool_end(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {
+            "event": "on_tool_end",
+            "name": "migrate",
+            "data": {"output": "success"},
+        }
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value="user-token"):
+            await log_tool_event(event, "conv-1")
+
+    @pytest.mark.asyncio
+    async def test_logs_tool_error(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {
+            "event": "on_tool_error",
+            "name": "migrate",
+            "data": {"error": "Connection failed"},
+        }
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value="user-token"):
+            await log_tool_event(event, "conv-1")
+
+    @pytest.mark.asyncio
+    async def test_logs_without_user_jwt(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {
+            "event": "on_tool_start",
+            "name": "test_tool",
+            "data": {"input": {}},
+        }
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value=None):
+            await log_tool_event(event, "conv-1")
+
+    @pytest.mark.asyncio
+    async def test_handles_missing_data_key(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {"event": "on_tool_start", "name": "test_tool"}
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value=None):
+            await log_tool_event(event, "conv-1")
+
+    @pytest.mark.asyncio
+    async def test_handles_unknown_event_kind(self):
+        from ss_tools.agent.middleware import log_tool_event
+        event = {"event": "on_custom_event", "name": "custom"}
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value=None):
+            await log_tool_event(event, "conv-1")
+
+    @pytest.mark.asyncio
+    async def test_truncates_long_input(self):
+        from ss_tools.agent.middleware import log_tool_event
+        long_input = "x" * 1000
+        event = {
+            "event": "on_tool_start",
+            "name": "big_tool",
+            "data": {"input": long_input},
+        }
+        with patch("ss_tools.agent.middleware.get_user_jwt", return_value="token"):
+            await log_tool_event(event, "conv-1")
+# #endregion test_log_tool_event
+# #endregion Test.AgentChat.Middleware