Houmeres/LLeMbas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Something can happen because time passed, and land somewhere worth reading

Browse Source 
Nothing in LLeMbas ever happened on its own. Every reply was downstream of
somebody pressing Send, and the one exception -- jobs.wake, waking a chat when a
background job finishes -- was downstream of a command they had run. PLAN.md
never listed scheduling as unbuilt because services/chat.py:618 had recorded it
as a decision: "a scheduler is a whole new concern for a single-worker
application". This is that concern, taken on deliberately, plus the two places
its output goes.

Reports first, because it is useful with no scheduling at all. A report is not a
Chat with one Message in it: it has no turns and no reply, it is read top to
bottom, and it must be writable with no chat behind it -- being the fallback for
a run whose own chat has gone. As a Chat it would need a sidebar row per daily
report, a title that regenerates itself, a composer to suppress and a bubble with
a rewind button around something that is not a turn. The section's character is
enforced by absence: nothing under reports/ includes the composer or renders
chat/_message.html, so there is no sse-connect anywhere and nothing on those
pages *can* start a generation. The test reads that off the OpenAPI schema, not
by walking app.routes -- this FastAPI keeps an included router wrapped rather
than flattening it, so the walk finds nothing and the assertion passes for the
wrong reason.

rule.py is pure, total, and was finished before anything called it. No session,
no wall clock, nothing that raises: validate clamps what it recognises, drops
what it does not, and answers {} for prose -- at which point the caller shows the
manual form. It had to be that way because the compile step's output is model
output that becomes a *timer*, which is the sharpest case of hard rule 6 here.
The invariant, pinned: anything validate accepts has a computable next
occurrence. A schedule that can never fire looks exactly like a working one on
every screen it appears on.

Wall-clock and elapsed time are kept apart because they mean different things.
at.times are wall-clock in the owner's zone, so 15:00 stays 15:00 across a
daylight-saving change -- that is what "every Monday at 3PM" means. every is
elapsed real time, so six hours stays six hours across a 23- or 25-hour day --
that is what a timer means. Conflating them gets one of the two wrong twice a
year. A time inside the spring-forward gap fires at the first minute that exists;
left to zoneinfo's own resolution it lands an hour away wearing a wall-clock time
that did not happen, and a daily 02:30 report vanishing once a year on a machine
nobody watches is the failure this file is arranged around.

The ticker claims and commits *before* it fires. The other order is a hot loop: a
firing that raises is retried every tick for ever against whatever it was that
failed, and the only symptom is load. Its blanket except is copied from the
terminal reaper for a sharper reason -- a ticker that dies on one bad row stops
every schedule on the instance and says nothing at all. No request fails, no
reply errors, no dot appears. The reports simply stop.

Three rules that look like bugs from outside: a firing arriving while the chat is
still answering queues rather than starting a second reply, and past max_queued
is skipped with the reason on the row; Run now does not advance next_fire_at, or
testing a schedule silently consumes the run it was testing; resuming recomputes
from now, or a schedule paused for a month fires the instant it comes back, once
per occurrence it missed. Catching up lives in the sweep and not in a startup
hook, because a suspended host and a long stall reproduce "its time passed while
nothing was running" with no restart to hang one on.

services/wake.py is the lock discipline extracted rather than copied. A finished
job and a due schedule are the same problem, and both depend on there being no
await between the running_for check and the writes; two lock dictionaries for one
invariant is how one of them drifts. jobs.wake is now a caller that supplies
wording, and _completion_text stayed exactly where it was because tool.background
quotes its opening sentence.

A scheduled run has no reader, so ask_user is withdrawn from resolve_tools rather
than merely discouraged in core.unattended -- a rule living only in a system
message is one a page the model just read can argue with, and a parked question
holds the reply for the whole approval_timeout with nobody to answer it. For the
same reason a task chat may not be an agent chat in v1: Manual, Edit and Plan all
stop to ask on RISK_EXECUTE, so the only two outcomes would be unattended
execution and a reply that stalls. That deserves its own pass.

Messages is bounded in the request and unbounded on disk. Only the latest chunk
is sent; everything else stays exactly where it was written. Nothing is folded
into text and nothing is deleted -- the visible conversation is identical either
way, so destroying the older rows would buy only disk, against being irreversible
and losing every attachment and tool call in the range, and it would contradict
the rule compaction already holds. should_compact refuses this kind for the
matching reason: two mechanisms narrowing one transcript is how a summary ends up
summarising a summary. The history route is the mirror of thread_tail and keeps
its four properties; the fifth is its own, that prepending moves the scroll
position, so app.js records scrollHeight before the swap and adds the difference
back after.

