agents-city 0.3.0-beta.21

package/city/worker/src/square.ts

@@ -0,0 +1,218 @@
+/**
+ * Square — the *now* of the city.
+ *
+ * One Durable Object for the whole city: it holds the spectator WebSockets with
+ * hibernation, keeps the live state (who has a light on, who is digging where,
+ * the latest notices) and fans out every change.
+ *
+ * Spectators CANNOT send anything. That is a decision, not an omission: the web
+ * is a mirror, not a control panel. If a round could be launched on somebody
+ * else's machine from here, the whole thing dies of mistrust.
+ */
+
+export interface Light {
+  agent: string;
+  user: string;
+  since: string;
+  digging?: string;
+}
+
+/**
+ * A worker is ONE window of ONE person digging in ONE parcel.
+ * A person has several: the seat window, one per repo, and one per worktree —
+ * same repo, different branches, different workers. They are identified by
+ * (user, window), and the user is set by the token, not claimed by the client.
+ */
+export interface Worker {
+  id: string; // user/window
+  user: string;
+  window: string;
+  parcel: string;
+  since: number;
+  last: number; // last heartbeat; without heartbeats they go home
+}
+
+export interface Notice {
+  ts: string;
+  from: string;
+  to: string;
+  tag: string;
+  text: string;
+  read: boolean;
+}
+
+export class Square {
+  state: DurableObjectState;
+  lights = new Map<string, Light>();
+  workers = new Map<string, Worker>();
+  notices: Notice[] = [];
+
+  constructor(state: DurableObjectState) {
+    this.state = state;
+    this.state.blockConcurrencyWhile(async () => {
+      this.notices = (await this.state.storage.get<Notice[]>('notices')) ?? [];
+      this.lights = new Map((await this.state.storage.get<[string, Light][]>('lights')) ?? []);
+      this.workers = new Map((await this.state.storage.get<[string, Worker][]>('workers')) ?? []);
+    });
+  }
+
+  /**
+   * Per-sender throttle. A leaked valid token — or a window in a loop — can push
+   * thousands of events a minute and swamp the fan-out to every spectator. 120 a
+   * minute is ten times what somebody actually working needs.
+   */
+  brakes = new Map<string, { n: number; until: number }>();
+  allowed(who: string): boolean {
+    const now = Date.now();
+    const b = this.brakes.get(who);
+    if (!b || b.until < now) {
+      this.brakes.set(who, { n: 1, until: now + 60_000 });
+      return true;
+    }
+    if (b.n >= 120) return false;
+    b.n++;
+    return true;
+  }
+
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+
+    // Spectator: subscribes and only receives.
+    if (url.pathname === '/ws') {
+      if (req.headers.get('Upgrade') !== 'websocket')
+        return new Response('expected websocket', { status: 426 });
+      const pair = new WebSocketPair();
+      // Hibernation: the DO can be evicted from memory without closing sockets.
+      this.state.acceptWebSocket(pair[1]);
+      pair[1].send(
+        JSON.stringify({
+          t: 'state',
+          lights: [...this.lights.values()],
+          workers: this.alive(),
+          notices: this.notices.slice(0, 40),
+        }),
+      );
+      return new Response(null, { status: 101, webSocket: pair[0] });
+    }
+
+    // Event intake: only from inside (the Worker already checked the secret).
+    if (url.pathname === '/ingest' && req.method === 'POST') {
+      const ev = await req.json<any>();
+      const who = String(ev.user ?? ev.from ?? ev.agent ?? 'anonymous');
+      if (!this.allowed(who)) return new Response('too many events', { status: 429 });
+      await this.apply(ev);
+      return Response.json({ ok: true });
+    }
+
+    if (url.pathname === '/state') {
+      return Response.json({
+        lights: [...this.lights.values()],
+        workers: this.alive(),
+        notices: this.notices.slice(0, 40),
+      });
+    }
+
+    return new Response('no', { status: 404 });
+  }
+
+  /** A worker with no heartbeat for three minutes has left: nobody digs alone. */
+  alive(): Worker[] {
+    const cut = Date.now() - 3 * 60_000;
+    let changed = false;
+    for (const [k, w] of this.workers)
+      if (w.last < cut) {
+        this.workers.delete(k);
+        changed = true;
+      }
+    if (changed) this.state.storage.put('workers', [...this.workers.entries()]);
+    return [...this.workers.values()];
+  }
+
+  async apply(ev: any) {
+    if (ev.t === 'worker') {
+      const id = `${ev.user}/${ev.window}`;
+      const before = this.workers.get(id);
+      if (ev.stopped) {
+        this.workers.delete(id);
+      } else {
+        this.workers.set(id, {
+          id,
+          user: ev.user,
+          window: ev.window,
+          parcel: ev.parcel,
+          since: before && before.parcel === ev.parcel ? before.since : Date.now(),
+          last: Date.now(),
+        });
+      }
+      await this.state.storage.put('workers', [...this.workers.entries()]);
+      // Only fan out on a move: a heartbeat every 30 s is not news.
+      if (!before || before.parcel !== ev.parcel || ev.stopped) this.fanOut({ ...ev, t: 'worker' });
+      return;
+    }
+    if (ev.t === 'attempt') return; // only needed to pass through the throttle
+    if (ev.t === 'light') {
+      if (ev.on) {
+        this.lights.set(ev.agent, {
+          agent: ev.agent,
+          user: String(ev.agent).split('/')[0],
+          since: new Date().toISOString(),
+          digging: ev.digging,
+        });
+      } else {
+        this.lights.delete(ev.agent);
+      }
+      await this.state.storage.put('lights', [...this.lights.entries()]);
+    } else if (ev.t === 'notice') {
+      this.notices.unshift({
+        ts: new Date().toISOString(),
+        from: ev.from,
+        to: ev.to,
+        tag: ev.tag ?? 'notice',
+        text: ev.text ?? '',
+        read: false,
+      });
+      this.notices = this.notices.slice(0, 200);
+      await this.state.storage.put('notices', this.notices);
+    } else if (ev.t === 'read') {
+      const n = this.notices.find((x) => x.ts === ev.ts);
+      if (n) {
+        n.read = true;
+        await this.state.storage.put('notices', this.notices);
+      }
+    }
+    this.fanOut(ev);
+  }
+
+  fanOut(ev: any) {
+    const msg = JSON.stringify({ t: 'change', ev });
+    for (const ws of this.state.getWebSockets()) {
+      try {
+        ws.send(msg);
+      } catch {
+        /* a spectator who left is not a problem */
+      }
+    }
+  }
+
+  // With hibernation these two handlers are required so the runtime knows what
+  // to do on wake-up.
+  /** Sockets already told they are spectators. Lost on hibernation, which only
+   *  means somebody gets told twice. */
+  avisados = new WeakSet<WebSocket>();
+
+  async webSocketMessage(ws: WebSocket) {
+    // Spectators do not send. Say so once, then ignore them: answering every
+    // message would let a client in a loop make this object work for nothing.
+    if (this.avisados.has(ws)) return;
+    this.avisados.add(ws);
+    ws.send(
+      JSON.stringify({
+        t: 'info',
+        text: 'spectator mode: this connection does not accept messages',
+      }),
+    );
+  }
+  async webSocketClose() {
+    /* nothing to clean: getWebSockets() drops it */
+  }
+}

