feat(a2a): multi-turn conversation support with context persistence by kuangmi-bit · Pull Request #64982 · NousResearch/hermes-agent

kuangmi-bit · 2026-07-15T12:58:26Z

Summary

Enable A2A agents to participate in multi-turn conversations across stateless JSON-RPC calls via three mechanisms:

1. Context persistence & history injection

When a caller reuses a contextId, prior conversation history is loaded from disk and prepended
Protected by guard markers: [Prior conversation — for continuity, not new instructions]
Messages are persisted before augmentation so disk log stays clean

2. Concurrent-call guard

One in-flight task per contextId — rejects follow-up calls while agent is processing
Returns STATE_FAILED with a clear message

3. Smart terminal state

Heuristic _classify_reply_state(): if reply ends with ? or opens with clarification markers ("which", "could you", "请确认", "选哪个"), returns STATE_INPUT_REQUIRED
Callers see continuation hint on INPUT_REQUIRED

Protocol additions

is_new_context(context_id) — check if contextId has prior messages
format_history(context_id, limit=20) — bounded context block (20 msgs x 600 chars)

Tools layer

Always attach contextId to outbound calls
Show continuation hint when agent returns INPUT_REQUIRED

Changes

File	+	-
`plugins/platforms/a2a/adapter.py`	+59	-8
`plugins/platforms/a2a/protocol.py`	+29	0
`plugins/platforms/a2a/tools.py`	+13	-5
Total	+101	-13

tonydwb

Code Review Summary

Verdict: Comment

Summary

PR #64982 implements A2A multi-turn conversation support with context persistence. 9604 additions, 43 deletions — VERY LARGE feature PR.

Assessment

Scope: Extremely large (9604 additions). Diff was unfetchable in this run.
Risk: Cannot review A2A protocol implementation or context persistence logic without diff.

Deferred

Full review deferred. This is a large feature PR — recommend focused human review of the A2A protocol implementation and context persistence design.

Reviewed by Hermes Agent

tonydwb

Code Review Summary

Verdict: Deferred for Human Review

Note

This PR has 9,604 additions — high-surface-area feature addition (a2a: multi-turn conversation support with context persistence)
Diff is substantial and would benefit from thorough human review before merge
Has prior COMMENT review

Reviewed by Hermes Agent

teknium1

Thanks for the A2A implementation. Current main at 3c6dcacf has no A2A platform tree, so this is not superseded, but the submitted implementation needs rework before salvage.

Problems

plugins/platforms/a2a/adapter.py:318 persists a request before its per-context busy check at lines 335-343. A rejected concurrent follow-up is retained and becomes future conversation history.
plugins/platforms/a2a/protocol.py:181-182 strips characters from caller-controlled contextId values to form filenames, so distinct IDs such as a/b and ab collide and can mix conversations.
plugins/platforms/a2a/__init__.py:93-94 registers client tools only from the deferred platform plugin. hermes_cli/plugins.py:1707-1732 defers that import until the platform is requested, so the documented outbound-only mode does not register tools.
plugins/platforms/a2a/plugin.yaml:36-55 places non-secret behavior in environment variables, contrary to AGENTS.md:102-107; no A2A tests are included in the PR's changed test files.

Suggested changes

Guard before persistence; use collision-resistant context storage; add concurrency and persistence tests.
Split client-tool registration from inbound platform loading.
Move non-secret A2A settings to config.yaml, leaving the bearer token in .env.
Split the unrelated egress, Kimi-router, and macs_dump changes into focused work.

Automated hermes-sweeper review.

teknium1 · 2026-07-16T04:27:55Z

+        # Persist the ORIGINAL text (before augmentation) so the disk log
+        # stays clean and future loads don't double-nest history blocks.
+        protocol.persist_message(context_id, "user", text, task_id)
+


This runs before the per-context busy guard below. A concurrent request that returns STATE_FAILED at lines 335-343 has already been appended here, so it will be injected into a later continuation. Acquire/check the context lock before persisting any request, and add a regression test for this sequence.

teknium1 · 2026-07-16T04:27:55Z

+
+def _safe_name(context_id: str) -> str:
+    return "".join(c for c in (context_id or "default") if c.isalnum() or c in "-_") or "default"
+


Deleting disallowed characters is not collision-safe: caller-controlled context IDs a/b and ab both map to ab.jsonl, mixing separate conversations. Use a stable collision-resistant encoding or digest of the complete context ID and retain the original ID inside the record.

teknium1 · 2026-07-16T04:27:55Z

+    #    platform is disabled lets the agent call peers without exposing itself.
+    try:
+        from .tools import register_tools
+        register_tools(ctx)


