@2en/clawly-plugins 1.4.1 → 1.6.0

package/channel.ts

@@ -9,8 +9,8 @@
 
 import {$} from 'zx'
 import type {PluginApi} from './index'
-import {sendPushNotification} from './notification'
-import {isClientOnline} from './presence'
+import {sendPushNotification} from './gateway/notification'
+import {isClientOnline} from './gateway/presence'
 
 $.verbose = false
 

package/{echo.ts → command/clawly_echo.ts}

@@ -3,7 +3,7 @@
  * invoking the LLM.
  */
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 
 export function registerEchoCommand(api: PluginApi) {
   api.registerCommand({

package/command/index.ts

@@ -0,0 +1,6 @@
+import type {PluginApi} from '../index'
+import {registerEchoCommand} from './clawly_echo'
+
+export function registerCommands(api: PluginApi) {
+  registerEchoCommand(api)
+}

package/{agent-send.ts → gateway/agent.ts}

@@ -9,7 +9,7 @@
  */
 
 import {$} from 'zx'
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 import {sendPushNotification} from './notification'
 import {isClientOnline} from './presence'
 

package/gateway/clawhub2gateway.md

@@ -0,0 +1,68 @@
+# clawhub2gateway
+
+OpenClaw plugin that wraps the **ClawHub CLI** as **Gateway WebSocket RPC methods**.
+
+## What you get
+
+Gateway methods (call via WS RPC):
+
+- `clawhub2gateway.search`
+- `clawhub2gateway.explore`
+- `clawhub2gateway.install`
+- `clawhub2gateway.update`
+- `clawhub2gateway.list`
+- `clawhub2gateway.inspect`
+- `clawhub2gateway.star`
+- `clawhub2gateway.unstar`
+
+## Install on a gateway host
+
+1) Install the ClawHub CLI (must be on PATH for the OpenClaw process):
+
+```bash
+npm i -g clawhub
+```
+
+2) Put this plugin on the gateway host and make it discoverable. Common options:
+
+- **Workspace plugin**: copy this folder to `<workspace>/.openclaw/extensions/clawhub2gateway/`
+  with `index.ts` + `openclaw.plugin.json`
+- **Config path**: set `plugins.load.paths` to the plugin folder path
+
+3) Enable the plugin in your `openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "entries": {
+      "clawhub2gateway": { "enabled": true, "config": {} }
+    }
+  }
+}
+```
+
+## Plugin config
+
+Configured under `plugins.entries.clawhub2gateway.config`:
+
+- `bin` (string, default: `"clawhub"`): command to execute
+- `defaultDir` (string, default: `"skills"`): default `--dir`
+- `defaultNoInput` (boolean, default: `true`): default `--no-input`
+- `defaultTimeoutMs` (number, default: `60000`)
+- `configPath` (string, optional): sets `CLAWHUB_CONFIG_PATH`. Defaults to
+  `<OPENCLAW_STATE_DIR>/clawhub/config.json` when state dir is known.
+
+## Call examples (RPC params)
+
+Install:
+
+```json
+{ "method": "clawhub2gateway.install", "params": { "slug": "my-skill-pack" } }
+```
+
+Explore:
+
+```json
+{ "method": "clawhub2gateway.explore", "params": { "limit": 50, "sort": "trending", "json": true } }
+```

package/gateway/clawhub2gateway.ts

@@ -0,0 +1,405 @@
+/**
+ * ClawHub CLI RPC bridge — expose ClawHub CLI commands as Gateway RPC methods.
+ *
+ * Gateway methods:
+ * - clawhub2gateway.search
+ * - clawhub2gateway.install
+ * - clawhub2gateway.update
+ * - clawhub2gateway.list
+ * - clawhub2gateway.explore
+ * - clawhub2gateway.inspect
+ * - clawhub2gateway.star
+ * - clawhub2gateway.unstar
+ *
+ * Notes:
+ * - This plugin shells out to the `clawhub` CLI. Install it on the gateway host:
+ *   `npm i -g clawhub` (or ensure it is in PATH).
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type {PluginApi} from '../index'
+
+type JsonSchema = Record<string, unknown>
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return Boolean(v && typeof v === 'object' && !Array.isArray(v))
+}
+
+function readBool(params: Record<string, unknown>, key: string): boolean | undefined {
+  return typeof params[key] === 'boolean' ? (params[key] as boolean) : undefined
+}
+
+function readString(params: Record<string, unknown>, key: string): string | undefined {
+  const v = params[key]
+  if (typeof v !== 'string') return undefined
+  const t = v.trim()
+  return t ? t : undefined
+}
+
+function readNumber(params: Record<string, unknown>, key: string): number | undefined {
+  const v = params[key]
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  if (typeof v === 'string' && v.trim()) {
+    const n = Number(v.trim())
+    if (Number.isFinite(n)) return n
+  }
+  return undefined
+}
+
+function coercePluginConfig(api: PluginApi): Record<string, unknown> {
+  return isRecord(api.pluginConfig) ? api.pluginConfig : {}
+}
+
+function configString(
+  cfg: Record<string, unknown>,
+  key: string,
+  fallback?: string,
+): string | undefined {
+  const v = cfg[key]
+  if (typeof v === 'string' && v.trim()) return v.trim()
+  return fallback
+}
+
+function configBool(cfg: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const v = cfg[key]
+  if (typeof v === 'boolean') return v
+  return fallback
+}
+
+function configNumber(cfg: Record<string, unknown>, key: string, fallback: number): number {
+  const v = cfg[key]
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  return fallback
+}
+
+async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, {recursive: true})
+}
+
+function buildGlobalCliArgs(
+  params: Record<string, unknown>,
+  defaults: {dir: string; noInput: boolean},
+) {
+  const out: string[] = []
+
+  const workdir = readString(params, 'workdir')
+  const dir = readString(params, 'dir') ?? defaults.dir
+  const site = readString(params, 'site')
+  const registry = readString(params, 'registry')
+  const noInput = readBool(params, 'noInput') ?? defaults.noInput
+
+  if (workdir) out.push('--workdir', workdir)
+  if (dir) out.push('--dir', dir)
+  if (site) out.push('--site', site)
+  if (registry) out.push('--registry', registry)
+  if (noInput) out.push('--no-input')
+
+  return out
+}
+
+async function runClawhubCommand(opts: {
+  api: PluginApi
+  argv: string[]
+  cwd?: string
+  timeoutMs: number
+  env?: Record<string, string | undefined>
+}) {
+  const runner = opts.api.runtime.system?.runCommandWithTimeout
+  if (!runner) {
+    throw new Error('Plugin runtime missing system.runCommandWithTimeout')
+  }
+  const result = await runner(opts.argv, {timeoutMs: opts.timeoutMs, cwd: opts.cwd, env: opts.env})
+  return result
+}
+
+function joinOutput(stdout: string, stderr: string): string {
+  const s1 = (stdout ?? '').trimEnd()
+  const s2 = (stderr ?? '').trimEnd()
+  if (s1 && s2) return `${s1}\n\n${s2}`
+  return s1 || s2 || ''
+}
+
+function baseToolParamsSchema(extra?: JsonSchema): JsonSchema {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      workdir: {type: 'string', description: 'Working directory (ClawHub --workdir)'},
+      dir: {type: 'string', description: 'Skills directory relative to workdir (ClawHub --dir)'},
+      site: {type: 'string', description: 'ClawHub site URL (ClawHub --site)'},
+      registry: {type: 'string', description: 'ClawHub registry API URL (ClawHub --registry)'},
+      noInput: {type: 'boolean', description: 'Disable prompts (ClawHub --no-input)'},
+      timeoutMs: {type: 'number', description: 'Command timeout in milliseconds'},
+      ...(extra ?? {}),
+    },
+  }
+}
+
+export function registerClawhub2gateway(api: PluginApi) {
+  const cfg = coercePluginConfig(api)
+  const bin = configString(cfg, 'bin', 'clawhub') ?? 'clawhub'
+  const defaultDir = configString(cfg, 'defaultDir', 'skills') ?? 'skills'
+  const defaultNoInput = configBool(cfg, 'defaultNoInput', true)
+  const defaultTimeoutMs = configNumber(cfg, 'defaultTimeoutMs', 60_000)
+  const configPath = configString(cfg, 'configPath')
+
+  const stateDir =
+    api.runtime.state?.resolveStateDir?.(process.env) ??
+    process.env.OPENCLAW_STATE_DIR ??
+    process.env.CLAWDBOT_STATE_DIR ??
+    ''
+  const defaultConfigPath = stateDir ? path.join(stateDir, 'clawhub', 'config.json') : ''
+
+  const resolveEnv = async (): Promise<Record<string, string | undefined>> => {
+    const env: Record<string, string | undefined> = {}
+    const resolved = configPath ?? defaultConfigPath
+    if (resolved) {
+      await ensureDir(path.dirname(resolved))
+      env.CLAWHUB_CONFIG_PATH = resolved
+    }
+    return env
+  }
+
+  const registerRpc = (rpc: {
+    method: string
+    description: string
+    parameters: JsonSchema
+    buildCli: (
+      params: Record<string, unknown>,
+    ) => Promise<{argv: string[]; cwd?: string; timeoutMs?: number}>
+  }) => {
+    api.registerGatewayMethod(rpc.method, async ({params, respond}) => {
+      try {
+        const timeoutMs = Math.max(
+          1_000,
+          Math.floor(readNumber(params, 'timeoutMs') ?? defaultTimeoutMs),
+        )
+        const built = await rpc.buildCli(params)
+        const env = await resolveEnv()
+        const res = await runClawhubCommand({
+          api,
+          argv: built.argv,
+          cwd: built.cwd,
+          timeoutMs: built.timeoutMs ?? timeoutMs,
+          env,
+        })
+        const output = joinOutput(res.stdout, res.stderr)
+        if (res.code && res.code !== 0) {
+          respond(false, undefined, {
+            code: 'command_failed',
+            message: output || `clawhub exited with code ${res.code}`,
+          })
+          return
+        }
+        respond(true, {
+          ok: true,
+          output,
+          stdout: res.stdout,
+          stderr: res.stderr,
+          code: res.code,
+          signal: res.signal,
+          killed: res.killed,
+          argv: built.argv,
+          cwd: built.cwd,
+        })
+      } catch (err) {
+        respond(false, undefined, {
+          code: 'error',
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    })
+  }
+
+  // -----------------------------
+  // Search
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.search',
+    description: 'ClawHub CLI: search skills.',
+    parameters: baseToolParamsSchema({
+      query: {type: 'string', description: 'Search query'},
+      limit: {type: 'number', description: 'Max results (clawhub search --limit)'},
+    }),
+    async buildCli(params) {
+      const query = readString(params, 'query')
+      if (!query) throw new Error('query required')
+      const limit = readNumber(params, 'limit')
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'search', query, ...globalArgs]
+      if (limit !== undefined) argv.push('--limit', String(Math.max(1, Math.floor(limit))))
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.explore',
+    description: 'ClawHub CLI: explore skills.!',
+    parameters: baseToolParamsSchema({
+      limit: {type: 'number', description: 'Max results (clawhub explore --limit, if supported)'},
+      sort: {
+        type: 'string',
+        enum: ['newest', 'downloads', 'rating', 'installs', 'installsAllTime', 'trending'],
+        description:
+          'Sort order (clawhub explore --sort). One of newest, downloads, rating, installs, installsAllTime, trending.',
+      },
+      json: {type: 'boolean', description: 'Output JSON'},
+    }),
+    async buildCli(params) {
+      const limit = readNumber(params, 'limit')
+      const sort = readString(params, 'sort')
+      const json = readBool(params, 'json') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'explore', ...globalArgs]
+      if (limit !== undefined) argv.push('--limit', String(Math.max(1, Math.floor(limit))))
+      if (sort) argv.push('--sort', sort)
+      if (json) argv.push('--json')
+      return {argv}
+    },
+  })
+
+  // -----------------------------
+  // Install / Update / List
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.install',
+    description: 'ClawHub CLI: install a skill into the workspace skills dir.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug to install'},
+      version: {type: 'string', description: 'Specific version to install'},
+      force: {
+        type: 'boolean',
+        description: 'Overwrite if folder exists (clawhub install --force)',
+      },
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const version = readString(params, 'version')
+      const force = readBool(params, 'force') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'install', slug, ...globalArgs]
+      if (version) argv.push('--version', version)
+      if (force) argv.push('--force')
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.update',
+    description: 'ClawHub CLI: update one skill or all installed skills.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug to update (omit when all=true)'},
+      all: {type: 'boolean', description: 'Update all skills (clawhub update --all)'},
+      version: {type: 'string', description: 'Update to a specific version (single slug only)'},
+      force: {
+        type: 'boolean',
+        description: 'Overwrite when local files do not match any published version',
+      },
+    }),
+    async buildCli(params) {
+      const all = readBool(params, 'all') ?? false
+      const slug = readString(params, 'slug')
+      const version = readString(params, 'version')
+      const force = readBool(params, 'force') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+
+      const argv = [bin, 'update', ...globalArgs]
+      if (all) {
+        argv.push('--all')
+      } else {
+        if (!slug) throw new Error('slug required when all=false')
+        argv.push(slug)
+        if (version) argv.push('--version', version)
+      }
+      if (force) argv.push('--force')
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.list',
+    description: 'ClawHub CLI: list installed skills from .clawhub/lock.json.',
+    parameters: baseToolParamsSchema(),
+    async buildCli(params) {
+      const argv = [
+        bin,
+        'list',
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  // -----------------------------
+  // Inspect / Star
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.inspect',
+    description: 'ClawHub CLI: inspect a skill without installing.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+
+      const argv = [bin, 'inspect', slug, ...globalArgs]
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.star',
+    description: 'ClawHub CLI: star a skill.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const argv = [
+        bin,
+        'star',
+        slug,
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.unstar',
+    description: 'ClawHub CLI: unstar a skill.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const argv = [
+        bin,
+        'unstar',
+        slug,
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  api.logger.info(
+    [
+      `clawhub2gateway: registered.`,
+      `Using clawhub bin: ${bin}`,
+      defaultConfigPath
+        ? `CLI config: ${configPath ?? defaultConfigPath}`
+        : 'CLI config: (not set)',
+    ].join(' '),
+  )
+}

package/gateway/index.ts

@@ -0,0 +1,16 @@
+import type {PluginApi} from '../index'
+import {registerAgentSend} from './agent'
+import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerMemoryBrowser} from './memory'
+import {registerNotification} from './notification'
+import {registerPlugins} from './plugins'
+import {registerPresence} from './presence'
+
+export function registerGateway(api: PluginApi) {
+  registerPresence(api)
+  registerNotification(api)
+  registerAgentSend(api)
+  registerMemoryBrowser(api)
+  registerClawhub2gateway(api)
+  registerPlugins(api)
+}

package/gateway/memory-browser.md

@@ -0,0 +1,55 @@
+# memory-browser
+
+OpenClaw plugin that exposes the **memory directory** (all `.md` files) as **Gateway WebSocket RPC methods**.
+
+## What you get
+
+Gateway methods (call via WS RPC):
+
+- **`memory-browser.list`** — List all `.md` files in the memory directory (recursive). Returns `{ files: string[] }` (relative paths).
+- **`memory-browser.get`** — Return the content of a single `.md` file. Params: `{ path: string }` (relative path, e.g. `"notes/foo.md"`). Returns `{ path: string, content: string }`.
+
+## Memory directory
+
+The memory directory is resolved in this order:
+
+1. Plugin config `memoryDir` (absolute path)
+2. `<OPENCLAW_STATE_DIR>/memory` (or `<CLAWDBOT_STATE_DIR>/memory`)
+3. `<process.cwd()>/memory`
+
+## Install on a gateway host
+
+1. Put this plugin on the gateway host and make it discoverable, e.g.:
+   - Workspace: `<workspace>/.openclaw/extensions/memory-browser/` with `index.ts` + `openclaw.plugin.json`
+   - Or set `plugins.load.paths` to the plugin folder
+
+2. Enable the plugin in `openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "entries": {
+      "memory-browser": { "enabled": true, "config": {} }
+    }
+  }
+}
+```
+
+Optional config: `config.memoryDir` to override the memory directory path.
+
+## Call examples (RPC params)
+
+List all `.md` files:
+
+```json
+{ "method": "memory-browser.list", "params": {} }
+```
+
+Get one file:
+
+```json
+{ "method": "memory-browser.get", "params": { "path": "notes/meeting-2024.md" } }
+```
+
+`path` must be a relative path to a `.md` file inside the memory directory; directory traversal (`..`) is rejected.