fn_registry/python/functions/infra/drain_fleet_events.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
drain_fleet_events	function	py	infra	1.0.0	impure	def drain_fleet_events(events_path: str | None = None, cursor_path: str | None = None, advance: bool = True) -> dict	Drena la cola JSONL de eventos de la flota desde un cursor persistente. Lee los eventos nuevos (desde la linea del cursor hasta el final), los parsea saltando lineas en blanco o JSON invalido, los agrupa por su campo `to` (RECLAMA, MAL_LANZADO, DICE_TERMINADO, ESTANCADO, TRABAJANDO, GONE), aisla los urgentes y avanza el cursor para no reprocesar. Pensado para que el orquestador-Claude de flota consuma eventos nuevos cada vez que despierta.	fleet claude-fleet jsonl cursor queue drain watcher orchestrator				false	error_go_core	os json	name desc events_path ruta a la cola JSONL append-only de eventos. Default: ~/.claude/fleet/events.jsonl name desc cursor_path ruta al archivo de cursor (numero de lineas ya procesadas, entero en texto plano). Default: ~/.claude/fleet/cursor name desc advance si True avanza el cursor al total de lineas para no reprocesar; si False hace peek sin mover el cursor (inspeccion)	dict con total_new (int), events (lista de eventos nuevos en orden), by_classification (dict agrupado por campo `to`), urgent (lista de eventos con urgent==True), cursor (nueva posicion) y opcionalmente reset==True si la cola estaba truncada/rotada y el cursor se reinicio a 0	true	cola con eventos cursor cero devuelve todos y avanza segunda llamada cero nuevos advance false no mueve cursor archivo ausente vacio sin crash json invalido se salta agrupacion por to y urgent cursor mayor que lineas reinicia	python/functions/infra/drain_fleet_events_test.py	python/functions/infra/drain_fleet_events.py

Ejemplo

from infra.drain_fleet_events import drain_fleet_events

# El orquestador despierta y consume los eventos nuevos de la flota.
drained = drain_fleet_events()  # usa ~/.claude/fleet/events.jsonl y ~/.claude/fleet/cursor

print(f"{drained['total_new']} eventos nuevos")
for ev in drained["by_classification"].get("RECLAMA", []):
    print("RECLAMA:", ev["session_id"], ev["goal"])

# Eventos urgentes primero.
for ev in drained["urgent"]:
    print("URGENTE:", ev["to"], ev["session_id"])

# Peek sin avanzar el cursor (no consume): util para inspeccionar antes de actuar.
peek = drain_fleet_events(advance=False)

Cuando usarla

Usala en el orquestador-Claude de flota cada vez que despierta y necesita ver las transiciones de estado producidas DESDE la ultima vez sin reprocesar las ya vistas. Tambien para diagnostico con advance=False cuando quieres mirar la cola sin consumirla.

Gotchas

• Impura: lee la cola JSONL del disco y, con advance=True, sobrescribe el archivo de cursor. Pasa advance=False para peek puro sin efectos en cursor.
• Cursor por lineas, no por bytes: el cursor cuenta lineas procesadas. Las lineas en blanco e invalidas tambien avanzan el cursor (se cuentan en el total de lineas) aunque no produzcan eventos, de modo que nunca se re-leen.
• Cola rotada/truncada: si el cursor guardado es mayor que el numero de lineas actual (la cola se trunco o rota), el drain reinicia desde 0 y marca reset: True en el dict de salida — devolvera de nuevo todos los eventos presentes. Diseñado asi para no perder eventos silenciosamente.
• JSON invalido o lineas en blanco: se saltan sin romper el drain. Solo los objetos JSON validos entran en events.
• by_classification: agrupa por el campo to. Un evento sin campo to (raro) entra en events pero no en ningun grupo.
• Fallo al persistir el cursor: si advance=True pero no se puede escribir el cursor (permisos, FS), el drain sigue siendo valido pero la proxima llamada reprocesara estos eventos (at-least-once, no at-most-once).