package/city/worker/wrangler.toml

@@ -0,0 +1,58 @@
+name = "city"
+main = "src/index.ts"
+compatibility_date = "2026-08-01"
+# The same Cloudflare account as the bus.
+account_id = "<YOUR_CLOUDFLARE_ACCOUNT_ID>"
+
+# The front end is served by the Worker itself: one origin, no CORS, no separate
+# CDN. run_worker_first is about security and not performance: without it the
+# static files are served BEFORE the Worker runs, so the Access door covered
+# neither the HTML nor the JS nor the sprites.
+[assets]
+directory = "../web/dist"
+binding = "ASSETS"
+run_worker_first = true
+
+# In production: turn these off and route a custom domain instead. A workers.dev
+# URL cannot sit behind an identity proxy, so leaving it on is a permanent back
+# door. Left on here so `wrangler dev` and a first deploy just work.
+# workers_dev = false
+# preview_urls = false
+#
+# [[routes]]
+# pattern = "city.example.com"
+# custom_domain = true
+
+# The square: live state, and fan-out to the spectators.
+[[durable_objects.bindings]]
+name = "SQUARE"
+class_name = "Square"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Square"]
+
+# The history: what has been built, which does not fit in memory and is queried.
+[[d1_databases]]
+binding = "DB"
+database_name = "city"
+database_id = "<YOUR_D1_DATABASE_ID>"
+
+# The bus's own token KV: a worker identifies itself with its own token.
+[[kv_namespaces]]
+binding = "TOKENS"
+id = "<YOUR_KV_NAMESPACE_ID>"
+
+[triggers]
+crons = ["*/5 * * * *"]   # batches of 6 repos: the whole org about every 2h
+
+[vars]
+GITHUB_ORG = "your-org"
+# Closed in production, open when you clone it. With "1", nothing is served
+# without the header your identity proxy sets — the static HTML included. Leave
+# it at "0" for local development and set it to "1" before you deploy: see
+# docs/install.md, "Closing the door".
+REQUIRE_ACCESS = "0"
+
+[observability]
+enabled = true

