Chronos

Chronos is the temporal substrate of the Agent OS. Every autonomous agent must answer two fundamental questions: when should I wake? and what should I do when I wake? Chronos answers the first question completely, and introduces the agenda primitive (in M1) that begins to answer the second.

The name comes from the Greek god of time — not the Titan Kronos, but the philosophical personification of linear, sequential time that flows forward and cannot be reversed.

Biological analogy

Chronos corresponds to the circadian rhythm / autonomic nervous system clock in biological systems. The circadian clock doesn't run behavior — it gates behavior by signaling when conditions are right for different kinds of activity. Chronos does the same thing for agents: it coalesces heterogeneous temporal signals from the environment (HTTP calls, file changes, sub-agent completions, heartbeats) into a single ordered wake stream that the kernel can consume without caring about the source.

Just as an organism's internal clock integrates light, temperature, and metabolic signals, WakeRouter integrates multiple WakeTrigger implementations into one stream. The kernel sees a uniform WakeEvent regardless of whether the wake came from a webhook or a heartbeat.

Architecture

Chronos is structured as four crates with strict dependency discipline:

Core types

WakeEvent

The universal envelope for every temporal signal the kernel receives:

pub struct WakeEvent {
    pub id: Ulid,
    pub timestamp: SystemTime,
    pub source: WakeSource,
    pub payload: WakePayload,
    pub target_session: Option<SessionId>,
}

Every trigger produces a WakeEvent. The kernel consumes WakeEvent values from the stream without needing to know which trigger produced them. target_session is set when a wake event is addressed to a specific running session (for example, a SubAgentReturn knows which parent session to resume).

WakeSource

The taxonomy of all possible wake origins:

pub enum WakeSource {
    Heartbeat,       // Regular interval ticks — real in M0
    Http,            // Inbound HTTP /runs call — stubbed, real in M1
    Cron,            // Cron schedule expression — stubbed, real in M2+
    FsWatch,         // File system change — stubbed, real in M3
    SubAgentReturn,  // Sub-agent completed — stubbed, real in M3
    Threshold,       // Metric crossed a threshold — stubbed, beyond M3
    Webhook,         // External webhook delivery — stubbed, beyond M3
}

WakeTrigger

The async trait every trigger backend implements:

pub trait WakeTrigger: Send + Sync {
    fn source(&self) -> WakeSource;
    fn stream(&self) -> Pin<Box<dyn Stream<Item = WakeEvent> + Send>>;
}

A trigger is responsible for producing an infinite stream of WakeEvent values. The WakeRouter merges streams from all registered triggers into one ordered output.

WakeRouter

The multiplexer that coalesces all trigger streams:

let mut router = WakeRouter::new();
router.register(HeartbeatTrigger::new(Duration::from_secs(30)));
// future: router.register(HttpTrigger::new(api_config));
// future: router.register(CronTrigger::new("0 * * * *"));

let mut wake_stream = router.run();
while let Some(event) = wake_stream.next().await {
    kernel.wake(event).await?;
}

WakeRouter::run() spawns each trigger concurrently and selects across them with fair scheduling. A failing trigger logs the error and is dropped from the set without taking down the router.

How it works

Milestone roadmap

Relation to other subsystems

Test coverage

At M0 ship: 15 Chronos-specific tests covering HeartbeatTrigger timing, WakeRouter concurrent multiplexing, SIGTERM shutdown sequence, and WakeEvent serialization round-trips. 315 regression tests across the full workspace remained green.