Files
skills/orchestrator/kvb_orchestrator/receipts.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 30b2a32095 feat(orchestrator): radio receipts inline (005 phase B)
Requirement 005: every radio message in the Stream and the radio log shows the avatars of the agents that read it, with read time and an ack badge where a receipt exists; receipt rows no longer appear as entries of their own, and the sender shows once. Read times come from seen marks, stamped only after a fresh presence pass no older than two sighting intervals; a stored time before its row is refused. An operator message links to its relay row through the ts radio.py prints first on stdout right after store(), checked against an exact row (sender Operator, relay text, targets, no to_sessions); a ts shared by two rows shows no readers. radio.py clips printed addresses; the hub keeps the first stdout line whole. Accepted MEDUSA false positives: MM-SCAN-058 at server.py:73, JB-SCAN-641 and JB-SCAN-616 at radio.py:389 (clip, the output sanitizer), FLA-SCAN-055 at radio.py:109. Committed below the 90/5 bar on the operator's word; the receipts e2e runs through the queue.

🎯 Fix: 89 %
💥 Break: 6 %
💸 Cost: –
⏱️ Time: –
🛡️ Security: 100 %
🏆 Score: 84
🚦 Gate: ⛔ fix 89 % < 90, break 6 % > 5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 17:19:39 +00:00

423 lines
19 KiB
Python

