agents-city 0.3.0-beta.21

package/bin/test-stress.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""A 40-agent Claude/Codex city survives fan-out and hub replacement."""
+import json
+import os
+import subprocess
+import sys
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+RAIZ = os.path.dirname(AQUI)
+sys.path.insert(0, AQUI)
+from testlib import afirma, comprueba, resumen  # noqa: E402
+
+
+def main():
+    print('\n  40-agent mixed Claude/Codex stress')
+    result = subprocess.run(
+        [sys.executable, os.path.join(RAIZ, 'benchmarks', 'stress', 'run.py'),
+         '--agents', '40', '--rounds', '2', '--json'],
+        capture_output=True, text=True, timeout=90)
+    try:
+        report = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        report = {}
+    afirma('· the offline 40-agent stress run passes',
+           result.returncode == 0 and report.get('status') == 'pass',
+           result.stderr.strip() or result.stdout[-1000:])
+    comprueba('· the city mixes 20 Claude and 20 Codex actors',
+              report.get('mix'),
+              {'claude-stream-json': 20, 'codex-app-server-ws': 20})
+    comprueba('· both rounds reach all 40 native runtimes',
+              [row.get('accepted') for row in report.get('rounds', [])], [40, 40])
+    comprueba('· each round keeps exactly one shared WebSocket hub',
+              [row.get('hubProcesses') for row in report.get('rounds', [])], [1, 1])
+    afirma('· local native acceptance stays inside the stress budget',
+           len(report.get('rounds', [])) == 2
+           and all(row.get('p95NativeAcceptMs', 99999) < 5_000
+                   and row.get('maxNativeAcceptMs', 99999) < 10_000
+                   for row in report['rounds']),
+           str(report.get('rounds')))
+    comprueba('· 80 acceptances are split across the native transports',
+              report.get('transportAcceptances'),
+              {'claude-stream-json': 40, 'codex-app-server-ws': 40})
+    afirma('· the browser WebSocket represents all 40 actors and survives hub replacement',
+           report.get('liveFeed', {}).get('transport')
+           == 'authenticated-read-only-websocket'
+           and report.get('liveFeed', {}).get('participantsPerRound') == [40, 40]
+           and report.get('liveFeed', {}).get('openEvents') == 2
+           and report.get('liveFeed', {}).get('survivedHubRestart') is True,
+           str(report.get('liveFeed')))
+    comprueba('· the live browser feed duplicates no committee event',
+              report.get('liveFeed', {}).get('duplicates'), 0)
+    comprueba('· stress recovery produces no duplicate delivery',
+              report.get('duplicateDeliveries'), 0)
+    afirma('· stress never uses terminal injection or leaves queued work',
+           report.get('terminalInjection') is False
+           and report.get('remainingOutboxes') == 0)
+    comprueba('· stress cleanup leaves no runtime or hub process',
+              report.get('cleanup'),
+              {'remainingHubProcesses': [], 'remainingRuntimeProcesses': 0})
+    return resumen('stress')
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/bin/test-widgets.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Run the terminal widgets through a fake window, and check what they return.
+
+Why this exists, precisely: the scripted harness in ui.py sets `TTY = False`, so
+every widget answers from AGENTS_CITY_ANSWERS and returns *before* entering its
+curses loop. That covers the wizard's logic and leaves the four widgets never
+executed — and one of them shipped broken for exactly that reason. `elige` did
+`marcadas |= {...}` inside its nested `run()`, which made `marcadas` local to it,
+so the very first frame died on `UnboundLocalError` and the roles screen was
+unreachable in any real terminal.
+
+So: no pty, no terminal, no hands. Replace `curses.wrapper` with something that
+calls `run()` against a window that renders nothing and returns a scripted list
+of keystrokes. Every branch of the key handling runs for real.
+
+    ./bin/test-widgets.py
+"""
+import curses
+import os
+import sys
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(os.path.dirname(AQUI), 'plugin', 'scripts'))
+import ui  # noqa: E402
+
+FALLOS = []
+TECLAS = []
+COMPROBADAS = 0
+
+
+class Ventana:
+    """Wide enough that nothing wraps, and every drawing call is a no-op. What we
+    are testing is what the widget decides, not what it paints."""
+    def getmaxyx(self):
+        return (40, 110)
+
+    def getch(self):
+        if not TECLAS:
+            raise AssertionError('the widget asked for a key after the script ran out '
+                                 '— it is not returning when it should')
+        return TECLAS.pop(0)
+
+    def __getattr__(self, _):
+        return lambda *a, **k: None
+
+
+def preparado():
+    """curses, stubbed down to the parts the widgets touch."""
+    ui.TTY = True
+    curses.wrapper = lambda fn, *a, **k: fn(Ventana(), *a, **k)
+    curses.curs_set = lambda *_: None
+    curses.color_pair = lambda _: 0
+    ui._pairs = lambda: None
+
+
+def comprueba(nombre, teclas, llama, espera):
+    global TECLAS, COMPROBADAS
+    TECLAS = list(teclas)
+    COMPROBADAS += 1
+    try:
+        salida = llama()
+    except Exception as e:                                    # noqa: BLE001
+        FALLOS.append(f'{nombre}: raised {type(e).__name__}: {e}')
+        return
+    if salida != espera:
+        FALLOS.append(f'{nombre}: got {salida!r}, expected {espera!r}')
+        return
+    if TECLAS:
+        FALLOS.append(f'{nombre}: returned with {len(TECLAS)} keystrokes unread')
+
+
+ESPACIO, ENTRA, ESC = ord(' '), 13, 27
+ABAJO, ARRIBA = curses.KEY_DOWN, curses.KEY_UP
+OPS = [('a', 'Alpha', 'first'), ('b', 'Beta', 'second'), ('c', 'Gamma', 'third')]
+
+
+def main():
+    preparado()
+
+    # ── elige: the multi-select, and the one that was broken ────────────────
+    comprueba('elige · enter with the preselection',
+              [ENTRA], lambda: ui.elige('R', OPS, marcadas=['a']), ['a'])
+    comprueba('elige · a takes all',                         # was UnboundLocalError
+              [ord('a'), ENTRA], lambda: ui.elige('R', OPS), ['a', 'b', 'c'])
+    comprueba('elige · n drops all',                         # was UnboundLocalError
+              [ord('a'), ord('n'), ENTRA], lambda: ui.elige('R', OPS), [])
+    comprueba('elige · space toggles on',
+              [ESPACIO, ENTRA], lambda: ui.elige('R', OPS), ['a'])
+    comprueba('elige · space toggles off again',
+              [ESPACIO, ENTRA], lambda: ui.elige('R', OPS, marcadas=['a']), [])
+    comprueba('elige · moves down before picking',
+              [ABAJO, ESPACIO, ENTRA], lambda: ui.elige('R', OPS), ['b'])
+    comprueba('elige · will not stop below the minimum',
+              [ENTRA, ESPACIO, ENTRA], lambda: ui.elige('R', OPS, minimo=1), ['a'])
+    comprueba('elige · quitting returns nothing',
+              [ESC], lambda: ui.elige('R', OPS), None)
+    comprueba('elige · filter narrows what a and space reach',
+              [ord('/'), ord('B'), ENTRA, ord('a'), ENTRA],
+              lambda: ui.elige('R', OPS), ['b'])
+    comprueba('elige · n only drops what the filter shows',
+              [ord('a'), ord('/'), ord('B'), ENTRA, ord('n'), ENTRA],
+              lambda: ui.elige('R', OPS), ['a', 'c'])
+    comprueba('elige · an empty list still returns',
+              [ENTRA], lambda: ui.elige('R', []), [])
+
+    # ── una: the single choice ─────────────────────────────────────────────
+    comprueba('una · enter takes the first',
+              [ENTRA], lambda: ui.una('K', OPS), 'a')
+    comprueba('una · down then enter',
+              [ABAJO, ENTRA], lambda: ui.una('K', OPS), 'b')
+    comprueba('una · up from the top wraps to the bottom',
+              [ARRIBA, ENTRA], lambda: ui.una('K', OPS), 'c')
+    comprueba('una · down past the bottom wraps to the top',
+              [ABAJO, ABAJO, ABAJO, ENTRA], lambda: ui.una('K', OPS), 'a')
+    comprueba('una · an empty list returns nothing instead of dividing by zero',
+              [], lambda: ui.una('K', []), None)
+    comprueba('una · quitting returns nothing',
+              [ESC], lambda: ui.una('K', OPS), None)
+
+    # ── pantalla: the page of text ─────────────────────────────────────────
+    comprueba('pantalla · enter continues',
+              [ENTRA], lambda: ui.pantalla('T', 'body\n\nsecond paragraph'), True)
+    comprueba('pantalla · q stops',
+              [ord('q')], lambda: ui.pantalla('T', 'body'), False)
+
+    # `pide` reads with input(), not curses, so it has nothing to stub. Its wrapping
+    # helper is pure and worth one check: paragraphs survive as blank lines.
+    lineas = ui.texto('one two\n\nthree four', 40)
+    if '' not in lineas:
+        FALLOS.append('texto: paragraph break was lost')
+
+    if FALLOS:
+        print(f'\n  {len(FALLOS)} widget failure(s)\n')
+        for f in FALLOS:
+            print(f'    ✗ {f}')
+        print()
+        return 1
+    print(f'\n  widgets ok — {COMPROBADAS} checks across elige, una, pantalla and texto\n')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/bin/test-workspace.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Agent-first workspaces: legacy repos still work, new agents mount folders.
+
+Under a throwaway data dir. The load-bearing cases: a bare `repos:` card
+normalises to one agent per repo (unchanged behaviour), a new `agents:` card
+drives workspaces with mounts, mounts are validated symlinks that resolve to
+their real target for the cage, and re-mounting a name repoints atomically.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+RAIZ = os.path.dirname(AQUI)
+sys.path.insert(0, os.path.join(RAIZ, "plugin", "scripts"))
+sys.path.insert(0, AQUI)
+
+import workspace as ws  # noqa: E402
+from testlib import afirma, comprueba, resumen  # noqa: E402
+
+LEGACY = """---
+user: ada
+agent: ada/seat
+repos: [nova, store-service]
+role.nova: po
+role.store-service: security
+runs.store-service: codex
+---
+"""
+
+NUEVO = """---
+user: ada
+agent: ada/seat
+agents: [writer, chair]
+kind.writer: knowledge
+role.writer: blank
+mounts.writer: [~/docs/handbook]
+kind.chair: coordinator
+runs.chair: claude
+---
+"""
+
+
+def legacy_subsume():
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        ags = ws.agentes(LEGACY, base)
+        comprueba("a bare repos card yields one agent per repo", len(ags), 2)
+        a = {x.slug: x for x in ags}
+        afirma("each legacy agent is marked legacy", all(x.legacy for x in ags))
+        comprueba("its kind defaults to code", a["nova"].clase, "code")
+        comprueba("its role carries over", a["nova"].rol, "po")
+        comprueba("its runtime carries over", a["store-service"].runtime, "codex")
+        comprueba("a legacy agent's single mount is its repo name",
+                  a["nova"].mounts, ["nova"])
+        # With a legacy resolver, the workspace becomes the resolved repo path.
+        ags2 = ws.agentes(LEGACY, base, resolver_legacy=lambda r: f"/repos/{r}")
+        comprueba("the resolver sets the workspace to the repo path",
+                  {x.slug: x.workspace for x in ags2}["nova"], "/repos/nova")
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def nuevo_modelo():
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        ags = {x.slug: x for x in ws.agentes(NUEVO, base)}
+        comprueba("an agents card yields the declared agents", len(ags), 2)
+        afirma("new agents are not legacy", not any(x.legacy for x in ags.values()))
+        comprueba("a knowledge agent keeps its kind", ags["writer"].clase, "knowledge")
+        comprueba("a coordinator keeps its kind", ags["chair"].clase, "coordinator")
+        comprueba("its workspace is under the city's agents dir",
+                  ags["writer"].workspace, ws.workspace_de(base, "writer"))
+        comprueba("declared mounts are read from the card",
+                  ags["writer"].mounts, ["~/docs/handbook"])
+        afirma("como_dict is JSON-shaped",
+               set(ags["writer"].como_dict()) >= {"name", "kind", "workspace", "mounts"})
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def montajes():
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        real = os.path.join(base, "real-docs")
+        os.makedirs(real)
+        with open(os.path.join(real, "note.md"), "w") as f:
+            f.write("x")
+        enlace = ws.monta(base, "writer", real)
+        afirma("mounting creates a symlink in the workspace", os.path.islink(enlace))
+        comprueba("the workspace mounts dir now lists it",
+                  [e for e, _ in ws.mounts_en_disco(base, "writer")],
+                  ["real-docs"])
+        comprueba("the mount resolves to its real target",
+                  ws.mounts_en_disco(base, "writer")[0][1], os.path.realpath(real))
+
+        # mount_targets follows the symlink to the real path — what the cage seals.
+        agente = ws.agentes(NUEVO, base)[0]  # 'writer'
+        targets = ws.mount_targets(agente, base)
+        afirma("mount_targets returns the resolved real path, not the link",
+               os.path.realpath(real) in targets)
+
+        # Re-mounting the same name repoints atomically, does not error.
+        otro = os.path.join(base, "other-docs")
+        os.makedirs(otro)
+        ws.monta(base, "writer", otro, nombre="real-docs")
+        comprueba("re-mounting a name repoints it",
+                  ws.mounts_en_disco(base, "writer")[0][1], os.path.realpath(otro))
+
+        afirma("mounting a nonexistent path is refused",
+               _rechaza(lambda: ws.monta(base, "writer", os.path.join(base, "ghost"))))
+        afirma("unmount removes the link", ws.desmonta(base, "writer", "real-docs"))
+        afirma("unmount of nothing returns False", not ws.desmonta(base, "writer", "nope"))
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def colisiones_de_basename():
+    # Two sources sharing a basename must NOT collapse into one mount.
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        a = os.path.join(base, "work", "api")
+        b = os.path.join(base, "other", "api")
+        os.makedirs(a)
+        os.makedirs(b)
+        ws.monta(base, "dev", a)
+        ws.monta(base, "dev", b)
+        destinos = sorted(t for _, t in ws.mounts_en_disco(base, "dev"))
+        comprueba("both same-basename mounts survive (no silent overwrite)",
+                  len(destinos), 2)
+        afirma("both real targets are present",
+               os.path.realpath(a) in destinos and os.path.realpath(b) in destinos)
+        # An uppercase/underscore name is slugged the same way at mount and unmount.
+        docs = os.path.join(base, "My_Docs")
+        os.makedirs(docs)
+        ws.monta(base, "dev", docs, nombre="My_Docs")
+        afirma("a mount is removable by the name it was created with",
+               ws.desmonta(base, "dev", "My_Docs"))
+        # A colon in the resolved path is refused (it would break the pipeline).
+        raro = os.path.join(base, "a:b")
+        os.makedirs(raro)
+        afirma("a colon-containing path is refused", _rechaza(lambda: ws.monta(base, "dev", raro)))
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def slugs_colisionados_rechazados():
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        chocan = "---\nuser: x\nagents: [store-service, store_service]\n---\n"
+        afirma("two agents that slug to one identity are refused",
+               _rechaza(lambda: ws.agentes(chocan, base)))
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def sync_solo_materializados():
+    base = tempfile.mkdtemp(prefix="agents-city-ws-")
+    try:
+        real = os.path.join(base, "real")
+        os.makedirs(real)
+        card_txt = ("---\nuser: x\nagents: [w]\nkind.w: knowledge\n"
+                    f"mounts.w: [{real}, {os.path.join(base, 'ghost')}]\n---\n")
+        agente = ws.agentes(card_txt, base)[0]
+        targets = ws.sincroniza(agente, base)
+        comprueba("sync returns only what materialised, not the missing source",
+                  targets, [os.path.realpath(real)])
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def _rechaza(fn):
+    try:
+        fn()
+        return False
+    except (OSError, ValueError):
+        return True
+
+
+legacy_subsume()
+nuevo_modelo()
+montajes()
+colisiones_de_basename()
+slugs_colisionados_rechazados()
+sync_solo_materializados()
+sys.exit(resumen("workspace"))

