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

docker/Dockerfile.agent

@@ -1,51 +1,42 @@
 # #region docker.agent.Dockerfile [C:3] [TYPE Module] [SEMANTICS docker,agent,build]
 # @BRIEF Agent Dockerfile — Python 3.11 slim + Gradio + LangGraph agent.
 # @LAYER Infrastructure
-# @RELATION DEPENDS_ON -> [EXT:path:backend/requirements.txt]
-# @PRE Docker builder context — корень проекта. backend/ и docker/ доступны.
-# @POST Образ с Gradio-агентом, LangGraph, минимальной копией backend/src/.
-# @RATIONALE Агенту нужен только src.agent.* и src.core.cot_logger (чистый stdlib).
-#            Полный трассировщик импортов показал:
-#              src.agent.app → src.agent.{context,document_parser,langgraph_setup,middleware,tools}
-#                            → src.core.cot_logger (stdlib-only, нет бизнес-логики)
-#            Ни src.models, ни src.api, ни src.services, ни src.plugins НЕ импортируются.
-# @REJECTED COPY backend/ /app/backend/ rejected — нарушает принцип изоляции контейнеров.
-#            COPY только backend/src/agent/ недостаточно — нужен src.core.cot_logger.
+# @RELATION DEPENDS_ON -> [EXT:path:agent/requirements.txt]
+# @RELATION DEPENDS_ON -> [EXT:path:shared/pyproject.toml]
+# @PRE Docker builder context — корень проекта. agent/, shared/, docker/ доступны.
+# @POST Образ с Gradio-агентом, LangGraph, shared-утилитами.
+# @RATIONALE Агент теперь в отдельном проекте agent/ с собственным pyproject.toml.
+#            Shared-пакет устанавливается как зависимость.
+# @REJECTED COPY backend/ копирование полностью устарело — агент больше не в backend.
 
 FROM python:3.11-slim
 
 WORKDIR /app
 
