@better_openclaw/betteremail 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,53 @@
+{
+  "id": "betteremail",
+  "name": "BetterEmail Digest",
+  "description": "Intelligent email digest — polls Gmail, deduplicates, classifies importance, exposes digest to agent",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "accounts": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": []
+      },
+      "pollIntervalMinutes": {
+        "type": "object",
+        "properties": {
+          "workHours": { "type": "number", "default": 5 },
+          "offHours": { "type": "number", "default": 30 }
+        },
+        "default": { "workHours": 5, "offHours": 30 }
+      },
+      "workHours": {
+        "type": "object",
+        "properties": {
+          "start": { "type": "number", "default": 9 },
+          "end": { "type": "number", "default": 18 },
+          "timezone": { "type": "string", "default": "Europe/London" }
+        },
+        "default": { "start": 9, "end": 18, "timezone": "Europe/London" }
+      },
+      "classifierTimeoutMs": {
+        "type": "number",
+        "default": 30000
+      },
+      "consecutiveFailuresBeforeAlert": {
+        "type": "number",
+        "default": 3
+      },
+      "rescanDaysOnHistoryReset": {
+        "type": "number",
+        "default": 7
+      }
+    }
+  },
+  "uiHints": {
+    "accounts": { "label": "Gmail accounts to poll", "placeholder": "user@gmail.com" },
+    "pollIntervalMinutes": { "label": "Poll intervals (minutes)" },
+    "workHours": { "label": "Work hours schedule" },
+    "classifierTimeoutMs": { "label": "Classifier timeout (ms)" },
+    "consecutiveFailuresBeforeAlert": { "label": "Failures before alerting agent" }
+  }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@better_openclaw/betteremail",
+  "version": "0.1.0",
+  "description": "Email digest plugin for OpenClaw — polls Gmail, deduplicates, classifies importance, exposes digest to agent",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}

package/src/classifier.ts