package/bin/testlib.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""The two assertions and the summary every suite here uses.
+
+Four suites carried an identical copy of `comprueba`, `afirma`, the two counters and
+the closing summary. The suites exist to hunt down copies that drift; their own
+helpers should not be the next example.
+
+Each suite runs as its own process, so module state is per-suite by construction.
+"""
+import os
+import signal
+import subprocess
+import time
+
+FALLOS, HECHAS = [], 0
+
+
+def comprueba(nombre, real, esperado):
+    """Equality, with both sides printed when it is not."""
+    global HECHAS
+    HECHAS += 1
+    if real != esperado:
+        FALLOS.append(f'{nombre}\n        got      {real!r}\n        expected {esperado!r}')
+
+
+def afirma(nombre, condicion, detalle=''):
+    """A plain condition, with whatever context the caller thought to keep."""
+    global HECHAS
+    HECHAS += 1
+    if not condicion:
+        FALLOS.append(f'{nombre}{chr(10) + "        " + detalle if detalle else ""}')
+
+
+def detiene_proceso(pid, segundos=2):
+    """Stop one exact test-owned PID and prove it did not become an orphan."""
+    if not pid:
+        return True
+    try:
+        os.kill(int(pid), signal.SIGTERM)
+    except ProcessLookupError:
+        return True
+    limite = time.monotonic() + segundos
+    while time.monotonic() < limite:
+        try:
+            os.kill(int(pid), 0)
+        except ProcessLookupError:
+            return True
+        time.sleep(.05)
+    try:
+        os.kill(int(pid), signal.SIGKILL)
+    except ProcessLookupError:
+        return True
+    time.sleep(.1)
+    try:
+        os.kill(int(pid), 0)
+        return False
+    except ProcessLookupError:
+        return True
+
+
+def hubs_de_ciudad(datos):
+    """Return only local-hub PIDs whose exact --data argument is test-owned."""
+    target = os.path.realpath(datos)
+    result = subprocess.run(
+        ['ps', '-axo', 'pid=,command='], capture_output=True, text=True)
+    pids = []
+    marker = 'local-hub.js --data '
+    for line in result.stdout.splitlines():
+        if marker not in line:
+            continue
+        raw_pid, command = line.strip().split(None, 1)
+        supplied = command.split(marker, 1)[1].strip()
+        if os.path.realpath(supplied) == target:
+            pids.append(int(raw_pid))
+    return sorted(set(pids))
+
+
+def detiene_hubs_de_ciudad(datos):
+    """Stop every exact test-owned hub, including a hidden startup-race loser."""
+    return all(detiene_proceso(pid) for pid in hubs_de_ciudad(datos)) \
+        and not hubs_de_ciudad(datos)
+
+
+def resumen(etiqueta):
+    """Print the verdict and return the exit code. `N checks` is the exact phrase
+    bin/test greps for, so it lives in one place."""
+    print()
+    if FALLOS:
+        print(f'  {len(FALLOS)} of {HECHAS} failed\n')
+        for f in FALLOS:
+            print(f'    ✗ {f}')
+        print()
+        return 1
+    print(f'  {etiqueta} ok — {HECHAS} checks\n')
+    return 0

package/bin/tokens.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Report this machine's token spend to the city.
+
+A one-line wrapper. The reporter itself ships inside the plugin, because that is
+what gets installed on everybody's machine — keeping a second copy here would
+mean two implementations of the same arithmetic, and one of them would rot.
+
+    ./bin/tokens.py --url https://your-city.workers.dev --push
+"""
+import os
+import sys
+os.execv(sys.executable, [sys.executable,
+         os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                      '..', 'plugin', 'scripts', 'tokens.py'), *sys.argv[1:]])

