Hermes Config Toolset Changes

Hermes Config Toolset Changes

Overview

A profile enables tools through lists in its config.yaml: a top-level toolsets: list, MCP server blocks, and a few other list-valued keys. The curated CLI commands show only part of the tool registry, so they can reject a toolset that the runtime supports. The correct workflow is to read the live config first, confirm the change against the docs, and make it through the CLI where the CLI can do it. A direct edit to a config file is an operator decision. It is never a workaround for a refused write.

When to Use

• A profile needs a toolset that the curated list does not show, such as an orchestrator-only toolset.
• You are adding, removing or verifying an MCP server entry on a profile.
• You are about to change any list-valued key, such as toolsets:, mcp_servers: or a custom_providers: list.
• A managed capability looks down on one profile but works on others.

Features

• Live-config check that reads the full list, not a truncated view.
• Doc check for toolsets that the docs say must be enabled in config.
• CLI decision table: what the CLI can set, what it stores as text, and what it cannot touch.
• Rules for list-valued sections and for multi-line entries.
• Post-change checklist that ends with a fresh session test.

Benefits

• A missing toolset is found from the real config, not from a guess about the CLI.
• List values are not corrupted into strings by a scalar-only setter.
• Operators approve every direct edit before it happens.
• A "service is down" report gets checked against the profile's toolset list first.

Procedure

1. Read the live config for the target profile in full. Confirm the path first:

   hermes --profile <profile> config path
   grep -n -B2 -A12 "^toolsets:" "$(hermes --profile <profile> config path)"

   Read the whole block. A short view that shows only the first items can make a present toolset look absent.

2. Check the docs page that governs the toolset. Some orchestrator-only toolsets are enabled in config, and the docs say so. Check the docs before you conclude what the CLI should do.

3. Check what the CLI can show and set. Use these probes, and treat each result as a fact to report:

   hermes --profile <profile> config path
   hermes tools list          # shows only the curated subset
   hermes tools enable <name> # rejects toolsets outside the curated list

   The interactive tools screen needs a terminal, so it cannot be driven from an agent shell.

4. Choose the change path:

   • If the CLI supports the change, use it, then read the config back.
   • If the change needs a list edit the CLI cannot do, prepare the exact change as a diff, with the current block quoted, and ask the operator to apply it or to authorize the agent to apply it in this session.
   • If the file tools refuse to write a config file, that refusal is the signal to stop and ask. Do not route the write around it.
5. For an authorized edit, use the verification ladder in config-verify-before-write: back up, check the list structurally, replace one exact block that matches once, write atomically, and read the key back. Build the block from the live file's exact bytes, not from an example in this skill.
6. Restart the gateway from the operator's terminal. Config changes take effect only in a new process.
7. Verify in a new session. Ask the agent to call the tool that was previously gated out, and confirm it appears in the tool list.

List-valued keys and multi-line entries

• A key such as custom_providers: is a list of mappings, not a mapping. Iterate it with a guard that skips non-dict items, not with .items():

  for item in cfg.get("custom_providers", []):
      if isinstance(item, dict) and item.get("name") == "<provider-name>":
          ...

• A scalar-only setter stores a list as text. Use it only for top-level scalar keys. For any nested list or mapping, edit the structure as a whole and read it back.
• Removing a multi-line list entry means removing every line of that entry. Removing only its first line leaves orphaned sub-keys at the wrong indent, and the file no longer parses.
• After any multi-line removal, parse the result before writing it anywhere.

Pitfalls

• Truncated reads hide list items. Read the block in full, with context lines, every time.
• Curated lists are not the full registry. hermes tools list and the interactive screen show a subset. The live config.yaml is the authority on what a profile enables.
• A missing toolset looks like a dead service. A profile that lacks the web toolset reports its web tool as down. Read the profile's toolset list before you diagnose a managed capability as broken, or you will re-architect around a service that was fine.
• Keys with similar names are not the same key. A file can contain several lines that mention toolsets:, such as per-platform overrides and disabled lists. Print every occurrence with its line number, and identify the one top-level block by its column.
• Indentation differs between profiles. One profile indents list items and another does not. Copy the exact bytes of the target profile's file, not an example.
• Do not match a list item with a regex that stops at the next column-zero line. Unindented list items end the match early. Enumerate lines instead.
• Do not use "is X already in the list" regex checks. A nested block can contain the same item. Parse the file and check the top-level key.
• Config changes do not reach a running process. A session that made the change still has the old tool schema.
• Secrets never go into a config list or into chat. Add provider keys through the secrets CLI or the profile's env file. Validate a key with one minimal request and read only the status code.
• Do not change a profile's default model or provider as a side effect of a toolset or key change. Check those keys before and after the change.
• A new provider block needs its upstream checked. Confirm the provider's base URL and API style from its own docs before you copy a block from memory. A native API style needs a native block, not the generic OpenAI-compatible one.

Verification

• The live toolsets: list, read in full, contains the expected entries and no others.
• The config check command reports no schema error.
• After the gateway restart, a new session can call the newly enabled tool.
• A profile that was reported as having a down service shows that service's toolset enabled, or the report is corrected.