agents-city 0.1.0

package/plugin/scripts/launch.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Create a short, auditable launcher so tmux never has to paste long commands."""
+import argparse
+import base64
+import json
+import os
+import shlex
+import time
+
+import runtime_processes
+
+
+def safe(value):
+    cleaned = ''.join(c if c.isalnum() or c in '-_' else '-' for c in value.lower())
+    return cleaned.strip('-')[:80] or 'actor'
+
+
+def make(args):
+    directory = os.path.join(runtime_processes.ruta(args.data), 'launchers')
+    app_home = os.path.realpath(os.environ.get('AGENTS_CITY_HOME') or
+                                os.path.join(args.data, '..', '..'))
+    os.makedirs(directory, mode=0o700, exist_ok=True)
+    os.chmod(directory, 0o700)
+    path = os.path.join(directory, f'{safe(args.actor)}-{os.getpid()}-{time.time_ns()}.sh')
+    command = base64.b64encode(args.command.encode('utf-8')).decode('ascii')
+    failure = base64.b64encode(json.dumps({
+        'sourceId': f'launcher:{args.actor}:{time.time_ns()}:failed',
+        'kind': 'runtime.launch.failed',
+        'phase': 'failed',
+        'tone': 'error',
+        'title': f'{args.actor} failed to start',
+        'summary': 'The agent command exited before a usable session was ready.',
+    }).encode('utf-8')).decode('ascii')
+    log = os.path.realpath(os.path.join(os.path.dirname(__file__), 'runtime_log.py'))
+    client = os.path.realpath(args.client)
+    lines = [
+        '#!/usr/bin/env bash',
+        'set +e',
+        f'DATA={shlex.quote(os.path.realpath(args.data))}',
+        f'APP_HOME={shlex.quote(app_home)}',
+        f'ACTOR={shlex.quote(args.actor)}',
+        f'WORKDIR={shlex.quote(os.path.realpath(args.cwd))}',
+        f'RUNTIME_DIR={shlex.quote(os.path.dirname(directory))}',
+        f'CLIENT={shlex.quote(client)}',
+        f'RUNTIME_LOG={shlex.quote(log)}',
+        f'COMMAND_B64={shlex.quote(command)}',
+        f'FAILURE_B64={shlex.quote(failure)}',
+        'export AGENTS_CITY_HOME="$APP_HOME" AGENTS_CITY_DATA="$DATA" CITY_BUS_ACTOR="$ACTOR"',
+        'python3 "$RUNTIME_LOG" launch.started --data "$DATA" --component launcher '
+        '  --actor "$ACTOR" --outcome starting',
+        'cd "$WORKDIR"',
+        'cd_status=$?',
+        'if [ "$cd_status" -eq 0 ]; then',
+        '  command_text="$(printf %s "$COMMAND_B64" | base64 --decode)"',
+        '  eval "$command_text"',
+        '  status=$?',
+        'else',
+        '  status=$cd_status',
+        'fi',
+        'if [ "$status" -eq 0 ]; then',
+        '  python3 "$RUNTIME_LOG" launch.exited --data "$DATA" --component launcher '
+        '    --actor "$ACTOR" --outcome ok --message "exit 0"',
+        'else',
+        '  python3 "$RUNTIME_LOG" launch.failed --data "$DATA" --component launcher '
+        '    --actor "$ACTOR" --outcome failed --message "exit $status"',
+        '  printf %s "$FAILURE_B64" | base64 --decode | env AGENTS_CITY_DATA="$DATA" '
+        '    CITY_BUS_ACTOR="$ACTOR" node "$CLIENT" activity publish '
+        '    --input - >/dev/null 2>&1 || true',
+        '  printf "\\n  Agents City: %s failed to start (exit %s).\\n" "$ACTOR" "$status" >&2',
+        '  printf "  Diagnostics: %s/diagnostics.jsonl\\n\\n" "$RUNTIME_DIR" >&2',
+        'fi',
+        'exit "$status"',
+        '',
+    ]
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o700)
+    with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+        stream.write('\n'.join(lines))
+    print(path)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('verb', choices=['create'])
+    parser.add_argument('--data', required=True)
+    parser.add_argument('--actor', required=True)
+    parser.add_argument('--cwd', required=True)
+    parser.add_argument('--client', required=True)
+    parser.add_argument('--command', required=True)
+    args = parser.parse_args()
+    make(args)
+
+
+if __name__ == '__main__':
+    main()

package/plugin/scripts/logs.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Read or follow one city's durable activity and diagnostic logs."""
+import argparse
+import json
+import os
+import sys
+import time
+
+import city_env
+import runtime_processes
+
+
+def read(path):
+    try:
+        with open(path, encoding='utf-8') as stream:
+            return [json.loads(line) for line in stream if line.strip()]
+    except (OSError, ValueError, json.JSONDecodeError):
+        return []
+
+
+def display(record, raw=False):
+    if raw:
+        print(json.dumps(record, ensure_ascii=False), flush=True)
+        return
+    at = str(record.get('at', ''))[11:19] or '--:--:--'
+    source = 'activity' if record.get('protocol') == 'agents-city-activity/1' else 'diagnostic'
+    actor = record.get('actor') or record.get('component') or 'city'
+    event = record.get('kind') or record.get('event') or 'event'
+    message = record.get('summary') or record.get('message') or record.get('outcome') or ''
+    print(f'{at}  {source:<10} {str(actor):<18} {event}  {message}', flush=True)
+
+
+def main():  # noqa: C901 - CLI selection and follow mode share one stream lifecycle
+    parser = argparse.ArgumentParser(
+        description='show persistent city conversations and operational diagnostics')
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        '--activity', action='store_true', help='only visible conversation/work events')
+    group.add_argument(
+        '--diagnostics', action='store_true', help='only operational diagnostics')
+    parser.add_argument('-f', '--follow', action='store_true', help='keep following new events')
+    parser.add_argument(
+        '-n', '--lines', type=int, default=100, help='initial records (default: 100)')
+    parser.add_argument('--json', action='store_true', help='emit JSONL unchanged')
+    args = parser.parse_args()
+
+    data = city_env.datos()
+    if not data:
+        print('agents-city: no selected city', file=sys.stderr)
+        return 2
+    directory = runtime_processes.ruta(data)
+    selected = []
+    if not args.diagnostics:
+        selected.append(os.path.join(directory, 'activity.jsonl'))
+    if not args.activity:
+        selected.append(os.path.join(directory, 'diagnostics.jsonl'))
+
+    rows = []
+    positions = {}
+    for path in selected:
+        values = read(path)
+        rows.extend(values)
+        try:
+            positions[path] = os.path.getsize(path)
+        except OSError:
+            positions[path] = 0
+    rows.sort(key=lambda row: str(row.get('at', '')))
+    for row in rows[-max(0, args.lines):]:
+        display(row, args.json)
+    if not args.follow:
+        return 0
+
+    try:
+        while True:
+            for path in selected:
+                try:
+                    size = os.path.getsize(path)
+                    if size < positions[path]:
+                        positions[path] = 0
+                    if size == positions[path]:
+                        continue
+                    with open(path, encoding='utf-8') as stream:
+                        stream.seek(positions[path])
+                        for line in stream:
+                            try:
+                                display(json.loads(line), args.json)
+                            except json.JSONDecodeError:
+                                pass
+                        positions[path] = stream.tell()
+                except OSError:
+                    continue
+            time.sleep(.2)
+    except KeyboardInterrupt:
+        return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugin/scripts/pairing.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Road pairing: how an unknown city earns the right to write to a seat.
+
+Exchanging invitation files works, but it is friction, and friction is why
+nobody connects two cities. Pairing is the low-friction path: an unknown seat's
+first message yields a short code the owner approves once. Approving grants one
+thing only — permission for that address to send to this seat — never road
+membership, never chair authority, never anything the code's holder did not
+already have.
+
+The safety comes from four constants and two rules. A code is short and
+unambiguous (no 0/O/1/I) so it can be read aloud; it expires; only a bounded
+number can be pending per city, so a flood cannot mint an unbounded backlog;
+and the human code is never echoed by tooling — approvals happen by an opaque
+id derived from it. The two rules: a pending request is created (and its code
+revealed) at most once per sender per window, and an approval is only ever
+consulted under the pairing policy, never to widen an allowlist.
+
+State is one JSON file per city under its runtime dir. No network, no daemon:
+the seat reads and writes it, the tests drive it on any platform.
+"""
+
+import hashlib
+import json
+import os
+import secrets
+import time
+
+CODIGO_LARGO = 8
+CODIGO_ALFABETO = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'  # no 0/O/1/I, read-aloud safe
+PENDIENTE_TTL_MS = 60 * 60 * 1000        # a code is good for one hour
+PENDIENTE_MAX = 3                        # at most this many pending per city
+CONCEDIDO_MAX = 500                      # a generous cap on approved senders
+
+
+def _ahora_ms():
+    return int(time.time() * 1000)
+
+
+def _estado(datos):
+    real = os.path.realpath(os.path.expanduser(datos))
+    ruta = os.path.join(real, '.runtime')
+    os.makedirs(ruta, mode=0o700, exist_ok=True)
+    return os.path.join(ruta, 'pairing.json')
+
+
+def _lee(datos):
+    try:
+        with open(_estado(datos), encoding='utf-8') as f:
+            objeto = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        objeto = {}
+    objeto.setdefault('pending', {})
+    objeto.setdefault('granted', {})
+    return objeto
+
+
+def _escribe(datos, objeto):
+    ruta = _estado(datos)
+    tmp = f'{ruta}.tmp'
+    with open(tmp, 'w', encoding='utf-8') as f:
+        json.dump(objeto, f, indent=2, sort_keys=True)
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, ruta)
+
+
+def _codigo():
+    return ''.join(secrets.choice(CODIGO_ALFABETO) for _ in range(CODIGO_LARGO))
+
+
+def id_solicitud(direccion, codigo):
+    """The opaque id a tool uses to approve, so the human code never travels."""
+    crudo = f'{direccion}\0{codigo}'.encode()
+    return 'pr_' + hashlib.sha256(crudo).hexdigest()[:20]
+
+
+def _purga(objeto, ahora):
+    objeto['pending'] = {
+        d: p for d, p in objeto['pending'].items()
+        if ahora - int(p.get('ts', 0)) < PENDIENTE_TTL_MS
+    }
+
+
+def concedido(datos, direccion):
+    """True when this seat address has already been approved to write here."""
+    objeto = _lee(datos)
+    return direccion in objeto['granted']
+
+
+def solicita(datos, direccion):
+    """Record a pending pairing for `direccion`, returning the code exactly once.
+
+    Returns `{"code", "id", "created": True}` the first time within the TTL, and
+    `{"id", "created": False}` on any repeat — the code is revealed once, so
+    re-messaging cannot re-spam it, and a flood cannot exceed the pending cap.
+    """
+    objeto = _lee(datos)
+    if direccion in objeto['granted']:
+        return {'created': False, 'already': True}
+    ahora = _ahora_ms()
+    _purga(objeto, ahora)
+    existente = objeto['pending'].get(direccion)
+    if existente:
+        return {'created': False, 'id': existente['id']}
+    if len(objeto['pending']) >= PENDIENTE_MAX:
+        return {'created': False, 'full': True}
+    codigo = _codigo()
+    entrada = {'code': codigo, 'id': id_solicitud(direccion, codigo), 'ts': ahora}
+    objeto['pending'][direccion] = entrada
+    _escribe(datos, objeto)
+    return {'created': True, 'code': codigo, 'id': entrada['id']}
+
+
+def _concede(datos, seleccion):
+    """Grant one pending request in a single read/write, given a picker.
+
+    `seleccion(pending) -> direccion|None` is the only thing that differs
+    between approving by code and approving by opaque id, so both entry points
+    share the read, purge, cap check, grant and write exactly once.
+    """
+    objeto = _lee(datos)
+    ahora = _ahora_ms()
+    _purga(objeto, ahora)
+    encontrado = seleccion(objeto['pending'])
+    if not encontrado:
+        _escribe(datos, objeto)
+        return None
+    if len(objeto['granted']) >= CONCEDIDO_MAX:
+        raise ValueError('the pairing grant table is full; revoke unused senders first')
+    objeto['granted'][encontrado] = {'ts': ahora}
+    del objeto['pending'][encontrado]
+    _escribe(datos, objeto)
+    return encontrado
+
+
+def _por_campo(campo, objetivo):
+    """A picker matching one pending field in constant time — no timing signal.
+
+    The target is compared as UTF-8 bytes so a non-ASCII or non-string input
+    (e.g. a client-supplied opaque id) yields a clean no-match instead of the
+    TypeError `compare_digest` raises on non-ASCII strings.
+    """
+    objetivo_b = str(objetivo or '').encode('utf-8')
+
+    def elige(pending):
+        hallado = None
+        for direccion, p in pending.items():
+            if secrets.compare_digest(str(p.get(campo, '')).encode('utf-8'), objetivo_b):
+                hallado = direccion
+        return hallado
+    return elige
+
+
+def aprueba(datos, codigo):
+    """Approve a pending request by its human code. Returns the address or None.
+
+    A non-string or empty code matches nothing and returns None — the
+    documented 'a wrong code approves nothing', never a crash.
+    """
+    return _concede(datos, _por_campo('code', str(codigo or '').strip().upper()))
+
+
+def aprueba_por_id(datos, id_):
+    """Approve by opaque id (what tooling holds), never echoing the code."""
+    return _concede(datos, _por_campo('id', id_))
+
+
+def revoca(datos, direccion):
+    """Withdraw a previously granted sender. Returns True if one was removed."""
+    objeto = _lee(datos)
+    quitado = objeto['granted'].pop(direccion, None) is not None
+    objeto['pending'].pop(direccion, None)
+    _escribe(datos, objeto)
+    return quitado
+
+
+def pendientes(datos):
+    """Opaque view of pending requests: id + age, never the code."""
+    objeto = _lee(datos)
+    ahora = _ahora_ms()
+    _purga(objeto, ahora)
+    return [
+        {'address': d, 'id': p['id'], 'ageMinutes': (ahora - int(p['ts'])) // 60000}
+        for d, p in sorted(objeto['pending'].items())
+    ]

package/plugin/scripts/parcels.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""The one reader of `parcels.yml`.
+
+There were two, and they were not the same reader. Both walked the format with the
+same byte-identical regex, and then they disagreed: the seeder handled the `lab:`
+section and complained about lines it could not parse; the reporter did neither,
+and read the folder out of a key called `path` that this format has never had. So
+the map and the growth reporter had different ideas about the same file, and the
+reporter's idea was wrong in a way that stopped it working at all.
+
+Two readers of one format is a bug waiting for someone to edit only one of them.
+
+It lives here, in `plugin/scripts/`, and not next to the seeder, because this
+directory is what gets installed on everybody's machine — the plugin ships without
+`city/`, so the plugin cannot import from there. The seeder runs from a clone and
+can import from here, so this is the only direction that works.
+
+Deliberately not YAML: the format is a line at a time on purpose, so this runs
+anywhere with no dependency to install.
+
+    repos:
+      main-site:
+        - ruta: "content/**/deposits/**" ; unidad: banking ; nombre: "main · deposits"
+        - ruta: ""                       ; unidad: none    ; nombre: "main · platform"
+    lab: []
+"""
+import re
+
+# A parcel line. Values may be quoted, fields are separated by `;`, and a missing
+# field is a default rather than an error.
+CAMPO = re.compile(r'(\w+):\s*"?([^";\n]*?)"?\s*(?:;|$)')
+CABECERA = re.compile(r'^[a-zA-Z0-9_.\-]+:\s*$')       # `repos:` / `lab:`
+REPO = re.compile(r'^  [a-zA-Z0-9_.\-]+:\s*$')         # `  main-site:`
+
+
+def campos(linea):
+    """`- ruta: "x" ; unidad: y ; nombre: "z"` -> {'ruta': 'x', …}"""
+    return dict(CAMPO.findall(linea.strip().lstrip('- ')))
+
+
+def identidad(repo, ruta):
+    """A parcel's id, which has to be computed the same way everywhere.
+
+    The reporter pushes growth keyed on this and the map stores rows keyed on this.
+    If the two ever disagree, growth lands on nothing and neither side says so.
+    """
+    return f'{repo}:{ruta}' if ruta else repo
+
+
+def lee(ruta_fichero):
+    """Walk the file once. Returns (parcelas, lab, raras).
+
+    parcelas: [{'id', 'repo', 'ruta', 'unidad', 'nombre'}] in file order
+    lab:      {repo, …} listed under `lab:`
+    raras:    lines under a repo that are not parcels — the caller decides whether
+              to complain, because a silent one is how a repo ends up in the wrong
+              district for a reason nobody can find
+    """
+    try:
+        with open(ruta_fichero, encoding='utf-8') as f:
+            txt = f.read()
+    except (FileNotFoundError, IsADirectoryError):
+        return [], set(), []
+
+    fuera, lab, raras = [], set(), []
+    repo, en_lab = None, False
+    for linea in txt.splitlines():
+        if re.match(r'^lab:\s*$', linea):
+            en_lab, repo = True, None
+            continue
+        if CABECERA.match(linea):
+            en_lab = False
+            continue
+        if REPO.match(linea):
+            repo = linea.strip().rstrip(':')
+        elif linea.strip().startswith('- ruta:') and repo:
+            c = campos(linea)
+            r = c.get('ruta', '')
+            fuera.append({'id': identidad(repo, r), 'repo': repo, 'ruta': r,
+                          'unidad': c.get('unidad', 'none'),
+                          'nombre': c.get('nombre', repo)})
+        elif linea.strip().startswith('- '):
+            suelto = linea.strip().lstrip('- ').strip()
+            if en_lab:
+                if suelto:
+                    lab.add(suelto)
+            elif repo:
+                raras.append(linea.strip()[:70])
+    return fuera, lab, raras
+
+
+def escribe(ruta_fichero, porRepo, lab=()):
+    """Write the whole file back, in the shape `lee` reads.
+
+    `porRepo` is {repo: [{'ruta', 'unidad', 'nombre'}, …]}. This exists so the
+    modelling — the one thing no tool can do for you — can be edited with a form
+    instead of by hand in a format nobody remembers. Round-tripping through `lee`
+    is pinned by a test, because a writer that drifts from its reader is exactly
+    the bug this module was created to end.
+    """
+    lineas = ['# Which slice of which repo serves which unit.',
+              '#',
+              '# A house is not a repo: it is a **parcel**, a slice of a repo serving one',
+              '# unit. One repo can hold several, and that is the central fact of most',
+              '# codebases.',
+              '',
+              'repos:']
+    for repo in sorted(porRepo):
+        filas = porRepo[repo] or [{'ruta': '', 'unidad': 'none', 'nombre': repo}]
+        lineas.append(f'  {repo}:')
+        for f in filas:
+            ruta = str(f.get('ruta', '')).replace(';', '').replace('"', '')
+            unidad = str(f.get('unidad', 'none')).replace(';', '') or 'none'
+            nombre = str(f.get('nombre') or repo).replace(';', ',').replace('"', "'")
+            lineas.append(f'    - ruta: "{ruta}"  ; unidad: {unidad} ; nombre: "{nombre}"')
+    lineas += ['', '# Research that does not ship yet gets its own district instead of',
+               '# reading as waste among the rest.']
+    lineas.append('lab:' if lab else 'lab: []')
+    for r in sorted(lab):
+        lineas.append(f'  - {r}')
+    with open(ruta_fichero, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(lineas) + '\n')
+
+
+def aviso(raras):
+    """What to say about lines that could not be read, or '' if there were none."""
+    if not raras:
+        return ''
+    lineas = [f'parcels.yml: {len(raras)} line(s) I could not read — they are being '
+              f'ignored. Use: - ruta: "<glob>" ; unidad: <unit> ; nombre: "<name>"']
+    lineas += [f'  {r}' for r in raras[:5]]
+    return '\n'.join(lineas)

