message_metadata.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380
  1. """Internal metadata attached to durable conversation messages."""
  2. from __future__ import annotations
  3. from collections import Counter
  4. from time import time as wall_time
  5. from uuid import uuid4
  6. from typing import Any, List, Mapping, MutableMapping, Optional, TypeVar
  7. from agent.conversation_compression_archive import MERGED_DURABLE_ROWS, RETIRED_DURABLE_ROWS, UNNAMED_DURABLE_ROWS
  8. # These fields describe Hermes' durable record and timeline display, not
  9. # provider-visible message content. The request builder strips them from every
  10. # outgoing copy and the token estimator ignores them: one set, so an estimate
  11. # never prices bytes the provider never receives (an edit's inline_diff in
  12. # display_metadata is ~9KB and would trigger premature compaction).
  13. # Transcript-repair bookkeeping riding on batch rows / live dicts (agent/transcript_repair.py): the
  14. # stored-row CAS digest and the durable row adopted onto the live dict. Never transcript payload.
  15. DB_ROW_SNAPSHOT = "_db_row_snapshot"
  16. CANONICAL_ROW = "_canonical_row"
  17. # Set by the agent flush on a batch row (never a live dict) whose ``message_uid`` the agent itself saw durable in
  18. # this session (written by an earlier flush, or loaded from the store with its marker). Only such a row, with no
  19. # row address or snapshot, may be skipped as a re-insert of an ACTIVE uid; a bare copied uid proves nothing.
  20. RESTORED_FROM_STORE = "_restored_from_store"
  21. REPAIR_BOOKKEEPING_FIELDS = frozenset({DB_ROW_SNAPSHOT, CANONICAL_ROW, RESTORED_FROM_STORE})
  22. # Unanswered text a merged user row held before the current turn was absorbed
  23. # (agent_runtime_helpers._merge_consecutive_users); the persist override keeps it.
  24. # It repeats the row's own content, so pricing it would double the estimate.
  25. MERGED_TURN_PREFIX = "_merged_turn_prefix"
  26. # The durable per-message id (``messages.message_uid``): minted once at the row's first insert and kept by
  27. # every host copy of that logical message (in-place compaction generation, rotation child, concurrent-tail
  28. # clone, replace re-issue, rewrite in place). Unlike ``_row_id`` (a physical id re-issued per copy, opt-in on
  29. # restore) it is restored unconditionally, so context engines can key on it across restarts and boundaries.
  30. MESSAGE_UID = "message_uid"
  31. # The merge witness on a consecutive-user merge survivor: the ``message_uid`` of each absorbed row, in
  32. # absorption order (the uid sibling of ``_absorbed_row_ids``; persisted as ``messages.absorbed_message_uids``).
  33. # The survivor keeps the FIRST constituent's uid.
  34. ABSORBED_MESSAGE_UIDS = "_absorbed_message_uids"
  35. # Per-occurrence tool-call identity. Provider tool-call ids repeat (Hermes mints deterministic ``call_<12hex>``
  36. # ids for identical calls, and models reuse ids), so an assistant row carries ``{provider id: uid}`` for its
  37. # ``tool_calls`` (``messages.tool_call_uids``) and its tool-result rows carry the matching uid
  38. # (``messages.tool_call_uid``). The provider-facing ``id`` is untouched; these never reach the wire.
  39. TOOL_CALL_UIDS = "_tool_call_uids"
  40. TOOL_CALL_UID = "_tool_call_uid"
  41. PERSISTENCE_ONLY_MESSAGE_FIELDS = frozenset(
  42. # Membership is the real contract, NOT the leading underscore: the chat-completions transport happens
  43. # to sweep underscore keys, but turn_context.py pops this set from every outgoing copy and a strict
  44. # backend 400s on any key it does not know.
  45. {"timestamp", "display_kind", "display_metadata", "_row_id", "_submit_row_session_id",
  46. MERGED_TURN_PREFIX, MESSAGE_UID, ABSORBED_MESSAGE_UIDS, TOOL_CALL_UIDS, TOOL_CALL_UID,
  47. # The alternation repair's row counts: an in-place compaction reads them off the live dict.
  48. MERGED_DURABLE_ROWS, UNNAMED_DURABLE_ROWS, RETIRED_DURABLE_ROWS}
  49. ) | REPAIR_BOOKKEEPING_FIELDS
  50. # Connector data-use requirement on a tool message; persisted inside ``display_metadata``, never sent to a model.
  51. DATA_USE = "data_use"
  52. def data_use_requirement(messages: Any) -> frozenset[str]:
  53. """The union of ``data_use`` over *messages*: what the model receiving them must guarantee."""
  54. return frozenset(r for m in messages or () if isinstance(m, Mapping) for r in m.get(DATA_USE) or ())
  55. def stamp_data_use(message: MutableMapping[str, Any], requires: list[str]) -> None:
  56. """Mark a tool message with its requirement. The ``display_metadata`` copy is the durable one: that
  57. column already rides every writer, branch and compaction copy, and replay lifts it back (SessionDB)."""
  58. if not requires:
  59. return
  60. message[DATA_USE] = list(requires)
  61. metadata = message.get("display_metadata")
  62. message["display_metadata"] = {**(metadata if isinstance(metadata, dict) else {}), DATA_USE: list(requires)}
  63. # What the user typed on a turn a ``pre_llm_call`` hook vetoed, kept inside ``display_metadata``. The row's
  64. # ``content`` is the withheld placeholder, so every reader that hands transcript text to a model (wire
  65. # replay, compaction, session_search, memory providers, background review) only ever sees that; transcript
  66. # views render this key instead (agent/turn_context.py::_withhold_blocked_prompt).
  67. WITHHELD_PROMPT = "withheld_prompt"
  68. PRE_LLM_BLOCK_WITHHELD_PROMPT = "[Message withheld: a pre_llm_call policy hook blocked it.]"
  69. def withheld_prompt_text(message: Any) -> Optional[str]:
  70. """The typed text a transcript view shows for a vetoed user row, else None."""
  71. metadata = message.get("display_metadata") if isinstance(message, Mapping) else None
  72. text = metadata.get(WITHHELD_PROMPT) if isinstance(metadata, Mapping) else None
  73. return text if isinstance(text, str) else None
  74. def typed_prompt_content(content: Any, message: Any) -> Any:
  75. """*content* (a rewind's live view of *message*) with the withheld placeholder swapped back for what
  76. the user typed: ``/retry`` re-submits the real ask so the hook decides again, and ``/undo`` restores it
  77. to the composer. Never the placeholder as a new prompt."""
  78. typed = withheld_prompt_text(message)
  79. if typed is None:
  80. return content
  81. if isinstance(content, str):
  82. return content.replace(PRE_LLM_BLOCK_WITHHELD_PROMPT, typed)
  83. if isinstance(content, list):
  84. return [{**part, "text": part["text"].replace(PRE_LLM_BLOCK_WITHHELD_PROMPT, typed)}
  85. if isinstance(part, dict) and isinstance(part.get("text"), str) else part for part in content]
  86. return content
  87. def without_withheld_prompts(messages: Any) -> Any:
  88. """*messages* with the vetoed text dropped from each row's ``display_metadata`` (copies only where
  89. one is present), for hand-offs that leave the host with whole row dicts (memory providers)."""
  90. if not isinstance(messages, list) or not any(withheld_prompt_text(m) is not None for m in messages):
  91. return messages
  92. return [
  93. {**m, "display_metadata": {k: v for k, v in m["display_metadata"].items() if k != WITHHELD_PROMPT}}
  94. if withheld_prompt_text(m) is not None else m
  95. for m in messages
  96. ]
  97. def lift_data_use(message: MutableMapping[str, Any]) -> None:
  98. """Restore a replayed row's ``data_use`` key from its durable ``display_metadata`` copy."""
  99. metadata = message.get("display_metadata")
  100. if isinstance(metadata, dict) and metadata.get(DATA_USE):
  101. message[DATA_USE] = list(metadata[DATA_USE])
  102. # Replay carriers the preflight estimate prices at 0, exactly as the compaction tail walk does (opaque signatures,
  103. # duplicate reasoning copies, ordered sidecars); a mismatch between the two estimates loops compaction.
  104. _UNPRICED_CORE_FIELDS = frozenset({"_anthropic_content_blocks", "reasoning_details", "extra_content",
  105. "bedrock_content_blocks", DATA_USE})
  106. def unpriced_replay_fields() -> frozenset[str]:
  107. """The core unpriced carriers plus every message carrier key a registered profile declares
  108. (``ProviderProfile.message_carrier_*``). Resolve once per message, never per key."""
  109. from agent.reasoning_carriers import declared_carrier_keys
  110. opaque, text = declared_carrier_keys()
  111. return _UNPRICED_CORE_FIELDS.union(opaque, text)
  112. def without_persistence_fields(msg: Mapping[str, Any]) -> Mapping[str, Any]:
  113. """*msg* itself when it carries no persistence-only field, else a shallow copy without them."""
  114. if PERSISTENCE_ONLY_MESSAGE_FIELDS.isdisjoint(msg):
  115. return msg
  116. return {k: v for k, v in msg.items() if k not in PERSISTENCE_ONLY_MESSAGE_FIELDS}
  117. def mint_uid() -> str:
  118. """A fresh durable id (message or tool-call occurrence): random, never derived from content."""
  119. return uuid4().hex
  120. def uid_list(value: Any) -> list[str]:
  121. """The unique non-empty string uids of a live list, in order; anything else is ``[]``."""
  122. return list(dict.fromkeys(u for u in (value if isinstance(value, list) else ()) if isinstance(u, str) and u))
  123. def message_uid_or_none(msg: Mapping[str, Any]) -> Optional[str]:
  124. """The dict's ``message_uid`` when it is a non-empty string, else ``None`` (never coerced: an int or a
  125. blank would be a bug upstream of the write, not an identity)."""
  126. uid = msg.get(MESSAGE_UID)
  127. return uid if isinstance(uid, str) and uid else None
  128. def stamp_message_uid(msg: MutableMapping[str, Any]) -> str:
  129. """The dict's ``message_uid``, minting one (``mint_uid``) when it carries none.
  130. Minted ONCE per logical message, at its first insert, and stamped on the caller's dict so every later
  131. insert of that dict (compaction generation, rotation handoff, replace) writes the same uid. Never
  132. derived from content, timestamp or tool-call ids: two distinct messages may share all three.
  133. """
  134. uid = message_uid_or_none(msg)
  135. if uid is None:
  136. uid = msg[MESSAGE_UID] = mint_uid()
  137. return uid
  138. # Producer-owned provenance for the compressor's standalone in-flight-task restatement. It rides in
  139. # display_metadata (persisted by SessionDB, popped from every wire copy) so gateway replay can send the
  140. # row unstamped, as the compaction turn did; a human pasting the header text carries no flag.
  141. INFLIGHT_TASK_RESTATEMENT = "compaction_inflight_task_restatement"
  142. def mark_inflight_restatement(msg: MutableMapping[str, Any]) -> None:
  143. metadata = msg.get("display_metadata")
  144. msg["display_metadata"] = {**(metadata if isinstance(metadata, dict) else {}), INFLIGHT_TASK_RESTATEMENT: True}
  145. def scaffolding_replay_fields(msg: Mapping[str, Any]) -> dict:
  146. """The compaction-provenance fields replay keeps (summary flag, restatement flag), else ``{}``. A proactive
  147. prune re-persists the replayed view, so a dropped flag would get the row stamped on the next replay."""
  148. metadata = msg.get("display_metadata")
  149. fields: dict = {"_compressed_summary": True} if msg.get("_compressed_summary") else {}
  150. if isinstance(metadata, dict) and metadata.get(INFLIGHT_TASK_RESTATEMENT):
  151. fields["display_metadata"] = {INFLIGHT_TASK_RESTATEMENT: True}
  152. return fields
  153. def is_compaction_scaffolding(msg: Mapping[str, Any]) -> bool:
  154. """Compaction sent its summary and restatement rows unstamped; a replay stamp would break the cached prefix."""
  155. return bool(scaffolding_replay_fields(msg))
  156. _IDENTITY_FIELD_TYPES = ((MESSAGE_UID, str), (ABSORBED_MESSAGE_UIDS, list), (TOOL_CALL_UIDS, dict), (TOOL_CALL_UID, str))
  157. def copy_identity_fields(src: Mapping[str, Any], dst: MutableMapping[str, Any]) -> None:
  158. """Copy the non-empty identity fields (uid, merge witness, tool-call uids) from *src* onto *dst*: the
  159. live dict to its flush row, and the committed row back onto the live dict."""
  160. for key, kind in _IDENTITY_FIELD_TYPES:
  161. value = src.get(key)
  162. if isinstance(value, kind) and value:
  163. dst[key] = kind(value)
  164. def message_identity(msg: MutableMapping[str, Any], *, with_tool_uids: bool = False) -> dict:
  165. """The identity fields a new row copied from *msg* must carry, minting *msg*'s uid first when it has none:
  166. a branch/seed copy writes fresh rows from the live dicts the new session keeps using, and a row without
  167. them would restore with a different uid than the live dict carries. ``with_tool_uids`` only for a copy
  168. that also carries ``tool_calls`` / ``tool_call_id``; a uid map on a row without its calls pairs nothing."""
  169. stamp_message_uid(msg)
  170. identity: dict = {}
  171. copy_identity_fields(msg, identity)
  172. if not with_tool_uids:
  173. identity.pop(TOOL_CALL_UIDS, None)
  174. identity.pop(TOOL_CALL_UID, None)
  175. return identity
  176. def record_absorbed_message(
  177. survivor: MutableMapping[str, Any], dropped: Mapping[str, Any], *, dropped_leads: bool = False,
  178. ) -> None:
  179. """Merge-witness bookkeeping for every host fold of *dropped* into *survivor*.
  180. The composite keeps the uid of the constituent whose text comes first and records every other
  181. constituent's uid in ``_absorbed_message_uids`` (text order, no repeats). By default the survivor's
  182. text leads; with *dropped_leads* the dropped dict's text was put first (the real user anchor folded
  183. into a scaffolding turn), so its uid becomes the survivor's and the survivor's former uid is recorded.
  184. A dict without a uid (unflushed, scaffolding, engine-authored) contributes nothing; an empty result
  185. leaves the survivor untouched.
  186. """
  187. survivor_uid = message_uid_or_none(survivor)
  188. dropped_uid = message_uid_or_none(dropped)
  189. own = uid_list(survivor.get(ABSORBED_MESSAGE_UIDS))
  190. theirs = uid_list(dropped.get(ABSORBED_MESSAGE_UIDS))
  191. if dropped_leads and dropped_uid:
  192. survivor[MESSAGE_UID] = dropped_uid
  193. ordered = theirs + ([survivor_uid] if survivor_uid else []) + own
  194. else:
  195. ordered = own + ([dropped_uid] if dropped_uid else []) + theirs
  196. if absorbed := [uid for uid in dict.fromkeys(ordered) if uid != survivor.get(MESSAGE_UID)]:
  197. survivor[ABSORBED_MESSAGE_UIDS] = absorbed
  198. def merge_tool_call_uids(into: Mapping[str, Any], extra: Mapping[str, Any]) -> dict:
  199. """Union two ``_tool_call_uids`` maps without losing an occurrence. Folding two assistant turns that
  200. reuse a provider id (llama.cpp-style constant ids) leaves both calls in ``tool_calls``; the id then maps
  201. to every occurrence's uid, in call order, as a list. Provider ids themselves are never rewritten."""
  202. merged = dict(into)
  203. for call_id, uid in extra.items():
  204. merged[call_id] = _uid_occurrences(merged[call_id]) + _uid_occurrences(uid) if call_id in merged else uid
  205. return merged
  206. def _uid_occurrences(value: Any) -> list:
  207. return list(value) if isinstance(value, list) else [value]
  208. def per_occurrence_tool_call_uids(uids: Mapping[str, Any], tool_calls: list[Mapping[str, Any]]) -> dict:
  209. """*uids* with every provider id this row names more than once spelled out as one uid per occurrence. A
  210. single response that repeats an id shares ONE uid (its results carry it, so every call stays paired);
  211. before a fold appends another turn's occurrences, the shared uid must fill each of this row's slots or
  212. the appended uids would align with the wrong calls."""
  213. from agent.message_sanitization import coalesce_tool_call_id
  214. counts = Counter(call_id for tc in tool_calls if (call_id := coalesce_tool_call_id(tc)))
  215. expanded = dict(uids)
  216. for call_id, count in counts.items():
  217. if count > 1 and isinstance(uid := uids.get(call_id), str):
  218. expanded[call_id] = [uid] * count
  219. return expanded
  220. def index_tool_call_uids(index: MutableMapping[str, str], assistant: Mapping[str, Any]) -> frozenset:
  221. """Register an assistant dict's ``_tool_call_uids`` under every pairing-id variant of its tool calls, so a
  222. later tool-result row can be resolved by any spelling of its ``tool_call_id``. Provider ids repeat, so
  223. every id this assistant names first shadows an earlier occurrence's entry: a result pairs with the
  224. NEAREST preceding call, and a call without a uid (a legacy row) pairs its result with nothing. A
  225. provider id repeated inside one row (two folded turns) maps each call to its own occurrence's uid.
  226. Returns every pairing-id variant the assistant names."""
  227. from agent.message_sanitization import coalesce_tool_call_id, tool_call_id_variants
  228. calls = [(tc, tool_call_id_variants(tc)) for tc in assistant.get("tool_calls") or ()]
  229. named = frozenset(variant for _, variants in calls for variant in variants)
  230. for variant in named:
  231. index.pop(variant, None)
  232. uids = assistant.get(TOOL_CALL_UIDS)
  233. if not isinstance(uids, dict) or not uids:
  234. return named
  235. occurrence: dict = {} # provider id -> calls seen so far: a list value holds one uid per occurrence
  236. for tc, variants in calls:
  237. call_id = coalesce_tool_call_id(tc)
  238. uid = uids.get(call_id)
  239. if isinstance(uid, list):
  240. nth = occurrence[call_id] = occurrence.get(call_id, -1) + 1
  241. uid = uid[nth] if nth < len(uid) else None
  242. if isinstance(uid, str) and uid:
  243. for variant in variants:
  244. index[variant] = uid
  245. return named
  246. def resolve_tool_call_uid(index: MutableMapping[str, str], tool_call_id: Any) -> Optional[str]:
  247. """The uid an indexed assistant dict minted for ``tool_call_id`` (any variant), else ``None``."""
  248. from agent.message_sanitization import tool_result_id_variants
  249. if not index or not isinstance(tool_call_id, str) or not tool_call_id:
  250. return None
  251. for variant in tool_result_id_variants(tool_call_id):
  252. uid = index.get(variant)
  253. if uid:
  254. return uid
  255. return None
  256. def tool_call_uid_from_history(messages: list[dict], tool_index: int, owners: dict) -> Optional[str]:
  257. """Resolve a tool-result dict's uid from the nearest preceding assistant dict in ``messages`` that
  258. named its ``tool_call_id`` (the cross-flush case: the assistant row landed in an earlier batch).
  259. ``owners`` memoizes each assistant's (named variants, uid index) across one flush's results, so K
  260. parallel results of one assistant cost O(K) variant work instead of O(K^2)."""
  261. tool_call_id = messages[tool_index].get("tool_call_id")
  262. if not isinstance(tool_call_id, str) or not tool_call_id:
  263. return None
  264. from agent.message_sanitization import tool_result_id_variants
  265. result_variants = set(tool_result_id_variants(tool_call_id))
  266. for prior_index in range(tool_index - 1, -1, -1): # no messages[:i] copy: this runs per flushed result
  267. prior = messages[prior_index]
  268. if not isinstance(prior, dict):
  269. continue
  270. if prior.get("role") == "user":
  271. return None # a tool result never pairs across a user turn
  272. if prior.get("role") != "assistant":
  273. continue
  274. if (entry := owners.get(id(prior))) is None:
  275. index: dict = {}
  276. entry = owners[id(prior)] = (index_tool_call_uids(index, prior), index)
  277. named, index = entry
  278. if result_variants.isdisjoint(named):
  279. continue
  280. # The nearest assistant naming this id owns the result: its uid, or none if it has no map (legacy).
  281. return resolve_tool_call_uid(index, tool_call_id)
  282. return None
  283. _Message = TypeVar("_Message", bound=MutableMapping[str, Any])
  284. def stamp_message_timestamp(
  285. message: _Message,
  286. *,
  287. timestamp: Optional[float] = None,
  288. ) -> _Message:
  289. """Attach a creation timestamp without replacing source-provided time.
  290. Gateway adapters can supply the platform event time; all other callers use
  291. the local wall clock. Returns the same mapping for use at append sites.
  292. """
  293. if message.get("timestamp") is None:
  294. message["timestamp"] = wall_time() if timestamp is None else timestamp
  295. return message
  296. def append_message(
  297. messages: list[Any],
  298. message: _Message,
  299. *,
  300. timestamp: Optional[float] = None,
  301. ) -> _Message:
  302. """Stamp and append one live transcript message."""
  303. messages.append(stamp_message_timestamp(message, timestamp=timestamp))
  304. return message