k8stools 2.1.0__tar.gz → 2.2.0__tar.gz

{k8stools-2.1.0 → k8stools-2.2.0}/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
 dates are release-tag dates.
 
+## 2.2.0 — 2026-09-28
+
+### Added
+- **`count` and `first_seen` on events** (issue #8). `get_pod_events` and
+  `get_events` now report how many occurrences Kubernetes combined into each
+  event record, and how long ago the first one was, next to `last_seen`. For a
+  crash-looping container this gives the restart rate directly: on one cluster,
+  a `Created` count of 579 over 2 days 8 hours is a restart every ~5.8 minutes,
+  a number agents kept getting wrong from the other durations. The tool
+  descriptions explain the window the count covers and warn that `BackOff`
+  counts are several times the number of restarts. `print_pod_events` and
+  `print_events` gain a COUNT column.
+- Captures store both fields; captures from before 2.2.0 replay them as `None`.
+
+### Fixed
+- **Replayed `captured_at` was on a different clock** (issue #7).
+  `get_cluster_info` returned the date in the capture file while every other
+  replayed timestamp was re-anchored to the server's start, so a pod killed
+  "5 minutes ago" appeared beside a capture taken a month ago. `captured_at` is
+  now the replay's anchor (the server's start time); the recorded date is in the
+  startup log and on `MockState.captured_at`.
+- **Replayed logs kept their original timestamps.** Log line timestamps were not
+  re-anchored, so they contradicted every other replayed time, and
+  `since_seconds` (compared against the replay's "now") returned an empty log for
+  any capture older than the window, as if the container had logged nothing.
+  The kubelet's timestamp prefix on each line is now moved like every other
+  datetime, keeping its original precision and format. Timestamps an application
+  writes inside its messages are left as recorded.
+- **Events recorded through `events.k8s.io/v1` had no time.** Their core/v1 view
+  leaves `lastTimestamp` empty and records the time in `eventTime` (and
+  repetition in `series`), so `last_seen` came back `None`. Both are now read
+  when the older fields are empty.
+
 ## 2.1.0 — 2026-09-28
 
 ### Added

{k8stools-2.1.0 → k8stools-2.2.0}/CLAUDE.md

@@ -24,6 +24,7 @@ tests/
   test_capture.py            - Capture serialization round-trip and capture-time redaction
   test_k8s_tools_realk8s.py  - Integration tests (real cluster, auto-skipped if unreachable)
   test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
+  test_events.py             - Event aggregation (count/first_seen), incl. the events.k8s.io fallback
   test_cluster_binding.py    - Cluster selection: configure(), the shared binding, get_cluster_info, server flags
   test_log_decoding.py       - Log decoding at the API boundary (bytes vs str), `previous` plumbing, log redaction
   test_mcp_client.py         - MCP client tests
@@ -213,6 +214,12 @@ Invariants worth preserving when touching this code:
   replay — "deployment 8d old, current replica set 7h34m old, so it was upgraded
   7h34m ago". The replay clock quantizes to whole seconds and samples once per
   query to keep that exact; don't reintroduce per-field `datetime.now()`.
+  One clock for everything replay returns: datetimes are re-anchored so
+  capture time becomes server start time, and that includes
+  `get_cluster_info().captured_at` (the anchor itself) and the kubelet's
+  timestamp prefix on each log line (`_reanchor_log`). Anything that reports a
+  time from the file verbatim contradicts the rest. Tests that capture and
+  replay at the same instant cannot see this; use a capture date in the past.
   Only ages advance: an `Interval` field is stored under the same `_seconds` key
   but read back unchanged. Replay tests that freeze the clock can't tell the two
   apart (frozen elapsed time is zero), so test a new duration field on an

{k8stools-2.1.0 → k8stools-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.1.0
+Version: 2.2.0
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Project-URL: Changelog, https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md
@@ -684,6 +684,15 @@ long session cannot see ages drift between its first tool call and its last.
 a suite that believed it had frozen the clock and had not would be flaky with no
 visible cause.)
 
+Absolute times are replayed the same way: every timestamp a tool returns is moved
+so the moment of capture becomes the moment the server started. A container killed
+5 minutes before the capture reads as killed 5 minutes before server start, and
+`get_cluster_info`'s `captured_at` is that start time, not the date in the file,
+so the agent sees one consistent clock. Log line timestamps (the kubelet's
+prefix) are moved too, so `since_seconds` works on a capture of any age;
+timestamps an application writes inside its own log messages are left as
+recorded. The file's own capture date is in the server's startup log.
+
 ### Replaying from Python
 
 For a test suite, skip the server and load the capture directly. `MockState` has

{k8stools-2.1.0 → k8stools-2.2.0}/README.md

@@ -464,6 +464,15 @@ long session cannot see ages drift between its first tool call and its last.
 a suite that believed it had frozen the clock and had not would be flaky with no
 visible cause.)
 
+Absolute times are replayed the same way: every timestamp a tool returns is moved
+so the moment of capture becomes the moment the server started. A container killed
+5 minutes before the capture reads as killed 5 minutes before server start, and
+`get_cluster_info`'s `captured_at` is that start time, not the date in the file,
+so the agent sees one consistent clock. Log line timestamps (the kubelet's
+prefix) are moved too, so `since_seconds` works on a capture of any age;
+timestamps an application writes inside its own log messages are left as
+recorded. The file's own capture date is in the server's startup log.
+
 ### Replaying from Python
 
 For a test suite, skip the server and load the capture directly. `MockState` has

{k8stools-2.1.0 → k8stools-2.2.0}/designs/mock-state-capture.md

@@ -341,12 +341,15 @@ become `*_offset_seconds` before `captured_at`.
   (a filtered view where `involved_kind == "Pod"` and `involved_name == pod_name`):
   ```json
   {
-    "last_seen_seconds": 120.0, "type": "Warning", "reason": "Evicted",
+    "last_seen_seconds": 120.0, "first_seen_seconds": 120.0, "count": 1,
+    "type": "Warning", "reason": "Evicted",
     "namespace": "default", "involved_kind": "Pod", "involved_name": "session-abc",
     "object": "Pod/session-abc",
     "message": "The node was low on resource: ephemeral-storage."
   }
   ```
+  `first_seen_seconds` and `count` were added in 2.2.0; captures without them
+  replay those fields as `null`.
   This is the one structural change from the original design: pods no longer embed
   their own `events`; `MockState.get_pod_events` filters the flat list instead. This
   also lets captures include events with no surviving pod (Evicted, FailedScheduling),

{k8stools-2.1.0 → k8stools-2.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "k8stools"
-version = "2.1.0"
+version = "2.2.0"
 description = "Tools and an MCP server for building Kubernetes agents"
 readme = "README.md"
 requires-python = ">=3.12"

{k8stools-2.1.0 → k8stools-2.2.0}/src/k8stools/__init__.py

@@ -78,4 +78,4 @@ the built-in OTel Demo snapshot by default, or your own via load_mock_state() or
 the server's --state-file option.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"

{k8stools-2.1.0 → k8stools-2.2.0}/src/k8stools/capture.py

@@ -253,6 +253,8 @@ def _capture_events(namespace: str, captured_at: datetime.datetime,
             kind, name = None, event.object
         records.append({
             "last_seen_seconds": event.last_seen.total_seconds() if event.last_seen else None,
+            "first_seen_seconds": event.first_seen.total_seconds() if event.first_seen else None,
+            "count": event.count,
             "type": event.type,
             "reason": event.reason,
             "namespace": namespace,

{k8stools-2.1.0 → k8stools-2.2.0}/src/k8stools/k8s_tools.py

@@ -667,10 +667,43 @@ def _format_timedelta(td: Optional[datetime.timedelta]) -> str:
 class EventSummary(BaseModel):
     """This is the representation of a Kubernetes Event"""
     last_seen: Optional[Duration]  # Time since event occurred
+    #: Time since the first occurrence combined into this record.
+    first_seen: Optional[Duration] = None
+    #: How many occurrences Kubernetes combined into this record.
+    count: Optional[int] = None
     type: str
     reason: str
     object: str
     message: str
+
+
+def _event_summary(event: Any, now: datetime.datetime, obj: str) -> EventSummary:
+    """Convert a core/v1 Event, including one recorded through events.k8s.io/v1.
+
+    The events.k8s.io API reaches the core/v1 view with the deprecated
+    ``count``/``firstTimestamp``/``lastTimestamp`` unset. Its time is
+    ``eventTime`` (the first observation) and any repetition is in ``series``, so
+    those fill in when the deprecated fields are empty. A record with
+    ``eventTime`` and no ``series`` was observed once.
+    """
+    series = getattr(event, "series", None)
+    event_time = getattr(event, "event_time", None)
+    last = (getattr(event, "last_timestamp", None)
+            or (series.last_observed_time if series else None)
+            or event_time)
+    first = getattr(event, "first_timestamp", None) or event_time
+    count = (getattr(event, "count", None)
+             or (series.count if series else None)
+             or (1 if event_time else None))
+    return EventSummary(
+        last_seen=(now - last) if last else None,
+        first_seen=(now - first) if first else None,
+        count=count,
+        type=event.type or "",
+        reason=event.reason or "",
+        object=obj,
+        message=event.message or "",
+    )
  
 
 def get_pod_events(pod_name: str, namespace: str = "default") -> list[EventSummary]:
@@ -690,8 +723,22 @@ def get_pod_events(pod_name: str, namespace: str = "default") -> list[EventSumma
     list of EventSummary
         List of events associated with the specified pod. Each EventSummary has the following fields:
 
-        last_seen : Optional[datetime.datetime]
-            Timestamp of the last occurrence of the event (if available).
+        last_seen : Optional[datetime.timedelta]
+            Time since the most recent occurrence of the event (if available).
+        first_seen : Optional[datetime.timedelta]
+            Time since the first occurrence combined into this record (if
+            available).
+        count : Optional[int]
+            How many occurrences Kubernetes combined into this record: repeats
+            of the same event on the same object are counted in one record
+            rather than listed separately. The count covers first_seen to
+            last_seen, not the object's lifetime - a record that stops repeating
+            expires (after 1h by default), and a later repeat starts a new one.
+            For a crash-looping container, count the "Created" or "Started"
+            events to get restarts. "BackOff" is emitted repeatedly while the
+            kubelet waits to restart, so its count is several times the number
+            of restarts. count divided by (first_seen - last_seen) is the
+            average rate over that window, not the current back-off.
         type : str
             Type of the event.
         reason : str
@@ -714,16 +761,8 @@ def get_pod_events(pod_name: str, namespace: str = "default") -> list[EventSumma
     field_selector = f"involvedObject.name={pod_name}"
     events = K8S.list_namespaced_event(namespace, field_selector=field_selector)
     now = datetime.datetime.now(datetime.timezone.utc)
-    return [
-        EventSummary(
-            last_seen=(now - event.last_timestamp) if event.last_timestamp else None,
-            type=event.type,
-            reason=event.reason,
-            object=getattr(event.involved_object, 'name', pod_name),
-            message=event.message,
-        )
-        for event in events.items
-    ]
+    return [_event_summary(event, now, getattr(event.involved_object, 'name', pod_name))
+            for event in events.items]
 
 
 def print_pod_events(pod_name: str, namespace: str = "default") -> None:
@@ -731,11 +770,12 @@ def print_pod_events(pod_name: str, namespace: str = "default") -> None:
     Print the events for the specified pod, in a similar format to `kubectl get events`.
     """
     events = get_pod_events(pod_name, namespace)
-    print(f"{'LAST SEEN':<12} {'TYPE':<10} {'REASON':<20} {'OBJECT':<32} {'MESSAGE':<40}")
+    print(f"{'LAST SEEN':<12} {'COUNT':<7} {'TYPE':<10} {'REASON':<20} {'OBJECT':<32} {'MESSAGE':<40}")
     for event in events:
         last_seen = _format_timedelta(event.last_seen) if event.last_seen else "-"
+        count = str(event.count) if event.count is not None else "-"
         message = (event.message[:37] + '...') if event.message and len(event.message) > 40 else event.message
-        print(f"{last_seen:<12} {event.type:<10} {event.reason:<20} {event.object:<32} {message:<40}")
+        print(f"{last_seen:<12} {count:<7} {event.type:<10} {event.reason:<20} {event.object:<32} {message:<40}")
 
 # see kubernetes.client.models.v1_container_state_running.V1ContainerStateRunning
 class ContainerStateRunning(BaseModel):
@@ -2427,8 +2467,9 @@ def get_events(namespace: Optional[str] = None,
     Unlike `get_pod_events` (which is scoped to a single named pod), this supports
     the sweep queries common in capacity/storage runbooks — e.g. all "Evicted"
     events, or all "FailedScheduling" events — where the affected pods often have no
-    stable name to look up. Note the Kubernetes API only retains roughly the last
-    hour of events.
+    stable name to look up. Note Kubernetes expires an event record about an hour
+    (by default) after its last occurrence, so events that stopped repeating
+    earlier than that are gone.
 
     Parameters
     ----------
@@ -2452,6 +2493,20 @@ def get_events(namespace: Optional[str] = None,
 
         last_seen : Optional[datetime.timedelta]
             Time since the event was last seen (if available).
+        first_seen : Optional[datetime.timedelta]
+            Time since the first occurrence combined into this record (if
+            available).
+        count : Optional[int]
+            How many occurrences Kubernetes combined into this record: repeats
+            of the same event on the same object are counted in one record
+            rather than listed separately. The count covers first_seen to
+            last_seen, not the object's lifetime - a record that stops repeating
+            expires (after 1h by default), and a later repeat starts a new one.
+            For a crash-looping container, count the "Created" or "Started"
+            events to get restarts. "BackOff" is emitted repeatedly while the
+            kubelet waits to restart, so its count is several times the number
+            of restarts. count divided by (first_seen - last_seen) is the
+            average rate over that window, not the current back-off.
         type : str
             Type of the event ("Normal" or "Warning").
         reason : str
@@ -2501,13 +2556,7 @@ def get_events(namespace: Optional[str] = None,
         obj_name = getattr(involved, "name", None) or ""
         obj_kind = getattr(involved, "kind", None)
         obj = f"{obj_kind}/{obj_name}" if obj_kind else obj_name
-        results.append(EventSummary(
-            last_seen=(now - event.last_timestamp) if getattr(event, "last_timestamp", None) else None,
-            type=event.type or "",
-            reason=event.reason or "",
-            object=obj,
-            message=event.message or "",
-        ))
+        results.append(_event_summary(event, now, obj))
     return results
 
 
@@ -2519,11 +2568,12 @@ def print_events(namespace: Optional[str] = None,
     """Calls get_events and prints the output to stdout, similar to
     `kubectl get events`."""
     events = get_events(namespace, reason, involved_kind, involved_name, event_type)
-    print(f"{'LAST SEEN':<12} {'TYPE':<10} {'REASON':<20} {'OBJECT':<40} {'MESSAGE':<40}")
+    print(f"{'LAST SEEN':<12} {'COUNT':<7} {'TYPE':<10} {'REASON':<20} {'OBJECT':<40} {'MESSAGE':<40}")
     for event in events:
         last_seen = _format_timedelta(event.last_seen) if event.last_seen else "-"
+        count = str(event.count) if event.count is not None else "-"
         message = (event.message[:37] + '...') if event.message and len(event.message) > 40 else event.message
-        print(f"{last_seen:<12} {event.type:<10} {event.reason:<20} {event.object:<40} {message:<40}")
+        print(f"{last_seen:<12} {count:<7} {event.type:<10} {event.reason:<20} {event.object:<40} {message:<40}")
 
 
 

{k8stools-2.1.0 → k8stools-2.2.0}/src/k8stools/mock_state.py

@@ -48,6 +48,7 @@ import datetime
 import functools
 import gzip
 import json
+import re
 import types
 import typing
 import zlib
@@ -319,8 +320,21 @@ class MockState:
             server_start_time or datetime.datetime.now(datetime.timezone.utc),
             frozen=frozen)
 
+        #: When the capture was recorded, as the file says. Tools never report
+        #: this: on replay every datetime is re-anchored to the server's start
+        #: time (see get_cluster_info), and this is for logs and humans.
         self.captured_at: Optional[str] = data.get("captured_at")
         self.redacted: bool = bool(data.get("redacted", False))
+        # How far replay moves every datetime: capture instant -> server start.
+        # Stored datetimes are offsets and need no shift, but log lines carry
+        # their original timestamps in the text.
+        self._log_shift: Optional[datetime.timedelta] = None
+        if self.captured_at:
+            try:
+                recorded = datetime.datetime.fromisoformat(self.captured_at.replace("Z", "+00:00"))
+                self._log_shift = self._clock.server_start_time - recorded
+            except ValueError:
+                pass  # an unparseable captured_at leaves log timestamps as recorded
 
         # Index the pod records for O(1) lookup; every other list is small enough
         # to filter linearly, which keeps the filtering identical to the real tools'.
@@ -383,6 +397,12 @@ class MockState:
         ``source`` is always "capture", so an agent can tell replayed evidence
         from a live cluster. Captures taken before the cluster was recorded
         (including the built-in one) report only when they were taken.
+
+        ``captured_at`` is the replay's anchor, not the date in the file. Every
+        other datetime a tool returns is re-anchored to the server's start
+        time, and the recorded date beside them contradicted them all - a pod
+        killed "5 minutes ago" in a capture taken a month ago. The recorded
+        date is on :attr:`captured_at` and in the server's startup log.
         """
         cluster = self._data.get("cluster") or {}
         return k8s_tools.ClusterInfo(
@@ -390,7 +410,7 @@ class MockState:
             context=cluster.get("context"),
             server=cluster.get("server"),
             server_version=cluster.get("server_version"),
-            captured_at=self.captured_at,
+            captured_at=self._clock.server_start_time,
         )
 
     @_pinned_query
@@ -468,12 +488,16 @@ class MockState:
     def _event_summary(self, record: dict[str, Any],
                        object_name: Optional[str] = None) -> k8s_tools.EventSummary:
         last_seen = record.get("last_seen_seconds")
+        # Both absent from captures taken before 2.2.0; they replay as None.
+        first_seen = record.get("first_seen_seconds")
         if object_name is None:
             kind = record.get("involved_kind")
             name = record.get("involved_name") or ""
             object_name = record.get("object") or (f"{kind}/{name}" if kind else name)
         return k8s_tools.EventSummary(
             last_seen=self._clock.age(last_seen) if last_seen is not None else None,
+            first_seen=self._clock.age(first_seen) if first_seen is not None else None,
+            count=record.get("count"),
             type=record.get("type", ""),
             reason=record.get("reason", ""),
             object=object_name,
@@ -506,7 +530,8 @@ class MockState:
                     f"Error fetching logs: previous terminated instance of container "
                     f"'{container_name}' in pod '{pod_name}' not found.")
             return ''
-        return _slice_log(logs[container_name], tail=tail, since_seconds=since_seconds,
+        return _slice_log(_reanchor_log(logs[container_name], self._log_shift),
+                          tail=tail, since_seconds=since_seconds,
                           now=self._clock.server_start_time + datetime.timedelta(
                               seconds=self._clock.elapsed()))
 
@@ -689,6 +714,44 @@ def _slice_log(text: str, tail: Optional[int], since_seconds: Optional[int],
     return "\n".join(lines)
 
 
+#: The RFC 3339 timestamp the kubelet prefixes to each log line when asked for
+#: timestamps, split so the fractional digits (nanoseconds, in practice) and the
+#: zone spelling can be written back exactly as they came.
+_LOG_TS_RE = re.compile(
+    r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})(?=\s|$)")
+
+
+def _reanchor_log(text: str, shift: Optional[datetime.timedelta]) -> str:
+    """Move each line's leading timestamp by ``shift``, as replay moves every datetime.
+
+    Without this, a replayed log kept its original dates beside re-anchored pod
+    and event times, and ``since_seconds`` - compared against the replay's "now"
+    - dropped every line of any capture older than the window, returning an
+    empty log as if the container had logged nothing.
+
+    Only the kubelet's prefix is moved. Timestamps an application writes inside
+    its own message are part of the message, and stay as recorded.
+    """
+    if not shift:
+        return text
+    return "\n".join(_shift_line(line, shift) for line in text.split("\n"))
+
+
+def _shift_line(line: str, shift: datetime.timedelta) -> str:
+    m = _LOG_TS_RE.match(line)
+    if m is None:
+        return line
+    base, frac, zone = m.group(1), m.group(2) or "", m.group(3)
+    micros = int((frac + "000000")[:6])
+    stamp = datetime.datetime.fromisoformat(base + ("+00:00" if zone == "Z" else zone))
+    shifted = stamp + datetime.timedelta(microseconds=micros) + shift
+    # Same number of fractional digits as the original: microseconds from the
+    # shifted time, any digits past them (nanoseconds) kept as they were.
+    new_frac = (f"{shifted.microsecond:06d}" + frac[6:])[:len(frac)]
+    head = shifted.replace(microsecond=0).strftime("%Y-%m-%dT%H:%M:%S")
+    return head + (f".{new_frac}" if frac else "") + zone + line[m.end():]
+
+
 def _leading_timestamp(line: str) -> Optional[datetime.datetime]:
     """Parse the RFC3339 timestamp kubectl prefixes to each log line, if present."""
     token = line.split(" ", 1)[0]

{k8stools-2.1.0 → k8stools-2.2.0}/tests/test_cluster_binding.py

@@ -217,10 +217,36 @@ def test_replayed_cluster_info_says_it_is_a_capture():
     assert info.source == "capture"
     assert (info.context, info.server, info.server_version) == \
         ("prod", "https://prod.example:6443", "v1.31.2")
-    assert info.captured_at.isoformat() == "2026-09-27T21:50:53+00:00"
     assert info.kubeconfig is None
 
 
+@pytest.mark.parametrize("frozen", [True, False])
+def test_replayed_captured_at_is_on_the_same_clock_as_everything_else(frozen):
+    """Issue #7: captured_at was the date in the file while every other datetime
+    was re-anchored to the server's start, so a pod killed "5 minutes ago"
+    appeared beside a capture taken a month ago."""
+    import datetime, json
+    recorded = "2026-08-01T12:00:00+00:00"
+    start = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)
+    status = {"pod_name": "p", "namespace": "default", "container_name": "c",
+              "image": "img", "ready": False, "restart_count": 1, "started": False,
+              "stop_signal": None, "state": None, "volume_mounts": [],
+              "resource_requests": {}, "resource_limits": {}, "allocated_resources": {},
+              "last_state": {"state_name": "Terminated", "exit_code": 137,
+                             "started_at_offset_seconds": 360.0,
+                             "finished_at_offset_seconds": 297.0}}
+    state = MockState(json.loads(json.dumps({
+        "version": "1", "captured_at": recorded, "redacted": False,
+        "pods": [{"summary": {"name": "p", "namespace": "default"},
+                  "container_statuses": [status]}]})),
+        frozen=frozen, server_start_time=start)
+    captured_at = state.get_cluster_info().captured_at
+    finished_at = state.get_pod_container_statuses("p", "default")[0].last_state.finished_at
+    assert captured_at == start
+    assert captured_at - finished_at == datetime.timedelta(seconds=297)
+    assert state.captured_at == recorded   # the file's own date stays available
+
+
 def test_a_capture_without_a_cluster_record_still_answers():
     info = MockState.from_builtin(frozen=True).get_cluster_info()
     assert info.source == "capture"

k8stools-2.2.0/tests/test_events.py

@@ -0,0 +1,164 @@
+"""Tests for event aggregation: EventSummary.count and first_seen (issue #8).
+
+Kubernetes combines repeats of an event into one record. core/v1 events carry
+that in count / firstTimestamp / lastTimestamp; events recorded through
+events.k8s.io/v1 reach the core/v1 view with those unset, and carry it in
+eventTime and series instead. No cluster needed: these are fake API objects.
+"""
+
+import datetime
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from k8stools import k8s_tools
+from k8stools.capture import _capture_events, _Redactor, CaptureStats
+from k8stools.mock_state import CAPTURE_VERSION, MockState
+
+UTC = datetime.timezone.utc
+NOW = datetime.datetime.now(UTC).replace(microsecond=0)
+
+
+def _event(reason="Created", *, count=None, first=None, last=None, event_time=None,
+           series=None, name="ad-1", kind="Pod"):
+    return SimpleNamespace(
+        type="Normal", reason=reason, message=f"{reason} message",
+        involved_object=SimpleNamespace(name=name, kind=kind),
+        count=count, first_timestamp=first, last_timestamp=last,
+        event_time=event_time, series=series)
+
+
+def _ago(**kw):
+    return NOW - datetime.timedelta(**kw)
+
+
+class _FakeCore:
+    def __init__(self, events):
+        self.events = events
+
+    def list_namespaced_event(self, namespace, field_selector=None):
+        return SimpleNamespace(items=self.events)
+
+    def list_event_for_all_namespaces(self, field_selector=None):
+        return SimpleNamespace(items=self.events)
+
+
+@pytest.fixture
+def serve(monkeypatch):
+    """Serve fake events to both event tools; returns what each tool made of them."""
+    def install(*events):
+        monkeypatch.setattr(k8s_tools, "K8S", _FakeCore(list(events)))
+        return (k8s_tools.get_pod_events("ad-1", "default"),
+                k8s_tools.get_events(namespace="default"))
+    return install
+
+
+def _only(results):
+    """Both tools must agree; return the one event."""
+    pod_events, events = results
+    assert len(pod_events) == len(events) == 1
+    a, b = pod_events[0], events[0]
+    assert (a.count, a.first_seen, a.last_seen) == (b.count, b.first_seen, b.last_seen)
+    return b
+
+
+def _close(td, **kw):
+    """Within a few seconds: NOW is sampled here, the tool samples its own."""
+    return abs(td - datetime.timedelta(**kw)) < datetime.timedelta(seconds=5)
+
+
+# --- core/v1 aggregation -------------------------------------------------------
+
+def test_aggregated_event_keeps_count_and_window(serve):
+    e = _only(serve(_event(count=579, first=_ago(days=2, hours=8), last=_ago(minutes=2))))
+    assert e.count == 579
+    assert _close(e.first_seen, days=2, hours=8)
+    assert _close(e.last_seen, minutes=2)
+
+
+def test_restart_rate_is_readable_from_one_record(serve):
+    """The motivating case from the issue, with benben's numbers: ad restarted
+    579 times in 2d8h15m, i.e. every ~5.8 minutes - not "every minute"."""
+    e = _only(serve(_event(count=579, first=_ago(days=2, hours=8, minutes=17),
+                           last=_ago(minutes=2))))
+    per_restart = (e.first_seen - e.last_seen) / e.count
+    assert datetime.timedelta(minutes=5, seconds=30) < per_restart < datetime.timedelta(minutes=6)
+
+
+# --- events.k8s.io/v1 in the core/v1 view --------------------------------------
+
+def test_series_fills_in_when_the_deprecated_fields_are_empty(serve):
+    series = SimpleNamespace(count=12, last_observed_time=_ago(minutes=1))
+    e = _only(serve(_event(event_time=_ago(hours=1), series=series)))
+    assert e.count == 12
+    assert _close(e.first_seen, hours=1)
+    assert _close(e.last_seen, minutes=1)
+
+
+def test_a_single_events_k8s_io_event_counts_once_and_has_a_time(serve):
+    """No series means observed once. last_seen used to be None here, although
+    the event's time was right there in eventTime."""
+    e = _only(serve(_event(reason="Scheduled", event_time=_ago(minutes=10))))
+    assert e.count == 1
+    assert _close(e.first_seen, minutes=10) and _close(e.last_seen, minutes=10)
+
+
+def test_the_deprecated_fields_win_when_both_are_set(serve):
+    series = SimpleNamespace(count=3, last_observed_time=_ago(hours=5))
+    e = _only(serve(_event(count=40, first=_ago(hours=2), last=_ago(minutes=1),
+                           event_time=_ago(hours=9), series=series)))
+    assert e.count == 40
+    assert _close(e.first_seen, hours=2) and _close(e.last_seen, minutes=1)
+
+
+def test_an_event_with_no_times_or_count_stays_unknown(serve):
+    e = _only(serve(_event()))
+    assert (e.count, e.first_seen, e.last_seen) == (None, None, None)
+
+
+def test_docstrings_warn_that_backoff_counts_are_not_restarts():
+    """BackOff is emitted repeatedly while waiting (2561 BackOff vs 579 Created
+    for one pod on benben), so reading it as restarts overstates the rate ~4x.
+    The docstring is the MCP tool description, so the warning has to be there."""
+    for tool in (k8s_tools.get_pod_events, k8s_tools.get_events):
+        assert '"BackOff"' in tool.__doc__ and '"Created"' in tool.__doc__
+        assert "first_seen" in tool.__doc__ and "count" in tool.__doc__
+
+
+# --- capture and replay --------------------------------------------------------
+
+def _capture(events):
+    return {"version": CAPTURE_VERSION, "captured_at": NOW.isoformat(),
+            "redacted": False, "events": events}
+
+
+def test_count_and_first_seen_round_trip_and_first_seen_ages(monkeypatch):
+    monkeypatch.setattr(k8s_tools, "get_events", lambda namespace=None: [
+        k8s_tools.EventSummary(last_seen=datetime.timedelta(minutes=2),
+                               first_seen=datetime.timedelta(days=2),
+                               count=579, type="Normal", reason="Created",
+                               object="Pod/ad-1", message="Container created")])
+    records = _capture_events("default", NOW, _Redactor(False, CaptureStats()))
+    assert records[0]["count"] == 579
+    assert records[0]["first_seen_seconds"] == 2 * 86400
+
+    later = datetime.datetime.now(UTC) - datetime.timedelta(hours=1)
+    state = MockState(json.loads(json.dumps(_capture(records))), frozen=False,
+                      server_start_time=later)
+    for e in (state.get_events()[0], state.get_pod_events("ad-1", "default")[0]):
+        assert e.count == 579
+        # An age, advanced like last_seen - the window between them is unchanged.
+        assert e.first_seen == datetime.timedelta(days=2, hours=1)
+        assert e.first_seen - e.last_seen == datetime.timedelta(days=2) - datetime.timedelta(minutes=2)
+
+
+def test_a_capture_from_before_2_2_0_replays_the_new_fields_as_none():
+    state = MockState(_capture([{
+        "last_seen_seconds": 120.0, "type": "Warning", "reason": "BackOff",
+        "namespace": "default", "involved_kind": "Pod", "involved_name": "ad-1",
+        "object": "Pod/ad-1", "message": "Back-off restarting failed container"}]),
+        frozen=True)
+    e = state.get_events()[0]
+    assert (e.count, e.first_seen) == (None, None)
+    assert e.last_seen == datetime.timedelta(seconds=120)

{k8stools-2.1.0 → k8stools-2.2.0}/tests/test_k8s_tools_realk8s.py

@@ -758,3 +758,15 @@ def test_get_cluster_info():
     if info.source == "kubeconfig":
         _, current = config.list_kube_config_contexts()
         assert info.context == current["name"]
+
+def test_events_carry_count_and_first_seen():
+    """On a real cluster every event record reports how many occurrences it
+    combines, and its window runs forwards: first_seen is no newer than last_seen."""
+    events = k8s_tools.get_events()
+    if not events:
+        pytest.skip("No events found in the cluster.")
+    for event in events:
+        assert event.count is None or event.count >= 1
+        if event.first_seen is not None and event.last_seen is not None:
+            assert event.first_seen >= event.last_seen
+    assert any(e.count is not None for e in events)

{k8stools-2.1.0 → k8stools-2.2.0}/tests/test_mock_state.py

@@ -224,7 +224,62 @@ def test_since_seconds_filters_on_parseable_timestamps():
     state = MockState(_capture(pods=[_pod_with_logs({"c": "\n".join(lines)})]),
                       frozen=True, server_start_time=now)
     out = state.get_logs_for_pod_and_container("p", "default", "c", since_seconds=120)
-    assert out.splitlines() == [lines[-1]]
+    # Compare messages: replay re-anchors the prefix by the (here, microseconds)
+    # between capture and server start. See TestReplayedLogTimestamps.
+    assert [l.split(" ", 1)[1] for l in out.splitlines()] == ["at -30s"]
+
+
+class TestReplayedLogTimestamps:
+    """Log lines carry their timestamps in the text, so replay has to move them
+    the way it moves every other datetime. Before 2.2.0 it did not: a replayed
+    log kept its original dates, and since_seconds - compared against the
+    replay's "now" - dropped every line of any capture older than the window.
+    The since_seconds test above could not see it: it captures and replays at
+    the same instant."""
+
+    CAPTURED = datetime.datetime(2026, 8, 1, 12, 0, 0, tzinfo=UTC)
+
+    def _state(self, logs, previous_logs=None, frozen=True, start=None):
+        capture = _capture(pods=[_pod_with_logs(logs, previous_logs)])
+        capture["captured_at"] = self.CAPTURED.isoformat()
+        return MockState(capture, frozen=frozen,
+                         server_start_time=start or datetime.datetime.now(UTC))
+
+    def _line(self, seconds_before_capture, text, fmt="%Y-%m-%dT%H:%M:%S.%f"):
+        ts = self.CAPTURED - datetime.timedelta(seconds=seconds_before_capture)
+        return f"{ts.strftime(fmt)}123Z {text}"   # nanosecond precision, as the kubelet writes
+
+    @pytest.mark.parametrize("frozen", [True, False])
+    def test_since_seconds_works_on_an_old_capture(self, frozen):
+        lines = [self._line(s, f"at -{s}s") for s in (600, 300, 30)]
+        state = self._state({"c": "\n".join(lines)}, frozen=frozen)
+        out = state.get_logs_for_pod_and_container("p", "default", "c", since_seconds=120)
+        assert [l.split(" ", 1)[1] for l in out.splitlines()] == ["at -30s"]
+
+    def test_prefixes_move_with_the_other_replayed_datetimes(self):
+        start = datetime.datetime.now(UTC)
+        state = self._state({"c": self._line(30, "killed")}, start=start)
+        line = state.get_logs_for_pod_and_container("p", "default", "c")
+        stamp = datetime.datetime.fromisoformat(line.split(" ", 1)[0][:26] + "+00:00")
+        # 30s before capture reads as 30s before the replay's anchor, like
+        # every started_at/finished_at the tools return.
+        assert abs(stamp - (start - datetime.timedelta(seconds=30))) < datetime.timedelta(microseconds=2)
+
+    def test_format_and_message_are_preserved(self):
+        app_stamp = "2026-08-01T11:59:00Z"
+        text = "\n".join([self._line(30, f"app says {app_stamp}"), "a continuation line"])
+        out = self._state({"c": text}).get_logs_for_pod_and_container("p", "default", "c")
+        first, second = out.splitlines()
+        prefix, message = first.split(" ", 1)
+        assert len(prefix) == len("2026-08-01T11:59:30.000000123Z")
+        assert prefix.endswith("123Z")                   # nanosecond digits kept
+        assert message == f"app says {app_stamp}"         # the app's own timestamp is not ours to move
+        assert second == "a continuation line"
+
+    def test_previous_logs_are_re_anchored_too(self):
+        state = self._state({"c": "current"}, {"c": self._line(30, "the OOM")})
+        out = state.get_logs_for_pod_and_container("p", "default", "c", previous=True)
+        assert not out.startswith("2026-08-01")
 
 
 def test_since_seconds_is_ignored_when_lines_carry_no_timestamp():

{k8stools-2.1.0 → k8stools-2.2.0}/uv.lock

@@ -544,7 +544,7 @@ wheels = [
 
 [[package]]
 name = "k8stools"
-version = "2.1.0"
+version = "2.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "kubernetes" },