@2en/clawly-plugins 1.16.1 → 1.16.3

package/auto-pair.ts

@@ -0,0 +1,72 @@
+import type {PluginApi} from './index'
+
+const AUTO_APPROVE_CLIENT_IDS = new Set(['openclaw-ios'])
+const POLL_INTERVAL_MS = 3_000
+
+type PendingRequest = {
+  requestId: string
+  deviceId: string
+  clientId?: string
+  displayName?: string
+  platform?: string
+}
+
+type PairedDevice = {
+  deviceId: string
+  displayName?: string
+  platform?: string
+}
+
+type DevicePairingList = {
+  pending: PendingRequest[]
+  paired: PairedDevice[]
+}
+
+export function registerAutoPair(api: PluginApi) {
+  let timer: ReturnType<typeof setInterval> | null = null
+  let sdk: {
+    listDevicePairing: () => Promise<DevicePairingList>
+    approveDevicePairing: (
+      requestId: string,
+    ) => Promise<{requestId: string; device: PairedDevice} | null>
+  } | null = null
+
+  api.on('gateway_start', async () => {
+    try {
+      sdk = await import('openclaw/plugin-sdk')
+    } catch {
+      api.logger.warn('auto-pair: openclaw/plugin-sdk not available, skipping')
+      return
+    }
+
+    api.logger.info('auto-pair: started polling for pending pairing requests')
+
+    timer = setInterval(async () => {
+      if (!sdk) return
+      try {
+        const {pending} = await sdk.listDevicePairing()
+        for (const req of pending) {
+          if (req.clientId && AUTO_APPROVE_CLIENT_IDS.has(req.clientId)) {
+            const result = await sdk.approveDevicePairing(req.requestId)
+            if (result) {
+              api.logger.info(
+                `auto-pair: approved device=${result.device.deviceId} ` +
+                  `name=${result.device.displayName ?? 'unknown'} ` +
+                  `platform=${result.device.platform ?? 'unknown'}`,
+              )
+            }
+          }
+        }
+      } catch (err) {
+        api.logger.warn(`auto-pair: poll error: ${String(err)}`)
+      }
+    }, POLL_INTERVAL_MS)
+  })
+
+  api.on('gateway_stop', () => {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  })
+}

package/gateway/index.ts

@@ -5,6 +5,7 @@ import {registerClawhub2gateway} from './clawhub2gateway'
 import {registerInject} from './inject'
 import {registerMemoryBrowser} from './memory'
 import {registerNotification} from './notification'
+import {registerOfflinePush} from './offline-push'
 import {registerPlugins} from './plugins'
 import {registerPresence} from './presence'
 
@@ -17,4 +18,5 @@ export function registerGateway(api: PluginApi) {
   registerClawhub2gateway(api)
   registerPlugins(api)
   registerChannelsConfigure(api)
+  registerOfflinePush(api)
 }

package/gateway/memory.ts

@@ -8,6 +8,7 @@
  * - clawly.workspace.get — read a .md file from workspace root
  */
 
+import fsSync from 'node:fs'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
@@ -39,6 +40,37 @@ function coercePluginConfig(api: PluginApi): Record<string, unknown> {
   return isRecord(api.pluginConfig) ? api.pluginConfig : {}
 }
 
