Compare commits

..

1 Commits

Author SHA1 Message Date
teknium1
762b681423 feat(curator): add hermes curator usage — all-skills usage view
Surfaces the usage_report()/provenance() data layer added in #36701 as a
user-facing CLI command. Unlike `hermes curator status` (scoped to
curator-managed agent-created candidates), `usage` lists every skill on disk
— bundled built-ins and hub-installed included — with per-skill use/view/patch
counts and an agent/bundled/hub provenance tag.

Flags: --sort {activity,recent,name}, --provenance {agent,bundled,hub} filter,
--json for machine-readable output.
2026-06-01 03:05:41 -07:00
5 changed files with 191 additions and 376 deletions

View File

@@ -473,6 +473,66 @@ def _cmd_list_archived(args) -> int:
return 0
def _cmd_usage(args) -> int:
"""Show usage telemetry for ALL skills, with provenance.
Unlike `status` (curator-scoped to agent-created candidates), this lists
every skill on disk — bundled built-ins and hub-installed included — so you
can see how often each is actually used regardless of curation.
"""
import json as _json
from tools import skill_usage
rows = skill_usage.usage_report()
prov_filter = getattr(args, "provenance", None)
if prov_filter:
rows = [r for r in rows if r.get("provenance") == prov_filter]
sort_key = getattr(args, "sort", "activity")
if sort_key == "name":
rows.sort(key=lambda r: r["name"])
elif sort_key == "recent":
# Most-recently-active first; never-active sinks to the bottom.
rows.sort(key=lambda r: r.get("last_activity_at") or "", reverse=True)
else: # "activity" (default): most-used first
rows.sort(key=lambda r: r.get("activity_count", 0), reverse=True)
if getattr(args, "json", False):
print(_json.dumps(rows, indent=2, ensure_ascii=False))
return 0
if not rows:
print("curator: no skills found")
return 0
# Provenance tallies for a quick header.
counts = {"agent": 0, "bundled": 0, "hub": 0}
for r in rows:
counts[r.get("provenance", "agent")] = counts.get(r.get("provenance", "agent"), 0) + 1
print(
f"skills: {len(rows)} total "
f"(agent={counts['agent']} bundled={counts['bundled']} hub={counts['hub']})"
)
print()
print(
f" {'skill':40s} {'origin':8s} "
f"{'use':>4s} {'view':>4s} {'patch':>5s} {'act':>4s} last_activity"
)
for r in rows:
last = _fmt_ts(r.get("last_activity_at"))
print(
f" {r['name'][:40]:40s} "
f"{r.get('provenance', 'agent'):8s} "
f"{r.get('use_count', 0):>4d} "
f"{r.get('view_count', 0):>4d} "
f"{r.get('patch_count', 0):>5d} "
f"{r.get('activity_count', 0):>4d} "
f"{last}"
)
return 0
# ---------------------------------------------------------------------------
# argparse wiring (called from hermes_cli.main)
# ---------------------------------------------------------------------------
@@ -489,6 +549,25 @@ def register_cli(parent: argparse.ArgumentParser) -> None:
p_status = subs.add_parser("status", help="Show curator status and skill stats")
p_status.set_defaults(func=_cmd_status)
p_usage = subs.add_parser(
"usage",
help="Show usage telemetry for ALL skills (built-in, hub, agent) with provenance",
)
p_usage.add_argument(
"--sort", choices=("activity", "recent", "name"), default="activity",
help="Sort order: activity (most-used first, default), recent "
"(most-recently-active first), or name (alphabetical)",
)
p_usage.add_argument(
"--provenance", choices=("agent", "bundled", "hub"), default=None,
help="Only show skills of this origin",
)
p_usage.add_argument(
"--json", action="store_true",
help="Emit the full report as JSON instead of a table",
)
p_usage.set_defaults(func=_cmd_usage)
p_run = subs.add_parser("run", help="Trigger a curator review now")
p_run.add_argument(
"--sync", "--synchronous", dest="synchronous", action="store_true",

View File

@@ -3009,7 +3009,6 @@ def run_setup_wizard(args):
[
"Quick Setup (Nous Portal) — free OAuth login, no API keys, model + tools (recommended)",
"Full setup — configure every provider, tool & option yourself (bring your own keys)",
"Blank Slate — everything off except the bare minimum; opt in to each capability",
],
0,
)
@@ -3017,9 +3016,6 @@ def run_setup_wizard(args):
if setup_mode == 0:
_run_first_time_quick_setup(config, hermes_home, is_existing)
return
if setup_mode == 2:
_run_blank_slate_setup(config, hermes_home, is_existing)
return
# ── Full Setup — run all sections ──
print_header("Configuration Location")
@@ -3140,237 +3136,6 @@ def _run_first_time_quick_setup(config: dict, hermes_home, is_existing: bool):
_print_setup_summary(config, hermes_home)
def _blank_slate_minimal_toolsets(config: dict):
"""Write the minimal toolset state for a Blank Slate install.
Only ``file`` and ``terminal`` are enabled. Two layers enforce this:
1. ``platform_toolsets["cli"] = ["file", "terminal"]`` — an explicit list of
configurable keys, which the resolver treats as authoritative
(``has_explicit_config``) so default toolsets aren't re-expanded.
2. ``agent.disabled_toolsets`` — a global hard-suppression list (applied last
in ``_get_platform_tools``, overriding every other path including the
non-configurable platform-toolset recovery that would otherwise re-add
toolsets like ``kanban``). We list every known toolset except the two we
keep, guaranteeing a true blank slate regardless of platform/recovery
quirks. The user re-enables any of them later via ``hermes tools`` (which
rewrites ``platform_toolsets``) or by editing ``agent.disabled_toolsets``.
"""
keep = {"file", "terminal"}
config.setdefault("platform_toolsets", {})["cli"] = sorted(keep)
try:
from toolsets import TOOLSETS
from hermes_cli.tools_config import CONFIGURABLE_TOOLSETS, _get_plugin_toolset_keys
all_keys = set()
all_keys.update(k for k, _, _ in CONFIGURABLE_TOOLSETS)
all_keys.update(_get_plugin_toolset_keys())
# Plain (non-composite) TOOLSETS entries — catches recovered toolsets
# like ``kanban`` that aren't in CONFIGURABLE_TOOLSETS but get re-added.
for k, tdef in TOOLSETS.items():
if k.startswith("hermes-"):
continue # platform composites — not user-facing toolsets
if isinstance(tdef, dict) and tdef.get("includes"):
continue # composite groupings, not leaf toolsets
all_keys.add(k)
disabled = sorted(all_keys - keep)
if disabled:
config.setdefault("agent", {})["disabled_toolsets"] = disabled
except Exception as exc:
logger.debug("blank-slate disabled_toolsets computation skipped: %s", exc)
def _blank_slate_minimize_config(config: dict):
"""Turn OFF the optional config features for a Blank Slate install.
Everything here is opt-in afterwards via ``hermes setup agent`` /
``hermes config set``. We keep only what's needed to run.
"""
config.setdefault("agent", {})["max_turns"] = 90
# Compression off — minimal footprint; user opts in if they want long sessions.
config.setdefault("compression", {})["enabled"] = False
# No automatic memory / user-profile capture.
mem = config.setdefault("memory", {})
mem["memory_enabled"] = False
mem["user_profile_enabled"] = False
# No filesystem checkpoints, no smart model routing, no auto session reset.
config.setdefault("checkpoints", {})["enabled"] = False
config.setdefault("smart_model_routing", {})["enabled"] = False
config.setdefault("session_reset", {})["mode"] = "none"
# Quiet, minimal display.
config.setdefault("display", {})["tool_progress"] = "all"
def _run_blank_slate_setup(config: dict, hermes_home, is_existing: bool):
"""Blank Slate setup — start with everything off except the bare minimum.
Forces only the essentials to run an agent (provider + model, the file and
terminal toolsets) and turns every other tool/skill/plugin/MCP/config
feature OFF. After applying that minimal baseline, the user chooses one of
two paths:
1. Start with everything disabled — finish now with the minimal agent.
2. Walk through every configuration — opt each capability back in.
Either way nothing is enabled that the user did not explicitly choose.
"""
from hermes_cli.config import load_config
print()
print_header("Blank Slate Setup")
print_info("Everything starts OFF. First we force-enable only what's required")
print_info("to run an agent, then you choose whether to stop there or walk")
print_info("through enabling more — opting in to exactly what you want.")
print_info("")
print_info("Forced on: Provider & Model, File Operations, Terminal.")
print_info("Everything else (web, browser, code exec, vision, memory,")
print_info("delegation, cron, skills, plugins, MCP, …) starts disabled.")
print()
# ── Step 1: Provider & Model (REQUIRED — the agent cannot run without it) ──
print_header("Step 1 — Provider & Model (required)")
setup_model_provider(config)
save_config(config)
# ── Step 2: Terminal backend (where commands run — a core decision) ──
print_header("Step 2 — Terminal Backend")
setup_terminal_backend(config)
# ── Step 3: Lock in the minimal toolset + minimized config knobs ──
_blank_slate_minimal_toolsets(config)
_blank_slate_minimize_config(config)
save_config(config)
print()
print_success("Minimal baseline applied:")
print_info(" Toolsets: file, terminal (everything else off)")
print_info(" Compression, memory, checkpoints, smart routing: off")
# ── The fork: stop here, or walk through enabling things ──
print()
print_header("How far do you want to go?")
path = prompt_choice(
"Your minimal agent is ready. What next?",
[
"Start with everything disabled — finish now (most minimal)",
"Walk through all configurations — opt in to tools, skills, plugins, MCP",
],
0,
)
if path == 0:
save_config(config)
# Blank Slate means no bundled skills; record the opt-out so future
# `hermes update` runs don't re-inject them.
try:
from tools.skills_sync import set_bundled_skills_opt_out
set_bundled_skills_opt_out(True)
except Exception as exc:
logger.debug("blank-slate skill opt-out error: %s", exc)
print()
print_success("Blank Slate setup complete — minimal agent ready.")
print_info("Enable anything later, on demand:")
print_info(" Enable tools: hermes tools")
print_info(" Seed skills: hermes skills opt-in --sync")
print_info(" Add MCP servers: hermes mcp add")
print_info(" Enable plugins: hermes plugins")
print_info(" Tune agent settings: hermes setup agent")
print()
_print_setup_summary(config, hermes_home)
return
# ── Walkthrough path — opt in to each capability ──
_blank_slate_walkthrough(config, hermes_home)
def _blank_slate_walkthrough(config: dict, hermes_home):
"""Opt-in walkthrough for Blank Slate: skills, tools, plugins, MCP, gateway."""
from hermes_cli.config import load_config
# ── Bundled skills — default to NONE, offer to seed all ──
print()
print_header("Bundled Skills")
print_info("Blank Slate ships with NO bundled skills by default.")
seed_skills = prompt_yes_no(
"Seed the full bundled skill catalog? (No = start with zero skills)",
default=False,
)
try:
from tools.skills_sync import set_bundled_skills_opt_out, sync_skills
if seed_skills:
# Make sure no stale opt-out marker blocks the seed, then sync.
set_bundled_skills_opt_out(False)
result = sync_skills(quiet=True)
copied = len(result.get("copied", [])) if isinstance(result, dict) else 0
print_success(f"Seeded {copied} bundled skills.")
else:
set_bundled_skills_opt_out(True)
print_info("No skills seeded. A .no-bundled-skills marker keeps future")
print_info("`hermes update` runs from re-injecting them. Opt back in any")
print_info("time with `hermes skills opt-in --sync`.")
except Exception as exc:
logger.debug("blank-slate skill handling error: %s", exc)
print_warning(f"Skill setup step encountered an error: {exc}")
# ── Walk through enabling additional tools ──
print()
print_header("Tools")
print_info("Pick exactly which additional toolsets to turn on.")
print_info("(file and terminal are already on; leave the rest off if you want")
print_info(" the most minimal agent.)")
if prompt_yes_no("Open the tool selector to enable more tools?", default=False):
try:
from hermes_cli.tools_config import tools_command
tools_command(first_install=False, config=config)
# tools_command saves via its own load/save cycle — re-sync.
_refreshed = load_config()
config.clear()
config.update(_refreshed)
except Exception as exc:
logger.debug("blank-slate tools_command error: %s", exc)
print_warning(f"Tool selector encountered an error: {exc}")
else:
print_info("Keeping the minimal toolset. Add tools later with `hermes tools`.")
# ── Built-in plugins (off unless chosen) ──
print()
print_header("Plugins")
if prompt_yes_no("Review and enable built-in plugins now?", default=False):
print_info("Manage plugins with `hermes plugins list` / `hermes plugins install`.")
else:
print_info("No plugins enabled. Add later with `hermes plugins`.")
# ── MCP servers (off unless chosen) ──
print()
print_header("MCP Servers")
if prompt_yes_no("Add an MCP server now?", default=False):
print_info("Add servers with `hermes mcp add <name> --url ... | --command ...`.")
else:
print_info("No MCP servers configured. Add later with `hermes mcp add`.")
# ── Optional messaging gateway ──
print()
if prompt_yes_no("Connect a messaging platform (Telegram, Discord, …)?", default=False):
setup_gateway(config)
save_config(config)
print()
print_success("Blank Slate setup complete — minimal agent ready.")
print_info(" Enable more tools: hermes tools")
print_info(" Seed skills: hermes skills opt-in --sync")
print_info(" Add MCP servers: hermes mcp add")
print_info(" Tune agent settings: hermes setup agent")
print()
_print_setup_summary(config, hermes_home)
def _run_quick_setup(config: dict, hermes_home):
"""Quick setup — only configure items that are missing."""
from hermes_cli.config import (

View File

@@ -0,0 +1,112 @@
"""Tests for `hermes curator usage` — the all-skills usage view.
Covers:
- Lists every skill regardless of provenance (agent / bundled / hub), unlike
`status` which is scoped to curator-managed candidates.
- --provenance filter, --sort ordering, and --json output.
"""
from __future__ import annotations
import json
from types import SimpleNamespace
def _fake_rows():
return [
{
"name": "agent-skill", "provenance": "agent", "state": "active",
"use_count": 2, "view_count": 1, "patch_count": 0,
"activity_count": 3, "last_activity_at": "2026-05-01T10:00:00+00:00",
"created_at": "2026-01-01T00:00:00+00:00", "_persisted": True,
},
{
"name": "bundled-skill", "provenance": "bundled", "state": "active",
"use_count": 9, "view_count": 4, "patch_count": 0,
"activity_count": 13, "last_activity_at": "2026-05-10T10:00:00+00:00",
"created_at": "2026-01-01T00:00:00+00:00", "_persisted": True,
},
{
"name": "hub-skill", "provenance": "hub", "state": "active",
"use_count": 0, "view_count": 0, "patch_count": 0,
"activity_count": 0, "last_activity_at": None,
"created_at": "2026-01-01T00:00:00+00:00", "_persisted": False,
},
]
def test_usage_lists_all_provenances(monkeypatch, capsys):
import hermes_cli.curator as curator_cli
import tools.skill_usage as skill_usage
monkeypatch.setattr(skill_usage, "usage_report", _fake_rows)
args = SimpleNamespace(sort="activity", provenance=None, json=False)
assert curator_cli._cmd_usage(args) == 0
out = capsys.readouterr().out
# Header tally and all three skills present.
assert "agent=1" in out and "bundled=1" in out and "hub=1" in out
assert "agent-skill" in out
assert "bundled-skill" in out
assert "hub-skill" in out
def test_usage_sort_activity_orders_most_used_first(monkeypatch, capsys):
import hermes_cli.curator as curator_cli
import tools.skill_usage as skill_usage
monkeypatch.setattr(skill_usage, "usage_report", _fake_rows)
args = SimpleNamespace(sort="activity", provenance=None, json=False)
assert curator_cli._cmd_usage(args) == 0
out = capsys.readouterr().out
# bundled-skill (act=13) must appear before agent-skill (act=3).
assert out.index("bundled-skill") < out.index("agent-skill")
def test_usage_provenance_filter(monkeypatch, capsys):
import hermes_cli.curator as curator_cli
import tools.skill_usage as skill_usage
monkeypatch.setattr(skill_usage, "usage_report", _fake_rows)
args = SimpleNamespace(sort="activity", provenance="bundled", json=False)
assert curator_cli._cmd_usage(args) == 0
out = capsys.readouterr().out
assert "bundled-skill" in out
assert "agent-skill" not in out
assert "hub-skill" not in out
def test_usage_json_output(monkeypatch, capsys):
import hermes_cli.curator as curator_cli
import tools.skill_usage as skill_usage
monkeypatch.setattr(skill_usage, "usage_report", _fake_rows)
args = SimpleNamespace(sort="name", provenance=None, json=True)
assert curator_cli._cmd_usage(args) == 0
out = capsys.readouterr().out
data = json.loads(out)
assert {r["name"] for r in data} == {"agent-skill", "bundled-skill", "hub-skill"}
assert {r["provenance"] for r in data} == {"agent", "bundled", "hub"}
def test_usage_empty(monkeypatch, capsys):
import hermes_cli.curator as curator_cli
import tools.skill_usage as skill_usage
monkeypatch.setattr(skill_usage, "usage_report", lambda: [])
args = SimpleNamespace(sort="activity", provenance=None, json=False)
assert curator_cli._cmd_usage(args) == 0
assert "no skills found" in capsys.readouterr().out
def test_usage_command_is_registered():
"""The `usage` subcommand must be wired into the curator argparse tree."""
import argparse
import hermes_cli.curator as curator_cli
parser = argparse.ArgumentParser(prog="hermes curator")
curator_cli.register_cli(parser)
args = parser.parse_args(["usage", "--sort", "recent", "--provenance", "hub", "--json"])
assert args.func is curator_cli._cmd_usage
assert args.sort == "recent"
assert args.provenance == "hub"
assert args.json is True

View File

@@ -1,131 +0,0 @@
"""Tests for Blank Slate setup mode (hermes_cli/setup.py).
Blank Slate is the third first-time setup option: everything off except the
bare minimum needed to run an agent (provider/model + file + terminal). These
tests pin the config the writers produce and the invariant that the toolset
resolver + tool-schema builder yield exactly the file/terminal tools.
"""
import pytest
from hermes_cli.setup import (
_blank_slate_minimal_toolsets,
_blank_slate_minimize_config,
)
class TestBlankSlateMinimalToolsets:
def test_only_file_and_terminal_enabled_for_cli(self):
cfg = {}
_blank_slate_minimal_toolsets(cfg)
assert cfg["platform_toolsets"]["cli"] == ["file", "terminal"]
def test_disabled_toolsets_excludes_kept_and_covers_known(self):
cfg = {}
_blank_slate_minimal_toolsets(cfg)
disabled = set(cfg["agent"]["disabled_toolsets"])
# The two kept toolsets must NOT be in the disabled list.
assert "file" not in disabled
assert "terminal" not in disabled
# A representative spread of capabilities must be suppressed.
for ts in ("web", "browser", "code_execution", "vision", "memory",
"delegation", "cronjob", "skills", "image_gen"):
assert ts in disabled
# The recovered non-configurable toolset that used to leak is suppressed.
assert "kanban" in disabled
def test_resolver_yields_exactly_file_and_terminal(self):
from hermes_cli.tools_config import _get_platform_tools
cfg = {}
_blank_slate_minimal_toolsets(cfg)
_blank_slate_minimize_config(cfg)
resolved = set(_get_platform_tools(cfg, "cli"))
assert resolved == {"file", "terminal"}
def test_tool_schema_builder_yields_only_file_and_terminal_tools(self):
# End-to-end: the exact schema set the agent would send to the model.
import model_tools
from hermes_cli.tools_config import _get_platform_tools
cfg = {}
_blank_slate_minimal_toolsets(cfg)
_blank_slate_minimize_config(cfg)
enabled = sorted(_get_platform_tools(cfg, "cli"))
defs = model_tools.get_tool_definitions(
enabled_toolsets=enabled, disabled_toolsets=None, quiet_mode=True
)
names = sorted(
{(d.get("function") or {}).get("name") or d.get("name") for d in defs}
)
assert names == ["patch", "process", "read_file", "search_files",
"terminal", "write_file"]
class TestBlankSlateMinimizeConfig:
def test_optional_features_turned_off(self):
cfg = {}
_blank_slate_minimize_config(cfg)
assert cfg["compression"]["enabled"] is False
assert cfg["memory"]["memory_enabled"] is False
assert cfg["memory"]["user_profile_enabled"] is False
assert cfg["checkpoints"]["enabled"] is False
assert cfg["smart_model_routing"]["enabled"] is False
assert cfg["session_reset"]["mode"] == "none"
def test_does_not_clobber_unrelated_keys(self):
cfg = {"model": {"provider": "openrouter", "default": "x/y"}}
_blank_slate_minimize_config(cfg)
# Model config is untouched by the minimizer.
assert cfg["model"]["provider"] == "openrouter"
assert cfg["model"]["default"] == "x/y"
class TestBlankSlateFork:
"""The post-baseline fork: finish now vs walk through configurations."""
def _patch_common(self, monkeypatch):
import hermes_cli.setup as s
# Neutralize side-effecting setup steps and I/O.
monkeypatch.setattr(s, "setup_model_provider", lambda cfg, **k: None)
monkeypatch.setattr(s, "setup_terminal_backend", lambda cfg, **k: None)
monkeypatch.setattr(s, "save_config", lambda cfg: None)
monkeypatch.setattr(s, "_print_setup_summary", lambda cfg, home: None)
monkeypatch.setattr(s, "print_header", lambda *a, **k: None)
monkeypatch.setattr(s, "print_info", lambda *a, **k: None)
monkeypatch.setattr(s, "print_success", lambda *a, **k: None)
monkeypatch.setattr(s, "print_warning", lambda *a, **k: None)
def test_finish_now_skips_walkthrough(self, monkeypatch, tmp_path):
import hermes_cli.setup as s
self._patch_common(monkeypatch)
# Fork prompt returns 0 = finish now.
monkeypatch.setattr(s, "prompt_choice", lambda *a, **k: 0)
walked = {"called": False}
monkeypatch.setattr(s, "_blank_slate_walkthrough",
lambda cfg, home: walked.__setitem__("called", True))
opted_out = {"value": None}
monkeypatch.setattr("tools.skills_sync.set_bundled_skills_opt_out",
lambda enabled: opted_out.__setitem__("value", enabled))
cfg = {}
s._run_blank_slate_setup(cfg, tmp_path, is_existing=False)
# Minimal baseline was applied, walkthrough was NOT run.
assert cfg["platform_toolsets"]["cli"] == ["file", "terminal"]
assert walked["called"] is False
# Finish-now path records the skill opt-out (no bundled skills).
assert opted_out["value"] is True
def test_walkthrough_path_invokes_walkthrough(self, monkeypatch, tmp_path):
import hermes_cli.setup as s
self._patch_common(monkeypatch)
# Fork prompt returns 1 = walk through.
monkeypatch.setattr(s, "prompt_choice", lambda *a, **k: 1)
walked = {"called": False}
monkeypatch.setattr(s, "_blank_slate_walkthrough",
lambda cfg, home: walked.__setitem__("called", True))
cfg = {}
s._run_blank_slate_setup(cfg, tmp_path, is_existing=False)
assert cfg["platform_toolsets"]["cli"] == ["file", "terminal"]
assert walked["called"] is True

View File

@@ -102,16 +102,6 @@ hermes setup --portal
That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
:::
:::info Setup modes
On a fresh install, `hermes setup` offers three modes:
- **Quick Setup (Nous Portal)** — free OAuth login, no API keys; sets up a model plus the Tool Gateway tools. The recommended fast path.
- **Full Setup** — walk through every provider, tool, and option yourself (bring your own keys).
- **Blank Slate** — everything starts **off** except the bare minimum needed to run an agent: **provider & model, the File Operations toolset, and the Terminal toolset**. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers — and compression, checkpoints, smart routing, and memory capture are all disabled. After the minimal baseline is applied, you choose one of two paths: **start with everything disabled** (finish now with the minimal agent), or **walk through all configurations** (opt in to tools, skills, plugins, MCP, and messaging). Pick this when you want a minimal, fully-controlled agent and intend to enable only exactly what you need.
Blank Slate writes an explicit `platform_toolsets.cli` list plus `agent.disabled_toolsets`, so nothing you didn't choose ever loads — not even after `hermes update`. Re-enable anything later with `hermes tools`, seed skills with `hermes skills opt-in --sync`, or tune settings with `hermes setup agent`.
:::
Good defaults:
| Provider | What it is | How to set up |