package/bus/scripts/deploy.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Deploy the hub. Creates the token KV the first time and writes its id into
+# wrangler.toml.
+#
+#   ./scripts/deploy.sh
+#
+# You have to be logged into the right Cloudflare account:
+#   npx --yes wrangler@4 login      (interactive, opens the browser)
+# o exportar CLOUDFLARE_API_TOKEN con un token que tenga
+#   Workers Scripts:Edit · Workers KV Storage:Edit · Account Settings:Read
+
+set -euo pipefail
+
+cd "$(dirname "$0")/../worker"
+
+# A malformed CF_API_TOKEN in the environment wins over everything else in
+# wrangler, including a perfectly good OAuth session — so it is taken out of the
+# way for this one invocation.
+unset CF_API_TOKEN
+
+# The runner: bun if it is here, npx otherwise — npx ships with npm, so it is
+# the one almost everybody already has.
+if command -v bunx >/dev/null 2>&1; then CORRE=(bunx)
+elif command -v bun >/dev/null 2>&1; then CORRE=(bun x)
+else CORRE=(npx --yes); fi
+W() { "${CORRE[@]}" wrangler@4 "$@"; }
+
+echo "→ account:"
+W whoami 2>&1 | grep -E "logged in|Account Name|│" | head -5 || true
+echo
+
+if grep -qE 'id = "(PENDIENTE_DE_CREAR|<YOUR_KV_NAMESPACE_ID>)"' wrangler.toml; then
+  echo "→ creating the token KV..."
+  OUT="$(W kv namespace create TOKENS 2>&1)"
+  echo "$OUT" | tail -5
+  ID="$(printf '%s' "$OUT" | grep -oE '"?id"?[ =:]+"?[a-f0-9]{32}' | grep -oE '[a-f0-9]{32}' | head -1)"
+  if [ -z "$ID" ]; then
+    echo "I could not find the KV id in wrangler's output." >&2
+    echo "Put it into worker/wrangler.toml by hand and run this again." >&2
+    exit 1
+  fi
+  sed -i.bak -E "s/id = \"(PENDIENTE_DE_CREAR|<YOUR_KV_NAMESPACE_ID>)\"/id = \"$ID\"/" wrangler.toml && rm -f wrangler.toml.bak
+  echo "  KV created: $ID"
+  echo
+fi
+
+echo "→ deploying..."
+W deploy
+
+cat <<'EOF'
+
+Done. Now one token per owner prefix (it can serve several cities):
+
+  ./scripts/mint-token.sh <user>
+
+And check the hub answers:
+
+  curl https://city-bus.<your-subdomain>.workers.dev/health
+
+EOF

