# How LoopX Heartbeat Automation Prompt Decides Scheduler Eligibility

> Discover how LoopX heartbeat automation prompts determine scheduler eligibility by checking runtime profiles, execution contexts, and mode settings.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-09-04

---

**The heartbeat automation prompt only attaches scheduler commands when the runtime profile supports scheduler arguments and a valid scheduler execution context is provided, selecting the appropriate hint rule based on whether the heartbeat runs in full, compact, or thin mode.**

LoopX (huangruiteng/loopx) implements a context-aware eligibility system to determine whether a heartbeat command should integrate with a scheduler. This mechanism prevents incompatible hosts from receiving scheduler flags while ensuring that CLI-driven goals and ARK-managed agents receive the correct execution hints.

## The Three Scheduler-Hint Rules Defined in rules.py

The foundation of scheduler eligibility rests on three textual constants defined in [`loopx/control_plane/heartbeat/rules.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/heartbeat/rules.py). These rules are imported by the heartbeat builder at lines 35-37 in [`loopx/control_plane/heartbeat/builder.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/heartbeat/builder.py) to annotate commands with the appropriate scheduler type.

### Full-Feature Scheduler Hint

The `SCHEDULER_HINT_APPLICATION_RULE` constant specifies the hint used for full-feature scheduler integration. This rule applies when the heartbeat operates in **full mode**, indicating that the target environment can handle the complete scheduler feature set including complex orchestration and state management.

### Compact-Mode Scheduler Hint

The `SCHEDULER_HINT_COMPACT_RULE` targets lightweight scheduler deployments. When the heartbeat runs with `compact=True`, this hint signals that the scheduler should operate with reduced overhead while still maintaining core automation capabilities.

### Thin-Mode Scheduler Hint

The `SCHEDULER_HINT_THIN_RULE` supports minimal scheduler footprints. This hint is reserved for **thin mode** executions where the scheduler must function with the smallest possible resource footprint, typically bypassing auxiliary services.

## Runtime Profile Inspection in builder.py

The eligibility decision begins in `build_heartbeat_prompt` within [`loopx/control_plane/heartbeat/builder.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/heartbeat/builder.py). This function receives a `runtime_profile` string and an optional `scheduler_execution_context` dictionary to evaluate whether the current execution context supports scheduler integration.

When the `runtime_profile` equals **`generic_cli`** (the default for CLI-driven goals) and a non-None `scheduler_execution_context` is supplied, the builder marks the run as **scheduler-eligible**. It then invokes `render_scheduler_execution_args` to generate the necessary scheduler arguments.

The system also evaluates eligibility for hosts that natively support scheduler input. If the profile indicates a **native goal host loop** (`uses_native_goal_host_loop`) or an **ARK-managed agent host**, the prompt continues processing because these environments accept scheduler parameters even when operating outside the standard CLI context.

## Hint Selection Logic in execution_context.py

Once eligibility is confirmed, `render_scheduler_execution_args` in [`loopx/control_plane/scheduler/execution_context.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/scheduler/execution_context.py) selects the specific hint to attach. The function inspects the heartbeat mode flags to determine which rule applies:

- **Full heartbeat** (`full=True`): Attaches the **application** hint using `SCHEDULER_HINT_APPLICATION_RULE`
- **Compact heartbeat** (`compact=True`): Uses the **compact** hint via `SCHEDULER_HINT_COMPACT_RULE`  
- **Thin heartbeat** (`thin=True`): Applies the **thin** hint through `SCHEDULER_HINT_THIN_RULE`

This selection mechanism ensures that the generated command line receives the precise scheduler flags appropriate for the execution environment's capabilities and resource constraints.

## Fallback Behavior When Context Is Missing

