helmpilot 0.4.2

package/channel-plugin.ts

@@ -0,0 +1,295 @@
+/**
+ * Helmpilot Channel Plugin — ChannelPlugin<ResolvedHelmpilotAccount> definition.
+ *
+ * Contains: meta, capabilities, config, adapters, gateway (startAccount).
+ */
+
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
+import { RelayClient } from './relay-client.js';
+import type { RelayConnectionState } from './relay-client.js';
+import { LocalBridge } from './bridge.js';
+import { registerRelay, unregisterRelay } from './relay-registry.js';
+import { createOutboundAdapter } from './outbound.js';
+import {
+  createMessagingAdapter,
+  createSetupAdapter,
+  createStatusAdapter,
+  createPairingAdapter,
+  createSecurityAdapter,
+} from './adapters.js';
+
+// ── Constants ──
+
+export const HELMPILOT_CHANNEL_ID = 'helmpilot';
+const HELMPILOT_CONFIG_SECTION = 'channels.helmpilot';
+const DEFAULT_ACCOUNT_ID = 'default';
+
+// ── Types ──
+
+export interface HelmpilotAccountConfig {
+  enabled?: boolean;
+  relayUrl?: string;
+  channelId?: string;
+  channelKey?: string;
+}
+
+export interface ResolvedHelmpilotAccount {
+  accountId: string;
+  config: HelmpilotAccountConfig;
+}
+
+interface RawHelmpilotConfig {
+  enabled?: boolean;
+  relayUrl?: string;
+  channelId?: string;
+  channelKey?: string | { source: string; id: string; provider?: string };
+  accounts?: Record<string, { enabled?: boolean; relayUrl?: string; channelId?: string; channelKey?: string | { source: string; id: string; provider?: string } }>;
+}
+
+function extractHelmpilotConfig(cfg: unknown): RawHelmpilotConfig {
+  const section = (cfg as Record<string, unknown>)?.channels as Record<string, unknown> | undefined;
+  return (section?.helmpilot as RawHelmpilotConfig) ?? {};
+}
+
+/** Env template pattern: ${ENV_VAR_NAME} */
+const ENV_TEMPLATE_RE = /^\$\{([A-Z][A-Z0-9_]{0,127})\}$/;
+
+/**
+ * Resolve a config value that may be a SecretRef or env template.
+ * Supports:
+ *   - Plain string: returned as-is
+ *   - Env template: "${HELMPILOT_CHANNEL_KEY}" → process.env.HELMPILOT_CHANNEL_KEY
+ *   - SecretRef object: { source: "env", id: "HELMPILOT_CHANNEL_KEY" } → process.env.HELMPILOT_CHANNEL_KEY
+ *   - SecretRef file: { source: "file", id: "/path/to/key" } → file contents
+ */
+function resolveSecretValue(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    const envMatch = ENV_TEMPLATE_RE.exec(value);
+    if (envMatch) {
+      const envVal = process.env[envMatch[1]];
+      if (!envVal) {
+        console.warn(`[helmpilot-channel] Env var ${envMatch[1]} not set for channelKey`);
+      }
+      return envVal;
+    }
+    return value;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const ref = value as { source?: string; id?: string };
+    if (ref.source === 'env' && typeof ref.id === 'string') {
+      const envVal = process.env[ref.id];
+      if (!envVal) {
+        console.warn(`[helmpilot-channel] Env var ${ref.id} not set for channelKey`);
+      }
+      return envVal;
+    }
+    if (ref.source === 'file' && typeof ref.id === 'string') {
+      try {
+        const fs = require('node:fs') as typeof import('node:fs');
+        return fs.readFileSync(ref.id, 'utf-8').trim();
+      } catch (err) {
+        console.error(`[helmpilot-channel] Failed to read secret file ${ref.id}:`, err);
+        return undefined;
+      }
+    }
+  }
+  return undefined;
+}
+
+// ── Channel Plugin ──
+
+export const helmpilotPlugin: ChannelPlugin<ResolvedHelmpilotAccount> = {
+  id: HELMPILOT_CHANNEL_ID,
+
+  meta: {
+    id: HELMPILOT_CHANNEL_ID,
+    label: 'Helmpilot Desktop',
+    selectionLabel: 'Helmpilot Desktop Client',
+    docsPath: '/docs/channels/helmpilot',
+    blurb: 'Connect to the Helmpilot desktop AI assistant client',
+    order: 100,
+  },
+
+  capabilities: {
+    chatTypes: ['direct'],
+    media: true,
+    reactions: false,
+    threads: false,
+    blockStreaming: true,
+  },
+
+  reload: { configPrefixes: [HELMPILOT_CONFIG_SECTION] },
+
+  outbound: createOutboundAdapter(),
+  messaging: createMessagingAdapter(),
+  setup: createSetupAdapter(),
+  status: createStatusAdapter(),
+  pairing: createPairingAdapter(),
+  security: createSecurityAdapter(),
+
+  config: {
+    listAccountIds(cfg) {
+      const hp = extractHelmpilotConfig(cfg);
+      if (hp.accounts && Object.keys(hp.accounts).length > 0) {
+        const ids = Object.keys(hp.accounts);
+        if (hp.relayUrl && hp.channelKey && !ids.includes(DEFAULT_ACCOUNT_ID)) {
+          ids.unshift(DEFAULT_ACCOUNT_ID);
+        }
+        return ids;
+      }
+      return [DEFAULT_ACCOUNT_ID];
+    },
+
+    resolveAccount(cfg, accountId) {
+      const id = accountId ?? DEFAULT_ACCOUNT_ID;
+      const hp = extractHelmpilotConfig(cfg);
+
+      const acct = hp.accounts?.[id];
+      if (acct) {
+        return {
+          accountId: id,
+          config: {
+            enabled: acct.enabled !== false && hp.enabled !== false,
+            relayUrl: typeof acct.relayUrl === 'string' ? acct.relayUrl : undefined,
+            channelId: typeof acct.channelId === 'string' ? acct.channelId : undefined,
+            channelKey: resolveSecretValue(acct.channelKey),
+          },
+        };
+      }
+
+      return {
+        accountId: id,
+        config: {
+          enabled: hp.enabled !== false,
+          relayUrl: typeof hp.relayUrl === 'string' ? hp.relayUrl : undefined,
+          channelId: typeof hp.channelId === 'string' ? hp.channelId : undefined,
+          channelKey: resolveSecretValue(hp.channelKey),
+        },
+      };
+    },
+
+    defaultAccountId() {
+      return DEFAULT_ACCOUNT_ID;
+    },
+
+    isEnabled(account) {
+      return account.config.enabled !== false;
+    },
+
+    isConfigured(account) {
+      const { relayUrl, channelId, channelKey } = account.config;
+      if (relayUrl || channelId || channelKey) {
+        return Boolean(relayUrl && channelId && channelKey);
+      }
+      return true;
+    },
+
+    setAccountEnabled(params: { cfg: Record<string, unknown>; accountId: string; enabled: boolean }) {
+      const cfg = structuredClone(params.cfg);
+      const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+      const hp = (channels.helmpilot ?? {}) as RawHelmpilotConfig;
+
+      if (hp.accounts?.[params.accountId]) {
+        hp.accounts[params.accountId].enabled = params.enabled;
+      } else if (params.accountId === DEFAULT_ACCOUNT_ID) {
+        hp.enabled = params.enabled;
+      }
+
+      channels.helmpilot = hp;
+      cfg.channels = channels;
+      return cfg;
+    },
+
+    deleteAccount(params: { cfg: Record<string, unknown>; accountId: string }) {
+      const cfg = structuredClone(params.cfg);
+      const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+      const hp = (channels.helmpilot ?? {}) as RawHelmpilotConfig;
+
+      if (hp.accounts?.[params.accountId]) {
+        delete hp.accounts[params.accountId];
+      } else if (params.accountId === DEFAULT_ACCOUNT_ID) {
+        delete channels.helmpilot;
+      }
+
+      cfg.channels = channels;
+      return cfg;
+    },
+
+    describeAccount(account: ResolvedHelmpilotAccount) {
+      return {
+        accountId: account.accountId,
+        enabled: account.config.enabled !== false,
+        configured: Boolean(account.config.relayUrl && account.config.channelId && account.config.channelKey),
+        mode: account.config.relayUrl ? 'relay' : 'local',
+      };
+    },
+  },
+
+  gatewayMethods: ['helmpilot.respond'],
+
+  gateway: {
+    async startAccount(ctx: any) {
+      const account = ctx.account as ResolvedHelmpilotAccount;
+      const { relayUrl, channelId, channelKey } = account.config;
+
+      if (!relayUrl || !channelId || !channelKey) {
+        console.log('[helmpilot-channel] No relay config, running in direct mode');
+        return;
+      }
+
+      const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT || '18789';
+      const localGwUrl = `ws://127.0.0.1:${gatewayPort}`;
+
+      // Read gateway auth token from config, falling back to env var in bridge
+      const gatewayToken = typeof ctx.cfg?.gateway?.auth?.token === 'string'
+        ? ctx.cfg.gateway.auth.token
+        : undefined;
+
+      console.log(`[helmpilot-channel] Starting Relay tunnel to ${relayUrl} (local gw: ${localGwUrl}, token: ${gatewayToken ? 'from-config' : 'from-env-or-none'})`);
+
+      const bridge = new LocalBridge(localGwUrl, gatewayToken);
+
+      const relayClient = new RelayClient(
+        { relayUrl, channelId, channelKey, useEd25519: true },
+        {
+          onRawMessage(data: string) {
+            bridge.forward(data);
+          },
+
+          onLifecycleEvent(event: string) {
+            console.log(`[helmpilot-channel] Relay lifecycle: ${event}`);
+            if (event === 'device_connected') {
+              bridge.open(relayClient);
+            } else if (event === 'device_disconnected') {
+              bridge.close();
+            }
+          },
+
+          onStateChange(state: RelayConnectionState) {
+            console.log(`[helmpilot-channel] Relay state: ${state}`);
+            if (state === 'disconnected' || state === 'error') {
+              bridge.close();
+            }
+          },
+        },
+      );
+
+      // Register gateway Ed25519 public key before connecting
+      await relayClient.registerPublicKey();
+
+      relayClient.start();
+      registerRelay(account.accountId, relayClient);
+
+      const abortSignal = ctx.abortSignal as AbortSignal;
+      await new Promise<void>((resolve) => {
+        abortSignal.addEventListener('abort', () => {
+          console.log('[helmpilot-channel] Stopping Relay tunnel');
+          unregisterRelay(account.accountId);
+          relayClient.stop();
+          bridge.close();
+          resolve();
+        });
+      });
+    },
+  },
+};

