docs(plugins): fold middleware, API-hook, and allow_tool_override coverage into the canonical author guide by webdevtodayjason · Pull Request #58538 · NousResearch/hermes-agent

webdevtodayjason · 2026-07-04T22:39:39Z

What

Reworked per the sweeper review: instead of adding a parallel guide outside the published navigation, this PR now folds the genuinely unique material from the original docs/plugins.md into the canonical author guide, website/docs/developer-guide/plugins/index.md, and deletes the parallel file.

What moved (71 added lines, each claim re-verified against current main):

Middleware registration: ctx.register_middleware with all four VALID_MIDDLEWARE kinds (tool_request, tool_execution, llm_request, llm_execution), their payload contracts, chaining with original_* and single-use next_call, error isolation, trace fields, and middleware_schema_version (hermes_cli/middleware.py:20-34, 120-162, 262-300).
Per-API-call request hooks: pre_api_request / post_api_request / api_request_error, their per-call vs per-turn semantics relative to pre_llm_call/post_llm_call, sanitized and size-capped payload views, and correlation fields (agent/conversation_loop.py:1242-1289, run_agent.py:2354-2577).
allow_tool_override: the per-plugin operator grant in plugins.entries., PluginToolOverrideError, the bundled exemption, fail-closed config behavior, and the hermes plugins enable prompt plus tri-state flags (hermes_cli/plugins.py:419-472, tools/registry.py:402-424). This also fixes pre-existing guide text implying override=True alone suffices for non-bundled plugins, which is no longer true on main.

