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):
- 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. thinkingNO 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 aidle(verificado). "Thinking" solo existe como estado inferido en el cliente
(workingsin 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_DIRredirige el directorio de estado (default~/.claude/) → así NO tocamos
~/.claudede la máquina.OFFICE_PROJECT_ROOTdebe coincidir con elcwddesde 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):
screenshots/office-main.png— vista completa. Se ven la escena, el banner de workflow
("Disoftx HQ — operaciones en vivo"), 6 personajes (algunos extra de ambiente/rol), anillos de
color por estado, el agenteresearch_boten rojo con reloj de arena y la barra inferior
"⚠️ Needs your attention: research_bot", más un roster con las tareas.screenshots/office-panel.png— mismo feed en modo?mode=panel.
(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
- Decidir #2 vs #1/#3 — este spike valida #2 como plenamente funcional.
- Fork propio (
disoftx/agent-virtual-office) para blindar el mantenimiento + look HQ. - Implementar
bridge.mjscontra nuestrostate.json/WebSocket real. - Deploy en el VPS:
systemd+OFFICE_API_TOKEN+ Nginx/TLS; exponer bajo dominio interno del HQ. - Probar el modo
?mode=panelembebido en el dashboard del HQ.
10. Estado del servidor (dejar limpio)
- Corriendo:
node server.mjs --port=4599 --no-open· PID 679690 (server.pid) · bind127.0.0.1:4599 - Datos de prueba:
status/office-status.json(6 agentes, workflow "Disoftx HQ — operaciones en vivo") - Log:
logs/server.log - Parar:
./run.sh stop(okill $(cat server.pid)) - Arrancar:
./run.sh start - No se tocó
~/.claudeni ningún archivo fuera deproyectos/hq-spike-2/ywiki/proyectos/hq-spike-2.md.
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
- Modo panel (embebible): añadir
&mode=panela la URL. - ⚠️ El
?agents=...es el que renombra los 8 roles fijos con NUESTROS nombres. Sin ese query
verás los nombres por defecto (Architect, Gatekeeper, etc.). 100.96.185.88= IP Tailscale de este host (Omni). Alcanzable solo por la tailnet.
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)
- Primaria:
/home/admin/.openclaw/workspace/hq/state.json(lo escribenhq/emit.pyy
hq/tracker_daemon.py). Actualmente 7 agentes;pipeline_ytenthinking. - Fallback: endpoint Cerebro
http://127.0.0.1:8000/hq-state(Flaskcerebro/app.py). - Cadencia del puente: poll cada 5 s (POST inmediato al detectar cambio real) + heartbeat
cada 25 s (evita el TTL de 5 min y la degradaciónworking→thinkinga 45 s).
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
- Office escucha en
0.0.0.0:4599, pero ufw solo permitetailscale0(+ 443/80/3007);
el puerto 4599 NO se expone a Internet (default-deny eneth0). - Escrituras (
POST /api/status) protegidas conOFFICE_API_TOKEN(office.env, chmod 600).
Las lecturas (navegador/GET) no requieren token.
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
GET /→ 200;GET /api/health→{"ok":true,...};GET /api/statusrefleja nuestros 8
agentes (p.ej.dev=planning←pipeline_ytthinking).- Prueba de reactividad con estado sintético: el puente mapeó
error→blocked,thinking→planning,
working→workingy el office lo reflejó (auto-recuperado en el siguiente heartbeat). - Nombres reales confirmados en el DOM (8/8) y en screenshot.
- Screenshot (estado real):
proyectos/hq-spike-2/screenshots/office-main.png(yoffice-panel.png).
11.8 Cómo cambiar / agregar agentes
- Editar la const
ROSTERenproyectos/hq-spike-2/bridge.mjs({agent, role, task}) y
./run.sh restart(osystemctl --user restart hq-bridge). - Sincronizar el
?agents=de la URL con los mismos nombres (el orden esNombre:rol). - Máximo 8 roles/agentes simultáneos (límite del office). Si un agente no está en
state.json,
aparece enidlecon "sin novedades".
11.9 Notas de limpieza
- Eliminados
server.pid/logs/server.piddel arranque manual previo (ya gestionado por systemd). - No se tocaron otros servicios ni configs (
~/.claude, Caddy existente, Cerebro intactos).
🌐 Subdominio publicado (2026-09-20)
- URL:
https://hq.disoftx.solutions/?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 - Restricción: SOLO red privada Tailscale (patrón idéntico a
facturas.disoftx.solutions). client_ip 100.64.0.0/10 172.18.0.1→ permite tailnet; resto → 403 ("Acceso restringido a la red privada (Tailscale)").- Infra: DNS
hq.disoftx.solutions→ 154.38.186.254 (Zeta). Bloque Caddy en Zeta/home/opsmgr/proyectos/caddy/sites/hq.caddy→reverse_proxy 100.96.185.88:4599(Omni, por Tailscale). - Certificado: Let's Encrypt emitido 2026-09-20 21:23 UTC (vence 2026-12-19).
- Verificado: público → 403 · tailnet (
--resolve ...:443:100.83.7.25) → 200. - Fallback directo (siempre funciona en Tailscale):
http://100.96.185.88:4599/
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)
- Decisión de Daniel: cancelar HQ. El valor era "ver a los agentes trabajar", ya cubierto por el panel y los reportes; el diseño base (8 personajes fijos, SVG mínimo) se veía pobre.
- Servicios detenidos y deshabilitados:
hq-office.service,hq-bridge.service,hq-activity.service(systemd de usuario). Puerto 4599 cerrado. - Vhost eliminado:
hq.disoftx.solutions(respaldohq.caddy.bak_20261111en el contenedorcaddy_proxy). El dominio ya no responde. - Código archivado: repo privado https://github.com/dannyelito/hq-disoftx (bridge, run.sh, src, screenshots y README con el motivo).
- Si se retoma: usar WorkAdventure, no este prototipo.