@better_openclaw/betterclaw 1.4.0 → 2.0.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/banner.png" alt="BetterClaw" width="100%" />
+  <img src="banner.png" alt="BetterClaw" width="100%" />
 </p>
 
 <p align="center">
@@ -17,9 +17,9 @@
 
 ## What is this?
 
-This is the server-side plugin for [BetterClaw](https://github.com/BetterClaw-app/BetterClaw-ios), an iOS app that connects your iPhone's sensors to your [OpenClaw](https://openclaw.dev) AI agent. The app streams device events (location, battery, health, geofences) to your gateway — this plugin decides what to do with them.
+This is the server-side plugin for [BetterClaw](https://betterclaw.app), an iOS app that connects your iPhone's sensors to your [OpenClaw](https://openclaw.dev) AI agent. The app streams device events (location, battery, health, geofences) to your gateway — this plugin decides what to do with them.
 
-Without this plugin, raw events go straight to your agent. With it, they're filtered, triaged, and enriched before anything reaches your agent's conversation.
+The plugin is the **sole event gateway** for all tiers. Smart mode controls filtering depth: OFF = passive context store, ON = full pipeline with rules, LLM triage, and proactive insights.
 
 ```
   BetterClaw iOS App          This Plugin (on gateway)              Agent
@@ -28,7 +28,7 @@ Without this plugin, raw events go straight to your agent. With it, they're filt
   battery ──────▶  ┌───────────────────┼───────────────────┐
   location ─────▶  │  Rules Engine     │  Context Store     │
   health ───────▶  │  LLM Triage       │  Pattern Engine    │ ──▶  filtered events
-  geofence ─────▶  │  Budget Limiter   │  Proactive Triggers│      + full context
+  geofence ─────▶  │  Daily Learner    │  Proactive Triggers│      + full context
                    └───────────────────┼───────────────────┘
                                        │
                                  proactive insights
@@ -38,12 +38,15 @@ Without this plugin, raw events go straight to your agent. With it, they're filt
 
 ## Features
 
-- **Smart Filtering** — Per-source dedup, cooldown windows, and a daily push budget prevent event spam
-- **LLM Triage** — Ambiguous events get a cheap LLM call to decide push vs. suppress, keeping the expensive agent focused
-- **Device Context** — Rolling state snapshot: battery, GPS, zone occupancy, health metrics, activity classification
-- **Pattern Recognition** — Computes location routines, health trends (7d/30d baselines), and event stats every 6 hours
+- **Tier-Aware Smart Mode** — Smart mode ON = full pipeline (rules → triage → push). Smart mode OFF = passive store (context updated, no filtering or pushing). Synced via periodic heartbeat from iOS.
+- **Two-Layer LLM Triage** — Daily learner builds a personalized triage profile from OpenClaw memory summaries + event reactions. Per-event cheap LLM call with structured output for ambiguous events.
+- **Smart Filtering** — Per-source dedup, cooldown windows, and a configurable daily push budget prevent event spam
+- **Device Context** — Rolling state snapshot with per-field timestamps: battery, GPS, zone occupancy, health metrics, activity classification
+- **Pattern Recognition** — Daily analysis computes location routines, health trends (7d/30d baselines), and event frequency stats
 - **Proactive Insights** — Combined-signal triggers: low battery away from home, unusual inactivity, sleep deficit, routine deviations, weekly digest
-- **Agent Tool** — `get_context` tool lets your agent read the full device snapshot on demand
+- **Per-Device Config** — iOS app can override push budget and proactive settings at runtime via RPC
+- **Agent Tool** — `get_context` tool lets your agent read the full device snapshot, tier, smart mode status, and triage profile on demand
+- **CLI Setup** — `openclaw betterclaw setup` configures gateway allowedCommands automatically
 
 ## Requirements
 
@@ -54,6 +57,7 @@ Without this plugin, raw events go straight to your agent. With it, they're filt
 
 ```bash
 openclaw plugins install @betterclaw-app/betterclaw
+openclaw betterclaw setup   # configures gateway allowedCommands
 ```
 
 ## Configure
@@ -67,10 +71,11 @@ Add to your `openclaw.json`:
       "betterclaw": {
         "enabled": true,
         "config": {
-          "llmModel": "openai/gpt-4o-mini",
+          "triageModel": "openai/gpt-4o-mini",
           "pushBudgetPerDay": 10,
           "patternWindowDays": 14,
-          "proactiveEnabled": true
+          "proactiveEnabled": true,
+          "analysisHour": 5
         }
       }
     }
@@ -84,29 +89,41 @@ All config keys are optional — defaults are shown above.
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `llmModel` | `openai/gpt-4o-mini` | Model used for ambiguous event triage |
+| `triageModel` | `openai/gpt-4o-mini` | Model for per-event triage (supports `provider/model` format) |
+| `triageApiBase` | — | Optional base URL for OpenAI-compatible endpoint (e.g., Ollama) |
 | `pushBudgetPerDay` | `10` | Max events forwarded to the agent per day |
 | `patternWindowDays` | `14` | Days of event history used for pattern computation |
 | `proactiveEnabled` | `true` | Enable proactive combined-signal insights |
+| `analysisHour` | `5` | Hour (0-23, system timezone) for daily pattern + learner analysis |
+
+> **Migration:** `llmModel` still works as a deprecated alias for `triageModel`.
 
 ## How It Works
 
 ### Event Pipeline
 
-Every device event from the BetterClaw app goes through a multi-stage pipeline before reaching your agent:
+Every device event from the BetterClaw app goes through the plugin:
 
-1. **Rules Engine** — Checks dedup, cooldown timers, and daily budget. Obvious spam is dropped immediately.
-2. **LLM Triage** — Events that aren't clearly push or suppress get a fast LLM call with device context for a judgment call.
-3. **Context Update** — The device context store is updated with the latest sensor data regardless of whether the event is forwarded.
-4. **Event Logging** — Every event and its decision (push/suppress/defer) is logged for pattern computation.
+1. **Context Update** — Device context store is always updated with the latest sensor data.
+2. **Smart Mode Check** — If smart mode is OFF, the event is stored and processing stops. If ON, continues.
+3. **Rules Engine** — Checks dedup, cooldown timers, and daily budget. Critical events (geofence, low battery) always push. Obvious spam is dropped.
+4. **LLM Triage** — Ambiguous events get a cheap LLM call with the personalized triage profile for a push/drop decision.
 5. **Agent Injection** — Events that pass are injected into the agent's main session with formatted context.
 
 ### Background Services
 
-Two engines run on a schedule in the background:
+- **Pattern Engine + Daily Learner** (daily at `analysisHour`) — Computes location routines, health trends, event stats. Then runs a subagent turn to build a personalized triage profile from OpenClaw memory summaries and notification reaction data.
+- **Proactive Engine** (hourly) — Evaluates combined-signal conditions and fires insights when thresholds are met.
+
+### Gateway RPCs
 
-- **Pattern Engine** (every 6h) — Analyzes event history to compute location routines, health trends, and event frequency stats
-- **Proactive Engine** (every 30min) — Evaluates combined-signal conditions and fires insights when thresholds are met
+| RPC | Direction | Purpose |
+|-----|-----------|---------|
+| `betterclaw.event` | iOS → plugin | Send a device event for processing |
+| `betterclaw.ping` | iOS → plugin | Heartbeat: sync tier + smartMode, get budget info |
+| `betterclaw.config` | iOS → plugin | Per-device settings override |
+| `betterclaw.context` | iOS → plugin | Full context for iOS Context tab |
+| `betterclaw.snapshot` | iOS → plugin | Bulk device state catch-up |
 
 ## Commands
 
@@ -118,7 +135,8 @@ Two engines run on a schedule in the background:
 
 | Plugin | BetterClaw iOS | OpenClaw |
 |--------|----------------|----------|
-| 1.x    | 1.x+           | 2025.12+ |
+| 2.x    | 2.x+           | 2025.12+ |
+| 1.x    | 1.x            | 2025.12+ |
 
 ## License
 

package/openclaw.plugin.json

@@ -1,34 +1,55 @@
 {
   "id": "betterclaw",
-  "name": "BetterClaw Context",
-  "description": "Intelligent context layer for BetterClaw iOS companion app",
-  "version": "1.0.3",
+  "name": "BetterClaw",
+  "description": "Intelligent device context, event filtering, and proactive insights for BetterClaw iOS",
+  "version": "2.0.0",
+  "main": "dist/index.js",
   "skills": ["./skills/betterclaw"],
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
     "properties": {
+      "triageModel": {
+        "type": "string",
+        "default": "openai/gpt-4o-mini",
+        "description": "Model for per-event triage (accepts llmModel as deprecated alias)"
+      },
       "llmModel": {
         "type": "string",
-        "default": "openai/gpt-4o-mini"
+        "description": "Deprecated — use triageModel instead"
+      },
+      "triageApiBase": {
+        "type": "string",
+        "description": "Optional base URL for OpenAI-compatible triage endpoint (e.g. http://localhost:11434/v1 for Ollama)"
       },
       "pushBudgetPerDay": {
         "type": "number",
-        "default": 10
+        "default": 10,
+        "description": "Max events forwarded to agent per day"
       },
       "patternWindowDays": {
         "type": "number",
-        "default": 14
+        "default": 14,
+        "description": "Days of event history for pattern computation"
       },
       "proactiveEnabled": {
         "type": "boolean",
-        "default": true
+        "default": true,
+        "description": "Enable proactive combined-signal insights"
+      },
+      "analysisHour": {
+        "type": "number",
+        "default": 5,
+        "minimum": 0,
+        "maximum": 23,
+        "description": "Hour (system timezone) for daily analysis run"
       }
-    }
+    },
+    "additionalProperties": false
   },
   "uiHints": {
-    "llmModel": { "label": "Triage LLM Model", "placeholder": "openai/gpt-4o-mini" },
-    "pushBudgetPerDay": { "label": "Max pushes per day" },
-    "proactiveEnabled": { "label": "Enable proactive insights" }
+    "triageModel": { "label": "Triage Model", "placeholder": "openai/gpt-4o-mini" },
+    "pushBudgetPerDay": { "label": "Push Budget / Day", "type": "number" },
+    "proactiveEnabled": { "label": "Proactive Insights", "type": "boolean" },
+    "analysisHour": { "label": "Analysis Hour (0-23)", "type": "number" }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better_openclaw/betterclaw",
-  "version": "1.4.0",
+  "version": "2.0.1",
   "description": "Intelligent event filtering, context tracking, and proactive triggers for BetterClaw",
   "license": "AGPL-3.0-only",
   "repository": {

package/skills/betterclaw/SKILL.md

@@ -9,23 +9,24 @@ You have access to the user's physical device state via BetterClaw (iOS companio
 
 ## Capabilities
 
-- **Real-time sensors**: battery level/state, GPS location, health metrics (steps, heart rate, HRV, sleep, distance, energy)
+- **Sensors**: battery level/state, GPS location, health metrics (steps, heart rate, HRV, sleep, distance, energy)
 - **Geofence events**: enter/exit named zones (Home, Office, etc.)
 - **Patterns**: location routines, health trends (7d/30d), battery drain rate
 - **Tool**: `get_context` — call anytime to read the full current device snapshot and derived patterns
 
-## Event Messages
+## Adaptive Behavior
 
-You'll receive two types of automated messages:
+Check `get_context().smartMode` and `get_context().tier` to understand your data flow:
 
-- **Device events** — prefixed with `[BetterClaw device event]`. These are real sensor events that passed the plugin's filtering pipeline. They include relevant context.
-- **Proactive insights** — prefixed with `[BetterClaw proactive insight]`. These are combined-signal analyses (e.g., low battery + away from home, unusual inactivity, sleep deficit).
+- **Smart mode ON**: Device events are being pushed to you automatically, pre-filtered for relevance. If you receive one, it's worth acknowledging.
+- **Smart mode OFF**: No events are pushed automatically. Call `get_context` when the user asks about their physical state (battery, location, health, activity) or when physical context would improve your response.
+
+Check `get_context().triageProfile.summary` for a description of the user's notification preferences.
 
 ## Guidelines
 
-- Events are pre-filtered for relevance. If you receive one, it's likely worth acknowledging.
-- Use `get_context` proactively when physical context would improve your response (weather questions, schedule planning, health discussions).
+- Use `get_context` when physical context would improve your response — don't rely on stale data.
 - Don't parrot raw data. Synthesize naturally: "You're running low and away from home" not "Battery: 0.15, location label: null".
-- Proactive insights are observations, not commands. Use your judgment about whether to relay them to the user.
-- When the user asks about their health, location, battery, or activity — call `get_context` first rather than relying on stale event data.
-- Respond with `no_reply` for routine events that don't need user attention (e.g., geofence enter at expected time).
+- Proactive insights are observations, not commands. Use your judgment about whether to relay them.
+- Respond with `no_reply` for routine events that don't need user attention.
+- Check timestamps (`updatedAt`, `computedAt`) to assess data freshness.

package/src/cli.ts

@@ -0,0 +1,29 @@
+export const BETTERCLAW_COMMANDS = [
+  "clipboard.write",
+  "device.battery",
+  "geofence.add",
+  "geofence.list",
+  "geofence.remove",
+  "health.distance",
+  "health.heartrate",
+  "health.hrv",
+  "health.restinghr",
+  "health.sleep",
+  "health.steps",
+  "health.summary",
+  "health.workouts",
+  "location.get",
+  "shortcuts.run",
+  "subscribe.add",
+  "subscribe.list",
+  "subscribe.pause",
+  "subscribe.remove",
+  "subscribe.resume",
+  "system.capabilities",
+  "system.notify",
+].sort();
+
+export function mergeAllowCommands(existing: string[], toAdd: string[]): string[] {
+  const set = new Set([...existing, ...toAdd]);
+  return [...set].sort();
+}

package/src/context.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { DeviceContext, DeviceEvent, Patterns } from "./types.js";
+import type { DeviceConfig, DeviceContext, DeviceEvent, Patterns, RuntimeState } from "./types.js";
 
 const CONTEXT_FILE = "context.json";
 const PATTERNS_FILE = "patterns.json";
@@ -9,6 +9,9 @@ export class ContextManager {
   private contextPath: string;
   private patternsPath: string;
   private context: DeviceContext;
+  private runtimeState: RuntimeState = { tier: "free", smartMode: false };
+  private timestamps: Record<string, number> = {};
+  private deviceConfig: DeviceConfig = {};
 
   constructor(stateDir: string) {
     this.contextPath = path.join(stateDir, CONTEXT_FILE);
@@ -38,9 +41,20 @@ export class ContextManager {
   async load(): Promise<void> {
     try {
       const raw = await fs.readFile(this.contextPath, "utf8");
-      this.context = JSON.parse(raw) as DeviceContext;
+      const parsed = JSON.parse(raw);
+      this.timestamps = parsed._timestamps ?? {};
+      delete parsed._timestamps;
+      this.context = parsed as DeviceContext;
     } catch {
       this.context = ContextManager.empty();
+      this.timestamps = {};
+    }
+    try {
+      const configPath = path.join(path.dirname(this.contextPath), "device-config.json");
+      const rawConfig = await fs.readFile(configPath, "utf8");
+      this.deviceConfig = JSON.parse(rawConfig) as DeviceConfig;
+    } catch {
+      this.deviceConfig = {};
     }
   }
 
@@ -48,18 +62,27 @@ export class ContextManager {
     return this.context;
   }
 
+  getTimestamp(field: string): number | undefined {
+    return this.timestamps[field];
+  }
+
   async save(): Promise<void> {
     await fs.mkdir(path.dirname(this.contextPath), { recursive: true });
-    await fs.writeFile(this.contextPath, JSON.stringify(this.context, null, 2) + "\n", "utf8");
+    const data = { ...this.context, _timestamps: this.timestamps };
+    await fs.writeFile(this.contextPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    const configPath = path.join(path.dirname(this.contextPath), "device-config.json");
+    await fs.writeFile(configPath, JSON.stringify(this.deviceConfig, null, 2) + "\n", "utf8");
   }
 
   updateFromEvent(event: DeviceEvent): void {
     const now = event.firedAt;
     const data = event.data;
 
-    // Reset daily counters at midnight UTC
-    const lastDay = Math.floor(this.context.meta.lastEventAt / 86400);
-    const currentDay = Math.floor(now / 86400);
+    // Reset daily counters at local midnight
+    const lastDate = new Date(this.context.meta.lastEventAt * 1000);
+    const currentDate = new Date(now * 1000);
+    const lastDay = `${lastDate.getFullYear()}-${lastDate.getMonth()}-${lastDate.getDate()}`;
+    const currentDay = `${currentDate.getFullYear()}-${currentDate.getMonth()}-${currentDate.getDate()}`;
     if (lastDay !== currentDay && this.context.meta.lastEventAt > 0) {
       this.context.meta.eventsToday = 0;
       this.context.meta.pushesToday = 0;
@@ -76,6 +99,7 @@ export class ContextManager {
           isLowPowerMode: (data.isLowPowerMode ?? 0) === 1,
           updatedAt: data.updatedAt ?? now,
         };
+        this.timestamps.battery = event.firedAt;
         break;
 
       case "geofence.triggered": {
@@ -112,6 +136,8 @@ export class ContextManager {
           label: this.context.activity.currentZone,
           updatedAt: data.timestamp ?? now,
         };
+        this.timestamps.location = event.firedAt;
+        this.timestamps.activity = event.firedAt;
         break;
       }
 
@@ -127,6 +153,7 @@ export class ContextManager {
             sleepDurationSeconds: data.sleepDurationSeconds ?? this.context.device.health?.sleepDurationSeconds ?? null,
             updatedAt: data.updatedAt ?? now,
           };
+          this.timestamps.health = event.firedAt;
         }
         break;
     }
@@ -141,8 +168,8 @@ export class ContextManager {
       sleepDurationSeconds?: number;
     };
     geofence?: { type: string; zoneName: string; latitude: number; longitude: number };
-  }): void {
-    const now = Date.now() / 1000;
+  }, timestamp?: number): void {
+    const now = timestamp ?? Date.now() / 1000;
 
     if (snapshot.battery) {
       this.context.device.battery = {
@@ -151,6 +178,7 @@ export class ContextManager {
         isLowPowerMode: snapshot.battery.isLowPowerMode,
         updatedAt: now,
       };
+      this.timestamps.battery = now;
     }
 
     if (snapshot.location) {
@@ -161,6 +189,7 @@ export class ContextManager {
         label: this.context.activity.currentZone,
         updatedAt: now,
       };
+      this.timestamps.location = now;
     }
 
     if (snapshot.health) {
@@ -174,6 +203,7 @@ export class ContextManager {
         sleepDurationSeconds: snapshot.health.sleepDurationSeconds ?? null,
         updatedAt: now,
       };
+      this.timestamps.health = now;
     }
 
     if (snapshot.geofence) {
@@ -196,6 +226,24 @@ export class ContextManager {
         this.context.device.location.label = this.context.activity.currentZone;
       }
     }
+
+    this.timestamps.lastSnapshot = now;
+  }
+
+  getRuntimeState(): RuntimeState {
+    return { ...this.runtimeState };
+  }
+
+  setRuntimeState(state: RuntimeState): void {
+    this.runtimeState = { ...state };
+  }
+
+  getDeviceConfig(): DeviceConfig {
+    return { ...this.deviceConfig };
+  }
+
+  setDeviceConfig(update: DeviceConfig): void {
+    this.deviceConfig = { ...this.deviceConfig, ...update };
   }
 
   recordPush(): void {

package/src/events.ts

@@ -26,7 +26,10 @@ export class EventLog {
         .trim()
         .split("\n")
         .filter((line) => line.length > 0)
-        .map((line) => JSON.parse(line) as EventLogEntry);
+        .flatMap((line) => {
+          try { return [JSON.parse(line) as EventLogEntry]; }
+          catch { return []; }
+        });
     } catch {
       return [];
     }
@@ -51,7 +54,9 @@ export class EventLog {
     const removed = entries.length - kept.length;
 
     const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
-    await fs.writeFile(this.filePath, content, "utf8");
+    const tmpPath = this.filePath + ".tmp";
+    await fs.writeFile(tmpPath, content, "utf8");
+    await fs.rename(tmpPath, this.filePath);
 
     return removed;
   }

package/src/filter.ts

@@ -18,7 +18,7 @@ export class RulesEngine {
     this.pushBudget = pushBudget;
   }
 
-  evaluate(event: DeviceEvent, context: DeviceContext): FilterDecision {
+  evaluate(event: DeviceEvent, context: DeviceContext, budgetOverride?: number): FilterDecision {
     // Debug events always pass
     if (event.data._debugFired === 1.0) {
       return { action: "push", reason: "debug event — always push" };
@@ -65,12 +65,13 @@ export class RulesEngine {
       if (hour >= 6 && hour <= 10) {
         return { action: "push", reason: "daily health summary — within morning window" };
       }
-      return { action: "defer", reason: "daily health summary — outside morning window" };
+      return { action: "drop", reason: "daily health summary — outside morning window" };
     }
 
     // Push budget check
-    if (context.meta.pushesToday >= this.pushBudget) {
-      return { action: "drop", reason: `push budget exhausted (${context.meta.pushesToday}/${this.pushBudget} today)` };
+    const budget = budgetOverride ?? this.pushBudget;
+    if (context.meta.pushesToday >= budget) {
+      return { action: "drop", reason: `push budget exhausted (${context.meta.pushesToday}/${budget} today)` };
     }
 
     // Anything else is ambiguous — forward to LLM judgment