@2en/clawly-plugins 1.1.2 → 1.3.0

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

@@ -9,14 +9,22 @@
  * - clawly.agent.send        — send a message to the agent (+ optional push)
  * - clawly.agent.echo        — echo-wrapped agent message (bypasses LLM)
  *
+ * Agent tools:
+ * - clawly_is_user_online    — check if user's device is connected
+ * - clawly_send_app_push     — send a push notification to user's device
+ *
  * Commands:
  * - /clawly_echo          — echo text back without LLM
  *
  * 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'
@@ -53,6 +61,19 @@ export type PluginApi = {
     requireAuth?: boolean
     handler: (ctx: {args?: string}) => Promise<{text: string}> | {text: string}
   }) => void
+  registerTool: (
+    tool: {
+      name: string
+      description: string
+      parameters: Record<string, unknown>
+      execute: (
+        toolCallId: string,
+        params: Record<string, unknown>,
+      ) => Promise<{content: Array<{type: string; text: string}>; details?: unknown}>
+    },
+    opts?: {optional?: boolean},
+  ) => void
+  registerChannel: (registration: {plugin: any}) => void
 }
 
 export default {
@@ -66,6 +87,10 @@ export default {
     registerPresence(api)
     registerNotification(api)
     registerAgentSend(api)
+    registerIsUserOnlineTool(api)
+    registerSendAppPushTool(api)
+    registerClawlyCronChannel(api)
+    registerCronHook(api)
     api.logger.info(`Loaded ${api.id} plugin.`)
   },
 }

package/notification.ts

@@ -45,6 +45,7 @@ export function getPushToken(): string | null {
 export async function sendPushNotification(
   opts: {body: string; title?: string; data?: Record<string, unknown>},
   api: PluginApi,
+  extras?: Record<string, unknown>,
 ): Promise<boolean> {
   const token = getPushToken()
   if (!token) {
@@ -62,6 +63,7 @@ export async function sendPushNotification(
         title: opts.title ?? 'Clawly',
         body: opts.body,
         data: opts.data,
+        ...extras,
       }),
     })
     const json = await res.json()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -13,11 +13,14 @@
   },
   "files": [
     "index.ts",
+    "channel.ts",
+    "cron-hook.ts",
     "outbound.ts",
     "echo.ts",
     "presence.ts",
     "notification.ts",
     "agent-send.ts",
+    "tools.ts",
     "openclaw.plugin.json"
   ],
   "publishConfig": {

package/tools.ts

@@ -0,0 +1,2 @@
+export {registerIsUserOnlineTool} from './tools/clawly-is-user-online'
+export {registerSendAppPushTool} from './tools/clawly-send-app-push'