@2en/clawly-plugins 1.30.0-beta.1 → 1.30.0-beta.11

package/gateway/config-timezone.ts

@@ -2,14 +2,15 @@
  * Timezone sync RPC: writes agents.defaults.userTimezone to openclaw.json
  * without triggering a gateway restart.
  *
+ * Uses the runtime config APIs (loadConfig + writeConfigFile) for atomic
+ * writes, env var preservation, and config validation.
+ *
  * Methods:
  * - clawly.config.setTimezone({ timezone }) → { changed, timezone }
  */
 
-import path from 'node:path'
-
 import type {PluginApi} from '../types'
-import {readOpenclawConfig, writeOpenclawConfig} from '../model-gateway-setup'
+import type {OpenClawConfig} from '../types/openclaw'
 
 export function registerConfigTimezone(api: PluginApi) {
   api.registerGatewayMethod('clawly.config.setTimezone', async ({params, respond}) => {
@@ -19,30 +20,34 @@ export function registerConfigTimezone(api: PluginApi) {
       return
     }
 
-    const stateDir = api.runtime.state.resolveStateDir()
-    if (!stateDir) {
-      respond(true, {changed: false, timezone, error: 'Cannot resolve state dir'})
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      respond(true, {changed: false, timezone, error: `Load failed: ${msg}`})
       return
     }
 
-    const configPath = path.join(stateDir, 'openclaw.json')
-    const config = readOpenclawConfig(configPath)
-
-    const agents = (config.agents ?? {}) as Record<string, unknown>
-    const defaults = (agents.defaults ?? {}) as Record<string, unknown>
-    const current = defaults.userTimezone
+    const currentDefaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+      | Record<string, unknown>
+      | undefined
 
-    if (current === timezone) {
+    if (currentDefaults?.userTimezone === timezone) {
       respond(true, {changed: false, timezone})
       return
     }
 
+    // Shallow-copy nested objects to avoid polluting the loadConfig() cache
+    // if writeConfigFile fails below.
+    const agents = {...((config.agents ?? {}) as Record<string, unknown>)}
+    const defaults = {...((agents.defaults ?? {}) as Record<string, unknown>)}
     defaults.userTimezone = timezone
     agents.defaults = defaults
     config.agents = agents
 
     try {
-      writeOpenclawConfig(configPath, config)
+      await api.runtime.config.writeConfigFile(config)
       api.logger.info(`config-timezone: set userTimezone to ${timezone}`)
       respond(true, {changed: true, timezone})
     } catch (err) {

package/gateway/cron-delivery.test.ts

@@ -263,6 +263,22 @@ describe('cron-delivery', () => {
       })
     })
 
+    test('skips HEARTBEAT OK with space (bare)', async () => {
+      const {api, logs, handlers} = createMockApi()
+      registerCronDelivery(api)
+
+      await handlers.get('agent_end')!(
+        {messages: makeMessages('HEARTBEAT OK')},
+        {sessionKey: 'agent:clawly:cron:weather-check', agentId: 'clawly'},
+      )
+
+      expect(injectCalls).toHaveLength(0)
+      expect(logs).toContainEqual({
+        level: 'info',
+        msg: expect.stringContaining('skipped (filtered: heartbeat ack)'),
+      })
+    })
+
     test('skips empty text', async () => {
       const {api, logs, handlers} = createMockApi()
       registerCronDelivery(api)

package/gateway/index.ts

@@ -3,8 +3,8 @@ import {registerAgentSend} from './agent'
 import {registerCalendarNative} from './calendar-native'
 import {registerAnalytics} from './analytics'
 import {registerAudit} from './audit'
-import {registerNodeDangerousAllowlist} from './node-dangerous-allowlist'
 import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerConfigModel} from './config-model'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
 import {registerCronDelivery} from './cron-delivery'
@@ -58,12 +58,12 @@ export function registerGateway(api: PluginApi) {
   registerCronTelemetry(api)
   registerMessageLog(api)
   registerAnalytics(api)
+  registerConfigModel(api)
   registerConfigRepair(api)
   registerConfigTimezone(api)
   registerSessionSanitize(api)
   registerPairing(api)
   registerVersion(api)
   registerAudit(api)
-  registerNodeDangerousAllowlist(api)
   registerCalendarNative(api)
 }

package/gateway/offline-push.test.ts

@@ -73,6 +73,11 @@ function createMockApi(): {
   return {api, logs, handlers}
 }
 
+/** Event with a simple assistant message — needed since the skip-on-no-text guard. */
+const eventWithReply = {
+  messages: [{role: 'assistant', content: 'Hello from the assistant'}],
+}
+
 // ── Tests ────────────────────────────────────────────────────────
 
 beforeEach(() => {
@@ -89,7 +94,7 @@ describe('offline-push', () => {
     registerOfflinePush(api)
 
     const handler = handlers.get('agent_end')!
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -117,8 +122,8 @@ describe('offline-push', () => {
 
     const handler = handlers.get('agent_end')!
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(2)
   })
@@ -129,11 +134,11 @@ describe('offline-push', () => {
 
     const handler = handlers.get('agent_end')!
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
     expect(lastPushExtras).toEqual({badge: 1})
     expect(mockBadgeCount).toBe(1)
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
     expect(lastPushExtras).toEqual({badge: 2})
     expect(mockBadgeCount).toBe(2)
   })
@@ -143,7 +148,7 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(lastPushExtras).toEqual({badge: 1})
     expect(mockBadgeCount).toBe(0) // incremented then decremented
@@ -153,7 +158,7 @@ describe('offline-push', () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:telegram:12345'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:telegram:12345'})
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -166,7 +171,9 @@ describe('offline-push', () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:cron:weather-check:run:abc123'})
+    await handlers.get('agent_end')!(eventWithReply, {
+      sessionKey: 'agent:clawly:cron:weather-check:run:abc123',
+    })
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -180,7 +187,7 @@ describe('offline-push', () => {
     registerOfflinePush(api)
 
     const handler = handlers.get('agent_end')!
-    await handler({})
+    await handler(eventWithReply)
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -192,7 +199,10 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main', agentId: 'luna'})
+    await handlers.get('agent_end')!(eventWithReply, {
+      sessionKey: 'agent:clawly:main',
+      agentId: 'luna',
+    })
 
     expect(lastPushOpts?.agentId).toBe('luna')
   })
@@ -201,8 +211,9 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
+    expect(lastPushOpts).not.toBeNull()
     expect(lastPushOpts?.title).toBeUndefined()
   })
 
@@ -223,17 +234,21 @@ describe('offline-push', () => {
     expect(lastPushOpts?.body).toBe('Hi there! How can I help you today?')
   })
 
-  test('body falls back when no messages', async () => {
-    const {api, handlers} = createMockApi()
+  test('skips push when no messages (no extractable text)', async () => {
+    const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
 
-    expect(lastPushOpts?.body).toBe('Your response is ready')
+    expect(lastPushOpts).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
+    })
   })
 
-  test('body falls back when messages has no assistant role', async () => {
-    const {api, handlers} = createMockApi()
+  test('skips push when messages has no assistant role', async () => {
+    const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!(
@@ -241,7 +256,11 @@ describe('offline-push', () => {
       {sessionKey: 'agent:clawly:main'},
     )
 
-    expect(lastPushOpts?.body).toBe('Your response is ready')
+    expect(lastPushOpts).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
+    })
   })
 
   test('body strips [[type:value]] placeholders', async () => {
@@ -427,6 +446,22 @@ describe('shouldSkipPushForMessage', () => {
     expect(shouldSkipPushForMessage('The token HEARTBEAT_OK is used for health checks.')).toBeNull()
   })
 
+  test('skips heartbeat ack with space variant (HEARTBEAT OK)', () => {
+    expect(shouldSkipPushForMessage('HEARTBEAT OK')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK.')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK\n')).toBe('heartbeat ack')
+  })
+
+  test('skips short content ending with HEARTBEAT OK (space variant)', () => {
+    expect(shouldSkipPushForMessage('All good. HEARTBEAT OK')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('Nothing to report. HEARTBEAT OK。')).toBe('heartbeat ack')
+  })
+
+  test('skips HEARTBEAT OK at start with short status note (space variant)', () => {
+    expect(shouldSkipPushForMessage('HEARTBEAT OK — all systems nominal.')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK. Nothing to report.')).toBe('heartbeat ack')
+  })
+
   test('skips system prompt leak', () => {
     expect(
       shouldSkipPushForMessage('Here is some Conversation info (untrusted metadata) text'),
@@ -565,6 +600,33 @@ describe('offline-push with filtered messages', () => {
     expect(lastPushOpts?.body?.endsWith('…')).toBe(true)
   })
 
+  test('sends push for long content and strips HEARTBEAT OK (space variant) from body', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const longContent = 'A'.repeat(301)
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {
+            role: 'assistant',
+            content: `${longContent}\n\nHEARTBEAT OK`,
+          },
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=agent:clawly:main)'),
+    })
+    // HEARTBEAT OK should be stripped from body, content truncated to 140
+    expect(lastPushOpts?.body?.length).toBe(141)
+    expect(lastPushOpts?.body?.endsWith('…')).toBe(true)
+    expect(lastPushOpts?.body).not.toContain('HEARTBEAT')
+  })
+
   test('sends push for normal message text', async () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
@@ -580,15 +642,15 @@ describe('offline-push with filtered messages', () => {
     })
   })
 
-  test('sends push when event has no messages (safe default)', async () => {
+  test('skips push when event has no messages (no extractable text)', async () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
 
     expect(logs).toContainEqual({
-      level: 'info',
-      msg: expect.stringContaining('notified (session=agent:clawly:main)'),
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
     })
   })
 })

package/gateway/offline-push.ts

@@ -160,12 +160,12 @@ export function shouldSkipPushForMessage(text: string): string | null {
   // Heartbeat acknowledgment — strip HEARTBEAT_OK from both edges (mirrors
   // OpenClaw's stripTokenAtEdges). Skip if remaining text ≤ ackMaxChars (300).
   const HEARTBEAT_ACK_MAX_CHARS = 300
-  const hasAtEnd = /HEARTBEAT_OK[\p{P}\s]*$/u.test(text)
-  const hasAtStart = /^[\p{P}\s]*HEARTBEAT_OK/u.test(text)
+  const hasAtEnd = /HEARTBEAT[_ ]OK[\p{P}\s]*$/u.test(text)
+  const hasAtStart = /^[\p{P}\s]*HEARTBEAT[_ ]OK/u.test(text)
   if (hasAtEnd || hasAtStart) {
     let stripped = text
-    if (hasAtEnd) stripped = stripped.replace(/HEARTBEAT_OK[\p{P}\s]*$/u, '')
-    if (hasAtStart) stripped = stripped.replace(/^[\p{P}\s]*HEARTBEAT_OK[\p{P}\s]*/u, '')
+    if (hasAtEnd) stripped = stripped.replace(/HEARTBEAT[_ ]OK[\p{P}\s]*$/u, '')
+    if (hasAtStart) stripped = stripped.replace(/^[\p{P}\s]*HEARTBEAT[_ ]OK[\p{P}\s]*/u, '')
     stripped = stripped.trim()
     if (stripped.length <= HEARTBEAT_ACK_MAX_CHARS) return 'heartbeat ack'
   }
@@ -226,6 +226,7 @@ export function registerOfflinePush(api: PluginApi) {
 
       // Extract full assistant text for filtering and preview.
       const fullText = getLastAssistantText(event.messages)
+      const triggerText = getTriggeringUserText(event.messages)
 
       // Skip if the message would be filtered by the mobile UI.
       if (fullText != null) {
@@ -270,6 +271,33 @@ export function registerOfflinePush(api: PluginApi) {
         return
       }
 
+      // Defensive: if we can't extract assistant text, sending a generic
+      // "Your response is ready" is never useful — the message likely wasn't
+      // persisted to the transcript either, so the user opens the app to nothing.
+      // Log the messages structure for debugging, then bail.
+      if (fullText == null || fullText === '') {
+        const msgCount = Array.isArray(event.messages) ? event.messages.length : 'n/a'
+        const lastRoles = Array.isArray(event.messages)
+          ? event.messages
+              .slice(-5)
+              .map(
+                (m: any) =>
+                  `${m?.role ?? '?'}(${typeof m?.content === 'string' ? 'str' : Array.isArray(m?.content) ? `parts:${m.content.length}` : typeof m?.content})`,
+              )
+              .join(', ')
+          : 'n/a'
+        api.logger.warn(
+          `offline-push: skipped (no extractable assistant text) msgCount=${msgCount} lastRoles=[${lastRoles}] triggerText=${triggerText ? `"${triggerText.slice(0, 80)}"` : 'null'}`,
+        )
+        if (isCron) markCronPushSkipped(sessionKey!, 'no extractable text', false)
+        captureEvent('push.skipped', {
+          reason: 'no_extractable_text',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
+        return
+      }
+
       // Only send push for the main clawly mobile session and cron sessions —
       // skip channel sessions (telegram, slack, discord, etc.) which have their own delivery.
       if (sessionKey !== undefined && sessionKey !== 'agent:clawly:main' && !isCron) {
@@ -280,12 +308,12 @@ export function registerOfflinePush(api: PluginApi) {
       const noHeartbeat =
         (() => {
           if (!fullText) return null
-          const atEnd = /HEARTBEAT_OK[\p{P}\s]*$/u.test(fullText)
-          const atStart = /^[\p{P}\s]*HEARTBEAT_OK/u.test(fullText)
+          const atEnd = /HEARTBEAT[_ ]OK[\p{P}\s]*$/u.test(fullText)
+          const atStart = /^[\p{P}\s]*HEARTBEAT[_ ]OK/u.test(fullText)
           if (!atEnd && !atStart) return fullText.trim()
           let s = fullText
-          if (atEnd) s = s.replace(/HEARTBEAT_OK[\p{P}\s]*$/u, '')
-          if (atStart) s = s.replace(/^[\p{P}\s]*HEARTBEAT_OK[\p{P}\s]*/u, '')
+          if (atEnd) s = s.replace(/HEARTBEAT[_ ]OK[\p{P}\s]*$/u, '')
+          if (atStart) s = s.replace(/^[\p{P}\s]*HEARTBEAT[_ ]OK[\p{P}\s]*/u, '')
           return s.trim()
         })() ?? null
       const cleaned = noHeartbeat ? stripPlaceholders(noHeartbeat) : null

package/gateway/presence.ts

@@ -27,14 +27,17 @@ export function isOnlineEntry(entry: PresenceEntry | undefined): boolean {
 }
 
 /**
- * Shells out to `openclaw gateway call system-presence` and checks
- * whether ANY device has a foreground presence entry.
+ * Shells out to `openclaw gateway call system-presence` and returns true
+ * if any device has a `foreground` presence entry.
+ *
+ * False-negatives (beacon lapsed) are handled client-side — the mobile
+ * app suppresses `agent_end` notifications while in the foreground.
  */
 export async function isClientOnline(): Promise<boolean> {
   try {
     const result = await $`openclaw gateway call system-presence --json`
-    const jsonStr = stripCliLogs(result.stdout)
-    const entries: PresenceEntry[] = JSON.parse(jsonStr)
+    const parsed: unknown = JSON.parse(stripCliLogs(result.stdout))
+    const entries: PresenceEntry[] = Array.isArray(parsed) ? parsed : []
     return entries.some(isOnlineEntry)
   } catch {
     return false

package/gateway-fetch.ts

@@ -11,11 +11,18 @@ export type HandlerResult = {ok: boolean; data?: unknown; error?: {code: string;
 export function getGatewayConfig(api: PluginApi): GatewayCfg {
   const cfg = api.pluginConfig && typeof api.pluginConfig === 'object' ? api.pluginConfig : {}
   const c = cfg as Record<string, unknown>
-  const baseUrl =
-    typeof c.skillGatewayBaseUrl === 'string'
-      ? (c.skillGatewayBaseUrl as string).replace(/\/$/, '')
-      : ''
-  const token = typeof c.skillGatewayToken === 'string' ? (c.skillGatewayToken as string) : ''
+
+  // URL: prefer clawlyApiBaseUrl, fall back to deprecated skillGatewayBaseUrl
+  const rawUrl =
+    (typeof c.clawlyApiBaseUrl === 'string' ? (c.clawlyApiBaseUrl as string) : '') ||
+    (typeof c.skillGatewayBaseUrl === 'string' ? (c.skillGatewayBaseUrl as string) : '')
+  const baseUrl = rawUrl.replace(/\/$/, '')
+
+  // Token: prefer modelGatewayToken, fall back to deprecated skillGatewayToken
+  const token =
+    (typeof c.modelGatewayToken === 'string' ? (c.modelGatewayToken as string) : '') ||
+    (typeof c.skillGatewayToken === 'string' ? (c.skillGatewayToken as string) : '')
+
   return {baseUrl, token}
 }
 

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)
  *
@@ -80,7 +80,7 @@ export default {
     registerAutoPair(api)
     registerAutoUpdate(api)
 
-    // Email & calendar (optional — requires skillGatewayBaseUrl + skillGatewayToken in config)
+    // Email & calendar (optional — requires API base URL + token)
     const gw = getGatewayConfig(api)
     if (gw.baseUrl && gw.token) {
       registerEmail(api, gw)

package/lib/calendar-cache.ts

@@ -23,6 +23,9 @@ export interface NativeCalendar {
   type: string
 }
 
+export type AlarmMethod = 'alarm' | 'alert' | 'email' | 'default' | 'sms'
+export type AlarmInput = {relativeOffset?: number; method?: AlarmMethod}
+
 export interface NativeCalendarEvent {
   id: string
   calendarId: string
@@ -35,6 +38,7 @@ export interface NativeCalendarEvent {
   url: string
   timeZone: string
   organizer: string
+  alarms?: AlarmInput[]
 }
 
 export interface CalendarCache {
@@ -105,7 +109,12 @@ export function initCache(): void {
 }
 
 export function getCache(): CalendarCache | null {
-  if (!cachedData) cachedData = loadCache()
+  // Always read from disk to avoid returning stale in-memory state.
+  // After gateway restart or ESM/CJS dual-loading, gateway methods and
+  // agent tools may hold separate module instances with divergent
+  // cachedData. Disk is the shared source of truth. The file is small
+  // (<10 KB) and tool calls are infrequent, so the I/O cost is negligible.
+  cachedData = loadCache()
   return cachedData
 }
 

package/openclaw.plugin.json

@@ -47,6 +47,7 @@
       "defaultNoInput": { "type": "boolean" },
       "defaultTimeoutMs": { "type": "number", "minimum": 1000 },
       "configPath": { "type": "string" },
+      "clawlyApiBaseUrl": { "type": "string" },
       "skillGatewayBaseUrl": { "type": "string" },
       "skillGatewayToken": { "type": "string" },
       "modelGatewayBaseUrl": { "type": "string" },

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.1",
+  "version": "1.30.0-beta.11",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -13,8 +13,10 @@
     "@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",
+    "json5": "^2.2.3",
+    "mime": "^4.1.0",
+    "posthog-node": "^5.28.0",
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [
@@ -47,8 +49,5 @@
     "extensions": [
       "./index.ts"
     ]
-  },
-  "devDependencies": {
-    "json5": "^2.2.3"
   }
 }