@chipschat/hermes 1.0.4 → 1.0.7

package/README.md

@@ -23,19 +23,44 @@ Apache-2.0. Not published: a local repository until Chips's SDK is.
 | The reply | `run.completed`'s `output`, else the `message.delta`s |
 | Files in the reply | each `MEDIA:<path>` line of its own in the reply, taken out of the words and sent from the agent's folder; a file outside it is refused, and the reply says so. Each run is told how in its `instructions`, which Hermes adds to the system prompt, over its own hint that its API server sends only pictures |
 | Cost | the run's tokens; a sub-agent's `cost_usd` as its step's share |
-| An approval card | `approval.request` → `POST …/approval`: once, session or always where Hermes offers it, else once; deny for a no. One answered in Hermes's own tools is settled in Chips (ADR 0079) |
+| An approval card | `approval.request` → `POST …/approval`: once, session or always where Hermes offers it, else once, and once for a command, which Chips remembers by how each part starts (Chips ADR 0239); deny for a no. One answered in Hermes's own tools is settled in Chips (ADR 0079) |
 | "Not right?" on a reply (ADR 0200) | a run of the agent that said it, in its session in the room, after the room's other turns: told its reply and the person's note (or, for a bare 👎, that there was none), it answers again in its place |
 | Fork (ADR 0087) | `POST /api/sessions/{id}/fork` of the agent's session in the room it is in (else the last it had), from its latest id when Hermes has compressed it, under an id made from the ask, so an ask heard twice forks once. Hermes ends the original as `branched`, and the original's runs go on in it. A turn still going isn't in the copy. An agent that never spoke is copied with nothing to remember |
 | Stop | `POST …/stop` |
 | A steer, a follow-up, an interrupt | `POST …/steer`; the next run of the turn; stop, then the next run with the words |
 | Trouble on the harness | `GET /health` every 30 s, per profile |
+| Restart on its page (ADR 0094) | Hermes's gateway restarted on this machine, and Hermes shown as restarting until its API server answers again (below) |
+| Context (ADRs 0134, 0238) | the files Hermes builds the agent from: `SOUL.md` (who it is), `memories/USER.md` and `memories/MEMORY.md` in the profile's home, and the first project file with words in it in the folder Hermes's gateway works in (`.hermes.md`, `HERMES.md`, `AGENTS.md` and the rest Hermes looks for). The first profile's files and the project file are the harness's own set, since every new agent reads them; another profile's files are the agent's own until a fork reads them too. An edit is saved where Hermes reads it, only if the file is still the one the person changed. A memory file is saved as Hermes saves it, under its lock, entries apart by a line with only `§`, and an edit over Hermes's limit (2,200 and 1,375 characters unless `config.yaml` says others) is refused with how much to take out. The page says Hermes reads them when a conversation starts: a space already talking picks up a change after it next compacts |
+| Context window (ADR 0146) | how full the agent's session is, from the webhook below: the last model call's prompt tokens, of its model's window. A sharp drop in a session is a compaction, and a turn past half the window says its peak. Read only: the limit is the profile's `compression.threshold` (75% under 512K tokens unless set higher), and Hermes can't be asked to compact from Chips. Nothing is shown until Hermes's first reading |
 
 Not yet:
 - Hermes's clarify questions (their event isn't documented).
 - Its cron jobs as Chips schedules (ADR 0157).
 - Its model list as the agent's Model group.
