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

> Understand how LoopX heartbeat automation uses scheduler_hint and ack_hint.cli_args to configure runtime profiles and self-acknowledge commands, optimizing the control loop.

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

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`.

```python

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

```python

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/heartbeat_prompt.py) with comprehensive test coverage in [`tests/test_host_loop_activation.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/tests/test_heartbeat_prompt.py) verify the payload construction and hint processing logic.