Skip to content
Merged
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,11 @@ 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 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).
- Task directories in Harbor's format as a task set (`data.tasks: <directory>`, `data.rollouts`), read without Harbor
(`hermit/task/directory.py`), with their own verifier script run in the judge's sandbox (`judge: {path:
hermit.task.verify, name: script}`: `/tests`, `/logs/verifier/reward.txt` or `reward.json`, and `feedback.txt`).
Expand Down
7 changes: 7 additions & 0 deletions docs/framework/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,13 +136,20 @@ 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
Hermes refuse. Hooks make every target refuse: no plugin carries them yet, and `deploy --host codex` or
`--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 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:

- **Codex** reads no instruction file and no subagent from a plugin. Its plugin format is Agent Plugins v1: root
Expand Down
61 changes: 40 additions & 21 deletions hermit/hosts/inputs.py
Original file line number Diff line number Diff line change
Expand Up @@ -374,25 +374,59 @@ 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
skills and agents; `hook_types`: the hook types it runs) and the adapter's other files, with paths in the
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"]:
Expand All @@ -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

Expand Down
46 changes: 40 additions & 6 deletions hermit/plugins/claude_plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,48 @@
- 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 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

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)
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
# the installed path is printf's argument, never part of the command; an adapter id has no % or quote
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:
Expand All @@ -35,7 +65,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"},
Expand All @@ -59,23 +89,24 @@ 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:
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}",
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:
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 "
Expand All @@ -84,6 +115,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 ""))
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", ""])
7 changes: 5 additions & 2 deletions hermit/plugins/codex_plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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}
18 changes: 17 additions & 1 deletion hermit/plugins/common.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@
from __future__ import annotations

from dataclasses import dataclass
from functools import cached_property
from pathlib import Path
import json
import shutil

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
Expand Down Expand Up @@ -67,6 +68,13 @@ def server(self) -> str:
def has_context(self) -> bool:
return bool(self.context.strip())

@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/`."""
return other_files(self.adapter, self.manifest, {"agents": self.roles}, self.hooks)


def load(adapter: Path, python: str) -> Bundle:
adapter = adapter.resolve()
Expand All @@ -91,6 +99,14 @@ 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, 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}/`)"


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
Expand Down
Loading
Loading