Herdr Agent State

The herdr-agent-state extension is the Herdr integration for pi. It bridges pi’s agent lifecycle into Herdr’s pane model so the workspace manager can show — and act on — whether each pi pane is working, blocked, or idle.

This file is installed and managed by Herdr. It is overwritten whenever you reinstall or update the integration, so do not edit it directly. Add custom hooks beside it in ~/.pi/agent/extensions/ instead.

What it does

The extension is a no-op unless it detects a Herdr environment (HERDR_ENV=1, HERDR_SOCKET_PATH, HERDR_PANE_ID). When active, it:

1. Reports the agent session to its Herdr pane on session_start, including the session file path so Herdr can resume or inspect it.
2. Publishes state transitions over the Herdr socket:
   • working — during an agent run
   • blocked — when the run is blocked (e.g. a tool asks for confirmation, or a herdr:blocked event is raised)
   • idle — once the run settles
3. Handles transient provider errors gracefully — retryable errors (rate limits, 429, 5xx, timeouts, network failures) hold the pane in working for a short grace period before falling back to blocked, avoiding flicker during auto-retries.
4. Releases authority on quit — only a real process exit (reason: "quit") releases Herdr’s full-lifecycle authority, so pi-internal reloads (/reload, /new, /resume, /fork) don’t suppress legitimate reports from the replacement runtime.

State updates are debounced (HERDR_PI_IDLE_DEBOUNCE_MS, default 250 ms) and queued so only the latest state is sent, even under rapid transitions.

Installation

The extension is installed automatically by Herdr — you do not copy or write the file yourself. Install the pi integration with:

herdr integration install pi

This writes ~/.pi/agent/extensions/herdr-agent-state.ts (managed, do not edit) and configures the socket communication. Verify it is registered:

herdr integration status

To update to a newer integration version, re-run the same install command:

herdr integration install pi   # idempotent; overwrites the managed file

To remove it:

herdr integration uninstall pi

Configuration

The extension is driven entirely by Herdr-supplied environment variables; there is no settings file to maintain. Tunable timings (set in the Herdr environment):

Variable	Default	Purpose
HERDR_PI_IDLE_DEBOUNCE_MS	250	Debounce before reporting idle
HERDR_RETRY_GRACE_MS	2500	How long to hold working during a retryable error

Activation

No manual steps are required. Launch pi from within a Herdr pane (herdr, or herdr --session <name>) and the environment variables are set automatically; the extension activates on session_start.