@2en/clawly-plugins 1.28.1 → 1.29.0-beta.0

package/gateway/cron-telemetry.ts

@@ -106,7 +106,7 @@ function extractJobId(sessionKey: string): string | null {
 
 function emit(attributes: CronTelemetryAttributes, api: PluginApi) {
   // Emit structured OTel LogRecord (if provider is initialized)
-  const otelLogger = getOtelLogger()
+  const otelLogger = getOtelLogger('cron-telemetry')
   if (otelLogger) {
     otelLogger.emit({
       severityNumber: SeverityNumber.INFO,

package/gateway/index.ts

@@ -3,12 +3,13 @@ import {registerAgentSend} from './agent'
 import {registerCalendarNative} from './calendar-native'
 import {registerAnalytics} from './analytics'
 import {registerAudit} from './audit'
-import {registerNodeBrowserAllowlist} from './node-browser-allowlist'
+import {registerNodeDangerousAllowlist} from './node-dangerous-allowlist'
 import {registerClawhub2gateway} from './clawhub2gateway'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
 import {registerCronDelivery} from './cron-delivery'
 import {registerCronTelemetry} from './cron-telemetry'
+import {registerMessageLog} from './message-log'
 import {registerMemoryBrowser} from './memory'
 import {registerNotification} from './notification'
 import {registerOfflinePush} from './offline-push'
@@ -55,6 +56,7 @@ export function registerGateway(api: PluginApi) {
   registerOfflinePush(api)
   registerCronDelivery(api)
   registerCronTelemetry(api)
+  registerMessageLog(api)
   registerAnalytics(api)
   registerConfigRepair(api)
   registerConfigTimezone(api)
@@ -62,6 +64,6 @@ export function registerGateway(api: PluginApi) {
   registerPairing(api)
   registerVersion(api)
   registerAudit(api)
-  registerNodeBrowserAllowlist(api)
+  registerNodeDangerousAllowlist(api)
   registerCalendarNative(api)
 }

package/gateway/message-log.ts

@@ -0,0 +1,156 @@
+/**
+ * Message lifecycle logging — captures LLM inputs, outputs, and channel
+ * deliveries via OTel structured logs and human-readable api.logger output.
+ *
+ * Gated by `messageLogEnabled` in pluginConfig (dev-only).
+ * Content is never logged — only metadata (model, provider, counts, success).
+ *
+ * Hooks:
+ * - llm_input    — logs model, provider, history size, images count
+ * - llm_output   — logs model, provider, content length
+ * - message_sent — logs channel delivery outcome
+ */
+
+import {SeverityNumber} from '@opentelemetry/api-logs'
+import type {PluginApi} from '../types'
+import {getOtelLogger} from './otel'
+import {readTelemetryPluginConfig} from './telemetry-config'
+
+// ── Structured telemetry attributes (OTel LogRecord) ────────────
+
+type MessageLogAttributes = {
+  'message.lifecycle': 'llm_input' | 'llm_output' | 'message_sent'
+  'message.model'?: string
+  'message.provider'?: string
+  'message.session_key'?: string
+  'message.session_id'?: string
+  'message.content_length'?: number
+  'message.history_count'?: number
+  'message.images_count'?: number
+  'message.to'?: string
+  'message.success'?: boolean
+  'message.error'?: string
+  'message.channel_id'?: string
+  'instance.id'?: string
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function emit(attributes: MessageLogAttributes, api: PluginApi) {
+  const otelLogger = getOtelLogger('message-log')
+  if (otelLogger) {
+    otelLogger.emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: 'INFO',
+      body: `message.${attributes['message.lifecycle']}`,
+      attributes: attributes as Record<string, unknown>,
+    })
+  }
+
+  const a = attributes
+  switch (a['message.lifecycle']) {
+    case 'llm_input':
+      api.logger.info(
+        `message-log[llm-input]: model=${a['message.model'] ?? '?'} provider=${a['message.provider'] ?? '?'} history=${a['message.history_count'] ?? 0} images=${a['message.images_count'] ?? 0}`,
+      )
+      break
+    case 'llm_output':
+      api.logger.info(
+        `message-log[llm-output]: model=${a['message.model'] ?? '?'} provider=${a['message.provider'] ?? '?'} len=${a['message.content_length'] ?? 0}`,
+      )
+      break
+    case 'message_sent':
+      api.logger.info(
+        `message-log[sent]: to=${a['message.to'] ?? '?'} success=${a['message.success'] ?? '?'} channel=${a['message.channel_id'] ?? '?'}${a['message.error'] ? ` error="${a['message.error']}"` : ''}`,
+      )
+      break
+  }
+}
+
+// ── Registration ─────────────────────────────────────────────────
+
+export function registerMessageLog(api: PluginApi) {
+  const cfg = readTelemetryPluginConfig(api.pluginConfig)
+
+  if (!cfg.messageLogEnabled) {
+    api.logger.info('message-log: disabled (messageLogEnabled not set in pluginConfig)')
+    return
+  }
+
+  const instanceId = cfg.instanceId ?? process.env.INSTANCE_ID
+
+  // llm_input: capture what goes into the LLM (metadata only)
+  api.on('llm_input', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const model = typeof event.model === 'string' ? event.model : undefined
+    const provider = typeof event.provider === 'string' ? event.provider : undefined
+    const prompt = typeof event.prompt === 'string' ? event.prompt : ''
+    const historyMessages = Array.isArray(event.historyMessages) ? event.historyMessages : []
+    const imagesCount = typeof event.imagesCount === 'number' ? event.imagesCount : 0
+    const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
+    const sessionId = typeof ctx?.sessionId === 'string' ? ctx.sessionId : undefined
+
+    emit(
+      {
+        'message.lifecycle': 'llm_input',
+        ...(model ? {'message.model': model} : {}),
+        ...(provider ? {'message.provider': provider} : {}),
+        'message.content_length': prompt.length,
+        'message.history_count': historyMessages.length,
+        'message.images_count': imagesCount,
+        ...(sessionKey ? {'message.session_key': sessionKey} : {}),
+        ...(sessionId ? {'message.session_id': sessionId} : {}),
+        ...(instanceId ? {'instance.id': instanceId} : {}),
+      },
+      api,
+    )
+  })
+
+  // llm_output: capture LLM response metadata
+  api.on('llm_output', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const model = typeof event.model === 'string' ? event.model : undefined
+    const provider = typeof event.provider === 'string' ? event.provider : undefined
+    const assistantTexts = Array.isArray(event.assistantTexts) ? event.assistantTexts : []
+    const contentLength = assistantTexts
+      .filter((t): t is string => typeof t === 'string')
+      .reduce((sum, t) => sum + t.length, 0)
+    const sessionKey = typeof ctx?.sessionKey === 'string' ? ctx.sessionKey : undefined
+    const sessionId = typeof ctx?.sessionId === 'string' ? ctx.sessionId : undefined
+
+    emit(
+      {
+        'message.lifecycle': 'llm_output',
+        ...(model ? {'message.model': model} : {}),
+        ...(provider ? {'message.provider': provider} : {}),
+        'message.content_length': contentLength,
+        ...(sessionKey ? {'message.session_key': sessionKey} : {}),
+        ...(sessionId ? {'message.session_id': sessionId} : {}),
+        ...(instanceId ? {'instance.id': instanceId} : {}),
+      },
+      api,
+    )
+  })
+
+  // message_sent: capture channel delivery outcome
+  api.on('message_sent', (event: Record<string, unknown>, ctx?: Record<string, unknown>) => {
+    const to = typeof event.to === 'string' ? event.to : undefined
+    const content = typeof event.content === 'string' ? event.content : ''
+    const success = typeof event.success === 'boolean' ? event.success : undefined
+    const error = typeof event.error === 'string' ? event.error : undefined
+    const channelId = typeof ctx?.channelId === 'string' ? ctx.channelId : undefined
+
+    emit(
+      {
+        'message.lifecycle': 'message_sent',
+        ...(to ? {'message.to': to} : {}),
+        'message.content_length': content.length,
+        ...(success != null ? {'message.success': success} : {}),
+        ...(error ? {'message.error': error} : {}),
+        ...(channelId ? {'message.channel_id': channelId} : {}),
+        ...(instanceId ? {'instance.id': instanceId} : {}),
+      },
+      api,
+    )
+  })
+
+  api.logger.info('message-log: registered llm_input + llm_output + message_sent hooks')
+}

package/gateway/node-dangerous-allowlist.ts

@@ -0,0 +1,81 @@
+/**
+ * Ensures all dangerous node commands are in gateway.nodes.allowCommands
+ * so the AI agent can invoke them on connected Clawly nodes.
+ *
+ * Dangerous commands are defined by OpenClaw's node-command-policy and
+ * must be explicitly allowlisted. Safe commands work without allowlisting.
+ *
+ * Runs on gateway_start. Writes directly to openclaw.json via
+ * writeOpenclawConfig (no restart triggered — gateway.* changes are
+ * classified as "none" by the config watcher).
+ */
+import path from 'node:path'
+
+import type {PluginApi} from '../types'
+import {readOpenclawConfig, writeOpenclawConfig} from '../model-gateway-setup'
+
+const DANGEROUS_COMMANDS = [
+  // Browser commands (Mac nodes)
+  'browser.proxy',
+  'browser.navigate',
+  'browser.click',
+  'browser.type',
+  'browser.screenshot',
+  'browser.read',
+  'browser.tabs',
+  'browser.back',
+  'browser.scroll',
+  'browser.evaluate',
+  // Reminders + calendar (iOS nodes)
+  'reminders.add',
+  'calendar.add',
+]
+
+export function registerNodeDangerousAllowlist(api: PluginApi) {
+  api.on('gateway_start', async () => {
+    let stateDir: string
+    try {
+      stateDir = api.runtime.state.resolveStateDir()
+    } catch {
+      api.logger.warn('node-dangerous-allowlist: cannot resolve state dir, skipping')
+      return
+    }
+
+    const configPath = path.join(stateDir, 'openclaw.json')
+    let config: Record<string, unknown>
+    try {
+      config = readOpenclawConfig(configPath)
+    } catch {
+      api.logger.warn('node-dangerous-allowlist: failed to read config, skipping')
+      return
+    }
+
+    const gateway = (config.gateway as Record<string, unknown>) ?? {}
+    const nodes = (gateway.nodes as Record<string, unknown>) ?? {}
+    const existing: string[] = Array.isArray(nodes.allowCommands)
+      ? (nodes.allowCommands as string[])
+      : []
+
+    const existingSet = new Set(existing)
+    const toAdd = DANGEROUS_COMMANDS.filter((cmd) => !existingSet.has(cmd))
+
+    if (toAdd.length === 0) {
+      api.logger.info('node-dangerous-allowlist: all commands already allowlisted')
+      return
+    }
+
+    nodes.allowCommands = [...existing, ...toAdd]
+    gateway.nodes = nodes
+    config.gateway = gateway
+
+    try {
+      writeOpenclawConfig(configPath, config)
+    } catch {
+      api.logger.warn('node-dangerous-allowlist: failed to write config')
+      return
+    }
+    api.logger.info(
+      `node-dangerous-allowlist: added ${toAdd.length} commands to allowlist: ${toAdd.join(', ')}`,
+    )
+  })
+}

package/gateway/otel.test.ts

@@ -69,7 +69,15 @@ describe('initOtel', () => {
       },
     })
     expect(getOtelLogger()).toBeTruthy()
-    expect(loggerName).toBe('cron-telemetry')
+    expect(loggerName).toBe('clawly-plugins')
+  })
+
+  test('returns scoped loggers by name', () => {
+    initOtel({otelToken: 'tok', otelDataset: 'ds'})
+    const a = getOtelLogger('cron-telemetry')
+    const b = getOtelLogger('message-log')
+    expect(a).toBeTruthy()
+    expect(b).toBeTruthy()
   })
 
   test('falls back to legacy env vars', () => {

package/gateway/otel.ts

@@ -17,7 +17,7 @@ import {BatchLogRecordProcessor, LoggerProvider} from '@opentelemetry/sdk-logs'
 import {readTelemetryPluginConfig} from './telemetry-config'
 
 let provider: LoggerProvider | null = null
-let logger: Logger | null = null
+const loggers = new Map<string, Logger>()
 
 export function initOtel(
   pluginConfig?: Record<string, unknown>,
@@ -40,11 +40,16 @@ export function initOtel(
 
   provider = new LoggerProvider({resource})
   provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter))
-  logger = provider.getLogger('cron-telemetry')
   return true
 }
 
-export function getOtelLogger(): Logger | null {
+export function getOtelLogger(scope = 'clawly-plugins'): Logger | null {
+  if (!provider) return null
+  let logger = loggers.get(scope)
+  if (!logger) {
+    logger = provider.getLogger(scope)
+    loggers.set(scope, logger)
+  }
   return logger
 }
 
@@ -52,6 +57,6 @@ export async function shutdownOtel(): Promise<void> {
   if (provider) {
     await provider.shutdown()
     provider = null
-    logger = null
+    loggers.clear()
   }
 }

package/gateway/telemetry-config.test.ts

@@ -17,6 +17,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: 'clawly-otel-logs-dev',
       posthogApiKey: 'ph-key',
       posthogHost: 'https://us.i.posthog.com',
+      messageLogEnabled: false,
     })
   })
 
