agents-city 0.3.0 → 0.5.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "city",
       "source": "./plugin",
-      "version": "0.3.0",
+      "version": "0.5.1",
       "description": "Operate one autonomous city seat, its domain, role, repo support agents, goal, recognised skills and explicit roads to other cities."
     }
   ]

package/README.es.md

@@ -106,7 +106,7 @@ Esto es `0.x` a propósito: los comandos ya se usan hoy, pero los formatos de
 fichero y las APIs todavía pueden cambiar entre versiones menores. Aquí nada
 pretende estar congelado.
 
-Necesitas Node.js 22 o superior, Python 3 y tmux; los detalles están en la
+Necesitas Node.js 22.13 o superior, Python 3 y tmux; los detalles están en la
 [tabla de requisitos](#requisitos-base), y `agents-city seat` se ofrece a
 instalar tmux si falta. No se instala nada en el sistema más allá de la carpeta
 global de npm de tu Node activo.
@@ -162,7 +162,7 @@ agents-city --version
 
 | Requisito | Para qué se usa |
 |---|---|
-| Node.js 22 o posterior | paquete npm, bus WebSocket y frontends |
+| Node.js 22.13 o posterior | paquete npm, bus WebSocket, recepción local y frontends |
 | npm | instalación y empaquetado |
 | Python 3 | Hall, onboarding, ciudades, mapas y utilidades |
 | bash | sesiones y launchers |
@@ -491,6 +491,7 @@ agents-city setup
 agents-city seat
 agents-city cities
 agents-city road
+agents-city connect
 agents-city bus
 agents-city committee
 agents-city agents
@@ -556,12 +557,46 @@ se escriben en el registro de actividad. El token de observador rota con el hub,
 sólo acepta un origen de este ordenador y es de sólo lectura: el navegador no
 puede dirigir el comité. `Ctrl-c` detiene el Hall.
 
+**Demos**, en el rail, reproduce un comité entero sin montar nada: una historia
+por dominio de trabajo — un estudio, una clínica, un despacho — con play, pausa,
+repetir y velocidad. Lo que reproduce son *grabaciones*: `demo/graba.py` ejecuta
+cada historia sobre el bus local real, a través de la máquina de estados real del
+comité, y guarda el flujo exacto de eventos que vio un espectador; el Hall los
+reproduce con el mismo renderizador que usa el rail en vivo. Lo dice en pantalla,
+porque una demo que finge estar en vivo es justo la que este producto no debe
+publicar. Para lanzar una en vivo desde terminal: `agents-city demo --domain
+software`.
+
+Regenera las grabaciones tras editar `demo/stories.py`:
+
+```bash
+demo/graba.py            # todas las historias
+demo/graba.py medicina   # sólo una
+```
+
+La suite de demo falla cuando una grabación deja de corresponderse con la
+historia que dice ser, así que una obsoleta es un build en rojo y no un navegador
+reproduciendo en silencio el comité del mes pasado.
+
 Bajo la marca hay dos botones: **día/noche** e **ES/EN**. El Hall habla español e
 inglés, arranca en el idioma del navegador y recuerda la elección explícita. Las
 traducciones se indexan por la frase en inglés, así que lo que aún no esté
 traducido cae en un inglés legible y no en un identificador — un texto nuevo
 nunca se queda bloqueado esperando a la traducción.
 
+La cobertura es una prueba, no una costumbre. `bin/test-i18n.py` lee las rutas de
+renderizado, saca cada frase en inglés que una persona va a ver, y falla cuando
+alguna no tiene español — así una vista nueva no puede colarse sin traducir, que
+es como la cobertura había caído al 40% sin que nadie se diera cuenta.
+
+El mecanismo evidente — barrer el DOM renderizado y traducir lo que coincida con
+una clave — es a propósito lo que **no** se hace. En el DOM no hay forma de
+distinguir una frase que escribió este producto de un nombre de ciudad o de
+agente que escribió alguien, así que a quien tenga una ciudad llamada `Overview`
+se le renombraría sola. Esa distinción sólo existe en el fuente, entre un literal
+y una interpolación, y ahí es donde se comprueba: lo que lleve un `${}` se
+salta.
+
 ### `agents-city setup`
 
 Crea o selecciona una ciudad y abre el Hall; con `--tui` entrega el flujo a
@@ -668,6 +703,59 @@ agents-city road disconnect producto <city-id-remoto>
 No se puede conectar una ciudad consigo misma. Una invitación remota debe
 aceptarse de forma independiente en cada máquina.
 
+### `agents-city connect`
+
+Empareja este ordenador con un servicio de Roads gestionadas. No crea una
+conexión unilateral: las dos personas la aprueban en el servicio y quien la
+recibe ve a la otra persona en su recepción humana privada, sin exponer un
+catálogo de ciudades. El cliente público implementa el protocolo v4; el servicio
+alojado queda fuera de este repositorio y todavía no está habilitado en
+producción ni auditado de forma independiente.
+
+```bash
+agents-city connect --service https://connect.example.com --trust-file roots.json
+agents-city connect --city producto
+agents-city connect --all
+agents-city connect status
+agents-city connect roads
+```
+
+El comando genera material Ed25519/X25519, Olm y ML-KEM-768 firmado en este
+ordenador, muestra un PASCO de un solo uso y abre el navegador para autorizarlo.
+Sólo sube material público. Las claves privadas, el estado del ratchet, las
+semillas ML-KEM y los reintentos quedan cifrados en
+`~/.agents-city/.runtime/connect/vault/`; la clave de envoltura permanece en el
+Llavero de macOS, Credential Manager de Windows o Secret Service de Linux. El
+cliente falla de forma cerrada si el keyring no está disponible. La jaula sella
+el vault para las ventanas de agentes de repositorio en macOS y Linux.
+
+La cadena de raíces firmada indicada con `--trust-file` es obligatoria en el
+primer emparejamiento con un servicio que no sea de desarrollo. El cliente
+conserva la última versión aceptada. Una raíz posterior debe continuar desde
+esa raíz local exacta y llevar suficientes firmas de las autoridades offline
+anteriores y nuevas; se rechazan saltos, rollback, caducidad y cambios
+silenciosos de operador o testigo. El protocolo v4 verifica después al peer
+mediante transparencia de claves, protege el primer mensaje Olm con X25519 +
+ML-KEM-768 híbrido y usa el Double Ratchet de Olm. Los envíos sellados normales
+omiten remitente, dispositivo, ciudad y Road de la petición exterior. Esto no
+oculta a Cloudflare la IP, el momento o el tamaño rellenado; los pasos
+posteriores del ratchet son clásicos.
+
+El paquete incluye una raíz pública únicamente para el origen exacto del
+sandbox gestionado. Los servicios autoalojados siguen necesitando su
+`--trust-file` revisado. Una raíz devuelta por el propio servicio nunca se
+acepta como primer anclaje.
+
+`--city` elige un hub local que mantiene viva la recepción del propietario; no
+elige un destinatario ni se revela a la otra persona. Un solo hub por ordenador
+mantiene el lease y una conexión cifrada saliente; no se abre ningún puerto
+público. Usa `--service URL` o `AGENTS_CITY_CONNECT_URL` para un endpoint piloto.
+El servidor alojado no forma parte de este repositorio Apache; el cliente y el
+protocolo auditables sí.
+
+[docs/managed-connect.md](docs/managed-connect.md) detalla el contrato de claves,
+sobres, cifrado, ACK, revocación y modelo de amenazas.
+
 ### `agents-city bus`
 
 Opera mensajes entre asientos sobre carreteras ya declaradas.
@@ -682,7 +770,7 @@ agents-city bus send '*' "Aviso para todas mis carreteras"
 | Subcomando | Efecto |
 |---|---|
 | `roster` | devuelve carreteras y presencia online conocida |
-| `inbox` | devuelve y consume el inbox pendiente; el historial append-only permanece |
+| `inbox` | devuelve y consume el siguiente lote aprobado de hasta 20; el texto gestionado no aparece hasta que el propietario lo envía desde el ayuntamiento |
 | `send owner/city TEXTO` | envía a un destino permitido |
 | `send '*' TEXTO` | envía a todas las carreteras; exige al menos una |
 
@@ -1551,9 +1639,28 @@ AGENTS_CITY_DATA="$HOME/.agents-city/$CITY_OWNER/producto" \
 En una sesión normal no hace falta establecer `AGENTS_CITY_DATA`: ya está
 inyectado en cada ventana. El ejemplo lo hace explícito para una terminal externa.
 
-### Caso 10: conectar ciudades de dos máquinas o personas
+### Caso 10: conectar dos personas desde ordenadores distintos
+
+Con un operador de Roads gestionadas, cada persona empareja su ordenador.
+`--city` elige el hub local que inicia la recepción del propietario; no revela
+esa ciudad ni da acceso directo a ella:
+
+```bash
+agents-city connect --city producto --service https://connect.example.com --trust-file roots.json
+agents-city connect --city research --service https://connect.example.com --trust-file roots.json
+```
+
+Una persona solicita la conexión en el servicio y la otra la acepta. Los
+clientes reciben la Road bilateral mediante sus sesiones autenticadas; ninguna
+parte intercambia un token compartido, abre un puerto local ni recibe el catálogo
+de ciudades de la otra. El texto entrante se detiene primero en la recepción
+humana. Quien lo recibe decide qué ciudad o ciudades locales pueden leerlo, o
+activa el router opcional que falla de forma cerrada y sólo actúa cuando una
+regla coincide sin ambigüedad. El contrato del cliente público está en
+[docs/managed-connect.md](docs/managed-connect.md).
 
-En la máquina A:
+Para autoalojar el transporte remoto existente basado en token, intercambia en
+cambio las invitaciones públicas de ciudad. En la máquina A:
 
 ```bash
 agents-city road invite producto > producto.invitation.json
@@ -1782,12 +1889,32 @@ El hub local no mezcla datos efímeros con la configuración legible:
 ├── road-queue/*.json
 ├── road-inbox/*.json
 └── road-history.jsonl
+
+~/.agents-city/.runtime/reception/
+└── reception.sqlite3       # cuarentena del propietario compartida por sus ciudades
 ```
 
 Las credenciales y ficheros de runtime se crean con permisos privados. Los
 outboxes permiten que un actor se reconecte sin perder tareas ya aceptadas; el
-ACK elimina el pendiente. El límite actual es 200 pendientes por cola y 72 horas
-de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-only.
+ACK elimina el pendiente. Los outboxes de actores y la cola local de reintentos
+admiten 200 pendientes; el inbox de Roads admite 500 por defecto y devuelve como
+máximo los 20 más antiguos en cada lectura. El texto E2EE gestionado entra
+primero en la recepción separada del propietario: ninguna ciudad ni modelo puede
+consumirlo hasta que una persona lo rechaza o lo envía a una o varias ciudades
+desde el ayuntamiento. Una ráfaga ya enrutada crea una sola activación agrupada
+del asiento, no un turno del modelo por mensaje, y cada runtime nativo ejecuta
+como máximo un turno a la vez. Una cola llena aplica backpressure en vez de
+borrar silenciosamente un elemento anterior. La vida de cada mensaje es de 72
+horas. `bus inbox` consume el `road-inbox` aprobado, no la cuarentena ni el
+historial append-only.
+
+El rendimiento del relay no es el rendimiento de respuestas. Para una ciudad,
+la capacidad semántica segura es aproximadamente las peticiones agrupadas por
+turno divididas por la duración del turno. La regresión local vacía 100 mensajes
+de Road en cinco lotes exactos de 20 tras una sola activación sin contenido; una
+prueba separada con 20 peticiones y runtime lento demuestra que la concurrencia
+del modelo permanece en uno y que el backlog durable se vacía sin pérdidas. El
+resultado `queued` del remitente nunca significa leído ni respondido.
 
 ### Variables configurables
 
@@ -1809,6 +1936,12 @@ de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-on
 | `CITY_HOOKS` | `city` | `everywhere` ejecuta los hooks de conciencia en todas las sesiones de Claude, no solo en runtimes de ciudad |
 | `CITY_DESKTOP` | `~/Desktop`, o el escritorio de Windows bajo WSL | dónde escribe `agents-city shortcut` |
 | `CITY_CAGE` | `1` | `0` arranca todas las ventanas sin jaula |
+| `CITY_ROAD_INBOX_MAX_PENDING` | `500` | capacidad local del inbox de Roads, entre 20 y 10.000; al llenarse aplica backpressure |
+| `CITY_ROAD_INBOX_WAKE_INTERVAL_MS` | `300000` | intervalo mínimo entre activaciones agrupadas del backlog, de 30 segundos a 1 hora |
+| `CITY_RECEPTION_MAX_PENDING` | `10000` | mensajes remotos pendientes del propietario antes de aplicar contrapresión al relay, de 100 a 100.000 |
+| `CITY_RECEPTION_MAX_BYTES` | `67108864` | bytes totales pendientes en la recepción local privada, de 1 MiB a 512 MiB |
+| `CITY_RECEPTION_PENDING_DAYS` | `30` | retención local de mensajes sin decidir, de 1 a 90 días |
+| `CITY_RECEPTION_DELIVERY_INTERVAL_MS` | `1000` | frecuencia con la que un bus reclama rutas aprobadas por la persona, de 250 ms a 30 segundos |
 | `CITY_CAGE_DENY` | vacío | rutas extra que sellar, separadas por `:` |
 | `CITY_CAGE_ALLOW_WRITE` | vacío | rutas extra que mantener escribibles, separadas por `:` |
 | `CITY_UPDATE_CHECK` | `1` | `0` no pregunta nunca a npm si hay versión más nueva |
@@ -1843,9 +1976,17 @@ CITY_SETTLE=0 CITY_STAGGER=0 agents-city seat --city producto
 Lee `.git/config` y `HEAD` directamente en vez de lanzar `git` una vez por
 repositorio, así que un escaneo completo termina mientras alguien mira la
 pantalla, y funciona allí donde funcione Python: macOS, Linux y Windows por
-igual. La guía y el Hall buscan sobre este índice; `plugin/scripts/find-repos.sh`
-es un envoltorio fino para quien lo llama desde shell, y sólo imprime la mitad
-git.
+igual. Este índice es el que usa la **terminal**: `seat --repos`, y el lanzador
+resolviendo el `repo@rama` de una ficha a una ruta de esta máquina.
+`plugin/scripts/find-repos.sh` es un envoltorio fino para quien lo llama desde
+shell, y sólo imprime la mitad git.
+
+El **Hall** no lo usa, y a propósito: allí, elegir sobre qué trabaja un agente es
+un explorador de carpetas. Recorres tu disco y coges lo que quieras — un
+repositorio, un worktree, una carpeta de documentos, un fichero exacto — y no se
+te adelanta nada ni se filtra nada. Una lista adivinada sólo puede ofrecerte lo
+que sabía buscar, y es una lista más que leer antes de hacer aquello a lo que
+venías.
 
 El índice se cachea un día en `$XDG_CACHE_HOME/agents-city/lugares.tsv` o
 `~/.cache/agents-city/lugares.tsv`. Tanto el formulario de casas del Hall como el
@@ -1937,10 +2078,18 @@ tus repos, adjuntarse a tu tmux o leer ficheros privados de tu home. Para códig
 no confiable usa cuentas/VMs/contenedores separados y aplica también los permisos
 del CLI de cada proveedor.
 
-El bus remoto amplía la superficie de confianza. Despliega HTTPS/WSS, rota
-tokens, limita los scopes y revisa [docs/self-host.md](docs/self-host.md). Una
-carretera autoriza intercambio de mensajes entre asientos; no implica confianza
-para ejecutar comandos recibidos ni acceso al filesystem remoto.
+Un bus remoto amplía la superficie de confianza. Para el transporte autoalojado
+con token, despliega HTTPS/WSS, rota tokens, limita los scopes y revisa
+[docs/self-host.md](docs/self-host.md). Managed Connect usa firmas de
+dispositivo, transparencia de claves con testigos, establecimiento de sesión
+híbrido X25519 + ML-KEM-768, Double Ratchet de Olm y entrega sellada. Su material
+privado queda cifrado bajo una clave del keyring del sistema operativo en el
+directorio sellado por la jaula `~/.agents-city/.runtime/connect/vault/`; consulta
+[docs/managed-connect.md](docs/managed-connect.md). Una Road gestionada autoriza
+alcance cifrado hasta la recepción humana del propietario, no entrada directa a
+un modelo. Solo la ruta posterior del propietario deja el texto disponible para
+las ciudades elegidas. Ninguna Road autoriza ejecutar comandos recibidos ni
+acceder al filesystem remoto.
 
 ## Resolución de problemas
 
@@ -2099,10 +2248,139 @@ agents-city seat --repos
 ```
 
 La detección exige `.git` (directorio o fichero de worktree) y un remote `origin`.
-Si acabas de cambiar las raíces, usa **Buscar otra vez** en el formulario de
-casas, o ejecuta `plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` puede estar filtrando el repo;
+Si acabas de cambiar las raíces, ejecuta `plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` puede estar filtrando el repo;
 déjala vacía para indexar todos los remotes.
 
+### Tus CLIs, tal y como las tienes
+
+Esto no compite con la CLI que ya usas. Las orquesta, y eso sólo funciona si
+respeta lo que configuraste en ellas — tus plugins, tus skills, tus servidores
+MCP, tu modelo, tus permisos.
+
+Eso es una afirmación sobre tu máquina, así que va como comando y no como
+promesa:
+
+```bash
+agents-city doctor --config          # qué añadimos, qué heredamos, qué no tocamos
+agents-city doctor --config --json   # lo mismo, como datos
+```
+
+Imprime tres columnas por CLI, y la diferencia entre ellas es lo importante:
+
+* **el trato** — lo que añadimos o pisamos. Es corto, cada línea dice *por qué*,
+  y es lo que hace que el bus sea la única ruta entre agentes y que la jaula
+  aguante. Sin eso no hay producto.
+* **heredamos** — lo que a propósito *no* mandamos, para que tu propia CLI lea
+  tu propia configuración. Tu modelo, tu esfuerzo, tu política de aprobación.
+* **no tocamos** — lo que carga exactamente igual que siempre.
+
+El informe y el runtime leen **el mismo fichero** —
+`plugin/channel/runtime/arnes.json` — así que la afirmación no puede separarse
+del comportamiento. Los conectores sacan sus valores de esa declaración en vez de
+escribirlos a mano, y la suite falla si un runtime impone algo que la declaración
+no menciona. Escribir esa comprobación encontró dos: un system prompt inyectado
+en Kimi que no declaraba nadie, y un valor de sandbox escrito en dos sitios.
+
+Donde tu ajuste y el nuestro se cruzan, gana el tuyo cuando puede: el
+`approval_policy` de Codex se respeta si lo has puesto, y `on-request` es sólo el
+recurso cuando no. El informe dice la consecuencia en voz alta — `never`
+desactiva las herramientas de app y MCP — en vez de decidir en silencio que no
+querías decir eso.
+
+### Tu silla conserva tu propio Claude Code
+
+La ventana del asiento abre **Claude Code de verdad** — tus plugins, tus skills,
+tus servidores MCP, tu statusline, el autocompletado de slash commands, el
+selector de modelo. Es el arnés que ya usas, en el panel, y es a propósito: la
+silla es donde una persona trabaja a mano.
+
+Sigue estando en el bus. Los hooks del plugin (`SessionStart`,
+`UserPromptSubmit`, `Stop`, `SessionEnd`) reportan los prompts y las respuestas
+de esa sesión como los mismos eventos `conversation.*` que reporta el gateway,
+así que el ayuntamiento ve la conversación igual. Y lleva los dos flags que
+hacen del bus la única ruta entre agentes — `crossSessionInbound: refuse` y
+`--disallowed-tools SendMessage,ListAgents`. Un producto más silencioso con un
+agujero dentro no sería un producto mejor.
+
+**Las casas de los agentes conservan el gateway** y su prompt `city>`, porque lo
+que compra el gateway es que el bus pueda *meter* trabajo en una ventana — que
+es el oficio entero de una casa y nada del oficio de la silla.
+
+Una clave de la ficha devuelve la silla a lo de antes:
+
+```yaml
+ui.seat: gateway     # el prompt de la ciudad en la silla, como antes
+```
+
+`CITY_UI=gateway` lo fuerza para un arranque. A las casas no se les pregunta:
+una casa existe para recibir encargos, y el gateway es lo que lo hace posible.
+
+### El motor con el que corre una casa
+
+`model.<ventana>` y `effort.<ventana>` en la ficha dicen con qué corre una casa,
+una sola vez, la mueva la CLI que la mueva. Claude los toma como flags; los
+gateways nativos leen esa misma grafía del texto del comando y la mandan con el
+turno — por eso una clave significa lo mismo para las cuatro:
+
+| proveedor | modelo | esfuerzo |
+| --- | --- | --- |
+| `claude` | sí, un alias que resuelve la CLI (`opus`, `sonnet`…) | sí |
+| `codex` | sí, el nombre que use tu Codex (`~/.codex/config.toml`) | sí |
+| `opencode` | sí, `proveedor/modelo` | no existe ese ajuste |
+| `kimi` | sí | no existe ese ajuste |
+
+Un comando que ya lleva el flag se lo queda: `runs.dbt: codex --model o3` es
+alguien diciendo lo que quería, y una clave genérica no debe pisar una frase
+concreta. El esfuerzo sólo se escribe donde se lee, porque un flag que nadie lee
+es justo como un control acaba pareciendo que funciona.
+
+### Publicar una versión
+
+Una release es una etiqueta. Empujar `v0.5.2` ejecuta la suite entera en Linux,
+macOS y Windows, comprueba que la etiqueta y los tres manifiestos dicen la misma
+versión, y publica con **procedencia**: una declaración firmada de qué commit y
+qué workflow produjeron ese tarball exacto. Cualquiera puede comprobarlo:
+
+```bash
+npm audit signatures
+```
+
+No hay ningún token guardado. Publica por *trusted publishing* de npm, que
+cambia una identidad OIDC de corta vida emitida por el workflow por el derecho a
+publicar este paquete: un secreto que no existe no se puede filtrar.
+
+```bash
+npm version patch --no-git-tag-version   # y luego un PR con la subida
+git tag v0.5.2 && git push origin v0.5.2 # la etiqueta es la release
+```
+
+Esto existe porque publicar a mano no funcionaba. Cuatro versiones se quedaron
+sin publicar en un solo día, no por descuido sino porque el paso vivía en la
+cabeza de una persona y necesitaba su passkey — y lo que llegaba al registro era
+lo que hubiera en un directorio de trabajo, sin conexión con ningún commit que
+nadie pudiera nombrar.
+
+### Desinstalarlo del todo
+
+```bash
+agents-city uninstall           # dice exactamente qué se iría; no borra nada
+agents-city uninstall --yes     # lo hace
+agents-city uninstall --keep-cities --yes   # desconecta la máquina, conserva las ciudades
+agents-city uninstall --npm --yes           # y quita también el paquete global
+```
+
+Cierra todas las sesiones, halls y mapas que el producto arrancó, quita los
+accesos directos del escritorio y el registro del plugin de Claude, y borra
+`~/.agents-city` (tus ciudades, su estado y sus copias), `~/.config/agents-city`,
+`~/.cache/agents-city` y `~/.claude/channels/city-bus` — más el token del bus en
+el Keychain de macOS.
+
+Nunca toca tus repositorios, tus worktrees ni tus carpetas de documentos. La casa
+de un agente guarda *enlaces* a eso, y lo único que se va es el enlace.
+
+`reset` responde a la otra pregunta: vacía una ciudad, deja una copia y conserva
+la instalación, para cuando piensas seguir usándolo.
+
 ### GitHub no muestra repos privados u organizaciones
 
 ```bash