UAT: server.sync.auto and server.sync.interval config keys are registered but never consumed — no background entity sync scheduler exists #2164

Open
opened 2026-04-03 04:36:49 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/server-sync-background-scheduler
  • Commit Message: fix(server): implement background entity sync scheduler consuming server.sync.auto and server.sync.interval config keys
  • Milestone: v3.7.0
  • Parent Epic: #399

Background

Code-level analysis during UAT revealed that the server.sync.auto and server.sync.interval configuration keys are registered in the config service but are never read or consumed anywhere in the codebase. No background sync scheduler exists, making these config keys misleading dead code.

What Was Tested

Code-level analysis of the server.sync.auto and server.sync.interval configuration keys and their usage throughout the codebase.

Expected Behavior (from spec)

The specification defines two configuration keys for automatic background entity synchronization:

  • server.sync.auto (default: True) — Whether to automatically sync entity definitions with the server
  • server.sync.interval (default: 300) — Seconds between automatic background syncs

When server.sync.auto is True, the system should:

  1. Start a background scheduler when the client connects to a server
  2. Periodically call _cleveragents/sync/pull every server.sync.interval seconds
  3. Apply any received entity updates to the local cache
  4. Stop the scheduler when the client disconnects

Actual Behavior

Both config keys are registered in src/cleveragents/application/services/config_service.py (lines 277-292) but are never read or consumed anywhere in the codebase:

# config_service.py lines 277-292 — keys registered but unused
_register("server", "sync.auto", bool, True, ...)
_register("server", "sync.interval", int, 300, ...)

A search of the entire src/ directory finds zero references to server.sync.auto or server.sync.interval outside of the config service registration. There is no background sync scheduler, no periodic task, and no code that reads these values to determine sync behavior.

The integration test helper robot/helper_wf14_server_mode.py (lines 36-37) lists these env vars in _WF14_CONFIG_ENV_OVERRIDES for cleanup purposes, confirming they are expected to be functional, but the actual scheduler implementation is absent.

Code Locations

  • src/cleveragents/application/services/config_service.py lines 277-292: Keys registered
  • robot/helper_wf14_server_mode.py lines 36-37: Env vars listed for cleanup (confirms expected functionality)
  • No other files reference server.sync.auto or server.sync.interval

Steps to Reproduce

# Verify the keys are registered
from cleveragents.application.services.config_service import _REGISTRY
assert "server.sync.auto" in _REGISTRY  # PASSES — key is registered
assert "server.sync.interval" in _REGISTRY  # PASSES — key is registered

# But no code reads them for actual sync scheduling
import subprocess
result = subprocess.run(
    ["grep", "-r", "sync.auto", "src/", "--include=*.py", "-l"],
    capture_output=True, text=True
)
# Only config_service.py appears — no scheduler reads this value
assert len(result.stdout.strip().split('\n')) == 1  # Only config_service.py

Severity

Medium — The background sync scheduler is important for keeping clients automatically up-to-date in server mode. Without it, clients must manually trigger syncs. The config keys being registered but unused is also misleading to users who configure them expecting automatic sync behavior.

Subtasks

  • Confirm spec requirements for background entity sync scheduler behaviour (start/stop lifecycle, interval, pull endpoint)
  • Implement a background scheduler service/component that reads server.sync.auto and server.sync.interval at client connect time
  • Wire the scheduler to call _cleveragents/sync/pull on the configured interval and apply updates to the local cache
  • Implement scheduler teardown on client disconnect
  • Write Behave unit tests (BDD) covering: scheduler starts when sync.auto=True, scheduler does not start when sync.auto=False, scheduler calls sync at correct interval, scheduler stops on disconnect
  • Write Robot Framework integration tests verifying end-to-end background sync in WF14 server mode
  • Add/update ASV benchmark for sync scheduler overhead
  • Ensure all nox sessions pass (lint, typecheck, unit_tests, integration_tests, coverage_report)
  • Verify coverage remains ≥ 97%
  • Update any relevant documentation or docstrings

