Files

busya 24d3b7d1f9 refactor(task-manager): implement task resilience and execution lifecycle improvements

Enhance the reliability and observability of the task execution engine
by introducing retry mechanisms, idempotency, and structured progress
tracking.

- Implement centralized retry logic with exponential backoff support
  in `JobLifecycle`.
- Add `retry_task` API endpoint and `TaskManager` method for manual
  task restarts.
- Introduce task idempotency using `_idempotency_key` to prevent
  duplicate executions.
- Add `retry_count`, `max_retries`, `last_error`, and `progress` fields
  to the `Task` model and ensure persistence via `TaskPersistenceService`.
- Upgrade `SchedulerService` to use differential synchronization with
  the persistent `SQLAlchemyJobStore` for better job durability.
- Implement structured heartbeat logging to support real-time progress
  updates.
- Update project documentation and ADRs to reflect the new plugin
  runtime and task resilience patterns.
- Add comprehensive unit and integration tests for the new task
  lifecycle features.

2026-07-12 15:31:56 +03:00

1.9 KiB

Raw Blame History

[DEF:ADR-0015:ADR]

@STATUS ACCEPTED

@PURPOSE Define package and Docker boundaries for the standalone conversational agent and its shared utilities.

@RELATION SUPERSEDES -> [ADR-0014:ADR]

@RELATION BINDS_TO -> [agent/pyproject.toml]

@RELATION BINDS_TO -> [shared/pyproject.toml]

@RELATION BINDS_TO -> [docker/Dockerfile.agent]

@RATIONALE The agent has a different Python runtime and dependency surface from the FastAPI backend. Keeping it under `backend/src` made Docker copy rules fragile and coupled agent imports to backend internals.

@REJECTED Copying selected `backend/src/core` modules into the agent image — rejected because package extraction provides explicit dependencies and makes the container build reproducible.

@REJECTED Copying the complete backend into the agent image — rejected because it expands the dependency and security surface without a runtime need.

Decision

The conversational agent and common lightweight utilities are independent Python packages:

agent/                       # ss-tools-agent, Python >=3.11
shared/                      # ss-tools-shared, Python >=3.11
backend/                     # FastAPI application, its own runtime boundary
docker/Dockerfile.agent      # installs shared first, then agent

docker/Dockerfile.agent copies and installs shared/ and agent/ as editable packages. It must not copy backend/src to satisfy agent imports. Shared code is limited to utilities that have no dependency on backend API, models, database, or service layers. Dependencies required only by the agent belong in agent/.

Consequences

Agent dependencies can evolve independently from the backend image.
Imports between agent and backend require an explicit API or shared-package contract; direct imports across those boundaries are forbidden.
A change to the agent Docker build must be verified with docker build using the repository root as build context.

1.9 KiB Raw Blame History