agents-city 0.3.0-beta.21

package/bin/city

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Bring YOUR city up, from your data repo. Same idea as bin/demo.
+#
+#   ./bin/city                       uses the selected city
+#   ./bin/city ~/.agents-city/me/x   uses that one
+set -euo pipefail
+cd "$(dirname "$0")/.."
+RAIZ="$PWD"
+
+# A free port, starting at 8787.
+#
+# Not a nicety: the first run of this on somebody else's machine died because
+# something else already held 8787, and the error wrangler prints for that is a
+# wall of C++ stack trace. A demo that refuses to start on its first attempt is a
+# demo nobody runs twice.
+puerto_libre() {
+  local p=${1:-8787}
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    if ! lsof -ti:"$p" >/dev/null 2>&1; then echo "$p"; return; fi
+    p=$((p + 1))
+  done
+  echo "$p"
+}
+PUERTO="$(puerto_libre 8787)"
+
+if [ $# -gt 0 ]; then
+  DATOS="$1"
+elif [ -n "${AGENTS_CITY_DATA:-}" ]; then
+  DATOS="$AGENTS_CITY_DATA"
+else
+  DATOS="$(python3 "$RAIZ/plugin/scripts/cities.py" current)"
+fi
+
+if [ ! -d "$DATOS" ]; then
+  echo "  No data repo at $DATOS"
+  echo "  Run ./bin/setup.py first — it writes one — or pass the path: ./bin/city ~/my-data"
+  exit 1
+fi
+
+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."; exit 1; fi
+
+printf '\n  \033[1mBuilding the map\033[0m\n'
+# Skip the build when a built front end shipped with the package (an npm install
+# has dist/ ready-made) or when the package dir is not ours to write.
+if [ ! -f city/web/dist/index.html ] || { [ -w city/web ] && [ city/web/src/main.ts -nt city/web/dist/city.js ]; }; then
+  if [ -w city/web ]; then
+    (cd city/web && npm install --silent && npm run build >/dev/null)
+  else
+    echo "  The front end is not built and this install is not writable."
+    echo "  Reinstall without sudo (nvm makes this the default), or run from a clone."
+    exit 1
+  fi
+fi
+
+printf '\n  \033[1mLoading %s\033[0m\n' "$DATOS"
+cd "$RAIZ/city/worker"
+# Demo and your city keep their state apart, and that is not tidiness.
+# Sharing one .wrangler/state means the Durable Object holding "who is connected"
+# survives from one to the other: run the demo once, open your own city, and three
+# of Aurora Games' agents are sitting on your bus with timestamps from hours ago.
+# D1 gets reseeded so the houses were right; the live state is what leaked.
+# Local D1/DO state lives in the home directory, never inside the package:
+# an npm -g install is shared and possibly read-only, and state is yours.
+# One local database per city, keyed by cities.py's slug: two cities — even two
+# folders that share a basename — must never overwrite each other's map.
+CIUDAD_ID="$(python3 "$RAIZ/plugin/scripts/cities.py" slug "$DATOS" 2>/dev/null)"
+ESTADO="${AGENTS_CITY_HOME:-$HOME/.agents-city}/state/${CIUDAD_ID:-mine}"
+VARS=(--var "CITY_ID:$(python3 "$RAIZ/plugin/scripts/cities.py" id "$DATOS" 2>/dev/null)")
+# The secret travels as a flag, not as a file written into the package: a global
+# npm install may be read-only, and a local one should not be dirtied either.
+[ -f .dev.vars ] || VARS+=(--var "CITY_SECRET:local-test")
+mkdir -p "$ESTADO"
+"${CORRE[@]}" wrangler@4 d1 execute city --local --persist-to "$ESTADO" --file schema.sql >/dev/null
+cd "$RAIZ"
+CITY_PERSIST="$ESTADO" ./city/scripts/seed.py --data "$DATOS" --local
+
+printf '\n  \033[1mYour city is at\033[0m http://127.0.0.1:%s\n' "$PUERTO"
+echo "  Houses have no floors yet: growth comes from your repos or from ./bin/report.py"
+echo "  ctrl-c to stop"
+[ "$PUERTO" = 8787 ] || echo "  (8787 was busy, so this one is on $PUERTO)"
+cd "$RAIZ/city/worker"
+exec "${CORRE[@]}" wrangler@4 dev --local --persist-to "$ESTADO" \
+  "${VARS[@]}" --port "$PUERTO"

package/bin/committee

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Vendor-neutral chair/member protocol over the city's local WebSocket bus.
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+. "$ROOT/plugin/scripts/city-env.sh"
+exec node "$ROOT/plugin/channel/client.js" committee "$@"

package/bin/demo

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# Aurora Games: one disposable personal city, the real Hall, the real local
+# WebSocket bus and a guided chair-mediated committee. No provider account,
+# repository or permanent Agents City data is required.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+RAIZ="$PWD"
+
+ABRIR=1
+DOMINIO=software
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-browser) ABRIR=0 ;;
+    --domain)
+      shift
+      DOMINIO="${1:-}"
+      ;;
+    -h|--help)
+      cat <<'EOF'
+usage: agents-city demo [--domain software|medicina|legal] [--no-browser]
+
+Opens one disposable demo city in the full Town Hall. The centre is the map;
+the right sidebar receives a guided committee over the real local WebSocket
+bus, and the same events become short game-style speech bubbles over each
+agent. The stories are real chaos told in plain words, one per domain:
+
+  software  Aurora Games — la noche en que desaparecieron las partidas
+  medicina  Clínica Alba — la mañana de las citas duplicadas
+  legal     Costa & Ley — el plazo de mañana a las nueve
+
+No Claude/Codex account is used and your own cities are not selected or changed.
+EOF
+      exit 0
+      ;;
+    *) echo "  Unknown demo option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+# One fixture per domain: the story's cast are the city's agents, so a clinic
+# argues about patients and a firm about deadlines — never a repo about either.
+case "$DOMINIO" in
+  software) FIXTURE=city ;;
+  medicina) FIXTURE=clinica ;;
+  legal) FIXTURE=despacho ;;
+  *) echo "  Unknown demo domain: $DOMINIO (software, medicina or legal)" >&2; exit 2 ;;
+esac
+
+[ -f city/worker/schema.sql ] && [ -f "demo/$FIXTURE/city.yml" ] || {
+  echo "  This install is incomplete: the $DOMINIO demo city or map schema is missing." >&2
+  exit 1
+}
+
+lee_ciudad() { sed -n "s/^$1:[[:space:]]*//p" "demo/$FIXTURE/city.yml" | head -1; }
+DEMO_OWNER="$(lee_ciudad owner)"
+DEMO_SLUG="$(lee_ciudad slug)"
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "  I need $1. $2" >&2
+    exit 1
+  }
+}
+need npm "Install Node from nodejs.org."
+need node "Install Node from nodejs.org."
+need python3 "It ships with macOS; on Linux install python3."
+need curl "Install curl and try again."
+
+if command -v bunx >/dev/null 2>&1; then
+  RUNNER=(bunx)
+elif command -v bun >/dev/null 2>&1; then
+  RUNNER=(bun x)
+elif command -v npx >/dev/null 2>&1; then
+  RUNNER=(npx --yes)
+else
+  echo "  I need npx (comes with Node) or bun." >&2
+  exit 1
+fi
+
+free_port() {
+  local port=8787
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    if ! lsof -ti:"$port" >/dev/null 2>&1; then
+      echo "$port"
+      return
+    fi
+    port=$((port + 1))
+  done
+  echo "  No free map port from 8787 to 8796." >&2
+  return 1
+}
+
+step() { printf '\n  \033[1m%s\033[0m\n' "$1"; }
+
+DEMO_PREFIX="${TMPDIR:-/tmp}/agents-city-demo."
+DEMO_RUNTIME="$(mktemp -d "${DEMO_PREFIX}XXXXXX")"
+DEMO_DATA="$DEMO_RUNTIME/city"
+DEMO_APP="$DEMO_RUNTIME/app"
+DEMO_STATE="$DEMO_RUNTIME/state"
+DEMO_CITY_ID="$(lee_ciudad id)"
+MAP_PORT="$(free_port)"
+MAP_PID=""
+STORY_PID=""
+
+cleanup() {
+  set +e
+  [ -n "$STORY_PID" ] && kill -TERM "$STORY_PID" 2>/dev/null
+  [ -n "$MAP_PID" ] && kill -TERM "$MAP_PID" 2>/dev/null
+  # The hub deliberately detaches in normal cities. This demo owns a temporary
+  # app home, so close only the PID recorded below that exact directory.
+  python3 - "$DEMO_APP" <<'PY'
+import glob, json, os, signal, sys
+for path in glob.glob(os.path.join(sys.argv[1], '.runtime', 'bus', '*', 'endpoint.json')):
+    try:
+        pid = int(json.load(open(path, encoding='utf-8')).get('pid', 0))
+        if pid > 1:
+            os.kill(pid, signal.SIGTERM)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        pass
+PY
+  sleep 0.35
+  if command -v lsof >/dev/null 2>&1 && [ -d "$DEMO_RUNTIME" ]; then
+    while IFS= read -r pid; do
+      case "$pid" in ''|*[!0-9]*) ;; *) kill -TERM "$pid" 2>/dev/null ;; esac
+    done < <(lsof -t +D "$DEMO_RUNTIME" 2>/dev/null | sort -u)
+  fi
+  case "$DEMO_RUNTIME" in
+    "$DEMO_PREFIX"*) rm -rf -- "$DEMO_RUNTIME" ;;
+  esac
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+mkdir -p "$DEMO_DATA" "$DEMO_APP" "$DEMO_STATE"
+cp -R "$RAIZ/demo/$FIXTURE/." "$DEMO_DATA/"
+
+step "1/5  Building the full Hall and city map"
+if [ ! -f city/web/dist/index.html ] || [ ! -f city/web/dist-hall/hall.js ] \
+  || { [ -w city/web ] && [ city/web/src/main.ts -nt city/web/dist/city.js ]; } \
+  || { [ -w city/web ] && [ city/web/src/hall.ts -nt city/web/dist-hall/hall.js ]; }; then
+  if [ -w city/web ]; then
+    (cd city/web && npm install --silent && npm run build >/dev/null)
+  else
+    echo "  The installed front end is missing. Reinstall agents-city without sudo." >&2
+    exit 1
+  fi
+fi
+
+step "2/5  Creating a disposable demo city ($DOMINIO)"
+cd "$RAIZ/city/worker"
+"${RUNNER[@]}" wrangler@4 d1 execute city --local --persist-to "$DEMO_STATE" \
+  --file schema.sql >/dev/null
+cd "$RAIZ"
+CITY_PERSIST="$DEMO_STATE" ./city/scripts/seed.py \
+  --data "$DEMO_DATA" --fake-history --local
+
+step "3/5  Starting the city map"
+MAP_LOG="$DEMO_RUNTIME/map.log"
+cd "$RAIZ/city/worker"
+"${RUNNER[@]}" wrangler@4 dev --local --persist-to "$DEMO_STATE" \
+  --var "CITY_SECRET:local-test" --var "CITY_ID:$DEMO_CITY_ID" \
+  --port "$MAP_PORT" >"$MAP_LOG" 2>&1 &
+MAP_PID=$!
+cd "$RAIZ"
+
+MAP_READY=0
+for _ in $(seq 1 120); do
+  if curl -fsS "http://127.0.0.1:$MAP_PORT/api/identity" 2>/dev/null \
+    | python3 -c 'import json,sys; raise SystemExit(json.load(sys.stdin).get("cityId") != sys.argv[1])' \
+      "$DEMO_CITY_ID" 2>/dev/null; then
+    MAP_READY=1
+    break
+  fi
+  sleep 0.25
+done
+if [ "$MAP_READY" -ne 1 ]; then
+  echo "  The map did not become ready. Last output:" >&2
+  tail -20 "$MAP_LOG" >&2 || true
+  exit 1
+fi
+
+step "4/5  Connecting the authenticated WebSocket bus"
+DEMO_ENV=(
+  "AGENTS_CITY_HOME=$DEMO_APP"
+  "AGENTS_CITY_DATA=$DEMO_DATA"
+  "AGENTS_CITY_USER=$DEMO_OWNER"
+  "CITY_ADDRESS=$DEMO_OWNER/$DEMO_SLUG"
+)
+env "${DEMO_ENV[@]}" python3 "$RAIZ/demo/show.py" --story "$DOMINIO" &
+STORY_PID=$!
+
+step "5/5  Opening the playable Town Hall"
+echo "  The map owns the centre. Follow the complete committee on the right."
+echo "  Each live turn also appears over its speaker as Para <recipient>: …"
+echo "  Everything disappears when you press ctrl-c; your cities stay untouched."
+if [ "$ABRIR" -eq 1 ]; then
+  env "${DEMO_ENV[@]}" "$RAIZ/bin/hall"
+else
+  env "${DEMO_ENV[@]}" "$RAIZ/bin/hall" --no-browser
+fi

