dsh-helm

DSH multi-node control plane: extends the single-machine "ChatGPT ↔ DSH" connector into a multi-node control plane. DeepSeek Harness (DSH) instances on multiple machines register with a unified Hub through node agents (node-agent); ChatGPT can route to any node through a single entry point—reading/writing code, managing sessions, checking health—without exposing any node to the public internet.

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 鉴权）

• Each node runs dsh-helm agent: outbound-only connection to the hub (mesh WS), bridging the local helm daemon's MCP (127.0.0.1:3457/mcp) inward.

• The hub is the only entry point: ChatGPT calls tools through the hub MCP (3471), and the hub forwards to the correct node according to routing policy; the number of nodes is transparent to ChatGPT.

• Single-machine compatibility: with a single node and node_id == hub defaultNodeId, routing and tool-call behavior is equivalent to the single-machine daemon (summary/guard/steer are upper-layer enhancements and do not affect existing call semantics).

Features

• Multi-node registration and heartbeat: node identity node_id (UUID) + HMAC challenge handshake; 15s heartbeat, 45s lease; newer agent versions automatically reconnect on heartbeat timeout (half-open connection detection and reconnect).

• Five-level routing: explicit target_node → session owner → workspace owner → unambiguous presence → defaultNodeId fallback; destructive/write operations with unclear targets are fail-closed rejected (route_confirmation_required), never guessed.

• Traceable forwarding: every forwarding result carries _route.node_name (display_name) marking the executing node; route_explain is a dry run that does not execute.

• MCP tool surface 19+5: the single-machine daemon's 19 tools (code_*/sessions_*/projects_list/supervisor_health, etc., snake_case parameters unchanged) are preserved as-is, with new additions nodes_list/node_get/route_explain/presence_claim/presence_release; all routable tools accept an optional target_node.

• presence: manual declaration (10-minute pin) + automatic macOS foreground-app detection (desktop sidecar); dual-node high confidence within the 15s ambiguity window → judged ambiguous, no automatic selection.

• Layered health: control / channel / adapter / datapath / serena / tunnel layers each report independently, never collapsed into a single status: ok.

• Cross-node aggregation: workspaces_list/sessions_list/agents_list/projects_list return flattened multi-node results (each entry carries node_id).

• Audit and routing logs: node registration, heartbeats, routing decisions, and presence changes are all persisted (audit/route_log).

• Metadata red line: hub storage contains only metadata (nodes/leases/session and workspace directories/audit), and never stores DSH session content.

Related MCP server: Peta Core

Directory structure

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 优先）

Quick start

