@better_openclaw/betterclaw 1.4.0

package/src/index.ts

@@ -0,0 +1,251 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { PluginConfig } from "./types.js";
+import { ContextManager } from "./context.js";
+import { createGetContextTool } from "./tools/get-context.js";
+import { EventLog } from "./events.js";
+import { RulesEngine } from "./filter.js";
+import { JudgmentLayer } from "./judgment.js";
+import { PatternEngine } from "./patterns.js";
+import { ProactiveEngine } from "./triggers.js";
+import { processEvent } from "./pipeline.js";
+import type { PipelineDeps } from "./pipeline.js";
+
+export type { PluginConfig } from "./types.js";
+
+const DEFAULT_CONFIG: PluginConfig = {
+  llmModel: "openai/gpt-4o-mini",
+  pushBudgetPerDay: 10,
+  patternWindowDays: 14,
+  proactiveEnabled: true,
+};
+
+function resolveConfig(raw: Record<string, unknown> | undefined): PluginConfig {
+  return {
+    llmModel:
+      typeof raw?.llmModel === "string" && raw.llmModel.trim()
+        ? raw.llmModel.trim()
+        : DEFAULT_CONFIG.llmModel,
+    pushBudgetPerDay:
+      typeof raw?.pushBudgetPerDay === "number" && raw.pushBudgetPerDay > 0
+        ? raw.pushBudgetPerDay
+        : DEFAULT_CONFIG.pushBudgetPerDay,
+    patternWindowDays:
+      typeof raw?.patternWindowDays === "number" && raw.patternWindowDays > 0
+        ? raw.patternWindowDays
+        : DEFAULT_CONFIG.patternWindowDays,
+    proactiveEnabled:
+      typeof raw?.proactiveEnabled === "boolean"
+        ? raw.proactiveEnabled
+        : DEFAULT_CONFIG.proactiveEnabled,
+  };
+}
+
+export default {
+  id: "betterclaw",
+  name: "BetterClaw Context",
+
+  register(api: OpenClawPluginApi) {
+    const config = resolveConfig(api.pluginConfig as Record<string, unknown> | undefined);
+    const stateDir = api.runtime.state.resolveStateDir();
+
+    api.logger.info(`betterclaw plugin loaded (model=${config.llmModel}, budget=${config.pushBudgetPerDay})`);
+
+    // Context manager (load synchronously — file read deferred to first access)
+    const ctxManager = new ContextManager(stateDir);
+
+    // Event log, rules engine, judgment layer
+    const eventLog = new EventLog(stateDir);
+    const rules = new RulesEngine(config.pushBudgetPerDay);
+    const judgment = new JudgmentLayer(api, config);
+
+    // Pipeline dependencies
+    const pipelineDeps: PipelineDeps = {
+      api,
+      config,
+      context: ctxManager,
+      events: eventLog,
+      rules,
+      judgment,
+    };
+
+    // Track whether async init has completed
+    let initialized = false;
+    const initPromise = (async () => {
+      try {
+        await ctxManager.load();
+        const recentEvents = await eventLog.readSince(Date.now() / 1000 - 86400);
+        rules.restoreCooldowns(
+          recentEvents
+            .filter((e) => e.decision === "push")
+            .map((e) => ({ subscriptionId: e.event.subscriptionId, firedAt: e.event.firedAt })),
+        );
+        initialized = true;
+        api.logger.info("betterclaw: async init complete");
+      } catch (err) {
+        api.logger.error(`betterclaw: init failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    })();
+
+    // Ping health check
+    api.registerGatewayMethod("betterclaw.ping", ({ respond }) => {
+      respond(true, { ok: true, version: "1.0.0", initialized });
+    });
+
+    // Context RPC — returns activity, trends, and recent decisions for iOS Context tab
+    api.registerGatewayMethod("betterclaw.context", async ({ respond }) => {
+      if (!initialized) await initPromise;
+
+      const state = ctxManager.get();
+      const patterns = await ctxManager.readPatterns();
+      const recentEntries = await eventLog.readRecent(20);
+
+      const activity = {
+        currentZone: state.activity.currentZone,
+        zoneEnteredAt: state.activity.zoneEnteredAt,
+        lastTransition: state.activity.lastTransition,
+        isStationary: state.activity.isStationary,
+        stationarySince: state.activity.stationarySince,
+      };
+
+      const trends = patterns
+        ? {
+            stepsAvg7d: patterns.healthTrends.stepsAvg7d,
+            stepsTrend: patterns.healthTrends.stepsTrend,
+            sleepAvg7d: patterns.healthTrends.sleepAvg7d,
+            sleepTrend: patterns.healthTrends.sleepTrend,
+            restingHrAvg7d: patterns.healthTrends.restingHrAvg7d,
+            restingHrTrend: patterns.healthTrends.restingHrTrend,
+            eventsPerDay7d: patterns.eventStats.eventsPerDay7d,
+            pushesPerDay7d: patterns.eventStats.pushesPerDay7d,
+            dropRate7d: patterns.eventStats.dropRate7d,
+          }
+        : null;
+
+      const decisions = recentEntries.map((e) => ({
+        source: e.event.source,
+        title: e.event.subscriptionId,
+        decision: e.decision,
+        reason: e.reason,
+        timestamp: e.timestamp,
+      }));
+
+      const meta = {
+        pushesToday: state.meta.pushesToday,
+        pushBudgetPerDay: config.pushBudgetPerDay,
+        eventsToday: state.meta.eventsToday,
+      };
+
+      const routines = patterns
+        ? {
+            weekday: patterns.locationRoutines.weekday,
+            weekend: patterns.locationRoutines.weekend,
+          }
+        : null;
+
+      respond(true, { activity, trends, decisions, meta, routines });
+    });
+
+    // Snapshot RPC — bulk-apply device state for Smart Mode catch-up
+    api.registerGatewayMethod("betterclaw.snapshot", async ({ params, respond }) => {
+      if (!initialized) await initPromise;
+
+      const snapshot = params as {
+        battery?: { level: number; state: string; isLowPowerMode: boolean };
+        location?: { latitude: number; longitude: number };
+        health?: {
+          stepsToday?: number; distanceMeters?: number; heartRateAvg?: number;
+          restingHeartRate?: number; hrv?: number; activeEnergyKcal?: number;
+          sleepDurationSeconds?: number;
+        };
+        geofence?: { type: string; zoneName: string; latitude: number; longitude: number };
+      };
+
+      ctxManager.applySnapshot(snapshot);
+      await ctxManager.save();
+      respond(true, { applied: true });
+    });
+
+    // Agent tool
+    api.registerTool(createGetContextTool(ctxManager), { optional: true });
+
+    // Auto-reply command
+    api.registerCommand({
+      name: "bc",
+      description: "Show current BetterClaw device context snapshot",
+      handler: () => {
+        const state = ctxManager.get();
+        const battery = state.device.battery;
+        const loc = state.device.location;
+        const health = state.device.health;
+        const activity = state.activity;
+
+        const lines: string[] = [];
+        if (battery) {
+          lines.push(`Battery: ${Math.round(battery.level * 100)}% (${battery.state})`);
+        }
+        if (loc) {
+          lines.push(`Location: ${loc.label ?? `${loc.latitude.toFixed(4)}, ${loc.longitude.toFixed(4)}`}`);
+        }
+        if (activity.currentZone) {
+          const since = activity.zoneEnteredAt
+            ? ` since ${new Date(activity.zoneEnteredAt * 1000).toLocaleTimeString()}`
+            : "";
+          lines.push(`Zone: ${activity.currentZone}${since}`);
+        }
+        if (health?.stepsToday) {
+          lines.push(`Steps: ${Math.round(health.stepsToday).toLocaleString()}`);
+        }
+        lines.push(`Events today: ${state.meta.eventsToday} | Pushes: ${state.meta.pushesToday}`);
+
+        return { text: lines.join("\n") };
+      },
+    });
+
+    // Event intake RPC
+    api.registerGatewayMethod("betterclaw.event", async ({ params, respond }) => {
+      try {
+        // Wait for init if still pending
+        if (!initialized) await initPromise;
+
+        const event = {
+          subscriptionId: typeof params?.subscriptionId === "string" ? params.subscriptionId : "",
+          source: typeof params?.source === "string" ? params.source : "",
+          data: (params?.data && typeof params.data === "object" ? params.data : {}) as Record<string, number>,
+          metadata: (params?.metadata && typeof params.metadata === "object"
+            ? params.metadata
+            : undefined) as Record<string, string> | undefined,
+          firedAt: typeof params?.firedAt === "number" ? params.firedAt : Date.now() / 1000,
+        };
+
+        if (!event.subscriptionId || !event.source) {
+          respond(false, undefined, { code: "INVALID_PARAMS", message: "subscriptionId and source required" });
+          return;
+        }
+
+        respond(true, { accepted: true });
+        await processEvent(pipelineDeps, event);
+      } catch (err) {
+        api.logger.error(`betterclaw.event handler error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    });
+
+    // Pattern engine + proactive engine
+    const patternEngine = new PatternEngine(ctxManager, eventLog, config.patternWindowDays);
+    const proactiveEngine = new ProactiveEngine(ctxManager, api, config);
+
+    // Background service
+    api.registerService({
+      id: "betterclaw-engine",
+      start: () => {
+        patternEngine.startSchedule();
+        proactiveEngine.startSchedule();
+        api.logger.info("betterclaw: background services started");
+      },
+      stop: () => {
+        patternEngine.stopSchedule();
+        proactiveEngine.stopSchedule();
+        api.logger.info("betterclaw: background services stopped");
+      },
+    });
+  },
+};

package/src/judgment.ts

@@ -0,0 +1,145 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { DeviceContext, DeviceEvent } from "./types.js";
+
+interface JudgmentResult {
+  push: boolean;
+  reason: string;
+}
+
+type RunEmbeddedPiAgentFn = (opts: Record<string, unknown>) => Promise<{ payloads?: unknown[] }>;
+
+let _runFn: RunEmbeddedPiAgentFn | null = null;
+
+async function loadRunEmbeddedPiAgent(): Promise<RunEmbeddedPiAgentFn> {
+  if (_runFn) return _runFn;
+  // Dynamic import from OpenClaw internals (same pattern as llm-task plugin)
+  const mod = await import("../../../src/agents/pi-embedded.js").catch(() =>
+    import("openclaw/agents/pi-embedded"),
+  );
+  if (typeof (mod as any).runEmbeddedPiAgent !== "function") {
+    throw new Error("runEmbeddedPiAgent not available");
+  }
+  _runFn = (mod as any).runEmbeddedPiAgent as RunEmbeddedPiAgentFn;
+  return _runFn;
+}
+
+export function buildPrompt(event: DeviceEvent, context: DeviceContext, pushesToday: number, budget: number): string {
+  // Strip raw coordinates from context for privacy
+  const sanitizedContext = {
+    ...context,
+    device: {
+      ...context.device,
+      location: context.device.location
+        ? {
+            label: context.device.location.label ?? "Unknown",
+            updatedAt: context.device.location.updatedAt,
+          }
+        : null,
+    },
+  };
+
+  return [
+    "You are an event triage system for a personal AI assistant.",
+    "Given the device context and a new event, decide: should the AI assistant be told about this?",
+    "",
+    "Respond with ONLY valid JSON: {\"push\": true/false, \"reason\": \"one sentence\"}",
+    "",
+    `Context: ${JSON.stringify(sanitizedContext)}`,
+    `Event: ${JSON.stringify(event)}`,
+    `Pushes today: ${pushesToday} of ~${budget} budget`,
+    `Time: ${new Date().toISOString()}`,
+  ].join("\n");
+}
+
+function extractText(payloads: unknown[]): string {
+  for (const p of payloads) {
+    if (typeof p === "string") return p;
+    if (p && typeof p === "object" && "text" in p && typeof (p as any).text === "string") {
+      return (p as any).text;
+    }
+    if (p && typeof p === "object" && "content" in p && Array.isArray((p as any).content)) {
+      for (const c of (p as any).content) {
+        if (c && typeof c.text === "string") return c.text;
+      }
+    }
+  }
+  return "";
+}
+
+export class JudgmentLayer {
+  private api: OpenClawPluginApi;
+  private config: { llmModel: string; pushBudgetPerDay: number };
+
+  constructor(api: OpenClawPluginApi, config: { llmModel: string; pushBudgetPerDay: number }) {
+    this.api = api;
+    this.config = config;
+  }
+
+  async evaluate(event: DeviceEvent, context: DeviceContext): Promise<JudgmentResult> {
+    const prompt = buildPrompt(event, context, context.meta.pushesToday, this.config.pushBudgetPerDay);
+
+    const [provider, ...modelParts] = this.config.llmModel.split("/");
+    const model = modelParts.join("/");
+
+    if (!provider || !model) {
+      this.api.logger.warn("betterclaw: invalid llmModel config, defaulting to push");
+      return { push: true, reason: "llm model not configured — fail open" };
+    }
+
+    let tmpDir: string | null = null;
+    try {
+      tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "betterclaw-judgment-"));
+      const sessionId = `betterclaw-judgment-${Date.now()}`;
+      const sessionFile = path.join(tmpDir, "session.json");
+
+      const runEmbeddedPiAgent = await loadRunEmbeddedPiAgent();
+
+      const result = await runEmbeddedPiAgent({
+        sessionId,
+        sessionFile,
+        workspaceDir: (this.api as any).config?.agents?.defaults?.workspace ?? process.cwd(),
+        config: (this.api as any).config,
+        prompt,
+        timeoutMs: 15_000,
+        runId: `betterclaw-judgment-${Date.now()}`,
+        provider,
+        model,
+        disableTools: true,
+      });
+
+      const text = extractText(result.payloads ?? []);
+      if (!text) {
+        this.api.logger.warn("betterclaw: LLM returned empty output, defaulting to push");
+        return { push: true, reason: "llm returned empty — fail open" };
+      }
+
+      // Strip code fences if present
+      const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+
+      try {
+        const parsed = JSON.parse(cleaned) as { push?: boolean; reason?: string };
+        return {
+          push: parsed.push === true,
+          reason: typeof parsed.reason === "string" ? parsed.reason : "no reason given",
+        };
+      } catch {
+        this.api.logger.warn(`betterclaw: LLM returned invalid JSON: ${text.slice(0, 200)}`);
+        return { push: true, reason: "llm returned invalid json — fail open" };
+      }
+    } catch (err) {
+      this.api.logger.error(`betterclaw: judgment call failed: ${err instanceof Error ? err.message : String(err)}`);
+      return { push: true, reason: "llm call failed — fail open" };
+    } finally {
+      if (tmpDir) {
+        try {
+          await fs.rm(tmpDir, { recursive: true, force: true });
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+}

package/src/patterns.ts

@@ -0,0 +1,248 @@
+import type { ContextManager } from "./context.js";
+import type { EventLog } from "./events.js";
+import type { EventLogEntry, Patterns } from "./types.js";
+
+const SIX_HOURS_MS = 6 * 60 * 60 * 1000;
+
+export class PatternEngine {
+  private context: ContextManager;
+  private events: EventLog;
+  private windowDays: number;
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(context: ContextManager, events: EventLog, windowDays: number) {
+    this.context = context;
+    this.events = events;
+    this.windowDays = windowDays;
+  }
+
+  startSchedule(): void {
+    // Run immediately, then every 6 hours
+    void this.compute().catch(() => {});
+    this.interval = setInterval(() => {
+      void this.compute().catch(() => {});
+    }, SIX_HOURS_MS);
+    this.interval.unref?.();
+  }
+
+  stopSchedule(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+
+  async compute(): Promise<Patterns> {
+    const windowStart = Date.now() / 1000 - this.windowDays * 86400;
+    const entries = await this.events.readSince(windowStart);
+
+    const existing = (await this.context.readPatterns()) ?? emptyPatterns();
+
+    const patterns: Patterns = {
+      locationRoutines: computeLocationRoutines(entries),
+      healthTrends: computeHealthTrends(entries),
+      batteryPatterns: computeBatteryPatterns(entries),
+      eventStats: computeEventStats(entries),
+      triggerCooldowns: existing.triggerCooldowns,
+      computedAt: Date.now() / 1000,
+    };
+
+    await this.context.writePatterns(patterns);
+
+    // Rotate event log if needed
+    await this.events.rotate();
+
+    return patterns;
+  }
+}
+
+export function emptyPatterns(): Patterns {
+  return {
+    locationRoutines: { weekday: [], weekend: [] },
+    healthTrends: {
+      stepsAvg7d: null,
+      stepsAvg30d: null,
+      stepsTrend: null,
+      sleepAvg7d: null,
+      sleepTrend: null,
+      restingHrAvg7d: null,
+      restingHrTrend: null,
+    },
+    batteryPatterns: {
+      avgDrainPerHour: null,
+      typicalChargeTime: null,
+      lowBatteryFrequency: null,
+    },
+    eventStats: {
+      eventsPerDay7d: 0,
+      pushesPerDay7d: 0,
+      dropRate7d: 0,
+      topSources: [],
+    },
+    triggerCooldowns: {},
+    computedAt: 0,
+  };
+}
+
+function computeLocationRoutines(entries: EventLogEntry[]) {
+  const geofenceEvents = entries.filter((e) => e.event.source === "geofence.triggered");
+
+  const weekdayZones = new Map<string, { arrives: number[]; leaves: number[] }>();
+  const weekendZones = new Map<string, { arrives: number[]; leaves: number[] }>();
+
+  for (const entry of geofenceEvents) {
+    const date = new Date(entry.event.firedAt * 1000);
+    const isWeekend = date.getDay() === 0 || date.getDay() === 6;
+    const hour = date.getHours() + date.getMinutes() / 60;
+    const type = entry.event.data.type === 1 ? "enter" : "exit";
+    const zones = isWeekend ? weekendZones : weekdayZones;
+
+    const zone = entry.event.metadata?.zoneName ?? "Unknown";
+    if (!zones.has(zone)) zones.set(zone, { arrives: [], leaves: [] });
+    const z = zones.get(zone)!;
+
+    if (type === "enter") z.arrives.push(hour);
+    else z.leaves.push(hour);
+  }
+
+  const formatRoutines = (zones: Map<string, { arrives: number[]; leaves: number[] }>) =>
+    Array.from(zones.entries()).map(([zone, data]) => ({
+      zone,
+      typicalArrive: data.arrives.length > 0 ? formatHour(median(data.arrives)) : null,
+      typicalLeave: data.leaves.length > 0 ? formatHour(median(data.leaves)) : null,
+    }));
+
+  return {
+    weekday: formatRoutines(weekdayZones),
+    weekend: formatRoutines(weekendZones),
+  };
+}
+
+function computeHealthTrends(entries: EventLogEntry[]) {
+  const healthEvents = entries.filter((e) => e.event.source.startsWith("health"));
+  const now = Date.now() / 1000;
+
+  const last7d = healthEvents.filter((e) => e.event.firedAt >= now - 7 * 86400);
+  const last30d = healthEvents;
+
+  const stepsValues7d = last7d
+    .map((e) => e.event.data.stepsToday)
+    .filter((v): v is number => v != null);
+  const stepsValues30d = last30d
+    .map((e) => e.event.data.stepsToday)
+    .filter((v): v is number => v != null);
+  const sleepValues7d = last7d
+    .map((e) => e.event.data.sleepDurationSeconds)
+    .filter((v): v is number => v != null);
+  const sleepValues30d = last30d
+    .map((e) => e.event.data.sleepDurationSeconds)
+    .filter((v): v is number => v != null);
+  const rhrValues7d = last7d
+    .map((e) => e.event.data.restingHeartRate)
+    .filter((v): v is number => v != null);
+  const rhrValues30d = last30d
+    .map((e) => e.event.data.restingHeartRate)
+    .filter((v): v is number => v != null);
+
+  const stepsAvg7d = average(stepsValues7d);
+  const stepsAvg30d = average(stepsValues30d);
+  const sleepAvg7d = average(sleepValues7d);
+  const sleepAvg30d = average(sleepValues30d);
+  const rhrAvg7d = average(rhrValues7d);
+  const rhrAvg30d = average(rhrValues30d);
+
+  return {
+    stepsAvg7d,
+    stepsAvg30d,
+    stepsTrend: computeTrend(stepsAvg7d, stepsAvg30d),
+    sleepAvg7d,
+    sleepTrend: computeTrend(sleepAvg7d, sleepAvg30d),
+    restingHrAvg7d: rhrAvg7d,
+    restingHrTrend: computeInverseTrend(rhrAvg7d, rhrAvg30d),
+  };
+}
+
+function computeBatteryPatterns(entries: EventLogEntry[]) {
+  const lowBatteryEvents = entries.filter(
+    (e) =>
+      e.event.subscriptionId === "default.battery-low" ||
+      e.event.subscriptionId === "default.battery-critical",
+  );
+
+  const daySpan =
+    entries.length > 0
+      ? Math.max(1, (entries[entries.length - 1].timestamp - entries[0].timestamp) / 86400)
+      : 1;
+
+  return {
+    avgDrainPerHour: null,
+    typicalChargeTime: null,
+    lowBatteryFrequency: lowBatteryEvents.length / daySpan,
+  };
+}
+
+function computeEventStats(entries: EventLogEntry[]) {
+  const now = Date.now() / 1000;
+  const last7d = entries.filter((e) => e.timestamp >= now - 7 * 86400);
+
+  const days = Math.max(1, 7);
+  const pushes = last7d.filter((e) => e.decision === "push");
+  const drops = last7d.filter((e) => e.decision === "drop");
+
+  const sourceCounts = new Map<string, number>();
+  for (const e of last7d) {
+    sourceCounts.set(e.event.source, (sourceCounts.get(e.event.source) ?? 0) + 1);
+  }
+  const topSources = Array.from(sourceCounts.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([source]) => source);
+
+  return {
+    eventsPerDay7d: last7d.length / days,
+    pushesPerDay7d: pushes.length / days,
+    dropRate7d: last7d.length > 0 ? drops.length / last7d.length : 0,
+    topSources,
+  };
+}
+
+// -- Helpers --
+
+function average(values: number[]): number | null {
+  if (values.length === 0) return null;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function formatHour(h: number): string {
+  const hours = Math.floor(h);
+  const mins = Math.round((h - hours) * 60);
+  return `${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}`;
+}
+
+function computeTrend(
+  recent: number | null,
+  baseline: number | null,
+): "improving" | "stable" | "declining" | null {
+  if (recent == null || baseline == null) return null;
+  const ratio = recent / baseline;
+  if (ratio > 1.1) return "improving";
+  if (ratio < 0.9) return "declining";
+  return "stable";
+}
+
+function computeInverseTrend(
+  recent: number | null,
+  baseline: number | null,
+): "improving" | "stable" | "declining" | null {
+  if (recent == null || baseline == null) return null;
+  const ratio = recent / baseline;
+  if (ratio < 0.9) return "improving";
+  if (ratio > 1.1) return "declining";
+  return "stable";
+}