hermes-agent 0.19.0 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DISCLAIMER.md +15 -16
- package/NOTICE +13 -11
- package/PRIVACY.md +59 -22
- package/README.md +472 -89
- package/SECURITY.md +291 -138
- package/bin/hermes-npm.js +5 -0
- package/lib/npm-channel.js +533 -0
- package/lib/package-metadata.js +1 -1
- package/lib/python-launcher.js +45 -52
- package/lib/upstream-migration.js +336 -0
- package/lib/uv-installer.js +258 -0
- package/package.json +20 -6
- package/scripts/postinstall.js +294 -46
package/README.md
CHANGED
|
@@ -1,158 +1,541 @@
|
|
|
1
1
|
# hermes-agent npm bridge
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/hermes-agent)
|
|
4
|
+
[](https://www.npmjs.com/package/hermes-agent)
|
|
5
|
+
[](https://github.com/wyrtensi/hermes-agent-npm/actions/workflows/ci.yml)
|
|
6
|
+
[](https://github.com/NousResearch/hermes-agent/releases)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://docs.npmjs.com/generating-provenance-statements)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
> [!IMPORTANT]
|
|
12
|
+
> **The deployment model changed in `0.20.0`.** Upstream Hermes Agent stopped
|
|
13
|
+
> publishing new PyPI releases. This bridge now creates a package-local Git
|
|
14
|
+
> checkout and an isolated Python runtime managed by `uv`. Existing users must
|
|
15
|
+
> reinstall the npm package. Python is no longer required on the host, but Git
|
|
16
|
+
> is required so the native `hermes update` command works consistently.
|
|
17
|
+
|
|
18
|
+
An unofficial npm bridge for [Hermes Agent](https://github.com/NousResearch/hermes-agent)
|
|
19
|
+
by Nous Research. It exposes the upstream `hermes` and `hermes-agent` commands
|
|
20
|
+
through npm. Normal npm installation does not execute the upstream shell or
|
|
21
|
+
PowerShell installers. An explicit, confirmed upstream handoff can run the
|
|
22
|
+
installer stored in the verified Release checkout.
|
|
23
|
+
|
|
24
|
+
This project is not affiliated with, endorsed by, sponsored by, or maintained
|
|
25
|
+
by Nous Research.
|
|
26
|
+
|
|
27
|
+
## Contents
|
|
28
|
+
|
|
29
|
+
- [Choose an installation method](#choose-an-installation-method)
|
|
30
|
+
- [Migration from pre-0.20](#migration-from-pre-020)
|
|
31
|
+
- [Install](#install)
|
|
32
|
+
- [Two update channels](#two-update-channels)
|
|
33
|
+
- [Move from npm to an upstream-managed install](#move-from-npm-to-an-upstream-managed-install)
|
|
34
|
+
- [Commands](#commands)
|
|
35
|
+
- [How installation works](#how-installation-works)
|
|
36
|
+
- [Runtime layout and isolation](#runtime-layout-and-isolation)
|
|
37
|
+
- [Release automation](#release-automation)
|
|
38
|
+
- [Security and privacy](#security-and-privacy)
|
|
39
|
+
- [Troubleshooting](#troubleshooting)
|
|
40
|
+
- [Development](#development)
|
|
41
|
+
- [Legal and attribution](#legal-and-attribution)
|
|
42
|
+
|
|
43
|
+
## Choose an installation method
|
|
44
|
+
|
|
45
|
+
Choose one owner for the Hermes runtime. This table is intentionally near the
|
|
46
|
+
top so both people and repository-scanning agents see the deployment boundary
|
|
47
|
+
before copying an install command.
|
|
48
|
+
|
|
49
|
+
| Method | Install | Code and venv | Updates | Removal |
|
|
50
|
+
| --- | --- | --- | --- | --- |
|
|
51
|
+
| npm-isolated (recommended for npm users) | Global: `npm install --global hermes-agent`; project: `npm install hermes-agent` | Inside the npm package | `hermes update` or `hermes-npm update` | Matching global/project `npm uninstall` |
|
|
52
|
+
| upstream-managed | [Official upstream installer](https://github.com/NousResearch/hermes-agent#quick-install) or the handoff below | User-scoped `$HERMES_HOME/hermes-agent` | `hermes update` | `hermes uninstall` |
|
|
53
|
+
| manual development | [Upstream contributing guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Developer checkout with an external venv | Developer-managed Git and `uv` | Remove the selected checkout and venv |
|
|
54
|
+
|
|
55
|
+
Machine-readable discovery:
|
|
5
56
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
57
|
+
```bash
|
|
58
|
+
hermes-npm methods --json
|
|
59
|
+
hermes-npm status --json
|
|
60
|
+
```
|
|
9
61
|
|
|
10
|
-
|
|
11
|
-
[NousResearch/Hermes-Agent](https://github.com/NousResearch/Hermes-Agent).
|
|
12
|
-
The npm bridge follows the latest published `hermes-agent` release on PyPI,
|
|
13
|
-
because the npm `postinstall` step installs that Python package.
|
|
62
|
+
Human-readable command help:
|
|
14
63
|
|
|
15
|
-
|
|
64
|
+
```bash
|
|
65
|
+
hermes-npm help install
|
|
66
|
+
hermes-npm help update
|
|
67
|
+
hermes-npm help migrate
|
|
68
|
+
hermes-npm help uninstall
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The npm default remains package-local deliberately. A global and several
|
|
72
|
+
project-local npm installations can then pin independent runtimes and npm can
|
|
73
|
+
remove everything it owns. Making every npm package write to one shared
|
|
74
|
+
`HERMES_HOME/hermes-agent` would create cross-project version races and leave
|
|
75
|
+
files outside npm ownership.
|
|
76
|
+
|
|
77
|
+
For a new upstream-managed installation that has never been owned by npm, the
|
|
78
|
+
current official commands are:
|
|
16
79
|
|
|
17
80
|
```bash
|
|
18
|
-
|
|
81
|
+
# Linux, macOS, WSL2, Termux
|
|
82
|
+
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
# Native Windows PowerShell
|
|
87
|
+
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
|
|
19
88
|
```
|
|
20
89
|
|
|
21
|
-
|
|
90
|
+
Those commands execute the current upstream network endpoint and belong to the
|
|
91
|
+
upstream trust boundary. Existing npm users can instead use the handoff below,
|
|
92
|
+
which executes the installer already present in the bridge's verified Release
|
|
93
|
+
checkout and pins the same full commit.
|
|
94
|
+
|
|
95
|
+
## Migration from pre-0.20
|
|
96
|
+
|
|
97
|
+
Versions through `0.15.2` installed a pinned `hermes-agent` package into a host
|
|
98
|
+
Python environment. The upstream `hermes update` command then independently
|
|
99
|
+
checked and upgraded that Python package through PyPI. npm could report one
|
|
100
|
+
version while Python executed another.
|
|
101
|
+
|
|
102
|
+
That legacy code was normally stored in the selected Python environment's
|
|
103
|
+
global or user `site-packages`; it was not an official source checkout at
|
|
104
|
+
`$HERMES_HOME/hermes-agent`. User configuration and state did use the normal
|
|
105
|
+
upstream `HERMES_HOME`, as they still do now.
|
|
106
|
+
|
|
107
|
+
Starting with `0.20.0`:
|
|
108
|
+
|
|
109
|
+
- PyPI is not used to install Hermes Agent itself;
|
|
110
|
+
- `uv` downloads an isolated managed Python 3.11 runtime;
|
|
111
|
+
- upstream source is checked out at the exact GitHub Release tag and commit;
|
|
112
|
+
- dependencies are synchronized from upstream `uv.lock`;
|
|
113
|
+
- `hermes update` remains the native upstream rolling updater;
|
|
114
|
+
- `hermes-npm update` is the explicit npm Release updater.
|
|
115
|
+
|
|
116
|
+
Upgrade globally with:
|
|
22
117
|
|
|
23
118
|
```bash
|
|
24
|
-
|
|
119
|
+
npm install --global hermes-agent@latest
|
|
25
120
|
```
|
|
26
121
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
122
|
+
The bridge no longer searches for or launches a system Python. Any legacy
|
|
123
|
+
Python installation of Hermes Agent is independent and is not removed
|
|
124
|
+
automatically.
|
|
30
125
|
|
|
31
|
-
|
|
126
|
+
## Install
|
|
127
|
+
|
|
128
|
+
Prerequisites:
|
|
129
|
+
|
|
130
|
+
- Node.js 20 or newer;
|
|
131
|
+
- Git available as `git` in `PATH`;
|
|
132
|
+
- network access to GitHub, Astral's Python downloads, and the Python artifact
|
|
133
|
+
indexes referenced by upstream.
|
|
134
|
+
|
|
135
|
+
Python, pip, curl, `tar`, and upstream installer scripts are not prerequisites.
|
|
136
|
+
|
|
137
|
+
Global installation:
|
|
32
138
|
|
|
33
139
|
```bash
|
|
34
|
-
hermes
|
|
35
|
-
hermes
|
|
140
|
+
npm install --global hermes-agent
|
|
141
|
+
hermes --help
|
|
36
142
|
```
|
|
37
143
|
|
|
38
|
-
|
|
39
|
-
repository publishes `hermes-agent` and exposes `hermes` as a CLI binary.
|
|
144
|
+
Project installation:
|
|
40
145
|
|
|
41
|
-
|
|
146
|
+
```bash
|
|
147
|
+
npm install hermes-agent
|
|
148
|
+
npx hermes --help
|
|
149
|
+
```
|
|
42
150
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- Install-script security notes: see [SECURITY.md](SECURITY.md).
|
|
151
|
+
The first install downloads Python and dependencies and can take several
|
|
152
|
+
minutes. A Windows test installation of `0.20.0` occupied about 450 MB after
|
|
153
|
+
the temporary dependency cache was removed; size varies by platform and future
|
|
154
|
+
upstream dependencies.
|
|
48
155
|
|
|
49
|
-
|
|
156
|
+
> [!WARNING]
|
|
157
|
+
> Stop running Hermes gateways and agents before an npm reinstall or npm-channel
|
|
158
|
+
> update. npm may replace the package-local checkout and virtual environment.
|
|
50
159
|
|
|
51
|
-
|
|
160
|
+
> [!CAUTION]
|
|
161
|
+
> While npm owns the deployment, do not run `hermes uninstall`. The upstream
|
|
162
|
+
> uninstaller operates on the checkout containing the running Python code and
|
|
163
|
+
> can delete the package-local runtime without removing the npm package. Use
|
|
164
|
+
> `npm uninstall hermes-agent` or `npm uninstall --global hermes-agent`.
|
|
52
165
|
|
|
53
|
-
|
|
166
|
+
## Two update channels
|
|
54
167
|
|
|
55
|
-
|
|
168
|
+
The bridge intentionally exposes two independent update channels.
|
|
56
169
|
|
|
57
|
-
|
|
170
|
+
| Channel | Command | Source | Result |
|
|
171
|
+
| --- | --- | --- | --- |
|
|
172
|
+
| Native rolling | `hermes update` | Upstream Git branch, normally `main` | Runs the unmodified upstream updater |
|
|
173
|
+
| npm Release | `hermes-npm update` | Latest published `hermes-agent` npm version | Returns to the latest GitHub Release pinned by npm |
|
|
58
174
|
|
|
59
|
-
|
|
175
|
+
### Native rolling channel
|
|
60
176
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
177
|
+
```bash
|
|
178
|
+
hermes update --check
|
|
179
|
+
hermes update
|
|
180
|
+
```
|
|
64
181
|
|
|
65
|
-
|
|
182
|
+
These arguments are passed directly to the official upstream console
|
|
183
|
+
entrypoint. The bridge does not replace `cmd_update`, set `HERMES_MANAGED`, or
|
|
184
|
+
translate the command into npm operations.
|
|
185
|
+
|
|
186
|
+
After a native update, the source checkout can be newer than both the npm
|
|
187
|
+
package version and the latest upstream GitHub Release. This is expected. npm
|
|
188
|
+
integrity and provenance still cover the bridge package, but no longer attest
|
|
189
|
+
to source subsequently fetched by the native updater.
|
|
190
|
+
|
|
191
|
+
The upstream updater may also install its own managed tools, dependencies, or
|
|
192
|
+
runtime files according to upstream behavior. In the current upstream release,
|
|
193
|
+
that includes a managed `uv` under `HERMES_HOME/bin` (normally `~/.hermes/bin`)
|
|
194
|
+
and may include checkout-local runtime-repair files. This is outside the npm
|
|
195
|
+
release-pinned boundary and is the explicit tradeoff for keeping native update
|
|
196
|
+
behavior unchanged.
|
|
197
|
+
|
|
198
|
+
### npm Release channel
|
|
199
|
+
|
|
200
|
+
Inspect the local relationship between npm and the live checkout:
|
|
66
201
|
|
|
67
202
|
```bash
|
|
68
|
-
npm
|
|
203
|
+
hermes-npm status
|
|
204
|
+
hermes-npm status --json
|
|
69
205
|
```
|
|
70
206
|
|
|
71
|
-
|
|
207
|
+
Check the npm registry:
|
|
72
208
|
|
|
73
209
|
```bash
|
|
74
|
-
hermes
|
|
75
|
-
hermes-agent --help
|
|
210
|
+
hermes-npm check
|
|
76
211
|
```
|
|
77
212
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
213
|
+
Return to or advance along the release-pinned channel:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
hermes-npm update
|
|
217
|
+
```
|
|
81
218
|
|
|
82
|
-
|
|
219
|
+
When a newer npm version exists, `hermes-npm update` installs the exact version
|
|
220
|
+
returned by its check from the same canonical registry. It does not resolve the
|
|
221
|
+
mutable `latest` tag a second time. Depending on installation scope, the
|
|
222
|
+
effective command is equivalent to:
|
|
83
223
|
|
|
84
224
|
```bash
|
|
85
|
-
|
|
225
|
+
npm install --global --registry=https://registry.npmjs.org hermes-agent@<checked-version>
|
|
226
|
+
npm install --registry=https://registry.npmjs.org hermes-agent@<checked-version>
|
|
86
227
|
```
|
|
87
228
|
|
|
88
|
-
|
|
89
|
-
|
|
229
|
+
An npm update intentionally replaces native rolling changes with the exact
|
|
230
|
+
checkout pinned by the npm Release. If npm is already at the latest version but
|
|
231
|
+
the live checkout has moved, `hermes-npm update` directly reprovisions that
|
|
232
|
+
same release commit. This discards tracked source changes in the package-local
|
|
233
|
+
checkout; upstream user configuration under `HERMES_HOME` is unaffected.
|
|
234
|
+
Running `npm rebuild` for the same package version instead
|
|
235
|
+
preserves an existing native-updated checkout and only resynchronizes its
|
|
236
|
+
environment.
|
|
90
237
|
|
|
91
|
-
|
|
238
|
+
For automation and agents, `hermes-npm status --json` is the canonical
|
|
239
|
+
machine-readable note. Child processes also receive:
|
|
92
240
|
|
|
93
|
-
|
|
241
|
+
```text
|
|
242
|
+
HERMES_NPM_BRIDGE=1
|
|
243
|
+
HERMES_NPM_PACKAGE_ROOT=<package directory>
|
|
244
|
+
HERMES_NPM_PACKAGE_VERSION=<npm version>
|
|
245
|
+
HERMES_NPM_RELEASE_TAG=<upstream release tag>
|
|
246
|
+
```
|
|
94
247
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- when a tag matching `npm-v*` is pushed
|
|
248
|
+
The bridge deliberately does not set `HERMES_MANAGED`; upstream currently uses
|
|
249
|
+
that flag to prohibit configuration and setup changes in addition to updates.
|
|
98
250
|
|
|
99
|
-
|
|
251
|
+
## Move from npm to an upstream-managed install
|
|
100
252
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
4. Skips publishing if the matching Python `hermes-agent==<version>` package
|
|
105
|
-
is not available on PyPI yet.
|
|
106
|
-
5. Runs `npm test`.
|
|
107
|
-
6. Runs `npm pack --dry-run`.
|
|
108
|
-
7. Publishes missing npm packages through npm trusted publishing with GitHub
|
|
109
|
-
Actions OIDC and npm provenance.
|
|
253
|
+
Use a one-way handoff when you want the normal upstream source location, PATH
|
|
254
|
+
integration, native uninstaller, and `hermes update` as the sole update owner.
|
|
255
|
+
First inspect the exact plan; this makes no changes:
|
|
110
256
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
257
|
+
```bash
|
|
258
|
+
hermes-npm migrate upstream
|
|
259
|
+
hermes-npm migrate upstream --json
|
|
260
|
+
```
|
|
114
261
|
|
|
115
|
-
|
|
262
|
+
Stop running Hermes processes, then execute it explicitly:
|
|
116
263
|
|
|
117
|
-
|
|
264
|
+
```bash
|
|
265
|
+
hermes-npm migrate upstream --yes
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The handoff:
|
|
269
|
+
|
|
270
|
+
1. requires the npm runtime to be at its exact Release-pinned commit;
|
|
271
|
+
2. uses `scripts/install.sh` or `scripts/install.ps1` from that already verified
|
|
272
|
+
checkout rather than downloading a mutable installer endpoint;
|
|
273
|
+
3. passes the exact commit and uses non-interactive, skip-setup mode;
|
|
274
|
+
4. installs to the user-scoped `$HERMES_HOME/hermes-agent` target on macOS and
|
|
275
|
+
Linux or `%LOCALAPPDATA%\hermes\hermes-agent` on Windows, unless
|
|
276
|
+
`HERMES_HOME` is already set;
|
|
277
|
+
5. verifies the resulting Git commit and venv `hermes` executable;
|
|
278
|
+
6. only after successful verification, removes the npm package in its detected
|
|
279
|
+
local or global scope;
|
|
280
|
+
7. re-runs only the official installer's idempotent `path` stage from the new
|
|
281
|
+
checkout, so a global npm uninstall cannot delete an official launcher when
|
|
282
|
+
both installations use the same bin directory.
|
|
283
|
+
|
|
284
|
+
Configuration, credentials, sessions, memories, skills, and other user state
|
|
285
|
+
under `HERMES_HOME` are preserved. The command refuses a non-Git target, a Git
|
|
286
|
+
target with an unexpected origin or uncommitted files, a `HERMES_HOME` inside
|
|
287
|
+
the npm package, or a runtime that has moved off its packaged Release. Run
|
|
288
|
+
`hermes-npm update` first if native rolling changes need to be reset before
|
|
289
|
+
handoff. Existing upstream checkout changes must be committed, stashed, or
|
|
290
|
+
removed explicitly; the bridge never answers an upstream restore prompt.
|
|
291
|
+
|
|
292
|
+
This is not a side-by-side mode. Two active checkouts sharing the same command
|
|
293
|
+
names, PATH entries, gateway definitions, ports, tokens, and user state cannot
|
|
294
|
+
be given reliable ownership across Windows, macOS, and Linux. To return later,
|
|
295
|
+
uninstall the upstream deployment while preserving the desired user data, then
|
|
296
|
+
install the npm package again.
|
|
297
|
+
|
|
298
|
+
Run the handoff as the account that should own `HERMES_HOME`; do not add `sudo`
|
|
299
|
+
just because the existing global npm package is root-owned. If the final global
|
|
300
|
+
npm removal lacks permission, the verified upstream installation remains in
|
|
301
|
+
place and the command prints the exact npm removal command to run separately
|
|
302
|
+
with the permissions required by that npm prefix.
|
|
303
|
+
|
|
304
|
+
## Commands
|
|
305
|
+
|
|
306
|
+
```bash
|
|
307
|
+
hermes # primary upstream CLI
|
|
308
|
+
hermes-agent # legacy/direct run_agent entrypoint
|
|
309
|
+
hermes-npm # npm ownership, release channel, methods, and handoff
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
`hermes` should be preferred for normal use. `hermes-agent` preserves upstream
|
|
313
|
+
legacy behavior; notably, its Fire-based argument handling is not equivalent
|
|
314
|
+
to the main CLI, and `hermes-agent --help` may initialize the direct agent
|
|
315
|
+
instead of acting like `hermes --help`.
|
|
316
|
+
|
|
317
|
+
The npm package is named `hermes-agent`. The unscoped package name `hermes`
|
|
318
|
+
belongs to another project, so this package exposes `hermes` only as a binary.
|
|
319
|
+
|
|
320
|
+
The repository can also build an alias package named `hermesagent` for legacy
|
|
321
|
+
compatibility testing; it is not published by the automated release workflow.
|
|
322
|
+
Installing both names is unnecessary and creates two isolated runtimes. An
|
|
323
|
+
alias installation can check the canonical `hermes-agent` Release channel, but
|
|
324
|
+
it refuses to install the canonical package over the alias automatically.
|
|
325
|
+
Instead, it prints scope-appropriate commands that remove the alias first and
|
|
326
|
+
then install the exact checked canonical version.
|
|
327
|
+
|
|
328
|
+
### `hermes-npm` command reference
|
|
329
|
+
|
|
330
|
+
| Command | Effect |
|
|
331
|
+
| --- | --- |
|
|
332
|
+
| `hermes-npm status [--json]` | Report npm identity, exact live Git commit, channel, dirty state, and install scope |
|
|
333
|
+
| `hermes-npm check [--json]` | Read the canonical npm Release channel without changing files |
|
|
334
|
+
| `hermes-npm update` | Install the checked exact npm version or reset the current runtime to its packaged Release |
|
|
335
|
+
| `hermes-npm methods [--json]` | List supported installation/ownership models for users and automation |
|
|
336
|
+
| `hermes-npm migrate upstream [--json]` | Show the one-way upstream handoff plan without changing files |
|
|
337
|
+
| `hermes-npm migrate upstream --yes` | Execute, verify, and finish the upstream handoff |
|
|
338
|
+
| `hermes-npm help [topic]` | Explain install, update, migration, or uninstall behavior |
|
|
339
|
+
|
|
340
|
+
## How installation works
|
|
341
|
+
|
|
342
|
+
`scripts/postinstall.js` performs the following without invoking a shell:
|
|
343
|
+
|
|
344
|
+
1. Validates the upstream repository, Release tag, and full commit SHA stored
|
|
345
|
+
in `package.json`.
|
|
346
|
+
2. Requires Git and creates a shallow checkout of the exact tag.
|
|
347
|
+
3. Verifies that the fetched tag resolves to the committed SHA before checkout.
|
|
348
|
+
4. Downloads the pinned Astral `uv` asset for the current OS, architecture, and
|
|
349
|
+
Linux libc variant.
|
|
350
|
+
5. Verifies the `uv` archive against a SHA-256 digest committed in
|
|
351
|
+
`lib/uv-installer.js` and extracts only the executable.
|
|
352
|
+
6. Creates an `uv`-managed Python 3.11 installation and `venv/` inside the
|
|
353
|
+
upstream checkout.
|
|
354
|
+
7. Runs `uv sync --locked --extra all --no-dev` using upstream project
|
|
355
|
+
configuration and `uv.lock`.
|
|
356
|
+
8. Deletes the temporary dependency cache and writes a runtime marker.
|
|
357
|
+
|
|
358
|
+
`HERMES_NIX_BUILD` is not enabled. It is not an installation or update endpoint
|
|
359
|
+
for this pinned upstream Release and would not provide npm ownership,
|
|
360
|
+
cross-platform Python provisioning, or a native-update checkout. The bridge
|
|
361
|
+
therefore uses the locked editable source synchronization path directly.
|
|
362
|
+
|
|
363
|
+
The launcher executes the real console scripts generated in the isolated venv:
|
|
118
364
|
|
|
119
365
|
```text
|
|
120
|
-
hermes-agent
|
|
366
|
+
Windows: runtime/hermes-agent/venv/Scripts/hermes.exe
|
|
367
|
+
macOS/Linux: runtime/hermes-agent/venv/bin/hermes
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
Arguments, current working directory, standard streams, exit code, and native
|
|
371
|
+
upstream update handling are preserved.
|
|
372
|
+
|
|
373
|
+
## Runtime layout and isolation
|
|
374
|
+
|
|
375
|
+
```text
|
|
376
|
+
hermes-agent/
|
|
377
|
+
├── .hermes-agent-runtime.json
|
|
378
|
+
├── .uv_bin/ # checksum-pinned uv
|
|
379
|
+
├── runtime/
|
|
380
|
+
│ ├── python/ # uv-managed Python
|
|
381
|
+
│ └── hermes-agent/
|
|
382
|
+
│ ├── .git/ # native update checkout
|
|
383
|
+
│ ├── venv/ # isolated dependencies and entrypoints
|
|
384
|
+
│ └── ... # upstream source and assets
|
|
385
|
+
├── bin/ # npm command shims
|
|
386
|
+
├── lib/ # bridge code
|
|
387
|
+
└── package.json # release tag and commit pin
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
The npm installer does not modify system Python, Git configuration, shell
|
|
391
|
+
profiles, or global `PATH` beyond npm's normal binary shims. It does not change
|
|
392
|
+
`HERMES_HOME`; upstream user configuration and state therefore retain their
|
|
393
|
+
normal location and survive npm reinstall/uninstall.
|
|
394
|
+
|
|
395
|
+
The package-local checkout is mutable by design because native updates are
|
|
396
|
+
enabled. Removing the npm package removes this runtime, but it does not remove
|
|
397
|
+
upstream user data.
|
|
398
|
+
|
|
399
|
+
The explicit upstream handoff is the exception to the package-local boundary:
|
|
400
|
+
the pinned official installer creates the official checkout and may update
|
|
401
|
+
user PATH and managed prerequisites according to upstream behavior. It is
|
|
402
|
+
never run by `npm install` and requires `--yes`.
|
|
403
|
+
|
|
404
|
+
## Release automation
|
|
405
|
+
|
|
406
|
+
The publish workflow runs on a schedule and through manual `workflow_dispatch`.
|
|
407
|
+
It reads the latest non-draft, non-prerelease upstream GitHub Release and then:
|
|
408
|
+
|
|
409
|
+
1. resolves annotated tags to their final commit SHA;
|
|
410
|
+
2. reads `project.version` from `pyproject.toml` at that exact commit;
|
|
411
|
+
3. updates npm package metadata;
|
|
412
|
+
4. refuses to reuse an npm version if its published tag/commit mapping differs;
|
|
413
|
+
5. runs wrapper tests, a native `hermes update --check`, and full runtime smoke
|
|
414
|
+
tests on Windows, macOS, and Linux;
|
|
415
|
+
6. publishes through npm trusted publishing with provenance.
|
|
416
|
+
|
|
417
|
+
Polling follows GitHub Releases, not PyPI and not the tip of `main`. Native
|
|
418
|
+
`hermes update` remains independent and may advance between Releases.
|
|
419
|
+
|
|
420
|
+
## Security and privacy
|
|
421
|
+
|
|
422
|
+
- [SECURITY.md](SECURITY.md) documents lifecycle-script behavior, trust
|
|
423
|
+
boundaries, reporting, and the reduced attestation boundary after native
|
|
424
|
+
updates.
|
|
425
|
+
- [PRIVACY.md](PRIVACY.md) documents installation and runtime network activity.
|
|
426
|
+
- [DISCLAIMER.md](DISCLAIMER.md) and [NOTICE](NOTICE) identify the unofficial
|
|
427
|
+
relationship with upstream.
|
|
428
|
+
|
|
429
|
+
The bridge itself does not collect telemetry. Runtime providers and tools used
|
|
430
|
+
by upstream Hermes Agent have their own behavior and policies.
|
|
431
|
+
|
|
432
|
+
Audit without running lifecycle scripts:
|
|
433
|
+
|
|
434
|
+
```bash
|
|
435
|
+
npm pack hermes-agent
|
|
436
|
+
npm install --ignore-scripts ./hermes-agent-*.tgz
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
After review:
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
npm rebuild hermes-agent
|
|
121
443
|
```
|
|
122
444
|
|
|
123
|
-
|
|
445
|
+
Use `npm rebuild --global hermes-agent` for a global installation.
|
|
446
|
+
|
|
447
|
+
## Troubleshooting
|
|
448
|
+
|
|
449
|
+
### Git is required
|
|
124
450
|
|
|
125
451
|
```text
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
452
|
+
Git is required for the native 'hermes update' channel
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
Install Git, confirm `git --version`, and run:
|
|
456
|
+
|
|
457
|
+
```bash
|
|
458
|
+
npm rebuild hermes-agent
|
|
132
459
|
```
|
|
133
460
|
|
|
134
|
-
|
|
135
|
-
also defines a matching GitHub Actions environment. In the package's npm
|
|
136
|
-
Publishing access settings, use `Require two-factor authentication and disallow
|
|
137
|
-
tokens` after trusted publishing is configured. GitHub Actions will keep
|
|
138
|
-
publishing through OIDC, while long-lived npm publish tokens are blocked.
|
|
461
|
+
### Runtime is not ready
|
|
139
462
|
|
|
140
|
-
|
|
463
|
+
If installation was performed with `--ignore-scripts`, provision it explicitly:
|
|
141
464
|
|
|
142
465
|
```bash
|
|
143
|
-
|
|
144
|
-
git push -u origin main
|
|
466
|
+
npm rebuild hermes-agent
|
|
145
467
|
```
|
|
146
468
|
|
|
147
|
-
|
|
148
|
-
first publish.
|
|
469
|
+
### Native and npm versions differ
|
|
149
470
|
|
|
150
|
-
|
|
471
|
+
This is expected after `hermes update`. Inspect both identities with:
|
|
472
|
+
|
|
473
|
+
```bash
|
|
474
|
+
hermes-npm status
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
Use `hermes-npm update` to return to a published Release.
|
|
478
|
+
|
|
479
|
+
### npm update cannot replace files
|
|
480
|
+
|
|
481
|
+
Stop running agents, gateways, desktop processes, and terminals using the
|
|
482
|
+
package runtime, then retry the npm update.
|
|
483
|
+
|
|
484
|
+
### `hermes uninstall` broke an npm installation
|
|
485
|
+
|
|
486
|
+
Rebuild or reinstall the npm package:
|
|
487
|
+
|
|
488
|
+
```bash
|
|
489
|
+
npm rebuild hermes-agent
|
|
490
|
+
# or
|
|
491
|
+
npm install --global hermes-agent@latest
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
Use npm, not the upstream uninstaller, to remove an npm-owned deployment.
|
|
495
|
+
|
|
496
|
+
### Upstream handoff is refused
|
|
497
|
+
|
|
498
|
+
Read the reported path or Git-origin conflict instead of forcing replacement.
|
|
499
|
+
If the only issue is a native-updated npm checkout, return it to the packaged
|
|
500
|
+
Release and inspect the plan again:
|
|
501
|
+
|
|
502
|
+
```bash
|
|
503
|
+
hermes-npm update
|
|
504
|
+
hermes-npm migrate upstream
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
## Development
|
|
151
508
|
|
|
152
509
|
```bash
|
|
153
|
-
python scripts/sync_upstream_version.py
|
|
154
510
|
npm test
|
|
155
511
|
npm pack --dry-run
|
|
156
512
|
npm run build:alias
|
|
157
|
-
npm pack --dry-run ./dist/hermesagent
|
|
158
513
|
```
|
|
514
|
+
|
|
515
|
+
The full local integration test downloads a managed Python runtime and upstream
|
|
516
|
+
dependencies:
|
|
517
|
+
|
|
518
|
+
```bash
|
|
519
|
+
npm run postinstall
|
|
520
|
+
npm run smoke
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
Release metadata can be refreshed with Python 3.11 or newer:
|
|
524
|
+
|
|
525
|
+
```bash
|
|
526
|
+
python scripts/sync_upstream_version.py
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
Do not publish solely because `main` changed. npm releases are synchronized
|
|
530
|
+
only from official upstream GitHub Releases.
|
|
531
|
+
|
|
532
|
+
## Legal and attribution
|
|
533
|
+
|
|
534
|
+
- Wrapper license: [MIT](LICENSE)
|
|
535
|
+
- Upstream attribution: [NOTICE](NOTICE)
|
|
536
|
+
- Unofficial-package notice: [DISCLAIMER.md](DISCLAIMER.md)
|
|
537
|
+
- Privacy notes: [PRIVACY.md](PRIVACY.md)
|
|
538
|
+
|
|
539
|
+
Bridge issues: https://github.com/wyrtensi/hermes-agent-npm/issues
|
|
540
|
+
|
|
541
|
+
Upstream issues: https://github.com/NousResearch/hermes-agent/issues
|