ax-provider-scheduler

name	ax-provider-scheduler
description	Use when modifying scheduler providers — cron jobs, heartbeats, proactive hints, or active hours in src/providers/scheduler/

Overview

The scheduler provider fires timed messages (heartbeats, cron jobs) into the host message pipeline. It runs host-side only and delivers InboundMessage objects via the onMessage callback registered during start().

Interface

CronJobDef

Field	Type	Required	Notes
id	string	yes	Unique job identifier
schedule	string	yes	Standard 5-field cron expr
agentId	string	yes	Target agent
prompt	string	yes	Message content sent on trigger
maxTokenBudget	number	no	Per-job token cap

SchedulerProvider

Method	Required	Description
start(onMessage)	yes	Begin timers; register message callback
stop()	yes	Clear all timers; release resources
addCron(job)	no	Register a cron job
removeCron(jobId)	no	Remove a cron job by ID
listJobs()	no	Return all registered CronJobDef entries
checkCronNow(at?)	no	Manually trigger cron evaluation (testing)
recordTokenUsage(n)	no	Feed token count for budget tracking
listPendingHints()	no	Return hints queued when budget exceeded

Implementations

Provider	File	Timers	Cron	Active Hours	Notes
plainjob	plainjob.ts	yes	yes	yes	Persistent job queue (Kysely DB) with one-shot support
none	none.ts	no	no	no	No-op; all stubs

PlainJob Provider

• Location: src/providers/scheduler/plainjob.ts
• Storage: Kysely-backed job queue (PostgreSQL in k8s, SQLite fallback) for persistence across restarts
• One-shot jobs: scheduleOnce(datetime, prompt) for future-dated single-execution jobs
• Cron jobs: Standard 5-field cron expressions, persisted to SQLite
• Heartbeat delivery: Configurable via config.scheduler.defaultDelivery
• Agent filtering: Jobs can target specific agents via agentId
• Async stop: Graceful shutdown clears all timers and flushes pending jobs

PlainJob Provider Details

• Dependency injection via PlainJobSchedulerDeps: accepts optional jobStore (testing), database (shared DatabaseProvider), eventbus, and documents (DocumentStore for HEARTBEAT.md)
• Three-tier initialization: (1) injected jobStore for testing, (2) KyselyJobStore with shared DatabaseProvider, (3) standalone SQLite at ~/.ax/data/scheduler.db
• Migration table: 'scheduler_migration' (prevents collision with storage, cortex, etc.)
• Heartbeat: fires every config.scheduler.heartbeat_interval_min minutes. Reads HEARTBEAT.md from DocumentStore (documents.get('identity', '{agentName}/HEARTBEAT.md')). Suppressed outside active hours.
• Cron check: runs every 60 seconds. Uses matchesCron() from utils.ts (standard 5-field: min hour dom month dow). Suppressed outside active hours. Filtered by agentName (multi-agent safe).
• Active hours: parsed from config.scheduler.active_hours.{start,end,timezone}. Uses toLocaleTimeString with the configured timezone. Both heartbeats and cron jobs are gated.
• Session addressing: each message uses schedulerSession(sender) which sets provider: 'scheduler', scope: 'dm'.
• One-shot jobs: scheduleOnce(datetime, prompt) for future-dated single-execution jobs via setRunAt(). Rehydrated on startup via listWithRunAt().
• Async methods: addCron, removeCron, listJobs, scheduleOnce are all async — they await the underlying KyselyJobStore operations.

Multi-Replica Deduplication

Prevents duplicate job firing across multiple host replicas:

• tryClaim(jobId, minuteKey): Atomic CAS on last_fired_at column — only the replica that wins the UPDATE fires the job
• PostgreSQL: Row-level locks serialize concurrent claims naturally
• SQLite: Atomic UPDATE...RETURNING semantics
• Synthetic heartbeat row: __heartbeat__:{agentName} row created on startup for distributed heartbeat dedup. Filtered from listJobs() results.
• In-memory fallback: MemoryJobStore uses lastFiredMinute Map (tests only)

In-Flight Protection

Prevents overlapping executions when a job takes longer than its interval:

• inFlight: Set<string> tracks currently executing jobs
• Before firing: if (inFlight.has(jobId)) continue
• inFlight.add() happens before any async operations (prevents race with rapid heartbeats)
• Removed via .finally() on the handler Promise

Common Tasks

• Add a new scheduled event type: create a new timer in plainjob.ts, gate it with isWithinActiveHours(), fire via onMessageHandler().
• Test cron matching: use checkCronNow(at) to inject a specific Date without waiting for the 60s interval.

Gotchas

• Host-side only: the scheduler cannot call agent-side functions like markRun(). Anything requiring agent execution must go through the message pipeline.
• Active hours timezone: isWithinActiveHours() uses toLocaleTimeString with the configured timezone string. Invalid timezones throw at runtime, not at config parse time.
• Cron uses local Date methods: matchesCron() calls date.getMinutes(), date.getHours(), etc., which use the host machine's local time -- not the configured timezone. Only the active-hours gate is timezone-aware.
• Multi-replica dedup uses tryClaim(): Both cron jobs and heartbeats use tryClaim(jobId, minuteKey) for distributed dedup. Only the winning replica fires.
• In-flight add before async: inFlight.add() must happen before documents.get() to prevent duplicate heartbeats when two rapid calls both pass the check.
• HEARTBEAT.md from DocumentStore: Identity files are now loaded async from DocumentStore, not synchronous readFileSync() from config.scheduler.agent_dir.
• Job migrations: Three migrations in src/migrations/jobs.ts: jobs_001_initial (core schema), jobs_002_last_fired_at (dedup column), jobs_003_creator_session_id (workspace sharing).
• Scoped cron checks: checkCronJobs() filters by agentName via jobs.list(agentName). Each host fires only its own agent's jobs.