@better_openclaw/betterclaw 1.4.0

package/src/pipeline.ts

@@ -0,0 +1,169 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { ContextManager } from "./context.js";
+import type { EventLog } from "./events.js";
+import type { RulesEngine } from "./filter.js";
+import type { JudgmentLayer } from "./judgment.js";
+import type { DeviceEvent, DeviceContext, PluginConfig } from "./types.js";
+
+export interface PipelineDeps {
+  api: OpenClawPluginApi;
+  config: PluginConfig;
+  context: ContextManager;
+  events: EventLog;
+  rules: RulesEngine;
+  judgment: JudgmentLayer;
+}
+
+export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Promise<void> {
+  const { api, config, context, events, rules, judgment } = deps;
+
+  // Always update context
+  context.updateFromEvent(event);
+
+  // Run rules engine
+  let decision = rules.evaluate(event, context.get());
+
+  // If ambiguous, run LLM judgment
+  if (decision.action === "ambiguous") {
+    const result = await judgment.evaluate(event, context.get());
+    decision = result.push
+      ? { action: "push" as const, reason: `llm: ${result.reason}` }
+      : { action: "drop" as const, reason: `llm: ${result.reason}` };
+  }
+
+  // Log the event + decision
+  await events.append({
+    event,
+    decision: decision.action === "push" ? "push" : decision.action === "defer" ? "defer" : "drop",
+    reason: decision.reason,
+    timestamp: Date.now() / 1000,
+  });
+
+  // If push, inject into agent session
+  if (decision.action === "push") {
+    rules.recordFired(event.subscriptionId, event.firedAt);
+    context.recordPush();
+
+    // If the iOS tunnel already pushed this event directly to the agent
+    // session (always-push events like geofence/battery-critical), skip
+    // delivery to avoid double-sending. Context was already updated above.
+    if (event.data._alreadyPushed === 1.0) {
+      api.logger.info(`betterclaw: skipped push for ${event.subscriptionId} (already pushed by tunnel)`);
+    } else {
+      const message = formatEnrichedMessage(event, context);
+
+      try {
+        await api.runtime.subagent.run({
+          sessionKey: "main",
+          message,
+          deliver: true,
+          idempotencyKey: `event-${event.subscriptionId}-${Math.floor(event.firedAt)}`,
+        });
+
+        api.logger.info(`betterclaw: pushed event ${event.subscriptionId} to agent`);
+      } catch (err) {
+        api.logger.error(
+          `betterclaw: failed to push to agent: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  } else {
+    api.logger.info(`betterclaw: ${decision.action} event ${event.subscriptionId}: ${decision.reason}`);
+  }
+
+  // Persist context
+  await context.save();
+}
+
+function formatEnrichedMessage(event: DeviceEvent, context: ContextManager): string {
+  const state = context.get();
+  const body = formatEventBody(event);
+  const contextSummary = formatContextSummary(state);
+
+  const prefix =
+    event.data._debugFired === 1.0
+      ? "[DEBUG test event fired manually from BetterClaw iOS debug menu — not a real device event. You MUST respond to confirm the pipeline is working.]"
+      : "[BetterClaw device event — processed by context plugin]";
+
+  return `${prefix}\n\n${body}\n\nCurrent context: ${contextSummary}`;
+}
+
+function formatEventBody(event: DeviceEvent): string {
+  const data = event.data;
+  const id = event.subscriptionId;
+
+  switch (id) {
+    case "default.battery-low": {
+      const level = data.level != null ? Math.round(data.level * 100) : "?";
+      return `🔋 Battery at ${level}% (threshold: <20%)`;
+    }
+    case "default.battery-critical": {
+      const level = data.level != null ? Math.round(data.level * 100) : "?";
+      return `🪫 Battery at ${level}% (threshold: <10%)`;
+    }
+    case "default.daily-health": {
+      const parts: string[] = [];
+      if (data.stepsToday != null) parts.push(`Steps: ${Math.round(data.stepsToday).toLocaleString()}`);
+      if (data.distanceMeters != null) parts.push(`Distance: ${(data.distanceMeters / 1000).toFixed(1)}km`);
+      if (data.heartRateAvg != null) parts.push(`Avg HR: ${Math.round(data.heartRateAvg)}bpm`);
+      if (data.sleepDurationSeconds != null) {
+        const h = Math.floor(data.sleepDurationSeconds / 3600);
+        const m = Math.floor((data.sleepDurationSeconds % 3600) / 60);
+        parts.push(`Sleep: ${h}h ${m}m`);
+      }
+      const summary = parts.length ? parts.join(" | ") : "No data";
+      return `🏥 Daily health summary — ${summary}`;
+    }
+    default: {
+      if (event.source === "geofence.triggered") {
+        const type = data.type === 1 ? "enter" : "exit";
+        const emoji = type === "enter" ? "📍" : "🚶";
+        const zone = event.metadata?.zoneName;
+        return zone
+          ? `${emoji} Geofence ${type}: ${zone}`
+          : `${emoji} Geofence ${type}`;
+      }
+      if (event.source.startsWith("health")) {
+        const pairs = Object.entries(data)
+          .filter(([k]) => k !== "_debugFired" && k !== "updatedAt")
+          .map(([k, v]) => `${k}: ${v}`)
+          .join(", ");
+        return `🏥 Health event — ${pairs}`;
+      }
+      const pairs = Object.entries(data)
+        .filter(([k]) => k !== "_debugFired")
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ");
+      return `📡 ${event.source} — ${pairs}`;
+    }
+  }
+}
+
+function formatContextSummary(state: DeviceContext): string {
+  const parts: string[] = [];
+
+  if (state.activity.currentZone) {
+    const since = state.activity.zoneEnteredAt
+      ? `since ${formatDuration(Date.now() / 1000 - state.activity.zoneEnteredAt)}`
+      : "";
+    parts.push(`At ${state.activity.currentZone} ${since}`.trim());
+  }
+
+  if (state.device.health?.stepsToday) {
+    parts.push(`${Math.round(state.device.health.stepsToday).toLocaleString()} steps today`);
+  }
+
+  if (state.device.battery) {
+    parts.push(`Battery ${Math.round(state.device.battery.level * 100)}% (${state.device.battery.state})`);
+  }
+
+  return parts.length ? parts.join(". ") + "." : "No context available.";
+}
+
+function formatDuration(seconds: number): string {
+  if (seconds < 60) return "<1m";
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.round((seconds % 3600) / 60);
+  return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}

package/src/tools/get-context.ts

@@ -0,0 +1,37 @@
+import { Type } from "@sinclair/typebox";
+import type { ContextManager } from "../context.js";
+
+export function createGetContextTool(ctx: ContextManager) {
+  return {
+    name: "get_context",
+    label: "Get Device Context",
+    description:
+      "Get the current physical context of the user's iPhone — battery, location, health metrics, activity zone, patterns, and trends. Call this when you need to know about the user's physical state.",
+    parameters: Type.Object({
+      include: Type.Optional(
+        Type.Array(Type.String(), {
+          description: "Sections to include. Omit for all. Options: device, activity, patterns, meta",
+        }),
+      ),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const sections =
+        Array.isArray(params.include) && params.include.every((s) => typeof s === "string")
+          ? (params.include as string[])
+          : ["device", "activity", "patterns", "meta"];
+
+      const state = ctx.get();
+      const patterns = await ctx.readPatterns();
+
+      const result: Record<string, unknown> = {};
+      if (sections.includes("device")) result.device = state.device;
+      if (sections.includes("activity")) result.activity = state.activity;
+      if (sections.includes("patterns") && patterns) result.patterns = patterns;
+      if (sections.includes("meta")) result.meta = state.meta;
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  };
+}

package/src/triggers.ts

@@ -0,0 +1,225 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { ContextManager } from "./context.js";
+import type { DeviceContext, Patterns, PluginConfig } from "./types.js";
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+interface TriggerResult {
+  id: string;
+  message: string;
+  priority: "low" | "normal" | "high";
+}
+
+type TriggerCheck = (ctx: DeviceContext, patterns: Patterns) => TriggerResult | null;
+
+const TRIGGER_COOLDOWNS: Record<string, number> = {
+  "low-battery-away": 4 * 3600,
+  "unusual-inactivity": 6 * 3600,
+  "sleep-deficit": 24 * 3600,
+  "routine-deviation": 4 * 3600,
+  "health-weekly-digest": 7 * 86400,
+};
+
+const triggers: Array<{ id: string; schedule: "hourly" | "daily" | "weekly"; check: TriggerCheck }> = [
+  {
+    id: "low-battery-away",
+    schedule: "hourly",
+    check: (ctx, patterns) => {
+      const battery = ctx.device.battery;
+      if (!battery || battery.level >= 0.3) return null;
+      if (ctx.activity.currentZone === "Home") return null;
+
+      const drain = patterns.batteryPatterns.avgDrainPerHour ?? 0.04;
+      const hoursRemaining = drain > 0 ? Math.round(battery.level / drain) : 0;
+
+      return {
+        id: "low-battery-away",
+        message: `🔋 Battery at ${Math.round(battery.level * 100)}%, draining ~${Math.round(drain * 100)}%/hr. You're away from home — estimated ${hoursRemaining}h remaining. Consider charging.`,
+        priority: battery.level < 0.15 ? "high" : "normal",
+      };
+    },
+  },
+  {
+    id: "unusual-inactivity",
+    schedule: "hourly",
+    check: (ctx, patterns) => {
+      const hour = new Date().getHours();
+      if (hour < 12) return null;
+
+      const steps = ctx.device.health?.stepsToday;
+      const avg = patterns.healthTrends.stepsAvg7d;
+      if (steps == null || avg == null) return null;
+
+      const expectedByNow = avg * (hour / 24);
+      if (steps >= expectedByNow * 0.5) return null;
+
+      return {
+        id: "unusual-inactivity",
+        message: `🚶 It's ${hour}:00 and you've done ${Math.round(steps).toLocaleString()} steps (usually ~${Math.round(expectedByNow).toLocaleString()} by now). Everything okay?`,
+        priority: "low",
+      };
+    },
+  },
+  {
+    id: "sleep-deficit",
+    schedule: "daily",
+    check: (ctx, patterns) => {
+      const hour = new Date().getHours();
+      if (hour < 7 || hour > 10) return null;
+
+      const sleep = ctx.device.health?.sleepDurationSeconds;
+      const avg = patterns.healthTrends.sleepAvg7d;
+      if (sleep == null || avg == null) return null;
+
+      const deficit = avg - sleep;
+      if (deficit < 3600) return null;
+
+      const sleepH = Math.floor(sleep / 3600);
+      const sleepM = Math.round((sleep % 3600) / 60);
+      const avgH = Math.floor(avg / 3600);
+      const avgM = Math.round((avg % 3600) / 60);
+
+      return {
+        id: "sleep-deficit",
+        message: `😴 You slept ${sleepH}h${sleepM}m last night (your average is ${avgH}h${avgM}m). Might want to take it easy today.`,
+        priority: "low",
+      };
+    },
+  },
+  {
+    id: "routine-deviation",
+    schedule: "hourly",
+    check: (ctx, patterns) => {
+      const now = new Date();
+      const day = now.getDay();
+      const isWeekday = day >= 1 && day <= 5;
+      if (!isWeekday) return null;
+
+      const hour = now.getHours() + now.getMinutes() / 60;
+      const routines = patterns.locationRoutines.weekday;
+
+      for (const routine of routines) {
+        if (!routine.typicalLeave) continue;
+        const [h, m] = routine.typicalLeave.split(":").map(Number);
+        const typicalLeaveHour = h + m / 60;
+
+        if (
+          ctx.activity.currentZone === routine.zone &&
+          hour > typicalLeaveHour + 1.5
+        ) {
+          return {
+            id: "routine-deviation",
+            message: `📅 It's ${now.getHours()}:${String(now.getMinutes()).padStart(2, "0")} on ${["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][day]} and you haven't left ${routine.zone} (usually leave at ${routine.typicalLeave}). Just noting in case.`,
+            priority: "low",
+          };
+        }
+      }
+
+      return null;
+    },
+  },
+  {
+    id: "health-weekly-digest",
+    schedule: "weekly",
+    check: (ctx, patterns) => {
+      if (new Date().getDay() !== 0) return null;
+      const hour = new Date().getHours();
+      if (hour < 9 || hour > 11) return null;
+
+      const trends = patterns.healthTrends;
+      const stats = patterns.eventStats;
+
+      const parts: string[] = [];
+      if (trends.stepsAvg7d != null) {
+        const trend = trends.stepsTrend ? ` (${trends.stepsTrend})` : "";
+        parts.push(`Avg steps: ${Math.round(trends.stepsAvg7d).toLocaleString()}/day${trend}`);
+      }
+      if (trends.sleepAvg7d != null) {
+        const h = Math.floor(trends.sleepAvg7d / 3600);
+        const m = Math.round((trends.sleepAvg7d % 3600) / 60);
+        parts.push(`Avg sleep: ${h}h${m}m`);
+      }
+      if (trends.restingHrAvg7d != null) {
+        parts.push(`Resting HR: ${Math.round(trends.restingHrAvg7d)}bpm`);
+      }
+      parts.push(`Events: ${stats.eventsPerDay7d.toFixed(1)}/day, ${Math.round(stats.dropRate7d * 100)}% filtered`);
+
+      return {
+        id: "health-weekly-digest",
+        message: `📊 Weekly health digest\n\n${parts.join("\n")}`,
+        priority: "low",
+      };
+    },
+  },
+];
+
+export class ProactiveEngine {
+  private context: ContextManager;
+  private api: OpenClawPluginApi;
+  private config: PluginConfig;
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(context: ContextManager, api: OpenClawPluginApi, config: PluginConfig) {
+    this.context = context;
+    this.api = api;
+    this.config = config;
+  }
+
+  startSchedule(): void {
+    if (!this.config.proactiveEnabled) return;
+
+    this.interval = setInterval(() => {
+      void this.checkAll().catch((err) => {
+        this.api.logger.error(`betterclaw: proactive check failed: ${err}`);
+      });
+    }, ONE_HOUR_MS);
+    this.interval.unref?.();
+
+    // Run initial check after 5 minutes (let context populate)
+    setTimeout(() => {
+      void this.checkAll().catch(() => {});
+    }, 5 * 60 * 1000).unref?.();
+  }
+
+  stopSchedule(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+
+  async checkAll(): Promise<void> {
+    const ctx = this.context.get();
+    const patterns = (await this.context.readPatterns()) ?? (await import("./patterns.js")).emptyPatterns();
+
+    for (const trigger of triggers) {
+      const lastFired = patterns.triggerCooldowns[trigger.id] ?? 0;
+      const cooldown = TRIGGER_COOLDOWNS[trigger.id] ?? 3600;
+      if (Date.now() / 1000 - lastFired < cooldown) continue;
+
+      const result = trigger.check(ctx, patterns);
+      if (!result) continue;
+
+      this.api.logger.info(`betterclaw: proactive trigger fired: ${trigger.id}`);
+
+      // Write cooldown BEFORE push to prevent runaway retries on failure
+      patterns.triggerCooldowns[trigger.id] = Date.now() / 1000;
+      await this.context.writePatterns(patterns);
+
+      const message = `[BetterClaw proactive insight — combined signal analysis]\n\n${result.message}`;
+
+      try {
+        await this.api.runtime.subagent.run({
+          sessionKey: "main",
+          message,
+          deliver: true,
+          idempotencyKey: `trigger-${trigger.id}-${Math.floor(Date.now() / 1000)}`,
+        });
+      } catch (err) {
+        this.api.logger.error(
+          `betterclaw: trigger push failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+// -- Incoming event from iOS --
+
+export interface DeviceEvent {
+  subscriptionId: string;
+  source: string;
+  data: Record<string, number>;
+  metadata?: Record<string, string>;
+  firedAt: number;
+}
+
+// -- Context state (context.json) --
+
+export interface BatteryState {
+  level: number;
+  state: string;
+  isLowPowerMode: boolean;
+  updatedAt: number;
+}
+
+export interface LocationState {
+  latitude: number;
+  longitude: number;
+  horizontalAccuracy: number;
+  label: string | null;
+  updatedAt: number;
+}
+
+export interface HealthState {
+  stepsToday: number | null;
+  distanceMeters: number | null;
+  heartRateAvg: number | null;
+  restingHeartRate: number | null;
+  hrv: number | null;
+  activeEnergyKcal: number | null;
+  sleepDurationSeconds: number | null;
+  updatedAt: number;
+}
+
+export interface ActivityState {
+  currentZone: string | null;
+  zoneEnteredAt: number | null;
+  lastTransition: {
+    from: string | null;
+    to: string | null;
+    at: number;
+  } | null;
+  isStationary: boolean;
+  stationarySince: number | null;
+}
+
+export interface ContextMeta {
+  lastEventAt: number;
+  eventsToday: number;
+  lastAgentPushAt: number;
+  pushesToday: number;
+}
+
+export interface DeviceContext {
+  device: {
+    battery: BatteryState | null;
+    location: LocationState | null;
+    health: HealthState | null;
+  };
+  activity: ActivityState;
+  meta: ContextMeta;
+}
+
+// -- Filter decisions --
+
+export type FilterDecision =
+  | { action: "push"; reason: string }
+  | { action: "drop"; reason: string }
+  | { action: "defer"; reason: string }
+  | { action: "ambiguous"; reason: string };
+
+// -- Event log entry --
+
+export interface EventLogEntry {
+  event: DeviceEvent;
+  decision: "push" | "drop" | "defer";
+  reason: string;
+  timestamp: number;
+}
+
+// -- Patterns --
+
+export interface LocationRoutine {
+  zone: string;
+  typicalLeave: string | null;
+  typicalArrive: string | null;
+}
+
+export interface Patterns {
+  locationRoutines: {
+    weekday: LocationRoutine[];
+    weekend: LocationRoutine[];
+  };
+  healthTrends: {
+    stepsAvg7d: number | null;
+    stepsAvg30d: number | null;
+    stepsTrend: "improving" | "stable" | "declining" | null;
+    sleepAvg7d: number | null;
+    sleepTrend: "improving" | "stable" | "declining" | null;
+    restingHrAvg7d: number | null;
+    restingHrTrend: "improving" | "stable" | "declining" | null;
+  };
+  batteryPatterns: {
+    avgDrainPerHour: number | null;
+    typicalChargeTime: string | null;
+    lowBatteryFrequency: number | null;
+  };
+  eventStats: {
+    eventsPerDay7d: number;
+    pushesPerDay7d: number;
+    dropRate7d: number;
+    topSources: string[];
+  };
+  triggerCooldowns: Record<string, number>;
+  computedAt: number;
+}
+
+// -- Plugin config --
+
+export interface PluginConfig {
+  llmModel: string;
+  pushBudgetPerDay: number;
+  patternWindowDays: number;
+  proactiveEnabled: boolean;
+}