pi-anti-doom-loop

Stop agent doom loops in pi before they burn tokens.

Cheap models sometimes get stuck repeating the same cheap tool call — grep the same file, re-run the same failing command — with no progress. Each iteration is so cheap nobody notices until the bill mounts. This extension watches every tool call and blocks the loop at the source.

Install

pi install npm:pi-anti-doom-loop

What it detects

| Signal | Default | Blocked when | | ------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Same (tool, args) repeated | 3× in the last 10 calls | The pattern has repeated 3 times with no change | | Same tool failing consecutively | 3× | A tool errored 3 times in a row — stop retrying it blindly | | Same assistant text verbatim | 3× within the last N messages | The model re-emitted identical text 3 times inside the sliding window | | Same sentence inside ONE message | 3× | A sentence repeats 3+ times within a single message (growing self-concatenation loops) | | Near-identical text (rephrasing) | 3× in a row | Consecutive messages share ≥55% tokens — the model is rephrasing the same step | | Near-identical text cycle (rotating rephrased commands) | 3× within the last N messages | Near-identical assistant texts (≥55% token similarity) accumulate to the repeat threshold in the window, even when not identical and not consecutive |

Blocks hand the model an instructive reason ("change your approach, use a different tool, or ask the user"). If the model ignores the block and re-issues the exact same call, the turn is aborted.

Escalation (text loops): steer → abort → bounded resume

The first text-loop detection steers the agent mid-run (injects guidance, lets it continue). If it persists, the run is aborted and one fresh- resume directive is queued so work continues with a new approach. If it still loops after that, the run aborts for real and control returns to you — the auto-resume budget is capped so a truly stuck model can't cycle forever. Counters reset on every user prompt, so a task legitimately repeated later in the same session is never a false positive.

Configuration

Environment variables, read at session/prompt start:

| Variable | Default | Meaning | | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | PI_ANTI_LOOP_REPEATS | 3 | Identical-call block threshold | | PI_ANTI_LOOP_FAILS | 3 | Consecutive-failure block threshold | | PI_ANTI_LOOP_TEXT_REPEATS | 3 | Window/cycle repeat threshold for identical and near-identical assistant texts | | PI_ANTI_LOOP_WINDOW | 10 | How many recent calls/results are inspected | | PI_ANTI_LOOP_TIME_WINDOW | 0 | Elapsed-time window in ms (0 = disabled, count-only): evicts window entries older than this so slow chronic loops over a long session are caught | | PI_ANTI_LOOP_FAIL_RATE | 0 | Fail-rate block threshold 0..1 (0 = disabled): block when a tool's error share of its in-window calls reaches this | | PI_ANTI_LOOP_FAIL_RATE_MIN | 3 | Minimum calls before the fail-rate window can block | | PI_ANTI_LOOP_TOOLS_EXCLUDE | — | Comma-separated tool names to disable detection for entirely (never block, never enter the window) | | PI_ANTI_LOOP_DISABLE | — | Set to 1 to disable the extension entirely |

Command

• /loopcheck — show thresholds, counters (steers/aborts this session), suspend state, the current window contents (most-repeated recent calls and texts), wasted-token count, and the fail-rate/time-window/exclude config when enabled
• /loopcheck reset — clear counters
• /loopcheck suspend — pause detection until the next prompt (escape hatch for intentional repetition)
• /loopcheck resume — re-enable detection early

Token-cost awareness

The detector estimates tokens burned on redundant repeats (~4 chars/token) and reports "~N tokens burned on repeats." in tool-call block reasons. The cumulative wasted-token count also appears in /loopcheck status, so you can see how much a loop actually cost before it was stopped.

How it works

Everything hooks into the tool_call / tool_result / message_end events; detection is a small sliding-window counter (see extensions/detector.ts) with per-session counters (steers/aborts) tracked in extensions/controller.ts. Works with any model — cheap models just trigger it more often.

Development

Requires Node 22.18+ (plain node runs the TS self-check).

npm install
npm test        # node --test: unit + fixture + fuzz + integration + e2e
npm run check   # npm test + tsc + oxlint --deny-warnings + oxfmt

Test suite (Node built-in runner, no framework)

| Suite | File | What it proves | | ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | unit | tests/unit.test.ts | detector semantics: repeat/failure/text signals, window eviction, options clamping, helpers | | fixture | tests/fixtures.ts + tests/fixture.test.ts | real doom-loop transcripts (CI-log loops, verbatim repeats) are caught; healthy sessions are not | | fuzz | tests/fuzz.test.ts | seeded random streams: never throws, no false positives, injected loops always block, canonical stability | | integration | tests/integration.test.ts | controller + index.ts adapter driven through a fake PiLike: blocks, escalations, aborts, resets, /loopcheck | | e2e | tests/e2e.test.ts | real subprocesses: detector self-check, version guard, tarball contents (extensions/scripts ship, tests don't) |

peerDependencies pins @earendil-works/pi-coding-agent at "*" on purpose — the pi packages docs require an unbounded range for pi-core packages (pi provides them at runtime). The extension loads .ts directly via jiti, so no build step ships; prepublishOnly runs the full quality gate before publish.

When a call is blocked, escalation still works without recording it in the window: re-issuing the identical call increments a per-signature block counter and aborts the turn on the second block. Thresholds are clamped to a minimum of 2 so a bad config can never brick the agent.

Releasing

Publishing is handled by the GitHub Actions workflow .github/workflows/release.yml, guarded against version drift:

1. Add an npm Automation token as the NPM_TOKEN repo secret (Settings → Secrets and variables → Actions, or gh secret set NPM_TOKEN).
2. Bump version in package.json, commit, then tag and push:

git tag v0.0.1
git push origin v0.0.1

CI runs the quality gate, then the version bump guard (npm run guard): it blocks publishing if the version is already on npm or the tag doesn't match package.json. After the first publish, the pi.dev gallery picks the package up automatically via the pi-package keyword.

License

MIT