feat(hooks): add centralized HookCenter for named hook points and plugin discovery#3541
Closed
aiguozhi123456 wants to merge 1 commit into
Closed
feat(hooks): add centralized HookCenter for named hook points and plugin discovery#3541aiguozhi123456 wants to merge 1 commit into
aiguozhi123456 wants to merge 1 commit into
Conversation
4f1f997 to
0e556dc
Compare
Add a new nanobot/hooks package providing: - HookCenter with register_point/register_handler/emit for named hook points - HookContext (mutable data bag) and HookResult (Literal-typed action) - entry_points-based plugin discovery (nanobot.hooks group) with error isolation - AgentLoop integration: 4 standard hook points with emit in _LoopHook lifecycle - Full cancel semantics: before_iteration and before_execute_tools can cancel the agent run via AgentHookContext.cancel flag, checked by AgentRunner - Handler dedup, warning on bad return types, empty hook_points handling - 59 tests covering core, discovery, integration, cancel, and backward compat
0e556dc to
7d1d433
Compare
This was referenced Apr 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a centralized
HookCenterinfrastructure that lets internal developers declare named hook points and external plugins attach handlers via Pythonentry_points. The system supports full interceptor semantics: handlers can observe, mutate data, short-circuit, or cancel the flow. ExistingAgentHook/CompositeHookremain untouched.Context
nanobot already uses
entry_pointsfor channel plugin discovery (nanobot.channelsgroup) and hasAgentHook/CompositeHookfor agent-lifecycle callbacks. Neither mechanism provides a generic, named hook point system that external plugins can tap into. Contributors who want to inject behavior at arbitrary points must modify core code.Why
Solve
Introduce
nanobot/hooks/— a self-contained package with four components:HookContext/HookResult— A mutable data bag passed between handlers, and aLiteral-typed control-flow signal (continue/short_circuit/cancel).HookCenter— Global singleton registry withregister_point(),register_handler(), andasync emit(). Handlers run in registration order with per-handler error isolation (failing handler is logged and skipped).nanobot.hooksentry_points group. Callable plugins must declare ahook_pointsattribute; dict plugins map{point_name: handler}. Invalid plugins are logged and skipped._init_hook_center()runs on startup, discovers external plugins, and logs registration count.Changes
nanobot/hooks/context.pyHookContextdataclass (mutable dict),HookResultwithLiteral["continue","short_circuit","cancel"]actionnanobot/hooks/types.pyHookHandlerprotocol definition (`async (HookContext) -> HookResultnanobot/hooks/center.pyHookCenterclass: register_point, register_handler, emit, reset; globalget_center()/reset_center()nanobot/hooks/discovery.pydiscover_hook_plugins()andregister_discovered()viaimportlib.metadata.entry_pointsnanobot/hooks/__init__.pyHookCenter,HookContext,HookResult,HookHandlernanobot/agent/loop.py_init_hook_center()called inAgentLoop.__init__docs/hook-center-guide.mdTest
tests/hooks/test_center.pytests/hooks/test_discovery.pytests/hooks/test_integration.pytests/agent/test_hook_composite.pyTotal: 53 tests, all passing. No regressions in existing test suites.