docs(adr): document agent source copy strategy and logger.py dependency
This commit is contained in:
34
docs/adr/ADR-0014-agent-source-copy-strategy.md
Normal file
34
docs/adr/ADR-0014-agent-source-copy-strategy.md
Normal 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.
|
||||
Reference in New Issue
Block a user