Index 14: Cron Scheduler - 持久化调度 / 会话级触发

$ cat-code
> /cron add nightly-build 0 9 * * * ./gradlew test
Cron job created: cron-1 (recurring)
  next fire: 2026-08-08 09:00
> /cron test 0 9 * * *              ← 先验证表达式
Expression: 0 9 * * *
  1. 2026-08-08 09:00
  2. 2026-08-09 09:00
  3. 2026-08-10 09:00
> exit                              ← 退出 REPL，任务定义已持久化

$ cat-code                          ← 次日 9 点重启 REPL
🐱 Cat-Code · ... · s14: Cron Scheduler
> /cron list
Cron jobs (1):
  cron-1  [ON/recur]  0 9 * * *  nightly-build  next=2026-08-09 09:00
                                   ↑ lastFiredAt 已记 2026-08-08 09:00（今天已触发）
🔔 cron-1 - completed (exit code 0)  ← 回合间 drain 出来的完成通知

s05 TodoWrite -> s12 TaskSystem -> s13 BackgroundTasks -> s14 CronScheduler
                              ↘ s17 AutonomousAgents

        ┌───────────────────────────────────────────────┐
        │             ~/.cat-code/cron.json             │
        │ {"jobs":[{"id":"cron-1","cron":"0 9 * * *",…}]}│
        └──────────────────────┬────────────────────────┘
                               │ 原子写 + fail-open 读（同 s12）
        ┌──────────────────────▼────────────────────────┐
        │                  CronStore                     │
        │   内存缓存 + 构造加载 + 临时文件原子 move        │
        └──────────────────────┬────────────────────────┘
                               │ loadAll / save / update / delete
        ┌──────────────────────▼────────────────────────┐
        │               CronScheduler                   │
        │  nextFireCache: id -> (cron, nextFire)         │
        │  tick(): 读 store -> 判到期 -> fire -> 推进     │
        │  start(scope): 轮询协程每 30s 调 tick()         │
        └──────┬───────────────────────────┬────────────┘
   handleRecurring│                  handleOneShot│
   (cache miss:   │                  (now>=fireAt │
    nextFire(now  │                   -> fire+delete)
    -1min))       │                             │
               fire(job) via CronExecutor        │
        ┌────────▼────────────────────────────────▼─────┐
        │   CronExecutor (fun interface, ReplLoop 注入)  │
        │   -> BackgroundRunner.launch(job.command)      │
        │   -> NotificationQueue.push("cron 'x' fired")  │
        └────────────────────────────────────────────────┘
                               │ s13 通知队列
                               ▼
                    ReplLoop.drainNotifications()
                    "🔔 cron:1 - cron 'nightly' fired -> bg-3"

        CronExpr（纯算法）：parse("0 9 * * 1-5") -> Set<Int>×5 + restricted flags
                          nextFire(from) -> 字段逐级推进 -> LocalDateTime?

repl -> cron, background, tool, agent, ...
cron -> kotlinx.coroutines, kotlinx.serialization（不依赖 background/agent）

// cron/CronJob.kt
@Serializable
data class CronJob(
    val id: String,                     // "cron-N"
    val name: String,                   // 人类可读标签
    val cron: String,                   // 5 字段 cron 表达式
    val command: String,                // 触发时执行的 shell 命令
    val enabled: Boolean = true,
    val oneShot: Boolean = false,       // true=一次性（触发后自动删除）
    val fireAt: Long? = null,           // one-shot 目标时刻（epoch millis）；recurring 为 null
    val createdAt: Long = System.currentTimeMillis(),
    val lastFiredAt: Long? = null
)

// cron/CronExpr.kt:113
fun parse(expr: String): CronExpr {
    val fields = expr.trim().split(Regex("\\s+"))
    require(fields.size == 5) { "cron expression must have 5 fields, got ${fields.size}: '$expr'" }

    val minutes = parseField(fields[0], 0, 59)
    val hours = parseField(fields[1], 0, 23)
    val daysOfMonth = parseField(fields[2], 1, 31)
    val months = parseField(fields[3], 1, 12)
    // 周允许 0-7（0 和 7 都是周日），解析后对 7 取模归一
    val daysOfWeek = parseField(fields[4], 0, 7).map { it % 7 }.toSet()

    return CronExpr(
        ...,
        domRestricted = fields[2] != "*",   // 日是否被限制（非 *）
        dowRestricted = fields[4] != "*",   // 周是否被限制
        raw = expr.trim()
    )
}