package/plugin/scripts/read-card.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Read one field out of a card's frontmatter, for the shell scripts.
+
+    read-card.py <card.md> agent
+    read-card.py <card.md> repos     -> comma-separated list
+    read-card.py --window <repo>     -> canonical tmux/bus actor slug
+    read-card.py --actor-role <card.md> <actor> -> safe operating role or blank
+
+A thin front on card.py, which is where the parsing lives. It used to hold its own
+copy, and that copy is why the tmux session asked for `agente` — a field no card in
+this repo has ever carried — and got nothing every single time.
+
+`agente` still answers, for a card somebody wrote by hand.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import card  # noqa: E402
+
+
+def main():
+    if len(sys.argv) == 3 and sys.argv[1] == '--window':
+        print(card.ventana(sys.argv[2]))
+        return
+    if len(sys.argv) == 4 and sys.argv[1] == '--actor-role':
+        try:
+            texto = open(sys.argv[2], encoding='utf-8').read()
+        except OSError as e:
+            sys.exit(f'cannot read {sys.argv[2]}: {e}')
+        actor = card.ventana(sys.argv[3])
+        print(card.rol_seguro(card.campo(texto, f'role.{actor}')))
+        return
+    if len(sys.argv) < 3:
+        sys.exit(
+            'usage: read-card.py <card.md> <field> | --window <repo> | '
+            '--actor-role <card.md> <actor>'
+        )
+    ruta, campo = sys.argv[1], sys.argv[2]
+    try:
+        with open(ruta, encoding='utf-8') as f:
+            texto = f.read()
+    except OSError as e:
+        sys.exit(f'cannot read {ruta}: {e}')
+    valor = card.campo(texto, campo)
+    # A bracketed value is a list everywhere else in this product — `repos:`,
+    # `agents:`, `mounts.<agent>:` — and the shell wants one line. Deciding by
+    # SHAPE rather than by a list of blessed field names is what stopped this
+    # from having to be edited every time the card grew another list.
+    esLista = valor.strip().startswith('[') and valor.strip().endswith(']')
+    print(','.join(card.lista(valor)) if esLista else valor)
+
+
+if __name__ == '__main__':
+    main()