@2en/clawly-plugins 1.26.0-beta.0 → 1.26.0

package/gateway/index.ts

@@ -1,8 +1,12 @@
 import type {PluginApi} from '../types'
 import {registerAgentSend} from './agent'
+import {registerAnalytics} from './analytics'
 import {registerClawhub2gateway} from './clawhub2gateway'
 import {registerConfigRepair} from './config-repair'
 import {registerCronDelivery} from './cron-delivery'
+import {registerCronTelemetry} from './cron-telemetry'
+import {initOtel, shutdownOtel} from './otel'
+import {initPostHog, setOpenClawVersion, shutdownPostHog} from './posthog'
 import {registerPairing} from './pairing'
 import {registerMemoryBrowser} from './memory'
 import {registerNotification} from './notification'
@@ -12,6 +16,33 @@ import {registerPresence} from './presence'
 import {registerVersion} from './version'
 
 export function registerGateway(api: PluginApi) {
+  // Initialize OTel logs provider (no-op if plugin telemetry config is missing)
+  const otelEnabled = initOtel(api.pluginConfig)
+  if (otelEnabled) {
+    api.logger.info('otel: LoggerProvider initialized (OTLP/HTTP)')
+  }
+
+  // Initialize PostHog analytics (no-op if plugin telemetry config is missing)
+  const posthogEnabled = initPostHog(api.pluginConfig)
+  if (posthogEnabled) {
+    const openclawVersion = api.config?.meta?.lastTouchedVersion
+    if (openclawVersion) setOpenClawVersion(openclawVersion)
+    api.logger.info('posthog: client initialized')
+  }
+
+  if (otelEnabled || posthogEnabled) {
+    api.on('gateway_stop', async () => {
+      if (otelEnabled) {
+        await shutdownOtel()
+        api.logger.info('otel: LoggerProvider shut down')
+      }
+      if (posthogEnabled) {
+        await shutdownPostHog()
+        api.logger.info('posthog: client shut down')
+      }
+    })
+  }
+
   registerPresence(api)
   registerNotification(api)
   registerAgentSend(api)
@@ -20,6 +51,8 @@ export function registerGateway(api: PluginApi) {
   registerPlugins(api)
   registerOfflinePush(api)
   registerCronDelivery(api)
+  registerCronTelemetry(api)
+  registerAnalytics(api)
   registerConfigRepair(api)
   registerPairing(api)
   registerVersion(api)

package/gateway/offline-push.test.ts

@@ -3,6 +3,8 @@ import type {PluginApi} from '../types'
 import {
   getLastAssistantPreview,
   getLastAssistantText,
+  getTriggeringUserText,
+  isHeartbeatTriggered,
   registerOfflinePush,
   shouldSkipPushForMessage,
 } from './offline-push'
@@ -515,3 +517,210 @@ describe('offline-push with filtered messages', () => {
     })
   })
 })
