provenance.py 3.8 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586
  1. """Derive ACP session-provenance metadata from the existing compression chain.
  2. Additive Hermes extension under ACP ``_meta.hermes`` (unknown to other clients,
  3. so ignored). No new persisted state: everything is derived from the ``sessions``
  4. table (``parent_session_id`` / ``end_reason``), which already models
  5. compression-continuation chains.
  6. The ACP/editor ``session_id`` stays the stable public handle; when compression
  7. rotates the internal Hermes head, ``build_session_provenance`` exposes the
  8. previous/current internal ids and lineage root without parsing status text.
  9. """
  10. from __future__ import annotations
  11. from typing import Any, Dict, Optional
  12. # Bound defensive walks; compression chains this deep are pathological.
  13. _MAX_WALK = 100
  14. def _get_row(db: Any, session_id: str) -> Optional[dict[str, Any]]:
  15. try:
  16. return db.get_session(session_id)
  17. except Exception:
  18. return None
  19. def _is_compression_end(row: Any) -> bool:
  20. return bool(row) and row.get("end_reason") == "compression"
  21. def build_session_provenance(
  22. db: Any, acp_session_id: str, current_hermes_session_id: str, *, previous_hermes_session_id: Optional[str] = None,
  23. ) -> Optional[dict[str, Any]]:
  24. """Build ``_meta.hermes.sessionProvenance`` for an ACP session.
  25. ``db`` must expose ``get_session``. ``current_hermes_session_id`` is the live
  26. internal id (``state.agent.session_id``); ``previous_hermes_session_id`` is
  27. the id before the most recent turn, supplied by ``prompt()`` to flag a
  28. rotation. Returns ``None`` if the session can't be read."""
  29. row = _get_row(db, current_hermes_session_id)
  30. if not row:
  31. return None
  32. parent_id = row.get("parent_session_id")
  33. # Walk parents to the lineage root. Only compression-split parents
  34. # (parent.end_reason == 'compression') count toward depth — delegate/branch
  35. # children share the parent_session_id column but are not compaction boundaries.
  36. root_id, compression_depth, cursor_parent = current_hermes_session_id, 0, parent_id
  37. seen = {current_hermes_session_id}
  38. for _ in range(_MAX_WALK):
  39. if not cursor_parent or cursor_parent in seen:
  40. break
  41. seen.add(cursor_parent)
  42. prow = _get_row(db, cursor_parent)
  43. if not prow:
  44. break
  45. root_id = cursor_parent
  46. compression_depth += _is_compression_end(prow)
  47. cursor_parent = prow.get("parent_session_id")
  48. # A continuation is a session whose immediate parent ended with end_reason='compression'.
  49. is_continuation = bool(parent_id) and _is_compression_end(_get_row(db, parent_id))
  50. provenance: dict[str, Any] = {
  51. "acpSessionId": acp_session_id, "currentHermesSessionId": current_hermes_session_id,
  52. "rootHermesSessionId": root_id, "parentHermesSessionId": parent_id,
  53. "sessionKind": "continuation" if is_continuation else "root", "compressionDepth": compression_depth,
  54. }
  55. if previous_hermes_session_id:
  56. provenance["previousHermesSessionId"] = previous_hermes_session_id
  57. if previous_hermes_session_id != current_hermes_session_id:
  58. # The only mechanism that rotates the internal id mid-turn is
  59. # compression-driven session splitting.
  60. provenance["reason"] = "compression"
  61. provenance["creatorKind"] = "compression"
  62. return provenance
  63. def session_provenance_meta(
  64. db: Any, acp_session_id: str, current_hermes_session_id: str, *, previous_hermes_session_id: Optional[str] = None,
  65. ) -> Optional[dict[str, Any]]:
  66. """Return a ready ``_meta`` payload: ``{"hermes": {"sessionProvenance": ...}}``."""
  67. prov = build_session_provenance(db, acp_session_id, current_hermes_session_id,
  68. previous_hermes_session_id=previous_hermes_session_id)
  69. return None if prov is None else {"hermes": {"sessionProvenance": prov}}