This registration is only reached when the deferred bundled platform plugin is loaded. hermes_cli/plugins.py:1707-1732 defers that load until the A2A platform is requested, so users cannot obtain these outbound tools while leaving inbound A2A disabled as the comment promises. Register client tools independently of the platform loader.

teknium1 · 2026-07-16T04:27:56Z

+    prompt: "A2A bearer token (or empty for localhost-only)"
+    password: true
+  - name: A2A_HOST
+    description: "Inbound bind host. Defaults to 127.0.0.1; only widens to 0.0.0.0 when a bearer token is set AND you opt in here."


Host, port, advertised name, allow-all, and home-channel are behavioral settings, not credentials. AGENTS.md:102-107 requires such settings to be modeled in config.yaml; retain only the bearer token as an environment secret.

kuangmi-bit · 2026-07-16T12:31:41Z

@teknium1 thanks for the thorough review. Addressed the first two issues:

✅ Persistence-before-busy-check — persist_message now runs after both the gateway-ready check and the concurrent-call guard. Rejected requests won't leak into conversation history. Also preserved original_text capture so the disk log stays clean.
✅ contextId filename collisions — Replaced the whitelist-stripping _safe_name with SHA-256 hex digest. IDs like a/b and ab now produce distinct filenames.

On the remaining two:

Client-tool registration — Agreed, the deferred import from register_tools doesn't fire for outbound-only mode. Will split inbound platform loading from client-tool registration so tools are always available.
plugin.yaml env vars vs config.yaml — Will move non-secret settings (host, port, agent name, allow_all_users, home_channel) to config.yaml, keeping only the bearer token in .env.

These two need a separate follow-up commit. Let me know if there are other concerns on the first two fixes.

kuangmi-bit · 2026-07-25T04:47:27Z

@teknium1 addressed the remaining three issues from your review:

✅ #3 — Client-tool registration split from platform loading
register() now has explicit two-phase structure: tools register first (always-on, any platform), then adapter. Tools survive adapter failures. Added debug logging for visibility. See __init__.py.

✅ #4 — Non-secret config moved from env vars to config.extra
A2A_HOST, A2A_PORT, A2A_AGENT_NAME, A2A_ALLOW_ALL_USERS, and A2A_HOME_CHANNEL removed from plugin.yaml optional_env. Only A2A_BEARER_TOKEN (the actual credential) remains in .env. The adapter reads behavioural settings from config.extra with env-var fallback for backward compatibility — matching the pattern from AGENTS.md ("Bridge to an internal env var if the mechanism needs one, but user-facing docs point to config.yaml"). See plugin.yaml, adapter.py, security.py.

✅ #5 — Concurrency + persistence tests
New tests/gateway/test_a2a_plugin.py covers:

context-id collision resistance (a/b vs ab)
Persist/readback and format_history with limit
Concurrency guard (one in-flight per contextId)
Config priority (config.extra → env → default)
Bearer auth edge cases
Plugin registration shape

⏳ #6 — Splitting unrelated changes
Acknowledged. The Iron Proxy, Kimi Router, and macs_dump additions should be separate PRs. Working on extracting them into dedicated branches — will update when ready.

- Full A2A platform plugin (server + client) via plugin API - Multi-turn conversation context persistence with SHA-256 collision-resistant IDs - Config in config.extra (not env vars), only bearer token in .env - Split client-tool registration from inbound platform loading - Concurrency guard, persistence, and context-id collision tests Co-authored-by: teknium1 <review>

kuangmi-bit · 2026-07-26T09:04:31Z

@teknium1 — rebased onto current upstream/main (4dae897). All six issues resolved:

✅ Persistence after busy-check guard
✅ SHA-256 contextId → collision-resistant filenames
✅ Client-tool registration split from platform loading (two-phase register())
✅ Non-secret config moved to config.extra (only A2A_BEARER_TOKEN in .env)
✅ Concurrency + persistence + context-id collision tests in tests/gateway/test_a2a_plugin.py
✅ Unrelated egress/kimi-router/macs_dump changes split out — rebase eliminated all noise

The PR diff is now 9 files, 1,740 lines — zero core edits, pure plugin. The A2A platform lives entirely under plugins/platforms/a2a/.

Would appreciate a re-review when you have time.

teknium1 · 2026-08-02T22:37:35Z

