Skip to content

The agent that grows with you

feat(nix): dev shell runs the pm-pinned tool set

ethernete2adc90f822f
diff --git a/.envrc b/.envrc
index 663714366d2..fd5648edb95 100644
--- a/.envrc
+++ b/.envrc
@@ -1,5 +1,5 @@
-watch_file pyproject.toml uv.lock hermes
+watch_file pyproject.toml uv.lock pm/ hermes_constants.py hermes_cli/venv_sync.py hermes_cli/ hermes_yaml.py hermes_platform/
watch_file package-lock.json package.json web/package.json ui-tui/package.json website/package.json apps/shared/package.json apps/desktop/package.json ui-tui/packages/hermes-ink/package.json
-watch_file flake.nix flake.lock nix/devShell.nix nix/tui.nix nix/package.nix nix/python.nix nix/hermes-agent.nix nix/desktop.nix
+watch_file flake.nix flake.lock nix/
use flake
diff --git a/nix/checks.nix b/nix/checks.nix
index 8e15e4f8a72..446084b4bab 100644
--- a/nix/checks.nix
+++ b/nix/checks.nix
@@ -165,6 +165,24 @@ json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
echo "ok" > $out/result
'';
+ # The pm artifacts are upstream glibc binaries. autoPatchelf rewrites
+ # their interpreter at build time, and this sandbox has no
+ # /lib64/ld-linux-x86-64.so.2 (that is host nix-ld), so exec'ing them
+ # here is the proof they run on a host that never enabled nix-ld.
+ pm-packages-exec = pkgs.runCommand "hermes-pm-packages-exec" { } ''
+ mkdir -p $out
+ if [ -e /lib64/ld-linux-x86-64.so.2 ]; then
+ echo "sandbox unexpectedly carries a host loader; this proves nothing" >&2
+ exit 1
+ fi
+ ${self'.packages.pm-uv}/bin/uv --version > $out/uv
+ ${self'.packages.pm-node}/bin/node --version > $out/node
+ ${self'.packages.pm-ffmpeg}/bin/ffmpeg -version > $out/ffmpeg
+ ${self'.packages.pm-ripgrep}/bin/rg --version > $out/rg
+ ${self'.packages.pm-python}/bin/python3 -c 'import ssl, sqlite3' > $out/python
+ cat $out/*
+ '';
+
# Verify the default package builds successfully (cross-platform).
# On Linux the runtime checks below already depend on the package,
# but this ensures darwin builders also build it during flake check.
diff --git a/nix/devShell.nix b/nix/devShell.nix
index d1c08750455..dd10d6cecc7 100644
--- a/nix/devShell.nix
+++ b/nix/devShell.nix
@@ -28,7 +28,6 @@
install -Dm755 ${../hermes} $out/bin/hermes
'')
self'.packages.sandbox
- uv
# Headless Wayland compositor for E2E tests (test:e2e:visual).
# cage renders a single client with no window management, so
# the Electron window opens at a fixed size without tiling.
@@ -43,18 +42,25 @@
]
++ self'.packages.default.passthru.devDeps;
shellHook = ''
+ # for the devshell to pick up the src (the pm hook reads it)
+ export HERMES_PYTHON_SRC_ROOT=$(git rev-parse --show-toplevel)
+
${hermesAgentDevShellHook}
${hermesNpmLib.mkNpmDevShellHook npmPackageJsonPaths}
# Force Node to use Nix's playwright-test binary instead of node_modules/.bin
export PATH="${pkgs.playwright-test}/bin:$PATH"
- # for the devshell to pick up the src
- export HERMES_PYTHON_SRC_ROOT=$(git rev-parse --show-toplevel)
+ # Let `uv run --active --no-sync` reuse the Nix-built venv instead of
+ # creating an empty project .venv. Named explicitly: `python` on PATH
+ # is the lock's interpreter, which is not inside a venv.
+ export VIRTUAL_ENV="${self'.packages.default.passthru.devPython}"
- # Let `uv run --active --no-sync` reuse Nix's provisioned Python
- # environment instead of creating an empty project .venv.
- export VIRTUAL_ENV="$(dirname "$(dirname "$(readlink -f "$(command -v python)")")")"
+ # The lock's interpreter is python-build-standalone, whose OpenSSL has
+ # no compiled-in NixOS trust store; point it at the CA bundle so
+ # urllib/httpx/requests verify certificates like the nixpkgs one.
+ export SSL_CERT_FILE="${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"
+ export NIX_SSL_CERT_FILE="$SSL_CERT_FILE"
echo "Hermes Agent dev shell in $HERMES_PYTHON_SRC_ROOT"
echo "Ready. Run 'hermes' or 'sandbox hermes' to start."
diff --git a/nix/hermes-agent.nix b/nix/hermes-agent.nix
index 0f7a4061c9e..d04371f1211 100644
--- a/nix/hermes-agent.nix
+++ b/nix/hermes-agent.nix
@@ -31,6 +31,8 @@
pyproject-nix,
pyproject-build-systems,
npm-lockfile-fix,
+ # nix/pm-packages.nix output: every pm/lock.json pin as a derivation.
+ pmPackages,
# Locked git revision of the flake source — embedded so banner.py can
# check for updates without needing a local .git directory. Null for
# impure / dirty builds where flakes can't determine a rev.
@@ -105,7 +107,13 @@ let
};
hermesNpmLib = callPackage ./lib.nix {
- inherit npm-lockfile-fix;
+ inherit npm-lockfile-fix pmPackages;
+ };
+
+ # npm 12.0.2 from the lock, wrapped onto the pm-pinned node so the dev
+ # shell's `npm` and `node` are the same generation.
+ npmPinned = callPackage ./npm-pinned.nix {
+ nodejs = pmPackages.node;
};
hermesTui = callPackage ./tui.nix {
@@ -313,6 +321,12 @@ stdenv.mkDerivation (finalAttrs: {
passthru =
let
devPython = (mkHermesVenv (extraDependencyGroups ++ [ "dev" ])).editableVenv;
+ # The shell's interpreter: the exact build pm/lock.json installs, not
+ # nixpkgs'. uv2nix structurally needs a nixpkgs interpreter to BUILD the
+ # venv, so the site-packages stay Nix-owned and only the interpreter the
+ # shell runs (and `hermes` uses) comes from the lock.
+ devSitePackages = "${devPython}/${sitePackagesPath}";
+ pmPython = pythonLock.pinned;
pm = writeShellApplication {
name = "pm";
text = ''
@@ -333,6 +347,9 @@ stdenv.mkDerivation (finalAttrs: {
installStampFile
pmRuntime
python
+ devPython
+ devSitePackages
+ pmPython
;
# `hermesDesktop` references `finalAttrs.finalPackage` (this whole
@@ -354,17 +371,42 @@ stdenv.mkDerivation (finalAttrs: {
};
devShellHook = ''
- export HERMES_PYTHON=${devPython}/bin/python3
+ export HERMES_PYTHON=${pmPython}/bin/python3
+ # Dependencies come from the Nix-built editable venv; only the
+ # interpreter is the lock's own build. PYTHONPATH rather than the
+ # venv's bin/python3, which is the nixpkgs interpreter.
+ export PYTHONPATH=${devSitePackages}:$HERMES_PYTHON_SRC_ROOT
'';
devDeps =
- runtimeDeps
- ++ [
- devPython
- pm
+ # The pinned tool set, straight from pm/lock.json: the shell runs the
+ # same uv, node, npm, ripgrep and ffmpeg `hermes pm install` provisions
+ # on a non-Nix host. nixpkgs still supplies what pm ships no Linux
+ # artifact for — git and openssh are win32-only pins — plus the
+ # platform tools Nix owns. package order matters: makeBinPath keeps
+ # the list order, and the pinned npm must win over the npm bundled
+ # inside the node artifact.
+ [
+ npmPinned
+ pmPackages.node
+ pmPackages.uv
+ pmPackages.ripgrep
+ pmPackages.ffmpeg
+ git
+ openssh
]
++ lib.optionals stdenv.isLinux [
+ wl-clipboard
+ xclip
cage # for running e2e tests without popping windows
+ ]
+ ++ [
+ # The lock's interpreter first: `python` in the shell is the build a
+ # real install runs. devPython stays on PATH for its console scripts
+ # (pytest, debugpy), which are bound to the Nix-built venv.
+ pmPython
+ devPython
+ pm
];
};
diff --git a/nix/lib.nix b/nix/lib.nix
index 45f08a9bef1..40f1ba841a5 100644
--- a/nix/lib.nix
+++ b/nix/lib.nix
@@ -24,27 +24,47 @@
writeShellScript,
coreutils,
callPackage,
- nodejs_26,
- symlinkJoin,
buildNpmPackage,
runCommand,
+ python3,
+ # pm/lock.json pins, used for node and npm.
+ pmPackages,
}:
let
repoRoot = ./..;
- npm12 = callPackage ./npm-pinned.nix { };
- node_gyp_11_4_0 = callPackage ./node-gyp-11-4-0.nix { };
- nodejs_26_npm_12 = symlinkJoin {
- name = "nodejs-26-npm-12";
- paths = [
- npm12
- nodejs_26
- ];
- inherit (nodejs_26) meta passthru;
+ # Every JS tool comes from pm/lock.json — the node the builds and the
+ # shipped app run on, plus npm wrapped onto it. nixpkgs supplies nothing
+ # here; node/npm have Linux artifacts in the lock.
+ pmNode = pmPackages.node;
+ npm12 = callPackage ./npm-pinned.nix { nodejs = pmNode; };
+ node_gyp_11_4_0 = callPackage ./node-gyp-11-4-0.nix { nodejs = nodejs; };
+ # bin/npm and bin/npx are the pinned npm; the rest of the tree (node,
+ # include/node headers, lib/node_modules/node's own bundled npm) is the
+ # pinned node. A plain symlinkJoin cannot express that: both paths carry
+ # bin/npm, so assemble it explicitly.
+ nodejs = (runCommand "nodejs-26-npm-12" {
+ # buildNpmPackage reads nodejs.meta.platforms; the pm derivation carries no
+ # meta, and the lock has artifacts for every platform.
+ meta = {
+ platforms = lib.platforms.all;
+ mainProgram = "node";
+ };
+ } ''
+ cp -rs ${pmNode} $out
+ # cp -r copies the store's read-only directory modes; make the farm's own
+ # directories writable so bin/npm and bin/npx can be replaced. Only real
+ # directories are chmodded, never the symlink targets.
+ find $out -type d -exec chmod u+w {} +
+ rm -f $out/bin/npm $out/bin/npx
+ ln -s ${npm12}/bin/npm $out/bin/npm
+ ln -s ${npm12}/bin/npx $out/bin/npx
+ '') // {
+ # buildNpmPackage puts nodejs.python (its build interpreter) on the npm
+ # hook's PATH; the pm node derivation has no such attribute.
+ python = python3;
};
- nodejs = nodejs_26_npm_12;
-
# Patched hook: just a new derivation that copies and patches the script
patchedNpmConfigHook = runCommand "npm-config-hook-patched" { } ''
mkdir -p $out/nix-support
diff --git a/nix/npm-pinned.nix b/nix/npm-pinned.nix
index 020cc089ab6..b2b422c0cdb 100644
--- a/nix/npm-pinned.nix
+++ b/nix/npm-pinned.nix
@@ -3,6 +3,10 @@
makeWrapper,
fetchurl,
nodejs_26,
+ # The interpreter the wrapper launches. Defaults to nixpkgs, but the dev
+ # shell passes the pm-pinned node so `npm` runs on the same node as the
+ # rest of that environment.
+ nodejs ? nodejs_26,
}:
let
# pm/lock.json is the one pin table. Every artifact carries its resolved
@@ -29,9 +33,9 @@ stdenv.mkDerivation {
cp -r . $out/lib/npm/
mkdir -p $out/bin
- makeWrapper ${nodejs_26}/bin/node $out/bin/npm \
+ makeWrapper ${nodejs}/bin/node $out/bin/npm \
--add-flags "$out/lib/npm/bin/npm-cli.js"
- makeWrapper ${nodejs_26}/bin/node $out/bin/npx \
+ makeWrapper ${nodejs}/bin/node $out/bin/npx \
--add-flags "$out/lib/npm/bin/npx-cli.js"
'';
}
diff --git a/nix/packages.nix b/nix/packages.nix
index 47758c54d1a..29641fa663a 100644
--- a/nix/packages.nix
+++ b/nix/packages.nix
@@ -37,6 +37,7 @@
minimal = pkgs.callPackage ./hermes-agent.nix {
inherit (inputs) uv2nix pyproject-nix pyproject-build-systems;
npm-lockfile-fix = inputs'.npm-lockfile-fix.packages.default;
+ inherit pmPackages;
inherit
rev
branch
@@ -74,6 +75,7 @@
node-gyp =
(pkgs.callPackage ./lib.nix {
inherit (pkgs) npm-lockfile-fix;
+ inherit pmPackages;
}).node-gyp;
default = full;
diff --git a/nix/pm-packages.nix b/nix/pm-packages.nix
index c217c9c2526..93dbaf2f04e 100644
--- a/nix/pm-packages.nix
+++ b/nix/pm-packages.nix
@@ -3,6 +3,8 @@
stdenv,
fetchurl,
unzip,
+ autoPatchelfHook,
+ patchelf,
}:
# The thin translation layer: pm/lock.json -> one fetched, unpacked
# derivation per package for this nix system. Nothing here knows versions,
@@ -41,6 +43,12 @@ let
isArchive = artifact:
lib.any (suffix: lib.hasSuffix suffix artifact.url) [ ".tar.gz" ".tgz" ".tar.xz" ".txz" ".tar.bz2" ".zip" ];
+ # python-build-standalone finds its own libpython through an $ORIGIN/../lib
+ # RPATH. autoPatchelf rewrites that into a literal path and leaves the
+ # interpreter unable to load its own stdlib, so for it the ELF interpreter
+ # and RPATH are set explicitly: $ORIGIN stays, and Nix's glibc is appended.
+ originRpath = name: name == "python";
+
derive = name: pin: artifacts:
stdenv.mkDerivation {
pname = name;
@@ -56,13 +64,62 @@ let
# pm merges them into one store entry.
sourceRoot = ".";
nativeBuildInputs =
- lib.optional (lib.any (a: lib.hasSuffix ".zip" a.url) artifacts) unzip;
+ lib.optionals (originRpath name) [ patchelf ]
+ ++ lib.optional (!originRpath name) autoPatchelfHook
+ ++ lib.optional (lib.any (a: lib.hasSuffix ".zip" a.url) artifacts) unzip;
+ # The upstream tarballs are glibc-linked (interpreter
+ # /lib64/ld-linux-x86-64.so.2, which only exists on a host with nix-ld).
+ # Their whole dependency set is glibc + libstdc++/libgcc/libatomic, so
+ # autoPatchelfHook rewrites the interpreter and RPATH at build time and
+ # every consumer runs them on a plain NixOS host. ripgrep ships musl-
+ # static and is left untouched.
+ buildInputs = [ stdenv.cc.cc.lib ];
+ # Keep the RPATH written below byte for byte; the fixup shrinker cannot
+ # tell that $ORIGIN/../lib is load-bearing.
+ dontPatchELF = originRpath name;
+ postFixup = lib.optionalString (originRpath name) ''
+ for exe in $out/bin/*; do
+ if [ -f "$exe" ] && patchelf --print-interpreter "$exe" >/dev/null 2>&1; then
+ patchelf \
+ --set-interpreter ${stdenv.cc.bintools.dynamicLinker} \
+ --set-rpath '$ORIGIN/../lib:${stdenv.cc.libc}/lib' \
+ "$exe"
+ fi
+ done
+ '';
dontBuild = true;
dontConfigure = true;
installPhase = ''
mkdir -p $out
cp -r . $out/
+
+ # Archives wrap their tree in one versioned directory
+ # (`uv-x86_64-unknown-linux-gnu/`, `node-v26.12.1-linux-x64/`, `package/`).
+ # pm's store strips it; mirror that so `$out/bin` is the entry point
+ # instead of `$out/<archive-name>/bin`. `env-vars` is Nix's own file
+ # in $out by the time installPhase runs, so it never counts as content.
+ shopt -s dotglob nullglob
+ wrapped=() stray=()
+ for entry in "$out"/*; do
+ [ "$(basename "$entry")" = env-vars ] && continue
+ if [ -d "$entry" ]; then wrapped+=("$entry"); else stray+=("$entry"); fi
+ done
+ if [ ''${#wrapped[@]} -eq 1 ] && [ ''${#stray[@]} -eq 0 ]; then
+ mv "''${wrapped[0]}"/* "$out"/
+ rmdir "''${wrapped[0]}"
+ fi
+ shopt -u dotglob nullglob
+
+ # Entry points also disagree: node and ffmpeg carry `bin/`, uv and
+ # ripgrep put their executables at the root. PATH composition
+ # (mkShell, lib.makeBinPath) only reads `bin`, so link root-level
+ # executables into it.
+ mkdir -p $out/bin
+ for exe in "$out"/*; do
+ [ -f "$exe" ] && [ -x "$exe" ] || continue
+ ln -sf "../$(basename "$exe")" "$out/bin/$(basename "$exe")"
+ done
'';
};
in
diff --git a/nix/pythonLock.nix b/nix/pythonLock.nix
index ac91b641238..6297e48bc01 100644
--- a/nix/pythonLock.nix
+++ b/nix/pythonLock.nix
@@ -37,4 +37,11 @@ in
inherit family;
interpreter = selectPython family pkgs;
+
+ # The interpreter the lock itself installs. uv2nix cannot build a venv
+ # against it (a tarball interpreter has no `pkgs`), so the venv keeps
+ # `interpreter` while a shell that must match a real runtime takes this.
+ # Derived here, not passed in: every caller of this file reads `interpreter`
+ # and nothing else should have to know about the pinned build.
+ pinned = (pkgs.callPackage ./pm-packages.nix { }).python;
}
diff --git a/website/docs/reference/package-management.md b/website/docs/reference/package-management.md
index 38f8f98a0b4..e4d8c81cc98 100644
--- a/website/docs/reference/package-management.md
+++ b/website/docs/reference/package-management.md
@@ -513,7 +513,10 @@ references. `--offline` and `--cache` control dependency acquisition.
For application environment builds, PM must already be able to start in the
invoking Python. These builds are not an interpreter bootstrap. They do not modify a running application's
imports or replace its selected environment. Nix's declarative uv2nix builds
-remain Nix-owned. Package-manager commands for unrelated projects or agent
+remain Nix-owned: `nix develop` still builds its dependencies with uv2nix, but
+runs them on the interpreter `pm/lock.json` pins (uv2nix cannot build a venv
+against a tarball interpreter, so only the interpreter comes from the lock).
+Package-manager commands for unrelated projects or agent
sandboxes do not manage Hermes itself.
## Commands