LoopX Quota Should‑Run Contract: How Agent Eligibility Is Determined

The LoopX quota should‑run contract is the decision routine that evaluates whether an autonomous agent turn may execute based on current quota state, analyzing compute limits, health severity, operator gates, and slot consumption in loopx/quota.py.

The LoopX framework governs autonomous agent execution through a sophisticated quota system. The quota should‑run contract serves as the definitive gatekeeper that determines agent eligibility before each turn, implemented primarily in the loopx/quota.py module according to the huangruiteng/loopx source code.

What Is the Should‑Run Contract?

The should‑run contract is a specific decision mode within the generic quota planning logic. When you invoke the CLI command:

loopx quota should-run --goal-id <goal>

The request forwards to loopx/quota.py, which executes build_quota_plan(..., mode="should-run"). This mode evaluates whether current conditions permit an automatic agent turn to proceed, returning a structured payload that includes a state field and a human‑readable reason.

How Agent Eligibility Is Determined

The eligibility check follows a five‑step pipeline:

1. Collects the latest status payload for the requested goal, including attention items, project assets, and recent runs.
2. Builds a quota plan by calling build_quota_plan with mode set to should-run. Inside this planner, the function _quota_plan_goal_quota (lines 438‑478 in loopx/quota.py) assembles the quota object for the goal.
3. Derives the quota state via quota_status (lines 72‑85), which evaluates a strict hierarchy of blocking conditions.
4. Applies hand‑off outcome floor logic through quota_with_handoff_outcome_floor (lines 4‑27), which may impose additional focus_wait states.
5. Returns the quota payload to the CLI, where the state field determines execution rights.

The Evaluation Hierarchy in quota_status

The quota_status function evaluates conditions in the following order of precedence:

• Compute quota — If compute ≤ 0, the state becomes paused.
• Health severity — If severity == "high", the state becomes blocked_health.
• Operator gate — If waiting_on indicates a controller or user gate, the state becomes operator_gate.
• External evidence — When waiting_on == "external_evidence", the state becomes waiting.
• Focus‑wait — If the goal waits on the Codex and lifecycle markers contain a focus‑wait flag, the state becomes focus_wait.
• Quota throttling — When waiting_on == "codex", the routine compares allowed slots versus spent slots:
  • If spent_slots ≥ allowed_slots → throttled.
  • Otherwise → eligible.
• Fallback — Any other situation defaults to waiting ("no active Codex‑ready work").

The resulting quota object includes a state field (e.g., eligible, throttled, focus_wait) and a reason field explaining the decision (lines 86‑119).

Quota States and Their Meanings

State	Condition	Meaning
eligible	waiting_on == "codex" and slots remain	Agent may run an automatic turn.
throttled	spent_slots ≥ allowed_slots	Quota slots exhausted for the current window.
paused	compute ≤ 0	No compute quota remains; all automatic turns paused.
blocked_health	severity == "high"	Health or contract blocker prevents spending compute.
operator_gate	waiting_on is user_or_controller or controller	Operator gate blocks gated delivery; read‑only work may continue.
waiting	waiting_on == "external_evidence" or fallback	External evidence pending or no Codex‑ready work selected.
focus_wait	Focus‑wait marker present or hand‑off floor not met	Delivery paused awaiting new evidence or novelty.

Hand‑Off Outcome Floor Logic

Before finalizing the decision, the system applies quota_with_handoff_outcome_floor (lines 4‑27). If the hand‑off outcome floor has not been met, this logic can override the state to focus_wait with a detailed reason, ensuring agents do not proceed until substantive progress thresholds are satisfied.

Code Examples

The following examples demonstrate how quota_status evaluates different scenarios:

from loopx.quota import quota_status

# Example: Eligible goal with available compute and slots

goal = {
    "id": "example-goal",
    "quota": {"compute": 1.0, "allowed_slots": 5, "spent_slots": 3},
}
print(quota_status(goal))

Output shows the eligible state:

{'compute': 1.0, 'window_hours': 24, 'slot_minutes': 1,
 'allowed_slots': 5, 'spent_slots': 3,
 'state': 'eligible',
 'reason': '1 compute quota; eligible for the next automatic agent turn'}

# Example: Throttled because slots are exhausted

goal["quota"]["spent_slots"] = 5
print(quota_status(goal))

Output:

{'state': 'throttled',
 'reason': '1 compute quota spent 5/5 slots in this window'}

# Example: Operator gate blocks delivery

print(quota_status(goal, waiting_on="controller"))

Output:

{'state': 'operator_gate',
 'reason': 'operator gate blocks gated delivery; safe non‑gated steering may continue'}

Key Files in the Implementation

• loopx/quota.py — Core quota‑state computation (quota_status, _quota_plan_goal_quota, quota_with_handoff_outcome_floor).
• loopx/cli_commands/quota.py — CLI wrapper mapping loopx quota should-run to the planning logic.
• tests/test_turn_envelope.py — Verifies should‑run behavior across states.
• loopx/presentation/renderers/quota_markdown.py — Renders quota decisions for CLI output.

Summary

• The LoopX quota should‑run contract determines agent eligibility through build_quota_plan(..., mode="should-run") in loopx/quota.py.
• Eligibility hierarchy evaluates compute, health, operator gates, external evidence, focus‑wait markers, and slot consumption in strict order.
• Quota states include eligible, throttled, paused, blocked_health, operator_gate, waiting, and focus_wait.
• Hand‑off outcome floor logic provides an additional blocking layer before finalizing the decision.
• The CLI command loopx quota should-run --goal-id <goal> exposes this contract for external automation and monitoring.

Frequently Asked Questions

What triggers the throttled state in LoopX?

The throttled state occurs when waiting_on == "codex" and spent_slots reaches or exceeds allowed_slots in the current quota window. This condition is evaluated within quota_status (lines 72‑85) and prevents additional automatic turns until the quota window resets or slots become available.

How does the operator gate affect agent execution?

When waiting_on indicates user_or_controller or controller, the quota_status function returns operator_gate. According to the source code in loopx/quota.py, this state blocks gated delivery while permitting safe non‑gated steering operations to continue. This ensures human oversight maintains control over critical execution paths.

What is the difference between waiting and focus_wait states?

The waiting state indicates the goal is pending external evidence or has no active Codex‑ready work, serving as a general pause condition. In contrast, focus_wait is a specific blocking state that occurs when lifecycle markers indicate the goal requires new evidence or novelty before proceeding, or when the hand‑off outcome floor has not been met. The latter enforces stricter readiness criteria before agents may resume.

Where is the quota state actually computed in the codebase?

The definitive quota state computation resides in loopx/quota.py, specifically within the quota_status function (lines 72‑85) which derives the state, and _quota_plan_goal_quota (lines 438‑478) which assembles the quota object. Additional processing occurs in quota_with_handoff_outcome_floor (lines 4‑27), which may modify the state based on outcome floor requirements.

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