Cron Internals

​

Key Files

​

Scheduling Model

​

Job Storage

{
  "id": "a1b2c3d4e5f6",
  "name": "Daily briefing",
  "prompt": "Summarize today's AI news and funding rounds",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "display": "0 9 * * *"
  },
  "skills": ["ai-funding-daily-report"],
  "deliver": "telegram:-1001234567890",
  "repeat": {
    "times": null,
    "completed": 42
  },
  "state": "scheduled",
  "enabled": true,
  "next_run_at": "2025-01-16T09:00:00Z",
  "last_run_at": "2025-01-15T09:00:00Z",
  "last_status": "ok",
  "created_at": "2025-01-01T00:00:00Z",
  "model": null,
  "provider": null,
  "script": null
}

​

last_status literals

​

Job Lifecycle States

​

Backward Compatibility

​

Scheduler Runtime

​

Tick Cycle

tick()
  1. Acquire scheduler lock (prevents overlapping ticks)
  2. Load all jobs from jobs.json
  3. Filter to due jobs (next_run <= now AND state == "scheduled")
  4. For each due job:
     a. Set state to "running"
     b. Create fresh AIAgent session (no conversation history)
     c. Load attached skills in order (injected as user messages)
     d. Run the job prompt through the agent
     e. Deliver the response to the configured target
     f. Update run_count, compute next_run
     g. If repeat count exhausted → state = "completed"
     h. Otherwise → state = "scheduled"
  5. Write updated jobs back to jobs.json
  6. Release scheduler lock

​

Missed-occurrence contract (restart gaps)

1. Pre-dispatch advance is provisional. tick() advances next_run_at past the due occurrence before dispatch so a crash mid-run cannot re-fire it on every restart. Because that leaves a window — advanced, but no fire claim yet (interpreter finalizing, executor refusing work, SIGKILL) — the due scan stamps pending_slot = {scheduled_at, at, by} on the record in the same save. claim_job_for_fire (the point after which side effects may exist) and mark_job_run clear it; an explicit schedule / next_run_at / enabled / state rewrite (edit, pause, resume, run-now) drops it.
2. Restore once. A later scan that finds a pending_slot whose owner is provably gone (this process and the job is not in its running set; another process past the 300 s fire-claim lease or with a dead pid) puts scheduled_at back as next_run_at, drops the stamp, and logs a WARNING (cron/occurrences.py::unclaimed_pending_slot). This happens at most once per lost occurrence — the restored instant then meets the ordinary rules below like any other overdue slot, so there is never a replay of N slots.
3. Already fired → never twice. completed_occurrence() consults the executions ledger for a completed row with that exact scheduled_instant before anything is due; a slot that ran before the restart advances without firing. failed / unknown rows do not count as completion, and neither does a completed row whose finished_at (else claimed_at) precedes the instant it is stamped with — a run cannot prove an occurrence that had not happened yet. Rows without a comparable timestamp keep counting. An occurrence identity is only claimable once it is due: claim_job_for_fire drops a scheduled_instant that is still in the future, so an off-tick fire (dashboard trigger, webhook, lease reclaim, misfire backstop) runs occurrence-free instead of consuming the next slot.
4. Late within grace → fire late. Grace = half the period clamped to [120 s, 2 h] (_compute_grace_seconds); the dispatch is stamped last_dispatch.kind = late.
5. Past grace → collapse the backlog, fire once (kind = catch_up), or skip with a logged reason when the operator set cron.catch_up_missed: false (planned downtime). One-shots past their 120 s grace are retired with a diagnostic, never resurrected.
6. Paused / disabled / terminal jobs never fire; the due scan drops them before any of the above, and pause/resume clears any pending slot. A recurring occurrence that came due while paused is not lost, though: resume_job keeps a past stored next_run_at as the due instant instead of re-anchoring from now (and logs that it did), so the first tick after resume applies rules 3–5 to it — one late/catch-up run, or a logged skip. One-shots and future instants recompute from now on resume.

