@chipschat/hermes 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+              Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The Chips Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# chips-hermes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Hermes Agent](https://hermes-agent.nousresearch.com) as a [Chips](https://chipschat.ai) harness,
+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 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.
+
+Apache-2.0. Not published: a local repository until Chips's SDK is.
+
+## What Chips shows
+
+| In Chips | From Hermes (`/v1/runs`) |
+| --- | --- |
+| A message to the agent | `POST /v1/runs` in the room's session: the room note, what was said, the words |
+| The thinking bubble's words | `reasoning.available`, `message.interim` |
+| Steps, drawn by kind | `tool.started` / `tool.completed` (by `tool_call_id`, else first in, first out per tool); a sub-agent's `subagent.start` / `subagent.complete` |
+| 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) |
+| "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 |
+
+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).
+
+**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
+guarded command is denied, or with `approvals.unattended_mode: approve` run unasked, instead of
+reaching `/v1/runs` as an approval. Until the fix lands, only the asks Hermes does send (MCP
+consent) reach Chips as cards. Don't set `unattended_mode: approve` for an agent people talk to
+through Chips: it would act on everything without asking anyone.
+
+**On v0.22.0** (run for real on 16 October 2026), `approvals.mode` is `smart` by default: Hermes's
+own guardian model judges a flagged command first, and runs it when it judges it safe. The step's
+result then says "auto-approved by smart approval", and no card is asked. Only what the guardian
+escalates goes the way above. `approvals.mode: manual` leaves every flagged command to a person; it
+hasn't been tried through Chips yet.
+
+## From Chips's gallery
+
+The card's line is `chips connect hermes '<link>'` (Chips ADR 0218). It downloads this bridge as the npm package
+`@chipschat/hermes`, the newest 1.x, checks it against the registry's checksum, and runs it on the Node
+that Chips carries, so the machine needs no Node or npm of its own. The bridge checks Hermes,
+joins, and keeps itself running from login. `chips disconnect hermes` stops it. On another computer,
+`curl -fsSL https://chipschat.ai/install | sh -s -- connect hermes '<link>'` installs Chips there
+first. The steps below run the bridge from this checkout instead, to work on it.
+
+## Run it
+
+1. Turn on Hermes's API server, with a key, in `~/.hermes/.env`:
+
+   ```
+   API_SERVER_ENABLED=true
+   API_SERVER_KEY=<a long random key>
+   ```
+
+   Then `hermes gateway`. It listens on `127.0.0.1:8642`.
+
+2. Once, in this repository: `npm install`.
+
+3. Join Chips once, with a link from Chips's gallery (Add an agent → Hermes), whose card gives
+   this line with the link in it:
+
+   ```
+   cd ~/Work/Chips/chips-hermes && CHIPS_JOIN_LINK='<link>' npm run keep
+   ```
+
+   `npm run keep` joins, then keeps the bridge running from login (below); `npm start` is the
+   same in the terminal only.
+
+   Or with `CHIPS_URL` and a code a person allows. Before it takes the link up, which works once,
+   it checks there is a key, and that Hermes answers and takes it (`/v1/models`, since `/health`
+   needs none). Anything missing stops it with what to do, and the link is still good. Joined, its
+   Main agent says hello in its room once, which the card waits for. The key Chips gives it is
+   kept, so later starts need nothing; a new link from Chips replaces it.
+
+That is all most people need: with no config the bridge is Hermes's default profile, and the key is
+the `API_SERVER_KEY` in `$API_SERVER_KEY` if set, else in Hermes's own `.env` (`$HERMES_HOME/.env`
+when `HERMES_HOME` is set).
+
+**Keep it running.** `npm run keep` does what `npm start` does, with the link or without, then
+writes a launch agent (`~/Library/LaunchAgents/chat.chips.hermes.plist`; a systemd user unit on
+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.
+
+**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.
+
+**More than one agent.** Name them in `~/.chips-hermes/config.json` (see `config.example.json`).
+Each agent is one of three:
+- the default profile;
+- a profile under `/p/<profile>`, with `gateway.multiplex_profiles` on and that profile's own key;
+- a profile's own gateway at a `url` of its own.
+
+Each key is read from the variable `keyEnv` names, in the environment or Hermes's `.env`.
+`folders` moves where the agents' folders are made. `folder`, for the config or one agent, puts
+the agents it covers in one folder they share instead.
+
+## Tests
+
+```
+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
+`pnpm release:sdk <this repo>/vendor`.
+
+```
+npm run e2e
+```
+
+The gallery's card for this connector, run as a person runs it, against a scratch Chips from a
+Chips checkout (`CHIPS_REPO`, `~/Work/Chips/chips-main` unless set; skipped without one) and the same scripted Hermes.
+Each thing not set up stops it with the link still good; then it joins with what the card grants,
+says hello once in its room, says nothing more started again, and takes up a new link in place of
+the key it kept. The scratch Chips, the link and the run come from Chips's `tools/connect-kit`, which packs this checkout and serves it from a stand-in npm registry, so the card's `chips connect` downloads, checks and runs what would be published.
+
+## Release
+
+`npm run release` builds `dist/main.js`, one file with the SDK and everything else bundled in, and
+`dist/THIRD-PARTY-NOTICES.md` beside it; runs the tests; and packs `chipschat-hermes-<version>.tgz`. `npm publish`
+publishes it. A version's major is the Chips protocol it speaks, and Chips's card names that major
+(Chips ADR 0218): a fix is a minor or a patch, and reaches every card of its major the day it is
+published.