47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[003-pi-subagents-herdr-compatibility-research]]"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/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.
|