kvb-org-radio is the default channel to other agents: broadcast and direct reach the receiver on its next prompt, security and pan-pan mid-turn through a PostToolBatch hook, and only mayday or direct --wake wake a session, through the receiver's own asyncRewake Stop hook (a SendMessage fallback is printed for sessions without a listener). It keeps the news.jsonl store and lock, so news.py stays a forwarding shim. A mayday holds radio silence for two hours: watch.py blocks new heavy commands and the operator gets a desktop notice. hotfix.py announces merged hotfixes as security items. kvb-org-queue grants heavy jobs by rule instead of chair messages: queue.py hold waits under a flock with disk reservation, hotfix-first and register rank order, slot limits, stage and silence checks, then runs the command and releases. Every job is recorded; history.py learns disk need per command and slot limits per kind (p90, five runs), watch.py mirrors the history to ~/.local/state. enable-plugins.js registers the new hooks behind a file check so a missing script never blocks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
474 lines
16 KiB
Python
Executable File
474 lines
16 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Reach other agents by radio: five classes, from a board line to a wake, in one shared store.
|
|
|
|
Environment:
|
|
AGENTS_COUNCIL_ROOT: council directory shared by every agent on the host;
|
|
/tmp/agents-council unless set. Rows live in <root>/news.jsonl under
|
|
<root>/news.lock, the store the old news.py reads and writes too.
|
|
AGENTS_COUNCIL_CONFIG: config file whose "notify" argv tells the operator
|
|
of a mayday; ~/.config/agents-council/config.json unless set.
|
|
CLAUDE_CODE_SESSION_ID: the calling session; hooks read the payload's
|
|
session_id first, other runtimes pass --session.
|
|
|
|
Args:
|
|
send <class> "<text>" [--to <name> ...] [--wake] [--session <id>]: add a
|
|
row. broadcast, security, pan-pan and mayday go to all and take no
|
|
--to; direct needs --to; --wake only with direct. mayday also sets
|
|
radio silence (<root>/radio-silence.json) for two hours. A wake
|
|
(mayday, direct --wake) then prints `wake: SendMessage to <name>`
|
|
for every addressee without a live listener.
|
|
post "<text>" [--to <name> ...] [--session <id>]: send broadcast, or
|
|
direct with --to.
|
|
clear [--force] [--session <id>]: end radio silence; its sender may,
|
|
anyone else only with --force.
|
|
hook: UserPromptSubmit hook; prints the active silence and the unseen
|
|
rows, mayday, pan-pan and security first, at most 10, and marks them
|
|
seen. Never fails the prompt.
|
|
tool: PostToolBatch hook; prints the unseen urgent rows as
|
|
additionalContext. Never fails.
|
|
listen: Stop hook with asyncRewake; polls every POLL_SECONDS until a
|
|
mayday or a direct --wake reaches this session, prints it to stderr
|
|
and exits 2; exits 0 once a newer listener of the session took over.
|
|
show [--all] [--session <id>]: print the active silence and the unseen
|
|
rows, or every kept row, without marking them.
|
|
|
|
Exit codes:
|
|
0 done, 2 usage error (listen: wake the session), 3 radio silence held
|
|
by another session.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import contextlib
|
|
import datetime
|
|
import fcntl
|
|
import functools
|
|
import importlib.util
|
|
import json
|
|
import math
|
|
import os
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
import time
|
|
from collections.abc import Iterator
|
|
from pathlib import Path
|
|
from types import ModuleType
|
|
|
|
# Every agent on the host must agree on one council directory and one config without being told.
|
|
ROOT = Path(os.environ.get("AGENTS_COUNCIL_ROOT", "/tmp/agents-council"))
|
|
CONFIG = Path(
|
|
os.environ.get("AGENTS_COUNCIL_CONFIG", str(Path.home() / ".config" / "agents-council" / "config.json"))
|
|
)
|
|
NEWS = ROOT / "news.jsonl"
|
|
LOCK = ROOT / "news.lock"
|
|
SEEN = ROOT / "news-seen"
|
|
STATE = ROOT / "radio-seen"
|
|
LISTEN = ROOT / "radio-listen"
|
|
SILENCE = ROOT / "radio-silence.json"
|
|
NOTIFIED = ROOT / "radio-notified"
|
|
COUNCIL = Path(__file__).resolve().parents[2] / "kvb-org-organize" / "scripts" / "council.py"
|
|
CLASSES = ("broadcast", "direct", "security", "pan-pan", "mayday")
|
|
URGENT = ("mayday", "pan-pan", "security")
|
|
WINDOW = 86400
|
|
SHOWN = 10
|
|
KEPT = 500
|
|
SILENCE_SECONDS = 7200
|
|
NOTIFY_SECONDS = 10
|
|
POLL_SECONDS = 15
|
|
NEVER = 0.0
|
|
|
|
|
|
def fail(message: str) -> None:
|
|
print(f"radio: {message}", file=sys.stderr)
|
|
sys.exit(2)
|
|
|
|
|
|
@functools.cache
|
|
def council() -> ModuleType:
|
|
spec = importlib.util.spec_from_file_location("council", COUNCIL)
|
|
module = importlib.util.module_from_spec(spec)
|
|
spec.loader.exec_module(module)
|
|
return module
|
|
|
|
|
|
def name_of(sid: str) -> str:
|
|
return council().live_sessions().get(sid) or sid
|
|
|
|
|
|
def items() -> list[dict]:
|
|
try:
|
|
lines = NEWS.read_text(encoding="utf-8").splitlines()
|
|
except OSError:
|
|
return []
|
|
rows = []
|
|
for line in lines:
|
|
try:
|
|
row = json.loads(line)
|
|
except ValueError:
|
|
continue
|
|
if isinstance(row, dict) and isinstance(row.get("ts"), int | float):
|
|
rows.append(row)
|
|
return rows
|
|
|
|
|
|
def kind(row: dict) -> str:
|
|
if row.get("class") in CLASSES:
|
|
return row["class"]
|
|
return "direct" if row.get("to") else "broadcast"
|
|
|
|
|
|
def urgent(row: dict) -> bool:
|
|
return kind(row) in URGENT
|
|
|
|
|
|
def rank(row: dict) -> int:
|
|
return URGENT.index(kind(row)) if urgent(row) else len(URGENT)
|
|
|
|
|
|
def ordered(rows: list[dict]) -> list[dict]:
|
|
return sorted(rows, key=lambda row: (rank(row), row["ts"]))
|
|
|
|
|
|
def clock(ts: float) -> str:
|
|
return datetime.datetime.fromtimestamp(ts).strftime("%H:%M")
|
|
|
|
|
|
def line(row: dict) -> str:
|
|
target = f" to {', '.join(row['to'])}" if row.get("to") else ""
|
|
return f"RADIO {kind(row).upper()} {clock(row['ts'])} {row.get('from')}{target}: {row.get('text')}"
|
|
|
|
|
|
def for_me(row: dict, name: str) -> bool:
|
|
return row.get("from") != name and (not row.get("to") or name in row["to"])
|
|
|
|
|
|
def read_json(path: Path) -> dict:
|
|
try:
|
|
data = json.loads(path.read_text(encoding="utf-8"))
|
|
except (OSError, ValueError):
|
|
return {}
|
|
return data if isinstance(data, dict) else {}
|
|
|
|
|
|
def write_atomic(path: Path, text: str) -> None:
|
|
with tempfile.NamedTemporaryFile("w", dir=path.parent, delete=False, encoding="utf-8") as handle:
|
|
handle.write(text)
|
|
os.replace(handle.name, path)
|
|
|
|
|
|
def prompt_mark(sid: str) -> float:
|
|
try:
|
|
return float((SEEN / sid).read_text(encoding="utf-8"))
|
|
except (OSError, ValueError):
|
|
return NEVER
|
|
|
|
|
|
def mark(state: dict, key: str) -> float:
|
|
value = state.get(key)
|
|
return NEVER if value is None else value
|
|
|
|
|
|
def news_mtime() -> float | None:
|
|
try:
|
|
return NEWS.stat().st_mtime
|
|
except FileNotFoundError:
|
|
return None
|
|
|
|
|
|
@contextlib.contextmanager
|
|
def session(sid: str) -> Iterator[dict]:
|
|
STATE.mkdir(parents=True, exist_ok=True)
|
|
with (STATE / f"{sid}.lock").open("w") as lock:
|
|
fcntl.flock(lock, fcntl.LOCK_EX)
|
|
yield read_json(STATE / f"{sid}.json")
|
|
|
|
|
|
def save(sid: str, state: dict) -> None:
|
|
write_atomic(STATE / f"{sid}.json", json.dumps(state))
|
|
|
|
|
|
def hook_session() -> str | None:
|
|
payload = json.load(sys.stdin)
|
|
if payload.get("agent_id"):
|
|
return None
|
|
return payload.get("session_id") or os.environ.get("CLAUDE_CODE_SESSION_ID")
|
|
|
|
|
|
def silence() -> dict | None:
|
|
state = read_json(SILENCE)
|
|
until = state.get("until")
|
|
return state if isinstance(until, int | float) and until > time.time() else None
|
|
|
|
|
|
def silence_line(active: dict) -> str:
|
|
return (
|
|
f"MAYDAY ACTIVE since {clock(active['since'])} by {active['by']}: {active['text']}; "
|
|
"no new heavy jobs until radio.py clear"
|
|
)
|
|
|
|
|
|
def notify_once(active: dict | None) -> None:
|
|
if active is None:
|
|
return
|
|
try:
|
|
argv = json.loads(CONFIG.read_text(encoding="utf-8"))["notify"]
|
|
NOTIFIED.mkdir(parents=True, exist_ok=True)
|
|
os.close(os.open(NOTIFIED / str(active["since"]), os.O_CREAT | os.O_EXCL | os.O_WRONLY))
|
|
subprocess.run(
|
|
[*argv, f"Agents radio MAYDAY by {active['by']}: {active['text']}"],
|
|
capture_output=True,
|
|
timeout=NOTIFY_SECONDS,
|
|
check=False,
|
|
)
|
|
except (OSError, ValueError, KeyError, TypeError, subprocess.TimeoutExpired):
|
|
return
|
|
|
|
|
|
def listening(sid: str) -> bool:
|
|
try:
|
|
pid = int((LISTEN / f"{sid}.pid").read_text(encoding="utf-8"))
|
|
except (OSError, ValueError):
|
|
return False
|
|
if pid <= 0:
|
|
return False
|
|
try:
|
|
os.kill(pid, 0)
|
|
except PermissionError:
|
|
return True
|
|
except OSError:
|
|
return False
|
|
return True
|
|
|
|
|
|
def unreached(cls: str, to: list[str], sender: str) -> list[str]:
|
|
live = council().live_sessions()
|
|
if cls == "mayday":
|
|
targets = [(name or sid, [sid]) for sid, name in live.items() if sid != sender]
|
|
else:
|
|
targets = [(name, [sid for sid, label in live.items() if name in (label, sid)]) for name in to]
|
|
return [name for name, sids in targets if not any(map(listening, sids))]
|
|
|
|
|
|
def cmd_send(args: argparse.Namespace) -> int:
|
|
to = args.to or []
|
|
if args.cls == "direct" and not to:
|
|
fail("direct needs --to")
|
|
if args.cls != "direct" and to:
|
|
fail(f"{args.cls} goes to all; drop --to")
|
|
if args.wake and args.cls != "direct":
|
|
fail("--wake only with direct")
|
|
text = " ".join(args.text.split())
|
|
if not text:
|
|
fail(f"{args.cls} needs a text")
|
|
sid, _ = council().caller(args.session)
|
|
sender = name_of(sid)
|
|
ROOT.mkdir(parents=True, exist_ok=True)
|
|
with LOCK.open("w") as lock:
|
|
fcntl.flock(lock, fcntl.LOCK_EX)
|
|
rows = items()
|
|
ts = time.time()
|
|
if rows:
|
|
ts = max(ts, math.nextafter(max(row["ts"] for row in rows), math.inf))
|
|
entry = {"ts": ts, "from": sender, "to": to, "text": text, "class": args.cls}
|
|
if args.wake:
|
|
entry["wake"] = True
|
|
write_atomic(NEWS, "".join(json.dumps(row) + "\n" for row in [*rows[-(KEPT - 1):], entry]))
|
|
if args.cls == "mayday":
|
|
write_atomic(
|
|
SILENCE,
|
|
json.dumps({"since": ts, "until": ts + SILENCE_SECONDS, "by": sender, "text": text}),
|
|
)
|
|
print(f"sent {args.cls} to {', '.join(to) or 'all'}")
|
|
if args.wake or args.cls == "mayday":
|
|
for name in unreached(args.cls, to, sid):
|
|
print(f"wake: SendMessage to {name}")
|
|
return 0
|
|
|
|
|
|
def cmd_post(args: argparse.Namespace) -> int:
|
|
args.cls = "direct" if args.to else "broadcast"
|
|
args.wake = False
|
|
return cmd_send(args)
|
|
|
|
|
|
def cmd_clear(args: argparse.Namespace) -> int:
|
|
sid, _ = council().caller(args.session)
|
|
me = name_of(sid)
|
|
ROOT.mkdir(parents=True, exist_ok=True)
|
|
with LOCK.open("w") as lock:
|
|
fcntl.flock(lock, fcntl.LOCK_EX)
|
|
active = silence()
|
|
if active is None:
|
|
print("no radio silence active")
|
|
return 0
|
|
if active["by"] != me and not args.force:
|
|
print(f"radio silence held by {active['by']}; only they clear it, anyone else with --force")
|
|
return 3
|
|
SILENCE.unlink(missing_ok=True)
|
|
forced = f", forced by {me}" if active["by"] != me else ""
|
|
print(f"cleared radio silence by {active['by']}{forced}")
|
|
return 0
|
|
|
|
|
|
def unseen(sid: str, name: str) -> list[dict]:
|
|
floor = max(prompt_mark(sid), time.time() - WINDOW)
|
|
return [row for row in items() if row["ts"] > floor and for_me(row, name)]
|
|
|
|
|
|
def delivered(row: dict, state: dict) -> bool:
|
|
if urgent(row):
|
|
return row["ts"] <= mark(state, "urgent")
|
|
return bool(row.get("wake")) and row["ts"] <= mark(state, "listen")
|
|
|
|
|
|
def cmd_hook(_: argparse.Namespace) -> int:
|
|
try:
|
|
sid = hook_session()
|
|
if not sid:
|
|
return 0
|
|
active = silence()
|
|
out = [silence_line(active)] if active else []
|
|
name = name_of(sid)
|
|
with session(sid) as state:
|
|
rows = unseen(sid, name)
|
|
fresh = [row for row in rows if not delivered(row, state)]
|
|
picked = sorted(fresh, key=lambda row: (rank(row), -row["ts"]))[:SHOWN]
|
|
out += [line(row) for row in ordered(picked)]
|
|
if len(fresh) > SHOWN:
|
|
out.append(f"RADIO {len(fresh) - SHOWN} more items: radio.py show --all")
|
|
if rows:
|
|
SEEN.mkdir(parents=True, exist_ok=True)
|
|
(SEEN / sid).write_text(str(max(row["ts"] for row in rows)), encoding="utf-8")
|
|
if out:
|
|
print("\n".join(out))
|
|
notify_once(active)
|
|
except Exception: # noqa: BLE001
|
|
return 0
|
|
return 0
|
|
|
|
|
|
def cmd_tool(_: argparse.Namespace) -> int:
|
|
try:
|
|
sid = hook_session()
|
|
if not sid:
|
|
return 0
|
|
with session(sid) as state:
|
|
mtime = news_mtime()
|
|
if mtime is None or mtime <= mark(state, "mtime"):
|
|
return 0
|
|
name = name_of(sid)
|
|
floor = max(mark(state, "urgent"), prompt_mark(sid), time.time() - WINDOW)
|
|
rows = ordered([row for row in items() if urgent(row) and row["ts"] > floor and for_me(row, name)])
|
|
state["mtime"] = mtime
|
|
if rows:
|
|
state["urgent"] = max(row["ts"] for row in rows)
|
|
save(sid, state)
|
|
if rows:
|
|
context = "\n".join(line(row) for row in rows)
|
|
print(json.dumps({"hookSpecificOutput": {"hookEventName": "PostToolBatch", "additionalContext": context}}))
|
|
if any(kind(row) == "mayday" for row in rows):
|
|
notify_once(silence())
|
|
except Exception: # noqa: BLE001
|
|
return 0
|
|
return 0
|
|
|
|
|
|
def calls(sid: str) -> list[str]:
|
|
name = name_of(sid)
|
|
with session(sid) as state:
|
|
floor = max(prompt_mark(sid), time.time() - WINDOW)
|
|
heard = max(mark(state, "listen"), floor)
|
|
loud = max(mark(state, "urgent"), floor)
|
|
rows = [row for row in items() if row["ts"] > floor and for_me(row, name)]
|
|
wakes = [
|
|
row
|
|
for row in rows
|
|
if row["ts"] > heard
|
|
and ((kind(row) == "direct" and row.get("wake")) or (kind(row) == "mayday" and row["ts"] > loud))
|
|
]
|
|
if not wakes:
|
|
return []
|
|
alarms = [row for row in rows if urgent(row) and row["ts"] > loud]
|
|
state["listen"] = max(row["ts"] for row in wakes)
|
|
if alarms:
|
|
state["urgent"] = max(row["ts"] for row in alarms)
|
|
save(sid, state)
|
|
return [line(row) for row in ordered(alarms + [row for row in wakes if not urgent(row)])]
|
|
|
|
|
|
def cmd_listen(_: argparse.Namespace) -> int:
|
|
try:
|
|
sid = hook_session()
|
|
if not sid:
|
|
return 0
|
|
LISTEN.mkdir(parents=True, exist_ok=True)
|
|
pidfile = LISTEN / f"{sid}.pid"
|
|
mine = str(os.getpid())
|
|
write_atomic(pidfile, mine)
|
|
parent = os.getppid()
|
|
known: float | None = None
|
|
# A listener outliving its session would poll forever; the session exiting changes its parent.
|
|
while pidfile.read_text(encoding="utf-8") == mine and os.getppid() == parent:
|
|
mtime = news_mtime()
|
|
if mtime != known:
|
|
known = mtime
|
|
lines = calls(sid)
|
|
if lines:
|
|
print("\n".join(lines), file=sys.stderr)
|
|
notify_once(silence())
|
|
return 2
|
|
time.sleep(POLL_SECONDS)
|
|
except Exception: # noqa: BLE001
|
|
return 0
|
|
return 0
|
|
|
|
|
|
def cmd_show(args: argparse.Namespace) -> int:
|
|
active = silence()
|
|
if active:
|
|
print(silence_line(active))
|
|
if args.all:
|
|
rows = items()
|
|
else:
|
|
sid, _ = council().caller(args.session)
|
|
rows = ordered(unseen(sid, name_of(sid)))
|
|
for row in rows:
|
|
print(line(row))
|
|
return 0
|
|
|
|
|
|
def main() -> int:
|
|
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
|
sub = parser.add_subparsers(dest="command", required=True)
|
|
p = sub.add_parser("send")
|
|
p.add_argument("cls", metavar="class", choices=CLASSES)
|
|
p.add_argument("text")
|
|
p.add_argument("--to", action="append")
|
|
p.add_argument("--wake", action="store_true")
|
|
p.add_argument("--session")
|
|
p.set_defaults(func=cmd_send)
|
|
p = sub.add_parser("post")
|
|
p.add_argument("text")
|
|
p.add_argument("--to", action="append")
|
|
p.add_argument("--session")
|
|
p.set_defaults(func=cmd_post)
|
|
p = sub.add_parser("clear")
|
|
p.add_argument("--force", action="store_true")
|
|
p.add_argument("--session")
|
|
p.set_defaults(func=cmd_clear)
|
|
sub.add_parser("hook").set_defaults(func=cmd_hook)
|
|
sub.add_parser("tool").set_defaults(func=cmd_tool)
|
|
sub.add_parser("listen").set_defaults(func=cmd_listen)
|
|
p = sub.add_parser("show")
|
|
p.add_argument("--all", action="store_true")
|
|
p.add_argument("--session")
|
|
p.set_defaults(func=cmd_show)
|
|
args = parser.parse_args()
|
|
return args.func(args)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|