Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ jobs:
env:
CHROME_NO_SANDBOX: '1'
timeout-minutes: 2
- run: node tests/browser/hermes-reporting.mjs
env:
CHROME_NO_SANDBOX: '1'
timeout-minutes: 2
- run: node tests/browser/proxy.mjs
env:
CHROME_NO_SANDBOX: '1'
Expand Down Expand Up @@ -245,8 +249,11 @@ jobs:
path: bin/native
merge-multiple: true
- run: chmod +x bin/native/*/agent-guild-report
# A release also names the commit it is built from, whose Hermes plugin it installs.
- if: inputs.version != ''
run: npm version "$VERSION" --no-git-tag-version
run: |
npm version "$VERSION" --no-git-tag-version
npm pkg set agentGuild.commit="$GITHUB_SHA"
env:
VERSION: ${{ inputs.version }}
# A release packs the Windows modules that sign.yml signed, keeping node-pty's copies to compare.
Expand All @@ -273,9 +280,9 @@ jobs:
version=$(node -p "require('./package.json').version")
node scripts/yard-pack.mjs --out "$RUNNER_TEMP/package" --url-base "https://github.com/$GITHUB_REPOSITORY/releases/download/v$version/"
npm pack --pack-destination "$RUNNER_TEMP/package"
upstream=()
if [ "$SIGNED" = true ]; then upstream=(--upstream "$RUNNER_TEMP/upstream"); fi
node tests/package/check-tarball.mjs "$RUNNER_TEMP"/package/*.tgz --version "$version" "${upstream[@]}"
release=()
if [ "$SIGNED" = true ]; then release=(--upstream "$RUNNER_TEMP/upstream" --commit "$GITHUB_SHA"); fi
node tests/package/check-tarball.mjs "$RUNNER_TEMP"/package/*.tgz --version "$version" "${release[@]}"
cd "$RUNNER_TEMP/package"
sha256sum -- *.tgz yard-art-*.tar.gz > SHA256SUMS
echo "version=$version" >> "$GITHUB_OUTPUT"
Expand Down
31 changes: 31 additions & 0 deletions .github/workflows/hermes-compat.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Checks the Hermes plugin against a real Hermes Agent with Hermes's own catalog gates. It downloads
# Hermes, so it is not part of CI: pull requests test the plugin with local fixtures only, and a
# failure here never blocks a merge.
name: Hermes compatibility

on:
push:
branches: [main]
paths: [plugins/hermes/**, .github/workflows/hermes-compat.yml]
schedule:
- cron: '17 6 * * 1'
workflow_dispatch:

permissions:
contents: read

jobs:
hermes:
name: Hermes plugins (catalog gates)
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: plugins/hermes
# Hermes Agent v0.23.1.
- run: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --commit 3b421578588243f920886e6fe79a6faa87ea026e --non-interactive --skip-browser --skip-computer-use
- run: |
"$HOME/.local/bin/hermes" plugins validate --install-deps plugins/hermes/agent-guild
"$HOME/.local/bin/hermes" plugins doctor plugins/hermes/agent-guild --ci
22 changes: 22 additions & 0 deletions config/providers.optional.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,28 @@
"winget": { "id": "OddEssentials.TerminalAIChat" }
}
}
},
{
"id": "hermes",
"vendor": "Nous Research",
"tool": "Hermes Agent",
"command": "hermes",
"versionArgs": ["--version"],
"reporting": "hermes",
"mcp": "hermes",
"homeVar": "HERMES_HOME",
"profiles": "hermes",
"resumeArgs": ["--resume", "{id}"],
"color": "#8B5CF6",
"monogram": "H",
"install": "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash",
"docs": "https://hermes-agent.nousresearch.com/docs",
"channels": {
"native": { "paths": ["~/.local/bin/hermes", "~/.hermes/hermes-agent"], "update": ["update"] }
},
"win32": {
"install": "iex (irm https://hermes-agent.nousresearch.com/install.ps1)"
}
}
]
}
1 change: 1 addition & 0 deletions docs/agent-reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ report these through hooks or the `agent-guild-report` command.
| Claude Code, Codex CLI | Automatic when the installed version can load hooks for one session. Otherwise the card says so; add the hooks yourself below. |
| Grok Build | Turn on **Agent reporting** on its card. It adds Agent Guild's hooks to the `hooks` folder of each Grok Build home (`~/.grok/hooks` by default). |
| Antigravity CLI | Turn on **Agent reporting** on its card. Reports the model, its conversation (for Resume) and each turn's answer, not helper agents. |
| Hermes Agent | Turn on **Agent reporting** on its card (an optional card). For each account (the default is Hermes's base home, the others are its profiles) it keeps a report token and its own address in a file of its own, saves that file's path with `hermes config set AGENT_GUILD_HERMES_TOKEN_FILE`, and installs the [Agent Guild plugin](../plugins/hermes/agent-guild) with `hermes plugins install --ref`, at the commit this release of Agent Guild was built from; a running gateway loads it at once. A plugin of another commit, as after Agent Guild is upgraded, keeps reporting, and the card offers **Update plugin**, which installs this release's; nothing is reinstalled when Agent Guild starts. A build that is not a release installs no plugin unless `AGENT_GUILD_HERMES_PLUGIN_COMMIT` names a commit to install. The plugin reports every session the gateway runs, Telegram, cron and the CLI included, with its subagents, shell commands and approvals, on the Hermes Agent tool card, per profile. It shows the sessions active since reporting started: one already running appears at its next turn or tool call. The plugin sends events in order and, while anything is open, a heartbeat every 30 seconds that closes whatever a lost event left open and rebuilds what one never delivered, also after a manager restart. A profile reports only with a token issued for its own home: one cloned from a profile that reports, with its settings, sends nothing until reporting is turned on for it. Commands and subagent goals pass through Hermes's own secret redaction first, and are left out when it fails; a reporting process silent for 90 seconds is dropped. |
| Docker Agent | Automatic from 1.55.0. Reports from the first prompt: its sub-agents (`transfer_task`, background agents; from 1.81.2, which names the agent on each event), shell commands in its approval modes, and turns. For the model, turn on **Model reporting** on its card (1.100.0 and later). A shell command Docker Agent runs without asking (every command in autonomous mode, and the ones its balanced and restricted modes classify as safe, or that you allowed for the session) fires no `pre_tool_use` for Agent Guild's hooks, so it shows only with the hook below. Its matching `post_tool_use` fires, and the card ignores it. Resume opens the first session that runs a prompt: the one Agent Guild started or resumed (from 1.81.2 it names that session, so Resume works before the first prompt), unless a tab opened with `/new` before the first prompt ran it. A sub-agent is a session first heard from under another agent's name while another session's run is in progress (from its `session_start` to its `session_end`); the launch agent is the one named on the first event. Later tabs (`/new`, `/fork`, `/sessions`) start with the agent Docker Agent was launched with, so they are not shown as sub-agents and do not move Resume; a skill that agent runs, or a sub-agent with its name, counts as that agent's own work, as does an agent switched to before the first prompt. A tab prompted under another agent's name while another tab's run is in progress shows as a sub-agent until it ends. Docker Agent run inside a Shell card, with the hooks below configured in its own settings, reports the same way from 1.81.2, and **Model reporting** shows its model there too. From 1.81.2, Docker Agent run inside another tool's card reports nothing to that card. |

The end of each main turn also brings the agent's answer, which the terminal's
Expand Down
29 changes: 21 additions & 8 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ on; any route can answer others.
"usageSource": "claude",
"historySource": "claude",
"memorySource": "claude",
"accounts": [{ "id": "default", "label": "Default" }, { "id": "work", "label": "Work" }],
"accounts": [{ "id": "default", "label": "Default", "live": null }, { "id": "work", "label": "Work", "live": null }],
"color": "#D97757",
"monogram": "A",
"iconUrl": null,
Expand Down Expand Up @@ -112,7 +112,7 @@ or uninstall session's result,
are lines the card shows about the copies, such as several being installed.
`npmNote` qualifies an npm install, or is null. `modelPattern` is the
provider's, or null. `reporting` is the tool's reporting mode: `claude`,
`codex`, `antigravity`, `grok`, `docker`, or null.
`codex`, `antigravity`, `grok`, `docker`, `hermes`, or null.

`installs` lists every copy of the tool that was found, each
`{ path, displayPath, channel, version, versionStatus, active, newer, onPath, uninstall, uninstallGuidance }`.
Expand All @@ -139,7 +139,12 @@ can read saved messages: for every built-in history source, not for a
under: `default` is the tool's own, and each further one has its own home
folder, so it keeps its own sign-in and usage. `POST /sessions` takes an
account id. `accountsEditable` is true when accounts can be added, renamed
and removed through `/providers/:id/accounts`.
and removed through `/providers/:id/accounts`; for Hermes Agent the accounts are its own
profiles instead: `default` is Hermes's base home (`HERMES_HOME`, else Hermes's own default), and each
other one a profile folder in it, found when the cards load. An account's `live` is null
except for a Hermes Agent profile whose plugin reports: then it is
`{ working, waiting, agents, shells }`: the counts of its Hermes sessions and subagents working
and waiting, the first 64 of them as `{ id, name, status, detail }`, and their shell commands as `{ id }`.

`shells` is null except for the `@shell` provider, where it lists the
installed shells, each `{ id, label, path, multiplexer }`, and `defaultShell`
Expand All @@ -153,12 +158,19 @@ leaves the multiplexer's own session running, and

For a tool whose agent or model reporting has to be turned on,
`reportingEnabled` says whether it is, and `reportingNote` says why that switch
cannot be used, or is null.
cannot be used, or for Hermes Agent why reporting is off until it is turned on
again, or is null. `reportingUpdate` is true for Hermes Agent while a profile
that reports has an Agent Guild plugin of another commit than the one this
Agent Guild installs; that plugin keeps reporting until it is updated. For
Hermes Agent, `reportingEnabled` also stays true while a profile's report token
is still accepted after a revocation that failed, with a `reportingNote` that
says so, so turning it off can be tried again.

`mcp` is null unless the tool is installed and Agent Guild can add its own MCP
server (`agent-guild mcp`, see [mcp.md](mcp.md)) to the tool's settings:
Claude Code, Codex CLI, Antigravity CLI and Grok Build. Otherwise it is
`{ mode, accounts }`: `mode` is `claude`, `codex`, `antigravity` or `grok`, and
Claude Code, Codex CLI, Antigravity CLI, Grok Build and Hermes Agent, where it
is `mcp_servers.agent-guild` in the profile's `config.yaml`, marked untrusted. Otherwise it is
`{ mode, accounts }`: `mode` is `claude`, `codex`, `antigravity`, `grok` or `hermes`, and
`accounts` has one `{ id, label, state, managed, from, command, allowInput,
detail, fingerprint }` per account, read from that account's settings. A
settings file the tool keeps as JSON is read again when it changes; a tool
Expand Down Expand Up @@ -663,7 +675,7 @@ All paths are under `/api/v1`.
| POST | `/providers/:id/accounts` | `{ label, revision }` | `201 { account, dir, providers, revision }`: adds an account to `providers.json`. Its id is made from `label` and does not change. |
| PATCH | `/providers/:id/accounts/:account` | `{ label, revision }` | `{ account, dir, providers, revision }`: renames an account, including `default`. |
| DELETE | `/providers/:id/accounts/:account?revision=` | | `{ account, dir, providers, revision }`: removes an account from `providers.json`. Its home folder, `dir`, stays on disk. 409 `default_account` for `default`; 409 `account_in_use` while a running session uses it. |
| POST | `/providers/:id/reporting` | `{ enabled }` | `{ provider }`: turns agent or model reporting on or off for a tool that has `reportingEnabled`. |
| POST | `/providers/:id/reporting` | `{ enabled }` or `{ update: true }` | `{ provider }`: turns agent or model reporting on or off for a tool that has `reportingEnabled`. `{ update: true }` installs this Agent Guild's Hermes plugin in every profile that reports with another commit, and no other; a profile whose update fails keeps the plugin it had, and the error says so. 400 `not_applicable` for a tool other than Hermes Agent; 409 `reporting_unavailable` when this build names no plugin commit; 502 `reporting_setup_failed` when Hermes fails or does not record the new commit. |
| POST | `/providers/:id/mcp` | `{ account, action, expect }` | `{ provider, result }`: changes Agent Guild's MCP server in one account's settings. `action` is `on` (add it, or turn it on in the tool), `off` (remove Agent Guild's entry, or turn off one that comes from another tool's settings) or `replace` (put Agent Guild's own entry in place of the one there). `expect` is the account's `fingerprint`: the account is read again first, and nothing changes unless the entry is still that one. `result` is `{ outcome, state, detail? }`, `outcome` `changed`, `unchanged` or `failed`. 400 `not_applicable` for a tool without `mcp`; 404 `unknown_account`; 409 `provider_unavailable` when it is not installed, `busy` while a change for that tool is running, `changed` when the entry is no longer `expect`, `unreadable` when the settings cannot be read, `conflict` for `on` or `off` on another server of that name, `needs_replace` for `on` on a Codex CLI entry Agent Guild did not add. |
| POST | `/providers/:id/install` | `{ force? }` | `201 { session }`: a session that installs or updates the tool. 409 `provider_in_use` (with `running`, the session count) while the provider's sessions are running; retry with `force: true` after the user confirms. |
| POST | `/providers/:id/uninstall` | `{ path, force? }` | `201 { session }`: a session that removes the copy at `path`, one of the provider's `installs`. `force` as for `install`. |
Expand Down Expand Up @@ -726,6 +738,7 @@ All paths are under `/api/v1`.
| POST | `/sessions/:id/docker` | `{ event, sessionId, agentName?, toolName?, toolUseId?, command?, model?, reply? }` | `{ ok }`. One Docker Agent hook event. |
| POST | `/sessions/:id/shells` | `{ shell, key \| task, match?, agentId?, persist?, endsWithAgent?, kind?, tasks? }` | `{ ok }`. A shell command the tool started, ended or put in the background. |
| POST | `/sessions/:id/hook?event=&reporting=` | A coding tool's hook event, as the tool gives it to its hooks | `{ ok }`, or `{ ok, errors }` when reports the event makes are refused, each `{ status, code?, message }` as its own route would answer. The manager turns the event into the session's reports as `agent-guild-report --hook` does. `event` names an event that does not name itself; `reporting` is the session's `AGENT_GUILD_REPORTING` where the hook ran, and defaults to the session's own. A transcript the event names is read only if it is a regular file. |
| POST | `/hermes/hook` | `{ instance, messages }` | `{ ok }`. What the Hermes Agent plugin of one profile reports, for every Hermes Agent card of that account. `instance` names the reporting process; `messages` are its events, `{ seq, event, data }`, and heartbeats, `{ seq, open }`, applied in `seq` order, each `seq` once. A heartbeat lists what is still open: `sessions` (each `{ platform }`), `working` (session ids), `subagents` (each `{ parent_session_id, child_role, child_goal }`), `tools` (each `{ session_id, tool_name }`) and `waits` (each `{ session_id }`), keyed by id. It closes the rest and rebuilds what is missing. An instance that sends nothing for 90 seconds is dropped. Needs the profile's Hermes report token in `X-Agent-Guild-Report-Token`, which turning on its reporting sets; 401 `unauthorized` otherwise. |
| POST | `/shutdown` | `{ force?, restart? }` | `202 { ok, running, restart }`: stops the manager and every session, detaching tmux and herdr sessions. 409 `sessions_running` (with `running`) while other sessions run; retry with `force: true` after the user confirms. With `restart`, a new manager takes over on the same port and token, running the version on disk. |

`cwd` defaults to the user's home folder, and a leading `~` is expanded.
Expand All @@ -744,7 +757,7 @@ header. The manager gives that token only to the processes inside that
session.

Request bodies are limited to 64 KiB, except `PUT /notes`,
`POST /sessions/:id/reply` and `POST /sessions/:id/docker`, which accept
`POST /sessions/:id/reply`, `POST /sessions/:id/docker` and `POST /hermes/hook`, which accept
1 MiB, and `POST /sessions/:id/hook`, which accepts 32 MiB and checks the token
before reading the body. Messages a client sends on a WebSocket are limited to 1 MiB.

Expand Down
2 changes: 2 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ Invalid values are ignored; a file that cannot be read is reported in `manager.l
| `modelPattern` | Regular expression that finds the model name on screen |
| `homeVar` | Variable that moves the tool's home folder; required for `accounts` |
| `accounts` | Extra sign-ins; see [Accounts](#accounts) |
| `profiles` | `hermes`: the accounts are Hermes's home, as `default`, and each of its profiles, found as Hermes finds them when the cards load, in place of `accounts`; they are created in the tool |
| `color`, `monogram`, `icon` | Card appearance; `icon` is a URL path |
| `install`, `docs` | Shown when the tool is not installed; for a `plugin`, or with `channels.native.reinstall`, `install` is the command **Install** and **Update** run |
| `channels` | Where each kind of copy lives, so the card can update and remove it: `native` `{ paths, remove, reinstall, versionEnv }`, `brew` `{ names }`, `winget` `{ id }`. A copy inside a `native` path is native; **Remove** deletes its `remove` paths, which must be inside your home folder. With `reinstall`, running `install` again updates a native copy, and `versionEnv` names the variable that pins `install` to the version `releases` reports |
Expand Down Expand Up @@ -124,6 +125,7 @@ Codex CLI and Grok Build support this.
| `AGENT_GUILD_HOME` | Moves the data folder. Turns off **Settings → Startup**. |
| `AGENT_GUILD_NPM_REGISTRY` | npm registry for version checks and installs |
| `AGENT_GUILD_NO_UPDATE_CHECK` | `1` turns off online version checks and self-upgrade |
| `AGENT_GUILD_HERMES_PLUGIN_COMMIT` | For a build that is not a release: the commit of `oddessentials/agent-guild` whose Hermes plugin turning on Hermes reporting installs. A release always installs its own commit's. |
| `AGENT_GUILD_SKIP_SHELL_ENV` | `1` stops reading PATH from your login shell, or from the registry on Windows |
| `AGENT_GUILD_ALLOWED_HOSTS`, `AGENT_GUILD_ALLOWED_ORIGINS` | Legacy proxy allowlists, used until remote access settings are saved. An invalid value stops the manager from starting. |

Expand Down
1 change: 1 addition & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ With Agent Guild installed (`npm install -g @oddessentials/agent-guild`):
| Codex CLI | `codex mcp add agent-guild -- agent-guild mcp` |
| Antigravity CLI | `agy mcp add agent-guild agent-guild mcp` |
| Gemini CLI | `gemini mcp add -s user agent-guild agent-guild mcp` |
| Hermes Agent | `hermes config set mcp_servers.agent-guild '{"command": "agent-guild", "args": ["mcp"], "trust": "untrusted"}'` |
| VS Code | `code --add-mcp '{"name":"agent-guild","type":"stdio","command":"agent-guild","args":["mcp"]}'` |

For one VS Code workspace, `.vscode/mcp.json`:
Expand Down
Loading
Loading