Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

4.5 KB
Raw Blame
"""Connect-time merge support for thin-tail task run streams.

A thin-tail run keeps only a short live tail in Redis and serves history from
the durable run log. The agent stamps a shared ``event_id`` on each event in
both stores (format ``<boot>-<seq>``: a random per-boot prefix and a counter
monotonic within that boot). A log entry coalesced from a run of chunk events
carries the covered range as ``first_event_id``..``event_id``.

``TaskRunStreamBacklogIndex`` collects the ids (and ranges) present in the log
backlog so the SSE view can drop live-tail entries the backlog already covers.
Entries without ids (older agents, server-published events) are never dropped.
"""

TASK_RUN_STREAM_LOG_CURSOR_PREFIX = "log-"

STREAMING_CHUNK_UPDATES = frozenset({"agent_message_chunk", "agent_thought_chunk"})


def session_update_type(event: dict) -> str | None:
    notification = event.get("notification")
    if not isinstance(notification, dict) or notification.get("method") != "session/update":
        return None
    params = notification.get("params")
    update = params.get("update") if isinstance(params, dict) else None
    session_update = update.get("sessionUpdate") if isinstance(update, dict) else None
    return session_update if isinstance(session_update, str) else None


def _parse_event_id(event_id: str) -> tuple[str, int] | None:
    boot, _, seq = event_id.rpartition("-")
    if not boot:
        return None
    try:
        return boot, int(seq)
    except ValueError:
        return None


def parse_log_cursor(last_event_id: str) -> int | None:
    """Index of the last served backlog entry, or ``None`` for any other cursor.

    Accepts only what ``format_log_cursor`` emits: plain non-negative ASCII
    decimals. ``int()`` alone would also take signs, whitespace, underscores and
    non-ASCII digits, turning a caller-supplied header into a negative or
    out-of-range list index downstream.
    """
    if not last_event_id.startswith(TASK_RUN_STREAM_LOG_CURSOR_PREFIX):
        return None
    suffix = last_event_id[len(TASK_RUN_STREAM_LOG_CURSOR_PREFIX) :]
    if not suffix.isascii() or not suffix.isdigit():
        return None
    return int(suffix)


def format_log_cursor(index: int) -> str:
    return f"{TASK_RUN_STREAM_LOG_CURSOR_PREFIX}{index}"


class TaskRunStreamBacklogIndex:
    def __init__(self, entries: list[dict]) -> None:
        self._ids: set[str] = set()
        self._ranges: dict[str, list[tuple[int, int]]] = {}
        for entry in entries:
            event_id = entry.get("event_id")
            if not isinstance(event_id, str) or not event_id:
                continue
            self._ids.add(event_id)
            first_event_id = entry.get("first_event_id")
            if not isinstance(first_event_id, str) or not first_event_id:
                continue
            first = _parse_event_id(first_event_id)
            last = _parse_event_id(event_id)
            if first is None or last is None or first[0] != last[0]:
                self._ids.add(first_event_id)
                continue
            self._ranges.setdefault(first[0], []).append((first[1], last[1]))

    def covers(self, event: dict) -> bool:
        event_id = event.get("event_id")
        if not isinstance(event_id, str) or not event_id:
            return False
        if event_id in self._ids:
            return True
        parsed = _parse_event_id(event_id)
        if parsed is None:
            return False
        return self._covers_parsed(*parsed)

    def has_gap_before(self, event: dict) -> bool:
        """True when the oldest id-carrying tail entry shows the log lagging behind the Redis trim.

        A covered entry means the log reaches into the tail; a streaming chunk means an
        in-flight message outgrew the tail, which the log only carries once it completes.
        Otherwise a missing per-boot predecessor is the loss mode thin-tail trimming cannot rule out.
        """
        event_id = event.get("event_id")
        if not isinstance(event_id, str) or not event_id:
            return False
        parsed = _parse_event_id(event_id)
        if parsed is None:
            return False
        boot, seq = parsed
        if seq <= 1 or self._covers_parsed(boot, seq):
            return False
        if session_update_type(event) in STREAMING_CHUNK_UPDATES:
            return False
        return not self._covers_parsed(boot, seq - 1)

    def _covers_parsed(self, boot: str, seq: int) -> bool:
        if f"{boot}-{seq}" in self._ids:
            return True
        return any(lo <= seq <= hi for lo, hi in self._ranges.get(boot, ()))