aamp-openclaw-plugin 0.1.36 → 0.1.38

package/README.md

@@ -38,6 +38,7 @@ npm run build
         "enabled": true,
         "config": {
           "aampHost": "https://meshmail.ai",
+          "taskDispatchConcurrency": 10,
           "slug": "openclaw-agent",
           "credentialsFile": "~/.openclaw/extensions/aamp-openclaw-plugin/.credentials.json",
           "senderPolicies": [
@@ -57,6 +58,7 @@ npm run build
 ```
 
 If `senderPolicies` is omitted, all senders are accepted. If set, the dispatch sender must match one policy and all configured dispatch-context rules for that sender must pass.
+`taskDispatchConcurrency` is optional and defaults to `10`.
 
 The plugin also understands:
 

package/bin/aamp-openclaw-plugin.mjs

@@ -8,6 +8,7 @@ import { stdin as input, stdout as output, stderr } from 'node:process'
 import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
+import { AampClient } from 'aamp-sdk'
 
 const PLUGIN_ID = 'aamp-openclaw-plugin'
 const DEFAULT_AAMP_HOST = 'https://meshmail.ai'
@@ -444,50 +445,15 @@ export async function ensureMailboxIdentity({ aampHost, slug, credentialsFile })
     }
   }
 
-  const base = normalizeBaseUrl(aampHost)
-  const discoveryRes = await fetch(`${base}/.well-known/aamp`)
-  if (!discoveryRes.ok) {
-    const text = await discoveryRes.text().catch(() => '')
-    throw new Error(`AAMP discovery failed (${discoveryRes.status}): ${text || discoveryRes.statusText}`)
-  }
-  const discovery = await discoveryRes.json()
-  const apiUrl = discovery?.api?.url
-  if (!apiUrl) {
-    throw new Error('AAMP discovery did not return api.url')
-  }
-  const apiBase = new URL(apiUrl, `${base}/`).toString()
-
-  const registerRes = await fetch(`${apiBase}?action=aamp.mailbox.register`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      slug,
-      description: 'OpenClaw AAMP agent node',
-    }),
+  const credData = await AampClient.registerMailbox({
+    aampHost: normalizeBaseUrl(aampHost),
+    slug,
+    description: 'OpenClaw AAMP agent node',
   })
-
-  if (!registerRes.ok) {
-    const text = await registerRes.text().catch(() => '')
-    throw new Error(`AAMP self-register failed (${registerRes.status}): ${text || registerRes.statusText}`)
-  }
-
-  const registerData = await registerRes.json()
-  const code = registerData?.registrationCode
-  if (!code) {
-    throw new Error('AAMP self-register succeeded but no registrationCode was returned')
-  }
-
-  const credRes = await fetch(`${apiBase}?action=aamp.mailbox.credentials&code=${encodeURIComponent(code)}`)
-  if (!credRes.ok) {
-    const text = await credRes.text().catch(() => '')
-    throw new Error(`AAMP credential exchange failed (${credRes.status}): ${text || credRes.statusText}`)
-  }
-
-  const credData = await credRes.json()
   const identity = {
     email: credData?.email,
-    mailboxToken: credData?.mailbox?.token ?? credData?.jmap?.token,
-    smtpPassword: credData?.smtp?.password,
+    mailboxToken: credData?.mailboxToken,
+    smtpPassword: credData?.smtpPassword,
   }
 
   if (!identity.email || !identity.mailboxToken || !identity.smtpPassword) {

package/dist/index.js

@@ -1,12 +1,13 @@
-// ../sdk/src/jmap-push.js
+// ../sdk/dist/jmap-push.js
 import WebSocket from "ws";
 
-// ../sdk/src/types.js
+// ../sdk/dist/types.js
 var AAMP_PROTOCOL_VERSION = "1.1";
 var AAMP_HEADER = {
   VERSION: "X-AAMP-Version",
   INTENT: "X-AAMP-Intent",
   TASK_ID: "X-AAMP-TaskId",
+  SESSION_KEY: "X-AAMP-Session-Key",
   CONTEXT_LINKS: "X-AAMP-ContextLinks",
   DISPATCH_CONTEXT: "X-AAMP-Dispatch-Context",
   PRIORITY: "X-AAMP-Priority",
@@ -23,7 +24,7 @@ var AAMP_HEADER = {
   CARD_SUMMARY: "X-AAMP-Card-Summary"
 };
 
-// ../sdk/src/parser.js
+// ../sdk/dist/parser.js
 function normalizeBodyText(value) {
   return value?.replace(/\r\n/g, "\n").trim() ?? "";
 }
@@ -171,6 +172,7 @@ function parseAampHeaders(meta) {
   if (intent === "task.dispatch") {
     const contextLinksStr = getAampHeader(headers, AAMP_HEADER.CONTEXT_LINKS) ?? "";
     const dispatchContext = parseDispatchContextHeader(getAampHeader(headers, AAMP_HEADER.DISPATCH_CONTEXT));
+    const sessionKey = getAampHeader(headers, AAMP_HEADER.SESSION_KEY);
     const parentTaskId = getAampHeader(headers, AAMP_HEADER.PARENT_TASK_ID);
     const priority = getAampHeader(headers, AAMP_HEADER.PRIORITY) ?? "normal";
     const expiresAt = getAampHeader(headers, AAMP_HEADER.EXPIRES_AT);
@@ -178,6 +180,7 @@ function parseAampHeaders(meta) {
       protocolVersion,
       intent: "task.dispatch",
       taskId,
+      ...sessionKey ? { sessionKey } : {},
       title: decodedSubject.replace(/^\[AAMP Task\]\s*/, "").trim() || "Untitled Task",
       priority: priority === "urgent" || priority === "high" ? priority : "normal",
       ...expiresAt ? { expiresAt } : {},
@@ -310,6 +313,9 @@ function buildDispatchHeaders(params) {
   if (params.expiresAt) {
     headers[AAMP_HEADER.EXPIRES_AT] = params.expiresAt;
   }
+  if (params.sessionKey?.trim()) {
+    headers[AAMP_HEADER.SESSION_KEY] = params.sessionKey.trim();
+  }
   if (params.contextLinks.length > 0) {
     headers[AAMP_HEADER.CONTEXT_LINKS] = params.contextLinks.join(",");
   }
@@ -381,7 +387,7 @@ function buildCardResponseHeaders(params) {
   };
 }
 
-// ../sdk/src/tiny-emitter.js
+// ../sdk/dist/tiny-emitter.js
 var TinyEmitter = class {
   listeners = /* @__PURE__ */ new Map();
   onceWrappers = /* @__PURE__ */ new WeakMap();
@@ -421,9 +427,20 @@ var TinyEmitter = class {
     }
     return true;
   }
+  async emitAsync(event, ...args) {
+    const bucket = this.listeners.get(event);
+    if (!bucket || bucket.size === 0)
+      return false;
+    const settled = await Promise.allSettled([...bucket].map((listener) => Promise.resolve(listener(...args))));
+    const rejected = settled.find((result) => result.status === "rejected");
+    if (rejected) {
+      throw rejected.reason;
+    }
+    return true;
+  }
 };
 
-// ../sdk/src/jmap-push.js
+// ../sdk/dist/jmap-push.js
 function describeError(err) {
   if (!(err instanceof Error))
     return String(err);
@@ -1103,7 +1120,7 @@ var JmapPushClient = class extends TinyEmitter {
   }
 };
 
-// ../sdk/src/smtp-sender.js
+// ../sdk/dist/smtp-sender.js
 import { createTransport } from "nodemailer";
 import { randomUUID } from "crypto";
 var sanitize = (s) => s.replace(/[\r\n]/g, " ").trim();
@@ -1361,7 +1378,7 @@ var SmtpSender = class _SmtpSender {
       from: this.config.user,
       to: opts.to,
       subject: `[AAMP Task] ${sanitize(opts.title)}`,
-      text: [
+      text: opts.rawBodyText ?? [
         `Task: ${opts.title}`,
         `Task ID: ${taskId}`,
         `Priority: ${opts.priority ?? "normal"}`,
@@ -1429,7 +1446,7 @@ ${opts.contextLinks.map((l) => `  ${l}`).join("\n")}` : "",
       from: this.config.user,
       to: opts.to,
       subject: `[AAMP Result] Task ${opts.taskId} \u2014 ${opts.status}`,
-      text: [
+      text: opts.rawBodyText ?? [
         `AAMP Task Result`,
         ``,
         `Task ID: ${opts.taskId}`,
@@ -1503,7 +1520,7 @@ Error: ${opts.errorMsg}` : ""
       from: this.config.user,
       to: opts.to,
       subject: `[AAMP Help] Task ${opts.taskId} needs assistance`,
-      text: [
+      text: opts.rawBodyText ?? [
         `AAMP Task Help Request`,
         ``,
         `Task ID: ${opts.taskId}`,
@@ -1819,7 +1836,7 @@ Stream ID: ${opts.streamId}`,
   }
 };
 
-// ../sdk/src/thread.js
+// ../sdk/dist/thread.js
 function singleLine(value, maxLength = 220) {
   const normalized = (value ?? "").replace(/\s+/g, " ").trim();
   if (!normalized)
@@ -1873,7 +1890,7 @@ function renderThreadHistoryForAgent(events, options = {}) {
   ].join("\n");
 }
 
-// ../sdk/src/client.js
+// ../sdk/dist/client.js
 function buildRegisteredCommandDispatchPayload(opts) {
   const command = opts.command.trim();
   if (!command) {
@@ -1897,14 +1914,27 @@ function buildRegisteredCommandDispatchPayload(opts) {
     stream: { mode: opts.streamMode ?? "full" }
   };
 }
+var DEFAULT_TASK_DISPATCH_CONCURRENCY = 10;
+function normalizeTaskDispatchConcurrency(value) {
+  if (value == null)
+    return DEFAULT_TASK_DISPATCH_CONCURRENCY;
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+    throw new Error("taskDispatchConcurrency must be a positive integer");
+  }
+  return value;
+}
 var AampClient = class _AampClient extends TinyEmitter {
   jmapClient;
   smtpSender;
   config;
+  taskDispatchConcurrency;
+  pendingTaskDispatches = [];
+  activeTaskDispatchCount = 0;
   streamAppendQueues = /* @__PURE__ */ new Map();
   constructor(config) {
     super();
     this.config = config;
+    this.taskDispatchConcurrency = normalizeTaskDispatchConcurrency(config.taskDispatchConcurrency);
     const mailboxToken = config.mailboxToken;
     const resolvedBaseUrl = config.baseUrl;
     const derived = deriveMailboxServiceDefaults(config.email, resolvedBaseUrl);
@@ -1940,7 +1970,7 @@ var AampClient = class _AampClient extends TinyEmitter {
       rejectUnauthorized: config.rejectUnauthorized
     });
     this.jmapClient.on("task.dispatch", (task) => {
-      this.emit("task.dispatch", task);
+      this.enqueueTaskDispatch(task);
     });
     this.jmapClient.on("task.cancel", (task) => {
       this.emit("task.cancel", task);
@@ -1993,6 +2023,7 @@ var AampClient = class _AampClient extends TinyEmitter {
       smtpPort: config.smtpPort ?? 587,
       smtpPassword: config.smtpPassword,
       reconnectInterval: config.reconnectInterval,
+      taskDispatchConcurrency: config.taskDispatchConcurrency,
       rejectUnauthorized: config.rejectUnauthorized
     });
   }
@@ -2063,6 +2094,22 @@ var AampClient = class _AampClient extends TinyEmitter {
       baseUrl: base
     };
   }
+  static async checkMailbox(opts) {
+    const base = opts.aampHost.replace(/\/$/, "");
+    const res = await _AampClient.callDiscoveredApi(base, {
+      action: "aamp.mailbox.check",
+      query: { email: opts.email }
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Mailbox check failed: ${res.status} ${body || res.statusText}`);
+    }
+    const payload = await res.json();
+    return {
+      aamp: Boolean(payload.aamp),
+      ...payload.domain ? { domain: payload.domain } : {}
+    };
+  }
   // =====================================================
   // Lifecycle
   // =====================================================
@@ -2109,6 +2156,7 @@ var AampClient = class _AampClient extends TinyEmitter {
       rawBodyText: JSON.stringify(payload, null, 2),
       priority: opts.priority,
       expiresAt: opts.expiresAt,
+      sessionKey: opts.sessionKey,
       contextLinks: opts.contextLinks,
       dispatchContext: opts.dispatchContext,
       parentTaskId: opts.parentTaskId,
@@ -2246,6 +2294,30 @@ var AampClient = class _AampClient extends TinyEmitter {
     }
     return res.json();
   }
+  enqueueTaskDispatch(task) {
+    this.pendingTaskDispatches.push(task);
+    this.drainTaskDispatchQueue();
+  }
+  drainTaskDispatchQueue() {
+    while (this.activeTaskDispatchCount < this.taskDispatchConcurrency && this.pendingTaskDispatches.length > 0) {
+      const nextTask = this.pendingTaskDispatches.shift();
+      if (!nextTask)
+        return;
+      this.activeTaskDispatchCount += 1;
+      void this.runTaskDispatch(nextTask);
+    }
+  }
+  async runTaskDispatch(task) {
+    try {
+      await this.emitAsync("task.dispatch", task);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", error);
+    } finally {
+      this.activeTaskDispatchCount = Math.max(0, this.activeTaskDispatchCount - 1);
+      this.drainTaskDispatchQueue();
+    }
+  }
   getStreamAppendQueue(streamId) {
     let queue = this.streamAppendQueues.get(streamId);
     if (!queue) {
@@ -2706,6 +2778,10 @@ function isSyntheticPendingKey(taskKey) {
 function isTaskAwaitingHelpReply(task) {
   return task.awaitingHelpReply === true;
 }
+function isConversationalTask(task) {
+  const source = task.dispatchContext?.source?.trim().toLowerCase();
+  return source === "feishu" || source === "wechat";
+}
 function threadAlreadyTerminal(events) {
   return (events ?? []).some(
     (event) => event.intent === "task.result" || event.intent === "task.cancel"
@@ -2752,12 +2828,36 @@ function buildOpenClawMainSessionKey(mainKey, config) {
 function buildAampConversationSessionKey(value, config) {
   return buildOpenClawMainSessionKey(`${AAMP_SESSION_PREFIX}default:${value}`, config);
 }
+function buildAampStickySessionKey(sessionKey, config) {
+  const stickyValue = sessionKey?.trim();
+  if (!stickyValue)
+    return void 0;
+  return buildAampConversationSessionKey(`session:${stickyValue}`, config);
+}
 function buildAampTaskSessionKey(taskId, config) {
   return buildAampConversationSessionKey(`task:${taskId}`, config);
 }
 function buildAampWakeSessionKey(kind, id) {
   return `${AAMP_SESSION_PREFIX}wake:${kind}:${id}`;
 }
+function buildSessionKeyForPendingTask(task, config) {
+  return buildAampStickySessionKey(task.sessionKey, config) ?? buildAampTaskSessionKey(task.taskId, config);
+}
+function buildWakeSessionKeyForPendingTask(task, config) {
+  return buildAampStickySessionKey(task.sessionKey, config) ?? buildAampWakeSessionKey("task", task.taskId);
+}
+function findPendingEntryForSession(sessionKey, config) {
+  if (typeof sessionKey !== "string" || !isAampSessionKey(sessionKey))
+    return void 0;
+  const requested = buildOpenClawMainSessionKey(stripOpenClawAgentScope(sessionKey), config);
+  const entries = [...pendingTasks.entries()].filter(([key, task]) => isActionablePendingTask(key, task)).filter(([, task]) => buildSessionKeyForPendingTask(task, config) === requested).sort((a, b) => {
+    const rankDiff = priorityRank(a[1].priority) - priorityRank(b[1].priority);
+    if (rankDiff !== 0)
+      return rankDiff;
+    return new Date(a[1].receivedAt).getTime() - new Date(b[1].receivedAt).getTime();
+  });
+  return entries[0];
+}
 function resolvePendingKeyFromSessionKey(sessionKey) {
   if (typeof sessionKey !== "string")
     return void 0;
@@ -2848,6 +2948,7 @@ function queuePendingTask(task) {
     from: task.from,
     title: task.title,
     bodyText: task.bodyText ?? "",
+    dispatchContext: task.dispatchContext,
     threadHistory: task.threadHistory ?? [],
     threadContextText: task.threadContextText ?? "",
     priority: task.priority ?? "normal",
@@ -2865,39 +2966,15 @@ function queuePendingTask(task) {
 }
 async function registerNode(cfg) {
   const slug = (cfg.slug ?? "openclaw-agent").toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "");
-  const base = baseUrl(cfg.aampHost);
-  const discoveryRes = await fetch(`${base}/.well-known/aamp`);
-  if (!discoveryRes.ok) {
-    throw new Error(`AAMP discovery failed (${discoveryRes.status}): ${discoveryRes.statusText}`);
-  }
-  const discovery = await discoveryRes.json();
-  const apiUrl = discovery.api?.url;
-  if (!apiUrl) {
-    throw new Error("AAMP discovery did not return api.url");
-  }
-  const apiBase = new URL(apiUrl, `${base}/`).toString();
-  const res = await fetch(`${apiBase}?action=aamp.mailbox.register`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ slug, description: "OpenClaw AAMP agent node" })
+  const credData = await AampClient.registerMailbox({
+    aampHost: cfg.aampHost,
+    slug,
+    description: "OpenClaw AAMP agent node"
   });
-  if (!res.ok) {
-    const err = await res.json().catch(() => ({}));
-    throw new Error(`AAMP registration failed (${res.status}): ${err.error ?? res.statusText}`);
-  }
-  const regData = await res.json();
-  const credRes = await fetch(
-    `${apiBase}?action=aamp.mailbox.credentials&code=${encodeURIComponent(regData.registrationCode)}`
-  );
-  if (!credRes.ok) {
-    const err = await credRes.json().catch(() => ({}));
-    throw new Error(`AAMP credential exchange failed (${credRes.status}): ${err.error ?? credRes.statusText}`);
-  }
-  const credData = await credRes.json();
   return {
     email: credData.email,
-    mailboxToken: credData.mailbox.token,
-    smtpPassword: credData.smtp.password
+    mailboxToken: credData.mailboxToken,
+    smtpPassword: credData.smtpPassword
   };
 }
 async function resolveIdentity(cfg) {
@@ -3030,8 +3107,8 @@ var src_default = {
       api.logger.info(`[AAMP] Directory profile synced${cardText ? " (card text registered)" : ""}`);
     }
     function wakeAgentForPendingTask(task) {
-      const fallbackSessionKey = buildAampWakeSessionKey("task", task.taskId);
-      const openClawSessionKey = buildAampTaskSessionKey(task.taskId, api.config);
+      const fallbackSessionKey = buildWakeSessionKeyForPendingTask(task, api.config);
+      const openClawSessionKey = buildSessionKeyForPendingTask(task, api.config);
       const fallback = () => triggerHeartbeatWake(fallbackSessionKey, `task ${task.taskId}`);
       const dispatcher = channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher;
       api.logger.info(
@@ -3117,13 +3194,14 @@ var src_default = {
         email: identity.email,
         smtpPassword: identity.smtpPassword,
         baseUrl: base,
+        taskDispatchConcurrency: cfg.taskDispatchConcurrency,
         // Local/dev: management-service proxy uses plain HTTP, no TLS cert to verify.
         // Production: set to true when using wss:// with valid certs.
         rejectUnauthorized: false
       });
       aampClient.on("task.dispatch", (task) => {
         api.logger.info(`[AAMP] \u2190 task.dispatch  ${task.taskId}  "${task.title}"  from=${task.from}`);
-        void (async () => {
+        return (async () => {
           try {
             if (terminalTaskIds.has(task.taskId)) {
               api.logger.info(`[AAMP] Skipping already-terminal task ${task.taskId}`);
@@ -3167,7 +3245,7 @@ var src_default = {
           } catch (err) {
             api.logger.error(`[AAMP] task.dispatch handler failed for ${task.taskId}: ${err.message}`);
             if (pendingTasks.has(task.taskId)) {
-              triggerHeartbeatWake(buildAampWakeSessionKey("task", task.taskId), `task ${task.taskId}`);
+              triggerHeartbeatWake(buildWakeSessionKeyForPendingTask(pendingTasks.get(task.taskId), api.config), `task ${task.taskId}`);
             }
           }
         })();
@@ -3567,7 +3645,8 @@ ${notifyBody?.bodyText ?? help.question}`;
           }
           return [targetedPendingKey, targetedTask];
         })() : void 0;
-        const nextEntry = targetedPendingKey ? targetedEntry : nextPendingEntry();
+        const sessionScopedEntry = targetedPendingKey ? void 0 : findPendingEntryForSession(ctx?.sessionKey, api.config);
+        const nextEntry = targetedPendingKey ? targetedEntry : sessionScopedEntry ?? nextPendingEntry();
         if (!nextEntry)
           return {};
         const [taskKey, task] = nextEntry;
@@ -3602,19 +3681,45 @@ ${notifyBody?.bodyText ?? help.question}`;
             `   Example: attachments: [{ filename: "file.html", path: "/tmp/aamp-files/file.html" }]`
           ] : []
         ].join("\n") : "";
-        const lines = isNotification ? [
-          `## Sub-task Update`,
+        const dispatchContextLines = task.dispatchContext && Object.keys(task.dispatchContext).length > 0 ? `Dispatch Context:
+${Object.entries(task.dispatchContext).map(([key, value]) => `  - ${key}: ${value}`).join("\n")}` : "";
+        const taskPromptLines = isConversationalTask(task) ? [
+          `## Pending AAMP Conversation Turn`,
           ``,
-          `A sub-task you dispatched has returned a result. Review the information below.`,
-          `If the sub-task included attachments, use aamp_download_attachment to fetch them.`,
+          `This AAMP task came from a chat surface (${task.dispatchContext?.source ?? "unknown"}).`,
+          `Treat it as an ongoing conversation turn, not a one-off work order.`,
+          `Your job is to reply naturally to the user's latest message and keep the conversation moving.`,
+          ``,
+          `### Tool selection rules for chat turns:`,
+          ``,
+          `Use aamp_send_result for normal conversation replies, including:`,
+          `  - greetings, acknowledgements, and small talk ("hi", "hello", "thanks", "got it")`,
+          `  - short follow-up questions that help narrow the user's intent`,
+          `  - direct answers, suggestions, or next-step guidance`,
+          ``,
+          `Use aamp_send_help ONLY when you are truly blocked and cannot produce a meaningful`,
+          `reply without waiting for specific missing information from the human.`,
+          `Do NOT use aamp_send_help just because the message is brief or casual.`,
+          ``,
+          `IMPORTANT: For conversational traffic, replying to "hi" with a natural greeting and an`,
+          `offer to help is CORRECT. Do not reject greetings as invalid tasks.`,
+          ``,
+          `### Sub-task dispatch rules:`,
+          `If you delegate work to another agent via aamp_dispatch_task, you MUST pass`,
+          `parentTaskId: "${task.taskId}" to establish the parent-child relationship.`,
+          `If you need to find a suitable agent first, call aamp_directory_search.`,
           ``,
           `Task ID:  ${task.taskId}`,
-          `Priority: ${task.priority}`,
           `From:     ${task.from}`,
           `Title:    ${task.title}`,
-          task.bodyText ? `
+          dispatchContextLines,
+          task.threadContextText ? `${task.threadContextText}` : "",
+          task.bodyText ? `Latest user message:
 ${task.bodyText}` : "",
-          actionRequiredSection,
+          task.contextLinks.length ? `Context Links:
+${task.contextLinks.map((l) => `  - ${l}`).join("\n")}` : "",
+          task.expiresAt ? `Expires: ${task.expiresAt}` : `Expires: none`,
+          `Received: ${task.receivedAt}`,
           otherActionableTasks.length > 0 ? `
 (+${otherActionableTasks.length} more tasks queued)` : ""
         ] : [
@@ -3649,6 +3754,7 @@ ${task.bodyText}` : "",
           `Task ID:  ${task.taskId}`,
           `From:     ${task.from}`,
           `Title:    ${task.title}`,
+          dispatchContextLines,
           task.threadContextText ? `${task.threadContextText}` : "",
           task.bodyText ? `Description:
 ${task.bodyText}` : "",
@@ -3658,7 +3764,23 @@ ${task.contextLinks.map((l) => `  - ${l}`).join("\n")}` : "",
           `Received: ${task.receivedAt}`,
           otherActionableTasks.length > 0 ? `
 (+${otherActionableTasks.length} more tasks queued)` : ""
-        ].filter(Boolean).join("\n");
+        ];
+        const lines = isNotification ? [
+          `## Sub-task Update`,
+          ``,
+          `A sub-task you dispatched has returned a result. Review the information below.`,
+          `If the sub-task included attachments, use aamp_download_attachment to fetch them.`,
+          ``,
+          `Task ID:  ${task.taskId}`,
+          `Priority: ${task.priority}`,
+          `From:     ${task.from}`,
+          `Title:    ${task.title}`,
+          task.bodyText ? `
+${task.bodyText}` : "",
+          actionRequiredSection,
+          otherActionableTasks.length > 0 ? `
+(+${otherActionableTasks.length} more tasks queued)` : ""
+        ] : taskPromptLines.filter(Boolean).join("\n");
         return { prependContext: lines };
       },
       { priority: 5 }
@@ -4075,17 +4197,9 @@ ${lines.join("\n")}`
               const dir = "/tmp/aamp-files";
               ensureDir(dir);
               const downloaded = [];
-              const base = baseUrl(cfg.aampHost);
-              const identity = loadCachedIdentity(cfg.credentialsFile ?? defaultCredentialsPath());
-              const authHeader = identity ? `Basic ${Buffer.from(identity.email + ":" + identity.smtpPassword).toString("base64")}` : "";
               for (const att of r.attachments) {
                 try {
-                  const dlUrl = `${base}/jmap/download/n/${encodeURIComponent(att.blobId)}/${encodeURIComponent(att.filename)}?accept=application/octet-stream`;
-                  api.logger.info(`[AAMP] Fetching ${dlUrl}`);
-                  const dlRes = await fetch(dlUrl, { headers: { Authorization: authHeader } });
-                  if (!dlRes.ok)
-                    throw new Error(`HTTP ${dlRes.status}`);
-                  const buffer = Buffer.from(await dlRes.arrayBuffer());
+                  const buffer = await aampClient.downloadBlob(att.blobId, att.filename);
                   const filepath = `${dir}/${att.filename}`;
                   writeBinaryFile(filepath, buffer);
                   downloaded.push(`${att.filename} (${(buffer.length / 1024).toFixed(1)} KB) \u2192 ${filepath}`);
@@ -4157,18 +4271,10 @@ Question: ${h.question}`,
           return { content: [{ type: "text", text: "Error: email parameter is required" }] };
         }
         try {
-          const discoveryRes = await fetch(`${base}/.well-known/aamp`);
-          if (!discoveryRes.ok)
-            throw new Error(`HTTP ${discoveryRes.status}`);
-          const discovery = await discoveryRes.json();
-          const apiUrl = discovery.api?.url;
-          if (!apiUrl)
-            throw new Error("AAMP discovery did not return api.url");
-          const apiBase = new URL(apiUrl, `${base}/`).toString();
-          const res = await fetch(`${apiBase}?action=aamp.mailbox.check&email=${encodeURIComponent(email)}`);
-          if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-          const data = await res.json();
+          const data = await AampClient.checkMailbox({
+            aampHost: base,
+            email
+          });
           return {
             content: [{
               type: "text",