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

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

@@ -1,12 +1,10 @@
 /**
- * On plugin init, patches openclaw.json to add the `clawly-model-gateway`
- * model provider entry.  Credentials come from pluginConfig; the model list
- * is derived from `agents.defaults.model`
- * already present in the config.
+ * Reconciles the `clawly-model-gateway` provider in openclaw.json from
+ * pluginConfig inputs and the current runtime-facing agent defaults.
  *
- * This runs synchronously during plugin registration (before gateway_start).
- * OpenClaw loads the config file once at startup, so writing before the
- * gateway fully starts ensures the provider is active on first boot.
+ * This is a runtime reconcile path, not a provision/bootstrap contract.
+ * The first-boot correctness of gateway startup should not rely on this file
+ * write winning a race against OpenClaw's internal startup snapshot timing.
  */
 
 import fs from 'node:fs'

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": []
   }

package/outbound.ts

@@ -1,9 +1,12 @@
 /**
- * TTS outbound persistence — copies ephemeral TTS audio to a persistent directory
- * so mobile can fetch it after the temp files are cleaned up.
+ * Outbound file serving — serves files to the mobile client.
+ *
+ * Resolution order (HTTP route + gateway method):
+ *   1. Hash-mapped file: ~/.openclaw/clawly/outbound/<sha256(path)>.<ext>
+ *   2. Direct path: if the raw path is under an allowlisted directory
  *
  * Hook:   tool_result_persist → copies TTS audioPath to ~/.openclaw/clawly/outbound/<hash>.<ext>
- * Method: clawly.file.getOutbound → reads outbound file by original-path hash
+ * Method: clawly.file.getOutbound → reads outbound file by original-path hash or direct path
  */
 
 import crypto from 'node:crypto'
