agents-city 0.1.0

package/plugin/scripts/roles.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""The roles offered to an owner seat, across the built-in work domains.
+
+The v2 road address is stable ``owner/city`` and never depends on role. The short
+role suffixes remain only to read and import v1 cards such as ``alice/lead``.
+
+The catalogue is shared by the Hall and seat so they cannot label the same role
+differently. Which subset is relevant is owned by ``domains.py``: a city first
+chooses its work domain, then one role inside it. Role descriptions may still be
+overridden by a city's own role files.
+
+Only picker labels and one-line summaries live here. The operating knowledge and
+trade come from each role's Markdown file, looked up in your city first and the
+plugin's examples second — duplicating those in code is how a managing partner
+once got labelled a master builder.
+"""
+
+import os
+import re
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+
+# (id, what the city calls it, its one line, whether it owns a property of every
+# folder rather than folders of its own).
+CATALOGO = [
+    # Deliberately no role pack. ``blank`` is an explicit choice to start with
+    # no predefined responsibility or operating knowledge; it is offered in
+    # every domain and can also be assigned to an individual repo agent.
+    ("blank", "Blank role", "no predefined responsibility or role knowledge", True),
+    # Software development
+    ("cpto", "Product & technology lead", "direction, priorities and product outcomes", True),
+    ("dev", "Software engineer", "owns repositories and answers for their code", False),
+    (
+        "data-engineer",
+        "Data engineer",
+        "pipelines, transformations, storage contracts and data reliability",
+        False,
+    ),
+    ("devops", "Platform / DevOps lead", "security, reliability, performance, cost and CI", True),
+    ("data", "Data & analytics lead", "events, schemas and comparable measurement", True),
+    ("product-design", "Product designer", "design system, accessibility and user flows", True),
+    ("po", "Product manager", "scope, priority and delivery coherence", True),
+    ("llm-engineer", "AI / LLM engineer", "model calls, prompts, evaluations and token cost", True),
+    ("ai-manager", "AI portfolio lead", "initiative overlap, adoption and portfolio value", True),
+    # Marketing, legal and finance
+    ("brand-lead", "Brand lead", "positioning, priorities and brand coherence", True),
+    ("content", "Content lead", "owns pieces, channels and editorial intent", False),
+    ("performance", "Performance marketing lead", "paid acquisition, spend and conversion", True),
+    ("seo", "SEO lead", "organic structure, indexing, links and durable URLs", True),
+    (
+        "lifecycle",
+        "Lifecycle / CRM lead",
+        "segments, triggers, sequences and contact pressure",
+        True,
+    ),
+    ("managing-partner", "Managing partner", "practice direction, matters and staffing", True),
+    ("associate", "Lawyer / associate", "owns matters and their legal context", False),
+    ("compliance", "Compliance lead", "obligations, deadlines, conflicts and records", True),
+    ("knowledge", "Knowledge lead", "precedents, reusable work and institutional memory", True),
+    ("cfo", "CFO / finance lead", "financial direction, priorities and resource choices", True),
+    ("controller", "Controller", "close, reconciliations, controls and audit trail", True),
+    (
+        "fin-analytics",
+        "Financial analyst",
+        "definitions, comparability, forecasts and scenarios",
+        True,
+    ),
+    ("ops", "Operations specialist", "owns operational processes and their exceptions", False),
+    # Healthcare
+    (
+        "clinical-director",
+        "Clinical director",
+        "clinical direction, accountability and care priorities",
+        True,
+    ),
+    ("clinician", "Clinician", "owns patient or pathway context and clinical judgement", False),
+    (
+        "patient-safety",
+        "Patient safety & quality lead",
+        "harm prevention, incidents and safeguards",
+        True,
+    ),
+    (
+        "clinical-ops",
+        "Clinical operations lead",
+        "capacity, pathways, handoffs and service delivery",
+        True,
+    ),
+    ("health-data", "Clinical data lead", "health measures, provenance and data quality", True),
+    (
+        "health-compliance",
+        "Health privacy & compliance lead",
+        "privacy, consent, access and regulation",
+        True,
+    ),
+    # Revenue
+    ("revenue-lead", "Revenue leader", "commercial direction, forecast and commitments", True),
+    ("account-executive", "Account executive", "owns opportunities and buyer context", False),
+    (
+        "revops",
+        "Revenue operations lead",
+        "pipeline definitions, routing, systems and forecast hygiene",
+        True,
+    ),
+    (
+        "customer-success",
+        "Customer success lead",
+        "adoption, outcomes, renewal and churn risk",
+        True,
+    ),
+    (
+        "enablement",
+        "Sales enablement lead",
+        "playbooks, evidence and reusable field knowledge",
+        True,
+    ),
+    # Research and general operations
+    (
+        "research-director",
+        "Research director",
+        "questions, portfolio direction and research decisions",
+        True,
+    ),
+    ("researcher", "Researcher", "owns studies, sources and interpretation", False),
+    (
+        "methods",
+        "Methods / statistics lead",
+        "study design, validity, uncertainty and analysis",
+        True,
+    ),
+    (
+        "research-ops",
+        "Research operations lead",
+        "participants, tooling, data and study delivery",
+        True,
+    ),
+    ("ethics", "Ethics lead", "consent, proportionality, vulnerable groups and review", True),
+    ("operations-lead", "Operations lead", "operating direction, outcomes and trade-offs", True),
+    ("program-manager", "Programme manager", "dependencies, scope, milestones and delivery", True),
+    ("process-owner", "Process owner", "owns a process, its exceptions and its outcomes", False),
+    (
+        "quality",
+        "Quality & risk lead",
+        "acceptance, failure modes, controls and verification",
+        True,
+    ),
+    ("city-lead", "City lead", "sets direction and chairs decisions in a custom domain", True),
+    ("specialist", "Domain specialist", "owns a body of work and answers from its evidence", False),
+]
+
+# Short, lowercase and stable. A role nobody anticipated still gets a sensible name
+# from `sufijo()` rather than nothing.
+SUFIJOS = {
+    "blank": "blank",
+    "cpto": "lead",
+    "devops": "ops",
+    "data": "data",
+    "product-design": "design",
+    "po": "po",
+    "llm-engineer": "llm",
+    "ai-manager": "ai",
+    "dev": "dev",
+    "data-engineer": "dataeng",
+    "brand-lead": "brand",
+    "content": "content",
+    "performance": "ads",
+    "seo": "seo",
+    "lifecycle": "crm",
+    "managing-partner": "partner",
+    "associate": "assoc",
+    "compliance": "comp",
+    "knowledge": "know",
+    "cfo": "cfo",
+    "controller": "ctrl",
+    "fin-analytics": "fin",
+    "ops": "ops",
+    "clinical-director": "clinical",
+    "clinician": "clinician",
+    "patient-safety": "safety",
+    "clinical-ops": "careops",
+    "health-data": "healthdata",
+    "health-compliance": "privacy",
+    "revenue-lead": "revenue",
+    "account-executive": "account",
+    "revops": "revops",
+    "customer-success": "success",
+    "enablement": "enable",
+    "research-director": "research",
+    "researcher": "researcher",
+    "methods": "methods",
+    "research-ops": "resops",
+    "ethics": "ethics",
+    "operations-lead": "operations",
+    "program-manager": "program",
+    "process-owner": "process",
+    "quality": "quality",
+    "city-lead": "lead",
+    "specialist": "specialist",
+}
+
+# Whoever sets the goals. Not a style rule: goals are the one thing this system keeps
+# whatever kind of city you build, and they are agreed between the architect and each
+# city seat. Without that seat there is nobody to agree them with, and every round
+# degrades into a status report.
+ARQUITECTOS = {
+    "cpto",
+    "brand-lead",
+    "managing-partner",
+    "cfo",
+    "clinical-director",
+    "revenue-lead",
+    "research-director",
+    "operations-lead",
+    "city-lead",
+}
+
+
+def sufijo(rol):
+    """The agent-name suffix for a role."""
+    return SUFIJOS.get(rol, rol.split("-")[0][:8])
+
+
+def agente(usuario, rol, ciudad=""):
+    """A stable owner/city address, or the legacy user/role address.
+
+    Repo agents stay private behind the seat.  Once a city is known, the public
+    endpoint is ``user/city`` so changing its role cannot break every road.
+    """
+    if ciudad:
+        segura = re.sub(r"[^a-z0-9-]+", "-", ciudad.lower()).strip("-") or "city"
+        return f"{usuario}/{segura}"
+    return f"{usuario}/{sufijo(rol)}"
+
+
+def nombre(rol):
+    """What the city calls this role, or a readable version of its id."""
+    for r, n, _, _ in CATALOGO:
+        if r == rol:
+            return n
+    return rol.replace("-", " ").title()
+
+
+def oficio(rol, datos=""):
+    """The trade, read from the role's own file — never from a table in code.
+
+    A hardcoded map labels every unknown role as the same thing, which is exactly
+    what once turned a managing partner into a master builder. Looked up in the data
+    repo first (roles are data, and a team renames them), then in the examples this
+    plugin ships. `../roles/examples` and not a path through the clone, because the
+    installed plugin has no clone — this is the one lookup that works at both doors.
+
+    There were two copies of this: the wizard's skipped the data repo, so a re-run
+    against renamed roles showed the stale trade. One copy, the complete one.
+    """
+    if rol == "blank":
+        return "No preset"
+    bases = [os.path.join(datos, "roles")] if datos else []
+    bases.append(os.path.join(AQUI, "..", "roles", "examples"))
+    for base in bases:
+        f = os.path.join(base, f"{rol}.md")
+        if os.path.exists(f):
+            m = re.search(r"^trade:\s*(.+)$", open(f).read(), re.M)
+            if m:
+                return m.group(1).strip()
+    # No role file: say what the role is called rather than inventing a trade.
+    return rol.replace("-", " ").title()
+
+
+def transversal(rol):
+    """Whether this role owns a property of every folder rather than folders."""
+    for r, _, _, t in CATALOGO:
+        if r == rol:
+            return t
+    return True

package/plugin/scripts/runtime_log.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Append secret-scrubbed operational diagnostics for one local city."""
+import argparse
+import datetime
+import json
+import os
+import re
+import uuid
+
+import runtime_processes
+
+
+def _clean(value, limit=2000):
+    text = str(value or '').strip()
+    text = re.sub(r'([?&](?:token|secret|key)=)[^&\s]+', r'\1[redacted]', text,
+                  flags=re.IGNORECASE)
+    text = re.sub(r'Bearer\s+\S+', 'Bearer [redacted]', text, flags=re.IGNORECASE)
+    text = re.sub(r'(Authorization:\s*)\S+(?:\s+\S+)?', r'\1[redacted]', text,
+                  flags=re.IGNORECASE)
+    text = re.sub(r'(--(?:token|password|secret|api-key)(?:=|\s+))\S+',
+                  r'\1[redacted]', text, flags=re.IGNORECASE)
+    text = re.sub(r'((?:TOKEN|SECRET|PASSWORD|API_KEY)=)[^\s]+',
+                  r'\1[redacted]', text, flags=re.IGNORECASE)
+    return text[:limit]
+
+
+def append(data, component, event, **fields):
+    """Best-effort logging: diagnostics must never stop an agent."""
+    try:
+        directory = runtime_processes.ruta(data)
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+        path = os.path.join(directory, 'diagnostics.jsonl')
+        record = {
+            'protocol': 'agents-city-diagnostic/1',
+            'id': 'diagnostic_' + uuid.uuid4().hex,
+            'at': datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            'pid': os.getpid(),
+            'component': _clean(component, 80),
+            'event': _clean(event, 120),
+        }
+        for key, value in fields.items():
+            if value is None:
+                continue
+            record[key] = ('[redacted]' if re.search(
+                r'token|secret|authorization|credential', key, re.IGNORECASE)
+                else _clean(value))
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, 'a', encoding='utf-8') as stream:
+            stream.write(json.dumps(record, ensure_ascii=False) + '\n')
+    except Exception:
+        pass
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('event')
+    parser.add_argument('--data', default=os.environ.get('AGENTS_CITY_DATA', ''))
+    parser.add_argument('--component', default='launcher')
+    parser.add_argument('--actor', default=os.environ.get('CITY_BUS_ACTOR', ''))
+    parser.add_argument('--outcome', default='')
+    parser.add_argument('--message', default='')
+    args = parser.parse_args()
+    if args.data:
+        append(args.data, args.component, args.event, actor=args.actor,
+               outcome=args.outcome, message=args.message)
+
+
+if __name__ == '__main__':
+    main()

