AlexandrAI AGENTS.md
agents-md

Personal Work Agent Scheduler Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent scheduler services, cron next-run computation, repository/runtime split, scheduled jobs, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent scheduling.

Project Overview

The scheduler computes due jobs from cron expressions, reconciles next-run state, persists scheduled job records, launches runnable work, and plugs into the daemon runtime. It is intentionally small and should stay separate from platform connector logic.

Use this boundary when changing cron parsing, scheduled job state, repository persistence, runtime execution, or CLI scheduler commands.

Project Map

  • src/workagent/scheduler/service.py contains SchedulerJobState, compute_next_run, identify_runnable_jobs, and reconcile_due_jobs.
  • src/workagent/scheduler/repository.py persists scheduler jobs with SQLAlchemy.
  • src/workagent/scheduler/runtime.py launches due jobs through a repository and launcher protocol.
  • src/workagent/services/scheduler_jobs.py provides service-level job behavior.
  • src/workagent/runtime/app_runtime.py invokes scheduler runtime during app cycles.
  • src/workagent/cli.py exposes scheduler run-due.
  • tests/test_scheduler_service.py, test_scheduler_repository.py, test_scheduler_runtime.py, test_scheduler_jobs.py, and test_scheduled_case_launcher.py cover the boundary.

Setup Commands

bashuv run pytest tests/test_scheduler_service.py tests/test_scheduler_repository.py tests/test_scheduler_runtime.py -q
uv run pytest tests/test_scheduler_jobs.py tests/test_scheduled_case_launcher.py tests/test_app_runtime_cycles.py -q
make lint

Change Rules For Agents

  • Keep cron computation deterministic for timezone-aware datetimes.
  • Do not mix scheduler repository code with platform API polling.
  • Preserve the protocol split between repository and launcher so tests can use fakes.
  • When adding job types, update enum/model definitions, service behavior, launcher tests, and CLI if needed.
  • Keep run-due idempotent enough to tolerate daemon retries.
  • Do not store credentials in scheduled job payloads.
  • Make missed-run behavior explicit in tests.

Verification

bashuv run pytest tests/test_scheduler_service.py tests/test_scheduler_runtime.py tests/test_scheduled_case_launcher.py -q
make lint

Broaden to app runtime tests when scheduler execution order changes.

Security Notes

Scheduled jobs can trigger local actions. Keep payloads minimal, avoid secrets, and keep launch decisions auditable through job state and tests.

PR Checklist

  • Next-run calculations are tested.
  • Repository persistence and runtime launch paths are both covered.
  • New job types have migration and enum coverage when needed.
  • Daemon integration still reports scheduler summaries.