mks-agentics Playbooks E2E

01

Dossier técnico — reversing CCR

Cómo reverseamos el cambio de transporte de --sdk-url (WebSocket → CCR SSE+REST) que tiró el spawn del harness en el binary 2.1.185, y el fix validado end-to-end. La épica completa: el leak original que se volvió columna del proyecto, la evolución del transporte en 3 etapas, y el round-trip PONG sobre el protocolo reverseado desde cero.

★

El transporte fantasma — WS → CCR

leer en tablet

Abrir dossier HTML →
Diagnóstico CERRADO + fix VALIDADO (round-trip PONG)
Causa: 2.1.185 cambió --sdk-url de WebSocket a SSE+REST
Decisión ADR-0004 · bloquea spawn-plane

02

El ecosistema

Cada playbook verifica un camino específico a través de este ecosistema. El diagrama muestra los 5 componentes principales y cómo se interconectan: broker público (bus central), workspace container (ejecución remota), gateway-proxy (multi-provider), gateway-web (UI), y el Mac de waxin (cliente).

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

03

Los 6 playbooks

Cada playbook es autocontenido: tiene su propio diagrama de arquitectura, fases de verificación con criterios de cierre concretos, bloques de comandos copypasteables, árboles Q&A para diagnóstico, y matriz de verificación. Se renderizan a HTML con /dossier — un solo archivo portable.

P0

Prerrequisitos

30 min

Broker público vivo
Workspace container con gateway + a2a-mcp
Credenciales OIDC
Proxy multi-provider
claudio --channels funcional en Mac

UC1

Proxy Session

5 min

cl minimax --proxy → sesión básica
Verificar que el proxy enruta correctamente
Cambio de provider (MiniMax, GLM, DeepSeek)
Virtual keys + autenticación

UC2

Gateway-Web Session

10 min

Abrir gateway-web → conectar al workspace
Crear sesión con provider alternativo
Verificar output en la UI
WS bridge UI ↔ workspace

UC3

Mac Peers Channels

15 min

Dos sesiones cl minimax --proxy --channels
Peer discovery: ListPeers muestra ambos
SendPeerMessage → channel block realtime
Bidireccional sin polling del inbox

UC4

Spawn Peer Local

20 min

Runner daemon en Mac (GATEWAY_MODE=runner)
SpawnPeer desde sesión existente
Nueva sesión aparece en ListPeers
Comunicación post-spawn

UC5

Workspace E2E

30 min

Todo en el workspace container remoto
Sesión con channels via gateway-web
Mac ↔ workspace mensajería realtime
Spawn en workspace + comunicación A↔B↔Mac

Cómo leer los playbooks

Cada .dossier.md se renderiza a un HTML autocontenido con:

Tema dual: modo papel (crema + tinta) y modo noche (oscuro + naranja)
Diagramas D2: con toggle de tema, pan/zoom — mismo SVG renderizado en claro y oscuro
Fases numeradas: F1 → F2 → F3... con criterios de cierre por cada paso
Árboles Q&A: SÍ/NO → ramas de diagnóstico → siguiente paso
Matriz de verificación: 3 tonos (verificado / research / pendiente)

Abrir cualquier .html en el navegador o en la tablet.

04

Orden de ejecución

~30 min

P0 — Prerrequisitos: verificar que todo está vivo

Broker público healthz → 200 OK https://broker.gateway.mks2508.systems/healthz
Workspace container gateway-server health → 200 OK https://lab1-helsinki.api.mks2508.systems/health
a2a-mcp wrapper existe en workspace PATH docker exec <container> which a2a-mcp → /usr/local/bin/a2a-mcp
claudio --channels emite exports sin errores claudio minimax --env --channels → mergea a2a MCP + channels
Proxy público health → 200 OK https://proxy.gateway.mks2508.systems/health

~5 min

UC1 — Sesión básica con proxy

cl minimax --proxy arranca sin errores Claude Code con MiniMax vía proxy
El modelo responde a un prompt simple Verificar que el proxy enruta correctamente

~15 min

UC3 — Dos peers Mac con channels

Dos sesiones cl minimax --proxy --channels se ven mutuamente ListPeers muestra 2 peers
SendPeerMessage → block en la sesión destino Mensajería realtime sin polling
Respuesta bidireccional A↔B Ciclo completo A→B→A confirmado

