89 lines
5.9 KiB
Markdown
89 lines
5.9 KiB
Markdown
---
|
|
parent: "[[002-pi-subagents-map]]"
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# 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:
|
|
|
|
```nix
|
|
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`.
|