aamp-openclaw-plugin 0.1.39 → 0.1.42

package/README.md

@@ -4,6 +4,10 @@ OpenClaw plugin that gives an OpenClaw agent an AAMP mailbox identity.
 
 ## Install
 
+Requires OpenClaw `>=2026.3.22`. Both `openclaw plugins install` and
+`npx aamp-openclaw-plugin init` stop before installation when the detected
+OpenClaw version is older.
+
 ```bash
 npm install aamp-openclaw-plugin
 ```

package/bin/aamp-openclaw-plugin.mjs

@@ -15,6 +15,8 @@ const DEFAULT_AAMP_HOST = 'https://meshmail.ai'
 const DEFAULT_CREDENTIALS_FILE = '~/.openclaw/extensions/aamp-openclaw-plugin/.credentials.json'
 const DEFAULT_PAIRING_FILE = '~/.openclaw/extensions/aamp-openclaw-plugin/.pairing.json'
 const DEFAULT_SENDER_POLICIES_FILE = '~/.openclaw/extensions/aamp-openclaw-plugin/.sender-policies.json'
+export const MIN_OPENCLAW_VERSION = '2026.3.22'
+export const MIN_OPENCLAW_VERSION_RANGE = `>=${MIN_OPENCLAW_VERSION}`
 const CODING_TOOL_ALLOWLIST = [
   'read',
   'write',
@@ -200,6 +202,108 @@ export function normalizeBaseUrl(url) {
   return `https://${url.replace(/\/$/, '')}`
 }
 
+export function parseOpenClawVersion(outputText) {
+  const match = String(outputText ?? '').match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/)
+  return match?.[1] ?? null
+}
+
+function parseVersionParts(version) {
+  const [withoutBuild] = String(version ?? '').split('+', 1)
+  const prereleaseIndex = withoutBuild.indexOf('-')
+  const core = prereleaseIndex === -1 ? withoutBuild : withoutBuild.slice(0, prereleaseIndex)
+  const prereleaseText = prereleaseIndex === -1 ? '' : withoutBuild.slice(prereleaseIndex + 1)
+  const numbers = core.split('.').map((part) => Number(part))
+  if (numbers.length !== 3 || numbers.some((part) => !Number.isInteger(part) || part < 0)) {
+    return null
+  }
+  const prerelease = prereleaseText ? prereleaseText.split('.') : []
+  return { numbers, prerelease }
+}
+
+function comparePrereleaseIdentifier(left, right) {
+  const leftNumeric = /^\d+$/.test(left)
+  const rightNumeric = /^\d+$/.test(right)
+  if (leftNumeric && rightNumeric) return Number(left) - Number(right)
+  if (leftNumeric) return -1
+  if (rightNumeric) return 1
+  return left.localeCompare(right)
+}
+
+export function compareOpenClawVersions(leftVersion, rightVersion) {
+  const left = parseVersionParts(leftVersion)
+  const right = parseVersionParts(rightVersion)
+  if (!left || !right) {
+    throw new Error(`Invalid OpenClaw version comparison: ${leftVersion} vs ${rightVersion}`)
+  }
+
+  for (let idx = 0; idx < 3; idx += 1) {
+    const diff = left.numbers[idx] - right.numbers[idx]
+    if (diff !== 0) return diff
+  }
+
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0
+  if (left.prerelease.length === 0) return 1
+  if (right.prerelease.length === 0) return -1
+
+  const maxLength = Math.max(left.prerelease.length, right.prerelease.length)
+  for (let idx = 0; idx < maxLength; idx += 1) {
+    const leftPart = left.prerelease[idx]
+    const rightPart = right.prerelease[idx]
+    if (leftPart === undefined) return -1
+    if (rightPart === undefined) return 1
+    const diff = comparePrereleaseIdentifier(leftPart, rightPart)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+export function checkOpenClawVersion(currentVersion, minimumVersion = MIN_OPENCLAW_VERSION) {
+  const comparison = compareOpenClawVersions(currentVersion, minimumVersion)
+  return {
+    ok: comparison >= 0,
+    currentVersion,
+    minimumVersion,
+    range: `>=${minimumVersion}`,
+  }
+}
+
+export function getCurrentOpenClawVersion() {
+  const result = spawnSync('openclaw', ['--version'], {
+    encoding: 'utf-8',
+  })
+
+  if (result.error) {
+    throw new Error(
+      `OpenClaw CLI was not found. Install OpenClaw ${MIN_OPENCLAW_VERSION_RANGE} or newer before installing ${PLUGIN_ID}.`,
+    )
+  }
+
+  if (result.status !== 0) {
+    const reason = (result.stderr || result.stdout || `exit code ${result.status}`).trim()
+    throw new Error(`Could not detect OpenClaw version: ${reason}`)
+  }
+
+  const version = parseOpenClawVersion(`${result.stdout ?? ''}\n${result.stderr ?? ''}`)
+  if (!version) {
+    throw new Error(`Could not parse OpenClaw version from: ${(result.stdout || result.stderr || '').trim()}`)
+  }
+  return version
+}
+
+export function assertOpenClawVersionSupported(currentVersion = getCurrentOpenClawVersion()) {
+  const check = checkOpenClawVersion(currentVersion)
+  if (check.ok) return check
+
+  throw new Error(
+    [
+      `${PLUGIN_ID} requires OpenClaw ${check.range}.`,
+      `Detected OpenClaw ${check.currentVersion}.`,
+      'Please upgrade OpenClaw, then rerun this installer.',
+      'Example: npm install -g openclaw@latest',
+    ].join('\n'),
+  )
+}
+
 export function ensurePluginConfig(config, pluginConfig, options = {}) {
   const next = config && typeof config === 'object' ? structuredClone(config) : {}
   if (!next.plugins || typeof next.plugins !== 'object') next.plugins = {}
@@ -508,6 +612,7 @@ function printHelp() {
 }
 
 export async function runInit() {
+  const openClawVersionCheck = assertOpenClawVersionSupported()
   const configPath = resolveOpenClawConfigPath()
   const existing = readJsonFile(configPath)
   const previousEntry = existing?.plugins?.entries?.[PLUGIN_ID] ?? existing?.plugins?.entries?.aamp
@@ -530,6 +635,7 @@ export async function runInit() {
     const rl = createInterface({ input, output })
     try {
       output.write('AAMP OpenClaw Plugin Setup\n\n')
+      output.write(`Detected OpenClaw ${openClawVersionCheck.currentVersion} (${MIN_OPENCLAW_VERSION_RANGE} required)\n\n`)
 
       if (previousConfig) {
         output.write(

package/dist/index.js

@@ -1499,12 +1499,34 @@ var SmtpSender = class _SmtpSender {
       return false;
     return Boolean(this.config.httpBaseUrl && this.config.authToken);
   }
+  normalizeAttachments(attachments) {
+    if (!attachments?.length)
+      return void 0;
+    return attachments.map((a) => ({
+      filename: a.filename,
+      contentType: a.contentType,
+      content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content
+    }));
+  }
   getJmapAuthHeader() {
     if (!this.config.authToken) {
       throw new Error("JMAP auth token is not configured");
     }
     return `Basic ${this.config.authToken}`;
   }
+  rewriteUrlToConfiguredOrigin(rawUrl) {
+    const base = this.config.httpBaseUrl?.replace(/\/$/, "");
+    if (!base)
+      return rawUrl;
+    const parsed = new URL(rawUrl, `${base}/`);
+    const configured = new URL(base);
+    parsed.protocol = configured.protocol;
+    parsed.username = configured.username;
+    parsed.password = configured.password;
+    parsed.hostname = configured.hostname;
+    parsed.port = configured.port;
+    return parsed.toString();
+  }
   async resolveJmapSession() {
     const base = this.config.httpBaseUrl?.replace(/\/$/, "");
     if (!base) {
@@ -1525,7 +1547,8 @@ var SmtpSender = class _SmtpSender {
         }
         return {
           accountId,
-          apiUrl: `${base}/jmap/`
+          apiUrl: `${base}/jmap/`,
+          uploadUrl: this.rewriteUrlToConfiguredOrigin(session.uploadUrl ?? `${base}/jmap/upload/{accountId}/`)
         };
       })();
     }
@@ -1562,6 +1585,38 @@ var SmtpSender = class _SmtpSender {
     const data = await res.json();
     return data.methodResponses ?? [];
   }
+  async uploadSentAttachment(attachment) {
+    const session = await this.resolveJmapSession();
+    const content = typeof attachment.content === "string" ? Buffer.from(attachment.content, "base64") : attachment.content;
+    const uploadUrl = session.uploadUrl.replace(/\{accountId\}|%7BaccountId%7D/gi, encodeURIComponent(session.accountId));
+    const res = await this.fetch(uploadUrl, {
+      method: "POST",
+      headers: {
+        Authorization: this.getJmapAuthHeader(),
+        "Content-Type": attachment.contentType
+      },
+      body: content
+    });
+    const bodyText = await res.text();
+    if (!res.ok) {
+      throw new Error(`JMAP attachment upload failed: ${res.status} ${bodyText}`);
+    }
+    let data;
+    try {
+      data = JSON.parse(bodyText);
+    } catch {
+      throw new Error("JMAP attachment upload returned invalid JSON");
+    }
+    if (!data.blobId) {
+      throw new Error("JMAP attachment upload did not return blobId");
+    }
+    return {
+      blobId: data.blobId,
+      type: data.type ?? attachment.contentType,
+      size: data.size ?? content.byteLength,
+      name: attachment.filename
+    };
+  }
   async getSentMailboxId() {
     if (!this.sentMailboxIdPromise) {
       this.sentMailboxIdPromise = (async () => {
@@ -1586,20 +1641,43 @@ var SmtpSender = class _SmtpSender {
     const sentMailboxId = await this.getSentMailboxId();
     if (!sentMailboxId)
       return;
+    const uploadedAttachments = params.attachments?.length ? await Promise.all(params.attachments.map((attachment) => this.uploadSentAttachment(attachment))) : [];
     const emailCreate = {
       mailboxIds: { [sentMailboxId]: true },
       from: [{ email: params.from }],
       to: [{ email: params.to }],
       subject: params.subject,
-      bodyValues: {
+      keywords: { "$seen": true }
+    };
+    if (uploadedAttachments.length) {
+      emailCreate.bodyStructure = {
+        type: "multipart/mixed",
+        subParts: [
+          { partId: "body", type: "text/plain" },
+          ...uploadedAttachments.map((attachment) => ({
+            blobId: attachment.blobId,
+            type: attachment.type,
+            size: attachment.size,
+            name: attachment.name,
+            disposition: "attachment"
+          }))
+        ]
+      };
+      emailCreate.bodyValues = {
+        body: {
+          value: params.text,
+          isTruncated: false
+        }
+      };
+    } else {
+      emailCreate.bodyValues = {
         body: {
           value: params.text,
           charset: "utf-8"
         }
-      },
-      textBody: [{ partId: "body", type: "text/plain" }],
-      keywords: { "$seen": true }
-    };
+      };
+      emailCreate.textBody = [{ partId: "body", type: "text/plain" }];
+    }
     if (params.inReplyTo) {
       emailCreate["header:In-Reply-To:asText"] = ` ${sanitize(params.inReplyTo)}`;
     }
@@ -1622,6 +1700,12 @@ var SmtpSender = class _SmtpSender {
     try {
       await this.saveToSent(params);
     } catch {
+      if (params.attachments?.length) {
+        try {
+          await this.saveToSent({ ...params, attachments: void 0 });
+        } catch {
+        }
+      }
     }
   }
   /**
@@ -1631,6 +1715,7 @@ var SmtpSender = class _SmtpSender {
    */
   async sendTask(opts) {
     const taskId = opts.taskId ?? randomUUID();
+    const attachments = this.normalizeAttachments(opts.attachments);
     const aampHeaders = buildDispatchHeaders({
       taskId,
       priority: opts.priority,
@@ -1653,12 +1738,8 @@ var SmtpSender = class _SmtpSender {
       ].filter(Boolean).join("\n"),
       headers: aampHeaders
     };
-    if (opts.attachments?.length) {
-      sendMailOpts.attachments = opts.attachments.map((a) => ({
-        filename: a.filename,
-        content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content,
-        contentType: a.contentType
-      }));
+    if (attachments) {
+      sendMailOpts.attachments = attachments;
     }
     if (this.shouldUseHttpFallback(opts.to)) {
       const info2 = await this.sendViaHttp({
@@ -1666,11 +1747,7 @@ var SmtpSender = class _SmtpSender {
         subject: sendMailOpts.subject,
         text: sendMailOpts.text,
         aampHeaders,
-        attachments: opts.attachments?.map((a) => ({
-          filename: a.filename,
-          contentType: a.contentType,
-          content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content
-        }))
+        attachments
       });
       await this.saveToSentBestEffort({
         from: this.config.user,
@@ -1678,7 +1755,8 @@ var SmtpSender = class _SmtpSender {
         subject: sendMailOpts.subject,
         text: sendMailOpts.text,
         aampHeaders,
-        messageId: info2.messageId
+        messageId: info2.messageId,
+        attachments
       });
       return { taskId, messageId: info2.messageId ?? "" };
     }
@@ -1689,7 +1767,8 @@ var SmtpSender = class _SmtpSender {
       subject: sendMailOpts.subject,
       text: sendMailOpts.text,
       aampHeaders,
-      messageId: info.messageId
+      messageId: info.messageId,
+      attachments
     });
     return { taskId, messageId: info.messageId ?? "" };
   }
@@ -1697,6 +1776,7 @@ var SmtpSender = class _SmtpSender {
    * Send a task.result email back to the dispatcher
    */
   async sendResult(opts) {
+    const attachments = this.normalizeAttachments(opts.attachments);
     const aampHeaders = buildResultHeaders({
       taskId: opts.taskId,
       status: opts.status,
@@ -1725,12 +1805,8 @@ Error: ${opts.errorMsg}` : ""
       mailOpts.inReplyTo = opts.inReplyTo;
       mailOpts.references = opts.inReplyTo;
     }
-    if (opts.attachments?.length) {
-      mailOpts.attachments = opts.attachments.map((a) => ({
-        filename: a.filename,
-        content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content,
-        contentType: a.contentType
-      }));
+    if (attachments) {
+      mailOpts.attachments = attachments;
     }
     if (this.shouldUseHttpFallback(opts.to)) {
       const info2 = await this.sendViaHttp({
@@ -1738,11 +1814,7 @@ Error: ${opts.errorMsg}` : ""
         subject: mailOpts.subject,
         text: mailOpts.text,
         aampHeaders,
-        attachments: opts.attachments?.map((a) => ({
-          filename: a.filename,
-          contentType: a.contentType,
-          content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content
-        }))
+        attachments
       });
       await this.saveToSentBestEffort({
         from: this.config.user,
@@ -1752,7 +1824,8 @@ Error: ${opts.errorMsg}` : ""
         aampHeaders,
         messageId: info2.messageId,
         inReplyTo: opts.inReplyTo,
-        references: opts.inReplyTo
+        references: opts.inReplyTo,
+        attachments
       });
       return;
     }
@@ -1765,13 +1838,15 @@ Error: ${opts.errorMsg}` : ""
       aampHeaders,
       messageId: info.messageId,
       inReplyTo: opts.inReplyTo,
-      references: opts.inReplyTo
+      references: opts.inReplyTo,
+      attachments
     });
   }
   /**
    * Send a task.help_needed email when the agent is blocked
    */
   async sendHelp(opts) {
+    const attachments = this.normalizeAttachments(opts.attachments);
     const aampHeaders = buildHelpHeaders({
       taskId: opts.taskId,
       question: opts.question,
@@ -1800,12 +1875,8 @@ ${opts.suggestedOptions.map((o, i) => `  ${i + 1}. ${o}`).join("\n")}` : ""
       helpMailOpts.inReplyTo = opts.inReplyTo;
       helpMailOpts.references = opts.inReplyTo;
     }
-    if (opts.attachments?.length) {
-      helpMailOpts.attachments = opts.attachments.map((a) => ({
-        filename: a.filename,
-        content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content,
-        contentType: a.contentType
-      }));
+    if (attachments) {
+      helpMailOpts.attachments = attachments;
     }
     if (this.shouldUseHttpFallback(opts.to)) {
       const info2 = await this.sendViaHttp({
@@ -1813,11 +1884,7 @@ ${opts.suggestedOptions.map((o, i) => `  ${i + 1}. ${o}`).join("\n")}` : ""
         subject: helpMailOpts.subject,
         text: helpMailOpts.text,
         aampHeaders,
-        attachments: opts.attachments?.map((a) => ({
-          filename: a.filename,
-          contentType: a.contentType,
-          content: typeof a.content === "string" ? Buffer.from(a.content, "base64") : a.content
-        }))
+        attachments
       });
       await this.saveToSentBestEffort({
         from: this.config.user,
@@ -1827,7 +1894,8 @@ ${opts.suggestedOptions.map((o, i) => `  ${i + 1}. ${o}`).join("\n")}` : ""
         aampHeaders,
         messageId: info2.messageId,
         inReplyTo: opts.inReplyTo,
-        references: opts.inReplyTo
+        references: opts.inReplyTo,
+        attachments
       });
       return;
     }
@@ -1840,7 +1908,8 @@ ${opts.suggestedOptions.map((o, i) => `  ${i + 1}. ${o}`).join("\n")}` : ""
       aampHeaders,
       messageId: info.messageId,
       inReplyTo: opts.inReplyTo,
-      references: opts.inReplyTo
+      references: opts.inReplyTo,
+      attachments
     });
   }
   /**
@@ -3652,24 +3721,24 @@ var src_default = {
         return;
       if (request.to.trim().toLowerCase() !== agentEmail.trim().toLowerCase())
         return;
+      const senderPoliciesFile = cfg.senderPoliciesFile ?? defaultSenderPoliciesPath();
       const consumed = consumePairingCode2({
         file: cfg.pairingFile ?? defaultPairingPath(),
         mailbox: agentEmail,
         pairCode: request.pairCode
       });
-      if (!consumed) {
-        const reason = "invalid or expired pair code";
-        api.logger.warn(`[AAMP] Rejected pair.request from ${request.from}: ${reason}`);
-        await sendPairResponse(request, false, reason);
-        return;
+      const pairResponse = consumed ? { success: true } : { success: false, reason: "invalid or expired pair code" };
+      if (pairResponse.success) {
+        pairedSenderPolicies = addPairedSenderPolicy(senderPoliciesFile, {
+          sender: request.from.trim().toLowerCase(),
+          dispatchContextRules: request.dispatchContextRules ?? {},
+          pairedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        api.logger.info(`[AAMP] Paired sender ${request.from}; sender policy saved to ${senderPoliciesFile}`);
+      } else {
+        api.logger.warn(`[AAMP] Rejected pair.request from ${request.from}: ${pairResponse.reason}`);
       }
-      pairedSenderPolicies = addPairedSenderPolicy(cfg.senderPoliciesFile ?? defaultSenderPoliciesPath(), {
-        sender: request.from.trim().toLowerCase(),
-        dispatchContextRules: request.dispatchContextRules ?? {},
-        pairedAt: (/* @__PURE__ */ new Date()).toISOString()
-      });
-      api.logger.info(`[AAMP] Paired sender ${request.from}; sender policy saved to ${cfg.senderPoliciesFile ?? defaultSenderPoliciesPath()}`);
-      await sendPairResponse(request, true);
+      await sendPairResponse(request, pairResponse.success, pairResponse.reason);
     }
     async function renderPairingCodeForCurrentAgent() {
       const identity = agentEmail ? { email: agentEmail } : loadCachedIdentity(cfg.credentialsFile ?? defaultCredentialsPath());