@2en/clawly-plugins 1.25.0 → 1.26.0-beta.1

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

package/gateway/posthog.test.ts

@@ -0,0 +1,73 @@
+import {afterEach, beforeEach, describe, expect, mock, test} from 'bun:test'
+
+let constructorArgs: {apiKey: string; host: string} | null = null
+let captures: Array<{distinctId: string; event: string; properties?: Record<string, unknown>}> = []
+let shutdownCount = 0
+
+mock.module('posthog-node', () => ({
+  PostHog: class PostHog {
+    constructor(apiKey: string, opts: {host: string}) {
+      constructorArgs = {apiKey, host: opts.host}
+    }
+    capture(payload: {distinctId: string; event: string; properties?: Record<string, unknown>}) {
+      captures.push(payload)
+    }
+    async shutdown() {
+      shutdownCount++
+    }
+  },
+}))
+
+const {captureEvent, initPostHog, shutdownPostHog} = await import('./posthog')
+
+describe('initPostHog', () => {
+  beforeEach(async () => {
+    await shutdownPostHog()
+    constructorArgs = null
+    captures = []
+    shutdownCount = 0
+    delete process.env.PLUGIN_POSTHOG_API_KEY
+    delete process.env.PLUGIN_POSTHOG_HOST
+    delete process.env.INSTANCE_ID
+  })
+
+  afterEach(async () => {
+    await shutdownPostHog()
+  })
+
+  test('prefers pluginConfig over legacy env vars', () => {
+    process.env.PLUGIN_POSTHOG_API_KEY = 'legacy-key'
+    process.env.PLUGIN_POSTHOG_HOST = 'https://legacy.posthog.com'
+    process.env.INSTANCE_ID = 'legacy-inst'
+
+    expect(
+      initPostHog({
+        posthogApiKey: 'cfg-key',
+        posthogHost: 'https://cfg.posthog.com',
+        instanceId: 'inst-1',
+      }),
+    ).toBe(true)
+
+    expect(constructorArgs).toEqual({
+      apiKey: 'cfg-key',
+      host: 'https://cfg.posthog.com',
+    })
+  })
+
+  test('falls back to legacy env vars', () => {
+    process.env.PLUGIN_POSTHOG_API_KEY = 'legacy-key'
+    process.env.INSTANCE_ID = 'legacy-inst'
+
+    expect(initPostHog()).toBe(true)
+    expect(constructorArgs).toEqual({
+      apiKey: 'legacy-key',
+      host: 'https://us.i.posthog.com',
+    })
+  })
+
+  test('returns false when api key is missing', () => {
+    expect(initPostHog({instanceId: 'inst-1'})).toBe(false)
+    captureEvent('cron.deleted')
+    expect(captures).toHaveLength(0)
+  })
+})

package/gateway/posthog.ts

@@ -0,0 +1,61 @@
+/**
+ * PostHog analytics provider for plugin telemetry.
+ *
+ * Reads telemetry config provisioned by Fleet via pluginConfig:
+ *
+ *   posthogApiKey=<PostHog project API key>
+ *   posthogHost=<PostHog ingest URL> (optional, defaults to https://us.i.posthog.com)
+ *   instanceId=<distinct_id>
+ *
+ * Falls back to legacy PLUGIN_POSTHOG_* / INSTANCE_ID env vars for backward
+ * compatibility and manual debug sessions.
+ *
+ * The distinct_id for all events is the provisioned instanceId (one sprite = one user).
+ */
+
+import {PostHog} from 'posthog-node'
+import pkg from '../package.json'
+import {readTelemetryPluginConfig} from './telemetry-config'
+
+let client: PostHog | null = null
+let distinctId: string | null = null
+let superProperties: Record<string, unknown> = {}
+
+export function initPostHog(pluginConfig?: Record<string, unknown>): boolean {
+  const cfg = readTelemetryPluginConfig(pluginConfig)
+  const apiKey = cfg.posthogApiKey ?? process.env.PLUGIN_POSTHOG_API_KEY
+  if (!apiKey) return false
+  if (client) return true
+
+  const host = cfg.posthogHost ?? process.env.PLUGIN_POSTHOG_HOST ?? 'https://us.i.posthog.com'
+  distinctId = cfg.instanceId ?? process.env.INSTANCE_ID ?? null
+  if (!distinctId) return false
+
+  client = new PostHog(apiKey, {host})
+  superProperties = {plugin_version: pkg.version}
+  return true
+}
+
+/** Set the OpenClaw version (read from api.config after gateway init). */
+export function setOpenClawVersion(version: string): void {
+  superProperties.openclaw_version = version
+}
+
+const EVENT_PREFIX = 'plugin.'
+
+export function captureEvent(event: string, properties?: Record<string, unknown>): void {
+  if (!client || !distinctId) return
+  client.capture({
+    distinctId,
+    event: `${EVENT_PREFIX}${event}`,
+    properties: {...superProperties, ...properties},
+  })
+}
+
+export async function shutdownPostHog(): Promise<void> {
+  if (client) {
+    await client.shutdown()
+    client = null
+    distinctId = null
+  }
+}

package/gateway/telemetry-config.test.ts

