Initial import of NousResearch/hermes-agent

nix/checks.nix

@@ -0,0 +1,491 @@
+# nix/checks.nix — Build-time verification tests
+#
+# Checks are Linux-only: the full Python venv (via uv2nix) includes
+# transitive deps like onnxruntime that lack compatible wheels on
+# aarch64-darwin. The package and devShell still work on macOS.
+{ inputs, ... }: {
+  perSystem = { pkgs, lib, self', ... }:
+    let
+      hermes-agent = self'.packages.default;
+      hermesVenv = hermes-agent.hermesVenv;
+
+      configMergeScript = pkgs.callPackage ./configMergeScript.nix { };
+
+      # Auto-generated config key reference — always in sync with Python
+      configKeys = pkgs.runCommand "hermes-config-keys" {} ''
+        set -euo pipefail
+        export HOME=$TMPDIR
+        ${hermesVenv}/bin/python3 -c '
+import json, sys
+from hermes_cli.config import DEFAULT_CONFIG
+
+def leaf_paths(d, prefix=""):
+    paths = []
+    for k, v in sorted(d.items()):
+        path = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, dict) and v:
+            paths.extend(leaf_paths(v, path))
+        else:
+            paths.append(path)
+    return paths
+
+json.dump(sorted(leaf_paths(DEFAULT_CONFIG)), sys.stdout, indent=2)
+' > $out
+      '';
+    in {
+      packages.configKeys = configKeys;
+
+      checks = {
+        # Cross-platform evaluation — catches "not supported for interpreter"
+        # errors (e.g. sphinx dropping python311) without needing a darwin builder.
+        # Evaluation is pure and instant; it doesn't build anything.
+        cross-eval = let
+          targetSystems = builtins.filter
+            (s: inputs.self.packages ? ${s})
+            [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" "x86_64-darwin" ];
+          tryEvalPkg = sys:
+            let pkg = inputs.self.packages.${sys}.default;
+            in builtins.tryEval (builtins.seq pkg.drvPath true);
+          results = map (sys: { inherit sys; result = tryEvalPkg sys; }) targetSystems;
+          failures = builtins.filter (r: !r.result.success) results;
+          failMsg = lib.concatMapStringsSep "\n" (r: "  - ${r.sys}") failures;
+        in pkgs.runCommand "hermes-cross-eval" { } (
+          if failures != [] then
+            throw "Package fails to evaluate on:\n${failMsg}"
+          else ''
+            echo "PASS: package evaluates on all ${toString (builtins.length targetSystems)} platforms"
+            mkdir -p $out
+            echo "ok" > $out/result
+          ''
+        );
+      } // lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
+        # Verify binaries exist and are executable
+        package-contents = pkgs.runCommand "hermes-package-contents" { } ''
+          set -e
+          echo "=== Checking binaries ==="
+          test -x ${hermes-agent}/bin/hermes || (echo "FAIL: hermes binary missing"; exit 1)
+          test -x ${hermes-agent}/bin/hermes-agent || (echo "FAIL: hermes-agent binary missing"; exit 1)
+          echo "PASS: All binaries present"
+
+          echo "=== Checking version ==="
+          ${hermes-agent}/bin/hermes version 2>&1 | grep -qi "hermes" || (echo "FAIL: version check"; exit 1)
+          echo "PASS: Version check"
+
+          echo "=== All checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify every pyproject.toml [project.scripts] entry has a wrapped binary
+        entry-points-sync = pkgs.runCommand "hermes-entry-points-sync" { } ''
+          set -e
+          echo "=== Checking entry points match pyproject.toml [project.scripts] ==="
+          for bin in hermes hermes-agent hermes-acp; do
+            test -x ${hermes-agent}/bin/$bin || (echo "FAIL: $bin binary missing from Nix package"; exit 1)
+            echo "PASS: $bin present"
+          done
+
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify CLI subcommands are accessible
+        cli-commands = pkgs.runCommand "hermes-cli-commands" { } ''
+          set -e
+          export HOME=$(mktemp -d)
+
+          echo "=== Checking hermes --help ==="
+          ${hermes-agent}/bin/hermes --help 2>&1 | grep -q "gateway" || (echo "FAIL: gateway subcommand missing"; exit 1)
+          ${hermes-agent}/bin/hermes --help 2>&1 | grep -q "config" || (echo "FAIL: config subcommand missing"; exit 1)
+          echo "PASS: All subcommands accessible"
+
+          echo "=== All CLI checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify bundled skills are present in the package
+        bundled-skills = pkgs.runCommand "hermes-bundled-skills" { } ''
+          set -e
+          echo "=== Checking bundled skills ==="
+          test -d ${hermes-agent}/share/hermes-agent/skills || (echo "FAIL: skills directory missing"; exit 1)
+          echo "PASS: skills directory exists"
+
+          SKILL_COUNT=$(find ${hermes-agent}/share/hermes-agent/skills -name "SKILL.md" | wc -l)
+          test "$SKILL_COUNT" -gt 0 || (echo "FAIL: no SKILL.md files found in skills directory"; exit 1)
+          echo "PASS: $SKILL_COUNT bundled skills found"
+
+          grep -q "HERMES_BUNDLED_SKILLS" ${hermes-agent}/bin/hermes || \
+            (echo "FAIL: HERMES_BUNDLED_SKILLS not in wrapper"; exit 1)
+          echo "PASS: HERMES_BUNDLED_SKILLS set in wrapper"
+
+          echo "=== All bundled skills checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify bundled plugins (platforms, memory, context_engine) are present
+        bundled-plugins = pkgs.runCommand "hermes-bundled-plugins" { } ''
+          set -e
+          echo "=== Checking bundled plugins ==="
+          test -d ${hermes-agent}/share/hermes-agent/plugins || (echo "FAIL: plugins directory missing"; exit 1)
+          echo "PASS: plugins directory exists"
+
+          test -f ${hermes-agent}/share/hermes-agent/plugins/platforms/irc/plugin.yaml || \
+            (echo "FAIL: irc plugin manifest missing"; exit 1)
+          echo "PASS: irc plugin manifest present"
+
+          grep -q "HERMES_BUNDLED_PLUGINS" ${hermes-agent}/bin/hermes || \
+            (echo "FAIL: HERMES_BUNDLED_PLUGINS not in wrapper"; exit 1)
+          echo "PASS: HERMES_BUNDLED_PLUGINS set in wrapper"
+
+          echo "=== All bundled plugins checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify bundled TUI is present and compiled
+        bundled-tui = pkgs.runCommand "hermes-bundled-tui" { } ''
+          set -e
+          echo "=== Checking bundled TUI ==="
+          test -d ${hermes-agent}/ui-tui || (echo "FAIL: ui-tui directory missing"; exit 1)
+          echo "PASS: ui-tui directory exists"
+
+          test -f ${hermes-agent}/ui-tui/dist/entry.js || (echo "FAIL: compiled entry.js missing"; exit 1)
+          echo "PASS: compiled entry.js present"
+
+          # self-contained bundle; no runtime node_modules expected
+
+          grep -q "HERMES_TUI_DIR" ${hermes-agent}/bin/hermes || \
+            (echo "FAIL: HERMES_TUI_DIR not in wrapper"; exit 1)
+          echo "PASS: HERMES_TUI_DIR set in wrapper"
+
+          echo "=== All bundled TUI checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify HERMES_NODE is set in wrapper and points to Node 20+
+        # (string-width uses the /v regex flag which requires Node 20+)
+        hermes-node = pkgs.runCommand "hermes-node-version" { } ''
+          set -e
+          echo "=== Checking HERMES_NODE in wrapper ==="
+          grep -q "HERMES_NODE" ${hermes-agent}/bin/hermes || \
+            (echo "FAIL: HERMES_NODE not set in wrapper"; exit 1)
+          echo "PASS: HERMES_NODE present in wrapper"
+
+          HERMES_NODE=$(sed -n "s/^export HERMES_NODE='\(.*\)'/\1/p" ${hermes-agent}/bin/hermes)
+          test -x "$HERMES_NODE" || (echo "FAIL: HERMES_NODE=$HERMES_NODE not executable"; exit 1)
+          echo "PASS: HERMES_NODE executable at $HERMES_NODE"
+
+          NODE_MAJOR=$("$HERMES_NODE" --version | sed 's/^v//' | cut -d. -f1)
+          test "$NODE_MAJOR" -ge 20 || \
+            (echo "FAIL: Node v$NODE_MAJOR < 20, TUI needs /v regex flag support"; exit 1)
+          echo "PASS: Node v$NODE_MAJOR >= 20"
+
+          echo "=== All HERMES_NODE checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify HERMES_MANAGED guard works on all mutation commands
+        managed-guard = pkgs.runCommand "hermes-managed-guard" { } ''
+          set -e
+          export HOME=$(mktemp -d)
+
+          check_blocked() {
+            local label="$1"
+            shift
+            OUTPUT=$(HERMES_MANAGED=true "$@" 2>&1 || true)
+            echo "$OUTPUT" | grep -q "managed by NixOS" || (echo "FAIL: $label not guarded"; echo "$OUTPUT"; exit 1)
+            echo "PASS: $label blocked in managed mode"
+          }
+
+          echo "=== Checking HERMES_MANAGED guards ==="
+          check_blocked "config set" ${hermes-agent}/bin/hermes config set model foo
+          check_blocked "config edit" ${hermes-agent}/bin/hermes config edit
+
+          echo "=== All guard checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify extraPythonPackages PYTHONPATH injection
+        extra-python-packages = let
+          testPkg = pkgs.python312Packages.pyfiglet;
+          hermesWithExtra = hermes-agent.override {
+            extraPythonPackages = [ testPkg ];
+          };
+        in pkgs.runCommand "hermes-extra-python-packages" { } ''
+          set -e
+          echo "=== Checking extraPythonPackages PYTHONPATH injection ==="
+
+          grep -q "PYTHONPATH" ${hermesWithExtra}/bin/hermes || \
+            (echo "FAIL: PYTHONPATH not in wrapper"; exit 1)
+          echo "PASS: PYTHONPATH present in wrapper"
+
+          grep -q "${testPkg}" ${hermesWithExtra}/bin/hermes || \
+            (echo "FAIL: test package path not in PYTHONPATH"; exit 1)
+          echo "PASS: test package path found in wrapper"
+
+          echo "=== Checking base package has no PYTHONPATH ==="
+          if grep -q "PYTHONPATH" ${hermes-agent}/bin/hermes; then
+            echo "FAIL: base package should not have PYTHONPATH"; exit 1
+          fi
+          echo "PASS: base package clean"
+
+          echo "=== All extraPythonPackages checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Verify extraDependencyGroups passes through to python.nix
+        extra-dependency-groups = let
+          hermesWithGroups = hermes-agent.override {
+            extraDependencyGroups = [ "honcho" ];
+          };
+        in pkgs.runCommand "hermes-extra-dependency-groups" { } ''
+          set -e
+          echo "=== Checking extraDependencyGroups override evaluates ==="
+
+          # Eval-only: verify the override produces valid derivation paths
+          # without building the full venv (which is expensive and redundant
+          # since the mechanism is just list concatenation into python.nix).
+          echo "derivation: ${hermesWithGroups}"
+          echo "venv: ${hermesWithGroups.hermesVenv}"
+          echo "PASS: extraDependencyGroups override evaluates cleanly"
+
+          echo "=== All extraDependencyGroups checks passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # Regression guard: messaging deps live outside [all], so the
+        # #messaging variant must actually ship discord.py — otherwise
+        # `nix profile install .#messaging` regresses to the broken default.
+        messaging-variant = pkgs.runCommand "hermes-messaging-variant" { } ''
+          set -e
+          echo "=== Checking discord.py importable from messaging variant ==="
+          ${self'.packages.messaging.hermesVenv}/bin/python3 -c \
+            "import discord; print(discord.__version__)"
+          echo "PASS: discord.py importable from messaging variant venv"
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+
+        # ── Config merge + round-trip test ────────────────────────────────
+        # Tests the merge script (Nix activation behavior) across 7
+        # scenarios, then verifies Python's load_config() reads correctly.
+        config-roundtrip = let
+          # Nix settings used across scenarios
+          nixSettings = pkgs.writeText "nix-settings.json" (builtins.toJSON {
+            model = "test/nix-model";
+            toolsets = ["nix-toolset"];
+            terminal = { backend = "docker"; timeout = 999; };
+            mcp_servers = {
+              nix-server = { command = "echo"; args = ["nix"]; };
+            };
+          });
+
+          # Pre-built YAML fixtures for each scenario
+          fixtureB = pkgs.writeText "fixture-b.yaml" ''
+            model: "old-model"
+            mcp_servers:
+              old-server:
+                url: "http://old"
+          '';
+          fixtureC = pkgs.writeText "fixture-c.yaml" ''
+            skills:
+              disabled:
+                - skill-a
+                - skill-b
+            session_reset:
+              mode: idle
+              idle_minutes: 30
+            streaming:
+              enabled: true
+            fallback_model:
+              provider: openrouter
+              model: test-fallback
+          '';
+          fixtureD = pkgs.writeText "fixture-d.yaml" ''
+            model: "user-model"
+            skills:
+              disabled:
+                - skill-x
+            streaming:
+              enabled: true
+              transport: edit
+          '';
+          fixtureE = pkgs.writeText "fixture-e.yaml" ''
+            mcp_servers:
+              user-server:
+                url: "http://user-mcp"
+              nix-server:
+                command: "old-cmd"
+                args: ["old"]
+          '';
+          fixtureF = pkgs.writeText "fixture-f.yaml" ''
+            terminal:
+              cwd: "/user/path"
+              custom_key: "preserved"
+              env_passthrough:
+                - USER_VAR
+          '';
+
+        in pkgs.runCommand "hermes-config-roundtrip" {
+          nativeBuildInputs = [ pkgs.jq ];
+        } ''
+          set -e
+          export HOME=$(mktemp -d)
+          ERRORS=""
+
+          fail() { ERRORS="$ERRORS\nFAIL: $1"; }
+
+          # Helper: run merge then load with Python, output merged JSON
+          merge_and_load() {
+            local hermes_home="$1"
+            export HERMES_HOME="$hermes_home"
+            ${configMergeScript} ${nixSettings} "$hermes_home/config.yaml"
+            ${hermesVenv}/bin/python3 -c '
+import json, sys
+from hermes_cli.config import load_config
+json.dump(load_config(), sys.stdout, default=str)
+'
+          }
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario A: Fresh install — no existing config.yaml
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario A: Fresh install ==="
+          A_HOME=$(mktemp -d)
+          A_CONFIG=$(merge_and_load "$A_HOME")
+
+          echo "$A_CONFIG" | jq -e '.model == "test/nix-model"' > /dev/null \
+            || fail "A: model not set from Nix"
+          echo "$A_CONFIG" | jq -e '.mcp_servers."nix-server".command == "echo"' > /dev/null \
+            || fail "A: MCP nix-server missing"
+          echo "PASS: Scenario A"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario B: Nix keys override existing values
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario B: Nix overrides ==="
+          B_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureB} "$B_HOME/config.yaml"
+          B_CONFIG=$(merge_and_load "$B_HOME")
+
+          echo "$B_CONFIG" | jq -e '.model == "test/nix-model"' > /dev/null \
+            || fail "B: Nix model did not override"
+          echo "PASS: Scenario B"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario C: User-only keys preserved
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario C: User keys preserved ==="
+          C_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureC} "$C_HOME/config.yaml"
+          C_CONFIG=$(merge_and_load "$C_HOME")
+
+          echo "$C_CONFIG" | jq -e '.skills.disabled == ["skill-a", "skill-b"]' > /dev/null \
+            || fail "C: skills.disabled not preserved"
+          echo "$C_CONFIG" | jq -e '.session_reset.mode == "idle"' > /dev/null \
+            || fail "C: session_reset.mode not preserved"
+          echo "$C_CONFIG" | jq -e '.session_reset.idle_minutes == 30' > /dev/null \
+            || fail "C: session_reset.idle_minutes not preserved"
+          echo "$C_CONFIG" | jq -e '.streaming.enabled == true' > /dev/null \
+            || fail "C: streaming.enabled not preserved"
+          echo "$C_CONFIG" | jq -e '.fallback_model.provider == "openrouter"' > /dev/null \
+            || fail "C: fallback_model not preserved"
+          echo "PASS: Scenario C"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario D: Mixed — Nix wins for its keys, user keys preserved
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario D: Mixed merge ==="
+          D_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureD} "$D_HOME/config.yaml"
+          D_CONFIG=$(merge_and_load "$D_HOME")
+
+          echo "$D_CONFIG" | jq -e '.model == "test/nix-model"' > /dev/null \
+            || fail "D: Nix model did not override user model"
+          echo "$D_CONFIG" | jq -e '.skills.disabled == ["skill-x"]' > /dev/null \
+            || fail "D: user skills not preserved"
+          echo "$D_CONFIG" | jq -e '.streaming.enabled == true' > /dev/null \
+            || fail "D: user streaming not preserved"
+          echo "PASS: Scenario D"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario E: MCP additive merge
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario E: MCP additive merge ==="
+          E_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureE} "$E_HOME/config.yaml"
+          E_CONFIG=$(merge_and_load "$E_HOME")
+
+          echo "$E_CONFIG" | jq -e '.mcp_servers."user-server".url == "http://user-mcp"' > /dev/null \
+            || fail "E: user MCP server not preserved"
+          echo "$E_CONFIG" | jq -e '.mcp_servers."nix-server".command == "echo"' > /dev/null \
+            || fail "E: Nix MCP server did not override same-name user server"
+          echo "$E_CONFIG" | jq -e '.mcp_servers."nix-server".args == ["nix"]' > /dev/null \
+            || fail "E: Nix MCP server args wrong"
+          echo "PASS: Scenario E"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario F: Nested deep merge
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario F: Nested deep merge ==="
+          F_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureF} "$F_HOME/config.yaml"
+          F_CONFIG=$(merge_and_load "$F_HOME")
+
+          echo "$F_CONFIG" | jq -e '.terminal.backend == "docker"' > /dev/null \
+            || fail "F: Nix terminal.backend did not override"
+          echo "$F_CONFIG" | jq -e '.terminal.timeout == 999' > /dev/null \
+            || fail "F: Nix terminal.timeout did not override"
+          echo "$F_CONFIG" | jq -e '.terminal.custom_key == "preserved"' > /dev/null \
+            || fail "F: terminal.custom_key not preserved"
+          echo "$F_CONFIG" | jq -e '.terminal.cwd == "/user/path"' > /dev/null \
+            || fail "F: user terminal.cwd not preserved when Nix does not set it"
+          echo "$F_CONFIG" | jq -e '.terminal.env_passthrough == ["USER_VAR"]' > /dev/null \
+            || fail "F: user terminal.env_passthrough not preserved"
+          echo "PASS: Scenario F"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Scenario G: Idempotency — merging twice yields the same result
+          # ═══════════════════════════════════════════════════════════════
+          echo "=== Scenario G: Idempotency ==="
+          G_HOME=$(mktemp -d)
+          install -m 0644 ${fixtureD} "$G_HOME/config.yaml"
+          ${configMergeScript} ${nixSettings} "$G_HOME/config.yaml"
+          FIRST=$(cat "$G_HOME/config.yaml")
+          ${configMergeScript} ${nixSettings} "$G_HOME/config.yaml"
+          SECOND=$(cat "$G_HOME/config.yaml")
+
+          if [ "$FIRST" != "$SECOND" ]; then
+            fail "G: second merge produced different output"
+            echo "--- first ---"
+            echo "$FIRST"
+            echo "--- second ---"
+            echo "$SECOND"
+          fi
+          echo "PASS: Scenario G"
+
+          # ═══════════════════════════════════════════════════════════════
+          # Report
+          # ═══════════════════════════════════════════════════════════════
+          if [ -n "$ERRORS" ]; then
+            echo ""
+            echo "FAILURES:"
+            echo -e "$ERRORS"
+            exit 1
+          fi
+
+          echo ""
+          echo "=== All 7 merge scenarios passed ==="
+          mkdir -p $out
+          echo "ok" > $out/result
+        '';
+      };
+    };
+}

