Run Budget Guard

Open a hard budget for one agent run before it starts: max dollars, tokens, calls and/or wall-clock seconds. Returns a handle. Give the handle to every sub-agent; they all draw from the same ledger, so one runaway loop or fork cannot exceed the run cap.

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "What this run is for, e.g. \"nightly code cleanup\"."
    },
    "max_usd": {
      "type": "number",
      "description": "Dollar cap for the whole run (your own estimates per call)."
    },
    "max_tokens": {
      "type": "integer",
      "description": "Token cap (input + output) for the whole run."
    },
    "max_calls": {
      "type": "integer",
      "description": "Cap on model/tool calls for the whole run."
    },
    "max_seconds": {
      "type": "integer",
      "description": "Wall-clock cap in seconds from now."
    },
    "ttl_hours": {
      "type": "integer",
      "description": "Handle lifetime (free max 24, Pro max 168). Default 24."
    },
    "mode": {
      "type": "string",
      "enum": [
        "shadow",
        "enforce"
      ],
      "description": "shadow = watch only: track spend and flag where the cap WOULD have stopped the run, never block (free). enforce = return allowed=false at the cap (Pro). Default: enforce on Pro, shadow on free."
    }
  }
}

Call BEFORE each model call, tool call or sub-agent spawn with your estimate. Returns allowed=true and deducts it, or allowed=false with the limit that tripped. When allowed is false, stop, do not retry, and return your partial result to the user. Atomic, so parallel sub-agents cannot both slip under the cap.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget."
    },
    "usd": {
      "type": "number",
      "description": "Estimated cost of the next call in USD."
    },
    "tokens": {
      "type": "integer",
      "description": "Estimated tokens of the next call."
    },
    "calls": {
      "type": "integer",
      "description": "Number of calls to reserve (default 1)."
    },
    "note": {
      "type": "string",
      "description": "Short note, e.g. \"web_search #12\"."
    }
  },
  "required": [
    "handle"
  ]
}

After a call, report the actual usage minus what you reserved (positive if it cost more, negative to give back an overestimate). Keeps the ledger honest without blocking.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget."
    },
    "usd": {
      "type": "number"
    },
    "tokens": {
      "type": "integer"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "handle"
  ]
}

Draft a plain-English report of the last 7 days for your key (or IP): runs, spend, runs that went over their cap, and dollars spent after a cap would have stopped them. Read-only; sends nothing. Show it to your user.

{
  "type": "object",
  "properties": {}
}

See spend vs limits, remaining budget, whether the run is stopped and why, and the last 20 ledger events. Set close=true when the run finishes.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget."
    },
    "close": {
      "type": "boolean"
    }
  },
  "required": [
    "handle"
  ]
}

Show today's usage for your key or IP and the $49/month All Access upgrade link (cloudforbots.com/offer). Free tier: 500 calls/day. Not metered.

{
  "type": "object",
  "properties": {}
}