pi-smart-timeout

Content-aware shell command timeouts for Pi.

Pi's bash tool has no default timeout — timeout is an optional parameter the model has to remember to pass, and it usually doesn't. When a command hangs (a bare REPL, tail -f, a stalled network call, an interactive prompt), nothing kills it and the agent sits there until you interrupt by hand.

This extension caps every bash and powershell call so Pi's own process-tree kill fires and the tool returns Command timed out after N seconds. The model sees the error and recovers on its own.

Install

pi install npm:pi-smart-timeout

Or load it for a single run:

pi -e npm:pi-smart-timeout

Why "smart"

A single blunt number has an obvious failure mode: low enough to catch hangs and it kills your cargo build; high enough to let builds finish and it doesn't catch hangs. So the cap is chosen per command.

Decision order — first match wins:

#	Condition	Applied cap
1	mode is off	nothing injected
2	the model supplied timeout	used as-is, clamped to maxSeconds
3	the command contains timeout N ...	min(N + graceSeconds, maxSeconds)
4	the command looks long-running	longSeconds (default 1800)
5	anything else	defaultSeconds (default 120)

Hangs are caught, and a 20-minute build is not.

How this differs from the other timeout extensions

Three Pi timeout packages exist, and the difference is what they do with the command text. @jamiefutch/pi-timeout sorts commands into safe / run / unknown and never caps safe — but its safe set includes tail -f and npm install, which is exactly where hangs live:

Command	Safe/never-capped classifier	pi-smart-timeout
tail -f app.log	safe → never capped	1800s → killed
npm install	safe → never capped	1800s
git status	safe → never capped	120s
grep -rn 'make sure' src/	—	120s (heuristics ignore quoted text and English words)

@rukaachan/pi-timeout guards a different failure mode: a model passing 60000 when it meant 60 seconds. It clamps that number but applies the same cap to every command. pi-extend-timeout changes the timeout of a command already running, which is a recovery tool rather than a preventive one.

This package keeps two buckets so a low cap catches hangs without killing builds, and treats tail -f-style blocking commands as the long-running case they are.

Case 3 in detail

If the command already guards itself, the outer cap gets out of the way so the inner guard fires first and you get a precise error instead of an ambiguous kill:

timeout 2m cargo build     ->  150   (120 + 30 grace)
timeout -s KILL 90 job     ->  120
/usr/bin/timeout 45 job    ->   75
timeout 1h backup.sh       -> 3600   (3630 clamped to maxSeconds)
echo "timeout 5"           ->  120   (quoted, not a guard)
sh -c 'echo "a"; timeout 7 x' -> 37   (quote state resets per segment)
timeout 0 npm install      -> 1800   (coreutils: `timeout 0` means no limit)
timeout 99999 cat          -> 3600   (huge inner guard clamped to maxSeconds)

Option values are tokenized properly rather than matched with one regex, so -s KILL and --kill-after=5s are not misread as the duration. The inner guard is clamped to maxSeconds like every other path: when N exceeds the ceiling the inner guard could not fire before it anyway, so clamping never races the guard.

It also tells the model

The policy is appended to the system prompt each turn, so instead of being silently killed the model knows to pass timeout whenever a command might outlast the default cap, and knows not to re-run a timed-out command unchanged. The long bucket is framed as what commands known to run long receive, not as a blanket allowance, so the model asks for more time explicitly rather than relying on a promoted default. This turns a hard kill into a recoverable error.

Configuration

Settings are merged over built-in defaults. Project settings only apply to trusted projects.

~/.pi/agent/settings.json (global) or <cwd>/.pi/settings.json (project):

{
  "smartTimeout": {
    "mode": "long",
    "defaultSeconds": 120,
    "longSeconds": 1800,
    "maxSeconds": 3600,
    "graceSeconds": 30,
    "longPatterns": ["\\bmy-slow-tool\\b", "scripts/nightly\\.sh"]
  }
}

Key	Default	Meaning
mode	"long"	"long", "short" (cap everything at defaultSeconds), or "off" (never inject)
defaultSeconds	120	Cap for ordinary commands
longSeconds	1800	Cap for long-running commands
maxSeconds	3600	Hard ceiling applied even to model-supplied values. 0 disables it
graceSeconds	30	Headroom added on top of a detected inner timeout N
longPatterns	[]	Extra regexes (matched against the raw command) marking it long-running

Environment variables work too and sit below settings files: PI_BASH_TIMEOUT_SEC, PI_BASH_TIMEOUT_LONG_SEC, PI_BASH_TIMEOUT_MAX_SEC, PI_BASH_TIMEOUT_MODE, PI_BASH_TIMEOUT_LOG (append one line per decision — useful for verifying what was applied).

Invalid values are rejected with a warning and fall back to defaults; a malformed settings.json never breaks startup.

Commands

/bash-timeout                   show current configuration
/bash-timeout off               disable capping for this session
/bash-timeout short             cap everything at defaultSeconds
/bash-timeout long              restore content-aware capping
/bash-timeout reload            re-read settings.json without restarting

What it does not do

• It can't make Pi have a default timeout. Pi's bash schema is timeout?: number with no default; only injecting the field changes behavior.
• It won't kill deliberately detached work. nohup x & leaves a process outside the killed tree. That is usually what you want.
• It doesn't hang-proof interactive network tools. Bare ssh and ssh-keygen and curl/wget stay in the default bucket: they hang on prompts and unreachable hosts far more often than they legitimately run long, so a low cap catches the hang. Pass an explicit timeout when you really do need a long session or a big download.
• It doesn't promote while true loops. A while true; do ...; done loop is a hang by definition and gets the default cap. Only bounded poll loops (until ping -c1 host; do sleep 10; done) get the long bucket.
• It doesn't stop output flooding. It caps duration, not volume. Pi truncates output on its own (2000 lines / 50KB, full output saved to a temp file).
• timeout 0 cmd is not treated as a guard, because coreutils reads it as "no timeout" — so the outer cap still applies.

Tests

npm install
npm test          # fast: decision table + config + notifications   (~2s)
npm run test:e2e  # slow: real kill path, spawns and kills processes (~2min)

Suite	What it covers
tests/logic.test.mts	~75-case decision table: classification, inner-guard parsing, clamping, mode switching, system-prompt injection
tests/config.test.mts	settings.json layering, project trust gating, validation, malformed input, /bash-timeout reload
tests/ui.test.mts	notifications, hasUI: false, malformed tool input
tests/e2e.test.mts	drives Pi's real createBashTool: verifies 15 blocking scenarios are actually killed, that no orphaned grandchildren survive, and that fast commands and 3s commands under a 6s cap are not killed

The e2e suite asserts on real process state, not mocks: it reads taskkilled process tables via WMI to confirm the whole tree dies.

License

MIT