@@ -35,6 +36,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: 'clawly-otel-logs-dev',
       posthogApiKey: 'ph-key',
       posthogHost: 'https://us.i.posthog.com',
+      messageLogEnabled: false,
     })
   })
 
@@ -53,6 +55,7 @@ describe('readTelemetryPluginConfig', () => {
       otelDataset: undefined,
       posthogApiKey: undefined,
       posthogHost: undefined,
+      messageLogEnabled: false,
     })
   })
 })

package/gateway/telemetry-config.ts

@@ -4,6 +4,7 @@ export interface TelemetryPluginConfig {
   otelDataset?: string
   posthogApiKey?: string
   posthogHost?: string
+  messageLogEnabled?: boolean
 }
 
 function readString(value: unknown): string | undefined {
@@ -23,5 +24,6 @@ export function readTelemetryPluginConfig(
     otelDataset: readString(cfg.otelDataset),
     posthogApiKey: readString(cfg.posthogApiKey),
     posthogHost: readString(cfg.posthogHost),
+    messageLogEnabled: cfg.messageLogEnabled === true || cfg.messageLogEnabled === 'true',
   }
 }

package/index.ts

@@ -34,6 +34,9 @@
  * - 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
+ * - llm_input             — message-log (dev-only): logs model, provider, history size, images count (no content)
+ * - llm_output            — message-log (dev-only): logs model, provider, content length (no content)
+ * - message_sent          — message-log (dev-only): logs channel delivery outcome (no content)
  * - 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
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.28.1",
+  "version": "1.29.0-beta.0",
   "module": "index.ts",
   "type": "module",
   "repository": {

package/tools/clawly-msg-break.ts

@@ -0,0 +1,32 @@
+/**
+ * Agent tool: clawly_msg_break — split the current response into multiple messages.
+ *
+ * When called, this tool acts as a structural boundary: the text before the
+ * tool call becomes one assistant message, and the text after becomes a new one.
+ * The client relies on the existing "text reset" mechanism (post-tool-call text
+ * detection) to create the split — the tool itself is a no-op.
+ *
+ * This is preferred over in-band separator tokens (e.g. [MSG_BREAK]) because
+ * tool calls are structured and never leak to other channels (Telegram, etc.).
+ */
+
+import type {PluginApi} from '../types'
+
+const TOOL_NAME = 'clawly_msg_break'
+
+export function registerMsgBreakTool(api: PluginApi) {
+  api.registerTool({
+    name: TOOL_NAME,
+    description:
+      'Split the current response into multiple messages. Call this between distinct thoughts or topics to send them as separate message bubbles. The text you wrote before this call becomes one message; continue writing after the call to start a new message.',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+    async execute() {
+      return {content: [{type: 'text', text: JSON.stringify({ok: true})}]}
+    },
+  })
+
+  api.logger.info(`tool: registered ${TOOL_NAME} agent tool`)
+}

package/tools/index.ts

@@ -1,6 +1,7 @@
 import type {PluginApi} from '../types'
 import {registerCalendarTools} from './clawly-calendar'
 import {registerIsUserOnlineTool} from './clawly-is-user-online'
+import {registerMsgBreakTool} from './clawly-msg-break'
 import {registerDeepSearchTool, registerGrokSearchTool, registerSearchTool} from './clawly-search'
 import {registerSendAppPushTool} from './clawly-send-app-push'
 import {registerSendImageTool} from './clawly-send-image'
@@ -9,6 +10,7 @@ import {registerSendMessageTool} from './clawly-send-message'
 export function registerTools(api: PluginApi) {
   registerCalendarTools(api)
   registerIsUserOnlineTool(api)
+  registerMsgBreakTool(api)
   registerSearchTool(api)
   registerDeepSearchTool(api)
   registerGrokSearchTool(api)

package/gateway/node-browser-allowlist.ts

@@ -1,62 +0,0 @@
-/**
- * Ensures browser.* node commands are in gateway.nodes.allowCommands
- * so the AI agent can invoke them on connected Clawly Mac nodes.
- *
- * Runs on gateway_start. Writes directly to openclaw.json via
- * writeOpenclawConfig (no restart triggered — gateway.* changes are
- * classified as "none" by the config watcher).
- */
-import path from 'node:path'
-
-import type {PluginApi} from '../types'
-import {readOpenclawConfig, writeOpenclawConfig} from '../model-gateway-setup'
-
-const BROWSER_COMMANDS = [
-  'browser.proxy',
-  'browser.navigate',
-  'browser.click',
-  'browser.type',
-  'browser.screenshot',
-  'browser.read',
-  'browser.tabs',
-  'browser.back',
-  'browser.scroll',
-  'browser.evaluate',
-]
-
-export function registerNodeBrowserAllowlist(api: PluginApi) {
-  api.on('gateway_start', async () => {
-    let stateDir: string
-    try {
-      stateDir = api.runtime.state.resolveStateDir()
-    } catch {
-      api.logger.warn('node-browser-allowlist: cannot resolve state dir, skipping')
-      return
-    }
-
-    const configPath = path.join(stateDir, 'openclaw.json')
-    const config = readOpenclawConfig(configPath)
-
-    // Ensure gateway.nodes.allowCommands includes browser.* commands
-    const gateway = (config.gateway as Record<string, unknown>) ?? {}
-    const nodes = (gateway.nodes as Record<string, unknown>) ?? {}
-    const existing: string[] = Array.isArray(nodes.allowCommands)
-      ? (nodes.allowCommands as string[])
-      : []
-
-    const existingSet = new Set(existing)
-    const toAdd = BROWSER_COMMANDS.filter((cmd) => !existingSet.has(cmd))
-
-    if (toAdd.length === 0) {
-      api.logger.info('node-browser-allowlist: browser commands already allowlisted')
-      return
-    }
-
-    nodes.allowCommands = [...existing, ...toAdd]
-    gateway.nodes = nodes
-    config.gateway = gateway
-
-    writeOpenclawConfig(configPath, config)
-    api.logger.info(`node-browser-allowlist: added ${toAdd.length} browser commands to allowlist`)
-  })
-}