Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

agent/message_metadata.py

@@ -0,0 +1,41 @@
+"""Internal metadata attached to durable conversation messages."""
+
+from __future__ import annotations
+
+from time import time as wall_time
+from typing import Any, MutableMapping, Optional, TypeVar
+
+
+# These fields describe Hermes' durable record, not provider-visible message
+# content. They must not influence context-pressure decisions.
+PERSISTENCE_ONLY_MESSAGE_FIELDS = frozenset({"timestamp"})
+
+_Message = TypeVar("_Message", bound=MutableMapping[str, Any])
+
+
+def stamp_message_timestamp(
+    message: _Message,
+    *,
+    timestamp: Optional[float] = None,
+) -> _Message:
+    """Attach a creation timestamp without replacing source-provided time.
+
+    Gateway adapters can supply the platform event time. All other callers use
+    the local wall clock at the point the message enters the live transcript.
+    Returning the same mapping keeps the helper convenient at append sites.
+    """
+    if message.get("timestamp") is None:
+        message["timestamp"] = wall_time() if timestamp is None else timestamp
+    return message
+
+
+def append_message(
+    messages: list[Any],
+    message: _Message,
+    *,
+    timestamp: Optional[float] = None,
+) -> _Message:
+    """Stamp and append one live transcript message."""
+    stamp_message_timestamp(message, timestamp=timestamp)
+    messages.append(message)
+    return message