@2en/clawly-plugins 1.31.0 → 1.32.0-beta.0

package/clawly-config-defaults.json5

@@ -15,9 +15,9 @@
           {
             id: "auto",
             name: "auto",
-            input: ["text", "image"],
-            contextWindow: 262144,
-            maxTokens: 65535,
+            input: ["text"],
+            contextWindow: 204800,
+            maxTokens: 131072,
           },
           {
             id: "moonshotai/kimi-k2.5",

package/gateway/index.ts

@@ -7,6 +7,8 @@ import {registerClawhub2gateway} from './clawhub2gateway'
 import {registerConfigModel} from './config-model'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
+import {registerInfo} from './info'
+import {registerIssueAccessToken} from './issueAccessToken'
 import {registerCronDelivery} from './cron-delivery'
 import {registerCronTelemetry} from './cron-telemetry'
 import {registerMessageLog} from './message-log'
@@ -19,6 +21,7 @@ import {registerPlugins} from './plugins'
 import {initPostHog, shutdownPostHog} from './posthog'
 import {registerPresence} from './presence'
 import {registerSessionSanitize} from './session-sanitize'
+import {registerUploadHttpRoute} from '../http/file/upload'
 import {registerVersion} from './version'
 
 export function registerGateway(api: PluginApi) {
@@ -47,6 +50,7 @@ export function registerGateway(api: PluginApi) {
     })
   }
 
+  registerInfo(api)
   registerPresence(api)
   registerNotification(api)
   registerAgentSend(api)
@@ -64,6 +68,8 @@ export function registerGateway(api: PluginApi) {
   registerSessionSanitize(api)
   registerPairing(api)
   registerVersion(api)
+  registerIssueAccessToken(api)
+  registerUploadHttpRoute(api)
   registerAudit(api)
   registerCalendarNative(api)
 }

package/gateway/info.ts

@@ -0,0 +1,18 @@
+/**
+ * Plugin info — fast, synchronous metadata from package.json.
+ *
+ * Only static info that can be resolved without I/O or network calls.
+ *
+ * Method: clawly.info({}) → { version: string }
+ */
+
+import type {PluginApi} from '../types'
+
+// @ts-expect-error — JSON import
+import pkg from '../package.json'
+
+export function registerInfo(api: PluginApi) {
+  api.registerGatewayMethod('clawly.info', async ({respond}) => {
+    respond(true, {version: pkg.version})
+  })
+}

package/gateway/issueAccessToken.ts

@@ -0,0 +1,17 @@
+import {createAccessToken, resolveGatewaySecret} from '../lib/httpAuth'
+import type {PluginApi} from '../types'
+
+export function registerIssueAccessToken(api: PluginApi) {
+  api.registerGatewayMethod('clawly.issueAccessToken', async ({respond}) => {
+    const secret = resolveGatewaySecret(api)
+    if (!secret) {
+      respond(false, undefined, {
+        code: 'no_secret',
+        message: 'gateway auth token is not configured',
+      })
+      return
+    }
+    const {token, expiresAt} = createAccessToken(secret)
+    respond(true, {accessToken: token, expiresAt})
+  })
+}

package/{outbound.ts → http/file/outbound.ts}

@@ -20,8 +20,8 @@ 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'
+import type {PluginApi} from '../../types'
+import {guardHttpAuth, handleCors, sendJson} from '../../lib/httpAuth'
 
 const OUTBOUND_DIR = path.join(os.homedir(), '.openclaw', 'clawly', 'outbound')
 
@@ -116,19 +116,6 @@ export function registerOutboundMethods(api: PluginApi) {
     )
     respond(true, {base64: buffer.toString('base64')})
   })
-
-  api.registerGatewayMethod('clawly.issueAccessToken', async ({respond}) => {
-    const secret = resolveGatewaySecret(api)
-    if (!secret) {
-      respond(false, undefined, {
-        code: 'no_secret',
-        message: 'gateway auth token is not configured',
-      })
-      return
-    }
-    const {token, expiresAt} = createAccessToken(secret)
-    respond(true, {accessToken: token, expiresAt})
-  })
 }
 
 // ── HTTP route: GET /clawly/file/outbound?path=<original-path> ─────────────
