2.5 KiB
status, parent, blocked-by, tags
| status | parent | blocked-by | tags | |
|---|---|---|---|---|
| resolved | 003-pi-subagents-herdr-compatibility-research |
|
Herdr Pi integration research
Question
What does Herdr's Pi integration extension actually report or enable, and how does that change the requirements for Pi-spawned subagents to appear with useful lifecycle state in Herdr?
Resolution
Findings
Herdr's Pi integration is a Pi lifecycle reporter, not a launcher or subagent manager.
A safe fake install generated /tmp/herdr-pi.12G0B5/.pi/agent/extensions/herdr-agent-state.ts without touching the real home.
The generated extension enables itself only when HERDR_ENV === "1", HERDR_SOCKET_PATH, and HERDR_PANE_ID are present.
Citation: generated herdr-agent-state.ts inspected under /tmp/herdr-pi.12G0B5.
The extension reports to Herdr through pane-bound API calls.
It uses pane.report_agent_session for Pi session identity, pane.report_agent for lifecycle state, and pane.release_agent on real quit.
It reports working on Pi agent_start, idle on agent_settled when Pi is idle, and blocked through a custom herdr:blocked event.
Citation: generated herdr-agent-state.ts and herdr api schema --json definitions for pane reporting methods.
The integration runs only for Pi contexts with UI.
On session_start, the generated extension returns early unless ctx.hasUI === true.
Pi docs state ctx.hasUI is false in print and JSON modes.
Citation: generated herdr-agent-state.ts and Pi docs/extensions.md mode behavior.
Pi's official subagent example launches children with --mode json -p --no-session and no Herdr pane assignment.
Those children would not pass the integration's UI guard, and any inherited Herdr pane env vars would identify the parent pane rather than an independent child pane.
Citation: Pi examples/extensions/subagent/index.ts.
Implications
The Herdr Pi integration makes interactive Pi processes inside Herdr panes authoritative lifecycle reporters. It does not make background or JSON-mode Pi subprocesses appear as independent Herdr agents.
Useful Herdr visibility for Pi subagents therefore requires either running each visible child in a Herdr-addressable pane with the Pi integration loaded, or building a separate mechanism that maps child lifecycle into a Herdr pane or parent-pane metadata representation.
If blocked or waiting state matters, the subagent workflow must emit or translate a blocked-state signal. The default Pi lifecycle only provides working and idle through the generated integration.