~20 min

UC4 — Spawn desde sesión Mac

Runner daemon arranca y se conecta al broker GATEWAY_MODE=runner → runner online
SpawnPeer → nueva sesión aparece en ListPeers Spawn-plane local funciona
StopPeer → sesión spawneada se detiene Lifecycle completo spawn→communicate→stop

~30 min

UC5 — Workspace E2E (VICTORIA)

Sesión en workspace con channels via gateway-web POST /api/sessions {channels:true} → 200
Mac ve el peer del workspace en ListPeers Peer discovery cross-machine
Mac ↔ workspace: mensajes realtime vía channel-push block en ambas direcciones
Workspace spawn + comunicación A↔B↔Mac Ciclo completo con 3+ peers

05

Estado actual

Infraestructura3/5 checks

Broker público vivo https://broker.gateway.mks2508.systems/healthz → 200
Workspace container corriendo https://lab1-helsinki.api.mks2508.systems/health → 200
Proxy público vivo https://proxy.gateway.mks2508.systems/health → 200
a2a-mcp en workspace Pendiente verificación post-boot
Runner daemon en Mac No configurado como servicio permanente

Playbooks0/6 ejecutados

P0 — Prerrequisitos ⏳ pendiente
UC1 — Proxy session ⏳ pendiente
UC2 — Gateway-web session ⏳ pendiente
UC3 — Mac peers channels ⏳ pendiente
UC4 — Spawn peer local ⏳ pendiente (requiere runner daemon)
UC5 — Workspace E2E ⏳ pendiente (requiere UC3+UC4)

Bloqueantes2 issues

CI mks-workspaces roto Symlink mesh-drop huérfano en Dockerfile.unified:649. Fix en curso (handoff enviado).
Runner daemon no configurado Necesario para UC4. No bloquea UC1/UC2/UC3.

06

Playbooks individuales

Índice de playbooks — click en el HTML para abrir
#	Playbook	HTML	Esfuerzo	Depende de	Estado
P0	PREREQUISITES	Abrir HTML	30 min	nada	⏳
UC1	Proxy Provider	Abrir HTML	5 min	P0	⏳
UC2	Gateway-Web Session	Abrir HTML	10 min	P0	⏳
UC3	Mac Peers Channels	Abrir HTML	15 min	P0 + UC1	⏳
UC4	Spawn Peer Local	Abrir HTML	20 min	P0 + UC3	⏳
UC5	Workspace E2E	Abrir HTML	30 min	P0 + UC3 + UC4	⏳

07

Arquitectura de componentes

1

Gateway Broker — Bus centralbroker.gateway.mks2508.systems · OIDC · SQLite · WS + REST

prod vivo

API REST + WebSocket

/api/peers · /api/teams · /api/spawn · /api/runners · /ws/runner/:id · /ws/broker/peer/:id

AuthOIDC JWT · BROKER_ALLOWED_CLIENTS

client_credentials grant
Per-client allowlist

Peersregister · unregister · message · inbox

SQLite persistence
GC dead operators 60s

Spawnspawn_order → runner → peer_registered

Runner registry in-memory
GC stale runners 120s

ChannelsWS /ws/broker/peer/:id realtime push

Server-initiated notifications
Per-peer filtered event stream

https://broker.gateway.mks2508.systems/healthz

Workloads → MCP tools (13 operaciones)Channel-push realtimeSpawn-plane routing

2

Workspace Container — Ejecución remotalab1-helsinki.api.mks2508.systems · Coolify · Docker

configurado

Container Docker con supervisord

entrypoint.sh → 17 setup functions → supervisord (gateway + codeserver + sshd + desktop)

Gatewaypull-on-startup desde GitHub Releases

gateway-server.js bundle
update-gateway.sh baked
autorestart=true

a2a-mcppull-on-startup + wrapper en PATH

a2a-mcp.js bundle
/usr/local/bin/a2a-mcp
Channel-push WS al broker

Claude Codebaked en imagen · multi-provider

API keys inyectadas vía env
Per-session CONFIG_DIR isolation

https://lab1-helsinki.api.mks2508.systems/health

Workloads → Sesiones Claude Code via gateway-webSpawn de peers secundariosChannel-push al broker

3

Gateway Proxy — Multi-providerproxy.gateway.mks2508.systems · GLM · MiniMax · DeepSeek

