The same numbers for agents

A small local file and a command let an agent check headroom before it picks an account or waits.

The widget is for me, but a lot of my work is now done by agents and scripts that start their own sessions, and they hit the same limits I do. They have no way to glance at a dial, so they were choosing an account without knowing how much was left on it.

The fix was to give them the same numbers I see, in a form they can read without help.

A file and a command

After each refresh, Monizard writes a small file in my home folder. It holds the short window and the week for each plan and account, along with when each one resets. It does not contain any secrets, and it is readable only by the person who owns it.

Reading JSON by hand is tedious, so there is also a command, monizard-usage. It prints one line per plan or account. Run with --json, it prints the file as it is.

The point of both is that an agent does not need to call any provider itself. Those services slow down callers that ask too often, and Monizard already knows how to back off. Reading a local file puts no load on those services.

Figure 1 follows one reading from the plan to the agent. Only the widget talks to the providers; everything below it reads what the widget wrote.

Figure 1Where an agent's numbers come from. The dashed line is a script that reads the file itself.

The command has a few forms. Each one answers a slightly different question, so an agent can ask only for what it needs.

The forms of `monizard-usage` and when each is useful.
Command	What it prints	Useful when
`monizard-usage`	One line per plan or account: the short window, the week and when each resets.	A person or a log wants a quick summary.
`--json`	The file as it is.	A program wants every field and will decide for itself.
`--recommend`	Where work can go, freest first, with a reason for each entry and the ones to avoid.	An agent wants advice it can explain.
`--pick account`	Exactly one name.	An agent only needs to know which account to start on.

Advice, not instructions

Raw percentages still leave the agent to work out what they mean. So monizard-usage --recommend ranks where work can go, freest first, with a short reason for each entry. It also lists the ones to avoid, such as an account that is nearly full or has an error.

Here is a made-up exchange to show the shape of it. The names and numbers are illustrative and do not come from real use.

Example

agent: which account should this long job use?
$ monizard-usage --recommend
account-b  5h 22%  7d 41%  under pace  pick
account-a  5h 91%  7d 70%  over pace   avoid: 5h nearly full

$ monizard-usage --pick account
account-b

An agent that reads this can start its task on account-b and leave account-a to recover. If the pick finds no account with headroom, it says so, and waiting is the sensible choice.

Figure 2Picks spread by headroom instead of all landing on the top entry. The split is an example, not a promise.

If an agent only wants a name, monizard-usage --pick account prints exactly one. The pick is weighted by headroom rather than only ever taking the top entry, so several agents that start at the same moment do not pile onto the same account.

Without the weighting, every agent would read the same ranking and choose the same first line, and the freest account would fill up first, all at once.

Knowing when the numbers are old

Each entry carries a stale flag, and the file records when it was last written, so a reader can tell that Monizard has stopped running.

When an entry is marked stale. In every case a careful reader treats it as unknown.
The entry is stale when	Why that matters
It has no data	The plan could not be read at all, so there is no number to trust.
It has not been refreshed recently	Use may have moved a long way since the reading was taken.
A reset has passed since it was taken	The window has started again, so the old figure is too high.

I added this because an old number is worse than no number. A script that trusts a reading from two hours ago may walk into a limit that the widget would have shown in red. With the flag, the agent can treat a stale entry as unknown and choose more carefully.

Monizard sees usage and does not see tasks, so the advice stays advice. The agent, or the person running it, makes the choice.

It cannot know that one job matters more than another, and it does not try to.

Several machines

Monizard can also share its readings between my machines, so a machine that cannot read an account itself can still show it, marked as copied from elsewhere. Copied readings are marked as such in the agent-facing file.

This is something I use every day on my own setup. I wanted to describe the idea because I think it applies beyond my machines: any tool that makes a decision about spending a limited allowance should be able to look at a gauge first.