Cron

Schedule agents to run tasks on a fixed interval, cron expression, or one-shot trigger

Overview

MeepaGateway has a built-in cron system that runs agent tasks on a schedule. Each job sends a message to an agent (triggering the full agent loop) and optionally delivers the response to a specific connector and channel.

Jobs are stored per-agent in SQLite and survive restarts. The scheduler uses a next-wake model: it sleeps until the earliest due job (capped at 60 seconds) rather than polling continuously.

---

Schedule Types

Every

Fixed interval: "30m", "2h", "1d". Runs repeatedly at the given interval.

Cron

7-field cron expression with seconds: "0 0 9 * * 1-5 *". Full calendar control.

At

One-shot: fires once at a specific UTC datetime. Use delete_after_run = true to clean up automatically.

---

Configuration

Cron jobs are defined per-agent in config.yaml:

agents:
  - id: meepa
    name: Meepa
    default: true

    cron_jobs:
      # Fixed interval — check in every hour
      - name: heartbeat
        message: "Check in: review recent activity and summarize status."
        schedule:
          every: 1h
        delivery:
          connector: discord
          channel_id: general

      # Cron expression — weekday standups at 9 AM UTC
      - name: morning-standup
        message: "Generate a standup summary from yesterday's activity."
        schedule:
          cron: "0 0 9 * * 1-5 *"
        delivery:
          connector: meepachat
          channel_id: standup

      # One-shot reminder — fires once then deletes itself
      - name: deploy-reminder
        message: "Remind the team about the scheduled deploy at 10 AM."
        delete_after_run: true
        schedule:
          at: "2025-07-01T09:00:00Z"
        delivery:
          connector: slack
          channel_id: C0123456789

---

Job Options

name · string · required

Unique job name within the agent.

message · string · required

The prompt sent to the agent when the job fires. This is the agent’s input — not the final message delivered to users. The agent processes it through the full loop and the response goes to delivery.

schedule · object · required

One of:

• { every = "30m" } — fixed interval (supports s, m, h, d)
• { cron = "0 0 9 * * 1-5 *" } — 7-field cron with seconds
• { at = "2025-07-01T09:00:00Z" } — one-shot RFC 3339 datetime

delivery · object

Where to post the agent’s response. If omitted, the response is discarded (useful for jobs that write to memory or trigger side effects).

delivery:
  connector: discord   # connector name as defined in channel config
  channel_id: general  # platform channel ID or name

enabled · boolean · default: "true"

Enable or disable the job without removing it.

delete_after_run · boolean · default: "false"

Delete the job after its first successful execution. Useful for one-shot jobs.

model · string

Override the agent’s default model for this job.

max_iterations · integer

Override the agent’s max_iterations for this job.

timeout · string

Per-job execution timeout (e.g. "2m").

active_hours · array

Restrict execution to a UTC hour range. Format: [start_hour, end_hour] (0–23). Jobs that fall outside this window are skipped and retried at the next scheduled time.

active_hours: [9, 17]  # 9 AM UTC to 5 PM UTC

---

Cron Expression Format

MeepaGateway uses a 7-field cron format with seconds as the first field:

# second (0-59)
# | minute (0-59)
# | | hour (0-23)
# | | | day of month (1-31)
# | | | | month (1-12)
# | | | | | day of week (0-6, Sunday=0)
# | | | | | | year (optional)
  * * * * * * *

Examples:

Expression	Meaning
0 0 9 * * 1-5 *	Weekdays at 9:00 AM UTC
0 */30 * * * * *	Every 30 minutes
0 0 0 1 * * *	First day of each month at midnight
0 0 8,12,18 * * * *	8 AM, noon, 6 PM daily

---

Managing Jobs at Runtime

Jobs can be created, updated, and deleted via the Captain Dashboard or API without restarting the gateway.

Captain API

# List cron jobs for an agent
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:63372/api/agents/meepa/cron

# Create a job
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-report",
    "message": "Generate a weekly activity report.",
    "schedule": {"type": "cron", "value": "0 0 9 * * 1 *"},
    "delivery": {"connector": "discord", "channel_id": "reports"}
  }' \
  http://localhost:63372/api/agents/meepa/cron

# Delete a job
curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  http://localhost:63372/api/agents/meepa/cron/weekly-report

---

Failure Recovery

The scheduler tracks consecutive_failures per job. Failed jobs are retried at the next scheduled time. There is no exponential back-off — the schedule drives retry timing.

Jobs that exceed their timeout are killed and counted as failures. The scheduler does not block waiting for a failed job; other due jobs continue to fire independently.

---

Architecture

• CronStore — per-agent SQLite store for job definitions, run history (last_run_at, next_run_at), and failure counts
• CronScheduler — unified scheduler across all agent stores; uses a next-wake model (sleeps until earliest due job, capped at 60s)
• When a job fires, its message is dispatched through the same agent loop as a regular incoming message, with delivery context set for the response