-# Install system deps for pdfplumber + psycopg (v3 needs libpq) + certs
+# System deps for pdfplumber + psycopg + certs
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libgl1 libglib2.0-0 libpq5 ca-certificates openssl && rm -rf /var/lib/apt/lists/*
 
-# Python dependencies — agent runtime (gradio, langgraph, httpx, pdfplumber, ...)
-# Без sentence-transformers — embedding router безопасно отключается при ImportError.
+# Python dependencies — agent runtime
 ARG WITH_EMBEDDINGS=false
 
-COPY backend/requirements-agent.txt /app/backend/requirements-agent.txt
-RUN pip install --no-cache-dir -r /app/backend/requirements-agent.txt
+# Install shared package first (lightweight utilities)
+COPY shared/ /app/shared/
+RUN pip install --no-cache-dir -e /app/shared/
 
-# Optional: semantic embedding routing (большие ML-зависимости: ~500 MB+)
-COPY backend/requirements-embeddings.txt /app/backend/requirements-embeddings.txt
+# Install agent requirements
+COPY agent/requirements.txt /app/agent/requirements.txt
+RUN pip install --no-cache-dir -r /app/agent/requirements.txt
+
+# Optional: semantic embedding routing
+COPY agent/requirements-embeddings.txt /app/agent/requirements-embeddings.txt
 RUN if [ "$WITH_EMBEDDINGS" = "true" ]; then \
-        pip install --no-cache-dir -r /app/backend/requirements-embeddings.txt; \
+        pip install --no-cache-dir -r /app/agent/requirements-embeddings.txt; \
     fi
 
-# ── Минимальная копия backend/src/ ──────────────────────────────
-# Только то, что реально импортирует агент (трассировка 2026-06-14):
-#   src/__init__.py           — пакетный корень src
-#   src/core/__init__.py      — пакетный корень src.core
-#   src/core/cot_logger.py    — разделяемый логгер (stdlib-only)
-#   src/agent/*.py            — сам агент (8 .py-файлов, плоская структура)
-# Ничего из api/, models/, schemas/, services/, plugins/ — не копируем.
-COPY backend/src/__init__.py /app/backend/src/__init__.py
-COPY backend/src/core/__init__.py /app/backend/src/core/__init__.py
-COPY backend/src/core/cot_logger.py /app/backend/src/core/cot_logger.py
-COPY backend/src/core/logger.py /app/backend/src/core/logger.py
-COPY backend/src/core/ws_log_handler.py /app/backend/src/core/ws_log_handler.py
-COPY backend/src/agent/ /app/backend/src/agent/
+# Agent source code
+COPY agent/ /app/agent/
+RUN pip install --no-cache-dir -e /app/agent/
 
 # Entrypoint for corporate CA cert installation
 COPY docker/certs.sh /app/docker/certs.sh
@@ -56,6 +47,6 @@ RUN chmod +x /app/docker/agent.entrypoint.sh /app/docker/certs.sh
 ENV GRADIO_SERVER_NAME=0.0.0.0
 ENV GRADIO_SERVER_PORT=7860
 
-WORKDIR /app/backend
+WORKDIR /app/agent
 ENTRYPOINT ["/app/docker/agent.entrypoint.sh"]
 # #endregion docker.agent.Dockerfile

docker/agent.entrypoint.sh

@@ -15,5 +15,5 @@ else
   echo "[agent-entry] certs.sh not found — skipping corporate CA installation"
 fi
 
-exec python -m src.agent.run
+exec python -m ss_tools.agent.run
 # #endregion docker.agent.entrypoint

docker/backend.Dockerfile

@@ -2,9 +2,10 @@
 # @BRIEF Backend Dockerfile — Python 3.11 slim + Playwright + entrypoint с установкой сертификатов.
 # @LAYER Infrastructure
 # @RELATION DEPENDS_ON -> [EXT:path:docker/backend.entrypoint.sh]
-# @RELATION DEPENDS_ON -> [EXT:path:backend/requirements.txt]
-# @PRE Docker builder context — корень проекта. backend/ и docker/ доступны.
-# @POST Образ с backend API, Playwright, entrypoint для bootstrap admin и установки сертификатов.
+# @RELATION DEPENDS_ON -> [EXT:path:backend/requirements-backend.txt]
+# @RELATION DEPENDS_ON -> [EXT:path:shared/pyproject.toml]
+# @PRE Docker builder context — корень проекта. backend/, shared/, docker/ доступны.
+# @POST Образ с backend API, Playwright, shared-утилитами, entrypoint для bootstrap admin.
 
 FROM python:3.11-slim
 
@@ -14,8 +15,7 @@ ENV BACKEND_PORT=8000
 
 WORKDIR /app
 
-# Системные зависимости: ca-certificates для корп. сертификатов, libnss3-tools
-# для установки CA в NSS базу Chromium, curl, git для Playwright/GitPython
+# Системные зависимости
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates \
     curl \
@@ -23,15 +23,23 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libnss3-tools \
     && rm -rf /var/lib/apt/lists/*
 
-# Python зависимости — backend runtime (agent/ML deps excluded)
+# Python зависимости — backend runtime
 COPY backend/requirements-backend.txt /app/backend/requirements-backend.txt
 RUN pip install --no-cache-dir -r /app/backend/requirements-backend.txt
+
+# Install shared package (LLM health, SSL, cot_logger)
+COPY shared/ /app/shared/
+RUN pip install --no-cache-dir -e /app/shared/
+
+# Install shared LLM deps (openai, httpx for _llm_health)
+RUN pip install --no-cache-dir "openai>=1.0.0" "httpx>=0.28.1"
+
 RUN python -m playwright install --with-deps chromium
 
 # Исходный код
 COPY backend/ /app/backend/
 
-# Копируем shared certs.sh и entrypoint — установит корп. сертификаты, Playwright и сделает bootstrap admin
+# Копируем shared certs.sh и entrypoint
 COPY docker/certs.sh /app/certs.sh
 COPY docker/backend.entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh
@@ -42,4 +50,4 @@ EXPOSE 8000
 
 ENTRYPOINT ["/app/entrypoint.sh"]
 CMD ["python", "-m", "uvicorn", "src.app:app", "--host", "0.0.0.0", "--port", "8000"]
-# #endregion docker.backend.Dockerfile
+# #endregion docker.backend.Dockerfile