@2en/clawly-plugins 0.1.0 → 1.1.0

package/agent-send.ts

@@ -0,0 +1,93 @@
+/**
+ * Agent messaging gateway methods — send messages to the agent from
+ * external callers (cron, other agents) and optionally push-notify
+ * when the mobile client is offline.
+ *
+ * Methods:
+ * - clawly.agent.send  — run `openclaw agent --message <msg>`
+ * - clawly.agent.echo  — same, but wraps message as `/clawly.echo <msg>`
+ */
+
+import {$} from 'zx'
+import type {PluginApi} from './index'
+import {sendPushNotification} from './notification'
+import {isClientOnline} from './presence'
+
+// Suppress zx default stdout logging
+$.verbose = false
+
+interface AgentSendParams {
+  message: string
+  notificationMessage?: string
+}
+
+interface AgentSendResult {
+  ok: boolean
+  online: boolean
+  pushSent: boolean
+}
+
+async function runAgentMessage(
+  message: string,
+  api: PluginApi,
+): Promise<{ok: boolean; error?: string}> {
+  try {
+    await $`openclaw agent --agent main --message ${message}`
+    return {ok: true}
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    api.logger.error(`agent-send: openclaw agent failed — ${msg}`)
+    return {ok: false, error: msg}
+  }
+}
+
+async function handleAgentSend(
+  rawMessage: string,
+  params: AgentSendParams,
+  api: PluginApi,
+): Promise<AgentSendResult> {
+  const {ok} = await runAgentMessage(rawMessage, api)
+  const online = await isClientOnline()
+
+  let pushSent = false
+  if (!online && params.notificationMessage) {
+    pushSent = await sendPushNotification({body: params.notificationMessage}, api)
+  }
+
+  return {ok, online, pushSent}
+}
+
+export function registerAgentSend(api: PluginApi) {
+  // clawly.agent.send — send a raw message to the agent
+  api.registerGatewayMethod('clawly.agent.send', async ({params, respond}) => {
+    const message = typeof params.message === 'string' ? params.message.trim() : ''
+    if (!message) {
+      respond(false, undefined, {code: 'invalid_params', message: 'message is required'})
+      return
+    }
+
+    const notificationMessage =
+      typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined
+
+    const result = await handleAgentSend(message, {message, notificationMessage}, api)
+    respond(result.ok, result)
+  })
+
+  // clawly.agent.echo — send an echo-wrapped message (bypasses LLM)
+  api.registerGatewayMethod('clawly.agent.echo', async ({params, respond}) => {
+    const message = typeof params.message === 'string' ? params.message.trim() : ''
+    if (!message) {
+      respond(false, undefined, {code: 'invalid_params', message: 'message is required'})
+      return
+    }
+
+    const notificationMessage =
+      typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined
+
+    const echoMessage = `/clawly_echo ${message}`
+    const result = await handleAgentSend(echoMessage, {message, notificationMessage}, api)
+    respond(result.ok, result)
+  })
+
+  api.logger.info('agent-send: registered clawly.agent.send + clawly.agent.echo methods')
+}

package/echo.ts

@@ -0,0 +1,21 @@
+/**
+ * Echo command — `/clawly_echo <text>` replies directly without
+ * invoking the LLM.
+ */
+
+import type {PluginApi} from './index'
+
+export function registerEchoCommand(api: PluginApi) {
+  api.registerCommand({
+    name: 'clawly_echo',
+    description: 'Echo text back without invoking the LLM',
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const text = ctx.args?.trim() || ''
+      if (!text) return {text: 'Usage: /clawly_echo <message>'}
+      return {text}
+    },
+  })
+
+  api.logger.info('echo: registered /clawly_echo command')
+}

package/index.ts

@@ -2,10 +2,25 @@
  * OpenClaw plugin: Clawly utility RPC methods (clawly.*).
  *
  * Gateway methods:
