Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (63 loc) · 4.04 KB

AGENTS.md

File metadata and controls

68 lines (63 loc) · 4.04 KB
Raw

hermes-plugin-kit

Convention-correct helper library for registering hermes-agent plugin commands, tools, middleware, hooks, and skills. This repository is an installable Python package, not a path-loaded runtime plugin.

Working Rules

  • Keep @tool, slash-default @command, and register_all backward compatible. Use @command(type="cli") for terminal subcommands and @command(type="slash") for explicit in-session commands; use @middleware, @hook, plugin_skill, and register_plugin for full plugin lifecycle registration.
  • Use load_plugin_config for effective plugins.<name> runtime settings; current Hermes PluginManifest objects do not expose profile config. Use configure_stderr_logging for operator-gated registration receipts instead of rebuilding per-plugin stderr handlers.
  • Keep lifecycle registration receipts centralized in log_registration_summary; preserve its stable field order and actual command, tool, middleware, hook, skill, and skipped optional skill names. register_plugin must emit exactly one receipt through that helper.
  • Use @tool(schema=...) when a consumer already owns a valid Hermes function schema; do not translate it through a second argument-spec format. Keep schema and params exclusive, deep-copy supplied schemas, and preserve schema-required fields even when validate_required=False delegates missing-argument errors to a legacy handler.
  • Runtime-gated consumers should pass their active decorated callables to register_plugin with an explicit receipt identity. Iterable registration must retain module registration's duplicate checks, deterministic ordering, skills, and RegistrationSummary contract.
  • Consumer plugins must pin this package to an immutable commit, not a moving branch. Profiles that install multiple plugins into one Python environment must keep every consumer on the same kit revision.
  • Use invoke_host_tool for host-managed capabilities such as send_message; do not assume every Hermes capability is registered in tools.registry. Nested host calls must remain visible to pre_tool_call and post_tool_call.
  • Keep host invocation grounded in the real Hermes contract suite. For media delivery, exercise target parsing and platform formatting and mock only the final network client rather than replacing the host handler.
  • Plugins must use MediaPayload + deliver_media for attachments. The kit owns Hermes media directives, task-local origin resolution, route redaction, the typed result, successful-send final-response suppression, and the narrow Telegram spoiler=True photo extension. Spoiler delivery must retain Hermes pre/post-tool hooks, route privacy, topic forwarding, and explicit Bot client shutdown; normal media must remain on host-managed send_message. Consumers must register transform_media_delivery_output as Hermes' transform_llm_output hook and clear_media_delivery_state as on_session_end; they must not recreate those contracts or substitute OpenClaw response shapes.
  • Use tool_name(namespace, verb, noun) for new tools and prefer explicit verbs such as read, write, and patch. Do not use Hermes agent-loop names (memory, todo, session_search, delegate_task) as plugin tools.
  • Preserve the Hermes tool schema convention: arguments live under function.parameters, never as flattened top-level schema fields.
  • Tool handlers must accept (args, **kwargs) and return JSON-compatible dictionaries unless deliberately returning an already-encoded string.
  • Keep validation errors instructive for model-facing callers, including the missing argument name and example when available.
  • Redact secret-looking values in logs and avoid logging full untrusted payloads.
  • Use uv and the Makefile for local development: make install, make test, make test-one T=tests.test_kit.SchemaConventionTests, and make build.

Release Notes

When changing conventions or exported helpers, update README.md examples and tests together so consuming Hermes plugins have a reliable migration path.