@better_openclaw/betterclaw 1.4.0 → 2.0.0

package/src/patterns.ts

@@ -2,13 +2,11 @@ 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;
+  private timer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(context: ContextManager, events: EventLog, windowDays: number) {
     this.context = context;
@@ -16,19 +14,38 @@ export class PatternEngine {
     this.windowDays = windowDays;
   }
 
-  startSchedule(): void {
-    // Run immediately, then every 6 hours
+  startSchedule(analysisHour: number, dailyCallback?: () => Promise<void>): void {
+    // Run initial compute on startup
     void this.compute().catch(() => {});
-    this.interval = setInterval(() => {
-      void this.compute().catch(() => {});
-    }, SIX_HOURS_MS);
-    this.interval.unref?.();
+
+    this.scheduleNext(analysisHour, dailyCallback);
+  }
+
+  private scheduleNext(analysisHour: number, dailyCallback?: () => Promise<void>): void {
+    const now = new Date();
+    const target = new Date(now);
+    target.setHours(analysisHour, 0, 0, 0);
+    if (target <= now) {
+      target.setDate(target.getDate() + 1);
+    }
+    const msUntil = target.getTime() - now.getTime();
+
+    this.timer = setTimeout(async () => {
+      try {
+        await this.compute();
+        if (dailyCallback) await dailyCallback();
+      } catch {
+        // ignore errors, will retry next day
+      }
+      this.scheduleNext(analysisHour, dailyCallback);
+    }, msUntil);
+    this.timer.unref?.();
   }
 
   stopSchedule(): void {
-    if (this.interval) {
-      clearInterval(this.interval);
-      this.interval = null;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
     }
   }
 

package/src/pipeline.ts

@@ -2,8 +2,10 @@ 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 { ReactionTracker } from "./reactions.js";
 import type { DeviceEvent, DeviceContext, PluginConfig } from "./types.js";
+import { triageEvent } from "./triage.js";
+import { loadTriageProfile } from "./learner.js";
 
 export interface PipelineDeps {
   api: OpenClawPluginApi;
@@ -11,68 +13,138 @@ export interface PipelineDeps {
   context: ContextManager;
   events: EventLog;
   rules: RulesEngine;
-  judgment: JudgmentLayer;
+  reactions: ReactionTracker;
+  stateDir: string;
 }
 
 export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Promise<void> {
-  const { api, config, context, events, rules, judgment } = deps;
+  const { api, config, context, events, rules } = deps;
 
   // Always update context
   context.updateFromEvent(event);
+  await context.save();
+
+  // If smartMode is OFF, store only — no filtering or pushing
+  if (!context.getRuntimeState().smartMode) {
+    await events.append({ event, decision: "stored", reason: "smartMode off", timestamp: Date.now() / 1000 });
+    return;
+  }
 
   // Run rules engine
-  let decision = rules.evaluate(event, context.get());
+  const deviceConfig = context.getDeviceConfig();
+  const effectiveBudget = deviceConfig.pushBudgetPerDay ?? config.pushBudgetPerDay;
+  const decision = rules.evaluate(event, context.get(), effectiveBudget);
 
-  // If ambiguous, run LLM judgment
+  // Ambiguous events go through LLM triage
   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,
-  });
+    const profile = await loadTriageProfile(deps.stateDir);
+    const triageResult = await triageEvent(
+      event,
+      deps.context,
+      profile,
+      { triageModel: deps.config.triageModel, triageApiBase: deps.config.triageApiBase },
+      async () => {
+        try {
+          const auth = await deps.api.runtime.modelAuth.resolveApiKeyForProvider({
+            provider: deps.config.triageModel.includes("/")
+              ? deps.config.triageModel.split("/")[0]
+              : "openai",
+          });
+          return auth.apiKey;
+        } catch {
+          return undefined;
+        }
+      },
+    );
+
+    if (triageResult.push) {
+      const pushed = await pushToAgent(deps, event, `triage: ${triageResult.reason}`);
+
+      if (pushed) {
+        rules.recordFired(event.subscriptionId, event.firedAt);
+        context.recordPush();
+        deps.reactions.recordPush({
+          idempotencyKey: `event-${event.subscriptionId}-${Math.floor(event.firedAt)}`,
+          subscriptionId: event.subscriptionId,
+          source: event.source,
+          pushedAt: 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)`);
+      await events.append({
+        event,
+        decision: pushed ? "push" : "drop",
+        reason: pushed ? `triage: ${triageResult.reason}` : `triage push failed: ${triageResult.reason}`,
+        timestamp: Date.now() / 1000,
+      });
     } else {
-      const message = formatEnrichedMessage(event, context);
+      await events.append({
+        event,
+        decision: "drop",
+        reason: `triage: ${triageResult.reason}`,
+        timestamp: Date.now() / 1000,
+      });
+    }
 
-      try {
-        await api.runtime.subagent.run({
-          sessionKey: "main",
-          message,
-          deliver: true,
-          idempotencyKey: `event-${event.subscriptionId}-${Math.floor(event.firedAt)}`,
-        });
+    await context.save();
+    await deps.reactions.save();
+    return;
+  }
 
-        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)}`,
-        );
-      }
+  if (decision.action === "push") {
+    const pushed = await pushToAgent(deps, event, decision.reason);
+
+    if (pushed) {
+      rules.recordFired(event.subscriptionId, event.firedAt);
+      context.recordPush();
+      deps.reactions.recordPush({
+        idempotencyKey: `event-${event.subscriptionId}-${Math.floor(event.firedAt)}`,
+        subscriptionId: event.subscriptionId,
+        source: event.source,
+        pushedAt: Date.now() / 1000,
+      });
     }
+
+    await events.append({
+      event,
+      decision: pushed ? "push" : "drop",
+      reason: pushed ? decision.reason : `push failed: ${decision.reason}`,
+      timestamp: Date.now() / 1000,
+    });
   } else {
-    api.logger.info(`betterclaw: ${decision.action} event ${event.subscriptionId}: ${decision.reason}`);
+    await events.append({
+      event,
+      decision: "drop",
+      reason: decision.reason,
+      timestamp: Date.now() / 1000,
+    });
+    api.logger.info(`betterclaw: drop event ${event.subscriptionId}: ${decision.reason}`);
   }
 
-  // Persist context
+  // Persist context and reactions
   await context.save();
+  await deps.reactions.save();
+}
+
+async function pushToAgent(deps: PipelineDeps, event: DeviceEvent, reason: string): Promise<boolean> {
+  const message = formatEnrichedMessage(event, deps.context);
+  const idempotencyKey = `event-${event.subscriptionId}-${Math.floor(event.firedAt)}`;
+
+  try {
+    await deps.api.runtime.subagent.run({
+      sessionKey: "main",
+      message,
+      deliver: true,
+      idempotencyKey,
+    });
+    deps.api.logger.info(`betterclaw: pushed event ${event.subscriptionId} to agent`);
+    return true;
+  } catch (err) {
+    deps.api.logger.error(
+      `betterclaw: failed to push to agent: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
 }
 
 function formatEnrichedMessage(event: DeviceEvent, context: ContextManager): string {

package/src/reactions.ts

@@ -0,0 +1,57 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ReactionEntry } from "./types.js";
+
+export class ReactionTracker {
+  private reactions: ReactionEntry[] = [];
+  private filePath: string;
+
+  constructor(stateDir: string) {
+    this.filePath = path.join(stateDir, "push-reactions.jsonl");
+  }
+
+  recordPush(entry: Omit<ReactionEntry, "engaged" | "checkedAt">): void {
+    this.reactions.push({ ...entry, engaged: null });
+  }
+
+  markEngaged(idempotencyKey: string, engaged: boolean): void {
+    const entry = this.reactions.find((r) => r.idempotencyKey === idempotencyKey);
+    if (entry) {
+      entry.engaged = engaged;
+      entry.checkedAt = Date.now() / 1000;
+    }
+  }
+
+  getRecent(hours: number): ReactionEntry[] {
+    const cutoff = Date.now() / 1000 - hours * 3600;
+    return this.reactions.filter((r) => r.pushedAt >= cutoff);
+  }
+
+  async save(): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    const lines = this.reactions.map((r) => JSON.stringify(r)).join("\n");
+    await fs.writeFile(this.filePath, lines + "\n", "utf-8");
+  }
+
+  async load(): Promise<void> {
+    try {
+      const content = await fs.readFile(this.filePath, "utf-8");
+      this.reactions = content
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((line) => {
+          try { return [JSON.parse(line) as ReactionEntry]; }
+          catch { return []; }
+        });
+    } catch {
+      this.reactions = [];
+    }
+  }
+
+  /** Rotate: keep only last 30 days */
+  rotate(): void {
+    const cutoff = Date.now() / 1000 - 30 * 86400;
+    this.reactions = this.reactions.filter((r) => r.pushedAt >= cutoff);
+  }
+}

package/src/tools/get-context.ts

@@ -1,7 +1,8 @@
 import { Type } from "@sinclair/typebox";
 import type { ContextManager } from "../context.js";
+import { loadTriageProfile } from "../learner.js";
 
-export function createGetContextTool(ctx: ContextManager) {
+export function createGetContextTool(ctx: ContextManager, stateDir?: string) {
   return {
     name: "get_context",
     label: "Get Device Context",
@@ -21,13 +22,35 @@ export function createGetContextTool(ctx: ContextManager) {
           : ["device", "activity", "patterns", "meta"];
 
       const state = ctx.get();
+      const runtime = ctx.getRuntimeState();
       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;
+      const result: Record<string, unknown> = {
+        tier: runtime.tier,
+        smartMode: runtime.smartMode,
+      };
+
+      if (sections.includes("device")) {
+        result.device = {
+          battery: state.device.battery ? { ...state.device.battery, updatedAt: ctx.getTimestamp("battery") } : null,
+          location: state.device.location ? { ...state.device.location, updatedAt: ctx.getTimestamp("location") } : null,
+          health: state.device.health ? { ...state.device.health, updatedAt: ctx.getTimestamp("health") } : null,
+        };
+      }
+      if (sections.includes("activity")) {
+        result.activity = { ...state.activity, updatedAt: ctx.getTimestamp("activity") };
+      }
       if (sections.includes("patterns") && patterns) result.patterns = patterns;
-      if (sections.includes("meta")) result.meta = state.meta;
+      if (sections.includes("meta")) {
+        result.meta = {
+          ...state.meta,
+          lastSnapshotAt: ctx.getTimestamp("lastSnapshot"),
+          lastAnalysisAt: patterns?.computedAt,
+        };
+      }
+
+      const profile = stateDir ? await loadTriageProfile(stateDir) : null;
+      result.triageProfile = profile ? { summary: profile.summary, computedAt: profile.computedAt } : null;
 
       return {
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],

package/src/triage.ts

@@ -0,0 +1,134 @@
+import type { DeviceEvent, TriageProfile } from "./types.js";
+import type { ContextManager } from "./context.js";
+
+export interface TriageResult {
+  push: boolean;
+  reason: string;
+  priority?: "low" | "normal" | "high";
+}
+
+export function buildTriagePrompt(
+  event: DeviceEvent,
+  context: ContextManager,
+  profile: TriageProfile | null,
+): string {
+  const ctx = context.get();
+  const battery = ctx.device.battery;
+  const location = ctx.device.location;
+  const health = ctx.device.health;
+  const activity = ctx.activity;
+
+  const profileSection = profile
+    ? `## User Triage Profile\n${profile.summary}\n\nInterruption tolerance: ${profile.interruptionTolerance}`
+    : "## User Triage Profile\nNo triage profile available — default to pushing the event.";
+
+  const contextSection = [
+    `## Current Device Context`,
+    battery ? `Battery: ${Math.round(battery.level * 100)}% (${battery.state})` : null,
+    location?.label ? `Location: ${location.label}` : null,
+    health?.stepsToday != null ? `Steps today: ${health.stepsToday}` : null,
+    activity?.currentZone ? `Zone: ${activity.currentZone}` : null,
+    `Time: ${String(new Date().getHours()).padStart(2, "0")}:${String(new Date().getMinutes()).padStart(2, "0")}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return `You are an event triage system for a personal assistant. Decide whether this device event should be pushed as a notification to the user.
+
+${profileSection}
+
+${contextSection}
+
+## Event
+- Subscription: ${event.subscriptionId}
+- Source: ${event.source}
+- Data: ${JSON.stringify(event.data)}
+- Fired at: ${new Date(event.firedAt * 1000).toISOString()}
+${event.metadata ? `- Metadata: ${JSON.stringify(event.metadata)}` : ""}
+
+Respond with JSON: {"push": boolean, "reason": string, "priority"?: "low"|"normal"|"high"}`;
+}
+
+export function parseTriageResponse(text: string): TriageResult {
+  try {
+    // Strip markdown code fence if present
+    const cleaned = text.replace(/```json?\n?/g, "").replace(/```/g, "").trim();
+    const parsed = JSON.parse(cleaned);
+    return {
+      push: parsed.push === true,
+      reason: String(parsed.reason ?? "no reason"),
+      priority: ["low", "normal", "high"].includes(parsed.priority) ? parsed.priority : undefined,
+    };
+  } catch {
+    return { push: true, reason: "failed to parse triage response" };
+  }
+}
+
+export async function triageEvent(
+  event: DeviceEvent,
+  context: ContextManager,
+  profile: TriageProfile | null,
+  config: { triageModel: string; triageApiBase?: string },
+  resolveApiKey: () => Promise<string | undefined>,
+): Promise<TriageResult> {
+  const prompt = buildTriagePrompt(event, context, profile);
+
+  try {
+    const apiKey = process.env.BETTERCLAW_TRIAGE_API_KEY ?? (await resolveApiKey());
+    if (!apiKey) {
+      return { push: true, reason: "no API key for triage — defaulting to push" };
+    }
+
+    const baseUrl = config.triageApiBase ?? "https://api.openai.com/v1";
+    const model = config.triageModel.includes("/")
+      ? config.triageModel.split("/").slice(1).join("/")
+      : config.triageModel;
+
+    const response = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: prompt }],
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: "triage_decision",
+            strict: true,
+            schema: {
+              type: "object",
+              properties: {
+                push: { type: "boolean" },
+                reason: { type: "string" },
+                priority: { type: "string", enum: ["low", "normal", "high"] },
+              },
+              required: ["push", "reason", "priority"],
+              additionalProperties: false,
+            },
+          },
+        },
+        max_tokens: 150,
+        temperature: 0,
+      }),
+    });
+
+    if (!response.ok) {
+      return { push: true, reason: `triage API error: ${response.status}` };
+    }
+
+    const data = (await response.json()) as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+    const content = data.choices?.[0]?.message?.content;
+    if (!content) {
+      return { push: true, reason: "empty triage response" };
+    }
+
+    return parseTriageResponse(content);
+  } catch (err) {
+    return { push: true, reason: `triage call failed: ${err}` };
+  }
+}

package/src/triggers.ts

@@ -189,6 +189,13 @@ export class ProactiveEngine {
   }
 
   async checkAll(): Promise<void> {
+    if (!this.context.getRuntimeState().smartMode) {
+      return;
+    }
+    const deviceConfig = this.context.getDeviceConfig();
+    if (deviceConfig.proactiveEnabled === false) {
+      return;
+    }
     const ctx = this.context.get();
     const patterns = (await this.context.readPatterns()) ?? (await import("./patterns.js")).emptyPatterns();
 

package/src/types.ts

@@ -70,14 +70,13 @@ export interface DeviceContext {
 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";
+  decision: "push" | "drop" | "stored";
   reason: string;
   timestamp: number;
 }
@@ -122,8 +121,44 @@ export interface Patterns {
 // -- Plugin config --
 
 export interface PluginConfig {
-  llmModel: string;
+  triageModel: string;
+  triageApiBase?: string;
   pushBudgetPerDay: number;
   patternWindowDays: number;
   proactiveEnabled: boolean;
+  analysisHour: number;
 }
+
+// Triage profile produced by daily learning agent
+export interface TriageProfile {
+  eventPreferences: Record<string, "push" | "drop" | "context-dependent">;
+  lifeContext: string;
+  interruptionTolerance: "low" | "normal" | "high";
+  timePreferences: { quietHoursStart?: number; quietHoursEnd?: number; activeStart?: number; activeEnd?: number };
+  sensitivityThresholds: Record<string, number>;
+  locationRules: Record<string, "push" | "drop" | "context-dependent">;
+  summary: string;
+  computedAt: number;
+}
+
+// Reaction tracking for pushed events
+export interface ReactionEntry {
+  idempotencyKey: string;
+  subscriptionId: string;
+  source: string;
+  pushedAt: number;
+  engaged: boolean | null; // null = not yet determined
+  checkedAt?: number;
+}
+
+// Per-device config from betterclaw.config RPC
+export interface DeviceConfig {
+  pushBudgetPerDay?: number;
+  proactiveEnabled?: boolean;
+}
+
+// Runtime state (not persisted)
+export interface RuntimeState {
+  tier: "free" | "premium" | "premium+";
+  smartMode: boolean;
+}