- * - clawly.file.get — read a local file and return base64-encoded content
+ * - clawly.file.getOutbound — read a persisted outbound file by original-path hash
+ * - clawly.isOnline          — check if a mobile client is connected
+ * - clawly.notification.setToken — register Expo push token for offline notifications
+ * - 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)
+ *
+ * Commands:
+ * - /clawly_echo          — echo text back without LLM
+ *
+ * Hooks:
+ * - tool_result_persist   — copies TTS audio to persistent outbound directory
  */
 
-import {registerFileMethods} from './file'
+import {registerAgentSend} from './agent-send'
+import {registerEchoCommand} from './echo'
+import {registerNotification} from './notification'
+import {registerOutboundHook, registerOutboundMethods} from './outbound'
+import {registerPresence} from './presence'
 
 type PluginRuntime = {
   state?: {
@@ -30,6 +45,14 @@ export type PluginApi = {
       respond: (ok: boolean, payload?: unknown, error?: {code?: string; message?: string}) => void
     }) => Promise<void> | void,
   ) => void
+  on: (hookName: string, handler: (...args: any[]) => any, opts?: {priority?: number}) => void
+  registerCommand: (cmd: {
+    name: string
+    description?: string
+    acceptsArgs?: boolean
+    requireAuth?: boolean
+    handler: (ctx: {args?: string}) => Promise<{text: string}> | {text: string}
+  }) => void
 }
 
 export default {
@@ -37,7 +60,12 @@ export default {
   name: 'Clawly Plugins',
   description: 'Clawly utility RPC methods (clawly.*).',
   register(api: PluginApi) {
-    registerFileMethods(api)
+    registerOutboundHook(api)
+    registerOutboundMethods(api)
+    registerEchoCommand(api)
+    registerPresence(api)
+    registerNotification(api)
+    registerAgentSend(api)
     api.logger.info(`Loaded ${api.id} plugin.`)
   },
 }

package/notification.ts

@@ -0,0 +1,130 @@
+/**
+ * Expo push notification support — stores the device push token
+ * and sends notifications via Expo's push API.
+ *
+ * Methods:
+ * - clawly.notification.setToken({ token }) → { registered: boolean }
+ * - clawly.notification.send({ body, title?, data? }) → { sent: boolean }
+ *
+ * Internal: sendPushNotification({ body, title?, data? })
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+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')
+const EXPO_PUSH_URL = 'https://exp.host/--/api/v2/push/send'
+
+let pushToken: string | null = null
+
+function loadPersistedToken(api: PluginApi): void {
+  try {
+    if (fs.existsSync(TOKEN_FILE)) {
+      const data = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf-8'))
+      if (typeof data.token === 'string' && data.token) {
+        pushToken = data.token
+        api.logger.info(`notification: loaded persisted push token`)
+      }
+    }
+  } catch (err) {
+    api.logger.warn(
+      `notification: failed to load persisted token: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+}
+
+function persistToken(token: string, api: PluginApi): void {
+  try {
+    fs.mkdirSync(TOKEN_DIR, {recursive: true})
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify({token}, null, 2))
+  } catch (err) {
+    api.logger.warn(
+      `notification: failed to persist token: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+}
+
+export function getPushToken(): string | null {
+  return pushToken
+}
+
+export async function sendPushNotification(
+  opts: {body: string; title?: string; data?: Record<string, unknown>},
+  api: PluginApi,
+): Promise<boolean> {
+  if (!pushToken) {
+    api.logger.warn('notification: no push token registered, skipping notification')
+    return false
+  }
+
+  try {
+    const res = await fetch(EXPO_PUSH_URL, {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        to: pushToken,
+        sound: 'default',
+        title: opts.title ?? 'Clawly',
+        body: opts.body,
+        data: opts.data,
+      }),
+    })
+
+    if (!res.ok) {
+      api.logger.error(`notification: push failed — ${res.status} ${res.statusText}`)
+      return false
+    }
+
+    api.logger.info(`notification: push sent — "${opts.body}"`)
+    return true
+  } catch (err) {
+    api.logger.error(
+      `notification: push failed — ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return false
+  }
+}
+
+export function registerNotification(api: PluginApi) {
+  loadPersistedToken(api)
+
+  api.registerGatewayMethod('clawly.notification.setToken', async ({params, respond}) => {
+    const token = typeof params.token === 'string' ? params.token.trim() : ''
+
+    if (!token) {
+      respond(false, undefined, {code: 'invalid_params', message: 'token is required'})
+      return
+    }
+
+    pushToken = token
+    persistToken(token, api)
+    api.logger.info('notification: push token registered')
+    respond(true, {registered: true})
+  })
+
+  api.registerGatewayMethod('clawly.notification.send', async ({params, respond}) => {
+    const body = typeof params.body === 'string' ? params.body.trim() : ''
+
+    if (!body) {
+      respond(false, undefined, {code: 'invalid_params', message: 'body is required'})
+      return
+    }
+
+    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
+
+    const sent = await sendPushNotification({body, title, data}, api)
+    respond(sent, {sent})
+  })
+
+  api.logger.info(
+    'notification: registered clawly.notification.setToken + clawly.notification.send',
+  )
+}

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "clawly-plugins",
   "name": "Clawly Plugins",
-  "description": "Clawly utility RPC methods (clawly.*): file access.",
-  "version": "0.1.0",
+  "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, and agent messaging.",
+  "version": "0.2.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/outbound.ts

@@ -0,0 +1,88 @@
+/**
+ * TTS outbound persistence — copies ephemeral TTS audio to a persistent directory
+ * so mobile can fetch it after the temp files are cleaned up.
+ *
+ * Hook:   tool_result_persist → copies TTS audioPath to ~/.openclaw/clawly/outbound/<hash>.<ext>
+ * Method: clawly.file.getOutbound → reads outbound file by original-path hash
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import type {PluginApi} from './index'
+
+const OUTBOUND_DIR = path.join(os.homedir(), '.openclaw', 'clawly', 'outbound')
+
+function hashPath(filePath: string): string {
+  return crypto.createHash('sha256').update(filePath).digest('hex')
+}
+
+function outboundFilePath(originalPath: string): string {
+  const hash = hashPath(originalPath)
+  const ext = path.extname(originalPath) // e.g. ".mp3"
+  return path.join(OUTBOUND_DIR, `${hash}${ext}`)
+}
+
+function ensureOutboundDir(): void {
+  fs.mkdirSync(OUTBOUND_DIR, {recursive: true})
+}
+
+// ── Hook: tool_result_persist ───────────────────────────────────────
+
+export function registerOutboundHook(api: PluginApi) {
+  api.on(
+    'tool_result_persist',
+    (event: {toolName?: string; message?: {details?: {audioPath?: string}}}) => {
+      if (event.toolName !== 'tts') return
+      const audioPath = event.message?.details?.audioPath
+      if (!audioPath) return
+
+      try {
+        const dest = outboundFilePath(audioPath)
+        if (fs.existsSync(dest)) return // idempotent
+
+        if (!fs.existsSync(audioPath)) {
+          api.logger.warn(`outbound: source file missing, skipping copy: ${audioPath}`)
+          return
+        }
+
+        ensureOutboundDir()
+        fs.copyFileSync(audioPath, dest)
+        api.logger.info(`outbound: persisted ${audioPath} → ${dest}`)
+      } catch (err) {
+        api.logger.error(
+          `outbound: failed to persist ${audioPath}: ${err instanceof Error ? err.message : String(err)}`,
+        )
+      }
+    },
+  )
+}
+
+// ── Gateway method: clawly.file.getOutbound ─────────────────────────
+
+export function registerOutboundMethods(api: PluginApi) {
+  api.registerGatewayMethod('clawly.file.getOutbound', async ({params, respond}) => {
+    const rawPath = typeof params.path === 'string' ? params.path.trim() : ''
+
+    if (!rawPath) {
+      respond(false, undefined, {code: 'invalid_params', message: 'path is required'})
+      return
+    }
+
+    const dest = outboundFilePath(rawPath)
+
+    if (!fs.existsSync(dest)) {
+      api.logger.warn(`outbound: file not found: ${rawPath} ${dest}`)
+      respond(false, undefined, {code: 'not_found', message: 'outbound file not found'})
+      return
+    }
+
+    const buffer = fs.readFileSync(dest)
+    const base64 = buffer.toString('base64')
+
+    api.logger.info(`clawly.file.getOutbound: served ${rawPath} (${buffer.length} bytes)`)
+    respond(true, {base64})
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -8,14 +8,18 @@
     "url": "https://github.com/2enai/clawly",
     "directory": "plugins/clawly-plugins"
   },
+  "dependencies": {
+    "zx": "npm:zx@8.8.5-lite"
+  },
   "files": [
     "index.ts",
-    "file.ts",
+    "outbound.ts",
+    "echo.ts",
+    "presence.ts",
+    "notification.ts",
+    "agent-send.ts",
     "openclaw.plugin.json"
   ],
-  "dependencies": {
-    "file-type": "^19.6.0"
-  },
   "openclaw": {
     "extensions": [
       "./index.ts"

package/presence.ts

@@ -0,0 +1,51 @@
+/**
+ * Online presence check — queries `system-presence` via the gateway CLI
+ * and checks if the mobile client (`openclaw-ios`) is connected.
+ *
+ * Method: clawly.isOnline({ host? }) → { isOnline: boolean }
+ */
+
+import {$} from 'zx'
+
+import type {PluginApi} from './index'
+
+$.verbose = false
+
+const DEFAULT_HOST = 'openclaw-ios'
+
+interface PresenceEntry {
+  host?: string
+  reason?: string
+}
+
+/**
+ * Shells out to `openclaw gateway call system-presence` and checks
+ * whether the given host has a non-"disconnect" entry.
+ */
+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 entries: PresenceEntry[] = JSON.parse(jsonStr)
+    const entry = entries.find((e) => e.host === host)
+    if (!entry) return false
+    return entry.reason === 'connect'
+  } catch {
+    return false
+  }
+}
+
+export function registerPresence(api: PluginApi) {
+  api.registerGatewayMethod('clawly.isOnline', async ({params, respond}) => {
+    const host = typeof params.host === 'string' ? params.host : DEFAULT_HOST
+    const isOnline = await isClientOnline(host)
+    respond(true, {isOnline})
+  })
+
+  api.logger.info('presence: registered clawly.isOnline method')
+}

