helmpilot 0.4.2

package/scripts/link-sdk-core.cjs

@@ -0,0 +1,124 @@
+/**
+ * Shared module: openclaw plugin-sdk symlink creation logic.
+ *
+ * Used by both preload.cjs and postinstall-link-sdk.js to avoid duplication.
+ * Must be CJS format because preload.cjs requires synchronous require().
+ */
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { execSync } = require("node:child_process");
+
+const CLI_NAMES = ["openclaw", "clawdbot", "moltbot"];
+
+/**
+ * Find the global openclaw installation root.
+ * Tries: npm root -g, which/where <cli>, extensions directory inference.
+ */
+function findOpenclawRoot(pluginRoot) {
+  // Strategy 1: npm root -g
+  try {
+    const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+    for (const name of CLI_NAMES) {
+      const candidate = path.join(globalRoot, name);
+      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    }
+  } catch {}
+
+  // Strategy 2: which/where <cli>
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  for (const name of CLI_NAMES) {
+    try {
+      const bin = execSync(`${whichCmd} ${name}`, {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim().split("\n")[0];
+      if (!bin) continue;
+      const realBin = fs.realpathSync(bin);
+      const c1 = path.resolve(path.dirname(realBin), "..", "lib", "node_modules", name);
+      if (fs.existsSync(path.join(c1, "package.json"))) return c1;
+      const c2 = path.resolve(path.dirname(realBin), "..");
+      if (fs.existsSync(path.join(c2, "package.json")) && fs.existsSync(path.join(c2, "plugin-sdk"))) return c2;
+    } catch {}
+  }
+
+  // Strategy 3: infer from extensions directory structure
+  const extensionsDir = path.dirname(pluginRoot);
+  const dataDir = path.dirname(extensionsDir);
+  const dataDirName = path.basename(dataDir);
+  const cliName = dataDirName.replace(/^\./, "");
+  if (cliName) {
+    try {
+      const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+      const candidate = path.join(globalRoot, cliName);
+      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    } catch {}
+  }
+
+  return null;
+}
+
+/**
+ * Validate existing node_modules/openclaw is complete and usable.
+ */
+function isLinkValid(linkTarget) {
+  try {
+    const stat = fs.lstatSync(linkTarget);
+    if (stat.isSymbolicLink()) {
+      return fs.existsSync(path.join(linkTarget, "dist", "plugin-sdk"))
+        || fs.existsSync(path.join(linkTarget, "plugin-sdk"));
+    }
+    // Real directory — check for core.js
+    return fs.existsSync(path.join(linkTarget, "dist", "plugin-sdk", "core.js"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure the openclaw plugin-sdk symlink exists.
+ *
+ * @param {string} pluginRoot - Plugin root directory path
+ * @param {string} [tag="[link-sdk]"] - Log prefix
+ * @returns {boolean} true if symlink already exists or was successfully created
+ */
+function ensurePluginSdkSymlink(pluginRoot, tag) {
+  tag = tag || "[link-sdk]";
+  try {
+    if (!pluginRoot.includes("extensions")) return true;
+
+    const linkTarget = path.join(pluginRoot, "node_modules", "openclaw");
+
+    if (fs.existsSync(linkTarget)) {
+      if (isLinkValid(linkTarget)) return true;
+      // Invalid/incomplete — remove and recreate
+      try {
+        fs.rmSync(linkTarget, { recursive: true, force: true });
+        console.log(`${tag} removed incomplete node_modules/openclaw`);
+      } catch {}
+    }
+
+    const openclawRoot = findOpenclawRoot(pluginRoot);
+    if (!openclawRoot) {
+      console.error(`${tag} WARNING: could not find openclaw global installation, symlink not created`);
+      return false;
+    }
+
+    fs.mkdirSync(path.join(pluginRoot, "node_modules"), { recursive: true });
+    fs.symlinkSync(openclawRoot, linkTarget, "junction");
+    console.log(`${tag} symlink created: node_modules/openclaw -> ${openclawRoot}`);
+    return true;
+  } catch (e) {
+    console.error(`${tag} WARNING: symlink check failed: ${e.message || e}`);
+    return false;
+  }
+}
+
+module.exports = {
+  CLI_NAMES,
+  findOpenclawRoot,
+  isLinkValid,
+  ensurePluginSdkSymlink,
+};

package/setup-entry.ts

@@ -0,0 +1,193 @@
+/**
+ * Helmpilot Channel — Setup-only plugin entry.
+ *
+ * Loaded by the CLI for `openclaw channels add --channel helmpilot`.
+ * This is a lightweight entry that only exposes meta + setup adapter.
+ * ALL code is inlined to avoid import chain issues in extensions directory.
+ */
+
+import { defineSetupPluginEntry } from 'openclaw/plugin-sdk/core';
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
+
+const HELMPILOT_CHANNEL_ID = 'helmpilot';
+const HELMPILOT_CONFIG_SECTION = 'channels.helmpilot';
+const DEFAULT_ACCOUNT_ID = 'default';
+
+interface HelmpilotAccountConfig {
+  enabled?: boolean;
+  relayUrl?: string;
+  channelId?: string;
+  channelKey?: string;
+}
+
+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) ?? {};
+}
+
+// ── Inlined Setup Adapter ──
+
+function createInlinedSetupAdapter() {
+  return {
+    applyAccountConfig(params: {
+      cfg: Record<string, unknown>;
+      accountId: string;
+      input: { url?: string; token?: string; code?: string };
+    }): Record<string, unknown> {
+      const cfg = structuredClone(params.cfg);
+      const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+      const hp = (channels.helmpilot ?? {}) as Record<string, unknown>;
+
+      if (params.input.url) {
+        hp.relayUrl = params.input.url;
+      }
+      if (params.input.code) {
+        hp.channelId = params.input.code;
+      }
+      if (params.input.token) {
+        hp.channelKey = params.input.token;
+      }
+      hp.enabled = true;
+
+      channels.helmpilot = hp;
+      cfg.channels = channels;
+      return cfg;
+    },
+
+    validateInput(params: {
+      cfg: Record<string, unknown>;
+      accountId: string;
+      input: { url?: string; token?: string; code?: string };
+    }): string | null {
+      const { url, token, code } = params.input;
+
+      if (url) {
+        try {
+          const parsed = new URL(url);
+          if (!['ws:', 'wss:', 'http:', 'https:'].includes(parsed.protocol)) {
+            return 'Relay URL must use ws://, wss://, http://, or https:// protocol';
+          }
+        } catch {
+          return 'Invalid Relay URL format';
+        }
+      }
+
+      if (code && !code.startsWith('ch_')) {
+        return 'Channel ID must start with "ch_"';
+      }
+
+      if (token && !token.startsWith('ck_')) {
+        return 'Channel key must start with "ck_"';
+      }
+
+      // Check for required fields (existing config values fill gaps)
+      const channels = (params.cfg?.channels ?? {}) as Record<string, unknown>;
+      const existing = (channels?.helmpilot ?? {}) as Record<string, unknown>;
+      const hasUrl = url || existing.relayUrl;
+      const hasCode = code || existing.channelId;
+      const hasToken = token || typeof existing.channelKey === 'string';
+
+      if (!hasUrl && !hasCode && !hasToken) {
+        return 'Helmpilot requires --url (Relay URL), --code (channel ID), and --token (channel key).\n'
+          + 'Example: openclaw channels add --channel helmpilot --url ws://localhost:4800 --code ch_xxx --token ck_xxx';
+      }
+
+      return null;
+    },
+  };
+}
+
+export const helmpilotSetupPlugin: 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,
+  },
+
+  setup: createInlinedSetupAdapter(),
+
+  reload: { configPrefixes: [HELMPILOT_CONFIG_SECTION] },
+
+  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: typeof acct.channelKey === 'string' ? acct.channelKey : undefined,
+          },
+        };
+      }
+
+      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: typeof hp.channelKey === 'string' ? hp.channelKey : undefined,
+        },
+      };
+    },
+
+    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;
+    },
+  },
+};
+
+export default defineSetupPluginEntry(helmpilotSetupPlugin);

