Time
AEL, the Agent Engineering Language, keeps two kinds of time apart, so that a clock change can never shorten a timeout or make a duration negative.
| Kind | Moves | Use it for |
|---|---|---|
| Monotonic time | Only forward, from a point of its own. | Durations, deadlines, timeouts and timers. |
| Wall-clock time | With the calendar, and can jump when the clock is set. | Timestamps in logs and records, and calendar schedules. |
A duration is always measured with monotonic time. Two wall-clock times are never subtracted to find how long something took.
Reading the time
Reading a clock is an effect, and the compiler tracks it like any other: a function that reads the time says so through everything that calls it, and no helper can hide it. See Effects and capabilities.
Durations
- Durations are whole numbers with checked arithmetic. They are never negative, and an overflow is reported like any other.
- You can express a duration in nanoseconds, but that does not promise nanosecond accuracy: the resolution depends on the target's clock.
- Time measured on one machine is compared only with time from the same clock. Comparing timestamps from different devices needs a stated bound on how far their clocks may differ.
Deadlines and timeouts
- Every request and every call to a model, a service or another program has a finite deadline.
- Child work inherits the earliest deadline of the work that started it. A retry or a restart never extends a deadline.
- When a deadline is reached, the work fails at that point. Nothing waits past it, including the delay before a retry.
- Retries, output repair, timeouts and cancellation draw on one shared budget, so nested retries cannot multiply cost. See Budgets, retries and validation.
Timers
Timers wake a waiting handler after a duration. Concurrency describes how they fit the scheduling model.
- Timers measure monotonic time, and keep working when a hardware counter wraps around to zero.
- You can cancel a timer. A timer that was cancelled or reused can never wake the wait it used to belong to.
- Timers that expire at the same moment run in a defined order.
- On a microcontroller, the number of timers is fixed when you build. Running out of timers is a typed result, not a crash.
Delays on a board
A microcontroller program reads a monotonic clock and uses bounded delays and polling, as part of the hardware access that also covers GPIO, UART and interrupts.
- A delay or a poll that blocks says so, and the compiler tracks it: a real-time path cannot call it.
- Waiting on a timer lets other handlers run; a delay that blocks does not. Prefer timers for anything longer than a short pause.
Schedules
Agents can start on a schedule, on a poll or on an event. Scheduled triggers have:
- intervals, or calendar schedules in a named time zone, with defined behaviour across daylight-saving changes;
- a missed-run policy, with a limit on how many missed runs are caught up;
- an overlap policy for a run that starts while the last one is still going;
- a maximum number of concurrent runs, and pause and resume.
Schedules survive restarts when their agent declares a storage point; see Bindings and storage. Workflows describes triggers. Date and calendar arithmetic beyond schedules is outside this reference.
Time in the time and token summary
The elapsed time of a run, reported by default when it ends, is measured with monotonic time. You choose the unit it is shown in, or turn it off; see Console and logging.
Testing code that uses time
Tests run time-dependent code against a controlled clock that advances only when the test says so: timeouts, schedules across time-zone changes and timer wraparound can be tested without waiting. See Testing.