aesculap-hermes

name	aesculap-hermes
description	Use when a user asks an agent to install, configure, validate, operate, or troubleshoot Aesculap, the safety-gated self-healing daemon for Hermes Agent. Guides environment discovery, explicit permission-tier selection, provider setup without exposing keys, notification target and language confirmation, explicit fix-mode disclosure, systemd installation, and end-to-end verification.
version	0.1.0
author	banxia-O
license	MIT
metadata	{"hermes":{"tags":["hermes","self-healing","reliability","systemd","monitoring","incident-response"],"related_skills":["hermes-agent"]}}

Aesculap for Hermes Agent

Overview

Aesculap is a resident health-monitoring and recovery daemon for Hermes Agent. It detects persistent failures, asks an LLM to diagnose and propose a route, then lets deterministic code decide whether any action is allowed. Safe, bounded repairs may run automatically; risky, ambiguous, repeated, or unsupported cases escalate to a coding agent or a human.

This skill is the installation and operations entrypoint. Read AGENT.md for the complete agent-facing manual, README.md for the product overview, and Aesculap_PRD.md when auditing design decisions.

Core invariant: the LLM proposes; code gates decide. Never describe Aesculap as unrestricted autonomous repair.

When to Use

Use this skill when the user asks to:

• install Aesculap beside a Hermes deployment;
• configure probes, providers, permission boundaries, or notifications;
• choose between permission tiers A/B/C;
• run Aesculap in observe or fix mode;
• install or troubleshoot the systemd service;
• inspect status, audit records, or pending escalations;
• verify whether human-intervention notifications actually arrive.

Do not use it as a generic server-monitoring guide, a replacement for backups, or authorization to edit identity files, credentials, billing settings, or unrelated applications.

Operating Contract

Before writing files or starting a service, explain and obtain explicit answers for every consequential decision below.

Decision	Required behavior
Writable scope	Present A/B/C with risks. Recommend A. Never silently choose C.
Identity files	Show detected candidates and let the user confirm the immutable list.
Triage provider/model	Detect configured providers by key presence only; never read or print key values. Include OpenAI-compatible domestic services such as DeepSeek, GLM, and Kimi/Moonshot instead of assuming OpenAI or Anthropic.
Coding-agent escalation	Report whether Claude Code, Codex, or another supported tool is actually available.
Notification target	Run hermes send --list; let the user choose a real destination; send a test message.
Notification language	Ask: “Aesculap needs human intervention. Which language should it use to notify you: English or Simplified Chinese?” Persist the answer as notify.language.
Service scope	Ask whether systemd should use user or system scope. Prefer user scope unless system scope is necessary.
Activation mode	New installs default to fix so protection is active immediately. State this before service start. Switch to observe only when the user explicitly wants a dry run or temporary safety downgrade.

Never infer notification language from logs, stack traces, server locale, model output, or an occasional message. Supported values are en and zh-CN; legacy configurations without the field default to en.

Installation Workflow

1. Read-only preflight

Run these checks without changing the system:

python3 --version
git -C <project-root> rev-parse --is-inside-work-tree
hermes --version
hermes gateway status
hermes send --list
command -v systemctl || true
command -v claude || true
command -v codex || true

Also inspect:

• whether Hermes writes logs to a file that Aesculap can watch;
• whether the protected project is a git repository;
• whether ~/.hermes or the active profile contains identity files such as SOUL.md, MEMORY.md, USER.md, persona, or identity documents;
• which provider environment variables exist, checking only presence;
• available disk space and Python ≥ 3.11.

Completion criterion: report every prerequisite as pass, missing, or intentionally disabled. Do not begin installation while file logging or the intended rollback repository is unresolved.

2. Ask for the safety boundary

Present the tiers in plain language:

• A — project tree only: safest and recommended for most users.
• B — Hermes configuration plus project tree: only for a dedicated Hermes host and only after identity/credential exclusions are confirmed.
• C — whole host: highest risk. Use only after explicit user selection and confirmation that the machine is dedicated and contains no unrelated important data.

