hermes-agent 0.14.0

package/README.md

@@ -0,0 +1,111 @@
+# hermes-agent npm package
+
+This repository publishes the npm bridge for
+[NousResearch/Hermes-Agent](https://github.com/NousResearch/Hermes-Agent).
+
+The npm package name is:
+
+```bash
+hermes-agent
+```
+
+The installed commands are:
+
+```bash
+hermes
+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.
+
+## Install
+
+Prerequisites:
+
+- Node.js 20 or newer
+- Python 3.11 or newer
+- pip available for that Python installation
+
+Install globally:
+
+```bash
+npm install -g hermes-agent
+```
+
+Use it:
+
+```bash
+hermes --help
+hermes-agent --help
+```
+
+During npm installation, `postinstall` installs the matching Python package:
+
+```bash
+python -m pip install --upgrade hermes-agent==<npm package version>
+```
+
+## Automated publishing
+
+`.github/workflows/npm-publish.yml` runs:
+
+- manually with `workflow_dispatch`
+- daily on a schedule
+- when a tag matching `npm-v*` is pushed
+
+The workflow:
+
+1. Fetches the current Hermes Agent version from upstream `pyproject.toml`.
+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.
+
+## GitHub setup
+
+Create a GitHub repository named:
+
+```text
+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:
+
+```text
+npm package: hermes-agent
+publisher: GitHub Actions
+organization or user: wyrtensi
+repository: hermes-agent-npm
+workflow filename: npm-publish.yml
+allowed action: npm publish
+```
+
+Then push this repository:
+
+```bash
+git remote add origin git@github.com:wyrtensi/hermes-agent-npm.git
+git push -u origin main
+```
+
+After that, open GitHub Actions and run `Publish npm package` manually for the
+first publish.
+
+## Local checks
+
+```bash
+python scripts/sync_upstream_version.py
+npm test
+npm pack --dry-run
+```

package/bin/hermes-agent.js

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

package/lib/python-launcher.js

@@ -0,0 +1,99 @@
+const { spawn, spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const packageJson = require("../package.json");
+
+function getPythonCandidates(platform = process.platform) {
+  if (platform === "win32") {
+    return [
+      { command: "py", args: ["-3"] },
+      { command: "python", args: [] },
+      { command: "python3", args: [] }
+    ];
+  }
+
+  return [
+    { command: "python3", args: [] },
+    { command: "python", args: [] }
+  ];
+}
+
+function findPython(candidates = getPythonCandidates()) {
+  for (const candidate of candidates) {
+    const result = spawnSync(
+      candidate.command,
+      [...candidate.args, "-c", "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)"],
+      { encoding: "utf8", windowsHide: true }
+    );
+
+    if (result.status === 0) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function normalizeBinName(binName) {
+  const baseName = path.basename(binName || "hermes-agent").toLowerCase();
+  return baseName.replace(/(\.cmd|\.exe)$/i, "");
+}
+
+function getPythonEntryPoint(binName) {
+  return normalizeBinName(binName) === "hermes" ? "hermes_cli.main" : "run_agent";
+}
+
+function getPythonCode(binName) {
+  const moduleName = getPythonEntryPoint(binName);
+  return `from ${moduleName} import main; raise SystemExit(main())`;
+}
+
+function buildPythonInvocation(candidate, binName, userArgs) {
+  return {
+    command: candidate.command,
+    args: [...candidate.args, "-c", getPythonCode(binName), ...userArgs]
+  };
+}
+
+function getPythonPackageSpec() {
+  const version = packageJson.hermesAgent?.pythonPackageVersion || packageJson.version;
+  return `hermes-agent==${version}`;
+}
+
+function runHermes(binName, userArgs, stdio = "inherit") {
+  const candidate = findPython();
+
+  if (!candidate) {
+    console.error("Hermes Agent requires Python 3.11 or newer.");
+    console.error("Install Python, then run: python -m pip install --upgrade " + getPythonPackageSpec());
+    return 1;
+  }
+
+  const invocation = buildPythonInvocation(candidate, binName, userArgs);
+  const child = spawn(invocation.command, invocation.args, { stdio, windowsHide: false });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 1);
+  });
+
+  child.on("error", (error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+
+  return 0;
+}
+
+module.exports = {
+  buildPythonInvocation,
+  findPython,
+  getPythonCandidates,
+  getPythonEntryPoint,
+  getPythonPackageSpec,
+  runHermes
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "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",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "hermes": "bin/hermes-agent.js",
+    "hermes-agent": "bin/hermes-agent.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wyrtensi/hermes-agent-npm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NousResearch/Hermes-Agent/issues"
+  },
+  "homepage": "https://github.com/NousResearch/Hermes-Agent#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/postinstall.js",
+    "README.md"
+  ],
+  "hermesAgent": {
+    "pythonPackageVersion": "0.14.0",
+    "upstreamRepository": "nousresearch/hermes-agent"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const { findPython, getPythonPackageSpec } = require("../lib/python-launcher");
+
+const candidate = findPython();
+const packageSpec = getPythonPackageSpec();
+
+if (!candidate) {
+  console.error("Hermes Agent requires Python 3.11 or newer.");
+  console.error(`Install Python, then run: python -m pip install --upgrade ${packageSpec}`);
+  process.exit(1);
+}
+
+function runPip(extraArgs) {
+  return spawnSync(
+    candidate.command,
+    [...candidate.args, "-m", "pip", "install", "--upgrade", ...extraArgs, packageSpec],
+    { stdio: "inherit", windowsHide: true }
+  );
+}
+
+let result = runPip([]);
+
+if (result.status !== 0) {
+  console.warn("Global pip install failed; retrying with --user.");
+  result = runPip(["--user"]);
+}
+
+if (result.status !== 0) {
+  console.error(`Failed to install ${packageSpec}.`);
+  process.exit(result.status || 1);
+}