🔗 Nexus

← Volver a notas
21 KB 11/11/2026 12:24
🔗

HQ Spike #2 — KbWen/agent-virtual-office (validación práctica)

Proyecto: Sede Virtual Disoftx HQ · Autor: Nexus (subagente) · Fecha: 2026-09-20
Repo: https://github.com/KbWen/agent-virtual-office · commit 940eecb · versión 1.6.9 · MIT
Stack: React 19 + Vite 8 + SVG puro + Zustand · Node ≥ 22 · sin backend, sin DB, sin GPU
Estado: ✅ Spike ejecutado — servidor corriendo en http://127.0.0.1:4599


1. Resumen ejecutivo

El repo funciona tal como promete y encaja con nuestros requisitos técnicos. Lo clonamos, compilamos,
levantamos y la oficina reaccionó correctamente a nuestro feed de estados (6 agentes inyectados vía
HTTP con working / planning / idle / blocked). Confirmado con screenshots reales (ver §5).

Veredicto: SÍ SIRVE como base para la Sede Virtual HQ. Es ligero (bundle ~500 kB JS / 36 kB CSS),
sin backend propio, sin canvas/GPU, licencia MIT, y acepta eventos por POST /api/status — conectar
nuestro feed es escribir un puente de ~60–100 líneas.

Dos restricciones de diseño importantes que condicionan la integración (detalle en §4):

  1. El conjunto de agentes es FIJO: 8 roles (pm, arch, dev, qa, ops, res, gate, designer). No se
    inventan personajes nuevos; se renombran los 8 existentes (?agents=Nombre:rol) y opcionalmente
    se recolorean. Máximo 8 personajes simultáneos en escena.
  2. thinking NO es un estado aceptado por la API. El enum real es
    idle · working · blocked · done · planning · awaiting-approval. Si mandas "thinking", el server lo
    coacciona a idle (verificado). "Thinking" solo existe como estado inferido en el cliente
    (working sin updates ≥45 s → thinking).

Esfuerzo de integración estimado: 1–2 días (puente + mapeo + renombrado + deploy/systemd + reverse-proxy).


2. Cómo correrlo (comandos exactos)

Todo quedó en /home/admin/.openclaw/workspace/proyectos/hq-spike-2/.

cd /home/admin/.openclaw/workspace/proyectos/hq-spike-2/agent-virtual-office
npm install                 # 70 paquetes, ~5 s
npm run build               # vite build → dist/  (dist ~692 KB)

# Servir (producción, Node nativo — no necesita Vite):
OFFICE_STATUS_DIR=/home/admin/.openclaw/workspace/proyectos/hq-spike-2/status \
OFFICE_PROJECT_ROOT=/home/admin/.openclaw/workspace/proyectos/hq-spike-2/agent-virtual-office \
node server.mjs --port=4599 --no-open

Helper creado (recomendado para levantar/parar limpio):

./run.sh start     # arranca en background (setsid) en :4599
./run.sh status    # puerto + /api/health
./run.sh stop      # detiene