When `scheduler_execution_context` is None or the runtime profile lacks scheduler support, the heartbeat prompt omits all scheduler-related flags entirely. This behavior is enforced in `build_heartbeat_prompt` and verified in [`tests/control_plane/test_scheduler_fallback_hint.py`](https://github.com/huangruiteng/loopx/blob/main/tests/control_plane/test_scheduler_fallback_hint.py), where assertions confirm that hint strings appear exclusively when the scheduler is truly eligible.

This conservative fallback prevents scheduler commands from being injected into simple CLI calls or incompatible host environments that would fail to interpret the additional flags.

## Practical Code Examples

### Eligible Full Heartbeat with Scheduler

When running a full heartbeat with a valid scheduler context on a CLI profile, the builder attaches the application hint:

```python
payload = build_heartbeat_prompt(
    goal_id="my-goal",
    runtime_profile="generic_cli",
    scheduler_execution_context={"type": "sqlite", "url": "file:///tmp/db"},
    full=True,
)
print(payload["commands"]["heartbeat_prompt"])

# Output includes: "... heartbeat-prompt --full … -H sqlite …"

```

### Ineligible Thin Heartbeat Without Scheduler

A thin heartbeat lacking execution context omits the scheduler flags:

```python
payload = build_heartbeat_prompt(
    goal_id="my-goal",
    runtime_profile="generic_cli",
    thin=True,
    # No scheduler_execution_context supplied

)
print(payload["commands"]["heartbeat_prompt"])

# Output: "... heartbeat-prompt --thin …" (no -H flag)

```

### Eligible Compact Heartbeat on ARK-Managed Host

ARK-managed agents support scheduler integration even in compact mode:

```python
payload = build_heartbeat_prompt(
    goal_id="my-goal",
    runtime_profile="ark_managed_agent",
    scheduler_execution_context={"type": "sqlite"},
    compact=True,
)
print(payload["commands"]["heartbeat_prompt"])

# Output includes: "... heartbeat-prompt --compact … -H sqlite …"

```

## Summary

- **Rule definitions**: [`loopx/control_plane/heartbeat/rules.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/heartbeat/rules.py) declares three constants (`SCHEDULER_HINT_APPLICATION_RULE`, `SCHEDULER_HINT_COMPACT_RULE`, `SCHEDULER_HINT_THIN_RULE`) imported at lines 35-37 of the builder module.
- **Profile validation**: The `build_heartbeat_prompt` function checks for `generic_cli` profiles, native goal host loops, or ARK-managed agents to establish baseline eligibility.
- **Context requirement**: A non-None `scheduler_execution_context` is mandatory for scheduler flag generation.
- **Mode-based selection**: `render_scheduler_execution_args` maps `full`, `compact`, or `thin` flags to their corresponding hint rules in [`loopx/control_plane/scheduler/execution_context.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/scheduler/execution_context.py).
- **Safe fallback**: Missing contexts trigger silent omission of scheduler flags, verified by [`tests/control_plane/test_scheduler_fallback_hint.py`](https://github.com/huangruiteng/loopx/blob/main/tests/control_plane/test_scheduler_fallback_hint.py).

## Frequently Asked Questions

### What runtime profiles allow scheduler eligibility in LoopX?

The `generic_cli` profile (standard for CLI-driven goals) supports scheduler eligibility when combined with a valid execution context. Additionally, profiles indicating `uses_native_goal_host_loop` or `ark_managed_agent` hosts permit scheduler integration because these environments are designed to accept and process scheduler arguments.

### How does LoopX handle missing scheduler execution contexts?

When `scheduler_execution_context` is None, `build_heartbeat_prompt` skips the scheduler argument generation entirely. The resulting heartbeat command contains no `-H` flags or scheduler hints, ensuring that incompatible simple CLI calls remain unmodified and executable without scheduler dependencies.

### What is the difference between the three scheduler hint rules?

`SCHEDULER_HINT_APPLICATION_RULE` provisions the full-feature scheduler with complete orchestration capabilities. `SCHEDULER_HINT_COMPACT_RULE` enables a reduced-footprint mode suitable for resource-constrained environments. `SCHEDULER_HINT_THIN_RULE` activates minimal scheduler functionality for scenarios requiring the lowest possible overhead, as implemented in [`loopx/control_plane/scheduler/execution_context.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/scheduler/execution_context.py).

### Where is the scheduler eligibility logic tested?

The fallback behavior and hint attachment logic are validated in [`tests/control_plane/test_scheduler_fallback_hint.py`](https://github.com/huangruiteng/loopx/blob/main/tests/control_plane/test_scheduler_fallback_hint.py). This test suite asserts that scheduler hints appear only when both the runtime profile and execution context indicate eligibility, confirming that the builder correctly omits flags for ineligible runs.