helmpilot 0.4.2

package/outbound.ts

@@ -0,0 +1,98 @@
+/**
+ * Helmpilot Channel — Outbound Adapter
+ *
+ * Sends messages from OpenClaw to the Helmpilot desktop client via the relay tunnel.
+ *
+ * Message format (OpenClaw event frame, sent as raw WS string through relay):
+ *   { "type": "event", "event": "helmpilot.outbound", "payload": { kind, text|mediaUrl, messageId, ... } }
+ *
+ * The Helmpilot client's handleMessage → handleEvent → EventDispatcher routes these
+ * to registered 'helmpilot.outbound' event handlers.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { getRelay } from './relay-registry.js';
+
+/** Maximum text length per outbound message (chars). Exceeding text will be chunked. */
+const TEXT_CHUNK_LIMIT = 4000;
+const CHANNEL_ID = 'helmpilot';
+
+/**
+ * Build the outbound adapter object for ChannelPlugin.outbound.
+ *
+ * deliveryMode: "direct" — the adapter runs in the gateway process (where the relay lives).
+ */
+export function createOutboundAdapter() {
+  return {
+    deliveryMode: 'direct' as const,
+    textChunkLimit: TEXT_CHUNK_LIMIT,
+
+    async sendText(ctx: {
+      to: string;
+      text: string;
+      replyToId?: string | null;
+      accountId?: string | null;
+      identity?: { name?: string; avatar?: string; emoji?: string };
+    }) {
+      const relay = getRelay(ctx.accountId);
+      if (!relay || relay.getState() !== 'connected') {
+        return { channel: CHANNEL_ID, messageId: '', error: 'Relay not connected' };
+      }
+
+      const messageId = `msg_${randomUUID()}`;
+      const msg = JSON.stringify({
+        type: 'event',
+        event: 'helmpilot.outbound',
+        payload: {
+          kind: 'text',
+          text: ctx.text,
+          messageId,
+          replyToId: ctx.replyToId ?? undefined,
+          identity: ctx.identity ?? undefined,
+        },
+      });
+
+      const sent = relay.sendRaw(msg);
+      if (!sent) {
+        return { channel: CHANNEL_ID, messageId: '', error: 'Failed to send via relay' };
+      }
+
+      return { channel: CHANNEL_ID, messageId };
+    },
+
+    async sendMedia(ctx: {
+      to: string;
+      text?: string;
+      mediaUrl?: string;
+      replyToId?: string | null;
+      accountId?: string | null;
+      identity?: { name?: string; avatar?: string; emoji?: string };
+    }) {
+      const relay = getRelay(ctx.accountId);
+      if (!relay || relay.getState() !== 'connected') {
+        return { channel: CHANNEL_ID, messageId: '', error: 'Relay not connected' };
+      }
+
+      const messageId = `msg_${randomUUID()}`;
+      const msg = JSON.stringify({
+        type: 'event',
+        event: 'helmpilot.outbound',
+        payload: {
+          kind: 'media',
+          mediaUrl: ctx.mediaUrl,
+          text: ctx.text ?? undefined,
+          messageId,
+          replyToId: ctx.replyToId ?? undefined,
+          identity: ctx.identity ?? undefined,
+        },
+      });
+
+      const sent = relay.sendRaw(msg);
+      if (!sent) {
+        return { channel: CHANNEL_ID, messageId: '', error: 'Failed to send via relay' };
+      }
+
+      return { channel: CHANNEL_ID, messageId };
+    },
+  };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "helmpilot",
+  "version": "0.4.2",
+  "description": "Helmpilot desktop channel plugin for OpenClaw — interactive tools and gateway RPC bridge",
+  "type": "module",
+  "main": "index.ts",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "helmpilot",
+    "channel",
+    "desktop"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "helmpilot",
+      "label": "Helmpilot Desktop",
+      "docsPath": "/docs/channels/helmpilot",
+      "blurb": "Connect to the Helmpilot desktop AI assistant client"
+    },
+    "compat": {
+      "pluginApi": ">=2026.3.24",
+      "minGatewayVersion": "2026.3.24"
+    }
+  },
+  "dependencies": {
+    "ws": ">=8.0.0",
+    "@types/ws": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  }
+}

package/preload.cjs

