clankercode/agent-file-chat

Sala de agente simple

Cuándo usarla

Una sala es un registro de chat de muchos a muchos. Cualquier número de agentes puede publicar en una sala, y cualquier agente puede Monitorizarla. Usos típicos:

• Varios subagentes trabajando en tareas relacionadas y necesitando compartir hallazgos intermedios (un codificador reportando un error en el parser, un investigador reportando una URL, un probador reportando una aserción fallida).
• Un agente de larga duración que necesita ser descubrible por otros agentes que puedan aparecer más tarde.
• Un canal de coordinación para un "equipo de agentes" que ejecuta un plan de múltiples pasos.

Para comunicaciones uno a uno con un subagente único de larga duración, la habilidad hermana simple-agent-comms (dos archivos + un monitor) es más ligera.

Lo que necesitas saber (el agente)

Tres comandos, todos en $PATH. No necesitas conocer ninguna ruta de archivo. El nombre de la sala es lo único que pasas.

simple-room-send    <sala> [args]    # publicar un mensaje
simple-room-monitor <sala> [args]    # transmitir nuevos mensajes (apto para Monitor)
simple-room-scan    <sala> <subcmd>  # contar / tail / activos / grep / ids / ruta

Eso es todo. Eliges un nombre de sala (alfanumérico, punto, guión bajo, guión; máximo 64 caracteres), eliges un id de agente para ti mismo, y envías / lees.

Si el resto del sistema necesita saber dónde se almacena la sala, la única ubicación canónica es ~/.cache/simple-agent-room/<sala>.log, reemplazable mediante $SIMPLE_AGENT_ROOM_DIR (raro — solo para pruebas o diseños multiinquilino).

Inicio rápido (un agente, una línea)

simple-room-send cocina "la estufa está encendida" # publicaste un mensaje
simple-room-scan  cocina tail -n 5                  # leíste los últimos 5
simple-room-scan  cocina active --window 60         # quién está aquí

Inicio rápido (dos agentes coordinándose)

# agente A                                            # agente B
simple-room-send tareas -m "Estoy empezando"             \
                                                      simple-room-monitor tareas   # en un Monitor:
                                                                       ▲           #   llegan nuevas líneas,
                                                                       │           #   mensajes propios filtrados
# --- luego, en otro terminal/turno ---               simple-room-send tareas -m "recibido"

El patrón correcto: inicia el monitor como un comando en segundo plano persistente en una llamada a la herramienta Monitor(...), luego envía / escanea / habla en primer plano.

Diagramas de flujo ASCII

Publicar un mensaje

       agente                       simple-room-send              en disco
       ──────                       ────────────────              ───────
  $ simple-room-send cocina \             │
        -a alicia -m "hola"             │  format_record
                                          │  → línea JSON + '\n'
                                          │  → os.open(O_APPEND|O_CREAT, 0o644)
                                          │  → os.write(fd, línea)
                                          ▼
                              ~/.cache/simple-agent-room/cocina.log
                              ─────────────────────────────────────────
                              {"id":"…","ts":"…","agent":"alicia", … }
                              {"id":"…","ts":"…","agent":"bob",   … }
                              …

Los publicadores concurrentes no rompen los registros de los demás: las escrituras O_APPEND son atómicas en POSIX para buffers ≤ PIPE_BUF (4096 B), y el registro JSON siempre tiene menos de 1 KiB en la práctica.

Monitoreo (la forma Monitor(...))

       simple-room-monitor                  Herramienta Monitor
       ───────────────────                  ───────────
  backfill: tail de los últimos N registros       salida estándar
             (o 0 para "solo en vivo")                │
             parsear JSON, omitir propio     ──────►│  cada línea es un
                                                     │  evento de fondo,
  en vivo:  pyinotify.watch en el archivo           │  no una respuesta de usuario
           IN_MODIFY  ─► leer nuevos bytes
           IN_DELETE  ─► esperar recreación
           IN_MOVE    ─► esperar recreación
                                                     ▼
                                               el agente lee la línea,
                                               decide qué hacer

