diff --git a/docs/adr/ADR-0014-agent-source-copy-strategy.md b/docs/adr/ADR-0014-agent-source-copy-strategy.md new file mode 100644 index 00000000..8cc3c4f3 --- /dev/null +++ b/docs/adr/ADR-0014-agent-source-copy-strategy.md @@ -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.