Skip to content

feat(platforms): register gateway platforms with @platform - #50

Merged
offendingcommit merged 10 commits into
chore/just-to-misefrom
feat/platform-annotation
Nov 13, 2026
Merged

offendingcommit merged 10 commits into
chore/just-to-misefrom
feat/platform-annotation

Conversation

@offendingcommit

@offendingcommit offendingcommit commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Adds an @platform(...) annotation so a Hermes plugin can register a gateway messaging platform through register_plugin with the guarantees tools and hooks already get, instead of calling ctx.register_platform directly.

Plan: docs/plans/2026-11-13-0900-feat-platform-annotation-plan.md.

In flight

  • The annotation and its decoration-time checks
  • Discovery, preflight and registration in register_plugin, rolling back already-registered platforms if the host refuses one, plus receipt fields platforms and replaced_platforms
  • Replacement guard: replacing an existing platform fails loudly unless the operator lists it under plugins.<plugin>.replace_platforms
  • Recording host support and an option-name drift check against the host's PlatformEntry (OpenSpec change, archived)
  • Real-host contract cases at the pinned Hermes revision (6 cases, all executed, not skipped)
  • README, authoring skill reference and AGENTS.md
  • Code review receipt, then ready for review

Decisions from plan review

  • Access-policy options are never optional. trusted_inbound, allowed_users_env, allow_all_env, allow_bots_env, own_policy_env, group_allowed_chats_env and allowlist_suppresses_pairing raise ValueError in optional_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.
  • The guard reads the scope Hermes writes to. Existence comes from snapshot_registration under the plugin manager's scope_key (falling back to current_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:

Check Result
just test 330 run, 26 skipped, EXIT=0
just test-contract-pinned 26 run, EXIT=0
just build, just check-dist, just check-install EXIT=0
openspec validate --specs --strict 1 passed

Falsified: removing the rollback dispose, the scope read, the policy bar, the vars lookup, 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-validate exits 1 whenever no OpenSpec change is active, which has been true on main since the four changes were archived. CI does not run it.

https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY

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
@offendingcommit
offendingcommit changed the base branch from main to chore/just-to-mise November 13, 2026 16:05
@offendingcommit
offendingcommit marked this pull request as ready for review November 13, 2026 16:06
@offendingcommit
offendingcommit merged commit fef698c into main Nov 13, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant