@2en/clawly-plugins 1.4.1 → 1.6.0

package/gateway/memory.ts

@@ -0,0 +1,187 @@
+/**
+ * Memory directory browser — expose memory directory .md files as Gateway RPC methods.
+ *
+ * Gateway methods:
+ * - memory-browser.list — list all .md files in the OpenClaw memory directory
+ * - memory-browser.get — return the content of a single .md file by path
+ */
+
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import type {PluginApi} from '../index'
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return Boolean(v && typeof v === 'object' && !Array.isArray(v))
+}
+
+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 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 coercePluginConfig(api: PluginApi): Record<string, unknown> {
+  return isRecord(api.pluginConfig) ? api.pluginConfig : {}
+}
+
+/** Resolve the memory directory path. Memory lives under workspace (agents.defaults.workspace). */
+function resolveMemoryDir(api: PluginApi, profile?: string): string {
+  const cfg = coercePluginConfig(api)
+  const configPath = configString(cfg, 'memoryDir')
+  if (configPath) return configPath
+
+  const baseDir =
+    process.env.OPENCLAW_WORKSPACE ?? path.join(os.homedir(), '.openclaw', 'workspace')
+  // Profile-aware: "main" or empty → default workspace, otherwise workspace-<profile>
+  if (profile && profile !== 'main') {
+    const parentDir = path.dirname(baseDir)
+    const baseName = path.basename(baseDir)
+    return path.join(parentDir, `${baseName}-${profile}`, 'memory')
+  }
+  return path.join(baseDir, 'memory')
+}
+
+/** Check that a relative path is safe (no directory traversal). */
+function isSafeRelativePath(relativePath: string): boolean {
+  if (!relativePath || relativePath.startsWith('/') || relativePath.includes('\\')) {
+    return false
+  }
+  const normalized = path.normalize(relativePath)
+  if (normalized.startsWith('..') || normalized.includes('..')) {
+    return false
+  }
+  return true
+}
+
+/** Recursively collect all .md file paths under dir, relative to baseDir. */
+async function collectMdFiles(dir: string, baseDir: string, acc: string[] = []): Promise<string[]> {
+  let entries: fs.Dirent[]
+  try {
+    entries = await fs.readdir(dir, {withFileTypes: true})
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return acc
+    throw err
+  }
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name)
+    const rel = path.relative(baseDir, full)
+
+    if (e.isDirectory()) {
+      await collectMdFiles(full, baseDir, acc)
+    } else if (e.isFile() && e.name.toLowerCase().endsWith('.md')) {
+      acc.push(rel)
+    }
+  }
+  return acc
+}
+
+export function registerMemoryBrowser(api: PluginApi) {
+  const memoryDir = resolveMemoryDir(api)
+  api.logger.info(`memory-browser: memory directory: ${memoryDir}`)
+
+  // -----------------------------
+  // memory-browser.list
+  // -----------------------------
+  api.registerGatewayMethod('memory-browser.list', async ({params, respond}) => {
+    try {
+      const profile = readString(params, 'profile')
+      const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+      const files = await collectMdFiles(dir, dir)
+      api.logger.info(`memory-browser.list: ${files.length} files found`)
+      files.sort()
+      respond(true, {files})
+    } catch (err) {
+      api.logger.error(
+        `memory-browser.list failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  // -----------------------------
+  // memory-browser.get
+  // -----------------------------
+  api.registerGatewayMethod('memory-browser.get', async ({params, respond}) => {
+    const relativePath = readString(params, 'path')
+    const profile = readString(params, 'profile')
+    const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+    if (!relativePath) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path (relative path to .md file) is required',
+      })
+      return
+    }
+    if (!isSafeRelativePath(relativePath)) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path must be a safe relative path (no directory traversal)',
+      })
+      return
+    }
+    if (!relativePath.toLowerCase().endsWith('.md')) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path must point to a .md file',
+      })
+      return
+    }
+
+    const fullPath = path.join(dir, path.normalize(relativePath))
+    const realMemory = await fs.realpath(dir).catch(() => dir)
+    const realResolved = await fs.realpath(fullPath).catch(() => null)
+
+    if (!realResolved) {
+      respond(false, undefined, {
+        code: 'not_found',
+        message: 'file not found',
+      })
+      return
+    }
+    const rel = path.relative(realMemory, realResolved)
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      respond(false, undefined, {
+        code: 'not_found',
+        message: 'file not found or outside memory directory',
+      })
+      return
+    }
+
+    try {
+      const content = await fs.readFile(fullPath, 'utf-8')
+      respond(true, {path: relativePath, content})
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        respond(false, undefined, {code: 'not_found', message: 'file not found'})
+        return
+      }
+      api.logger.error(
+        `memory-browser.get failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.logger.info(`memory-browser: registered (dir: ${memoryDir})`)
+}

package/{notification.ts → gateway/notification.ts}

@@ -13,7 +13,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 
 const TOKEN_DIR = path.join(os.homedir(), '.openclaw', 'clawly')
 const TOKEN_FILE = path.join(TOKEN_DIR, 'expo-push-token.json')

package/gateway/plugins.ts

@@ -0,0 +1,243 @@
+/**
+ * Plugin version check and update management.
+ *
+ * Methods:
+ * - clawly.plugins.version({ pluginId, npmPkgName }) → VersionResult
+ * - clawly.plugins.update({ pluginId, npmPkgName, strategy, targetVersion?, restart? }) → UpdateResult
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import {$} from 'zx'
+
+import type {PluginApi} from '../index'
+import {LruCache} from '../lib/lruCache'
+import {isUpdateAvailable} from '../lib/semver'
+import {stripCliLogs} from '../lib/stripCliLogs'
+
+$.verbose = false
+
+interface NpmViewCache {
+  version: string
+  versions: string[]
+}
+
+const npmCache = new LruCache<NpmViewCache>({maxSize: 5, ttlMs: 5 * 60 * 1000})
+
+function resolveStateDir(api: PluginApi): string {
+  return api.runtime.state?.resolveStateDir?.(process.env) ?? process.env.OPENCLAW_STATE_DIR ?? ''
+}
+
+function readExtensionVersion(stateDir: string, pluginId: string): string | null {
+  try {
+    const pkgPath = path.join(stateDir, 'extensions', pluginId, 'package.json')
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+async function fetchNpmView(npmPkgName: string): Promise<NpmViewCache | null> {
+  const cached = npmCache.get(npmPkgName)
+  if (cached) return cached
+
+  try {
+    const result = await $`npm view ${npmPkgName} --json`
+    const parsed = JSON.parse(stripCliLogs(result.stdout))
+    const entry: NpmViewCache = {
+      version: typeof parsed.version === 'string' ? parsed.version : '',
+      versions: Array.isArray(parsed.versions) ? parsed.versions : [],
+    }
+    npmCache.set(npmPkgName, entry)
+    return entry
+  } catch {
+    return null
+  }
+}
+
+export function registerPlugins(api: PluginApi) {
+  // ── clawly.plugins.version ──────────────────────────────────────
+
+  api.registerGatewayMethod('clawly.plugins.version', async ({params, respond}) => {
+    const pluginId = typeof params.pluginId === 'string' ? params.pluginId.trim() : ''
+    const npmPkgName = typeof params.npmPkgName === 'string' ? params.npmPkgName.trim() : ''
+
+    if (!pluginId || !npmPkgName) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'pluginId and npmPkgName are required',
+      })
+      return
+    }
+
+    const stateDir = resolveStateDir(api)
+    api.logger.info(`plugins.version: checking ${pluginId} (${npmPkgName})`)
+    let latestNpmVersion: string | null = null
+    let allNpmVersions: string[] = []
+    let updateAvailable = false
+    const errors: string[] = []
+
+    // Step 1: Read installed version from extensions/<id>/package.json
+    const npmPackageVersion = stateDir ? readExtensionVersion(stateDir, pluginId) : null
+    api.logger.info(`plugins.version: installed version = ${npmPackageVersion ?? 'not found'}`)
+
+    // Step 2: Fetch npm registry info
+    try {
+      const npm = await fetchNpmView(npmPkgName)
+      if (npm) {
+        latestNpmVersion = npm.version
+        allNpmVersions = npm.versions
+        api.logger.info(
+          `plugins.version: npm registry latest=${latestNpmVersion}, ${allNpmVersions.length} versions available`,
+        )
+      } else {
+        api.logger.warn(`plugins.version: npm view returned null for ${npmPkgName}`)
+      }
+    } catch (err) {
+      errors.push(`npm view: ${err instanceof Error ? err.message : String(err)}`)
+      api.logger.error(`plugins.version: npm view failed — ${errors[errors.length - 1]}`)
+    }
+
+    // Step 3: Compute update availability
+    if (npmPackageVersion && latestNpmVersion) {
+      updateAvailable = isUpdateAvailable(npmPackageVersion, latestNpmVersion)
+    }
+
+    api.logger.info(
+      `plugins.version: result current=${npmPackageVersion} latest=${latestNpmVersion} updateAvailable=${updateAvailable}`,
+    )
+
+    respond(true, {
+      pluginVersion: npmPackageVersion,
+      npmPackageVersion,
+      latestNpmVersion,
+      allNpmVersions,
+      updateAvailable,
+      ...(errors.length ? {error: errors.join('; ')} : {}),
+    })
+  })
+
+  // ── clawly.plugins.update ──────────────────────────────────────
+
+  api.registerGatewayMethod('clawly.plugins.update', async ({params, respond}) => {
+    const pluginId = typeof params.pluginId === 'string' ? params.pluginId.trim() : ''
+    const npmPkgName = typeof params.npmPkgName === 'string' ? params.npmPkgName.trim() : ''
+    const strategy = typeof params.strategy === 'string' ? params.strategy.trim() : ''
+    const targetVersion =
+      typeof params.targetVersion === 'string' ? params.targetVersion.trim() : undefined
+    const restart = params.restart === true
+
+    if (!pluginId || !npmPkgName || !strategy) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'pluginId, npmPkgName, and strategy are required',
+      })
+      return
+    }
+
+    if (!['force', 'update', 'install'].includes(strategy)) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: `invalid strategy: ${strategy}`,
+      })
+      return
+    }
+
+    const installTarget = targetVersion ? `${npmPkgName}@${targetVersion}` : npmPkgName
+
+    try {
+      let output = ''
+
+      if (strategy === 'force') {
+        const stateDir = resolveStateDir(api)
+        if (!stateDir) throw new Error('cannot resolve openclaw state dir')
+
+        const configPath = path.join(stateDir, 'openclaw.json')
+
+        // 1. Save current plugins.entries.<id> config (preserve user settings)
+        let savedEntry: Record<string, unknown> = {enabled: true}
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+          const entry = config?.plugins?.entries?.[pluginId]
+          if (entry && typeof entry === 'object') {
+            savedEntry = entry as Record<string, unknown>
+          }
+        } catch {
+          // config unreadable — use default
+        }
+        api.logger.info(`plugins: force — saved entry config for ${pluginId}`)
+
+        // 2. Delete plugins.entries.<id> from config so install starts clean
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+          if (config?.plugins?.entries?.[pluginId]) {
+            delete config.plugins.entries[pluginId]
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+          }
+        } catch {
+          // ignore
+        }
+
+        // 3. Remove extension dir to force clean install
+        const extensionDir = path.join(stateDir, 'extensions', pluginId)
+        if (fs.existsSync(extensionDir)) {
+          api.logger.info(`plugins: force — removing ${extensionDir}`)
+          await $`rm -rf ${extensionDir}`
+        }
+
+        // 4. Install fresh
+        api.logger.info(`plugins: force — installing ${installTarget}`)
+        const result = await $`openclaw plugins install ${installTarget}`
+        output = result.stdout.trim()
+
+        // 5. Merge saved config back into plugins.entries.<id>
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+          if (!config.plugins) config.plugins = {}
+          if (!config.plugins.entries) config.plugins.entries = {}
+          config.plugins.entries[pluginId] = {
+            ...config.plugins.entries[pluginId],
+            ...savedEntry,
+          }
+          fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+          api.logger.info(`plugins: force — restored entry config for ${pluginId}`)
+        } catch (err) {
+          api.logger.warn(
+            `plugins: force — failed to restore entry config: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+      } else if (strategy === 'update') {
+        const result = await $`openclaw plugins update ${pluginId}`
+        output = result.stdout.trim()
+      } else {
+        // install
+        const result = await $`openclaw plugins install ${installTarget}`
+        output = result.stdout.trim()
+      }
+
+      // Invalidate npm cache for this package
+      npmCache.delete(npmPkgName)
+
+      let restarted = false
+      if (restart) {
+        try {
+          await $`openclaw gateway restart`
+          restarted = true
+        } catch (err) {
+          api.logger.warn(
+            `plugins: gateway restart failed — ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+      }
+
+      respond(true, {ok: true, strategy, output, restarted})
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      api.logger.error(`plugins: update failed — ${msg}`)
+      respond(false, {ok: false, strategy, error: msg})
+    }
+  })
+
+  api.logger.info('plugins: registered clawly.plugins.version + clawly.plugins.update')
+}

package/{presence.ts → gateway/presence.ts}

@@ -7,7 +7,8 @@
 
 import {$} from 'zx'
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
+import {stripCliLogs} from '../lib/stripCliLogs'
 
 $.verbose = false
 
@@ -25,12 +26,7 @@ interface PresenceEntry {
 export async function isClientOnline(host = DEFAULT_HOST): Promise<boolean> {
   try {
     const result = await $`openclaw gateway call system-presence --json`
-    const output = result.stdout.trim()
-    let jsonStr = output
-    if (!output.startsWith('[')) {
-      jsonStr = output.slice(output.indexOf('\n['))
-    }
-    console.log({jsonStr})
+    const jsonStr = stripCliLogs(result.stdout)
     const entries: PresenceEntry[] = JSON.parse(jsonStr)
     const entry = entries.find((e) => e.host === host)
     if (!entry) return false

package/index.ts

@@ -1,5 +1,5 @@
 /**
- * OpenClaw plugin: Clawly utility RPC methods (clawly.*).
+ * OpenClaw plugin: Clawly utility RPC methods (clawly.*), memory browser, and ClawHub CLI bridge.
  *
  * Gateway methods:
  * - clawly.file.getOutbound — read a persisted outbound file by original-path hash
@@ -8,6 +8,9 @@
  * - clawly.notification.send    — send a push notification directly
  * - clawly.agent.send        — send a message to the agent (+ optional push)
  * - clawly.agent.echo        — echo-wrapped agent message (bypasses LLM)
+ * - memory-browser.list      — list all .md files in the memory directory
+ * - memory-browser.get       — return content of a single .md file
+ * - clawhub2gateway.*        — ClawHub CLI RPC bridge (search/install/update/list/explore/inspect/star/unstar)
  *
  * Agent tools:
  * - clawly_is_user_online    — check if user's device is connected
@@ -21,19 +24,29 @@
  * - before_tool_call      — enforces delivery fields on cron.create
  */
 
-import {registerAgentSend} from './agent-send'
 import {registerCalendar} from './calendar'
-import {registerIsUserOnlineTool, registerSendAppPushTool} from './tools'
 import {registerClawlyCronChannel} from './channel'
+import {registerCommands} from './command'
 import {registerCronHook} from './cron-hook'
-import {registerEchoCommand} from './echo'
 import {registerEmail} from './email'
+import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
-import {registerNotification} from './notification'
 import {registerOutboundHook, registerOutboundMethods} from './outbound'
-import {registerPresence} from './presence'
+import {registerTools} from './tools'
 
 type PluginRuntime = {
+  system?: {
+    runCommandWithTimeout?: (
+      argv: string[],
+      opts: {timeoutMs: number; cwd?: string; env?: Record<string, string | undefined>},
+    ) => Promise<{
+      stdout: string
+      stderr: string
+      code: number | null
+      signal: string | null
+      killed: boolean
+    }>
+  }
   state?: {
     resolveStateDir?: (env?: NodeJS.ProcessEnv) => string
   }
@@ -86,14 +99,11 @@ export default {
   register(api: PluginApi) {
     registerOutboundHook(api)
     registerOutboundMethods(api)
-    registerEchoCommand(api)
-    registerPresence(api)
-    registerNotification(api)
-    registerAgentSend(api)
-    registerIsUserOnlineTool(api)
-    registerSendAppPushTool(api)
+    registerCommands(api)
+    registerTools(api)
     registerClawlyCronChannel(api)
     registerCronHook(api)
+    registerGateway(api)
 
     // Email & calendar (optional — requires gatewayBaseUrl + gatewayToken in config)
     const gw = getGatewayConfig(api)

package/lib/lruCache.test.ts

@@ -0,0 +1,85 @@
+import {afterEach, beforeEach, describe, expect, jest, test} from 'bun:test'
+import {LruCache} from './lruCache'
+
+describe('LruCache', () => {
+  test('get returns undefined for missing key', () => {
+    const cache = new LruCache<string>({maxSize: 3, ttlMs: 60_000})
+    expect(cache.get('missing')).toBeUndefined()
+  })
+
+  test('set and get', () => {
+    const cache = new LruCache<number>({maxSize: 3, ttlMs: 60_000})
+    cache.set('a', 1)
+    expect(cache.get('a')).toBe(1)
+    expect(cache.size).toBe(1)
+  })
+
+  test('evicts oldest when over maxSize', () => {
+    const cache = new LruCache<number>({maxSize: 2, ttlMs: 60_000})
+    cache.set('a', 1)
+    cache.set('b', 2)
+    cache.set('c', 3)
+    expect(cache.get('a')).toBeUndefined()
+    expect(cache.get('b')).toBe(2)
+    expect(cache.get('c')).toBe(3)
+    expect(cache.size).toBe(2)
+  })
+
+  test('get refreshes position (prevents eviction)', () => {
+    const cache = new LruCache<number>({maxSize: 2, ttlMs: 60_000})
+    cache.set('a', 1)
+    cache.set('b', 2)
+    // Access 'a' to refresh its position
+    cache.get('a')
+    // Insert 'c' — should evict 'b' (now oldest) instead of 'a'
+    cache.set('c', 3)
+    expect(cache.get('a')).toBe(1)
+    expect(cache.get('b')).toBeUndefined()
+    expect(cache.get('c')).toBe(3)
+  })
+
+  test('expired entries return undefined', () => {
+    const now = Date.now()
+    jest.setSystemTime(new Date(now))
+
+    const cache = new LruCache<string>({maxSize: 5, ttlMs: 1000})
+    cache.set('x', 'val')
+    expect(cache.get('x')).toBe('val')
+
+    // Advance past TTL
+    jest.setSystemTime(new Date(now + 1001))
+    expect(cache.get('x')).toBeUndefined()
+    expect(cache.size).toBe(0)
+
+    jest.restoreAllMocks()
+  })
+
+  test('delete removes entry', () => {
+    const cache = new LruCache<number>({maxSize: 5, ttlMs: 60_000})
+    cache.set('a', 1)
+    expect(cache.delete('a')).toBe(true)
+    expect(cache.get('a')).toBeUndefined()
+    expect(cache.delete('a')).toBe(false)
+  })
+
+  test('clear removes all entries', () => {
+    const cache = new LruCache<number>({maxSize: 5, ttlMs: 60_000})
+    cache.set('a', 1)
+    cache.set('b', 2)
+    cache.clear()
+    expect(cache.size).toBe(0)
+    expect(cache.get('a')).toBeUndefined()
+  })
+
+  test('overwriting a key updates value and refreshes position', () => {
+    const cache = new LruCache<number>({maxSize: 2, ttlMs: 60_000})
+    cache.set('a', 1)
+    cache.set('b', 2)
+    cache.set('a', 10)
+    // 'a' is refreshed, 'b' is oldest
+    cache.set('c', 3)
+    expect(cache.get('a')).toBe(10)
+    expect(cache.get('b')).toBeUndefined()
+    expect(cache.get('c')).toBe(3)
+  })
+})

package/lib/lruCache.ts

@@ -0,0 +1,50 @@
+interface CacheEntry<V> {
+  value: V
+  expiresAt: number
+}
+
+export class LruCache<V> {
+  private map = new Map<string, CacheEntry<V>>()
+  private maxSize: number
+  private ttlMs: number
+
+  constructor(opts: {maxSize: number; ttlMs: number}) {
+    this.maxSize = opts.maxSize
+    this.ttlMs = opts.ttlMs
+  }
+
+  get(key: string): V | undefined {
+    const entry = this.map.get(key)
+    if (!entry) return undefined
+    if (Date.now() > entry.expiresAt) {
+      this.map.delete(key)
+      return undefined
+    }
+    // Refresh position: delete and re-insert (Map preserves insertion order)
+    this.map.delete(key)
+    this.map.set(key, entry)
+    return entry.value
+  }
+
+  set(key: string, value: V): void {
+    this.map.delete(key)
+    if (this.map.size >= this.maxSize) {
+      // Evict oldest (first entry)
+      const oldest = this.map.keys().next().value
+      if (oldest !== undefined) this.map.delete(oldest)
+    }
+    this.map.set(key, {value, expiresAt: Date.now() + this.ttlMs})
+  }
+
+  delete(key: string): boolean {
+    return this.map.delete(key)
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+}