@2en/clawly-plugins 1.3.0 → 1.4.0

package/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/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
@@ -24,13 +27,27 @@
 import {registerAgentSend} from './agent-send'
 import {registerIsUserOnlineTool, registerSendAppPushTool} from './tools'
 import {registerClawlyCronChannel} from './channel'
+import {registerClawhub2gateway} from './clawhub2gateway'
 import {registerCronHook} from './cron-hook'
 import {registerEchoCommand} from './echo'
+import {registerMemoryBrowser} from './memory'
 import {registerNotification} from './notification'
 import {registerOutboundHook, registerOutboundMethods} from './outbound'
 import {registerPresence} from './presence'
 
 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
   }
@@ -91,6 +108,8 @@ export default {
     registerSendAppPushTool(api)
     registerClawlyCronChannel(api)
     registerCronHook(api)
+    registerMemoryBrowser(api)
+    registerClawhub2gateway(api)
     api.logger.info(`Loaded ${api.id} plugin.`)
   },
 }

package/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/openclaw.plugin.json

@@ -1,12 +1,52 @@
 {
   "id": "clawly-plugins",
   "name": "Clawly Plugins",
-  "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, and agent messaging.",
+  "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, agent messaging, memory browser, and ClawHub CLI bridge.",
   "version": "0.2.0",
+  "uiHints": {
+    "memoryDir": {
+      "label": "Memory directory",
+      "help": "Absolute path to the memory directory containing .md files. Defaults to <OPENCLAW_WORKSPACE>/memory.",
+      "placeholder": "/data/memory"
+    },
+    "bin": {
+      "label": "clawhub binary",
+      "help": "Command to run (must be in PATH on the gateway host).",
+      "placeholder": "clawhub"
+    },
+    "defaultDir": {
+      "label": "Default skills dir",
+      "help": "Maps to `clawhub --dir` when not provided per-call.",
+      "placeholder": "skills"
+    },
+    "defaultNoInput": {
+      "label": "Default no-input",
+      "help": "If true, adds `--no-input` unless the tool call overrides it.",
+      "advanced": true
+    },
+    "defaultTimeoutMs": {
+      "label": "Default timeout (ms)",
+      "help": "Default command timeout for most tool calls.",
+      "advanced": true
+    },
+    "configPath": {
+      "label": "CLAWHUB_CONFIG_PATH",
+      "help": "Where the ClawHub CLI stores auth/config. Defaults to `<OPENCLAW_STATE_DIR>/clawhub/config.json`.",
+      "advanced": true,
+      "placeholder": "~/.openclaw/clawhub/config.json"
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {},
+    "properties": {
+      "memoryDir": { "type": "string", "minLength": 1 },
+      "bin": { "type": "string", "minLength": 1 },
+      "defaultDir": { "type": "string", "minLength": 1 },
+      "defaultNoInput": { "type": "boolean" },
+      "defaultTimeoutMs": { "type": "number", "minimum": 1000 },
+      "configPath": { "type": "string" }
+    },
     "required": []
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -12,9 +12,12 @@
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [
+    "tools",
     "index.ts",
     "channel.ts",
+    "clawhub2gateway.ts",
     "cron-hook.ts",
+    "memory.ts",
     "outbound.ts",
     "echo.ts",
     "presence.ts",

package/tools/clawly-is-user-online.ts

@@ -0,0 +1,35 @@
+/**
+ * Agent tool: clawly_is_user_online — check if the user's mobile
+ * device is currently connected to the OpenClaw gateway.
+ *
+ */
+
+import type {PluginApi} from '../index'
+import {isClientOnline} from '../presence'
+
+const TOOL_NAME = 'clawly_is_user_online'
+
+const parameters: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    host: {
+      type: 'string',
+      description: 'Presence host identifier (default: "openclaw-ios")',
+    },
+  },
+}
+
+export function registerIsUserOnlineTool(api: PluginApi) {
+  api.registerTool({
+    name: TOOL_NAME,
+    description: "Check if the user's mobile device is currently online.",
+    parameters,
+    async execute(_toolCallId, params) {
+      const host = typeof params.host === 'string' ? params.host : undefined
+      const isOnline = await isClientOnline(host)
+      return {content: [{type: 'text', text: JSON.stringify({isOnline})}]}
+    },
+  })
+
+  api.logger.info(`tool: registered ${TOOL_NAME} agent tool`)
+}

package/tools/clawly-send-app-push.ts

@@ -0,0 +1,80 @@
+/**
+ * Agent tool: clawly_send_app_push — send a push notification to
+ * the user's phone from the LLM agent during a conversation.
+ *
+ * Expo push API reference:
+ * https://docs.expo.dev/push-notifications/sending-notifications/
+ */
+
+import type {PluginApi} from '../index'
+import {sendPushNotification} from '../notification'
+
+const TOOL_NAME = 'clawly_send_app_push'
+
+const parameters: Record<string, unknown> = {
+  type: 'object',
+  required: ['body'],
+  properties: {
+    body: {type: 'string', description: 'Notification message'},
+    title: {type: 'string', description: 'Title (default: "Clawly")'},
+    subtitle: {type: 'string', description: 'iOS subtitle'},
+    sound: {
+      type: ['string', 'null'],
+      description: 'Sound name (default: "default")',
+    },
+    badge: {type: 'number', description: 'iOS badge count'},
+    data: {type: 'object', description: 'Custom JSON payload'},
+    ttl: {type: 'number', description: 'Seconds to keep for redelivery'},
+    expiration: {type: 'number', description: 'Unix timestamp expiry'},
+    priority: {
+      type: 'string',
+      enum: ['default', 'normal', 'high'],
+      description: 'Delivery priority',
+    },
+    channelId: {type: 'string', description: 'Android notification channel'},
+    categoryId: {type: 'string', description: 'Notification category'},
+    interruptionLevel: {
+      type: 'string',
+      enum: ['active', 'critical', 'passive', 'time-sensitive'],
+      description: 'iOS interruption level',
+    },
+    mutableContent: {type: 'boolean', description: 'iOS mutable content'},
+    richContent: {
+      type: 'object',
+      description: 'Rich content (e.g. {image: url})',
+    },
+  },
+}
+
+export function registerSendAppPushTool(api: PluginApi) {
+  api.registerTool({
+    name: TOOL_NAME,
+    description: "Send a push notification to the user's phone.",
+    parameters,
+    async execute(_toolCallId, params) {
+      const body = typeof params.body === 'string' ? params.body.trim() : ''
+      if (!body) {
+        return {content: [{type: 'text', text: JSON.stringify({error: 'body is required'})}]}
+      }
+
+      const title = typeof params.title === 'string' ? params.title : undefined
+      const data =
+        typeof params.data === 'object' && params.data !== null
+          ? (params.data as Record<string, unknown>)
+          : undefined
+
+      // Collect Expo-specific extras (everything except body/title/data)
+      const {body: _body, title: _title, data: _data, ...extras} = params
+      const hasExtras = Object.keys(extras).length > 0
+
+      const sent = await sendPushNotification(
+        {body, title, data},
+        api,
+        hasExtras ? extras : undefined,
+      )
+      return {content: [{type: 'text', text: JSON.stringify({sent})}]}
+    },
+  })
+
+  api.logger.info(`tool: registered ${TOOL_NAME} agent tool`)
+}