@2en/clawly-plugins 1.2.0 → 1.3.1

package/channel.ts

@@ -0,0 +1,94 @@
+/**
+ * Clawly cron delivery channel — registers a minimal channel plugin so that
+ * cron jobs using `delivery: { channel: "clawly-cron" }` have a valid target.
+ *
+ * When a cron job delivers text, the channel injects it into the main session
+ * transcript via chat.inject (no LLM round-trip) and sends a push notification
+ * if the mobile client is offline.
+ */
+
+import {$} from 'zx'
+import type {PluginApi} from './index'
+import {sendPushNotification} from './notification'
+import {isClientOnline} from './presence'
+
+$.verbose = false
+
+async function injectAndNotify(text: string, api: PluginApi): Promise<void> {
+  try {
+    // Resolve main session key from config
+    const config = api.pluginConfig as Record<string, unknown> | undefined
+    const agentId = typeof config?.agentId === 'string' ? config.agentId : 'clawly'
+    const mainKey = typeof config?.mainKey === 'string' ? config.mainKey : 'main'
+    const sessionKey = `agent:${agentId}:${mainKey}`
+
+    const params = JSON.stringify({sessionKey, message: text})
+    await $`openclaw gateway call chat.inject --json --params ${params}`
+    api.logger.info(`clawly-cron: injected message (${text.length} chars) into ${sessionKey}`)
+
+    // Push notification if client is offline
+    const online = await isClientOnline()
+    if (!online) {
+      const pushSent = await sendPushNotification({body: text}, api)
+      api.logger.info(`clawly-cron: push notification sent=${pushSent}`)
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    api.logger.error(`clawly-cron: failed to inject message — ${msg}`)
+  }
+}
+
+export function registerClawlyCronChannel(api: PluginApi) {
+  const channelRegistration = {
+    plugin: {
+      id: 'clawly-cron',
+      meta: {
+        id: 'clawly-cron',
+        label: 'Clawly Cron',
+        selectionLabel: 'Clawly Cron (webchat)',
+        docsPath: '',
+        blurb: 'Webchat-only cron delivery channel',
+      },
+      capabilities: {chatTypes: ['dm'] as const},
+      config: {
+        listAccountIds: () => ['default'],
+        resolveAccount: () => ({id: 'default'}),
+        defaultAccountId: () => 'default',
+        isEnabled: () => true,
+        isConfigured: () => true,
+      },
+      status: {
+        buildAccountSnapshot: async () => ({
+          accountId: 'default',
+          enabled: true,
+          configured: true,
+          running: true,
+        }),
+        buildChannelSummary: async () => ({
+          configured: true,
+          running: true,
+        }),
+      },
+      outbound: {
+        deliveryMode: 'direct' as const,
+        sendText: async (...args: unknown[]) => {
+          const firstArg = args[0] as Record<string, unknown> | undefined
+          const text = typeof firstArg?.text === 'string' ? firstArg.text : ''
+          api.logger.info(`clawly-cron sendText: text=${text.length} chars`)
+          if (text) {
+            // Fire-and-forget — delivery system may not await sendText
+            injectAndNotify(text, api).catch(() => {})
+          }
+          return {channel: 'clawly-cron', messageId: crypto.randomUUID()}
+        },
+        sendMedia: async (...args: unknown[]) => {
+          api.logger.info(`clawly-cron sendMedia: ${JSON.stringify(args)}`)
+          return {channel: 'clawly-cron', messageId: crypto.randomUUID()}
+        },
+      },
+    },
+  }
+
+  api.registerChannel(channelRegistration)
+  api.logger.info('channel: registered clawly-cron delivery channel')
+}

package/cron-hook.ts

@@ -0,0 +1,66 @@
+/**
+ * before_tool_call hook for cron (action=add) — ensures delivery fields are
+ * always set correctly, even when the LLM omits them.
+ *
+ * Forces: delivery.channel = "clawly-cron", delivery.to = "self", delivery.mode = "announce"
+ * Patches: payload.kind "systemEvent" → "agentTurn"
+ *
+ * The cron tool name is "cron" (not "cron.create"). The LLM passes
+ * { action: "add", job: { delivery, payload, ... } } — delivery and payload
+ * live inside params.job (or at the top level for flat-params recovery).
+ */
+
+import type {PluginApi} from './index'
+
+type UnknownRecord = Record<string, unknown>
+
+function isRecord(v: unknown): v is UnknownRecord {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+function patchJob(job: UnknownRecord): UnknownRecord {
+  const patched: UnknownRecord = {...job}
+
+  // Force delivery fields
+  const delivery = isRecord(job.delivery) ? job.delivery : {}
+  patched.delivery = {
+    ...delivery,
+    mode: 'announce',
+    channel: 'clawly-cron',
+    to: 'self',
+  }
+
+  // Patch payload.kind: systemEvent → agentTurn
+  if (isRecord(job.payload) && job.payload.kind === 'systemEvent') {
+    patched.payload = {...job.payload, kind: 'agentTurn'}
+  }
+
+  return patched
+}
+
+export function registerCronHook(api: PluginApi) {
+  api.on('before_tool_call', (event: {toolName: string; params: UnknownRecord}) => {
+    if (event.toolName !== 'cron') return
+    if (event.params.action !== 'add') return
+
+    const params: UnknownRecord = {}
+
+    // Patch job object if present (normal path)
+    if (isRecord(event.params.job)) {
+      params.job = patchJob(event.params.job)
+    } else {
+      // Flat-params recovery: delivery/payload may be at the top level
+      if ('delivery' in event.params || 'payload' in event.params) {
+        const synthetic = {...event.params}
+        delete synthetic.action
+        Object.assign(params, patchJob(synthetic))
+      }
+    }
+
+    if (Object.keys(params).length === 0) return
+
+    return {params}
+  })
+
+  api.logger.info('hook: registered before_tool_call for cron add delivery enforcement')
+}

package/index.ts

@@ -18,10 +18,13 @@
  *
  * Hooks:
  * - tool_result_persist   — copies TTS audio to persistent outbound directory
+ * - before_tool_call      — enforces delivery fields on cron.create
  */
 
 import {registerAgentSend} from './agent-send'
 import {registerIsUserOnlineTool, registerSendAppPushTool} from './tools'
+import {registerClawlyCronChannel} from './channel'
+import {registerCronHook} from './cron-hook'
 import {registerEchoCommand} from './echo'
 import {registerNotification} from './notification'
 import {registerOutboundHook, registerOutboundMethods} from './outbound'
@@ -70,6 +73,7 @@ export type PluginApi = {
     },
     opts?: {optional?: boolean},
   ) => void
+  registerChannel: (registration: {plugin: any}) => void
 }
 
 export default {
@@ -85,6 +89,8 @@ export default {
     registerAgentSend(api)
     registerIsUserOnlineTool(api)
     registerSendAppPushTool(api)
+    registerClawlyCronChannel(api)
+    registerCronHook(api)
     api.logger.info(`Loaded ${api.id} plugin.`)
   },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -12,7 +12,10 @@
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [
+    "tools",
     "index.ts",
+    "channel.ts",
+    "cron-hook.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`)
+}