dsh-helm

Plano de control multipunto DSH: convierte el conector local «ChatGPT ↔ DSH» en un plano de control multipunto. Los DeepSeek Harness (DSH) de varias máquinas se registran en un hub unificado a través de agentes de nodo (node-agent), y ChatGPT puede enrutar a cualquier nodo desde una única entrada: leer y escribir código, gestionar sesiones, consultar el estado, sin exponer ningún nodo a la red pública.

ChatGPT Web（连接器/插件）
   │ OpenAI Secure MCP Tunnel（tunnel-client，TLS）
   ▼
Hub 控制平面     MCP 127.0.0.1:3471（ChatGPT 入口）    mesh <hub-ip>:3470（节点接入）
   │ 路由：显式 target → session owner → workspace owner → presence → default
   ├──────────────┬──────────────┬──────────────┐
   ▼              ▼              ▼              ▼
node-agent    node-agent    node-agent    node-agent   （每台机器：出站 WS + HMAC 握手）
   │              │              │              │
   ▼              ▼              ▼              ▼
daemon 3457 → DSH   daemon 3457 → DSH   ……      （各节点本地 helm daemon，Bearer 鉴权）

• Cada nodo ejecuta dsh-helm agent: solo conexión saliente al hub (mesh WS), y hacia dentro hace de puente con el MCP del daemon helm local (127.0.0.1:3457/mcp).

• El hub es la única entrada: ChatGPT invoca las herramientas a través del MCP del hub (3471), y el hub reenvía al nodo correcto según la política de enrutamiento; el número de nodos es transparente para ChatGPT.

• Compatibilidad mononodo: con un solo nodo y node_id == hub defaultNodeId, el enrutamiento y el comportamiento de invocación de herramientas equivalen a los del daemon mononodo (resumen/guard/steer son mejoras de capa superior y no alteran la semántica de invocación existente).

Características

• Registro y heartbeat multipunto: identidad de nodo node_id (UUID) + handshake de desafío HMAC; heartbeat de 15 s, arrendamiento de 45 s; en la nueva versión del agente, el heartbeat con timeout se reconecta automáticamente (detección de conexión semiactiva y reconexión).

• Enrutamiento de cinco niveles: target_node explícito → session owner → workspace owner → presence sin ambigüedad → defaultNodeId como respaldo; si el destino de una operación destructiva/de escritura no está claro, se rechaza con fail-closed (route_confirmation_required), nunca se adivina.

• Reenvío trazable: cada resultado de reenvío incluye _route.node_name (display_name) indicando el nodo de ejecución; route_explain es un ensayo que no ejecuta.

• Superficie de herramientas MCP 19+5: las 19 herramientas del daemon mononodo (code_*/sessions_*/projects_list/supervisor_health, etc., con parámetros snake_case sin cambios) se conservan tal cual, y se añaden nodes_list/node_get/route_explain/presence_claim/presence_release; todas las herramientas enrutables admiten target_node opcional.

• presence: declaración manual (pin de 10 minutos) + detección automática de la aplicación en primer plano en macOS (sidecar de escritorio); si dos nodos tienen alta confianza dentro de la ventana de ambigüedad de 15 s → se marca ambiguous, sin selección automática.

• Estado por capas: control / channel / adapter / datapath / serena / tunnel se reportan de forma independiente por capa, nunca se colapsan en un único status: ok.

• Agregación entre nodos: workspaces_list/sessions_list/agents_list/projects_list devuelven resultados planos de varios nodos (cada uno con node_id).

• Registros de auditoría y enrutamiento: registro de nodos, heartbeat, decisiones de enrutamiento y cambios de presence se persisten todos (audit/route_log).

• Línea roja de metadatos: el almacenamiento del hub solo contiene metadatos (nodos/arrendamientos/directorios de sesiones y workspaces/auditoría) y nunca almacena el contenido de las sesiones de DSH.

Related MCP server: Peta Core

Estructura de directorios

