agents-city 0.3.0 → 0.4.0

package/city/web/src/casa.ts

@@ -0,0 +1,282 @@
+/**
+ * Building one house: name, work, role, engine and everything it works on.
+ *
+ * This lived inside the first-run guide, and the Hall had its own version of the
+ * same question made of three chained `window.prompt` boxes — name, then kind,
+ * then role, with no engine and no way to pick a folder. Two implementations of
+ * one question, and the worse one was the one people met after the first day.
+ *
+ * So it is one form, mounted wherever it is needed: inside the guide as a step,
+ * inside a dialog from the houses view. It owns its own state and repaints
+ * itself; the host owns the frame around it and decides what the buttons say.
+ */
+
+import { plural, t as _ } from './idioma';
+import { Explorador } from './explorador';
+import { ESFUERZOS, MODELOS, RUNTIMES, opciones } from './motores';
+
+export interface Rol {
+  id: string;
+  name: string;
+  summary: string;
+  trade: string;
+}
+
+export interface DatosDeCasa {
+  nombre: string;
+  clase: string;
+  rol: string;
+  montajes: string[];
+  /** Which CLI runs it, and — on Claude — the engine and how hard it thinks.
+   * Empty means the owner's default, which is a real answer and the one most
+   * people should give. */
+  runtime: string;
+  modelo: string;
+  esfuerzo: string;
+}
+
+/** What the form needs from whoever is hosting it. */
+export interface Puerta {
+  api: <T>(ruta: string, opts?: RequestInit) => Promise<T>;
+  esc: (s: unknown) => string;
+  aviso: (texto: string, malo?: boolean) => void;
+  yo: string;
+}
+
+export const CLASES: Array<[string, string, string]> = [
+  [
+    'code',
+    'It writes code',
+    'Its house grows with the pull requests it merges. Mounts repositories and worktrees.',
+  ],
+  [
+    'knowledge',
+    'It keeps knowledge',
+    'Its house grows with the documents it writes. Needs no git at all.',
+  ],
+  ['coordinator', 'It coordinates', 'Its house grows with the decisions it records.'],
+];
+
+export class FormularioDeCasa {
+  readonly datos: DatosDeCasa = {
+    nombre: '',
+    clase: 'code',
+    rol: 'blank',
+    montajes: [],
+    runtime: '',
+    modelo: '',
+    esfuerzo: '',
+  };
+  private roles: Rol[] = [];
+  private host: HTMLElement | null = null;
+
+  constructor(
+    private readonly p: Puerta,
+    roles: Rol[] = [],
+  ) {
+    this.roles = roles;
+  }
+
+  /** Render into `host` and wire it. Safe to call again: that is the repaint. */
+  monta(host: HTMLElement): void {
+    this.host = host;
+    void this.aseguraRoles();
+    host.innerHTML = this.html();
+    this.enlaza(host);
+    const hueco = host.querySelector<HTMLElement>('.casaExp');
+    if (hueco) this.explora().monta(hueco);
+  }
+
+  private repinta(): void {
+    if (this.host) this.monta(this.host);
+  }
+
+  private async aseguraRoles(): Promise<void> {
+    if (this.roles.length) return;
+    try {
+      const r = await this.p.api<{ roles: Rol[] }>('/api/roles?scope=agent');
+      this.roles = r.roles ?? [];
+      this.repinta();
+    } catch {
+      this.roles = []; // the role list is a convenience; blank is always valid
+    }
+  }
+
+  /** The folder picker, built once so walking survives a repaint. */
+  private explorador: Explorador | null = null;
+
+  private explora(): Explorador {
+    if (!this.explorador)
+      this.explorador = new Explorador(
+        this.p,
+        (ruta) => {
+          const ya = this.datos.montajes.indexOf(ruta);
+          if (ya >= 0) this.datos.montajes.splice(ya, 1);
+          else this.datos.montajes.push(ruta);
+          this.repinta();
+        },
+        () => this.datos.montajes,
+      );
+    return this.explorador;
+  }
+
+  html(): string {
+    const a = this.datos;
+    const esc = this.p.esc;
+    const clases = CLASES.map(
+      ([id, titulo, porque]) => `
+      <button type="button" class="bvOpcion ${a.clase === id ? 'elegida' : ''}"
+        data-bv="clase" data-id="${id}">
+        <b>${_(titulo)}</b><span>${_(porque)}</span></button>`,
+    ).join('');
+    const roles = this.roles
+      .map(
+        (r) =>
+          `<option value="${esc(r.id)}"${r.id === a.rol ? ' selected' : ''}>${esc(r.name)}</option>`,
+      )
+      .join('');
+    const esClaude = (a.runtime || 'claude') === 'claude';
+    return `
+      <div class="campo"><label>${_('What do you call it?')}</label>
+        <input type="text" id="bvNombre" value="${esc(a.nombre)}"
+          placeholder="${_('urgencias, api, the handbook — whatever you would say out loud')}"></div>
+      <label class="bvEtiqueta">${_('What kind of work does it do?')}</label>
+      <div class="bvRejilla bvTres">${clases}</div>
+      <div class="campo"><label>${_('Its role — its speciality, never authority')}</label>
+        <select id="bvRol">${roles}</select></div>
+      <label class="bvEtiqueta">${_('What runs it?')}</label>
+      <p class="pista">${_(
+        'Leave all three on default and it runs the way you do. Model and effort are Claude’s to read; another CLI carries its own flags.',
+      )}</p>
+      <div class="bvMotor">
+        <div class="campo"><label>${_('provider')}</label>
+          <select id="bvRuntime">${opciones(RUNTIMES, a.runtime, esc, 'claude')}</select></div>
+        <div class="campo"><label>${_('engine')}</label>
+          <select id="bvModelo" ${esClaude ? '' : 'disabled'}>${opciones(
+            [''].concat(MODELOS),
+            a.modelo,
+            esc,
+            _('default'),
+          )}</select></div>
+        <div class="campo"><label>${_('effort')}</label>
+          <select id="bvEsfuerzo" ${esClaude ? '' : 'disabled'}>${opciones(
+            [''].concat(ESFUERZOS),
+            a.esfuerzo,
+            esc,
+            _('default'),
+          )}</select></div>
+      </div>
+      <label class="bvEtiqueta">${_('What does it work on?')}</label>
+      <p class="pista">${_(`Walk your disk and pick whatever you like: a repository, a
+      worktree, a folder of documents, one exact file. As many as you want. Nothing is
+      copied — each one is linked into this agent's own home.`)}</p>
+      <div class="casaExp"></div>
+      ${
+        a.montajes.length
+          ? `<div class="expElegidas"><label class="bvEtiqueta">${_('Working on')}</label>
+             ${a.montajes
+               .map(
+                 (m) => `<button type="button" class="bvChip elegida" data-bv="quita"
+                   data-ruta="${esc(m)}" title="${esc(m)}">${esc(
+                     m.split('/').pop() || m,
+                   )}<i class="expQuita">✕</i></button>`,
+               )
+               .join('')}</div>`
+          : `<p class="pista">${_('Nothing chosen yet — an agent with no mounts is fine too.')}</p>`
+      }`;
+  }
+
+  private enlaza(raiz: HTMLElement): void {
+    raiz.querySelectorAll<HTMLElement>('[data-bv]').forEach((el) => {
+      el.onclick = (evento) => {
+        evento.preventDefault();
+        const que = el.dataset.bv;
+        this.recoge(raiz);
+        if (que === 'clase') this.datos.clase = el.dataset.id ?? 'code';
+        else if (que === 'quita') {
+          const ya = this.datos.montajes.indexOf(el.dataset.ruta ?? '');
+          if (ya >= 0) this.datos.montajes.splice(ya, 1);
+        }
+        this.repinta();
+      };
+    });
+    raiz.querySelector<HTMLSelectElement>('#bvRuntime')?.addEventListener('change', () => {
+      this.recoge(raiz);
+      this.repinta();
+    });
+  }
+
+  /** Keep what is typed when a click forces a repaint. */
+  private recoge(raiz: HTMLElement): void {
+    const nombre = raiz.querySelector<HTMLInputElement>('#bvNombre');
+    const rol = raiz.querySelector<HTMLSelectElement>('#bvRol');
+    if (nombre) this.datos.nombre = nombre.value;
+    if (rol) this.datos.rol = rol.value;
+    for (const [id, campo] of [
+      ['#bvRuntime', 'runtime'],
+      ['#bvModelo', 'modelo'],
+      ['#bvEsfuerzo', 'esfuerzo'],
+    ] as const) {
+      const sel = raiz.querySelector<HTMLSelectElement>(id);
+      if (sel) this.datos[campo] = sel.value;
+    }
+  }
+
+  /**
+   * Build it. Returns the new agent's slug, or null when nothing was written.
+   *
+   * Three endpoints by necessity, not by sloppiness: `/api/agentes` owns who is
+   * on the roster, `/api/montaje` owns what an agent can reach, and
+   * `/api/agente` owns how one is run. None of them is allowed to learn
+   * another's job just to save a round trip.
+   */
+  async guarda(): Promise<{ slug: string; nombre: string } | null> {
+    if (this.host) this.recoge(this.host);
+    const a = this.datos;
+    const nombre = a.nombre.trim();
+    if (!nombre) {
+      this.p.aviso(_('Give it a name — it is how you will call it in its window'), true);
+      return null;
+    }
+    try {
+      const r = await this.p.api<{ ok?: boolean; agent?: string; error?: string }>('/api/agentes', {
+        method: 'POST',
+        body: JSON.stringify({ name: nombre, kind: a.clase, role: a.rol }),
+      });
+      if (!r.ok || !r.agent) {
+        this.p.aviso(r.error || _('Could not add that agent'), true);
+        return null;
+      }
+      for (const ruta of a.montajes) {
+        const m = await this.p.api<{ ok?: boolean; error?: string }>('/api/montaje', {
+          method: 'POST',
+          body: JSON.stringify({ agent: r.agent, add: ruta }),
+        });
+        if (!m.ok) this.p.aviso(`${ruta}: ${m.error ?? _('could not mount')}`, true);
+      }
+      const motor: Record<string, string> = {};
+      if (a.runtime) motor.runtime = a.runtime;
+      if (a.modelo) motor.model = a.modelo;
+      if (a.esfuerzo) motor.effort = a.esfuerzo;
+      if (Object.keys(motor).length) {
+        const m = await this.p.api<{ ok?: boolean; error?: string }>('/api/agente', {
+          method: 'POST',
+          body: JSON.stringify({ agent: r.agent, ...motor }),
+        });
+        if (!m.ok) this.p.aviso(m.error ?? _('Could not set its engine'), true);
+      }
+      return { slug: r.agent, nombre };
+    } catch (e) {
+      this.p.aviso(String(e), true);
+      return null;
+    }
+  }
+
+  /** How this house reads on a list, once it is built. */
+  resumen(): string {
+    const a = this.datos;
+    return a.montajes.length
+      ? plural(a.montajes.length, '{n} mount', '{n} mounts')
+      : _('nothing mounted yet');
+  }
+}

package/city/web/src/demo.ts

@@ -0,0 +1,247 @@
+/**
+ * The demo shelf: a committee, played back.
+ *
+ * `agents-city demo` has always existed and it is the honest one — an ephemeral
+ * city, the real bus, the real state machine. It also asks for a terminal, a
+ * wrangler download and two minutes. Somebody deciding whether this product is
+ * for their clinic or their law firm will not do that first; they will look for
+ * a play button, and there wasn't one.
+ *
+ * So the Hall plays a **recording**. Not a simulation: `demo/graba.py` runs each
+ * story over that same real bus and keeps the exact event stream a spectator
+ * saw, and this plays those events back through the very same renderer the live
+ * rail uses. Nothing here knows what a committee is, which is the point — a
+ * second implementation of the state machine is a second thing to drift.
+ *
+ * It says on screen that it is a recording. A demo that pretends to be live is
+ * the one kind of demo this product must never ship.
+ */
+
+import type { ActivityEvent } from './activity';
+import { t as _ } from './idioma';
+
+export interface Ficha {
+  id: string;
+  dominio: string;
+  ciudad: string;
+  titulo: string;
+  turnos: number;
+  reparto: string[];
+}
+
+interface Grabacion extends Ficha {
+  eventos: ActivityEvent[];
+  error?: string;
+}
+
+export interface PuertaDemo {
+  api: <T>(ruta: string, opts?: RequestInit) => Promise<T>;
+  esc: (s: unknown) => string;
+  /** The live rail's own turn renderer — the same one, deliberately. */
+  pinta: (evento: ActivityEvent) => string;
+}
+
+/** How fast a turn arrives, in milliseconds. The middle one is the pace the
+ * terminal demo uses, so the two feel like the same product. */
+const VELOCIDADES: Array<[string, number]> = [
+  ['0.5×', 2900],
+  ['1×', 1450],
+  ['2×', 700],
+  ['4×', 350],
+];
+
+export class Demos {
+  private catalogo: Ficha[] = [];
+  private cargando = false;
+  private elegida: Grabacion | null = null;
+  private hasta = 0;
+  private corriendo = false;
+  private velocidad = 1450;
+  private reloj: number | null = null;
+  private host: HTMLElement | null = null;
+
+  constructor(private readonly p: PuertaDemo) {}
+
+  monta(host: HTMLElement): void {
+    this.host = host;
+    if (!this.catalogo.length && !this.cargando) void this.lee();
+    this.repinta();
+  }
+
+  /** Stop the clock. Called when the section is left, or the page repaints
+   * elsewhere: a timer still firing into a detached node is a leak with a view. */
+  para(): void {
+    this.corriendo = false;
+    if (this.reloj !== null) {
+      clearTimeout(this.reloj);
+      this.reloj = null;
+    }
+  }
+
+  private repinta(): void {
+    if (!this.host) return;
+    this.host.innerHTML = this.html();
+    this.enlaza(this.host);
+    if (this.elegida) {
+      const lista = this.host.querySelector<HTMLElement>('#demoLista');
+      if (lista) lista.scrollTop = lista.scrollHeight;
+    }
+  }
+
+  private async lee(): Promise<void> {
+    this.cargando = true;
+    try {
+      const r = await this.p.api<{ demos: Ficha[] }>('/api/demos');
+      this.catalogo = r.demos ?? [];
+    } catch {
+      this.catalogo = [];
+    } finally {
+      this.cargando = false;
+      this.repinta();
+    }
+  }
+
+  private async abre(id: string): Promise<void> {
+    this.para();
+    this.hasta = 0;
+    this.elegida = null;
+    this.repinta();
+    try {
+      const r = await this.p.api<Grabacion>('/api/demos?story=' + encodeURIComponent(id));
+      if (!r.error) this.elegida = r;
+    } catch {
+      this.elegida = null;
+    }
+    this.repinta();
+    if (this.elegida) this.arranca();
+  }
+
+  private arranca(): void {
+    if (!this.elegida) return;
+    if (this.hasta >= this.elegida.eventos.length) this.hasta = 0;
+    this.corriendo = true;
+    this.repinta();
+    this.siguiente();
+  }
+
+  private siguiente(): void {
+    if (this.reloj !== null) clearTimeout(this.reloj);
+    this.reloj = window.setTimeout(() => {
+      if (!this.corriendo || !this.elegida) return;
+      this.hasta += 1;
+      if (this.hasta >= this.elegida.eventos.length) {
+        this.hasta = this.elegida.eventos.length;
+        this.corriendo = false;
+        this.repinta();
+        return;
+      }
+      this.repinta();
+      this.siguiente();
+    }, this.velocidad);
+  }
+
+  private html(): string {
+    if (this.elegida) return this.reproductor(this.elegida);
+    if (this.cargando) return `<p class="cargando">${_('reading the demo shelf')}</p>`;
+    if (!this.catalogo.length)
+      return `<div><span class="sub">${_('demos')}</span>
+        <h1 style="margin-top:6px">${_('Nothing recorded here')}</h1>
+        <p class="prosa">${_('This install has no demo recordings. Make them with demo/graba.py, or run the full thing from a terminal with agents-city demo.')}</p></div>`;
+    const esc = this.p.esc;
+    return `<div>
+      <span class="sub">${_('demos')}</span>
+      <h1 style="margin-top:6px">${_('See a committee happen')}</h1>
+      <p class="prosa">${_(`A real question, answered by a city of agents that never talk to each
+      other behind the chair's back. Pick the field closest to yours — the machine is the same
+      one in all three; only the work changes.`)}</p>
+      <div class="demoRejilla">${this.catalogo
+        .map(
+          (d) => `<button type="button" class="demoCarta" data-demo="abre" data-id="${esc(d.id)}">
+          <span class="demoDominio">${esc(d.dominio)}</span>
+          <b>${esc(d.titulo)}</b>
+          <span class="demoCiudad">${esc(d.ciudad)}</span>
+          <span class="demoReparto">${esc(d.reparto.join(' · '))}</span>
+          <span class="demoPlay">▶ ${_('{n} turns', { n: d.turnos })}</span>
+        </button>`,
+        )
+        .join('')}</div>
+      <p class="pista">${_('These are recordings of real runs over the real bus, played back here. To run one live in a terminal: agents-city demo --domain software.')}</p>
+    </div>`;
+  }
+
+  private reproductor(d: Grabacion): string {
+    const esc = this.p.esc;
+    const total = d.eventos.length;
+    const hecho = Math.min(this.hasta, total);
+    const turnos = d.eventos.slice(0, hecho).map(this.p.pinta).join('');
+    const acabado = hecho >= total;
+    return `<div class="demoPlayer">
+      <div class="demoCab">
+        <button type="button" class="bt bvMini" data-demo="atras">← ${_('All demos')}</button>
+        <div><span class="sub">${esc(d.dominio)} · ${esc(d.ciudad)}</span>
+          <h2>${esc(d.titulo)}</h2></div>
+      </div>
+      <div class="demoMandos">
+        <button type="button" class="bt ppal" data-demo="${this.corriendo ? 'pausa' : 'play'}">${
+          this.corriendo ? `❚❚ ${_('Pause')}` : acabado ? `↺ ${_('Replay')}` : `▶ ${_('Play')}`
+        }</button>
+        <button type="button" class="bt" data-demo="replay" ${hecho ? '' : 'disabled'}>↺ ${_(
+          'Replay',
+        )}</button>
+        <span class="demoVel">${VELOCIDADES.map(
+          ([etiqueta, ms]) =>
+            `<button type="button" class="demoVelBoton ${
+              ms === this.velocidad ? 'aqui' : ''
+            }" data-demo="vel" data-ms="${ms}">${esc(etiqueta)}</button>`,
+        ).join('')}</span>
+        <span class="demoCuenta">${_('{done} of {total}', { done: hecho, total })}</span>
+      </div>
+      <div class="demoBarra"><i style="width:${total ? (hecho / total) * 100 : 0}%"></i></div>
+      <ol class="liveLista" id="demoLista">${
+        turnos ||
+        `<li class="liveEmpty">${_('Press play. The turns arrive one by one, exactly as they did.')}</li>`
+      }</ol>
+      <p class="pista">${_('A recording of a real run: these events came off the real bus, from the real committee. Nothing here is being decided now.')}</p>
+    </div>`;
+  }
+
+  private enlaza(raiz: HTMLElement): void {
+    raiz.querySelectorAll<HTMLElement>('[data-demo]').forEach((el) => {
+      el.onclick = (evento) => {
+        evento.preventDefault();
+        switch (el.dataset.demo) {
+          case 'abre':
+            void this.abre(el.dataset.id ?? '');
+            break;
+          case 'atras':
+            this.para();
+            this.elegida = null;
+            this.hasta = 0;
+            this.repinta();
+            break;
+          case 'play':
+            this.arranca();
+            break;
+          case 'pausa':
+            this.para();
+            this.repinta();
+            break;
+          case 'replay':
+            this.para();
+            this.hasta = 0;
+            this.arranca();
+            break;
+          case 'vel': {
+            this.velocidad = Number(el.dataset.ms) || 1450;
+            // Take effect on the next turn rather than after the one already
+            // scheduled at the old pace: a speed control that waits three
+            // seconds to be believed reads as broken.
+            if (this.corriendo) this.siguiente();
+            this.repinta();
+            break;
+          }
+        }
+      };
+    });
+  }
+}