@2en/clawly-plugins 1.16.0 → 1.16.2

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,149 @@
+import {afterEach, beforeEach, describe, expect, mock, test} from 'bun:test'
+import type {PluginApi} from '../index'
+import {PUSH_COOLDOWN_S, _resetCooldowns, registerOfflinePush} from './offline-push'
+
+// ── Mocks ────────────────────────────────────────────────────────
+
+let mockOnline = false
+let mockPushSent = true
+
+mock.module('./presence', () => ({
+  isClientOnline: async () => mockOnline,
+}))
+
+mock.module('./notification', () => ({
+  sendPushNotification: async () => mockPushSent,
+}))
+
+// ── 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
+  _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)
+  })
+})

package/gateway/offline-push.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 type {PluginApi} from '../index'
+import {sendPushNotification} from './notification'
+import {isClientOnline} from './presence'
+
+/** 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>()
+
+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 sent = await sendPushNotification(
+        {
+          body: 'Your response is ready',
+          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,6 +24,7 @@
  * 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)
  */
 
@@ -35,6 +36,7 @@ import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
+import {setupModelGateway} from './model-gateway-setup'
 import {registerOutboundHook, registerOutboundHttpRoute, registerOutboundMethods} from './outbound'
 import {registerTools} from './tools'
 
@@ -117,6 +119,7 @@ export default {
     registerCronHook(api)
     registerGateway(api)
     registerAutoPair(api)
+    setupModelGateway(api)
 
     // Email & calendar (optional — requires skillGatewayBaseUrl + skillGatewayToken in config)
     const gw = getGatewayConfig(api)

package/model-gateway-setup.ts

@@ -0,0 +1,101 @@
+/**
+ * On plugin init, patches openclaw.json to add the `clawly-model-gateway`
+ * model provider entry.  Credentials come from pluginConfig; the model list
+ * is derived from `agents.defaults.model` / `agents.defaults.imageModel`
+ * already present in the config.
+ *
+ * This runs synchronously during plugin registration (before gateway_start).
+ * OpenClaw loads the config file once at startup, so writing before the
+ * gateway fully starts ensures the provider is active on first boot.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import type {PluginApi} from './index'
+
+const PROVIDER_NAME = 'clawly-model-gateway'
+
+function resolveStateDir(api: PluginApi): string {
+  return api.runtime.state?.resolveStateDir?.(process.env) ?? process.env.OPENCLAW_STATE_DIR ?? ''
+}
+
+function readOpenclawConfig(configPath: string): Record<string, unknown> {
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeOpenclawConfig(configPath: string, config: Record<string, unknown>) {
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+}
+
+export function setupModelGateway(api: PluginApi): void {
+  const cfg = api.pluginConfig as Record<string, unknown> | undefined
+  const baseUrl =
+    typeof cfg?.modelGatewayBaseUrl === 'string' ? cfg.modelGatewayBaseUrl.replace(/\/$/, '') : ''
+  const token = typeof cfg?.modelGatewayToken === 'string' ? cfg.modelGatewayToken : ''
+
+  if (!baseUrl || !token) {
+    api.logger.info('Model gateway not configured (missing baseUrl or token), skipping.')
+    return
+  }
+
+  const stateDir = resolveStateDir(api)
+  if (!stateDir) {
+    api.logger.warn('Cannot resolve state dir — model gateway setup skipped.')
+    return
+  }
+
+  const configPath = path.join(stateDir, 'openclaw.json')
+  const config = readOpenclawConfig(configPath)
+
+  // Already configured — skip
+  if (config.models?.providers?.[PROVIDER_NAME]) {
+    api.logger.info('Model gateway provider already configured.')
+    return
+  }
+
+  // Derive model IDs from agents.defaults
+  const defaultModelFull: string = (config.agents as any)?.defaults?.model?.primary ?? ''
+  const imageModelFull: string = (config.agents as any)?.defaults?.imageModel?.primary ?? ''
+
+  const prefix = `${PROVIDER_NAME}/`
+  const defaultModel = defaultModelFull.startsWith(prefix)
+    ? defaultModelFull.slice(prefix.length)
+    : defaultModelFull
+  const imageModel = imageModelFull.startsWith(prefix)
+    ? imageModelFull.slice(prefix.length)
+    : imageModelFull
+
+  if (!defaultModel) {
+    api.logger.warn('No default model found in agents.defaults — model gateway setup skipped.')
+    return
+  }
+
+  const models =
+    defaultModel === imageModel || !imageModel
+      ? [{id: defaultModel, name: defaultModel, input: ['text', 'image']}]
+      : [
+          {id: defaultModel, name: defaultModel, input: ['text']},
+          {id: imageModel, name: imageModel, input: ['text', 'image']},
+        ]
+
+  if (!config.models) config.models = {}
+  if (!(config.models as any).providers) (config.models as any).providers = {}
+  ;(config.models as any).providers[PROVIDER_NAME] = {
+    baseUrl,
+    apiKey: token,
+    api: 'openai-completions',
+    models,
+  }
+
+  try {
+    writeOpenclawConfig(configPath, config)
+    api.logger.info(`Model gateway provider configured: ${baseUrl} with ${models.length} model(s).`)
+  } catch (err) {
+    api.logger.error(`Failed to setup model gateway: ${(err as Error).message}`)
+  }
+}

package/openclaw.plugin.json

@@ -47,7 +47,9 @@
       "defaultTimeoutMs": { "type": "number", "minimum": 1000 },
       "configPath": { "type": "string" },
       "skillGatewayBaseUrl": { "type": "string" },
-      "skillGatewayToken": { "type": "string" }
+      "skillGatewayToken": { "type": "string" },
+      "modelGatewayBaseUrl": { "type": "string" },
+      "modelGatewayToken": { "type": "string" }
     },
     "required": []
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -24,6 +24,7 @@
     "email.ts",
     "gateway-fetch.ts",
     "outbound.ts",
+    "model-gateway-setup.ts",
     "openclaw.plugin.json"
   ],
   "publishConfig": {