dsh-helm/
├── packages/
│   ├── protocol/    # wire 协议：envelope、JSON-RPC、HMAC 握手、常量
│   ├── store/       # SQLite：节点注册表、presence、目录、审计
│   ├── hub/         # 控制面：Router、WS mesh 3470、MCP 3471
│   ├── node-agent/  # 节点代理：出站 WS、重连、本地 DSH 桥
│   ├── presence/    # presence providers（手动/macOS/浏览器）
│   ├── platform/    # 跨平台适配（launchd/systemd/Windows 模板）
│   └── cli/         # dsh-helm CLI（init/agent/hub/status/nodes/…）
├── tests/integration/  # 双 fake node 端到端测试
└── scripts/            # ops 脚本（bash，macOS 优先）

Inicio rápido

Requisitos previos: Node.js >= 22.5, pnpm, curl; en cada máquina nodo hay que tener instalados DSH y el daemon helm (127.0.0.1:3457/mcp, token Bearer en ~/.agent-chatgpt-helm/token).

# 1. 安装 CLI（构建 + 写 ~/.local/bin/{dsh-helm,dsh-helm-agent,dsh-helm-hub}，幂等）
./scripts/install.sh

# 2. 初始化节点身份（生成 ~/.dsh/helm/node.json，权限 0600）
dsh-helm init

# 3. 编辑 ~/.dsh/helm/node.json：设置 hub_url 与 local_mcp_token
#    hub_url：内网/Tailscale 用 ws://<hub-ip>:3470，生产用 wss://

# 4. hub 机器：启动控制面（mesh 3470 + MCP 3471；默认只绑 127.0.0.1）
dsh-helm hub
#    多机场景：dsh-helm hub --bind <tailnet-ip> --mcp-bind 127.0.0.1

# 5. 节点机器：启动 agent（先前台验证，再装自启服务）
dsh-helm agent
./scripts/install-service.sh        # macOS：launchd 服务（com.dsh-helm.node-agent）

# 6. 自检与状态
./scripts/verify.sh                 # 0 全绿 / 1 警告 / 2 严重
./scripts/health.sh                 # 节点状态表（走 hub MCP supervisor_health）
dsh-helm status                    # 本地配置与连接状态

Añadir más nodos: tras dsh-helm init en la nueva máquina nodo, entrega node_id y token de node.json al administrador del hub por un canal seguro y ejecuta en la máquina del hub (idempotente: añade/actualiza la tabla de tokens y recarga automáticamente el servicio launchd):

./scripts/register-node.sh <node_id> <token>

El proceso detallado está en docs/onboarding.md.

Conexión con ChatGPT

Dos rutas, según la fase de despliegue:

• A. Conexión directa mononodo (para empezar): si la máquina local ya tiene el daemon helm, el hub trata el nodo local como nodo local, con el mismo comportamiento que el conector mononodo, sin necesidad de túnel.

• B. Multinodo (plano de control, recomendado): túnel MCP seguro de OpenAI conectado al MCP del hub (3471); ChatGPT gestiona todos los nodos desde una única entrada.

El tutorial completo en OpenAI Platform (crear túnel / vincular workspace / crear API key / parámetros de tunnel-client / proxy) está en docs/chatgpt-tunnel-setup.md; el lado web de ChatGPT (modo desarrollador / crear conector / pruebas) está en docs/chatgpt-connector.md.

Compensación entre las dos topologías: cada daemon con su propio túnel y conector (múltiples entradas, cada una gestiona lo suyo), o un túnel de hub + un conector que gestiona N nodos (entrada única, recomendado: el hub enruta con target_node/reglas de enrutamiento y la respuesta incluye node_name).

HA del plano de control (doble plano de control)

Dos hubs forman un quórum (2/2) de plano de control; si uno falla, el otro sigue sirviendo el enrutamiento de lectura y la entrada de nodos.

• Roles y arrendamiento: gana el de menor --cp-priority como líder (único escritor); el líder renueva el arrendamiento con el peer cada 10 s; si el peer pierde contacto más allá del TTL del arrendamiento (--cp-failover-ms, 45 s por defecto) → ambos entran en read-only-no-quorum y las operaciones de escritura devuelven QUORUM_LOST. El follower nunca se promueve unilateralmente: sin quórum, solo lectura, sin escritura (CAP prioriza la seguridad).