@@ -74,6 +77,8 @@ export function registerOutboundHook(api: PluginApi) {
 // ── Gateway method: clawly.file.getOutbound ─────────────────────────
 
 export function registerOutboundMethods(api: PluginApi) {
+  const stateDir = api.runtime.state.resolveStateDir()
+
   api.registerGatewayMethod('clawly.file.getOutbound', async ({params, respond}) => {
     const rawPath = typeof params.path === 'string' ? params.path.trim() : ''
 
@@ -82,30 +87,18 @@ export function registerOutboundMethods(api: PluginApi) {
       return
     }
 
-    const dest = outboundFilePath(rawPath)
-
-    if (!(await fileExists(dest))) {
-      // Fallback: TTS writes directly to /tmp/openclaw/ and the tool_result_persist hook
-      // only fires for agent tool calls, not tts.convert RPC calls. Read the source file
-      // directly if it lives in the known-safe TTS temp directory.
-      if (rawPath.startsWith('/tmp/openclaw/') && (await fileExists(rawPath))) {
-        const buffer = await fsp.readFile(rawPath)
-        api.logger.info(
-          `clawly.file.getOutbound: served from source ${rawPath} (${buffer.length} bytes)`,
-        )
-        respond(true, {base64: buffer.toString('base64')})
-        return
-      }
-      api.logger.warn(`outbound: file not found: ${rawPath} ${dest}`)
+    const resolved = await resolveOutboundFile(rawPath, stateDir)
+    if (!resolved) {
+      api.logger.warn(`outbound: file not found: ${rawPath}`)
       respond(false, undefined, {code: 'not_found', message: 'outbound file not found'})
       return
     }
 
-    const buffer = await fsp.readFile(dest)
-    const base64 = buffer.toString('base64')
-
-    api.logger.info(`clawly.file.getOutbound: served ${rawPath} (${buffer.length} bytes)`)
-    respond(true, {base64})
+    const buffer = await fsp.readFile(resolved)
+    api.logger.info(
+      `clawly.file.getOutbound: served ${rawPath} -> ${resolved} (${buffer.length} bytes)`,
+    )
+    respond(true, {base64: buffer.toString('base64')})
   })
 }
 
@@ -119,6 +112,47 @@ const MIME: Record<string, string> = {
   '.aac': 'audio/aac',
   '.flac': 'audio/flac',
   '.webm': 'audio/webm',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.heic': 'image/heic',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+}
+
+/** Directories from which direct-path serving is allowed (no hash required). */
+let allowedRoots: string[] | null = null
+
+function getAllowedRoots(stateDir?: string): string[] {
+  if (!allowedRoots) {
+    const roots = [OUTBOUND_DIR + path.sep, '/tmp/']
+    if (stateDir) roots.push(stateDir + path.sep)
+    allowedRoots = roots
+  }
+  return allowedRoots
+}
+
+function isDirectPathAllowed(resolved: string, stateDir?: string): boolean {
+  return getAllowedRoots(stateDir).some((root) => resolved.startsWith(root))
+}
+
+/**
+ * Resolve which file to serve: hash-mapped first, then direct path if allowlisted.
+ * Returns the resolved file path or null.
+ */
+async function resolveOutboundFile(rawPath: string, stateDir?: string): Promise<string | null> {
+  // 1. Hash-mapped file
+  const hashed = outboundFilePath(rawPath)
+  if (await fileExists(hashed)) return hashed
+
+  // 2. Direct path (allowlisted directories only)
+  const resolved = path.resolve(rawPath)
+  if (isDirectPathAllowed(resolved, stateDir) && (await fileExists(resolved))) return resolved
+
+  return null
 }
 
 function sendJson(res: ServerResponse, status: number, body: Record<string, unknown>) {
@@ -127,6 +161,8 @@ function sendJson(res: ServerResponse, status: number, body: Record<string, unkn
 }
 
 export function registerOutboundHttpRoute(api: PluginApi) {
+  const stateDir = api.runtime.state.resolveStateDir()
+
   api.registerHttpRoute({
     path: '/clawly/file/outbound',
     handler: async (_req: IncomingMessage, res: ServerResponse) => {
@@ -138,17 +174,16 @@ export function registerOutboundHttpRoute(api: PluginApi) {
         return
       }
 
-      const dest = outboundFilePath(rawPath)
-
-      if (!(await fileExists(dest))) {
+      const resolved = await resolveOutboundFile(rawPath, stateDir)
+      if (!resolved) {
         api.logger.warn(`outbound http: file not found: ${rawPath}`)
         sendJson(res, 404, {error: 'outbound file not found'})
         return
       }
 
-      const ext = path.extname(dest).toLowerCase()
+      const ext = path.extname(resolved).toLowerCase()
       const contentType = MIME[ext] ?? 'application/octet-stream'
-      const stat = await fsp.stat(dest)
+      const stat = await fsp.stat(resolved)
       const total = stat.size
       const rangeHeader = _req.headers.range
 
@@ -158,7 +193,7 @@ export function registerOutboundHttpRoute(api: PluginApi) {
           const start = Number(match[1])
           const end = match[2] ? Number(match[2]) : total - 1
           const chunkSize = end - start + 1
-          const stream = fs.createReadStream(dest, {start, end})
+          const stream = fs.createReadStream(resolved, {start, end})
 
           res.writeHead(206, {
             'Content-Type': contentType,
@@ -168,13 +203,13 @@ export function registerOutboundHttpRoute(api: PluginApi) {
           })
           stream.pipe(res)
           api.logger.info(
-            `outbound http: served ${rawPath} -> ${dest} range ${start}-${end}/${total}`,
+            `outbound http: served ${rawPath} -> ${resolved} range ${start}-${end}/${total}`,
           )
           return
         }
       }
 
-      const buffer = await fsp.readFile(dest)
+      const buffer = await fsp.readFile(resolved)
       res.writeHead(200, {
         'Content-Type': contentType,
         'Content-Length': total,
@@ -182,7 +217,7 @@ export function registerOutboundHttpRoute(api: PluginApi) {
       })
       res.end(buffer)
 
-      api.logger.info(`outbound http: served ${rawPath} -> ${dest} (${total} bytes)`)
+      api.logger.info(`outbound http: served ${rawPath} -> ${resolved} (${total} bytes)`)
     },
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.26.0-beta.0",
+  "version": "1.26.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -9,6 +9,12 @@
     "directory": "plugins/clawly-plugins"
   },
   "dependencies": {
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "posthog-node": "^5.28.0",
+    "file-type": "^21.3.0",
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [