hermes-agent 0.14.0 → 0.15.2

package/DISCLAIMER.md

@@ -0,0 +1,22 @@
+# Disclaimer
+
+This is an unofficial npm bridge for Hermes Agent.
+
+Hermes Agent is developed by Nous Research:
+
+https://github.com/NousResearch/hermes-agent
+
+This project is not affiliated with, endorsed by, sponsored by, or maintained by
+Nous Research. References to Hermes Agent and Nous Research are provided only to
+identify the upstream open-source project that this npm package installs and
+launches.
+
+The npm package name is `hermes-agent` because it installs the upstream Python
+package with the same name. This repository does not claim ownership of the
+upstream Hermes Agent project, its source code, or its trademarks.
+
+Any product names, project names, logos, or marks referenced here belong to
+their respective owners and are used only to identify the upstream project.
+
+This package is provided as-is, without warranty. Users should review the
+upstream project, its license, and this package's install behavior before use.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wyrtensi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,23 @@
+hermes-agent npm bridge
+Copyright (c) 2026 wyrtensi
+License: MIT
+
+This repository publishes an unofficial npm bridge for Hermes Agent.
+
+Hermes Agent is developed by Nous Research.
+Upstream repository: https://github.com/NousResearch/hermes-agent
+Upstream package: hermes-agent on PyPI
+Upstream license: MIT
+Upstream copyright notice: Copyright (c) 2025 Nous Research
+
+This npm package does not claim ownership of Hermes Agent, the Hermes Agent
+source code, the Hermes Agent name, or Nous Research marks. It only provides a
+Node.js package wrapper that installs and launches the upstream Python package.
+
+The npm package includes wrapper code from this repository. It does not vendor
+or redistribute the upstream Hermes Agent source tree. During installation, the
+postinstall script asks pip to install the pinned upstream Python package
+version matching this npm package.
+
+For the upstream license text, see:
+https://github.com/NousResearch/hermes-agent/blob/main/LICENSE

package/PRIVACY.md

@@ -0,0 +1,34 @@
+# Privacy
+
+This npm bridge does not collect telemetry.
+
+The package does not intentionally collect, store, or transmit:
+
+- personal information
+- analytics events
+- npm tokens
+- GitHub tokens
+- SSH keys
+- API keys
+- repository contents
+- shell history
+
+During normal installation, npm runs `scripts/postinstall.js`. That script only
+uses the local Node.js runtime, the local Python interpreter, and pip. Its
+network activity is limited to pip downloading the pinned Python package and its
+dependencies from the user's configured Python package index.
+
+The package does not run a separate telemetry endpoint, background service,
+scheduled task, or analytics uploader.
+
+Users who do not want npm lifecycle scripts to run can install with:
+
+```bash
+npm install -g hermes-agent --ignore-scripts
+```
+
+Then install the upstream Python runtime manually:
+
+```bash
+python -m pip install --upgrade hermes-agent==<npm package version>
+```

package/README.md