-- Context files.
-- A context gauge (Hermes reports no window during a run).
+
+**How full each context is: Hermes's webhook.** Hermes's API server reports no window during a
+run, so the bridge adds an outbound webhook to each profile's `config.yaml` when it starts (and
+in the check before a link is taken up):
+
+```yaml
+hooks:
+  outbound:
+    - name: chips
+      url: http://127.0.0.1:<port>/chips-hermes/default
+      events: [post_api_request]
+      secret_env: CHIPS_HOOK_SECRET
+      timeout: 5
+```
+
+It only ever adds: with no `hooks:` it appends this block, and under a `hooks:` with no
+`outbound:` yet it puts `outbound:` first. Anything else it leaves as it is, and its log says the
+lines to add. The secret goes in the profile's `.env`, which Hermes loads into its gateway; a
+profile with no `.env` gets the secret in the entry instead. Hermes reads its hooks when its
+gateway starts, so after the bridge adds one, start `hermes gateway` again once (the setup step
+says so when the gateway was running). After every model call Hermes then POSTs the call's
+numbers, signed, to the bridge on 127.0.0.1. Hermes sends the reply's words too: the bridge
+checks the signature, keeps only the numbers, and drops the rest. The port is chosen the first
+time and kept; `hookPort` in the config fixes one.
 
 **Approvals and Hermes v0.20.6.** Hermes's API server counts itself as unattended (issue
 [#98728](https://github.com/NousResearch/hermes-agent/issues/98728), open on 14 October 2026). So a
@@ -97,8 +122,29 @@ writes a launch agent (`~/Library/LaunchAgents/chat.chips.hermes.plist`; a syste
 Linux) that runs the bridge from login and again whenever it stops, and ends: closing the terminal
 or restarting the machine no longer takes it offline in Chips. Its log is
 `~/Library/Logs/chips-hermes.log`. `npm run keep -- --stop` stops it and removes the file. Stop a
-copy started by hand first: two answer twice. Hermes's own `hermes gateway` is kept running its own
-way.
+copy started by hand first: two answer twice. When the bridge starts and nothing answers at a local
+address, it starts Hermes's gateway (below), so Hermes comes back after a reboot too.
+
+**Restart.** Restart on Hermes's page in Chips restarts Hermes's gateway, the process serving its
+API server at the agents' address, when that is on this machine:
+- Installed as Hermes's own service (`hermes gateway install`, so
+  `~/Library/LaunchAgents/ai.hermes.gateway.plist` or a systemd unit), `hermes gateway restart`.
+- Run by hand, the process listening on the API's port is stopped (SIGTERM, then SIGKILL if it is
+  still there 15 s later), only if it is this user's `hermes gateway run`. Anything else there is
+  left alone, and Chips says so. Then `hermes gateway run` is started again with the same words, in
+  the folder it worked in, in a session of its own, its output added to
+  `~/Library/Logs/chips-hermes-gateway.log`.
+
+Chips shows Hermes as restarting until its API server answers again, then fine, or in a line what
+went wrong. Started with the bridge, it is the same, with `hermes gateway start` for a service. The
+bridge asks for `restarts` when it joins with a code; a harness joined without it gets Restart
+once Chips is told it takes it (`chips declare`, ADR 0046).
+
+On a Mac whose Homebrew python@3.14 can't load macOS's expat, Hermes dies as it starts with
+`Symbol not found: _XML_SetAllocTrackerActivationThreshold`. Then the bridge starts Hermes's entry
+point (the one the `hermes` wrapper runs) directly, with the wrapper's variables and
+`DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib`, which macOS would drop at the wrapper, and its log
+says so.
 
 **Folders.** Each agent gets a folder of its own, `~/chips-hermes/agents/<its name>`, made the
 first time it is spoken to and kept by its Chips agent after a rename. Each run tells the agent it
@@ -122,8 +168,9 @@ npm test
 ```
 
 They run the bridge against Chips's conformance fake and a scripted Hermes API server
-(`test/fake-hermes.ts`), on Hermes's own routes and event names. That includes Chips's golden
-scenario. The SDK and the kit are in `vendor/`, packed from a Chips checkout with
+(`test/fake-hermes.ts`), on Hermes's own routes and event names, and its webhook's signed
+readings. That includes Chips's golden scenario. Hermes's own files are in temporary homes: no
+test reads or writes `~/.hermes`. The SDK and the kit are in `vendor/`, packed from a Chips checkout with
 `pnpm release:sdk <this repo>/vendor`.
 
 ```

package/dist/THIRD-PARTY-NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-`dist/main.js` in @chipschat/hermes 1.0.4 carries these packages, bundled in. Each one's
+`dist/main.js` in @chipschat/hermes 1.0.7 carries these packages, bundled in. Each one's
 licence follows.
 
 ## @chipschat/harness 0.0.0 (Apache-2.0)