package/demo/ada.md

@@ -0,0 +1,50 @@
+---
+user: ada
+name: Ada Fontán
+role: cpto
+agent: ada/lead
+repos: []
+covers: [all]
+goals_defined: true
+---
+
+# Ada Fontán
+
+Role: **cpto** — in the city, the **architect**. The domain is in `roles/cpto.md`.
+
+## Repos
+
+No repos of their own: cross-cutting roles do not own any, they answer for one property of all of them.
+
+## Current goals
+
+### O1 — Every parcel has an owner who answers for it
+- **What**: Every parcel has an owner who answers for it.
+- **How it is measured**: 34 parcels, 9 with no owner on the card
+- **Measure**: `grep -c 'dueno' parcels.yml`
+- **Baseline**: 9 without an owner (2026-06-01)
+- **Target**: 0
+- **By when**: Q4 2026
+- **State**: in progress
+
+<!-- Format, one block per goal:
+
+### O1 — <short title>
+- **What**: what has to be achieved, in one sentence.
+- **How it is measured**: the concrete signal that says whether it is going well.
+- **Measure**: the command or query returning that signal, runnable as written.
+  If the signal is a judgement and not a number: `manual — <who looks at what, and
+  how often>`.
+- **Baseline**: what the measure returned the day it was agreed, with the date.
+- **Target**: the value to reach.
+- **By when**: a date or a quarter.
+- **State**: not started | in progress | at risk | done
+
+The measure gets run before the goal is agreed: if it does not work, what is
+missing is building it, and that is work. See /city:goals.
+
+-->
+
+## Round history
+
+Rounds leave their summary here, most recent first.

package/demo/bruno.md