+
+// ── getTriggeringUserText unit tests ─────────────────────────────
+
+describe('getTriggeringUserText', () => {
+  test('returns null for non-array input', () => {
+    expect(getTriggeringUserText(undefined)).toBeNull()
+    expect(getTriggeringUserText(null)).toBeNull()
+    expect(getTriggeringUserText('string')).toBeNull()
+  })
+
+  test('extracts user text preceding the last assistant message', () => {
+    const messages = [
+      {role: 'user', content: 'Hello'},
+      {role: 'assistant', content: 'Hi there!'},
+    ]
+    expect(getTriggeringUserText(messages)).toBe('Hello')
+  })
+
+  test('returns the user message just before the last assistant, not earlier ones', () => {
+    const messages = [
+      {role: 'user', content: 'First question'},
+      {role: 'assistant', content: 'First reply'},
+      {role: 'user', content: 'Second question'},
+      {role: 'assistant', content: 'Second reply'},
+    ]
+    expect(getTriggeringUserText(messages)).toBe('Second question')
+  })
+
+  test('skips system messages between assistant and user', () => {
+    const messages = [
+      {role: 'user', content: 'Trigger text'},
+      {role: 'system', content: 'System instruction'},
+      {role: 'assistant', content: 'Response'},
+    ]
+    expect(getTriggeringUserText(messages)).toBe('Trigger text')
+  })
+
+  test('returns null when no user message precedes assistant', () => {
+    const messages = [{role: 'assistant', content: 'Unprompted response'}]
+    expect(getTriggeringUserText(messages)).toBeNull()
+  })
+
+  test('returns null when no assistant message exists', () => {
+    const messages = [{role: 'user', content: 'Hello'}]
+    expect(getTriggeringUserText(messages)).toBeNull()
+  })
+
+  test('handles array content format for user message', () => {
+    const messages = [
+      {
+        role: 'user',
+        content: [
+          {type: 'text', text: 'Read HEARTBEAT.md'},
+          {type: 'text', text: ' and follow instructions'},
+        ],
+      },
+      {role: 'assistant', content: 'HEARTBEAT_OK'},
+    ]
+    expect(getTriggeringUserText(messages)).toBe('Read HEARTBEAT.md and follow instructions')
+  })
+
+  test('returns null for empty messages array', () => {
+    expect(getTriggeringUserText([])).toBeNull()
+  })
+})
+
+// ── isHeartbeatTriggered unit tests ──────────────────────────────
+
+describe('isHeartbeatTriggered', () => {
+  test('returns true for heartbeat prompt', () => {
+    const messages = [
+      {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+      {role: 'assistant', content: 'HEARTBEAT_OK'},
+    ]
+    expect(isHeartbeatTriggered(messages)).toBe(true)
+  })
+
+  test('returns true for verbose heartbeat response', () => {
+    const messages = [
+      {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+      {
+        role: 'assistant',
+        content: 'Checked your inbox, nothing new. All clear! HEARTBEAT_OK',
+      },
+    ]
+    expect(isHeartbeatTriggered(messages)).toBe(true)
+  })
+
+  test('returns true for heartbeat response without HEARTBEAT_OK', () => {
+    const messages = [
+      {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+      {
+        role: 'assistant',
+        content: 'Nothing to report right now. Everything looks quiet.',
+      },
+    ]
+    expect(isHeartbeatTriggered(messages)).toBe(true)
+  })
+
+  test('returns false for normal user messages', () => {
+    const messages = [
+      {role: 'user', content: 'What is the weather today?'},
+      {role: 'assistant', content: 'Let me check...'},
+    ]
+    expect(isHeartbeatTriggered(messages)).toBe(false)
+  })
+
+  test('returns false for no messages', () => {
+    expect(isHeartbeatTriggered([])).toBe(false)
+    expect(isHeartbeatTriggered(undefined)).toBe(false)
+  })
+})
+
+// ── Heartbeat-triggered integration tests ────────────────────────
+
+describe('offline-push with heartbeat-triggered turns', () => {
+  test('skips push for verbose heartbeat response', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+          {
+            role: 'assistant',
+            content: 'Checked your inbox, nothing new. All clear! HEARTBEAT_OK',
+          },
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: 'offline-push: skipped (heartbeat-triggered turn)',
+    })
+    expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(0)
+  })
+
+  test('skips push for heartbeat response without HEARTBEAT_OK sentinel', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+          {
+            role: 'assistant',
+            content: 'Nothing to report. Everything looks quiet on all fronts.',
+          },
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: 'offline-push: skipped (heartbeat-triggered turn)',
+    })
+    expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(0)
+  })
+
+  test('bare HEARTBEAT_OK is caught by existing filter before heartbeat-context check', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {role: 'user', content: 'Read HEARTBEAT.md and follow the instructions inside.'},
+          {role: 'assistant', content: 'HEARTBEAT_OK'},
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    // Should be caught by shouldSkipPushForMessage (heartbeat ack), not the trigger check
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('skipped (filtered: heartbeat ack)'),
+    })
+    expect(logs.filter((l) => l.msg.includes('heartbeat-triggered turn'))).toHaveLength(0)
+  })
+
+  test('non-heartbeat turn sends push normally (no regression)', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {role: 'user', content: 'What is the weather like today?'},
+          {role: 'assistant', content: 'It is sunny and 72°F!'},
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=agent:clawly:main)'),
+    })
+    expect(logs.filter((l) => l.msg.includes('heartbeat-triggered'))).toHaveLength(0)
+  })
+})

package/gateway/offline-push.ts

@@ -10,12 +10,14 @@
  */
 
 import type {PluginApi} from '../types'