package/bus/scripts/mint-token.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Mint a token for one city owner prefix and register it in KV.
+#
+#   ./scripts/mint-token.sh alice
+#   ./scripts/mint-token.sh alice --local        (against wrangler dev)
+#   ./scripts/mint-token.sh alice --to bob,carol (may only write to those)
+#
+# It prints the token ONCE: KV keeps only its SHA-256, so a lost token is a
+# reissued token. Hand it over privately — never through the repo.
+
+set -euo pipefail
+
+USER_NAME="${1:-}"
+[ -z "$USER_NAME" ] && { echo "usage: $0 <user> [--local] [--to a,b]" >&2; exit 1; }
+shift
+
+if ! [[ "$USER_NAME" =~ ^[a-z0-9][a-z0-9_-]{0,31}$ ]]; then
+  echo "invalid user: lowercase, digits, dashes; no slashes" >&2; exit 1
+fi
+
+REMOTE="--remote"
+CAN_SEND_TO=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --local) REMOTE="--local"; shift ;;
+    --to)    CAN_SEND_TO="${2:-}"; shift 2 ;;
+    *) echo "unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+# The runner: npx ships with npm, so it is the one almost everybody has.
+if command -v bunx >/dev/null 2>&1; then CORRE=(bunx)
+elif command -v bun >/dev/null 2>&1; then CORRE=(bun x)
+elif command -v npx >/dev/null 2>&1; then CORRE=(npx --yes)
+else echo "I need npx (comes with Node) or bun." >&2; exit 1; fi
+
+cd "$(dirname "$0")/../worker"
+
+TOKEN="rb_$(openssl rand -hex 24)"
+HASH="$(printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1)"
+
+if [ -n "$CAN_SEND_TO" ]; then
+  LIST="$(printf '%s' "$CAN_SEND_TO" | awk -F, '{for(i=1;i<=NF;i++) printf "%s\"%s\"", (i>1?",":""), $i}')"
+  VALUE="{\"user\":\"$USER_NAME\",\"can_send_to\":[$LIST]}"
+else
+  VALUE="{\"user\":\"$USER_NAME\"}"
+fi
+
+"${CORRE[@]}" wrangler@4 kv key put $REMOTE --binding TOKENS "tok:$HASH" "$VALUE" >/dev/null
+
+cat <<EOF
+
+Token for "$USER_NAME" (shown this once only):
+
+  $TOKEN
+
+They should keep it in the plugin's sensitive configuration or in
+~/.claude/channels/city-bus/.env :
+
+  CITY_BUS_URL=https://city-bus.<your-subdomain>.workers.dev
+  CITY_BUS_TOKEN=$TOKEN
+
+Each seat derives its own $USER_NAME/<city> address at runtime.
+
+To revoke it:
+  npx --yes wrangler@4 kv key delete $REMOTE --binding TOKENS "tok:$HASH"
+
+EOF