package/plugin/scripts/runtime_processes.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Exact process markers for one city's local bus and runtime gateways."""
+import json
+import os
+import re
+import shlex
+import subprocess
+
+import cities
+
+
+def ruta(datos):
+    ident = cities.identidad(datos)
+    key = re.sub(r'[^a-z0-9-]+', '-', ident.lower()).strip('-')[:80] or 'city'
+    return os.path.join(cities.raiz(), '.runtime', 'bus', key)
+
+
+def procesos(datos):
+    """Return every exact city runtime, including one that lost its marker.
+
+    Marker files are the fast path. A crashed or racing predecessor can lose
+    its endpoint while the process survives, so also inspect argv and accept
+    only a known entrypoint whose literal ``--data`` resolves to this city.
+    """
+    datos = os.path.realpath(datos)
+    base = ruta(datos)
+    candidatos = []
+    try:
+        endpoint = json.load(open(os.path.join(base, 'endpoint.json'), encoding='utf-8'))
+        candidatos.append(('bus hub', int(endpoint.get('pid', 0)), 'local-hub.js'))
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        pass
+    for folder, label, marker in (
+            ('gateways', 'gateway', 'runtime-gateway.js'),
+            ('adapters', 'terminal fallback', 'adapter.js')):
+        directory = os.path.join(base, folder)
+        try:
+            nombres = [n for n in os.listdir(directory) if n.endswith('.pid')]
+        except OSError:
+            nombres = []
+        for nombre in nombres:
+            try:
+                pid = int(open(os.path.join(directory, nombre), encoding='utf-8').read().strip())
+            except (OSError, ValueError):
+                continue
+            candidatos.append((f'{label} {nombre[:-4]}', pid, marker))
+
+    vistos = set()
+    fuera = []
+    for etiqueta, pid, componente in candidatos:
+        if pid <= 0:
+            continue
+        try:
+            comando = subprocess.run(
+                ['ps', '-p', str(pid), '-o', 'command='],
+                capture_output=True, text=True, timeout=3).stdout.strip()
+        except (OSError, subprocess.TimeoutExpired):
+            comando = ''
+        if componente in comando and datos in comando:
+            fuera.append({'label': etiqueta, 'pid': pid})
+            vistos.add(pid)
+    for proceso in _procesos_sin_marca(datos):
+        if proceso['pid'] not in vistos:
+            fuera.append(proceso)
+            vistos.add(proceso['pid'])
+    return fuera
+
+
+def _procesos_sin_marca(datos):
+    """Discover only node entrypoints with an exact ``--data <city>`` argv."""
+    try:
+        salida = subprocess.run(
+            ['ps', '-Ao', 'pid=,command='], capture_output=True, text=True,
+            timeout=5).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    componentes = {
+        'local-hub.js': 'bus hub',
+        'runtime-gateway.js': 'gateway',
+        'adapter.js': 'terminal fallback',
+    }
+    encontrados = []
+    for linea in salida.splitlines():
+        match = re.match(r'\s*(\d+)\s+(.*)', linea)
+        if not match:
+            continue
+        pid, comando = int(match.group(1)), match.group(2)
+        if pid in (os.getpid(), os.getppid()):
+            continue
+        try:
+            argv = shlex.split(comando)
+        except ValueError:
+            continue
+        indice = next(
+            (i for i, value in enumerate(argv[:3])
+             if os.path.basename(value) in componentes), None)
+        if indice is None:
+            continue
+        try:
+            data_index = argv.index('--data', indice + 1)
+            data = os.path.realpath(argv[data_index + 1])
+        except (ValueError, IndexError):
+            continue
+        if data != datos:
+            continue
+        componente = os.path.basename(argv[indice])
+        etiqueta = componentes[componente]
+        if componente in ('runtime-gateway.js', 'adapter.js'):
+            try:
+                actor = argv[argv.index('--actor', indice + 1) + 1]
+                etiqueta = f'{etiqueta} {actor}'
+            except (ValueError, IndexError):
+                pass
+        encontrados.append({'label': etiqueta, 'pid': pid})
+    return encontrados
+
+
+def limpia_marcas(datos):
+    base = ruta(datos)
+    rutas = [os.path.join(base, 'endpoint.json'), os.path.join(base, 'hub.lock')]
+    for folder in ('gateways', 'adapters'):
+        directory = os.path.join(base, folder)
+        try:
+            rutas += [os.path.join(directory, n) for n in os.listdir(directory)
+                      if n.endswith('.pid')]
+        except OSError:
+            pass
+    for path in rutas:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass

package/plugin/scripts/rutas.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Path containment, resolved twice, in one place.
+
+Every part of the security layer that trusts a path — the cage deciding what to
+re-allow for writing, the broker deciding which repo a token may act on — needs
+the same three questions answered the same way:
+
+1. Where does this path *really* point, even if its leaf does not exist yet?
+   A non-existent leaf under a symlinked parent still redirects, so we resolve
+   through the deepest ancestor that does exist.
+2. Is it inside a forbidden root?
+3. Does it *cover* a forbidden root (an ancestor of it)? Re-allowing `~` would
+   silently re-open `~/.ssh`; that is the bug this module exists to refuse.
+
+Kept dependency-free and pure so both the cage and the broker import it, and so
+the tests can drive it on any platform without a sandbox.
+"""
+
+import os
+
+
+def canonicaliza(ruta):
+    """Absolute real path, resolved through the deepest ancestor that exists.
+
+    `os.path.realpath` already does this on most inputs, but it stops resolving
+    once it meets a missing component; we walk up to the first existing ancestor,
+    resolve *that*, then re-attach the missing tail. A symlinked parent with a
+    not-yet-created child therefore still lands on the real target.
+    """
+    ruta = os.path.abspath(os.path.expanduser(ruta))
+    cola = []
+    actual = ruta
+    while not os.path.exists(actual):
+        padre = os.path.dirname(actual)
+        if padre == actual:
+            break
+        cola.append(os.path.basename(actual))
+        actual = padre
+    base = os.path.realpath(actual)
+    for segmento in reversed(cola):
+        base = os.path.join(base, segmento)
+    return base
+
+
+def _segmentos(ruta):
+    return [s for s in canonicaliza(ruta).split(os.sep) if s]
+
+
+def _dentro_seg(h, p):
+    return len(h) >= len(p) and h[: len(p)] == p
+
+
+def _cubre_seg(a, d):
+    return len(a) < len(d) and d[: len(a)] == a
+
+
+def dentro_de(hijo, padre):
+    """True when `hijo` is `padre` or lives under it — compared segment-wise so
+    `/a/bc` is never judged to be inside `/a/b`."""
+    return _dentro_seg(_segmentos(hijo), _segmentos(padre))
+
+
+def cubre(ancestro, descendiente):
+    """True when `ancestro` is a strict parent of `descendiente` (covers it)."""
+    return _cubre_seg(_segmentos(ancestro), _segmentos(descendiente))
+
+
+def motivo_bloqueo(ruta, bloqueados):
+    """Why `ruta` may not be trusted against a set of forbidden roots, or None.
+
+    Bidirectional on purpose: a path is refused both when it sits inside a
+    forbidden root and when it is an ancestor that would re-open one. `ruta` is
+    canonicalized once here and compared segment-wise against every root.
+    """
+    r_can = canonicaliza(ruta)
+    r_seg = [s for s in r_can.split(os.sep) if s]
+    for raiz in bloqueados:
+        raiz_seg = _segmentos(raiz)
+        if _dentro_seg(r_seg, raiz_seg):
+            return f'{r_can} is inside sealed {canonicaliza(raiz)}'
+        if _cubre_seg(r_seg, raiz_seg):
+            return f'{r_can} covers sealed {canonicaliza(raiz)}'
+    return None