+function resolveStateDir(api: PluginApi): string {
+  return api.runtime.state?.resolveStateDir?.(process.env) ?? process.env.OPENCLAW_STATE_DIR ?? ''
+}
+
+/** Read the default agent's workspace path from openclaw.json (cached). */
+let _cachedAgentWorkspace: string | null | undefined
+function readAgentWorkspace(api: PluginApi): string | null {
+  if (_cachedAgentWorkspace !== undefined) return _cachedAgentWorkspace
+  try {
+    const stateDir = resolveStateDir(api)
+    if (!stateDir) {
+      _cachedAgentWorkspace = null
+      return null
+    }
+    const raw = fsSync.readFileSync(path.join(stateDir, 'openclaw.json'), 'utf-8')
+    const config = JSON.parse(raw)
+    const agents = config?.agents?.list
+    if (!Array.isArray(agents)) {
+      _cachedAgentWorkspace = null
+      return null
+    }
+    const defaultAgent = agents.find((a: any) => a.default) ?? agents[0]
+    const ws = typeof defaultAgent?.workspace === 'string' ? defaultAgent.workspace : null
+    _cachedAgentWorkspace = ws
+    return ws
+  } catch {
+    _cachedAgentWorkspace = null
+    return null
+  }
+}
+
 /** Resolve the workspace root directory (without /memory suffix). */
 function resolveWorkspaceRoot(api: PluginApi, profile?: string): string {
   const cfg = coercePluginConfig(api)
@@ -46,7 +78,9 @@ function resolveWorkspaceRoot(api: PluginApi, profile?: string): string {
   if (configPath) return path.dirname(configPath) // strip /memory if configured
 
   const baseDir =
-    process.env.OPENCLAW_WORKSPACE ?? path.join(os.homedir(), '.openclaw', 'workspace')
+    process.env.OPENCLAW_WORKSPACE ??
+    readAgentWorkspace(api) ??
+    path.join(os.homedir(), '.openclaw', 'workspace')
   if (profile && profile !== 'main') {
     const parentDir = path.dirname(baseDir)
     const baseName = path.basename(baseDir)

package/gateway/offline-push.test.ts

@@ -0,0 +1,300 @@
+import {afterEach, beforeEach, describe, expect, mock, test} from 'bun:test'
+import type {PluginApi} from '../index'
+import {
+  PUSH_COOLDOWN_S,
+  _resetCooldowns,
+  getLastAssistantPreview,
+  registerOfflinePush,
+} from './offline-push'
+
+// ── Mocks ────────────────────────────────────────────────────────
+
+let mockOnline = false
+let mockPushSent = true
+let lastPushOpts: {body: string; title?: string; data?: Record<string, unknown>} | null = null
+let mockIdentity: {name?: string; emoji?: string} | null = null
+
+mock.module('./presence', () => ({
+  isClientOnline: async () => mockOnline,
+}))
+
+mock.module('./notification', () => ({
+  sendPushNotification: async (opts: {
+    body: string
+    title?: string
+    data?: Record<string, unknown>
+  }) => {
+    lastPushOpts = opts
+    return mockPushSent
+  },
+}))
+
+mock.module('./offline-push', () => {
+  const original = require('./offline-push')
+  return {
+    ...original,
+    getAgentIdentity: async () => mockIdentity,
+  }
+})
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function createMockApi(): {
+  api: PluginApi
+  logs: {level: string; msg: string}[]
+  handlers: Map<string, (event: Record<string, unknown>) => Promise<void>>
+} {
+  const logs: {level: string; msg: string}[] = []
+  const handlers = new Map<string, (event: Record<string, unknown>) => Promise<void>>()
+  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}),
+    },
+    on: (hookName: string, handler: (...args: any[]) => any) => {
+      handlers.set(hookName, handler as any)
+    },
+  } as unknown as PluginApi
+  return {api, logs, handlers}
+}
+
+// ── Tests ────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  mockOnline = false
+  mockPushSent = true
+  mockIdentity = null
+  lastPushOpts = null
+  _resetCooldowns()
+})
+
+describe('offline-push', () => {
+  test('sends push when client is offline', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const handler = handlers.get('agent_end')!
+    await handler({sessionKey: 'sess-1'})
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=sess-1)'),
+    })
+  })
+
+  test('skips push when client is online', async () => {
+    mockOnline = true
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({sessionKey: 'sess-1'})
+
+    expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(0)
+    expect(logs.filter((l) => l.msg.includes('skipped'))).toHaveLength(0)
+  })
+
+  test('respects per-session cooldown', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const handler = handlers.get('agent_end')!
+
+    // First call — should send
+    await handler({sessionKey: 'sess-1'})
+    expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(1)
+
+    // Second call same session — should be cooldown-skipped
+    await handler({sessionKey: 'sess-1'})
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('skipped (cooldown, session=sess-1)'),
+    })
+  })
+
+  test('different sessions have independent cooldowns', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const handler = handlers.get('agent_end')!
+
+    await handler({sessionKey: 'sess-1'})
+    await handler({sessionKey: 'sess-2'})
+
+    const notified = logs.filter((l) => l.msg.includes('notified'))
+    expect(notified).toHaveLength(2)
+    expect(notified[0].msg).toContain('sess-1')
+    expect(notified[1].msg).toContain('sess-2')
+  })
+
+  test('uses __global__ key when sessionKey is missing', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const handler = handlers.get('agent_end')!
+    await handler({})
+    await handler({})
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=unknown)'),
+    })
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('skipped (cooldown, session=__global__)'),
+    })
+  })
+
+  test('does not update cooldown when push is not sent', async () => {
+    mockPushSent = false
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const handler = handlers.get('agent_end')!
+
+    // Push returns false (e.g. no token) — cooldown should NOT be set
+    await handler({sessionKey: 'sess-1'})
+    expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(0)
+
+    // Second call should NOT be cooldown-skipped since first wasn't sent
+    mockPushSent = true
+    await handler({sessionKey: 'sess-1'})
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=sess-1)'),
+    })
+  })
+
+  test('exports PUSH_COOLDOWN_S as 30', () => {
+    expect(PUSH_COOLDOWN_S).toBe(30)
+  })
+
+  // ── Rich title/body tests ────────────────────────────────────
+
+  test('title shows agent emoji + name when identity is available', async () => {
+    mockIdentity = {name: 'Luna', emoji: '🐱'}
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({sessionKey: 'sess-1'})
+
+    expect(lastPushOpts?.title).toBe('🐱 Luna')
+  })
+
+  test('title falls back to 🦞 Clawly when identity fetch fails', async () => {
+    mockIdentity = null
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({sessionKey: 'sess-1'})
+
+    expect(lastPushOpts?.title).toBe('🦞 Clawly')
+  })
+
+  test('title uses default emoji when identity has name but no emoji', async () => {
+    mockIdentity = {name: 'Atlas'}
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({sessionKey: 'sess-1'})
+
+    expect(lastPushOpts?.title).toBe('🦞 Atlas')
+  })
+
+  test('body shows assistant message preview when messages are present', async () => {
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({
+      sessionKey: 'sess-1',
+      messages: [
+        {role: 'user', content: 'Hello'},
+        {role: 'assistant', content: 'Hi there! How can I help you today?'},
+      ],
+    })
+
+    expect(lastPushOpts?.body).toBe('Hi there! How can I help you today?')
+  })
+
+  test('body falls back when no messages', async () => {
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({sessionKey: 'sess-1'})
+
+    expect(lastPushOpts?.body).toBe('Your response is ready')
+  })
+
+  test('body falls back when messages has no assistant role', async () => {
+    const {api, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    await handlers.get('agent_end')!({
+      sessionKey: 'sess-1',
+      messages: [{role: 'user', content: 'Hello'}],
+    })
+
+    expect(lastPushOpts?.body).toBe('Your response is ready')
+  })
+})
+
+// ── getLastAssistantPreview unit tests ──────────────────────────
+
+describe('getLastAssistantPreview', () => {
+  test('returns null for non-array input', () => {
+    expect(getLastAssistantPreview(undefined)).toBeNull()
+    expect(getLastAssistantPreview(null)).toBeNull()
+    expect(getLastAssistantPreview('string')).toBeNull()
+  })
+
+  test('extracts string content from last assistant message', () => {
+    const messages = [
+      {role: 'user', content: 'Hi'},
+      {role: 'assistant', content: 'First reply'},
+      {role: 'user', content: 'Another question'},
+      {role: 'assistant', content: 'Second reply'},
+    ]
+    expect(getLastAssistantPreview(messages)).toBe('Second reply')
+  })
+
+  test('handles array content with text parts', () => {
+    const messages = [
+      {
+        role: 'assistant',
+        content: [
+          {type: 'text', text: 'Hello '},
+          {type: 'text', text: 'world!'},
+        ],
+      },
+    ]
+    expect(getLastAssistantPreview(messages)).toBe('Hello world!')
+  })
+
+  test('collapses newlines into spaces', () => {
+    const messages = [{role: 'assistant', content: 'Line one\n\nLine two\nLine three'}]
+    expect(getLastAssistantPreview(messages)).toBe('Line one Line two Line three')
+  })
+
+  test('truncates long messages with ellipsis', () => {
+    const longText = 'a'.repeat(200)
+    const messages = [{role: 'assistant', content: longText}]
+    const result = getLastAssistantPreview(messages, 140)!
+    expect(result.length).toBe(141) // 140 chars + "…"
+    expect(result.endsWith('…')).toBe(true)
+  })
+
+  test('skips assistant messages with empty content', () => {
+    const messages = [
+      {role: 'assistant', content: 'Good reply'},
+      {role: 'assistant', content: ''},
+    ]
+    expect(getLastAssistantPreview(messages)).toBe('Good reply')
+  })
+
+  test('returns null when no assistant messages exist', () => {
+    const messages = [{role: 'user', content: 'Hello'}]
+    expect(getLastAssistantPreview(messages)).toBeNull()
+  })
+})