OFFICE_STATUS_DIR redirige el directorio de estado (default ~/.claude/) → así NO tocamos
~/.claude de la máquina
. OFFICE_PROJECT_ROOT debe coincidir con el cwd desde el que se sirve,
porque el office filtra sesiones por project root (ver §4).
Alternativa dev: npm run dev -- --port=4599 (Vite, con los mismos endpoints /api/*).


3. Contrato de eventos — VERIFICADO EN VIVO

El office no tiene backend que configurar: cualquier cosa que haga un HTTP POST lo maneja.

3.1 POST /api/status — estado en vivo (transporte principal)

Formato completo (el que usaremos):

curl -X POST http://127.0.0.1:4599/api/status \
  -H "Content-Type: application/json" \
  -d '{
    "type": "office-status",
    "source": "nexus-feed",
    "workflow": "Disoftx HQ — operaciones en vivo",
    "mood": "intense",
    "agents": [
      {"role":"pm",  "task":"orquestar", "status":"working",  "label":"Nexus core: despachando subagentes"},
      {"role":"ops", "task":"backup",    "status":"working",  "label":"Siscont backup en curso"},
      {"role":"dev", "task":"render",    "status":"working",  "label":"Pipeline YT renderizando"},
      {"role":"designer","task":"ads",   "status":"planning", "label":"Zephyra marketing: planificando"},
      {"role":"qa",  "task":"espera",    "status":"idle",     "label":"Cyclofun QA en espera"},
      {"role":"res", "task":"rate limit","status":"blocked",  "label":"Error: API rate limit",
       "reasonCode":"api-rate-limit"}
    ]
  }'
# → {"ok":true,"agents":6}

Formato shorthand (también funciona):

curl -X POST http://127.0.0.1:4599/api/status -d '{"pm":"working","ops":"blocked","workflow":"X"}'

Campos del agente (contrato exacto, statusContract.mjs):

Campo Tipo Notas
role enum obligatorio pm·arch·dev·qa·ops·res·gate·designer. Rol inválido ⇒ el agente se descarta silenciosamente.
status enum idle·working·blocked·done·planning·awaiting-approval. Inválido/ausente ⇒ idle.
task string (≤200) Texto libre corto.
label string (≤200) Texto que aparece en la burbuja/roster.
reasonCode enum test-run-failed·build-failed·deps-failed·blocked-unknown·permission-denied·api-rate-limit·api-auth-failed (solo con blocked).
hint, activeFile, skill string Opcionales; activeFile habilita el pair-huddle (dos agentes con el mismo archivo).

Nivel payload: workflow (≤200, banner superior), mood ∈ normal·rushing·frustrated·stuck·smooth·intense·idle,
moodDuration (ms), source (≤50).
Límites: body ≤16 KB, máx 8 roles únicos (dedup por rol; se ignoran duplicados), rate-limit 30 POST/10 s.

3.2 GET /api/status — leer estado actual (verificado)

Devuelve el payload fusionado (todos los office-status*.json activos). Soporta ETag / 304.

3.3 GET /api/status/stream — SSE (verificado)

Emite event: status\ndata: {...} al conectar y en cada cambio (heartbeat cada 30 s). Ideal si
nuestro frontend quiere consumir el mismo feed
sin polling.

3.4 POST /api/event — eventos one-shot (verificado)

Dispara momentos predefinidos: deploy-success, pr-merged, test-failed, incident-start,
release, rollback… y custom con {role,status,label}. Ej:

curl -X POST http://127.0.0.1:4599/api/event -d '{"event":"deploy-success"}'   # → ops = done 🎉

3.5 Transporte alternativo: archivo de estado

Los hooks escriben directamente OFFICE_STATUS_DIR/office-status-{slug}.json (mismo esquema
{_seq, type, agents, workflow, source, _cwd}). El server lo detecta vía fs.watch y lo empuja por SSE.
Nuestro puente puede usar POST (recomendado) o escribir el JSON a disco.

3.6 GET /api/health → {"ok":true,"uptime":N,"hookSessionCount":M,...}


4. Mapeo de NUESTROS estados → oficina (contrato de integración)

Nuestro estado → API status Visual en la oficina ¿Directo?
idle idle Anillo gris + deambula / café ✅ directo
working working Anillo ámbar, teclea en el escritorio ✅ directo
thinking planning (o working y dejar que inferir) Anillo violeta (plan mode) ⚠️ manual
error blocked (+ reasonCode) Anillo rojo, ícono de bloqueo, barra "⚠️ Needs your attention" ✅ directo

Sobre thinking (gotcha confirmado): thinking no está en VALID_STATUSES; un POST con
"status":"thinking" se guarda como idle. Opciones reales:
- (a) Recomendada: mapear nuestros thinking → planning (violeta, semánticamente "pensando/planificando").
- (b) Mapear a working y no re-postear durante ≥45 s → el cliente infiere thinking solo
(anillo/aura de "cognición"). Es el comportamiento nativo del office, pero es basado en tiempo, no en señal.

Regla de frescura (crítica para el puente):
- El estado expira a los 5 min sin updates (STALE_MS). Sesiones >5 min desaparecen.
- Inferencia cliente: working sin update ≥45 s → thinking; blocked sin update ≥90 s → awaiting-approval.
- ⇒ El puente debe re-POSTear como heartbeat cada ≤30–45 s, aunque no cambie el estado, para que
"working" no se degrade a "thinking" y "blocked" no se degrade a "awaiting-approval".

Identidad/renombrado: los 8 roles son los personajes. Para que muestren nuestros nombres reales:

http://127.0.0.1:4599/?agents=nexus_core:pm,siscont_backup:ops,pipeline_yt:dev,zephyra_mkt:designer,cyclofun_qa:qa,research_bot:res

(?agents= solo cambia nombres; colores con window.__office_config__ = {agents:{dev:{name,color}}}.)
Verificado: en el screenshot aparecen nexus_core, siscont_backup, pipeline_yt, zephyra_mkt,
research_bot en sus puestos.

Filtrado por project root: el server sella _cwd en cada POST y scanAndMerge descarta sesiones
cuyo _cwd ≠ OFFICE_PROJECT_ROOT. Como el server sella con su propio PROJECT_ROOT, es consistente
mientras no se mezclen escritores externos.


5. Evidencia: screenshots reales

Inyectado el set de 6 agentes, capturado con Playwright/Chromium headless (spike-shot.mjs):

(Capturadas en 1440×900 @2x. El modo panel es el que embebemos en el HQ.)


6. Problemas encontrados

# Problema Impacto Mitigación
P1 Solo 8 roles fijos; no hay agentes arbitrarios Medio Renombrar los 8 roles; si hacen falta >8, correr múltiples sesiones (multi-worktree) o aceptar 8.
P2 thinking no aceptado → coerced a idle Bajo (diseño) Mapear a planning (recomendado). Documentado.
P3 TTL 5 min + inferencias por tiempo Medio Heartbeat del puente cada ≤45 s.
P4 Filtro por _cwd/project root Bajo Servir con OFFICE_PROJECT_ROOT == cwd; el server sella consistente.
P5 Playwright quería Chromium r1234, caché tenía r1228 Solo spike npx playwright install chromium (184 MB) — resuelto. En prod no aplica.
P6 Proyecto de autor único, 24★, "vibe-coding", cambios frecuentes Riesgo mantenimiento Fork propio bajo nuestra cuenta si lo adoptamos.
P7 Bundle JS 500 kB (>aviso 500 kB) Bajo Aceptable; o code-split.

No se encontraron errores de runtime: npm install, npm run build y el server corren limpios
(Node v24.15.0, cumple >=22). 133 archivos *.test.* en el repo (suite grande; no ejecutada en el spike).


7. Esfuerzo de integración estimado

Tarea Esfuerzo
Puente feed→office (leer state.json / WS → POST /api/status, mapeo + heartbeat + renombrado) ~4–6 h
Deploy: build + systemd/PM2 + OFFICE_API_TOKEN + Nginx TLS + servir bajo dominio interno ~4–6 h
Embebido en el HQ (iframe ?mode=panel, o fork para look "Disoftx") ~2–4 h
Pulido (recolor, moods, eventos one-shot de deploys/errores reales) ~2–4 h
Total ~1–2 días

Esqueleto del puente (listo para adaptar)

// bridge.mjs — lee nuestro estado y lo empuja al office
const OFFICE = 'http://127.0.0.1:4599/api/status'
const MAP = { idle:'idle', working:'working', thinking:'planning', error:'blocked' }
// rol por agente (máx 8). Si hay más, agrupar o rotar.
const AGENT_ROLE = { nexus_core:'pm', siscont_backup:'ops', pipeline_yt:'dev',
                     zephyra_mkt:'designer', cyclofun_qa:'qa', research_bot:'res' }

async function push(agents, workflow) {
  const out = agents
    .filter(a => AGENT_ROLE[a.id])
    .map(a => ({ role: AGENT_ROLE[a.id], status: MAP[a.state] || 'idle',
                 label: a.task || '', reasonCode: a.state==='error' ? 'blocked-unknown' : null }))
  await fetch(OFFICE, { method:'POST', headers:{'Content-Type':'application/json'},
    body: JSON.stringify({ type:'office-status', source:'nexus-feed', workflow, agents: out }) })
}
setInterval(() => push(readState(), 'Disoftx HQ — en vivo'), 30_000) // heartbeat ≤45s
// + llamar push() inmediatamente en cada cambio real de estado

8. Veredicto

✅ Sí sirve como base de la Sede Virtual HQ (#2 del research). Cumple todos los requisitos técnicos
(JS/React, SVG, sin GPU, sin backend, MIT) y el contrato de ingesta HTTP es trivial de conectar
(puente de horas, no días de desarrollo). Renuncia a features de gestión (chat/tareas/CI) a cambio de
total control visual, lo cual es exactamente el perfil buscado para "Disoftx HQ".

Único asterisco: el techo de 8 personajes y el mapeo thinking→planning. Si necesitamos más de
8 agentes en pantalla o estrictamente isométrico, reconsiderar #1 (agent-monitor) o #3 (pixel-agents).


9. Siguientes pasos

  1. Decidir #2 vs #1/#3 — este spike valida #2 como plenamente funcional.
  2. Fork propio (disoftx/agent-virtual-office) para blindar el mantenimiento + look HQ.
  3. Implementar bridge.mjs contra nuestro state.json/WebSocket real.
  4. Deploy en el VPS: systemd + OFFICE_API_TOKEN + Nginx/TLS; exponer bajo dominio interno del HQ.
  5. Probar el modo ?mode=panel embebido en el dashboard del HQ.

10. Estado del servidor (dejar limpio)


11. CULMINACIÓN — Sede Virtual en producción interna (2026-09-20)

Estado: ✅ CORRIENDO y estable (systemd de usuario, Restart=always, linger activo).
Alimentado por el estado REAL de nuestros agentes (hq/state.json).

11.1 URL para Daniel (abrir en el navegador)

http://100.96.185.88:4599/?agents=nexus_core:pm,siscont_backup:ops,pipeline_yt:dev,zephyra_mkt:designer,cyclofun_qa:qa,research_bot:res,dx_deploy:gate,shopify_sync:arch

11.2 Servicios (systemd --user, sobreviven a caídas y logout)

Servicio Función Comando
hq-office.service Sirve el office (bind 0.0.0.0:4599) node server.mjs --port=4599 --host --no-open
hq-bridge.service Puente estado real → office node /home/admin/.openclaw/workspace/proyectos/hq-spike-2/bridge.mjs
./run.sh start | stop | restart | status | logs | url | shot
systemctl --user status hq-office hq-bridge
journalctl --user -u hq-office -u hq-bridge -f

11.3 Fuente de estado REAL (verificada viva)

11.4 Mapeo aplicado

Agente → rol (8 fijos) — en bridge.mjs (const ROSTER):

Nuestro agente Rol office
nexus_core pm
siscont_backup ops
pipeline_yt dev
zephyra_mkt designer
cyclofun_qa qa
research_bot res
dx_deploy gate
shopify_sync arch

Estado → estado office: idle→idle · working→working · thinking→planning ·
error→blocked (+reasonCode:blocked-unknown) · done→done. El mood se deriva
(blocked→stuck, working/planning→intense, resto idle).

11.5 Seguridad / exposición

11.6 Caddy (hq.disoftx.solutions) — NO añadido (DNS no listo)

dig hq.disoftx.solutions → 154.38.186.254, que no es este host (nexus sí apunta a
144.91.97.41). Como el DNS del subdominio no resuelve aquí, añadir el bloque provocaría fallos de
ACME sin beneficio ⇒ se dejó la URL de Tailscale como principal. Cuando el DNS apunte a
144.91.97.41, añadir en /etc/caddy/Caddyfile (solo AÑADIR; no se tocó nada existente):

hq.disoftx.solutions {
    bind 144.91.97.41
    tls admin@disoftx.solutions
    handle {
        reverse_proxy localhost:4599
    }
}

y sudo systemctl reload nexus-caddy.

11.7 Verificación realizada

11.8 Cómo cambiar / agregar agentes

11.9 Notas de limpieza


🌐 Subdominio publicado (2026-09-20)


12. Fix 2026-09-23 — la sede se veía "congelada"

Síntoma (Daniel): todos los agentes quietos aunque Nexus estaba trabajando.

Diagnóstico: el HQ no estaba roto (hq-office y hq-bridge activos desde el 20/09). La causa real: la sede solo muestra lo que llega por eventos (hq/emit.py → hq/state.json), y solo el pipeline de YouTube emitía (scripts/yt_es_pipeline.sh, scripts/pipeline_biblical.py). El trabajo del orquestador (cupones Hoseg, DX-Guard) no emitía nada → state.json quedó con el último evento a las 07:00 del 23/09.

Arreglo: nuevo watcher hq/activity_watcher.py + servicio de usuario hq-activity.service (enable --now, Restart=always). Vigila la actividad de las sesiones de OpenClaw (~/.openclaw/agents/**/sessions/*.jsonl) y emite:
- actividad reciente (≤150 s) → nexus_core = working
- sin actividad → nexus_core = idle
Solo emite en los cambios de estado. Gestión: systemctl --user status|restart|stop hq-activity.

Notas / pendientes menores detectados:
- El roster del bridge (ROSTER en bridge.mjs) tiene cyclofun_qa y research_bot (siempre "sin novedades") y no incluye hoseg_pwa (que sí está en state.json). Alinear roster ↔ agentes reales.
- Los estados no expiran solos: el bridge re-empuja el mismo estado cada 25 s → pipeline_yt sigue en planning desde las 07:00. Considerar un timeout de inactividad (si since > X → idle).

🛑 Dado de baja (2026-11-11)