From f06cdc7de7aab70df4ee78d88d4f083731cc56cb Mon Sep 17 00:00:00 2001 From: Ruilin Gao Date: Wed, 18 Nov 2026 04:50:44 -0500 Subject: [PATCH 1/6] A plugin names the adapter's files as a deployment does; training deploys as hermit deploy does A Claude Code plugin prints, from a SessionStart hook, where its embedded adapter is and the files no export connects, the list a deployment's context gives. Codex, Pi and Hermes plugins, which cannot say where they are installed, list those files under unnamed_files. A test holds that training deploys an adapter as hermit deploy does, file for file on every host, the tools' server entry aside. --- CHANGELOG.md | 6 ++++ docs/framework/commands.md | 10 ++++++ hermit/hosts/inputs.py | 61 +++++++++++++++++++++------------ hermit/plugins/claude_plugin.py | 35 +++++++++++++++++-- hermit/plugins/codex_plugin.py | 7 ++-- hermit/plugins/common.py | 20 ++++++++++- hermit/plugins/hermes_plugin.py | 5 +-- hermit/plugins/pi_package.py | 7 ++-- tests/core/test_convert.py | 60 ++++++++++++++++++++++++++++++++ tests/core/test_deploy.py | 54 +++++++++++++++++++++++++++++ 10 files changed, 235 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eb9fdc0d..a05e90a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,12 @@ Changes are grouped by software version. Entries under Unreleased describe work ### Added +- `hermit convert` names the adapter's folder and files as a deployment does: a Claude Code plugin prints, from a + `SessionStart` hook, where its embedded adapter is and the files no export connects (the list a deployment's + context gives); Codex, Pi and Hermes plugins, which cannot say where they are installed, list those files under + `unnamed_files` in the result and in their README. +- A test that training deploys an adapter into a task's workspace as `hermit deploy` does, file for file on every + host, the tools' server entry aside (calls approved; the session's own tool server for a host that cannot start it). - LIBERO (`examples/libero/`): LIBERO's Object, Spatial, Goal, Long and LIBERO-90 suites and LIBERO-Pro's `_swap` and `_task` perturbations as tasks of ASPIRE's harness, on the Robosuite example's engine, which now takes a task row's `benchmark` and with it the venv, the init mode (`seeded` for LIBERO), the environment and the docs page; the diff --git a/docs/framework/commands.md b/docs/framework/commands.md index b3be667f..68c67e43 100644 --- a/docs/framework/commands.md +++ b/docs/framework/commands.md @@ -136,6 +136,7 @@ names the machine that produced it. | Tools | `.mcp.json` | `mcp.json` | generated extension, `pi.registerMcpServer` | `ctx.register_tool`, forwarding to `hermit serve` | | Roles | `agents/` | refused | refused | refused | | Hooks | refused | refused | refused | refused | +| The adapter's folder and its other files | named by a `SessionStart` hook | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | A part the target's plugin format cannot carry is refused: `convert` exits 2 and names every such part before writing anything. A non-empty context (`ADAPTER.md`) makes Codex and Pi refuse, and a context over 4,000 characters makes @@ -143,6 +144,15 @@ Hermes refuse. Hooks make every target refuse: no plugin carries them yet, and ` `--host claude-code` connects them in a workspace. `--allow-lossy` emits the plugin without those parts and lists them under `omitted` in the result. +In training and in a `deploy` workspace, the agent's context says where the adapter's copy is (paths in its +instructions, skills and roles are relative to that folder) and lists the files no export connects, such as a +README or a tool's source. A plugin carries those files under `adapter/`, but an output style, a skill folder or a +system prompt section cannot say where the plugin is installed. A Claude Code plugin says it with a `SessionStart` +hook: it prints the installed folder and the same list (`hermit-files.md`), and Claude Code adds a SessionStart hook's +output to the context (the hook runs under `sh`, Git Bash on Windows). Codex, Pi and Hermes have no such place, so their +result lists the files under `unnamed_files` and the plugin's README names them; nothing is refused for them, since +the plugin still holds the files. + Why the refusals: - **Codex** reads no instruction file and no subagent from a plugin. Its plugin format is Agent Plugins v1: root diff --git a/hermit/hosts/inputs.py b/hermit/hosts/inputs.py index 351f9487..097f81e7 100644 --- a/hermit/hosts/inputs.py +++ b/hermit/hosts/inputs.py @@ -374,6 +374,43 @@ def _hook_line(when: str, hook: dict, rel: str) -> str: "by the agent from the context: deploy to a host that runs it, or remove it") +def other_files(adapter: Path, manifest: dict, exports: dict, hooks: dict | None) -> list[str]: + """The adapter's files that no export connects and the context is not (paths in the adapter): what a deployment's + context names under "Other files", and what a plugin carries without naming it (hermit.plugins.common).""" + adapter = adapter.resolve() + covered = {manifest.get("context") or "ADAPTER.md", "exports.yaml"} + if _skill_entries(adapter, manifest): + covered.add(f"{_plain(manifest['skills']).rstrip('/')}/") + if exports.get("agents") and isinstance(manifest.get("agents"), str): + covered.add(f"{_plain(manifest['agents']).rstrip('/')}/") + if hooks and hooks.get("hooks"): + covered.add(_plain(manifest["hooks"])) + doc = adapter / (manifest.get("context") or "ADAPTER.md") + context = doc.read_bytes() if doc.is_file() else None + others = [] + for path in sorted(p for p in adapter.rglob("*") if p.is_file()): + if context is not None and path.stat().st_size == len(context) and path.read_bytes() == context: + continue # a copy of the context (a tree's AGENTS.md): already in it + name = path.relative_to(adapter).as_posix() + if (name.split("/")[0] in NOT_COPIED or any(part in CACHES for part in path.parts) or name.endswith(".pyc") + or name in covered or any(name.startswith(c) for c in covered if c.endswith("/")) + or is_internal(name, manifest)): + continue + others.append(name) + return others + + +def other_files_section(adapter: Path, names: list[str], folder: str | None) -> str: + """The context's list of `names` (other_files), each with its summary, as paths under `folder` (None: as they are + in the adapter, for a text that names the folder itself).""" + prefix = f"{folder}/" if folder else "" + listed = [f"- `{prefix}{n}`" + (f": {s}" if (s := _summary(adapter.resolve() / n)) else "") + for n in names[:LISTED_FILES]] + if len(names) > LISTED_FILES: + listed.append(f"- and {len(names) - LISTED_FILES} more files" + (f" under `{folder}/`" if folder else "")) + return "Other files of this adapter (read one when it is relevant):\n" + "\n".join(listed) + + def resources(adapter: Path, output: Path, manifest: dict, exports: dict, hooks: dict | None, native: set[str], hook_types: set[str] = frozenset()) -> tuple[str, dict]: """The part of the context that names what the host does not connect (`native`: the exports it does, of @@ -381,18 +418,15 @@ def resources(adapter: Path, output: Path, manifest: dict, exports: dict, hooks: workspace; and the record of where each export went ({export: "native" | "files" | "native and files"}).""" adapter = adapter.resolve() rel = adapter_folder(output, manifest).relative_to(output).as_posix() - sections, record, covered = [], {}, {manifest.get("context") or "ADAPTER.md", "exports.yaml"} + sections, record = [], {} skills = _skill_entries(adapter, manifest) if skills: record["skills"] = "native" if "skills" in native else "files" - covered |= {f"{_plain(manifest['skills']).rstrip('/')}/"} if "skills" not in native: sections.append("Skills (this agent does not load them itself: read a skill's SKILL.md before you use " "it):\n" + "\n".join(f"- `{n}`: {d} (`{rel}/{p}`)" for n, d, p in skills)) if exports.get("agents"): record["agents"] = "native" if "agents" in native else "files" - if isinstance(manifest.get("agents"), str): - covered |= {f"{_plain(manifest['agents']).rstrip('/')}/"} if "agents" not in native: lines = [] for role in exports["agents"]: @@ -414,27 +448,12 @@ def resources(adapter: Path, output: Path, manifest: dict, exports: dict, hooks: else: lines.append(_hook_line(when, hook, rel)) record["hooks"] = "native and files" if ran and lines else "native" if ran else "files" - covered |= {_plain(manifest["hooks"])} if lines: sections.append(f"Hooks this agent does not run by itself (from `{rel}/{_plain(manifest['hooks'])}`): " "at each of these moments, do it yourself:\n" + "\n".join(lines)) - doc = adapter / (manifest.get("context") or "ADAPTER.md") - context = doc.read_bytes() if doc.is_file() else None - others = [] - for path in sorted(p for p in adapter.rglob("*") if p.is_file()): - if context is not None and path.stat().st_size == len(context) and path.read_bytes() == context: - continue # a copy of the context (a tree's AGENTS.md): already in it - name = path.relative_to(adapter).as_posix() - if (name.split("/")[0] in NOT_COPIED or any(part in CACHES for part in path.parts) or name.endswith(".pyc") - or name in covered or any(name.startswith(c) for c in covered if c.endswith("/")) - or is_internal(name, manifest)): - continue - others.append(name) + others = other_files(adapter, manifest, exports, hooks) if others: - listed = [f"- `{rel}/{n}`" + (f": {s}" if (s := _summary(adapter / n)) else "") for n in others[:LISTED_FILES]] - if len(others) > LISTED_FILES: - listed.append(f"- and {len(others) - LISTED_FILES} more files under `{rel}/`") - sections.append("Other files of this adapter (read one when it is relevant):\n" + "\n".join(listed)) + sections.append(other_files_section(adapter, others, rel)) text = ("### Adapter resources\n\n" + "\n\n".join(sections)) if sections else "" return text, record diff --git a/hermit/plugins/claude_plugin.py b/hermit/plugins/claude_plugin.py index ada88716..8ec7a9cc 100644 --- a/hermit/plugins/claude_plugin.py +++ b/hermit/plugins/claude_plugin.py @@ -10,18 +10,46 @@ - roles: subagent files in the conventional `agents/` directory. Naming that directory in the manifest breaks it: as a string the manifest fails validation, as a list nothing loads. - skills: the conventional `skills/` directory. +- the adapter's files: embedded under `adapter/`. In training and in a `hermit deploy` workspace the context says + where the adapter's copy is and names the files no export connects (hermit.hosts.inputs.resources). An output + style cannot say where the plugin is installed (Claude Code substitutes `${CLAUDE_PLUGIN_ROOT}` in skills, + agents, hooks and servers, not in an output style), so a `SessionStart` hook says it: Claude Code adds a + SessionStart hook's output to the context. The hook runs under `sh` (Git Bash on Windows). """ from __future__ import annotations from pathlib import Path import json +from hermit.hosts.inputs import other_files_section from hermit.plugins.common import (ADAPTER_DIR, AUDIT_LOG, FRAMEWORK_VERSION, SERVER_COMMAND, clear, copy_skills, embed_adapter, load, prepare_output, record, refuse, server_args, subagent_file, write_json) SCHEMA = "https://anthropic.com/claude-code/plugin.schema.json" MARKETPLACE = ".claude-plugin/marketplace.json" +FILES_NOTE = "hermit-files.md" # the list of the adapter's other files the hook prints +HOOKS = "hooks/hooks.json" + + +def folder_hook(bundle, plugin: Path, skills: list[str]) -> str | None: + """Write the hook that tells the session where the adapter's files are, as the deployment's context does + (hermit.hosts.inputs.folder_note and the "Other files" list), when the adapter has any the agent may be sent to: + files no export connects, or skills and roles whose paths are relative to the adapter. Returns the hooks file.""" + others = bundle.other_files + if not (others or bundle.roles or skills): + return None + note = (f"The files of the `{bundle.id}` adapter are in `%s/{ADAPTER_DIR}/`. Paths in its instructions, and in " + f"its skills and roles, are relative to that folder: run a command they give from there " + f"(`cd \"%s/{ADAPTER_DIR}\" && ...`).") + command = f"printf '{note}\\n' \"$CLAUDE_PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\"" + if others: + # Past 10,000 characters Claude Code keeps a hook's output in a file and shows its first 2,000, which hold the + # folder; the list (at most LISTED_FILES entries, as a deployment's) is shorter for any ordinary adapter. + (plugin / FILES_NOTE).write_text("\n" + other_files_section(bundle.adapter, others, None) + "\n") + command += f" && cat \"$CLAUDE_PLUGIN_ROOT/{FILES_NOTE}\"" + write_json(plugin / HOOKS, {"hooks": {"SessionStart": [{"hooks": [{"type": "command", "command": command}]}]}}) + return HOOKS def output_style(name: str, description: str, context: str) -> str: @@ -35,7 +63,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False output = prepare_output(output, bundle.adapter, MARKETPLACE) plugin = output / "plugins" / bundle.id plugin.mkdir(parents=True, exist_ok=True) - clear(plugin, "agents", "output-styles", "skills", ".mcp.json") + clear(plugin, "agents", "output-styles", "skills", ".mcp.json", "hooks", FILES_NOTE) write_json(output / MARKETPLACE, { "name": f"{bundle.id}-adapters", "owner": {"name": "hermit"}, @@ -59,6 +87,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False output_style(bundle.id, f"Context of the {bundle.name} harness adapter", context)) skills = copy_skills(bundle, plugin / "skills") + hooks = folder_hook(bundle, plugin, skills) embed_adapter(bundle, plugin) record(bundle, plugin) if bundle.tools: @@ -72,7 +101,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"claude plugin install {bundle.id}@{bundle.id}-adapters"], "context": f"output-styles/{bundle.id}.md" if bundle.has_context else None, "skills": skills, "roles": roles, "server_name": bundle.server if bundle.tools else None, - "omitted": omitted} + "folder_hook": hooks, "unnamed_files": [], "omitted": omitted} def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list) -> str: @@ -84,6 +113,8 @@ def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list) -> s "The tools run as `hermit serve`, so `hermit` must be installed and on PATH.", "", f"- Context: the output style `{bundle.id}`, applied automatically while the plugin is enabled " "(`force-for-plugin`)." if bundle.has_context else "- Context: none", + f"- The adapter's files: under `{ADAPTER_DIR}/`, which a `SessionStart` hook names to the session" + + (f", with the {len(bundle.other_files)} files no export connects" if bundle.other_files else ""), f"- Skills: {', '.join(skills) or 'none'}", f"- Roles: {', '.join(roles.values()) or 'none'}", f"- Tools: {', '.join(t['name'] for t in bundle.tools) or 'none'}", f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""]) diff --git a/hermit/plugins/codex_plugin.py b/hermit/plugins/codex_plugin.py index d698b562..a8d657df 100644 --- a/hermit/plugins/codex_plugin.py +++ b/hermit/plugins/codex_plugin.py @@ -13,7 +13,8 @@ from pathlib import Path from hermit.plugins.common import (ADAPTER_DIR, AUDIT_LOG, FRAMEWORK_VERSION, SERVER_COMMAND, clear, copy_skills, - embed_adapter, load, prepare_output, record, refuse, server_args, write_json) + embed_adapter, load, prepare_output, record, refuse, server_args, + unnamed_line, write_json) PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json" @@ -53,9 +54,11 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"codex plugin add {bundle.id}@{bundle.id}-adapters", "```", "", "The tools run as `hermit serve`, so `hermit` must be installed and on PATH.", "", f"- Skills: {', '.join(skills) or 'none'}", f"- Tools: {', '.join(t['name'] for t in bundle.tools) or 'none'}", + unnamed_line(bundle, "Codex"), f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""])) return {"target": "codex", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "plugin": str(plugin), "install": [f"codex plugin marketplace add {output}", f"codex plugin add {bundle.id}@{bundle.id}-adapters"], - "skills": skills, "server_name": bundle.server if bundle.tools else None, "omitted": omitted} + "skills": skills, "server_name": bundle.server if bundle.tools else None, + "unnamed_files": bundle.other_files, "omitted": omitted} diff --git a/hermit/plugins/common.py b/hermit/plugins/common.py index abed3ed5..47a5ce12 100644 --- a/hermit/plugins/common.py +++ b/hermit/plugins/common.py @@ -16,7 +16,7 @@ from hermit import __version__ as FRAMEWORK_VERSION from hermit.adapter.loader import agent_tools, hook_definitions, load_manifest -from hermit.hosts.inputs import (copy_skills as _copy_skills, render_exports, role_body, server_name, +from hermit.hosts.inputs import (copy_skills as _copy_skills, other_files, render_exports, role_body, server_name, subagent_markdown, subagent_name) # The adapter travels inside the plugin: a plugin that referenced an outside directory would break the moment it @@ -67,6 +67,13 @@ def server(self) -> str: def has_context(self) -> bool: return bool(self.context.strip()) + @property + def other_files(self) -> list[str]: + """The adapter's files no export connects (paths in the adapter). In training and in a `hermit deploy` + workspace the agent's context names them, at the adapter's copy (hermit.hosts.inputs.resources); a plugin + embeds them under `adapter/`, where only a target that can say where it is installed names them.""" + return other_files(self.adapter, self.manifest, {"agents": self.roles}, self.hooks) + def load(adapter: Path, python: str) -> Bundle: adapter = adapter.resolve() @@ -91,6 +98,17 @@ def refuse(bundle: Bundle, target: str, reasons: dict[str, str], *, allow_lossy: return sorted(reasons) +def unnamed_line(bundle: Bundle, target: str) -> str: + """The README's line on the adapter's files that no export connects: in training and in a `hermit deploy` + workspace the context names them; this target's plugin carries them under `adapter/` but cannot say where it is + installed, so the session is not told about them.""" + if not bundle.other_files: + return "- Files the session is not told about: none" + return (f"- Files the session is not told about: {', '.join(bundle.other_files)} (under `{ADAPTER_DIR}/`; a " + f"{target} plugin cannot name where it is installed, while a `hermit deploy` workspace's context names " + "them)") + + def prepare_output(output: Path, adapter: Path, own_file: str) -> Path: """The output directory: outside the adapter, and empty unless an earlier conversion wrote `own_file` there. `own_file` is one this framework writes and the host's own packages do not have, so a foreign directory is never diff --git a/hermit/plugins/hermes_plugin.py b/hermit/plugins/hermes_plugin.py index 68cadda3..bd33d40a 100644 --- a/hermit/plugins/hermes_plugin.py +++ b/hermit/plugins/hermes_plugin.py @@ -19,7 +19,7 @@ import shutil from hermit.plugins.common import (FRAMEWORK_VERSION, RECORD, clear, copy_skills, embed_adapter, load, - prepare_output, record, refuse) + prepare_output, record, refuse, unnamed_line) SECTION_MAX_CHARS = 4_000 SECTION_MARKERS = ("", "") @@ -66,9 +66,10 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"all plugins' sections together would pass 8,000 characters." if context_file.exists() else "- Context: none", f"- Skills: {', '.join(skills) or 'none'}", f"- Tools: {', '.join(t['hermes_name'] for t in tools) or 'none'}", + unnamed_line(bundle, "Hermes"), f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""])) return {"target": "hermes", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "install": [f"cp -r {output} ~/.hermes/plugins/{bundle.id}", f"hermes plugins enable {bundle.id}"], "context_chars": len(context) if context_file.exists() else 0, "skills": skills, - "tools": [t["hermes_name"] for t in tools], "omitted": omitted} + "tools": [t["hermes_name"] for t in tools], "unnamed_files": bundle.other_files, "omitted": omitted} diff --git a/hermit/plugins/pi_package.py b/hermit/plugins/pi_package.py index 2e883135..4c58836d 100644 --- a/hermit/plugins/pi_package.py +++ b/hermit/plugins/pi_package.py @@ -13,7 +13,8 @@ import json from hermit.plugins.common import (ADAPTER_DIR, AUDIT_LOG, FRAMEWORK_VERSION, RECORD, SERVER_COMMAND, clear, - copy_skills, embed_adapter, load, prepare_output, record, refuse, write_json) + copy_skills, embed_adapter, load, prepare_output, record, refuse, + unnamed_line, write_json) EXTENSION = """\ // Generated by hermit convert: start the adapter's tools when Pi loads this package. @@ -59,8 +60,10 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"{bundle.version}.", "", "```", f"pi install {output}", "```", "", "The tools run as `hermit serve`, so `hermit` must be installed and on PATH.", "", f"- Skills: {', '.join(skills) or 'none'}", f"- Tools: {', '.join(t['name'] for t in bundle.tools) or 'none'}", + unnamed_line(bundle, "Pi"), f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""])) return {"target": "pi", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "install": [f"pi install {output}"], "skills": skills, - "server_name": bundle.server if bundle.tools else None, "omitted": omitted} + "server_name": bundle.server if bundle.tools else None, "unnamed_files": bundle.other_files, + "omitted": omitted} diff --git a/tests/core/test_convert.py b/tests/core/test_convert.py index bfd75ae5..ae74ca9b 100644 --- a/tests/core/test_convert.py +++ b/tests/core/test_convert.py @@ -264,3 +264,63 @@ def test_hooks_are_refused_by_every_target(tmp_path, target): build(target, a, tmp_path / "x", sys.executable) assert not (tmp_path / "x").exists() assert build(target, a, tmp_path / "y", sys.executable, allow_lossy=True)["omitted"] == ["hooks"] + + +# ---- the adapter's files: named to the session as a deployment names them ------------------------------------------ +def _session_start(plugin: Path, cwd: Path) -> str: + """What the plugin's SessionStart hooks print, run as Claude Code runs them: `sh -c` with CLAUDE_PLUGIN_ROOT set.""" + import subprocess + hooks = json.loads((plugin / "hooks" / "hooks.json").read_text())["hooks"]["SessionStart"] + return "".join(subprocess.run(["sh", "-c", h["command"]], cwd=cwd, capture_output=True, text=True, check=True, + env={**os.environ, "CLAUDE_PLUGIN_ROOT": str(plugin)}).stdout + for group in hooks for h in group["hooks"]) + + +def test_claude_code_names_the_adapters_folder_and_files_at_session_start(tmp_path): + from hermit.hosts.codex import prepare + installed = tmp_path / "plugins dir" # a path with a space stays one word + result = build("claude-code", EXAMPLE, installed, sys.executable) + plugin = installed / "plugins" / "file-example" + assert result["folder_hook"] == "hooks/hooks.json" and result["unnamed_files"] == [] + text = _session_start(plugin, tmp_path) + assert text.startswith(f"The files of the `file-example` adapter are in `{plugin}/adapter/`.") + # the same list a deployment's context gives, with paths in the adapter's folder + prepare(EXAMPLE, tmp_path / "w", sys.executable) + deployed = (tmp_path / "w" / "AGENTS.md").read_text() + listed = [line.replace("hermit/file-example/", "") for line in deployed.splitlines() + if line.startswith("- `hermit/file-example/")] + assert listed == ["- `README.md`: File interface example", + "- `tools.py`: A fixed tool used to demonstrate the adapter's deployment interface."] + assert [line for line in text.splitlines() if line.startswith("- `")] == listed + assert all((plugin / "adapter" / line[3:line.index("`", 3)]).is_file() for line in listed) + + +def test_claude_code_names_no_folder_when_nothing_of_the_adapter_lives_there(tmp_path): + a = variant(tmp_path, roles=False) + shutil.rmtree(a / "skills") + (a / "README.md").unlink() + (a / "exports.yaml").write_text("context: ADAPTER.md\n") + (a / "tools.py").unlink() + result = build("claude-code", a, tmp_path / "cc", sys.executable) + assert result["folder_hook"] is None and not (Path(result["plugin"]) / "hooks").exists() + + +def test_a_reconversion_drops_the_list_of_files_the_adapter_no_longer_has(tmp_path): + a = variant(tmp_path) + build("claude-code", a, tmp_path / "cc", sys.executable) + plugin = tmp_path / "cc" / "plugins" / "file-example" + assert (plugin / "hermit-files.md").is_file() + (a / "README.md").unlink() + (a / "exports.yaml").write_text("context: ADAPTER.md\nagents: agents\nskills: skills\n") + (a / "tools.py").unlink() + build("claude-code", a, tmp_path / "cc", sys.executable) + assert not (plugin / "hermit-files.md").exists() # the folder is still named: skills and a role + assert "Other files" not in _session_start(plugin, tmp_path) and "adapter/`." in _session_start(plugin, tmp_path) + + +@pytest.mark.parametrize("target", ["codex", "pi", "hermes"]) +def test_a_target_that_cannot_name_its_folder_reports_the_files_the_session_is_not_told_about(tmp_path, target): + result = build(target, variant(tmp_path, roles=False, context=False), tmp_path / target, sys.executable) + assert result["unnamed_files"] == ["README.md", "tools.py"] + readme = (Path(result.get("plugin") or result["output"]) / "README.md").read_text() + assert "- Files the session is not told about: README.md, tools.py (under `adapter/`" in readme diff --git a/tests/core/test_deploy.py b/tests/core/test_deploy.py index 9e77d078..292c4701 100644 --- a/tests/core/test_deploy.py +++ b/tests/core/test_deploy.py @@ -1,4 +1,5 @@ """Deploying the Lean template into Codex, Claude Code, Pi and DeepSeek Harness workspaces.""" +import importlib.util import json from pathlib import Path import sys @@ -9,6 +10,7 @@ from hermit.hosts.claude_code import prepare as claude_prepare from hermit.hosts.codex import prepare as codex_prepare from hermit.hosts.dsh import prepare as dsh_prepare +from hermit.agent.base.mini_swe_agent import CONFIG_FILE as MINI_CONFIG from hermit.hosts.opencode import prepare as opencode_prepare from hermit.hosts.pi import prepare as pi_prepare @@ -594,3 +596,55 @@ def test_codex_agent_deploys_a_codex_tree_and_writes_the_home(tmp_path): config = tomllib.loads((tmp_path / "home2" / "config.toml").read_text()) assert "multi_agent" not in config["features"] and config["forced_login_method"] == "chatgpt" assert config["web_search"] == "disabled" # the hosted search would reach past the proxy + + +# ---- training delivers the adapter as `hermit deploy` does ----------------------------------------------------------- +HOSTS = [("codex", "codex"), ("claude", "claude-code"), ("pi", "pi"), ("opencode", "opencode"), ("dsh", "dsh"), + ("hermes", "hermes"), + pytest.param("mini-swe-agent", "mini-swe-agent", marks=pytest.mark.skipif( + importlib.util.find_spec("minisweagent") is None, reason="mini-swe-agent is not installed"))] +# What training changes on purpose (hermit.agent.acting.workspace._deploy): nobody is there to approve a tool call, and +# a host that cannot start the adapter's tool server in time, or reads none from the workspace, gets the tools from the +# session's own tool server instead. These files hold the tools' server entry. +TOOL_SERVER_FILES = {"codex": {".codex/config.toml"}, "opencode": {"opencode.json"}, + "hermes": {".hermes/hermit.config.yaml"}, "mini-swe-agent": {MINI_CONFIG}} + + +def _workspace(path: Path) -> dict: + """Every file of a workspace with the workspace's own path written as , so that two can be compared.""" + files = {} + for p in sorted(path.rglob("*")): + if p.is_file(): + files[p.relative_to(path).as_posix()] = p.read_bytes().replace(str(path).encode(), b"") + return files + + +def _deployed_by_both(adapter: Path, tmp_path: Path, backend: str, host: str, capsys) -> tuple[dict, dict, dict]: + """The workspace training gives a task's session and the one `hermit deploy` makes, and training's record.""" + from hermit.agent.acting import workspace as cli + from hermit.cli import main + deployed, _ = cli._deploy({"id": "t"}, adapter, tmp_path / "train", backend, {}) + assert main(["deploy", "--adapter", str(adapter), "--workspace", str(tmp_path / "user"), "--host", host]) == 0 + capsys.readouterr() + return _workspace(tmp_path / "train"), _workspace(tmp_path / "user"), deployed + + +@pytest.mark.parametrize("backend,host", HOSTS) +def test_training_deploys_an_adapter_without_tools_as_hermit_deploy_does(tmp_path, backend, host, capsys): + train, user, _ = _deployed_by_both(tree_adapter(tmp_path), tmp_path, backend, host, capsys) + assert train == user # context, skills, roles, hooks and the adapter's copy, byte for byte + + +@pytest.mark.parametrize("backend,host", HOSTS) +def test_training_deploys_an_adapter_with_tools_as_hermit_deploy_does_but_for_the_tool_server(tmp_path, backend, + host, capsys): + a = Path(__file__).resolve().parents[2] / "docs" / "_examples" / "file_adapter" + train, user, deployed = _deployed_by_both(a, tmp_path, backend, host, capsys) + differ = {k for k in train.keys() | user.keys() if train.get(k) != user.get(k)} + assert differ <= TOOL_SERVER_FILES.get(backend, set()) | {".hermit-deploy.json"} + if backend == "codex": # the same server, its calls approved + config = tomllib.loads(train[".codex/config.toml"].decode()) + assert config["mcp_servers"]["file_example"].pop("default_tools_approval_mode") == "approve" + assert config == tomllib.loads(user[".codex/config.toml"].decode()) + elif differ: # the session's own tool server serves them + assert deployed["harness_tools"] == "file-example" and deployed.get("server_name") is None From 04a2fca000a58230cdfc1d50a50cf112e9dc0e6f Mon Sep 17 00:00:00 2001 From: Ruilin Gao Date: Wed, 18 Nov 2026 04:59:47 -0500 Subject: [PATCH 2/6] Review fixes: a Hermes plugin names the adapter's folder; README and Windows wording; tighter tests A Hermes plugin's register appends the folder note and the list of other files to its system prompt section, within its 4,000 characters. The Claude Code README mentions the hook only when there is one, and the docs say the hook needs a POSIX shell. Tests: a reconversion removes a hook no longer needed; the deployment records differ only in the tools' entries. --- CHANGELOG.md | 4 +-- docs/framework/commands.md | 18 ++++++++----- hermit/plugins/claude_plugin.py | 24 +++++++++--------- hermit/plugins/common.py | 18 +++++++++++-- hermit/plugins/hermes/plugin_init.py | 17 ++++++++----- hermit/plugins/hermes_plugin.py | 38 +++++++++++++++++++++++----- tests/core/test_convert.py | 36 +++++++++++++++++++++++--- tests/core/test_deploy.py | 3 +++ 8 files changed, 120 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a05e90a6..2bee51b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,8 +30,8 @@ Changes are grouped by software version. Entries under Unreleased describe work - `hermit convert` names the adapter's folder and files as a deployment does: a Claude Code plugin prints, from a `SessionStart` hook, where its embedded adapter is and the files no export connects (the list a deployment's - context gives); Codex, Pi and Hermes plugins, which cannot say where they are installed, list those files under - `unnamed_files` in the result and in their README. + context gives), and a Hermes plugin appends them to its system prompt section; Codex and Pi plugins, which read no + context, list those files under `unnamed_files` in the result and in their README. - A test that training deploys an adapter into a task's workspace as `hermit deploy` does, file for file on every host, the tools' server entry aside (calls approved; the session's own tool server for a host that cannot start it). - LIBERO (`examples/libero/`): LIBERO's Object, Spatial, Goal, Long and LIBERO-90 suites and LIBERO-Pro's `_swap` and diff --git a/docs/framework/commands.md b/docs/framework/commands.md index 68c67e43..ebc07ae3 100644 --- a/docs/framework/commands.md +++ b/docs/framework/commands.md @@ -136,7 +136,7 @@ names the machine that produced it. | Tools | `.mcp.json` | `mcp.json` | generated extension, `pi.registerMcpServer` | `ctx.register_tool`, forwarding to `hermit serve` | | Roles | `agents/` | refused | refused | refused | | Hooks | refused | refused | refused | refused | -| The adapter's folder and its other files | named by a `SessionStart` hook | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | +| The adapter's folder and its other files | named by a `SessionStart` hook | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | named at the end of the section, within 4,000 characters | A part the target's plugin format cannot carry is refused: `convert` exits 2 and names every such part before writing anything. A non-empty context (`ADAPTER.md`) makes Codex and Pi refuse, and a context over 4,000 characters makes @@ -146,12 +146,16 @@ under `omitted` in the result. In training and in a `deploy` workspace, the agent's context says where the adapter's copy is (paths in its instructions, skills and roles are relative to that folder) and lists the files no export connects, such as a -README or a tool's source. A plugin carries those files under `adapter/`, but an output style, a skill folder or a -system prompt section cannot say where the plugin is installed. A Claude Code plugin says it with a `SessionStart` -hook: it prints the installed folder and the same list (`hermit-files.md`), and Claude Code adds a SessionStart hook's -output to the context (the hook runs under `sh`, Git Bash on Windows). Codex, Pi and Hermes have no such place, so their -result lists the files under `unnamed_files` and the plugin's README names them; nothing is refused for them, since -the plugin still holds the files. +README or a tool's source. A plugin carries those files under `adapter/` and names them where its format can say +where it is installed: + +- **Claude Code:** an output style gets no `${CLAUDE_PLUGIN_ROOT}`, so a `SessionStart` hook prints the installed + folder and the same list (`hermit-files.md`), and Claude Code adds its output to the context. The hook is a POSIX + shell command (`sh`; Git Bash on Windows, without which Claude Code uses PowerShell and the hook fails). +- **Hermes:** the plugin's `register` appends the folder and the list to its system prompt section (`files.md`), when + the section stays within 4,000 characters; otherwise the files are listed under `unnamed_files`. +- **Codex and Pi** read no context from a plugin, so the result lists the files under `unnamed_files` and the + plugin's README names them. Nothing is refused for them, since the plugin still holds the files. Why the refusals: diff --git a/hermit/plugins/claude_plugin.py b/hermit/plugins/claude_plugin.py index 8ec7a9cc..0fcad203 100644 --- a/hermit/plugins/claude_plugin.py +++ b/hermit/plugins/claude_plugin.py @@ -14,7 +14,8 @@ where the adapter's copy is and names the files no export connects (hermit.hosts.inputs.resources). An output style cannot say where the plugin is installed (Claude Code substitutes `${CLAUDE_PLUGIN_ROOT}` in skills, agents, hooks and servers, not in an output style), so a `SessionStart` hook says it: Claude Code adds a - SessionStart hook's output to the context. The hook runs under `sh` (Git Bash on Windows). + SessionStart hook's output to the context. The hook is a POSIX shell command: `sh` on macOS and Linux, Git Bash on + Windows (where Claude Code falls back to PowerShell without Git Bash, and the hook fails). """ from __future__ import annotations @@ -23,8 +24,8 @@ from hermit.hosts.inputs import other_files_section from hermit.plugins.common import (ADAPTER_DIR, AUDIT_LOG, FRAMEWORK_VERSION, SERVER_COMMAND, clear, copy_skills, - embed_adapter, load, prepare_output, record, refuse, server_args, - subagent_file, write_json) + embed_adapter, folder_sentence, load, names_folder, prepare_output, + record, refuse, server_args, subagent_file, write_json) SCHEMA = "https://anthropic.com/claude-code/plugin.schema.json" MARKETPLACE = ".claude-plugin/marketplace.json" @@ -37,12 +38,10 @@ def folder_hook(bundle, plugin: Path, skills: list[str]) -> str | None: (hermit.hosts.inputs.folder_note and the "Other files" list), when the adapter has any the agent may be sent to: files no export connects, or skills and roles whose paths are relative to the adapter. Returns the hooks file.""" others = bundle.other_files - if not (others or bundle.roles or skills): + if not names_folder(bundle, skills): return None - note = (f"The files of the `{bundle.id}` adapter are in `%s/{ADAPTER_DIR}/`. Paths in its instructions, and in " - f"its skills and roles, are relative to that folder: run a command they give from there " - f"(`cd \"%s/{ADAPTER_DIR}\" && ...`).") - command = f"printf '{note}\\n' \"$CLAUDE_PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\"" + # the installed path is printf's argument, never part of the command; an adapter id has no % or quote + command = f"printf '{folder_sentence(bundle, '%s')}\\n' \"$CLAUDE_PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\"" if others: # Past 10,000 characters Claude Code keeps a hook's output in a file and shows its first 2,000, which hold the # folder; the list (at most LISTED_FILES entries, as a deployment's) is shorter for any ordinary adapter. @@ -94,7 +93,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False write_json(plugin / ".mcp.json", {"mcpServers": {bundle.server: { "type": "stdio", "command": SERVER_COMMAND, "args": server_args(f"${{CLAUDE_PLUGIN_ROOT}}/{ADAPTER_DIR}", f"${{CLAUDE_PLUGIN_DATA}}/{AUDIT_LOG}")}}}) - (plugin / "README.md").write_text(_readme(bundle, output, skills, roles, omitted)) + (plugin / "README.md").write_text(_readme(bundle, output, skills, roles, omitted, hooks)) return {"target": "claude-code", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "plugin": str(plugin), "install": [f"claude plugin marketplace add {output}", @@ -104,7 +103,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False "folder_hook": hooks, "unnamed_files": [], "omitted": omitted} -def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list) -> str: +def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list, hooks: str | None) -> str: return "\n".join([ f"# {bundle.name}", "", f"A Claude Code plugin generated by `hermit convert` from the `{bundle.id}` adapter, version " @@ -113,8 +112,9 @@ def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list) -> s "The tools run as `hermit serve`, so `hermit` must be installed and on PATH.", "", f"- Context: the output style `{bundle.id}`, applied automatically while the plugin is enabled " "(`force-for-plugin`)." if bundle.has_context else "- Context: none", - f"- The adapter's files: under `{ADAPTER_DIR}/`, which a `SessionStart` hook names to the session" - + (f", with the {len(bundle.other_files)} files no export connects" if bundle.other_files else ""), + (f"- The adapter's files: under `{ADAPTER_DIR}/`, which a `SessionStart` hook names to the session" + + (f", with the {len(bundle.other_files)} files no export connects" if bundle.other_files else "")) + if hooks else "- The adapter's files: under `adapter/`, for its tools; none is named to the session", f"- Skills: {', '.join(skills) or 'none'}", f"- Roles: {', '.join(roles.values()) or 'none'}", f"- Tools: {', '.join(t['name'] for t in bundle.tools) or 'none'}", f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""]) diff --git a/hermit/plugins/common.py b/hermit/plugins/common.py index 47a5ce12..147f9cef 100644 --- a/hermit/plugins/common.py +++ b/hermit/plugins/common.py @@ -10,6 +10,7 @@ from __future__ import annotations from dataclasses import dataclass +from functools import cached_property from pathlib import Path import json import shutil @@ -67,11 +68,11 @@ def server(self) -> str: def has_context(self) -> bool: return bool(self.context.strip()) - @property + @cached_property def other_files(self) -> list[str]: """The adapter's files no export connects (paths in the adapter). In training and in a `hermit deploy` workspace the agent's context names them, at the adapter's copy (hermit.hosts.inputs.resources); a plugin - embeds them under `adapter/`, where only a target that can say where it is installed names them.""" + embeds them under `adapter/`, and names them where the target can say where it is installed.""" return other_files(self.adapter, self.manifest, {"agents": self.roles}, self.hooks) @@ -98,6 +99,19 @@ def refuse(bundle: Bundle, target: str, reasons: dict[str, str], *, allow_lossy: return sorted(reasons) +def folder_sentence(bundle: Bundle, root: str) -> str: + """The deployment's folder note (hermit.hosts.inputs.folder_note) for a plugin installed at `root`.""" + return (f"The files of the `{bundle.id}` adapter are in `{root}/{ADAPTER_DIR}/`. Paths in its instructions, and in " + f"its skills and roles, are relative to that folder: run a command they give from there " + f"(`cd \"{root}/{ADAPTER_DIR}\" && ...`).") + + +def names_folder(bundle: Bundle, skills: list[str]) -> bool: + """Whether the session should be told where the adapter's files are: it has files no export connects, or skills + or roles whose paths are relative to the adapter's folder (as a deployment's context says).""" + return bool(bundle.other_files or bundle.roles or skills) + + def unnamed_line(bundle: Bundle, target: str) -> str: """The README's line on the adapter's files that no export connects: in training and in a `hermit deploy` workspace the context names them; this target's plugin carries them under `adapter/` but cannot say where it is diff --git a/hermit/plugins/hermes/plugin_init.py b/hermit/plugins/hermes/plugin_init.py index acb4e3a8..fbcfbfa0 100644 --- a/hermit/plugins/hermes/plugin_init.py +++ b/hermit/plugins/hermes/plugin_init.py @@ -1,8 +1,8 @@ """Generated by hermit convert: a harness adapter as a native Hermes plugin. -`convert` copies this file unchanged into every Hermes plugin it emits, as the plugin's `__init__.py`. What is specific -to the adapter sits next to it: `hermit.json` (plugin id, version, tool list), `context.md`, `skills/` and the -embedded `adapter/`. The tools run in one `hermit serve` process, started on the first call and reused for the +`convert` copies this file unchanged into every Hermes plugin it emits, as the plugin's `__init__.py`. What is +specific to the adapter sits next to it: `hermit.json` (plugin id, version, tool list), `context.md`, `files.md` +(where the adapter's files are), `skills/` and the embedded `adapter/`. The tools run in one `hermit serve` process, started on the first call and reused for the session. """ import json @@ -85,9 +85,14 @@ def handle(args, **kwargs): def register(ctx): META.update(json.loads((ROOT / "hermit.json").read_text())) - context = ROOT / "context.md" - if context.is_file(): - ctx.register_system_prompt_section(META["plugin"], context.read_text()) + section = (ROOT / "context.md").read_text().strip() if (ROOT / "context.md").is_file() else "" + files = ROOT / "files.md" # where the adapter's files are; convert left room for the installed path + if files.is_file(): + note = files.read_text().replace(META["folder"], str(ROOT)).strip() + if len(section) + 2 + len(note) <= META["section_max"]: + section = (section + "\n\n" + note).strip() + if section: + ctx.register_system_prompt_section(META["plugin"], section + "\n") skills = ROOT / "skills" if skills.is_dir(): for child in sorted(skills.iterdir()): diff --git a/hermit/plugins/hermes_plugin.py b/hermit/plugins/hermes_plugin.py index bd33d40a..d717db3b 100644 --- a/hermit/plugins/hermes_plugin.py +++ b/hermit/plugins/hermes_plugin.py @@ -8,6 +8,10 @@ - tools: `ctx.register_tool`, each forwarding to a `hermit serve` process the plugin starts on the first call, so the tools run exactly as they do under the other hosts. - roles: Hermes has no file-defined subagents; an adapter with roles is refused. +- the adapter's files: embedded under `adapter/`. `register` knows where the plugin is installed, so the section + ends with the deployment's folder note and its list of the files no export connects (`files.md`, the folder + written in when Hermes loads the plugin), as long as the section stays within 4,000 characters; otherwise the files + are listed under `unnamed_files`. The plugin's `__init__.py` is `hermes/plugin_init.py`, the same file for every adapter; the adapter-specific parts are data next to it. @@ -18,10 +22,14 @@ import json import shutil -from hermit.plugins.common import (FRAMEWORK_VERSION, RECORD, clear, copy_skills, embed_adapter, load, - prepare_output, record, refuse, unnamed_line) +from hermit.hosts.inputs import other_files_section +from hermit.plugins.common import (FRAMEWORK_VERSION, RECORD, clear, copy_skills, embed_adapter, folder_sentence, load, + names_folder, prepare_output, record, refuse, unnamed_line) SECTION_MAX_CHARS = 4_000 +FILES = "files.md" # the folder note and the list, with FOLDER where the installed folder goes +FOLDER = "@HERMIT_PLUGIN_ROOT@" +PATH_ROOM = 2 * 300 # the installed path, written in twice, counted against the section's limit SECTION_MARKERS = ("", "") # Copied unchanged into every emitted plugin as its `__init__.py`. @@ -41,7 +49,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False reasons["roles"] = f"Hermes has no file-defined subagents ({', '.join(r['name'] for r in bundle.roles)})" omitted = refuse(bundle, "Hermes", reasons, allow_lossy=allow_lossy) output = prepare_output(output, bundle.adapter, RECORD) - clear(output, "skills", "context.md") + clear(output, "skills", "context.md", FILES) tools = [{"name": t["name"], "hermes_name": f"{bundle.server}_{t['name']}", "description": t["description"], "input_schema": t["input_schema"]} for t in bundle.tools] @@ -49,11 +57,12 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"name: {bundle.id}\nversion: {json.dumps(bundle.version)}\ndescription: {json.dumps(bundle.name)}\n" + (f"provides_tools: [{', '.join(t['hermes_name'] for t in tools)}]\n" if tools else "")) shutil.copyfile(PLUGIN_INIT, output / "__init__.py") - record(bundle, output, toolset=bundle.server, tools=tools) + record(bundle, output, toolset=bundle.server, tools=tools, section_max=SECTION_MAX_CHARS, folder=FOLDER) context_file = output / "context.md" if bundle.has_context and "context" not in omitted: context_file.write_text(context + "\n") skills = copy_skills(bundle, output / "skills") + named = _files_note(bundle, output, skills, context if context_file.exists() else "") embed_adapter(bundle, output) (output / "README.md").write_text("\n".join([ f"# {bundle.name}", "", @@ -66,10 +75,27 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"all plugins' sections together would pass 8,000 characters." if context_file.exists() else "- Context: none", f"- Skills: {', '.join(skills) or 'none'}", f"- Tools: {', '.join(t['hermes_name'] for t in tools) or 'none'}", - unnamed_line(bundle, "Hermes"), + (f"- The adapter's files: under `adapter/`, named at the end of the section" + + (f" with the {len(bundle.other_files)} files no export connects" if bundle.other_files else "")) + if named else unnamed_line(bundle, "Hermes"), f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""])) return {"target": "hermes", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "install": [f"cp -r {output} ~/.hermes/plugins/{bundle.id}", f"hermes plugins enable {bundle.id}"], "context_chars": len(context) if context_file.exists() else 0, "skills": skills, - "tools": [t["hermes_name"] for t in tools], "unnamed_files": bundle.other_files, "omitted": omitted} + "tools": [t["hermes_name"] for t in tools], "files_named": named, + "unnamed_files": [] if named else bundle.other_files, "omitted": omitted} + + +def _files_note(bundle, output: Path, skills: list[str], context: str) -> bool: + """Write `files.md`, which `register` appends to the section with the installed folder written in, when the session + should be told where the adapter's files are and the section stays within Hermes' limit. Whether it was written.""" + if not names_folder(bundle, skills): + return False + text = folder_sentence(bundle, FOLDER) + if bundle.other_files: + text += "\n\n" + other_files_section(bundle.adapter, bundle.other_files, None) + if len(context) + 2 + len(text) + PATH_ROOM > SECTION_MAX_CHARS: + return False + (output / FILES).write_text(text + "\n") + return True diff --git a/tests/core/test_convert.py b/tests/core/test_convert.py index ae74ca9b..68e88df2 100644 --- a/tests/core/test_convert.py +++ b/tests/core/test_convert.py @@ -4,6 +4,7 @@ import os from pathlib import Path import shutil +import subprocess import sys import pytest @@ -269,7 +270,6 @@ def test_hooks_are_refused_by_every_target(tmp_path, target): # ---- the adapter's files: named to the session as a deployment names them ------------------------------------------ def _session_start(plugin: Path, cwd: Path) -> str: """What the plugin's SessionStart hooks print, run as Claude Code runs them: `sh -c` with CLAUDE_PLUGIN_ROOT set.""" - import subprocess hooks = json.loads((plugin / "hooks" / "hooks.json").read_text())["hooks"]["SessionStart"] return "".join(subprocess.run(["sh", "-c", h["command"]], cwd=cwd, capture_output=True, text=True, check=True, env={**os.environ, "CLAUDE_PLUGIN_ROOT": str(plugin)}).stdout @@ -315,10 +315,40 @@ def test_a_reconversion_drops_the_list_of_files_the_adapter_no_longer_has(tmp_pa (a / "tools.py").unlink() build("claude-code", a, tmp_path / "cc", sys.executable) assert not (plugin / "hermit-files.md").exists() # the folder is still named: skills and a role - assert "Other files" not in _session_start(plugin, tmp_path) and "adapter/`." in _session_start(plugin, tmp_path) + text = _session_start(plugin, tmp_path) + assert "Other files" not in text and "adapter/`." in text + shutil.rmtree(a / "skills") + shutil.rmtree(a / "agents") + (a / "exports.yaml").write_text("context: ADAPTER.md\n") + result = build("claude-code", a, tmp_path / "cc", sys.executable) + assert result["folder_hook"] is None and not (plugin / "hooks").exists() # nothing left for a hook to name + assert "none is named to the session" in (plugin / "README.md").read_text() + + +def test_hermes_names_the_adapters_folder_and_files_at_the_end_of_its_section(tmp_path): + out = tmp_path / "installed here" + result = build("hermes", variant(tmp_path, roles=False), out, sys.executable) + assert result["files_named"] is True and result["unnamed_files"] == [] + ctx = StubContext() + load_hermes_module(out).register(ctx) + section = ctx.sections["file-example"] + assert section.startswith("Review the task requirements") + assert f"The files of the `file-example` adapter are in `{out.resolve()}/adapter/`." in section + assert "- `README.md`: File interface example" in section and "- `tools.py`:" in section + assert len(section) <= 4_000 + + +def test_hermes_reports_the_files_when_naming_them_would_pass_its_section_limit(tmp_path): + a = variant(tmp_path, roles=False) + (a / "ADAPTER.md").write_text("Check the result. " * 210) # about 3,800 characters: within 4,000 + result = build("hermes", a, tmp_path / "h", sys.executable) + assert result["files_named"] is False and result["unnamed_files"] == ["README.md", "tools.py"] + ctx = StubContext() + load_hermes_module(tmp_path / "h").register(ctx) + assert "adapter/`" not in ctx.sections["file-example"] -@pytest.mark.parametrize("target", ["codex", "pi", "hermes"]) +@pytest.mark.parametrize("target", ["codex", "pi"]) def test_a_target_that_cannot_name_its_folder_reports_the_files_the_session_is_not_told_about(tmp_path, target): result = build(target, variant(tmp_path, roles=False, context=False), tmp_path / target, sys.executable) assert result["unnamed_files"] == ["README.md", "tools.py"] diff --git a/tests/core/test_deploy.py b/tests/core/test_deploy.py index 292c4701..b3ae7b36 100644 --- a/tests/core/test_deploy.py +++ b/tests/core/test_deploy.py @@ -642,6 +642,9 @@ def test_training_deploys_an_adapter_with_tools_as_hermit_deploy_does_but_for_th train, user, deployed = _deployed_by_both(a, tmp_path, backend, host, capsys) differ = {k for k in train.keys() | user.keys() if train.get(k) != user.get(k)} assert differ <= TOOL_SERVER_FILES.get(backend, set()) | {".hermit-deploy.json"} + records = [json.loads(w[".hermit-deploy.json"].decode()) for w in (train, user)] + assert {k for k in records[0].keys() | records[1].keys() if records[0].get(k) != records[1].get(k)} <= \ + {"server", "server_name", "audit_log", "environment_class", "tools"} # the tools' entries only if backend == "codex": # the same server, its calls approved config = tomllib.loads(train[".codex/config.toml"].decode()) assert config["mcp_servers"]["file_example"].pop("default_tools_approval_mode") == "approve" From 90b30138d5c33e6bcac2d6b80a24eae0531f1c7b Mon Sep 17 00:00:00 2001 From: Ruilin Gao Date: Wed, 18 Nov 2026 05:00:08 -0500 Subject: [PATCH 3/6] Wrap the Hermes plugin's docstring --- hermit/plugins/hermes/plugin_init.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hermit/plugins/hermes/plugin_init.py b/hermit/plugins/hermes/plugin_init.py index fbcfbfa0..e7f043c0 100644 --- a/hermit/plugins/hermes/plugin_init.py +++ b/hermit/plugins/hermes/plugin_init.py @@ -2,8 +2,8 @@ `convert` copies this file unchanged into every Hermes plugin it emits, as the plugin's `__init__.py`. What is specific to the adapter sits next to it: `hermit.json` (plugin id, version, tool list), `context.md`, `files.md` -(where the adapter's files are), `skills/` and the embedded `adapter/`. The tools run in one `hermit serve` process, started on the first call and reused for the -session. +(where the adapter's files are), `skills/` and the embedded `adapter/`. The tools run in one `hermit serve` +process, started on the first call and reused for the session. """ import json from pathlib import Path From 1fff957764cfaff2df66d34e146dcaccaf99862c Mon Sep 17 00:00:00 2001 From: Ruilin Gao Date: Wed, 18 Nov 2026 21:44:46 -0500 Subject: [PATCH 4/6] Hermes plugins report the files, as Codex and Pi do; shorter docs --- CHANGELOG.md | 3 +-- docs/framework/commands.md | 15 +++-------- hermit/plugins/claude_plugin.py | 9 ++++--- hermit/plugins/common.py | 24 +++--------------- hermit/plugins/hermes/plugin_init.py | 19 +++++--------- hermit/plugins/hermes_plugin.py | 38 +++++----------------------- tests/core/test_convert.py | 29 +++------------------ 7 files changed, 31 insertions(+), 106 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 095d4154..2089125a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,8 +39,7 @@ Changes are grouped by software version. Entries under Unreleased describe work - `hermit convert` names the adapter's folder and files as a deployment does: a Claude Code plugin prints, from a `SessionStart` hook, where its embedded adapter is and the files no export connects (the list a deployment's - context gives), and a Hermes plugin appends them to its system prompt section; Codex and Pi plugins, which read no - context, list those files under `unnamed_files` in the result and in their README. + context gives); Codex, Pi and Hermes plugins list those files under `unnamed_files` in the result and their README. - A test that training deploys an adapter into a task's workspace as `hermit deploy` does, file for file on every host, the tools' server entry aside (calls approved; the session's own tool server for a host that cannot start it). - RoboDojo-Sim (`examples/robodojo_sim/`), a first implementation (its smoke run on the real simulator; no diff --git a/docs/framework/commands.md b/docs/framework/commands.md index ebc07ae3..9d36865e 100644 --- a/docs/framework/commands.md +++ b/docs/framework/commands.md @@ -136,7 +136,7 @@ names the machine that produced it. | Tools | `.mcp.json` | `mcp.json` | generated extension, `pi.registerMcpServer` | `ctx.register_tool`, forwarding to `hermit serve` | | Roles | `agents/` | refused | refused | refused | | Hooks | refused | refused | refused | refused | -| The adapter's folder and its other files | named by a `SessionStart` hook | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | named at the end of the section, within 4,000 characters | +| The adapter's folder and its other files | named by a `SessionStart` hook | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | not named: listed under `unnamed_files` | A part the target's plugin format cannot carry is refused: `convert` exits 2 and names every such part before writing anything. A non-empty context (`ADAPTER.md`) makes Codex and Pi refuse, and a context over 4,000 characters makes @@ -146,16 +146,9 @@ under `omitted` in the result. In training and in a `deploy` workspace, the agent's context says where the adapter's copy is (paths in its instructions, skills and roles are relative to that folder) and lists the files no export connects, such as a -README or a tool's source. A plugin carries those files under `adapter/` and names them where its format can say -where it is installed: - -- **Claude Code:** an output style gets no `${CLAUDE_PLUGIN_ROOT}`, so a `SessionStart` hook prints the installed - folder and the same list (`hermit-files.md`), and Claude Code adds its output to the context. The hook is a POSIX - shell command (`sh`; Git Bash on Windows, without which Claude Code uses PowerShell and the hook fails). -- **Hermes:** the plugin's `register` appends the folder and the list to its system prompt section (`files.md`), when - the section stays within 4,000 characters; otherwise the files are listed under `unnamed_files`. -- **Codex and Pi** read no context from a plugin, so the result lists the files under `unnamed_files` and the - plugin's README names them. Nothing is refused for them, since the plugin still holds the files. +README or a tool's source. A Claude Code plugin names them with a `SessionStart` hook, which prints the installed +folder and the same list (an output style gets no `${CLAUDE_PLUGIN_ROOT}`); the hook needs a POSIX shell (Git Bash on +Windows). The other targets list them under `unnamed_files` and in the plugin's README. Why the refusals: diff --git a/hermit/plugins/claude_plugin.py b/hermit/plugins/claude_plugin.py index 0fcad203..976d5d17 100644 --- a/hermit/plugins/claude_plugin.py +++ b/hermit/plugins/claude_plugin.py @@ -24,7 +24,7 @@ from hermit.hosts.inputs import other_files_section from hermit.plugins.common import (ADAPTER_DIR, AUDIT_LOG, FRAMEWORK_VERSION, SERVER_COMMAND, clear, copy_skills, - embed_adapter, folder_sentence, load, names_folder, prepare_output, + embed_adapter, load, prepare_output, record, refuse, server_args, subagent_file, write_json) SCHEMA = "https://anthropic.com/claude-code/plugin.schema.json" @@ -38,10 +38,13 @@ def folder_hook(bundle, plugin: Path, skills: list[str]) -> str | None: (hermit.hosts.inputs.folder_note and the "Other files" list), when the adapter has any the agent may be sent to: files no export connects, or skills and roles whose paths are relative to the adapter. Returns the hooks file.""" others = bundle.other_files - if not names_folder(bundle, skills): + if not (others or bundle.roles or skills): return None # the installed path is printf's argument, never part of the command; an adapter id has no % or quote - command = f"printf '{folder_sentence(bundle, '%s')}\\n' \"$CLAUDE_PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\"" + note = (f"The files of the `{bundle.id}` adapter are in `%s/{ADAPTER_DIR}/`. Paths in its instructions, and in " + f"its skills and roles, are relative to that folder: run a command they give from there " + f"(`cd \"%s/{ADAPTER_DIR}\" && ...`).") + command = f"printf '{note}\\n' \"$CLAUDE_PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\"" if others: # Past 10,000 characters Claude Code keeps a hook's output in a file and shows its first 2,000, which hold the # folder; the list (at most LISTED_FILES entries, as a deployment's) is shorter for any ordinary adapter. diff --git a/hermit/plugins/common.py b/hermit/plugins/common.py index 147f9cef..411c05a7 100644 --- a/hermit/plugins/common.py +++ b/hermit/plugins/common.py @@ -72,7 +72,7 @@ def has_context(self) -> bool: def other_files(self) -> list[str]: """The adapter's files no export connects (paths in the adapter). In training and in a `hermit deploy` workspace the agent's context names them, at the adapter's copy (hermit.hosts.inputs.resources); a plugin - embeds them under `adapter/`, and names them where the target can say where it is installed.""" + embeds them under `adapter/`.""" return other_files(self.adapter, self.manifest, {"agents": self.roles}, self.hooks) @@ -99,28 +99,12 @@ def refuse(bundle: Bundle, target: str, reasons: dict[str, str], *, allow_lossy: return sorted(reasons) -def folder_sentence(bundle: Bundle, root: str) -> str: - """The deployment's folder note (hermit.hosts.inputs.folder_note) for a plugin installed at `root`.""" - return (f"The files of the `{bundle.id}` adapter are in `{root}/{ADAPTER_DIR}/`. Paths in its instructions, and in " - f"its skills and roles, are relative to that folder: run a command they give from there " - f"(`cd \"{root}/{ADAPTER_DIR}\" && ...`).") - - -def names_folder(bundle: Bundle, skills: list[str]) -> bool: - """Whether the session should be told where the adapter's files are: it has files no export connects, or skills - or roles whose paths are relative to the adapter's folder (as a deployment's context says).""" - return bool(bundle.other_files or bundle.roles or skills) - - def unnamed_line(bundle: Bundle, target: str) -> str: - """The README's line on the adapter's files that no export connects: in training and in a `hermit deploy` - workspace the context names them; this target's plugin carries them under `adapter/` but cannot say where it is - installed, so the session is not told about them.""" + """The README's line on the adapter's files that no export connects, which the plugin carries but does not name to + the session (a `hermit deploy` workspace's context names them).""" if not bundle.other_files: return "- Files the session is not told about: none" - return (f"- Files the session is not told about: {', '.join(bundle.other_files)} (under `{ADAPTER_DIR}/`; a " - f"{target} plugin cannot name where it is installed, while a `hermit deploy` workspace's context names " - "them)") + return f"- Files the session is not told about: {', '.join(bundle.other_files)} (under `{ADAPTER_DIR}/`)" def prepare_output(output: Path, adapter: Path, own_file: str) -> Path: diff --git a/hermit/plugins/hermes/plugin_init.py b/hermit/plugins/hermes/plugin_init.py index e7f043c0..acb4e3a8 100644 --- a/hermit/plugins/hermes/plugin_init.py +++ b/hermit/plugins/hermes/plugin_init.py @@ -1,9 +1,9 @@ """Generated by hermit convert: a harness adapter as a native Hermes plugin. -`convert` copies this file unchanged into every Hermes plugin it emits, as the plugin's `__init__.py`. What is -specific to the adapter sits next to it: `hermit.json` (plugin id, version, tool list), `context.md`, `files.md` -(where the adapter's files are), `skills/` and the embedded `adapter/`. The tools run in one `hermit serve` -process, started on the first call and reused for the session. +`convert` copies this file unchanged into every Hermes plugin it emits, as the plugin's `__init__.py`. What is specific +to the adapter sits next to it: `hermit.json` (plugin id, version, tool list), `context.md`, `skills/` and the +embedded `adapter/`. The tools run in one `hermit serve` process, started on the first call and reused for the +session. """ import json from pathlib import Path @@ -85,14 +85,9 @@ def handle(args, **kwargs): def register(ctx): META.update(json.loads((ROOT / "hermit.json").read_text())) - section = (ROOT / "context.md").read_text().strip() if (ROOT / "context.md").is_file() else "" - files = ROOT / "files.md" # where the adapter's files are; convert left room for the installed path - if files.is_file(): - note = files.read_text().replace(META["folder"], str(ROOT)).strip() - if len(section) + 2 + len(note) <= META["section_max"]: - section = (section + "\n\n" + note).strip() - if section: - ctx.register_system_prompt_section(META["plugin"], section + "\n") + context = ROOT / "context.md" + if context.is_file(): + ctx.register_system_prompt_section(META["plugin"], context.read_text()) skills = ROOT / "skills" if skills.is_dir(): for child in sorted(skills.iterdir()): diff --git a/hermit/plugins/hermes_plugin.py b/hermit/plugins/hermes_plugin.py index d717db3b..bd33d40a 100644 --- a/hermit/plugins/hermes_plugin.py +++ b/hermit/plugins/hermes_plugin.py @@ -8,10 +8,6 @@ - tools: `ctx.register_tool`, each forwarding to a `hermit serve` process the plugin starts on the first call, so the tools run exactly as they do under the other hosts. - roles: Hermes has no file-defined subagents; an adapter with roles is refused. -- the adapter's files: embedded under `adapter/`. `register` knows where the plugin is installed, so the section - ends with the deployment's folder note and its list of the files no export connects (`files.md`, the folder - written in when Hermes loads the plugin), as long as the section stays within 4,000 characters; otherwise the files - are listed under `unnamed_files`. The plugin's `__init__.py` is `hermes/plugin_init.py`, the same file for every adapter; the adapter-specific parts are data next to it. @@ -22,14 +18,10 @@ import json import shutil -from hermit.hosts.inputs import other_files_section -from hermit.plugins.common import (FRAMEWORK_VERSION, RECORD, clear, copy_skills, embed_adapter, folder_sentence, load, - names_folder, prepare_output, record, refuse, unnamed_line) +from hermit.plugins.common import (FRAMEWORK_VERSION, RECORD, clear, copy_skills, embed_adapter, load, + prepare_output, record, refuse, unnamed_line) SECTION_MAX_CHARS = 4_000 -FILES = "files.md" # the folder note and the list, with FOLDER where the installed folder goes -FOLDER = "@HERMIT_PLUGIN_ROOT@" -PATH_ROOM = 2 * 300 # the installed path, written in twice, counted against the section's limit SECTION_MARKERS = ("", "") # Copied unchanged into every emitted plugin as its `__init__.py`. @@ -49,7 +41,7 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False reasons["roles"] = f"Hermes has no file-defined subagents ({', '.join(r['name'] for r in bundle.roles)})" omitted = refuse(bundle, "Hermes", reasons, allow_lossy=allow_lossy) output = prepare_output(output, bundle.adapter, RECORD) - clear(output, "skills", "context.md", FILES) + clear(output, "skills", "context.md") tools = [{"name": t["name"], "hermes_name": f"{bundle.server}_{t['name']}", "description": t["description"], "input_schema": t["input_schema"]} for t in bundle.tools] @@ -57,12 +49,11 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"name: {bundle.id}\nversion: {json.dumps(bundle.version)}\ndescription: {json.dumps(bundle.name)}\n" + (f"provides_tools: [{', '.join(t['hermes_name'] for t in tools)}]\n" if tools else "")) shutil.copyfile(PLUGIN_INIT, output / "__init__.py") - record(bundle, output, toolset=bundle.server, tools=tools, section_max=SECTION_MAX_CHARS, folder=FOLDER) + record(bundle, output, toolset=bundle.server, tools=tools) context_file = output / "context.md" if bundle.has_context and "context" not in omitted: context_file.write_text(context + "\n") skills = copy_skills(bundle, output / "skills") - named = _files_note(bundle, output, skills, context if context_file.exists() else "") embed_adapter(bundle, output) (output / "README.md").write_text("\n".join([ f"# {bundle.name}", "", @@ -75,27 +66,10 @@ def build(adapter: Path, output: Path, python: str, *, allow_lossy: bool = False f"all plugins' sections together would pass 8,000 characters." if context_file.exists() else "- Context: none", f"- Skills: {', '.join(skills) or 'none'}", f"- Tools: {', '.join(t['hermes_name'] for t in tools) or 'none'}", - (f"- The adapter's files: under `adapter/`, named at the end of the section" - + (f" with the {len(bundle.other_files)} files no export connects" if bundle.other_files else "")) - if named else unnamed_line(bundle, "Hermes"), + unnamed_line(bundle, "Hermes"), f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""])) return {"target": "hermes", "adapter_id": bundle.id, "version": bundle.version, "framework": FRAMEWORK_VERSION, "output": str(output), "install": [f"cp -r {output} ~/.hermes/plugins/{bundle.id}", f"hermes plugins enable {bundle.id}"], "context_chars": len(context) if context_file.exists() else 0, "skills": skills, - "tools": [t["hermes_name"] for t in tools], "files_named": named, - "unnamed_files": [] if named else bundle.other_files, "omitted": omitted} - - -def _files_note(bundle, output: Path, skills: list[str], context: str) -> bool: - """Write `files.md`, which `register` appends to the section with the installed folder written in, when the session - should be told where the adapter's files are and the section stays within Hermes' limit. Whether it was written.""" - if not names_folder(bundle, skills): - return False - text = folder_sentence(bundle, FOLDER) - if bundle.other_files: - text += "\n\n" + other_files_section(bundle.adapter, bundle.other_files, None) - if len(context) + 2 + len(text) + PATH_ROOM > SECTION_MAX_CHARS: - return False - (output / FILES).write_text(text + "\n") - return True + "tools": [t["hermes_name"] for t in tools], "unnamed_files": bundle.other_files, "omitted": omitted} diff --git a/tests/core/test_convert.py b/tests/core/test_convert.py index 68e88df2..0167cbc4 100644 --- a/tests/core/test_convert.py +++ b/tests/core/test_convert.py @@ -325,32 +325,9 @@ def test_a_reconversion_drops_the_list_of_files_the_adapter_no_longer_has(tmp_pa assert "none is named to the session" in (plugin / "README.md").read_text() -def test_hermes_names_the_adapters_folder_and_files_at_the_end_of_its_section(tmp_path): - out = tmp_path / "installed here" - result = build("hermes", variant(tmp_path, roles=False), out, sys.executable) - assert result["files_named"] is True and result["unnamed_files"] == [] - ctx = StubContext() - load_hermes_module(out).register(ctx) - section = ctx.sections["file-example"] - assert section.startswith("Review the task requirements") - assert f"The files of the `file-example` adapter are in `{out.resolve()}/adapter/`." in section - assert "- `README.md`: File interface example" in section and "- `tools.py`:" in section - assert len(section) <= 4_000 - - -def test_hermes_reports_the_files_when_naming_them_would_pass_its_section_limit(tmp_path): - a = variant(tmp_path, roles=False) - (a / "ADAPTER.md").write_text("Check the result. " * 210) # about 3,800 characters: within 4,000 - result = build("hermes", a, tmp_path / "h", sys.executable) - assert result["files_named"] is False and result["unnamed_files"] == ["README.md", "tools.py"] - ctx = StubContext() - load_hermes_module(tmp_path / "h").register(ctx) - assert "adapter/`" not in ctx.sections["file-example"] - - -@pytest.mark.parametrize("target", ["codex", "pi"]) -def test_a_target_that_cannot_name_its_folder_reports_the_files_the_session_is_not_told_about(tmp_path, target): +@pytest.mark.parametrize("target", ["codex", "pi", "hermes"]) +def test_codex_pi_and_hermes_report_the_files_the_session_is_not_told_about(tmp_path, target): result = build(target, variant(tmp_path, roles=False, context=False), tmp_path / target, sys.executable) assert result["unnamed_files"] == ["README.md", "tools.py"] readme = (Path(result.get("plugin") or result["output"]) / "README.md").read_text() - assert "- Files the session is not told about: README.md, tools.py (under `adapter/`" in readme + assert "- Files the session is not told about: README.md, tools.py (under `adapter/`)" in readme From eef948258774bf9c2463f662db4e1da5cf661418 Mon Sep 17 00:00:00 2001 From: Ruilin Gao Date: Wed, 18 Nov 2026 21:54:38 -0500 Subject: [PATCH 5/6] Name the adapter folder by its constant in the README --- hermit/plugins/claude_plugin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hermit/plugins/claude_plugin.py b/hermit/plugins/claude_plugin.py index 976d5d17..0536a1ff 100644 --- a/hermit/plugins/claude_plugin.py +++ b/hermit/plugins/claude_plugin.py @@ -117,7 +117,7 @@ def _readme(bundle, output: Path, skills: list, roles: dict, omitted: list, hook "(`force-for-plugin`)." if bundle.has_context else "- Context: none", (f"- The adapter's files: under `{ADAPTER_DIR}/`, which a `SessionStart` hook names to the session" + (f", with the {len(bundle.other_files)} files no export connects" if bundle.other_files else "")) - if hooks else "- The adapter's files: under `adapter/`, for its tools; none is named to the session", + if hooks else f"- The adapter's files: under `{ADAPTER_DIR}/`, for its tools; none is named to the session", f"- Skills: {', '.join(skills) or 'none'}", f"- Roles: {', '.join(roles.values()) or 'none'}", f"- Tools: {', '.join(t['name'] for t in bundle.tools) or 'none'}", f"- Left out (--allow-lossy): {', '.join(omitted)}" if omitted else "- Left out: nothing", ""]) From ebdf73ba0de14dd1b9a993f2533491423ff62627 Mon Sep 17 00:00:00 2001 From: Haizhong Zheng Date: Fri, 20 Nov 2026 15:35:47 -0500 Subject: [PATCH 6/6] Parity test: compare the tool-server files with only the tools' entry taken out The test let a whole tool-server file differ between training and `hermit deploy`, so training losing Hermes's skills settings passed, and whether a host's tools come from the workspace or the session's own server was checked only when a file differed. Now every other file must match byte for byte, the tool-server file must match once the tools' entry is removed (OpenCode, Hermes, mini-swe-agent), and each host's tool handoff is asserted on its own. Co-Authored-By: Claude Opus 5.5 --- tests/core/test_deploy.py | 40 +++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/tests/core/test_deploy.py b/tests/core/test_deploy.py index 2872f0cf..e5af8617 100644 --- a/tests/core/test_deploy.py +++ b/tests/core/test_deploy.py @@ -626,6 +626,31 @@ def test_codex_agent_deploys_a_codex_tree_and_writes_the_home(tmp_path): # session's own tool server instead. These files hold the tools' server entry. TOOL_SERVER_FILES = {"codex": {".codex/config.toml"}, "opencode": {"opencode.json"}, "hermes": {".hermes/hermit.config.yaml"}, "mini-swe-agent": {MINI_CONFIG}} +SESSION_SERVED = {"opencode", "hermes", "mini-swe-agent"} + + +def _tool_server_removed(backend: str, text: str, adapter: Path): + """A tool-server file of `hermit deploy`'s workspace, parsed, with the entry that serves the adapter's tools taken + out: what training's file holds when the session's own tool server serves them.""" + import yaml + from hermit.adapter.loader import agent_tools, load_manifest + from hermit.agent.base.mini_swe_agent import tools_section + from hermit.hosts.inputs import server_name + manifest = load_manifest(adapter) + if backend == "opencode": + config = json.loads(text) + del config["mcp"]["servers"][server_name(manifest)] + elif backend == "hermes": + config = yaml.safe_load(text) + assert set(config.pop("mcp_servers")) == {server_name(manifest)} + else: # mini-swe-agent: its environment runs the tools, its prompt names them + config = yaml.safe_load(text) + for key in ("environment_class", "adapter", "audit_log"): + del config["environment"][key] + section = "\n\n" + tools_section(agent_tools(manifest)) + assert section in config["agent"]["system_template"] + config["agent"]["system_template"] = config["agent"]["system_template"].replace(section, "") + return config def _workspace(path: Path) -> dict: @@ -658,14 +683,21 @@ def test_training_deploys_an_adapter_with_tools_as_hermit_deploy_does_but_for_th host, capsys): a = Path(__file__).resolve().parents[2] / "docs" / "_examples" / "file_adapter" train, user, deployed = _deployed_by_both(a, tmp_path, backend, host, capsys) - differ = {k for k in train.keys() | user.keys() if train.get(k) != user.get(k)} - assert differ <= TOOL_SERVER_FILES.get(backend, set()) | {".hermit-deploy.json"} + assert train.keys() == user.keys() + for path in train.keys() - TOOL_SERVER_FILES.get(backend, set()) - {".hermit-deploy.json"}: + assert train[path] == user[path], path records = [json.loads(w[".hermit-deploy.json"].decode()) for w in (train, user)] assert {k for k in records[0].keys() | records[1].keys() if records[0].get(k) != records[1].get(k)} <= \ {"server", "server_name", "audit_log", "environment_class", "tools"} # the tools' entries only + if backend in SESSION_SERVED: # the session's own tool server serves them, the workspace's file does not + assert deployed["harness_tools"] == "file-example" and deployed.get("server_name") is None + import yaml + (path,) = TOOL_SERVER_FILES[backend] + parse = json.loads if path.endswith(".json") else yaml.safe_load + assert parse(train[path].decode()) == _tool_server_removed(backend, user[path].decode(), a) + else: # the workspace's own server, as `hermit deploy` connects it + assert deployed["server_name"] == "file_example" and "harness_tools" not in deployed if backend == "codex": # the same server, its calls approved config = tomllib.loads(train[".codex/config.toml"].decode()) assert config["mcp_servers"]["file_example"].pop("default_tools_approval_mode") == "approve" assert config == tomllib.loads(user[".codex/config.toml"].decode()) - elif differ: # the session's own tool server serves them - assert deployed["harness_tools"] == "file-example" and deployed.get("server_name") is None