@@ -0,0 +1,62 @@
+---
+user: bruno
+name: Bruno Castel
+role: devops
+agent: bruno/ops
+repos: [consent-kit, infrastructure, ci-templates]
+covers: [all]
+also: [data]
+goals_defined: true
+---
+
+# Bruno Castel
+
+Role: **devops** — in the city, the **surveyor**. The domain is in `roles/devops.md`.
+
+## Repos
+
+Answers for: `consent-kit`, `infrastructure`, `ci-templates`.
+
+## Current goals
+
+### O1 — Launcher start-up drops from 4.2 s to 2 s
+- **What**: Launcher start-up drops from 4.2 s to 2 s.
+- **How it is measured**: time to the game-select screen on the reference machine.
+- **Measure**: `npm run bench:launcher --silent | tail -1`
+- **Baseline**: 4.2 s (2026-01-08)
+- **Target**: 2.0 s
+- **By when**: Q1 2026
+- **State**: in progress
+
+### O2 — No open work sits for more than 14 days
+- **What**: No open work sits for more than 14 days.
+- **How it is measured**: PRs open for over two weeks across the whole org.
+- **Measure**: `gh search prs --owner your-org --state open --created '<2026-01-01' --json number --jq 'length'`
+- **Baseline**: 38 (2026-01-08)
+- **Target**: 0
+- **By when**: Q2 2026
+- **State**: at risk
+
+_Last edited: 2026-02-14 by ada._
+
+<!-- Format, one block per goal:
+
+### O1 — <short title>
+- **What**: what has to be achieved, in one sentence.
+- **How it is measured**: the concrete signal that says whether it is going well.
+- **Measure**: the command or query returning that signal, runnable as written.
+  If the signal is a judgement and not a number: `manual — <who looks at what, and
+  how often>`.
+- **Baseline**: what the measure returned the day it was agreed, with the date.
+- **Target**: the value to reach.
+- **By when**: a date or a quarter.
+- **State**: not started | in progress | at risk | done
+
+The measure gets run before the goal is agreed: if it does not work, what is
+missing is building it, and that is work. See /city:goals.
+
+-->
+
+## Round history
+
+Rounds leave their summary here, most recent first.

package/demo/camila.md

@@ -0,0 +1,56 @@
+---
+user: camila
+name: Camila Ruiz
+role: product-design
+agent: camila/design
+repos: []
+covers: [mobile, arcade]
+goals_defined: true
+---
+
+# Camila Ruiz
+
+Role: **product-design** — in the city, the **interior designer**. The domain is in `roles/product-design.md`.
+
+## Repos
+
+No repos of their own: cross-cutting roles do not own any, they answer for one property of all of them.
+
+## What they cover
+
+Units: **Mobile Games**, **Arcade Cabinets**. The map of which repo and which path belongs to each unit is in `parcels.yml`.
+
+## Current goals
+
+### O1 — No interface component outside the design system
+- **What**: No interface component outside the design system.
+- **How it is measured**: components in nova/packages/ui with no system token.
+- **Measure**: `manual — Camila reviews packages/ui every two weeks`
+- **Baseline**: 9 outside (2026-01-10)
+- **Target**: 0
+- **By when**: Q2 2026
+- **State**: in progress
+
+_Last edited: 2026-02-14 by ada._
+
+<!-- Format, one block per goal:
+
+### O1 — <short title>
+- **What**: what has to be achieved, in one sentence.
+- **How it is measured**: the concrete signal that says whether it is going well.
+- **Measure**: the command or query returning that signal, runnable as written.
+  If the signal is a judgement and not a number: `manual — <who looks at what, and
+  how often>`.
+- **Baseline**: what the measure returned the day it was agreed, with the date.
+- **Target**: the value to reach.
+- **By when**: a date or a quarter.
+- **State**: not started | in progress | at risk | done
+
+The measure gets run before the goal is agreed: if it does not work, what is
+missing is building it, and that is work. See /city:goals.
+
+-->
+
+## Round history
+
+Rounds leave their summary here, most recent first.

package/demo/city/ada.md

