hermes-agent 0.22.1 → 0.22.3
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/README.md +211 -33
- package/SECURITY.md +84 -19
- package/lib/npm-channel.js +211 -49
- package/lib/provision.js +177 -0
- package/lib/python-launcher.js +67 -9
- package/lib/upstream-migration.js +2 -1
- package/lib/upstream-ownership.js +281 -0
- package/package.json +5 -5
- package/scripts/postinstall.js +49 -3
package/README.md
CHANGED
|
@@ -9,6 +9,32 @@
|
|
|
9
9
|
[](https://t.me/+AoFg5hgLSlIyYTAy)
|
|
10
10
|
[](LICENSE)
|
|
11
11
|
|
|
12
|
+
## Important recent changes
|
|
13
|
+
|
|
14
|
+
- **npm 12 skips the install script.** npm 12 blocks dependency install
|
|
15
|
+
scripts by default, so a plain install leaves `hermes` without its runtime.
|
|
16
|
+
Starting with the first npm release after `0.22.2`, the first `hermes`
|
|
17
|
+
launch provisions the runtime itself, and `hermes-npm setup` does it ahead
|
|
18
|
+
of time. On `0.22.2` and earlier, install with
|
|
19
|
+
`npm install --global --allow-scripts=hermes-agent hermes-agent`.
|
|
20
|
+
See [npm 12 and install scripts](#npm-12-and-install-scripts).
|
|
21
|
+
- **Run `hermes-npm setup` before background use.** Run it once before you
|
|
22
|
+
register `hermes` with an MCP client or a gateway service, so the first
|
|
23
|
+
background launch does not spend 1-2 minutes on setup and hit a startup
|
|
24
|
+
timeout.
|
|
25
|
+
- **`hermes update` follows upstream `stable` by default.** Unconfigured
|
|
26
|
+
checkouts track the latest GitHub Release. The rolling `main` branch is
|
|
27
|
+
opt-in through `hermes update --set-channel main`. See
|
|
28
|
+
[Two update channels](#two-update-channels).
|
|
29
|
+
- **A native `hermes update` hands dependencies to upstream.** Upstream's
|
|
30
|
+
package manager then keeps its environment under `HERMES_HOME/installs` and
|
|
31
|
+
its launchers in `~/.local/bin` (or `HERMES_HOME\bin` on Windows).
|
|
32
|
+
`hermes-npm status` shows who owns the dependencies. An npm reinstall or a
|
|
33
|
+
same-version `hermes-npm update` takes them back. See
|
|
34
|
+
[Native upstream channel](#native-upstream-channel).
|
|
35
|
+
- **The runtime uses Python 3.14** since `0.21.6`, matching upstream. See
|
|
36
|
+
[Python 3.14 in release 0.21.6](#python-314-in-release-0216).
|
|
37
|
+
|
|
12
38
|
> [!IMPORTANT]
|
|
13
39
|
> **The deployment model changed in `0.20.0`.** Upstream Hermes Agent stopped
|
|
14
40
|
> publishing new PyPI releases. This bridge now creates a package-local Git
|
|
@@ -27,9 +53,11 @@ by Nous Research.
|
|
|
27
53
|
|
|
28
54
|
## Contents
|
|
29
55
|
|
|
56
|
+
- [Important recent changes](#important-recent-changes)
|
|
30
57
|
- [Choose an installation method](#choose-an-installation-method)
|
|
31
58
|
- [Migration from pre-0.20](#migration-from-pre-020)
|
|
32
59
|
- [Install](#install)
|
|
60
|
+
- [npm 12 and install scripts](#npm-12-and-install-scripts)
|
|
33
61
|
- [Two update channels](#two-update-channels)
|
|
34
62
|
- [Move from npm to an upstream-managed install](#move-from-npm-to-an-upstream-managed-install)
|
|
35
63
|
- [Commands](#commands)
|
|
@@ -49,7 +77,7 @@ before copying an install command.
|
|
|
49
77
|
|
|
50
78
|
| Method | Install | Code and venv | Updates | Removal |
|
|
51
79
|
| --- | --- | --- | --- | --- |
|
|
52
|
-
| 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
|
|
80
|
+
| npm-isolated (recommended for npm users) | Global: `npm install --global hermes-agent`; project: `npm install hermes-agent` ([npm 12](#npm-12-and-install-scripts)) | Inside the npm package | `hermes-npm update` or `hermes update` | Matching global/project `npm uninstall` |
|
|
53
81
|
| 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` |
|
|
54
82
|
| 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 |
|
|
55
83
|
|
|
@@ -112,7 +140,7 @@ Starting with `0.20.0`:
|
|
|
112
140
|
metadata;
|
|
113
141
|
- upstream source is checked out at the exact GitHub Release tag and commit;
|
|
114
142
|
- dependencies are synchronized from upstream `uv.lock`;
|
|
115
|
-
- `hermes update` remains the native upstream
|
|
143
|
+
- `hermes update` remains the native upstream updater;
|
|
116
144
|
- `hermes-npm update` is the explicit npm Release updater.
|
|
117
145
|
|
|
118
146
|
Upgrade globally with:
|
|
@@ -155,6 +183,14 @@ minutes. A Windows test installation of `0.20.0` occupied about 450 MB after
|
|
|
155
183
|
the temporary dependency cache was removed; size varies by platform and future
|
|
156
184
|
upstream dependencies.
|
|
157
185
|
|
|
186
|
+
If npm skipped the install script (npm 12 does by default, as does
|
|
187
|
+
`--ignore-scripts`), the first `hermes` or `hermes-agent` launch performs the
|
|
188
|
+
same provisioning before starting Hermes, or you can run it explicitly:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
hermes-npm setup
|
|
192
|
+
```
|
|
193
|
+
|
|
158
194
|
> [!WARNING]
|
|
159
195
|
> Stop running Hermes gateways and agents before an npm reinstall or npm-channel
|
|
160
196
|
> update. npm may replace the package-local checkout and virtual environment.
|
|
@@ -165,16 +201,73 @@ upstream dependencies.
|
|
|
165
201
|
> can delete the package-local runtime without removing the npm package. Use
|
|
166
202
|
> `npm uninstall hermes-agent` or `npm uninstall --global hermes-agent`.
|
|
167
203
|
|
|
204
|
+
## npm 12 and install scripts
|
|
205
|
+
|
|
206
|
+
npm 12 blocks dependency install scripts by default. A plain
|
|
207
|
+
`npm install --global hermes-agent` then installs only the command shims and
|
|
208
|
+
prints `install scripts blocked`. The bridge handles this itself: the first
|
|
209
|
+
`hermes` (or `hermes-agent`, or `npx hermes`) launch runs the package's own
|
|
210
|
+
installer, prints a one-line note to stderr, and continues once the runtime is
|
|
211
|
+
ready. This is a one-time download that usually takes 1-2 minutes; concurrent
|
|
212
|
+
first launches wait for a single setup. You can also provision ahead of time:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
hermes-npm setup
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
> [!IMPORTANT]
|
|
219
|
+
> Run `hermes-npm setup` once before you register `hermes` with an MCP client,
|
|
220
|
+
> a gateway service, or any other program that starts it in the background.
|
|
221
|
+
> Otherwise the first background launch spends 1-2 minutes on setup before
|
|
222
|
+
> Hermes writes anything to stdout, and the client may give up on a startup
|
|
223
|
+
> timeout. Do the same after any `npm install` or `npm update` that replaced
|
|
224
|
+
> the package without running its install script; `hermes-npm update` already
|
|
225
|
+
> provisions the new release before it returns.
|
|
226
|
+
|
|
227
|
+
To let npm run the install script as on npm 11 and earlier:
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
# global, once
|
|
231
|
+
npm install --global --allow-scripts=hermes-agent hermes-agent
|
|
232
|
+
|
|
233
|
+
# global, every future install
|
|
234
|
+
npm config set allow-scripts=hermes-agent --location=user
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
For a project dependency, npm 12 rejects `--allow-scripts` and records the
|
|
238
|
+
approval in `package.json` instead:
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
npm install hermes-agent
|
|
242
|
+
npm install-scripts approve hermes-agent
|
|
243
|
+
npm rebuild hermes-agent
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
By default `approve` pins the entry to the installed version
|
|
247
|
+
(`"allowScripts": {"hermes-agent@<version>": true}`), so every version bump
|
|
248
|
+
needs a new approval. `npm install-scripts approve --no-allow-scripts-pin hermes-agent`
|
|
249
|
+
writes a name-only entry instead. Without any approval, `hermes-npm setup` or
|
|
250
|
+
the first launch provisions the runtime.
|
|
251
|
+
|
|
252
|
+
`hermes-npm update` does not depend on npm running the script either: after
|
|
253
|
+
npm installs the checked release, it runs the new package's installer directly
|
|
254
|
+
when the runtime is missing. On npm 11 and earlier nothing changes, because
|
|
255
|
+
npm has already provisioned the runtime by then.
|
|
256
|
+
|
|
257
|
+
Set `HERMES_NPM_AUTO_SETUP=0` to turn off provisioning on launch; `hermes` then
|
|
258
|
+
exits with an error that points to `hermes-npm setup`.
|
|
259
|
+
|
|
168
260
|
## Two update channels
|
|
169
261
|
|
|
170
262
|
The bridge intentionally exposes two independent update channels.
|
|
171
263
|
|
|
172
264
|
| Channel | Command | Source | Result |
|
|
173
265
|
| --- | --- | --- | --- |
|
|
174
|
-
| Native rolling | `hermes update` | Upstream Git branch, normally `main` | Runs the unmodified upstream updater |
|
|
175
266
|
| npm Release | `hermes-npm update` | Latest published `hermes-agent` npm version | Returns to the latest GitHub Release pinned by npm |
|
|
267
|
+
| Native upstream | `hermes update` | Upstream `stable` channel by default: the latest GitHub Release, forward only | Runs the unmodified upstream updater |
|
|
268
|
+
| Native rolling (opt-in) | `hermes update --set-channel main`, then `hermes update` | Upstream `main` branch | Runs the unmodified upstream updater on the rolling branch |
|
|
176
269
|
|
|
177
|
-
### Native
|
|
270
|
+
### Native upstream channel
|
|
178
271
|
|
|
179
272
|
```bash
|
|
180
273
|
hermes update --check
|
|
@@ -185,17 +278,73 @@ These arguments are passed directly to the official upstream console
|
|
|
185
278
|
entrypoint. The bridge does not replace `cmd_update`, set `HERMES_MANAGED`, or
|
|
186
279
|
translate the command into npm operations.
|
|
187
280
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
281
|
+
Since upstream `v0.21.6`, an official checkout with no configured channel
|
|
282
|
+
tracks `stable`: `hermes update --check` prints `Update channel: stable`, and
|
|
283
|
+
`hermes update` moves only forward to the latest upstream GitHub Release. The
|
|
284
|
+
package-local checkout counts as such a checkout. The rolling `main` branch is
|
|
285
|
+
opt-in through `hermes update --set-channel main` (`--set-channel stable`
|
|
286
|
+
returns). Because the bridge publishes each upstream Release to npm, the
|
|
287
|
+
native stable channel usually reaches a new Release before `hermes-npm update`
|
|
288
|
+
does, and lands on the same commit.
|
|
289
|
+
|
|
290
|
+
After a native update, the source checkout can be newer than the npm package
|
|
291
|
+
version, and on the `main` channel newer than the latest upstream GitHub
|
|
292
|
+
Release. This is expected. npm integrity and provenance still cover the bridge
|
|
293
|
+
package, but no longer attest to source subsequently fetched by the native
|
|
294
|
+
updater.
|
|
295
|
+
|
|
296
|
+
The upstream updater also manages its own tools and environments according to
|
|
297
|
+
upstream behavior. In upstream `v0.22.x` it unshallows the package-local Git
|
|
298
|
+
checkout, builds a new dependency environment with its own managed Python and
|
|
299
|
+
`uv` under `HERMES_HOME/installs` and `HERMES_HOME/tools`, writes an
|
|
300
|
+
`install-stamp.json` into the checkout, and can publish `hermes` launchers
|
|
301
|
+
outside npm: `~/.local/bin` on macOS and Linux, and `HERMES_HOME\bin` added to
|
|
302
|
+
the user `PATH` on Windows. These are outside the npm release-pinned boundary
|
|
303
|
+
and are the explicit tradeoff for keeping native update behavior unchanged.
|
|
304
|
+
|
|
305
|
+
After a native update, upstream owns the dependency environment and the
|
|
306
|
+
launchers:
|
|
307
|
+
|
|
308
|
+
- Upstream records the environment it built under
|
|
309
|
+
`HERMES_HOME/installs/<key>`, where the key is derived from the checkout
|
|
310
|
+
path, marks the checkout as self-managed with an untracked
|
|
311
|
+
`install-stamp.json`, and selects that environment at startup instead of the
|
|
312
|
+
package's own `venv`. `hermes-npm status` reports this as
|
|
313
|
+
`dependencies: upstream package manager` (`dependenciesOwner: "upstream-pm"`
|
|
314
|
+
in `--json`, with the selected environment in `dependencyEnvironment`) and
|
|
315
|
+
does not report the `npm-release` channel. The record lives in
|
|
316
|
+
`~/.hermes/installs` (`%LOCALAPPDATA%\hermes\installs` on Windows) unless
|
|
317
|
+
`HERMES_HOME` points outside that directory, in which case it lives in
|
|
318
|
+
`HERMES_HOME/installs` (or `<root>/installs` for a `<root>/profiles/<name>`
|
|
319
|
+
home); `<key>` is the first 16 hex digits of the SHA-256 of the
|
|
320
|
+
`runtime source` path that `hermes-npm status` prints.
|
|
321
|
+
- npm takes the dependencies back whenever the bridge puts the checkout back
|
|
322
|
+
on the commit pinned by the npm package: after `npm install` replaces the
|
|
323
|
+
package (or `hermes-npm update` installs a newer one) and provisions a fresh
|
|
324
|
+
checkout, and when a same-version `hermes-npm update` resets the checkout in
|
|
325
|
+
place. The installer then removes that `installs/<key>` directory and the
|
|
326
|
+
checkout's `install-stamp.json`, prints what it removed, and upstream falls
|
|
327
|
+
back to the package `venv`. Nothing else under `HERMES_HOME` is touched, so
|
|
328
|
+
upstream's shared tools under `HERMES_HOME/tools` and all user data stay.
|
|
329
|
+
`hermes-npm setup` and `npm rebuild` for the same version keep the existing
|
|
330
|
+
checkout and therefore keep a native update, dependencies included. The
|
|
331
|
+
installer uses the `HERMES_HOME` of the shell it runs in; run it with the
|
|
332
|
+
same `HERMES_HOME` as `hermes update`.
|
|
333
|
+
- The launchers upstream publishes in `~/.local/bin` execute files inside the
|
|
334
|
+
npm package (`runtime/hermes-agent/.hermes/bin`). They stop working once npm
|
|
335
|
+
reinstalls or removes the package; if `~/.local/bin` comes before the npm
|
|
336
|
+
prefix in `PATH`, `hermes` then fails instead of reaching the npm shim.
|
|
337
|
+
Remove those three files (`hermes`, `hermes-agent`, `hermes-acp`) if they
|
|
338
|
+
point into the npm package. Setting `cli.expose_on_path: false` in
|
|
339
|
+
`HERMES_HOME/config.yaml` stops upstream from publishing them on macOS and
|
|
340
|
+
Linux; it has no effect on Windows, where upstream publishes its launchers
|
|
341
|
+
in the `bin` directory it adds to the user `PATH`.
|
|
342
|
+
|
|
343
|
+
To return fully to npm ownership after a native update, run `hermes-npm update`
|
|
344
|
+
or reinstall the package, and remove those launchers yourself; the bridge does
|
|
345
|
+
not remove files outside the npm package other than that `installs/<key>`
|
|
346
|
+
directory. User configuration, sessions, and skills elsewhere in `HERMES_HOME`
|
|
347
|
+
are not affected.
|
|
199
348
|
|
|
200
349
|
### npm Release channel
|
|
201
350
|
|
|
@@ -206,6 +355,17 @@ hermes-npm status
|
|
|
206
355
|
hermes-npm status --json
|
|
207
356
|
```
|
|
208
357
|
|
|
358
|
+
`runtimeChannel` is `npm-release` only when the checkout is clean at the commit
|
|
359
|
+
pinned by the npm package and npm owns its dependencies. It is
|
|
360
|
+
`upstream-native` when the source has moved, when upstream's package manager
|
|
361
|
+
has recorded a dependency environment for the checkout
|
|
362
|
+
(`dependenciesOwner: "upstream-pm"`, read from
|
|
363
|
+
`<root>/installs/<key>/facts.json` exactly where upstream looks), or when the
|
|
364
|
+
checkout carries an untracked `install-stamp.json` with
|
|
365
|
+
`updateMechanism: "self"` (`upstreamSelfManagedStamp`), which hands it to
|
|
366
|
+
upstream's package manager on its next launch. `hermes-npm status` reads only
|
|
367
|
+
the record for the active Hermes root, the one upstream itself selects first.
|
|
368
|
+
|
|
209
369
|
Check the npm registry:
|
|
210
370
|
|
|
211
371
|
```bash
|
|
@@ -228,13 +388,16 @@ npm install --global --registry=https://registry.npmjs.org hermes-agent@<checked
|
|
|
228
388
|
npm install --registry=https://registry.npmjs.org hermes-agent@<checked-version>
|
|
229
389
|
```
|
|
230
390
|
|
|
231
|
-
An npm update intentionally replaces
|
|
232
|
-
checkout pinned by the npm Release. If npm is already at the latest version but
|
|
233
|
-
the live checkout has moved,
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
391
|
+
An npm update intentionally replaces source moved by a native update with
|
|
392
|
+
the exact checkout pinned by the npm Release. If npm is already at the latest version but
|
|
393
|
+
the live checkout has moved, or upstream's package manager owns its
|
|
394
|
+
dependencies, `hermes-npm update` directly reprovisions that same release
|
|
395
|
+
commit. This discards tracked source changes in the package-local checkout and
|
|
396
|
+
returns dependency selection to the package `venv` as described under
|
|
397
|
+
[Native upstream channel](#native-upstream-channel); upstream user
|
|
398
|
+
configuration under `HERMES_HOME` is unaffected.
|
|
399
|
+
Running `hermes-npm setup` (or `npm rebuild`) for the same package version
|
|
400
|
+
instead preserves an existing native-updated checkout and only resynchronizes its
|
|
238
401
|
environment.
|
|
239
402
|
|
|
240
403
|
### Python 3.14 in release 0.21.6
|
|
@@ -300,7 +463,7 @@ Configuration, credentials, sessions, memories, skills, and other user state
|
|
|
300
463
|
under `HERMES_HOME` are preserved. The command refuses a non-Git target, a Git
|
|
301
464
|
target with an unexpected origin or uncommitted files, a `HERMES_HOME` inside
|
|
302
465
|
the npm package, or a runtime that has moved off its packaged Release. Run
|
|
303
|
-
`hermes-npm update` first if native
|
|
466
|
+
`hermes-npm update` first if native update changes need to be reset before
|
|
304
467
|
handoff. Existing upstream checkout changes must be committed, stashed, or
|
|
305
468
|
removed explicitly; the bridge never answers an upstream restore prompt.
|
|
306
469
|
|
|
@@ -347,6 +510,7 @@ then install the exact checked canonical version.
|
|
|
347
510
|
| `hermes-npm status [--json]` | Report npm identity, exact live Git commit, channel, dirty state, and install scope |
|
|
348
511
|
| `hermes-npm check [--json]` | Read the canonical npm Release channel without changing files |
|
|
349
512
|
| `hermes-npm update` | Install the checked exact npm version or reset the current runtime to its packaged Release |
|
|
513
|
+
| `hermes-npm setup` | Install or repair the isolated runtime of the installed npm version (alias: `provision`) |
|
|
350
514
|
| `hermes-npm methods [--json]` | List supported installation/ownership models for users and automation |
|
|
351
515
|
| `hermes-npm migrate upstream [--json]` | Show the one-way upstream handoff plan without changing files |
|
|
352
516
|
| `hermes-npm migrate upstream --yes` | Execute, verify, and finish the upstream handoff |
|
|
@@ -354,7 +518,10 @@ then install the exact checked canonical version.
|
|
|
354
518
|
|
|
355
519
|
## How installation works
|
|
356
520
|
|
|
357
|
-
`scripts/postinstall.js` performs the following without invoking a shell
|
|
521
|
+
`scripts/postinstall.js` performs the following without invoking a shell. npm
|
|
522
|
+
runs it as the package install script; when npm skips that script, the first
|
|
523
|
+
launch, `hermes-npm setup`, and `hermes-npm update` run the same file directly
|
|
524
|
+
with the current Node.js under a lock file in the package directory.
|
|
358
525
|
|
|
359
526
|
1. Validates the upstream repository, Release tag, and full commit SHA stored
|
|
360
527
|
in `package.json`.
|
|
@@ -386,7 +553,9 @@ macOS/Linux: runtime/hermes-agent/venv/bin/hermes
|
|
|
386
553
|
```
|
|
387
554
|
|
|
388
555
|
Arguments, current working directory, standard streams, exit code, and native
|
|
389
|
-
upstream update handling are preserved.
|
|
556
|
+
upstream update handling are preserved. When the console script is missing,
|
|
557
|
+
the launcher provisions the runtime first and sends that output to stderr, so
|
|
558
|
+
the command's stdout stays clean.
|
|
390
559
|
|
|
391
560
|
## Runtime layout and isolation
|
|
392
561
|
|
|
@@ -438,7 +607,8 @@ non-prerelease upstream GitHub Release once and then:
|
|
|
438
607
|
6. publishes through npm trusted publishing with provenance.
|
|
439
608
|
|
|
440
609
|
Polling follows GitHub Releases, not PyPI and not the tip of `main`. Native
|
|
441
|
-
`hermes update` remains independent
|
|
610
|
+
`hermes update` remains independent; it follows Releases by default and the
|
|
611
|
+
`main` branch only after `hermes update --set-channel main`.
|
|
442
612
|
|
|
443
613
|
## Security and privacy
|
|
444
614
|
|
|
@@ -462,10 +632,13 @@ npm install --ignore-scripts ./hermes-agent-*.tgz
|
|
|
462
632
|
After review:
|
|
463
633
|
|
|
464
634
|
```bash
|
|
465
|
-
npm
|
|
635
|
+
hermes-npm setup
|
|
466
636
|
```
|
|
467
637
|
|
|
468
|
-
|
|
638
|
+
`npm rebuild hermes-agent` (`npm rebuild --global hermes-agent` for a global
|
|
639
|
+
installation) does the same on npm 11 and earlier, and on npm 12 once the
|
|
640
|
+
install script is allowed. Running `hermes` before the review also provisions
|
|
641
|
+
the runtime; set `HERMES_NPM_AUTO_SETUP=0` while auditing to prevent that.
|
|
469
642
|
|
|
470
643
|
## Troubleshooting
|
|
471
644
|
|
|
@@ -478,17 +651,22 @@ Git is required for the native 'hermes update' channel
|
|
|
478
651
|
Install Git, confirm `git --version`, and run:
|
|
479
652
|
|
|
480
653
|
```bash
|
|
481
|
-
npm
|
|
654
|
+
hermes-npm setup
|
|
482
655
|
```
|
|
483
656
|
|
|
484
657
|
### Runtime is not ready
|
|
485
658
|
|
|
486
|
-
If
|
|
659
|
+
If npm skipped the install script (npm 12 by default, or `--ignore-scripts`),
|
|
660
|
+
the first `hermes` launch provisions the runtime. If that failed or was
|
|
661
|
+
disabled with `HERMES_NPM_AUTO_SETUP=0`, provision it explicitly:
|
|
487
662
|
|
|
488
663
|
```bash
|
|
489
|
-
npm
|
|
664
|
+
hermes-npm setup
|
|
490
665
|
```
|
|
491
666
|
|
|
667
|
+
For a root-owned global npm prefix, run it with the same privileges used for
|
|
668
|
+
`npm install --global`.
|
|
669
|
+
|
|
492
670
|
### Native and npm versions differ
|
|
493
671
|
|
|
494
672
|
This is expected after `hermes update`. Inspect both identities with:
|
|
@@ -506,10 +684,10 @@ package runtime, then retry the npm update.
|
|
|
506
684
|
|
|
507
685
|
### `hermes uninstall` broke an npm installation
|
|
508
686
|
|
|
509
|
-
|
|
687
|
+
Re-provision or reinstall the npm package:
|
|
510
688
|
|
|
511
689
|
```bash
|
|
512
|
-
npm
|
|
690
|
+
hermes-npm setup
|
|
513
691
|
# or
|
|
514
692
|
npm install --global hermes-agent@latest
|
|
515
693
|
```
|
package/SECURITY.md
CHANGED
|
@@ -14,8 +14,9 @@ updates.
|
|
|
14
14
|
|
|
15
15
|
Security fixes in upstream Hermes Agent become available to this channel after
|
|
16
16
|
upstream publishes a GitHub Release and the matching npm bridge passes its
|
|
17
|
-
release checks. The native
|
|
18
|
-
|
|
17
|
+
release checks. The native upstream updater can apply a Release sooner, and
|
|
18
|
+
upstream `main` commits when switched to the rolling channel, with the
|
|
19
|
+
different trust boundary described below.
|
|
19
20
|
|
|
20
21
|
## Reporting a vulnerability
|
|
21
22
|
|
|
@@ -43,7 +44,9 @@ This policy covers:
|
|
|
43
44
|
|
|
44
45
|
- the npm command shims and `hermes-npm` release-channel commands;
|
|
45
46
|
- the explicit `hermes-npm migrate upstream` handoff and its preflight checks;
|
|
46
|
-
- npm lifecycle provisioning in `scripts/postinstall.js
|
|
47
|
+
- npm lifecycle provisioning in `scripts/postinstall.js`, including its
|
|
48
|
+
direct execution on first launch, by `hermes-npm setup`, and by
|
|
49
|
+
`hermes-npm update` when npm skipped the install script;
|
|
47
50
|
- `uv` asset selection, download, checksum verification, and extraction;
|
|
48
51
|
- GitHub Release metadata synchronization and npm publishing workflows;
|
|
49
52
|
- confinement of npm lifecycle installer-created files to the installed npm
|
|
@@ -64,11 +67,12 @@ The bridge is intended to preserve these properties:
|
|
|
64
67
|
4. Release installation fetches the recorded Git tag and verifies that it
|
|
65
68
|
resolves to the full commit SHA recorded in `package.json`.
|
|
66
69
|
5. npm lifecycle installer deletion/replacement targets must resolve inside
|
|
67
|
-
the npm package.
|
|
70
|
+
the npm package. The only exception is the upstream install state named in
|
|
71
|
+
invariant 12.
|
|
68
72
|
6. Python, the virtual environment, the Git checkout, and temporary caches
|
|
69
73
|
created by npm lifecycle installation remain inside the npm package.
|
|
70
74
|
7. `hermes update` is passed to the upstream console entrypoint unchanged; the
|
|
71
|
-
bridge does not falsely represent
|
|
75
|
+
bridge does not falsely represent natively updated source as npm-attested source.
|
|
72
76
|
8. A release-channel reset returns tracked upstream source to the commit pinned
|
|
73
77
|
by npm without deleting untracked files with `git clean`.
|
|
74
78
|
9. npm publication is blocked unless Windows, macOS, and Linux runtime smoke
|
|
@@ -77,6 +81,19 @@ The bridge is intended to preserve these properties:
|
|
|
77
81
|
A handoff requires `migrate upstream --yes`, uses the script from the
|
|
78
82
|
verified Release checkout, pins the same full commit, verifies the new
|
|
79
83
|
checkout/venv, and removes npm ownership only after that verification.
|
|
84
|
+
11. When npm skips the install script, the bridge provisions only by running
|
|
85
|
+
the installed package's own `scripts/postinstall.js` with the current
|
|
86
|
+
Node.js, with the same verification and package-local boundary as the
|
|
87
|
+
npm lifecycle. It never passes `--allow-scripts` to npm or changes npm
|
|
88
|
+
configuration.
|
|
89
|
+
12. Under `HERMES_HOME`, the installer deletes only `<root>/installs/<key>`,
|
|
90
|
+
the install state upstream's package manager keeps for this package's
|
|
91
|
+
checkout, with `<root>` from upstream's `get_default_hermes_root` and
|
|
92
|
+
`<key>` from its `install_key`, and only after it has replaced or reset
|
|
93
|
+
the checkout to the pinned commit. The key must be 16 hex digits and
|
|
94
|
+
neither `installs` nor the target may be a symbolic link. Inside the
|
|
95
|
+
package it additionally deletes only the checkout's untracked
|
|
96
|
+
`install-stamp.json`. Every removed path is printed.
|
|
80
97
|
|
|
81
98
|
A change that violates one of these invariants is security-relevant even if no
|
|
82
99
|
exploit has yet been demonstrated.
|
|
@@ -94,6 +111,18 @@ Lifecycle scripts execute with the installing user's permissions. Review the
|
|
|
94
111
|
package before installation when that is not an acceptable trust decision; the
|
|
95
112
|
audit procedure below avoids lifecycle execution.
|
|
96
113
|
|
|
114
|
+
npm 12 blocks dependency install scripts by default, so `npm install` may leave
|
|
115
|
+
only the command shims. The same `scripts/postinstall.js` then runs when the
|
|
116
|
+
user first starts `hermes` or `hermes-agent`, runs `hermes-npm setup`, or
|
|
117
|
+
updates with `hermes-npm update`. It runs with the permissions of that user,
|
|
118
|
+
in the package directory, under a lock file
|
|
119
|
+
(`.hermes-agent-provision.lock`) that serializes concurrent first launches.
|
|
120
|
+
Starting a Hermes command is treated as consent to provision it; set
|
|
121
|
+
`HERMES_NPM_AUTO_SETUP=0` to require an explicit `hermes-npm setup` instead.
|
|
122
|
+
Allowing the script in npm (`--allow-scripts=hermes-agent` for global installs,
|
|
123
|
+
`npm install-scripts approve hermes-agent` for projects) restores provisioning
|
|
124
|
+
during installation.
|
|
125
|
+
|
|
97
126
|
## Exact install behavior
|
|
98
127
|
|
|
99
128
|
`scripts/postinstall.js` and `lib/uv-installer.js`:
|
|
@@ -107,7 +136,8 @@ audit procedure below avoids lifecycle execution.
|
|
|
107
136
|
supported architecture and Linux libc variants;
|
|
108
137
|
5. enforce compressed and extracted size limits, verify SHA-256, and extract
|
|
109
138
|
only `uv`/`uv.exe` with Node.js;
|
|
110
|
-
6. provision managed Python
|
|
139
|
+
6. provision the managed Python version pinned in the package metadata
|
|
140
|
+
(`hermesAgent.pythonVersion`, currently 3.14) under `runtime/python/`;
|
|
111
141
|
7. create `runtime/hermes-agent/venv/` and run
|
|
112
142
|
`uv sync --frozen --extra all --no-dev` using upstream project configuration
|
|
113
143
|
and `uv.lock`;
|
|
@@ -136,7 +166,7 @@ The bridge deliberately provides two update channels.
|
|
|
136
166
|
registry. When a newer package exists, `hermes-npm update` installs the exact
|
|
137
167
|
version that was checked from that same registry; it does not perform a second
|
|
138
168
|
mutable `@latest` resolution. If the npm package is already current, the command
|
|
139
|
-
resets a clean
|
|
169
|
+
resets a clean natively updated checkout in place to the tag/commit pinned by the
|
|
140
170
|
installed npm version. A dirty or damaged checkout is replaced transactionally
|
|
141
171
|
with rollback where possible.
|
|
142
172
|
|
|
@@ -144,13 +174,40 @@ npm integrity and provenance cover the bridge tarball and its pinned Release
|
|
|
144
174
|
identity. They do not include dependencies downloaded during lifecycle
|
|
145
175
|
execution.
|
|
146
176
|
|
|
147
|
-
### Native
|
|
177
|
+
### Native upstream channel
|
|
148
178
|
|
|
149
179
|
`hermes update` and `hermes update --check` run the unmodified upstream updater.
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
180
|
+
Since upstream `v0.21.6`, an official checkout with no configured channel,
|
|
181
|
+
including the package-local one, follows upstream's `stable` channel: the
|
|
182
|
+
latest GitHub Release, forward only. `hermes update --set-channel main` opts
|
|
183
|
+
into the rolling `main` branch. The updater mutates the package-local checkout
|
|
184
|
+
(including unshallowing it), builds its own dependency environments and managed
|
|
185
|
+
tools under `HERMES_HOME`, writes `install-stamp.json` into the checkout, and
|
|
186
|
+
can publish launchers outside npm (`~/.local/bin` on macOS and Linux, a
|
|
187
|
+
`HERMES_HOME\bin` user `PATH` entry on Windows). After a native update, npm
|
|
188
|
+
provenance no longer attests to the live upstream source.
|
|
189
|
+
|
|
190
|
+
The dependency environment the native updater builds is recorded under
|
|
191
|
+
`HERMES_HOME/installs/`, keyed by the checkout path, and upstream selects it at
|
|
192
|
+
startup. `hermes-npm status` reports this case as
|
|
193
|
+
`dependenciesOwner: "upstream-pm"` and does not report the `npm-release`
|
|
194
|
+
channel while upstream's record or a self-managed install stamp is present.
|
|
195
|
+
|
|
196
|
+
When the installer puts the checkout back on the commit pinned by npm (a fresh
|
|
197
|
+
checkout after npm reinstalls or replaces the package, or an in-place reset by
|
|
198
|
+
`hermes-npm update`), it takes dependency selection back: it removes exactly
|
|
199
|
+
`<root>/installs/<key>` for this checkout, where `<root>` and `<key>` are
|
|
200
|
+
computed the way upstream computes them, and the checkout's untracked
|
|
201
|
+
`install-stamp.json`, and prints each removed path. It refuses a key that is
|
|
202
|
+
not 16 hex digits, a path that is not `<root>/installs/<key>`, and an
|
|
203
|
+
`installs` directory or install-state directory that is a symbolic link. A
|
|
204
|
+
removal failure is reported and leaves the installation in place;
|
|
205
|
+
`hermes-npm status` then still shows upstream ownership. When the installer
|
|
206
|
+
keeps an existing checkout (`hermes-npm setup` or `npm rebuild` for the same
|
|
207
|
+
version), it removes nothing, so a native update stays in effect. Launchers
|
|
208
|
+
published to `~/.local/bin` point into the npm package and break when npm
|
|
209
|
+
replaces or removes it; the bridge does not remove them. The README describes
|
|
210
|
+
how to remove them.
|
|
154
211
|
|
|
155
212
|
Use `hermes-npm status --json` to distinguish `npm-release`, `upstream-native`,
|
|
156
213
|
and `missing` runtime states. Use `hermes-npm update` to return to the npm
|
|
@@ -214,6 +271,9 @@ runtime/python/
|
|
|
214
271
|
runtime/hermes-agent/
|
|
215
272
|
```
|
|
216
273
|
|
|
274
|
+
Provisioning also creates the transient `.hermes-agent-provision.lock` while
|
|
275
|
+
it runs.
|
|
276
|
+
|
|
217
277
|
It does not modify system Python, shell profiles, the global `PATH` beyond
|
|
218
278
|
normal npm command shims, services, scheduled tasks, or Git configuration.
|
|
219
279
|
|
|
@@ -282,9 +342,10 @@ and impact; these examples are not automatic ratings.
|
|
|
282
342
|
- The commit pin prevents tag retargeting from silently changing a published
|
|
283
343
|
npm version, but this bridge does not independently verify a Git tag's GPG or
|
|
284
344
|
SSH signature.
|
|
285
|
-
- Native
|
|
286
|
-
|
|
287
|
-
|
|
345
|
+
- Native updates are upstream's trust domain: by default they move the
|
|
346
|
+
checkout to the latest upstream Release before the bridge has published and
|
|
347
|
+
smoke-tested it, on the opt-in `main` channel they follow a mutable branch
|
|
348
|
+
beyond reviewed Releases, and they create files outside the npm package.
|
|
288
349
|
- Host compromise, malicious npm/Git configuration, or write access to the
|
|
289
350
|
installed package can invalidate local guarantees.
|
|
290
351
|
- Only the latest npm bridge release is maintained; users must update to
|
|
@@ -331,14 +392,18 @@ package/lib/upstream-migration.js
|
|
|
331
392
|
```
|
|
332
393
|
|
|
333
394
|
Compare `hermesAgent.upstreamGitTag` and `hermesAgent.upstreamCommit` with the
|
|
334
|
-
official upstream Release.
|
|
395
|
+
official upstream Release. Starting `hermes` provisions the runtime, so keep
|
|
396
|
+
`HERMES_NPM_AUTO_SETUP=0` set until the review is done. After review, provision
|
|
397
|
+
with:
|
|
335
398
|
|
|
336
399
|
```bash
|
|
337
|
-
npm
|
|
338
|
-
# or, for a global installation:
|
|
339
|
-
npm rebuild --global hermes-agent
|
|
400
|
+
hermes-npm setup
|
|
340
401
|
```
|
|
341
402
|
|
|
403
|
+
`npm rebuild hermes-agent` (or `npm rebuild --global hermes-agent`) is
|
|
404
|
+
equivalent on npm 11 and earlier, and on npm 12 once the install script is
|
|
405
|
+
allowed.
|
|
406
|
+
|
|
342
407
|
Security scanners are expected to flag the lifecycle script. Treat that as a
|
|
343
408
|
prompt to review the explicit download, verification, and execution boundary,
|
|
344
409
|
not as proof that the lifecycle step is safe or malicious by itself.
|