monotonic-pi-extensions/packages/pi-turn-limit/turn-limit-widget-plan.md

Turn Limit Extension — Widget & Confirmation Plan

Goal

Extend the pi-turn-limit extension with:

1. A /turn-limit <N> command to change the max turns mid-session
2. A live widget showing Turns: {current}/{max}
3. A yes/no confirmation dialog when the turn limit boundary is reached (instead of immediate abort)

---

Files to Change

File	Change
packages/pi-turn-limit/src/turn-limit.ts	Only file to modify. Add command, widget, and confirmation logic.

No other files need changes. No new files, no dependency updates, no config changes.

---

Design Details

Current behavior (preserve these)

• DEFAULT_MAX_TURNS = 25
• getMaxTurns() reads PI_MAX_TURNS env var, falls back to default
• checkTurnLimit() pure function — do not modify
• agent_start resets turnCount = 0
• turn_start increments counter, checks limit, aborts if exceeded
• ctx.hasUI guard before UI calls

New behavior

A. /turn-limit <N> command

Register via pi.registerCommand().

• Name: turn-limit
• Description: Set the maximum number of agent turns for this session
• Handler:
  • Parse args as integer
  • If invalid (not a positive integer): show error via ctx.ui.notify("Invalid turn limit. Must be a positive integer.", "error") and return
  • Update the in-memory maxTurns variable
  • Call ctx.ui.setWidget() to update the widget display immediately
  • Optionally notify: ctx.ui.notify("Turn limit set to {N}.", "info")

B. Live widget

• Widget name: "turn-limit" (unique string identifier)
• Content: ["Turns: {current}/{max}"] — single line array
• Placement: default (above editor)
• Update timing:
  • Set on every turn_start (after incrementing turnCount)
  • Clear on agent_end (new user prompt starts)
• Example output: Turns: 12/25

C. Confirmation dialog at boundary

• Trigger condition: turnIndex === maxTurns (the boundary turn, NOT > maxTurns)
• Guard: Only if ctx.hasUI is true (print/JSON mode aborts silently)
• Dialog:

  Title: "Turn limit reached"
  Message: `You've used ${maxTurns} turns. Continue?`
  

• On "Yes" (confirmed):
  • Reset turnCount = 0
  • Do NOT abort — let the turn proceed
• On "No" (not confirmed):
  • Call ctx.ui.notify("Agent aborted by user.", "error")
  • Call ctx.abort()
• After confirmation: Update the widget with the reset counter (Turns: 0/{max})

D. Exit condition

The agent still aborts when the user has said "No" to every boundary confirmation. Since the counter resets on "Yes", the user can re-approve multiple times. The only way out is "No" or PI_MAX_TURNS = 0 (edge case).

---

Implementation Checklist

• Step 1: Add /turn-limit command registration

  • Use pi.registerCommand("turn-limit", { description, handler })
  • Handler parses args, validates positive integer
  • Updates maxTurns in-memory variable
  • Updates widget via ctx.ui.setWidget("turn-limit", ["Turns: {current}/{max}"])
  • Shows notify on success or error

• Step 2: Add live widget updates

  • In turn_start handler, after incrementing turnCount, call ctx.ui.setWidget("turn-limit", ["Turns: ${turnCount}/${maxTurns}"])
  • In agent_end handler, call ctx.ui.setWidget("turn-limit", undefined) to clear

• Step 3: Add boundary confirmation logic

  • In turn_start handler, after incrementing, check if (event.turnIndex === maxTurns)
  • If ctx.hasUI:
    • Show confirmation dialog via ctx.ui.confirm("Turn limit reached", \You've used ${maxTurns} turns. Continue?`)`
    • If confirmed: reset turnCount = 0, update widget, continue (do not abort)
    • If not confirmed: notify user, call ctx.abort()
  • If !ctx.hasUI: abort silently (same as current behavior)

• Step 4: Verify existing behavior is preserved

  • checkTurnLimit() function unchanged
  • getMaxTurns() function unchanged
  • agent_start still resets counter
  • DEFAULT_MAX_TURNS still 25
  • Env var PI_MAX_TURNS still respected

---

Code Structure (target file)

packages/pi-turn-limit/src/turn-limit.ts
├── DEFAULT_MAX_TURNS = 25                    (unchanged)
├── getMaxTurns()                             (unchanged)
├── checkTurnLimit()                          (unchanged)
└── export default function (pi: ExtensionAPI)
    ├── let turnCount = 0
    ├── let maxTurns = getMaxTurns()
    │
    ├── pi.on("session_start", ...)           (unchanged reset logic)
    ├── pi.on("agent_start", ...)             (unchanged reset logic)
    ├── pi.on("agent_end", ...)               (NEW: clear widget)
    ├── pi.on("turn_start", ...)              (MODIFIED: widget + confirmation)
    │
    └── pi.registerCommand("turn-limit", ...) (NEW: set max turns)

---

Edge Cases & Notes

• PI_MAX_TURNS = 0: Every turn hits the boundary immediately. The user gets a confirmation dialog every turn. This is the correct behavior — the user explicitly set 0, so they're asked each time.
• PI_MAX_TURNS = 1: First turn hits boundary. User confirms → counter resets → second turn hits boundary → user confirms again. Works as expected.
• Multiple /turn-limit calls: Each call updates maxTurns in-memory. Widget reflects the new value. No persistence needed (per-session).
• ctx.hasUI false: In print/JSON mode, the confirmation dialog can't be shown. Fall back to immediate abort (current behavior).
• Widget name collision: Use "turn-limit" as the widget name. It's unique to this extension.
• Import requirements: No new imports needed. pi.registerCommand is available on the pi object. ctx.ui.confirm, ctx.ui.notify, ctx.ui.setWidget, ctx.abort are all available on ctx.

---

Testing (manual)

1. Start pi with the extension loaded
2. Run agent tasks and watch the widget update: Turns: 1/25, Turns: 2/25, ...
3. When turns hit 25, confirm dialog appears → click "Yes" → counter resets to 0, widget shows Turns: 0/25
4. Click "No" → agent aborts with error notification
5. Run /turn-limit 10 → widget immediately shows Turns: 0/10
6. Run /turn-limit abc → error notification shown
7. Run /turn-limit 0 → confirmation dialog every turn
8. Run with PI_MAX_TURNS=5 → boundary at turn 5