// cron/CronExpr.kt:60
private fun dayOk(t: LocalDateTime): Boolean {
    val cronDow = t.dayOfWeek.value % 7   // java DayOfWeek 周日=7 -> cron 周日=0
    val domMatch = t.dayOfMonth in daysOfMonth
    val dowMatch = cronDow in daysOfWeek
    return when {
        domRestricted && dowRestricted -> domMatch || dowMatch  // 都限制：任一匹配
        domRestricted -> domMatch                               // 只限日：用日
        dowRestricted -> dowMatch                               // 只限周：用周
        else -> true                                            // 都 *：每天
    }
}

// cron/CronExpr.kt:78
fun nextFire(from: LocalDateTime): LocalDateTime? {
    var t = from.plusMinutes(1).truncatedTo(ChronoUnit.MINUTES)   // 严格大于 from
    var iters = 0
    while (iters < MAX_ITERATIONS) {
        iters++
        if (t.monthValue !in months) {           // 月不匹配 -> 跳到下月 1 号 00:00
            t = t.withDayOfMonth(1).withHour(0).withMinute(0).plusMonths(1); continue
        }
        if (!dayOk(t)) {                          // 日不匹配 -> 跳到次日 00:00
            t = t.withHour(0).withMinute(0).plusDays(1); continue
        }
        if (t.hour !in hours) {                   // 时不匹配 -> 跳到下一小时 :00
            t = t.withMinute(0).plusHours(1); continue
        }
        if (t.minute !in minutes) {               // 分不匹配 -> 跳到下一分钟
            t = t.plusMinutes(1); continue
        }
        return t
    }
    return null   // 无解：迭代上限内未找到匹配（如 2 月 30 日）
}

// cron/CronStore.kt
class CronStore(private val file: Path) {
    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
    private val cache = mutableListOf<CronJob>()

    init { reloadFromDisk() }

    fun loadAll(): List<CronJob>   // 按 createdAt 升序（同时刻按 id 决胜键，确定性）
    fun save(job: CronJob): Boolean
    fun update(job: CronJob): Boolean   // 保留 createdAt
    fun delete(id: String): Boolean
    fun findById(id: String): CronJob?
    fun replaceAll(jobs: List<CronJob>)
}

// cron/CronConfig.kt
data class CronConfig(
    val cronFile: String = "~/.cat-code/cron.json",
    val pollIntervalSeconds: Long = 30
) {
    fun resolvedCronFile(): Path { /* 展开 ~ */ }
    val pollIntervalMillis: Long get() = pollIntervalSeconds * 1000
}

// cron/CronExecutor.kt
fun interface CronExecutor {
    fun fire(job: CronJob)
}

// cron/CronScheduler.kt:100
fun tick(now: LocalDateTime = clock()): Int {
    val jobs = store.loadAll()           // 持久化的单一事实来源
    val liveIds = mutableSetOf<String>()
    var fired = 0
    for (job in jobs) {
        liveIds.add(job.id)
        if (!job.enabled) { nextFireCache.remove(job.id); continue }
        fired += if (job.oneShot) handleOneShot(job, now) else handleRecurring(job, now)
    }
    nextFireCache.keys.retainAll(liveIds)   // 清理已删除任务的缓存
    return fired
}

// cron/CronScheduler.kt:135
private fun handleRecurring(job: CronJob, now: LocalDateTime): Int {
    val expr = try { CronExpr.parse(job.cron) } catch (e: IllegalArgumentException) {
        logger.warn { "Invalid cron expression for ${job.id} ...; skipped" }
        nextFireCache.remove(job.id); return 0
    }
    val cached = nextFireCache[job.id]
    val next = if (cached == null || cached.cron != job.cron) {
        // 新任务或 cron 已修改 -> 从 now 起算下一次匹配。
        // 用 now-1min 让 nextFire（严格大于 from）把"当前分钟"纳入候选：
        // 若 now 恰处于某匹配分钟内（如 now=09:00:30、cron=0 9 * * *），
        // nextFire(now-1min)=09:00，本 tick 即触发该分钟的一次 tick。
        val n = expr.nextFire(now.minusMinutes(1)) ?: run { ...; return 0 }
        nextFireCache[job.id] = CachedNext(job.cron, n); n
    } else cached.nextFire

    return if (!next.isAfter(now)) {   // next <= now -> 到期
        fireAndRecord(job, updateStore = true)
        val advanced = expr.nextFire(next) ?: run { ...; return 1 }   // 推进到下一次（严格大于刚触发的）
        nextFireCache[job.id] = CachedNext(job.cron, advanced); 1
    } else 0
}

