Playbook UC5 Workspace E2E

01

Objetivo final

El playbook de victoria. Todo el ecosistema a2a funcionando en el workspace container remoto: gateway-web conectado al workspace, sesión con channels, spawn de una segunda sesión desde el workspace, mensajería bidireccional realtime entre peers remotos y el Mac de waxin. Si este playbook pasa, la fase 0.18 está completa.

drag to pan · scroll to zoom · double-click to fit

02

El flow completo

1

Mac → gateway-web

browser

Abrir gateway-web en el navegador
Conectar al workspace remoto
Seleccionar provider + channels ON

2

Workspace → Sesión A

cli-launcher

POST /api/sessions {channels:true}
cliLauncher.launch() → Bun.spawn(claude)
a2a-mcp config → peer registrado en broker

3

Sesión A → Channels

channel-push

dangerouslyLoadDevelopmentChannels
WS /ws/broker/peer/:id
Listo para recibir mensajes realtime

4

Mac → ListPeers

discovery

Sesión Claude en Mac con channels
ListPeers muestra peer del workspace
Verificación: el workspace es visible

5

Mac ↔ Workspace

bidireccional

SendPeerMessage Mac → workspace
Channel block en workspace (realtime)
Respuesta workspace → Mac
Channel block en Mac (realtime)

6

Workspace spawn

spawn-plane

Sesión A spawnea Sesión B
Runner integrado en gateway-server
B aparece en ListPeers
Comunicación A↔B↔Mac

03

F1 — Preparación del workspace

5 min

Verificar que el workspace está listo

curl -s https://lab1-helsinki.api.mks2508.systems/health → 200 OK Gateway-server del workspace responde
curl -s https://broker.gateway.mks2508.systems/healthz → 200 OK Broker público responde
SSH al workspace: which a2a-mcp → /usr/local/bin/a2a-mcp a2a-mcp wrapper existe
SSH al workspace: env | grep GATEWAY_BROKER_URL → broker público Env var configurada
SSH al workspace: env | grep OIDC_CLIENT_ID → valor presente Credenciales OIDC inyectadas
SSH al workspace: supervisorctl status gateway → RUNNING Servicio gateway corriendo

04

F2 — Crear sesión A en workspace {#f2-sessionA}

5 min

Crear sesión con channels desde gateway-web

Abrir gateway-web → Remote slot → https://lab1-helsinki.api.mks2508.systems Conectado al workspace remoto
Provider: MiniMax, Channels: ON La sesión se crea con channels activos
Click 'New Session' → sesión creada con estado 'running' POST /api/sessions 200 + WS bridge activo
Enviar 'di hola' en el chat → respuesta del modelo La sesión funciona normalmente
SSH al workspace: ps aux | grep claude → proceso corriendo El CLI de Claude está vivo dentro del container

POST /api/sessions con channels

Crear sesión con channels en el workspace

# Desde gateway-web o vía curl:
$ curl -s -X POST https://lab1-helsinki.api.mks2508.systems/api/sessions \
    -H "Content-Type: application/json" \
    -d '{
      "providerMode": "minimax",
      "cwd": "/workspace",
      "channels": true
    }' | jq .
→ {
→   "session": {
→     "sessionId": "ws-a-abc123...",
→     "state": "running",
→     "model": "claude-sonnet-4-20250514",
→     "channels": true
→   }
→ }

# Verificar en el workspace:
$ ssh developer@lab1-helsinki.api.mks2508.systems
$ cat ~/.mks-harness/sessions/ws-a-abc123/.claude.json | jq '.mcpServers'
→ {
→   "agent2agent": {
→     "command": "a2a-mcp",
→     "env": {
→       "GATEWAY_BASE_URL": "https://broker.gateway.mks2508.systems",
→       "A2A_PEER_ID": "ws-a-abc123...",
→       "A2A_CHANNEL_PUSH": "1"
→     }
→   }
→ }

05

F3 — Conectar Mac al ecosistema

5 min

Arrancar sesión Claude en Mac con channels

