82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# pi-turn-limit
|
|
|
|
Pi coding agent extension to limit the number of turns taken by a model in a session.
|
|
|
|
## Why
|
|
|
|
Pi agents can run indefinitely, consuming tokens and time, and taking focus. This extension gives you a circuit breaker: when the agent reaches a configurable turn limit, you decide whether to continue or abort.
|
|
|
|
This is useful for:
|
|
|
|
- **Interaction** — Shorter _Time To Next Interaction (TTNI)_ keeps you in the loop. Focus, clarity, single-tasking mode.
|
|
- **Cost control** — prevent runaway sessions from burning through API credits
|
|
- **Quality control** — if an agent needs more turns than expected, something may be wrong with the prompt or task
|
|
|
|
## How it works
|
|
|
|
The extension tracks turns (agent round-trips) per session. Each new user prompt resets the counter.
|
|
|
|
| Event | Behavior |
|
|
|-----------------------|---------------------------------------------------|
|
|
| `agent_start` | Counter resets to 0 |
|
|
| `turn_start` | Counter increments; widget updates |
|
|
| Counter reaches limit | User prompted: continue (counter resets) or abort |
|
|
| No UI available | Silent abort at limit |
|
|
|
|
When the limit is reached and the user confirms continuation, the counter resets to 0, allowing another round of turns. This repeats — there's no maximum number of continuations.
|
|
|
|
## Configuration
|
|
|
|
### Environment variable
|
|
|
|
Set `PI_MAX_TURNS` before starting pi:
|
|
|
|
```bash
|
|
# 50 turns
|
|
PI_MAX_TURNS=50 pi
|
|
|
|
# Unlimited — no boundary check fires
|
|
PI_MAX_TURNS=unlimited pi
|
|
|
|
# Default (25 turns)
|
|
pi
|
|
```
|
|
|
|
### Runtime command
|
|
|
|
Adjust the limit during a session with the `turn-limit` command:
|
|
|
|
```
|
|
/turn-limit 50 # Set to 50 turns
|
|
/turn-limit unlimited # Disable the limit
|
|
/turn-limit 25 # Re-enable with 25 turns (counter resets from 0)
|
|
```
|
|
|
|
### Unlimited mode
|
|
|
|
Setting the limit to `unlimited` disables the boundary check entirely. The turn counter still increments and the widget still displays `∞`, so you retain observability without enforcement.
|
|
|
|
Switching from unlimited back to a number triggers the **LimitReEnabled** rule: the counter resets to 0 so the new limit applies from a clean starting point.
|
|
|
|
## Widget
|
|
|
|
When a UI is available, the extension displays a widget showing `Turns: N/M` (or `Turns: N/∞` in unlimited mode).
|
|
|
|
## Spec
|
|
|
|
This extension was developed using [Allium](https://juxt.github.io/allium/), a formal language for specifying software behavior. The Allium spec captures the turn counting, limit enforcement, unlimited mode, and re-enable rules:
|
|
|
|
📄 [turn-limit.allium](./turn-limit.allium)
|
|
|
|
## Contributing
|
|
|
|
This is an experimental extension. To contribute:
|
|
|
|
1. Fork the repository
|
|
2. Make your changes
|
|
3. Contact Willem through [qwan.co.uk](https://qwan.co.uk) to discuss your contribution
|
|
|
|
## License
|
|
|
|
MIT
|