Houmeres/LLeMbas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 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/rule.py
+506
View File
@@ -0,0 +1,506 @@
"""When a schedule next comes due.
Pure and total. Nothing here opens a session, reads the wall clock or raises:
every function takes what it needs and answers, so the whole of this module can
be tested exhaustively before anything calls it. That is deliberate, because
everything downstream fails *quietly* -- a schedule that never fires looks
exactly like a working one on the list page, and a schedule that fires an hour
out looks like nothing at all until somebody notices the report is late.
## The shape
Plain cron cannot say "ten minutes from now, five times", so the rule is a dict
with two independent generators and a bound:
{
"start": "2026-08-05T14:30:00Z", # first candidate instant, UTC
"every": {"minutes": 10}, # a stride
"at": {"weekdays": [0], # 0 = Monday
"days": [1, 15], # day of the month
"months": [1, 4, 7, 10],
"times": ["15:00"]}, # wall-clock, in the owner's zone
"count": 5, # total firings, 0 = unbounded
"until": "2026-12-31T00:00:00Z" # last instant, "" = unbounded
}
`every` and `at` compose, and the four combinations are the whole vocabulary:
every at meaning
----- ---- ------------------------------------------------------------
- - fire once, at `start`
x - a timer: start, start + every, start + 2*every, ...
- x a calendar: every matching wall-clock moment after `start`
x x a calendar with a stride: matching moments, every Nth kept
## Timezone, and why the two halves differ
`at.times` are **wall-clock** in the owner's zone: 15:00 stays 15:00 across a
DST change, because that is what "every Monday at 3PM" means to the person who
said it. `every` durations are **elapsed real time**: ten minutes is ten
minutes, and a six-hourly timer must not skip or double on a 23- or 25-hour day.
Those are different meanings, not an inconsistency, and conflating them is how
one of the two comes out wrong twice a year.
A wall-clock time that does not exist (the hour skipped on a spring-forward day)
fires at the first instant that does, rather than being skipped -- a daily report
vanishing once a year is precisely the silent failure this file exists to avoid.
One that occurs twice on a fall-back day fires on the first, once.
## Not expressible
Said plainly, because the gap is the point: "the last Friday of the month", "the
third Monday", "weekdays except holidays", "the Nth business day", sub-minute
intervals, sunrise-relative times, and any conditional firing ("only if the
build is red"). The first two are what people will actually ask for; the rule is
JSON, so an `nth` key inside `at` adds them later with no migration.
"""
from __future__ import annotations
import logging
from datetime import UTC, datetime, timedelta, tzinfo
log = logging.getLogger(__name__)
# The stride units, and how many seconds each is worth. Months are absent on
# purpose: a month is not a duration, and "every month" is `at: {days: [n]}`,
# which is what somebody means by it.
UNITS: dict[str, int] = {
"minutes": 60,
"hours": 3600,
"days": 86400,
"weeks": 604800,
}
# Bounds. Every one of these is a clamp rather than a rejection, because the
# rule can arrive from a *model* -- the compile step's output is model output
# that becomes a timer, and `validate` is this feature's `nh3.clean`.
MIN_INTERVAL_SECONDS = 60
MAX_INTERVAL_SECONDS = 366 * 86400
MAX_COUNT = 10_000
MAX_TIMES = 24
MAX_HORIZON_DAYS = 366 * 5
# How far ahead a calendar search will walk before giving up. A rule asking for
# 31 February matches nothing, and a search with no bound would spin for ever
# inside the ticker. Days rather than iterations, so the limit is a statement
# about the schedule rather than about the loop.
SEARCH_DAYS = 366 * 4
WEEKDAYS = (0, 1, 2, 3, 4, 5, 6)
# --- Reading a rule ------------------------------------------------------------
def _int(value: object, *, low: int, high: int, default: int = 0) -> int:
try:
number = int(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return default
return max(low, min(number, high))
def _stamp(value: object) -> datetime | None:
"""An ISO instant, or None. Naive input is read as UTC.
`fromisoformat` handles a trailing Z from Python 3.11, but a model writes
all sorts of things, so anything unparseable is simply absent.
"""
if isinstance(value, datetime):
return value if value.tzinfo else value.replace(tzinfo=UTC)
if not isinstance(value, str) or not value.strip():
return None
try:
parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
except ValueError:
return None
return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
def _times(value: object) -> list[tuple[int, int]]:
"""Wall-clock times as (hour, minute), sorted and deduplicated.
Accepts "15:00", "15:00:30" and "9:5", because a model writes all three, and
a rule refused for its punctuation is a round trip spent on nothing.
"""
if isinstance(value, str):
value = [value]
if not isinstance(value, (list, tuple)):
return []
found: set[tuple[int, int]] = set()
for item in list(value)[:MAX_TIMES]:
if not isinstance(item, str) or ":" not in item:
continue
hour, _, rest = item.strip().partition(":")
minute = rest.partition(":")[0]
try:
pair = (int(hour), int(minute))
except ValueError:
continue
if 0 <= pair[0] <= 23 and 0 <= pair[1] <= 59:
found.add(pair)
return sorted(found)
def _numbers(value: object, *, low: int, high: int) -> list[int]:
if isinstance(value, int) and not isinstance(value, bool):
value = [value]
if not isinstance(value, (list, tuple)):
return []
found: set[int] = set()
for item in value:
if isinstance(item, bool):
continue
try:
number = int(item) # type: ignore[arg-type]
except (TypeError, ValueError):
continue
if low <= number <= high:
found.add(number)
return sorted(found)
def _every(value: object) -> dict[str, int]:
"""A stride, clamped to something that can actually be run.
An interval under a minute is refused rather than clamped to a minute: the
ticker's own granularity is coarser than that, so honouring it is impossible
and pretending to would be a schedule that silently runs late for ever.
Clamped up, because "every 10 seconds" from a model means "often", and often
is a minute.
"""
if not isinstance(value, dict):
return {}
seconds = 0
for unit, size in UNITS.items():
seconds += _int(value.get(unit), low=0, high=MAX_INTERVAL_SECONDS) * size
if seconds <= 0:
return {}
seconds = max(MIN_INTERVAL_SECONDS, min(seconds, MAX_INTERVAL_SECONDS))
return {"minutes": seconds // 60}
def validate(rule: object) -> dict:
"""Normalise a rule, or return {} for one that cannot be made sense of.
**Total on purpose.** The compile step hands this whatever a model wrote, so
it drops what it does not recognise and clamps what it does, and never
raises. `{}` is the honest answer for prose, for a cron string, for an empty
object -- and the caller's job is then to show the manual form rather than
write a schedule that never fires. A schedule that can never fire is
indistinguishable from a working one on every screen it appears on, which is
this feature's flagship silent failure.
The invariant worth holding on to, and pinned in the tests: **anything this
returns non-empty has a computable next occurrence.**
"""
if not isinstance(rule, dict):
return {}
every = _every(rule.get("every"))
raw_at = rule.get("at") if isinstance(rule.get("at"), dict) else {}
at = {
"weekdays": _numbers(raw_at.get("weekdays"), low=0, high=6),
"days": _numbers(raw_at.get("days"), low=1, high=31),
"months": _numbers(raw_at.get("months"), low=1, high=12),
"times": [f"{hour:02d}:{minute:02d}" for hour, minute in _times(raw_at.get("times"))],
}
# A calendar with no time of day has no time of day. Midnight is the only
# defensible reading and it is what every cron-like thing does, so it is
# filled in rather than making the whole `at` block meaningless.
if any(at[key] for key in ("weekdays", "days", "months")) and not at["times"]:
at["times"] = ["00:00"]
if not at["times"]:
at = {}
start = _stamp(rule.get("start"))
until = _stamp(rule.get("until"))
count = _int(rule.get("count"), low=0, high=MAX_COUNT)
# A one-shot is `start` and nothing else, so without a start there is
# nothing to fire and nothing to infer -- unlike a calendar, which is
# perfectly meaningful from now onwards.
if not every and not at and start is None:
return {}
# A window that closes before it opens produces nothing, which is a rule
# that cannot fire rather than one that fires oddly.
if start is not None and until is not None and until < start:
return {}
normalised: dict = {}
if start is not None:
normalised["start"] = start.astimezone(UTC).isoformat()
if every:
normalised["every"] = every
if at:
normalised["at"] = {key: value for key, value in at.items() if value}
normalised["at"]["times"] = at["times"]
if count:
normalised["count"] = count
if until is not None:
normalised["until"] = until.astimezone(UTC).isoformat()
return normalised
# --- When it next comes due -----------------------------------------------------
def _interval(rule: dict) -> timedelta:
return timedelta(minutes=int((rule.get("every") or {}).get("minutes") or 0))
def _matches(moment: datetime, at: dict) -> bool:
"""Whether a local date satisfies the calendar constraints.
Empty means "every", per field, which is what makes `{"times": ["09:00"]}`
read as "daily at nine" without having to enumerate seven weekdays.
"""
weekdays = at.get("weekdays") or []
days = at.get("days") or []
months = at.get("months") or []
if weekdays and moment.weekday() not in weekdays:
return False
if days and moment.day not in days:
return False
return not (months and moment.month not in months)
def _wall(day: datetime, hour: int, minute: int, zone: tzinfo) -> datetime:
"""A wall-clock time on a given local day, as an instant.
Two DST cases, both handled here rather than left to `zoneinfo`'s defaults:
- **The hour that does not exist.** On a spring-forward day, 02:30 is not a
time. Constructing it anyway yields something that does not round-trip, so
the gap is detected by comparing and the result is pushed to the first
instant that does exist. Skipping the day instead is how a daily report
disappears once a year.
- **The hour that happens twice.** `fold=0` picks the first, and the
advance-past-the-last-fire rule upstream is what stops the second being
taken as a separate occurrence.
"""
naive = day.replace(hour=hour, minute=minute, second=0, microsecond=0, tzinfo=None)
local = naive.replace(tzinfo=zone, fold=0)
# A time inside the spring-forward gap does not survive the round trip.
if local.astimezone(UTC).astimezone(zone).replace(tzinfo=None) != naive:
# Walk forward a minute at a time to the far side of the gap. Gaps are
# an hour at most in every zone the database has ever carried, so this
# is bounded and cheap; adding the offset difference directly would
# assume the size of a gap this code has no business knowing.
for extra in range(1, 181):
candidate = (naive + timedelta(minutes=extra)).replace(tzinfo=zone, fold=0)
round_trip = candidate.astimezone(UTC).astimezone(zone).replace(tzinfo=None)
if round_trip == naive + timedelta(minutes=extra):
return candidate.astimezone(UTC)
return local.astimezone(UTC)
def _calendar_after(rule: dict, after: datetime, *, zone: tzinfo) -> datetime | None:
"""The first calendar occurrence strictly after `after`."""
at = rule.get("at") or {}
times = [tuple(int(part) for part in value.split(":")) for value in at.get("times") or []]
if not times:
return None
local = after.astimezone(zone)
day = local.replace(hour=0, minute=0, second=0, microsecond=0)
for _ in range(SEARCH_DAYS):
if _matches(day, at):
for hour, minute in times:
moment = _wall(day, hour, minute, zone)
if moment > after:
return moment
day += timedelta(days=1)
# Re-anchor to local midnight: adding a day across a DST boundary
# otherwise leaves the cursor an hour either side of it, and the day
# after a fall-back would be searched from 23:00 the previous evening.
day = day.astimezone(zone).replace(hour=0, minute=0, second=0, microsecond=0)
return None
def _exhausted(rule: dict, moment: datetime, fired: int) -> bool:
count = int(rule.get("count") or 0)
if count and fired >= count:
return True
until = _stamp(rule.get("until"))
return bool(until and moment > until)
def next_after(
rule: dict, after: datetime, *, zone: tzinfo, fired: int = 0
) -> datetime | None:
"""The next instant this rule comes due, strictly after `after`.
`None` means never again: the count is spent, the window has closed, or the
calendar matches nothing inside the search horizon. A caller seeing `None`
disables the schedule -- exhaustion switches off, it does not loop.
`fired` is how many times it has already run, and is what makes `count`
work without the rule having to carry mutable state.
"""
if not isinstance(rule, dict) or not rule:
return None
count = int(rule.get("count") or 0)
if count and fired >= count:
return None
after = after.astimezone(UTC)
start = _stamp(rule.get("start"))
every = _interval(rule)
at = rule.get("at") or {}
moment: datetime | None
if at:
# A calendar never fires before its start, so the search begins at
# whichever of the two is later.
floor = max(after, start - timedelta(microseconds=1)) if start else after
moment = _calendar_after(rule, floor, zone=zone)
if moment is not None and every:
# A stride over a calendar keeps every Nth match. Counted from the
# start rather than from `after`, so "every other Monday" means the
# same two Mondays whenever it is asked.
stride = max(1, int(round(every.total_seconds() / 86400)) or 1)
if stride > 1 and start is not None:
elapsed = (moment.astimezone(zone).date() - start.astimezone(zone).date()).days
skipped = 0
while elapsed % stride and skipped < SEARCH_DAYS:
moment = _calendar_after(rule, moment, zone=zone)
if moment is None:
break
elapsed = (
moment.astimezone(zone).date() - start.astimezone(zone).date()
).days
skipped += 1
elif every:
if start is None:
return None
if after < start:
moment = start
else:
# Absolute arithmetic, deliberately: a timer measures elapsed time,
# so it must not shift when the offset does. Computed rather than
# stepped, so a schedule idle for a year costs one division.
elapsed = (after - start).total_seconds()
steps = int(elapsed // every.total_seconds()) + 1
moment = start + every * steps
else:
# A one-shot. Due exactly once, and only if it has not already run --
# `fired` is what stops it being re-offered for ever once its moment has
# passed, since `start > after` is false from then on.
if start is None or fired:
return None
moment = start if start > after else None
if moment is None or _exhausted(rule, moment, fired):
return None
return moment
def advance(
rule: dict, *, after: datetime, now: datetime, zone: tzinfo, fired: int = 0
) -> tuple[bool, datetime | None]:
"""Catch up on a schedule whose time passed while nothing was running.
Answers two things at once: whether it is owed a firing *now*, and when it
should next come due. The pair is one function because the second depends on
the first -- a caller that asked separately would have to decide what
"next" means for a schedule it has just decided to fire.
**A missed run collapses to one.** The next occurrence returned is the first
one strictly after `now`, not the one after the slot that was missed -- so a
host switched off for a week comes back owing one report rather than a
hundred and sixty-eight. That is the whole reason this is not just
`next_after`.
It is called from the *sweep* rather than only at startup, because a
suspended laptop, a paused container and a long stall all reproduce the
same situation with no restart to hang a startup hook on.
"""
due = next_after(rule, after, zone=zone, fired=fired)
if due is None:
return False, None
if due > now:
return False, due
# Overdue. Fire once, and resume from wherever the rule is now -- counting
# this firing, so `count` is spent by what actually ran.
return True, next_after(rule, now, zone=zone, fired=fired + 1)
# --- Saying it back -------------------------------------------------------------
_DAY_NAMES = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
_MONTH_NAMES = (
"January", "February", "March", "April", "May", "June",
"July", "August", "September", "October", "November", "December",
)
def _join(words: list[str]) -> str:
if len(words) <= 1:
return "".join(words)
return f"{', '.join(words[:-1])} and {words[-1]}"
def _ordinal(number: int) -> str:
if 10 <= number % 100 <= 20:
return f"{number}th"
return f"{number}{ {1: 'st', 2: 'nd', 3: 'rd'}.get(number % 10, 'th') }"
def _duration(delta: timedelta) -> str:
minutes = int(delta.total_seconds() // 60)
for size, unit in ((10080, "week"), (1440, "day"), (60, "hour"), (1, "minute")):
if minutes >= size and not minutes % size:
amount = minutes // size
return f"{amount} {unit}{'s' if amount != 1 else ''}"
return f"{minutes} minute{'s' if minutes != 1 else ''}"
def describe(rule: dict, *, zone: tzinfo) -> str:
"""One line saying what this rule does, in the reader's own zone.
Not decoration. It is what the setup screen echoes back before anything is
saved, what the list page shows beside each schedule, and what the harness
tells a model about its own chat. A row reading "Every Monday at 3PM" over a
rule that fires daily is the same class of failure as three places
disagreeing about a tool's name -- and this one is the reader's only view of
a decision that happens while they are not looking.
"""
rule = rule or {}
if not rule:
return "Never"
at = rule.get("at") or {}
every = _interval(rule)
parts: list[str] = []
if at:
times = _join(list(at.get("times") or []))
when = []
if at.get("weekdays"):
when.append(_join([_DAY_NAMES[day] for day in at["weekdays"]]))
if at.get("days"):
when.append(f"the {_join([_ordinal(day) for day in at['days']])}")
if at.get("months"):
when.append(f"of {_join([_MONTH_NAMES[month - 1] for month in at['months']])}")
parts.append(
f"Every {' '.join(when)} at {times}" if when else f"Every day at {times}"
)
# A stride over a calendar is a qualifier rather than a rewording:
# "Every Monday at 15:00, skipping to every 14 days" is clumsy but true,
# and inventing "every other Monday" for it would be a phrase that stops
# being true the moment the stride is not two.
stride_days = int(every.total_seconds() // 86400) if every else 0
if stride_days > 1:
parts.append(f"but only every {stride_days} days")
elif every:
parts.append(f"Every {_duration(every)}")
else:
start = _stamp(rule.get("start"))
local = start.astimezone(zone) if start else None
return f"Once, on {local.strftime('%-d %B %Y at %H:%M')}" if local else "Once"
count = int(rule.get("count") or 0)
if count:
parts.append(f"{count} time{'s' if count != 1 else ''}")
until = _stamp(rule.get("until"))
if until:
parts.append(f"until {until.astimezone(zone).strftime('%-d %B %Y')}")
return ", ".join(parts)