@@ -0,0 +1,58 @@
+import {describe, expect, test} from 'bun:test'
+import {readTelemetryPluginConfig} from './telemetry-config'
+
+describe('readTelemetryPluginConfig', () => {
+  test('reads telemetry fields from pluginConfig', () => {
+    expect(
+      readTelemetryPluginConfig({
+        instanceId: 'inst-1',
+        otelToken: 'otel-token',
+        otelDataset: 'clawly-otel-logs-dev',
+        posthogApiKey: 'ph-key',
+        posthogHost: 'https://us.i.posthog.com',
+      }),
+    ).toEqual({
+      instanceId: 'inst-1',
+      otelToken: 'otel-token',
+      otelDataset: 'clawly-otel-logs-dev',
+      posthogApiKey: 'ph-key',
+      posthogHost: 'https://us.i.posthog.com',
+    })
+  })
+
+  test('trims surrounding whitespace from string values', () => {
+    expect(
+      readTelemetryPluginConfig({
+        instanceId: ' inst-1 ',
+        otelToken: ' otel-token ',
+        otelDataset: ' clawly-otel-logs-dev ',
+        posthogApiKey: ' ph-key ',
+        posthogHost: ' https://us.i.posthog.com ',
+      }),
+    ).toEqual({
+      instanceId: 'inst-1',
+      otelToken: 'otel-token',
+      otelDataset: 'clawly-otel-logs-dev',
+      posthogApiKey: 'ph-key',
+      posthogHost: 'https://us.i.posthog.com',
+    })
+  })
+
+  test('drops empty and non-string values', () => {
+    expect(
+      readTelemetryPluginConfig({
+        instanceId: '   ',
+        otelToken: null,
+        otelDataset: 1,
+        posthogApiKey: '',
+        posthogHost: undefined,
+      }),
+    ).toEqual({
+      instanceId: undefined,
+      otelToken: undefined,
+      otelDataset: undefined,
+      posthogApiKey: undefined,
+      posthogHost: undefined,
+    })
+  })
+})

package/gateway/telemetry-config.ts

@@ -0,0 +1,27 @@
+export interface TelemetryPluginConfig {
+  instanceId?: string
+  otelToken?: string
+  otelDataset?: string
+  posthogApiKey?: string
+  posthogHost?: string
+}
+
+function readString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+export function readTelemetryPluginConfig(
+  pluginConfig?: Record<string, unknown> | null,
+): TelemetryPluginConfig {
+  const cfg = pluginConfig ?? {}
+
+  return {
+    instanceId: readString(cfg.instanceId),
+    otelToken: readString(cfg.otelToken),
+    otelDataset: readString(cfg.otelDataset),
+    posthogApiKey: readString(cfg.posthogApiKey),
+    posthogHost: readString(cfg.posthogHost),
+  }
+}

package/index.ts

@@ -16,16 +16,22 @@
  * 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
+ * - clawly_send_image        — send an image to the user (URL download or local file)
  * - clawly_send_message      — send a message to user via main session agent (supports role: user|assistant)
  *
  * Commands:
  * - /clawly_echo          — echo text back without LLM
  *
+ * HTTP routes:
+ * - GET /clawly/file/outbound — serve files (hash lookup first, then direct path with allowlist)
+ *
  * Hooks:
  * - before_message_write — restores original /skill command in user messages (undoes gateway rewrite)
  * - tool_result_persist   — copies TTS audio to persistent outbound directory
  * - before_tool_call      — enforces delivery fields on cron.create
  * - agent_end             — sends push notification when client is offline; injects cron results into main session
+ * - after_tool_call       — cron telemetry: captures cron job creation/deletion
+ * - agent_end (pri 100)   — cron telemetry: captures cron execution outcomes with delivery/push flags
  * - gateway_start         — auto-approves device pairing for Clawly mobile clients (clientId: openclaw-ios)
  * - gateway_start         — registers auto-update cron job (0 3 * * *) for clawly-plugins
  */
@@ -76,6 +82,6 @@ export default {
       registerCalendar(api, gw)
     }
 
-    api.logger.info(`Loaded ${api.id} plugin.`)
+    api.logger.info(`Loaded ${api.id} plugin. (debug-instrumented build)`)
   },
 }

package/model-gateway-setup.ts

@@ -65,6 +65,12 @@ export const EXTRA_GATEWAY_MODELS: Array<{
     alias: 'Qwen3.5 Plus',
     input: ['text', 'image'],
   },
+  {
+    id: 'openai/gpt-5.4',
+    name: 'openai/gpt-5.4',
+    alias: 'GPT-5.4',
+    input: ['text', 'image'],
+  },
 ]
 
 export function readOpenclawConfig(configPath: string): Record<string, unknown> {

package/openclaw.plugin.json

@@ -50,13 +50,18 @@
       "skillGatewayToken": { "type": "string" },
       "modelGatewayBaseUrl": { "type": "string" },
       "modelGatewayToken": { "type": "string" },
+      "instanceId": { "type": "string" },
       "agentId": { "type": "string" },
       "agentName": { "type": "string" },
       "workspaceDir": { "type": "string" },
       "defaultModel": { "type": "string" },
       "defaultImageModel": { "type": "string" },
       "elevenlabsApiKey": { "type": "string" },
-      "elevenlabsVoiceId": { "type": "string" }
+      "elevenlabsVoiceId": { "type": "string" },
+      "otelToken": { "type": "string" },
+      "otelDataset": { "type": "string" },
+      "posthogApiKey": { "type": "string" },
+      "posthogHost": { "type": "string" }
     },
     "required": []
   }