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

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.25.0",
+  "version": "1.26.0-beta.1",
   "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": [

package/tools/clawly-send-image.ts

@@ -0,0 +1,228 @@
+/**
+ * Agent tool: clawly_send_image — send an image to the user.
+ *
+ * Accepts a URL (https/http) or a local file path (or arrays of either).
+ * URLs are downloaded and cached locally. Magic-byte validation ensures
+ * only real images are served. Injects a MEDIA:<path> assistant message
+ * via chat.inject so the mobile client renders inline images.
+ */
+
+import crypto from 'node:crypto'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+import {fileTypeFromBuffer, fileTypeFromFile} from 'file-type'
+
+import {injectAssistantMessage, resolveSessionKey} from '../gateway/inject'
+import type {PluginApi} from '../types'
+
+const TOOL_NAME = 'clawly_send_image'
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024 // 50 MB
+
+const parameters: Record<string, unknown> = {
+  type: 'object',
+  required: ['source'],
+  properties: {
+    source: {
+      oneOf: [
+        {type: 'string', description: 'Image URL (https://...) or local file path'},
+        {
+          type: 'array',
+          items: {type: 'string'},
+          description: 'Array of image URLs or local file paths',
+        },
+      ],
+    },
+    caption: {type: 'string', description: 'Optional caption text'},
+  },
+}
+
+// ── Image MIME allowlist (aligned with expo-image, excluding SVG) ────
+
+const IMAGE_MIMES = new Set([
+  'image/jpeg',
+  'image/png',
+  'image/apng',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'image/heic',
+  'image/bmp',
+  'image/x-icon',
+])
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function downloadsDir(api: PluginApi): string {
+  return path.join(api.runtime.state.resolveStateDir(), 'clawly', 'downloads')
+}
+
+function extFromUrl(url: string): string {
+  try {
+    const pathname = new URL(url).pathname
+    const ext = path.extname(pathname).toLowerCase()
+    if (
+      ext &&
+      ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.avif', '.heic', '.ico'].includes(ext)
+    )
+      return ext
+  } catch {}
+  return '.jpg'
+}
+
+function localPath(source: string, ext: string, api: PluginApi): string {
+  const hash = crypto.createHash('sha256').update(source).digest('hex')
+  return path.join(downloadsDir(api), `${hash}${ext}`)
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fsp.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function formatMediaMessage(filePaths: string[], caption?: string): string {
+  const parts: string[] = []
+  if (caption) parts.push(caption)
+  for (const p of filePaths) parts.push(`MEDIA:${p}`)
+  return parts.join('\n')
+}
+
+// ── Download ─────────────────────────────────────────────────────────
+
+/** Downloads an image, validates it, and saves with the detected extension. Returns the final path or throws. */
+const DOWNLOAD_TIMEOUT_MS = 30_000
+
+async function downloadImage(url: string, api: PluginApi): Promise<string> {
+  const dir = downloadsDir(api)
+  await fsp.mkdir(dir, {recursive: true})
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS)
+  try {
+    const res = await fetch(url, {redirect: 'follow', signal: controller.signal})
+    if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`)
+
+    const contentLength = res.headers.get('content-length')
+    if (contentLength && Number(contentLength) > MAX_DOWNLOAD_BYTES) {
+      throw new Error(`file too large (${contentLength} bytes, max ${MAX_DOWNLOAD_BYTES})`)
+    }
+
+    const chunks: Uint8Array[] = []
+    let totalSize = 0
+    const reader = res.body?.getReader()
+    if (!reader) throw new Error('no response body')
+
+    while (true) {
+      const {done, value} = await reader.read()
+      if (done) break
+      totalSize += value.byteLength
+      if (totalSize > MAX_DOWNLOAD_BYTES) {
+        reader.cancel()
+        throw new Error(`file too large (exceeded ${MAX_DOWNLOAD_BYTES} bytes)`)
+      }
+      chunks.push(value)
+    }
+
+    const buffer = Buffer.concat(chunks)
+
+    const type = await fileTypeFromBuffer(buffer)
+    if (!type || !IMAGE_MIMES.has(type.mime)) {
+      throw new Error('downloaded file is not a recognized image format')
+    }
+
+    const dest = localPath(url, `.${type.ext}`, api)
+    await fsp.writeFile(dest, buffer)
+    api.logger.info(`${TOOL_NAME}: downloaded ${url} -> ${dest} (${buffer.length} bytes)`)
+    return dest
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+// ── Tool registration ────────────────────────────────────────────────
+
+export function registerSendImageTool(api: PluginApi) {
+  api.registerTool({
+    name: TOOL_NAME,
+    description:
+      'Send one or more images to the user. Accepts a single URL/path or an array of URLs/paths. Images are displayed inline in the chat.',
+    parameters,
+    async execute(_toolCallId, params) {
+      // Normalize source to string[]
+      let sources: string[]
+      if (typeof params.source === 'string') {
+        sources = [params.source.trim()]
+      } else if (Array.isArray(params.source)) {
+        sources = params.source
+          .filter((s): s is string => typeof s === 'string')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      } else {
+        sources = []
+      }
+
+      if (sources.length === 0) {
+        return {content: [{type: 'text', text: JSON.stringify({error: 'source is required'})}]}
+      }
+
+      const caption = typeof params.caption === 'string' ? params.caption.trim() : undefined
+
+      const resolveSource = async (source: string): Promise<string> => {
+        if (source.startsWith('https://') || source.startsWith('http://')) {
+          // Check cache with URL-derived extension (best guess)
+          const guessExt = extFromUrl(source)
+          const cached = localPath(source, guessExt, api)
+          if (await fileExists(cached)) {
+            api.logger.info(`${TOOL_NAME}: serving cached ${cached}`)
+            return cached
+          }
+
+          return await downloadImage(source, api)
+        }
+
+        // Local file source
+        if (!(await fileExists(source))) {
+          throw new Error(`${source}: file not found`)
+        }
+
+        const type = await fileTypeFromFile(source)
+        if (!type || !IMAGE_MIMES.has(type.mime)) {
+          throw new Error(`${source}: not a recognized image format`)
+        }
+
+        // Copy to downloads dir so the outbound endpoint can serve it
+        const dest = localPath(source, `.${type.ext}`, api)
+        if (!(await fileExists(dest))) {
+          const dir = path.dirname(dest)
+          await fsp.mkdir(dir, {recursive: true})
+          await fsp.copyFile(source, dest)
+        }
+        return dest
+      }
+
+      try {
+        const resolved = await Promise.all(sources.map(resolveSource))
+
+        // Inject MEDIA: lines as an assistant message so they appear in the chat
+        const mediaMessage = formatMediaMessage(resolved, caption)
+        const sessionKey = await resolveSessionKey('clawly', api)
+        await injectAssistantMessage({sessionKey, message: mediaMessage}, api)
+        api.logger.info(`${TOOL_NAME}: injected ${resolved.length} image(s) into session`)
+
+        return {
+          content: [{type: 'text', text: JSON.stringify({sent: true, count: resolved.length})}],
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        api.logger.error(`${TOOL_NAME}: ${msg}`)
+        return {content: [{type: 'text', text: JSON.stringify({error: msg})}]}
+      }
+    },
+  })
+
+  api.logger.info(`tool: registered ${TOOL_NAME} agent tool`)
+}

package/tools/index.ts

@@ -1,10 +1,12 @@
 import type {PluginApi} from '../types'
 import {registerIsUserOnlineTool} from './clawly-is-user-online'
 import {registerSendAppPushTool} from './clawly-send-app-push'
+import {registerSendImageTool} from './clawly-send-image'
 import {registerSendMessageTool} from './clawly-send-message'
 
 export function registerTools(api: PluginApi) {
   registerIsUserOnlineTool(api)
   registerSendAppPushTool(api)
+  registerSendImageTool(api)
   registerSendMessageTool(api)
 }