+import {markCronPushSent, markCronPushSkipped} from './cron-telemetry'
 import {
   decrementBadgeCount,
   getPushToken,
   incrementBadgeCount,
   sendPushNotification,
 } from './notification'
+import {captureEvent} from './posthog'
 import {isClientOnline} from './presence'
 
 /** Strip [[type:value]], [[word]], and MEDIA:xxx placeholders from text (canonical: apps/mobile/lib/stripPlaceholders.ts). */
@@ -70,6 +72,54 @@ export function getLastAssistantPreview(messages: unknown, maxLen = 140): string
   return `${text.slice(0, maxLen)}…`
 }
 
+// ── Trigger detection: inspect what caused the agent turn ──
+
+/**
+ * Walk backwards from the last assistant message to find the preceding
+ * user message text. Symmetric to `getLastAssistantText` but for the
+ * triggering user turn.
+ */
+export function getTriggeringUserText(messages: unknown): string | null {
+  if (!Array.isArray(messages)) return null
+
+  // Find the last assistant message index, then look backwards for user
+  let foundAssistant = false
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]
+    if (typeof msg !== 'object' || msg === null) continue
+    const role = (msg as any).role
+
+    if (!foundAssistant) {
+      if (role === 'assistant') foundAssistant = true
+      continue
+    }
+
+    // Skip system messages between assistant and user
+    if (role !== 'user') continue
+
+    const content = (msg as any).content
+    if (typeof content === 'string') return content
+    if (Array.isArray(content)) {
+      return content
+        .filter((p: any) => typeof p === 'object' && p !== null && p.type === 'text')
+        .map((p: any) => p.text)
+        .join('')
+    }
+    return null
+  }
+
+  return null
+}
+
+/**
+ * Returns true if the agent turn was triggered by a heartbeat prompt.
+ * Mirrors the mobile filter: `text.startsWith('Read HEARTBEAT.md')`.
+ */
+export function isHeartbeatTriggered(messages: unknown): boolean {
+  const text = getTriggeringUserText(messages)
+  return text != null && text.startsWith('Read HEARTBEAT.md')
+}
+
 // ── Push-filter: skip push for messages the mobile UI would hide ──
 
 /**
@@ -77,8 +127,8 @@ export function getLastAssistantPreview(messages: unknown, maxLen = 140): string
  * UI would filter out via shouldFilterMessage(). If true, skip the push
  * so the user isn't woken for nothing.
  *
- * Only covers assistant-role filter reasons — user-role triggers (heartbeat
- * prompt, memory flush, etc.) are not directly available on the event.
+ * Only covers assistant-text filter reasons. Trigger-level filtering
+ * (e.g. heartbeat prompt detection) is handled by `isHeartbeatTriggered`.
  */
 export function shouldSkipPushForMessage(text: string): string | null {
   const trimmed = text.trim()
@@ -106,10 +156,25 @@ export function shouldSkipPushForMessage(text: string): string | null {
 
 export function registerOfflinePush(api: PluginApi) {
   api.on('agent_end', async (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    // Read sessionKey early so we can report skip reasons for cron sessions.
+    const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
+    const agentId = typeof ctx?.agentId === 'string' ? ctx.agentId : undefined
+    const isCron = sessionKey?.startsWith('agent:clawly:cron:') ?? false
+
+    api.logger.info(
+      `offline-push[debug]: agent_end fired sessionKey=${sessionKey ?? 'undefined'} trigger=${String(ctx?.trigger ?? 'undefined')} isCron=${isCron}`,
+    )
+
     try {
       // Skip if client is still connected — they got the response in real-time.
       const online = await isClientOnline()
       if (online) {
+        if (isCron) markCronPushSkipped(sessionKey!, 'client online', true)
+        captureEvent('push.skipped', {
+          reason: 'client_online',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
         api.logger.info('offline-push: skipped (client online)')
         return
       }
@@ -121,22 +186,33 @@ export function registerOfflinePush(api: PluginApi) {
       if (fullText != null) {
         const reason = shouldSkipPushForMessage(fullText)
         if (reason) {
+          if (isCron) markCronPushSkipped(sessionKey!, `filtered: ${reason}`, false)
+          captureEvent('push.skipped', {
+            reason: `filtered_${reason}`,
+            is_cron: isCron,
+            ...(sessionKey ? {session_key: sessionKey} : {}),
+          })
           api.logger.info(`offline-push: skipped (filtered: ${reason})`)
           return
         }
       }
 
-      // agentId and sessionKey live on ctx (PluginHookAgentContext), not event.
-      const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
-      const agentId = typeof ctx?.agentId === 'string' ? ctx.agentId : undefined
+      // Heartbeat-triggered turns are silent by default — agent uses
+      // clawly_send_app_push tool for genuinely urgent findings.
+      if (isHeartbeatTriggered(event.messages)) {
+        if (isCron) markCronPushSkipped(sessionKey!, 'heartbeat-triggered', false)
+        captureEvent('push.skipped', {
+          reason: 'heartbeat_triggered',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
+        api.logger.info('offline-push: skipped (heartbeat-triggered turn)')
+        return
+      }
 
       // Only send push for the main clawly mobile session and cron sessions —
       // skip channel sessions (telegram, slack, discord, etc.) which have their own delivery.
-      if (
-        sessionKey !== undefined &&
-        sessionKey !== 'agent:clawly:main' &&
-        !sessionKey.startsWith('agent:clawly:cron:')
-      ) {
+      if (sessionKey !== undefined && sessionKey !== 'agent:clawly:main' && !isCron) {
         api.logger.info(`offline-push: skipped (non-main session: ${sessionKey})`)
         return
       }
@@ -147,6 +223,12 @@ export function registerOfflinePush(api: PluginApi) {
       const body = preview || 'Your response is ready'
 
       if (!getPushToken()) {
+        if (isCron) markCronPushSkipped(sessionKey!, 'no push token', false)
+        captureEvent('push.skipped', {
+          reason: 'no_push_token',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
         api.logger.warn('offline-push: skipped (no push token)')
         return
       }
@@ -166,14 +248,27 @@ export function registerOfflinePush(api: PluginApi) {
       )
 
       if (sent) {
+        if (isCron) markCronPushSent(sessionKey!)
+        captureEvent('push.sent', {
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
         api.logger.info(`offline-push: notified (session=${sessionKey ?? 'unknown'})`)
       } else {
         decrementBadgeCount()
+        if (isCron) markCronPushSkipped(sessionKey!, 'send failed', false)
+        captureEvent('push.skipped', {
+          reason: 'send_failed',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
       }
     } catch (err) {
-      api.logger.error(`offline-push: ${err instanceof Error ? err.message : String(err)}`)
+      const msg = err instanceof Error ? err.message : String(err)
+      if (isCron) markCronPushSkipped(sessionKey!, msg)
+      api.logger.error(`offline-push: ${msg}`)
     }
   })
 
-  api.logger.info('offline-push: registered agent_end hook')
+  api.logger.info('offline-push: registered agent_end hook (debug-instrumented)')
 }

package/gateway/otel.test.ts

@@ -0,0 +1,88 @@
+import {afterEach, beforeEach, describe, expect, mock, test} from 'bun:test'
+
+let exporterOptions: Record<string, unknown> | null = null
+let loggerName: string | null = null
+let shutdownCount = 0
+const fakeLogger = {emit: () => {}}
+
+mock.module('@opentelemetry/exporter-logs-otlp-http', () => ({
+  OTLPLogExporter: class OTLPLogExporter {
+    constructor(opts: Record<string, unknown>) {
+      exporterOptions = opts
+    }
+  },
+}))
+
+mock.module('@opentelemetry/resources', () => ({
+  Resource: class Resource {
+    constructor(_attrs: Record<string, unknown>) {}
+  },
+}))
+
+mock.module('@opentelemetry/sdk-logs', () => ({
+  BatchLogRecordProcessor: class BatchLogRecordProcessor {
+    constructor(_exporter: unknown) {}
+  },
+  LoggerProvider: class LoggerProvider {
+    addLogRecordProcessor(_processor: unknown) {}
+    getLogger(name: string) {
+      loggerName = name
+      return fakeLogger
+    }
+    async shutdown() {
+      shutdownCount++
+    }
+  },
+}))
+
+const {getOtelLogger, initOtel, shutdownOtel} = await import('./otel')
+
+describe('initOtel', () => {
+  beforeEach(async () => {
+    await shutdownOtel()
+    exporterOptions = null
+    loggerName = null
+    shutdownCount = 0
+    delete process.env.PLUGIN_OTEL_TOKEN
+    delete process.env.PLUGIN_OTEL_DATASET
+  })
+
+  afterEach(async () => {
+    await shutdownOtel()
+  })
+
+  test('prefers pluginConfig over legacy env vars', () => {
+    process.env.PLUGIN_OTEL_TOKEN = 'legacy-token'
+    process.env.PLUGIN_OTEL_DATASET = 'legacy-dataset'
+
+    const enabled = initOtel({
+      otelToken: 'cfg-token',
+      otelDataset: 'cfg-dataset',
+    })
+
+    expect(enabled).toBe(true)
+    expect(exporterOptions).toEqual({
+      url: 'https://api.axiom.co',
+      headers: {
+        Authorization: 'Bearer cfg-token',
+        'X-Axiom-Dataset': 'cfg-dataset',
+      },
+    })
+    expect(getOtelLogger()).toBeTruthy()
+    expect(loggerName).toBe('cron-telemetry')
+  })
+
+  test('falls back to legacy env vars', () => {
+    process.env.PLUGIN_OTEL_TOKEN = 'legacy-token'
+    process.env.PLUGIN_OTEL_DATASET = 'legacy-dataset'
+
+    expect(initOtel()).toBe(true)
+    expect((exporterOptions?.headers as Record<string, string>)['X-Axiom-Dataset']).toBe(
+      'legacy-dataset',
+    )
+  })
+
+  test('returns false when no telemetry config is present', () => {
+    expect(initOtel()).toBe(false)
+  })
+})

package/gateway/otel.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenTelemetry Logs provider for plugin telemetry.
+ *
+ * Reads telemetry config provisioned by Fleet via pluginConfig:
+ *
+ *   otelToken=<Axiom API token>
+ *   otelDataset=<Axiom dataset name>
+ *
+ * Falls back to legacy PLUGIN_OTEL_* env vars for backward compatibility and
+ * manual debug sessions.
+ */
+
+import type {Logger} from '@opentelemetry/api-logs'
+import {OTLPLogExporter} from '@opentelemetry/exporter-logs-otlp-http'
+import {Resource} from '@opentelemetry/resources'
+import {BatchLogRecordProcessor, LoggerProvider} from '@opentelemetry/sdk-logs'
+import {readTelemetryPluginConfig} from './telemetry-config'
+
+let provider: LoggerProvider | null = null
+let logger: Logger | null = null
+
+export function initOtel(
+  pluginConfig?: Record<string, unknown>,
+  serviceName = 'clawly-plugins',
+): boolean {
+  const cfg = readTelemetryPluginConfig(pluginConfig)
+  const token = cfg.otelToken ?? process.env.PLUGIN_OTEL_TOKEN
+  const dataset = cfg.otelDataset ?? process.env.PLUGIN_OTEL_DATASET
+  if (!token || !dataset) return false
+  if (provider) return true
+
+  const resource = new Resource({'service.name': serviceName})
+  const exporter = new OTLPLogExporter({
+    url: 'https://api.axiom.co',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'X-Axiom-Dataset': dataset,
+    },
+  })
+
+  provider = new LoggerProvider({resource})
+  provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter))
+  logger = provider.getLogger('cron-telemetry')
+  return true
+}
+
+export function getOtelLogger(): Logger | null {
+  return logger
+}
+
+export async function shutdownOtel(): Promise<void> {
+  if (provider) {
+    await provider.shutdown()
+    provider = null
+    logger = null
+  }
+}

package/gateway/plugins.ts

@@ -12,6 +12,7 @@ import {$} from 'zx'
 
 import type {PluginApi} from '../types'
 import {LruCache} from '../lib/lruCache'
+import {captureEvent} from './posthog'
 import {isUpdateAvailable} from '../lib/semver'
 import {stripCliLogs} from '../lib/stripCliLogs'
 
@@ -311,9 +312,11 @@ export function registerPlugins(api: PluginApi) {
         }
       }
 
+      captureEvent('plugin.updated', {plugin_id: pluginId, strategy, success: true, restarted})
       respond(true, {ok: true, strategy, output, restarted})
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
+      captureEvent('plugin.updated', {plugin_id: pluginId, strategy, success: false, error: msg})
       api.logger.error(`plugins: update failed — ${msg}`)
       respond(false, {ok: false, strategy, error: msg})
     }