How the Automation Scheduler Processes Cron Triggers in Background Agents

The automation scheduler in the ColeMurray/background-agents repository processes cron triggers by executing a 30-minute interval check that compares remote Git commit SHAs using git ls-remote, enqueueing image rebuild jobs only when the source code has actually changed.

The ColeMurray/background-agents repository implements a robust automation scheduler to keep sandbox environments current within the Modal serverless compute platform. Located in the Modal Infra package (packages/modal-infra), this scheduler leverages cron triggers to orchestrate periodic tasks without manual intervention. Understanding how the automation scheduler processes cron triggers reveals the efficiency mechanisms that prevent unnecessary computational overhead.

Architecture of the Cron-Based Scheduler

The core automation scheduler resides in packages/modal-infra/src/scheduler/image_builder.py. According to the source code comments, the system performs "Scheduled rebuilds every 30 minutes (cron) with git ls-remote comparison" (line 9).

The 30-Minute Cron Interval

The scheduler operates on a fixed 30-minute cadence. This interval balances the need for fresh code against the cost of repeated image builds. The cron trigger fires automatically within the Modal worker environment, initiating the rebuild validation sequence.

Git SHA Comparison Logic

When triggered, the scheduler executes the logic marked by the comment # Scheduler: cron-based rebuild logic (line 416). The process follows these steps:

1. Fetch Remote State: For each registered repository, the scheduler invokes git ls-remote to retrieve the latest commit SHA from the remote origin.
2. Compare Stored Hash: The fetched SHA is compared against the last_built_sha stored in the scheduler's persistent state.
3. Conditional Enqueue: Only when the SHAs differ does the scheduler call enqueue_image_build(), passing the repository ID and the new commit hash.

Image Rebuild Workflow

Upon detecting a changed commit, the scheduler interacts with the control plane APIs defined in src/web_api.py. The workflow proceeds as follows:

• Trigger Build: The scheduler POSTs to /build-image with the new SHA.
• Create Sandbox: After a successful build, it may invoke /create-sandbox to provision fresh execution environments.
• Update State: The last_built_sha is updated in the database to reflect the newly built version.

This sequence ensures that background agents always execute against the most recent code without manual image management.

Testing Cron Trigger Behavior

The packages/modal-infra/tests/test_scheduler.py file contains integration tests that verify the cron logic. The test suite includes a "rebuild_images cron function" test that mocks control-plane responses.

The tests validate:

• No-Op Scenarios: When git ls-remote returns a matching SHA, no build task is queued.
• Rebuild Triggers: When SHAs differ, the test asserts that enqueue_image_build receives the correct parameters.

Practical Implementation Examples

The following examples demonstrate the cron trigger implementation as found in the source code.

Core cron handler from image_builder.py:

# packages/modal-infra/src/scheduler/image_builder.py

async def run_cron():
    """
    Cron handler executed every 30 minutes.
    Rebuilds images only when remote commits differ from last built.
    """
    for repo in registered_repos:
        latest_sha = await git_ls_remote(repo.url)
        if latest_sha != repo.last_built_sha:
            await enqueue_image_build(repo.id, latest_sha)
            repo.last_built_sha = latest_sha

Test verification from test_scheduler.py:

# packages/modal-infra/tests/test_scheduler.py

def test_rebuild_images_cron():
    # Mock the control-plane endpoint returning latest commit SHA

    mock_post = mock_control_plane_latest_sha()
    
    # Execute cron handler

    result = await image_builder.run_cron()
    
    # Verify build queued only for changed repositories

    assert result == {"rebuilt": ["repo-A"], "skipped": ["repo-B"]}

Summary

• The automation scheduler processes cron triggers via packages/modal-infra/src/scheduler/image_builder.py.
• It runs on a strict 30-minute interval configured within the Modal worker environment.
• The trigger uses git ls-remote to fetch current commit SHAs and compares them against stored last_built_sha values.
• Image rebuilds only occur when the remote SHA differs, preventing redundant builds.
• Integration tests in packages/modal-infra/tests/test_scheduler.py mock these interactions to verify correct cron behavior.

Frequently Asked Questions

How often does the automation scheduler check for code changes?

The scheduler executes its cron trigger every 30 minutes. This interval is hardcoded in the scheduler configuration to balance freshness with resource efficiency.

What prevents unnecessary image rebuilds in the cron process?

The scheduler stores the last_built_sha for each repository. Before enqueueing a build, it compares the remote SHA from git ls-remote against this stored value. Only when the SHAs differ does it trigger a rebuild, eliminating redundant work for unchanged codebases.

Which file contains the core cron logic for background agents?

The primary implementation resides in packages/modal-infra/src/scheduler/image_builder.py. This file contains the run_cron() function and the # Scheduler: cron-based rebuild logic comment marking the decision point for rebuilds.

How is the cron trigger tested in the repository?

The test suite in packages/modal-infra/tests/test_scheduler.py mocks the control-plane interactions. It simulates git ls-remote responses to verify that the scheduler correctly identifies changed repositories and calls enqueue_image_build() only when appropriate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}