nix/configMergeScript.nix

@@ -0,0 +1,33 @@
+# nix/configMergeScript.nix — Deep-merge Nix settings into existing config.yaml
+#
+# Used by the NixOS module activation script and by checks.nix tests.
+# Nix keys override; user-added keys (skills, streaming, etc.) are preserved.
+{ pkgs }:
+pkgs.writeScript "hermes-config-merge" ''
+  #!${pkgs.python3.withPackages (ps: [ ps.pyyaml ])}/bin/python3
+  import json, yaml, sys
+  from pathlib import Path
+
+  nix_json, config_path = sys.argv[1], Path(sys.argv[2])
+
+  with open(nix_json) as f:
+      nix = json.load(f)
+
+  existing = {}
+  if config_path.exists():
+      with open(config_path) as f:
+          existing = yaml.safe_load(f) or {}
+
+  def deep_merge(base, override):
+      result = dict(base)
+      for k, v in override.items():
+          if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+              result[k] = deep_merge(result[k], v)
+          else:
+              result[k] = v
+      return result
+
+  merged = deep_merge(existing, nix)
+  with open(config_path, "w") as f:
+      yaml.dump(merged, f, default_flow_style=False, sort_keys=False)
+''

nix/devShell.nix

@@ -0,0 +1,30 @@
+# nix/devShell.nix — Dev shell that delegates setup to each package
+#
+# Each package in inputsFrom might expose passthru.devShellHook — a bash snippet
+# with stamp-checked setup logic. This file collects and runs them all.
+{ ... }:
+{
+  perSystem =
+    { pkgs, self', ... }:
+    let
+      packages = builtins.attrValues self'.packages;
+    in
+    {
+      devShells.default = pkgs.mkShell {
+        inputsFrom = packages;
+        packages = with pkgs; [
+          uv
+        ];
+        shellHook =
+          let
+            hooks = map (p: p.passthru.devShellHook or "") packages;
+            combined = pkgs.lib.concatStringsSep "\n" (builtins.filter (h: h != "") hooks);
+          in
+          ''
+            echo "Hermes Agent dev shell"
+            ${combined}
+            echo "Ready. Run 'hermes' to start."
+          '';
+      };
+    };
+}

nix/hermes-agent.nix

@@ -0,0 +1,220 @@
+# nix/hermes-agent.nix — Overridable Hermes Agent package
+#
+# callPackage auto-wires nixpkgs args; flake inputs are passed explicitly.
+# Users override via:
+#   pkgs.hermes-agent.override { extraPythonPackages = [...]; }
+#   pkgs.hermes-agent.override { extraDependencyGroups = [ "hindsight" ]; }
+{
+  lib,
+  stdenv,
+  makeWrapper,
+  callPackage,
+  python312,
+  nodejs_22,
+  ripgrep,
+  git,
+  openssh,
+  ffmpeg,
+  tirith,
+
+  # linux-only deps
+  wl-clipboard,
+  xclip,
+
+  # Flake inputs — passed explicitly by packages.nix and overlays.nix
+  uv2nix,
+  pyproject-nix,
+  pyproject-build-systems,
+  npm-lockfile-fix,
+  # 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.
+  rev ? null,
+  # Overridable parameters
+  extraPythonPackages ? [ ],
+  extraDependencyGroups ? [ ],
+}:
+let
+  nodejs = nodejs_22;
+  hermesVenv = callPackage ./python.nix {
+    inherit uv2nix pyproject-nix pyproject-build-systems;
+    dependency-groups = [ "all" ] ++ extraDependencyGroups;
+  };
+
+  hermesNpmLib = callPackage ./lib.nix {
+    inherit npm-lockfile-fix nodejs;
+  };
+
+  hermesTui = callPackage ./tui.nix {
+    inherit hermesNpmLib;
+  };
+
+  hermesWeb = callPackage ./web.nix {
+    inherit hermesNpmLib;
+  };
+
+  bundledSkills = lib.cleanSourceWith {
+    src = ../skills;
+    filter = path: _type: !(lib.hasInfix "/index-cache/" path);
+  };
+
+  # Import bundled plugins (memory, context_engine, platforms/*).  Keeping
+  # them out of the Python site-packages keeps import semantics identical
+  # to a dev checkout — the loader reads them from HERMES_BUNDLED_PLUGINS.
+  bundledPlugins = lib.cleanSourceWith {
+    src = ../plugins;
+    filter = path: _type: !(lib.hasInfix "/__pycache__/" path);
+  };
+
+  runtimeDeps = [
+    nodejs
+    ripgrep
+    git
+    openssh
+    ffmpeg
+    tirith
+  ]
+  ++ lib.optionals stdenv.isLinux [
+    wl-clipboard
+    xclip
+  ];
+
+  runtimePath = lib.makeBinPath runtimeDeps;
+
+  sitePackagesPath = python312.sitePackages;
+
+  # Walk propagatedBuildInputs to include transitive Python deps in PYTHONPATH.
+  # Without this, a plugin listing e.g. requests as a dep would fail at runtime
+  # if requests isn't already in the sealed uv2nix venv.
+  allExtraPythonPackages = python312.pkgs.requiredPythonModules extraPythonPackages;
+
+  pythonPath = lib.makeSearchPath sitePackagesPath allExtraPythonPackages;
+
+  pyprojectHash = builtins.hashString "sha256" (builtins.readFile ../pyproject.toml);
+  uvLockHash =
+    if builtins.pathExists ../uv.lock then
+      builtins.hashString "sha256" (builtins.readFile ../uv.lock)
+    else
+      "none";
+  checkPackageCollisions = ''
+    import pathlib, sys, re
+
+    def canonical(name):
+        return re.sub(r'[-_.]+', '-', name).lower()
+
+    # Collect core venv package names
+    core = set()
+    venv_sp = pathlib.Path('${hermesVenv}/${sitePackagesPath}')
+    for di in venv_sp.glob('*.dist-info'):
+        meta = di / 'METADATA'
+        if meta.exists():
+            for line in meta.read_text().splitlines():
+                if line.startswith('Name:'):
+                    core.add(canonical(line.split(':', 1)[1].strip()))
+                    break
+
+    # Check each extra package for collisions
+    extras_dirs = [${lib.concatMapStringsSep ", " (p: "'${toString p}'") allExtraPythonPackages}]
+    for edir in extras_dirs:
+        sp = pathlib.Path(edir) / '${sitePackagesPath}'
+        if not sp.exists():
+            continue
+        for di in sp.glob('*.dist-info'):
+            meta = di / 'METADATA'
+            if not meta.exists():
+                continue
+            for line in meta.read_text().splitlines():
+                if line.startswith('Name:'):
+                    pkg = canonical(line.split(':', 1)[1].strip())
+                    if pkg in core:
+                        print(f'ERROR: plugin package \"{pkg}\" collides with a package in hermes sealed venv', file=sys.stderr)
+                        print(f'  from: {di}', file=sys.stderr)
+                        print(f'  Remove this dependency from extraPythonPackages.', file=sys.stderr)
+                        sys.exit(1)
+                    break
+
+    print('No collisions found.')
+  '';
+in
+stdenv.mkDerivation {
+  pname = "hermes-agent";
+  version = (fromTOML (builtins.readFile ../pyproject.toml)).project.version;
+
+  dontUnpack = true;
+  dontBuild = true;
+  nativeBuildInputs = [ makeWrapper ];
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir -p $out/share/hermes-agent $out/bin
+    cp -r ${bundledSkills} $out/share/hermes-agent/skills
+    cp -r ${bundledPlugins} $out/share/hermes-agent/plugins
+    cp -r ${hermesWeb} $out/share/hermes-agent/web_dist
+
+    mkdir -p $out/ui-tui
+    cp -r ${hermesTui}/lib/hermes-tui/* $out/ui-tui/
+
+    ${lib.concatMapStringsSep "\n"
+      (name: ''
+        makeWrapper ${hermesVenv}/bin/${name} $out/bin/${name} \
+          --suffix PATH : "${runtimePath}" \
+          --set HERMES_BUNDLED_SKILLS $out/share/hermes-agent/skills \
+          --set HERMES_BUNDLED_PLUGINS $out/share/hermes-agent/plugins \
+          --set HERMES_WEB_DIST $out/share/hermes-agent/web_dist \
+          --set HERMES_TUI_DIR $out/ui-tui \
+          --set HERMES_PYTHON ${hermesVenv}/bin/python3 \
+          --set HERMES_NODE ${lib.getExe nodejs} \
+          ${lib.optionalString (rev != null) ''--set HERMES_REVISION ${rev} \''}
+          ${lib.optionalString (extraPythonPackages != [ ]) ''--suffix PYTHONPATH : "${pythonPath}"''}
+      '')
+      [
+        "hermes"
+        "hermes-agent"
+        "hermes-acp"
+      ]
+    }
+
+    ${lib.optionalString (extraPythonPackages != [ ]) ''
+      echo "=== Checking for plugin/core package collisions ==="
+      ${hermesVenv}/bin/python3 -c "${checkPackageCollisions}"
+      echo "=== No collisions ==="
+    ''}
+
+    runHook postInstall
+  '';
+
+  passthru = {
+    inherit
+      hermesTui
+      hermesWeb
+      hermesNpmLib
+      hermesVenv
+      ;
+
+    devShellHook = ''
+      STAMP=".nix-stamps/hermes-agent"
+      STAMP_VALUE="${pyprojectHash}:${uvLockHash}"
+      if [ ! -f "$STAMP" ] || [ "$(cat "$STAMP")" != "$STAMP_VALUE" ]; then
+        echo "hermes-agent: installing Python dependencies..."
+        uv venv .venv --python ${python312}/bin/python3 2>/dev/null || true
+        source .venv/bin/activate
+        uv pip install -e ".[all]"
+        [ -d mini-swe-agent ] && uv pip install -e ./mini-swe-agent 2>/dev/null || true
+        mkdir -p .nix-stamps
+        echo "$STAMP_VALUE" > "$STAMP"
+      else
+        source .venv/bin/activate
+        export HERMES_PYTHON=${hermesVenv}/bin/python3
+      fi
+    '';
+  };
+
+  meta = with lib; {
+    description = "AI agent with advanced tool-calling capabilities";
+    homepage = "https://github.com/NousResearch/hermes-agent";
+    mainProgram = "hermes";
+    license = licenses.mit;
+    platforms = platforms.unix;
+  };
+}

nix/lib.nix

@@ -0,0 +1,245 @@
+# nix/lib.nix — Shared helpers for nix stuff
+{
+  pkgs,
+  npm-lockfile-fix,
+  nodejs,
+}:
+{
+  # Returns a buildNpmPackage-compatible attrs set that provides:
+  #   patchPhase             — ensures lockfile has exactly one trailing newline
+  #   nativeBuildInputs      — [ updateLockfileScript ] (list, prepend with ++ for more)
+  #   passthru.devShellHook  — stamp-checked npm install + hash auto-update
+  #   passthru.npmLockfile   — metadata for mkFixLockfiles
+  #   nodejs                 — fixed nodejs version for all packages we use in the repo
+  #
+  # NOTE: npmConfigHook runs `diff` between the source lockfile and the
+  # npm-deps cache lockfile. fetchNpmDeps preserves whatever trailing
+  # newlines the lockfile has. The patchPhase normalizes to exactly one
+  # trailing newline so both sides always match.
+  #
+  # Usage:
+  #   npm = hermesNpmLib.mkNpmPassthru { folder = "ui-tui"; attr = "tui"; pname = "hermes-tui"; };
+  #   pkgs.buildNpmPackage (npm // { ... } # or:
+  #   pkgs.buildNpmPackage ({ ... } // npm)
+  mkNpmPassthru =
+    {
+      folder, # repo-relative folder with package.json, e.g. "ui-tui"
+      attr, # flake package attr, e.g. "tui"
+      pname, # e.g. "hermes-tui"
+      nixFile ? "nix/${attr}.nix", # defaults to nix/<attr>.nix
+    }:
+    {
+      inherit nodejs;
+      patchPhase = ''
+        runHook prePatch
+        # Normalize trailing newlines so source and npm-deps always match,
+        # regardless of what fetchNpmDeps preserves.
+        sed -i -z 's/\n*$/\n/' package-lock.json
+
+        # Make npmConfigHook's byte-for-byte diff newline-agnostic by
+        # replacing its hardcoded /nix/store/.../diff with a wrapper that
+        # normalizes trailing newlines on both sides before comparing.
+        mkdir -p "$TMPDIR/bin"
+        cat > "$TMPDIR/bin/diff" << DIFFWRAP
+        #!/bin/sh
+        f1=\$(mktemp) && sed -z 's/\n*$/\n/' "\$1" > "\$f1"
+        f2=\$(mktemp) && sed -z 's/\n*$/\n/' "\$2" > "\$f2"
+        ${pkgs.diffutils}/bin/diff "\$f1" "\$f2" && rc=0 || rc=\$?
+        rm -f "\$f1" "\$f2"
+        exit \$rc
+        DIFFWRAP
+        chmod +x "$TMPDIR/bin/diff"
+        export PATH="$TMPDIR/bin:$PATH"
+
+        runHook postPatch
+      '';
+
+      nativeBuildInputs = [
+        (pkgs.writeShellScriptBin "update_${attr}_lockfile" ''
+          set -euox pipefail
+
+          REPO_ROOT=$(git rev-parse --show-toplevel)
+
+          cd "$REPO_ROOT/${folder}"
+          rm -rf node_modules/
+          ${pkgs.lib.getExe' nodejs "npm"} cache clean --force
+          CI=true ${pkgs.lib.getExe' nodejs "npm"} install
+          ${pkgs.lib.getExe npm-lockfile-fix} ./package-lock.json
+
+          NIX_FILE="$REPO_ROOT/${nixFile}"
+          sed -i "s/hash = \"[^\"]*\";/hash = \"\";/" $NIX_FILE
+          NIX_OUTPUT=$(nix build .#${attr} 2>&1 || true)
+          NEW_HASH=$(echo "$NIX_OUTPUT" | grep 'got:' | awk '{print $2}')
+          echo got new hash $NEW_HASH
+          sed -i "s|hash = \"[^\"]*\";|hash = \"$NEW_HASH\";|" $NIX_FILE
+          nix build .#${attr}
+          echo "Updated npm hash in $NIX_FILE to $NEW_HASH"
+        '')
+      ];
+
+      passthru = {
+        devShellHook = pkgs.writeShellScript "npm-dev-hook-${pname}" ''
+          REPO_ROOT=$(git rev-parse --show-toplevel)
+
+          _hermes_npm_stamp() {
+            sha256sum "${folder}/package.json" "${folder}/package-lock.json" \
+              2>/dev/null | sha256sum | awk '{print $1}'
+          }
+          STAMP=".nix-stamps/${pname}"
+          STAMP_VALUE="$(_hermes_npm_stamp)"
+          if [ ! -f "$STAMP" ] || [ "$(cat "$STAMP")" != "$STAMP_VALUE" ]; then
+            echo "${pname}: installing npm dependencies..."
+            ( cd ${folder} && CI=true ${pkgs.lib.getExe' nodejs "npm"} install --silent --no-fund --no-audit 2>/dev/null )
+
+            # Auto-update the nix hash so it stays in sync with the lockfile
+            echo "${pname}: prefetching npm deps..."
+            NIX_FILE="$REPO_ROOT/${nixFile}"
+            if NEW_HASH=$(${pkgs.lib.getExe pkgs.prefetch-npm-deps} "${folder}/package-lock.json" 2>/dev/null); then
+              sed -i "s|hash = \"sha256-[A-Za-z0-9+/=]+\"|hash = \"$NEW_HASH\";|" "$NIX_FILE"
+              echo "${pname}: updated hash to $NEW_HASH"
+            else
+              echo "${pname}: warning: prefetch failed, run 'nix run .#fix-lockfiles' manually" >&2
+            fi
+
+            mkdir -p .nix-stamps
+            _hermes_npm_stamp > "$STAMP"
+          fi
+          unset -f _hermes_npm_stamp
+        '';
+
+        npmLockfile = {
+          inherit attr folder nixFile;
+        };
+      };
+    };
+
+  # Aggregate `fix-lockfiles` bin from a list of packages carrying
+  #   passthru.npmLockfile = { attr; folder; nixFile; };
+  # Invocations:
+  #   fix-lockfiles --check   # exit 1 if any hash is stale
+  #   fix-lockfiles --apply   # rewrite stale hashes in place
+  #   fix-lockfiles           # alias of --apply
+  # Writes machine-readable fields (stale, changed, report) to $GITHUB_OUTPUT
+  # when set, so CI workflows can post a sticky PR comment directly.
+  mkFixLockfiles =
+    {
+      packages, # list of packages with passthru.npmLockfile
+    }:
+    let
+      entries = map (p: p.passthru.npmLockfile) packages;
+      entryArgs = pkgs.lib.concatMapStringsSep " " (e: "\"${e.attr}:${e.folder}:${e.nixFile}\"") entries;
+    in
+    pkgs.writeShellScriptBin "fix-lockfiles" ''
+      set -uox pipefail
+      MODE="''${1:---apply}"
+      case "$MODE" in
+        --check|--apply) ;;
+        -h|--help)
+          echo "usage: fix-lockfiles [--check|--apply]"
+          exit 0 ;;
+        *)
+          echo "usage: fix-lockfiles [--check|--apply]" >&2
+          exit 2 ;;
+      esac
+
+      ENTRIES=(${entryArgs})
+
+      REPO_ROOT="$(git rev-parse --show-toplevel)"
+      cd "$REPO_ROOT"
+
+      # When running in GH Actions, emit Markdown links in the report pointing
+      # at the offending line of the nix file (and the lockfile) at the exact
+      # commit that was checked. LINK_SHA should be set by the workflow to the
+      # PR head SHA; falls back to GITHUB_SHA (which on pull_request is the
+      # test-merge commit, still browseable).
+      LINK_SERVER="''${GITHUB_SERVER_URL:-https://github.com}"
+      LINK_REPO="''${GITHUB_REPOSITORY:-}"
+      LINK_SHA="''${LINK_SHA:-''${GITHUB_SHA:-}}"
+
+      STALE=0
+      FIXED=0
+      REPORT=""
+
+      for entry in "''${ENTRIES[@]}"; do
+        IFS=":" read -r ATTR FOLDER NIX_FILE <<< "$entry"
+        echo "==> .#$ATTR ($FOLDER -> $NIX_FILE)"
+
+        # Compute the actual hash from the lockfile directly using
+        # prefetch-npm-deps. This avoids false "ok" from nix build when
+        # an old derivation is cached in a substituter (cachix/cache.nixos.org).
+        LOCK_FILE="$FOLDER/package-lock.json"
+        NEW_HASH=$(${pkgs.lib.getExe pkgs.prefetch-npm-deps} "$LOCK_FILE" 2>/dev/null)
+        if [ -z "$NEW_HASH" ]; then
+          echo "    prefetch-npm-deps failed, falling back to nix build" >&2
+          OUTPUT=$(nix build ".#$ATTR.npmDeps" --no-link --print-build-logs 2>&1)
+          STATUS=$?
+          if [ "$STATUS" -eq 0 ]; then
+            echo "    ok (via nix build)"
+            continue
+          fi
+          NEW_HASH=$(echo "$OUTPUT" | awk '/got:/ {print $2; exit}')
+          if [ -z "$NEW_HASH" ]; then
+            if echo "$OUTPUT" | grep -qE "throttled|HTTP error 418|substituter .* is disabled|some outputs of .* are not valid"; then
+              echo "    skipped (transient cache failure — see primary nix build for real status)" >&2
+              echo "$OUTPUT" | tail -8 >&2
+              continue
+            fi
+            echo "    build failed with no hash mismatch:" >&2
+            echo "$OUTPUT" | tail -40 >&2
+            exit 1
+          fi
+        fi
+
+        OLD_HASH=$(grep -oE 'hash = "sha256-[^"]+"' "$NIX_FILE" | head -1 \
+          | sed -E 's/hash = "(.*)"/\1/')
+
+        if [ "$NEW_HASH" = "$OLD_HASH" ]; then
+          echo "    ok"
+          continue
+        fi
+
+        HASH_LINE=$(grep -n 'hash = "sha256-' "$NIX_FILE" | head -1 | cut -d: -f1)
+        echo "    stale: $NIX_FILE:$HASH_LINE $OLD_HASH -> $NEW_HASH"
+        STALE=1
+
+        if [ -n "$LINK_REPO" ] && [ -n "$LINK_SHA" ]; then
+          NIX_URL="$LINK_SERVER/$LINK_REPO/blob/$LINK_SHA/$NIX_FILE#L$HASH_LINE"
+          LOCK_URL="$LINK_SERVER/$LINK_REPO/blob/$LINK_SHA/$LOCK_FILE"
+          REPORT+="- [\`$NIX_FILE:$HASH_LINE\`]($NIX_URL) (\`.#$ATTR\`): \`$OLD_HASH\` → \`$NEW_HASH\` — lockfile: [\`$LOCK_FILE\`]($LOCK_URL)"$'\n'
+        else
+          REPORT+="- \`$NIX_FILE:$HASH_LINE\` (\`.#$ATTR\`): \`$OLD_HASH\` → \`$NEW_HASH\`"$'\n'
+        fi
+
+        if [ "$MODE" = "--apply" ]; then
+          sed -i "s|hash = \"sha256-[^\"]*\";|hash = \"$NEW_HASH\";|" "$NIX_FILE"
+          if ! nix build ".#$ATTR.npmDeps" --no-link --print-build-logs; then
+            echo "    verification build failed after hash update" >&2
+            exit 1
+          fi
+          FIXED=1
+          echo "    fixed"
+        fi
+      done
+
+      if [ -n "''${GITHUB_OUTPUT:-}" ]; then
+        {
+          [ "$STALE" -eq 1 ] && echo "stale=true" || echo "stale=false"
+          [ "$FIXED" -eq 1 ] && echo "changed=true" || echo "changed=false"
+          if [ -n "$REPORT" ]; then
+            echo "report<<REPORT_EOF"
+            printf "%s" "$REPORT"
+            echo "REPORT_EOF"
+          fi
+        } >> "$GITHUB_OUTPUT"
+      fi
+
+      if [ "$STALE" -eq 1 ] && [ "$MODE" = "--check" ]; then
+        echo
+        echo "Stale lockfile hashes detected. Run:"
+        echo "  nix run .#fix-lockfiles"
+        exit 1
+      fi
+
+      exit 0
+    '';
+}

nix/overlays.nix

@@ -0,0 +1,11 @@
+# nix/overlays.nix — Expose pkgs.hermes-agent for external NixOS configs
+{ inputs, ... }:
+{
+  flake.overlays.default = final: _: {
+    hermes-agent = final.callPackage ./hermes-agent.nix {
+      inherit (inputs) uv2nix pyproject-nix pyproject-build-systems;
+      npm-lockfile-fix = inputs.npm-lockfile-fix.packages.${final.stdenv.hostPlatform.system}.default;
+      rev = inputs.self.rev or null;
+    };
+  };
+}

nix/packages.nix

@@ -0,0 +1,58 @@
+# nix/packages.nix — Hermes Agent package built with uv2nix
+{ inputs, ... }:
+{
+  perSystem =
+    { pkgs, lib, inputs', ... }:
+    let
+      hermesAgent = pkgs.callPackage ./hermes-agent.nix {
+        inherit (inputs) uv2nix pyproject-nix pyproject-build-systems;
+        npm-lockfile-fix = inputs'.npm-lockfile-fix.packages.default;
+        # Only embed clean revs — dirtyRev doesn't represent any upstream
+        # commit, so comparing it would always claim "update available".
+        rev = inputs.self.rev or null;
+      };
+    in
+    {
+      packages = {
+        default = hermesAgent;
+
+        # Ships discord.py + python-telegram-bot + slack-sdk so a plain
+        # `nix profile install .#messaging` connects to Discord/Telegram/Slack
+        # on first run — lazy-install can't write to the read-only /nix/store.
+        messaging = hermesAgent.override {
+          extraDependencyGroups = [ "messaging" ];
+        };
+
+        # All platform-portable optional integrations pre-built.
+        # matrix is Linux-only (oqs/liboqs lacks aarch64-darwin wheels).
+        full = hermesAgent.override {
+          extraDependencyGroups = [
+            "anthropic"
+            "azure-identity"
+            "bedrock"
+            "daytona"
+            "dingtalk"
+            "edge-tts"
+            "exa"
+            "fal"
+            "feishu"
+            "firecrawl"
+            "hindsight"
+            "honcho"
+            "messaging"
+            "modal"
+            "parallel-web"
+            "tts-premium"
+            "voice"
+          ] ++ lib.optionals pkgs.stdenv.isLinux [ "matrix" ];
+        };
+
+        tui = hermesAgent.hermesTui;
+        web = hermesAgent.hermesWeb;
+
+        fix-lockfiles = hermesAgent.hermesNpmLib.mkFixLockfiles {
+          packages = [ hermesAgent.hermesTui hermesAgent.hermesWeb ];
+        };
+      };
+    };
+}

nix/python.nix

@@ -0,0 +1,101 @@
+# nix/python.nix — uv2nix virtual environment builder
+{
+  python312,
+  lib,
+  callPackage,
+  uv2nix,
+  pyproject-nix,
+  pyproject-build-systems,
+  stdenv,
+  dependency-groups ? [ "all" ],
+}:
+let
+  workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./..; };
+  hacks = callPackage pyproject-nix.build.hacks { };
+
+  overlay = workspace.mkPyprojectOverlay {
+    sourcePreference = "wheel";
+  };
+
+  isAarch64Darwin = stdenv.hostPlatform.system == "aarch64-darwin";
+
+  # Keep the workspace locked through uv2nix, but supply the local voice stack
+  # from nixpkgs so wheel-only transitive artifacts do not break evaluation.
+  mkPrebuiltPassthru = dependencies: {
+    inherit dependencies;
+    optional-dependencies = { };
+    dependency-groups = { };
+  };
+
+  mkPrebuiltOverride = final: from: dependencies:
+    hacks.nixpkgsPrebuilt {
+      inherit from;
+      prev = {
+        nativeBuildInputs = [ final.pyprojectHook ];
+        passthru = mkPrebuiltPassthru dependencies;
+      };
+    };
+
+  # Legacy alibabacloud packages ship only sdists with setup.py/setup.cfg
+  # and no pyproject.toml, so setuptools isn't declared as a build dep.
+  buildSystemOverrides = final: prev: builtins.mapAttrs
+    (name: _: prev.${name}.overrideAttrs (old: {
+      nativeBuildInputs = (old.nativeBuildInputs or [ ]) ++ [ final.setuptools ];
+    }))
+    (lib.genAttrs [
+      "alibabacloud-credentials-api"
+      "alibabacloud-endpoint-util"
+      "alibabacloud-gateway-dingtalk"
+      "alibabacloud-gateway-spi"
+      "alibabacloud-tea"
+    ] (_: null));
+
+  pythonPackageOverrides = final: _prev:
+    if isAarch64Darwin then {
+      numpy = mkPrebuiltOverride final python312.pkgs.numpy { };
+
+      pyarrow = mkPrebuiltOverride final python312.pkgs.pyarrow { };
+
+      av = mkPrebuiltOverride final python312.pkgs.av { };
+
+      humanfriendly = mkPrebuiltOverride final python312.pkgs.humanfriendly { };
+
+      coloredlogs = mkPrebuiltOverride final python312.pkgs.coloredlogs {
+        humanfriendly = [ ];
+      };
+
+      onnxruntime = mkPrebuiltOverride final python312.pkgs.onnxruntime {
+        coloredlogs = [ ];
+        numpy = [ ];
+        packaging = [ ];
+      };
+
+      ctranslate2 = mkPrebuiltOverride final python312.pkgs.ctranslate2 {
+        numpy = [ ];
+        pyyaml = [ ];
+      };
+
+      faster-whisper = mkPrebuiltOverride final python312.pkgs.faster-whisper {
+        av = [ ];
+        ctranslate2 = [ ];
+        huggingface-hub = [ ];
+        onnxruntime = [ ];
+        tokenizers = [ ];
+        tqdm = [ ];
+      };
+    } else {};
+
+  pythonSet =
+    (callPackage pyproject-nix.build.packages {
+      python = python312;
+    }).overrideScope
+      (lib.composeManyExtensions [
+        pyproject-build-systems.overlays.default
+        overlay
+        buildSystemOverrides
+        pythonPackageOverrides
+      ]);
+in
+pythonSet.mkVirtualEnv "hermes-agent-env" {
+  hermes-agent = dependency-groups;
+}

nix/tui.nix

@@ -0,0 +1,35 @@
+# nix/tui.nix — Hermes TUI (Ink/React) compiled with tsc and bundled
+{ pkgs, hermesNpmLib, ... }:
+let
+  src = ../ui-tui;
+  npmDeps = pkgs.fetchNpmDeps {
+    inherit src;
+    hash = "sha256-F6/MzZOWc0zhW9mIfnaY+PrllPvJcsA/OdFdEM+NpLY=";
+  };
+
+  npm = hermesNpmLib.mkNpmPassthru { folder = "ui-tui"; attr = "tui"; pname = "hermes-tui"; };
+
+  packageJson = builtins.fromJSON (builtins.readFile (src + "/package.json"));
+  version = packageJson.version;
+in
+pkgs.buildNpmPackage (npm // {
+  pname = "hermes-tui";
+  inherit src npmDeps version;
+
+  doCheck = false;
+  npmFlags = [ "--legacy-peer-deps" ];
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir -p $out/lib/hermes-tui
+
+    # Single self-contained bundle built by scripts/build.mjs (esbuild).
+    cp -r dist $out/lib/hermes-tui/dist
+
+    # package.json kept for "type": "module" resolution on `node dist/entry.js`.
+    cp package.json $out/lib/hermes-tui/
+
+    runHook postInstall
+  '';
+})

nix/web.nix

@@ -0,0 +1,31 @@
+# nix/web.nix — Hermes Web Dashboard (Vite/React) frontend build
+{ pkgs, hermesNpmLib, ... }:
+let
+  src = ../web;
+  npmDeps = pkgs.fetchNpmDeps {
+    inherit src;
+    hash = "sha256-HV0aISBVjwbGqDj8qQynSxGFrrZDzuYAW3D3lB/x3zo=";
+  };
+
+  npm = hermesNpmLib.mkNpmPassthru { folder = "web"; attr = "web"; pname = "hermes-web"; };
+
+  packageJson = builtins.fromJSON (builtins.readFile (src + "/package.json"));
+  version = packageJson.version;
+in
+pkgs.buildNpmPackage (npm // {
+  pname = "hermes-web";
+  inherit src npmDeps version;
+
+  doCheck = false;
+
+  buildPhase = ''
+    npx tsc -b
+    npx vite build --outDir dist
+  '';
+
+  installPhase = ''
+    runHook preInstall
+    cp -r dist $out
+    runHook postInstall
+  '';
+})