@@ -0,0 +1,158 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { TrimmedEmail, ClassificationResult } from "./types.js";
+
+type RunEmbeddedPiAgentFn = (opts: Record<string, unknown>) => Promise<{ payloads?: unknown[] }>;
+
+let _runFn: RunEmbeddedPiAgentFn | null = null;
+
+async function loadRunEmbeddedPiAgent(): Promise<RunEmbeddedPiAgentFn> {
+  if (_runFn) return _runFn;
+  const mod = await import("../../../src/agents/pi-embedded.js").catch(() =>
+    import("openclaw/agents/pi-embedded"),
+  );
+  if (typeof (mod as any).runEmbeddedPiAgent !== "function") {
+    throw new Error("runEmbeddedPiAgent not available");
+  }
+  _runFn = (mod as any).runEmbeddedPiAgent as RunEmbeddedPiAgentFn;
+  return _runFn;
+}
+
+export function buildClassifierPrompt(emails: TrimmedEmail[]): string {
+  const emailSummaries = emails.map((e) => ({
+    id: e.id,
+    from: e.from,
+    to: e.to,
+    subject: e.subject,
+    date: e.date,
+    body: e.body,
+    account: e.account,
+    threadLength: e.threadLength,
+    hasAttachments: e.hasAttachments,
+  }));
+
+  return [
+    "You are triaging emails for the user. For each email, decide:",
+    '- importance: "high" | "medium" | "low"',
+    "- reason: one sentence explaining why",
+    "- notify: boolean (should the user be interrupted for this?)",
+    "",
+    "Consider: sender relationship, urgency signals, whether it requires action,",
+    "time sensitivity, financial/legal implications, personal importance.",
+    "",
+    "Respond with ONLY a valid JSON array. Each element must have: id, importance, reason, notify.",
+    "",
+    `Emails to triage (${emails.length}):`,
+    JSON.stringify(emailSummaries, null, 2),
+  ].join("\n");
+}
+
+function extractText(payloads: unknown[]): string {
+  for (const p of payloads) {
+    if (typeof p === "string") return p;
+    if (p && typeof p === "object" && "text" in p && typeof (p as any).text === "string") {
+      return (p as any).text;
+    }
+    if (p && typeof p === "object" && "content" in p && Array.isArray((p as any).content)) {
+      for (const c of (p as any).content) {
+        if (c && typeof c.text === "string") return c.text;
+      }
+    }
+  }
+  return "";
+}
+
+function failOpenDefaults(emailIds: string[]): ClassificationResult[] {
+  return emailIds.map((id) => ({
+    id,
+    importance: "high" as const,
+    reason: "classification failed — fail open",
+    notify: true,
+  }));
+}
+
+export function parseClassifierResponse(text: string, emailIds: string[]): ClassificationResult[] {
+  if (!text || !text.trim()) return failOpenDefaults(emailIds);
+
+  const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+
+  try {
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed)) return failOpenDefaults(emailIds);
+
+    const resultsMap = new Map<string, ClassificationResult>();
+    for (const item of parsed) {
+      if (item && typeof item.id === "string") {
+        resultsMap.set(item.id, {
+          id: item.id,
+          importance: ["high", "medium", "low"].includes(item.importance) ? item.importance : "high",
+          reason: typeof item.reason === "string" ? item.reason : "no reason given",
+          notify: typeof item.notify === "boolean" ? item.notify : true,
+        });
+      }
+    }
+
+    return emailIds.map(
+      (id) =>
+        resultsMap.get(id) ?? {
+          id,
+          importance: "high" as const,
+          reason: "missing from classifier response — fail open",
+          notify: true,
+        },
+    );
+  } catch {
+    return failOpenDefaults(emailIds);
+  }
+}
+
+export class Classifier {
+  private api: OpenClawPluginApi;
+  private timeoutMs: number;
+
+  constructor(api: OpenClawPluginApi, timeoutMs: number) {
+    this.api = api;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async classify(emails: TrimmedEmail[]): Promise<ClassificationResult[]> {
+    if (emails.length === 0) return [];
+
+    const prompt = buildClassifierPrompt(emails);
+    const emailIds = emails.map((e) => e.id);
+
+    let tmpDir: string | null = null;
+    try {
+      tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "betteremail-classify-"));
+      const sessionFile = path.join(tmpDir, "session.json");
+
+      const runEmbeddedPiAgent = await loadRunEmbeddedPiAgent();
+
+      const result = await runEmbeddedPiAgent({
+        sessionId: `betteremail-classifier-${Date.now()}`,
+        sessionFile,
+        workspaceDir: (this.api as any).config?.agents?.defaults?.workspace ?? process.cwd(),
+        config: (this.api as any).config,
+        prompt,
+        timeoutMs: this.timeoutMs,
+        runId: `betteremail-classify-${Date.now()}`,
+        disableTools: true,
+        skillsSnapshot: (this.api as any).skillsSnapshot ?? undefined,
+      });
+
+      const text = extractText(result.payloads ?? []);
+      return parseClassifierResponse(text, emailIds);
+    } catch (err) {
+      this.api.logger.error(
+        `betteremail: classifier failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return failOpenDefaults(emailIds);
+    } finally {
+      if (tmpDir) {
+        try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch {}
+      }
+    }
+  }
+}

package/src/commands/emails.ts

@@ -0,0 +1,61 @@
+import type { DigestManager } from "../digest.js";
+
+export function createEmailsCommandHandler(digest: DigestManager) {
+  return () => {
+    const grouped = digest.getGroupedByAccount("all");
+    const lines: string[] = [];
+
+    lines.push("Email Digest");
+    lines.push("\u2500".repeat(40));
+
+    let hasContent = false;
+
+    for (const [account, entries] of Object.entries(grouped)) {
+      const newEntries = entries.filter((e) => e.status === "new");
+      const surfaced = entries.filter((e) => e.status === "surfaced");
+      const deferred = entries.filter((e) => e.status === "deferred");
+      const handledToday = entries.filter(
+        (e) => e.status === "handled" && e.resolvedAt &&
+          new Date(e.resolvedAt).toDateString() === new Date().toDateString(),
+      );
+
+      const active = [...newEntries, ...surfaced];
+      if (active.length === 0 && deferred.length === 0) {
+        lines.push(`\n${account} — nothing new`);
+        continue;
+      }
+
+      hasContent = true;
+      lines.push(`\n${account} (${newEntries.length} new)`);
+
+      for (const entry of active) {
+        const imp = entry.importance === "high" ? "[HIGH]" : "[MED] ";
+        const age = formatAge(entry.firstSeenAt);
+        lines.push(`  ${imp} ${entry.subject} from ${entry.from} — ${age}`);
+      }
+
+      if (deferred.length > 0) {
+        lines.push(`  ${deferred.length} deferred`);
+      }
+      if (handledToday.length > 0) {
+        lines.push(`  ${handledToday.length} handled today`);
+      }
+    }
+
+    if (!hasContent) {
+      lines.push("\nNo pending emails across all accounts.");
+    }
+
+    return { text: lines.join("\n") };
+  };
+}
+
+function formatAge(isoDate: string): string {
+  const ms = Date.now() - new Date(isoDate).getTime();
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/src/digest.ts

@@ -0,0 +1,108 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { DigestEntry, DigestState, DigestStatus } from "./types.js";
+
+const DIGEST_FILE = "digest.json";
+
+export class DigestManager {
+  private filePath: string;
+  private state: DigestState;
+
+  constructor(stateDir: string) {
+    this.filePath = path.join(stateDir, DIGEST_FILE);
+    this.state = { entries: {} };
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      this.state = JSON.parse(raw) as DigestState;
+    } catch {
+      this.state = { entries: {} };
+    }
+  }
+
+  async save(): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    await fs.writeFile(this.filePath, JSON.stringify(this.state, null, 2) + "\n", "utf8");
+  }
+
+  add(entry: DigestEntry): void {
+    this.state.entries[entry.id] = entry;
+  }
+
+  get(id: string): DigestEntry | undefined {
+    return this.state.entries[id];
+  }
+
+  has(id: string): boolean {
+    return id in this.state.entries;
+  }
+
+  getByStatus(status: DigestStatus | "all"): DigestEntry[] {
+    const entries = Object.values(this.state.entries);
+    if (status === "all") return entries;
+    return entries.filter((e) => e.status === status);
+  }
+
+  getGroupedByAccount(status: DigestStatus | "all"): Record<string, DigestEntry[]> {
+    const entries = this.getByStatus(status);
+    const grouped: Record<string, DigestEntry[]> = {};
+    for (const entry of entries) {
+      if (!grouped[entry.account]) grouped[entry.account] = [];
+      grouped[entry.account].push(entry);
+    }
+    return grouped;
+  }
+
+  getActiveThreadIds(): DigestEntry[] {
+    return Object.values(this.state.entries).filter(
+      (e) => e.status === "surfaced" || e.status === "deferred",
+    );
+  }
+
+  markSurfaced(id: string): void {
+    const entry = this.state.entries[id];
+    if (entry) {
+      entry.status = "surfaced";
+      entry.surfacedAt = new Date().toISOString();
+    }
+  }
+
+  markHandled(id: string): void {
+    const entry = this.state.entries[id];
+    if (entry) {
+      entry.status = "handled";
+      entry.resolvedAt = new Date().toISOString();
+    }
+  }
+
+  defer(id: string, minutes: number): void {
+    const entry = this.state.entries[id];
+    if (entry) {
+      entry.status = "deferred";
+      entry.deferredUntil = new Date(Date.now() + minutes * 60_000).toISOString();
+    }
+  }
+
+  dismiss(id: string): void {
+    const entry = this.state.entries[id];
+    if (entry) {
+      entry.status = "dismissed";
+      entry.resolvedAt = new Date().toISOString();
+    }
+  }
+
+  expireDeferrals(): DigestEntry[] {
+    const now = new Date();
+    const expired: DigestEntry[] = [];
+    for (const entry of Object.values(this.state.entries)) {
+      if (entry.status === "deferred" && entry.deferredUntil && new Date(entry.deferredUntil) <= now) {
+        entry.status = "new";
+        entry.deferredUntil = undefined;
+        expired.push(entry);
+      }
+    }
+    return expired;
+  }
+}

package/src/email-log.ts

@@ -0,0 +1,53 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { EmailLogEntry } from "./types.js";
+
+const EMAILS_FILE = "emails.jsonl";
+const DEFAULT_MAX_LINES = 10_000;
+const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+export class EmailLog {
+  private filePath: string;
+
+  constructor(stateDir: string) {
+    this.filePath = path.join(stateDir, EMAILS_FILE);
+  }
+
+  async append(entry: EmailLogEntry): 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 readAll(): Promise<EmailLogEntry[]> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8");
+      return raw
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line) as EmailLogEntry);
+    } catch {
+      return [];
+    }
+  }
+
+  async hasMessageId(id: string): Promise<boolean> {
+    const all = await this.readAll();
+    return all.some((e) => e.email.id === id);
+  }
+
+  async rotate(maxLines: number = DEFAULT_MAX_LINES): Promise<number> {
+    const entries = await this.readAll();
+    if (entries.length <= maxLines) return 0;
+
+    const cutoff = Date.now() / 1000 - MAX_AGE_MS / 1000;
+    const kept = entries.filter((e) => e.timestamp >= cutoff).slice(-maxLines);
+    const removed = entries.length - kept.length;
+
+    const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    await fs.writeFile(this.filePath, content, "utf8");
+
+    return removed;
+  }
+}

package/src/index.ts

@@ -0,0 +1,146 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { PluginConfig } from "./types.js";
+import { DigestManager } from "./digest.js";
+import { EmailLog } from "./email-log.js";
+import { Poller } from "./poller.js";
+import { Classifier } from "./classifier.js";
+import { Scheduler } from "./scheduler.js";
+import { runPipeline } from "./pipeline.js";
+import { createGetEmailDigestTool } from "./tools/get-email-digest.js";
+import { createMarkEmailHandledTool } from "./tools/mark-email-handled.js";
+import { createDeferEmailTool } from "./tools/defer-email.js";
+import { createDismissEmailTool } from "./tools/dismiss-email.js";
+import { createEmailsCommandHandler } from "./commands/emails.js";
+
+const DEFAULT_CONFIG: PluginConfig = {
+  accounts: [],
+  pollIntervalMinutes: { workHours: 5, offHours: 30 },
+  workHours: { start: 9, end: 18, timezone: "Europe/London" },
+  classifierTimeoutMs: 30_000,
+  consecutiveFailuresBeforeAlert: 3,
+  rescanDaysOnHistoryReset: 7,
+};
+
+function resolveConfig(raw: Record<string, unknown> | undefined): PluginConfig {
+  return {
+    accounts: Array.isArray(raw?.accounts) ? (raw.accounts as string[]) : DEFAULT_CONFIG.accounts,
+    pollIntervalMinutes:
+      raw?.pollIntervalMinutes && typeof raw.pollIntervalMinutes === "object"
+        ? {
+            workHours: typeof (raw.pollIntervalMinutes as any).workHours === "number"
+              ? (raw.pollIntervalMinutes as any).workHours
+              : DEFAULT_CONFIG.pollIntervalMinutes.workHours,
+            offHours: typeof (raw.pollIntervalMinutes as any).offHours === "number"
+              ? (raw.pollIntervalMinutes as any).offHours
+              : DEFAULT_CONFIG.pollIntervalMinutes.offHours,
+          }
+        : DEFAULT_CONFIG.pollIntervalMinutes,
+    workHours:
+      raw?.workHours && typeof raw.workHours === "object"
+        ? {
+            start: typeof (raw.workHours as any).start === "number"
+              ? (raw.workHours as any).start
+              : DEFAULT_CONFIG.workHours.start,
+            end: typeof (raw.workHours as any).end === "number"
+              ? (raw.workHours as any).end
+              : DEFAULT_CONFIG.workHours.end,
+            timezone: typeof (raw.workHours as any).timezone === "string"
+              ? (raw.workHours as any).timezone
+              : DEFAULT_CONFIG.workHours.timezone,
+          }
+        : DEFAULT_CONFIG.workHours,
+    classifierTimeoutMs:
+      typeof raw?.classifierTimeoutMs === "number" ? raw.classifierTimeoutMs : DEFAULT_CONFIG.classifierTimeoutMs,
+    consecutiveFailuresBeforeAlert:
+      typeof raw?.consecutiveFailuresBeforeAlert === "number"
+        ? raw.consecutiveFailuresBeforeAlert
+        : DEFAULT_CONFIG.consecutiveFailuresBeforeAlert,
+    rescanDaysOnHistoryReset:
+      typeof raw?.rescanDaysOnHistoryReset === "number"
+        ? raw.rescanDaysOnHistoryReset
+        : DEFAULT_CONFIG.rescanDaysOnHistoryReset,
+  };
+}
+
+export default {
+  id: "betteremail",
+  name: "BetterEmail Digest",
+
+  register(api: OpenClawPluginApi) {
+    const config = resolveConfig(api.pluginConfig as Record<string, unknown> | undefined);
+    const stateDir = api.runtime.state.resolveStateDir();
+
+    api.logger.info(
+      `betteremail plugin loaded (accounts=${config.accounts.length}, ` +
+      `workHours=${config.pollIntervalMinutes.workHours}m, offHours=${config.pollIntervalMinutes.offHours}m)`,
+    );
+
+    if (config.accounts.length === 0) {
+      api.logger.warn("betteremail: no accounts configured — plugin will not poll");
+      return;
+    }
+
+    const digest = new DigestManager(stateDir);
+    const emailLog = new EmailLog(stateDir);
+    const poller = new Poller(api, stateDir, config.accounts, config.rescanDaysOnHistoryReset);
+    const classifier = new Classifier(api, config.classifierTimeoutMs);
+
+    let initialized = false;
+    const initPromise = (async () => {
+      try {
+        await digest.load();
+        await poller.loadState();
+        initialized = true;
+        api.logger.info("betteremail: async init complete");
+      } catch (err) {
+        api.logger.error(`betteremail: init failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    })();
+
+    api.registerTool(createGetEmailDigestTool(digest), { optional: true });
+    api.registerTool(createMarkEmailHandledTool(digest), { optional: true });
+    api.registerTool(createDeferEmailTool(digest), { optional: true });
+    api.registerTool(createDismissEmailTool(digest), { optional: true });
+
+    api.registerCommand({
+      name: "emails",
+      description: "Show current email digest status across all accounts",
+      handler: createEmailsCommandHandler(digest),
+    });
+
+    const runOnce = async () => {
+      if (!initialized) await initPromise;
+
+      await runPipeline({
+        accounts: config.accounts,
+        poller,
+        classifier,
+        digest,
+        emailLog,
+        logger: api.logger,
+        runCommand: (args, opts) => api.runtime.system.runCommandWithTimeout(args, opts),
+        consecutiveFailuresBeforeAlert: config.consecutiveFailuresBeforeAlert,
+      });
+
+      await emailLog.rotate();
+    };
+
+    const scheduler = new Scheduler(
+      config.pollIntervalMinutes,
+      config.workHours,
+      runOnce,
+    );
+
+    api.registerService({
+      id: "betteremail-poller",
+      start: () => {
+        scheduler.start();
+        api.logger.info("betteremail: polling service started");
+      },
+      stop: () => {
+        scheduler.stop();
+        api.logger.info("betteremail: polling service stopped");
+      },
+    });
+  },
+};

