agents-city 0.3.0-beta.21

package/plugin/scripts/cage.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""The cage: one macOS seatbelt profile per repo window.
+
+The yolo flag stays — a committee cannot work if every bus command needs a
+human. What changes is what the kernel lets the window touch. An agent inside
+the cage is never asked anything: writes land only in its own repo and the
+runtime state it legitimately owns, and the files that turn a prompt injection
+into a credential theft (`~/.ssh`, `~/.git-credentials`, cloud configs, the
+`gh` token) simply do not exist for it.
+
+Seatbelt semantics, verified on a real machine before this was written:
+the LAST matching rule wins, children and grandchildren inherit the profile,
+and the network stays open unless denied. So the profile reads top to bottom
+as: allow everything, forbid all writes, re-allow the working set, and finally
+seal the secrets — reads and writes both.
+
+Honest limits, documented rather than hidden: credentials held in the macOS
+keychain travel over IPC, not file reads, so a jailed `git push` still works
+when the owner keeps GitHub credentials there; outbound network stays open;
+and every window still runs as the same OS user. The cage narrows what a
+compromised window can steal — it is not hostile-process isolation.
+"""
+
+import argparse
+import os
+import re
+import shutil
+import sys
+
+import rutas
+
+# Read+write denied inside the cage: directories that exist to hold credentials.
+SECRETOS_DIR = (
+    '.ssh', '.aws', '.kube', '.gnupg',
+    os.path.join('.config', 'gcloud'),
+    os.path.join('.config', 'gh'),
+    os.path.join('.docker'),
+)
+# Single files with the same job. `~/.npmrc` is deliberately NOT here: denying
+# it breaks every `npm install` for owners who configure a registry, and a
+# broken product protects nobody. Owners who keep tokens there add it through
+# CITY_CAGE_DENY.
+SECRETOS_FICHERO = ('.git-credentials', '.netrc', '.pgpass')
+
+# Writable beyond the repo: the runtime state and build caches a working agent
+# legitimately owns. Everything here is cache or agent state, never a secret —
+# with the exceptions sealed again further down.
+ESCRITURA_CASA = (
+    '.claude', '.agents-city', '.codex', '.opencode', '.kimi',
+    '.npm', '.cache', '.cargo', '.rustup', '.gradle', '.m2',
+    '.pnpm-store', '.bun',
+    os.path.join('Library', 'Caches'),
+    os.path.join('Library', 'Logs'),
+    os.path.join('Library', 'pnpm'),
+    os.path.join('Library', 'Developer'),
+)
+ESCRITURA_SISTEMA = ('/dev', '/private/tmp', '/private/var/tmp', '/private/var/folders')
+
+
+def _sbpl(ruta):
+    """Quote one path for SBPL: backslashes and double quotes escaped."""
+    return '"' + ruta.replace('\\', '\\\\').replace('"', '\\"') + '"'
+
+
+def agents_home(casa):
+    """The Agents City state root, honouring AGENTS_CITY_HOME like the broker.
+
+    The broker writes its token store under this root (`broker.estado_de`), so
+    the cage must seal the *same* root it uses — not a hardcoded `~/.agents-city`
+    that silently misses the broker dir when the owner relocated the home.
+    """
+    hogar = os.environ.get('AGENTS_CITY_HOME') or os.path.join(casa, '.agents-city')
+    return rutas.canonicaliza(hogar)
+
+
+def sellados(casa):
+    """The canonical set of read+write-sealed roots.
+
+    The single source of truth for "must never be reachable": the deny lines
+    emit it, and the write-allow filter refuses any owner path that re-enters
+    it. Extra owner denies (CITY_CAGE_DENY) join it, so an owner can widen the
+    seal but the allow-list can never outrun it.
+    """
+    ac = agents_home(casa)
+    extra = [p for p in os.environ.get('CITY_CAGE_DENY', '').split(':') if p]
+    raices = [os.path.join(casa, d) for d in SECRETOS_DIR]
+    raices += [os.path.join(casa, f) for f in SECRETOS_FICHERO]
+    raices += [os.path.expanduser(p) for p in extra]
+    raices.append(os.path.join(ac, '.runtime', 'broker'))
+    raices.append(os.path.join(casa, '.cargo', 'credentials'))
+    raices.append(os.path.join(casa, '.cargo', 'credentials.toml'))
+    return [rutas.canonicaliza(r) for r in raices]
+
+
+def _permitidas_escritura(repo, casa, bloqueados, extra_escritura=()):
+    """Canonical write-allow roots, given the already-computed sealed set.
+
+    Covering roots are intentionally kept: the sealed-secret block is emitted
+    last and, under seatbelt's last-match-wins rule, re-denies any secret that
+    a broad writable ancestor would otherwise expose. So the ordering — not a
+    filter here — is the guarantee, and `bin/test-cage.py` proves it against the
+    live kernel. What this pass does add is a loud drop of an owner extra that
+    resolves strictly *inside* a sealed root: that write is already dead under
+    the final deny, so honouring it silently would only mislead. The relocated
+    state home is added explicitly so a custom AGENTS_CITY_HOME stays writable.
+
+    `extra_escritura` is where the agent-first model plugs in: the resolved
+    targets of the agent's workspace mounts (symlinks already followed to their
+    real path). They pass through the same sealed-root check as any owner extra.
+    """
+    extra = [os.path.expanduser(p)
+             for p in os.environ.get('CITY_CAGE_ALLOW_WRITE', '').split(':') if p]
+    extra += list(extra_escritura)
+    fijas = [repo, agents_home(casa), *ESCRITURA_SISTEMA]
+    fijas += [os.path.join(casa, p) for p in ESCRITURA_CASA]
+    aceptadas = [rutas.canonicaliza(c) for c in fijas]
+    for c in extra:
+        if any(rutas.dentro_de(c, raiz) for raiz in bloqueados):
+            sys.stderr.write(f'cage: ignoring write-allow {c}: inside a sealed root\n')
+            continue
+        aceptadas.append(rutas.canonicaliza(c))
+    return aceptadas
+
+
+def _lineas_permite_escritura(repo, casa, bloqueados, extra_escritura=()):
+    permitidas = _permitidas_escritura(repo, casa, bloqueados, extra_escritura)
+    lineas = [f'  (subpath {_sbpl(r)})' for r in permitidas]
+    # Claude keeps `~/.claude.json` (and its backups) at the HOME root.
+    lineas.append(f'  (regex #"^{re.escape(os.path.join(casa, ".claude.json"))}")')
+    return lineas
+
+
+def _lineas_secretos(casa, bloqueados):
+    lineas = []
+    for raiz in bloqueados:
+        # A file target uses `literal`; a directory (or a not-yet-created dir)
+        # uses `subpath` so everything beneath it is sealed too.
+        if os.path.isfile(raiz):
+            lineas.append(f'  (literal {_sbpl(raiz)})')
+        else:
+            lineas.append(f'  (subpath {_sbpl(raiz)})')
+    # Remote road tokens configured for the seat: repo windows must never read
+    # them, even though the rest of `~/.claude` stays open for the runtime.
+    canal = re.escape(os.path.join(casa, '.claude', 'channels'))
+    lineas.append(f'  (regex #"^{canal}/[^/]+/\\.env$")')
+    return lineas
+
+
+def perfil(repo, casa=None, fichero_token=None, extra_escritura=()):
+    """The SBPL profile for one window, as text. Pure: no filesystem writes.
+
+    `repo` is the window's working directory (a repo, or an agent workspace).
+    `extra_escritura` are additional writable roots — the resolved targets of an
+    agent's workspace mounts — sealed-root-checked like any other write-allow.
+    """
+    casa = rutas.canonicaliza(casa or '~')
+    repo = rutas.canonicaliza(repo)
+    if not os.path.isdir(repo):
+        raise ValueError(f'the cage needs an existing working directory, got: {repo}')
+    # Compute the sealed set once and thread it through every helper below.
+    bloqueados = sellados(casa)
+    motivo = rutas.motivo_bloqueo(repo, bloqueados)
+    if motivo:
+        raise ValueError(f'the working directory is unsafe to cage: {motivo}')
+    partes = [
+        '(version 1)',
+        '; Agents City cage — generated, one per window. Do not edit.',
+        '(allow default)',
+        '(deny file-write*)',
+        '(allow file-write*',
+        *_lineas_permite_escritura(repo, casa, bloqueados, extra_escritura),
+        ')',
+        '(deny file-read* file-write*',
+        *_lineas_secretos(casa, bloqueados),
+        ')',
+    ]
+    if fichero_token:
+        # This window's own broker token, and only this window's: the broker
+        # directory deny above stays in force for every other file in it.
+        partes.append(f'(allow file-read* (literal {_sbpl(rutas.canonicaliza(fichero_token))}))')
+    return '\n'.join(partes) + '\n'
+
+
+def disponible():
+    """Whether this machine can cage a window at all."""
+    if os.environ.get('CITY_CAGE', '1') == '0':
+        return False
+    return sys.platform == 'darwin' and shutil.which('sandbox-exec') is not None
+
+
+def escribe_perfil(repo, ventana, casa=None, fichero_token=None, extra_escritura=()):
+    """Write the profile under the runtime dir and return its path."""
+    casa_real = os.path.realpath(casa or os.path.expanduser('~'))
+    directorio = os.path.join(casa_real, '.agents-city', '.runtime', 'cage')
+    os.makedirs(directorio, mode=0o700, exist_ok=True)
+    segmento = re.sub(r'[^a-zA-Z0-9_-]', '-', ventana) or 'window'
+    ruta = os.path.join(directorio, f'{segmento}.sb')
+    contenido = perfil(repo, casa=casa_real, fichero_token=fichero_token,
+                       extra_escritura=extra_escritura)
+    with open(ruta, 'w', encoding='utf-8') as f:
+        f.write(contenido)
+    os.chmod(ruta, 0o600)
+    return ruta
+
+
+def linea(repo, ventana, casa=None, fichero_token=None, extra_escritura=()):
+    """The launch prefix for one window: `sandbox-exec -f <profile> `, or ''.
+
+    Empty means "launch uncaged": not macOS, no sandbox-exec, or the owner set
+    CITY_CAGE=0. The caller prepends the result verbatim, so the degraded path
+    is exactly the behaviour the product always had.
+    """
+    if not disponible():
+        return ''
+    ruta = escribe_perfil(repo, ventana, casa=casa, fichero_token=fichero_token,
+                          extra_escritura=extra_escritura)
+    return f'sandbox-exec -f {ruta} '
+
+
+def main():
+    p = argparse.ArgumentParser(description='One seatbelt cage per window.')
+    p.add_argument('orden', choices=['line', 'profile', 'check'])
+    p.add_argument('--repo', help='the working directory this window owns')
+    p.add_argument('--window', default='window', help='window name, used to name the profile')
+    p.add_argument('--home', help='HOME override (tests only)')
+    p.add_argument('--token-file', help="this window's broker token file, allowed read-only")
+    p.add_argument('--mounts', default='',
+                   help='colon-separated resolved mount targets to also make writable')
+    args = p.parse_args()
+    if args.orden == 'check':
+        print('cage available' if disponible() else 'cage unavailable on this machine')
+        return 0 if disponible() else 1
+    if not args.repo:
+        print('--repo is required', file=sys.stderr)
+        return 2
+    extra = tuple(m for m in args.mounts.split(':') if m)
+    try:
+        if args.orden == 'profile':
+            sys.stdout.write(perfil(args.repo, casa=args.home, fichero_token=args.token_file,
+                                    extra_escritura=extra))
+        else:
+            sys.stdout.write(
+                linea(args.repo, args.window, casa=args.home, fichero_token=args.token_file,
+                      extra_escritura=extra))
+    except (OSError, ValueError) as e:
+        print(f'{e}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugin/scripts/capabilities.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Live, read-only recognition of skills available to a city's repo agents.
+
+Agents City never installs, copies, enables or edits a skill.  The runtime in a
+repo remains the source of truth and decides whether a skill applies to a task.
+This module only discovers conventional repo-local ``SKILL.md`` files so a seat
+can see which agent is likely to know how to help.
+"""
+
+import os
+import re
+import subprocess
+import sys
+
+import card
+import cities
+import workspace
+
+
+RAICES = (".claude/skills", ".codex/skills", ".agents/skills", "skills")
+
+
+def _campo(texto, clave):
+    if not texto.startswith("---"):
+        return ""
+    partes = texto.split("---", 2)
+    if len(partes) < 3:
+        return ""
+    m = re.search(rf"^{re.escape(clave)}:[ \t]*(.+)$", partes[1], re.M)
+    return m.group(1).strip().strip("\"'") if m else ""
+
+
+def descubre_repo(ruta_repo):
+    """Skills declared by this repo, with no cache and no writes."""
+    fuera, vistos = [], set()
+    raiz_manifest = os.path.join(ruta_repo, "SKILL.md")
+    if os.path.isfile(raiz_manifest):
+        try:
+            texto = open(raiz_manifest, encoding="utf-8").read()
+        except OSError:
+            texto = ""
+        if texto:
+            real = os.path.realpath(raiz_manifest)
+            vistos.add(real)
+            fuera.append(
+                {
+                    "name": _campo(texto, "name") or os.path.basename(ruta_repo),
+                    "description": _campo(texto, "description"),
+                    "manifest": real,
+                    "provider": "repo",
+                }
+            )
+    for relativa in RAICES:
+        base = os.path.join(ruta_repo, relativa)
+        if not os.path.isdir(base):
+            continue
+        for nombre in sorted(os.listdir(base)):
+            manifiesto = os.path.join(base, nombre, "SKILL.md")
+            if not os.path.isfile(manifiesto):
+                continue
+            real = os.path.realpath(manifiesto)
+            if real in vistos:
+                continue
+            vistos.add(real)
+            try:
+                texto = open(manifiesto, encoding="utf-8").read()
+            except OSError:
+                continue
+            fuera.append(
+                {
+                    "name": _campo(texto, "name") or nombre,
+                    "description": _campo(texto, "description"),
+                    "manifest": real,
+                    "provider": relativa.split("/", 1)[0].lstrip(".") or "repo",
+                }
+            )
+    return fuera
+
+
+def _indice_repos():
+    guion = os.path.join(os.path.dirname(__file__), "find-repos.sh")
+    try:
+        salida = subprocess.run([guion], capture_output=True, text=True, timeout=300).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return {}
+    fuera = {}
+    for linea in salida.splitlines():
+        if "\t" in linea:
+            nombre, ruta = linea.split("\t", 1)
+            fuera[nombre.strip()] = ruta.strip()
+    return fuera
+
+
+def ficha_de_ciudad(datos):
+    owner = cities.lee_clave(datos, "owner")
+    preferida = os.path.join(datos, f"{owner}.md") if owner else ""
+    if preferida and os.path.isfile(preferida):
+        return preferida
+    try:
+        fichas = sorted(
+            os.path.join(datos, f)
+            for f in os.listdir(datos)
+            if f.endswith(".md") and card.lee(os.path.join(datos, f)).get("user")
+        )
+    except OSError:
+        fichas = []
+    return fichas[0] if fichas else ""
+
+
+def ruta_de(nombre, rutas=None):
+    """One legacy repo's folder on this disk, or ''. The single mechanism both
+    full discovery and one-agent lookups share — resolving one path must never
+    cost a whole-city skill scan."""
+    rutas = _indice_repos() if rutas is None else rutas
+    code = os.path.expanduser(os.environ.get("CITY_CODE_DIR", "~/codigo"))
+    ruta = rutas.get(nombre, os.path.join(code, nombre))
+    return os.path.realpath(ruta) if os.path.isdir(ruta) else ""
+
+
+def descubre_ciudad(datos, rutas=None):
+    """``{agent: {path, role, skills}}`` for the city's support agents.
+
+    Both card shapes, through the one normaliser (`workspace.agentes`): a
+    legacy repo agent looks for its repo on disk exactly as before, and an
+    agents-first agent looks in its own workspace and in every mount it
+    declares. Before this, an agents-first city honestly full of skills showed
+    "Agents & skills 0" — the discovery only knew `repos:`.
+    """
+    ficha = ficha_de_ciudad(datos)
+    if not ficha:
+        return {}
+    try:
+        texto = open(ficha, encoding="utf-8").read()
+    except OSError:
+        return {}
+    try:
+        agentes = workspace.agentes(texto, datos)
+    except ValueError:
+        # A malformed card (two names that slug to one identity) is the card
+        # tools' error to raise loudly; read-only discovery just has nothing
+        # safe to list for it.
+        return {}
+    if not agentes:
+        return {}
+    # The disk index is a find-repos scan: paid lazily, and only when a legacy
+    # agent actually needs it — a pure agents-first city never touches it.
+    fuera = {}
+    for a in agentes:
+        if a.legacy:
+            rutas = _indice_repos() if rutas is None else rutas
+            candidatos = [ruta_de(a.nombre, rutas)]
+        else:
+            candidatos = [a.workspace] + [os.path.expanduser(m) for m in a.mounts]
+        existentes = [c for c in candidatos if c and os.path.isdir(c)]
+        skills = []
+        vistos = set()
+        for c in existentes:
+            for s in descubre_repo(c):
+                if s["name"] in vistos:
+                    continue
+                vistos.add(s["name"])
+                skills.append(s)
+        fuera[a.nombre] = {
+            "path": os.path.realpath(existentes[0]) if existentes else "",
+            "role": a.rol,
+            "skills": skills,
+        }
+    return fuera
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help", "help"):
+        print(
+            "usage: agents-city skills [city]\n\n"
+            "Read-only discovery of skills already installed in each repo."
+        )
+        return 0
+    usuario = cities.usuario_actual()
+    pedida = sys.argv[1] if len(sys.argv) > 1 else ""
+    datos = cities.resuelve(pedida, usuario) if pedida else cities.actual(usuario)
+    if not datos:
+        print(f"  No city called {pedida!r}.", file=sys.stderr)
+        return 1
+    capacidades = descubre_ciudad(datos)
+    print(f"  Skills visible to {cities.direccion(usuario, datos)}")
+    if not capacidades:
+        print("  No repo agents in this city.")
+    for repo, info in capacidades.items():
+        nombres = ", ".join(s["name"] for s in info["skills"]) or "none discovered"
+        estado = info["path"] or "repo not found on this machine"
+        print(f"  {repo} [{info['role']}]: {nombres}\n    {estado}")
+    print("\n  Read-only discovery: Agents City installed and changed nothing.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())