@better_openclaw/betterclaw 1.4.0 → 2.0.0

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.0",
   "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