pi-turn-budget

Keep your AI agents focused, on time, and under your control.

I built pi-turn-budget because I like working with AI agents in small, provable steps.

If I think a task should take 30 seconds, 2 minutes, or 5 minutes, I want to know when it doesn't.

Without a real time limit, an agent can keep researching, thinking, trying alternatives, or drifting away from the original task. By the time you notice, you've already lost time and context.

pi-turn-budget gives every Pi turn a real time budget.

Set the next turn to 5 seconds, 2 minutes, or whatever makes sense. You can see the countdown while the agent works. If time runs out, the active work is stopped and control comes back to you.

The goal isn't simply to stop agents.

The goal is to learn faster.

When a task exceeds its expected time, that's useful information. Maybe the task was too large. Maybe the estimate was wrong. Maybe the agent is drifting. Maybe a tool failed. You can inspect what happened, make the next step smaller, and continue from evidence instead of letting the agent work indefinitely.

That's how I use it:

small task → time budget → visible work → stop or result → learn → next small task

/budget 30s

• The next Pi turn gets 30 seconds.
• You can see the countdown.
• If it finishes, great.
• If time expires, active work is stopped.
• Afterward, the normal budget returns automatically.

It works by itself for everyday Pi use.

Advanced users can also consume lifecycle information for supervisors, harnesses, or state machines.

Technical reference

Behavior

The extension enforces a hard wall-clock deadline for the whole request. Plain pi uses a default turn budget of 120 seconds (120000 ms), so no environment variable is required.

At before_agent_start, the extension resolves and captures one budget for the entire request, starts the deadline, and displays a live countdown when UI is available. At expiry it claims the terminal outcome, requests abort before emitting expiry observations, and blocks later tool calls.

Optional session base override

PI_TURN_BUDGET_MS remains optional. Set it to a positive safe integer in milliseconds to replace the session base budget:

PI_TURN_BUDGET_MS=60000 pi

Invalid explicit values, including zero, negative, non-integer, and unsafe integer values, fail closed.

Budget status

Run /budget with no argument to inspect the current configuration without invoking the LLM, starting a timed request, changing a budget, or consuming a pending override:

Default: 2m
Session base: 2m
Next turn override: none
Effective next turn: 2m

After /budget 30s, status shows Next turn override: 30s and Effective next turn: 30s. After one actual agent request consumes the override, status returns to none and the session base. With PI_TURN_BUDGET_MS=60000, the default remains 2m while the session base and effective next turn show 1m.

Next-request override

Use /budget with a positive whole number of seconds or minutes:

/budget 30s
/budget 2m

For example, /budget 30s confirms Next turn budget: 30 seconds without invoking the LLM. It affects only the next owner-submitted request. The override is consumed immediately when that request starts, and the following request automatically returns to the session base budget or the package default.

Budget precedence for each request is:

1. pending /budget override;
2. optional PI_TURN_BUDGET_MS session base override;
3. package default of 120000 ms.

Enforcement and observations

The deadline covers the whole request rather than only tool-call boundaries. On expiry, the extension requests abort and blocks any later tool call before execution. An active/released/expired winner guard makes release and expiry mutually exclusive.

Each request emits generic pi-turn-budget:armed and one winning pi-turn-budget:released or pi-turn-budget:expired event when a terminal outcome is observed. Event details are in docs/events-v1.md. Matching local receipts are best-effort and non-authoritative. Runtime evidence uses the existing proof-oriented file beneath the active working directory and is reset at request start. Exported test seams make the terminal guard and receipt failure behavior deterministic to test.

Local installation concept

Pi can load the package from its directory path. Version 0.4.1 is the current release candidate for a separate clean global-install proof; it has not been published.

Security

Pi extensions execute with the permissions of the Pi process and can access the local system. This extension reads optional PI_TURN_BUDGET_MS and PI_TURN_BUDGET_CORRELATION_ID environment variables and writes runtime evidence beneath the active working directory.

Status

Release candidate 0.4.1; ready for clean-install proof.