Prerequisites: Node.js >= 22.5, pnpm, curl; each node machine must have DSH and the helm daemon installed (127.0.0.1:3457/mcp, Bearer token at ~/.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                    # 本地配置与连接状态

Adding more nodes: after dsh-helm init on a new node machine, hand the node_id and token from node.json to the hub administrator over a secure channel, then run on the hub machine (idempotent: appends/updates the token table, auto-reloads the launchd service):

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

Detailed flow in docs/onboarding.md.

Connecting ChatGPT

Two paths, choose by deployment stage:

• A. Single-machine direct (starting out): when the local machine already has a helm daemon, the hub treats the local node as a local node, behaving identically to the single-machine connector, no tunnel needed.

• B. Multi-node (control plane, recommended): OpenAI Secure MCP Tunnel connects to the hub MCP (3471); ChatGPT manages all nodes through one entry point.

Full OpenAI Platform tutorial (creating tunnel / binding workspace / creating API key / tunnel-client parameters / proxy) in docs/chatgpt-tunnel-setup.md; ChatGPT Web side (developer mode / creating connector / testing) in docs/chatgpt-connector.md.

Trade-off between the two topologies: one tunnel + connector per daemon (multiple entry points, each managing its own), or one hub tunnel + one connector managing N nodes (single entry point, recommended—hub routes via target_node/routing rules, replies carry node_name).

Control-plane HA (dual Control Plane)

Two hubs form a quorum (2/2) control plane; if either fails, the other can still serve read routing and node entry.

• Roles and leases: the one with the smaller --cp-priority wins as leader (sole writer); the leader renews the lease with the peer every 10s; if the peer is unreachable beyond the lease TTL (--cp-failover-ms, default 45s) → both sides enter read-only-no-quorum, and write operations return QUORUM_LOST. A follower never unilaterally promotes itself—without quorum it is read-only (CAP prioritizes safety).

• Recovery: peer reconnects → full registry sync → forced re-election (term+1) → lease confirmed by both sides → writes resume. Both sides remain read-only throughout the recovery window.

• agent multi-endpoint: node.json configures hub_url + fallback_urls; on reconnect it polls in turn and pins on success; on failure it automatically switches to the second CP.

• Observability: GET /cp-status returns role/phase/writeMode/quorum/term/leaderId/peers/syncOk/leaseEpoch/failoverCount; dsh-helm doctor and the Dashboard "Control Plane HA" card display it directly.

• ChatGPT entry HA: the OpenAI tunnel-client's --mcp.server-url is channel-scoped with no multi-backend failover within one connector. Run a local dsh-helm ha-proxy (default 127.0.0.1:3481, --primary http://127.0.0.1:3471 --secondary http://<peer-cp>:3471); the tunnel still points to one connector (3481); it automatically switches to the secondary CP when the primary is unreachable and switches back after recovery. Dual tunnel + dual connector is the alternative topology.

• Second CP deployment: dsh-helm hub --cp-peer ws://<peer-cp>:3470 --cp-priority 1 --cp-id <node-id> --cp-token-env DSH_HELM_CP_TOKEN; both sides' DSH_HELM_TOKEN must contain both nodes' token tables (so the other CP can authenticate any agent during failover). Use --mcp-bind <tailnet-ip> when MCP must be reachable across machines (Tailscale ACL fence; keep loopback for single-machine scenarios).

Device pairing (adding a DSH device)

Dashboard "Add DSH Device" → generates a one-time pairing code (valid 10 minutes, single-use, only the hash is stored); the new machine runs dsh-helm join --control-plane ws://<hub>:3470 --code <code> to join the network (generates a long-term node token written to ~/.dsh/helm/node.json; the hub stores only the hash/status). The pairing API is loopback-only + anti-CSRF header; logs record only the hash prefix. See docs/security.md §5.

MCP Context Isolation (large-context stability)

Response slimming and monitoring for long-running, large-context sessions in the ChatGPT ↔ DSH connector (compatibility layer, chain unchanged):

• sessions_get default summary: by default returns only a structured summary (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, no messages). The summary is generated by the node agent: it requests only the last 20 messages from DSH (SUMMARY_WINDOW), current_goal takes the most action-oriented user instruction in the window (with source seq), recent_evidence is extracted by regex heuristics, and suspected credential lines are stripped before entering any summary field (safety_sanitized flag). Measured baseline: early large-session responses 75KB → 1.2KB; fidelity acceptance fixture (1000 messages) ~107KB → 0.7KB, default response <1KB. Cached at ~/.dsh/helm/summaries/<session_id>.json (60s TTL, invalidated after write operations).

• Full history on demand: include_messages=true (configurable max_messages, default 20) returns full messages; the before_seq parameter is passed through but DSH 0.1.1 does not implement real pagination (probe-verified: max_messages ≤100 and beforeSeq is ineffective)—history beyond the most recent 100 messages is currently unreachable, and history_ref explicitly marks the reachable range (reachable_max_messages:100); legacy calls (without parameters) automatically use the summary, callers need not change parameters, but note the return content changes from full messages to a summary (use explicit include_messages=true when the original text is needed).

• Response Size Guard: unified middleware on all hub MCP responses, MAX_RESPONSE_BYTES=50000; over-limit responses are automatically smart-truncated (still valid JSON, with truncated metadata attached), logged as [mcp-guard] <tool> original=.. returned=.. truncated.

• Health monitoring: hub adds GET /metrics (request count/average and max response bytes/truncation and error counts/active connections/perTool breakdown), GET /readyz (HA quorum readiness), GET /version; Dashboard adds an "MCP Control Plane" tab.

• Correction queue-jumping/immediate intervention: sessions_prompt supports mode=queue|steer (default queue preserves queueing semantics); steer bypasses the queue and injects into the running turn via the DSH host API (structured return steered/queued/rejected/unavailable), confirmed by the DSH history event agent/inbox/spliced. Design review and implementation details in docs/priority-queue.md.

Platform support

Core code has zero platform-specific logic (launchd/osascript/PowerShell all isolated in packages/platform and packages/presence); macOS dual-machine (Tailscale) verified on real hardware; Linux/Windows awaiting real-device verification.

Documentation

Security highlights

• Credentials: ~/.dsh/helm/node.json (node token) and the daemon token file are both 0600; the hub token table is injected via the DSH_HELM_TOKEN environment variable (never written to disk); tokens never appear in argv/git/logs; tunnel credentials are injected with the env: syntax.

• Binding: the hub binds only 127.0.0.1 by default; for cross-machine use, Tailscale + --bind <tailnet-ip> is recommended, with --mcp-bind 127.0.0.1 keeping MCP loopback-only. Hub MCP (3471) v1 has no authentication—never expose it directly to the public internet; production mesh uses wss:// (TLS handled by a reverse proxy/external https server).

• fail-closed: destructive operations (sessions_prompt/sessions_resume) are rejected without a clear target; no guessing within the presence ambiguity window.

• No content storage: the store holds only metadata and audit records, never DSH session content.

• Full security model in docs/security.md and docs/threat-model.md.

Status and evidence tiers

Version v0.1.0. Automated verification all green (unit + full-protocol end-to-end integration tests with two fake nodes + fidelity acceptance: 399/399 (48 files), build/lint clean); macOS dual-machine Tailscale real-device smoke test complete. doctor/dashboard/install implemented; CLI online RPC commands (nodes/node/route-explain/presence/rotate-token) still require a live hub connection (currently prompts requires live hub connection, planned for the next milestone); the same capability is available via hub MCP tools (nodes_list, etc.); session handoff v1 honestly returns unsupported.

Capability status is tiered by evidence strength (no conflation):

Explicitly not promised: no production-ready guarantee; HA is self-managed control-plane redundancy with no SLA / zero-downtime promise; no commitment on OpenAI official capability boundaries (tunnel multi-instance HA, automatic key rotation) until obtained. Acceptance verdict is CONDITIONAL PASS (fidelity and security closed loop; completeness limited by DSH 0.1.1 protocol boundaries).

ops scripts

All scripts are bash 3.2 compatible, use the [dsh-helm] output prefix, are idempotent, and only probe—never modify—existing services on production ports (3080/3457/3458).