Herdr Pi integration Nix-pure deployment research

Question

Can the Herdr Pi integration be installed declaratively through Nix/Home Manager without vendoring the generated Pi extension file by hand?

Findings

Herdr exposes first-party integration management through the herdr integration command group. herdr --help lists herdr integration <subcommand> as the built-in interface for managing agent integrations, and herdr integration install --help says the install command takes a single target argument whose possible values include pi. On this host, herdr --version reports herdr 0.7.5.

The Pi integration installs a Pi-side extension file, not a Herdr config file. herdr integration status reported pi: not installed (/home/alexion/.pi/agent/extensions/herdr-agent-state.ts) before installation, and herdr integration install pi reported installed pi integration to /home/alexion/.pi/agent/extensions/herdr-agent-state.ts. After installation, herdr integration status reported pi: current (v6) (/home/alexion/.pi/agent/extensions/herdr-agent-state.ts). The generated file begins with Herdr-owned metadata: HERDR_INTEGRATION_ID=pi and HERDR_INTEGRATION_VERSION=6.

The installer does not create the Pi extension directory. With a temporary HOME and no ~/.pi/agent/extensions, herdr integration install pi failed with pi extension directory not found at .../.pi/agent/extensions. install pi first. After creating that directory in the temporary home, the same command succeeded and wrote herdr-agent-state.ts. This matters for Nix because the derivation or activation code must provide a fake Pi home layout before invoking the installer.

The installer can run in a Nix build derivation on this machine. A test derivation using pkgs.stdenvNoCC.mkDerivation, nativeBuildInputs = [ pkgs.herdr ], a fake $TMPDIR/home/.pi/agent/extensions, and HOME=$TMPDIR/home herdr integration install pi built successfully and copied the generated file to $out/herdr-agent-state.ts. The generated store file was root-owned and read-only, as expected for a Nix build output. Its SHA-256 matched the file produced by the imperative install in the real home: 12efd27592fbf185343f035ee4fd2b1999e9356e323e4b01225f7d6bc89b16de for both files.

Therefore a Nix-pure deployment is feasible in this repository without manually vendoring the generated file. The dotfiles module can create a small derivation that runs Herdr's own installer into a fake home and then expose the generated herdr-agent-state.ts as a Home Manager-managed Pi extension. This keeps the generated adapter tied to the pinned pkgs.herdr package and avoids a stale checked-in copy.

Recommended declarative shape

Keep the extension deployment in the Pi module because the runtime artifact is a Pi extension file:

let
  herdrPiIntegration = pkgs.stdenvNoCC.mkDerivation {
    name = "herdr-pi-integration";
    nativeBuildInputs = [ pkgs.herdr ];
    phases = [ "installPhase" ];
    installPhase = ''
      mkdir -p $TMPDIR/home/.pi/agent/extensions
      HOME=$TMPDIR/home herdr integration install pi
      mkdir -p $out
      cp $TMPDIR/home/.pi/agent/extensions/herdr-agent-state.ts $out/herdr-agent-state.ts
    '';
  };
in {
  home-manager.users.${user}.home.file."${piDir}/extensions/herdr-agent-state.ts".source =
    "${herdrPiIntegration}/herdr-agent-state.ts";
}

This uses Herdr as the source of truth for its adapter while leaving Pi to load the resulting file through its normal extension directory. It should not require herdr integration install pi during activation. It also avoids installing into ~/.pi/agent/extensions imperatively, which is important because this repo already manages Pi extension deployment declaratively.

A slightly more structured version could package the generated file as pkgs.herdr-pi-integration in an overlay or local package helper if more modules need it. For a single file used only by modules/agents/pi/pi.nix, an inline derivation is enough.

Caveats

The build-time test establishes that Herdr 0.7.5's Pi installer can run in a Nix derivation on this host. It does not prove future Herdr versions will remain build-sandbox friendly. If a future installer starts requiring network access, a running Herdr server, or writable global config, the derivation will fail and reveal that at build time.

The generated file says it is "managed by herdr" and can be overwritten by reinstalling or updating the integration. When Nix generates the file, the practical manager is the Nix derivation, but the content still belongs to Herdr. Do not edit the generated TypeScript by hand.

The current direct install under ~/.pi/agent/extensions/herdr-agent-state.ts is not the final declarative state. A later implementation should either remove that unmanaged file or let Home Manager replace it with the generated store-backed file.

Citations

herdr --help on this host lists herdr integration <subcommand> as the interface for managing built-in agent integrations and reports config/log paths.
herdr integration install --help on this host defines install <TARGET> and lists pi among supported targets.
herdr integration status on this host reported the Pi integration path and current installed state before and after installation.
herdr integration install pi on this host wrote /home/alexion/.pi/agent/extensions/herdr-agent-state.ts and reported success.
Temporary-home installer test: HOME=$(mktemp -d) without .pi/agent/extensions failed with the missing-directory diagnostic, and the same command succeeded after creating .pi/agent/extensions.
Nix derivation test at /tmp/herdr-pi-integration-test.nix built successfully with nix build --impure --no-link --print-out-paths --file /tmp/herdr-pi-integration-test.nix and generated /nix/store/9qnkkqkv8f3smm09n4rzshwh961fbj9h-herdr-pi-integration-test/herdr-agent-state.ts.

5.9 KiB Raw Blame History