/hermes-runtime

name: hermes-runtime
description: Use when Hermes needs to become a formal NextClaw runtime entry, especially for setup, doctor, repair, readiness checks, and first-message smoke on the preferred narp-stdio(acp) path.
description_zh: 用于将 Hermes 接入为正式的 NextClaw runtime，覆盖安装配置、诊断修复、就绪检查和首条消息冒烟验证。
metadata: {"nextclaw":{"emoji":"🧠"}}

Hermes Runtime

Use this skill when the user wants Hermes to appear inside NextClaw as a formal session type.

The only preferred product path is:

• runtime entry label: `Hermes`
• runtime type: `narp-stdio`
• wire dialect: `acp`
• runtime entry launcher: `hermes acp`
• route ownership: `NextClaw -> RuntimeRoute(model/apiBase/apiKey/headers) -> Hermes ACP`

Do not present Hermes as:

• a plugin-private integration
• a connector-first integration
• an API-server-first integration
• a second independent provider configuration system

This installed skill must stay self-contained.

Do not assume the user can open this repository's internal design docs after installing it from the marketplace. Everything needed for setup, readiness, repair, and first-message verification should be explained here.

Install Boundary: Skill vs Hermes Binary

Always distinguish these two things before taking action:

• the NextClaw marketplace skill:

installed into the active workspace as `skills/hermes-runtime/SKILL.md`

• the Hermes executable:

the external runtime binary exposed as `hermes`

Installing this skill does not install Hermes by itself. The skill must detect whether `hermes` is already available and install or repair Hermes when it is not.

What This Skill Owns

• explain the correct product mental model
• install Hermes when missing
• detect and repair `hermes acp`
• write or repair `agents.runtimes.entries.hermes`
• verify that `Hermes` appears as a formal session type
• run a real first-message smoke
• diagnose and repair common failures

This skill does not redefine the runtime architecture. It operationalizes the already-locked product contract.

Required Mental Model

Always describe the system in this order:

1. NextClaw owns the unified runtime registry. 2. `Hermes` is one runtime entry inside that registry. 3. The preferred first version of `Hermes` is:

• `type: "narp-stdio"`
• `wireDialect: "acp"`
• `command: "hermes"`
• `args: ["acp"]`

4. NextClaw owns `model / apiBase / apiKey / headers`. 5. Hermes ACP consumes that route through the dedicated Hermes ACP bridge prepared by the Hermes setup/launcher path, not through kernel-side Hermes detection.

Do not teach users that the main setup path is:

• installing a first-party Hermes connector package
• starting a Hermes API server first

Execution Style

This skill is execution-oriented, not explanation-oriented.

When the user asks to set up, doctor, repair, or validate Hermes, the agent should:

• do the checks itself instead of handing the user a checklist
• silently run the needed shell commands and real smoke checks
• rewrite config when repair is needed
• loop until the runtime either passes or a concrete blocker is identified

The validation method does not need to be a hard-coded product script.

Good options include:

• direct shell checks
• real `NextClaw -> Hermes` message smokes
• an independent second-pass verification by another agent when delegation is available and appropriate

The important requirement is: the agent must actually verify, not just describe how verification could be done.

Product Contract

The integration is complete only when all of the following are true:

1. a `Hermes` runtime entry exists in the unified runtime registry 2. that entry is registered as a formal session type 3. NextClaw resolves the active model into a `RuntimeRoute` 4. Hermes ACP consumes that route directly 5. a real first reply succeeds

If any of the five conditions above is false, do not call the integration complete.

Preferred Runtime Entry Shape

Use the unified runtime registry as the primary configuration surface:

{
  "agents": {
    "runtimes": {
      "entries": {
        "hermes": {
          "enabled": true,
          "label": "Hermes",
          "icon": {
            "kind": "image",
            "src": "app://runtime-icons/hermes-agent.png",
            "alt": "Hermes"
          },
          "type": "narp-stdio",
          "config": {
            "wireDialect": "acp",
            "processScope": "per-session",
            "command": "hermes",
            "args": ["acp"],
            "env": {},
            "startupTimeoutMs": 8000,
            "probeTimeoutMs": 3000,
            "requestTimeoutMs": 120000
          }
        }
      }
    }
  }
}

The important part is not hidden implementation details. The important part is:

• the launcher is `hermes acp`
• the runtime entry should carry the bundled app resource URI `app://runtime-icons/hermes-agent.png`
• NextClaw stays the owner of route selection
• Hermes ACP does not require a second provider setup path for this integration
• the bridge is provided by the bundled Hermes ACP bridge setup/launcher path; kernel and generic `narp-stdio` code must not hard-code Hermes detection

Setup Contract

`setup` must cover this full path:

1. explain that the goal is a formal `Hermes` session type inside NextClaw 2. check whether `hermes` exists 3. install Hermes when it is missing 4. check whether `hermes acp` can start 5. create or repair the `agents.runtimes.entries.hermes` entry 6. run readiness checks 7. run a real first-message smoke 8. finish only after `Hermes` is visible as a selectable session type and can really reply

Do not stop at:

• `command -v hermes`
• “the config file looks correct”
• “the command starts”

Do not ask the user to manually run the validation steps if the agent can run them itself.

Cold-Start Beginner Flow

This skill must work for the hardest onboarding case:

• the user only knows the name `Hermes`
• Hermes is not installed yet
• the user has no prior Hermes kn