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

package/auto-pair.ts

@@ -1,3 +1,4 @@
+import {captureEvent} from './gateway/posthog'
 import type {PluginApi} from './index'
 
 const AUTO_APPROVE_CLIENT_IDS = new Set(['openclaw-ios'])
@@ -49,6 +50,10 @@ export function registerAutoPair(api: PluginApi) {
           if (req.clientId && AUTO_APPROVE_CLIENT_IDS.has(req.clientId)) {
             const result = await sdk.approveDevicePairing(req.requestId)
             if (result) {
+              captureEvent('device.paired', {
+                client_id: req.clientId,
+                platform: result.device.platform ?? 'unknown',
+              })
               api.logger.info(
                 `auto-pair: approved device=${result.device.deviceId} ` +
                   `name=${result.device.displayName ?? 'unknown'} ` +

package/config-setup.ts

@@ -1,17 +1,21 @@
 /**
- * On plugin init, patches openclaw.json to set all business config that was
- * previously written by provision's buildConfig().
+ * Reconciles runtime config owned by clawly-plugins after provision has already
+ * established the bootstrap baseline (plugin entry, pluginConfig inputs,
+ * workspace files, install metadata).
  *
- * Domain helpers read the pluginConfig, apply enforce or set-if-missing
- * semantics, and write once if anything changed.  This runs before
- * setupModelGateway so agents.defaults.model is available for the model
- * provider setup.
+ * This file intentionally owns two narrower responsibilities:
+ * - repair legacy state damaged by older provision flows
+ * - reconcile runtime-facing config derived from pluginConfig
  *
- * Backward compatibility: old sprites have pluginConfig with only 4 fields
- * (skill/model gateway credentials). Helpers check for the new fields and
- * skip gracefully when absent.
+ * It does not try to redefine provision's startup contract. Anything that must
+ * exist before the first gateway boot should remain provision-owned.
+ *
+ * Backward compatibility: old sprites may have only the original gateway
+ * credentials in pluginConfig. Helpers check for newer fields and skip
+ * gracefully when absent.
  */
 
+import fs from 'node:fs'
 import path from 'node:path'
 
 import type {PluginApi} from './index'
@@ -23,6 +27,7 @@ import {
 } from './model-gateway-setup'
 
 export interface ConfigPluginConfig {
+  instanceId?: string
   agentId?: string
   agentName?: string
   workspaceDir?: string
@@ -32,6 +37,10 @@ export interface ConfigPluginConfig {
   elevenlabsVoiceId?: string
   modelGatewayBaseUrl?: string
   modelGatewayToken?: string
+  otelToken?: string
+  otelDataset?: string
+  posthogApiKey?: string
+  posthogHost?: string
 }
 
 function toPC(api: PluginApi): ConfigPluginConfig {
@@ -372,8 +381,100 @@ export function patchSession(config: Record<string, unknown>): boolean {
   return dirty
 }
 
+const PLUGIN_ID = 'clawly-plugins'
+const NPM_PKG_NAME = '@2en/clawly-plugins'
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+/**
+ * Self-healing: reconstruct missing `plugins.installs.clawly-plugins` record.
+ * Older provisioned sprites had this record destroyed by a full-overwrite bug
+ * in the provision write-plugins-config step.  Without this record,
+ * `openclaw plugins update` cannot function.
+ */
+export function patchInstallRecord(config: Record<string, unknown>, stateDir: string): boolean {
+  const plugins = asObj(config.plugins)
+  const installs = asObj(plugins.installs)
+
+  // Already has a valid install record — nothing to do
+  if (
+    installs[PLUGIN_ID] &&
+    typeof installs[PLUGIN_ID] === 'object' &&
+    (installs[PLUGIN_ID] as Record<string, unknown>).source &&
+    (installs[PLUGIN_ID] as Record<string, unknown>).spec
+  )
+    return false
+
+  // Read version from installed plugin's package.json
+  const installPath = path.join(stateDir, 'extensions', PLUGIN_ID)
+  const pkgPath = path.join(installPath, 'package.json')
+  let rawPkg: string
+  try {
+    rawPkg = fs.readFileSync(pkgPath, 'utf-8')
+  } catch {
+    // Plugin not installed on disk — skip
+    return false
+  }
+  let version: string | undefined
+  try {
+    const pkg = JSON.parse(rawPkg)
+    if (typeof pkg.version === 'string') version = pkg.version
+  } catch {
+    // package.json is malformed — proceed without version
+  }
+  let installedAt = new Date().toISOString()
+  try {
+    installedAt = fs.statSync(pkgPath).mtime.toISOString()
+  } catch {
+    // Fall back to repair time if file metadata is unavailable.
+  }
+
+  installs[PLUGIN_ID] = {
+    source: 'npm',
+    spec: version ? `${NPM_PKG_NAME}@${version}` : NPM_PKG_NAME,
+    installPath,
+    version,
+    installedAt,
+  }
+  plugins.installs = installs
+  config.plugins = plugins
+  return true
+}
+
+function repairLegacyProvisionState(
+  api: PluginApi,
+  config: Record<string, unknown>,
+  stateDir: string,
+) {
+  const installRecordPatched = patchInstallRecord(config, stateDir)
+  if (installRecordPatched) {
+    api.logger.warn('plugins.installs.clawly-plugins was missing — self-healed from disk.')
+  }
+  return installRecordPatched
+}
+
+function reconcileRuntimeConfig(
+  api: PluginApi,
+  config: Record<string, unknown>,
+  pc: ConfigPluginConfig,
+): boolean {
+  let dirty = false
+  dirty = patchAgent(config, pc) || dirty
+  dirty = patchGateway(config) || dirty
+  dirty = patchBrowser(config) || dirty
+  dirty = patchSession(config) || dirty
+  dirty = patchTts(config, pc) || dirty
+  dirty = patchWebSearch(config, pc) || dirty
+  dirty = patchModelGateway(config, api) || dirty
+  return dirty
+}
+
 // ---------------------------------------------------------------------------
-// Entry point — single read, patch all, single write
+// Entry point — single read, targeted reconcile, single write
 // ---------------------------------------------------------------------------
 
 export function setupConfig(api: PluginApi): void {
@@ -388,13 +489,8 @@ export function setupConfig(api: PluginApi): void {
   const pc = toPC(api)
 
   let dirty = false
-  dirty = patchAgent(config, pc) || dirty
-  dirty = patchGateway(config) || dirty
-  dirty = patchBrowser(config) || dirty
-  dirty = patchSession(config) || dirty
-  dirty = patchTts(config, pc) || dirty
-  dirty = patchWebSearch(config, pc) || dirty
-  dirty = patchModelGateway(config, api) || dirty
+  dirty = repairLegacyProvisionState(api, config, stateDir) || dirty
+  dirty = reconcileRuntimeConfig(api, config, pc) || dirty
 
   if (!dirty) {
     api.logger.info('Config setup: no changes needed.')

package/gateway/analytics.ts

@@ -0,0 +1,83 @@
+/**
+ * Broad PostHog analytics — captures agent turns, LLM usage, and tool calls.
+ *
+ * Hooks:
+ * - agent_end     — tracks every agent turn completion (trigger, duration, success)
+ * - llm_output    — tracks LLM token usage per response (provider, model, tokens)
+ * - after_tool_call — tracks tool usage (tool name, duration, success)
+ *
+ * Cron-specific lifecycle events (created/executed/deleted) are handled by
+ * cron-telemetry.ts and are NOT duplicated here.
+ *
+ * Other modules (offline-push, auto-pair, plugins, clawhub2gateway) call
+ * captureEvent() directly for their domain-specific events.
+ */
+
+import type {PluginApi} from '../types'
+import {captureEvent} from './posthog'
+
+export function registerAnalytics(api: PluginApi) {
+  // ── agent_end: track every agent turn ───────────────────────────
+  api.on('agent_end', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const trigger = typeof ctx?.trigger === 'string' ? ctx.trigger : 'unknown'
+    const agentId = typeof ctx?.agentId === 'string' ? ctx.agentId : undefined
+    const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
+    const sessionId = typeof ctx?.sessionId === 'string' ? ctx.sessionId : undefined
+    const success = event.error == null
+    const durationMs = typeof event.durationMs === 'number' ? event.durationMs : undefined
+
+    captureEvent('agent.turn_completed', {
+      trigger,
+      ...(agentId ? {agent_id: agentId} : {}),
+      ...(sessionKey ? {session_key: sessionKey} : {}),
+      ...(sessionId ? {session_id: sessionId} : {}),
+      success,
+      ...(durationMs != null ? {duration_ms: durationMs} : {}),
+      ...(typeof event.error === 'string' ? {error: event.error} : {}),
+    })
+  })
+
+  // ── llm_output: track token usage ──────────────────────────────
+  api.on('llm_output', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const provider = typeof event.provider === 'string' ? event.provider : undefined
+    const model = typeof event.model === 'string' ? event.model : undefined
+    const usage = event.usage as Record<string, unknown> | undefined
+
+    if (!usage) return
+
+    const trigger = typeof ctx?.trigger === 'string' ? ctx.trigger : undefined
+    const sessionId = typeof ctx?.sessionId === 'string' ? ctx.sessionId : undefined
+
+    captureEvent('llm.response', {
+      ...(provider ? {provider} : {}),
+      ...(model ? {model} : {}),
+      ...(trigger ? {trigger} : {}),
+      ...(sessionId ? {session_id: sessionId} : {}),
+      ...(typeof usage.input === 'number' ? {tokens_input: usage.input} : {}),
+      ...(typeof usage.output === 'number' ? {tokens_output: usage.output} : {}),
+      ...(typeof usage.cacheRead === 'number' ? {tokens_cache_read: usage.cacheRead} : {}),
+      ...(typeof usage.cacheWrite === 'number' ? {tokens_cache_write: usage.cacheWrite} : {}),
+      ...(typeof usage.total === 'number' ? {tokens_total: usage.total} : {}),
+    })
+  })
+
+  // ── after_tool_call: track tool usage ──────────────────────────
+  api.on('after_tool_call', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const toolName = typeof event.toolName === 'string' ? event.toolName : undefined
+    if (!toolName) return
+
+    const sessionId = typeof ctx?.sessionId === 'string' ? ctx.sessionId : undefined
+    const success = event.error == null
+    const durationMs = typeof event.durationMs === 'number' ? event.durationMs : undefined
+
+    captureEvent('tool.called', {
+      tool_name: toolName,
+      success,
+      ...(sessionId ? {session_id: sessionId} : {}),
+      ...(durationMs != null ? {duration_ms: durationMs} : {}),
+      ...(typeof event.error === 'string' ? {error: event.error} : {}),
+    })
+  })
+
+  api.logger.info('analytics: registered agent_end + llm_output + after_tool_call hooks')
+}

package/gateway/clawhub2gateway.ts

@@ -20,6 +20,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import type {PluginApi} from '../types'
+import {captureEvent} from './posthog'
 
 type JsonSchema = Record<string, unknown>
 
@@ -182,13 +183,21 @@ export function registerClawhub2gateway(api: PluginApi) {
           env,
         })
         const output = joinOutput(res.stdout, res.stderr)
+        const action = rpc.method.split('.').pop() ?? rpc.method
         if (res.code && res.code !== 0) {
+          captureEvent('clawhub.action', {action, success: false})
           respond(false, undefined, {
             code: 'command_failed',
             message: output || `clawhub exited with code ${res.code}`,
           })
           return
         }
+        captureEvent('clawhub.action', {
+          action,
+          success: true,
+          ...(params.slug ? {slug: params.slug} : {}),
+          ...(params.query ? {query: params.query} : {}),
+        })
         respond(true, {
           ok: true,
           output,
@@ -201,6 +210,12 @@ export function registerClawhub2gateway(api: PluginApi) {
           cwd: built.cwd,
         })
       } catch (err) {
+        const action = rpc.method.split('.').pop() ?? rpc.method
+        captureEvent('clawhub.action', {
+          action,
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        })
         respond(false, undefined, {
           code: 'error',
           message: err instanceof Error ? err.message : String(err),

package/gateway/cron-delivery.ts

@@ -15,6 +15,7 @@
  */
 
 import type {PluginApi} from '../types'
+import {markCronDelivered, markCronDeliverySkipped} from './cron-telemetry'
 import {injectAssistantMessage, resolveSessionKey} from './inject'
 import {shouldSkipPushForMessage} from './offline-push'
 
@@ -51,6 +52,10 @@ export function registerCronDelivery(api: PluginApi) {
     const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
     const agentId = typeof ctx?.agentId === 'string' ? ctx.agentId : undefined
 
+    api.logger.info(
+      `cron-delivery[debug]: agent_end fired sessionKey=${sessionKey ?? 'undefined'} agentId=${agentId ?? 'undefined'} trigger=${String(ctx?.trigger ?? 'undefined')}`,
+    )
+
     // Only fire for cron sessions
     if (!sessionKey?.startsWith('agent:clawly:cron:')) return
 
@@ -59,6 +64,7 @@ export function registerCronDelivery(api: PluginApi) {
       const text = getRawLastAssistantText(event.messages)
       if (text == null) {
         api.logger.info('cron-delivery: skipped (no assistant message)')
+        if (sessionKey) markCronDeliverySkipped(sessionKey, 'no assistant message')
         return
       }
 
@@ -66,12 +72,14 @@ export function registerCronDelivery(api: PluginApi) {
       const reason = shouldSkipPushForMessage(text)
       if (reason) {
         api.logger.info(`cron-delivery: skipped (filtered: ${reason})`)
+        if (sessionKey) markCronDeliverySkipped(sessionKey, `filtered: ${reason}`)
         return
       }
 
       // Resolve main session key for this agent
       if (!agentId) {
         api.logger.error('cron-delivery: skipped (no agentId on ctx)')
+        if (sessionKey) markCronDeliverySkipped(sessionKey, 'no agentId')
         return
       }
 
@@ -86,13 +94,16 @@ export function registerCronDelivery(api: PluginApi) {
         api,
       )
 
+      if (sessionKey) markCronDelivered(sessionKey)
       api.logger.info(
         `cron-delivery: injected into ${mainSessionKey} (messageId=${result.messageId})`,
       )
     } catch (err) {
-      api.logger.error(`cron-delivery: ${err instanceof Error ? err.message : String(err)}`)
+      const msg = err instanceof Error ? err.message : String(err)
+      if (sessionKey) markCronDeliverySkipped(sessionKey, msg)
+      api.logger.error(`cron-delivery: ${msg}`)
     }
   })
 
-  api.logger.info('cron-delivery: registered agent_end hook')
+  api.logger.info('cron-delivery: registered agent_end hook (debug-instrumented)')
 }