@@ -180,17 +167,7 @@ export function registerOutboundHttpRoute(api: PluginApi) {
     path: '/clawly/file/outbound',
     auth: 'plugin',
     handler: async (_req: IncomingMessage, res: ServerResponse) => {
-      res.setHeader('Access-Control-Allow-Origin', '*')
-
-      // Handle CORS preflight
-      if (_req.method === 'OPTIONS') {
-        res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS')
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
-        res.setHeader('Access-Control-Max-Age', '86400')
-        res.statusCode = 204
-        res.end()
-        return
-      }
+      if (handleCors(_req, res, 'GET, HEAD, OPTIONS')) return
 
       const url = new URL(_req.url ?? '/', 'http://localhost')
       if (!guardHttpAuth(api, _req, res, url)) return

package/http/file/upload.ts

@@ -0,0 +1,98 @@
+import crypto from 'node:crypto'
+import fsp from 'node:fs/promises'
+import type {IncomingMessage, ServerResponse} from 'node:http'
+import path from 'node:path'
+
+import mime from 'mime'
+import {guardHttpAuth, handleCors, sendJson} from '../../lib/httpAuth'
+import type {PluginApi} from '../../types'
+
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024 // 20 MB
+const ALLOWED_CONTENT_TYPE_PREFIXES = ['image/', 'audio/']
+
+function uploadsDir(api: PluginApi): string {
+  return path.join(api.runtime.state.resolveStateDir(), 'media', 'clawly')
+}
+
+function collectBody(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    let done = false
+    req.on('data', (chunk: Buffer) => {
+      if (done) return
+      size += chunk.length
+      if (size > maxBytes) {
+        done = true
+        req.destroy()
+        reject(new Error(`body too large (exceeded ${maxBytes} bytes)`))
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (!done) resolve(Buffer.concat(chunks))
+    })
+    req.on('error', reject)
+  })
+}
+
+export function registerUploadHttpRoute(api: PluginApi) {
+  api.registerHttpRoute({
+    path: '/clawly/file/upload',
+    auth: 'plugin',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      if (handleCors(req, res, 'POST, OPTIONS')) return
+
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      if (!guardHttpAuth(api, req, res, url)) return
+
+      if (req.method !== 'POST') {
+        sendJson(res, 405, {error: 'method not allowed'})
+        return
+      }
+
+      const contentType = req.headers['content-type']?.split(';')[0]?.trim()
+      if (!contentType || !ALLOWED_CONTENT_TYPE_PREFIXES.some((p) => contentType.startsWith(p))) {
+        sendJson(res, 415, {
+          error: `only ${ALLOWED_CONTENT_TYPE_PREFIXES.map((p) => p + '*').join(', ')} content types are accepted`,
+        })
+        return
+      }
+
+      const filename = url.searchParams.get('filename')?.trim() ?? ''
+      const extFromFilename = filename ? path.extname(filename).toLowerCase() : ''
+      const extFromMime = mime.getExtension(contentType)
+      const ext = extFromFilename || (extFromMime ? `.${extFromMime}` : '')
+      if (!ext) {
+        sendJson(res, 400, {error: 'cannot determine file extension from filename or Content-Type'})
+        return
+      }
+
+      let buffer: Buffer
+      try {
+        buffer = await collectBody(req, MAX_UPLOAD_BYTES)
+      } catch (err) {
+        sendJson(res, 413, {error: err instanceof Error ? err.message : 'body too large'})
+        return
+      }
+
+      if (buffer.length === 0) {
+        sendJson(res, 400, {error: 'empty body'})
+        return
+      }
+
+      const dir = uploadsDir(api)
+      await fsp.mkdir(dir, {recursive: true})
+
+      const hash = crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 16)
+      const destFilename = `${hash}${ext}`
+      const destPath = path.join(dir, destFilename)
+
+      await fsp.writeFile(destPath, buffer)
+      api.logger.info(`upload: saved ${destPath} (${buffer.length} bytes)`)
+
+      sendJson(res, 200, {path: destPath})
+    },
+  })
+}

package/index.ts

@@ -50,7 +50,11 @@ import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
-import {registerOutboundHook, registerOutboundHttpRoute, registerOutboundMethods} from './outbound'
+import {
+  registerOutboundHook,
+  registerOutboundHttpRoute,
+  registerOutboundMethods,
+} from './http/file/outbound'
 import {registerSkillCommandRestore} from './skill-command-restore'
 import {registerTools} from './tools'
 import type {PluginApi} from './types'

package/lib/httpAuth.ts

@@ -94,6 +94,27 @@ export function authenticateHttpRequest(req: IncomingMessage, url: URL, secret:
   return false
 }
 
