@2en/clawly-plugins 1.11.0 → 1.13.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/gateway/memory.ts

@@ -1,9 +1,11 @@
 /**
- * Memory directory browser — expose memory directory .md files as Gateway RPC methods.
+ * Memory & workspace browser — expose workspace .md files as Gateway RPC methods.
  *
  * Gateway methods:
- * - memory-browser.list — list all .md files in the OpenClaw memory directory
- * - memory-browser.get — return the content of a single .md file by path
+ * - memory-browser.list — list .md files in memory directory (may be shadowed by built-in)
+ * - memory-browser.get — read a .md file from memory directory (may be shadowed by built-in)
+ * - clawly.workspace.list — list root-level .md files in workspace directory
+ * - clawly.workspace.get — read a .md file from workspace root
  */
 
 import fs from 'node:fs/promises'
@@ -108,30 +110,84 @@ async function listRootMdFiles(dir: string): Promise<string[]> {
     .sort()
 }
 
+/** Validate path and read a .md file, responding via the RPC respond callback. */
+async function readMdFile(
+  dir: string,
+  relativePath: string | undefined,
+  api: PluginApi,
+  respond: (ok: boolean, payload?: unknown, error?: {code: string; message: string}) => void,
+) {
+  if (!relativePath) {
+    respond(false, undefined, {
+      code: 'invalid_params',
+      message: 'path (relative path to .md file) is required',
+    })
+    return
+  }
+  if (!isSafeRelativePath(relativePath)) {
+    respond(false, undefined, {
+      code: 'invalid_params',
+      message: 'path must be a safe relative path (no directory traversal)',
+    })
+    return
+  }
+  if (!relativePath.toLowerCase().endsWith('.md')) {
+    respond(false, undefined, {
+      code: 'invalid_params',
+      message: 'path must point to a .md file',
+    })
+    return
+  }
+
+  const fullPath = path.join(dir, path.normalize(relativePath))
+  const realBase = await fs.realpath(dir).catch(() => dir)
+  const realResolved = await fs.realpath(fullPath).catch(() => null)
+
+  if (!realResolved) {
+    respond(false, undefined, {code: 'not_found', message: 'file not found'})
+    return
+  }
+  const rel = path.relative(realBase, realResolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    respond(false, undefined, {
+      code: 'not_found',
+      message: 'file not found or outside allowed directory',
+    })
+    return
+  }
+
+  try {
+    const content = await fs.readFile(fullPath, 'utf-8')
+    respond(true, {path: relativePath, content})
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'ENOENT') {
+      respond(false, undefined, {code: 'not_found', message: 'file not found'})
+      return
+    }
+    api.logger.error(`readMdFile failed: ${err instanceof Error ? err.message : String(err)}`)
+    respond(false, undefined, {
+      code: 'error',
+      message: err instanceof Error ? err.message : String(err),
+    })
+  }
+}
+
 export function registerMemoryBrowser(api: PluginApi) {
   const memoryDir = resolveMemoryDir(api)
-  api.logger.info(`memory-browser: memory directory: ${memoryDir}`)
+  const wsRoot = resolveWorkspaceRoot(api)
+  api.logger.info(`memory-browser: memory=${memoryDir} workspace=${wsRoot}`)
 
   // -----------------------------
-  // memory-browser.list
+  // memory-browser.list (may be shadowed by built-in)
   // -----------------------------
   api.registerGatewayMethod('memory-browser.list', async ({params, respond}) => {
     try {
-      api.logger.info(`memory-browser.list params: ${JSON.stringify(params)}`)
       const profile = readString(params, 'profile')
-      const scope = readString(params, 'scope') ?? 'memory'
-
-      let files: string[]
-      if (scope === 'root') {
-        const wsRoot = resolveWorkspaceRoot(api, profile)
-        files = await listRootMdFiles(wsRoot)
-        api.logger.info(`memory-browser.list (root): ${files.length} files found in ${wsRoot}`)
-      } else {
-        const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
-        files = await collectMdFiles(dir, dir)
-        files.sort()
-        api.logger.info(`memory-browser.list: ${files.length} files found`)
-      }
+      const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+      const files = await collectMdFiles(dir, dir)
+      files.sort()
+      api.logger.info(`memory-browser.list: ${files.length} files found`)
       respond(true, {files})
     } catch (err) {
       api.logger.error(
@@ -145,71 +201,27 @@ export function registerMemoryBrowser(api: PluginApi) {
   })
 
   // -----------------------------
-  // memory-browser.get
+  // memory-browser.get (may be shadowed by built-in)
   // -----------------------------
   api.registerGatewayMethod('memory-browser.get', async ({params, respond}) => {
-    const relativePath = readString(params, 'path')
     const profile = readString(params, 'profile')
-    const scope = readString(params, 'scope') ?? 'memory'
-    const dir =
-      scope === 'root'
-        ? resolveWorkspaceRoot(api, profile)
-        : profile
-          ? resolveMemoryDir(api, profile)
-          : memoryDir
-    if (!relativePath) {
-      respond(false, undefined, {
-        code: 'invalid_params',
-        message: 'path (relative path to .md file) is required',
-      })
-      return
-    }
-    if (!isSafeRelativePath(relativePath)) {
-      respond(false, undefined, {
-        code: 'invalid_params',
-        message: 'path must be a safe relative path (no directory traversal)',
-      })
-      return
-    }
-    if (!relativePath.toLowerCase().endsWith('.md')) {
-      respond(false, undefined, {
-        code: 'invalid_params',
-        message: 'path must point to a .md file',
-      })
-      return
-    }
-
-    const fullPath = path.join(dir, path.normalize(relativePath))
-    const realMemory = await fs.realpath(dir).catch(() => dir)
-    const realResolved = await fs.realpath(fullPath).catch(() => null)
-
-    if (!realResolved) {
-      respond(false, undefined, {
-        code: 'not_found',
-        message: 'file not found',
-      })
-      return
-    }
-    const rel = path.relative(realMemory, realResolved)
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
-      respond(false, undefined, {
-        code: 'not_found',
-        message: 'file not found or outside memory directory',
-      })
-      return
-    }
+    const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+    await readMdFile(dir, readString(params, 'path'), api, respond)
+  })
 
+  // -----------------------------
+  // clawly.workspace.list — workspace root .md files (not shadowed)
+  // -----------------------------
+  api.registerGatewayMethod('clawly.workspace.list', async ({params, respond}) => {
     try {
-      const content = await fs.readFile(fullPath, 'utf-8')
-      respond(true, {path: relativePath, content})
+      const profile = readString(params, 'profile')
+      const root = resolveWorkspaceRoot(api, profile)
+      const files = await listRootMdFiles(root)
+      api.logger.info(`clawly.workspace.list: ${files.length} files in ${root}`)
+      respond(true, {files})
     } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code
-      if (code === 'ENOENT') {
-        respond(false, undefined, {code: 'not_found', message: 'file not found'})
-        return
-      }
       api.logger.error(
-        `memory-browser.get failed: ${err instanceof Error ? err.message : String(err)}`,
+        `clawly.workspace.list failed: ${err instanceof Error ? err.message : String(err)}`,
       )
       respond(false, undefined, {
         code: 'error',
@@ -218,5 +230,14 @@ export function registerMemoryBrowser(api: PluginApi) {
     }
   })
 
-  api.logger.info(`memory-browser: registered v1.11.0 (dir: ${memoryDir})`)
+  // -----------------------------
+  // clawly.workspace.get — read a single .md file from workspace root
+  // -----------------------------
+  api.registerGatewayMethod('clawly.workspace.get', async ({params, respond}) => {
+    const profile = readString(params, 'profile')
+    const root = resolveWorkspaceRoot(api, profile)
+    await readMdFile(root, readString(params, 'path'), api, respond)
+  })
+
+  api.logger.info('memory-browser: registered')
 }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.11.0",
+  "version": "1.13.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}`)