agents-city 0.1.0

package/plugin/scripts/actualiza.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Knowing there is a new version, and getting it.
+
+A tool that cannot tell you it is out of date leaves every owner running
+whatever they installed the day they found it — including the day a security
+fix shipped. So this asks npm, and it asks rarely: once a day at most, cached
+under the runtime dir, and never on a plain command. The check runs where the
+person deliberately opened something (`doctor`, `update`, the Hall), not behind
+their back on every `agents-city cities`.
+
+It is a GET to the public registry and nothing else: no identifiers, no
+counters, nothing about this machine leaves it. `CITY_UPDATE_CHECK=0` turns it
+off completely, and the answer is cached so a plane, a firewall or a dead
+registry degrade to silence rather than to an error.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+GUIONES = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, GUIONES)
+import cities  # noqa: E402
+
+PAQUETE = 'agents-city'
+REGISTRO = f'https://registry.npmjs.org/{PAQUETE}/latest'
+#: A day. The point is to notice a release, not to poll a registry.
+VIDA = 24 * 3600
+
+
+def version_instalada():
+    """What is running right now, read from the package this file ships in."""
+    raiz = os.path.dirname(os.path.dirname(GUIONES))
+    try:
+        with open(os.path.join(raiz, 'package.json'), encoding='utf-8') as f:
+            return str(json.load(f).get('version') or '')
+    except (OSError, ValueError):
+        return ''
+
+
+def _cache():
+    return os.path.join(cities.raiz(), '.runtime', 'version.json')
+
+
+def _lee_cache():
+    try:
+        with open(_cache(), encoding='utf-8') as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def _guarda_cache(ultima):
+    ruta = _cache()
+    try:
+        os.makedirs(os.path.dirname(ruta), mode=0o700, exist_ok=True)
+        cities.escribe_atomico(ruta, json.dumps({'latest': ultima, 'when': time.time()}))
+    except OSError:
+        pass  # not being able to remember is not a reason to fail a command
+
+
+def consulta_registro(timeout=8):
+    """The published version, or '' when the network says nothing useful.
+
+    Eight seconds because the first call of the day pays DNS and a TLS
+    handshake from cold; a tighter budget turns "you are up to date" into a
+    lie told by a stopwatch.
+    """
+    try:
+        peticion = urllib.request.Request(
+            REGISTRO, headers={'Accept': 'application/vnd.npm.install-v1+json'}
+        )
+        with urllib.request.urlopen(peticion, timeout=timeout) as r:
+            return str(json.load(r).get('version') or '')
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+        return ''
+
+
+def _partes(v):
+    """A version as comparable pieces. A prerelease sorts BELOW its release."""
+    base, _, pre = str(v).partition('-')
+    numeros = []
+    for trozo in base.split('.'):
+        try:
+            numeros.append(int(trozo))
+        except ValueError:
+            numeros.append(0)
+    while len(numeros) < 3:
+        numeros.append(0)
+    # No prerelease outranks one: 1.0.0 > 1.0.0-beta.1, as semver says.
+    return (numeros[0], numeros[1], numeros[2], 1 if not pre else 0, pre)
+
+
+def es_mas_nueva(candidata, actual):
+    return bool(candidata) and bool(actual) and _partes(candidata) > _partes(actual)
+
+
+def comprueba(forzar=False, vida=VIDA):
+    """(installed, published, there-is-an-update). Cached, quiet, opt-out-able.
+
+    Returns the published version as '' when the check is switched off or the
+    registry could not be reached — the caller then says nothing, which is the
+    right thing to say when you do not know.
+    """
+    instalada = version_instalada()
+    if os.environ.get('CITY_UPDATE_CHECK', '1') == '0':
+        return instalada, '', False
+    guardado = _lee_cache()
+    fresca = (time.time() - float(guardado.get('when') or 0)) < vida
+    if fresca and not forzar:
+        ultima = str(guardado.get('latest') or '')
+    else:
+        ultima = consulta_registro()
+        if ultima:
+            _guarda_cache(ultima)
+        else:
+            ultima = str(guardado.get('latest') or '')
+    return instalada, ultima, es_mas_nueva(ultima, instalada)
+
+
+def aviso():
+    """One line for a person who did not ask, or '' when there is nothing to say."""
+    instalada, ultima, hay = comprueba()
+    if not hay:
+        return ''
+    return (f'  A newer Agents City is out: {instalada} → {ultima}. '
+            f'Update with: agents-city update')
+
+
+def como_se_instalo():
+    """'npm' when this copy lives inside a global npm install, else 'clone'.
+
+    It decides what `update` may do: pulling somebody's git checkout from under
+    them is not an update, it is a surprise.
+    """
+    raiz = os.path.dirname(os.path.dirname(GUIONES))
+    if os.path.isdir(os.path.join(raiz, '.git')):
+        return 'clone'
+    return 'npm' if f'node_modules{os.sep}{PAQUETE}' in raiz else 'clone'
+
+
+def actualiza(canal=''):
+    """Install the newest published version over this one. Returns an exit code."""
+    if como_se_instalo() == 'clone':
+        print('  This is a git checkout, not an npm install.\n'
+              '  Update it the way you got it:\n'
+              '    git pull && npm pack && npm install -g ./agents-city-*.tgz')
+        return 1
+    destino = f'{PAQUETE}@{canal}' if canal else PAQUETE
+    print(f'  Installing {destino} over {version_instalada()}…')
+    hecho = subprocess.run(['npm', 'install', '-g', destino])
+    if hecho.returncode != 0:
+        print('  npm could not install it. Nothing was changed.', file=sys.stderr)
+        return hecho.returncode
+    print('  Done. Open cities keep the code they already loaded;\n'
+          '  `agents-city exit <city>` and then `agents-city seat` picks the new one up.')
+    return 0
+
+
+def _uso():
+    print(
+        '  usage: agents-city update [--check] [--tag beta]\n\n'
+        '  Install the newest published version, or just ask whether there is one.\n\n'
+        '    --check      say what is installed and what is published, and stop\n'
+        '    --tag NAME   follow a dist-tag (for example: beta)\n\n'
+        '  The check is one GET to the public npm registry, cached for a day.\n'
+        '  Nothing about this machine is sent. CITY_UPDATE_CHECK=0 disables it.'
+    )
+
+
+def main():
+    args = sys.argv[1:]
+    if any(a in ('-h', '--help', 'help') for a in args):
+        _uso()
+        return 0
+    if '--check' in args:
+        instalada, ultima, hay = comprueba(forzar=True)
+        if not ultima:
+            print(f'  Installed: {instalada}. The registry could not be reached '
+                  '(or the check is off).')
+            return 0
+        print(f'  Installed: {instalada}\n  Published: {ultima}')
+        print('  There is a newer version — agents-city update' if hay
+              else '  You are up to date.')
+        return 0
+    canal = ''
+    if '--tag' in args:
+        i = args.index('--tag')
+        canal = args[i + 1] if len(args) > i + 1 else ''
+    return actualiza(canal)
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugin/scripts/admision.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Admission as an ordered gate graph, not a boolean.
+
+Whether a seat accepts an inbound road message is a decision with a *reason*,
+and the reason must be inspectable without leaking who is on the allowlist. So
+every admission returns the ordered list of gates it evaluated, which gate was
+decisive, a stable machine-readable reason code, and — for each gate — a
+redacted diagnostic: counts and opaque ids, never a raw sender or allowlist
+entry.
+
+The mechanism (an ordered reducer that stops at the first blocking gate) is
+kept separate from the policy (`decide_entrada`), so new gates or new callers
+compose without rewriting either. Pure and transport-free: the tests drive it
+directly, and the same function can decide a local road, a remote road, or a
+future chat channel.
+"""
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Admision(str, Enum):
+    DESPACHA = 'dispatch'          # deliver to the seat
+    OBSERVA = 'observe'            # record as context, do not act
+    OMITE = 'skip'                 # not addressed to us; ignore quietly
+    DESCARTA = 'drop'              # malformed or refused; drop
+    EMPAREJA = 'pairing-required'  # unknown sender, a pairing code is owed
+
+    def __str__(self):
+        return self.value
+
+
+#: Closed set of reason codes. A code outside this set is a bug, so the
+#: constructor asserts membership rather than letting prose leak in.
+RAZONES = frozenset({
+    'road_allowed',
+    'road_missing',
+    'road_incident',
+    'sender_not_paired',
+    'sender_paired',
+    'payload_malformed',
+    'payload_empty',
+    'not_addressed_here',
+})
+
+#: Which reason a gate emits maps to how the seat should treat the message.
+_ADMISION_POR_RAZON = {
+    'road_allowed': Admision.DESPACHA,
+    'sender_paired': Admision.DESPACHA,
+    'road_missing': Admision.OMITE,
+    'not_addressed_here': Admision.OMITE,
+    'road_incident': Admision.DESCARTA,
+    'payload_malformed': Admision.DESCARTA,
+    'payload_empty': Admision.DESCARTA,
+    'sender_not_paired': Admision.EMPAREJA,
+}
+
+
+def id_opaco(valor):
+    """A stable, non-reversible short id for one allowlist entry or sender."""
+    return 'x' + hashlib.sha256(str(valor).encode()).hexdigest()[:12]
+
+
+def redacta(entradas):
+    """A diagnostic for an allowlist that reveals shape, never content."""
+    entradas = list(entradas)
+    return {'n': len(entradas), 'ids': [id_opaco(e) for e in entradas]}
+
+
+@dataclass(frozen=True)
+class Puerta:
+    id: str
+    fase: str
+    permitido: bool
+    razon: str
+    diagnostico: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        # A real raise, not assert: validation must survive `python -O`.
+        if self.razon not in RAZONES:
+            raise ValueError(f'unknown reason code: {self.razon}')
+
+
+@dataclass(frozen=True)
+class Decision:
+    admision: Admision
+    razon: str
+    puerta_decisiva: str
+    grafo: tuple
+
+    def permitido(self):
+        # Authorization lives here and ONLY here — never inferred from an
+        # evidence field, so a blocked decision can never read as authorised.
+        return self.admision is Admision.DESPACHA
+
+    def como_dict(self):
+        return {
+            'admission': str(self.admision),
+            'reasonCode': self.razon,
+            'decisiveGate': self.puerta_decisiva,
+            'gates': [
+                {'id': g.id, 'phase': g.fase, 'allowed': g.permitido,
+                 'reasonCode': g.razon, 'diagnostic': g.diagnostico}
+                for g in self.grafo
+            ],
+        }
+
+
+def _resuelve(grafo):
+    """Reduce an ordered gate list to a decision: first blocker wins, else last.
+
+    The decision carries no evidence state on purpose: allow/deny is `permitido()`
+    (derived from the admission), and an audit-provenance vocabulary belongs to
+    the layer that records the action, not to this pure routing decision. That
+    keeps authorization impossible to read off a decorative field.
+    """
+    decisiva = next((g for g in grafo if not g.permitido), grafo[-1])
+    admision = _ADMISION_POR_RAZON[decisiva.razon]
+    return Decision(admision, decisiva.razon, decisiva.id, tuple(grafo))
+
+
+def decide_entrada(*, road_existe, road_incidente, direccion_coincide,
+                   emparejado, allowlist, payload_valido, texto_no_vacio,
+                   dirigido_aqui=True):
+    """Agents City's road-inbound policy, phase by phase.
+
+    Order matters and is the policy: address → road → sender → payload. A road
+    that resolves but has no matching sender is an explicit block, never a
+    fallthrough; an unknown sender under pairing yields EMPAREJA so the seat can
+    mint a code rather than silently dropping a first contact.
+    """
+    grafo = []
+    diag = redacta(allowlist)
+
+    if not dirigido_aqui:
+        grafo.append(Puerta('address', 'route', False, 'not_addressed_here'))
+        return _resuelve(grafo)
+    grafo.append(Puerta('address', 'route', True, 'road_allowed'))
+
+    if not road_existe:
+        grafo.append(Puerta('road', 'route', False, 'road_missing', diag))
+        return _resuelve(grafo)
+    if road_incidente:
+        grafo.append(Puerta('road', 'route', False, 'road_incident', diag))
+        return _resuelve(grafo)
+    grafo.append(Puerta('road', 'route', True, 'road_allowed', diag))
+
+    if not direccion_coincide:
+        if emparejado:
+            grafo.append(Puerta('sender', 'sender', True, 'sender_paired', diag))
+        else:
+            grafo.append(Puerta('sender', 'sender', False, 'sender_not_paired', diag))
+            return _resuelve(grafo)
+    else:
+        grafo.append(Puerta('sender', 'sender', True, 'road_allowed', diag))
+
+    if not payload_valido:
+        grafo.append(Puerta('payload', 'event', False, 'payload_malformed'))
+        return _resuelve(grafo)
+    if not texto_no_vacio:
+        grafo.append(Puerta('payload', 'event', False, 'payload_empty'))
+        return _resuelve(grafo)
+    grafo.append(Puerta('payload', 'event', True, 'road_allowed'))
+    return _resuelve(grafo)

package/plugin/scripts/apaga.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Close the whole day: the tmux sessions, every agent inside them, the hall,
+the map. The seat's missing other half.
+
+    agents-city exit            close everything, every city
+    agents-city exit home       close ONE city — its session, its agents, its
+                                map — and leave the others working
+    agents-city exit --dry-run  say what would close, close nothing
+
+`seat` builds a session with an agent per window and nothing ever tore it down:
+detach, open another city, run the hall — and a machine fills with processes
+nobody remembers starting. One session was found nineteen windows deep while
+this was being written.
+
+Precision matters more than reach here. This closes ONLY what the city started,
+identified by marks the city itself leaves, and never by broad process-name
+sweeps that would take down some other project's dev server:
+
+  * tmux sessions whose name is one this product minted — always user-city —
+    across every city this user owns. Your own
+    unrelated tmux sessions are not touched.
+  * the town hall, matched by its own entry point.
+  * the map and the demo, found by who holds the city's local database open
+    (`~/.agents-city/state`) — not by killing every wrangler on the machine.
+
+Killing a session SIGHUPs its panes, which is how every Claude inside exits.
+"""
+import argparse
+import os
+import signal
+import subprocess
+import sys
+import time
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, AQUI)
+import cities  # noqa: E402
+import runtime_processes  # noqa: E402
+
+ESTADO = os.path.join(cities.raiz(), 'state')
+
+
+def _corre(args):
+    try:
+        r = subprocess.run(args, capture_output=True, text=True, timeout=30)
+        return r.stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return ''
+
+
+def sesiones_de_la_ciudad(solo=''):
+    """Every live tmux session this product would have minted, and only those.
+
+    Candidates come from city metadata: for each city this machine knows, the
+    owner-city session minted by cities.py. A session called anything else is
+    somebody's own work and stays alive. With `solo` set to one
+    city's folder, only that city's sessions qualify — closing the client's day
+    must not end the company's.
+    """
+    vivas = {l.strip() for l in _corre(['tmux', 'ls', '-F', '#{session_name}']).splitlines()
+             if l.strip()}
+    if not vivas:
+        return []
+    donde = ([{'ruta': solo}] if solo else cities.lista())
+    candidatas = set()
+    for ciudad in donde:
+        usuario = cities.lee_clave(ciudad['ruta'], 'owner')
+        if usuario:
+            candidatas.add(cities.sesion(usuario, ciudad['ruta']))
+    return sorted(vivas & candidatas)
+
+
+def servidores():
+    """The Hall and an in-flight setup launcher, by their own entry points —
+    never a pattern loose enough to match somebody else's Python."""
+    pids = []
+    for patron in ('bin/hall', 'bin/setup.py'):
+        salida = _corre(['pgrep', '-f', patron])
+        pids += [int(p) for p in salida.split() if p.strip().isdigit()]
+    return sorted(set(pids) - {os.getpid(), os.getppid()})
+
+
+def mapas(solo=''):
+    """Whoever holds the city's local database open: wrangler, workerd, the demo.
+    lsof on our own state directory is exact — it cannot name another project's
+    dev server, because no other project has these files open. With `solo`, only
+    that city's slice of the state; the demo counts as everything-only."""
+    donde = os.path.join(ESTADO, cities.slug(solo)) if solo else ESTADO
+    if not os.path.isdir(donde):
+        return []
+    salida = _corre(['lsof', '-t', '+D', donde])
+    return sorted({int(p) for p in salida.split() if p.strip().isdigit()}
+                  - {os.getpid(), os.getppid()})
+
+
+def mata(pids):
+    """TERM first, KILL for whatever ignores it. Returns how many actually died."""
+    if not pids:
+        return 0
+    for pid in pids:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            pass
+    time.sleep(1.2)
+    muertos = 0
+    for pid in pids:
+        try:
+            os.kill(pid, 0)
+            os.kill(pid, signal.SIGKILL)
+        except ProcessLookupError:
+            muertos += 1
+        except PermissionError:
+            pass
+    return muertos
+
+
+def _argumentos():
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument('ciudad', nargs='?', default='',
+                    help='close only this city (name or path); empty closes all')
+    ap.add_argument('--dry-run', action='store_true')
+    ap.add_argument('-h', '--help', action='store_true')
+    return ap.parse_args()
+
+
+def _objetivo(nombre):
+    if not nombre:
+        return ''
+    solo = cities.resuelve(nombre)
+    if solo:
+        print(f'  Only the city at {solo} — the rest keep working.')
+        return solo
+    conocidas = ', '.join(c['nombre'] for c in cities.lista()) or 'none'
+    raise ValueError(f'No city called {nombre!r}. Known here: {conocidas}.')
+
+
+def _recursos(solo):
+    ciudades = [solo] if solo else [c['ruta'] for c in cities.lista()]
+    procesos = [(ciudad, proceso) for ciudad in ciudades
+                for proceso in runtime_processes.procesos(ciudad)]
+    return {
+        'sesiones': sesiones_de_la_ciudad(solo),
+        # The hall covers all cities, so a scoped exit leaves it alive.
+        'webs': [] if solo else servidores(),
+        'mapas': mapas(solo),
+        'ciudades': ciudades,
+        'bus': procesos,
+    }
+
+
+def _vacio(recursos):
+    return not any(recursos[k] for k in ('sesiones', 'webs', 'mapas', 'bus'))
+
+
+def _describe(recursos, dry_run):
+    verbo = 'Would close' if dry_run else 'Closing'
+    for sesion_ in recursos['sesiones']:
+        ventanas = _corre(['tmux', 'list-windows', '-t', sesion_]).count('\n')
+        print(f'  {verbo}: tmux session `{sesion_}` — {ventanas} windows, '
+              f'every agent inside included')
+    webs = recursos['webs']
+    if webs:
+        print(f'  {verbo}: the town hall server ({len(webs)} process'
+              f'{"es" if len(webs) > 1 else ""})')
+    dibujos = recursos['mapas']
+    if dibujos:
+        print(f'  {verbo}: the map ({len(dibujos)} process'
+              f'{"es" if len(dibujos) > 1 else ""} holding the local database)')
+    for _, proceso in recursos['bus']:
+        print(f'  {verbo}: {proceso["label"]} (pid {proceso["pid"]})')
+
+
+def _cierra_sesiones(sesiones):
+    """Close our current tmux session last so this command can finish."""
+    propia = os.environ.get('TMUX', '')
+    actual = _corre(['tmux', 'display-message', '-p', '#{session_name}']).strip()
+    ultimas = []
+    for sesion_ in sesiones:
+        if propia and actual == sesion_:
+            ultimas.append(sesion_)
+        else:
+            subprocess.run(['tmux', 'kill-session', '-t', sesion_], capture_output=True)
+    return ultimas
+
+
+def _cierra(recursos):
+    # Sessions first: SIGHUP lets every runtime exit on its own terms.
+    ultimas = _cierra_sesiones(recursos['sesiones'])
+    mata(recursos['webs'])
+    mata(recursos['mapas'])
+    mata([proceso['pid'] for _, proceso in recursos['bus']])
+    # A gateway can notice the hub dying in the narrow interval before tmux's
+    # SIGHUP reaches it and recreate a hub. Re-scan exact --data argv after the
+    # session is gone; this also catches old hubs whose marker was overwritten.
+    for _ in range(3):
+        restantes = [proceso['pid'] for ciudad in recursos['ciudades']
+                      for proceso in runtime_processes.procesos(ciudad)]
+        if not restantes:
+            break
+        mata(sorted(set(restantes)))
+    for ciudad in recursos['ciudades']:
+        runtime_processes.limpia_marcas(ciudad)
+    for sesion_ in ultimas:
+        subprocess.run(['tmux', 'kill-session', '-t', sesion_], capture_output=True)
+
+
+def main():
+    a = _argumentos()
+    if a.help:
+        print(__doc__)
+        return 0
+
+    try:
+        solo = _objetivo(a.ciudad)
+    except ValueError as error:
+        print(f'  {error}', file=sys.stderr)
+        return 1
+    recursos = _recursos(solo)
+    if _vacio(recursos):
+        print('  Nothing of the city is running. The machine is yours.')
+        return 0
+    _describe(recursos, a.dry_run)
+    if a.dry_run:
+        return 0
+    _cierra(recursos)
+    print('  Done. `agents-city seat` brings it all back.')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())