How LoopX Heartbeat Automation Consumes Quota `scheduler_hint` and `ack_hint.cli_args`

The LoopX heartbeat automation extracts scheduler_hint from quota responses to configure the --runtime-profile and appends ack_hint.cli_args to the CLI command, enabling the heartbeat to self-acknowledge and close the control loop.

The heartbeat automation in the huangruiteng/loopx repository dynamically orchestrates agent turns by interpreting scheduling directives from the quota subsystem. By consuming the scheduler_hint and ack_hint.cli_args fields returned by the loopx quota should-run command, the automation ensures each heartbeat adheres to the correct scheduling policy and properly reports its completion to the control plane.

Understanding the Quota Response Structure

When the heartbeat automation queries the quota system, the loopx quota should-run command returns a JSON payload containing two critical fields that drive the next execution turn. The schedulerhint field (corresponding to scheduler_hint in documentation) specifies which scheduler profile should handle the heartbeat, while the ackhint object contains a cliargs array (corresponding to ack_hint.cli_args) that encodes acknowledgment parameters.

These fields originate from the quota subsystem and are processed by the heartbeat prompt builder to construct the final executable command.

Consuming scheduler_hint for Runtime Profiling

The automation uses the schedulerhint value to set the runtime profile for the heartbeat command. In loopx/heartbeat_prompt.py, the build_heartbeat_prompt function extracts payload["schedulerhint"] and injects it as the --runtime-profile argument.

This ensures the heartbeat follows the same scheduling policy as the rest of the agent loop. For example, if the quota system returns "codex_app_heartbeat" as the scheduler hint, the generated command includes --runtime-profile codex_app_heartbeat.

# Excerpt from loopx/heartbeat_prompt.py logic

quota_response = {
    "schedulerhint": "codex_app_heartbeat",
    "ackhint": {
        "cliargs": [
            "--goal-id", "my-heartbeat-goal",
            "--agent-id", "heartbeat-agent",
        ]
    },
}

# Extract scheduler hint for runtime profile

scheduler = quota_response["schedulerhint"]

# Results in: --runtime-profile codex_app_heartbeat

Processing ack_hint.cli_args for Self-Acknowledgment

After setting the runtime profile, the automation processes ackhint.cliargs to enable self-acknowledgment. The heartbeat automation reads payload["ackhint"]["cliargs"] and appends these arguments directly to the generated command line.

This concatenation allows the heartbeat to "close the loop" by embedding goal IDs, agent IDs, and turn instance IDs into its own execution command, ensuring the control plane records the turn as completed.

# Consuming ack_hint.cli_args from quota response

ack_cli = quota_response["ackhint"]["cliargs"]

# Build final heartbeat command

heartbeat_cmd = [
    "loopx", "heartbeat-prompt",
    "--runtime-profile", scheduler,
    *ack_cli,  # Injects: --goal-id my-heartbeat-goal --agent-id heartbeat-agent

]

# Executed as:

# loopx heartbeat-prompt --runtime-profile codex_app_heartbeat \

#   --goal-id my-heartbeat-goal --agent-id heartbeat-agent

The Complete Heartbeat Execution Flow

According to the huangruiteng/loopx source code, the heartbeat automation follows a four-phase execution flow that consumes these quota hints:

1. Generate the heartbeat prompt – The build_heartbeat_prompt function in loopx/heartbeat_prompt.py constructs a packet containing the quota should-run command.
2. Execute the quota command – The CLI runs loopx quota should-run --goal-id <goal>, returning JSON with schedulerhint and ackhint.
3. Consume the hints – The automation extracts schedulerhint for the --runtime-profile argument and concatenates ackhint.cliargs to the command line.
4. Run the heartbeat – The fully-formed command executes via subprocess.run, completing the turn and updating the quota state.

The test suite validates this behavior in tests/test_host_loop_activation.py, which verifies that the activation packet contains the quota command and that the generated CLI includes both the runtime profile and acknowledgment arguments. Additional validation appears in tests/test_heartbeat_prompt.py, confirming that build_heartbeat_prompt returns payloads with properly structured hint processing.

Summary

• The loopx quota should-run command returns JSON containing schedulerhint and ackhint.cliargs fields.
• The heartbeat automation consumes scheduler_hint to set the --runtime-profile argument, ensuring scheduler consistency.
• The ack_hint.cli_args array is appended to the heartbeat command to enable self-acknowledgment and proper turn tracking.
• Implementation resides in loopx/heartbeat_prompt.py with comprehensive test coverage in tests/test_host_loop_activation.py.

Frequently Asked Questions

What does the scheduler_hint field control?

The scheduler_hint field (JSON key schedulerhint) specifies which scheduler profile the heartbeat should use for its next execution turn. The automation maps this value directly to the --runtime-profile CLI argument, ensuring the heartbeat follows the same scheduling policy as the rest of the agent loop.

What information is contained in ack_hint.cli_args?

The ack_hint.cli_args field (JSON path ackhint.cliargs) contains a list of CLI arguments including --goal-id, --agent-id, and --turn-instance-id. These arguments allow the heartbeat command to self-acknowledge its execution, closing the control loop and enabling the control plane to record the turn as completed.

How does build_heartbeat_prompt process these quota hints?

The build_heartbeat_prompt function in loopx/heartbeat_prompt.py constructs the initial heartbeat packet and interprets the quota response. It extracts schedulerhint to configure the runtime profile and reads ackhint.cliargs to append acknowledgment parameters to the final command array.

Where is the hint consumption behavior tested?

The hint consumption logic is validated in tests/test_host_loop_activation.py, which confirms that activation packets include the quota command and that generated commands contain both the runtime profile and CLI arguments. Additional unit tests in tests/test_heartbeat_prompt.py verify the payload construction and hint processing logic.

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