Cap the Turns: A Weekend Call Envelope for Agent Side Projects

Description and use

A file‑backed call envelope limits model and tool calls to stop agent loops when the local budget is exhausted.

Problem

Side‑project agents can run forever, consuming model and tool calls until the laptop is closed, wasting capacity and budget.

Outcome

The envelope stops agent loops when the local budget is exhausted, preventing overnight idle consumption and providing a clear, testable stop condition.

Workflow

• Persist remaining call budget in a JSON file
• Wrap model and tool calls behind a try_consume() gate
• Return EnvelopeEmpty exception when budget is exhausted
• Provide CLI to inspect, reset, and dry‑run the envelope
• Prove halt with a unit test that does not hit the network

Evidence

Persist remaining call budget in a JSON file.

Source

Wrap both model calls and tool calls behind one try_consume() gate.

Source