feat(a2a): add secure peer protocol integration

[ComicBit]

What does this PR do?

Adds an opt-in, authenticated Hermes-to-Hermes integration for the official Agent2Agent Protocol 1.0. A Hermes instance can expose a task-oriented A2A endpoint and contact named peers through hermes a2a, including card discovery, send/get/list/cancel, and explicit context continuation.

The integration follows Hermes' narrow-waist model: the agent uses a plugin-local CLI skill instead of gaining a permanent model tool, and the official SDK is isolated behind the optional a2a extra.

Why / integration gap

Hermes' existing platform path is designed around messaging delivery. A standards-compliant A2A endpoint additionally needs synchronous request/response dispatch, protocol task ownership and cancellation, and a host-enforced tool boundary. This PR adds those generic gateway contracts and consumes them from the A2A platform rather than introducing an A2A-specific bypass in the agent core.

Type of Change

• New feature
• Security hardening
• Documentation update
• Tests
• Plugin-local skill

Changes Made

• Add an official a2a-sdk==1.1.0 server/client plugin with Agent Card and JSON-RPC task lifecycle support.
• Add profile-scoped named peers, inbound principals, dedicated credentials, and context state through hermes a2a.
• Add generic platform request dispatch, canonical session interruption, bounded two-phase teardown, and platform-scoped agent tool policies.
• Package an A2A-specific CLI skill and user/CLI documentation.

Security and compatibility

• The listener binds to loopback; remote ingress requires a configured HTTPS URL through a private overlay or trusted reverse proxy.
• Inbound principals and outbound peers use dedicated credentials; API_SERVER_KEY and arbitrary request URLs are rejected.
• Credentials stay in a profile-local, permission-restricted store rather than config or environment files.
• A2A disables gateway slash commands and inbound local context-reference expansion.
• The platform uses an exact explicit tool allowlist; the default configured policy preserves existing platform behavior.
• Streaming, push notifications, and extended cards are not exposed.

Validation

• 161 focused A2A and lifecycle tests passed locally.
• 704 gateway/plugin/tool-policy tests passed locally; 1 skipped.
• Official client/server interoperability passed locally.
• Wheel/sdist packaging, lockfile, Ruff, compilation, and diff checks passed.
• The exact pushed SHA also passed 161 focused tests and official interoperability on Linux/Norbert.

Notes for reviewers

This is intentionally a draft while it is rebased onto current main; the branch base is 67 commits behind and overlaps recent upstream edits in four files.

[alt-glitch]

This was generated by AI during triage.

Related: #41711 (core-team consolidated A2A plugin, closes #514, authoritative live carrier -- verified plugins/platforms/a2a/ is not yet on main), #46241 (competing A2A server adapter), #514 (umbrella). This is a competing A2A implementation in a saturated cluster; flagging for maintainer to pick between this and the core-team consolidation #41711 rather than merging in parallel.

[teknium1]

Thanks for the substantial security and lifecycle work. The feature is not present on current main, but it overlaps active A2A implementations that need a maintainer-led consolidation.

Problems

• pyproject.toml:220 adds a2a-sdk[http-server,sqlite]==1.1.0. AGENTS.md:559-575 requires bounded PyPI ranges for non-CI dependencies.
• This PR changes 12 core files, including gateway/run.py, model_tools.py, run_agent.py, and hermes_cli/main.py, alongside the plugin. Current open A2A work #41711 and #46241 overlaps this transport and gateway-contract surface; #56434 also identifies this PR as a competing implementation.

Suggested changes

• Use the repository's bounded dependency form and regenerate the lockfile.
• Reconcile the generic gateway-contract work with the implementation maintainers select, then carry the credential-bound identity/task-storage pieces as focused follow-ups rather than merging parallel A2A stacks.

Automated hermes-sweeper review.

[ComicBit]

Addressed the dependency-policy review thread in a6dff21.

a2a-sdk[http-server,sqlite] now uses the required bounded runtime range >=1.1.0,<2, and uv.lock was regenerated.

Validation: 29 focused A2A tests and 12 packaging-metadata tests passed.

[ComicBit]

Follow-up: merged current upstream main in 17bb681 and resolved the sole conflict by keeping the new centralized port-binding policy in gateway.config while adding A2A to that shared allowlist.

Post-merge validation: 50 A2A, multiplex-profile, and packaging tests passed.

[teknium1]

Thanks @ComicBit — the SDK-isolated, CLI-skill-first architecture here was a thoughtful application of the narrow-waist model. A2A support has now landed on main via #77109 taking the other fork in the road: a stdlib platform plugin (plugins/platforms/a2a/) with zero SDK dependency, v1.0-conformant against the official a2a-sdk, with client tools in an opt-in toolset. That supersedes this integration path, so closing with credit. Your peer-management UX ideas (named peers, explicit context continuation via hermes a2a) are worth revisiting as a follow-up against the landed plugin if you're interested.