Autonomous agents and background worker loops frequently rely on scheduled polling or heartbeat loops. In a typical architecture, a cron job or daemon wakes up periodically, inspects an inbox or task queue, and submits context to a large language model to decide what to do next.

When an inbox is completely empty, contains automated health check pings, or receives bursts of duplicate alerts, querying an LLM on every tick wastes money and API quota. Running full model inferences to confirm that there is nothing new to process creates unnecessary network latency and unneeded token spend.

The solution is a deterministic pre-flight check: a zero-token gatekeeper that inspects pending messages, enforces rate limits, evaluates regular expressions, and confirms actionable work exists before triggering your agent's LLM reasoning loop.

Install & Usage

The script is self-contained and relies exclusively on Python standard library modules (argparse, dataclasses, json, pathlib, re, time). It requires Python 3.8 or newer and does not require running pip install for third-party packages.

Save the script file locally as cheap_non_llm_gate_before_agent_heartbeat_pol.py.

You can view the available command-line flags directly:

python cheap_non_llm_gate_before_agent_heartbeat_pol.py --help 

Checking the Built-in Diagnostics and Demo

To verify that the evaluation rules and state management work properly in your environment, run the embedded self-test suite:

python cheap_non_llm_gate_before_agent_heartbeat_pol.py --self-test 

To see how the decision engine handles a mock stream of incoming tasks, cooldown windows, and watchdog timers, run the interactive demo:

python cheap_non_llm_gate_before_agent_heartbeat_pol.py --demo 

Using the Gate in Shell Scripts and Pipelines

The gate relies on conventional process exit codes:

  • 0 (DISPATCH): Actionable work detected or watchdog timer expired. Run the agent.
  • 1 (SUPPRESS): No work detected, messages filtered out, or cooldown active. Skip the agent.
  • 2 (ERROR): Invalid configuration or file access failure.

You can inspect standard input by passing --stdin:

echo "PING" | python cheap_non_llm_gate_before_agent_heartbeat_pol.py --stdin --ignore-regex "^PING$" 

Because PING matches the ignore pattern, the gate exits with status 1.

In a production polling loop, you can gate the agent execution using standard shell flow:

if python cheap_non_llm_gate_before_agent_heartbeat_pol.py \ --inbox-dir ./agent_inbox \ --state-file ~/.cache/agent_gate/state.json \ --min-interval 60.0 \ --max-idle 3600.0 \ --ignore-regex "^PING$" \ --ignore-regex "^healthz"; then echo "Actionable work found. Triggering LLM reasoning loop..." python run_llm_agent.py else echo "Heartbeat suppressed by pre-flight gate." fi 

If you need programmatic integration with orchestration engines, add --json to output structured metadata:

python cheap_non_llm_gate_before_agent_heartbeat_pol.py --inbox-dir ./agent_inbox --json 

How It Works

The gate evaluates incoming candidates against three core stages: message filtering, rate-limiting cooldowns, and a maximum idle watchdog.

1. Filtering Noise with Byte Checks and Regex

Before any schedule or timer logic runs, the gate evaluates each payload string in _filter_candidate. Items that are too small or match ignore patterns are discarded:

def _filter_candidate(self, text: str) -> Tuple[bool, str]: stripped = text.strip() if len(stripped.encode("utf-8")) < self.min_payload_bytes: return False, f"Payload below min size ({self.min_payload_bytes} bytes)" for pattern in self.ignore_res: if pattern.search(stripped): return False, f"Matched ignore pattern: '{pattern.pattern}'" if self.require_res: matched = any(p.search(stripped) for p in self.require_res) if not matched: return False, "Failed to match any required pattern" return True, "Valid actionable work" 

If you supply --require-regex, an event must match at least one required pattern to be retained. If no patterns are matched or if an item matches an --ignore-regex, it is moved to the suppressed list.

2. Evaluating Timing and State

Once messages are classified into actionable or suppressed groups, NonLLMGate.evaluate() checks persistent gate history stored in GateState:

# Check 1: Watchdog max idle elapsed (only triggers after an initial dispatch) if ( self.max_idle > 0.0 and state.last_dispatch_ts > 0.0 and elapsed_since_dispatch >= self.max_idle ): dispatch = True decision_reason = ( f"Watchdog trigger: max idle window ({self.max_idle:.1f}s) exceeded" ) # Check 2: Cooldown violation elif actionable and cooldown_remaining > 0.0: dispatch = False decision_reason = ( f"Rate-limiting cooldown: {cooldown_remaining:.1f}s remaining" ) # Check 3: Actionable items ready elif actionable: dispatch = True decision_reason = f"Actionable items detected ({len(actionable)} items)" # Check 4: No actionable items else: dispatch = False decision_reason = "No actionable events or all filtered out" 
  1. Watchdog Check: If an agent has previously run (state.last_dispatch_ts > 0.0) and the time since the last dispatch exceeds --max-idle, the gate authorizes dispatch even if the inbox is empty. This prevents agents from going completely silent during quiet periods.
  2. Cooldown Check: If actionable work arrives, but the elapsed time since the last run is less than --min-interval, dispatch is suppressed to prevent downstream agent thrashing.
  3. Actionable Work Check: If actionable work is ready and the cooldown window has elapsed, the gate dispatches (exit code 0).
  4. Empty Check: If no valid events remain, the gate suppresses execution (exit code 1).

3. Safe State Updates

State is stored on disk in JSON format and written atomically using a temporary file (temp_file.replace(path)) to avoid corrupting the file if an evaluation is aborted mid-write.

Limitations

When integrating this script into production systems, keep the following design limitations in mind:

  • Watchdog Cold-Start Behavior: In the implementation, the watchdog condition explicitly checks state.last_dispatch_ts > 0.0. If a state file is newly created and the agent has never dispatched an initial run, the watchdog timer will not trigger on an empty inbox until at least one event triggers a dispatch.
  • No Queue Ingestion or Deletion: The function scan_inbox() only reads file contents from the specified directory. It does not delete, move, or archive files after evaluation. The calling script or downstream agent must handle moving or deleting processed files to prevent the gate from re-reading the same files on subsequent runs.
  • Unused Hash State: While GateState includes a known_content_hash field, the core evaluate() method does not compute or compare content hashes across cycles. Duplicate detection must be handled via regex or file management outside the gate.
  • Deterministic Heuristics Only: The gate evaluates regex, payload byte lengths, and timing constraints. It cannot perform semantic deduplication or interpret natural language intent.

FAQ

Does this script make any outbound network connections?

No. The script runs entirely offline on the local system, inspecting local files, timestamps, and standard input.

How does the gate estimate dollar savings?

The gate multiplies the total number of suppressed evaluations (total_suppressed) by the value provided in --cost-per-llm-call (defaulting to $0.015). This is an informational counter saved to the state file and included in JSON reports.

What happens if multiple tasks are found in the inbox during a cooldown period?

If actionable tasks are present while the cooldown timer is active, the gate rejects execution, reports the remaining cooldown seconds, and increments total_suppressed. The inbox files remain in place until the cooldown expires and the next evaluation allows dispatch.

Full version and the rest of the toolkit: Cheap non LLM gate before agent heartbeat pol on PyForge. Product page: https://py-forge.com/products/cheap-non-llm-gate-before-agent-heartbeat-pol