El script no hace polling. Se bloquea en pyinotify.Notifier y se activa en eventos del kernel. La latencia desde el envío hasta la entrega del evento es submilisegundo en sistemas de archivos locales.

Escaneo (solo lectura)

       simple-room-scan <sala> <subcmd> [args]
       ────────────────────────────────────────
              │
              ├─ count                 → 1 línea: conteo total de registros
              ├─ ids                   → 1 id por línea (ordenados)
              ├─ path                  → 1 línea: ruta absoluta del archivo
              ├─ active  [--window S]  → "agente<TAB>ts" por agente activo
              ├─ tail    [-n N] [-a A] → últimos N registros (o del agente)
              └─ grep    <pattern>     → registros cuyo msg coincide
                       [--since-seq N]
                       [-a A] [--json]
              │
              ▼
       iter_records(ruta) → flujo de diccionarios
       (omite líneas en blanco / '#' / malformadas)

Referencia

simple-room-send <sala> [-m MSG] [-k {msg,system,meta}] [-a AGENTE] [--stdin]

bandera	significado
-m MENSAJE	el texto del mensaje (si no, lee de stdin)
--stdin	forzar lectura de stdin (anula -m)
-k TIPO	msg (por defecto), system, o meta
-a AGENTE	id del agente local; por defecto $SIMPLE_AGENT_ID si no $USER-<host>-<pid>
--seq N	secuencia monótona explícita (opcional)
--id ID	id de registro explícito (uuid4 hex, opcional)
--ts ISO	marca de tiempo explícita (opcional)
-q	suprimir confirmación "sent id=…" en stderr

El mensaje se almacena textualmente (saltos de línea, tabuladores, barras invertidas se escapan como JSON dentro del registro; los ves en el lado de lectura como caracteres normales).

simple-room-monitor <sala> [-a AGENTE] [--exclude-self] [--backfill N] [--grep PATRÓN] [--json]

bandera	significado
-a AGENTE	id del agente local (por defecto como arriba)
--exclude-self	descartar registros del agente local (por defecto: activado)
--no-exclude-self	incluirlos (úsalo cuando quieras ver tus propios mensajes)
-b N	emitir los últimos N registros existentes antes de ir a vivo
	(-1 = todos; 0 = solo eventos, el valor por defecto)
--grep PATRÓN	solo emitir registros cuya línea renderizada coincida con la expresión regular
--json	emitir el registro JSON crudo por línea (si no, HH:MM:SS agente: msg)

El script se ejecuta hasta que se mata. Úsalo como el comando de una llamada a la herramienta Monitor(...) persistente — el patrón correcto es un Monitor por sala por sesión. Los eventos del Monitor son eventos de fondo, no respuestas de usuario; no los trates como un mensaje de usuario que finaliza un turno.

simple-room-scan <sala> <subcomando> [args]

subcomando	args	salida
count	—	conteo total de registros
ids	—	un id de agente por línea
path	—	ruta absoluta del archivo
active	--window SEGUNDOS (120)	agente<TAB>ts por agente activo
tail	-n N (20), -a AGENTE, --json	últimos N registros
grep	PATRÓN, --since-seq N, -a A, --json, -c (conteo→stderr)	registros coincidentes

grep distingue mayúsculas y minúsculas y usa sintaxis de expresiones regulares de Python (que es cercana a PCRE para los casos comunes — ., *, +, ?, \b, clases de caracteres).

Patrón de autofiltro (la receta "no hables contigo mismo")

El monitor usa por defecto --exclude-self porque en un bucle de turno de un solo agente, el agente acaba de enviar su propio mensaje y reproducirlo como un evento es ruido. Si necesitas ver ambos lados de una sesión de depuración de un solo agente, pasa --no-exclude-self.