from __future__ import annotations
import functools
import inspect
import json
import math
import os
import sys
import threading
import time
from collections import Counter
from collections.abc import Callable
from pathlib import Path
from types import ModuleType
from .council import NEWS, RECEIPT
from .names import PSEUDO, SESSION_ID, Directory, Names
from .presence import fresh_snapshot, read_snapshot
from .records import epoch, read_json, read_jsonl, read_regular, write_atomic
from .skill_scripts import RADIO, script_module
SEEN = "radio-seen"
PROMPT = "news-seen"
NAMES = "receipt-names.json"
READS = "receipt-reads.json"
READ_ENTRIES = 32768
LOG_CHARS = 300
SNAPSHOT_SOURCE = "session"
PROMPT_BYTES = 64
STATE_BYTES = 4096
CACHED = 4096
SIGHTING = 15.0
LOOKED_AGE = 2 * SIGHTING
KEPT = 7 * 86400
ENTRIES = 4096
STEP = 3600.0
NAME_CHARS = 200
SEEN_PARAMETERS = ("row", "name", "sid", "prompt", "state", "since")
Marks = tuple[float | None, dict[str, float]]
Stamp = tuple[int, int, int]
def radio_module(skills: Path) -> ModuleType | None:
"""Args:
skills: the installed skills directory, the hub's --skills mount.
Returns:
Its kvb-org-radio radio.py as a module, the same file the hooks run;
None when it is missing, does not load or its seen() does not take
SEEN_PARAMETERS, as after an install of other skills than the hub's.
"""
module = script_module(skills / RADIO)
seen = getattr(module, "seen", None)
try:
parameters = tuple(inspect.signature(seen).parameters) if callable(seen) else ()
except (TypeError, ValueError):
return None
return module if parameters == SEEN_PARAMETERS else None
def moment(value: object, now: float) -> float | None:
found = epoch(value)
return found if found is not None and found <= now else None
def stamp(path: Path) -> Stamp | None:
try:
found = os.lstat(path)
except OSError:
return None
return found.st_ino, found.st_mtime_ns, found.st_size
@functools.lru_cache(maxsize=CACHED)
def parsed_prompt(path: Path, version: Stamp) -> float | None:
try:
return float(read_regular(path, PROMPT_BYTES))
except (OSError, ValueError):
return None
@functools.lru_cache(maxsize=CACHED)
def parsed_state(path: Path, version: Stamp) -> object:
try:
return json.loads(read_regular(path, STATE_BYTES))
except (OSError, ValueError, RecursionError):
return None
def prompt_of(path: Path, now: float) -> float | None:
version = stamp(path)
return None if version is None else moment(parsed_prompt(path, version), now)
def state_of(path: Path, now: float) -> dict[str, float]:
version = stamp(path)
data = None if version is None else parsed_state(path, version)
if not isinstance(data, dict):
return {}
return {key: found for key, value in data.items() if (found := moment(value, now)) is not None}
def read_marks(council: Path, now: float) -> dict[str, Marks]:
"""Args:
council: the council directory with radio-seen/<sid>.json and the
older news-seen/<sid>.
now: the moment to judge at.
Returns:
Per session id with a mark file its prompt mark and its radio-seen
marks; a missing, malformed, unreadable, non-regular, oversized or
future-dated mark is left out, a prompt mark then None. A file is
parsed again only after its inode, mtime or size changed.
"""
sids = {path.stem for path in (council / SEEN).glob("*.json")} | {path.name for path in (council / PROMPT).glob("*")}
return {sid: (prompt_of(council / PROMPT / sid, now), state_of(council / SEEN / f"{sid}.json", now)) for sid in sorted(sids)}
def fits(sid: str, name: object) -> bool:
return bool(SESSION_ID.fullmatch(sid)) and isinstance(name, str) and 0 < len(name) <= NAME_CHARS
class ReceiptNames(Names):
def __init__(self, file: Path) -> None:
"""Args:
file: the hub's receipt name store; beside the Names history it
keeps each session's last sighting under sighted. An entry or
observed name whose session id is not of SESSION_ID or whose
name is not 1 to NAME_CHARS characters, and a malformed
sighting are left out.
"""
super().__init__(file)
self.entries = [entry for entry in self.entries if fits(entry["session"], entry["name"])]
self.observed = {key: name for key, name in self.observed.items() if fits(key.partition("\x00")[0], name)}
sighted = self.data.get("sighted")
self.sighted: dict[str, float] = {sid: when for sid, value in sighted.items() if SESSION_ID.fullmatch(sid) and (when := epoch(value)) is not None} if isinstance(sighted, dict) else {}
def payload(self) -> dict:
return {**super().payload(), "sighted": self.sighted}
def keep(self, live: list[str], now: float) -> None:
"""Args:
live: the sessions of the snapshot, sighted at now; a sighting is
stored at most every STEP seconds, and a session without one
counts as sighted now.
now: the moment of the sighting; a sighting after it counts as at
it, a session not sighted for KEPT seconds loses its entries,
and past ENTRIES entries the sessions sighted longest ago lose
theirs first.
"""
seen = set(live)
with self.lock:
future = {sid for sid, last in self.sighted.items() if last > now}
changed = bool(future)
self.sighted.update(dict.fromkeys(future, now))
sessions = {entry["session"] for entry in self.entries}
for sid in sorted(sessions | seen):
last = self.sighted.get(sid)
if last is None or (sid in seen and now - last >= STEP):
self.sighted[sid] = now
changed = True
gone = {sid for sid, last in self.sighted.items() if now - last > KEPT or sid not in sessions}
counts = Counter(entry["session"] for entry in self.entries if entry["session"] not in gone)
total = sum(counts.values())
for sid in sorted(counts, key=lambda sid: (self.sighted[sid], sid)):
if total <= ENTRIES:
break
gone.add(sid)
total -= counts[sid]
if gone:
self.entries = [entry for entry in self.entries if entry["session"] not in gone]
self.observed = {key: name for key, name in self.observed.items() if key.partition("\x00")[0] not in gone}
self.sighted = {sid: last for sid, last in self.sighted.items() if sid not in gone}
changed = True
if changed:
self.save()
def sightings(sessions: dict[str, dict]) -> list[tuple[str, str, None, str]]:
return [(sid, record["name"], None, SNAPSHOT_SOURCE) for sid, record in sessions.items() if fits(sid, record.get("name"))]
def stored_read(entry: object) -> tuple[tuple[str, float], float | None] | None:
if not isinstance(entry, list) or len(entry) != 3 or not isinstance(entry[0], str) or not SESSION_ID.fullmatch(entry[0]):
return None
ts, when = epoch(entry[1]), epoch(entry[2])
if ts is None or (when is None and entry[2] is not None) or (when is not None and when < ts):
return None
return (entry[0], ts), when
def clamped(times: dict[tuple[str, float], float | None], now: float) -> dict[tuple[str, float], float | None]:
return {key: when if when is None or when <= now else now for key, when in times.items()}
class ReceiptReads:
def __init__(self, file: Path) -> None:
"""Args:
file: the hub's read time store, {"reads": [[session id, row ts,
first sighting or null]]}; an entry of another shape, a
session id not of SESSION_ID, a time that is no epoch or a
sighting before its row is left out.
"""
self.file = file
self.lock = threading.Lock()
self.looked: float | None = None
self.floor = -math.inf
data = read_json(file)
reads = data.get("reads") if isinstance(data, dict) else None
self.times: dict[tuple[str, float], float | None] = dict(found for entry in reads if (found := stored_read(entry))) if isinstance(reads, list) else {}
def listed(self, now: float) -> dict[tuple[str, float], float | None]:
"""Returns:
Per (session id, row ts) its first sighting, one after now as
now.
"""
with self.lock:
return clamped(self.times, now)
def blind(self) -> None:
with self.lock:
self.looked = None
def see(self, covered: set[tuple[str, float]], now: float, begin: float, fresh: bool) -> None:
"""Args:
covered: (session id, row ts) of each row a mark of the session
covers now.
now: the moment of the sighting pass; a pair not stored yet is
stored with it, with None unless the previous pass of this
process read a fresh snapshot at most LOOKED_AGE seconds
before, since it was read at an unknown time before the hub
looked, as across a frozen hub; a stored sighting after it is
stored as it.
begin: the start of the radio window; pairs of older rows go, and
past READ_ENTRIES those of the oldest rows, which then never
come back with a later time.
fresh: whether this pass read a fresh session snapshot.
"""
with self.lock:
when = now if self.looked is not None and 0 <= now - self.looked <= LOOKED_AGE else None
self.floor = max(self.floor, begin)
times = {key: value for key, value in clamped(self.times, now).items() if key[1] >= self.floor}
times.update({key: when for key in covered if key[1] >= self.floor and key not in times})
if len(times) > READ_ENTRIES:
self.floor = math.nextafter(sorted(key[1] for key in times)[-READ_ENTRIES - 1], math.inf)
times = {key: value for key, value in times.items() if key[1] >= self.floor}
self.looked = now if fresh else None
if times != self.times:
self.times = times
write_atomic(self.file, json.dumps({"reads": [[sid, ts, read] for (sid, ts), read in sorted(times.items())]}).encode("utf-8"))
def session_directory(store: ReceiptNames, sessions: dict[str, dict], now: float) -> Directory:
"""Args:
store: the hub's own name file for receipts, apart from the claim and
title history, which any agent can feed through a claim file.
sessions: read_snapshot(), written on the host from Claude Code's
sessions; each record's name is the one radio.py's name_of()
reads, kept as is, so rows and receipts match it unnormalized; a
record without a session id of SESSION_ID or a name of 1 to
NAME_CHARS characters is left out.
now: the moment of the sighting.
Returns:
The store's history from snapshot sightings alone, the names of
ended sessions included until ReceiptNames.keep() drops them.
"""
found = sightings(sessions)
store.observe(found, now)
store.keep([sid for sid, *_ in found], now)
return Directory([entry for entry in store.listed() if entry["source"] == SNAPSHOT_SOURCE])
def first_known(directory: Directory, sid: str, first: dict[str, float]) -> float:
if sid not in first:
first[sid] = directory.timeline(sid)[0]["since"]
return first[sid]
def owners(directory: Directory, sender: str, ts: float, sessions: set[str], first: dict[str, float]) -> list[str]:
held = [sid for sid in sorted(directory.aliases(sender)) if not sid.startswith(PSEUDO) and directory.at(sid, ts) == sender]
strict = [sid for sid in held if first_known(directory, sid, first) <= ts]
return strict or held or ([sender] if sender in sessions else [])
def acknowledged(radio: ModuleType, rows: list[dict], sessions: set[str], directory: Directory) -> dict[float, dict[str, float]]:
found: dict[float, dict[str, float]] = {}
first: dict[str, float] = {}
for row in rows:
call, sender, ts = epoch(row.get("call")), row.get("from"), epoch(row["ts"])
if radio.kind(row) != RECEIPT or call is None or not isinstance(sender, str):
continue
for owner in owners(directory, sender, ts, sessions, first):
found.setdefault(call, {}).setdefault(owner, ts)
return found
def reader(radio: ModuleType, row: dict, sid: str, name: str, marks: Marks, acked: dict[str, float], sighted: dict[tuple[str, float], float | None]) -> dict | None:
prompt, state = marks
if not radio.seen(row, name, sid, radio.NEVER if prompt is None else prompt, state, radio.NEVER):
return None
if sid in acked:
return {"session": sid, "name": name, "read": acked[sid], "approximate": False}
when = sighted.get((sid, epoch(row["ts"])))
return {"session": sid, "name": name, "read": when, "approximate": when is not None}
def order(entry: dict) -> tuple:
return entry["read"] is None, entry["read"] or 0.0, entry["name"], entry["session"]
def readers_and_acks(radio: ModuleType, news: list[dict], window: tuple[float, float], marks: dict[str, Marks], directory: Directory, sighted: dict[tuple[str, float], float | None]) -> dict[float, dict]:
"""Args:
radio: radio_module(); its seen() decides whether a session read a
row, with the marks alone and no delivery window.
news: every news.jsonl row; a receipt counts for its call even when
it lies outside the window.
window: (begin, end); each row inside it but a receipt gets an entry.
marks: read_marks() of the sessions.
directory: session_directory(); a session goes by the name it held
at the row's time, after it ended too, and by its id without one,
as radio.py's name_of(); a receipt belongs to the
sessions known to hold its sender's name by its time, else to
those whose first known name it is.
sighted: ReceiptReads.listed(), per (session id, row ts) the first
sighting pass that found a mark covering the row.
Returns:
Per row ts {"readers": [{"session", "name", "read", "approximate"}],
"acks": [session ids]}: acks the sessions with a receipt whose call is
that ts; read the first such receipt's ts, else its sighting with
approximate true, else None, never a mark, which holds a send time.
A ts more than one row carries gets no entry: radio.py never stores
two rows at one ts, so a row appended with a genuine ts can neither
replace nor lend its readers and acks.
"""
begin, end = window
rows = [row for row in news if epoch(row.get("ts")) is not None]
shared = {ts for ts, count in Counter(epoch(row["ts"]) for row in rows).items() if count > 1}
acks = acknowledged(radio, rows, set(marks), directory)
reach = {sid: max(radio.NEVER if prompt is None else prompt, radio.NEVER, *state.values()) for sid, (prompt, state) in marks.items()}
found = {}
for row in rows:
ts = epoch(row["ts"])
if radio.kind(row) == RECEIPT or not begin <= ts <= end or ts in shared:
continue
acked = acks.get(ts, {})
readers = [entry for sid, held in marks.items() if ts <= reach[sid] and (entry := reader(radio, row, sid, directory.at(sid, ts) or sid, held, acked, sighted))]
found[ts] = {"readers": sorted(readers, key=order), "acks": sorted(acked)}
return found
def inline(skills: Path, council: Path, store: ReceiptNames, reads: ReceiptReads, snapshot: Path, news: list[dict], window: tuple[float, float], now: float) -> dict[float, dict]:
"""Args:
skills: the installed skills directory, for radio_module().
council: the council directory holding the seen marks.
store: the hub's receipt name store, NAMES in its state directory.
reads: the hub's read time store, READS in its state directory.
snapshot: agent-sessions.json, the host's session snapshot.
news: every news.jsonl row.
window: (begin, end) of the rows the hub serves.
now: the moment to judge at.
Returns:
readers_and_acks() of the rows; empty while radio.py is missing or
its seen() does not take SEEN_PARAMETERS.
"""
radio = radio_module(skills)
if radio is None:
return {}
directory = session_directory(store, read_snapshot(snapshot, now), now)
return readers_and_acks(radio, news, window, read_marks(council, now), directory, reads.listed(now))
def read_of(inlined: dict[float, dict], ts: float | None) -> dict:
return inlined.get(ts, {"readers": [], "acks": []})
def sighting_pass(skills: Path, council: Path, store: ReceiptNames, reads: ReceiptReads, snapshot: Path, window: float, now: float) -> None:
"""Args:
skills: the installed skills directory, for radio_module().
council: the council directory with news.jsonl and the seen marks.
store: the hub's receipt name store; the pass records the snapshot's
names in it, so a session that left before the next state build
keeps its name.
reads: the hub's read time store; the pass records each row of the
last window seconds a mark newly covers.
snapshot: agent-sessions.json, which the host rewrites every 15
seconds; a pass without a fresh one or without radio_module()
counts as one that did not look.
window: seconds of rows the pass looks at, the hub's radio window.
now: the moment of the pass.
"""
sessions = fresh_snapshot(snapshot, now)
directory = session_directory(store, sessions or {}, now)
radio = radio_module(skills)
if radio is None:
reads.see(set(), now, now - window, False)
return
found = readers_and_acks(radio, read_jsonl(council / NEWS), (now - window, now), read_marks(council, now), directory, {})
reads.see({(entry["session"], ts) for ts, row in found.items() for entry in row["readers"]}, now, now - window, sessions is not None)
def sight(step: Callable[[float], None], reads: ReceiptReads, stop: threading.Event, every: float) -> None:
"""Args:
step: one sighting pass, called with its moment; a pass that fails
for any reason but SystemExit or KeyboardInterrupt logs one line
to stderr and the next one runs.
reads: the read time store the passes feed; a failed pass counts as
one that did not look.
stop: ends the loop once set.
every: seconds between two passes.
"""
while True:
try:
step(time.time())
except Exception as error: # noqa: BLE001
reads.blind()
print(f"receipts: sighting pass failed: {error!r}"[:LOG_CHARS], file=sys.stderr, flush=True)
if stop.wait(every):
return