@@ -0,0 +1,33 @@
+/**
+ * Plugin preload entry (CJS format).
+ *
+ * The openclaw framework loads plugins via require(), so this needs a .cjs suffix
+ * to work correctly in a "type": "module" package.
+ *
+ * Before requiring the actual plugin code (which depends on openclaw/plugin-sdk),
+ * we synchronously ensure the node_modules/openclaw symlink exists.
+ */
+"use strict";
+
+const { ensurePluginSdkSymlink } = require("./scripts/link-sdk-core.cjs");
+
+// 1) Synchronously create symlink
+ensurePluginSdkSymlink(__dirname, "[helmpilot-preload]");
+
+// 2) Node 22 natively supports CJS require() loading ESM modules
+//    Synchronously load plugin entry so the framework can find register/activate
+const _pluginModule = require("./index.ts");
+
+// 3) Flatten default export: framework checks register/activate at top level
+//    ESM's export default becomes { default: plugin, ... } after require()
+const _default = _pluginModule.default;
+const merged = Object.assign({}, _pluginModule);
+if (_default && typeof _default === "object") {
+  for (const key of Object.keys(_default)) {
+    if (!(key in merged)) {
+      merged[key] = _default[key];
+    }
+  }
+}
+
+module.exports = merged;

package/relay-client.ts