@@ -1,4 +1,11 @@
-# hermes-agent npm package
+# hermes-agent npm bridge
+
+This is an unofficial npm bridge for Hermes Agent by Nous Research. It is not
+affiliated with, endorsed by, sponsored by, or maintained by Nous Research.
+
+Hermes Agent is developed by Nous Research and distributed separately as a
+Python package. This npm package only installs and launches that upstream Python
+runtime.
 
 This repository publishes the npm bridge for
 [NousResearch/Hermes-Agent](https://github.com/NousResearch/Hermes-Agent).
@@ -9,6 +16,16 @@ The npm package name is:
 hermes-agent
 ```
 
+This repository can build an alias package manifest for:
+
+```bash
+hermesagent
+```
+
+npm currently blocks publishing the unscoped `hermesagent` package because the
+name is too similar to the existing `hermes-agent` package. The available npm
+alternative is a scoped package such as `@wyrtensi/hermesagent`.
+
 The installed commands are:
 
 ```bash
@@ -19,6 +36,22 @@ hermes-agent
 The npm package name `hermes` is already owned by another package on npm, so this
 repository publishes `hermes-agent` and exposes `hermes` as a CLI binary.
 
+## Legal and attribution
+
+- Wrapper license: MIT, see [LICENSE](LICENSE).
+- Upstream attribution: see [NOTICE](NOTICE).
+- Unofficial package disclaimer: see [DISCLAIMER.md](DISCLAIMER.md).
+- Privacy notes: see [PRIVACY.md](PRIVACY.md).
+- Install-script security notes: see [SECURITY.md](SECURITY.md).
+
+For wrapper issues, use this repository:
+
+https://github.com/wyrtensi/hermes-agent-npm/issues
+
+For upstream Hermes Agent issues, use the upstream project:
+
+https://github.com/NousResearch/hermes-agent/issues
+
 ## Install
 
 Prerequisites:
@@ -40,28 +73,38 @@ hermes --help
 hermes-agent --help
 ```
 
+If a scoped alias package is published later, you do not need to install both
+`hermes-agent` and the alias. If one is already installed globally, the other
+package prints a warning during `postinstall`.
+
 During npm installation, `postinstall` installs the matching Python package:
 
 ```bash
 python -m pip install --upgrade hermes-agent==<npm package version>
 ```
 
+For a detailed explanation of why this package uses `postinstall` and exactly
+what the script does, see [SECURITY.md](SECURITY.md).
+
 ## Automated publishing
 
 `.github/workflows/npm-publish.yml` runs:
 
 - manually with `workflow_dispatch`
-- daily on a schedule
+- four times per hour on a schedule
 - when a tag matching `npm-v*` is pushed
 
 The workflow:
 
-1. Fetches the current Hermes Agent version from upstream `pyproject.toml`.
+1. Fetches the latest published Hermes Agent version from PyPI.
 2. Updates `package.json` in the workflow workspace.
 3. Skips publishing if `hermes-agent@<version>` already exists on npm.
-4. Runs `npm test`.
-5. Runs `npm pack --dry-run`.
-6. Publishes to npm with the `NPM_TOKEN` GitHub Actions secret.
+4. Skips publishing if the matching Python `hermes-agent==<version>` package
+   is not available on PyPI yet.
+5. Runs `npm test`.
+6. Runs `npm pack --dry-run`.
+7. Publishes missing npm packages through npm trusted publishing with GitHub
+   Actions OIDC and npm provenance.
 
 ## GitHub setup
 
@@ -71,17 +114,7 @@ Create a GitHub repository named:
 hermes-agent-npm
 ```
 
-Create a classic or automation npm token with publish access, then add it as a
-GitHub Actions secret:
-
-```text
-Repository -> Settings -> Secrets and variables -> Actions -> New repository secret
-Name: NPM_TOKEN
-Value: your npm token
-```
-
-After the first package version exists on npm, this repository can be switched
-back to npm trusted publishing if desired:
+Configure npm trusted publishing for the published npm package:
 
 ```text
 npm package: hermes-agent
@@ -92,6 +125,12 @@ workflow filename: npm-publish.yml
 allowed action: npm publish
 ```
 
+The trusted publisher environment name should stay empty unless the workflow job
+also defines a matching GitHub Actions environment. In the package's npm
+Publishing access settings, use `Require two-factor authentication and disallow
+tokens` after trusted publishing is configured. GitHub Actions will keep
+publishing through OIDC, while long-lived npm publish tokens are blocked.
+
 Then push this repository:
 
 ```bash
@@ -108,4 +147,6 @@ first publish.
 python scripts/sync_upstream_version.py
 npm test
 npm pack --dry-run
+npm run build:alias
+npm pack --dry-run ./dist/hermesagent
 ```

package/SECURITY.md

@@ -0,0 +1,174 @@
+# Security notes for the npm postinstall script
+
+This package intentionally includes a `postinstall` script:
+
+```json
+{
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  }
+}
+```
+
+Install scripts deserve careful review because they execute automatically during
+`npm install`. This document explains exactly why this package has one, what it
+does, and what it does not do.
+
+## Why postinstall exists
+
+`hermes-agent` on npm is an unofficial small Node.js bridge for the upstream
+Python project:
+
+https://github.com/NousResearch/Hermes-Agent
+
+This npm bridge is not affiliated with, endorsed by, sponsored by, or maintained
+by Nous Research. See [DISCLAIMER.md](DISCLAIMER.md) and [NOTICE](NOTICE) for
+the project attribution and legal notice.
+
+The actual Hermes Agent runtime is distributed as the Python package
+`hermes-agent`. The npm package provides convenient global commands:
+
+```bash
+hermes
+hermes-agent
+```
+
+The canonical npm package is `hermes-agent`. The package `hermesagent` is an
+alias manifest for users who search for the name without the hyphen. npm blocks
+publishing the unscoped `hermesagent` package because the name is too similar to
+`hermes-agent`; a scoped alias such as `@wyrtensi/hermesagent` can be published
+separately if needed.
+
+The `postinstall` step installs the matching Python package version so that a
+single command prepares the npm wrapper and the Python runtime:
+
+```bash
+npm install -g hermes-agent
+```
+
+Without `postinstall`, users would need to run a second command manually:
+
+```bash
+python -m pip install --upgrade hermes-agent==<npm package version>
+```
+
+## Exact behavior
+
+The script is located at:
+
+```text
+scripts/postinstall.js
+```
+
+It performs these steps:
+
+1. Finds an available Python 3 interpreter.
+   - On Windows it tries `py -3`, then `python`, then `python3`.
+   - On macOS and Linux it tries `python3`, then `python`.
+2. Verifies that the interpreter is Python 3.11 or newer.
+3. Builds the pinned Python package spec from `package.json`, for example:
+
+   ```bash
+   hermes-agent==<npm package version>
+   ```
+
+4. Runs:
+
+   ```bash
+   python -m pip install --upgrade hermes-agent==<npm package version>
+   ```
+
+5. If that install fails, retries with:
+
+   ```bash
+   python -m pip install --upgrade --user hermes-agent==<npm package version>
+   ```
+
+6. Exits with a non-zero status if both attempts fail.
+
+The script also checks whether the related alias package is already installed
+globally. If `hermes-agent` is installed and a user installs `hermesagent`, or
+the other way around, it prints a warning explaining that both packages point to
+the same Hermes Agent runtime. It does not uninstall packages or modify npm
+global state.
+
+## What the script does not do
+
+The `postinstall` script does not:
+
+- read SSH keys, npm tokens, GitHub tokens, or other secrets
+- inspect project source files outside this npm package
+- upload telemetry or analytics
+- call custom remote shell scripts
+- run `curl | sh`, PowerShell downloads, or arbitrary downloaded code
+- modify shell profiles such as `.bashrc`, `.zshrc`, or PowerShell profiles
+- add startup items, services, scheduled tasks, or background daemons
+- change Git configuration
+- install npm packages dynamically
+
+Its network activity is limited to the normal package downloads performed by
+`pip` from the user's configured Python package index.
+
+## Publishing security
+
+The npm package is published by GitHub Actions through npm trusted publishing
+with OpenID Connect. The publish workflow is allowed to publish only from:
+
+```text
+GitHub owner: wyrtensi
+GitHub repository: hermes-agent-npm
+Workflow file: npm-publish.yml
+Allowed npm action: npm publish
+```
+
+The workflow does not use a long-lived npm publish token. npm package settings
+should use `Require two-factor authentication and disallow tokens` so manual
+publishes require 2FA and traditional npm tokens cannot publish this package.
+Trusted publishing continues to work because it uses short-lived OIDC
+credentials issued for the configured workflow.
+
+## Why the package is version-pinned
+
+The npm package version and the Python package version are kept in sync. The
+postinstall script installs the exact matching Python version:
+
+```bash
+hermes-agent==<npm package version>
+```
+
+This avoids silently installing a newer Python Hermes runtime than the npm
+wrapper was published for.
+
+## How to audit locally
+
+Review the install script:
+
+```bash
+npm pack hermes-agent
+tar -xzf hermes-agent-*.tgz
+cat package/scripts/postinstall.js
+cat package/lib/python-launcher.js
+```
+
+Install without running lifecycle scripts:
+
+```bash
+npm install -g hermes-agent --ignore-scripts
+```
+
+Then install the Python runtime manually:
+
+```bash
+python -m pip install --upgrade hermes-agent==<npm package version>
+```
+
+## Why security scanners flag this package
+
+Some scanners flag every npm package with `preinstall`, `install`, or
+`postinstall` scripts because those scripts can execute code automatically.
+That warning is useful and should not be ignored.
+
+For this package, the install script is intentionally small and exists only to
+install the pinned Python Hermes Agent runtime. Users who prefer not to run npm
+lifecycle scripts can use `--ignore-scripts` and install the Python package
+manually.

package/bin/hermes-agent.js

@@ -2,4 +2,4 @@
 
 const { runHermes } = require("../lib/python-launcher");
 
-runHermes(process.argv[1], process.argv.slice(2));
+runHermes("hermes-agent", process.argv.slice(2));

package/bin/hermes.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runHermes } = require("../lib/python-launcher");
+
+runHermes("hermes", process.argv.slice(2));

