@2en/clawly-plugins 1.12.0 → 1.14.0

package/gateway/agent.ts

@@ -3,53 +3,111 @@
  * external callers (cron, other agents) and optionally push-notify
  * when the mobile client is offline.
  *
+ * Uses `openclaw gateway call agent` (gateway RPC) instead of
+ * `openclaw agent --message` for richer parameter support
+ * (extraSystemPrompt, sessionKey, lane, spawnedBy, etc.).
+ *
  * Methods:
- * - clawly.agent.send  — run `openclaw agent --message <msg>`
- * - clawly.agent.echo  — same, but wraps message as `/clawly.echo <msg>`
+ * - clawly.agent.send  — trigger agent turn via gateway RPC
+ * - clawly.agent.echo  — echo-wrapped agent message (bypasses LLM)
  */
 
 import {$} from 'zx'
 import type {PluginApi} from '../index'
+import {stripCliLogs} from '../lib/stripCliLogs'
 import {sendPushNotification} from './notification'
 import {isClientOnline} from './presence'
 
 // Suppress zx default stdout logging
 $.verbose = false
 
-interface AgentSendParams {
+// ── Shared agent gateway call ────────────────────────────────────
+
+export interface AgentCallParams {
   message: string
-  agent?: string
-  notificationMessage?: string
+  agentId?: string
+  sessionKey?: string
+  extraSystemPrompt?: string
+  label?: string
+  spawnedBy?: string
+  lane?: string
 }
 
-interface AgentSendResult {
+export interface AgentCallResult {
   ok: boolean
-  online: boolean
-  pushSent: boolean
+  runId?: string
+  error?: string
 }
 
-async function runAgentMessage(
-  message: string,
-  agent: string,
+/**
+ * Trigger an agent turn via `openclaw gateway call agent`.
+ * Exported so other modules (e.g. clawly_send_message tool) can reuse.
+ */
+export async function callAgentGateway(
+  params: AgentCallParams,
   api: PluginApi,
-): Promise<{ok: boolean; error?: string}> {
+): Promise<AgentCallResult> {
+  const rpcParams = JSON.stringify({
+    message: params.message,
+    ...(params.agentId ? {agentId: params.agentId} : {}),
+    ...(params.sessionKey ? {sessionKey: params.sessionKey} : {}),
+    ...(params.extraSystemPrompt ? {extraSystemPrompt: params.extraSystemPrompt} : {}),
+    ...(params.label ? {label: params.label} : {}),
+    ...(params.spawnedBy ? {spawnedBy: params.spawnedBy} : {}),
+    ...(params.lane ? {lane: params.lane} : {}),
+    idempotencyKey: crypto.randomUUID(),
+  })
+
   try {
-    await $`openclaw agent --agent ${agent} --message ${message}`
-    return {ok: true}
+    const result = await $`openclaw gateway call agent --json --params ${rpcParams}`
+    const jsonStr = stripCliLogs(result.stdout)
+    const parsed = JSON.parse(jsonStr)
+    return {ok: true, runId: parsed.runId}
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    api.logger.error(`agent-send: openclaw agent failed — ${msg}`)
+    api.logger.error(`agent-send: gateway call agent failed — ${msg}`)
     return {ok: false, error: msg}
   }
 }
 
+// ── clawly.agent.send / clawly.agent.echo ────────────────────────
+
+interface AgentSendParams {
+  message: string
+  agent?: string
+  sessionKey?: string
+  extraSystemPrompt?: string
+  label?: string
+  spawnedBy?: string
+  lane?: string
+  notificationMessage?: string
+}
+
+interface AgentSendResult {
+  ok: boolean
+  runId?: string
+  online: boolean
+  pushSent: boolean
+}
+
 async function handleAgentSend(
   rawMessage: string,
   params: AgentSendParams,
   api: PluginApi,
 ): Promise<AgentSendResult> {
-  const agent = params.agent || 'clawly'
-  const {ok} = await runAgentMessage(rawMessage, agent, api)
+  const {ok, runId} = await callAgentGateway(
+    {
+      message: rawMessage,
+      agentId: params.agent || 'clawly',
+      sessionKey: params.sessionKey,
+      extraSystemPrompt: params.extraSystemPrompt,
+      label: params.label,
+      spawnedBy: params.spawnedBy,
+      lane: params.lane,
+    },
+    api,
+  )
+
   const online = await isClientOnline()
 
   let pushSent = false
@@ -57,11 +115,15 @@ async function handleAgentSend(
     pushSent = await sendPushNotification({body: params.notificationMessage}, api)
   }
 
-  return {ok, online, pushSent}
+  return {ok, ...(runId ? {runId} : {}), online, pushSent}
+}
+
+function parseString(val: unknown): string | undefined {
+  return typeof val === 'string' ? val.trim() || undefined : undefined
 }
 
 export function registerAgentSend(api: PluginApi) {
-  // clawly.agent.send — send a raw message to the agent
+  // clawly.agent.send — trigger an agent turn via gateway RPC
   api.registerGatewayMethod('clawly.agent.send', async ({params, respond}) => {
     const message = typeof params.message === 'string' ? params.message.trim() : ''
     if (!message) {
@@ -69,11 +131,22 @@ export function registerAgentSend(api: PluginApi) {
       return
     }
 
-    const agent = typeof params.agent === 'string' ? params.agent.trim() : undefined
-    const notificationMessage =
-      typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined
-
-    const result = await handleAgentSend(message, {message, agent, notificationMessage}, api)
+    const result = await handleAgentSend(
+      message,
+      {
+        message,
+        agent: parseString(params.agent),
+        sessionKey: parseString(params.sessionKey),
+        extraSystemPrompt:
+          typeof params.extraSystemPrompt === 'string' ? params.extraSystemPrompt : undefined,
+        label: parseString(params.label),
+        spawnedBy: parseString(params.spawnedBy),
+        lane: parseString(params.lane),
+        notificationMessage:
+          typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined,
+      },
+      api,
+    )
     respond(result.ok, result)
   })
 
@@ -85,12 +158,17 @@ export function registerAgentSend(api: PluginApi) {
       return
     }
 
-    const agent = typeof params.agent === 'string' ? params.agent.trim() : undefined
-    const notificationMessage =
-      typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined
-
     const echoMessage = `/clawly_echo ${message}`
-    const result = await handleAgentSend(echoMessage, {message, agent, notificationMessage}, api)
+    const result = await handleAgentSend(
+      echoMessage,
+      {
+        message: echoMessage,
+        agent: parseString(params.agent),
+        notificationMessage:
+          typeof params.notificationMessage === 'string' ? params.notificationMessage : undefined,
+      },
+      api,
+    )
     respond(result.ok, result)
   })
 

package/gateway/index.ts

@@ -1,6 +1,7 @@
 import type {PluginApi} from '../index'
 import {registerAgentSend} from './agent'
 import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerInject} from './inject'
 import {registerMemoryBrowser} from './memory'
 import {registerNotification} from './notification'
 import {registerPlugins} from './plugins'
@@ -10,6 +11,7 @@ export function registerGateway(api: PluginApi) {
   registerPresence(api)
   registerNotification(api)
   registerAgentSend(api)
+  registerInject(api)
   registerMemoryBrowser(api)
   registerClawhub2gateway(api)
   registerPlugins(api)

package/gateway/inject.ts

@@ -0,0 +1,99 @@
+/**
+ * Assistant-role message injection — inject messages into the chat transcript
+ * as role: "assistant" without triggering an agent run.
+ *
+ * Method:
+ * - clawly.inject({ sessionKey, message, label? }) → { ok, messageId }
+ *
+ * Wraps the core `chat.inject` OpenClaw gateway method.
+ */
+
+import {$} from 'zx'
+import type {PluginApi} from '../index'
+import {stripCliLogs} from '../lib/stripCliLogs'
+
+$.verbose = false
+
+interface InjectParams {
+  sessionKey: string
+  message: string
+  label?: string
+}
+
+interface InjectResult {
+  ok: boolean
+  messageId: string
+}
+
+/**
+ * Inject a message into the chat transcript as role: "assistant".
+ * Calls the core `chat.inject` gateway method via CLI.
+ */
+export async function injectAssistantMessage(
+  params: InjectParams,
+  api: PluginApi,
+): Promise<InjectResult> {
+  const rpcParams = JSON.stringify({
+    sessionKey: params.sessionKey,
+    message: params.message,
+    ...(params.label ? {label: params.label} : {}),
+  })
+
+  try {
+    const result = await $`openclaw gateway call chat.inject --json --params ${rpcParams}`
+    const jsonStr = stripCliLogs(result.stdout)
+    const parsed = JSON.parse(jsonStr)
+    return {ok: parsed.ok ?? true, messageId: parsed.messageId ?? ''}
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    api.logger.error(`inject: chat.inject failed — ${msg}`)
+    throw new Error(`chat.inject failed: ${msg}`)
+  }
+}
+
+/**
+ * Resolve the session key for an agent via `sessions.resolve`.
+ */
+export async function resolveSessionKey(agentId: string, api: PluginApi): Promise<string> {
+  try {
+    const rpcParams = JSON.stringify({agentId})
+    const result = await $`openclaw gateway call sessions.resolve --json --params ${rpcParams}`
+    const jsonStr = stripCliLogs(result.stdout)
+    const parsed = JSON.parse(jsonStr)
+    if (parsed.key) return parsed.key
+    throw new Error(`sessions.resolve returned no key for agentId=${agentId}`)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    api.logger.error(`inject: sessions.resolve failed — ${msg}`)
+    throw new Error(`sessions.resolve failed: ${msg}`)
+  }
+}
+
+export function registerInject(api: PluginApi) {
+  api.registerGatewayMethod('clawly.inject', async ({params, respond}) => {
+    const sessionKey = typeof params.sessionKey === 'string' ? params.sessionKey.trim() : ''
+    const message = typeof params.message === 'string' ? params.message.trim() : ''
+    const label = typeof params.label === 'string' ? params.label.trim() : undefined
+
+    if (!sessionKey) {
+      respond(false, undefined, {code: 'invalid_params', message: 'sessionKey is required'})
+      return
+    }
+    if (!message) {
+      respond(false, undefined, {code: 'invalid_params', message: 'message is required'})
+      return
+    }
+
+    try {
+      const result = await injectAssistantMessage({sessionKey, message, label}, api)
+      respond(true, result)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'inject_failed',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.logger.info('inject: registered clawly.inject method')
+}

package/index.ts

@@ -6,8 +6,9 @@
  * - clawly.isOnline          — check if a mobile client is connected
  * - clawly.notification.setToken — register Expo push token for offline notifications
  * - clawly.notification.send    — send a push notification directly
- * - clawly.agent.send        — send a message to the agent (+ optional push)
+ * - clawly.agent.send        — trigger agent turn with a message (+ optional push)
  * - clawly.agent.echo        — echo-wrapped agent message (bypasses LLM)
+ * - clawly.inject             — inject assistant-role message into transcript (wraps chat.inject)
  * - memory-browser.list      — list all .md files in the memory directory
  * - memory-browser.get       — return content of a single .md file
  * - clawhub2gateway.*        — ClawHub CLI RPC bridge (search/install/update/list/explore/inspect/star/unstar)
@@ -15,7 +16,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_message      — send a message to user via main session agent
+ * - clawly_send_message      — send a message to user via main session agent (supports role: user|assistant)
  *
  * Commands:
  * - /clawly_echo          — echo text back without LLM
@@ -32,7 +33,7 @@ import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
-import {registerOutboundHook, registerOutboundMethods} from './outbound'
+import {registerOutboundHook, registerOutboundHttpRoute, registerOutboundMethods} from './outbound'
 import {registerTools} from './tools'
 
 type PluginRuntime = {
@@ -91,6 +92,13 @@ export type PluginApi = {
     opts?: {optional?: boolean},
   ) => void
   registerChannel: (registration: {plugin: any}) => void
+  registerHttpRoute: (params: {
+    path: string
+    handler: (
+      req: import('node:http').IncomingMessage,
+      res: import('node:http').ServerResponse,
+    ) => Promise<void> | void
+  }) => void
 }
 
 export default {
@@ -100,6 +108,7 @@ export default {
   register(api: PluginApi) {
     registerOutboundHook(api)
     registerOutboundMethods(api)
+    registerOutboundHttpRoute(api)
     registerCommands(api)
     registerTools(api)
     registerClawlyCronChannel(api)

package/outbound.ts

@@ -8,6 +8,8 @@
 
 import crypto from 'node:crypto'
 import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import type {IncomingMessage, ServerResponse} from 'node:http'
 import os from 'node:os'
 import path from 'node:path'
 
@@ -29,6 +31,15 @@ function ensureOutboundDir(): void {
   fs.mkdirSync(OUTBOUND_DIR, {recursive: true})
 }
 
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fsp.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
 // ── Hook: tool_result_persist ───────────────────────────────────────
 
 export function registerOutboundHook(api: PluginApi) {
@@ -73,16 +84,94 @@ export function registerOutboundMethods(api: PluginApi) {
 
     const dest = outboundFilePath(rawPath)
 
-    if (!fs.existsSync(dest)) {
+    if (!(await fileExists(dest))) {
       api.logger.warn(`outbound: file not found: ${rawPath} ${dest}`)
       respond(false, undefined, {code: 'not_found', message: 'outbound file not found'})
       return
     }
 
-    const buffer = fs.readFileSync(dest)
+    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})
   })
 }
+
+// ── 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',
+}
+
+function sendJson(res: ServerResponse, status: number, body: Record<string, unknown>) {
+  res.writeHead(status, {'Content-Type': 'application/json'})
+  res.end(JSON.stringify(body))
+}
+
+export function registerOutboundHttpRoute(api: PluginApi) {
+  api.registerHttpRoute({
+    path: '/clawly/file/outbound',
+    handler: async (_req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(_req.url ?? '/', 'http://localhost')
+      const rawPath = url.searchParams.get('path')?.trim() ?? ''
+
+      if (!rawPath) {
+        sendJson(res, 400, {error: 'path query parameter is required'})
+        return
+      }
+
+      const dest = outboundFilePath(rawPath)
+
+      if (!(await fileExists(dest))) {
+        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 contentType = MIME[ext] ?? 'application/octet-stream'
+      const stat = await fsp.stat(dest)
+      const total = stat.size
+      const rangeHeader = _req.headers.range
+
+      if (rangeHeader) {
+        const match = /bytes=(\d+)-(\d*)/.exec(rangeHeader)
+        if (match) {
+          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})
+
+          res.writeHead(206, {
+            'Content-Type': contentType,
+            'Content-Range': `bytes ${start}-${end}/${total}`,
+            'Accept-Ranges': 'bytes',
+            'Content-Length': chunkSize,
+          })
+          stream.pipe(res)
+          api.logger.info(
+            `outbound http: served ${rawPath} -> ${dest} range ${start}-${end}/${total}`,
+          )
+          return
+        }
+      }
+
+      const buffer = await fsp.readFile(dest)
+      res.writeHead(200, {
+        'Content-Type': contentType,
+        'Content-Length': total,
+        'Accept-Ranges': 'bytes',
+      })
+      res.end(buffer)
+
+      api.logger.info(`outbound http: served ${rawPath} -> ${dest} (${total} bytes)`)
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "module": "index.ts",
   "type": "module",
   "repository": {

package/tools/clawly-send-message.ts

@@ -2,14 +2,14 @@
  * Agent tool: clawly_send_message — send a message to the main session
  * agent from an isolated context (e.g. cron job).
  *
- * Runs `openclaw agent --agent <agent> --message <message>` which delivers
- * the text as a natural assistant response in the user's chat.
+ * - role: "user" (default) — triggers agent turn via gateway RPC
+ * - role: "assistant" — injects into transcript via chat.inject (no agent trigger,
+ *   since the calling agent has already decided to send)
  */
 
-import {$} from 'zx'
 import type {PluginApi} from '../index'
-
-$.verbose = false
+import {callAgentGateway} from '../gateway/agent'
+import {injectAssistantMessage, resolveSessionKey} from '../gateway/inject'
 
 const TOOL_NAME = 'clawly_send_message'
 
@@ -19,6 +19,16 @@ const parameters: Record<string, unknown> = {
   properties: {
     message: {type: 'string', description: 'The message to send to the user'},
     agent: {type: 'string', description: 'Target agent ID (default: "clawly")'},
+    role: {
+      type: 'string',
+      enum: ['user', 'assistant'],
+      description:
+        'Message role. "user" (default) sends as user and triggers agent run. "assistant" injects into transcript as assistant without triggering a run.',
+    },
+    sessionKey: {
+      type: 'string',
+      description: 'Session key for assistant injection. Auto-resolved from agent if omitted.',
+    },
   },
 }
 
@@ -26,7 +36,7 @@ export function registerSendMessageTool(api: PluginApi) {
   api.registerTool({
     name: TOOL_NAME,
     description:
-      'Send a message to the user via the main session agent. Use this from cron jobs or isolated sessions to deliver results to the user.',
+      'Send a message to the user via the main session agent. Use this from cron jobs or isolated sessions to deliver results to the user. Set role to "assistant" to inject the message directly into the transcript without triggering an agent run.',
     parameters,
     async execute(_toolCallId, params) {
       const message = typeof params.message === 'string' ? params.message.trim() : ''
@@ -35,13 +45,34 @@ export function registerSendMessageTool(api: PluginApi) {
       }
 
       const agent = typeof params.agent === 'string' ? params.agent.trim() : 'clawly'
+      const role = params.role === 'assistant' ? 'assistant' : 'user'
 
       try {
-        await $`openclaw agent --agent ${agent} --message ${message}`
+        if (role === 'assistant') {
+          const sessionKey =
+            typeof params.sessionKey === 'string' && params.sessionKey.trim()
+              ? params.sessionKey.trim()
+              : await resolveSessionKey(agent, api)
+          const result = await injectAssistantMessage({sessionKey, message}, api)
+          api.logger.info(
+            `${TOOL_NAME}: injected assistant message (${message.length} chars) into session ${sessionKey}`,
+          )
+          return {
+            content: [
+              {type: 'text', text: JSON.stringify({sent: true, messageId: result.messageId})},
+            ],
+          }
+        }
+
+        const {ok, runId, error} = await callAgentGateway({message, agentId: agent}, api)
+        if (!ok) {
+          api.logger.error(`${TOOL_NAME}: failed — ${error}`)
+          return {content: [{type: 'text', text: JSON.stringify({sent: false, error})}]}
+        }
         api.logger.info(
-          `${TOOL_NAME}: delivered message (${message.length} chars) to agent ${agent}`,
+          `${TOOL_NAME}: delivered message (${message.length} chars) to agent ${agent} (runId: ${runId})`,
         )
-        return {content: [{type: 'text', text: JSON.stringify({sent: true})}]}
+        return {content: [{type: 'text', text: JSON.stringify({sent: true, runId})}]}
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
         api.logger.error(`${TOOL_NAME}: failed — ${msg}`)