@2en/clawly-plugins 1.30.0-beta.1 → 1.30.0-beta.10

package/gateway/config-model.ts

@@ -0,0 +1,74 @@
+/**
+ * Model switch RPC: writes agents.defaults.model.primary to openclaw.json
+ * without triggering a gateway restart.
+ *
+ * OpenClaw reads agents.defaults.model.primary dynamically on each chat
+ * request (loadConfig() has a ~200ms cache). A disk write takes effect
+ * within that window — no SIGUSR1 needed.
+ *
+ * Uses the runtime config APIs (loadConfig + writeConfigFile) for atomic
+ * writes, env var preservation, and config validation.
+ *
+ * Methods:
+ * - clawly.config.setModel({ model }) → { changed, model }
+ */
+
+import type {PluginApi} from '../types'
+import type {OpenClawConfig} from '../types/openclaw'
+import {backfillDiskConfig} from '../model-gateway-setup'
+
+export function registerConfigModel(api: PluginApi) {
+  api.registerGatewayMethod('clawly.config.setModel', async ({params, respond}) => {
+    const model = typeof params.model === 'string' ? params.model : ''
+    if (!model) {
+      respond(true, {changed: false, model: '', error: 'Missing model param'})
+      return
+    }
+
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      respond(true, {changed: false, model, error: `Load failed: ${msg}`})
+      return
+    }
+
+    const current = (config.agents as Record<string, unknown> | undefined)?.defaults as
+      | Record<string, unknown>
+      | undefined
+    const currentModel = (current?.model as Record<string, unknown> | undefined)?.primary
+
+    if (currentModel === model) {
+      respond(true, {changed: false, model})
+      return
+    }
+
+    // Shallow-copy nested objects to avoid polluting the loadConfig() cache
+    // if writeConfigFile fails below.
+    const agents = {...((config.agents ?? {}) as Record<string, unknown>)}
+    const defaults = {...((agents.defaults ?? {}) as Record<string, unknown>)}
+    const modelObj = {...((defaults.model ?? {}) as Record<string, unknown>)}
+    modelObj.primary = model
+    defaults.model = modelObj
+    agents.defaults = defaults
+    config.agents = agents
+
+    // Backfill fields written by setupConfig (which writes directly to disk)
+    // so writeConfigFile's merge-patch doesn't revert them.
+    const stateDir = api.runtime.state.resolveStateDir()
+    const configToWrite = stateDir ? backfillDiskConfig(stateDir, config) : config
+
+    try {
+      await api.runtime.config.writeConfigFile(configToWrite)
+      api.logger.info(`config-model: set model.primary to ${model}`)
+      respond(true, {changed: true, model})
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      api.logger.error(`config-model: write failed — ${msg}`)
+      respond(true, {changed: false, model, error: `Write failed: ${msg}`})
+    }
+  })
+
+  api.logger.info('config-model: registered clawly.config.setModel')
+}

package/gateway/config-timezone.ts

@@ -2,14 +2,16 @@
  * Timezone sync RPC: writes agents.defaults.userTimezone to openclaw.json
  * without triggering a gateway restart.
  *
+ * Uses the runtime config APIs (loadConfig + writeConfigFile) for atomic
+ * writes, env var preservation, and config validation.
+ *
  * Methods:
  * - clawly.config.setTimezone({ timezone }) → { changed, timezone }
  */
 
-import path from 'node:path'
-
 import type {PluginApi} from '../types'