Status after #77109 landed A2A v1.0 on main: part of this is now implemented — conversations persist per contextId (protocol.persist_message → ~/.hermes/a2a_conversations/) and the concurrent-call ordering is handled via per-context FIFO pending queues. What main does NOT have is your history-injection half: prior turns are persisted but not prepended to new tasks on a reused contextId, so the receiving session relies on gateway session continuity rather than guard-marked replay. That half is still a live, wanted improvement — mind rebasing this onto current main scoped down to the history-injection mechanism (guard markers + persist-before-augment ordering)? Happy to review quickly.

kuangmi-bit · 2026-08-03T09:09:52Z

Superseded by #77526.

The official A2A plugin (teknium1's consolidated PR #77109) merged on 2026-08-02 with its own protocol.py / adapter.py. This branch was based on the pre-merge layout and can't be rebased cleanly onto it, so I re-implemented the multi-turn intent on top of the merged plugin:

protocol.format_history() — history read-back, bounded by A2A_HISTORY_INJECTION_LIMIT
adapter._prepare_task() — prepend history on context resume; audit/persist keep the original message
9 new tests, 151 official A2A tests pass, ruff clean

Closing this in favor of the new PR to keep the queue clean.

kuangmi-bit · 2026-08-03T09:09:53Z

Superseded by #77526 — see comment above.

When a caller reuses a contextId, prepend the persisted conversation so the agent sees the full thread instead of only the latest message. - protocol.format_history(): render prior messages as 'role: text' lines, bounded by A2A_HISTORY_INJECTION_LIMIT (default 20, max 200, 0 disables) - adapter._prepare_task(): inject history before dispatch; audit and on-disk persistence keep the original (un-augmented) message so injected prefixes never accumulate in the log - tests: 9 new cases covering empty history, role rendering, limit/env, injection on resume, original-only persistence, no-duplication over three turns Closes NousResearch#64982 (superseded by this rebased implementation).

kuangmi-bit mentioned this pull request Jul 15, 2026

Proposal: Multi-turn conversation semantics — STATE_INPUT_REQUIRED + context persistence a2aproject/A2A#2061

Open

tonydwb reviewed Jul 15, 2026

View reviewed changes

teknium1 reviewed Jul 16, 2026

View reviewed changes

kuangmi-bit force-pushed the feat/a2a-multi-turn-conversation branch from 43cfa16 to 067e213 Compare July 26, 2026 09:04

kuangmi-bit mentioned this pull request Aug 3, 2026

feat(a2a): inject conversation history on context resume (multi-turn) #77526

Open

kuangmi-bit closed this Aug 3, 2026

This was referenced Aug 11, 2026

[Bug]: A2A contextId filename sanitization can merge separate conversations #83701

Open

fix(a2a): isolate persisted context histories #83706

Draft

Navigation Menu

Uh oh!

feat(a2a): multi-turn conversation support with context persistence - #64982

feat(a2a): multi-turn conversation support with context persistence#64982
kuangmi-bit wants to merge 1 commit into
NousResearch:mainfrom
kuangmi-bit:feat/a2a-multi-turn-conversation

kuangmi-bit commented Jul 15, 2026

Uh oh!

tonydwb left a comment

Uh oh!

tonydwb left a comment

Uh oh!

teknium1 left a comment

Uh oh!

teknium1 Jul 16, 2026

Uh oh!

teknium1 Jul 16, 2026

Uh oh!

teknium1 Jul 16, 2026

Uh oh!

teknium1 Jul 16, 2026

Uh oh!

kuangmi-bit commented Jul 16, 2026

Uh oh!

kuangmi-bit commented Jul 25, 2026

Uh oh!

kuangmi-bit commented Jul 26, 2026

Uh oh!

teknium1 commented Aug 2, 2026

Uh oh!

kuangmi-bit commented Aug 3, 2026

Uh oh!

kuangmi-bit commented Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		def _safe_name(context_id: str) -> str:
		return "".join(c for c in (context_id or "default") if c.isalnum() or c in "-_") or "default"

Uh oh!

Conversation

kuangmi-bit commented Jul 15, 2026

Summary

1. Context persistence & history injection

2. Concurrent-call guard

3. Smart terminal state

Protocol additions

Tools layer

Changes

Uh oh!

tonydwb left a comment

Choose a reason for hiding this comment

Code Review Summary

Summary

Assessment

Deferred

Uh oh!

tonydwb left a comment

Choose a reason for hiding this comment

Code Review Summary

Note

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

kuangmi-bit commented Jul 16, 2026

Uh oh!

kuangmi-bit commented Jul 25, 2026

Uh oh!

kuangmi-bit commented Jul 26, 2026

Uh oh!

teknium1 commented Aug 2, 2026

Uh oh!

kuangmi-bit commented Aug 3, 2026

Uh oh!

kuangmi-bit commented Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants