@pi-in-go/pigpen-herdr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kinsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# herdr reporter Package
+
+Go extension, written against PiG's public Go extension SDK, that reports PiG's `idle`, `working` and `blocked` state to [herdr](https://github.com/herdrdev/herdr), the terminal workspace manager. Outside a herdr pane it registers nothing. It needs no Node.js: PiG builds it from source with a Go toolchain, and a Piglet Binary fuses it. It implements herdr's published [Add Herdr support to your agent](https://herdr.dev/docs/add-herdr-support/) contract: state, the resume command (herdr 0.9.2+) and release. See the [herdr Piglet](../../piglets/herdr/README.md) for what it reports and how it behaves.
+
+**It works on its own.** Installing this Package is enough: no Piglet is needed.
+The [`herdr` Piglet](../../piglets/herdr/README.md) is an optional composition that
+selects this same Package. Use it directly from the Pigpen checkout root:
+
+```sh
+pig package validate ./components/herdr
+pig install ./components/herdr
+```
+
+The local install references this checkout; keep it at its installed path and remove it with `pig remove` using the same path. The `herdr` Piglet selects this Package through `npm run stage`.
+
+`PIG_BIN=/path/to/pig npm run test:go` runs `go test` in `extensions/herdr` against a fake `HERDR_BIN_PATH` (with `HERDR_SOCKET_PATH`) and a wire-level fake PiG host; it needs a Go toolchain and PiG's SDK (`PIG_SDK_DIR`, `PIG_SOURCE_ROOT` or `PIG_BIN` selects it). The tests are a port of the earlier TypeScript suite, case for case; the two `herdr:blocked` bus cases are named, skipped tests until the bridge below exists.
+
+**Not ported: `herdr:blocked`.** The earlier TypeScript extension also listened to the `herdr:blocked` event on `pi.events`, the bus herdr's own Pi integration handles, so that another extension could mark a block that is not a UI prompt. This Go extension reports `blocked` only for UI prompts (`ui_prompt_start` and `ui_prompt_end`). PiG's Go SDK has the `pi.events` bridge since 0.4.0 (`Extension.Events()`), so the extension can listen for `herdr:blocked`; it does not yet, and the two tests that name it stay skipped until it does. It does not run on Pi: the TypeScript file was removed with this port, and Pi users keep herdr's own Pi integration.
+
+[MIT](LICENSE), original work by Michael Kinsy; see `provenance.json`.

package/extensions/herdr/bench_test.go

@@ -0,0 +1,55 @@
+package herdr
+
+import (
+	"strings"
+	"testing"
+)
+
+// The reporter runs on agent_start, agent_settled and prompt events. Each handler takes the lock, decides
+// whether the state changed, and only a change queues a herdr call (a process exec, off the handler's path).
+// These benchmarks keep the reporter released so no herdr process is started: they measure the handler logic.
+//
+//	go test -run xxx -bench . -benchmem
+func benchReporter() *reporter {
+	return &reporter{env: herdrEnv{bin: "/bin/true", paneID: "p1"}, rootSession: true, released: true}
+}
+
+func BenchmarkReporterStartSettled(b *testing.B) {
+	r := benchReporter()
+	path, id := "/home/u/.pig/agent/sessions/--work--/2026-01-01_abc.jsonl", "0199abcd-0000-7000-8000-000000000000"
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		r.agentStarted(path, id)
+		r.agentSettled()
+	}
+}
+
+// The same state again (a second agent_start in one run, a repeated prompt event) is dropped without queueing.
+func BenchmarkReporterUnchangedState(b *testing.B) {
+	r := benchReporter()
+	r.agentStarted("/s.jsonl", "id")
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		r.agentStarted("/s.jsonl", "id")
+	}
+}
+
+func BenchmarkReportArgs(b *testing.B) {
+	r := benchReporter()
+	r.sessionPath, r.sessionID = "/home/u/.pig/agent/sessions/--work--/2026-01-01_abc.jsonl", "0199abcd-0000-7000-8000-000000000000"
+	rep := report{state: stateBlocked, message: "Allow this tool call?", seq: 7}
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		r.mu.Lock()
+		_ = r.reportArgsLocked(rep, true)
+		r.mu.Unlock()
+	}
+}
+
+func BenchmarkMessageFrom(b *testing.B) {
+	title := strings.Repeat("Allow bash to run a long command?\n  with several lines\tand tabs ", 3)
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_ = messageFrom(title)
+	}
+}

