Repository navigation
feat(platforms): register gateway platforms with @platform - #50
Merged
Merged
Conversation
Plan for registering Hermes gateway platforms through the kit, with preflight before any registration, a fail-loud replacement guard behind an operator config override, receipt fields, and an option-name drift check. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
Marks a BasePlatformAdapter subclass as a gateway platform without wrapping it, so the class itself is the adapter factory Hermes calls. Decoration validates what needs no host: the name is already in the lowercase form Hermes keys on, the label is non-empty, check and validate are callable, option names are identifiers that neither duplicate a named argument nor claim a host-owned field, and every optional option was actually passed. Annotating never imports Hermes. Registration through register_plugin follows in the next commits. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
register_plugin now discovers annotated adapter classes, from a module or an iterable, and registers them through ctx.register_platform. A class's spec is read from its own namespace, so an unannotated subclass of an annotated adapter is not mistaken for a second declaration. Every platform check runs before the first registration: duplicate names, the host's platform module and base adapter (a host without them refuses registration), the BasePlatformAdapter subclass check, option names against the host's own PlatformEntry fields (unknown ones fail unless the plugin marked them optional, in which case they are dropped and logged by name), and trusted_inbound on a platform Hermes ships. A host refusal only appears once register_platform returns None, so platforms register first and a refusal disposes the handles this call already holds before raising. That keeps "a bad declaration registers nothing" true for the refusal case as well. The receipt appends platforms and replaced_platforms after the existing fields; every earlier field keeps its position. The recording host gains register_platform, returning a disposable handle, with a refuse_platforms knob for the refusal path. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
…erator override The platform registry is last-writer-wins and logs a replacement at INFO, so a plugin naming `telegram` would silently swap out the real adapter. Preflight now refuses any platform name that Hermes ships or that is already registered, unless the operator lists it under plugins.<plugin>.replace_platforms. The error names the platform, its current owner where the registry exposes one, and that exact key. A permitted replacement is named in the receipt's replaced_platforms. Existence is read without resolving deferred loaders, which would import a bundled platform's SDK: core_ships_platform, is_registered, and snapshot_registration in the registry's current scope. A host missing any of these fails closed and names every missing read. A reload of this plugin's own platform (the existing entry's plugin_name is this plugin's manifest name) registers without the override, but only for names Hermes does not ship: a core platform needs the override whoever registered it last. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
…tformEntry register_platform takes its options as **entry_kwargs, so replaying a recorded call against its signature accepts any option name: a Hermes release that drops or renames a PlatformEntry field would replay clean while the plugin fails at registration. check_against_host gains an optional platform_entry_fields keyword and reports each recorded option the host's PlatformEntry lacks as drift naming the option. ResolvedHost.platform_entry_fields() reads those names from the checkout. A recorded platform call replayed without them is reported unchecked, never clean, and the report still lists any signature drift it did find. Callers that record no platform call see no change. The OpenSpec change check-platform-option-drift adds both scenarios to the "Recorded calls replay against the real host signatures" requirement. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
Registers a platform through the real PluginManager and PlatformRegistry at the deployed revision, and checks that a core name without an override, an option the pinned PlatformEntry lacks, and a host refusal all leave the registry exactly as it was. The refusal case disposes earlier handles through PluginRegistration, and it fails when that dispose is removed. A binding case replays every host symbol the preflight reads. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
…override README gains a gateway platforms section: the annotation, option checks against the host's PlatformEntry, optional options, the operator-only plugins.<name>.replace_platforms override, rollback on host refusal, and the two new receipt fields. The skill reference, its harness snippet and AGENTS.md teach the same contract, and the public-surface guard treats BasePlatformAdapter as host-owned. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
The harness now checks recorded platform options against the host's PlatformEntry, so the change is folded into the plugin-test-harness spec. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
…s write scope Two owner decisions from review: Access-policy PlatformEntry options can no longer be optional. Dropping one on an older Hermes would silently change who can reach the agent: losing own_policy_env skips the startup refusal of an open policy, and losing allowlist_suppresses_pairing hands strangers pairing codes. Hermes tags no field as policy, so the kit lists the seven names. The replacement guard now reads existence in the scope Hermes' register_platform writes to, its plugin manager's scope_key, falling back to current_scope_key() without a manager, plus the global scope. In a multiplexer HERMES_HOME's scope can differ, and the guard then refused a free name or missed a real owner. is_registered is no longer read: it always uses current_scope_key(). A real-host case reproduces the divergence at the pin. Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
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.
Adds an
@platform(...)annotation so a Hermes plugin can register a gateway messaging platform throughregister_pluginwith the guarantees tools and hooks already get, instead of callingctx.register_platformdirectly.Plan:
docs/plans/2026-11-13-0900-feat-platform-annotation-plan.md.In flight
register_plugin, rolling back already-registered platforms if the host refuses one, plus receipt fieldsplatformsandreplaced_platformsplugins.<plugin>.replace_platformsPlatformEntry(OpenSpec change, archived)Decisions from plan review
trusted_inbound,allowed_users_env,allow_all_env,allow_bots_env,own_policy_env,group_allowed_chats_envandallowlist_suppresses_pairingraiseValueErrorinoptional_options. Losing one on an older host would silently change who can reach the agent. Hermes tags no field as policy, so the kit keeps the list.snapshot_registrationunder the plugin manager'sscope_key(falling back tocurrent_scope_key()) plus the global scope. In a multiplexer,HERMES_HOME's scope can differ; a real-host case reproduces that at the pin. The manager attribute is private, and the contract suite pins it.Verification
Each command's own exit status was captured:
just testjust test-contract-pinnedjust build,just check-dist,just check-installopenspec validate --specs --strictFalsified: removing the rollback
dispose, the scope read, the policy bar, thevarslookup, the core-reload carve-out, the refusal and the drift append each fails only its own tests.Known gap, not from this branch:
just spec-validateexits 1 whenever no OpenSpec change is active, which has been true onmainsince the four changes were archived. CI does not run it.https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY