Cron Scheduler

Cron Scheduler - Scheduled Task Management

When to Apply

Positive Triggers

• Creating new cron jobs or scheduled tasks
• Adding Vercel cron entries to vercel.json
• Writing Next.js API route handlers for /api/cron/* endpoints
• Implementing backend periodic tasks (APScheduler, asyncio)
• Reviewing cron expression syntax or scheduling intervals
• Adding overlap protection to existing scheduled tasks
• User mentions: "cron", "schedule", "periodic", "interval", "timer", "background job"

Negative Triggers

• Implementing real-time WebSocket or SSE connections
• Designing state machine transitions (use state-machine instead)
• Building workflow pipelines with manual triggers (use genesis-orchestrator instead)
• Handling one-off async background tasks without recurrence

Core Directives

The Four Rules of Scheduled Tasks

1. Authenticated: Every cron endpoint validates CRON_SECRET
2. Idempotent: Re-running the same job produces the same result
3. Observable: Every execution logs start, end, duration, and outcome
4. Overlap-safe: Concurrent invocations do not corrupt shared state

Existing Project Cron Jobs

Existing Cron Jobs

Configuration: apps/web/vercel.json → crons array

Scheduled Audit Runner

Location: apps/web/lib/audit/scheduled-audit-runner.ts

In-process scheduler using setInterval with AuditSchedule type and simplified cron parsing. Supports add/remove/toggle schedules.

Frontend Patterns (Next.js + Vercel Cron)

Standard Route Handler Template

Every cron route handler must follow this structure:

import { NextResponse } from 'next/server';
import { logger } from '@/lib/logger';

/**
 * {Job Name} Cron Job
 *
 * Runs {schedule description} ({cron expression})
 * {What it does}
 */
export async function GET(request: Request) {
  const startedAt = Date.now();

  try {
    // 1. Authenticate
    const authHeader = request.headers.get('authorization');
    if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
      return new NextResponse('Unauthorised', { status: 401 });
    }

    // 2. Execute job logic
    const result = await executeJob();

    // 3. Log success with duration
    const duration = Date.now() - startedAt;
    logger.info('cron_job_completed', {
      job: 'job-name',
      duration_ms: duration,
      result,
    });

    // 4. Return structured response
    return NextResponse.json({
      success: true,
      ...result,
      duration_ms: duration,
      timestamp: new Date().toISOString(),
    });
  } catch (error) {
    const duration = Date.now() - startedAt;
    logger.error('cron_job_failed', {
      job: 'job-name',
      duration_ms: duration,
      error: error instanceof Error ? error.message : 'Unknown error',
    });

    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Unknown error' },
      { status: 500 }
    );
  }
}

Route File Location

apps/web/app/api/cron/
├── cleanup-old-runs/route.ts    # Existing
├── health-check/route.ts        # Existing
├── daily-report/route.ts        # Existing
└── {new-job-name}/route.ts      # New jobs go here

Vercel Cron Registration

When adding a new cron job, update apps/web/vercel.json:

{
  "crons": [
    {
      "path": "/api/cron/{job-name}",
      "schedule": "{cron expression}"
    }
  ]
}

Authentication

CRON_SECRET Pattern

Every cron endpoint must validate the CRON_SECRET environment variable:

const authHeader = request.headers.get('authorization');
if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
  return new NextResponse('Unauthorised', { status: 401 });
}

No authentication or hardcoded secrets are REJECTED. Store CRON_SECRET in .env.local.

Overlap Protection

The existing cron jobs lack overlap protection. Use one of these patterns:

Pattern 1: Database Lock (Recommended for Vercel)

import { createClient } from '@/lib/supabase/server';

async function acquireLock(jobName: string, ttlSeconds: number): Promise<boolean> {
  const supabase = await createClient();
  const lockId = `cron_lock_${jobName}`;
  const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString();

  // Attempt to insert lock row — fails if already locked
  const { error } = await supabase
    .from('cron_locks')
    .upsert(
      { id: lockId, locked_at: new Date().toISOString(), expires_at: expiresAt },
      { onConflict: 'id', ignoreDuplicates: false }
    )
    .lt('expires_at', new Date().toISOString());  // Only if expired

  return !error;
}

async function releaseLock(jobName: string): Promise<void> {
  const supabase = await createClient();
  await supabase
    .from('cron_locks')
    .delete()
    .eq('id', `cron_lock_${jobName}`);
}

Usage in a cron handler:

export async function GET(request: Request) {
  // ... auth check ...

  const locked = await acquireLock('cleanup-old-runs', 300);
  if (!locked) {
    return NextResponse.json({ skipped: true, reason: 'Already running' });
  }

  try {
    const result = await executeJob();
    return NextResponse.json({ success: true, ...result });
  } finally {
    await releaseLock('cleanup-old-runs');
  }
}

Pattern 2: In-Memory Flag (For ScheduledAuditRunner)

class ScheduledAuditRunner {
  private running: Set<string> = new Set();

  async runAudit(type: AuditType, config?: AuditConfig): Promise<ScheduledAuditResult> {
    const lockKey = `${type}_${JSON.stringify(config ?? {})}`;

    if (this.running.has(lockKey)) {
      return { status: 'skipped', reason: 'Already running' } as ScheduledAuditResult;
    }

    this.running.add(lockKey);
    try {
      // ... existing audit logic ...
    } finally {
      this.running.delete(lockKey);
    }
  }
}