Dos agentes en la misma sala deben elegir diferentes ids de agente. El valor por defecto ($USER-<host>-<pid>) es único por proceso; si creas múltiples agentes desde el mismo shell, establece SIMPLE_AGENT_ID para cada uno para mantenerlos distintos.

Lo que no necesitas saber

• La ruta en disco. Es ~/.cache/simple-agent-room/<sala>.log. Nunca escribes directamente en ella. simple-room-scan <sala> path te la dirá si tienes curiosidad.
• El esquema. La librería lee el archivo, parsea JSON, descarta líneas malformadas y desescapa cadenas msg. Ves un diccionario con id, ts, agent, msg, kind, seq opcional.
• Polling. El monitor está completamente impulsado por eventos (inotify).
• Bloqueo. Los registros tienen menos de 4 KiB, O_APPEND es atómico en POSIX, por lo que no se necesita flock / fcntl. Dos escritores pueden publicar simultáneamente sin romper los registros del otro.

Modos de fallo que vale la pena conocer

• inotify obsoleto después de eliminar/renombrar: la librería vuelve a adjuntar la vigilancia en IN_CREATE para la misma ruta, por lo que una herramienta de rotación de logs que reemplaza el archivo se maneja. Si eliminas el archivo manualmente, el monitor creará uno nuevo vacío en el próximo envío.
• Colisión de id de agente: dos agentes con el mismo id verán los mensajes del otro como propios (y los filtrarán por defecto). Siempre usa SIMPLE_AGENT_ID o el valor por defecto $USER-<host>-<pid>.
• Desviación de reloj: ts es la hora UTC del remitente. Si ordenas por ts entre agentes, configura NTP. Para orden dentro de un solo agente, usa seq.
• Mensajes muy largos: no hay un límite estricto, pero si publicas regularmente > 4 KiB puedes alcanzar PIPE_BUF y empezar a ver registros rotos. Mantén los mensajes < 4 KiB.
• Líneas malformadas: el lector omite silenciosamente cualquier línea que no se pueda parsear como un objeto JSON. Basura entra = basura descartada silenciosamente; los registros válidos a su alrededor no se ven afectados.

Archivos

skills/simple-agent-room/
  SKILL.md                       ← este archivo
  bin/
    simple-room-send             ← envoltorio delgado, llama a lib.simple_room_send.main
    simple-room-monitor          ← envoltorio delgado, llama a lib.simple_room_monitor.main
    simple-room-scan             ← envoltorio delgado, llama a lib.simple_room_scan.main
  lib/
    simple_agent_room_lib.py     ← librería compartida (formato/parseo, inotify, escaneo)
    simple_room_send.py          ← punto de entrada de envío
    simple_room_monitor.py       ← punto de entrada de monitor
    simple_room_scan.py          ← punto de entrada de escaneo

Cada envoltorio bin/simple-room-* es un archivo Python de 12 líneas que ajusta sys.path y delega en lib/simple_room_*.main. Los envoltorios resuelven su propia ruta real, por lo que los enlaces simbólicos en ~/.local/bin/ funcionan de manera transparente.

Instalación

Desde la raíz del repositorio:

./install.sh

Esto coloca simple-agent-room en ~/.claude/skills/ y ~/.agents/skills/, y las tres CLI en tu $PATH como simple-room-send, simple-room-monitor, simple-room-scan.

Si prefieres hacerlo a mano:

ln -s "$PWD/skills/simple-agent-room"                    ~/.claude/skills/simple-agent-room
ln -s "$PWD/skills/simple-agent-room"                    ~/.agents/skills/simple-agent-room
ln -s "$PWD/skills/simple-agent-room/bin/"*             ~/.local/bin/

Dependencias

• Python ≥ 3.10
• pyinotify (pip install pyinotify). Requerido solo por el monitor; simple-room-send y simple-room-scan funcionan sin él.