Agent TARS: a hard dollar limit per headless run with model.headers

[domondi1]

A single Agent TARS task can run for many steps, and in browser mode every step sends the page or a screenshot back to the model. If you run it headless from scripts or CI (agent-tars --headless --input ...), a task that loops or wanders keeps spending until it hits a step limit, and you only see the cost on the provider dashboard.

The model config already has everything needed to cap that per run: baseURL and headers, which go straight to the OpenAI client as defaultHeaders. Point it at an OpenAI-compatible gateway that enforces a per-run budget, and since the config is TypeScript, give every invocation its own run id.

Run the gateway (it uses your provider key):

pip install inferrail
export OPENAI_API_KEY=sk-...
inferrail serve --quickstart --app-mode   # http://127.0.0.1:8000

agent-tars.config.ts:

import { randomUUID } from "node:crypto";

const runId = process.env.TARS_RUN_ID ?? `tars-${randomUUID()}`;

export default {
  model: {
    provider: "openai",
    id: "gpt-4o-mini",
    baseURL: "http://127.0.0.1:8000/v1",
    apiKey: "unused",
    headers: {
      "X-Inferrail-Attribute-Work-Id": runId,
      "X-Inferrail-Budget-Usd": process.env.TARS_BUDGET_USD ?? "1.00",
    },
  },
  maxTokens: 800, // the reservation is based on it
};

TARS_RUN_ID=report-0412 TARS_BUDGET_USD=0.50 \
  agent-tars --config ./agent-tars.config.ts --headless --input "..." --format text

inferrail work report-0412   # calls made and what the run cost

Each model call reserves its worst-case cost (input plus maxTokens) before it's sent. When the run's budget can't cover the next step, the call is refused with HTTP 402 before it reaches OpenAI, and the run ends with Error: 402 budget ... would be exceeded instead of continuing. The OpenAI client doesn't retry a 402, and the headers aren't forwarded upstream. Screenshot (image_url) content is accepted, with a fixed per-image allowance in the reservation.

What I tested: @agent-tars/cli 0.3.0, inferrail 0.4.12, headless mode, with a local stub upstream standing in for OpenAI. With a $1 budget the run completed and inferrail work showed its 2 calls. With a budget smaller than one step, the first call was refused before reaching the upstream and the CLI printed the 402 and stopped. I didn't exercise a long browser session against the real API, so reports are welcome.

Caveats: --config needs to point at the file (it isn't picked up by that name automatically); the OpenAI provider uses chat completions, which is what the gateway serves; the model needs a price in Inferrail (gpt-4o-mini, gpt-4.1-mini, gpt-4.1 built in, inferrail models lists others, and you can add your own prices). In serve/web UI mode the config is read once, so all sessions share the run id. That makes it a cap for the whole server process rather than per session.

Setup details: guide. I maintain Inferrail (open source, Apache-2.0), so take the suggestion with that in mind.