alexion/ai-artifacts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add artifact vault contents

Browse Source
This commit is contained in:
alexion
2026-08-01 14:05:09 -04:00
parent 361bde2621
commit 3230f9395b
78 changed files with 6156 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
projects/dotfiles/011-pi-subagents-herdr-pi-integration-research.md Normal file
View File

@@ -0,0 +1,46 @@
---
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.