​

Gateway Integration

• empty (default) → the built-in InProcessCronScheduler, which runs the historical in-process loop calling scheduler.tick() every 60 seconds. This is byte-identical to the pre-provider behavior.
• a named provider (e.g. chronos, a managed-cron provider for scale-to-zero deployments) → discovered from plugins/cron_providers/<name>/ or $mibyan_HOME/plugins/<name>/.

​

Managed cron (Chronos) for scale-to-zero

create/update a cron job
  → Chronos asks Nous to arm a one-shot at the job's next_run_at
      (authenticated with the agent's existing Nous token)
  → at fire time Nous calls the gateway: POST {callback_url}/api/cron/fire
      (authenticated with a short-lived, purpose-scoped Nous-minted JWT)
  → the gateway verifies the token, claims the job (store compare-and-set so
    multi-replica deployments fire at-most-once), runs it, and re-arms the next
    one-shot

​

Fresh Session Isolation

• No conversation history from previous runs
• No memory of previous cron executions (persistent memory — MEMORY.md / USER.md — does load, like any other agent run, so durable preferences and facts carry over; per-run conversation context does not)
• The prompt must be self-contained — cron jobs cannot ask clarifying questions
• The cronjob toolset is disabled (recursion guard)

​

Skill-Backed Jobs

1. Skills are loaded in the specified order
2. Each skill’s SKILL.md content is injected as context
3. The job’s prompt is appended as the task instruction
4. The agent processes the combined skill context + prompt

Create a daily funding report → attach "ai-funding-daily-report" skill

​

Script-Backed Jobs

# ~/.mibyan/scripts/check_competitors.py
import requests, json
# Fetch competitor release notes, diff against last run
# Print summary to stdout — agent analyzes and reports

1. Module-level override — _SCRIPT_TIMEOUT (for tests/monkeypatching). Only used when it differs from the default.
2. Environment variable — mibyan_CRON_SCRIPT_TIMEOUT
3. Config — cron.script_timeout_seconds in config.yaml (read via load_config())
4. Default — 3600 seconds (1 hour)

​

Provider Recovery

• Fallback providers — reads fallback_providers (list) or fallback_model (legacy dict) from config.yaml, matching the gateway’s _load_fallback_model() pattern. Passed as fallback_model= to AIAgent.__init__, which normalizes both formats into a fallback chain. Unpinned jobs only: _job_fallback_chain() returns no chain for a job carrying its own provider, model or base_url, and the same answer feeds the credential-resolution walk in _resolve_job_runtime(), the pre-dispatch key check, and the mid-run ladder, so a pinned job never lands on a global chain entry (#100437). It shares mibyan_cli.fallback_config.scoped_fallback_chain() with pinned delegation children.
• Credential pool — loads via load_pool(provider) from agent.credential_pool using the resolved runtime provider name. Only passed when the pool has credentials (pool.has_credentials()). Enables same-provider key rotation on 429/rate-limit errors.

​

Delivery Model

​

Response Wrapping

• A header identifying the cron job name and task
• A footer noting the agent cannot see the delivered message in conversation

​

Session Isolation

​

Recursion Guard

• A scheduled job from creating new cron jobs
• Recursive scheduling that could explode token usage
• Accidental mutation of the job schedule from within a job

​

Locking

​

Stale-code yield

​

CLI Interface

mibyan cron list                    # Show all jobs
mibyan cron create                  # Interactive job creation (alias: add)
mibyan cron edit <job_id>           # Edit job configuration
mibyan cron pause <job_id>          # Pause a running job
mibyan cron resume <job_id>         # Resume a paused job
mibyan cron run <job_id>            # Trigger immediate execution
mibyan cron remove <job_id>         # Delete a job

​

Related Docs

• Cron Feature Guide
• Gateway Internals
• Agent Loop Internals