[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.

2.5 KiB Raw Blame History