package/lib/package-metadata.js

@@ -0,0 +1,36 @@
+const CANONICAL_PACKAGE_NAME = "hermes-agent";
+const ALIAS_PACKAGE_NAME = "hermesagent";
+
+function getRelatedPackageNames(packageName) {
+  if (packageName === CANONICAL_PACKAGE_NAME) {
+    return [ALIAS_PACKAGE_NAME];
+  }
+
+  if (packageName === ALIAS_PACKAGE_NAME) {
+    return [CANONICAL_PACKAGE_NAME];
+  }
+
+  return [];
+}
+
+function getAliasPackageName(packageName) {
+  return packageName === CANONICAL_PACKAGE_NAME ? ALIAS_PACKAGE_NAME : packageName;
+}
+
+function getPackageBinNames(packageName) {
+  const names = ["hermes", "hermes-agent"];
+
+  if (packageName === ALIAS_PACKAGE_NAME) {
+    names.push(ALIAS_PACKAGE_NAME);
+  }
+
+  return names;
+}
+
+module.exports = {
+  ALIAS_PACKAGE_NAME,
+  CANONICAL_PACKAGE_NAME,
+  getAliasPackageName,
+  getPackageBinNames,
+  getRelatedPackageNames
+};

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "hermes-agent",
-  "version": "0.14.0",
-  "description": "npm bridge for Hermes Agent 0.14.0: The self-improving AI agent \u2014 creates skills from experience, improves them during use, and runs anywhere",
+  "version": "0.15.2",
+  "description": "Unofficial npm bridge for Hermes Agent 0.15.2: The self-improving AI agent \u2014 creates skills from experience, improves them during use, and runs anywhere",
   "license": "MIT",
   "type": "commonjs",
   "bin": {
-    "hermes": "bin/hermes-agent.js",
+    "hermes": "bin/hermes.js",
     "hermes-agent": "bin/hermes-agent.js"
   },
   "scripts": {
+    "build:alias": "node scripts/build-alias-package.js",
     "postinstall": "node scripts/postinstall.js",
     "test": "node --test"
   },
