@2en/clawly-plugins 1.30.0-beta.2 → 1.30.0-beta.3

package/index.ts

@@ -17,7 +17,7 @@
  * 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_file         — send a file to the user (URL or local path under $HOME/tmp)
  * - clawly_search             — web search via Perplexity (replaces denied web_search)
  * - clawly_send_message      — send a message to user via main session agent (supports role: user|assistant)
  *

package/outbound.ts

@@ -18,6 +18,7 @@ import fsp from 'node:fs/promises'
 import type {IncomingMessage, ServerResponse} from 'node:http'
 import os from 'node:os'
 import path from 'node:path'
+import mime from 'mime'
 
 import type {PluginApi} from './index'
 import {createAccessToken, guardHttpAuth, resolveGatewaySecret, sendJson} from './lib/httpAuth'
@@ -132,24 +133,7 @@ export function registerOutboundMethods(api: PluginApi) {
 
 // ── HTTP route: GET /clawly/file/outbound?path=<original-path> ─────────────
 
-const MIME: Record<string, string> = {
-  '.mp3': 'audio/mpeg',
-  '.wav': 'audio/wav',
-  '.ogg': 'audio/ogg',
-  '.m4a': 'audio/mp4',
-  '.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',
-}
+// Content-Type resolution via `mime` package (replaces hardcoded map)
 
 /** Directories from which direct-path serving is allowed (no hash required). */
 let allowedRoots: string[] | null = null
@@ -183,6 +167,12 @@ async function resolveOutboundFile(rawPath: string, stateDir?: string): Promise<
   return null
 }
 
