@mcinteerj/openclaw-gmail 1.2.0

package/README.md

@@ -0,0 +1,117 @@
+# Gmail Channel (Plugin)
+
+Connects Moltbot to Gmail via the `gog` CLI.
+
+## Installation
+
+This is a plugin. To install from source:
+
+```bash
+moltbot plugins install ./extensions/gmail
+```
+
+## Features
+
+- **Polling-based sync**: Robustly fetches new unread emails from Inbox.
+- **Circuit Breaker**: Handles API failures and rate limiting gracefully.
+- **Rich Text**: Markdown support for outbound emails.
+- **Threading**: Native Gmail thread support with quoted reply context.
+- **Archiving**: Automatically archives threads upon reply.
+- **Email Body Sanitisation**: Automatically cleans incoming email bodies for LLM consumption.
+
+## Email Body Sanitisation
+
+Incoming emails are automatically sanitised to produce clean, readable text — no configuration needed.
+
+### What It Does
+
+- **HTML-to-text conversion**: Strips tags, removes `<style>` and `<script>` blocks, filters out tracking pixels, and decodes HTML entities.
+- **Footer junk removal**: Strips common noise like unsubscribe links, "Sent from my iPhone", and confidentiality notices.
+- **Whitespace cleanup**: Collapses excessive blank lines and trims leading/trailing whitespace.
+- **Signature stripping**: Removes content below `-- ` signature separators by default.
+
+### Configurable Signature Stripping
+
+Signature stripping is enabled by default. If you need to preserve content after `--` separators (e.g. for emails where dashes appear in the body), you can disable it programmatically:
+
+```ts
+extractTextBody(html, plain, { stripSignature: false })
+```
+
+No plugin configuration is required — sanitisation runs automatically on every inbound message.
+
+## Reply Behavior
+
+- **Reply All**: When the bot replies to a thread, it uses "Reply All" to ensure all participants are included.
+- **Quoted Replies**: By default, replies include the full thread history as quoted text (standard Gmail format: "On [date], [author] wrote:"). This can be disabled per-account or globally.
+- **Allowlist Gatekeeping**: The bot only responds to emails from senders on the `allowFrom` list. However, if an allowed user includes others (CC) who are *not* on the allowlist, the bot will still "Reply All", including them in the conversation. This allows authorized users to bring others into the loop.
+- **Outbound Restrictions** (optional): Use `allowOutboundTo` and `threadReplyPolicy` to control who the bot can send emails to. By default, no outbound restrictions are applied (backwards compatible).
+
+## Configuration
+
+Add to `moltbot.json`:
+
+```json5
+{
+  "channels": {
+    "gmail": {
+      "accounts": {
+        "main": {
+          "email": "user@gmail.com",
+          "allowFrom": ["*"],
+          "includeQuotedReplies": true,  // default: true
+          // Optional: restrict who the bot can send emails TO
+          "allowOutboundTo": ["@mycompany.com", "partner@example.com"],
+          "threadReplyPolicy": "allowlist"  // default: "open"
+        }
+      },
+      "defaults": {
+        "includeQuotedReplies": true  // global default
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `includeQuotedReplies` | boolean | `true` | Include thread history as quoted text in replies. Set to `false` for cleaner, shorter replies. |
+| `allowOutboundTo` | string[] | (falls back to `allowFrom`) | Restrict who the bot can send emails to. Supports exact emails and domain wildcards (e.g., `@company.com`). |
+| `threadReplyPolicy` | string | `"open"` | Controls thread reply behavior: `"open"` (no restrictions), `"allowlist"` (all recipients must be in `allowOutboundTo`), or `"sender-only"` (only original thread sender checked). |
+
+### Thread Reply Policies
+
+- **`open`** (default): No outbound restrictions. The bot can reply to any thread it was BCCd into. Backwards compatible.
+- **`allowlist`**: All thread participants (To, CC, From) must be in `allowOutboundTo`. Blocks replies if *any* recipient is not allowed.
+- **`sender-only`**: Only checks if the original thread sender is in `allowOutboundTo`. Useful when you want to reply to threads started by allowed users, even if they CC'd external parties.
+
+## Development
+
+Run tests:
+```bash
+npm test
+# or
+./node_modules/.bin/vitest run src/
+```
+
+## Publishing
+
+This repo includes a GitHub Actions workflow for npm publishing.
+
+### Automatic (on release)
+Create a GitHub release → automatically publishes to npm.
+
+### Manual (workflow dispatch)
+Go to Actions → "Publish to npm" → Run workflow.
+
+**Note:** Manual dispatch will:
+1. Bump the version (patch by default, or specify major/minor)
+2. Commit and push the version bump with a tag
+3. Publish to npm
+
+### Setup
+Add `NPM_TOKEN` secret to the repository:
+1. Generate token at npmjs.com → Access Tokens → Classic Token (Automation)
+2. Add to repo: Settings → Secrets → Actions → New repository secret

package/index.ts

@@ -0,0 +1,14 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { gmailPlugin } from "./src/channel.js";
+
+import { setGmailRuntime } from "./src/runtime.js";
+
+const plugin = {
+  ...gmailPlugin,
+  register: (api: ClawdbotPluginApi) => {
+    setGmailRuntime(api.runtime);
+    api.registerChannel(gmailPlugin);
+  }
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openclaw-gmail",
+  "channels": [
+    "gmail"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mcinteerj/openclaw-gmail",
+  "version": "1.2.0",
+  "description": "Gmail channel plugin for OpenClaw - uses gog CLI for secure Gmail access",
+  "type": "module",
+  "main": "index.ts",
+  "author": "Jake McInteer <mcinteerj@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcinteerj/openclaw-gmail"
+  },
+  "keywords": [
+    "openclaw",
+    "gmail",
+    "email",
+    "channel",
+    "plugin"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "gmail",
+      "label": "Gmail",
+      "selectionLabel": "Gmail (gog)",
+      "detailLabel": "Gmail",
+      "docsPath": "/channels/gmail",
+      "docsLabel": "gmail",
+      "blurb": "Uses gog for secure Gmail access.",
+      "systemImage": "envelope",
+      "order": 100,
+      "showConfigured": true
+    }
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "dompurify": "^3.2.3",
+    "jsdom": "^25.0.1",
+    "marked": "^15.0.6",
+    "proper-lockfile": "^4.1.2",
+    "sanitize-html": "^2.14.0",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.0"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,57 @@
+import {
+  type ChannelConfig,
+  type ResolvedChannelAccount,
+  DEFAULT_ACCOUNT_ID,
+} from "openclaw/plugin-sdk";
+import type { GmailConfig } from "./config.js";
+
+export interface ResolvedGmailAccount extends ResolvedChannelAccount {
+  email: string;
+  historyId?: string;
+  delegate?: string;
+  pollIntervalMs?: number;
+}
+
+export function resolveGmailAccount(
+  cfg: ChannelConfig<GmailConfig>,
+  accountId?: string,
+): ResolvedGmailAccount {
+  const resolvedId = accountId || DEFAULT_ACCOUNT_ID;
+  const account = cfg.channels?.gmail?.accounts?.[resolvedId];
+
+  if (!account) {
+    // Graceful fallback for UI logic that queries 'default' on unconfigured channels
+    return {
+        accountId: resolvedId,
+        name: resolvedId,
+        enabled: false,
+        email: "",
+        historyId: undefined,
+        delegate: undefined,
+        allowFrom: [],
+        pollIntervalMs: undefined,
+    };
+  }
+
+  return {
+    accountId: resolvedId,
+    name: account.name || account.email,
+    enabled: account.enabled,
+    email: account.email,
+    historyId: account.historyId,
+    delegate: account.delegate,
+    allowFrom: account.allowFrom,
+    pollIntervalMs: account.pollIntervalMs,
+  };
+}
+
+export function listGmailAccountIds(cfg: ChannelConfig<GmailConfig>): string[] {
+  return Object.keys(cfg.channels?.gmail?.accounts || {});
+}
+
+export function resolveDefaultGmailAccountId(cfg: ChannelConfig<GmailConfig>): string {
+  const ids = listGmailAccountIds(cfg);
+  if (ids.length === 0) return DEFAULT_ACCOUNT_ID;
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0]; // Fallback to first
+}

package/src/attachments.ts

@@ -0,0 +1,29 @@
+import type { GogMessagePart } from "./inbound.js";
+
+export interface GmailAttachment {
+  filename: string;
+  mimeType: string;
+  attachmentId: string;
+  size: number;
+}
+
+export function extractAttachments(part: GogMessagePart): GmailAttachment[] {
+  const attachments: GmailAttachment[] = [];
+
+  if (part.filename && part.body?.attachmentId) {
+    attachments.push({
+      filename: part.filename,
+      mimeType: part.mimeType,
+      attachmentId: part.body.attachmentId,
+      size: part.body.size,
+    });
+  }
+
+  if (part.parts) {
+    for (const subPart of part.parts) {
+      attachments.push(...extractAttachments(subPart));
+    }
+  }
+
+  return attachments;
+}

package/src/channel.ts

@@ -0,0 +1,360 @@
+import {
+  buildChannelConfigSchema,
+  getChatChannelMeta,
+  type ChannelPlugin,
+  missingTargetError,
+  setAccountEnabledInConfigSection,
+  deleteAccountFromConfigSection,
+  type InboundMessage,
+  type OpenClawConfig,
+  type ChannelGatewayContext,
+  type MsgContext,
+} from "openclaw/plugin-sdk";
+import { GmailConfigSchema } from "./config.js";
+import {
+  resolveGmailAccount,
+  resolveDefaultGmailAccountId,
+  listGmailAccountIds,
+  type ResolvedGmailAccount,
+} from "./accounts.js";
+import { setGmailRuntime, getGmailRuntime } from "./runtime.js";
+import { sendGmailText, type GmailOutboundContext } from "./outbound.js";
+import { gmailThreading } from "./threading.js";
+import { normalizeGmailTarget, isGmailThreadId, isAllowed } from "./normalize.js";
+import { parseInboundGmail, type GogPayload } from "./inbound.js";
+import { monitorGmail, quarantineMessage } from "./monitor.js";
+import { extractAttachments } from "./attachments.js";
+import { Semaphore } from "./semaphore.js";
+import crypto from "node:crypto";
+
+const meta = {
+  id: "gmail",
+  label: "Gmail",
+  selectionLabel: "Gmail (gog)",
+  detailLabel: "Gmail",
+  docsPath: "/channels/gmail",
+  docsLabel: "gmail",
+  blurb: "Uses gog for secure Gmail access.",
+  systemImage: "envelope",
+  order: 100,
+  showConfigured: true,
+};
+
+// Map to store active account contexts
+const activeAccounts = new Map<string, ChannelGatewayContext<ResolvedGmailAccount>>();
+
+// Limit concurrent dispatches to avoid memory spikes
+const dispatchSemaphore = new Semaphore(5);
+
+/**
+ * Convert an InboundMessage to a finalized MsgContext for dispatch.
+ * Gmail threads are equivalent to Slack channels - each thread gets its own session.
+ */
+function buildGmailMsgContext(
+  msg: InboundMessage,
+  account: ResolvedGmailAccount,
+  cfg: OpenClawConfig,
+): MsgContext {
+  const runtime = getGmailRuntime();
+  const to = `gmail:${account.email}`;
+  const threadLabel = `Gmail thread ${msg.threadId}`;
+
+  const ctx = runtime.channel.reply.finalizeInboundContext({
+    Body: msg.text,
+    RawBody: msg.text,
+    CommandBody: msg.text,
+    From: msg.sender.id,
+    To: to,
+    SessionKey: `gmail:${account.email}:${msg.threadId}`,
+    AccountId: msg.accountId,
+    ChatType: "direct",
+    ConversationLabel: threadLabel,
+    SenderName: msg.sender.name,
+    SenderId: msg.sender.id,
+    Provider: "gmail" as const,
+    Surface: "gmail" as const,
+    MessageSid: msg.channelMessageId,
+    ReplyToId: msg.channelMessageId,
+    ThreadLabel: threadLabel,
+    MessageThreadId: msg.threadId,
+    ThreadStarterBody: undefined,
+    Timestamp: msg.timestamp ? Math.round(msg.timestamp / 1_000) : undefined, // InboundMessage timestamp is ms, finalizeInboundContext expects seconds
+    MediaPath: msg.mediaPath,
+    MediaType: msg.mediaType,
+    MediaUrl: msg.mediaUrl,
+    CommandAuthorized: false,
+    OriginatingChannel: "gmail" as const,
+    OriginatingTo: to,
+  });
+
+  return ctx;
+}
+
+async function dispatchGmailMessage(
+  ctx: ChannelGatewayContext<ResolvedGmailAccount>,
+  msg: InboundMessage,
+) {
+  const { account, accountId, cfg, log } = ctx;
+  const runtime = getGmailRuntime();
+  const requestId = crypto.randomUUID().split("-")[0];
+
+  await dispatchSemaphore.run(async () => {
+    try {
+      log?.info(`[gmail][${requestId}] Dispatching message ${msg.channelMessageId} from ${msg.sender.id}`);
+      
+      // Build the dispatch context
+      const ctxPayload = buildGmailMsgContext(msg, account, cfg);
+
+      // Build reply dispatcher options using gateway's reply capability
+      const deliver = async (payload: { text: string }) => {
+        const originalSubject = msg.raw?.subject ||
+                               msg.raw?.headers?.subject || 
+                               msg.raw?.payload?.headers?.find((h: any) => h.name.toLowerCase() === "subject")?.value;
+        
+        const replySubject = originalSubject 
+          ? (originalSubject.toLowerCase().startsWith("re:") ? originalSubject : `Re: ${originalSubject}`)
+          : "Re: ";
+
+        await sendGmailText({
+          to: msg.threadId || msg.sender.id,
+          text: payload.text,
+          accountId,
+          cfg,
+          threadId: msg.threadId,
+          replyToId: msg.channelMessageId,
+          subject: replySubject,
+        });
+      };
+
+      const humanDelay = runtime.channel.reply.resolveHumanDelayConfig(cfg, accountId);
+
+      // Dispatch to agent
+      await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg,
+        dispatcherOptions: {
+          deliver,
+          humanDelay,
+          onError: (err: unknown, info: { kind: string }) => {
+            log?.error(`[gmail][${requestId}] ${info.kind} reply failed: ${String(err)}`);
+          },
+        },
+      });
+      log?.info(`[gmail][${requestId}] Dispatch complete for ${msg.channelMessageId}`);
+    } catch (e: unknown) {
+      log?.error(`[gmail][${requestId}] Dispatch failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  });
+}
+
+import { gmailOnboardingAdapter } from "./onboarding.js";
+
+export const gmailPlugin: ChannelPlugin<ResolvedGmailAccount> = {
+  id: "gmail",
+  onboarding: gmailOnboardingAdapter,
+  meta: {
+    ...meta,
+    showConfigured: true,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    threads: true,
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean", default: true },
+        accounts: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              enabled: { type: "boolean", default: true },
+              email: { type: "string" },
+              name: { type: "string" },
+              allowFrom: { type: "array", items: { type: "string" } },
+              historyId: { type: "string" },
+              delegate: { type: "string" },
+            },
+            required: ["email"],
+          },
+        },
+        defaults: {
+          type: "object",
+          properties: {
+            allowFrom: { type: "array", items: { type: "string" } },
+          },
+        },
+      },
+    },
+  },
+  config: {
+    listAccountIds: (cfg) => listGmailAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveGmailAccount(cfg, accountId),
+    defaultAccountId: (cfg) => resolveDefaultGmailAccountId(cfg),
+    isEnabled: (account) => account.enabled,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name || account.email,
+      enabled: account.enabled,
+      configured: true,
+      linked: true,
+      allowFrom: account.allowFrom,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      resolveGmailAccount(cfg, accountId ?? undefined).allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((e) => String(e).trim()).filter(Boolean),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "gmail",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "gmail",
+        accountId,
+      }),
+  },
+  outbound: {
+    deliveryMode: "gateway",
+    textChunkLimit: 8000,
+    sendText: sendGmailText,
+    resolveTarget: ({ to, allowFrom }) => {
+      const trimmed = to?.trim() ?? "";
+      const normalized = normalizeGmailTarget(trimmed);
+
+      if (!normalized) {
+        return {
+          ok: false,
+          error: missingTargetError("Gmail", "email address or thread ID"),
+        };
+      }
+
+      // If it's a thread ID, we allow it implicitly (assuming we only have thread IDs
+      // for threads we were allowed to ingest).
+      if (isGmailThreadId(normalized)) {
+        return { ok: true, to: normalized };
+      }
+
+      // Security: check allowFrom for new email addresses
+      const allowed = (allowFrom || []).map((e) => String(e).trim());
+      if (allowed.includes("*")) {
+        return { ok: true, to: normalized };
+      }
+      
+      if (allowed.length > 0) {
+        const isAllowed = allowed.some(entry => {
+          if (entry === normalized) return true;
+          if (entry.startsWith("@") && normalized.endsWith(entry)) return true;
+          return false;
+        });
+        
+        if (!isAllowed) {
+          return { ok: false, error: new Error(`Recipient ${normalized} not in allowList`) };
+        }
+      }
+
+      return { ok: true, to: normalized };
+    },
+  },
+  threading: gmailThreading,
+  messaging: {
+    normalizeTarget: normalizeGmailTarget,
+    targetResolver: {
+      looksLikeId: (id) => normalizeGmailTarget(id) !== null,
+      hint: "email or threadId",
+    },
+  },
+  agentPrompt: {
+    messageToolHints: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) => {
+      const account = resolveGmailAccount(cfg, accountId);
+      return [
+        "### Gmail Messaging",
+        "- To reply to this email, just write your response normally as text in your turn. This will Reply All to everyone on the thread.",
+        "- Your Markdown response is automatically converted to a rich HTML email using the `marked` library.",
+        "- Headings, tables, and code blocks are fully supported.",
+        `- Sending as: ${account.email || "the configured Gmail account"}.`,
+        "### Attachments",
+        "- **Location**: All attachments are stored in \`.attachments/{{threadId}}/\` relative to your workspace.",
+        "- **Auto-Download**: Files under 5MB are already there. The message text contains their paths.",
+        "- **Manual Download**: For larger files (listed with an ID), download them to that same folder:",
+        `- Command: \`mkdir -p .attachments/{{threadId}} && gog gmail attachment <messageId> <attachmentId> --account ${account.email} --out .attachments/{{threadId}}/<filename>\``,
+      ];
+    },
+  },
+  actions: {
+    listActions: () => ["send"],
+    supportsAction: ({ action }: { action: string }) => action === "send",
+    handleAction: async (ctx: any) => {
+      if (ctx.action !== "send") return { ok: false, error: new Error(`Unsupported action: ${ctx.action}`) };
+      
+      const { params, accountId, cfg, toolContext } = ctx;
+      const to = (params.target || params.to) as string;
+      const text = params.message as string;
+      
+      const isThread = isGmailThreadId(to);
+      let subject = params.subject as string | undefined;
+      let replyToId: string | undefined;
+      
+      if (isThread && toolContext?.currentThreadTs) {
+          replyToId = toolContext.currentThreadTs;
+      }
+
+      await sendGmailText({
+        to,
+        text,
+        accountId,
+        cfg,
+        threadId: isThread ? to : undefined,
+        replyToId,
+        subject,
+      });
+      
+      return { ok: true, content: [{ type: "text", text: "Message sent via Gmail." }] };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      ctx.log?.info(`[gmail] Account ${ctx.account.accountId} started`);
+
+      if (ctx.account.email) {
+        activeAccounts.set(ctx.account.email.toLowerCase(), ctx);
+      }
+
+      ctx.setStatus({ accountId: ctx.accountId, running: true, connected: true });
+
+      // Create abort signal for stopping the monitor
+      const abortController = new AbortController();
+
+      // Start the Gmail polling monitor
+      monitorGmail({
+        account: ctx.account,
+        onMessage: async (msg) => {
+          await dispatchGmailMessage(ctx, msg);
+        },
+        signal: abortController.signal,
+        log: ctx.log,
+        setStatus: ctx.setStatus,
+      }).catch((err) => {
+        ctx.log?.error(`[gmail] Monitor error: ${String(err)}`);
+      });
+
+      return {
+        stop: async () => {
+          abortController.abort();
+          if (ctx.account.email) {
+            activeAccounts.delete(ctx.account.email.toLowerCase());
+          }
+          ctx.setStatus({ accountId: ctx.accountId, running: false, connected: false });
+        },
+      };
+    },
+  },
+};