@@ -17,9 +18,9 @@
     "url": "git+https://github.com/wyrtensi/hermes-agent-npm.git"
   },
   "bugs": {
-    "url": "https://github.com/NousResearch/Hermes-Agent/issues"
+    "url": "https://github.com/wyrtensi/hermes-agent-npm/issues"
   },
-  "homepage": "https://github.com/NousResearch/Hermes-Agent#readme",
+  "homepage": "https://github.com/wyrtensi/hermes-agent-npm#readme",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -27,10 +28,15 @@
     "bin/",
     "lib/",
     "scripts/postinstall.js",
-    "README.md"
+    "DISCLAIMER.md",
+    "LICENSE",
+    "NOTICE",
+    "PRIVACY.md",
+    "README.md",
+    "SECURITY.md"
   ],
   "hermesAgent": {
-    "pythonPackageVersion": "0.14.0",
+    "pythonPackageVersion": "0.15.2",
     "upstreamRepository": "nousresearch/hermes-agent"
   }
 }

package/scripts/postinstall.js

@@ -1,10 +1,55 @@
 #!/usr/bin/env node
 
 const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const packageJson = require("../package.json");
+const { getRelatedPackageNames } = require("../lib/package-metadata");
 const { findPython, getPythonPackageSpec } = require("../lib/python-launcher");
 
 const candidate = findPython();
 const packageSpec = getPythonPackageSpec();
+const packageName = packageJson.name;
+
+function warnIfRelatedPackageInstalled() {
+  const relatedPackages = getRelatedPackageNames(packageName);
+
+  if (relatedPackages.length === 0) {
+    return;
+  }
+
+  const npmRootCommand = process.env.npm_execpath
+    ? { command: process.execPath, args: [process.env.npm_execpath, "root", "-g"] }
+    : { command: process.platform === "win32" ? "npm.cmd" : "npm", args: ["root", "-g"] };
+
+  const rootResult = spawnSync(npmRootCommand.command, npmRootCommand.args, {
+    encoding: "utf8",
+    windowsHide: true
+  });
+
+  if (rootResult.status !== 0) {
+    return;
+  }
+
+  const globalRoot = rootResult.stdout.trim();
+
+  for (const relatedPackage of relatedPackages) {
+    const relatedPackageJson = path.join(globalRoot, relatedPackage, "package.json");
+
+    try {
+      if (require("node:fs").existsSync(relatedPackageJson)) {
+        console.warn(
+          `${relatedPackage} is already installed globally. ` +
+            `${packageName} is an alias package for the same Hermes Agent runtime; ` +
+            "you do not need to install both."
+        );
+      }
+    } catch {
+      return;
+    }
+  }
+}
+
+warnIfRelatedPackageInstalled();
 
 if (!candidate) {
   console.error("Hermes Agent requires Python 3.11 or newer.");