package/tools.ts

@@ -0,0 +1,121 @@
+/**
+ * Helmpilot Channel — Tool definitions
+ *
+ * Defines hp_send_file, hp_send_msg, hp_ask_user tools and
+ * hp_read_file, hp_write_file, hp_list_dir client-side file tools,
+ * plus the process-level pending request map for blocking tools ↔ helmpilot.respond.
+ *
+ * Schemas are plain JSON Schema objects (no TypeBox dependency) to avoid
+ * pnpm symlink issues when the plugin is installed to ~/.openclaw/extensions/.
+ */
+
+// ── Tool names (hp_ prefix per channel convention) ──
+
+export const HP_SEND_FILE = 'hp_send_file';
+export const HP_SEND_MSG = 'hp_send_msg';
+export const HP_ASK_USER = 'hp_ask_user';
+export const HP_READ_FILE = 'hp_read_file';
+export const HP_WRITE_FILE = 'hp_write_file';
+export const HP_LIST_DIR = 'hp_list_dir';
+
+// ── Schemas (plain JSON Schema) ──
+
+export const SendFileParamsSchema = {
+  type: 'object' as const,
+  required: ['filename', 'content'],
+  properties: {
+    filename: { type: 'string' as const, description: 'Filename (e.g. AGENTS.md)' },
+    content: { type: 'string' as const, description: 'File content' },
+  },
+};
+
+const QuestionOptionSchema = {
+  type: 'object' as const,
+  required: ['label'],
+  properties: {
+    label: { type: 'string' as const },
+    description: { type: 'string' as const },
+    recommended: { type: 'boolean' as const },
+  },
+};
+
+const QuestionSchema = {
+  type: 'object' as const,
+  required: ['header', 'question'],
+  properties: {
+    header: { type: 'string' as const, maxLength: 50 },
+    question: { type: 'string' as const, maxLength: 500 },
+    options: { type: 'array' as const, items: QuestionOptionSchema },
+    multiSelect: { type: 'boolean' as const },
+    allowFreeformInput: { type: 'boolean' as const },
+  },
+};
+
+export const AskUserParamsSchema = {
+  type: 'object' as const,
+  required: ['questions'],
+  properties: {
+    questions: { type: 'array' as const, items: QuestionSchema, minItems: 1, maxItems: 10 },
+  },
+};
+
+export const SendMsgParamsSchema = {
+  type: 'object' as const,
+  required: ['message'],
+  properties: {
+    message: { type: 'string' as const, description: 'Message content (supports Markdown)' },
+    type: {
+      type: 'string' as const,
+      enum: ['info', 'success', 'warning', 'error'],
+      description: 'Message type that determines display style. Defaults to "info".',
+    },
+    title: { type: 'string' as const, description: 'Optional notification title' },
+  },
+};
+
+// ── File tool schemas ──
+
+export const ReadFileParamsSchema = {
+  type: 'object' as const,
+  required: ['path'],
+  properties: {
+    path: { type: 'string' as const, description: 'Relative path to a file within the user workspace (e.g. "src/main.ts")' },
+  },
+};
+
+export const WriteFileParamsSchema = {
+  type: 'object' as const,
+  required: ['path', 'content'],
+  properties: {
+    path: { type: 'string' as const, description: 'Relative path within the user workspace where the file will be written' },
+    content: { type: 'string' as const, description: 'File content to write' },
+  },
+};
+
+export const ListDirParamsSchema = {
+  type: 'object' as const,
+  required: ['path'],
+  properties: {
+    path: { type: 'string' as const, description: 'Relative path to a directory within the user workspace (e.g. "src" or "")' },
+  },
+};
+
+// ── Process-level shared state (toolCallId → pending request) ──
+// Uses Symbol.for() key for namespace isolation, following OpenClaw's own
+// globalThis[Symbol.for(...)] pattern for cross-module-graph state sharing.
+
+export interface PendingRequest {
+  resolve: (answer: string) => void;
+  questions: unknown;
+  toolCallId: string;
+}
+
+const PENDING_MAP_KEY = Symbol.for('helmpilot.pendingMap');
+
+export function getPendingMap(): Map<string, PendingRequest> {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[PENDING_MAP_KEY]) {
+    g[PENDING_MAP_KEY] = new Map<string, PendingRequest>();
+  }
+  return g[PENDING_MAP_KEY] as Map<string, PendingRequest>;
+}