package/file.ts

@@ -1,161 +0,0 @@
-/**
- * clawly.file.get — read a file from the local filesystem and return it as base64.
- *
- * Validates: absolute path, no traversal, MIME whitelist, 50 MB size limit.
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import {fileTypeFromBuffer} from 'file-type'
-
-import type {PluginApi} from './index'
-
-const MAX_FILE_SIZE = 50 * 1024 * 1024 // 50 MB
-
-const ALLOWED_MIME_PREFIXES = ['image/', 'video/', 'audio/']
-
-/** Extensions allowed via fallback when file-type cannot detect MIME (e.g. plain text). */
-const DOCUMENT_EXT_WHITELIST = new Set([
-  'pdf',
-  'doc',
-  'docx',
-  'xls',
-  'xlsx',
-  'ppt',
-  'pptx',
-  'txt',
-  'csv',
-  'rtf',
-])
-
-const EXT_TO_MIME: Record<string, string> = {
-  pdf: 'application/pdf',
-  doc: 'application/msword',
-  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-  xls: 'application/vnd.ms-excel',
-  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-  ppt: 'application/vnd.ms-powerpoint',
-  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  txt: 'text/plain',
-  csv: 'text/csv',
-  rtf: 'application/rtf',
-}
-
-function getExtension(filePath: string): string {
-  const dot = filePath.lastIndexOf('.')
-  return dot === -1 ? '' : filePath.slice(dot + 1).toLowerCase()
-}
-
-function getFilename(filePath: string): string {
-  return path.basename(filePath)
-}
-
-export function registerFileMethods(api: PluginApi) {
-  api.registerGatewayMethod('clawly.file.get', async ({params, respond}) => {
-    const rawPath = typeof params.path === 'string' ? params.path.trim() : ''
-
-    // ── Validate path ──────────────────────────────────────────────
-    if (!rawPath) {
-      respond(false, undefined, {code: 'invalid_params', message: 'path is required'})
-      return
-    }
-
-    if (!path.isAbsolute(rawPath)) {
-      respond(false, undefined, {code: 'invalid_params', message: 'path must be absolute'})
-      return
-    }
-
-    const normalized = path.normalize(rawPath)
-
-    // Resolve symlinks and verify the real path matches the normalized expectation
-    let realPath: string
-    try {
-      realPath = await fs.realpath(normalized)
-    } 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(
-        `clawly.file.get realpath failed: ${err instanceof Error ? err.message : String(err)}`,
-      )
-      respond(false, undefined, {code: 'error', message: 'failed to resolve path'})
-      return
-    }
-
-    // ── Size check ─────────────────────────────────────────────────
-    let stat: Awaited<ReturnType<typeof fs.stat>>
-    try {
-      stat = await fs.stat(realPath)
-    } 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(
-        `clawly.file.get stat failed: ${err instanceof Error ? err.message : String(err)}`,
-      )
-      respond(false, undefined, {code: 'error', message: 'failed to stat file'})
-      return
-    }
-
-    if (!stat.isFile()) {
-      respond(false, undefined, {code: 'invalid_params', message: 'path is not a regular file'})
-      return
-    }
-
-    if (stat.size > MAX_FILE_SIZE) {
-      respond(false, undefined, {
-        code: 'file_too_large',
-        message: `file exceeds ${MAX_FILE_SIZE / 1024 / 1024} MB limit`,
-      })
-      return
-    }
-
-    // ── Read file ──────────────────────────────────────────────────
-    let buffer: Buffer
-    try {
-      buffer = await fs.readFile(realPath)
-    } catch (err) {
-      api.logger.error(
-        `clawly.file.get readFile failed: ${err instanceof Error ? err.message : String(err)}`,
-      )
-      respond(false, undefined, {code: 'error', message: 'failed to read file'})
-      return
-    }
-
-    // ── MIME detection ─────────────────────────────────────────────
-    let mimeType: string | undefined
-
-    const detected = await fileTypeFromBuffer(buffer)
-    if (detected) {
-      mimeType = detected.mime
-    }
-
-    // Check against allowed MIME prefixes
-    if (mimeType && ALLOWED_MIME_PREFIXES.some((prefix) => mimeType!.startsWith(prefix))) {
-      // Allowed media type
-    } else {
-      // Fallback: check document extension whitelist
-      const ext = getExtension(realPath)
-      if (DOCUMENT_EXT_WHITELIST.has(ext)) {
-        mimeType = EXT_TO_MIME[ext] ?? 'application/octet-stream'
-      } else {
-        respond(false, undefined, {
-          code: 'unsupported_type',
-          message: `file type not allowed: ${mimeType ?? `unknown (ext: .${ext || '?'})`}`,
-        })
-        return
-      }
-    }
-
-    // ── Respond ────────────────────────────────────────────────────
-    const base64 = buffer.toString('base64')
-    const filename = getFilename(realPath)
-
-    api.logger.info(`clawly.file.get: served ${filename} (${mimeType}, ${buffer.length} bytes)`)
-    respond(true, {base64, mimeType, filename})
-  })
-}