now=09:00:00, cron="0 9 * * *"
  nextFire(now)       = 2026-08-08 09:00  ← 错过今天 09:00（错误）
  nextFire(now-1min)  = 2026-08-07 09:00  ← 命中今天 09:00（正确）
  !next.isAfter(now)  = !(09:00 > 09:00) = true → 触发
  advance: nextFire(09:00) = 2026-08-08 09:00

// cron/CronScheduler.kt:123
private fun handleOneShot(job: CronJob, now: LocalDateTime): Int {
    val fireAt = job.fireAt ?: return 0
    if (now.toEpochMillis() >= fireAt) {
        fireAndRecord(job, updateStore = false)   // 即将删除，无需更新 lastFiredAt
        store.delete(job.id)
        nextFireCache.remove(job.id)
        return 1
    }
    return 0
}

// cron/CronScheduler.kt:68
fun start(scope: CoroutineScope) {
    if (pollJob?.isActive == true) return
    pollJob = scope.launch {
        try {
            while (isActive) {
                val fired = tick()
                if (fired > 0) logger.info { "Cron tick fired $fired job(s)" }
                delay(config.pollIntervalMillis)
            }
        } catch (e: CancellationException) {
            logger.info { "Cron scheduler stopped" }; throw e
        }
    }
}

// cron/CronScheduler.kt:193
private fun fireAndRecord(job: CronJob, updateStore: Boolean) {
    try {
        executor.fire(job)
    } catch (e: Exception) {
        logger.error(e) { "Cron executor threw for ${job.id}; execution skipped but schedule continues" }
    }
    if (updateStore) store.update(job.copy(lastFiredAt = System.currentTimeMillis()))
}

/cron                       列出所有任务（含下次触发）
/cron list                  同上
/cron add <name> <5-field-cron> <command>   新增周期任务
/cron once <name> <5-field-cron> <command>  新增一次性任务（触发后自动删除）
/cron show <id>             显示详情
/cron enable <id> / disable <id>   启用/禁用
/cron delete <id>           删除
/cron next [id]             显示下次触发时间
/cron test <5-field-cron>   解析测试，显示接下来 3 次匹配（不保存）

          ┌─────────────┐  register   ┌──────────────┐
LLM ─────▶│ ToolRegistry │────────────▶│  AgentLoop   │（自然发现，走 s03 权限 + s04 hooks）
          └──────┬──────┘             └──────────────┘
        cron_create / cron_list / cron_delete
                 │
    ┌────────────┼─────────────────────┐
    ▼            ▼                     ▼
┌────────┐  ┌──────────────┐    ┌──────────────┐
│CronStore│  │CronScheduler │    │ CronJob.build │（factory：parse + 算 fireAt）
│ nextId │  │ nextFireAt    │    └───────┬──────┘
│ save   │  └──────────────┘            │
│ delete │                          ┌────┴────┐
│loadAll │                          ▼         ▼
└────────┘                    CronExpr.parse  CronExpr.nextFire
       │
       ▼
  ~/.cat-code/cron.json（持久化，跨会话）

companion object {
    const val ID_PREFIX = "cron"

    fun build(
        id: String, name: String, cron: String, command: String,
        oneShot: Boolean, now: LocalDateTime
    ): CronBuildResult {
        val expr = try {
            CronExpr.parse(cron)
        } catch (e: IllegalArgumentException) {
            return CronBuildResult.InvalidExpr(e.message ?: "invalid cron expression")
        }
        val fireAt = if (oneShot) {
            expr.nextFire(now)?.toEpochMillis() ?: return CronBuildResult.NoFutureMatch
        } else {
            null
        }
        return CronBuildResult.Ok(
            CronJob(id = id, name = name, cron = cron, command = command, oneShot = oneShot, fireAt = fireAt)
        )
    }
}

sealed interface CronBuildResult {
    data class Ok(val job: CronJob) : CronBuildResult
    data class InvalidExpr(val message: String) : CronBuildResult
    data object NoFutureMatch : CronBuildResult
}