package/index.ts

@@ -0,0 +1,298 @@
+/**
+ * Helmpilot Desktop Channel — OpenClaw plugin entry point
+ *
+ * This file handles ONLY plugin registration, assembling:
+ *   - Channel plugin (from channel-plugin.ts)
+ *   - Gateway RPC methods (helmpilot.respond)
+ *   - Agent tools (hp_send_file, hp_send_msg, hp_ask_user)
+ *
+ * Architecture:
+ *   The gateway loads plugin registration twice — once at connection-level (for
+ *   gateway methods) and once per-agent (for tools). Because they don't share
+ *   closure state, we use `globalThis[Symbol.for('helmpilot.pendingMap')]` as a process-level
+ *   shared mailbox between the helmpilot.respond handler and hp_ask_user execute().
+ *
+ * Module structure:
+ *   - index.ts          — Plugin registration (this file)
+ *   - channel-plugin.ts — ChannelPlugin definition (meta/config/gateway)
+ *   - bridge.ts         — LocalBridge class (WS tunnel lifecycle)
+ *   - relay-client.ts   — RelayClient (Relay connection + Ed25519 auth)
+ *   - tools.ts          — Tool schemas + PendingMap
+ *   - adapters.ts       — Channel adapters (messaging/setup/status/pairing/security)
+ *   - outbound.ts       — Outbound message adapter
+ *   - relay-registry.ts — Per-account RelayClient registry
+ */
+
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { helmpilotPlugin, HELMPILOT_CHANNEL_ID } from './channel-plugin.js';
+import {
+  HP_SEND_FILE,
+  HP_SEND_MSG,
+  HP_ASK_USER,
+  HP_READ_FILE,
+  HP_WRITE_FILE,
+  HP_LIST_DIR,
+  SendFileParamsSchema,
+  SendMsgParamsSchema,
+  AskUserParamsSchema,
+  ReadFileParamsSchema,
+  WriteFileParamsSchema,
+  ListDirParamsSchema,
+  getPendingMap,
+} from './tools.js';
+
+export default definePluginEntry({
+  id: HELMPILOT_CHANNEL_ID,
+  name: 'Helmpilot Desktop Channel',
+  description:
+    'Helmpilot desktop client channel — provides interactive tools and gateway RPC bridge for Helmpilot ↔ OpenClaw communication.',
+
+  register(api) {
+    api.registerChannel({ plugin: helmpilotPlugin });
+
+    // ── Timeout helper for client-blocking tool calls ──
+    const FILE_TOOL_TIMEOUT_MS = 30_000;
+
+    function waitForClientResponse(toolCallId: string, params: unknown, timeoutMs: number): Promise<string> {
+      const pendingMap = getPendingMap();
+      const stale = pendingMap.get(toolCallId);
+      if (stale) {
+        stale.resolve('[Superseded by a new request.]');
+        pendingMap.delete(toolCallId);
+      }
+
+      return new Promise<string>((resolve) => {
+        const timer = setTimeout(() => {
+          pendingMap.delete(toolCallId);
+          resolve('[Error] Client did not respond within timeout.');
+        }, timeoutMs);
+
+        pendingMap.set(toolCallId, {
+          resolve: (answer: string) => {
+            clearTimeout(timer);
+            resolve(answer);
+          },
+          questions: params,
+          toolCallId,
+        });
+      });
+    }
+
+    // ── Gateway RPC: helmpilot.respond ──
+
+    api.registerGatewayMethod(
+      'helmpilot.respond',
+      ({ params, respond }) => {
+        const toolCallId = typeof params?.toolCallId === 'string' ? params.toolCallId : '';
+        const answers = typeof params?.answers === 'string' ? params.answers : '';
+        if (!answers) {
+          respond(false, undefined, { code: 'INVALID_REQUEST', message: 'Missing answers string' });
+          return;
+        }
+        if (!toolCallId) {
+          respond(false, undefined, { code: 'INVALID_REQUEST', message: 'Missing toolCallId — required for account isolation' });
+          return;
+        }
+        const pendingMap = getPendingMap();
+        const pending = pendingMap.get(toolCallId);
+        if (!pending) {
+          respond(false, undefined, { code: 'NOT_FOUND', message: 'No pending hp_ask_user request for this toolCallId' });
+          return;
+        }
+        pendingMap.delete(toolCallId);
+        pending.resolve(answers);
+        respond(true, { status: 'ok' });
+      },
+    );
+
+    // ── Tool: hp_send_file ──
+
+    api.registerTool({
+      name: HP_SEND_FILE,
+      description: [
+        'Send a single file to the Helmpilot desktop client.',
+        'The client receives the filename and content via tool events and handles',
+        'display and writing locally. Call once per file.',
+        'This tool does NOT write files on the server — it only relays content to the client.',
+      ].join('\n'),
+      label: 'Send File to Helmpilot',
+      parameters: SendFileParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        const p = params as { filename?: string; content?: string };
+        return {
+          content: [{ type: 'text' as const, text: `File "${p.filename ?? 'unknown'}" sent to Helmpilot client.` }],
+          details: {},
+        };
+      },
+    });
+
+    // ── Tool: hp_send_msg ──
+
+    api.registerTool({
+      name: HP_SEND_MSG,
+      description: [
+        'Send a notification or structured message to the Helmpilot desktop client.',
+        'Use this for status updates, alerts, confirmations, or formatted content',
+        'that should appear as a distinct notification rather than inline chat text.',
+        'Supports Markdown in the message body.',
+        '',
+        'Types: "info" (default), "success", "warning", "error".',
+      ].join('\n'),
+      label: 'Send Message to Helmpilot',
+      parameters: SendMsgParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        const p = params as { message?: string; type?: string; title?: string };
+        const msgType = p.type ?? 'info';
+        return {
+          content: [{ type: 'text' as const, text: `[${msgType}] message delivered to Helmpilot client.` }],
+          details: {},
+        };
+      },
+    });
+
+    // ── Tool: hp_ask_user ──
+
+    api.registerTool({
+      name: HP_ASK_USER,
+      description: [
+        'Ask the user one or more questions with an interactive UI in the Helmpilot client.',
+        'Each question can have predefined selectable options (single or multi-select),',
+        'allow freeform text input, or both.',
+        'The tool blocks until the user submits answers and returns them as text.',
+        '',
+        'Use this when you need clarification, preferences, or structured input.',
+      ].join('\n'),
+      label: 'Ask User',
+      parameters: AskUserParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        try {
+          const pendingMap = getPendingMap();
+
+          const stale = pendingMap.get(_toolCallId);
+          if (stale) {
+            stale.resolve('[Superseded by a new hp_ask_user call.]');
+            pendingMap.delete(_toolCallId);
+          }
+
+          const typedParams = params as { questions?: unknown[] };
+
+          // Wait indefinitely until the user responds.
+          // Natural cleanup boundaries: conversation end, gateway restart, relay flush expiry.
+          const answer = await new Promise<string>((resolve) => {
+            pendingMap.set(_toolCallId, {
+              resolve,
+              questions: typedParams.questions ?? [],
+              toolCallId: _toolCallId,
+            });
+          });
+
+          return {
+            content: [{ type: 'text' as const, text: answer }],
+            details: {},
+          };
+        } catch (err) {
+          console.error('[hp_ask_user] execute() error:', err);
+          return {
+            content: [{ type: 'text' as const, text: `[hp_ask_user error: ${err}]` }],
+            details: {},
+          };
+        }
+      },
+    });
+
+    // ── Tool: hp_read_file ──
+
+    api.registerTool({
+      name: HP_READ_FILE,
+      description: [
+        'Read a file from the user\'s local workspace on the Helmpilot desktop client.',
+        'The path must be relative to the workspace root (e.g. "src/main.ts").',
+        'Absolute paths and path traversal (../) are rejected.',
+        'Files larger than 1 MB will return an error.',
+        'The tool blocks until the client reads the file and returns its content.',
+      ].join('\n'),
+      label: 'Read File from Workspace',
+      parameters: ReadFileParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        try {
+          const answer = await waitForClientResponse(_toolCallId, params, FILE_TOOL_TIMEOUT_MS);
+
+          return {
+            content: [{ type: 'text' as const, text: answer }],
+            details: {},
+          };
+        } catch (err) {
+          return {
+            content: [{ type: 'text' as const, text: `[hp_read_file error: ${err}]` }],
+            details: {},
+          };
+        }
+      },
+    });
+
+    // ── Tool: hp_write_file ──
+
+    api.registerTool({
+      name: HP_WRITE_FILE,
+      description: [
+        'Write content to a file in the user\'s local workspace on the Helmpilot desktop client.',
+        'The path must be relative to the workspace root (e.g. "docs/notes.md").',
+        'Creates the file if it does not exist; overwrites if it does.',
+        'Parent directories are created automatically.',
+        'Absolute paths and path traversal (../) are rejected.',
+      ].join('\n'),
+      label: 'Write File to Workspace',
+      parameters: WriteFileParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        try {
+          const answer = await waitForClientResponse(_toolCallId, params, FILE_TOOL_TIMEOUT_MS);
+
+          return {
+            content: [{ type: 'text' as const, text: answer }],
+            details: {},
+          };
+        } catch (err) {
+          return {
+            content: [{ type: 'text' as const, text: `[hp_write_file error: ${err}]` }],
+            details: {},
+          };
+        }
+      },
+    });
+
+    // ── Tool: hp_list_dir ──
+
+    api.registerTool({
+      name: HP_LIST_DIR,
+      description: [
+        'List the contents of a directory in the user\'s local workspace on the Helmpilot desktop client.',
+        'The path must be relative to the workspace root. Use "" or "." for the root directory.',
+        'Returns a JSON array of entries, each with name, type ("file" or "directory"), and size.',
+        'Absolute paths and path traversal (../) are rejected.',
+      ].join('\n'),
+      label: 'List Directory in Workspace',
+      parameters: ListDirParamsSchema,
+
+      async execute(_toolCallId: string, params: unknown) {
+        try {
+          const answer = await waitForClientResponse(_toolCallId, params, FILE_TOOL_TIMEOUT_MS);
+
+          return {
+            content: [{ type: 'text' as const, text: answer }],
+            details: {},
+          };
+        } catch (err) {
+          return {
+            content: [{ type: 'text' as const, text: `[hp_list_dir error: ${err}]` }],
+            details: {},
+          };
+        }
+      },
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,67 @@
+{
+  "id": "helmpilot",
+  "name": "Helmpilot Desktop Channel",
+  "description": "Helmpilot desktop client channel plugin — provides interactive tools (ask_user, send_msg, send_file) and gateway RPC methods for Helmpilot \u2194 OpenClaw communication.",
+  "version": "0.4.0",
+  "channels": ["helmpilot"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable or disable the Helmpilot channel globally",
+        "default": true
+      },
+      "relayUrl": {
+        "type": "string",
+        "description": "(Legacy single-account) Relay URL — prefer using accounts.{id}.relayUrl"
+      },
+      "channelKey": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "properties": {
+              "source": { "type": "string", "enum": ["env", "file"] },
+              "provider": { "type": "string" },
+              "id": { "type": "string" }
+            },
+            "required": ["source", "id"]
+          }
+        ],
+        "description": "(Legacy single-account) Channel key. Supports: plain string, \"${ENV_VAR}\", or SecretRef {source,id}."
+      },
+      "accounts": {
+        "type": "object",
+        "description": "Named accounts (one per device). Each key is an account ID, value has relayUrl + channelKey.",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "relayUrl": { "type": "string" },
+            "channelKey": {
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "source": { "type": "string", "enum": ["env", "file"] },
+                    "provider": { "type": "string" },
+                    "id": { "type": "string" }
+                  },
+                  "required": ["source", "id"]
+                }
+              ],
+              "description": "Channel key. Supports: plain string, \"${ENV_VAR}\", or SecretRef {source,id}."
+            }
+          },
+          "required": ["relayUrl", "channelKey"]
+        }
+      }
+    }
+  },
+  "contracts": {
+    "tools": ["hp_ask_user", "hp_send_msg", "hp_send_file"]
+  }
+}