Coder preparations

common/time.py

@@ -0,0 +1,31 @@
+# orchestrator/time.py
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+# Single canonical format for all timestamps the agent writes.
+# ISO 8601, UTC, second precision, trailing "Z".
+# Examples: "2026-09-21T11:45:00Z"
+ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def now_iso() -> str:
+    """Current UTC time as an ISO 8601 string."""
+    return datetime.now(timezone.utc).strftime(ISO_FORMAT)
+
+
+def now_iso_plus(
+    *,
+    days: int = 0,
+    hours: int = 0,
+    minutes: int = 0,
+    seconds: int = 0,
+) -> str:
+    """Current UTC time plus a delta, as an ISO 8601 string."""
+    delta = timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
+    return (datetime.now(timezone.utc) + delta).strftime(ISO_FORMAT)
+
+
+def parse_iso(s: str) -> datetime:
+    """Parse an ISO 8601 string produced by now_iso / now_iso_plus."""
+    return datetime.strptime(s, ISO_FORMAT).replace(tzinfo=timezone.utc)