Aesculap still hard-blocks identity files, credentials, its own directory, read-only files, sensitive system paths, destructive commands, force pushes, deletion, and billing/payment operations. A larger tier never removes those hard tripwires.

Completion criterion: record the user’s explicit tier and immutable identity-file choices. If the user is uncertain, stop at A.

3. Prepare an isolated Python environment

From the repository or SkillHub-installed directory:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/pip install -e .

Install only the provider extras actually selected:

.venv/bin/pip install -e '.[openai]'
# or
.venv/bin/pip install -e '.[anthropic]'
# or both only when both are genuinely needed

The openai extra also powers openai_compatible endpoints. Domestic services can be used directly; self-hosting is optional, not required. For example:

triage:
  provider: openai_compatible
  model: deepseek-v4-pro
  base_url: https://api.deepseek.com/v1
  api_key_env: DEEPSEEK_API_KEY

The same adapter supports GLM, Kimi/Moonshot, Ollama, and vLLM when they expose an OpenAI-compatible endpoint. Use each provider's real model ID, base URL, and key environment-variable name; do not reuse the DeepSeek values for another provider.

Never paste API keys into chat or config.yaml. The configuration stores environment-variable names such as OPENAI_API_KEY, not secret values. Tell the user which approved environment file or service environment to edit, then verify only that the variable exists.

Completion criterion: .venv/bin/aesculap --version exits successfully and no credential value appears in shell history, logs, config, or chat.

4. Resolve notification delivery before running the wizard

List actual Hermes destinations:

hermes send --list

Ask the user which destination should receive human-intervention alerts. Build a command template from a real target, for example:

notify:
  command_template: "hermes send --to telegram {message}"

Targets may be a platform home channel or an explicit platform/chat/thread destination. Use the exact syntax shown by hermes send --help on the installed Hermes version. Test the target before relying on it:

hermes send --to <target> "Aesculap notification test"

If no destination is available, leave notify.command_template empty and state clearly that escalations will be audited but not delivered. Never retain an obsolete notification subcommand copied from an older Hermes release.

Then ask the language question and retain the explicit answer:

• English → notify.language: en
• 简体中文 → notify.language: zh-CN

The selected language controls the human-readable triage diagnosis and final notification shell. Machine-consumed action strings, JSON keys, enum values, and audit fields remain stable English or structured objects.

Completion criterion: either a real test message arrived at the user-selected destination, or delivery is explicitly marked disabled; the chosen language is documented.

5. Run the interactive installer

.venv/bin/aesculap install ./config.yaml

Use the answers already confirmed with the user. Do not reinterpret them during the CLI wizard. When asked for the notification template, paste the verified template or leave it blank. When asked for notification language, enter en or zh-CN exactly.

After generation, inspect the configuration without printing secret values:

.venv/bin/aesculap config ./config.yaml

Confirm at minimum:

• scope.tier matches the user’s choice;
• project and Hermes paths are correct;
• identity files are protected;
• provider and model names are intended;
• notify.command_template is either tested or empty;
• notify.language matches the explicit answer;
• mode is fix unless the user deliberately requested observe;
• no API key value is stored in YAML.

Completion criterion: config validation exits 0 and every consequential field matches a user-confirmed decision.

6. Establish a health baseline before service start

New configurations default to fix; this avoids a monitoring-only install being forgotten. Before starting the resident service, state plainly that bounded repairs may run within the selected tier, then inspect the baseline:

.venv/bin/aesculap probe ./config.yaml
.venv/bin/aesculap status ./config.yaml

A failing probe is not automatically an installer failure. Determine whether it reflects a real Hermes issue, an incorrect path, or a probe that should be disabled. Do not start the service merely to make the output green.

If the user explicitly wants a dry run or a temporary safety downgrade, switch modes before service start:

.venv/bin/aesculap mode observe ./config.yaml

Completion criterion: every enabled probe has an explained result, the active mode is stated to the user, and fix remains enabled unless the user deliberately selected observe.

7. Install systemd with a dry run first

Render the unit before writing it:

