@2en/clawly-plugins 1.0.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

@@ -3,12 +3,24 @@
  *
  * Gateway methods:
  * - 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
+ * - tool_result_persist   — copies TTS audio to persistent outbound directory
  */
 
+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?: {
@@ -34,6 +46,13 @@ export type PluginApi = {
     }) => 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 {
@@ -43,6 +62,10 @@ export default {
   register(api: PluginApi) {
     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

@@ -80,24 +80,9 @@ export function registerOutboundMethods(api: PluginApi) {
     }
 
     const buffer = fs.readFileSync(dest)
-
-    const EXT_MIME: Record<string, string> = {
-      '.mp3': 'audio/mpeg',
-      '.wav': 'audio/wav',
-      '.m4a': 'audio/mp4',
-      '.ogg': 'audio/ogg',
-      '.aac': 'audio/aac',
-      '.flac': 'audio/flac',
-      '.webm': 'audio/webm',
-    }
-    const mimeType = EXT_MIME[path.extname(dest).toLowerCase()] ?? 'application/octet-stream'
-
     const base64 = buffer.toString('base64')
-    const filename = path.basename(rawPath)
 
-    api.logger.info(
-      `clawly.file.getOutbound: served ${filename} (${mimeType}, ${buffer.length} bytes)`,
-    )
-    respond(true, {base64, mimeType, filename})
+    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": "1.0.0",
+  "version": "1.1.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -8,9 +8,16 @@
     "url": "https://github.com/2enai/clawly",
     "directory": "plugins/clawly-plugins"
   },
+  "dependencies": {
+    "zx": "npm:zx@8.8.5-lite"
+  },
   "files": [
     "index.ts",
     "outbound.ts",
+    "echo.ts",
+    "presence.ts",
+    "notification.ts",
+    "agent-send.ts",
     "openclaw.plugin.json"
   ],
   "openclaw": {

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')
+}