@@ -0,0 +1,380 @@
+/**
+ * Relay outbound client for helmpilot-channel plugin.
+ *
+ * Connects to a Helmpilot Relay Service as the "gateway" side.
+ * The relay is a transparent tunnel — raw WS messages are forwarded
+ * between the device (Helmpilot Desktop) and the gateway plugin.
+ *
+ * Supports two auth modes:
+ *   1. Ed25519 challenge-response (preferred) — signs relay nonce with keypair
+ *   2. Legacy key auth — channelKey in URL query parameter
+ *
+ * Relay-originated messages (lifecycle events) are identified by `__relay: true`
+ * and handled internally. Everything else is forwarded via onRawMessage callback.
+ *
+ * In tunnel mode:
+ *   Helmpilot Desktop ──WS──→ Relay ←──WS── this client (gateway plugin)
+ *                                        ↕ bridge
+ *                                     Local Gateway WS
+ */
+
+import { WebSocket } from 'ws';
+import { generateKeyPairSync, sign, randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── Types ──
+
+/** Relay-originated lifecycle event (identified by __relay: true) */
+interface RelayLifecycleMessage {
+  __relay: true;
+  type: 'lifecycle';
+  event: string;
+  timestamp: number;
+}
+
+/** Ed25519 keypair for relay authentication */
+interface RelayKeyPair {
+  publicKey: string; // base64url, 32 bytes raw
+  privateKeyDer: string; // base64url, PKCS8 DER encoded
+}
+
+interface RelayClientConfig {
+  relayUrl: string;
+  channelId: string;
+  channelKey: string;
+  /** If true, use Ed25519 challenge-response instead of channelKey in URL */
+  useEd25519?: boolean;
+}
+
+interface RelayClientCallbacks {
+  /** Called when a raw application message arrives from the device, to be forwarded to local gateway */
+  onRawMessage: (data: string) => void;
+  /** Called when the relay sends a lifecycle event (device_connected, device_disconnected, etc.) */
+  onLifecycleEvent: (event: string) => void;
+  /** Called when the Relay connection state changes */
+  onStateChange: (state: RelayConnectionState) => void;
+}
+
+export type RelayConnectionState = 'disconnected' | 'connecting' | 'connected' | 'authenticating' | 'error';
+
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30_000;
+const PING_INTERVAL_MS = 25_000;
+
+/** Ed25519 SPKI DER header (12 bytes) — stripped to get raw 32-byte public key */
+const ED25519_SPKI_HEADER_LEN = 12;
+
+/**
+ * Get or generate an Ed25519 keypair for the gateway plugin.
+ * Persists in ~/.openclaw/helmpilot-gateway-keypair.json
+ */
+function getOrCreateKeyPair(): RelayKeyPair {
+  const dir = join(homedir(), '.openclaw');
+  const file = join(dir, 'helmpilot-gateway-keypair.json');
+
+  if (existsSync(file)) {
+    try {
+      const data = JSON.parse(readFileSync(file, 'utf-8')) as RelayKeyPair;
+      if (data.publicKey && data.privateKeyDer) return data;
+    } catch { /* regenerate */ }
+  }
+
+  const { publicKey: pubKeyObject, privateKey: privKeyObject } = generateKeyPairSync('ed25519');
+
+  // Export raw 32-byte public key as base64url
+  const spkiDer = pubKeyObject.export({ type: 'spki', format: 'der' });
+  const rawPubKey = spkiDer.subarray(ED25519_SPKI_HEADER_LEN);
+  const publicKey = rawPubKey.toString('base64url');
+
+  // Export private key as PKCS8 DER (for signing)
+  const pkcs8Der = privKeyObject.export({ type: 'pkcs8', format: 'der' });
+  const privateKeyDer = pkcs8Der.toString('base64url');
+
+  const kp: RelayKeyPair = { publicKey, privateKeyDer };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, JSON.stringify(kp, null, 2), { mode: 0o600 });
+  console.log('[helmpilot-relay-client] Generated new Ed25519 gateway keypair');
+  return kp;
+}
+
+/**
+ * Manages the outbound WebSocket connection to the Relay service.
+ * Auto-reconnects on disconnect with exponential backoff.
+ * Operates as a transparent tunnel — forwards raw messages without parsing.
+ */
+export class RelayClient {
+  private ws: WebSocket | null = null;
+  private state: RelayConnectionState = 'disconnected';
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+  private keyPair: RelayKeyPair | null = null;
+
+  constructor(
+    private config: RelayClientConfig,
+    private callbacks: RelayClientCallbacks,
+  ) {
+    if (config.useEd25519) {
+      this.keyPair = getOrCreateKeyPair();
+    }
+  }
+
+  /** Get the Ed25519 public key (for registration with Relay) */
+  getPublicKey(): string | null {
+    return this.keyPair?.publicKey ?? null;
+  }
+
+  /**
+   * Register the gateway Ed25519 public key with the Relay via HTTP.
+   * Must be called before start() for Ed25519 auth to work.
+   * On failure, falls back to legacy auth silently.
+   */
+  async registerPublicKey(): Promise<boolean> {
+    if (!this.keyPair) return false;
+
+    try {
+      const url = new URL(this.config.relayUrl);
+      // Convert ws/wss to http/https for REST API calls
+      const httpProtocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+      const base = `${httpProtocol}//${url.host}`;
+      const res = await fetch(`${base}/api/channels/${this.config.channelId}/register-key`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          side: 'gateway',
+          publicKey: this.keyPair.publicKey,
+          channelKey: this.config.channelKey,
+        }),
+      });
+      if (res.ok) {
+        console.log('[helmpilot-relay-client] Gateway Ed25519 public key registered');
+        return true;
+      }
+      console.warn(`[helmpilot-relay-client] Failed to register gateway public key: ${res.status}`);
+      // Fall back to legacy auth
+      this.config = { ...this.config, useEd25519: false };
+      this.keyPair = null;
+      return false;
+    } catch (err) {
+      console.warn('[helmpilot-relay-client] Failed to register gateway public key:', err);
+      this.config = { ...this.config, useEd25519: false };
+      this.keyPair = null;
+      return false;
+    }
+  }
+
+  /** Start the Relay connection (with auto-reconnect) */
+  start(): void {
+    this.stopped = false;
+    this.connect();
+  }
+
+  /** Stop the Relay connection and cancel reconnect */
+  stop(): void {
+    this.stopped = true;
+    this.clearTimers();
+    if (this.ws) {
+      try { this.ws.close(1000, 'Plugin stopping'); } catch {}
+      this.ws = null;
+    }
+    this.setState('disconnected');
+  }
+
+  /** Forward a raw message to the device through the Relay (transparent tunnel) */
+  sendRaw(data: string): boolean {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false;
+    try {
+      this.ws.send(data);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Get current connection state */
+  getState(): RelayConnectionState {
+    return this.state;
+  }
+
+  // ── Internal ──
+
+  private connect(): void {
+    if (this.stopped) return;
+
+    this.setState('connecting');
+
+    // Build WS URL
+    const url = new URL(this.config.relayUrl);
+    if (!url.pathname.endsWith('/ws/gateway')) {
+      url.pathname = url.pathname.replace(/\/$/, '') + '/ws/gateway';
+    }
+    url.searchParams.set('channel', this.config.channelId);
+
+    // Only include key in URL for legacy auth (not Ed25519)
+    if (!this.config.useEd25519) {
+      url.searchParams.set('key', this.config.channelKey);
+    }
+
+    try {
+      this.ws = new WebSocket(url.toString());
+    } catch (err) {
+      console.error('[helmpilot-relay-client] Failed to create WebSocket:', err);
+      this.setState('error');
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.on('open', () => {
+      if (this.config.useEd25519) {
+        console.log('[helmpilot-relay-client] Connected to Relay, awaiting auth challenge');
+        this.setState('authenticating');
+      } else {
+        console.log('[helmpilot-relay-client] Connected to Relay (legacy auth)');
+        this.setState('connected');
+        this.reconnectAttempt = 0;
+        this.startPing();
+      }
+    });
+
+    this.ws.on('message', (data) => {
+      const raw = typeof data === 'string' ? data : data.toString();
+
+      // Check if this is a relay-originated message
+      if (raw.startsWith('{"__relay":true')) {
+        this.handleRelayMessage(raw);
+        return;
+      }
+
+      // Everything else is a forwarded application message (OpenClaw WS protocol)
+      this.callbacks.onRawMessage(raw);
+    });
+
+    this.ws.on('close', (code, reason) => {
+      console.log(`[helmpilot-relay-client] Disconnected: ${code} ${reason}`);
+      this.ws = null;
+      this.stopPing();
+      if (!this.stopped) {
+        this.setState('disconnected');
+        this.scheduleReconnect();
+      }
+    });
+
+    this.ws.on('error', (err) => {
+      console.error('[helmpilot-relay-client] WebSocket error:', err);
+      // 'close' event will follow
+    });
+  }
+
+  /** Handle relay-originated messages (__relay: true) — auth, lifecycle, flush markers, keepalive responses */
+  private handleRelayMessage(raw: string): void {
+    let msg: { __relay: true; type: string; event?: string; nonce?: string; reason?: string; count?: number; oldestTimestamp?: number };
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+
+    if (!msg.__relay) return;
+
+    switch (msg.type) {
+      case 'auth_challenge':
+        this.handleAuthChallenge(msg.nonce!);
+        break;
+      case 'auth_ok':
+        console.log('[helmpilot-relay-client] Ed25519 auth succeeded');
+        this.setState('connected');
+        this.reconnectAttempt = 0;
+        this.startPing();
+        break;
+      case 'auth_failed':
+        console.error(`[helmpilot-relay-client] Ed25519 auth failed: ${msg.reason}`);
+        this.setState('error');
+        break;
+      case 'flush_start':
+        console.log(`[helmpilot-relay-client] Flushing ${msg.count} buffered messages (oldest: ${msg.oldestTimestamp ? new Date(msg.oldestTimestamp).toISOString() : '?'})`);
+        break;
+      case 'flush_end':
+        console.log('[helmpilot-relay-client] Flush complete');
+        break;
+      case 'lifecycle':
+        if (typeof msg.event === 'string') {
+          this.callbacks.onLifecycleEvent(msg.event);
+        }
+        break;
+    }
+  }
+
+  /** Sign and respond to Ed25519 auth challenge from Relay */
+  private handleAuthChallenge(nonce: string): void {
+    if (!this.keyPair || !this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    try {
+      const { createPrivateKey } = require('node:crypto') as typeof import('node:crypto');
+
+      const message = `relay-auth|${this.config.channelId}|${nonce}`;
+      const messageBuffer = Buffer.from(message, 'utf-8');
+
+      // Reconstruct private key from PKCS8 DER
+      const pkcs8Der = Buffer.from(this.keyPair.privateKeyDer, 'base64url');
+      const privateKey = createPrivateKey({ key: pkcs8Der, format: 'der', type: 'pkcs8' });
+
+      const signature = sign(null, messageBuffer, privateKey);
+
+      this.ws.send(JSON.stringify({
+        __relay: true,
+        type: 'auth_response',
+        publicKey: this.keyPair.publicKey,
+        signature: signature.toString('base64url'),
+      }));
+    } catch (err) {
+      console.error('[helmpilot-relay-client] Failed to sign auth challenge:', err);
+      this.setState('error');
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return;
+    const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+    this.reconnectAttempt++;
+    console.log(`[helmpilot-relay-client] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})`);
+    this.reconnectTimer = setTimeout(() => this.connect(), delay);
+  }
+
+  private startPing(): void {
+    this.stopPing();
+    // Send relay-level keepalive (not WS-level ping) so the relay server
+    // can update lastPing via its onMessage handler. The relay recognises
+    // messages starting with '{"__relay":true' and will NOT forward them.
+    const keepalive = JSON.stringify({ __relay: true, type: 'ping' });
+    this.pingTimer = setInterval(() => {
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        this.ws.send(keepalive);
+      }
+    }, PING_INTERVAL_MS);
+  }
+
+  private stopPing(): void {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+
+  private clearTimers(): void {
+    this.stopPing();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private setState(state: RelayConnectionState): void {
+    if (this.state !== state) {
+      this.state = state;
+      this.callbacks.onStateChange(state);
+    }
+  }
+}

package/relay-registry.ts

@@ -0,0 +1,32 @@
+/**
+ * Module-level relay client registry.
+ *
+ * Allows the outbound adapter to access the RelayClient instance
+ * created by gateway.startAccount(). Each account gets one relay client.
+ */
+
+import type { RelayClient } from './relay-client.js';
+
+const accountRelays = new Map<string, RelayClient>();
+
+/** Register a relay client for an account (called from gateway.startAccount) */
+export function registerRelay(accountId: string, client: RelayClient): void {
+  accountRelays.set(accountId, client);
+}
+
+/** Unregister a relay client (called on account stop/abort) */
+export function unregisterRelay(accountId: string): void {
+  accountRelays.delete(accountId);
+}
+
+/** Get the relay client for an account. Requires explicit accountId — no fallback to prevent cross-account leaks. */
+export function getRelay(accountId?: string | null): RelayClient | null {
+  if (!accountId) return null;
+  return accountRelays.get(accountId) ?? null;
+}
+
+/** Get the first available relay client (only for single-account fallback during bootstrap). */
+export function getFirstRelay(): RelayClient | null {
+  const first = accountRelays.values().next();
+  return first.done ? null : first.value;
+}