An empty Chat.kind meant "both sides of the switch" and had been read as "no
filter" since there were only two of them. The sidebar passes "" precisely when
agent chats are switched off -- so the moment a third kind existed, every task
chat and every Messages conversation appeared in somebody's ordinary chat list,
on exactly the instances whose owners would never think to look. KINDS stays the
two-sided fork, because set_sidebar_kind validates against it and a third entry
there makes the tree filterable to a side with no button to leave it; ALL_KINDS
is what a row may be. Both narrowings are pinned, because they are two
implementations of one rule and only one of them is SQL.

Per-user timezone had to exist for any of this: harness.py:179 was telling every
reader the *server's* idea of the date, which is survivable while the answer is
prose and stops being survivable the moment somebody says "every Monday at 3" and
something has to work out when that is.

Three things were caught by a test being wrong rather than by the code being
wrong. The task-chat "no composer" assertions were passing against a page
rendering its no-models-configured branch. A permission test asserted the same
thing twice because the administrator bypasses every permission. And every
Messages test passed with default_model never called, because none of them
configured a model -- so the pair it returns was being assigned straight to
model_id, and SQLite refuses a tuple in a String column. The fixtures now say why
they exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jaroslav Beneš
2026-08-05 21:31:36 +02:00
co-authored by Claude Opus 5
parent 178742501d
commit 9ddc0a2103
63 changed files with 6773 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lembas/services/schedule/ticker.py
+210
View File
@@ -0,0 +1,210 @@
"""The loop that notices a schedule is due, and claims it.
Modelled on `agent/terminal.py:_reaper_loop`, which is the only periodic task
this codebase had before now — including the blanket `except` around the sweep,
for a reason that is sharper here: **a ticker that dies on one bad row stops
every schedule on the instance, and says nothing.** Nothing else would notice.
There is no request failing, no reply erroring, no dot appearing. The reports
simply stop, and the first person to find out is whoever eventually wonders why.
Started from the lifespan rather than lazily like the reaper. Lazy is right for
terminals — a shell only exists once somebody opened one — and wrong here: a
schedule can be due at startup with nobody logged in, which is most of the point.
## Claiming, and why the order is the whole design
One worker and one loop, so the risk is not two processes racing; it is two
*overlapping sweeps*, and a firing that raises being retried every tick for ever.
Three things answer that:
1. A lock around the sweep, so a slow one (a firing awaits a model, which can
take minutes) cannot overlap the next tick.
2. **Advance, then fire.** The row is moved on and committed *before* anything
is awaited. A firing that dies has still consumed its slot, so the schedule
resumes at its next occurrence with the reason on the row — rather than
becoming a hot loop against an endpoint that is down.
3. `claimed_at` outliving a firing is what lets a run that never finished say so
instead of looking like one that never started.
Exhaustion **disables**: a rule with nothing left returns `None`, and the row is
switched off rather than being re-examined for ever.
"""
from __future__ import annotations
import asyncio
import contextlib
import logging
from datetime import UTC, datetime, timedelta
from sqlalchemy import select
from lembas.db.models import Schedule, User
from lembas.db.session import session_scope
from lembas.services import settings_store
from lembas.services.schedule import clock, runner
from lembas.services.schedule import rule as rule_service
log = logging.getLogger(__name__)
_TICKER: asyncio.Task | None = None
_SWEEPING = asyncio.Lock()
# Live firings, so shutdown can wait for them rather than leaving a half-written
# reply and a `claimed_at` that never clears.
_FIRING: set[asyncio.Task] = set()
# Fallback when nothing has been configured. `settings_store.schedules` clamps
# the stored value; this is only for a sweep that runs before anything is read.
TICK_SECONDS = 30.0
def _due(now: datetime):
return (
select(Schedule)
.where(
Schedule.enabled.is_(True),
Schedule.next_fire_at.is_not(None),
Schedule.next_fire_at <= now,
)
.order_by(Schedule.next_fire_at)
)
def claim(schedule: Schedule, *, now: datetime, zone) -> tuple[bool, datetime | None]:
"""Move one schedule on, and say whether it is owed a firing.
Pure bookkeeping on the row: it does not fire anything and does not commit,
so the caller decides the transaction boundary. The caller must commit
before awaiting.
"""
rule = schedule.rule_json or {}
after = clock.as_utc(schedule.next_fire_at) if schedule.next_fire_at else now
fire_now, following = rule_service.advance(
rule,
# A microsecond earlier, because `next_after` answers *strictly* after
# what it is given -- so handing it the stored due moment would return
# the one following and skip the firing that is actually owed. The
# alternative, making `next_after` inclusive, would break the far more
# common "give me the one after this one" call it exists for.
after=after - timedelta(microseconds=1),
now=now,
zone=zone,
fired=schedule.fired_count or 0,
)
if fire_now:
schedule.fired_count = (schedule.fired_count or 0) + 1
schedule.last_fire_at = now
schedule.next_fire_at = following
if following is None:
# Nothing left to do: a spent count, a closed window, a calendar that
# matches nothing inside the horizon. Switched off rather than left
# enabled with a null next time, which would read as "waiting" for ever.
schedule.enabled = False
return fire_now, following
async def sweep(*, now: datetime | None = None) -> int:
"""One pass. Returns how many schedules were fired.
Claims every due row and commits, then starts the firings — in that order,
and with the commit in between, which is the property `test_schedule_ticker`
checks by making a firing raise.
"""
now = now or datetime.now(tz=UTC)
to_fire: list[tuple[str, datetime]] = []
async with _SWEEPING:
with session_scope() as db:
if not settings_store.schedules(db).get("enabled"):
return 0
limit = int(settings_store.schedules(db).get("max_concurrent") or 3)
for schedule in db.scalars(_due(now)):
try:
owner = db.get(User, schedule.user_id)
if owner is None:
# The account is gone; the CASCADE will take the row.
schedule.enabled = False
continue
due_at = clock.as_utc(schedule.next_fire_at) if schedule.next_fire_at else now
fire_now, _ = claim(schedule, now=now, zone=clock.zone_for(owner))
if fire_now:
to_fire.append((schedule.id, due_at))
except Exception: # noqa: BLE001 - one bad row must not stop the sweep
log.exception("could not claim schedule %s", schedule.id)
with contextlib.suppress(Exception):
schedule.enabled = False
schedule.last_error = "This schedule could not be read, so it was stopped."
# Committed before a single firing starts. This is the claim.
db.commit()
if not to_fire:
return 0
semaphore = asyncio.Semaphore(max(1, limit))
async def _guarded(schedule_id: str, due_at: datetime) -> None:
async with semaphore:
await runner.fire(schedule_id, due_at=due_at)
for schedule_id, due_at in to_fire:
task = asyncio.create_task(_guarded(schedule_id, due_at))
_FIRING.add(task)
task.add_done_callback(_FIRING.discard)
return len(to_fire)
def _interval() -> float:
with contextlib.suppress(Exception), session_scope() as db:
return float(settings_store.schedules(db).get("tick_seconds") or TICK_SECONDS)
return TICK_SECONDS
async def _loop() -> None:
while True:
try:
await asyncio.sleep(_interval())
await sweep()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001 - the ticker must outlive one bad sweep
log.exception("the schedule ticker raised")
def start() -> None:
"""Begin ticking, once. Idempotent, so a second call in one process is not a
second ticker firing everything twice."""
global _TICKER
if _TICKER is None or _TICKER.done():
_TICKER = asyncio.create_task(_loop())
async def shutdown() -> None:
global _TICKER
if _TICKER is not None:
_TICKER.cancel()
with contextlib.suppress(asyncio.CancelledError, Exception):
await _TICKER
_TICKER = None
for task in list(_FIRING):
task.cancel()
for task in list(_FIRING):
with contextlib.suppress(asyncio.CancelledError, Exception):
await task
_FIRING.clear()
def release_claims() -> int:
"""Clear `claimed_at` on rows whose firing did not survive the last run.
A restart abandons a reply in flight -- that is already true of every
generation here -- so a schedule whose firing was interrupted would
otherwise carry a claim stamp for ever and read as permanently running.
"""
with session_scope() as db:
stuck = list(db.scalars(select(Schedule).where(Schedule.claimed_at.is_not(None))))
for schedule in stuck:
schedule.claimed_at = None
schedule.last_error = "This run was interrupted by a restart."
if stuck:
db.commit()
return len(stuck)