+/**
+ * Set CORS headers and handle OPTIONS preflight.
+ * Returns true if the request was a preflight (response already sent).
+ */
+export function handleCors(
+  req: IncomingMessage,
+  res: ServerResponse,
+  methods: string = 'GET, HEAD, OPTIONS',
+): boolean {
+  res.setHeader('Access-Control-Allow-Origin', '*')
+  if (req.method === 'OPTIONS') {
+    res.setHeader('Access-Control-Allow-Methods', methods)
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+    res.setHeader('Access-Control-Max-Age', '86400')
+    res.statusCode = 204
+    res.end()
+    return true
+  }
+  return false
+}
+
 export function sendJson(res: ServerResponse, status: number, body: Record<string, unknown>) {
   res.writeHead(status, {'Content-Type': 'application/json'})
   res.end(JSON.stringify(body))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.31.0",
+  "version": "1.32.0-beta.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -33,7 +33,7 @@
     "cron-hook.ts",
     "email.ts",
     "gateway-fetch.ts",
-    "outbound.ts",
+    "http",
     "model-gateway-setup.ts",
     "resolve-gateway-credentials.ts",
     "skill-command-restore.ts",

package/tools/clawly-search.test.ts

@@ -192,6 +192,105 @@ describe('clawly_search', () => {
     expect(call.body?.search_mode).toBeUndefined()
   })
 
+  test('extracts citations from message annotations (OpenRouter format)', async () => {
+    mockResponse.body = {
+      choices: [
+        {
+          message: {
+            content: 'Answer with annotation citations',
+            annotations: [
+              {type: 'url_citation', url_citation: {url: 'https://example.com/a'}},
+              {type: 'url_citation', url_citation: {url: 'https://example.com/b'}},
+            ],
+          },
+        },
+      ],
+    }
+    const {execute} = createMockApi(registerSearchTool)
+    const res = parseResult(await execute('tc-1', {query: 'test'}))
+
+    expect(res.answer).toBe('Answer with annotation citations')
+    expect(res.citations).toEqual(['https://example.com/a', 'https://example.com/b'])
+  })
+
+  test('prefers top-level citations over annotations', async () => {
+    mockResponse.body = {
+      choices: [
+        {
+          message: {
+            content: 'Answer',
+            annotations: [
+              {type: 'url_citation', url_citation: {url: 'https://example.com/annotation'}},
+            ],
+          },
+        },
+      ],
+      citations: ['https://example.com/top-level'],
+    }
+    const {execute} = createMockApi(registerSearchTool)
+    const res = parseResult(await execute('tc-1', {query: 'test'}))
+
+    expect(res.citations).toEqual(['https://example.com/top-level'])
+  })
+
+  test('deduplicates annotation citations', async () => {
+    mockResponse.body = {
+      choices: [
+        {
+          message: {
+            content: 'Answer',
+            annotations: [
+              {type: 'url_citation', url_citation: {url: 'https://example.com/same'}},
+              {type: 'url_citation', url_citation: {url: 'https://example.com/same'}},
+              {type: 'url_citation', url_citation: {url: 'https://example.com/other'}},
+            ],
+          },
+        },
+      ],
+    }
+    const {execute} = createMockApi(registerSearchTool)
+    const res = parseResult(await execute('tc-1', {query: 'test'}))
+
+    expect(res.citations).toEqual(['https://example.com/same', 'https://example.com/other'])
+  })
+
+  test('extracts citations from annotation.url fallback', async () => {
+    mockResponse.body = {
+      choices: [
+        {
+          message: {
+            content: 'Answer',
+            annotations: [{type: 'url_citation', url: 'https://example.com/fallback-url'}],
+          },
+        },
+      ],
+    }
+    const {execute} = createMockApi(registerSearchTool)
+    const res = parseResult(await execute('tc-1', {query: 'test'}))
+
+    expect(res.citations).toEqual(['https://example.com/fallback-url'])
+  })
+
+  test('falls back to annotations when top-level citations is empty array', async () => {
+    mockResponse.body = {
+      choices: [
+        {
+          message: {
+            content: 'Answer',
+            annotations: [
+              {type: 'url_citation', url_citation: {url: 'https://example.com/fallback'}},
+            ],
+          },
+        },
+      ],
+      citations: [],
+    }
+    const {execute} = createMockApi(registerSearchTool)
+    const res = parseResult(await execute('tc-1', {query: 'test'}))
+
+    expect(res.citations).toEqual(['https://example.com/fallback'])
+  })
+
   test('returns error on API failure', async () => {
     mockResponse = {ok: false, status: 503, body: {error: 'service unavailable'}}
     const {execute} = createMockApi(registerSearchTool)

package/tools/clawly-search.ts

@@ -7,6 +7,7 @@ import {
   createSearchToolRegistrar,
   parseGrokResponse,
   parseKimiResponse,
+  parsePerplexityResponse,
 } from './create-search-tool'
 
 export const registerSearchTool = createSearchToolRegistrar({
@@ -17,6 +18,7 @@ export const registerSearchTool = createSearchToolRegistrar({
   buildUrl: buildPerplexityUrl,
   timeoutMs: 30_000,
   provider: 'perplexity',
+  parseResponse: parsePerplexityResponse,
 })
 
 export const registerDeepSearchTool = createSearchToolRegistrar({
@@ -27,6 +29,7 @@ export const registerDeepSearchTool = createSearchToolRegistrar({
   buildUrl: buildPerplexityUrl,
   timeoutMs: 120_000,
   provider: 'perplexity',
+  parseResponse: parsePerplexityResponse,
 })
 
 // model is 'grok-4-fast' (not 'x-ai/grok-4-fast') because this goes through

package/tools/create-search-tool.ts

@@ -17,9 +17,8 @@ export interface SearchToolConfig {
   buildUrl: (baseUrl: string) => string
   timeoutMs: number
   provider: SearchProvider
-  extraBody?: Record<string, unknown>
   buildBody?: (model: string, query: string) => Record<string, unknown>
-  parseResponse?: (data: unknown) => {answer: string; citations: string[]}
+  parseResponse: (data: unknown) => {answer: string; citations: string[]}
 }
 
 function createParameters(): Record<string, unknown> {
@@ -70,6 +69,47 @@ function extractCitations(text: string): string[] {
   return urls
 }
 
+export function parsePerplexityResponse(data: unknown): {answer: string; citations: string[]} {
+  const d = data as {
+    choices?: {
+      message?: {
+        content?: string
+        annotations?: Array<{type?: string; url?: string; url_citation?: {url?: string}}>
+      }
+    }[]
+    citations?: string[]
+  }
+  const answer = d.choices?.[0]?.message?.content ?? ''
+
+  const seen = new Set<string>()
+  const topLevel = (d.citations ?? []).reduce<string[]>((acc, raw) => {
+    if (typeof raw !== 'string') return acc
+    const url = raw.trim()
+    if (url && !seen.has(url)) {
+      seen.add(url)
+      acc.push(url)
+    }
+    return acc
+  }, [])
+  if (topLevel.length > 0) {
+    return {answer, citations: topLevel}
+  }
+
+  // Fallback: extract from message annotations (OpenRouter format)
+  const citations: string[] = []
+  for (const annotation of d.choices?.[0]?.message?.annotations ?? []) {
+    if (annotation.type !== 'url_citation') continue
+    const raw = annotation.url_citation?.url ?? annotation.url
+    if (typeof raw !== 'string') continue
+    const url = raw.trim()
+    if (url && !seen.has(url)) {
+      seen.add(url)
+      citations.push(url)
+    }
+  }
+  return {answer, citations}
+}
+
 export function parseKimiResponse(data: unknown): {answer: string; citations: string[]} {
   const d = data as {choices?: {message?: {content?: string}}[]}
   const answerText = d.choices?.[0]?.message?.content ?? ''
@@ -120,12 +160,7 @@ export function createSearchToolRegistrar(config: SearchToolConfig) {
             body: JSON.stringify(
               config.buildBody
                 ? config.buildBody(config.model, query)
-                : {
-                    model: config.model,
-                    stream: false,
-                    messages: [{role: 'user', content: query}],
-                    ...config.extraBody,
-                  },
+                : {model: config.model, stream: false, messages: [{role: 'user', content: query}]},
             ),
             signal: controller.signal,
           })
@@ -143,18 +178,7 @@ export function createSearchToolRegistrar(config: SearchToolConfig) {
 
           const data = await res.json()
 
-          const parsed = config.parseResponse
-            ? config.parseResponse(data)
-            : (() => {
-                const d = data as {
-                  choices?: {message?: {content?: string}}[]
-                  citations?: string[]
-                }
-                return {
-                  answer: d.choices?.[0]?.message?.content ?? '',
-                  citations: d.citations ?? [],
-                }
-              })()
+          const parsed = config.parseResponse(data)
 
           const result: SearchResult = {
             query,