[Feature]: Emit Hermes ACP session provenance metadata for compression-driven session rotation

Suggested labels: enhancement, comp/acp, comp/agent, P2

Problem or Use Case

Hermes can rotate its internal AIAgent.session_id when context compression creates a continuation session, but ACP clients do not currently get a reliable, structured signal that the logical conversation's internal head moved.

Today, an ACP client mostly sees the stable editor-facing ACP session_id and normal session/update frames. When compression happens, Hermes' storage layer can represent the split using sessions.parent_session_id plus end_reason='compression', and hermes_state.SessionDB.get_compression_tip() can walk the continuation chain. However, an ACP client cannot safely infer that boundary from the stream without either:

• parsing human/status text like “context compacted”;
• guessing from usage_update token drops;
• reading Hermes' private state.db; or
• treating all session/load / replay behavior as possible compaction.

This blocks portable ACP clients from rendering a correct “context compacted / current head changed” boundary and from keeping old/new session ids in lineage without coupling directly to Hermes internals.

Proposed Solution

Emit additive Hermes-specific provenance metadata on ACP session surfaces using ACP _meta, while preserving the stable ACP/editor session_id as the public session handle.

Suggested shape, intentionally under _meta.hermes so existing ACP clients can ignore it:

{
  "sessionUpdate": "session_info_update",
  "title": "...",
  "updatedAt": "2026-05-27T00:00:00Z",
  "_meta": {
    "hermes": {
      "sessionProvenance": {
        "acpSessionId": "stable-acp-session-id",
        "currentHermesSessionId": "20260527_123456_abcdef",
        "previousHermesSessionId": "20260527_120000_123456",
        "rootHermesSessionId": "20260527_120000_123456",
        "parentHermesSessionId": "20260527_120000_123456",
        "sessionKind": "continuation",
        "creatorKind": "compression",
        "reason": "compression",
        "compressionDepth": 1,
        "isUserFacing": true
      }
    }
  }
}

The exact names can follow the existing/proposed Hermes provenance taxonomy, but the contract should include enough information for clients to distinguish:

• stable ACP/editor session_id vs. current internal Hermes DB session id;
• previous/current session ids when compression rotates the internal head;
• root/parent lineage;
• compaction/continuation depth, if known;
• whether the change was a split compression continuation vs. in-place metadata-only compaction.

Recommended emission points:

1. session/new, session/load, session/resume, and session/list responses include _meta.hermes.sessionProvenance so late/reconnecting clients hydrate current state immediately.
2. After session/prompt, compare the pre-turn internal Hermes session id with state.agent.session_id. If it changed because agent._compress_context() split the DB session, emit a session_info_update or metadata-only compatible session/update carrying the updated provenance.
3. Keep normal ACP usage_update behavior unchanged. Usage is pressure/telemetry, not the canonical compaction signal.
4. Do not require ACP protocol changes; this is an additive Hermes extension until/unless ACP standardizes a first-class context_compacted / history_compacted event.

Implementation Notes

Relevant code paths in current Hermes:

• agent/conversation_compression.py
  • compress_context() marks the old session ended with end_reason='compression', creates a new session with parent_session_id=old_session_id, assigns agent.session_id to the new id, and notifies context/memory providers.
• hermes_state.py
  • sessions.parent_session_id, sessions.end_reason, and get_compression_tip() already model compression-continuation chains.
  • list_sessions_rich(project_compression_tips=True) already projects roots to live compression tips for session listings.
• acp_adapter/server.py
  • _send_session_info_update() is the likely place to attach metadata after title/provenance changes.
  • prompt() can snapshot the pre-turn internal id before agent.run_conversation(...) and detect post-turn rotation.
• acp_adapter/session.py
  • May need to track the stable ACP id separately from the current internal Hermes DB session id, so ACP clients keep a stable handle while metadata points at the active Hermes continuation.

Existing work appears to be very close or already sufficient:

• https://github.com/NousResearch/hermes-agent/pull/30069 — persists session provenance and continuation taxonomy.
• https://github.com/NousResearch/hermes-agent/pull/31076 — “feat(acp): expose session provenance metadata”; appears to add _meta.hermes provenance to ACP session surfaces and detect post-compression internal session rotation.

If #31076 is still viable, this issue can be treated as the tracking/acceptance issue for reviewing, rebasing, and landing that PR rather than rebuilding from scratch.

Alternatives Considered

• Wait for ACP to standardize a compaction event. Desirable long-term, but Hermes ACP clients need an additive signal now. ACP discussion is active here: https://github.com/agentclientprotocol/agent-client-protocol/discussions/871#discussioncomment-17083273
• Use usage_update token drops. Useful heuristic only; usage drops are not ordered compaction boundaries and do not include previous/current session ids.
• Parse assistant/status text. Brittle and localization/provider/UI dependent.
• Have clients read Hermes state.db. Not portable ACP behavior and couples external clients/UI surfaces to private Hermes storage.
• Change top-level ACP schemas immediately. More interoperable eventually, but _meta.hermes is backwards-compatible and can ship independently.

Feature Type

Other — ACP / session provenance / client interoperability.

Scope

Medium (few files, < 300 lines conceptually if building on existing provenance work; touches ACP session state, metadata builder, prompt rotation detection, session list/load/replay tests).

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)

N/A — feature request based on ACP/client interoperability and code-path inspection.

Acceptance Criteria

• After compression-driven session rotation in an ACP prompt, the client receives an additive ACP update containing _meta.hermes.sessionProvenance (or equivalent _meta.hermes fields) with previous/current Hermes session ids and reason/depth.
• session/new, session/load, session/resume, and session/list expose enough provenance metadata for a reconnecting client to hydrate the current internal Hermes head without reading state.db.
• Stable ACP/editor session_id behavior remains backwards-compatible; clients that ignore _meta continue to work unchanged.
• Metadata does not leak into provider-facing model messages.
• Tests cover:
  • normal ACP session with no compression;
  • split compression continuation (end_reason='compression', child parent_session_id);
  • session list/load hydration after compression;
  • no false positive event when metadata updates but the internal head did not change;
  • existing usage_update behavior unchanged.
• Documentation or docstrings clarify that this is a Hermes extension under ACP _meta, not a standardized ACP compaction event.

Related

• ACP compaction discussion/comment: https://github.com/agentclientprotocol/agent-client-protocol/discussions/871#discussioncomment-17083273
• Existing Hermes PR: https://github.com/NousResearch/hermes-agent/pull/31076
• Provenance dependency PR: https://github.com/NousResearch/hermes-agent/pull/30069
• Adjacent structured compact API request: https://github.com/NousResearch/hermes-agent/issues/15801
• Complementary ACP _meta timing request: https://github.com/NousResearch/hermes-agent/issues/31117