Definition of Done

  • server.sync.auto and server.sync.interval config keys are read by a background scheduler component
  • Background scheduler starts automatically on client connect when server.sync.auto is True
  • Scheduler calls _cleveragents/sync/pull every server.sync.interval seconds and applies updates to local cache
  • Scheduler stops cleanly on client disconnect
  • Behave unit tests cover all scheduler lifecycle scenarios
  • Robot Framework integration tests verify end-to-end background sync in server mode
  • All nox stages pass
  • Coverage >= 97%
  • PR merged and this issue closed

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/server-sync-background-scheduler` - **Commit Message**: `fix(server): implement background entity sync scheduler consuming server.sync.auto and server.sync.interval config keys` - **Milestone**: v3.7.0 - **Parent Epic**: #399 ## Background Code-level analysis during UAT revealed that the `server.sync.auto` and `server.sync.interval` configuration keys are registered in the config service but are **never read or consumed anywhere in the codebase**. No background sync scheduler exists, making these config keys misleading dead code. ## What Was Tested Code-level analysis of the `server.sync.auto` and `server.sync.interval` configuration keys and their usage throughout the codebase. ## Expected Behavior (from spec) The specification defines two configuration keys for automatic background entity synchronization: - `server.sync.auto` (default: `True`) — Whether to automatically sync entity definitions with the server - `server.sync.interval` (default: `300`) — Seconds between automatic background syncs When `server.sync.auto` is `True`, the system should: 1. Start a background scheduler when the client connects to a server 2. Periodically call `_cleveragents/sync/pull` every `server.sync.interval` seconds 3. Apply any received entity updates to the local cache 4. Stop the scheduler when the client disconnects ## Actual Behavior Both config keys are registered in `src/cleveragents/application/services/config_service.py` (lines 277-292) but are **never read or consumed anywhere in the codebase**: ```python # config_service.py lines 277-292 — keys registered but unused _register("server", "sync.auto", bool, True, ...) _register("server", "sync.interval", int, 300, ...) ``` A search of the entire `src/` directory finds zero references to `server.sync.auto` or `server.sync.interval` outside of the config service registration. There is no background sync scheduler, no periodic task, and no code that reads these values to determine sync behavior. The integration test helper `robot/helper_wf14_server_mode.py` (lines 36-37) lists these env vars in `_WF14_CONFIG_ENV_OVERRIDES` for cleanup purposes, confirming they are expected to be functional, but the actual scheduler implementation is absent. ## Code Locations - `src/cleveragents/application/services/config_service.py` lines 277-292: Keys registered - `robot/helper_wf14_server_mode.py` lines 36-37: Env vars listed for cleanup (confirms expected functionality) - No other files reference `server.sync.auto` or `server.sync.interval` ## Steps to Reproduce ```python # Verify the keys are registered from cleveragents.application.services.config_service import _REGISTRY assert "server.sync.auto" in _REGISTRY # PASSES — key is registered assert "server.sync.interval" in _REGISTRY # PASSES — key is registered # But no code reads them for actual sync scheduling import subprocess result = subprocess.run( ["grep", "-r", "sync.auto", "src/", "--include=*.py", "-l"], capture_output=True, text=True ) # Only config_service.py appears — no scheduler reads this value assert len(result.stdout.strip().split('\n')) == 1 # Only config_service.py ``` ## Severity **Medium** — The background sync scheduler is important for keeping clients automatically up-to-date in server mode. Without it, clients must manually trigger syncs. The config keys being registered but unused is also misleading to users who configure them expecting automatic sync behavior. ## Subtasks - [ ] Confirm spec requirements for background entity sync scheduler behaviour (start/stop lifecycle, interval, pull endpoint) - [ ] Implement a background scheduler service/component that reads `server.sync.auto` and `server.sync.interval` at client connect time - [ ] Wire the scheduler to call `_cleveragents/sync/pull` on the configured interval and apply updates to the local cache - [ ] Implement scheduler teardown on client disconnect - [ ] Write Behave unit tests (BDD) covering: scheduler starts when `sync.auto=True`, scheduler does not start when `sync.auto=False`, scheduler calls sync at correct interval, scheduler stops on disconnect - [ ] Write Robot Framework integration tests verifying end-to-end background sync in WF14 server mode - [ ] Add/update ASV benchmark for sync scheduler overhead - [ ] Ensure all nox sessions pass (`lint`, `typecheck`, `unit_tests`, `integration_tests`, `coverage_report`) - [ ] Verify coverage remains ≥ 97% - [ ] Update any relevant documentation or docstrings ## Definition of Done - [ ] `server.sync.auto` and `server.sync.interval` config keys are read by a background scheduler component - [ ] Background scheduler starts automatically on client connect when `server.sync.auto` is `True` - [ ] Scheduler calls `_cleveragents/sync/pull` every `server.sync.interval` seconds and applies updates to local cache - [ ] Scheduler stops cleanly on client disconnect - [ ] Behave unit tests cover all scheduler lifecycle scenarios - [ ] Robot Framework integration tests verify end-to-end background sync in server mode - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR merged and this issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-03 04:36:53 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium (confirmed) — Config keys registered but never consumed. Related to #2148 (sync stubs).
  • Milestone: v3.7.0 (confirmed)
  • MoSCoW: Should Have — The background sync scheduler is important for server mode but server mode is deferred. The dead config keys are misleading.
  • Parent Epic: #399 (confirmed correct)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (confirmed) — Config keys registered but never consumed. Related to #2148 (sync stubs). - **Milestone**: v3.7.0 (confirmed) - **MoSCoW**: Should Have — The background sync scheduler is important for server mode but server mode is deferred. The dead config keys are misleading. - **Parent Epic**: #399 (confirmed correct) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo self-assigned this 2026-04-03 16:57:59 +00:00
Author
Owner

Starting implementation on branch fix/server-sync-background-scheduler. Difficulty assessment: Medium → starting at sonnet tier.

Subtask wave plan:

  • Wave 1 (parallel): Subtask 1 (spec confirmation), Subtask 2 (implement scheduler service), Subtask 3 (wire sync pull call), Subtask 4 (scheduler teardown)
  • Wave 2 (parallel): Subtask 5 (Behave unit tests), Subtask 6 (Robot Framework integration tests), Subtask 7 (ASV benchmark)
  • Wave 3 (sequential): Subtask 8 (nox sessions), Subtask 9 (coverage), Subtask 10 (docs/docstrings)

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/server-sync-background-scheduler`. Difficulty assessment: Medium → starting at sonnet tier. Subtask wave plan: - **Wave 1 (parallel)**: Subtask 1 (spec confirmation), Subtask 2 (implement scheduler service), Subtask 3 (wire sync pull call), Subtask 4 (scheduler teardown) - **Wave 2 (parallel)**: Subtask 5 (Behave unit tests), Subtask 6 (Robot Framework integration tests), Subtask 7 (ASV benchmark) - **Wave 3 (sequential)**: Subtask 8 (nox sessions), Subtask 9 (coverage), Subtask 10 (docs/docstrings) --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#399 Epic: Post-MVP Server & Clients
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2164
No description provided.