+export function buildContentDisposition(filename: string): string {
+  const asciiName = filename.replace(/[^\x20-\x7E]/g, '_').replace(/["\\]/g, '\\$&')
+  const utf8Name = encodeURIComponent(filename)
+  return `attachment; filename="${asciiName}"; filename*=UTF-8''${utf8Name}`
+}
+
 export function registerOutboundHttpRoute(api: PluginApi) {
   const stateDir = api.runtime.state.resolveStateDir()
 
@@ -219,8 +209,7 @@ export function registerOutboundHttpRoute(api: PluginApi) {
         return
       }
 
-      const ext = path.extname(resolved).toLowerCase()
-      const contentType = MIME[ext] ?? 'application/octet-stream'
+      const contentType = mime.getType(resolved) ?? 'application/octet-stream'
       const stat = await fsp.stat(resolved)
       const total = stat.size
 
@@ -230,6 +219,15 @@ export function registerOutboundHttpRoute(api: PluginApi) {
         return
       }
 
+      const downloadFilename = url.searchParams.get('download')
+      const baseHeaders: Record<string, string | number> = {
+        'Content-Type': contentType,
+        'Accept-Ranges': 'bytes',
+      }
+      if (downloadFilename && path.extname(downloadFilename) === path.extname(resolved)) {
+        baseHeaders['Content-Disposition'] = buildContentDisposition(downloadFilename)
+      }
+
       const rangeHeader = _req.headers.range
 
       if (rangeHeader) {
@@ -241,9 +239,8 @@ export function registerOutboundHttpRoute(api: PluginApi) {
           const stream = fs.createReadStream(resolved, {start, end})
 
           res.writeHead(206, {
-            'Content-Type': contentType,
+            ...baseHeaders,
             'Content-Range': `bytes ${start}-${end}/${total}`,
-            'Accept-Ranges': 'bytes',
             'Content-Length': chunkSize,
           })
           stream.pipe(res)
@@ -256,9 +253,8 @@ export function registerOutboundHttpRoute(api: PluginApi) {
 
       const buffer = await fsp.readFile(resolved)
       res.writeHead(200, {
-        'Content-Type': contentType,
+        ...baseHeaders,
         'Content-Length': total,
-        'Accept-Ranges': 'bytes',
       })
       res.end(buffer)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.30.0-beta.2",
+  "version": "1.30.0-beta.3",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -13,8 +13,9 @@
     "@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",
+    "mime": "^4.1.0",
+    "posthog-node": "^5.28.0",
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [
@@ -47,8 +48,5 @@
     "extensions": [
       "./index.ts"
     ]
-  },
-  "devDependencies": {
-    "json5": "^2.2.3"
   }
 }

package/tools/clawly-send-file.test.ts

@@ -0,0 +1,400 @@
+import {afterAll, beforeEach, describe, expect, mock, test} from 'bun:test'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import type {PluginApi} from '../types'
+import {registerSendFileTool} from './clawly-send-file'
+
+// ── Mocks ────────────────────────────────────────────────────────
+
+let mockInjectParams: {sessionKey: string; message: string} | null = null
+let mockFileTypeFromBuffer: (buf: Uint8Array) => Promise<{mime: string; ext: string} | undefined>
+let mockFileTypeFromFile: (p: string) => Promise<{mime: string; ext: string} | undefined>
+
+mock.module('../gateway/inject', () => ({
+  resolveSessionKey: async () => 'agent:clawly:main',
+  injectAssistantMessage: async (params: {sessionKey: string; message: string}) => {
+    mockInjectParams = params
+    return {ok: true, messageId: 'msg-123'}
+  },
+}))
+
+mock.module('file-type', () => ({
+  fileTypeFromBuffer: async (buf: Uint8Array) => mockFileTypeFromBuffer(buf),
+  fileTypeFromFile: async (p: string) => mockFileTypeFromFile(p),
+}))
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+type ToolExecute = (
+  toolCallId: string,
+  params: Record<string, unknown>,
+) => Promise<{content: {type: string; text: string}[]}>
+
+function createMockApi(stateDir?: string): {
+  api: PluginApi
+  logs: {level: string; msg: string}[]
+  execute: ToolExecute
+} {
+  const logs: {level: string; msg: string}[] = []
+  let registeredExecute: ToolExecute | null = null
+  const dir = stateDir ?? path.join(os.tmpdir(), `clawly-send-file-test-${Date.now()}`)
+
+  const api = {
+    id: 'test',
+    name: 'test',
+    logger: {
+      info: (msg: string) => logs.push({level: 'info', msg}),
+      warn: (msg: string) => logs.push({level: 'warn', msg}),
+      error: (msg: string) => logs.push({level: 'error', msg}),
+    },
+    runtime: {
+      state: {
+        resolveStateDir: () => dir,
+      },
+    },
+    registerTool: (tool: {execute: ToolExecute}) => {
+      registeredExecute = tool.execute
+    },
+  } as unknown as PluginApi
+
+  registerSendFileTool(api)
+
+  return {api, logs, execute: registeredExecute!}
+}
+
+function parseResult(res: {content: {type: string; text: string}[]}): Record<string, unknown> {
+  return JSON.parse(res.content[0].text)
+}
+
+// Minimal PNG magic bytes (first 8 bytes)
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+let originalFetch: typeof globalThis.fetch
+
+beforeEach(() => {
+  mockInjectParams = null
+  mockFileTypeFromBuffer = async () => ({mime: 'image/png', ext: 'png'})
+  mockFileTypeFromFile = async () => ({mime: 'image/png', ext: 'png'})
+
+  originalFetch = globalThis.fetch
+  globalThis.fetch = (async (url: string, init?: RequestInit) => {
+    const body = new ReadableStream({
+      start(controller) {
+        controller.enqueue(PNG_BYTES)
+        controller.close()
+      },
+    })
+    return new Response(body, {
+      status: 200,
+      headers: {'content-length': String(PNG_BYTES.length)},
+    })
+  }) as typeof fetch
+})
+
+afterAll(() => {
+  globalThis.fetch = originalFetch
+})
+
+// ── Tests ────────────────────────────────────────────────────────
+
+describe('clawly_send_file', () => {
+  describe('validation', () => {
+    test('returns error for empty source', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: ''}))
+      expect(res.error).toBe('source is required')
+    })
+
+    test('returns error for missing source', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {}))
+      expect(res.error).toBe('source is required')
+    })
+
+    test('returns error for empty array source', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: []}))
+      expect(res.error).toBe('source is required')
+    })
+
+    test('returns error for array of empty strings', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: ['', '  ', '']}))
+      expect(res.error).toBe('source is required')
+    })
+  })
+
+  describe('URL source', () => {
+    test('downloads URL and injects FILE message', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: 'https://example.com/image.png'}))
+
+      expect(res.sent).toBe(true)
+      expect(res.count).toBe(1)
+      expect(mockInjectParams).not.toBeNull()
+      expect(mockInjectParams!.message).toContain('FILE:')
+      expect(mockInjectParams!.message).toMatch(/FILE:\/.*\/[a-f0-9]+\.png\?filename=image\.png/)
+    })
+
+    test('rejects URL with executable extension', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: 'https://example.com/script.sh'}))
+
+      expect(res.error).toContain('executable extension')
+    })
+
+    test('rejects downloaded executable by MIME', async () => {
+      mockFileTypeFromBuffer = async () => ({
+        mime: 'application/x-elf',
+        ext: 'elf',
+      })
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: 'https://example.com/binary'}))
+
+      expect(res.error).toContain('executable')
+    })
+
+    test('uses caption when provided', async () => {
+      const {execute} = createMockApi()
+      await execute('tc-1', {
+        source: 'https://example.com/photo.jpg',
+        caption: 'Check this out',
+      })
+
+      expect(mockInjectParams!.message).toStartWith('Check this out')
+      expect(mockInjectParams!.message).toContain('FILE:')
+    })
+  })
+
+  describe('local file source', () => {
+    test('accepts file under /tmp', async () => {
+      const tmpFile = path.join('/tmp', `clawly-send-file-test-${Date.now()}.txt`)
+      await fsp.writeFile(tmpFile, 'hello')
+      try {
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: tmpFile}))
+
+        expect(res.sent).toBe(true)
+        expect(res.count).toBe(1)
+        expect(mockInjectParams!.message).toContain('FILE:')
+      } finally {
+        await fsp.unlink(tmpFile).catch(() => {})
+      }
+    })
+
+    test('accepts file under $HOME', async () => {
+      const homeFile = path.join(os.homedir(), `clawly-send-file-test-${Date.now()}.txt`)
+      await fsp.writeFile(homeFile, 'hello')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: homeFile}))
+
+        expect(res.sent).toBe(true)
+        expect(res.count).toBe(1)
+      } finally {
+        await fsp.unlink(homeFile).catch(() => {})
+      }
+    })
+
+    test('accepts tilde-expanded path', async () => {
+      const homeFile = path.join(os.homedir(), `clawly-send-file-test-${Date.now()}.txt`)
+      await fsp.writeFile(homeFile, 'hello')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: `~/${path.basename(homeFile)}`}))
+
+        expect(res.sent).toBe(true)
+      } finally {
+        await fsp.unlink(homeFile).catch(() => {})
+      }
+    })
+
+    test('rejects file outside $HOME and /tmp', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: '/etc/hosts'}))
+
+      expect(res.error).toContain('$HOME or /tmp')
+    })
+
+    test('rejects dot files', async () => {
+      const dotFile = path.join('/tmp', `.clawly-send-file-test-${Date.now()}`)
+      await fsp.writeFile(dotFile, 'secret')
+      try {
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: dotFile}))
+
+        expect(res.error).toContain('dot files')
+      } finally {
+        await fsp.unlink(dotFile).catch(() => {})
+      }
+    })
+
+    test('rejects path with dot component (e.g. .openclaw)', async () => {
+      const inDotDir = path.join('/tmp', '.openclaw', `test-${Date.now()}.txt`)
+      await fsp.mkdir(path.dirname(inDotDir), {recursive: true})
+      await fsp.writeFile(inDotDir, 'config')
+      try {
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: inDotDir}))
+
+        expect(res.error).toContain('dot files')
+      } finally {
+        await fsp.unlink(inDotDir).catch(() => {})
+        await fsp.rmdir(path.dirname(inDotDir)).catch(() => {})
+      }
+    })
+
+    test('rejects executable by extension', async () => {
+      const shFile = path.join('/tmp', `clawly-send-file-test-${Date.now()}.sh`)
+      await fsp.writeFile(shFile, '#!/bin/bash\necho hi')
+      try {
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: shFile}))
+
+        expect(res.error).toContain('executable')
+      } finally {
+        await fsp.unlink(shFile).catch(() => {})
+      }
+    })
+
+    test('rejects executable by MIME', async () => {
+      const binFile = path.join('/tmp', `clawly-send-file-test-${Date.now()}.bin`)
+      await fsp.writeFile(binFile, '\x7fELF')
+      try {
+        mockFileTypeFromFile = async () => ({
+          mime: 'application/x-elf',
+          ext: 'elf',
+        })
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: binFile}))
+
+        expect(res.error).toContain('executable')
+      } finally {
+        await fsp.unlink(binFile).catch(() => {})
+      }
+    })
+
+    test('returns error for non-existent file', async () => {
+      const {execute} = createMockApi()
+      const res = parseResult(await execute('tc-1', {source: '/tmp/nonexistent-file-12345.txt'}))
+
+      expect(res.error).toContain('file not found')
+    })
+  })
+
+  describe('state dir restriction', () => {
+    test('rejects file directly under state dir', async () => {
+      const stateDir = path.join('/tmp', `.clawly-state-test-${Date.now()}`)
+      const stateFile = path.join(stateDir, 'config.json')
+      await fsp.mkdir(stateDir, {recursive: true})
+      await fsp.writeFile(stateFile, '{}')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'application/json', ext: 'json'})
+        const {execute} = createMockApi(stateDir)
+        const res = parseResult(await execute('tc-1', {source: stateFile}))
+        expect(res.error).toContain('state directory')
+      } finally {
+        await fsp.rm(stateDir, {recursive: true}).catch(() => {})
+      }
+    })
+
+    test('rejects file in non-allowed state subdir', async () => {
+      const stateDir = path.join('/tmp', `.clawly-state-test-${Date.now()}`)
+      const secretFile = path.join(stateDir, 'agents', 'secret.txt')
+      await fsp.mkdir(path.dirname(secretFile), {recursive: true})
+      await fsp.writeFile(secretFile, 'secret')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi(stateDir)
+        const res = parseResult(await execute('tc-1', {source: secretFile}))
+        expect(res.error).toContain('state directory')
+      } finally {
+        await fsp.rm(stateDir, {recursive: true}).catch(() => {})
+      }
+    })
+
+    test('allows file under state dir clawly/', async () => {
+      const stateDir = path.join('/tmp', `.clawly-state-test-${Date.now()}`)
+      const allowedFile = path.join(stateDir, 'clawly', 'data.txt')
+      await fsp.mkdir(path.dirname(allowedFile), {recursive: true})
+      await fsp.writeFile(allowedFile, 'ok')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi(stateDir)
+        const res = parseResult(await execute('tc-1', {source: allowedFile}))
+        expect(res.sent).toBe(true)
+      } finally {
+        await fsp.rm(stateDir, {recursive: true}).catch(() => {})
+      }
+    })
+
+    test('allows file under state dir canvas/', async () => {
+      const stateDir = path.join('/tmp', `.clawly-state-test-${Date.now()}`)
+      const allowedFile = path.join(stateDir, 'canvas', 'sketch.png')
+      await fsp.mkdir(path.dirname(allowedFile), {recursive: true})
+      await fsp.writeFile(allowedFile, 'ok')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'image/png', ext: 'png'})
+        const {execute} = createMockApi(stateDir)
+        const res = parseResult(await execute('tc-1', {source: allowedFile}))
+        expect(res.sent).toBe(true)
+      } finally {
+        await fsp.rm(stateDir, {recursive: true}).catch(() => {})
+      }
+    })
+
+    test('allows file under state dir memory/', async () => {
+      const stateDir = path.join('/tmp', `.clawly-state-test-${Date.now()}`)
+      const allowedFile = path.join(stateDir, 'memory', 'note.md')
+      await fsp.mkdir(path.dirname(allowedFile), {recursive: true})
+      await fsp.writeFile(allowedFile, 'ok')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi(stateDir)
+        const res = parseResult(await execute('tc-1', {source: allowedFile}))
+        expect(res.sent).toBe(true)
+      } finally {
+        await fsp.rm(stateDir, {recursive: true}).catch(() => {})
+      }
+    })
+  })
+
+  describe('array source', () => {
+    test('processes multiple sources', async () => {
+      const tmp1 = path.join('/tmp', `clawly-send-file-a-${Date.now()}.txt`)
+      const tmp2 = path.join('/tmp', `clawly-send-file-b-${Date.now()}.txt`)
+      await fsp.writeFile(tmp1, 'a')
+      await fsp.writeFile(tmp2, 'b')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: [tmp1, tmp2]}))
+
+        expect(res.sent).toBe(true)
+        expect(res.count).toBe(2)
+        expect(mockInjectParams!.message.split('FILE:').length - 1).toBe(2)
+      } finally {
+        await fsp.unlink(tmp1).catch(() => {})
+        await fsp.unlink(tmp2).catch(() => {})
+      }
+    })
+
+    test('filters empty strings from array', async () => {
+      const tmpFile = path.join('/tmp', `clawly-send-file-${Date.now()}.txt`)
+      await fsp.writeFile(tmpFile, 'x')
+      try {
+        mockFileTypeFromFile = async () => ({mime: 'text/plain', ext: 'txt'})
+        const {execute} = createMockApi()
+        const res = parseResult(await execute('tc-1', {source: ['', tmpFile, '  ', tmpFile]}))
+
+        expect(res.sent).toBe(true)
+        expect(res.count).toBe(2)
+      } finally {
+        await fsp.unlink(tmpFile).catch(() => {})
+      }
+    })
+  })
+})