.venv/bin/aesculap install-systemd ./config.yaml --scope user
# or, only if explicitly selected:
.venv/bin/aesculap install-systemd ./config.yaml --scope system

Review the executable path, working directory, config path, service user, and hardening directives. Then install only after approval:

.venv/bin/aesculap install-systemd ./config.yaml --scope user --write

Use the enable/start command printed by the installer. For user services that must survive logout, check whether linger is required before enabling it.

Completion criterion: systemd reports the unit active, the process uses the intended .venv, and logs show one clean startup rather than a restart loop.

8. Verify end to end

Run:

.venv/bin/aesculap config ./config.yaml
.venv/bin/aesculap probe ./config.yaml
.venv/bin/aesculap status ./config.yaml
systemctl --user status aesculap.service --no-pager

Adapt the final command for system scope. Inspect recent audit entries and service logs. Trigger only a harmless, reversible test condition or use a test fixture; do not break a production agent merely to prove recovery.

Verify separately:

1. Aesculap detects and audits the test event.
2. In default fix mode, every attempted repair remains inside the selected tier and deterministic gate; if the user selected observe, no repair runs.
3. A human escalation reaches the configured target.
4. The title, diagnosis, headings, and guidance use the chosen language.
5. Technical evidence may remain in its original language but credentials are redacted.
6. Repeated equivalent events respect deduplication/cooldown.

If the user temporarily selected observe, restore the normal active mode once the dry run is complete unless they explicitly choose to remain observation-only:

.venv/bin/aesculap mode fix ./config.yaml

Completion criterion: detection, audit, delivery, language, redaction, safety-gate behavior, and service health are all verified with real output; the final mode is stated explicitly.

Routine Operations

.venv/bin/aesculap status ./config.yaml
.venv/bin/aesculap mode observe ./config.yaml
.venv/bin/aesculap mode fix ./config.yaml
.venv/bin/aesculap disable ./config.yaml
.venv/bin/aesculap enable ./config.yaml
.venv/bin/aesculap stop

Use observe immediately when a diagnosis or repair route appears suspicious. disable is the master stop for Aesculap behavior; stopping the systemd service additionally stops the daemon process.

When a notification requests a credential, tell the user which environment variable and file need attention. Never request, echo, transmit, or log the credential itself.

Common Pitfalls

1. Accepting an obsolete notification command. Current Hermes uses hermes send; verify with live --help and --list. An untested template means notification delivery is not configured.
2. Guessing the user’s language. Always ask during installation. Logs and locale are evidence about software, not the person receiving alerts.
3. Localizing machine actions. actions are parsed downstream. Keep strings in English or use structured action objects; localize only human-facing diagnosis and notification copy.
4. Leaving a new install in observation-only mode by accident. New installs default to fix so protection is active. Use observe deliberately for a dry run or incident downgrade, and record whether/when it should return to fix.
5. Treating tier C as unrestricted root. Hard tripwires and protected paths still apply. C is not permission to edit identity, credentials, billing, or Aesculap itself.
6. Running without git rollback. Resolve the intended rollback repository before enabling repairs.
7. Claiming success from config validation alone. A complete install requires service health, probe results, a real notification test, and language verification.
8. Mixing project source with production dirty changes. Use an isolated worktree for development and preserve the deployed checkout until changes are reviewed and deliberately rolled out.

Verification Checklist

• Python ≥ 3.11 and isolated .venv are in use
• Hermes file logging and project git rollback are available
• Permission tier and identity-file protections were explicitly confirmed
• Provider choice was detected without reading or printing secrets
• hermes send --list was checked on the live installation
• Notification target was tested or explicitly disabled
• Notification language was explicitly selected and persisted
• config, probe, and status commands were exercised
• Initial mode is fix, unless the user deliberately selected observe
• User was told that starting the service in fix permits bounded repairs within the selected tier
• systemd unit was reviewed before --write
• Audit, notification delivery, localization, and redaction were verified end to end
• Any deliberate use of observe includes a recorded decision about whether/when to restore fix
• Final report states scope tier, mode, service status, notification target/language, and unresolved probe failures