package/src/pipeline.ts

@@ -0,0 +1,179 @@
+import type { TrimmedEmail, ClassificationResult, DigestEntry, EmailLogEntry } from "./types.js";
+
+export interface PipelineDeps {
+  accounts: string[];
+  poller: {
+    loadState(): Promise<void>;
+    saveState(): Promise<void>;
+    pollAccount(account: string, seenMessageIds: Set<string>): Promise<TrimmedEmail[]>;
+    recordSuccess(account: string, historyId: string): void;
+    recordFailure(account: string): number;
+    getAccountState(account: string): { historyId: string; lastPollAt: string; consecutiveFailures: number } | undefined;
+    checkThreadForReply(threadId: string, account: string): Promise<boolean>;
+  };
+  classifier: {
+    classify(emails: TrimmedEmail[]): Promise<ClassificationResult[]>;
+  };
+  digest: {
+    load(): Promise<void>;
+    save(): Promise<void>;
+    add(entry: DigestEntry): void;
+    has(id: string): boolean;
+    getActiveThreadIds(): DigestEntry[];
+    expireDeferrals(): DigestEntry[];
+    markHandled(id: string): void;
+  };
+  emailLog: {
+    append(entry: EmailLogEntry): Promise<void>;
+    hasMessageId(id: string): Promise<boolean>;
+    readAll(): Promise<EmailLogEntry[]>;
+  };
+  logger: {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+  };
+  runCommand: (args: string[], opts: { timeoutMs: number }) => Promise<{ code: number; stdout?: string; stderr?: string }>;
+  consecutiveFailuresBeforeAlert: number;
+}
+
+const BATCH_SIZE = 10;
+
+export async function runPipeline(deps: PipelineDeps): Promise<void> {
+  const { accounts, poller, classifier, digest, emailLog, logger } = deps;
+
+  await poller.loadState();
+  await digest.load();
+
+  const expired = digest.expireDeferrals();
+  if (expired.length > 0) {
+    logger.info(`betteremail: ${expired.length} deferred email(s) re-entered digest`);
+  }
+
+  // Auto-resolve: re-check active threads for owner replies
+  const activeEntries = digest.getActiveThreadIds();
+  for (const entry of activeEntries) {
+    try {
+      const replied = await poller.checkThreadForReply(entry.threadId, entry.account);
+      if (replied) {
+        digest.markHandled(entry.id);
+        logger.info(`betteremail: auto-resolved ${entry.id} — owner replied`);
+      }
+    } catch {
+      // Non-critical — will retry next cycle
+    }
+  }
+
+  // Build seen IDs set from email log
+  const allLogEntries = await emailLog.readAll();
+  const seenIds = new Set(allLogEntries.map(e => e.email.id));
+
+  const allNewEmails: TrimmedEmail[] = [];
+
+  for (const account of accounts) {
+    try {
+      const emails = await poller.pollAccount(account, seenIds);
+      const filtered = emails.filter((e) => !digest.has(e.id));
+      allNewEmails.push(...filtered);
+      const currentState = poller.getAccountState(account);
+      poller.recordSuccess(account, currentState?.historyId ?? "");
+      logger.info(`betteremail: ${account} — ${emails.length} fetched, ${filtered.length} new`);
+    } catch (err) {
+      const failures = poller.recordFailure(account);
+      logger.error(`betteremail: poll failed for ${account}: ${err instanceof Error ? err.message : String(err)}`);
+
+      if (failures >= deps.consecutiveFailuresBeforeAlert) {
+        try {
+          await deps.runCommand(
+            [
+              "openclaw", "agent",
+              "--session-id", "main",
+              "--deliver",
+              "--message", `[BetterEmail] Gmail polling has failed ${failures} times in a row for ${account}. Likely auth token expiry — please re-authenticate gog.`,
+            ],
+            { timeoutMs: 30_000 },
+          );
+        } catch {
+          logger.error("betteremail: failed to alert agent about polling failures");
+        }
+      }
+    }
+  }
+
+  if (allNewEmails.length === 0) {
+    await digest.save();
+    await poller.saveState();
+    return;
+  }
+
+  for (let i = 0; i < allNewEmails.length; i += BATCH_SIZE) {
+    const batch = allNewEmails.slice(i, i + BATCH_SIZE);
+    const results = await classifier.classify(batch);
+
+    for (let j = 0; j < batch.length; j++) {
+      const email = batch[j];
+      const result = results[j];
+
+      await emailLog.append({
+        email,
+        importance: result.importance,
+        reason: result.reason,
+        notify: result.notify,
+        timestamp: Date.now() / 1000,
+      });
+
+      if (result.importance === "high" || result.importance === "medium") {
+        const entry: DigestEntry = {
+          id: email.id,
+          threadId: email.threadId,
+          account: email.account,
+          from: email.from,
+          subject: email.subject,
+          date: email.date,
+          body: email.body,
+          importance: result.importance,
+          reason: result.reason,
+          notify: result.notify,
+          status: "new",
+          firstSeenAt: new Date().toISOString(),
+        };
+        digest.add(entry);
+
+        if (result.importance === "high" && result.notify) {
+          const message = formatPushMessage(email, result);
+          try {
+            await deps.runCommand(
+              [
+                "openclaw", "agent",
+                "--session-id", "main",
+                "--deliver",
+                "--message", message,
+              ],
+              { timeoutMs: 30_000 },
+            );
+            logger.info(`betteremail: pushed ${email.id} to agent`);
+          } catch (err) {
+            logger.error(`betteremail: failed to push to agent: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      }
+    }
+  }
+
+  await digest.save();
+  await poller.saveState();
+}
+
+function formatPushMessage(email: TrimmedEmail, result: ClassificationResult): string {
+  return [
+    "[BetterEmail] New high-importance email:",
+    `From: ${email.from}`,
+    `Subject: ${email.subject}`,
+    `Account: ${email.account}`,
+    `Date: ${email.date}`,
+    `Reason: ${result.reason}`,
+    `MessageID: ${email.id}`,
+    "",
+    "Use defer_email to postpone or mark_email_handled when resolved.",
+  ].join("\n");
+}

package/src/poller.ts

@@ -0,0 +1,189 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { RawGogMessage, RawGogThread, PollState, TrimmedEmail } from "./types.js";
+import { trimEmailBody } from "./trimmer.js";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const STATE_FILE = "state.json";
+
+export function parseGogMessages(stdout: string): RawGogMessage[] {
+  if (!stdout || !stdout.trim()) return [];
+  try {
+    const parsed = JSON.parse(stdout.trim());
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === "object" && parsed.id) return [parsed];
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+export function parseGogThread(stdout: string): RawGogThread | null {
+  if (!stdout || !stdout.trim()) return null;
+  try {
+    const parsed = JSON.parse(stdout.trim());
+    if (parsed && parsed.id && Array.isArray(parsed.messages)) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function extractEmail(fromField: string): string {
+  const match = fromField.match(/<([^>]+)>/);
+  return (match ? match[1] : fromField).toLowerCase().trim();
+}
+
+export function detectOwnerReply(thread: RawGogThread, ownerAccounts: string[]): boolean {
+  const lowerAccounts = ownerAccounts.map((a) => a.toLowerCase());
+  return thread.messages.some((msg) => {
+    if (!msg.from) return false;
+    const email = extractEmail(msg.from);
+    return lowerAccounts.includes(email);
+  });
+}
+
+export class Poller {
+  private api: OpenClawPluginApi;
+  private stateDir: string;
+  private accounts: string[];
+  private rescanDays: number;
+  private state: PollState;
+
+  constructor(api: OpenClawPluginApi, stateDir: string, accounts: string[], rescanDays: number) {
+    this.api = api;
+    this.stateDir = stateDir;
+    this.accounts = accounts;
+    this.rescanDays = rescanDays;
+    this.state = { accounts: {}, lastClassifierRunAt: "" };
+  }
+
+  async loadState(): Promise<void> {
+    try {
+      const raw = await fs.readFile(path.join(this.stateDir, STATE_FILE), "utf8");
+      this.state = JSON.parse(raw) as PollState;
+    } catch {
+      this.state = { accounts: {}, lastClassifierRunAt: "" };
+    }
+  }
+
+  async saveState(): Promise<void> {
+    await fs.mkdir(this.stateDir, { recursive: true });
+    await fs.writeFile(
+      path.join(this.stateDir, STATE_FILE),
+      JSON.stringify(this.state, null, 2) + "\n",
+      "utf8",
+    );
+  }
+
+  getAccountState(account: string) {
+    return this.state.accounts[account];
+  }
+
+  recordSuccess(account: string, historyId: string): void {
+    this.state.accounts[account] = {
+      historyId,
+      lastPollAt: new Date().toISOString(),
+      consecutiveFailures: 0,
+    };
+  }
+
+  recordFailure(account: string): number {
+    const existing = this.state.accounts[account];
+    const failures = (existing?.consecutiveFailures ?? 0) + 1;
+    this.state.accounts[account] = {
+      historyId: existing?.historyId ?? "",
+      lastPollAt: existing?.lastPollAt ?? "",
+      consecutiveFailures: failures,
+    };
+    return failures;
+  }
+
+  async runGog(args: string[]): Promise<{ stdout: string; ok: boolean }> {
+    try {
+      const result = await this.api.runtime.system.runCommandWithTimeout(
+        ["gog", ...args],
+        { timeoutMs: 30_000 },
+      );
+      if (result.code !== 0) {
+        this.api.logger.warn(`betteremail: gog failed (code ${result.code}): ${result.stderr?.slice(0, 200)}`);
+        return { stdout: "", ok: false };
+      }
+      return { stdout: result.stdout ?? "", ok: true };
+    } catch (err) {
+      this.api.logger.error(`betteremail: gog error: ${err instanceof Error ? err.message : String(err)}`);
+      return { stdout: "", ok: false };
+    }
+  }
+
+  async checkThreadForReply(threadId: string, account: string): Promise<boolean> {
+    const result = await this.runGog([
+      "gmail", "thread", "get", threadId, "--account", account, "--json",
+    ]);
+    if (!result.ok) return false;
+    const thread = parseGogThread(result.stdout);
+    if (!thread) return false;
+    return detectOwnerReply(thread, this.accounts);
+  }
+
+  async pollAccount(account: string, seenMessageIds: Set<string>): Promise<TrimmedEmail[]> {
+    const accountState = this.state.accounts[account];
+    const historyId = accountState?.historyId;
+
+    let messages: RawGogMessage[];
+
+    if (historyId) {
+      const result = await this.runGog([
+        "gmail", "history", "--since", historyId, "--account", account, "--json",
+      ]);
+      if (!result.ok) {
+        this.api.logger.info(`betteremail: history fetch failed for ${account}, falling back to rescan`);
+        const fallback = await this.runGog([
+          "gmail", "messages", "search", `newer_than:${this.rescanDays}d`,
+          "--account", account, "--json", "--include-body",
+        ]);
+        if (!fallback.ok) return [];
+        messages = parseGogMessages(fallback.stdout);
+      } else {
+        messages = parseGogMessages(result.stdout);
+      }
+    } else {
+      const result = await this.runGog([
+        "gmail", "messages", "search", `newer_than:${this.rescanDays}d`,
+        "--account", account, "--json", "--include-body",
+      ]);
+      if (!result.ok) return [];
+      messages = parseGogMessages(result.stdout);
+    }
+
+    const newMessages = messages.filter((m) => !seenMessageIds.has(m.id));
+    const trimmedEmails: TrimmedEmail[] = [];
+
+    for (const msg of newMessages) {
+      const threadResult = await this.runGog([
+        "gmail", "thread", "get", msg.threadId, "--account", account, "--json",
+      ]);
+
+      const thread = threadResult.ok ? parseGogThread(threadResult.stdout) : null;
+
+      if (thread && detectOwnerReply(thread, this.accounts)) {
+        continue;
+      }
+
+      trimmedEmails.push({
+        id: msg.id,
+        threadId: msg.threadId,
+        account,
+        from: msg.from ?? "unknown",
+        to: msg.to ?? account,
+        subject: msg.subject ?? "(no subject)",
+        date: msg.date ?? new Date().toISOString(),
+        body: trimEmailBody(msg.body ?? ""),
+        threadLength: thread?.messages.length ?? 1,
+        hasAttachments: Array.isArray(msg.labelIds) && msg.labelIds.includes("ATTACHMENT"),
+      });
+    }
+
+    return trimmedEmails;
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,65 @@
+import type { WorkHoursConfig, PollIntervalConfig } from "./types.js";
+
+export function isWorkHours(now: Date, config: WorkHoursConfig): boolean {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    hour: "numeric",
+    hour12: false,
+    timeZone: config.timezone,
+  });
+  const hour = parseInt(formatter.format(now), 10);
+  return hour >= config.start && hour < config.end;
+}
+
+export function getIntervalMs(
+  now: Date,
+  intervals: PollIntervalConfig,
+  workConfig: WorkHoursConfig,
+): number {
+  const minutes = isWorkHours(now, workConfig) ? intervals.workHours : intervals.offHours;
+  return minutes * 60 * 1000;
+}
+
+export class Scheduler {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private running = false;
+  private intervals: PollIntervalConfig;
+  private workConfig: WorkHoursConfig;
+  private onTick: () => Promise<void>;
+
+  constructor(
+    intervals: PollIntervalConfig,
+    workConfig: WorkHoursConfig,
+    onTick: () => Promise<void>,
+  ) {
+    this.intervals = intervals;
+    this.workConfig = workConfig;
+    this.onTick = onTick;
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.scheduleNext();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private scheduleNext(): void {
+    if (!this.running) return;
+    const interval = getIntervalMs(new Date(), this.intervals, this.workConfig);
+    this.timer = setTimeout(async () => {
+      try {
+        await this.onTick();
+      } catch {
+        // Pipeline handles its own errors — scheduler just keeps going
+      }
+      this.scheduleNext();
+    }, interval);
+  }
+}

package/src/tools/defer-email.ts

@@ -0,0 +1,32 @@
+import { Type } from "@sinclair/typebox";
+import type { DigestManager } from "../digest.js";
+
+export function createDeferEmailTool(digest: DigestManager) {
+  return {
+    name: "defer_email",
+    label: "Defer Email",
+    description:
+      "Defer an email — it will re-appear in the digest after the specified number of minutes. " +
+      "Use this when the user can't deal with it right now (e.g., in a meeting).",
+    parameters: Type.Object({
+      messageId: Type.String({ description: "The message ID to defer" }),
+      minutes: Type.Number({ description: "Minutes until the email re-surfaces in the digest" }),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const messageId = params.messageId as string;
+      const minutes = params.minutes as number;
+      const entry = digest.get(messageId);
+      if (!entry) {
+        return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
+      }
+      digest.defer(messageId, minutes);
+      await digest.save();
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Deferred "${entry.subject}" — will re-surface in ${minutes} minutes.`,
+        }],
+      };
+    },
+  };
+}

package/src/tools/dismiss-email.ts

@@ -0,0 +1,26 @@
+import { Type } from "@sinclair/typebox";
+import type { DigestManager } from "../digest.js";
+
+export function createDismissEmailTool(digest: DigestManager) {
+  return {
+    name: "dismiss_email",
+    label: "Dismiss Email",
+    description: "Permanently dismiss an email from the digest. It will never be re-flagged.",
+    parameters: Type.Object({
+      messageId: Type.String({ description: "The message ID to dismiss" }),
+      reason: Type.Optional(Type.String({ description: "Optional reason for dismissing" })),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const messageId = params.messageId as string;
+      const entry = digest.get(messageId);
+      if (!entry) {
+        return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
+      }
+      digest.dismiss(messageId);
+      await digest.save();
+      return {
+        content: [{ type: "text" as const, text: `Dismissed "${entry.subject}" from ${entry.from}. It won't be flagged again.` }],
+      };
+    },
+  };
+}

package/src/tools/get-email-digest.ts

@@ -0,0 +1,74 @@
+import { Type } from "@sinclair/typebox";
+import type { DigestManager } from "../digest.js";
+import type { DigestStatus } from "../types.js";
+
+export function createGetEmailDigestTool(digest: DigestManager) {
+  return {
+    name: "get_email_digest",
+    label: "Get Email Digest",
+    description:
+      "Get current email digest — unresolved important emails from all Gmail accounts. " +
+      "Returns emails grouped by account with importance level, reason, and age. " +
+      "Call this to check for new emails or review pending items.",
+    parameters: Type.Object({
+      status: Type.Optional(
+        Type.String({
+          description: 'Filter by status: "new", "surfaced", "deferred", or "all". Default: "new"',
+        }),
+      ),
+      account: Type.Optional(
+        Type.String({ description: "Filter by account email address" }),
+      ),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const status = (typeof params.status === "string" ? params.status : "new") as DigestStatus | "all";
+      const account = typeof params.account === "string" ? params.account : undefined;
+
+      let grouped = digest.getGroupedByAccount(status);
+
+      if (account) {
+        grouped = { [account]: grouped[account] ?? [] };
+      }
+
+      for (const entries of Object.values(grouped)) {
+        for (const entry of entries) {
+          if (entry.status === "new") {
+            digest.markSurfaced(entry.id);
+          }
+        }
+      }
+
+      const summary: Record<string, unknown[]> = {};
+      for (const [acc, entries] of Object.entries(grouped)) {
+        summary[acc] = entries.map((e) => ({
+          messageId: e.id,
+          from: e.from,
+          subject: e.subject,
+          importance: e.importance,
+          reason: e.reason,
+          status: e.status,
+          date: e.date,
+          age: formatAge(e.firstSeenAt),
+          body: e.body,
+          deferredUntil: e.deferredUntil ?? undefined,
+        }));
+      }
+
+      await digest.save();
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(summary, null, 2) }],
+      };
+    },
+  };
+}
+
+function formatAge(isoDate: string): string {
+  const ms = Date.now() - new Date(isoDate).getTime();
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/src/tools/mark-email-handled.ts

@@ -0,0 +1,25 @@
+import { Type } from "@sinclair/typebox";
+import type { DigestManager } from "../digest.js";
+
+export function createMarkEmailHandledTool(digest: DigestManager) {
+  return {
+    name: "mark_email_handled",
+    label: "Mark Email Handled",
+    description: "Mark an email as handled/dealt with. It will no longer appear in the digest.",
+    parameters: Type.Object({
+      messageId: Type.String({ description: "The message ID to mark as handled" }),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const messageId = params.messageId as string;
+      const entry = digest.get(messageId);
+      if (!entry) {
+        return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
+      }
+      digest.markHandled(messageId);
+      await digest.save();
+      return {
+        content: [{ type: "text" as const, text: `Marked "${entry.subject}" from ${entry.from} as handled.` }],
+      };
+    },
+  };
+}

package/src/trimmer.ts

@@ -0,0 +1,54 @@
+const DEFAULT_MAX_LENGTH = 3000;
+
+const HTML_ENTITY_MAP: Record<string, string> = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&apos;": "'",
+  "&nbsp;": " ",
+};
+
+export function trimEmailBody(raw: string, maxLength: number = DEFAULT_MAX_LENGTH): string {
+  if (!raw || typeof raw !== "string") return "";
+
+  let body = raw;
+
+  // 1. Strip HTML tags
+  body = body.replace(/<[^>]*>/g, "");
+
+  // 2. Decode HTML entities
+  body = body.replace(/&\w+;|&#\d+;/g, (match) => HTML_ENTITY_MAP[match] ?? match);
+
+  // 3. Remove quoted reply chains ("On <date>, <person> wrote:")
+  body = body.replace(/\n*On\s+.{10,80}\s+wrote:\s*\n(>[^\n]*\n?)*/gi, "");
+
+  // 4. Remove > prefixed quote blocks
+  body = body.replace(/\n*(?:^|\n)(>[^\n]*\n?)+/g, "");
+
+  // 5. Remove email signatures (-- delimiter)
+  body = body.replace(/\n--\s*\n[\s\S]*$/m, "");
+
+  // 6. Remove "Sent from" signatures
+  body = body.replace(/\n*Sent from my [\w\s]+$/i, "");
+  body = body.replace(/\n*(?:Best regards|Kind regards|Regards|Cheers|Thanks|Best),?\s*\n[\s\S]{0,200}$/i, "");
+
+  // 7. Remove legal disclaimers
+  body = body.replace(/\n*(?:This email is confidential|CONFIDENTIALITY NOTICE|DISCLAIMER|If you (?:are not|received this in error))[\s\S]*$/i, "");
+
+  // 8. Remove tracking pixels / image references
+  body = body.replace(/\[(?:image|cid:[^\]]*)\]/gi, "");
+  body = body.replace(/\[https?:\/\/[^\]]*\.(?:png|gif|jpg|jpeg|bmp)\]/gi, "");
+
+  // 9. Collapse excessive whitespace
+  body = body.replace(/\n{3,}/g, "\n\n");
+  body = body.trim();
+
+  // 10. Truncate
+  if (body.length > maxLength) {
+    body = body.slice(0, maxLength);
+  }
+
+  return body;
+}