• Recuperación: reconexión del peer → sincronización completa del registro → reelección forzada (term+1) → confirmación del arrendamiento por ambas partes → recuperación de escritura. Durante toda la ventana de recuperación, ambas partes permanecen en solo lectura.

• Múltiples endpoints del agente: node.json configura hub_url + fallback_urls; al reconectar se prueban en rotación y se fija el que funciona; ante un fallo se cambia automáticamente al segundo CP.

• Observabilidad: GET /cp-status devuelve role/phase/writeMode/quorum/term/leaderId/peers/syncOk/leaseEpoch/failoverCount; dsh-helm doctor y la tarjeta «HA del plano de control» del Dashboard lo muestran directamente.

• HA de la entrada de ChatGPT: --mcp.server-url de OpenAI tunnel-client está limitado por canal y no tiene failover multibackend en el mismo conector. Localmente se levanta dsh-helm ha-proxy (por defecto 127.0.0.1:3481, --primary http://127.0.0.1:3471 --secondary http://<peer-cp>:3471); el túnel sigue apuntando a un conector (3481); si el CP principal pierde contacto, cambia automáticamente al CP secundario y vuelve al recuperarse. Doble túnel + doble conector es la topología alternativa.

• Despliegue del segundo CP: dsh-helm hub --cp-peer ws://<peer-cp>:3470 --cp-priority 1 --cp-id <node-id> --cp-token-env DSH_HELM_CP_TOKEN; en ambos lados, DSH_HELM_TOKEN debe contener la tabla de tokens de ambos nodos (para que el otro CP pueda autenticar a cualquier agente en un failover). Si el MCP debe ser accesible entre máquinas, usa --mcp-bind <tailnet-ip> (perímetro ACL de Tailscale; en escenario mononodo, mantén loopback).

Emparejamiento de dispositivos (añadir dispositivo DSH)

Dashboard «Añadir dispositivo DSH» → genera un código de emparejamiento de un solo uso (válido 10 minutos, consumo único, solo se guarda el hash); la máquina nueva ejecuta dsh-helm join --control-plane ws://<hub>:3470 --code <code> para entrar en la red (genera un token de nodo de larga duración escrito en ~/.dsh/helm/node.json; el hub solo guarda hash/estado). La API de emparejamiento solo admite loopback + cabecera anti-CSRF; los registros solo guardan el prefijo del hash. Ver docs/security.md §5.

Aislamiento de contexto MCP (estabilidad con contextos grandes)

Reducción de respuesta y monitorización del conector ChatGPT ↔ DSH en sesiones de larga duración y contexto grande (capa de compatibilidad, la cadena no cambia):

• Resumen por defecto en sessions_get: por defecto solo devuelve un resumen estructurado (id/title/status/workspace/created_at/updated_at/last_message_summary/last_assistant_summary/current_goal/current_goal_seq/last_user_message/recent_evidence{commits,paths,errors,tests}/history_ref/safety_sanitized/token_estimate/continuation_available, sin messages). El resumen lo genera el agente de nodo: solo pide a DSH los últimos 20 mensajes (SUMMARY_WINDOW); current_goal toma la instrucción de usuario con mayor acción dentro de la ventana (con seq de origen); recent_evidence se extrae con heurística de expresiones regulares; las líneas con posible credencial se eliminan antes de entrar en cualquier campo del resumen (marcado safety_sanitized). Línea base medida: respuesta de sesión grande temprana de 75 KB → 1,2 KB; fixture de aceptación de fidelidad de información (1000 mensajes) de ~107 KB → 0,7 KB, respuesta por defecto <1 KB. Caché en ~/.dsh/helm/summaries/<session_id>.json (TTL de 60 s, se invalida tras operaciones de escritura).

• Historial completo bajo demanda: include_messages=true (con max_messages configurable, 20 por defecto) devuelve los mensajes completos; el parámetro before_seq se pasa tal cual, pero DSH 0.1.1 no implementa paginación real (medido en pruebas: max_messages ≤100 y beforeSeq no tiene efecto): el historial más allá de los últimos 100 mensajes no es accesible actualmente, y history_ref marca explícitamente el rango alcanzable (reachable_max_messages:100); las llamadas antiguas (sin parámetros) pasan automáticamente al resumen, el llamador no necesita cambiar parámetros, pero ten en cuenta que el contenido devuelto pasa de mensajes completos a resumen (si necesitas el texto original, usa explícitamente include_messages=true).

• Response Size Guard: middleware unificado en todas las respuestas MCP del hub, MAX_RESPONSE_BYTES=50000; si se supera, smart-truncate automático (garantiza que siga siendo JSON válido, con metadatos truncated), registro [mcp-guard] <tool> original=.. returned=.. truncated.

• Monitorización de salud: el hub añade GET /metrics (número de peticiones/bytes de respuesta medios y máximos/contadores de truncado y error/conexiones activas/detalle por herramienta), GET /readyz (disponibilidad del quórum HA) y GET /version; el Dashboard añade la pestaña «Plano de control MCP».

• Intervención inmediata/inserción correctiva: sessions_prompt admite mode=queue|steer (por defecto queue, semántica de cola sin cambios); steer omite la cola e inyecta en la ronda en curso a través de la API del host de DSH (devuelve estructurado steered/queued/rejected/unavailable); el evento de historial de DSH agent/inbox/spliced confirma la inyección. Revisión de diseño y detalles de implementación en docs/priority-queue.md.

Soporte de plataformas

El código central no tiene lógica específica de plataforma (launchd/osascript/PowerShell están aislados en packages/platform y packages/presence); el escenario de dos máquinas macOS (Tailscale) ya está verificado en hardware real; Linux/Windows pendiente de verificación en hardware real.

Documentación

Puntos clave de seguridad

• Credenciales: ~/.dsh/helm/node.json (token de nodo) y el archivo de token del daemon con permisos 0600; la tabla de tokens del hub se inyecta por entorno con DSH_HELM_TOKEN (no se escribe en disco); los tokens no aparecen en argv/git/registros; las credenciales del túnel se inyectan con sintaxis env:.

• Bind: el hub solo se vincula a 127.0.0.1 por defecto; entre máquinas se recomienda Tailscale + --bind <tailnet-ip>, y --mcp-bind 127.0.0.1 mantiene el MCP solo en loopback. El MCP del hub (3471) v1 no tiene autenticación: prohibido exponerlo directamente a la red pública; en producción el mesh va por wss:// (el TLS lo gestiona un proxy inverso/servidor https externo).

• Fail-closed: las operaciones destructivas (sessions_prompt/sessions_resume) se rechazan si no hay un destino claro; dentro de la ventana de ambigüedad de presence no se adivina.

• Sin almacenamiento de contenido: el store solo guarda metadatos y auditoría, no el contenido de las sesiones de DSH.

• Modelo de seguridad detallado en docs/security.md y docs/threat-model.md.

Estado y capas de evidencia

Versión v0.1.0. Verificación automatizada totalmente en verde (unitarias + pruebas de integración de protocolo completo de extremo a extremo con dos nodos fake + aceptación de fidelidad de información: 399/399 (48 archivos), build/lint limpios); smoke en hardware real completado con dos máquinas macOS por Tailscale. doctor/dashboard/install implementados; los comandos RPC en línea de la CLI (nodes/node/route-explain/presence/rotate-token) aún requieren conexión a un hub en vivo (actualmente muestran requires live hub connection, previsto para el próximo hito); la misma capacidad puede usarse a través de las herramientas MCP del hub (nodes_list, etc.); session handoff v1 devuelve honestamente unsupported.

El estado de capacidades se divide por capas según la fuerza de la evidencia (sin mezclar):

Lo que explícitamente no se promete: sin garantía de production-ready; la HA es redundancia de plano de control autogestionada, sin SLA / sin promesa de zero-downtime; no se prometen capacidades fuera de los límites oficiales de OpenAI (HA de túnel multiinstancia, rotación automática de claves) hasta que se obtengan. El veredicto de aceptación es CONDITIONAL PASS (fidelidad y seguridad cerradas; la completitud está limitada por los límites de protocolo de DSH 0.1.1).

Scripts de operaciones

Todos los scripts son compatibles con bash 3.2, con prefijo de salida [dsh-helm], idempotentes, y solo sondean sin modificar los servicios existentes en los puertos de producción (3080/3457/3458).