@better_openclaw/betterclaw 2.2.2 → 3.0.1

package/src/reaction-scanner.ts

@@ -0,0 +1,238 @@
+import type { ReactionStatus } from "./types.js";
+import type { ReactionTracker } from "./reactions.js";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+// --- Types ---
+
+export interface PushMatch {
+  pushIndex: number;
+  subsequentMessages: Array<{ role: string; content: unknown }>;
+}
+
+export interface ClassificationResult {
+  status: ReactionStatus;
+  reason: string;
+}
+
+export interface ScanDeps {
+  api: OpenClawPluginApi;
+  reactions: ReactionTracker;
+  classificationModel: string;
+  classificationApiBase?: string;
+  getApiKey: () => Promise<string | undefined>;
+}
+
+// --- Helpers ---
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b: any) => b.type === "text")
+      .map((b: any) => b.text ?? "")
+      .join("");
+  }
+  return "";
+}
+
+function isBetterClawPush(text: string): boolean {
+  return text.includes("[BetterClaw device event");
+}
+
+// --- Exported functions ---
+
+/**
+ * Deterministic search: find the pushed message in the session transcript by
+ * timestamp proximity (within 30s) + content prefix match.
+ */
+export function findPushInMessages(
+  messages: Array<{ role: string; content: unknown; timestamp?: number }>,
+  pushedAt: number,
+  messageSummary: string,
+): PushMatch | null {
+  const prefix = messageSummary.slice(0, 30);
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const text = extractText(msg.content);
+
+    // Must be a BetterClaw push message
+    if (!isBetterClawPush(text)) continue;
+
+    // Must be within 30s of pushedAt
+    if (msg.timestamp !== undefined) {
+      if (Math.abs(msg.timestamp - pushedAt) > 30) continue;
+    }
+
+    // Must contain the first 30 chars of messageSummary
+    if (!text.includes(prefix)) continue;
+
+    // Collect subsequent messages until next BetterClaw push or limit of 5
+    const subsequent: Array<{ role: string; content: unknown }> = [];
+    for (let j = i + 1; j < messages.length && subsequent.length < 5; j++) {
+      const next = messages[j];
+      const nextText = extractText(next.content);
+      if (isBetterClawPush(nextText)) break;
+      subsequent.push({ role: next.role, content: next.content });
+    }
+
+    return { pushIndex: i, subsequentMessages: subsequent };
+  }
+
+  return null;
+}
+
+/**
+ * Build a classification prompt asking the LLM to determine engagement status.
+ */
+export function buildClassificationPrompt(
+  pushMessage: string,
+  subsequentMessages: Array<{ role: string; content: unknown }>,
+): string {
+  const convoLines = subsequentMessages
+    .map((m) => `${m.role}: ${extractText(m.content)}`)
+    .join("\n");
+
+  return `You are classifying user engagement with a pushed device notification.
+
+The following message was pushed to the user's AI assistant:
+---
+${pushMessage}
+---
+
+Conversation that followed:
+${convoLines || "(no subsequent messages)"}
+
+Classify the user's engagement with this notification:
+- "engaged": the user acknowledged, replied, or acted on the notification
+- "ignored": the user changed topic, ignored it, or showed no reaction
+- "unclear": not enough information to determine
+
+Respond with JSON: {"status": "engaged"|"ignored"|"unclear", "reason": string}`;
+}
+
+/**
+ * Parse LLM JSON response into classification result.
+ */
+export function parseClassificationResponse(text: string): ClassificationResult {
+  try {
+    const cleaned = text.replace(/```json?\n?/g, "").replace(/```/g, "").trim();
+    const parsed = JSON.parse(cleaned);
+    const validStatuses: ReactionStatus[] = ["engaged", "ignored", "unclear"];
+    const status = validStatuses.includes(parsed.status) ? parsed.status : "unclear";
+    return {
+      status,
+      reason: typeof parsed.reason === "string" ? parsed.reason : "no reason provided",
+    };
+  } catch {
+    return { status: "unclear", reason: "failed to parse LLM response" };
+  }
+}
+
+/**
+ * Orchestrator: scan all pending reactions, do deterministic transcript search,
+ * classify via LLM, and record results on the ReactionTracker.
+ */
+export async function scanPendingReactions(deps: ScanDeps): Promise<void> {
+  const { api, reactions } = deps;
+
+  const pending = reactions.getPending();
+  if (pending.length === 0) {
+    api.logger.info("reaction-scanner: no pending reactions to classify");
+    return;
+  }
+
+  api.logger.info(`reaction-scanner: scanning ${pending.length} pending reaction(s)`);
+
+  // Fetch session messages once (limit 200) to search through
+  let messages: Array<{ role: string; content: unknown; timestamp?: number }> = [];
+  try {
+    const { messages: fetched } = await api.runtime.subagent.getSessionMessages({
+      sessionKey: "main",
+      limit: 200,
+    });
+    messages = fetched;
+  } catch (err) {
+    api.logger.error(
+      `reaction-scanner: failed to fetch session messages: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return;
+  }
+
+  for (const reaction of pending) {
+    try {
+      // Step 1: Deterministic search
+      const match = findPushInMessages(messages, reaction.pushedAt, reaction.messageSummary);
+      if (!match) {
+        api.logger.info(
+          `reaction-scanner: no transcript match for ${reaction.subscriptionId} at ${reaction.pushedAt} — skipping`,
+        );
+        continue;
+      }
+
+      // Step 2: Build prompt
+      const pushText = extractText(
+        messages[match.pushIndex].content,
+      );
+      const prompt = buildClassificationPrompt(pushText, match.subsequentMessages);
+
+      // Step 3: LLM classification via subagent
+      const sessionKey = `betterclaw-classify-${reaction.subscriptionId}-${Math.floor(reaction.pushedAt)}`;
+      let classificationResult: ClassificationResult = { status: "unclear", reason: "classification not attempted" };
+
+      try {
+        // Clean up any stale session first
+        try { await api.runtime.subagent.deleteSession({ sessionKey }); } catch { /* ignore */ }
+
+        const { runId } = await api.runtime.subagent.run({
+          sessionKey,
+          message: prompt,
+          deliver: false,
+          idempotencyKey: `classify-${reaction.subscriptionId}-${Math.floor(reaction.pushedAt)}`,
+        });
+
+        await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
+
+        const { messages: classifyMessages } = await api.runtime.subagent.getSessionMessages({
+          sessionKey,
+          limit: 5,
+        });
+
+        const lastAssistant = classifyMessages.filter((m: any) => m.role === "assistant").pop();
+        if (lastAssistant) {
+          const content = extractText(lastAssistant.content);
+          if (content) {
+            classificationResult = parseClassificationResponse(content);
+          }
+        }
+      } finally {
+        try { await api.runtime.subagent.deleteSession({ sessionKey }); } catch { /* ignore */ }
+      }
+
+      // Step 4: Record classification using compound key
+      reactions.classify(
+        reaction.subscriptionId,
+        reaction.pushedAt,
+        classificationResult.status,
+        classificationResult.reason,
+      );
+
+      api.logger.info(
+        `reaction-scanner: classified ${reaction.subscriptionId} as "${classificationResult.status}" — ${classificationResult.reason}`,
+      );
+    } catch (err) {
+      api.logger.error(
+        `reaction-scanner: error classifying ${reaction.subscriptionId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // Persist updated reactions
+  try {
+    await reactions.save();
+  } catch (err) {
+    api.logger.error(
+      `reaction-scanner: failed to save reactions: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/reactions.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { ReactionEntry } from "./types.js";
+import type { ReactionEntry, ReactionStatus } from "./types.js";
 
 export class ReactionTracker {
   private reactions: ReactionEntry[] = [];
@@ -10,21 +10,43 @@ export class ReactionTracker {
     this.filePath = path.join(stateDir, "push-reactions.jsonl");
   }
 
-  recordPush(entry: Omit<ReactionEntry, "engaged" | "checkedAt">): void {
-    this.reactions.push({ ...entry, engaged: null });
+  recordPush(entry: { subscriptionId: string; source: string; pushedAt: number; messageSummary: string }): void {
+    this.reactions.push({
+      ...entry,
+      status: "pending",
+    });
   }
 
-  markEngaged(idempotencyKey: string, engaged: boolean): void {
-    const entry = this.reactions.find((r) => r.idempotencyKey === idempotencyKey);
+  /** Classify a reaction by matching on subscriptionId + pushedAt compound key */
+  classify(subscriptionId: string, pushedAt: number, status: ReactionStatus, reason: string): void {
+    const entry = this.reactions.find(
+      (r) => r.subscriptionId === subscriptionId && r.pushedAt === pushedAt && r.status === "pending"
+    );
     if (entry) {
-      entry.engaged = engaged;
-      entry.checkedAt = Date.now() / 1000;
+      entry.status = status;
+      entry.classifiedAt = Date.now() / 1000;
+      entry.classificationReason = reason;
     }
   }
 
-  getRecent(hours: number): ReactionEntry[] {
+  /** Get pending (unclassified) reactions; optionally filtered to the last N hours */
+  getPending(hours?: number): ReactionEntry[] {
+    const pending = this.reactions.filter((r) => r.status === "pending");
+    if (hours === undefined) {
+      return pending;
+    }
+    const cutoff = Date.now() / 1000 - hours * 3600;
+    return pending.filter((r) => r.pushedAt >= cutoff);
+  }
+
+  getRecent(_hours?: number): ReactionEntry[] {
+    return [...this.reactions];
+  }
+
+  /** Get classified reactions for learner input */
+  getClassified(hours: number = 24): ReactionEntry[] {
     const cutoff = Date.now() / 1000 - hours * 3600;
-    return this.reactions.filter((r) => r.pushedAt >= cutoff);
+    return this.reactions.filter((r) => r.status !== "pending" && r.pushedAt >= cutoff);
   }
 
   async save(): Promise<void> {
@@ -49,7 +71,6 @@ export class ReactionTracker {
     }
   }
 
-  /** 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/check-tier.ts

@@ -0,0 +1,63 @@
+import { Type } from "@sinclair/typebox";
+import type { ContextManager } from "../context.js";
+
+export interface CheckTierState {
+  pingReceived: boolean;
+  calibrating: boolean;
+  calibrationEndsAt?: number;
+}
+
+export function createCheckTierTool(ctx: ContextManager, getState: () => CheckTierState) {
+  return {
+    name: "check_tier",
+    label: "Check Device Tier",
+    description:
+      "Check the user's BetterClaw subscription tier and get instructions for how to access their device data. Call this first before accessing device data, or use your cached tier if still valid.",
+    parameters: Type.Object({}),
+    async execute(_id: string, _params: Record<string, unknown>) {
+      const state = getState();
+
+      if (!state.pingReceived) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              tier: "unknown",
+              dataPath: "Tier not yet determined — the device hasn't connected. Try again shortly.",
+              cacheUntil: Math.floor(Date.now() / 1000) + 60,
+              cacheInstruction: "Re-check in about a minute.",
+            }, null, 2),
+          }],
+        };
+      }
+
+      const runtime = ctx.getRuntimeState();
+      const cacheUntil = Math.floor(Date.now() / 1000) + 86400;
+
+      const isPremium = runtime.tier === "premium" || runtime.tier === "premium+";
+
+      const dataPath = isPremium
+        ? "Use node commands for current device readings: location.get, device.battery, health.steps, health.heartrate, health.hrv, health.sleep, health.distance, health.restinghr, health.workouts, health.summary, geofence.list. Use get_context for patterns, trends, history, and broad situational awareness — its device snapshot may not be perfectly recent but is useful for the big picture."
+        : "Use get_context for all device data. This is a cached snapshot from the last time the user had BetterClaw open — check timestamps for freshness. You cannot query fresh data on free tier.";
+
+      const cacheInstruction = `Save your tier and data path to your memory. Re-check after cacheUntil (${new Date(cacheUntil * 1000).toISOString()}). Until then, use the cached tier to decide how to access device data.`;
+
+      const result: Record<string, unknown> = {
+        tier: runtime.tier,
+        dataPath,
+        cacheUntil,
+        cacheInstruction,
+      };
+
+      if (state.calibrating) {
+        result.calibrating = true;
+        result.calibrationEndsAt = state.calibrationEndsAt;
+        result.calibrationNote = "BetterClaw's smart filtering is still calibrating — it needs a few days to learn your preferences. Events are being tracked but filtering is in rules-only mode.";
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  };
+}

package/src/tools/get-context.ts

@@ -1,4 +1,3 @@
-import { Type } from "@sinclair/typebox";
 import type { ContextManager } from "../context.js";
 import { loadTriageProfile } from "../learner.js";
 
@@ -7,47 +6,47 @@ export function createGetContextTool(ctx: ContextManager, stateDir?: string) {
     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"];
-
+      "Get BetterClaw context — patterns, trends, activity zone, event history, and cached device snapshots with staleness indicators. On premium, node commands return fresher data for current readings. On free, this includes the latest device snapshot.",
+    parameters: {},
+    async execute(_id: string, _params: Record<string, unknown>) {
       const state = ctx.get();
       const runtime = ctx.getRuntimeState();
       const patterns = await ctx.readPatterns();
+      const dataAge = ctx.getDataAge();
+
+      const isPremium = runtime.tier === "premium" || runtime.tier === "premium+";
 
       const result: Record<string, unknown> = {
-        tier: runtime.tier,
+        tierHint: {
+          tier: runtime.tier,
+          note: isPremium
+            ? "Node commands available for fresh readings (location.get, device.battery, health.*)"
+            : "This is the only data source on free tier — check dataAgeSeconds for freshness",
+        },
         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,
-          lastSnapshotAt: ctx.getTimestamp("lastSnapshot"),
-          lastAnalysisAt: patterns?.computedAt,
-        };
-      }
+      result.device = {
+        battery: state.device.battery
+          ? { ...state.device.battery, updatedAt: ctx.getTimestamp("battery"), dataAgeSeconds: dataAge.battery }
+          : null,
+        location: state.device.location
+          ? { ...state.device.location, updatedAt: ctx.getTimestamp("location"), dataAgeSeconds: dataAge.location }
+          : null,
+        health: state.device.health
+          ? { ...state.device.health, updatedAt: ctx.getTimestamp("health"), dataAgeSeconds: dataAge.health }
+          : null,
+      };
+
+      result.activity = { ...state.activity, updatedAt: ctx.getTimestamp("activity") };
+
+      if (patterns) result.patterns = patterns;
+
+      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;

package/src/triage.ts

@@ -11,6 +11,7 @@ export function buildTriagePrompt(
   event: DeviceEvent,
   context: ContextManager,
   profile: TriageProfile | null,
+  budget?: { budgetUsed: number; budgetTotal: number },
 ): string {
   const ctx = context.get();
   const battery = ctx.device.battery;
@@ -33,12 +34,16 @@ export function buildTriagePrompt(
     .filter(Boolean)
     .join("\n");
 
+  const budgetSection = budget
+    ? `## Push Budget\n${budget.budgetUsed} of ${budget.budgetTotal} pushes used today — be selective.`
+    : "";
+
   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}
-
+${budgetSection ? `\n${budgetSection}` : ""}
 ## Event
 - Subscription: ${event.subscriptionId}
 - Source: ${event.source}
@@ -60,7 +65,7 @@ export function parseTriageResponse(text: string): TriageResult {
       priority: ["low", "normal", "high"].includes(parsed.priority) ? parsed.priority : undefined,
     };
   } catch {
-    return { push: true, reason: "failed to parse triage response" };
+    return { push: false, reason: "failed to parse triage response — defaulting to drop" };
   }
 }
 
@@ -68,15 +73,19 @@ export async function triageEvent(
   event: DeviceEvent,
   context: ContextManager,
   profile: TriageProfile | null,
-  config: { triageModel: string; triageApiBase?: string },
+  config: { triageModel: string; triageApiBase?: string; budgetUsed?: number; budgetTotal?: number },
   resolveApiKey: () => Promise<string | undefined>,
 ): Promise<TriageResult> {
-  const prompt = buildTriagePrompt(event, context, profile);
+  const prompt = buildTriagePrompt(event, context, profile,
+    config.budgetUsed != null && config.budgetTotal != null
+      ? { budgetUsed: config.budgetUsed, budgetTotal: config.budgetTotal }
+      : undefined
+  );
 
   try {
     const apiKey = await resolveApiKey();
     if (!apiKey) {
-      return { push: true, reason: "no API key for triage — defaulting to push" };
+      return { push: false, reason: "no API key for triage — defaulting to drop" };
     }
 
     const baseUrl = config.triageApiBase ?? "https://api.openai.com/v1";
@@ -116,7 +125,7 @@ export async function triageEvent(
     });
 
     if (!response.ok) {
-      return { push: true, reason: `triage API error: ${response.status}` };
+      return { push: false, reason: `triage API error: ${response.status} — defaulting to drop` };
     }
 
     const data = (await response.json()) as {
@@ -124,11 +133,11 @@ export async function triageEvent(
     };
     const content = data.choices?.[0]?.message?.content;
     if (!content) {
-      return { push: true, reason: "empty triage response" };
+      return { push: false, reason: "empty triage response — defaulting to drop" };
     }
 
     return parseTriageResponse(content);
   } catch (err) {
-    return { push: true, reason: `triage call failed: ${err}` };
+    return { push: false, reason: `triage call failed: ${err} — defaulting to drop` };
   }
 }

package/src/types.ts

@@ -76,7 +76,7 @@ export type FilterDecision =
 
 export interface EventLogEntry {
   event: DeviceEvent;
-  decision: "push" | "drop" | "stored";
+  decision: "push" | "drop" | "stored" | "free_stored";
   reason: string;
   timestamp: number;
 }
@@ -114,7 +114,6 @@ export interface Patterns {
     dropRate7d: number;
     topSources: string[];
   };
-  triggerCooldowns: Record<string, number>;
   computedAt: number;
 }
 
@@ -129,28 +128,27 @@ export interface PluginConfig {
   analysisHour: number;
   deduplicationCooldowns: Record<string, number>;
   defaultCooldown: number;
+  calibrationDays: number;
 }
 
 // Triage profile produced by daily learning agent
 export interface TriageProfile {
-  eventPreferences: Record<string, "push" | "drop" | "context-dependent">;
-  lifeContext: string;
+  summary: string;              // 1-2 sentence description of what the user cares about
   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;
+  computedAt: number;           // epoch seconds
 }
 
 // Reaction tracking for pushed events
+export type ReactionStatus = "pending" | "engaged" | "ignored" | "unclear";
+
 export interface ReactionEntry {
-  idempotencyKey: string;
   subscriptionId: string;
   source: string;
   pushedAt: number;
-  engaged: boolean | null; // null = not yet determined
-  checkedAt?: number;
+  messageSummary: string;       // first ~100 chars of the pushed message
+  status: ReactionStatus;
+  classifiedAt?: number;        // epoch when LLM classified
+  classificationReason?: string; // one-line reason from classifier
 }
 
 // Per-device config from betterclaw.config RPC

package/openclaw-plugin-sdk.md

@@ -1,38 +0,0 @@
-# OpenClaw Plugin SDK — What Plugins Can and Cannot Do
-
-## No LLM/Agent Access from Plugins
-
-Plugins **cannot** invoke LLMs or spawn agent sessions. This was discovered through deep investigation of the OpenClaw source code and plugin SDK.
-
-### What we tried
-- `runEmbeddedPiAgent` — an internal OpenClaw function used by the core agent. Both betteremail and betterclaw plugins tried to import it via `openclaw/agents/pi-embedded`. This **does not work** because it's not exported in the plugin SDK.
-
-### Why it doesn't work
-- The plugin SDK (`openclaw/plugin-sdk`) only exports a limited surface:
-  - `OpenClawPluginApi` — the `api` object passed to `register()`
-  - `openclaw/plugin-sdk/llm-task` — exists as an export path but provides no agent invocation
-- `openclaw/agents/*` is **not an exported path** — the import fails at runtime via Jiti (TypeScript loader)
-- `runEmbeddedPiAgent` is internal to OpenClaw's agent system and intentionally not exposed to plugins
-- The betterclaw plugin has the **exact same bug** — it also imports `runEmbeddedPiAgent` and has never successfully run its judgment layer
-
-### What plugins CAN do
-- `api.registerTool()` — expose tools to the agent (with optional `{ optional: true }` flag)
-- `api.registerService()` — run background services (polling loops, etc.)
-- `api.registerCommand()` — add `/commands` to the chat UI
-- `api.runtime.system.runCommandWithTimeout()` — run shell commands (including `gog`, `openclaw` CLI)
-- `api.runtime.state.resolveStateDir()` — get persistent state directory
-- `api.pluginConfig` — read plugin config from openclaw.yaml
-- `api.logger` — structured logging
-
-### What plugins CANNOT do
-- Invoke LLMs or create agent sessions
-- Import internal OpenClaw modules outside the plugin SDK exports
-- Access `runEmbeddedPiAgent` or any agent runtime internals
-- Run embedded "sub-agents" for classification or judgment
-
-### The solution we adopted
-Instead of classifying emails in the plugin, we removed the classifier entirely and made the plugin a **pure stateful memory layer**. All emails enter the digest, and the agent triages them during cron-triggered sessions with full context (memory, skills, user preferences). This is actually better because:
-1. The agent has full context for triage decisions
-2. No separate LLM invocation cost
-3. Simpler architecture — the plugin just tracks state
-4. Cron job runs in isolated session, only notifies main session when something matters