package/extensions/herdr/diagnostics_test.go

@@ -0,0 +1,92 @@
+package herdr_test
+
+// A report herdr does not take must not stall or fail the agent, and it must not
+// vanish without a trace either: a herdr that never hears about a pane is
+// otherwise impossible to tell from one that was told. The reporter writes one
+// line to stderr (which PiG collects as the extension's output) naming the cause.
+// This came from the herdr-agent-state extension of pigpen pull request 2.
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	herdr "github.com/MichaelKinsy/pigpen/components/herdr/extensions/herdr"
+)
+
+// captureStderr swaps os.Stderr for a pipe and returns what was written so far.
+func captureStderr(t *testing.T) func() string {
+	t.Helper()
+	orig := os.Stderr
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stderr = w
+	t.Cleanup(func() { os.Stderr = orig })
+	return func() string {
+		settle()
+		_ = w.SetDeadline(time.Now())
+		os.Stderr = orig
+		_ = w.Close()
+		b, _ := io.ReadAll(r)
+		return string(b)
+	}
+}
+
+func TestRefusedReportsAreExplained(t *testing.T) {
+	t.Run("a refused report names the cause", func(t *testing.T) {
+		host, h := startTUI(t)
+		h.failWithMessage(1, "error: pane p_9 not found")
+		read := captureStderr(t)
+		host.fire("session_start", map[string]any{"reason": "startup"})
+		h.waitForCalls(1)
+		got := read()
+		if !strings.Contains(got, "herdr: pane report-agent failed") || !strings.Contains(got, "pane p_9 not found") {
+			t.Fatalf("stderr = %q", got)
+		}
+	})
+
+	t.Run("a herdr that keeps refusing is reported once, not once per report", func(t *testing.T) {
+		host, h := startTUI(t)
+		h.failWithMessage(1, "error: failed to connect to herdr socket")
+		read := captureStderr(t)
+		host.fire("session_start", map[string]any{"reason": "startup"})
+		for range 3 {
+			host.fire("agent_start", nil)
+			host.fire("agent_settled", nil)
+		}
+		h.waitForCalls(2)
+		settle()
+		if n := strings.Count(read(), "failed to connect to herdr socket"); n != 1 {
+			t.Fatalf("the same failure was written %d times", n)
+		}
+	})
+
+	t.Run("a herdr binary that is gone is reported", func(t *testing.T) {
+		installFakeHerdr(t)
+		missing := filepath.Join(t.TempDir(), "missing")
+		t.Setenv("HERDR_BIN_PATH", missing)
+		host := startHost(t, herdr.Extension(), "tui")
+		read := captureStderr(t)
+		host.fire("session_start", map[string]any{"reason": "startup"})
+		if got := read(); !strings.Contains(got, "herdr: pane report-agent failed") || !strings.Contains(got, "missing") {
+			t.Fatalf("stderr = %q", got)
+		}
+	})
+
+	t.Run("a healthy herdr and an old herdr that refuses only the resume command stay silent", func(t *testing.T) {
+		host, h := startTUI(t)
+		h.refuseResume("old")
+		read := captureStderr(t)
+		host.fire("session_start", map[string]any{"reason": "startup"})
+		host.fire("agent_start", nil)
+		h.waitForCalls(2)
+		if got := read(); got != "" {
+			t.Fatalf("stderr = %q, want nothing", got)
+		}
+	})
+}