Skip to content

An always-on second brain you talk to. Voice notes in Telegram → typed, linked knowledge in your Obsidian vault. Runs 24/7 on the Claude subscription you already have.

feat(cron): runner — in-bot ticker, delivery, self-healing

smixs847fc0cf6a11
diff --git a/src/d_brain/bot/main.py b/src/d_brain/bot/main.py
index 09a1c98..88899ab 100644
--- a/src/d_brain/bot/main.py
+++ b/src/d_brain/bot/main.py
@@ -12,6 +12,7 @@ from aiogram.fsm.storage.memory import MemoryStorage
from aiogram.types import Update
from d_brain.config import Settings
+from d_brain.services.cron_runner import run_cron
from d_brain.services.runtime import get_session
from d_brain.services.systemd_notify import notify, watchdog_interval
@@ -110,10 +111,15 @@ async def run_bot(settings: Settings) -> None:
notify("READY=1")
pinger = asyncio.create_task(_watchdog_pinger())
+ cron_task = (
+ asyncio.create_task(run_cron(settings, bot)) if settings.cron_enabled else None
+ )
logger.info("Starting bot polling...")
try:
await dp.start_polling(bot, allowed_updates=dp.resolve_used_update_types())
finally:
pinger.cancel()
+ if cron_task is not None:
+ cron_task.cancel()
await bot.session.close()
diff --git a/src/d_brain/cron.py b/src/d_brain/cron.py
index 00ee229..655903e 100644
--- a/src/d_brain/cron.py
+++ b/src/d_brain/cron.py
@@ -11,7 +11,7 @@ import argparse
import os
import sys
import uuid
-from datetime import datetime, timezone
+from datetime import UTC, datetime
from pathlib import Path
from d_brain.services.cron_store import (
@@ -77,7 +77,7 @@ def _fmt_schedule(job: CronJob) -> str:
def _cmd_add(args: argparse.Namespace) -> int:
store = CronStore(Path(args.dir))
- now = datetime.now(timezone.utc)
+ now = datetime.now(UTC)
schedule = parse_schedule(
at=args.at, every=args.every, cron=args.cron, tz=args.tz, default_tz=args.tz
)
@@ -141,7 +141,7 @@ def _cmd_remove(args: argparse.Namespace) -> int:
def _cmd_enable(args: argparse.Namespace) -> int:
store = CronStore(Path(args.dir))
- now = datetime.now(timezone.utc)
+ now = datetime.now(UTC)
def fix(jobs: list[CronJob]) -> None:
job = _find(jobs, args.job_id)
diff --git a/src/d_brain/services/cron_runner.py b/src/d_brain/services/cron_runner.py
new file mode 100644
index 0000000..676ab77
--- /dev/null
+++ b/src/d_brain/services/cron_runner.py
@@ -0,0 +1,233 @@
+"""Cron runner: the in-bot ticker that fires scheduled jobs in the cron
+brain (the second, isolated ClaudeSession).
+
+Semantics:
+* jobs.json is re-read every tick (hot-reload — the brain edits it via
+ the CLI while the bot runs).
+* At-most-once: next_run is advanced and persisted BEFORE ask(), so a
+ crash mid-run never refires the same slot.
+* Self-healing lives here, not in the watchdog: a failed ask() recovers
+ the cron session; max_consecutive_errors auto-disables the job and
+ alerts the admin. rate_limited is not the job's fault — skip, wait.
+* A reply starting with [SILENT] is not delivered (anti-spam for
+ monitoring jobs).
+"""
+
+import asyncio
+import copy
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from d_brain.services.cron_store import CronJob, CronStore, compute_next_run
+
+logger = logging.getLogger(__name__)
+
+SILENT_MARKER = "[SILENT]"
+
+
+def wrap_job_prompt(job_id: str, prompt: str, *, scheduled_for: str | None) -> str:
+ """Per-run envelope for the cron brain. The marker instruction is NOT
+ duplicated here — ask(wrap=True) appends it."""
+ return (
+ f"[CRON JOB {job_id}] Это плановый запуск по расписанию "
+ f"(scheduled_for: {scheduled_for}), не сообщение пользователя.\n\n"
+ f"{prompt}\n\n"
+ "Правила запуска: ответ уйдёт в Telegram — форматируй в HTML "
+ "(<b> <i> <code> <a>), без Markdown. Если доставлять нечего — начни "
+ f"ответ строкой {SILENT_MARKER}. В этом запуске ЗАПРЕЩЕНО создавать, "
+ "изменять или удалять cron-задания (никаких d_brain.cron add/remove)."
+ )
+
+
+def _find(jobs: list[CronJob], job_id: str) -> CronJob | None:
+ return next((j for j in jobs if j.id == job_id), None)
+
+
+class CronRunner:
+ def __init__(
+ self,
+ store: CronStore,
+ session: Any,
+ *,
+ deliver: Callable[[int, str], Awaitable[None]],
+ alert: Callable[[str], Awaitable[None]],
+ default_chat_id: int | None,
+ job_timeout: float = 600.0,
+ max_consecutive_errors: int = 3,
+ retry_seconds: float = 300.0,
+ clock: Callable[[], datetime] | None = None,
+ ) -> None:
+ self.store = store
+ self.session = session
+ self.deliver = deliver
+ self.alert = alert
+ self.default_chat_id = default_chat_id
+ self.job_timeout = job_timeout
+ self.max_consecutive_errors = max_consecutive_errors
+ self.retry_seconds = retry_seconds
+ self.clock = clock or (lambda: datetime.now(UTC))
+
+ # ── scheduling ───────────────────────────────────────────────────
+
+ def claim_due(self, now: datetime) -> list[CronJob]:
+ """Snapshot due jobs and advance their next_run under the lock.
+
+ Persisting the advance BEFORE execution gives at-most-once: a
+ crash mid-ask never refires the slot. One-shot ('at') jobs get
+ next_run=None here; success deletes them, failure re-arms a retry.
+ """
+ claimed: list[CronJob] = []
+
+ def advance(jobs: list[CronJob]) -> None:
+ for job in jobs:
+ if not job.enabled or not job.state.next_run:
+ continue
+ if datetime.fromisoformat(job.state.next_run) > now:
+ continue
+ claimed.append(copy.deepcopy(job))
+ if job.schedule.kind == "at":
+ job.state.next_run = None
+ else:
+ nxt = compute_next_run(job.schedule, now=now)
+ job.state.next_run = nxt.isoformat() if nxt else None
+
+ self.store.mutate(advance)
+ return claimed
+
+ # ── execution ────────────────────────────────────────────────────
+
+ async def run_job(self, job: CronJob) -> None:
+ wrapped = wrap_job_prompt(
+ job.id, job.prompt, scheduled_for=job.state.next_run
+ )
+ res = await asyncio.to_thread(
+ self.session.ask, wrapped, timeout=self.job_timeout
+ )
+ now = self.clock()
+
+ if res.status == "rate_limited":
+ logger.warning("cron job %s skipped: subscription rate limit", job.id)
+ self._record_failure(job, now, status="rate_limited", count=False)
+ return
+
+ if res.ok:
+ reply = (res.reply or "").strip()
+ silent = reply.startswith(SILENT_MARKER)
+ if reply and not silent:
+ chat = job.chat_id or self.default_chat_id
+ if chat is not None:
+ await self.deliver(chat, reply)
+ # Jobs are stateless by contract; drop the turn's context so
+ # the next job starts clean and the window never grows.
+ await asyncio.to_thread(self.session.send_control, "/clear")
+ self._record_success(job, now, silent=silent)
+ return
+
+ logger.error("cron job %s failed: %s %s", job.id, res.status, res.detail)
+ await asyncio.to_thread(self.session.force_recover)
+ disabled = self._record_failure(
+ job, now, status=res.status, detail=res.detail, count=True
+ )
+ if disabled:
+ await self.alert(
+ f"⛔ Cron job <code>{job.id}</code> отключён после "
+ f"{self.max_consecutive_errors} ошибок подряд "
+ f"(последняя: {res.status}). Включить: "
+ f"<code>python -m d_brain.cron enable {job.id}</code>"
+ )
+
+ # ── state updates (single write path: store.mutate) ─────────────
+
+ def _record_success(self, job: CronJob, now: datetime, *, silent: bool) -> None:
+ def fn(jobs: list[CronJob]) -> None:
+ current = _find(jobs, job.id)
+ if current is None:
+ return
+ if job.delete_after_run:
+ jobs.remove(current)
+ return
+ current.state.last_run = now.isoformat()
+ current.state.last_status = "ok-silent" if silent else "ok"
+ current.state.last_error = None
+ current.state.consecutive_errors = 0
+
+ self.store.mutate(fn)
+
+ def _record_failure(
+ self,
+ job: CronJob,
+ now: datetime,
+ *,
+ status: str,
+ detail: str | None = None,
+ count: bool,
+ ) -> bool:
+ """Update job state after a non-ok run; True if it got disabled."""
+ disabled = False
+
+ def fn(jobs: list[CronJob]) -> None:
+ nonlocal disabled
+ current = _find(jobs, job.id)
+ if current is None:
+ return
+ current.state.last_run = now.isoformat()
+ current.state.last_status = status
+ current.state.last_error = detail
+ if count:
+ current.state.consecutive_errors += 1
+ if current.state.consecutive_errors >= self.max_consecutive_errors:
+ current.enabled = False
+ disabled = True
+ # A claimed one-shot lost its next_run; re-arm a retry unless
+ # the job just got disabled.
+ if current.schedule.kind == "at" and not disabled:
+ retry_at = now + timedelta(seconds=self.retry_seconds)
+ current.state.next_run = retry_at.isoformat()
+
+ self.store.mutate(fn)
+ return disabled
+
+ # ── loop ─────────────────────────────────────────────────────────
+
+ async def tick(self) -> None:
+ for job in self.claim_due(self.clock()):
+ await self.run_job(job)
+
+ async def run(self, tick_seconds: float) -> None:
+ logger.info("cron runner started (tick %.0fs)", tick_seconds)
+ while True:
+ try:
+ await self.tick()
+ except Exception: # noqa: BLE001 — one bad tick must not kill the loop
+ logger.exception("cron tick failed")
+ await asyncio.sleep(tick_seconds)
+
+
+async def run_cron(settings: Any, bot: Any) -> None:
+ """Wire the runner to the real store, cron session and Telegram."""
+ from d_brain.bot.formatters import send_response
+ from d_brain.services import runtime
+
+ store = CronStore(settings.cron_dir)
+ session = runtime.get_cron_session(settings)
+
+ async def deliver(chat_id: int, text: str) -> None:
+ await send_response(bot, chat_id, text)
+
+ async def alert(text: str) -> None:
+ if settings.admin_chat_id is not None:
+ await bot.send_message(settings.admin_chat_id, text)
+
+ runner = CronRunner(
+ store,
+ session,
+ deliver=deliver,
+ alert=alert,
+ default_chat_id=settings.admin_chat_id,
+ job_timeout=settings.cron_job_timeout,
+ max_consecutive_errors=settings.cron_max_consecutive_errors,
+ retry_seconds=settings.cron_retry_seconds,
+ )
+ await runner.run(settings.cron_tick_seconds)
diff --git a/tests/test_cron_runner.py b/tests/test_cron_runner.py
new file mode 100644
index 0000000..57924f5
--- /dev/null
+++ b/tests/test_cron_runner.py
@@ -0,0 +1,259 @@
+"""Tests for the cron runner: ticker semantics, delivery, self-healing.
+
+FakeSession pattern as in test_claude_session.py — no tmux, scripted
+AskResults, recorder callables for deliver/alert, a manual clock.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from d_brain.services.claude_session import AskResult
+from d_brain.services.cron_runner import SILENT_MARKER, CronRunner, wrap_job_prompt
+from d_brain.services.cron_store import CronJob, CronStore, Schedule
+
+NOW = datetime(2026, 6, 10, 12, 0, tzinfo=timezone.utc)
+
+
+class FakeSession:
+ def __init__(self, results=None, on_ask=None):
+ self.results = list(results or [])
+ self.on_ask = on_ask
+ self.asked: list[str] = []
+ self.controls: list[str] = []
+ self.recovered = 0
+
+ def ask(self, prompt, *, timeout=0.0, wrap=True):
+ self.asked.append(prompt)
+ if self.on_ask:
+ self.on_ask()
+ return self.results.pop(0) if self.results else AskResult("ok", reply="done")
+
+ def send_control(self, text):
+ self.controls.append(text)
+
+ def force_recover(self):
+ self.recovered += 1
+ return True
+
+
+class Recorder:
+ def __init__(self):
+ self.calls = []
+
+ async def __call__(self, *args):
+ self.calls.append(args)
+
+
+def _store(tmp_path):
+ return CronStore(tmp_path / "cron")
+
+
+def _add_job(store, job_id="j1", *, kind="every", next_run=NOW, **over):
+ if kind == "every":
+ schedule = Schedule(kind="every", every_seconds=3600)
+ elif kind == "at":
+ schedule = Schedule(kind="at", at=next_run.isoformat())
+ else:
+ schedule = Schedule(kind="cron", expr="0 9 * * *", tz="UTC")
+ base = dict(id=job_id, prompt="do it", schedule=schedule)
+ base.update(over)
+ job = CronJob(**base)
+ job.state.next_run = next_run.isoformat()
+ store.mutate(lambda jobs: jobs.append(job))
+ return job
+
+
+def _runner(store, session, *, deliver=None, alert=None, clock=None, **over):
+ base = dict(
+ deliver=deliver or Recorder(),
+ alert=alert or Recorder(),
+ default_chat_id=111,
+ job_timeout=10.0,
+ max_consecutive_errors=3,
+ retry_seconds=300.0,
+ clock=clock or (lambda: NOW),
+ )
+ base.update(over)
+ return CronRunner(store, session, **base)
+
+
+# ── ticker semantics ─────────────────────────────────────────────────
+
+
+async def test_due_job_runs_and_delivers(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ deliver = Recorder()
+ session = FakeSession([AskResult("ok", reply="<b>done</b>")])
+ await _runner(store, session, deliver=deliver).tick()
+ assert len(session.asked) == 1
+ assert "do it" in session.asked[0]
+ assert deliver.calls == [(111, "<b>done</b>")]
+
+
+async def test_future_and_disabled_jobs_skipped(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "future", next_run=NOW + timedelta(hours=1))
+ _add_job(store, "off", enabled=False)
+ session = FakeSession()
+ await _runner(store, session).tick()
+ assert session.asked == []
+
+
+async def test_next_run_persisted_before_ask(tmp_path):
+ """At-most-once: a crash mid-ask must not refire the same slot."""
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ seen = {}
+
+ def snapshot():
+ seen["next_run"] = store.load()[0].state.next_run
+
+ session = FakeSession([AskResult("ok", reply="x")], on_ask=snapshot)
+ await _runner(store, session).tick()
+ assert seen["next_run"] == (NOW + timedelta(hours=1)).isoformat()
+
+
+async def test_every_job_reschedules_after_run(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ await _runner(store, FakeSession([AskResult("ok", reply="x")])).tick()
+ job = store.load()[0]
+ assert job.state.next_run == (NOW + timedelta(hours=1)).isoformat()
+ assert job.state.last_status == "ok"
+ assert job.state.last_run == NOW.isoformat()
+
+
+async def test_hot_reload_picks_up_jobs_added_between_ticks(tmp_path):
+ store = _store(tmp_path)
+ session = FakeSession([AskResult("ok", reply="x")])
+ runner = _runner(store, session)
+ await runner.tick()
+ assert session.asked == []
+ _add_job(store, "late") # e.g. brain CLI while the bot is running
+ await runner.tick()
+ assert len(session.asked) == 1
+
+
+# ── delivery ─────────────────────────────────────────────────────────
+
+
+async def test_job_chat_id_overrides_default(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1", chat_id=999)
+ deliver = Recorder()
+ await _runner(
+ store, FakeSession([AskResult("ok", reply="x")]), deliver=deliver
+ ).tick()
+ assert deliver.calls == [(999, "x")]
+
+
+async def test_silent_reply_suppresses_delivery(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ deliver = Recorder()
+ reply = f"{SILENT_MARKER} nothing new"
+ await _runner(
+ store, FakeSession([AskResult("ok", reply=reply)]), deliver=deliver
+ ).tick()
+ assert deliver.calls == []
+ assert store.load()[0].state.last_status == "ok-silent"
+
+
+async def test_clear_sent_after_successful_run(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ session = FakeSession([AskResult("ok", reply="x")])
+ await _runner(store, session).tick()
+ assert "/clear" in session.controls
+
+
+# ── one-shot lifecycle ───────────────────────────────────────────────
+
+
+async def test_oneshot_deleted_after_success(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "once", kind="at", delete_after_run=True)
+ await _runner(store, FakeSession([AskResult("ok", reply="x")])).tick()
+ assert store.load() == []
+
+
+async def test_oneshot_error_kept_with_retry(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "once", kind="at", delete_after_run=True)
+ await _runner(store, FakeSession([AskResult("timeout")])).tick()
+ jobs = store.load()
+ assert len(jobs) == 1
+ assert jobs[0].state.next_run == (NOW + timedelta(seconds=300)).isoformat()
+ assert jobs[0].state.last_status == "timeout"
+
+
+# ── self-healing ─────────────────────────────────────────────────────
+
+
+async def test_error_recovers_session_and_counts(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ session = FakeSession([AskResult("error", detail="boom")])
+ await _runner(store, session).tick()
+ assert session.recovered == 1
+ job = store.load()[0]
+ assert job.state.consecutive_errors == 1
+ assert job.state.last_error == "boom"
+ assert job.enabled is True
+
+
+async def test_third_consecutive_error_disables_and_alerts(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+
+ def set_errors(jobs):
+ jobs[0].state.consecutive_errors = 2
+
+ store.mutate(set_errors)
+ alert = Recorder()
+ await _runner(store, FakeSession([AskResult("error")]), alert=alert).tick()
+ job = store.load()[0]
+ assert job.enabled is False
+ assert job.state.consecutive_errors == 3
+ assert len(alert.calls) == 1
+ assert "j1" in alert.calls[0][0]
+
+
+async def test_success_resets_error_counter(tmp_path):
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+
+ def set_errors(jobs):
+ jobs[0].state.consecutive_errors = 2
+
+ store.mutate(set_errors)
+ await _runner(store, FakeSession([AskResult("ok", reply="x")])).tick()
+ assert store.load()[0].state.consecutive_errors == 0
+
+
+async def test_rate_limited_skips_without_recover_or_count(tmp_path):
+ """Subscription limit is not the job's fault: wait for the next slot."""
+ store = _store(tmp_path)
+ _add_job(store, "j1")
+ session = FakeSession([AskResult("rate_limited")])
+ await _runner(store, session).tick()
+ job = store.load()[0]
+ assert session.recovered == 0
+ assert job.state.consecutive_errors == 0
+ assert job.state.last_status == "rate_limited"
+ assert "/clear" not in session.controls
+
+
+# ── prompt wrapper ───────────────────────────────────────────────────
+
+
+def test_wrap_job_prompt_contract():
+ wrapped = wrap_job_prompt("j1", "check the inbox", scheduled_for="2026-06-10")
+ assert "[CRON JOB j1]" in wrapped
+ assert "check the inbox" in wrapped
+ assert "2026-06-10" in wrapped
+ assert SILENT_MARKER in wrapped
+ # recursion guard: a scheduled run must not breed more jobs
+ assert "d_brain.cron" in wrapped
+ # marker instruction belongs to ask(wrap=True), never duplicated here
+ assert "<<<R:" not in wrapped