docs(adr): document agent source copy strategy and logger.py dependency

This commit is contained in:
2026-07-06 11:35:57 +03:00
parent 9f9ac07cac
commit 627b75497c

View File

@@ -0,0 +1,34 @@
# [DEF:ADR-0014:ADR]
# @STATUS ACTIVE
# @PURPOSE Define which backend/src/core files the agent Docker image must copy, and why the strict stdlib-only principle had to be relaxed.
# @RELATION BINDS_TO -> [docker/Dockerfile.agent]
# @RELATION CALLS -> [ADR-0001:ADR]
# @RATIONALE The agent image (Dockerfile.agent) previously copied only `src/core/cot_logger.py` under the principle that core source in the agent must be stdlib-only to minimise image size and dependency surface. However, `src/agent/run.py` imports `from src.core.logger import logger`, which requires `logger.py` and its transitive dependency `ws_log_handler.py` (both depend on `pydantic`, not stdlib-only). This violated the copy contract silently — the bug only manifested at runtime when the image was (re)built.
# @REJECTED Refactor run.py to use cot_logger directly — rejected because run.py needs the full structured logger (MarkerLogger protocol) with trace_id propagation, not the bare cot_log. Refactoring would duplicate business logic.
# @REJECTED Copy the entire src/core/ — rejected because core/ contains route helpers, middleware, and other services the agent must never import. Blind bulk copy would violate container isolation.
## Decision
The agent Dockerfile copies exactly these `src/core/` files:
```
src/core/__init__.py
src/core/cot_logger.py # stdlib-only, no business logic
src/core/logger.py # requires pydantic + ws_log_handler
src/core/ws_log_handler.py # requires pydantic
```
These files are **infrastructure, not business logic** — they provide logging, tracing, and structured output that the agent shares with the backend. The pydantic dependency is already satisfied by the agent's own requirements (`requirements-agent.txt`).
Do NOT add:
- `src/core/superset_client.py` — business logic
- `src/core/task_manager.py` — business logic
- `src/core/plugin_loader.py` — business logic
- Any `src/api/`, `src/services/`, `src/models/` — backend-only
## Consequences
- **Positive**: Agent has working structured logging (trace_id, span_id, JSON output) matching the backend format.
- **Positive**: No refactoring of `run.py` import chain needed.
- **Negative**: Agent image carries `logger.py` (383 lines) and `ws_log_handler.py` which are not pure stdlib. The size impact is negligible (~5 KB for both files).
- **Risk**: If `logger.py` or `ws_log_handler.py` gain new imports from business-logic modules, the agent image breaks at runtime. Mitigation: all `src/core/` files imported by the agent are covered by the CI build smoke test for the agent image.