hermes-agent 0.19.0 → 0.20.1

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 CHANGED
@@ -1,158 +1,541 @@
1
1
  # hermes-agent npm bridge
2
2
 
3
- This is an unofficial npm bridge for Hermes Agent by Nous Research. It is not
4
- affiliated with, endorsed by, sponsored by, or maintained by Nous Research.
3
+ [![npm version](https://img.shields.io/npm/v/hermes-agent?logo=npm)](https://www.npmjs.com/package/hermes-agent)
4
+ [![npm downloads](https://img.shields.io/npm/dm/hermes-agent?logo=npm)](https://www.npmjs.com/package/hermes-agent)
5
+ [![CI](https://github.com/wyrtensi/hermes-agent-npm/actions/workflows/ci.yml/badge.svg)](https://github.com/wyrtensi/hermes-agent-npm/actions/workflows/ci.yml)
6
+ [![Upstream release](https://img.shields.io/github/v/release/NousResearch/hermes-agent?label=upstream&logo=github)](https://github.com/NousResearch/hermes-agent/releases)
7
+ [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
8
+ [![npm provenance](https://img.shields.io/badge/npm%20provenance-enabled-brightgreen)](https://docs.npmjs.com/generating-provenance-statements)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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
- Hermes Agent is developed by Nous Research and distributed separately as a
7
- Python package. This npm package only installs and launches that upstream Python
8
- runtime.
57
+ ```bash
58
+ hermes-npm methods --json
59
+ hermes-npm status --json
60
+ ```
9
61
 
10
- This repository publishes the npm bridge for
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
- The npm package name is:
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
- hermes-agent
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
- This repository can build an alias package manifest for:
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
- hermesagent
119
+ npm install --global hermes-agent@latest
25
120
  ```
26
121
 
27
- npm currently blocks publishing the unscoped `hermesagent` package because the
28
- name is too similar to the existing `hermes-agent` package. The available npm
29
- alternative is a scoped package such as `@wyrtensi/hermesagent`.
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
- The installed commands are:
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-agent
140
+ npm install --global hermes-agent
141
+ hermes --help
36
142
  ```
37
143
 
38
- The npm package name `hermes` is already owned by another package on npm, so this
39
- repository publishes `hermes-agent` and exposes `hermes` as a CLI binary.
144
+ Project installation:
40
145
 
41
- ## Legal and attribution
146
+ ```bash
147
+ npm install hermes-agent
148
+ npx hermes --help
149
+ ```
42
150
 
43
- - Wrapper license: MIT, see [LICENSE](LICENSE).
44
- - Upstream attribution: see [NOTICE](NOTICE).
45
- - Unofficial package disclaimer: see [DISCLAIMER.md](DISCLAIMER.md).
46
- - Privacy notes: see [PRIVACY.md](PRIVACY.md).
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
- For wrapper issues, use this repository:
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
- https://github.com/wyrtensi/hermes-agent-npm/issues
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
- For upstream Hermes Agent issues, use the upstream project:
166
+ ## Two update channels
54
167
 
55
- https://github.com/NousResearch/hermes-agent/issues
168
+ The bridge intentionally exposes two independent update channels.
56
169
 
57
- ## Install
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
- Prerequisites:
175
+ ### Native rolling channel
60
176
 
61
- - Node.js 20 or newer
62
- - Python 3.11 or newer
63
- - pip available for that Python installation
177
+ ```bash
178
+ hermes update --check
179
+ hermes update
180
+ ```
64
181
 
65
- Install globally:
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 install -g hermes-agent
203
+ hermes-npm status
204
+ hermes-npm status --json
69
205
  ```
70
206
 
71
- Use it:
207
+ Check the npm registry:
72
208
 
73
209
  ```bash
74
- hermes --help
75
- hermes-agent --help
210
+ hermes-npm check
76
211
  ```
77
212
 
78
- If a scoped alias package is published later, you do not need to install both
79
- `hermes-agent` and the alias. If one is already installed globally, the other
80
- package prints a warning during `postinstall`.
213
+ Return to or advance along the release-pinned channel:
214
+
215
+ ```bash
216
+ hermes-npm update
217
+ ```
81
218
 
82
- During npm installation, `postinstall` installs the matching Python package:
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
- python -m pip install --upgrade hermes-agent==<npm package version>
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
- For a detailed explanation of why this package uses `postinstall` and exactly
89
- what the script does, see [SECURITY.md](SECURITY.md).
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
- ## Automated publishing
238
+ For automation and agents, `hermes-npm status --json` is the canonical
239
+ machine-readable note. Child processes also receive:
92
240
 
93
- `.github/workflows/npm-publish.yml` runs:
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
- - manually with `workflow_dispatch`
96
- - four times per hour on a schedule
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
- The workflow:
251
+ ## Move from npm to an upstream-managed install
100
252
 
101
- 1. Fetches the latest published Hermes Agent version from PyPI.
102
- 2. Updates `package.json` in the workflow workspace.
103
- 3. Skips publishing if `hermes-agent@<version>` already exists on npm.
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
- GitHub scheduled workflows are best-effort and can be delayed or skipped by
112
- GitHub. The schedule checks four times per hour so new PyPI releases are picked
113
- up quickly without requiring a paid service or upstream webhook access.
257
+ ```bash
258
+ hermes-npm migrate upstream
259
+ hermes-npm migrate upstream --json
260
+ ```
114
261
 
115
- ## GitHub setup
262
+ Stop running Hermes processes, then execute it explicitly:
116
263
 
117
- Create a GitHub repository named:
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-npm
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
- Configure npm trusted publishing for the published npm package:
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
- npm package: hermes-agent
127
- publisher: GitHub Actions
128
- organization or user: wyrtensi
129
- repository: hermes-agent-npm
130
- workflow filename: npm-publish.yml
131
- allowed action: npm publish
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
- The trusted publisher environment name should stay empty unless the workflow job
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
- Then push this repository:
463
+ If installation was performed with `--ignore-scripts`, provision it explicitly:
141
464
 
142
465
  ```bash
143
- git remote add origin git@github.com:wyrtensi/hermes-agent-npm.git
144
- git push -u origin main
466
+ npm rebuild hermes-agent
145
467
  ```
146
468
 
147
- After that, open GitHub Actions and run `Publish npm package` manually for the
148
- first publish.
469
+ ### Native and npm versions differ
149
470
 
150
- ## Local checks
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