fun nextId(): String {
    val max = loadAll()
        .mapNotNull { it.id.removePrefix("${CronJob.ID_PREFIX}-").toIntOrNull() }
        .maxOrNull() ?: 0
    return "${CronJob.ID_PREFIX}-${max + 1}"
}

{
  "name": "cron_create",
  "description": "Schedule a recurring or one-shot cron job that runs a shell command on a time schedule. The job persists across sessions and fires while the REPL is active. Pass a 5-field cron expression... Set one_shot=true to fire once at the next match then auto-delete. Use cron_list to view jobs and cron_delete to remove one.",
  "input_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Human-readable label for the job (shown in cron_list)" },
      "cron": { "type": "string", "description": "5-field cron expression: minute hour day-of-month month day-of-week. Ranges: 0-59 0-23 1-31 1-12 0-6 (0=Sunday). Supports *, single values, a-b ranges, a,b,c lists, and */n steps." },
      "command": { "type": "string", "description": "Shell command to execute when the job fires" },
      "one_shot": { "type": "boolean", "description": "If true, fires once at the next matching time then auto-deletes. Default false (recurring).", "default": false }
    },
    "required": ["name", "cron", "command"]
  }
}

// cron/CronCreateTool.kt
override suspend fun execute(input: JsonObject): ToolResult {
    val name = input["name"]?.jsonPrimitive?.contentOrNull
        ?: return ToolResult("", "Error: name is required", isError = true)
    val cron = input["cron"]?.jsonPrimitive?.contentOrNull
        ?: return ToolResult("", "Error: cron is required", isError = true)
    val command = input["command"]?.jsonPrimitive?.contentOrNull
        ?: return ToolResult("", "Error: command is required", isError = true)
    val oneShot = input["one_shot"]?.jsonPrimitive?.booleanOrNull ?: false

    val id = store.nextId()
    val job = when (val result = CronJob.build(id, name, cron, command, oneShot, LocalDateTime.now())) {
        is CronBuildResult.InvalidExpr ->
            return ToolResult("", "Error: invalid cron expression '$cron': ${result.message}", isError = true)
        CronBuildResult.NoFutureMatch ->
            return ToolResult("", "Error: cron expression has no future match: '$cron'", isError = true)
        is CronBuildResult.Ok -> result.job
    }
    store.save(job)
    // 返回 id + 模式 + schedule + command + 下次触发（recurring 用 scheduler.nextFireAt，one-shot 用 fireAt）
    ...
}

// cron/CronListTool.kt
override suspend fun execute(input: JsonObject): ToolResult {
    val jobs = store.loadAll()
    if (jobs.isEmpty()) {
        return ToolResult("", "No cron jobs scheduled. Use cron_create to add one.")
    }
    val text = buildString {
        append("Cron jobs (${jobs.size}):")
        for (j in jobs) {
            val state = if (j.enabled) "ON" else "OFF"
            val mode = if (j.oneShot) "once" else "recur"
            append("\n  ${j.id}  [$state/$mode]  ${j.cron}  ${j.name}")
            // 仅 enabled 任务展示触发时刻；disabled 不算 nextFire
            if (j.enabled) {
                if (j.oneShot) {
                    j.fireAt?.let { append("  fires=${epochMillisToLocal(it).formatCronTime()}") }
                } else {
                    val nxt = scheduler.nextFireAt(j.id)
                    if (nxt != null) append("  next=${nxt.formatCronTime()}")
                }
            }
        }
    }
    return ToolResult("", text)
}

// cron/CronDeleteTool.kt
override suspend fun execute(input: JsonObject): ToolResult {
    val id = input["id"]?.jsonPrimitive?.contentOrNull
        ?: return ToolResult("", "Error: id is required", isError = true)
    return if (store.delete(id)) {
        logger.info { "cron_delete: $id" }
        ToolResult("", "Cron job deleted: $id")
    } else {
        ToolResult("", "Error: cron job not found: $id", isError = true)
    }
}

> 帮我每天早上 9 点跑备份脚本 ./backup.sh
[LLM 调用 cron_create: name="daily-backup", cron="0 9 * * *", command="./backup.sh"]
Cron job created: cron-1 (recurring)
  schedule: 0 9 * * *
  command:  ./backup.sh
  next fire: 2026-08-11 09:00

> 看看现在有哪些定时任务
[LLM 调用 cron_list]
Cron jobs (1):
  cron-1  [ON/recur]  0 9 * * *  daily-backup  next=2026-08-11 09:00