En Mac: cl minimax --proxy --channels Claude Code en Mac con channels apuntando al broker público
ListPeers → muestra peer del Mac + peer del workspace (sesión A) Ambos peers visibles desde el Mac
GetPeer ws-a-abc123... → card de la sesión A en el workspace El Mac puede ver el peer del workspace

06

F4 — Mensajería Mac ↔ Workspace

5 min

Mensaje bidireccional realtime

En Mac: SendPeerMessage to=ws-a-abc123... content='hola desde Mac' Mensaje enviado al peer en el workspace
En gateway-web (sesión A): aparece <channel> block con 'hola desde Mac' El mensaje llegó en tiempo real al workspace
En gateway-web: responder 'hola desde workspace, recibido!' La sesión A responde al Mac
En Mac: aparece <channel> block con la respuesta del workspace Bidireccional confirmado — Mac ↔ Workspace realtime

Verificación del channel block en gateway-web

gateway-web — salida esperada

# En el chat de gateway-web, después de que Mac envía un mensaje:

<channel source="agent2agent" from_id="mac-peer-xyz..."
         kind="request" priority="normal">
hola desde Mac
</channel>

# La sesión A en el workspace puede responder:
> SendPeerMessage to=mac-peer-xyz... content="hola desde workspace, recibido!"

# Y en el Mac, Claude Code muestra:
<channel source="agent2agent" from_id="ws-a-abc123..."
         kind="request" priority="normal">
hola desde workspace, recibido!
</channel>

07

F5 — Spawn en workspace

5 min

Spawn de segunda sesión desde el workspace

En sesión A (workspace): SpawnPeer name='ws-session-B' provider='minimax' host='lab1-helsinki' Spawn de una segunda sesión gestionada por el gateway-server del workspace
ListPeers → 4+ peers (Mac, sesión A, sesión B, gateway-server como runner) La sesión B aparece registrada en el broker
En Mac: SendPeerMessage to=<peerId-B> content='hola a la spawneada' El Mac puede enviar mensajes a la sesión spawneada
En sesión A (workspace): SendPeerMessage to=<peerId-B> content='hola desde A' La sesión A también puede comunicarse con la spawneada

Spawn en workspace vs spawn en Mac

En el workspace, el gateway-server en modo server (no runner) actúa como runner implícito para spawns internos. Cuando el broker recibe un POST /api/spawn con host='lab1-helsinki', enruta el spawn_order al gateway-server del workspace (que está registrado como runner en el broker).

Esto es diferente a UC4 (runner independiente en Mac). Aquí el gateway-server del workspace es tanto servidor de sesiones como runner de spawns — unifica ambos roles en el mismo proceso.

Si el gateway-server del workspace NO está registrado como runner en el broker, el spawn fallará con RUNNER_OFFLINE. Hay que verificar que el gateway-server del workspace se registra como runner al iniciar (el código en runner.ts vs server.ts — verificar cuál entrypoint se usa en el workspace).

08

F6 — Verificación final

5 min

E2E completo — todos los caminos

Mac ↔ Workspace A: mensajes bidireccionales realtime Channel-push entre Mac y workspace
Workspace A ↔ Workspace B: mensajes bidireccionales Channel-push entre sesiones en el mismo workspace
Mac ↔ Workspace B: mensajes bidireccionales Channel-push entre Mac y sesión spawneada
ListPeers desde cualquier peer muestra todos los peers (4+) Peer discovery completo
CheckInbox de cada peer → mensajes también en inbox (durable) Los mensajes se persisten en el inbox del broker (SQLite)
StopPeer de la sesión B → peer removido Lifecycle completo: spawn → communicate → stop

Verificación de logs en el workspace

SSH al workspace — verificar logs

$ ssh developer@lab1-helsinki.api.mks2508.systems

# Log del gateway-server (cli-launcher):
$ tail -50 /var/log/supervisor/gateway.log
→ Spawning CLI for session ws-a-abc123...
→ Peer registered with remote broker: ws-a-abc123 (depth=1)
→ Spawning CLI for session ws-b-def456...
→ Peer registered with remote broker: ws-b-def456 (depth=1)