package/types.ts

@@ -0,0 +1,93 @@
+/**
+ * helmpilot-channel — Shared types
+ *
+ * Defines the question/answer schema used across:
+ *   - Plugin tool registration (plain JSON Schema)
+ *   - Gateway RPC callback (helmpilot.respond)
+ *   - Client-side rendering (QuestionCard)
+ *
+ * No TypeBox dependency — plain JSON Schema + manual TS types to avoid
+ * pnpm symlink resolution issues in ~/.openclaw/extensions/.
+ */
+
+// ── Question Schema (plain JSON Schema) ──
+
+export const QuestionOptionSchema = {
+  type: 'object' as const,
+  required: ['label'],
+  properties: {
+    label: { type: 'string' as const, description: 'Display label for this option' },
+    description: { type: 'string' as const, description: 'Optional secondary text shown with the option' },
+    recommended: { type: 'boolean' as const, description: 'Mark this option as the recommended default' },
+  },
+};
+
+export const QuestionSchema = {
+  type: 'object' as const,
+  required: ['header', 'question'],
+  properties: {
+    header: { type: 'string' as const, description: 'Short unique identifier for the question (used as answer key)', maxLength: 50 },
+    question: { type: 'string' as const, description: 'The question text to display to the user', maxLength: 500 },
+    options: { type: 'array' as const, items: QuestionOptionSchema, description: 'Predefined selectable answers. Omit for free-text only.' },
+    multiSelect: { type: 'boolean' as const, description: 'Allow selecting multiple options (default: false)' },
+    allowFreeformInput: { type: 'boolean' as const, description: 'Allow freeform text in addition to option selection (default: true)' },
+  },
+};
+
+export const AskUserParamsSchema = {
+  type: 'object' as const,
+  required: ['questions'],
+  properties: {
+    questions: { type: 'array' as const, items: QuestionSchema, minItems: 1, maxItems: 10, description: 'One or more questions to present to the user' },
+  },
+};
+
+// ── Derived TypeScript types ──
+
+export interface QuestionOption {
+  label: string;
+  description?: string;
+  recommended?: boolean;
+}
+
+export interface Question {
+  header: string;
+  question: string;
+  options?: QuestionOption[];
+  multiSelect?: boolean;
+  allowFreeformInput?: boolean;
+}
+
+export interface AskUserParams {
+  questions: Question[];
+}
+
+// ── HTTP callback types ──
+
+export interface AskUserRespondPayload {
+  /** Formatted answer string (human-readable) */
+  answers: string;
+}
+
+export interface AskUserRespondResult {
+  status: 'ok' | 'not_found' | 'expired';
+}
+
+// ── Tool result format ──
+
+// ── Tool names & constants ──
+
+export const ASK_USER_TOOL_NAME = 'hp_ask_user';
+export const SEND_MSG_TOOL_NAME = 'hp_send_msg';
+export const SEND_FILE_TOOL_NAME = 'hp_send_file';
+export const ASK_USER_RPC_METHOD = 'helmpilot.respond';
+
+// ── hp_send_msg types ──
+
+export type SendMsgType = 'info' | 'success' | 'warning' | 'error';
+
+export interface SendMsgParams {
+  message: string;
+  type?: SendMsgType;
+  title?: string;
+}