> 那个备份不用了，删掉
[LLM 调用 cron_list 找到 id，再 cron_delete: id="cron-1"]
Cron job deleted: cron-1

// repl/ReplLoop.kt:202
val cronConfig = CronConfig()
cronStore = CronStore(cronConfig.resolvedCronFile())
cronScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
val cronExecutor = CronExecutor { job: CronJob ->
    when (val result = backgroundRunner.launch(job.command)) {
        is BackgroundLaunchResult.Success -> notificationQueue.push(
            BackgroundNotification("cron:${job.id}", BackgroundStatus.RUNNING,
                "cron '${job.name}' fired -> ${result.taskId}"))
        is BackgroundLaunchResult.Rejected -> notificationQueue.push(
            BackgroundNotification("cron:${job.id}", BackgroundStatus.FAILED,
                "cron '${job.name}' fire rejected: ${result.reason}"))
    }
}
cronScheduler = CronScheduler(cronStore, cronExecutor, cronConfig)
cronScheduler.start(cronScope)

// repl/ReplLoop.kt（cronScheduler.start(cronScope) 之后）
toolRegistry.register(CronCreateTool(cronStore, cronScheduler))
toolRegistry.register(CronListTool(cronStore, cronScheduler))
toolRegistry.register(CronDeleteTool(cronStore))

// repl/ReplLoop.kt:301（finally 块）
cronScheduler.stop()
cronScope.cancel()

会话 A（2026-08-07 14:00）:
  > /cron add nightly 0 9 * * * ./gradlew test
    └─ CronCommand.addJob:
         ├─ CronExpr.parse("0 9 * * *") 校验通过
         ├─ job = CronJob(id=cron-1, recurring, fireAt=null)
         ├─ cronStore.save -> 写入 ~/.cat-code/cron.json
         └─ "Cron job created: cron-1, next fire: 2026-08-08 09:00"
  > exit
    └─ cronScheduler.stop() + cronScope.cancel()
       任务定义已持久化（cron.json 含 cron-1）

  [REPL 关闭，cronScope 取消，不再触发。任务定义在磁盘沉睡]

会话 B（2026-08-08 09:00:15，次日早上重启）:
  启动 -> CronStore 从 cron.json 加载 cron-1
       -> cronScheduler.start(cronScope): 轮询协程启动

  轮询协程（每 30s）:
    tick(now=09:00:15):
      job=cron-1 (recurring, enabled)
      handleRecurring: cache miss -> nextFire(09:00:15 - 1min = 08:59:15) = 09:00 today
      !09:00.isAfter(09:00:15) = !(false) = true → 到期
        fireAndRecord:
          executor.fire -> backgroundRunner.launch("./gradlew test") -> bg-1
          notificationQueue.push("cron 'nightly' fired -> bg-1")
          store.update(cron-1, lastFiredAt=09:00:15)
        advance: nextFire(09:00) = 2026-08-09 09:00 → cache
      return 1

  > /cron list                       ← 用户查看
  Cron jobs (1):
    cron-1  [ON/recur]  0 9 * * *  nightly  next=2026-08-09 09:00

  [后台 bg-1 跑测试，40 秒后完成]
  下一轮 REPL 回合结束 -> drainNotifications():
    🔔 cron:1 - cron 'nightly' fired -> bg-1     ← cron 触发通知
    🔔 bg-1 - completed (exit code 0)            ← s13 完成通知

> /cron once deploy-check 30 14 7 8 * echo check-the-deploy
  └─ addJob(oneShot=true):
       ├─ next = nextFire(now) = 14:30 today
       ├─ fireAt = 14:30 的 epoch millis
       └─ "Cron job created: cron-2 (once), fires at: 2026-08-07 14:30"

[14:30 到达，tick 触发]
  handleOneShot: now>=fireAt → fire + store.delete(cron-2)
  🔔 cron:2 - cron 'deploy-check' fired -> bg-5
  [cron-2 已自动删除，不再触发]

> /cron test 0 9 * * 1
Expression: 0 9 * * 1
  1. 2026-08-10 09:00     ← 周一
  2. 2026-08-17 09:00
  3. 2026-08-24 09:00
> /cron test 0 0 30 2 *
Expression: 0 0 30 2 *
  (no more matches)        ← 2 月 30 日不存在，nextFire 返回 null