package/tools/clawly-send-file.ts

@@ -0,0 +1,307 @@
+/**
+ * Agent tool: clawly_send_file — send a file to the user.
+ *
+ * Accepts a URL (https/http) or a local file path (or arrays of either).
+ * URLs are downloaded and cached locally. Injects a FILE:<path>?<filename> assistant
+ * message via chat.inject so the mobile client can render or display the file.
+ *
+ * Restrictions:
+ * - URLs: executable files are rejected (by MIME/extension).
+ * - Local files:
+ *   - Dot files rejected (e.g. ~/.openclaw, .env, .bashrc).
+ *   - Only files under $HOME or /tmp (files outside home are rejected unless in /tmp).
+ *   - State dir ($OPENCLAW_STATE_DIR) blocked, except clawly/, canvas/, memory/ subdirs.
+ *   - Executable files rejected (binaries + script extensions).
+ */
+
+import crypto from 'node:crypto'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+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_file'
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024 // 50 MB
+
+const parameters: Record<string, unknown> = {
+  type: 'object',
+  required: ['source'],
+  properties: {
+    source: {
+      oneOf: [
+        {type: 'string', description: 'File URL (https://...) or local file path'},
+        {
+          type: 'array',
+          items: {type: 'string'},
+          description: 'Array of file URLs or local file paths',
+        },
+      ],
+    },
+    caption: {type: 'string', description: 'Optional caption text'},
+  },
+}
+
+// ── Executable blocklist ───────────────────────────────────────────────
+
+/** MIME types for binary executables (ELF, Mach-O, PE, etc.) */
+const EXECUTABLE_MIMES = new Set([
+  'application/x-executable',
+  'application/x-elf',
+  'application/x-sharedlib',
+  'application/x-pie-executable',
+  'application/x-mach-binary',
+  'application/x-mach-binary-fat',
+  'application/x-msdownload',
+])
+
+/** Extensions for executables and executable scripts */
+const EXECUTABLE_EXTS = new Set([
+  '.exe',
+  '.com',
+  '.bat',
+  '.cmd',
+  '.sh',
+  '.bash',
+  '.csh',
+  '.zsh',
+  '.ps1',
+  '.psm1',
+])
+
+function isExecutableByMime(mime?: string): boolean {
+  return !!mime && EXECUTABLE_MIMES.has(mime)
+}
+
+function isExecutableByExt(filePath: string): boolean {
+  const ext = path.extname(filePath).toLowerCase()
+  return EXECUTABLE_EXTS.has(ext)
+}
+
+function hasDotFileComponent(filePath: string): boolean {
+  const normalized = path.normalize(filePath)
+  const parts = normalized.split(path.sep)
+  return parts.some((p) => p.startsWith('.') && p.length > 1)
+}
+
+function isUnderAllowedRoot(filePath: string): boolean {
+  const resolved = path.resolve(filePath)
+  const home = os.homedir()
+  return resolved.startsWith(home + path.sep) || resolved === home || resolved.startsWith('/tmp/')
+}
+
+// ── 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) return ext
+  } catch {}
+  return ''
+}
+
+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 sourceFilename(source: string): string {
+  try {
+    return path.basename(new URL(source).pathname) || path.basename(source)
+  } catch {
+    return path.basename(source)
+  }
+}
+
+function formatMediaMessage(filePaths: string[], sources: string[], caption?: string): string {
+  const parts: string[] = []
+  if (caption) parts.push(caption)
+  for (let i = 0; i < filePaths.length; i++) {
+    const filename = sourceFilename(sources[i] ?? filePaths[i])
+    const pathBasename = path.basename(filePaths[i])
+    const qs = filename !== pathBasename ? `?filename=${encodeURIComponent(filename)}` : ''
+    parts.push(`FILE:${filePaths[i]}${qs}`)
+  }
+  return parts.join('\n')
+}
+
+// ── Download ─────────────────────────────────────────────────────────
+
+const DOWNLOAD_TIMEOUT_MS = 30_000
+
+async function downloadFile(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 && isExecutableByMime(type.mime)) {
+      throw new Error('downloaded file is an executable and cannot be sent')
+    }
+    const urlExt = extFromUrl(url)
+    if (urlExt && EXECUTABLE_EXTS.has(urlExt)) {
+      throw new Error('downloaded file has executable extension and cannot be sent')
+    }
+
+    // Use urlExt for cache key so resolveSource cache lookup matches
+    const dest = localPath(url, urlExt, 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 registerSendFileTool(api: PluginApi) {
+  api.registerTool({
+    name: TOOL_NAME,
+    description:
+      'Send one or more files to the user. Accepts a single URL/path or an array of URLs/paths. Supports images, documents, audio, etc. Executable files and dot files are not allowed. Local files must be under $HOME or /tmp.',
+    parameters,
+    async execute(_toolCallId, params) {
+      let sources: string[]
+      if (typeof params.source === 'string') {
+        sources = [params.source.trim()].filter(Boolean)
+      } 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://')) {
+          const guessExt = extFromUrl(source)
+          if (guessExt && EXECUTABLE_EXTS.has(guessExt)) {
+            throw new Error(`${source}: URL has executable extension and cannot be sent`)
+          }
+          const cached = localPath(source, guessExt, api)
+          if (await fileExists(cached)) {
+            api.logger.info(`${TOOL_NAME}: serving cached ${cached}`)
+            return cached
+          }
+          return await downloadFile(source, api)
+        }
+
+        // Local file source
+        const resolved = path.resolve(source.replace(/^~/, os.homedir()))
+        if (!(await fileExists(resolved))) {
+          throw new Error(`${source}: file not found`)
+        }
+        if (!isUnderAllowedRoot(resolved)) {
+          throw new Error(
+            `${source}: file must be under $HOME or /tmp (files outside home are not allowed)`,
+          )
+        }
+        // Block state dir files except clawly/, canvas/, memory/ subdirs.
+        // This check runs BEFORE hasDotFileComponent because the state dir
+        // itself may contain a dot component (e.g. ~/.openclaw).
+        const stateDir = api.runtime.state.resolveStateDir()
+        const stateDirPrefix = stateDir + path.sep
+        const isUnderStateDir = resolved.startsWith(stateDirPrefix) || resolved === stateDir
+        if (isUnderStateDir) {
+          const allowedPrefixes = [
+            path.join(stateDir, 'clawly') + path.sep,
+            path.join(stateDir, 'canvas') + path.sep,
+            path.join(stateDir, 'memory') + path.sep,
+          ]
+          if (!allowedPrefixes.some((p) => resolved.startsWith(p))) {
+            throw new Error(`${source}: files under the state directory are not allowed`)
+          }
+        } else if (hasDotFileComponent(resolved)) {
+          throw new Error(`${source}: dot files (e.g. .openclaw, .env) are not allowed`)
+        }
+        if (isExecutableByExt(resolved)) {
+          throw new Error(`${source}: executable files are not allowed`)
+        }
+        const type = await fileTypeFromFile(resolved)
+        if (type && isExecutableByMime(type.mime)) {
+          throw new Error(`${source}: file is an executable and cannot be sent`)
+        }
+
+        const ext = path.extname(resolved) || (type?.ext ? `.${type.ext}` : '')
+        const dest = localPath(resolved, ext, api)
+        if (!(await fileExists(dest))) {
+          const dir = path.dirname(dest)
+          await fsp.mkdir(dir, {recursive: true})
+          await fsp.copyFile(resolved, dest)
+        }
+        return dest
+      }
+
+      try {
+        const resolved = await Promise.all(sources.map(resolveSource))
+        const mediaMessage = formatMediaMessage(resolved, sources, caption)
+        const sessionKey = await resolveSessionKey('clawly', api)
+        await injectAssistantMessage({sessionKey, message: mediaMessage}, api)
+        api.logger.info(`${TOOL_NAME}: injected ${resolved.length} file(s) into session`)
+
+        return {
+          content: [
+            {type: 'text', text: JSON.stringify({sent: true, count: resolved.length, sources})},
+          ],
+        }
+      } 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

@@ -4,7 +4,7 @@ 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'
+import {registerSendFileTool} from './clawly-send-file'
 import {registerSendMessageTool} from './clawly-send-message'
 
 export function registerTools(api: PluginApi) {
@@ -15,6 +15,6 @@ export function registerTools(api: PluginApi) {
   registerDeepSearchTool(api)
   registerGrokSearchTool(api)
   registerSendAppPushTool(api)
-  registerSendImageTool(api)
+  registerSendFileTool(api)
   registerSendMessageTool(api)
 }

package/tools/clawly-send-image.ts

@@ -1,228 +0,0 @@
-/**
- * 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`)
-}