package/src/config.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+export const GmailAccountSchema = z.object({
+  accountId: z.string().optional(),
+  name: z.string().optional(),
+  enabled: z.boolean().default(true),
+  email: z.string(), // The Gmail email address
+  allowFrom: z.array(z.string()).default([]),
+  // Gmail specific settings
+  historyId: z.string().optional(), // For resuming history
+  delegate: z.string().optional(), // If using delegation
+  pollIntervalMs: z.number().optional(), // Polling interval in ms (default 60s)
+  // Reply behavior
+  includeQuotedReplies: z.boolean().optional(), // Include thread history in replies (default: true)
+  // Outbound restrictions (security)
+  allowOutboundTo: z.array(z.string()).optional(), // Who we can SEND to (if not set, falls back to allowFrom)
+  threadReplyPolicy: z.enum(["open", "allowlist", "sender-only"]).optional(), // Default: "open" for backwards compat
+});
+
+export const GmailConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  accounts: z.record(GmailAccountSchema).optional(),
+  defaults: z.object({
+    allowFrom: z.array(z.string()).optional(),
+    includeQuotedReplies: z.boolean().default(true), // Global default for quoted replies
+    allowOutboundTo: z.array(z.string()).optional(), // Global default for outbound allowlist
+    threadReplyPolicy: z.enum(["open", "allowlist", "sender-only"]).optional(), // Global default
+  }).optional(),
+});
+
+export type GmailConfig = z.infer<typeof GmailConfigSchema>;
+export type GmailAccount = z.infer<typeof GmailAccountSchema>;