package/bin/exit

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Close the day — everything, or one city: `./bin/exit [city] [--dry-run]`.
+# The logic lives in plugin/scripts/apaga.py so /city:exit inside Claude and this
+# launcher are the same code through two doors.
+exec python3 "$(cd "$(dirname "$0")/../plugin/scripts" && pwd)/apaga.py" "$@"

package/bin/hall

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""The town hall: manage your city from the browser.
+
+    ./bin/hall                open it
+    ./bin/hall --city lab     open one known city
+    ./bin/hall --no-browser   print the address instead
+
+One page on localhost: the selected city's identity, owner seat (role, folders,
+goal), repo support agents, recognised skills, roads, districts and houses. It
+writes the same plain files every other door writes, through the same modules.
+
+The server is bin/serve.py. It binds to 127.0.0.1 on a port the OS picks, and
+every request carries a token minted for this run, because this process writes to
+your disk.
+"""
+import argparse
+import os
+import sys
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, AQUI)
+sys.path.insert(0, os.path.join(os.path.dirname(AQUI), 'plugin', 'scripts'))
+import serve  # noqa: E402
+import cities  # noqa: E402
+
+def asegura_build():
+    """hall.js, built if missing or older than its source. Same npm the map already
+    requires — the hall's headline feature is framing the map, so this is not a new
+    dependency, just the same one earlier."""
+    import subprocess
+    web = os.path.join(os.path.dirname(AQUI), 'city', 'web')
+    js = os.path.join(web, 'dist-hall', 'hall.js')
+    ts = os.path.join(web, 'src', 'hall.ts')
+    if os.path.isfile(js):
+        # Freshness only matters in a clone, where hall.ts gets edited. An npm
+        # install ships hall.js prebuilt — and npm normalises file times, so an
+        # mtime comparison there rebuilds for no reason, or fails where the
+        # install is not writable.
+        es_clon = os.path.isdir(os.path.join(os.path.dirname(AQUI), '.git'))
+        if not es_clon or os.path.getmtime(js) >= os.path.getmtime(ts):
+            return True
+    print('  Building the hall (first time needs npm install)…')
+    r = subprocess.run('npm install --silent && npm run build',
+                       shell=True, cwd=web, capture_output=True, text=True)
+    if not os.path.isfile(js):
+        print('  The build failed. Run by hand and read its output:\n'
+              '    cd city/web && npm install && npm run build\n'
+              f'  {(r.stderr or r.stdout).strip().splitlines()[-1:] or [""] }'[0:400],
+              file=sys.stderr)
+        return False
+    return True
+
+
+if __name__ == '__main__':
+    ap = argparse.ArgumentParser(description='Open one personal city in the local Hall')
+    ap.add_argument('--city', default='', help='known city name, id or path')
+    ap.add_argument('--no-browser', action='store_true', help='print the URL only')
+    a = ap.parse_args()
+    if not asegura_build():
+        sys.exit(1)
+    usuario = cities.usuario_actual()
+    datos = cities.resuelve(a.city, usuario) if a.city else cities.actual(usuario)
+    if not datos:
+        print(f'  No city called {a.city!r}.', file=sys.stderr)
+        sys.exit(1)
+    owner = cities.lee_clave(datos, 'owner')
+    if owner and owner != usuario:
+        print(f"  This city belongs to {owner!r}, not {usuario!r}.", file=sys.stderr)
+        sys.exit(1)
+    cities.selecciona(usuario, datos)
+    sys.exit(0 if serve.sirve(datos,
+                              abrir=not a.no_browser,
+                              pagina='hall') else 0)