<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11.6-routines-engine -->

# Routines Engine

- landing/zeptoclaw/docs/public/favicon.svg
- landing/zeptoclaw/favicon.svg
- landing/zeptoclaw/mascot-no-bg.png
- src/routines/engine.rs
- src/routines/mod.rs

The Routines Engine provides a flexible automation framework for executing background tasks and event-driven workflows. Unlike the standard `CronService` which focuses on scheduled timing, the Routines Engine supports complex triggers including regex-based message matching, HTTP webhooks, and manual execution, all governed by concurrency and cooldown guardrails.

## System Architecture

The Routines system is built around three core concepts: the `Trigger` (the "when"), the `RoutineAction` (the "what"), and `RoutineGuardrails` (the "safety limits") [src/routines/mod.rs16-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L16-L29)

### Core Components and Code Entities

### Routine Execution Flow

This diagram bridges the gap between the persistent configuration and the runtime execution loop.

```

```

Sources: [src/routines/mod.rs16-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L16-L29) [src/routines/engine.rs35-69](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L35-L69) [src/routines/engine.rs74-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L74-L92) [src/routines/engine.rs115-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L115-L120)

## Trigger Types

The `Trigger` enum defines four distinct ways to initiate a routine [src/routines/mod.rs34-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L34-L55):

1. Cron : Standard cron schedule string (e.g., 0 9 * * * ) src/routines/mod.rs 37 Evaluation is delegated to the caller using get_cron_routines src/routines/engine.rs 106-112
2. Event : Matches incoming messages using a Regex pattern. It can optionally be restricted to a specific channel src/routines/mod.rs 40-45
3. Webhook : Matches an incoming HTTP POST request based on a specific URL path (e.g., /hooks/deploy ) src/routines/mod.rs 48-51
4. Manual : Triggers that are only invoked via explicit CLI or API calls src/routines/mod.rs 54

### Event Matching Implementation

The `RoutineEngine` maintains a cache of `CompiledPattern` objects [src/routines/engine.rs10-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L10-L14) When a message arrives, `check_event_triggers` iterates through these patterns, verifying the `channel_filter` before executing the regex match [src/routines/engine.rs74-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L74-L92)

Sources: [src/routines/mod.rs34-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L34-L55) [src/routines/engine.rs10-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L10-L14) [src/routines/engine.rs74-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L74-L92)

## Action Execution Modes

When a trigger matches, the engine executes one of two `RoutineAction` types [src/routines/mod.rs60-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L60-L67):

- Lightweight : A single LLM call with a provided prompt. This mode does not enter the tool-execution loop, making it token-efficient for simple notifications or summaries src/routines/mod.rs 62-63
- FullJob : Delegates the prompt to the standard AgentLoop . This allows the routine to use tools (filesystem, shell, web search) to complete complex tasks src/routines/mod.rs 65-66

## Guardrails and Concurrency

To prevent infinite loops or resource exhaustion, the system enforces `RoutineGuardrails` [src/routines/mod.rs71-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L71-L78)

### Concurrency Control

The `RoutineEngine` tracks `active_counts` using a `HashMap<String, AtomicU64>` [src/routines/engine.rs23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L23-L23)

- Check : Before execution, can_execute compares the current atomic count against the routine's max_concurrent setting src/routines/engine.rs 115-120
- Lifecycle : The engine provides start_execution and finish_execution methods to increment and decrement these counters safely across threads src/routines/engine.rs 123-138

### Cooldown Persistence

The `RoutineStore` tracks the `last_executed` timestamp for every routine ID [src/routines/mod.rs103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L103-L103) The `check_cooldown` method ensures that the `elapsed()` time since the last run is greater than or equal to the configured `cooldown_secs` [src/routines/mod.rs168-178](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L168-L178)

Sources: [src/routines/mod.rs71-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L71-L78) [src/routines/mod.rs168-178](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L168-L178) [src/routines/engine.rs23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L23-L23) [src/routines/engine.rs115-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L115-L120)

## Data Flow: Webhook to Agent

This diagram illustrates the path of a Webhook trigger from the network layer to the execution logic.

```

```

Sources: [src/routines/mod.rs48-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L48-L51) [src/routines/engine.rs95-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L95-L100) [src/routines/engine.rs115-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/engine.rs#L115-L120) [src/routines/mod.rs181-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L181-L183)

## Persistence and Storage

Routines are persisted via the `RoutineStore`, which manages a JSON file on disk [src/routines/mod.rs97-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L97-L104)

- Initialization : The store loads existing routines from a specified PathBuf upon creation src/routines/mod.rs 108-123
- CRUD Operations : Methods like add , remove , and toggle update the in-memory cache and trigger a save() to synchronize with the filesystem src/routines/mod.rs 136-165
- Timestamp Tracking : The last_executed map is kept in memory to manage cooldowns without requiring disk writes for every execution timestamp src/routines/mod.rs 103

Sources: [src/routines/mod.rs97-123](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L97-L123) [src/routines/mod.rs136-165](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L136-L165) [src/routines/mod.rs181-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/routines/mod.rs#L181-L183)