# Procesos Claude Code corriendo:
$ ps aux | grep claude
→ developer  1234  ...  claude --sdk-url http://127.0.0.1:4105/ws/cli/ws-a-abc123 ...
→ developer  5678  ...  claude --sdk-url http://127.0.0.1:4105/ws/cli/ws-b-def456 ...

# Directorios de sesión:
$ ls ~/.mks-harness/sessions/
→ ws-a-abc123/  ws-b-def456/

09

Veredicto

Condiciones de victoria6 checks

Sesión en workspace con channels creada desde gateway-web UI → workspace → sesión → output
Mac ve el peer del workspace vía ListPeers Peer discovery cross-machine
Mac ↔ Workspace: mensajes realtime vía channel-push Channel-push cross-machine funciona
Workspace A ↔ Workspace B: mensajes realtime Channel-push intra-workspace funciona
Spawn de segunda sesión desde el workspace Spawn-plane en workspace remoto funciona
Ciclo completo Mac ↔ A ↔ B con mensajería realtime Ecosistema a2a completo y verificado

Puede fallar (esperable)3 checks

Channel-push cross-machine tiene latencia >5s Posible reconnect del WS en el workspace
El workspace no aparece como runner en /api/runners El gateway-server del workspace no está en modo runner
Los mensajes solo se entregan por inbox (no channel-push) WS channel-push caído en algún peer

Si falla → regresión2 checks

El workspace no registra peers en el broker a2a-mcp no funcional, GATEWAY_BROKER_URL mal configurada
Mac no ve ningún peer del workspace Broker no accesible desde ambos, o credenciales OIDC incorrectas

Q1

¿Aparece el peer del workspace en ListPeers del Mac? discovery

Desde el Mac, ejecutar ListPeers después de crear la sesión en el workspace

Sí → peer del workspace visible Continuar a F4 (mensajería). Peer discovery cross-machine funciona.

No → no se ve Revisar: (1) ¿está a2a-mcp funcionando en el workspace? (2) ¿GATEWAY_BROKER_URL apunta al mismo broker que el Mac? (3) ¿el peer se registró? Ver logs del gateway-server.

Q2

¿Llega el mensaje del Mac al workspace en tiempo real? channel-push

SendPeerMessage de Mac a workspace → verificar gateway-web

Sí → <channel> block en gateway-web Channel-push cross-machine funciona. Continuar a F5 (spawn).

No → no aparece Primero verificar que el mensaje está en el inbox (CheckInbox). Si está en inbox pero no en channel, el WS channel-push del workspace está caído. Si no está ni en inbox, el broker no enrutó el mensaje.

Q3

¿Funciona el spawn de segunda sesión en el workspace? spawn-plane

SpawnPeer desde sesión A del workspace → ¿peer B aparece?

Sí → peer B visible + responde VICTORIA. El ecosistema a2a está completo. UC5 VERDE. Fase 0.18 cerrada.

No → spawn falla o no se ve Revisar si el gateway-server del workspace está registrado como runner en el broker. Puede que necesite modo runner explícito o que el spawn interno no esté implementado aún.

Si UC5 pasa → 0.18 DONE

UC5 es el criterio de cierre definitivo para la fase 0.18 (broker reliability + flip público + spawn-plane).

Con UC5 verde:

0.18.E (MCP OIDC + settings) → ✅ verificado
0.18.F (workspace a2a E2E) → ✅ verificado
0.18.D (broker flip público) → ✅ verificado (el broker público es el bus central)
0.18.C (proxy UI dashboard) → pendiente (no bloquea)

Siguiente fase: 0.19 — polish + test harness automatizado basado en estos playbooks.

Playbooks relacionados

Código y diseño

cli-launcher.service.tssource
spawn-plane-design-2026-06-20.mdspec
broker-prod-sprint-state-2026-06-20.mdstate
entrypoint.shsource