How LoopX Heartbeat Automation Prompt Decides Scheduler Eligibility

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. These rules are imported by the heartbeat builder at lines 35-37 in 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. 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 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, 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:

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:

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:

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 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.
• Safe fallback: Missing contexts trigger silent omission of scheduler flags, verified by 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.

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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}