Patched Pi packaging research

Question

How should the flex-spacer Pi layout patch be packaged in this dotfiles flake so the ordinary pi command uses it after rebuild?

Findings

The flex-spacer change is not an extension-only change. Pi's interactive mode source adds TUI children directly in packages/coding-agent/src/modes/interactive/interactive-mode.ts: header, loaded resources, chat, pending messages, status, widgets above editor, editor, widgets below editor, and footer. That is the layout stack the flex-spacer must change. Source: /nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts.

The installed Pi package is the nixpkgs pi-coding-agent package at version 0.82.1. Its nixpkgs derivation builds from the upstream GitHub tag v0.82.1, restores the generated model catalog from the published npm package, builds TypeScript workspace packages, and wraps $out/bin/pi with Nix-provided ripgrep and fd on PATH plus default telemetry/version-check environment variables. Source: /nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix.

The active installed wrapper confirms the nixpkgs wrapper shape. /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi prepends Nix-store fd and rg paths, sets PI_SKIP_VERSION_CHECK and PI_TELEMETRY, then execs .pi-wrapped inside the same package output. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi.

The current dotfiles Pi module uses Home Manager's programs.pi-coding-agent module. It currently sets enable, settings, managed extension files, and managed prompt files, but does not override the Pi package. Source: modules/agents/pi/pi.nix.

The Home Manager Pi configuration does expose a package option in this evaluated system. A targeted eval of home-manager.users.alexion.programs.pi-coding-agent returned keys including package, and an extendModules eval setting home-manager.users.alexion.programs.pi-coding-agent.package = pkgs.pi-coding-agent.overrideAttrs (...) changed the evaluated package name to pi-coding-agent-test-0.82.1. Source: nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.programs.pi-coding-agent; command verification in this research session.

The patch should therefore be applied by overriding programs.pi-coding-agent.package, not by installing a competing wrapper or copying a patched tree under home. A package override keeps the ordinary pi command managed by Home Manager and preserves the nixpkgs wrapper behavior unless deliberately changed. Sources: modules/agents/pi/pi.nix; /nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix.

The safest patch point is source-level patching before the TypeScript build, not post-install editing of generated JavaScript. The nixpkgs package builds from upstream TypeScript source and already runs the TypeScript build in buildPhase, so a patches = [...] or postPatch override can modify packages/coding-agent/src/modes/interactive/interactive-mode.ts and packages/coding-agent/src/utils/tools-manager.ts before compiled output is produced. Source: /nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix.

The tool lookup hardening belongs in the same package override if the layout patch already overrides Pi. Upstream tools-manager.ts currently treats a local tool path as available if the file exists and treats spawnSync(cmd, ["--version"]) as success whenever there is no spawn error, without requiring exit status 0. On NixOS this allowed an unusable generic Linux ~/.pi/agent/bin/fd to mask the working Nix fd on PATH. Source: /nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts.

A package override avoids the hardcoded-wrapper problem that a post-install copied package would create. If we copied the already-built installed package manually, its bin/pi script would still contain hardcoded store paths to the original .pi-wrapped and original Nix fd/rg inputs. Using pkgs.pi-coding-agent.overrideAttrs and the original derivation's postFixup lets Nix regenerate the wrapper for the patched output. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi; /nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix.

The likely dotfiles shape is:

let
  patchedPi = pkgs.pi-coding-agent.overrideAttrs (old: {
    patches = (old.patches or [ ]) ++ [ ./patches/pi-flex-spacer.patch ];
  });
in {
  home-manager.users.${user}.programs.pi-coding-agent = {
    enable = true;
    package = patchedPi;
    # existing settings unchanged
  };
}

If the patch is implemented with postPatch instead of a patch file, preserve any upstream old.postPatch first. A patch file is preferable for reviewability because it makes the layout and tool-lookup changes explicit.

Answer

Package the flex-spacer as a source-level patch to pkgs.pi-coding-agent and set home-manager.users.${user}.programs.pi-coding-agent.package to that overridden package in modules/agents/pi/pi.nix.

Do not package it as a separate extension. Do not use the throwaway copied tree under ~/.local/share for deployment. Do not copy the built package output and edit generated JavaScript unless no source-level override works, because the installed wrapper hardcodes store paths and Nix's original derivation already knows how to rebuild and rewrap Pi correctly.

Implementation notes

Create a reviewed patch file under the dotfiles Pi module, for example modules/agents/pi/patches/pi-flex-spacer.patch. Patch these upstream source files:

packages/coding-agent/src/modes/interactive/interactive-mode.ts
packages/coding-agent/src/utils/tools-manager.ts

Then override the package in modules/agents/pi/pi.nix and assign it to programs.pi-coding-agent.package.

The implementation ticket [[070-pi-ui-flex-spacer-pi-patch-task]] should prefer this packaging plan.

Limitations

This research verified the package option by evaluation and inspected the current nixpkgs package source. It did not build the final override or run the patched source-level derivation.

The upstream Pi source path was realized with nix build --no-link during research because the fetched source store path had not yet been materialized.

Citations

modules/agents/pi/pi.nix.
/nix/store/bzc7kf828kg6zlan92766rb2inciclc4-source/pkgs/by-name/pi/pi-coding-agent/package.nix.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/bin/pi.
/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/modes/interactive/interactive-mode.ts.
/nix/store/7dv5wnq7ncw0mrhv5cldj5v6lar7lis7-source/packages/coding-agent/src/utils/tools-manager.ts.

7.0 KiB Raw Blame History