@weshipwork/pi-herd

Read-only Transcript mirror plumbing for Pi Subagents in Herdr.

This package is the v1 mirror-mode tracer bullet from the project ADRs:

• Subagents still run in the Delegator Pi process.
• A Delegator-side bridge serves structured mirror events over one Unix socket.
• pi-herd-viewer connects from a Herdr pane and renders a read-only transcript/status stream.

Viewer

pi-herd-viewer --socket /path/to/pi-herd.sock --agent-id <subagent-id>

The current tracer bullet supports:

• a read-only observation-source interface for Subagent snapshots and live updates;
• a forked pi-subagents mirror-service adapter shape;
• a Delegator-side MirrorBridge that forwards those updates to MirrorServer;
• initial snapshots, assistant text deltas, and status updates in the viewer stream.
• a Pi extension entrypoint that starts a session-scoped mirror runtime when an observation source is installed;
• Herdr pane launch for pi-herd-viewer mirrors.

Full chronological transcripts, tool folding, and scroll/focus keybindings are later slices.

Pi extension integration

./extensions/herd.ts starts only inside Herdr (HERDR_ENV and HERDR_PANE_ID) and requires a read-only observation source from the forked pi-subagents runtime:

import { installPiHerdObservationSource } from "@weshipwork/pi-herd/extensions/herd";

installPiHerdObservationSource(source);

The expected fork seam is represented by PiSubagentsMirrorService in src/pi-subagents-observation-source.ts.