Database Schema for Locks

CREATE TABLE IF NOT EXISTS cron_locks (
  id TEXT PRIMARY KEY,
  locked_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  expires_at TIMESTAMPTZ NOT NULL
);

-- Auto-cleanup expired locks
CREATE INDEX idx_cron_locks_expires ON cron_locks (expires_at);

Backend Patterns (FastAPI + asyncio)

Startup/Shutdown Lifecycle

from contextlib import asynccontextmanager
from asyncio import create_task, sleep, Task

_background_tasks: list[Task] = []


async def periodic_cleanup(interval_seconds: int = 3600) -> None:
    """Run cleanup every hour."""
    while True:
        try:
            await run_cleanup_job()
        except Exception as e:
            logger.error("periodic_cleanup_failed", error=str(e))
        await sleep(interval_seconds)


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: launch background tasks
    task = create_task(periodic_cleanup(3600))
    _background_tasks.append(task)
    yield
    # Shutdown: cancel all background tasks
    for task in _background_tasks:
        task.cancel()

APScheduler Integration (When Needed)

from apscheduler.schedulers.asyncio import AsyncIOScheduler
from apscheduler.triggers.cron import CronTrigger

scheduler = AsyncIOScheduler(timezone="Australia/Brisbane")
scheduler.add_job(
    cleanup_old_runs,
    CronTrigger(hour=2, minute=0),
    id="cleanup_old_runs",
    replace_existing=True,
    misfire_grace_time=300,
)
scheduler.start()

Cron Expression Reference

Syntax

┌─────────── minute (0-59)
│ ┌─────────── hour (0-23)
│ │ ┌─────────── day of month (1-31)
│ │ │ ┌─────────── month (1-12)
│ │ │ │ ┌─────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common Expressions

Timezone Consideration (AEST/AEDT)

Vercel cron runs in UTC. Convert Australian times:

For the backend (APScheduler), set timezone="Australia/Brisbane" to avoid manual conversion.

Idempotency

Cron jobs may execute more than once (retries, clock drift). Design for idempotency:

// GOOD: Idempotent — deletes by criteria, safe to re-run
await supabase.from('agent_runs').delete()
  .in('status', ['completed', 'failed'])
  .lt('completed_at', cutoffDate.toISOString());

// GOOD: Idempotent insert — upsert on unique key
await supabase.from('daily_reports')
  .upsert({ date: yesterday, data: report }, { onConflict: 'date' });

REJECTED: Plain .insert() without upsert — creates duplicates on retry.

Monitoring and Alerting

Structured Log Events

Every cron job must emit these log events:

// On start
logger.info('cron_job_started', { job: 'cleanup-old-runs' });

// On success
logger.info('cron_job_completed', {
  job: 'cleanup-old-runs',
  duration_ms: 1234,
  records_processed: 42,
});

// On failure
logger.error('cron_job_failed', {
  job: 'cleanup-old-runs',
  duration_ms: 567,
  error: 'Connection timeout',
});

// On skip (overlap protection)
logger.warn('cron_job_skipped', {
  job: 'cleanup-old-runs',
  reason: 'Already running',
});

Failure Alerting

Alert after 3+ consecutive failures. Track failure count per job in the database or in-memory store. Log cron_job_alert with consecutive_failures count when threshold is breached.

Anti-Patterns

Checklist for New Cron Jobs

Setup

• Route handler created in apps/web/app/api/cron/{job-name}/route.ts
• Cron entry added to apps/web/vercel.json
• CRON_SECRET validation at top of handler
• JSDoc with schedule description and cron expression

Safety

• Overlap protection implemented (database lock or flag)
• Job is idempotent — safe to re-run
• Timeout configured (Vercel function timeout or AbortSignal.timeout)
• Error handling with structured logging

Observability

• cron_job_started log event
• cron_job_completed log event with duration_ms
• cron_job_failed log event with error details
• cron_job_skipped log event for overlap protection
• Alerting on consecutive failures

Timezone

• Schedule expressed in UTC for Vercel cron
• AEST/AEDT conversion documented in JSDoc
• Backend uses Australia/Brisbane timezone for APScheduler

Response Format

[AGENT_ACTIVATED]: Cron Scheduler
[PHASE]: {Design | Implementation | Review}
[STATUS]: {in_progress | complete}

{scheduling analysis or implementation guidance}

[NEXT_ACTION]: {what to do next}

Integration Points

Structured Logging

• Every cron execution emits structured log events matching structured-logging patterns
• correlation_id per execution for tracing across services
• Duration tracking in milliseconds

Error Taxonomy

• Cron auth failures use AUTH_VALIDATION_MISSING_TOKEN (401)
• Job execution failures use SYS_RUNTIME_INTERNAL (500)
• Database lock failures use WORKFLOW_CONFLICT_LOCKED (409)

State Machine

• Cron job execution follows PENDING → RUNNING → COMPLETED/FAILED (same as NodeStatus)
• Lock states: UNLOCKED → LOCKED → UNLOCKED (with TTL expiry)

API Contract

• Cron route responses follow the standard JSON envelope pattern
• All responses include timestamp in ISO 8601

Australian Localisation (en-AU)

• Timezone: AEST (UTC+10) / AEDT (UTC+11) — store UTC, convert in display
• Spelling: serialise, analyse, optimise, behaviour, colour, authorise
• Date Format: ISO 8601 in API; DD/MM/YYYY in UI display