prod vivo

Proxy HTTP multi-provider con virtual keys

Data-plane /v1/messages + Control-plane /v1/keys · /v1/usage · /auth/*

ProvidersGLM (z.ai) · MiniMax · DeepSeek

anthropic-native protocol
Routing por model name + prefix

AuthVirtual keys sk-mks-* + OIDC admin

SHA-256 hash storage
Atomic writes chmod 600

Usagetracking tokens · quotas · rate limiting

Ventanas de 5h en usage.json
Provider quota endpoints

https://proxy.gateway.mks2508.systems/health

Workloads → Tier-1 (usuarios auth)Tier-2 (público con rate limit)

4

Claudio — Orchestrador de sesiones~/dotfiles/claude-model/ · modes + --proxy + --channels

funcional

Binary TypeScript que gestiona modos de Claude Code

cl <mode> --proxy --channels → CLAUDE_CONFIG_DIR isolation + a2a MCP merge + channel push

Modesnormal (OAuth) · glm · minimax · deepseek

Per-provider CONFIG_DIR (~/.claude-/)
Symlinks compartidos (skills/plugins/agents)

ProxyANTHROPIC_BASE_URL override

Local: 127.0.0.1:3200 (cl proxy)
Remoto VPN: configurable (claudio --proxy)

Channelsmerge a2a MCP + dangerouslyLoadDevelopmentChannels

Pin tengu_harbor=true (privacy gate)
A2A_CHANNEL_PUSH=1 en MCP env

file:///Users/mks/dotfiles/claude-model/src/index.ts

Workloads → Sesiones multi-providerChannel-push al brokerPer-provider isolation

08

Roadmap 0.18

Fase 0.18 — Broker reliability + flip público + spawn-plane
Sub-fase	Qué	Playbook	Estado
0.18.A	Proxy público (fail-closed)	UC1	✅ DONE
0.18.B	Usage tracking Tier-1/2	UC1	✅ DONE
0.18.C	UI dashboard	—	⏳ queued
0.18.D	Broker flip público + P0 fixes	UC3	🔵 EN CURSO
0.18.E	OIDC client_credentials + a2a MCP settings + claudio spawnViaBroker	UC3	✅ DONE
0.18.F	G1 GitHub Release + G2 OIDC creds workspace + G3 env vars + claudio --channels broker	UC5	✅ DONE

Q1

¿Está el ecosistema listo para ejecutar los playbooks? entrada

Verificar P0 (prerrequisitos) primero

P0 verde → continuar Ejecutar UC1 → UC3 → UC4 → UC5 en orden. Cada playbook indica cuándo parar si algo falla.

P0 falla → arreglar Revisar: (1) health del broker, (2) health del workspace, (3) a2a-mcp en workspace PATH, (4) claudio --channels funcional, (5) credenciales OIDC.

Q2

¿Hay runner daemon en Mac para UC4? spawn

UC4 requiere GATEWAY_MODE=runner corriendo en Mac

Sí — runner corriendo Proceder con UC4 tras UC3 verde.

No — UC4 bloqueado Arrancar runner manualmente (ver UC4 F1). O saltar a UC5 si el workspace gateway-server actúa como runner para spawns internos.

Q3

¿CI mks-workspaces está verde? infra

La imagen Docker del workspace necesita rebuild para incluir update-a2a-mcp.sh

Sí — imagen actualizada Workspace container tiene a2a-mcp out of the box.

No — CI roto Fix en curso (handoff enviado). La imagen actual ya tiene update-a2a-mcp.sh baked del último build verde (commit b0acfb7).

Playbooks

Docs relacionados

Dossier CCR transport (reversing WS→CCR)dossier
ROADMAP.mdindex
progress-log.mdlog
broker-prod-sprint-statestate
spawn-plane-designspec

Código clave

Próximo paso

Ejecutar P0 — verificar que el ecosistema base está vivo:

# 1. Broker
curl -s https://broker.gateway.mks2508.systems/healthz

# 2. Workspace
curl -s https://lab1-helsinki.api.mks2508.systems/health

# 3. Proxy
curl -s https://proxy.gateway.mks2508.systems/health

# 4. claudio
claudio minimax --env --channels 2>&1 | head -5

Si todo verde → UC1 (cl minimax --proxy). Si algo falla → abrir PREREQUISITES.html para diagnóstico.