package/src/types.ts

@@ -0,0 +1,117 @@
+// -- Plugin config --
+
+export interface PollIntervalConfig {
+  workHours: number;
+  offHours: number;
+}
+
+export interface WorkHoursConfig {
+  start: number;
+  end: number;
+  timezone: string;
+}
+
+export interface PluginConfig {
+  accounts: string[];
+  pollIntervalMinutes: PollIntervalConfig;
+  workHours: WorkHoursConfig;
+  classifierTimeoutMs: number;
+  consecutiveFailuresBeforeAlert: number;
+  rescanDaysOnHistoryReset: number;
+}
+
+// -- Raw email from gog CLI --
+
+export interface RawGogMessage {
+  id: string;
+  threadId: string;
+  subject?: string;
+  from?: string;
+  to?: string;
+  date?: string;
+  body?: string;
+  labelIds?: string[];
+  [key: string]: unknown;
+}
+
+export interface RawGogThread {
+  id: string;
+  messages: RawGogMessage[];
+}
+
+// -- Trimmed email ready for classification --
+
+export interface TrimmedEmail {
+  id: string;
+  threadId: string;
+  account: string;
+  from: string;
+  to: string;
+  subject: string;
+  date: string;
+  body: string;
+  threadLength: number;
+  hasAttachments: boolean;
+}
+
+// -- Classification result --
+
+export type ImportanceLevel = "high" | "medium" | "low";
+
+export interface ClassificationResult {
+  id: string;
+  importance: ImportanceLevel;
+  reason: string;
+  notify: boolean;
+}
+
+// -- Digest entry --
+
+export type DigestStatus = "new" | "surfaced" | "deferred" | "handled" | "dismissed";
+
+export interface DigestEntry {
+  id: string;
+  threadId: string;
+  account: string;
+  from: string;
+  subject: string;
+  date: string;
+  body: string;
+  importance: "high" | "medium";
+  reason: string;
+  notify: boolean;
+  status: DigestStatus;
+  firstSeenAt: string;
+  surfacedAt?: string;
+  deferredUntil?: string;
+  resolvedAt?: string;
+}
+
+// -- Digest state file --
+
+export interface DigestState {
+  entries: Record<string, DigestEntry>;
+}
+
+// -- Polling state file --
+
+export interface AccountState {
+  historyId: string;
+  lastPollAt: string;
+  consecutiveFailures: number;
+}
+
+export interface PollState {
+  accounts: Record<string, AccountState>;
+  lastClassifierRunAt: string;
+}
+
+// -- Email log entry (emails.jsonl) --
+
+export interface EmailLogEntry {
+  email: TrimmedEmail;
+  importance: ImportanceLevel;
+  reason: string;
+  notify: boolean;
+  timestamp: number;
+}