@better_openclaw/betteremail 0.1.0 → 0.2.0

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@better_openclaw/betteremail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Email digest plugin for OpenClaw — polls Gmail, deduplicates, classifies importance, exposes digest to agent",
   "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maximilianspitzer/openclaw-betteremail"
+  },
   "type": "module",
   "openclaw": {
     "extensions": ["./src/index.ts"]

package/src/atomic.ts

@@ -0,0 +1,26 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+
+/**
+ * Write content to a file atomically by first writing to a temp file
+ * in the same directory, then renaming. This prevents corruption on
+ * crash mid-write since rename is atomic on POSIX filesystems.
+ */
+export async function atomicWrite(filePath: string, content: string): Promise<void> {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmpPath = path.join(dir, `.${path.basename(filePath)}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  try {
+    await fs.writeFile(tmpPath, content, "utf8");
+    await fs.rename(tmpPath, filePath);
+  } catch (err) {
+    // Clean up temp file on failure
+    try {
+      await fs.unlink(tmpPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}

package/src/commands/emails.ts

@@ -1,4 +1,5 @@
 import type { DigestManager } from "../digest.js";
+import { formatAge } from "../utils.js";
 
 export function createEmailsCommandHandler(digest: DigestManager) {
   return () => {
@@ -49,13 +50,3 @@ export function createEmailsCommandHandler(digest: DigestManager) {
     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

@@ -1,12 +1,15 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { DigestEntry, DigestState, DigestStatus } from "./types.js";
+import { atomicWrite } from "./atomic.js";
 
 const DIGEST_FILE = "digest.json";
 
 export class DigestManager {
   private filePath: string;
   private state: DigestState;
+  private saving = false;
+  private saveQueue: (() => void)[] = [];
 
   constructor(stateDir: string) {
     this.filePath = path.join(stateDir, DIGEST_FILE);
@@ -23,8 +26,17 @@ export class DigestManager {
   }
 
   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");
+    if (this.saving) {
+      await new Promise<void>((resolve) => this.saveQueue.push(resolve));
+    }
+    this.saving = true;
+    try {
+      await atomicWrite(this.filePath, JSON.stringify(this.state, null, 2) + "\n");
+    } finally {
+      this.saving = false;
+      const next = this.saveQueue.shift();
+      if (next) next();
+    }
   }
 
   add(entry: DigestEntry): void {
@@ -55,9 +67,9 @@ export class DigestManager {
     return grouped;
   }
 
-  getActiveThreadIds(): DigestEntry[] {
+  getActiveEntries(): DigestEntry[] {
     return Object.values(this.state.entries).filter(
-      (e) => e.status === "surfaced" || e.status === "deferred",
+      (e) => e.status === "new" || e.status === "surfaced" || e.status === "deferred",
     );
   }
 
@@ -85,11 +97,12 @@ export class DigestManager {
     }
   }
 
-  dismiss(id: string): void {
+  dismiss(id: string, reason?: string): void {
     const entry = this.state.entries[id];
     if (entry) {
       entry.status = "dismissed";
       entry.resolvedAt = new Date().toISOString();
+      if (reason) entry.dismissReason = reason;
     }
   }
 

package/src/email-log.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { EmailLogEntry } from "./types.js";
+import { atomicWrite } from "./atomic.js";
 
 const EMAILS_FILE = "emails.jsonl";
 const DEFAULT_MAX_LINES = 10_000;
@@ -32,11 +33,6 @@ export class EmailLog {
     }
   }
 
-  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;
@@ -46,7 +42,7 @@ export class EmailLog {
     const removed = entries.length - kept.length;
 
     const content = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
-    await fs.writeFile(this.filePath, content, "utf8");
+    await atomicWrite(this.filePath, content);
 
     return removed;
   }

package/src/index.ts

@@ -22,33 +22,22 @@ const DEFAULT_CONFIG: PluginConfig = {
 };
 
 function resolveConfig(raw: Record<string, unknown> | undefined): PluginConfig {
+  const pollIntervalRaw = raw?.pollIntervalMinutes && typeof raw.pollIntervalMinutes === "object"
+    ? raw.pollIntervalMinutes as Record<string, unknown> : null;
+  const workHoursRaw = raw?.workHours && typeof raw.workHours === "object"
+    ? raw.workHours as Record<string, unknown> : null;
+
   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,
+    pollIntervalMinutes: pollIntervalRaw ? {
+      workHours: typeof pollIntervalRaw.workHours === "number" ? pollIntervalRaw.workHours : DEFAULT_CONFIG.pollIntervalMinutes.workHours,
+      offHours: typeof pollIntervalRaw.offHours === "number" ? pollIntervalRaw.offHours : DEFAULT_CONFIG.pollIntervalMinutes.offHours,
+    } : DEFAULT_CONFIG.pollIntervalMinutes,
+    workHours: workHoursRaw ? {
+      start: typeof workHoursRaw.start === "number" ? workHoursRaw.start : DEFAULT_CONFIG.workHours.start,
+      end: typeof workHoursRaw.end === "number" ? workHoursRaw.end : DEFAULT_CONFIG.workHours.end,
+      timezone: typeof workHoursRaw.timezone === "string" ? workHoursRaw.timezone : DEFAULT_CONFIG.workHours.timezone,
+    } : DEFAULT_CONFIG.workHours,
     classifierTimeoutMs:
       typeof raw?.classifierTimeoutMs === "number" ? raw.classifierTimeoutMs : DEFAULT_CONFIG.classifierTimeoutMs,
     consecutiveFailuresBeforeAlert:

package/src/pipeline.ts

@@ -5,7 +5,7 @@ export interface PipelineDeps {
   poller: {
     loadState(): Promise<void>;
     saveState(): Promise<void>;
-    pollAccount(account: string, seenMessageIds: Set<string>): Promise<TrimmedEmail[]>;
+    pollAccount(account: string, seenMessageIds: Set<string>): Promise<{ emails: TrimmedEmail[]; historyId?: string }>;
     recordSuccess(account: string, historyId: string): void;
     recordFailure(account: string): number;
     getAccountState(account: string): { historyId: string; lastPollAt: string; consecutiveFailures: number } | undefined;
@@ -19,13 +19,12 @@ export interface PipelineDeps {
     save(): Promise<void>;
     add(entry: DigestEntry): void;
     has(id: string): boolean;
-    getActiveThreadIds(): DigestEntry[];
+    getActiveEntries(): DigestEntry[];
     expireDeferrals(): DigestEntry[];
     markHandled(id: string): void;
   };
   emailLog: {
     append(entry: EmailLogEntry): Promise<void>;
-    hasMessageId(id: string): Promise<boolean>;
     readAll(): Promise<EmailLogEntry[]>;
   };
   logger: {
@@ -51,7 +50,7 @@ export async function runPipeline(deps: PipelineDeps): Promise<void> {
   }
 
   // Auto-resolve: re-check active threads for owner replies
-  const activeEntries = digest.getActiveThreadIds();
+  const activeEntries = digest.getActiveEntries();
   for (const entry of activeEntries) {
     try {
       const replied = await poller.checkThreadForReply(entry.threadId, entry.account);
@@ -72,11 +71,10 @@ export async function runPipeline(deps: PipelineDeps): Promise<void> {
 
   for (const account of accounts) {
     try {
-      const emails = await poller.pollAccount(account, seenIds);
+      const { emails, historyId } = 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 ?? "");
+      poller.recordSuccess(account, historyId ?? poller.getAccountState(account)?.historyId ?? "");
       logger.info(`betteremail: ${account} — ${emails.length} fetched, ${filtered.length} new`);
     } catch (err) {
       const failures = poller.recordFailure(account);

package/src/poller.ts

@@ -3,6 +3,7 @@ import type { RawGogMessage, RawGogThread, PollState, TrimmedEmail } from "./typ
 import { trimEmailBody } from "./trimmer.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { atomicWrite } from "./atomic.js";
 
 const STATE_FILE = "state.json";
 
@@ -18,6 +19,19 @@ export function parseGogMessages(stdout: string): RawGogMessage[] {
   }
 }
 
+export function extractHistoryId(stdout: string): string | undefined {
+  if (!stdout || !stdout.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(stdout.trim());
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.historyId === "string") {
+      return parsed.historyId;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function parseGogThread(stdout: string): RawGogThread | null {
   if (!stdout || !stdout.trim()) return null;
   try {
@@ -36,7 +50,8 @@ function extractEmail(fromField: string): string {
 
 export function detectOwnerReply(thread: RawGogThread, ownerAccounts: string[]): boolean {
   const lowerAccounts = ownerAccounts.map((a) => a.toLowerCase());
-  return thread.messages.some((msg) => {
+  // Skip first message (could be user-initiated thread)
+  return thread.messages.slice(1).some((msg) => {
     if (!msg.from) return false;
     const email = extractEmail(msg.from);
     return lowerAccounts.includes(email);
@@ -68,11 +83,9 @@ export class Poller {
   }
 
   async saveState(): Promise<void> {
-    await fs.mkdir(this.stateDir, { recursive: true });
-    await fs.writeFile(
+    await atomicWrite(
       path.join(this.stateDir, STATE_FILE),
       JSON.stringify(this.state, null, 2) + "\n",
-      "utf8",
     );
   }
 
@@ -126,15 +139,16 @@ export class Poller {
     return detectOwnerReply(thread, this.accounts);
   }
 
-  async pollAccount(account: string, seenMessageIds: Set<string>): Promise<TrimmedEmail[]> {
+  async pollAccount(account: string, seenMessageIds: Set<string>): Promise<{ emails: TrimmedEmail[]; historyId?: string }> {
     const accountState = this.state.accounts[account];
-    const historyId = accountState?.historyId;
+    const currentHistoryId = accountState?.historyId;
 
     let messages: RawGogMessage[];
+    let newHistoryId: string | undefined;
 
-    if (historyId) {
+    if (currentHistoryId) {
       const result = await this.runGog([
-        "gmail", "history", "--since", historyId, "--account", account, "--json",
+        "gmail", "history", "--since", currentHistoryId, "--account", account, "--json",
       ]);
       if (!result.ok) {
         this.api.logger.info(`betteremail: history fetch failed for ${account}, falling back to rescan`);
@@ -142,9 +156,11 @@ export class Poller {
           "gmail", "messages", "search", `newer_than:${this.rescanDays}d`,
           "--account", account, "--json", "--include-body",
         ]);
-        if (!fallback.ok) return [];
+        if (!fallback.ok) return { emails: [] };
         messages = parseGogMessages(fallback.stdout);
+        // No historyId from search fallback
       } else {
+        newHistoryId = extractHistoryId(result.stdout);
         messages = parseGogMessages(result.stdout);
       }
     } else {
@@ -152,8 +168,9 @@ export class Poller {
         "gmail", "messages", "search", `newer_than:${this.rescanDays}d`,
         "--account", account, "--json", "--include-body",
       ]);
-      if (!result.ok) return [];
+      if (!result.ok) return { emails: [] };
       messages = parseGogMessages(result.stdout);
+      // No historyId from initial search
     }
 
     const newMessages = messages.filter((m) => !seenMessageIds.has(m.id));
@@ -184,6 +201,6 @@ export class Poller {
       });
     }
 
-    return trimmedEmails;
+    return { emails: trimmedEmails, historyId: newHistoryId };
   }
 }

package/src/tools/defer-email.ts

@@ -13,12 +13,21 @@ export function createDeferEmailTool(digest: DigestManager) {
       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;
+      if (typeof params.messageId !== "string" || !params.messageId) {
+        return { content: [{ type: "text" as const, text: "Error: messageId must be a non-empty string." }] };
+      }
+      if (typeof params.minutes !== "number" || params.minutes <= 0 || !Number.isFinite(params.minutes)) {
+        return { content: [{ type: "text" as const, text: "Error: minutes must be a positive number." }] };
+      }
+      const messageId = params.messageId;
+      const minutes = params.minutes;
       const entry = digest.get(messageId);
       if (!entry) {
         return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
       }
+      if (entry.status === "handled" || entry.status === "dismissed" || entry.status === "deferred") {
+        return { content: [{ type: "text" as const, text: `Cannot defer: email is already "${entry.status}".` }] };
+      }
       digest.defer(messageId, minutes);
       await digest.save();
       return {

package/src/tools/dismiss-email.ts

@@ -11,12 +11,19 @@ export function createDismissEmailTool(digest: DigestManager) {
       reason: Type.Optional(Type.String({ description: "Optional reason for dismissing" })),
     }),
     async execute(_id: string, params: Record<string, unknown>) {
-      const messageId = params.messageId as string;
+      if (typeof params.messageId !== "string" || !params.messageId) {
+        return { content: [{ type: "text" as const, text: "Error: messageId must be a non-empty string." }] };
+      }
+      const messageId = params.messageId;
+      const reason = typeof params.reason === "string" ? params.reason : undefined;
       const entry = digest.get(messageId);
       if (!entry) {
         return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
       }
-      digest.dismiss(messageId);
+      if (entry.status === "handled" || entry.status === "dismissed") {
+        return { content: [{ type: "text" as const, text: `Cannot dismiss: email is already "${entry.status}".` }] };
+      }
+      digest.dismiss(messageId, reason);
       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

@@ -1,6 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import type { DigestManager } from "../digest.js";
 import type { DigestStatus } from "../types.js";
+import { formatAge } from "../utils.js";
 
 export function createGetEmailDigestTool(digest: DigestManager) {
   return {
@@ -21,7 +22,11 @@ export function createGetEmailDigestTool(digest: DigestManager) {
       ),
     }),
     async execute(_id: string, params: Record<string, unknown>) {
+      const validStatuses = ["new", "surfaced", "deferred", "all"];
       const status = (typeof params.status === "string" ? params.status : "new") as DigestStatus | "all";
+      if (!validStatuses.includes(status)) {
+        return { content: [{ type: "text" as const, text: `Error: status must be one of: ${validStatuses.join(", ")}` }] };
+      }
       const account = typeof params.account === "string" ? params.account : undefined;
 
       let grouped = digest.getGroupedByAccount(status);
@@ -30,14 +35,7 @@ export function createGetEmailDigestTool(digest: DigestManager) {
         grouped = { [account]: grouped[account] ?? [] };
       }
 
-      for (const entries of Object.values(grouped)) {
-        for (const entry of entries) {
-          if (entry.status === "new") {
-            digest.markSurfaced(entry.id);
-          }
-        }
-      }
-
+      // Build response first (while status is still "new")
       const summary: Record<string, unknown[]> = {};
       for (const [acc, entries] of Object.entries(grouped)) {
         summary[acc] = entries.map((e) => ({
@@ -54,6 +52,15 @@ export function createGetEmailDigestTool(digest: DigestManager) {
         }));
       }
 
+      // THEN mark as surfaced
+      for (const entries of Object.values(grouped)) {
+        for (const entry of entries) {
+          if (entry.status === "new") {
+            digest.markSurfaced(entry.id);
+          }
+        }
+      }
+
       await digest.save();
 
       return {
@@ -62,13 +69,3 @@ export function createGetEmailDigestTool(digest: DigestManager) {
     },
   };
 }
-
-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

@@ -10,11 +10,17 @@ export function createMarkEmailHandledTool(digest: DigestManager) {
       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;
+      if (typeof params.messageId !== "string" || !params.messageId) {
+        return { content: [{ type: "text" as const, text: "Error: messageId must be a non-empty string." }] };
+      }
+      const messageId = params.messageId;
       const entry = digest.get(messageId);
       if (!entry) {
         return { content: [{ type: "text" as const, text: `Email ${messageId} not found in digest.` }] };
       }
+      if (entry.status === "handled" || entry.status === "dismissed") {
+        return { content: [{ type: "text" as const, text: `Cannot mark as handled: email is already "${entry.status}".` }] };
+      }
       digest.markHandled(messageId);
       await digest.save();
       return {

package/src/types.ts

@@ -85,6 +85,7 @@ export interface DigestEntry {
   surfacedAt?: string;
   deferredUntil?: string;
   resolvedAt?: string;
+  dismissReason?: string;
 }
 
 // -- Digest state file --

package/src/utils.ts

@@ -0,0 +1,9 @@
+export 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`;
+}