@@ -0,0 +1,40 @@
+---
+user: ada
+name: Ada Fontán
+role: cpto
+agent: ada/seat
+repos: [nova, store-service, telemetry-collector, engine-core, launcher]
+role.nova: po
+role.store-service: security
+role.telemetry-collector: data-engineer
+role.engine-core: dev
+role.launcher: product-design
+runs.seat: claude
+runs.nova: claude
+runs.store-service: codex
+runs.telemetry-collector: opencode
+runs.engine-core: kimi
+runs.launcher: codex
+goals_defined: true
+---
+
+# Ada Fontán — Aurora Games chair
+
+Ada is the chair. The five repositories are private support agents with their
+own operating roles and mixed runtimes; the demo does not start paid models.
+
+## Current goal
+
+### O1 — Release cross-save without losing player progress
+- **What**: Ship cross-save through a reversible rollout shared by every game.
+- **How it is measured**: verified restores, conflict rate and rollback time.
+- **Measure**: `demo — scripted evidence over the local WebSocket committee`
+- **Baseline**: one game, no shared rollback contract
+- **Target**: canary verified before portfolio rollout
+- **By when**: demo day
+- **State**: in progress
+
+## Round history
+
+The guided committee writes its complete act here at runtime. The packaged
+fixture is copied to a temporary directory first, so this file stays untouched.

package/demo/city/city.yml

@@ -0,0 +1,8 @@
+# Aurora Games is fictional and exists only for `agents-city demo`.
+id: city_demo_aurora_v2
+name: Aurora Games
+slug: aurora-games
+owner: ada
+layout: personal-v2
+domain: software
+grow_command: demo — generated history

package/demo/city/parcels.yml

@@ -0,0 +1,15 @@
+# Five repo agents, five visible houses. The scripted committee deliberately
+# invites only three, so abstention and bounded participation remain believable.
+repos:
+  nova:
+    - ruta: "" ; unidad: games ; nombre: "Nova games"
+  store-service:
+    - ruta: "" ; unidad: platform ; nombre: "Player store"
+  telemetry-collector:
+    - ruta: "" ; unidad: data ; nombre: "Telemetry"
+  engine-core:
+    - ruta: "" ; unidad: platform ; nombre: "Engine core"
+  launcher:
+    - ruta: "" ; unidad: games ; nombre: "Game launcher"
+
+lab: []

package/demo/city/roads.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "roads": []
+}

package/demo/city/units.yml

@@ -0,0 +1,10 @@
+# A compact city: enough variety to understand districts without turning the
+# first screen into a wall of houses.
+units:
+  - id: games    ; name: Player Games      ; color: 3fb8a0 ; order: 1
+  - id: platform ; name: Shared Platform   ; color: 8f7ae6 ; order: 2
+  - id: data     ; name: Player Data       ; color: e2604f ; order: 3
+
+special:
+  - id: lab      ; name: Lab               ; color: 8fb8c9 ; order: 90
+  - id: none     ; name: Shared             ; color: c8b48a ; order: 99

package/demo/clinica/city.yml

@@ -0,0 +1,8 @@
+# Clínica Alba is fictional and exists only for `agents-city demo --domain medicina`.
+id: city_demo_clinica_v1
+name: Clínica Alba
+slug: clinica-alba
+owner: vera
+layout: personal-v2
+domain: medicina
+grow_command: demo — generated history

package/demo/clinica/parcels.yml

@@ -0,0 +1,15 @@
+# Five agents, five houses. The scripted committee invites only three, so
+# abstention and bounded participation remain believable — same as Aurora.
+repos:
+  urgencias:
+    - ruta: "" ; unidad: atencion ; nombre: "Urgencias"
+  laboratorio:
+    - ruta: "" ; unidad: diagnostico ; nombre: "Laboratorio"
+  farmacia:
+    - ruta: "" ; unidad: atencion ; nombre: "Farmacia"
+  archivo-historias:
+    - ruta: "" ; unidad: gestion ; nombre: "Archivo de historias"
+  admision:
+    - ruta: "" ; unidad: gestion ; nombre: "Admisión"
+
+lab: []

package/demo/clinica/roads.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "roads": []
+}

package/demo/clinica/units.yml

@@ -0,0 +1,9 @@
+# A small clinic: three districts anyone can read at a glance.
+units:
+  - id: atencion    ; name: Atención al Paciente ; color: 3fb8a0 ; order: 1
+  - id: diagnostico ; name: Diagnóstico          ; color: 4a9ede ; order: 2
+  - id: gestion     ; name: Gestión              ; color: 8f7ae6 ; order: 3
+
+special:
+  - id: lab         ; name: Lab                  ; color: 8fb8c9 ; order: 90
+  - id: none        ; name: Shared               ; color: c8b48a ; order: 99