package/gateway/offline-push.ts

@@ -0,0 +1,137 @@
+/**
+ * Offline push notification on agent_end — sends a push notification
+ * when an agent run completes and the mobile client is disconnected.
+ *
+ * Hook: agent_end → check presence → send Expo push if offline
+ *
+ * Avoids double-push with clawly.agent.send (which pushes at dispatch
+ * time for cron/external triggers) via a 30-second cooldown window.
+ */
+
+import {$} from 'zx'
+import type {PluginApi} from '../index'
+import {stripCliLogs} from '../lib/stripCliLogs'
+import {sendPushNotification} from './notification'
+import {isClientOnline} from './presence'
+
+$.verbose = false
+
+/** Minimum seconds between consecutive push notifications per session. */
+export const PUSH_COOLDOWN_S = 30
+
+/** Per-session cooldown tracker. Key = sessionKey (or "__global__" for unknown). */
+const lastPushBySession = new Map<string, number>()
+
+/**
+ * Fetch agent display identity (name, emoji) via gateway RPC.
+ * Returns null on failure so the caller can fall back to defaults.
+ */
+export async function getAgentIdentity(
+  agentId: string | undefined,
+): Promise<{name?: string; emoji?: string} | null> {
+  if (!agentId) return null
+  try {
+    const rpcParams = JSON.stringify({agentId})
+    const result = await $`openclaw gateway call agent.identity.get --json --params ${rpcParams}`
+    const parsed = JSON.parse(stripCliLogs(result.stdout))
+    return {
+      name: typeof parsed.name === 'string' ? parsed.name : undefined,
+      emoji: typeof parsed.emoji === 'string' ? parsed.emoji : undefined,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Extract the last assistant message text and truncate to `maxLen` chars.
+ * Handles both string content and `{type:'text', text}[]` content formats.
+ */
+export function getLastAssistantPreview(messages: unknown, maxLen = 140): string | null {
+  if (!Array.isArray(messages)) return null
+
+  // Walk backwards to find the last assistant message
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]
+    if (typeof msg !== 'object' || msg === null) continue
+    if ((msg as any).role !== 'assistant') continue
+
+    const content = (msg as any).content
+    let text: string | undefined
+
+    if (typeof content === 'string') {
+      text = content
+    } else if (Array.isArray(content)) {
+      // Concatenate all text parts
+      text = content
+        .filter((p: any) => typeof p === 'object' && p !== null && p.type === 'text')
+        .map((p: any) => p.text)
+        .join('')
+    }
+
+    if (!text) continue
+
+    // Collapse newlines → spaces, trim
+    const collapsed = text.replace(/\n+/g, ' ').trim()
+    if (!collapsed) continue
+
+    if (collapsed.length <= maxLen) return collapsed
+    return `${collapsed.slice(0, maxLen)}…`
+  }
+
+  return null
+}
+
+export function registerOfflinePush(api: PluginApi) {
+  api.on('agent_end', async (event: Record<string, unknown>) => {
+    try {
+      // Skip if client is still connected — they got the response in real-time.
+      const online = await isClientOnline()
+      if (online) return
+
+      const sessionKey = typeof event.sessionKey === 'string' ? event.sessionKey : undefined
+      const cooldownKey = sessionKey ?? '__global__'
+
+      // Cooldown: skip if a push was sent recently for this session
+      // (e.g. by clawly.agent.send).
+      const now = Date.now() / 1000
+      const lastPush = lastPushBySession.get(cooldownKey) ?? 0
+      if (now - lastPush < PUSH_COOLDOWN_S) {
+        api.logger.info(`offline-push: skipped (cooldown, session=${cooldownKey})`)
+        return
+      }
+
+      const agentId = typeof event.agentId === 'string' ? event.agentId : undefined
+      const identity = await getAgentIdentity(agentId)
+      const title = `${identity?.emoji ?? '🦞'} ${identity?.name ?? 'Clawly'}`
+      const preview = getLastAssistantPreview(event.messages, 140)
+      const body = preview ?? 'Your response is ready'
+
+      const sent = await sendPushNotification(
+        {
+          title,
+          body,
+          data: {
+            type: 'agent_end',
+            ...(sessionKey ? {sessionKey} : {}),
+          },
+        },
+        api,
+      )
+
+      if (sent) {
+        lastPushBySession.set(cooldownKey, Date.now() / 1000)
+        api.logger.info(`offline-push: notified (session=${sessionKey ?? 'unknown'})`)
+      }
+    } catch (err) {
+      api.logger.error(`offline-push: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  })
+
+  api.logger.info('offline-push: registered agent_end hook')
+}
+
+/** @internal — exposed for testing */
+export function _resetCooldowns() {
+  lastPushBySession.clear()
+}

package/gateway/presence.test.ts

@@ -0,0 +1,32 @@
+import {describe, expect, test} from 'bun:test'
+import {isOnlineEntry} from './presence'
+
+describe('isOnlineEntry', () => {
+  test('returns true for reason "foreground"', () => {
+    expect(isOnlineEntry({host: 'openclaw-ios', reason: 'foreground'})).toBe(true)
+  })
+
+  test('returns true for reason "connect" (backward compat)', () => {
+    expect(isOnlineEntry({host: 'openclaw-ios', reason: 'connect'})).toBe(true)
+  })
+
+  test('returns false for reason "background"', () => {
+    expect(isOnlineEntry({host: 'openclaw-ios', reason: 'background'})).toBe(false)
+  })
+
+  test('returns false for reason "disconnect"', () => {
+    expect(isOnlineEntry({host: 'openclaw-ios', reason: 'disconnect'})).toBe(false)
+  })
+
+  test('returns false for undefined entry (host not found)', () => {
+    expect(isOnlineEntry(undefined)).toBe(false)
+  })
+
+  test('returns false for entry with no reason', () => {
+    expect(isOnlineEntry({host: 'openclaw-ios'})).toBe(false)
+  })
+
+  test('returns false for empty entry', () => {
+    expect(isOnlineEntry({})).toBe(false)
+  })
+})

package/gateway/presence.ts

@@ -19,6 +19,12 @@ interface PresenceEntry {
   reason?: string
 }
 
+/** Returns true if the presence entry indicates the client is actively connected. */
+export function isOnlineEntry(entry: PresenceEntry | undefined): boolean {
+  if (!entry) return false
+  return entry.reason === 'foreground' || entry.reason === 'connect'
+}
+
 /**
  * Shells out to `openclaw gateway call system-presence` and checks
  * whether the given host has a non-"disconnect" entry.
@@ -29,8 +35,7 @@ export async function isClientOnline(host = DEFAULT_HOST): Promise<boolean> {
     const jsonStr = stripCliLogs(result.stdout)
     const entries: PresenceEntry[] = JSON.parse(jsonStr)
     const entry = entries.find((e) => e.host === host)
-    if (!entry) return false
-    return entry.reason === 'connect'
+    return isOnlineEntry(entry)
   } catch {
     return false
   }

package/index.ts

@@ -24,8 +24,11 @@
  * Hooks:
  * - tool_result_persist   — copies TTS audio to persistent outbound directory
  * - before_tool_call      — enforces delivery fields on cron.create
+ * - agent_end             — sends push notification when client is offline
+ * - gateway_start         — auto-approves device pairing for Clawly mobile clients (clientId: openclaw-ios)
  */
 
+import {registerAutoPair} from './auto-pair'
 import {registerCalendar} from './calendar'
 import {registerClawlyCronChannel} from './channel'
 import {registerCommands} from './command'
@@ -115,6 +118,7 @@ export default {
     registerClawlyCronChannel(api)
     registerCronHook(api)
     registerGateway(api)
+    registerAutoPair(api)
     setupModelGateway(api)
 
     // Email & calendar (optional — requires skillGatewayBaseUrl + skillGatewayToken in config)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.16.1",
+  "version": "1.16.3",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -17,13 +17,13 @@
     "lib",
     "tools",
     "index.ts",
+    "auto-pair.ts",
     "calendar.ts",
     "channel.ts",
     "cron-hook.ts",
     "email.ts",
     "gateway-fetch.ts",
     "outbound.ts",
-    "auto-pair.ts",
     "model-gateway-setup.ts",
     "openclaw.plugin.json"
   ],