Deliberately not migrated: everything duplicating the canonical guide or the hooks reference, coverage of a hook not present in VALID_HOOKS on main, and a stale deep-copy claim (softened to match _safe_copy's shallow fallback, hermes_cli/middleware.py:58-74).

Testing

Docs-only change. git diff --check clean, internal anchors resolve, no duplicate headings; all cited file:line references verified on the rebased branch (current main).

Platforms tested

Not applicable (documentation).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PnMCvi2vXqfs996AjVeF2F

teknium1

Thanks for consolidating the plugin surface; the middleware material covers a real current API (hermes_cli/middleware.py:29-34).

Problems

docs/plugins.md is not part of the published documentation navigation. The existing author guide is website/docs/developer-guide/plugins/index.md (website/sidebars.ts:740-753), and current-main git grep finds no reference to docs/plugins.md. This would create a parallel, undiscoverable guide while duplicating material already present in the canonical guide (website/docs/developer-guide/plugins/index.md:8-36).

Suggested changes

Salvage the unique middleware, API-hook, and allow_tool_override coverage into website/docs/developer-guide/plugins/index.md and the hooks reference as appropriate, then revalidate retained contracts against current main.

Automated hermes-sweeper review.

teknium1 · 2026-07-15T17:30:26Z

@@ -0,0 +1,633 @@
+# Hermes Plugin Author Guide


Please move the unique material into the published plugin guide instead of adding this standalone file. website/sidebars.ts:740-753 exposes website/docs/developer-guide/plugins/index.md, while current-main git grep finds no incoming reference to docs/plugins.md; this guide would not be discoverable from the documentation site.

webdevtodayjason · 2026-07-15T18:15:01Z

Reworked in 26bf4f1ce exactly along the suggested salvage line. docs/plugins.md is deleted; the unique middleware, per-API-call hook, and allow_tool_override coverage now lives in website/docs/developer-guide/plugins/index.md, inserted into the existing structure rather than restructuring it. Every migrated claim was re-verified against current main with file:line citations in the PR description, and the pass also fixed pre-existing guide text that implied override=True alone suffices for non-bundled plugins. Material that duplicated the canonical guide or the hooks reference was dropped rather than moved, including coverage of a hook that is not in VALID_HOOKS on main.

The plugin system's authoring contract currently lives only in code comments (VALID_HOOKS block, PluginContext docstrings, middleware.py). With the plugin-interface expansion underway, third-party authors need a single reference. This adds docs/plugins.md covering: - Quick start (manifest + register(ctx), enable, verify) - All four discovery sources, name-collision precedence, path-derived keys - plugin.yaml field reference and the five plugin kinds with their kind/source-aware loading rules (auto-load, deferred platform, opt-in) - plugins.enabled/disabled/entries config semantics - Full PluginContext surface: tools (incl. the allow_tool_override trust gate), slash + CLI commands, all 23 hooks with per-hook return contracts, the 4 middleware kinds with chaining/next_call semantics, backend provider registries and their config selectors, platforms, Slack actions, auxiliary tasks, skills, ctx.llm/inject_message/ dispatch_tool/profile_name - State & concurrency (plugins/plugin_utils primitives) - Distribution via `hermes plugins install` (all URL forms, after-install.md, manifest_version) - Debugging (HERMES_PLUGINS_DEBUG) and common gotchas - "Converting a waiting PR into a plugin" mapping table Every claim was cross-checked against hermes_cli/plugins.py, hermes_cli/middleware.py, tools/registry.py, and shipped plugins (spotify, google_meet, disk-cleanup); hook/middleware/method names in the doc are verified to exist by script. The classify_api_error entry is marked pending PR NousResearch#58524. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWMcB7RPSYUpsXDfBgwjzM

…aces Per maintainer feedback on the interface-ideas thread: a context-engine plugin already owns the full compression policy (should_compress / compress / preflight on the ContextEngine ABC), and a ProviderProfile already owns its model catalog (models_url / fetch_models / fallback_models). Call both out explicitly — the queued PRs that patch core for these (NousResearch#58418, NousResearch#58444, NousResearch#58453) suggest contributors don't find the existing surface, which is the failure mode this guide exists to fix. Also adds both rows to the PR-shape → seam mapping table. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWMcB7RPSYUpsXDfBgwjzM

Per review, docs/plugins.md was a parallel guide outside the published navigation. Its genuinely unique material moves into website/docs/developer-guide/plugins/index.md: the middleware registration surface (all four VALID_MIDDLEWARE kinds with contracts and chaining rules), the per-API-call request hooks, and the allow_tool_override operator grant (which also fixes pre-existing text implying override=True alone suffices for non-bundled plugins). Every migrated claim was re-verified against current main; stale material (deep-copy claim, approval-surface coverage, a hook that is not in VALID_HOOKS on main) was corrected or dropped rather than copied. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PnMCvi2vXqfs996AjVeF2F

webdevtodayjason · 2026-08-13T00:27:35Z

Guide content landed in #82012, closing.

alt-glitch added type/docs Documentation improvements comp/plugins Plugin system and bundled plugins P3 Low — cosmetic, nice to have labels Jul 4, 2026

webdevtodayjason mentioned this pull request Jul 4, 2026

feat(plugins): redaction pattern registry — vendor token formats as plugins #58550

Closed

webdevtodayjason mentioned this pull request Jul 14, 2026

Tracking: Plugin Interface Expansion — community ideas, July 2026 #64182

Closed

26 tasks

teknium1 reviewed Jul 15, 2026

View reviewed changes

webdevtodayjason force-pushed the docs/plugin-authoring-guide branch from ea3b0a5 to 26bf4f1 Compare July 15, 2026 18:14

webdevtodayjason changed the title ~~docs: plugin author guide — the full authoring surface in one reference~~ docs(plugins): fold middleware, API-hook, and allow_tool_override coverage into the canonical author guide Jul 15, 2026

teknium1 added the sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users label Jul 15, 2026

This was referenced Jul 16, 2026

feat(plugins): additive-only redaction pattern registry — ctx.register_redaction_patterns() #65449

Closed

feat(plugins): developer tooling — scaffold, Plugin Doctor, standalone test harness #64230

Closed

GottZ mentioned this pull request Jul 30, 2026

feat(plugins): expose API server route extensions #38645

Open

4 tasks

webdevtodayjason and others added 3 commits August 3, 2026 09:40

webdevtodayjason force-pushed the docs/plugin-authoring-guide branch from 26bf4f1 to 3f952fc Compare August 3, 2026 14:41

GottZ mentioned this pull request Aug 3, 2026

feat(plugins): propagate session context to plugin hooks #65188

Closed

webdevtodayjason mentioned this pull request Aug 8, 2026

feat(plugins): add runtime-backed Plugin Doctor #82012

Merged

webdevtodayjason closed this Aug 13, 2026

Navigation Menu

Uh oh!

docs(plugins): fold middleware, API-hook, and allow_tool_override coverage into the canonical author guide - #58538

docs(plugins): fold middleware, API-hook, and allow_tool_override coverage into the canonical author guide#58538
webdevtodayjason wants to merge 3 commits into
NousResearch:mainfrom
webdevtodayjason:docs/plugin-authoring-guide

webdevtodayjason commented Jul 4, 2026 •

edited

Loading

Uh oh!

teknium1 left a comment

Uh oh!

teknium1 Jul 15, 2026

Uh oh!

webdevtodayjason commented Jul 15, 2026

Uh oh!

webdevtodayjason commented Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

webdevtodayjason commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Testing

Platforms tested

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

webdevtodayjason commented Jul 15, 2026

Uh oh!

webdevtodayjason commented Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

webdevtodayjason commented Jul 4, 2026 •

edited

Loading