-import {readOpenclawConfig, writeOpenclawConfig} from '../model-gateway-setup'
+import type {OpenClawConfig} from '../types/openclaw'
+import {backfillDiskConfig} from '../model-gateway-setup'
 
 export function registerConfigTimezone(api: PluginApi) {
   api.registerGatewayMethod('clawly.config.setTimezone', async ({params, respond}) => {
@@ -19,30 +21,39 @@ export function registerConfigTimezone(api: PluginApi) {
       return
     }
 
-    const stateDir = api.runtime.state.resolveStateDir()
-    if (!stateDir) {
-      respond(true, {changed: false, timezone, error: 'Cannot resolve state dir'})
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      respond(true, {changed: false, timezone, error: `Load failed: ${msg}`})
       return
     }
 
-    const configPath = path.join(stateDir, 'openclaw.json')
-    const config = readOpenclawConfig(configPath)
-
-    const agents = (config.agents ?? {}) as Record<string, unknown>
-    const defaults = (agents.defaults ?? {}) as Record<string, unknown>
-    const current = defaults.userTimezone
+    const currentDefaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+      | Record<string, unknown>
+      | undefined
 
-    if (current === timezone) {
+    if (currentDefaults?.userTimezone === timezone) {
       respond(true, {changed: false, timezone})
       return
     }
 
+    // Shallow-copy nested objects to avoid polluting the loadConfig() cache
+    // if writeConfigFile fails below.
+    const agents = {...((config.agents ?? {}) as Record<string, unknown>)}
+    const defaults = {...((agents.defaults ?? {}) as Record<string, unknown>)}
     defaults.userTimezone = timezone
     agents.defaults = defaults
     config.agents = agents
 
+    // Backfill fields written by setupConfig (which writes directly to disk)
+    // so writeConfigFile's merge-patch doesn't revert them.
+    const stateDir = api.runtime.state.resolveStateDir()
+    const configToWrite = stateDir ? backfillDiskConfig(stateDir, config) : config
+
     try {
-      writeOpenclawConfig(configPath, config)
+      await api.runtime.config.writeConfigFile(configToWrite)
       api.logger.info(`config-timezone: set userTimezone to ${timezone}`)
       respond(true, {changed: true, timezone})
     } catch (err) {

package/gateway/cron-delivery.test.ts

@@ -263,6 +263,22 @@ describe('cron-delivery', () => {
       })
     })
 
+    test('skips HEARTBEAT OK with space (bare)', async () => {
+      const {api, logs, handlers} = createMockApi()
+      registerCronDelivery(api)
+
+      await handlers.get('agent_end')!(
+        {messages: makeMessages('HEARTBEAT OK')},
+        {sessionKey: 'agent:clawly:cron:weather-check', agentId: 'clawly'},
+      )
+
+      expect(injectCalls).toHaveLength(0)
+      expect(logs).toContainEqual({
+        level: 'info',
+        msg: expect.stringContaining('skipped (filtered: heartbeat ack)'),
+      })
+    })
+
     test('skips empty text', async () => {
       const {api, logs, handlers} = createMockApi()
       registerCronDelivery(api)

package/gateway/index.ts

@@ -3,8 +3,8 @@ import {registerAgentSend} from './agent'
 import {registerCalendarNative} from './calendar-native'
 import {registerAnalytics} from './analytics'
 import {registerAudit} from './audit'
-import {registerNodeDangerousAllowlist} from './node-dangerous-allowlist'
 import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerConfigModel} from './config-model'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
 import {registerCronDelivery} from './cron-delivery'
@@ -58,12 +58,12 @@ export function registerGateway(api: PluginApi) {
   registerCronTelemetry(api)
   registerMessageLog(api)
   registerAnalytics(api)
+  registerConfigModel(api)
   registerConfigRepair(api)
   registerConfigTimezone(api)
   registerSessionSanitize(api)
   registerPairing(api)
   registerVersion(api)
   registerAudit(api)
-  registerNodeDangerousAllowlist(api)
   registerCalendarNative(api)
 }

package/gateway/offline-push.test.ts

@@ -73,6 +73,11 @@ function createMockApi(): {
   return {api, logs, handlers}
 }
 
+/** Event with a simple assistant message — needed since the skip-on-no-text guard. */
+const eventWithReply = {
+  messages: [{role: 'assistant', content: 'Hello from the assistant'}],
+}
+
 // ── Tests ────────────────────────────────────────────────────────
 
 beforeEach(() => {
@@ -89,7 +94,7 @@ describe('offline-push', () => {
     registerOfflinePush(api)
 
     const handler = handlers.get('agent_end')!
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -117,8 +122,8 @@ describe('offline-push', () => {
 
     const handler = handlers.get('agent_end')!
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(logs.filter((l) => l.msg.includes('notified'))).toHaveLength(2)
   })
@@ -129,11 +134,11 @@ describe('offline-push', () => {
 
     const handler = handlers.get('agent_end')!
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
     expect(lastPushExtras).toEqual({badge: 1})
     expect(mockBadgeCount).toBe(1)
 
-    await handler({}, {sessionKey: 'agent:clawly:main'})
+    await handler(eventWithReply, {sessionKey: 'agent:clawly:main'})
     expect(lastPushExtras).toEqual({badge: 2})
     expect(mockBadgeCount).toBe(2)
   })
@@ -143,7 +148,7 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
     expect(lastPushExtras).toEqual({badge: 1})
     expect(mockBadgeCount).toBe(0) // incremented then decremented
@@ -153,7 +158,7 @@ describe('offline-push', () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:telegram:12345'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:telegram:12345'})
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -166,7 +171,9 @@ describe('offline-push', () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:cron:weather-check:run:abc123'})
+    await handlers.get('agent_end')!(eventWithReply, {
+      sessionKey: 'agent:clawly:cron:weather-check:run:abc123',
+    })
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -180,7 +187,7 @@ describe('offline-push', () => {
     registerOfflinePush(api)
 
     const handler = handlers.get('agent_end')!
-    await handler({})
+    await handler(eventWithReply)
 
     expect(logs).toContainEqual({
       level: 'info',
@@ -192,7 +199,10 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main', agentId: 'luna'})
+    await handlers.get('agent_end')!(eventWithReply, {
+      sessionKey: 'agent:clawly:main',
+      agentId: 'luna',
+    })
 
     expect(lastPushOpts?.agentId).toBe('luna')
   })
@@ -201,8 +211,9 @@ describe('offline-push', () => {
     const {api, handlers} = createMockApi()
     registerOfflinePush(api)
 
-    await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
+    await handlers.get('agent_end')!(eventWithReply, {sessionKey: 'agent:clawly:main'})
 
+    expect(lastPushOpts).not.toBeNull()
     expect(lastPushOpts?.title).toBeUndefined()
   })
 
@@ -223,17 +234,21 @@ describe('offline-push', () => {
     expect(lastPushOpts?.body).toBe('Hi there! How can I help you today?')
   })
 
-  test('body falls back when no messages', async () => {
-    const {api, handlers} = createMockApi()
+  test('skips push when no messages (no extractable text)', async () => {
+    const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
 
-    expect(lastPushOpts?.body).toBe('Your response is ready')
+    expect(lastPushOpts).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
+    })
   })
 
-  test('body falls back when messages has no assistant role', async () => {
-    const {api, handlers} = createMockApi()
+  test('skips push when messages has no assistant role', async () => {
+    const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!(
@@ -241,7 +256,11 @@ describe('offline-push', () => {
       {sessionKey: 'agent:clawly:main'},
     )
 
-    expect(lastPushOpts?.body).toBe('Your response is ready')
+    expect(lastPushOpts).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
+    })
   })
 
   test('body strips [[type:value]] placeholders', async () => {
@@ -427,6 +446,22 @@ describe('shouldSkipPushForMessage', () => {
     expect(shouldSkipPushForMessage('The token HEARTBEAT_OK is used for health checks.')).toBeNull()
   })
 
+  test('skips heartbeat ack with space variant (HEARTBEAT OK)', () => {
+    expect(shouldSkipPushForMessage('HEARTBEAT OK')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK.')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK\n')).toBe('heartbeat ack')
+  })
+
+  test('skips short content ending with HEARTBEAT OK (space variant)', () => {
+    expect(shouldSkipPushForMessage('All good. HEARTBEAT OK')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('Nothing to report. HEARTBEAT OK。')).toBe('heartbeat ack')
+  })
+
+  test('skips HEARTBEAT OK at start with short status note (space variant)', () => {
+    expect(shouldSkipPushForMessage('HEARTBEAT OK — all systems nominal.')).toBe('heartbeat ack')
+    expect(shouldSkipPushForMessage('HEARTBEAT OK. Nothing to report.')).toBe('heartbeat ack')
+  })
+
   test('skips system prompt leak', () => {
     expect(
       shouldSkipPushForMessage('Here is some Conversation info (untrusted metadata) text'),
@@ -565,6 +600,33 @@ describe('offline-push with filtered messages', () => {
     expect(lastPushOpts?.body?.endsWith('…')).toBe(true)
   })
 
+  test('sends push for long content and strips HEARTBEAT OK (space variant) from body', async () => {
+    const {api, logs, handlers} = createMockApi()
+    registerOfflinePush(api)
+
+    const longContent = 'A'.repeat(301)
+    await handlers.get('agent_end')!(
+      {
+        messages: [
+          {
+            role: 'assistant',
+            content: `${longContent}\n\nHEARTBEAT OK`,
+          },
+        ],
+      },
+      {sessionKey: 'agent:clawly:main'},
+    )
+
+    expect(logs).toContainEqual({
+      level: 'info',
+      msg: expect.stringContaining('notified (session=agent:clawly:main)'),
+    })
+    // HEARTBEAT OK should be stripped from body, content truncated to 140
+    expect(lastPushOpts?.body?.length).toBe(141)
+    expect(lastPushOpts?.body?.endsWith('…')).toBe(true)
+    expect(lastPushOpts?.body).not.toContain('HEARTBEAT')
+  })
+
   test('sends push for normal message text', async () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
@@ -580,15 +642,15 @@ describe('offline-push with filtered messages', () => {
     })
   })
 
-  test('sends push when event has no messages (safe default)', async () => {
+  test('skips push when event has no messages (no extractable text)', async () => {
     const {api, logs, handlers} = createMockApi()
     registerOfflinePush(api)
 
     await handlers.get('agent_end')!({}, {sessionKey: 'agent:clawly:main'})
 
     expect(logs).toContainEqual({
-      level: 'info',
-      msg: expect.stringContaining('notified (session=agent:clawly:main)'),
+      level: 'warn',
+      msg: expect.stringContaining('skipped (no extractable assistant text)'),
     })
   })
 })

package/gateway/offline-push.ts

@@ -160,12 +160,12 @@ export function shouldSkipPushForMessage(text: string): string | null {
   // Heartbeat acknowledgment — strip HEARTBEAT_OK from both edges (mirrors
   // OpenClaw's stripTokenAtEdges). Skip if remaining text ≤ ackMaxChars (300).
   const HEARTBEAT_ACK_MAX_CHARS = 300
-  const hasAtEnd = /HEARTBEAT_OK[\p{P}\s]*$/u.test(text)
-  const hasAtStart = /^[\p{P}\s]*HEARTBEAT_OK/u.test(text)
+  const hasAtEnd = /HEARTBEAT[_ ]OK[\p{P}\s]*$/u.test(text)
+  const hasAtStart = /^[\p{P}\s]*HEARTBEAT[_ ]OK/u.test(text)
   if (hasAtEnd || hasAtStart) {
     let stripped = text
-    if (hasAtEnd) stripped = stripped.replace(/HEARTBEAT_OK[\p{P}\s]*$/u, '')
-    if (hasAtStart) stripped = stripped.replace(/^[\p{P}\s]*HEARTBEAT_OK[\p{P}\s]*/u, '')
+    if (hasAtEnd) stripped = stripped.replace(/HEARTBEAT[_ ]OK[\p{P}\s]*$/u, '')
+    if (hasAtStart) stripped = stripped.replace(/^[\p{P}\s]*HEARTBEAT[_ ]OK[\p{P}\s]*/u, '')
     stripped = stripped.trim()
     if (stripped.length <= HEARTBEAT_ACK_MAX_CHARS) return 'heartbeat ack'
   }
@@ -226,6 +226,7 @@ export function registerOfflinePush(api: PluginApi) {
 
       // Extract full assistant text for filtering and preview.
       const fullText = getLastAssistantText(event.messages)
+      const triggerText = getTriggeringUserText(event.messages)
 
       // Skip if the message would be filtered by the mobile UI.
       if (fullText != null) {
@@ -270,6 +271,33 @@ export function registerOfflinePush(api: PluginApi) {
         return
       }
 
+      // Defensive: if we can't extract assistant text, sending a generic
+      // "Your response is ready" is never useful — the message likely wasn't
+      // persisted to the transcript either, so the user opens the app to nothing.
+      // Log the messages structure for debugging, then bail.
+      if (fullText == null || fullText === '') {
+        const msgCount = Array.isArray(event.messages) ? event.messages.length : 'n/a'
+        const lastRoles = Array.isArray(event.messages)
+          ? event.messages
+              .slice(-5)
+              .map(
+                (m: any) =>
+                  `${m?.role ?? '?'}(${typeof m?.content === 'string' ? 'str' : Array.isArray(m?.content) ? `parts:${m.content.length}` : typeof m?.content})`,
+              )
+              .join(', ')
+          : 'n/a'
+        api.logger.warn(
+          `offline-push: skipped (no extractable assistant text) msgCount=${msgCount} lastRoles=[${lastRoles}] triggerText=${triggerText ? `"${triggerText.slice(0, 80)}"` : 'null'}`,
+        )
+        if (isCron) markCronPushSkipped(sessionKey!, 'no extractable text', false)
+        captureEvent('push.skipped', {
+          reason: 'no_extractable_text',
+          is_cron: isCron,
+          ...(sessionKey ? {session_key: sessionKey} : {}),
+        })
+        return
+      }
+
       // Only send push for the main clawly mobile session and cron sessions —
       // skip channel sessions (telegram, slack, discord, etc.) which have their own delivery.
       if (sessionKey !== undefined && sessionKey !== 'agent:clawly:main' && !isCron) {
@@ -280,12 +308,12 @@ export function registerOfflinePush(api: PluginApi) {
       const noHeartbeat =
         (() => {
           if (!fullText) return null
-          const atEnd = /HEARTBEAT_OK[\p{P}\s]*$/u.test(fullText)
-          const atStart = /^[\p{P}\s]*HEARTBEAT_OK/u.test(fullText)
+          const atEnd = /HEARTBEAT[_ ]OK[\p{P}\s]*$/u.test(fullText)
+          const atStart = /^[\p{P}\s]*HEARTBEAT[_ ]OK/u.test(fullText)
           if (!atEnd && !atStart) return fullText.trim()
           let s = fullText
-          if (atEnd) s = s.replace(/HEARTBEAT_OK[\p{P}\s]*$/u, '')
-          if (atStart) s = s.replace(/^[\p{P}\s]*HEARTBEAT_OK[\p{P}\s]*/u, '')
+          if (atEnd) s = s.replace(/HEARTBEAT[_ ]OK[\p{P}\s]*$/u, '')
+          if (atStart) s = s.replace(/^[\p{P}\s]*HEARTBEAT[_ ]OK[\p{P}\s]*/u, '')
           return s.trim()
         })() ?? null
       const cleaned = noHeartbeat ? stripPlaceholders(noHeartbeat) : null

package/gateway/presence.ts

@@ -27,14 +27,17 @@ export function isOnlineEntry(entry: PresenceEntry | undefined): boolean {
 }
 
 /**
- * Shells out to `openclaw gateway call system-presence` and checks
- * whether ANY device has a foreground presence entry.
+ * Shells out to `openclaw gateway call system-presence` and returns true
+ * if any device has a `foreground` presence entry.
+ *
+ * False-negatives (beacon lapsed) are handled client-side — the mobile
+ * app suppresses `agent_end` notifications while in the foreground.
  */
 export async function isClientOnline(): Promise<boolean> {
   try {
     const result = await $`openclaw gateway call system-presence --json`
-    const jsonStr = stripCliLogs(result.stdout)
-    const entries: PresenceEntry[] = JSON.parse(jsonStr)
+    const parsed: unknown = JSON.parse(stripCliLogs(result.stdout))
+    const entries: PresenceEntry[] = Array.isArray(parsed) ? parsed : []
     return entries.some(isOnlineEntry)
   } catch {
     return false

package/gateway-fetch.ts

@@ -11,11 +11,18 @@ export type HandlerResult = {ok: boolean; data?: unknown; error?: {code: string;
 export function getGatewayConfig(api: PluginApi): GatewayCfg {
   const cfg = api.pluginConfig && typeof api.pluginConfig === 'object' ? api.pluginConfig : {}
   const c = cfg as Record<string, unknown>
-  const baseUrl =
-    typeof c.skillGatewayBaseUrl === 'string'
-      ? (c.skillGatewayBaseUrl as string).replace(/\/$/, '')
-      : ''
-  const token = typeof c.skillGatewayToken === 'string' ? (c.skillGatewayToken as string) : ''
+
+  // URL: prefer clawlyApiBaseUrl, fall back to deprecated skillGatewayBaseUrl
+  const rawUrl =
+    (typeof c.clawlyApiBaseUrl === 'string' ? (c.clawlyApiBaseUrl as string) : '') ||
+    (typeof c.skillGatewayBaseUrl === 'string' ? (c.skillGatewayBaseUrl as string) : '')
+  const baseUrl = rawUrl.replace(/\/$/, '')
+
+  // Token: prefer modelGatewayToken, fall back to deprecated skillGatewayToken
+  const token =
+    (typeof c.modelGatewayToken === 'string' ? (c.modelGatewayToken as string) : '') ||
+    (typeof c.skillGatewayToken === 'string' ? (c.skillGatewayToken as string) : '')
+
   return {baseUrl, token}
 }
 

package/index.ts

@@ -17,7 +17,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_image        — send an image to the user (URL download or local file)
+ * - clawly_send_file         — send a file to the user (URL or local path under $HOME/tmp)
  * - clawly_search             — web search via Perplexity (replaces denied web_search)
  * - clawly_send_message      — send a message to user via main session agent (supports role: user|assistant)
  *
@@ -80,7 +80,7 @@ export default {
     registerAutoPair(api)
     registerAutoUpdate(api)
 
-    // Email & calendar (optional — requires skillGatewayBaseUrl + skillGatewayToken in config)
+    // Email & calendar (optional — requires API base URL + token)
     const gw = getGatewayConfig(api)
     if (gw.baseUrl && gw.token) {
       registerEmail(api, gw)

package/lib/calendar-cache.ts

@@ -23,6 +23,9 @@ export interface NativeCalendar {
   type: string
 }
 
+export type AlarmMethod = 'alarm' | 'alert' | 'email' | 'default' | 'sms'
+export type AlarmInput = {relativeOffset?: number; method?: AlarmMethod}
+
 export interface NativeCalendarEvent {
   id: string
   calendarId: string
@@ -35,6 +38,7 @@ export interface NativeCalendarEvent {
   url: string
   timeZone: string
   organizer: string
+  alarms?: AlarmInput[]
 }
 
 export interface CalendarCache {
@@ -105,7 +109,12 @@ export function initCache(): void {
 }
 
 export function getCache(): CalendarCache | null {
-  if (!cachedData) cachedData = loadCache()
+  // Always read from disk to avoid returning stale in-memory state.
+  // After gateway restart or ESM/CJS dual-loading, gateway methods and
+  // agent tools may hold separate module instances with divergent
+  // cachedData. Disk is the shared source of truth. The file is small
+  // (<10 KB) and tool calls are infrequent, so the I/O cost is negligible.
+  cachedData = loadCache()
   return cachedData
 }
 

package/model-gateway-setup.ts

@@ -10,6 +10,7 @@
  */
 
 import fs from 'node:fs'
+import path from 'node:path'
 
 import type {PluginApi} from './index'
 import type {OpenClawConfig} from './types/openclaw'
@@ -67,3 +68,48 @@ export function patchModelGateway(config: OpenClawConfig, _api: PluginApi): bool
 
   return dirty
 }
+
+// ---------------------------------------------------------------------------
+// backfillDiskConfig — merge setupConfig's disk writes into a loadConfig() result
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+/**
+ * Deep-merge `source` into `target`, where source wins for any key it has.
+ * Arrays and primitives from source overwrite target.
+ * Plain objects recurse.
+ */
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    if (key === '$include') continue // meta-directive, not a resolved config field
+    const sv = source[key]
+    const tv = target[key]
+    if (isPlainObject(sv) && isPlainObject(tv)) {
+      deepMerge(tv, sv)
+    } else {
+      target[key] = sv
+    }
+  }
+}
+
+/**
+ * Read the raw disk config (openclaw.json) and deep-merge its fields into a
+ * runtime config snapshot (from `loadConfig()`). This ensures that fields
+ * written by `setupConfig` (which writes directly to disk) are present in the
+ * config object before it's passed to `writeConfigFile`.
+ *
+ * Without this, `writeConfigFile`'s inner merge-patch sees the stale runtime
+ * snapshot (missing setupConfig's changes) and reverts them on disk.
+ */
+export function backfillDiskConfig(stateDir: string, config: OpenClawConfig): OpenClawConfig {
+  const configPath = path.join(stateDir, 'openclaw.json')
+  const diskConfig = readOpenclawConfig(configPath)
+  // Start from disk (setupConfig's fields) then overlay config (RPC handler's
+  // changes) so the caller's modifications win over stale disk values.
+  const merged = {...diskConfig} as Record<string, unknown>
+  deepMerge(merged, config as Record<string, unknown>)
+  return merged as OpenClawConfig
+}

package/openclaw.plugin.json

@@ -47,6 +47,7 @@
       "defaultNoInput": { "type": "boolean" },
       "defaultTimeoutMs": { "type": "number", "minimum": 1000 },
       "configPath": { "type": "string" },
+      "clawlyApiBaseUrl": { "type": "string" },
       "skillGatewayBaseUrl": { "type": "string" },
       "skillGatewayToken": { "type": "string" },
       "modelGatewayBaseUrl": { "type": "string" },