@chipschat/hermes 1.0.5 → 1.0.8

package/README.md

@@ -5,11 +5,14 @@ on Hermes's own API server.
 - Each Hermes profile you name is a Chips agent. The first is the harness's Main agent.
 - Each Chips room an agent is in is a Hermes session of its profile, made the first time somebody
   there speaks to it.
-- A new agent a person asks for in a room (Add, then a new one) runs on the first profile, in a
-  session of its own.
+- A new agent a person asks for in a room (Add, then a new one) is a Hermes profile of its own,
+  cloned from the Main agent's, so it remembers only its own conversations (below). So is the agent
+  of a space a person asks Hermes for from the +. An agent made before 1.0.8 runs on the first
+  profile, in a session of its own, as it did.
 - A copy of an agent a person asks for in another room (Fork) is a fork of its session there in
   Hermes, so it remembers everything the agent did; from then on the two go on apart. It runs on
-  its original's profile, in its original's folder.
+  its original's profile, in its original's folder: Hermes forks a session only within its
+  profile, so a copy has no profile of its own.
 
 Apache-2.0. Not published: a local repository until Chips's SDK is.
 
@@ -23,19 +26,22 @@ 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 |
+| A space from the + (ADR 0241) | claimed under a key made from the space and named from its first words, which a new agent of the harness answers on a profile of its own (below); what is said there next goes to the same session |
 | 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 |
-| 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 |
+| 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 SOUL.md and the project file are the harness's own set, since every new agent starts from them; the first profile's memory files are the Main agent's own. Another profile's files are its 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 |
+| Model (ADR 0141) | the models Hermes's own picker lists for the agent's profile (`GET /api/model/options`), of the providers the profile is signed in to, each as `provider/model`. A pick is asked for by each of that agent's runs (`provider` and `model` on `/v1/runs`) and changes nothing in Hermes, so it is that agent's alone, on a profile of its own or one it shares. Hermes's default, the Same as switch, is the profile's own model, set in Hermes (`hermes -p <profile> model`). Hermes says no levels of effort, so none is offered. A `model` the config names for an agent is its own until a person picks another |
 | 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.
+- A model's levels of effort (Hermes lists none per model).
 
 **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
@@ -52,7 +58,8 @@ hooks:
 ```
 
 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
+`outbound:` yet it puts `outbound:` first. (In a profile it has just had Hermes make, it moves the
+copied entry to the profile's address.) 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
@@ -121,14 +128,61 @@ 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
 is its folder, in the run's `instructions`. The files an answer sends go to the room from there and
 from nowhere else.
 
+**Each new agent, a profile of its own.** An agent made in Chips (Add, then a new one, or a
+space from the +) gets a Hermes profile, made by Hermes with
+`hermes profile create <name> --clone-from <the Main agent's> --no-alias`:
+- It starts with the Main agent's `config.yaml` (its model and tools), the keys in its `.env`,
+  its skills and plugins, and its `SOUL.md` to start from. Hermes leaves out messaging channels.
+  No `<name>` shortcut is made: `hermes -p <name>` reaches it.
+- Its memory starts empty: the bridge takes out the copies of `memories/MEMORY.md` and `USER.md`.
+- Hermes counts its API server as a messaging channel, so the clone has no `API_SERVER_KEY`, and
+  Hermes answers `/p/<name>` only with that profile's own. The bridge adds one, a new random key,
+  to the profile's `.env`, and reads it from there.
+- Chips's webhook (above) is moved to the profile's own address, `/chips-hermes/<name>`.
+
+The profile is named after the agent when it is made, in lowercase letters, digits and `-`
+(`nova`, `nova-2` when Hermes has a `nova` already), and keeps that name after a rename, as the
+agent's folder does. Deleting the agent in Chips leaves its profile in Hermes: what it learned is
+yours to delete, with `hermes profile delete <name>`. `~/.chips-hermes/sessions.json` remembers
+which profile is whose.
+
+The one gateway serves every profile under `/p/<name>`, and takes a new one at once when the bridge
+asks over its control socket (`rescan-profiles`, as `hermes profile create` does). But a gateway
+that started when Hermes had only its default profile serves that one alone until it starts
+again. Then the bridge restarts it once, as Restart does (above), and its log says so; from then
+on it serves every profile. Hermes's gateway also keeps sending a new profile's readings to the
+Main agent's address until it starts again, which the bridge drops. Where Hermes doesn't make a
+profile, the agent runs on the first profile, in a session of its own, and the log says why.
+
 **More than one agent.** Name them in `~/.chips-hermes/config.json` (see `config.example.json`).
 Each agent is one of three:
 - the default profile;

package/dist/THIRD-PARTY-NOTICES.md

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