@better_openclaw/betterclaw 3.0.3 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better_openclaw/betterclaw",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "Intelligent event filtering, context tracking, and proactive triggers for BetterClaw",
   "license": "AGPL-3.0-only",
   "repository": {

package/skills/betterclaw/SKILL.md

@@ -28,6 +28,17 @@ You have two complementary tools:
 
 Both are useful. Node commands for precision, `get_context` for the big picture.
 
+### Action commands (premium only)
+
+Beyond sensors, you can perform actions on the device:
+
+- **Notifications**: `system.notify` — send a push notification to the user's device
+- **Clipboard**: `clipboard.write` — copy text to the device clipboard
+- **Shortcuts**: `shortcuts.run`, `shortcuts.install` — run or install iOS Shortcuts
+- **Geofences**: `geofence.add`, `geofence.remove`, `geofence.list` — manage location-based geofences
+- **Subscriptions**: `subscribe.add`, `subscribe.remove`, `subscribe.list`, `subscribe.pause`, `subscribe.resume` — manage event subscriptions that trigger proactive alerts
+- **Capabilities**: `system.capabilities` — check what the device supports
+
 ### Free tier
 
 `get_context` is the only data source. It returns a cached snapshot from the

package/src/context.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { DeviceConfig, DeviceContext, DeviceEvent, Patterns, RuntimeState } from "./types.js";
+import { errorMessage, noopLogger, type DeviceConfig, type DeviceContext, type DeviceEvent, type Patterns, type PluginModuleLogger, type RuntimeState } from "./types.js";
 
 const CONTEXT_FILE = "context.json";
 const PATTERNS_FILE = "patterns.json";
@@ -12,11 +12,13 @@ export class ContextManager {
   private runtimeState: RuntimeState = { tier: null, smartMode: false };
   private timestamps: Record<string, number> = {};
   private deviceConfig: DeviceConfig = {};
+  private logger: PluginModuleLogger;
 
-  constructor(stateDir: string) {
+  constructor(stateDir: string, logger?: PluginModuleLogger) {
     this.contextPath = path.join(stateDir, CONTEXT_FILE);
     this.patternsPath = path.join(stateDir, PATTERNS_FILE);
     this.context = ContextManager.empty();
+    this.logger = logger ?? noopLogger;
   }
 
   static empty(): DeviceContext {
@@ -81,12 +83,18 @@ export class ContextManager {
     };
   }
 
-  async save(): Promise<void> {
-    await fs.mkdir(path.dirname(this.contextPath), { recursive: true });
-    const data = { ...this.context, _timestamps: this.timestamps, _tier: this.runtimeState.tier };
-    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");
+  async save(): Promise<boolean> {
+    try {
+      await fs.mkdir(path.dirname(this.contextPath), { recursive: true });
+      const data = { ...this.context, _timestamps: this.timestamps, _tier: this.runtimeState.tier };
+      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");
+      return true;
+    } catch (err) {
+      this.logger.error(`context save failed: ${errorMessage(err)}`);
+      return false;
+    }
   }
 
   updateFromEvent(event: DeviceEvent): void {
@@ -275,8 +283,13 @@ export class ContextManager {
     }
   }
 
-  async writePatterns(patterns: Patterns): Promise<void> {
-    await fs.mkdir(path.dirname(this.patternsPath), { recursive: true });
-    await fs.writeFile(this.patternsPath, JSON.stringify(patterns, null, 2) + "\n", "utf8");
+  async writePatterns(patterns: Patterns): Promise<boolean> {
+    try {
+      await fs.writeFile(this.patternsPath, JSON.stringify(patterns, null, 2) + "\n", "utf8");
+      return true;
+    } catch (err) {
+      this.logger.error(`patterns write failed: ${errorMessage(err)}`);
+      return false;
+    }
   }
 }

package/src/diagnostic-logger.ts

@@ -0,0 +1,177 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { PluginModuleLogger, PluginLogEntry } from "./types.js";
+
+const LEVEL_ORDER = ["debug", "info", "warn", "error"] as const;
+
+/** Lean interface for module-facing logging. Modules import `dlog` and call these methods. */
+export interface DiagnosticLogWriter {
+  debug(source: string, event: string, message: string, data?: Record<string, unknown>): void;
+  info(source: string, event: string, message: string, data?: Record<string, unknown>): void;
+  warn(source: string, event: string, message: string, data?: Record<string, unknown>): void;
+  error(source: string, event: string, message: string, data?: Record<string, unknown>): void;
+}
+
+const NOOP: DiagnosticLogWriter = { debug() {}, info() {}, warn() {}, error() {} };
+
+/**
+ * Singleton diagnostic logger. Always a valid object:
+ * - Before initDiagnosticLogger(): silent no-op (safe in tests)
+ * - After initDiagnosticLogger(): real logger with JSONL persistence + dual-write
+ *
+ * Modules import this for structured logging. index.ts uses the full
+ * PluginDiagnosticLogger instance (returned by init) for readLogs/rotate/flush/scoped.
+ */
+export let dlog: DiagnosticLogWriter = NOOP;
+
+/** Initialize the singleton. Call once from index.ts register(). Returns the full instance. */
+export function initDiagnosticLogger(logDir: string, apiLogger: PluginModuleLogger): PluginDiagnosticLogger {
+  const instance = new PluginDiagnosticLogger(logDir, apiLogger);
+  dlog = instance;
+  return instance;
+}
+
+export class PluginDiagnosticLogger implements DiagnosticLogWriter {
+  private logDir: string;
+  private apiLogger: PluginModuleLogger;
+  private circuitBroken = false;
+  private dirEnsured = false;
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(logDir: string, apiLogger: PluginModuleLogger) {
+    this.logDir = logDir;
+    this.apiLogger = apiLogger;
+  }
+
+  debug(source: string, event: string, message: string, data?: Record<string, unknown>): void {
+    this.writeEntry({ timestamp: Date.now() / 1000, level: "debug", source, event, message, ...(data !== undefined && { data }) });
+  }
+
+  info(source: string, event: string, message: string, data?: Record<string, unknown>): void {
+    this.writeEntry({ timestamp: Date.now() / 1000, level: "info", source, event, message, ...(data !== undefined && { data }) });
+    this.apiLogger.info(`[${source}] ${message}`);
+  }
+
+  warn(source: string, event: string, message: string, data?: Record<string, unknown>): void {
+    this.writeEntry({ timestamp: Date.now() / 1000, level: "warn", source, event, message, ...(data !== undefined && { data }) });
+    this.apiLogger.warn(`[${source}] ${message}`);
+  }
+
+  error(source: string, event: string, message: string, data?: Record<string, unknown>): void {
+    this.writeEntry({ timestamp: Date.now() / 1000, level: "error", source, event, message, ...(data !== undefined && { data }) });
+    this.apiLogger.error(`[${source}] ${message}`);
+  }
+
+  scoped(source: string): PluginModuleLogger {
+    return {
+      info: (msg: string) => this.info(source, "info", msg),
+      warn: (msg: string) => this.warn(source, "warn", msg),
+      error: (msg: string) => this.error(source, "error", msg),
+    };
+  }
+
+  async readLogs(opts: { since?: number; limit?: number; level?: string; source?: string } = {}): Promise<{ entries: PluginLogEntry[]; total: number }> {
+    const since = opts.since ?? (Date.now() / 1000 - 86400);
+    const limit = Math.min(opts.limit ?? 200, 50_000);
+    const minLevelIdx = opts.level ? LEVEL_ORDER.indexOf(opts.level as (typeof LEVEL_ORDER)[number]) : 0;
+
+    let files: string[];
+    try {
+      files = (await fs.readdir(this.logDir))
+        .filter(f => f.startsWith("diagnostic-") && f.endsWith(".jsonl"))
+        .sort()
+        .reverse();
+    } catch {
+      return { entries: [], total: 0 };
+    }
+
+    const allEntries: PluginLogEntry[] = [];
+
+    for (const file of files) {
+      const dateMatch = file.match(/diagnostic-(\d{4}-\d{2}-\d{2})\.jsonl/);
+      if (dateMatch) {
+        const endOfDay = new Date(dateMatch[1] + "T23:59:59").getTime() / 1000;
+        if (endOfDay < since) break;
+      }
+
+      let content: string;
+      try {
+        content = await fs.readFile(path.join(this.logDir, file), "utf-8");
+      } catch {
+        continue;
+      }
+
+      for (const line of content.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const entry = JSON.parse(line) as PluginLogEntry;
+          if (entry.timestamp < since) continue;
+          if (minLevelIdx > 0 && LEVEL_ORDER.indexOf(entry.level) < minLevelIdx) continue;
+          if (opts.source && !entry.source.startsWith(opts.source)) continue;
+          allEntries.push(entry);
+        } catch {
+          // Skip malformed lines
+        }
+      }
+    }
+
+    allEntries.sort((a, b) => a.timestamp - b.timestamp);
+    const total = allEntries.length;
+    const entries = total > limit ? allEntries.slice(total - limit) : allEntries;
+    return { entries, total };
+  }
+
+  async rotate(): Promise<void> {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - 7);
+    const cutoffStr = this.formatDate(cutoff);
+
+    let files: string[];
+    try {
+      files = await fs.readdir(this.logDir);
+    } catch {
+      return;
+    }
+
+    for (const file of files) {
+      const dateMatch = file.match(/diagnostic-(\d{4}-\d{2}-\d{2})\.jsonl/);
+      if (dateMatch && dateMatch[1] < cutoffStr) {
+        try {
+          await fs.unlink(path.join(this.logDir, file));
+        } catch { /* already deleted */ }
+      }
+    }
+
+    this.circuitBroken = false;
+  }
+
+  async flush(): Promise<void> {
+    await this.writeChain;
+  }
+
+  private writeEntry(entry: PluginLogEntry): void {
+    if (this.circuitBroken) return;
+
+    const filePath = path.join(this.logDir, `diagnostic-${this.formatDate(new Date())}.jsonl`);
+    const line = JSON.stringify(entry) + "\n";
+
+    this.writeChain = this.writeChain
+      .then(async () => {
+        if (!this.dirEnsured) {
+          await fs.mkdir(this.logDir, { recursive: true });
+          this.dirEnsured = true;
+        }
+        await fs.appendFile(filePath, line, "utf-8");
+      })
+      .catch(() => {
+        if (!this.circuitBroken) {
+          this.apiLogger.warn("[diagnostic-logger] disk write failed, circuit breaker tripped");
+        }
+        this.circuitBroken = true;
+      });
+  }
+
+  private formatDate(d: Date): string {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+  }
+}

package/src/events.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { EventLogEntry } from "./types.js";
+import { errorMessage, noopLogger, type EventLogEntry, type PluginModuleLogger } from "./types.js";
 
 const EVENTS_FILE = "events.jsonl";
 const MAX_LINES = 10_000;
@@ -8,15 +8,23 @@ const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 
 export class EventLog {
   private filePath: string;
+  private logger: PluginModuleLogger;
 
-  constructor(stateDir: string) {
+  constructor(stateDir: string, logger?: PluginModuleLogger) {
     this.filePath = path.join(stateDir, EVENTS_FILE);
+    this.logger = logger ?? noopLogger;
   }
 
-  async append(entry: EventLogEntry): Promise<void> {
-    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
-    const line = JSON.stringify(entry) + "\n";
-    await fs.appendFile(this.filePath, line, "utf8");
+  async append(entry: EventLogEntry): Promise<boolean> {
+    try {
+      await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+      const line = JSON.stringify(entry) + "\n";
+      await fs.appendFile(this.filePath, line, "utf8");
+      return true;
+    } catch (err) {
+      this.logger.error(`events append failed: ${errorMessage(err)}`);
+      return false;
+    }
   }
 
   async readAll(): Promise<EventLogEntry[]> {
@@ -46,19 +54,24 @@ export class EventLog {
   }
 
   async rotate(): Promise<number> {
-    const entries = await this.readAll();
-    if (entries.length <= MAX_LINES) return 0;
+    try {
+      const entries = await this.readAll();
+      if (entries.length <= MAX_LINES) return 0;
 
-    const cutoff = Date.now() / 1000 - MAX_AGE_MS / 1000;
-    const kept = entries.filter((e) => e.timestamp >= cutoff).slice(-MAX_LINES);
-    const removed = entries.length - kept.length;
+      const cutoff = Date.now() / 1000 - MAX_AGE_MS / 1000;
+      const kept = entries.filter((e) => e.timestamp >= cutoff).slice(-MAX_LINES);
+      const removed = entries.length - kept.length;
 
-    const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
-    const tmpPath = this.filePath + ".tmp";
-    await fs.writeFile(tmpPath, content, "utf8");
-    await fs.rename(tmpPath, this.filePath);
+      const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
+      const tmpPath = this.filePath + ".tmp";
+      await fs.writeFile(tmpPath, content, "utf8");
+      await fs.rename(tmpPath, this.filePath);
 
-    return removed;
+      return removed;
+    } catch (err) {
+      this.logger.error(`events rotate failed: ${errorMessage(err)}`);
+      return 0;
+    }
   }
 
   async count(): Promise<number> {

package/src/filter.ts

@@ -1,7 +1,9 @@
 import type { DeviceContext, DeviceEvent, FilterDecision } from "./types.js";
+import { dlog } from "./diagnostic-logger.js";
 
 export class RulesEngine {
   private lastFired: Map<string, number> = new Map();
+  private lastPushedBatteryLevel: number | undefined;
   private pushBudget: number;
   private cooldowns: Record<string, number>;
   private defaultCooldown: number;
@@ -13,6 +15,10 @@ export class RulesEngine {
   }
 
   evaluate(event: DeviceEvent, context: DeviceContext, budgetOverride?: number): FilterDecision {
+    // Note: debug, critical battery, and geofence events intentionally bypass the push
+    // budget check below. These are high-priority events that should always reach the
+    // agent regardless of daily budget limits.
+
     // Debug events always pass
     if (event.data._debugFired === 1.0) {
       return { action: "push", reason: "debug event — always push" };
@@ -41,27 +47,23 @@ export class RulesEngine {
     // Battery low — check if level changed since last push
     if (event.subscriptionId === "default.battery-low") {
       const currentLevel = event.data.level;
-      const lastLevel = context.device.battery?.level;
-      if (
-        lastLevel !== undefined &&
+      const lastPushedLevel = this.lastPushedBatteryLevel;
+      const deduplicated =
+        lastPushedLevel !== undefined &&
         currentLevel !== undefined &&
-        Math.abs(currentLevel - lastLevel) < 0.02
-      ) {
+        Math.abs(currentLevel - lastPushedLevel) < 0.02;
+      dlog.debug("plugin.pipeline", "dedup.checked", "battery dedup evaluated", {
+        subscriptionId: event.subscriptionId,
+        currentLevel,
+        lastPushedLevel,
+        deduplicated,
+      });
+      if (deduplicated) {
         return { action: "drop", reason: "battery-low: level unchanged since last push" };
       }
       return { action: "push", reason: "battery low — level changed" };
     }
 
-    // Daily health — check time window
-    if (event.subscriptionId === "default.daily-health") {
-      const hour = new Date(event.firedAt * 1000).getHours();
-      // Preferred window: 6am-10am
-      if (hour >= 6 && hour <= 10) {
-        return { action: "push", reason: "daily health summary — within morning window" };
-      }
-      return { action: "drop", reason: "daily health summary — outside morning window" };
-    }
-
     // Push budget check
     const budget = budgetOverride ?? this.pushBudget;
     if (context.meta.pushesToday >= budget) {
@@ -72,17 +74,23 @@ export class RulesEngine {
     return { action: "ambiguous", reason: "no rule matched — forward to LLM judgment" };
   }
 
-  recordFired(subscriptionId: string, firedAt: number): void {
+  recordFired(subscriptionId: string, firedAt: number, data?: Record<string, number>): void {
     this.lastFired.set(subscriptionId, firedAt);
+    if (subscriptionId === "default.battery-low" && data?.level != null) {
+      this.lastPushedBatteryLevel = data.level;
+    }
   }
 
   /** Restore cooldown state (call on load) */
-  restoreCooldowns(entries: Array<{ subscriptionId: string; firedAt: number }>): void {
-    for (const { subscriptionId, firedAt } of entries) {
+  restoreCooldowns(entries: Array<{ subscriptionId: string; firedAt: number; data?: Record<string, number> }>): void {
+    for (const { subscriptionId, firedAt, data } of entries) {
       const existing = this.lastFired.get(subscriptionId);
       if (!existing || firedAt > existing) {
         this.lastFired.set(subscriptionId, firedAt);
       }
+      if (subscriptionId === "default.battery-low" && data?.level != null) {
+        this.lastPushedBatteryLevel = data.level;
+      }
     }
   }
 }

package/src/index.ts

@@ -1,5 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { PluginConfig, DeviceConfig } from "./types.js";
+import { errorMessage } from "./types.js";
+import { initDiagnosticLogger } from "./diagnostic-logger.js";
 import { ContextManager } from "./context.js";
 import { createGetContextTool } from "./tools/get-context.js";
 import { EventLog } from "./events.js";
@@ -65,8 +67,9 @@ export default {
   register(api: OpenClawPluginApi) {
     const config = resolveConfig(api.pluginConfig as Record<string, unknown> | undefined);
     const stateDir = api.runtime.state.resolveStateDir();
+    const diagnosticLogger = initDiagnosticLogger(path.join(stateDir, "logs"), api.logger);
 
-    api.logger.info(`betterclaw plugin loaded (model=${config.triageModel}, budget=${config.pushBudgetPerDay})`);
+    diagnosticLogger.info("plugin.service", "loaded", "plugin loaded", { model: config.triageModel, budget: config.pushBudgetPerDay });
 
     // Calibration state
     let calibrationStartedAt: number | null = null;
@@ -89,12 +92,12 @@ export default {
     }
 
     // Context manager (load synchronously — file read deferred to first access)
-    const ctxManager = new ContextManager(stateDir);
+    const ctxManager = new ContextManager(stateDir, diagnosticLogger.scoped("plugin.context"));
 
     // Event log, rules engine, reaction tracker
-    const eventLog = new EventLog(stateDir);
+    const eventLog = new EventLog(stateDir, diagnosticLogger.scoped("plugin.events"));
     const rules = new RulesEngine(config.pushBudgetPerDay, config.deduplicationCooldowns, config.defaultCooldown);
-    const reactionTracker = new ReactionTracker(stateDir);
+    const reactionTracker = new ReactionTracker(stateDir, diagnosticLogger.scoped("plugin.reactions"));
 
     // Pipeline dependencies
     const pipelineDeps: PipelineDeps = {
@@ -112,17 +115,22 @@ export default {
     // Track whether async init has completed
     let initialized = false;
     let learnerRunning = false;
+    const initStart = Date.now();
     const initPromise = (async () => {
       try {
         await ctxManager.load();
         initialized = true;
+        diagnosticLogger.info("plugin.service", "init.phase", "context loaded", { phase: "context", success: true });
       } catch (err) {
-        api.logger.error(`betterclaw: context init failed: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.service", "init.phase", "context init failed: " + msg, { phase: "context", success: false, error: msg });
       }
       try {
         await reactionTracker.load();
+        diagnosticLogger.info("plugin.service", "init.phase", "reactions loaded", { phase: "reactions", success: true });
       } catch (err) {
-        api.logger.warn(`betterclaw: reaction tracker load failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.warn("plugin.service", "init.phase", "reaction tracker load failed: " + msg, { phase: "reactions", success: false, error: msg });
       }
       if (initialized) {
         try {
@@ -130,11 +138,12 @@ export default {
           rules.restoreCooldowns(
             recentEvents
               .filter((e) => e.decision === "push")
-              .map((e) => ({ subscriptionId: e.event.subscriptionId, firedAt: e.event.firedAt })),
+              .map((e) => ({ subscriptionId: e.event.subscriptionId, firedAt: e.event.firedAt, data: e.event.data })),
           );
-          api.logger.info("betterclaw: async init complete");
+          diagnosticLogger.info("plugin.service", "init.complete", "async init complete", { durationMs: Date.now() - initStart });
         } catch (err) {
-          api.logger.error(`betterclaw: cooldown restore failed: ${err instanceof Error ? err.message : String(err)}`);
+          const msg = errorMessage(err);
+          diagnosticLogger.error("plugin.service", "init.phase", "cooldown restore failed: " + msg, { phase: "cooldowns", success: false, error: msg });
         }
       }
     })();
@@ -150,10 +159,12 @@ export default {
       if (jwt) {
         const payload = await storeJwt(jwt);
         if (payload) {
-          api.logger.info(`betterclaw: JWT verified, entitlements=${payload.ent.join(",")}`);
+          diagnosticLogger.info("plugin.rpc", "ping.received", "JWT verified", { tier, smartMode, entitlements: payload.ent });
         } else {
-          api.logger.warn("betterclaw: JWT verification failed");
+          diagnosticLogger.warn("plugin.rpc", "ping.received", "JWT verification failed", { tier, smartMode });
         }
+      } else {
+        diagnosticLogger.info("plugin.rpc", "ping.received", "device ping", { tier, smartMode, nodeConnected: context.hasConnectedMobileNode() });
       }
 
       ctxManager.setRuntimeState({ tier, smartMode });
@@ -163,11 +174,15 @@ export default {
         const existingProfile = await loadTriageProfile(stateDir);
         if (existingProfile?.computedAt) {
           calibrationStartedAt = existingProfile.computedAt - config.calibrationDays * 86400;
-          api.logger.info("betterclaw: existing triage profile found — skipping calibration");
+          diagnosticLogger.info("plugin.calibration", "calibration.skipped", "existing triage profile found");
         } else {
           calibrationStartedAt = Date.now() / 1000;
+          diagnosticLogger.info("plugin.calibration", "calibration.started", "calibration period started");
         }
-        fs.writeFile(calibrationFile, JSON.stringify({ startedAt: calibrationStartedAt }), "utf8").catch(() => {});
+        fs.writeFile(calibrationFile, JSON.stringify({ startedAt: calibrationStartedAt }), "utf8").catch((err) => {
+          const msg = errorMessage(err);
+          diagnosticLogger.warn("plugin.calibration", "calibration.error", "calibration file write failed: " + msg, { error: msg });
+        });
       }
 
       const meta = ctxManager.get().meta;
@@ -199,9 +214,11 @@ export default {
 
         ctxManager.setDeviceConfig(deviceConfig);
         await ctxManager.save();
+        diagnosticLogger.info("plugin.rpc", "config.applied", "config updated", { changedFields: Object.keys(deviceConfig) });
         respond(true, { applied: true });
       } catch (err) {
-        api.logger.error(`betterclaw.config error: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.rpc", "config.error", "config RPC failed: " + msg, { error: msg });
         respond(false, undefined, { code: "INTERNAL_ERROR", message: "config update failed" });
       }
     });
@@ -269,6 +286,7 @@ export default {
             }
           : null;
 
+        diagnosticLogger.info("plugin.rpc", "context.served", "context served", { tier: runtime.tier });
         respond(true, {
           tier: runtime.tier,
           smartMode: runtime.smartMode,
@@ -282,7 +300,8 @@ export default {
           triageProfile: profile ?? null,
         });
       } catch (err) {
-        api.logger.error(`betterclaw.context error: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.rpc", "context.error", "context RPC failed: " + msg, { error: msg });
         respond(false, undefined, { code: "INTERNAL_ERROR", message: "context fetch failed" });
       }
     });
@@ -290,6 +309,7 @@ export default {
     // Learn RPC — trigger on-demand triage profile learning
     api.registerGatewayMethod("betterclaw.learn", async ({ respond }) => {
       try {
+        diagnosticLogger.info("plugin.rpc", "learn.triggered", "learn RPC triggered");
         if (!initialized) await initPromise;
 
         if (learnerRunning) {
@@ -329,8 +349,9 @@ export default {
         }
       } catch (err) {
         learnerRunning = false;
-        api.logger.error(`betterclaw.learn error: ${err instanceof Error ? err.message : String(err)}`);
-        respond(true, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.rpc", "learn.error", "learn RPC failed: " + msg, { error: msg });
+        respond(true, { ok: false, error: msg });
       }
     });
 
@@ -352,13 +373,31 @@ export default {
 
         ctxManager.applySnapshot(snapshot);
         await ctxManager.save();
+        diagnosticLogger.info("plugin.rpc", "snapshot.applied", "snapshot applied", { fieldCount: Object.keys(snapshot).length });
         respond(true, { applied: true });
       } catch (err) {
-        api.logger.error(`betterclaw.snapshot error: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.rpc", "snapshot.error", "snapshot RPC failed: " + msg, { error: msg });
         respond(false, undefined, { code: "INTERNAL_ERROR", message: "snapshot apply failed" });
       }
     });
 
+    // Diagnostic logs RPC — read structured log entries
+    api.registerGatewayMethod("betterclaw.logs", async ({ params, respond }) => {
+      try {
+        const p = (params ?? {}) as Record<string, unknown>;
+        const result = await diagnosticLogger.readLogs({
+          since: typeof p.since === "number" ? p.since : undefined,
+          limit: typeof p.limit === "number" ? p.limit : undefined,
+          level: typeof p.level === "string" ? p.level : undefined,
+          source: typeof p.source === "string" ? p.source : undefined,
+        });
+        respond(true, result);
+      } catch (err) {
+        respond(false, undefined, { code: "LOGS_READ_FAILED", message: errorMessage(err) });
+      }
+    });
+
     // Agent tools
     api.registerTool(
       createCheckTierTool(ctxManager, () => ({
@@ -431,32 +470,37 @@ export default {
 
         // Sequential processing — prevents budget races
         eventQueue = eventQueue.then(() => processEvent(pipelineDeps, event)).catch((err) => {
-          api.logger.error(`event processing failed: ${err}`);
+          const msg = errorMessage(err);
+          diagnosticLogger.error("plugin.pipeline", "event.error", "event processing failed: " + msg, { error: msg });
+          eventLog.append({ event, decision: "error", reason: `processing error: ${msg}`, timestamp: Date.now() / 1000 });
         });
       } catch (err) {
-        api.logger.error(`betterclaw.event handler error: ${err instanceof Error ? err.message : String(err)}`);
+        const msg = errorMessage(err);
+        diagnosticLogger.error("plugin.rpc", "event.error", "event handler error: " + msg, { error: msg });
         respond(false, undefined, { code: "INTERNAL_ERROR", message: "event processing failed" });
       }
     });
 
     // Pattern engine
-    const patternEngine = new PatternEngine(ctxManager, eventLog, config.patternWindowDays);
+    const patternEngine = new PatternEngine(ctxManager, eventLog, config.patternWindowDays, diagnosticLogger.scoped("plugin.patterns"));
 
     // Background service
     api.registerService({
       id: "betterclaw-engine",
       start: () => {
         patternEngine.startSchedule(config.analysisHour, async () => {
+          await diagnosticLogger.rotate();
+
           if (ctxManager.getRuntimeState().smartMode) {
-            // Scan reactions first (feeds into learner)
             try {
               await scanPendingReactions({ reactions: reactionTracker, api });
             } catch (err) {
-              api.logger.error(`betterclaw: reaction scan failed: ${err}`);
+              const msg = errorMessage(err);
+              diagnosticLogger.error("plugin.reactions", "scan.failed", "reaction scan failed: " + msg, { error: msg });
             }
 
-            // Then run learner
             try {
+              const learnerStart = Date.now();
               await runLearner({
                 stateDir,
                 workspaceDir: path.join(os.homedir(), ".openclaw", "workspace"),
@@ -465,17 +509,18 @@ export default {
                 reactions: reactionTracker,
                 api,
               });
-              api.logger.info("betterclaw: daily learner completed");
+              diagnosticLogger.info("plugin.learner", "learner.completed", "daily learner completed", { durationMs: Date.now() - learnerStart });
             } catch (err) {
-              api.logger.error(`betterclaw: daily learner failed: ${err}`);
+              const msg = errorMessage(err);
+              diagnosticLogger.error("plugin.learner", "learner.failed", "daily learner failed: " + msg, { error: msg });
             }
           }
         });
-        api.logger.info("betterclaw: background services started");
+        diagnosticLogger.info("plugin.service", "started", "background services started", { analysisHour: config.analysisHour });
       },
       stop: () => {
         patternEngine.stopSchedule();
-        api.logger.info("betterclaw: background services stopped");
+        diagnosticLogger.info("plugin.service", "stopped", "background services stopped");
       },
     });
 

package/src/learner.ts

@@ -1,10 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { EventLogEntry, TriageProfile, ReactionEntry } from "./types.js";
+import { errorMessage, noopLogger, type EventLogEntry, type PluginModuleLogger, type TriageProfile, type ReactionEntry } from "./types.js";
 import type { EventLog } from "./events.js";
 import type { ContextManager } from "./context.js";
 import type { ReactionTracker } from "./reactions.js";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { dlog } from "./diagnostic-logger.js";
 
 export async function readMemorySummary(workspaceDir: string, date: Date): Promise<string | null> {
   const y = date.getFullYear();
@@ -97,9 +98,16 @@ export async function loadTriageProfile(stateDir: string): Promise<TriageProfile
   }
 }
 
-export async function saveTriageProfile(stateDir: string, profile: TriageProfile): Promise<void> {
-  await fs.mkdir(stateDir, { recursive: true });
-  await fs.writeFile(path.join(stateDir, "triage-profile.json"), JSON.stringify(profile, null, 2), "utf-8");
+
+export async function saveTriageProfile(stateDir: string, profile: TriageProfile, logger: PluginModuleLogger = noopLogger): Promise<boolean> {
+  try {
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.writeFile(path.join(stateDir, "triage-profile.json"), JSON.stringify(profile, null, 2), "utf-8");
+    return true;
+  } catch (err) {
+    logger.error(`triage profile save failed: ${errorMessage(err)}`);
+    return false;
+  }
 }
 
 export interface RunLearnerDeps {
@@ -133,6 +141,13 @@ export async function runLearner(deps: RunLearnerDeps): Promise<void> {
   const patterns = await context.readPatterns();
   const patternsJson = JSON.stringify(patterns ?? {});
 
+  dlog.info("plugin.learner", "learner.started", "daily learner run started", {
+    eventsCount: recentEvents.length,
+    reactionsCount: recentReactions.length,
+    hasMemory: memorySummary !== null,
+    hasPreviousProfile: previousProfile !== null,
+  });
+
   // 6. Build prompt (include JSON-only instruction since extraSystemPrompt is not a valid SDK param)
   const prompt = buildLearnerPrompt({
     memorySummary,
@@ -147,6 +162,7 @@ export async function runLearner(deps: RunLearnerDeps): Promise<void> {
 
   // 8. Run subagent with try/finally for session cleanup
   let newProfile: TriageProfile | null = null;
+  let content: string | null = null;
   try {
     const { runId } = await api.runtime.subagent.run({
       sessionKey: "betterclaw-learn",
@@ -167,7 +183,7 @@ export async function runLearner(deps: RunLearnerDeps): Promise<void> {
     // 11. Parse last assistant message — handle both string and content-block formats
     const lastAssistant = (messages as any[]).filter((m) => m.role === "assistant").pop();
     if (lastAssistant) {
-      const content = typeof lastAssistant.content === "string"
+      content = typeof lastAssistant.content === "string"
         ? lastAssistant.content
         : Array.isArray(lastAssistant.content)
           ? lastAssistant.content.filter((b: any) => b.type === "text").map((b: any) => b.text).join("")
@@ -182,8 +198,17 @@ export async function runLearner(deps: RunLearnerDeps): Promise<void> {
   }
 
   // 13. Save if valid
+  if (!newProfile && content) {
+    dlog.warn("plugin.learner", "parse.failed", "failed to parse triage profile from LLM response", {
+      rawContent: content.slice(0, 200),
+    });
+  }
   if (newProfile) {
-    await saveTriageProfile(stateDir, newProfile);
+    await saveTriageProfile(stateDir, newProfile, api.logger);
+    dlog.info("plugin.learner", "profile.updated", "triage profile updated", {
+      summary: newProfile.summary,
+      interruptionTolerance: newProfile.interruptionTolerance,
+    });
   }
 
   // 14. Rotate old reactions

package/src/patterns.ts

@@ -1,22 +1,25 @@
 import type { ContextManager } from "./context.js";
 import type { EventLog } from "./events.js";
-import type { EventLogEntry, Patterns } from "./types.js";
+import { errorMessage, noopLogger, type EventLogEntry, type Patterns, type PluginModuleLogger } from "./types.js";
+import { dlog } from "./diagnostic-logger.js";
 
 export class PatternEngine {
   private context: ContextManager;
   private events: EventLog;
   private windowDays: number;
   private timer: ReturnType<typeof setTimeout> | null = null;
+  private logger: PluginModuleLogger;
 
-  constructor(context: ContextManager, events: EventLog, windowDays: number) {
+  constructor(context: ContextManager, events: EventLog, windowDays: number, logger?: PluginModuleLogger) {
     this.context = context;
     this.events = events;
     this.windowDays = windowDays;
+    this.logger = logger ?? noopLogger;
   }
 
   startSchedule(analysisHour: number, dailyCallback?: () => Promise<void>): void {
     // Run initial compute on startup
-    void this.compute().catch(() => {});
+    void this.compute().catch((err) => { this.logger.warn(`initial pattern compute failed: ${errorMessage(err)}`); });
 
     this.scheduleNext(analysisHour, dailyCallback);
   }
@@ -34,8 +37,8 @@ export class PatternEngine {
       try {
         await this.compute();
         if (dailyCallback) await dailyCallback();
-      } catch {
-        // ignore errors, will retry next day
+      } catch (err) {
+        this.logger.warn(`scheduled pattern compute failed: ${errorMessage(err)}`);
       }
       this.scheduleNext(analysisHour, dailyCallback);
     }, msUntil);
@@ -63,6 +66,11 @@ export class PatternEngine {
 
     await this.context.writePatterns(patterns);
 
+    dlog.info("plugin.patterns", "compute.completed", "pattern compute finished", {
+      eventsProcessed: entries.length,
+      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    });
+
     // Rotate event log if needed
     await this.events.rotate();
 

package/src/pipeline.ts

@@ -4,9 +4,11 @@ import type { EventLog } from "./events.js";
 import type { RulesEngine } from "./filter.js";
 import type { ReactionTracker } from "./reactions.js";
 import type { DeviceEvent, DeviceContext, PluginConfig } from "./types.js";
+import { errorMessage } from "./types.js";
 import { triageEvent } from "./triage.js";
 import { loadTriageProfile } from "./learner.js";
 import { requireEntitlement } from "./jwt.js";
+import { dlog } from "./diagnostic-logger.js";
 
 export interface PipelineDeps {
   api: OpenClawPluginApi;
@@ -21,13 +23,15 @@ export interface PipelineDeps {
 export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Promise<void> {
   const { api, config, context, events, rules } = deps;
 
+  dlog.info("plugin.pipeline", "event.received", "incoming device event", { subscriptionId: event.subscriptionId, source: event.source });
+
   // Always update context (even for non-premium users)
   context.updateFromEvent(event);
   await context.save();
 
   // Tier gate: free users get store-only path — no triage, no push
   if (context.getRuntimeState().tier === "free") {
-    api.logger.info(`betterclaw: event stored (free tier)`);
+    dlog.info("plugin.pipeline", "event.free_stored", "event stored (free tier)", { subscriptionId: event.subscriptionId });
     await events.append({ event, decision: "free_stored", reason: "free tier", timestamp: Date.now() / 1000 });
     return;
   }
@@ -35,7 +39,8 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
   // Gate event forwarding behind premium entitlement (security boundary)
   const entitlementError = requireEntitlement("premium");
   if (entitlementError) {
-    api.logger.info(`betterclaw: event blocked (no premium entitlement)`);
+    dlog.info("plugin.pipeline", "event.blocked", "event blocked (no premium entitlement)", { subscriptionId: event.subscriptionId });
+    await events.append({ event, decision: "blocked", reason: "no premium entitlement", timestamp: Date.now() / 1000 });
     return;
   }
 
@@ -77,7 +82,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
       const pushed = await pushToAgent(deps, event, `triage: ${triageResult.reason}`, message);
 
       if (pushed) {
-        rules.recordFired(event.subscriptionId, event.firedAt);
+        rules.recordFired(event.subscriptionId, event.firedAt, event.data);
         context.recordPush();
         deps.reactions.recordPush({
           subscriptionId: event.subscriptionId,
@@ -85,6 +90,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
           pushedAt: Date.now() / 1000,
           messageSummary: message.slice(0, 100),
         });
+        dlog.info("plugin.pipeline", "push.decided", "event pushed to agent via triage", { subscriptionId: event.subscriptionId, decision: "push", reason: `triage: ${triageResult.reason}` });
       }
 
       await events.append({
@@ -94,6 +100,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
         timestamp: Date.now() / 1000,
       });
     } else {
+      dlog.info("plugin.pipeline", "push.decided", `triage drop: ${triageResult.reason}`, { subscriptionId: event.subscriptionId, decision: "drop", reason: `triage: ${triageResult.reason}` });
       await events.append({
         event,
         decision: "drop",
@@ -112,7 +119,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
     const pushed = await pushToAgent(deps, event, decision.reason, message);
 
     if (pushed) {
-      rules.recordFired(event.subscriptionId, event.firedAt);
+      rules.recordFired(event.subscriptionId, event.firedAt, event.data);
       context.recordPush();
       deps.reactions.recordPush({
         subscriptionId: event.subscriptionId,
@@ -120,6 +127,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
         pushedAt: Date.now() / 1000,
         messageSummary: message.slice(0, 100),
       });
+      dlog.info("plugin.pipeline", "push.decided", "event pushed to agent", { subscriptionId: event.subscriptionId, decision: "push", reason: decision.reason });
     }
 
     await events.append({
@@ -135,7 +143,7 @@ export async function processEvent(deps: PipelineDeps, event: DeviceEvent): Prom
       reason: decision.reason,
       timestamp: Date.now() / 1000,
     });
-    api.logger.info(`betterclaw: drop event ${event.subscriptionId}: ${decision.reason}`);
+    dlog.info("plugin.pipeline", "push.decided", "event dropped", { subscriptionId: event.subscriptionId, decision: "drop", reason: decision.reason });
   }
 
   // Persist context and reactions
@@ -153,12 +161,11 @@ async function pushToAgent(deps: PipelineDeps, event: DeviceEvent, reason: strin
       deliver: false,
       idempotencyKey,
     });
-    deps.api.logger.info(`betterclaw: pushed event ${event.subscriptionId} to agent`);
+    dlog.info("plugin.pipeline", "push.sent", "event pushed to agent", { subscriptionId: event.subscriptionId });
     return true;
   } catch (err) {
-    deps.api.logger.error(
-      `betterclaw: failed to push to agent: ${err instanceof Error ? err.message : String(err)}`,
-    );
+    const msg = errorMessage(err);
+    dlog.error("plugin.pipeline", "push.failed", "failed to push event to agent", { subscriptionId: event.subscriptionId, error: msg });
     return false;
   }
 }

package/src/reaction-scanner.ts

@@ -1,6 +1,8 @@
 import type { ReactionStatus } from "./types.js";
 import type { ReactionTracker } from "./reactions.js";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { errorMessage } from "./types.js";
+import { dlog } from "./diagnostic-logger.js";
 
 // --- Types ---
 
@@ -133,13 +135,16 @@ export function parseClassificationResponse(text: string): ClassificationResult
 export async function scanPendingReactions(deps: ScanDeps): Promise<void> {
   const { api, reactions } = deps;
 
+  let classified = 0;
+  let skipped = 0;
+
   const pending = reactions.getPending();
   if (pending.length === 0) {
-    api.logger.info("reaction-scanner: no pending reactions to classify");
+    dlog.debug("plugin.reactions", "scan.empty", "no pending reactions to classify");
     return;
   }
 
-  api.logger.info(`reaction-scanner: scanning ${pending.length} pending reaction(s)`);
+  dlog.info("plugin.reactions", "scan.started", "scanning pending reactions", { pendingCount: pending.length });
 
   // Fetch session messages once (limit 200) to search through
   let messages: Array<{ role: string; content: unknown; timestamp?: number }> = [];
@@ -150,9 +155,8 @@ export async function scanPendingReactions(deps: ScanDeps): Promise<void> {
     });
     messages = fetched as typeof messages;
   } catch (err) {
-    api.logger.error(
-      `reaction-scanner: failed to fetch session messages: ${err instanceof Error ? err.message : String(err)}`,
-    );
+    const msg = errorMessage(err);
+    dlog.error("plugin.reactions", "scan.error", "failed to fetch session messages", { error: msg });
     return;
   }
 
@@ -161,9 +165,8 @@ export async function scanPendingReactions(deps: ScanDeps): Promise<void> {
       // 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`,
-        );
+        skipped++;
+        dlog.info("plugin.reactions", "scan.skipped", "no transcript match for reaction", { subscriptionId: reaction.subscriptionId, pushedAt: reaction.pushedAt });
         continue;
       }
 
@@ -214,22 +217,16 @@ export async function scanPendingReactions(deps: ScanDeps): Promise<void> {
         classificationResult.reason,
       );
 
-      api.logger.info(
-        `reaction-scanner: classified ${reaction.subscriptionId} as "${classificationResult.status}" — ${classificationResult.reason}`,
-      );
+      classified++;
+      dlog.info("plugin.reactions", "classified", "reaction classified", { subscriptionId: reaction.subscriptionId, status: classificationResult.status, reason: classificationResult.reason });
     } catch (err) {
-      api.logger.error(
-        `reaction-scanner: error classifying ${reaction.subscriptionId}: ${err instanceof Error ? err.message : String(err)}`,
-      );
+      const msg = errorMessage(err);
+      dlog.error("plugin.reactions", "classified.error", "error classifying reaction", { subscriptionId: reaction.subscriptionId, error: msg });
     }
   }
 
-  // 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)}`,
-    );
-  }
+  dlog.info("plugin.reactions", "scan.completed", "reaction scan finished", { classified, skipped });
+
+  // Persist updated reactions (save is self-catching)
+  await reactions.save();
 }

package/src/reactions.ts

@@ -1,13 +1,15 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { ReactionEntry, ReactionStatus } from "./types.js";
+import { errorMessage, noopLogger, type PluginModuleLogger, type ReactionEntry, type ReactionStatus } from "./types.js";
 
 export class ReactionTracker {
   private reactions: ReactionEntry[] = [];
   private filePath: string;
+  private logger: PluginModuleLogger;
 
-  constructor(stateDir: string) {
+  constructor(stateDir: string, logger?: PluginModuleLogger) {
     this.filePath = path.join(stateDir, "push-reactions.jsonl");
+    this.logger = logger ?? noopLogger;
   }
 
   recordPush(entry: { subscriptionId: string; source: string; pushedAt: number; messageSummary: string }): void {
@@ -49,10 +51,16 @@ export class ReactionTracker {
     return this.reactions.filter((r) => r.status !== "pending" && 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 save(): Promise<boolean> {
+    try {
+      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");
+      return true;
+    } catch (err) {
+      this.logger.error(`reactions save failed: ${errorMessage(err)}`);
+      return false;
+    }
   }
 
   async load(): Promise<void> {

package/src/tools/get-context.ts

@@ -1,12 +1,55 @@
 import type { ContextManager } from "../context.js";
 import { loadTriageProfile } from "../learner.js";
 
+// Per-field staleness thresholds (seconds)
+// Location: updates every ~60s on movement, 10 min threshold
+// Battery: updates every 10 min, 15 min threshold
+// Health: updates every 30 min, 60 min threshold
+const STALE_THRESHOLDS: Record<string, number> = {
+  location: 600,
+  battery: 900,
+  health: 3600,
+};
+
+/** Format seconds into human-readable age string */
+export function formatAge(seconds: number): string {
+  const clamped = Math.max(0, seconds);
+  if (clamped < 60) return `${Math.round(clamped)}s ago`;
+  if (clamped < 3600) return `${Math.round(clamped / 60)}m ago`;
+  if (clamped < 86400) return `${Math.round(clamped / 3600)}h ago`;
+  return `${Math.round(clamped / 86400)}d ago`;
+}
+
+/**
+ * On premium, stale device data is replaced with a pointer to the fresh
+ * node command. Null age is treated as stale on premium (no timestamp =
+ * can't verify freshness).
+ */
+function deviceFieldOrPointer(
+  data: Record<string, unknown> | null,
+  ageSeconds: number | null,
+  freshCommand: string,
+  isPremium: boolean,
+  field: string,
+): Record<string, unknown> | null {
+  if (!data) return null;
+  const threshold = STALE_THRESHOLDS[field] ?? 600;
+  if (isPremium && (ageSeconds == null || ageSeconds > threshold)) {
+    return {
+      stale: true,
+      ageHuman: ageSeconds != null ? formatAge(ageSeconds) : "unknown",
+      freshCommand,
+    };
+  }
+  return { ...data, dataAgeSeconds: ageSeconds };
+}
+
 export function createGetContextTool(ctx: ContextManager, stateDir?: string) {
   return {
     name: "get_context",
     label: "Get Device Context",
     description:
-      "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.",
+      "Get BetterClaw context — patterns, trends, activity zone, and event history. On premium, stale device readings are hidden — use node commands (location.get, device.battery, health.*) for current data. On free, this includes the full device snapshot.",
     parameters: {},
     async execute(_id: string, _params: Record<string, unknown>) {
       const state = ctx.get();
@@ -20,22 +63,34 @@ export function createGetContextTool(ctx: ContextManager, stateDir?: string) {
         tierHint: {
           tier: runtime.tier,
           note: isPremium
-            ? "Node commands available for fresh readings (location.get, device.battery, health.*)"
+            ? "Node commands available for fresh readings (location.get, device.battery, health.*). Stale device data is hidden — call the node command instead."
             : "This is the only data source on free tier — check dataAgeSeconds for freshness",
         },
         smartMode: runtime.smartMode,
       };
 
       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,
+        battery: deviceFieldOrPointer(
+          state.device.battery as unknown as Record<string, unknown>,
+          dataAge.battery,
+          "device.battery",
+          isPremium,
+          "battery",
+        ),
+        location: deviceFieldOrPointer(
+          state.device.location as unknown as Record<string, unknown>,
+          dataAge.location,
+          "location.get",
+          isPremium,
+          "location",
+        ),
+        health: deviceFieldOrPointer(
+          state.device.health as unknown as Record<string, unknown>,
+          dataAge.health,
+          "health.summary",
+          isPremium,
+          "health",
+        ),
       };
 
       result.activity = { ...state.activity, updatedAt: ctx.getTimestamp("activity") };

package/src/triage.ts

@@ -1,5 +1,7 @@
 import type { DeviceEvent, TriageProfile } from "./types.js";
+import { errorMessage } from "./types.js";
 import type { ContextManager } from "./context.js";
+import { dlog } from "./diagnostic-logger.js";
 
 export interface TriageResult {
   push: boolean;
@@ -76,6 +78,11 @@ export async function triageEvent(
   config: { triageModel: string; triageApiBase?: string; budgetUsed?: number; budgetTotal?: number },
   resolveApiKey: () => Promise<string | undefined>,
 ): Promise<TriageResult> {
+  dlog.info("plugin.triage", "triage.called", "sending triage request", {
+    subscriptionId: event.subscriptionId,
+    model: config.triageModel,
+  });
+
   const prompt = buildTriagePrompt(event, context, profile,
     config.budgetUsed != null && config.budgetTotal != null
       ? { budgetUsed: config.budgetUsed, budgetTotal: config.budgetTotal }
@@ -136,8 +143,19 @@ export async function triageEvent(
       return { push: false, reason: "empty triage response — defaulting to drop" };
     }
 
-    return parseTriageResponse(content);
+    const result = parseTriageResponse(content);
+    dlog.info("plugin.triage", "triage.result", `triage decision: ${result.push ? "push" : "drop"}`, {
+      subscriptionId: event.subscriptionId,
+      decision: result.push ? "push" : "drop",
+      reason: result.reason,
+    });
+    return result;
   } catch (err) {
+    dlog.error("plugin.triage", "triage.fallback", `triage failed, falling back to drop: ${errorMessage(err)}`, {
+      subscriptionId: event.subscriptionId,
+      error: errorMessage(err),
+      fallbackAction: "drop",
+    });
     return { push: false, reason: `triage call failed: ${err} — defaulting to drop` };
   }
 }

package/src/types.ts

@@ -1,3 +1,35 @@
+/**
+ * Minimal logger interface for plugin modules. Compatible with the SDK's PluginLogger.
+ *
+ * All stateful modules (EventLog, ContextManager, ReactionTracker, PatternEngine) accept
+ * an optional PluginModuleLogger in their constructor. Write operations (save, append,
+ * rotate, writePatterns) catch errors internally, log via this logger, and return boolean.
+ * Callers do NOT need try/catch around write calls — the module handles it.
+ */
+export type PluginModuleLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+/** Shared noop logger for modules and tests. Use when logging is not needed. */
+export const noopLogger: PluginModuleLogger = { info: () => {}, warn: () => {}, error: () => {} };
+
+/** Extract error message from unknown catch parameter. */
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Structured log entry for diagnostic JSONL files. */
+export interface PluginLogEntry {
+  timestamp: number;
+  level: "debug" | "info" | "warn" | "error";
+  source: string;
+  event: string;
+  message: string;
+  data?: Record<string, unknown>;
+}
+
 // -- Incoming event from iOS --
 
 export interface DeviceEvent {
@@ -76,7 +108,7 @@ export type FilterDecision =
 
 export interface EventLogEntry {
   event: DeviceEvent;
-  decision: "push" | "drop" | "stored" | "free_stored";
+  decision: "push" | "drop" | "stored" | "free_stored" | "blocked" | "error";
   reason: string;
   timestamp: number;
 }