package/demo/clinica/vera.md

@@ -0,0 +1,46 @@
+---
+user: vera
+name: Vera Salas
+role: cpto
+agent: vera/seat
+agents: [urgencias, laboratorio, farmacia, archivo-historias, admision]
+kind.urgencias: coordinator
+kind.laboratorio: knowledge
+kind.farmacia: knowledge
+kind.archivo-historias: knowledge
+kind.admision: coordinator
+role.urgencias: triaje
+role.laboratorio: analisis
+role.farmacia: recetas
+role.archivo-historias: historias
+role.admision: citas
+runs.seat: claude
+runs.urgencias: claude
+runs.laboratorio: claude
+runs.farmacia: claude
+runs.archivo-historias: claude
+runs.admision: claude
+goals_defined: true
+---
+
+# Vera Salas — Clínica Alba, dirección
+
+Vera chairs the clinic. No agent here is a repository: they are knowledge and
+coordination agents — the agents-first model, where a repo is just one thing an
+agent may mount and none of these mounts one.
+
+## Current goal
+
+### O1 — Nadie sale de la sala de espera sin un camino
+- **What**: Que cada persona que entra salga atendida o con cita real en mano.
+- **How it is measured**: sala bajo aforo y reprogramaciones con día y hora.
+- **Measure**: `demo — scripted evidence over the local WebSocket committee`
+- **Baseline**: mañanas de caos cuando el sistema de citas falla
+- **Target**: caos absorbido sin cerrar la puerta
+- **By when**: demo day
+- **State**: in progress
+
+## Round history
+
+The guided committee writes its complete act here at runtime. The packaged
+fixture is copied to a temporary directory first, so this file stays untouched.

package/demo/dante.md

@@ -0,0 +1,54 @@
+---
+user: dante
+name: Dante Oliveira
+role: product-design
+agent: dante/design
+repos: []
+covers: [console, school]
+goals_defined: true
+---
+
+# Dante Oliveira
+
+Role: **product-design** — in the city, the **interior designer**. The domain is in `roles/product-design.md`.
+
+## Repos
+
+No repos of their own: cross-cutting roles do not own any, they answer for one property of all of them.
+
+## What they cover
+
+Units: **Console Games**, **School Editions**. The map of which repo and which path belongs to each unit is in `parcels.yml`.
+
+## Current goals
+
+### O1 — The design system is what ships, not a reference
+- **What**: The design system is what ships, not a reference.
+- **How it is measured**: Screens built from components rather than one-off styles
+- **Measure**: `rg -l 'StyleSheet.create' apps | wc -l`
+- **Baseline**: 38 files (2026-06-20)
+- **Target**: under 10
+- **By when**: Q1 2027
+- **State**: at risk
+
+<!-- Format, one block per goal:
+
+### O1 — <short title>
+- **What**: what has to be achieved, in one sentence.
+- **How it is measured**: the concrete signal that says whether it is going well.
+- **Measure**: the command or query returning that signal, runnable as written.
+  If the signal is a judgement and not a number: `manual — <who looks at what, and
+  how often>`.
+- **Baseline**: what the measure returned the day it was agreed, with the date.
+- **Target**: the value to reach.
+- **By when**: a date or a quarter.
+- **State**: not started | in progress | at risk | done
+
+The measure gets run before the goal is agreed: if it does not work, what is
+missing is building it, and that is work. See /city:goals.
+
+-->
+
+## Round history
+
+Rounds leave their summary here, most recent first.

package/demo/despacho/city.yml

@@ -0,0 +1,8 @@
+# Costa & Ley is fictional and exists only for `agents-city demo --domain legal`.
+id: city_demo_despacho_v1
+name: Costa & Ley
+slug: costa-ley
+owner: marta
+layout: personal-v2
+domain: legal
+grow_command: demo — generated history