mercury-agent 0.4.5

package/examples/extensions/web-search/skill/references/hotels.md

@@ -0,0 +1,148 @@
+# Hotels Reference
+
+## Primary site: Google Hotels
+
+**Why Google Hotels:**
+- Deep-link URL accepts city, dates, and guest counts
+- Clean accessibility tree: hotel cards have price, rating, and neighbourhood in aria-labels
+- No CAPTCHA for read-only searches
+- Aggregates pricing across Booking.com, Expedia, Hotels.com, and direct hotel sites
+
+**Fallback: Booking.com** — broader international coverage, especially for non-English cities. See below.
+
+---
+
+## URL Construction
+
+```
+https://www.google.com/travel/hotels/entity/{CITY_SLUG}?q=hotels+in+{CITY}&checkin={CHECKIN}&checkout={CHECKOUT}&adults={ADULTS}&children={CHILDREN_AGES}
+```
+
+The simplest and most reliable approach is the natural-language search URL:
+
+```
+https://www.google.com/travel/hotels?q=hotels+in+{CITY}&checkin={CHECKIN}&checkout={CHECKOUT}
+```
+
+| Placeholder | Format | Example |
+|---|---|---|
+| `{CITY}` | URL-encoded city name | `Bangkok` → `Bangkok` |
+| `{CHECKIN}` | YYYY-MM-DD | `2026-11-01` |
+| `{CHECKOUT}` | YYYY-MM-DD | `2026-11-08` |
+| `{ADULTS}` | integer | `2` |
+| `{CHILDREN_AGES}` | comma-separated ages | `7,3` |
+
+**Worked example — Bangkok, 2 adults + child 7 + child 3, Nov 1–8:**
+```
+https://www.google.com/travel/hotels?q=hotels+in+Bangkok&checkin=2026-11-01&checkout=2026-11-08
+```
+
+Guest counts and filters are best applied after load via filter refs (see below).
+
+---
+
+## Step-by-Step Workflow
+
+```bash
+# 1. Ensure browser is running
+pinchtab_ensure || exit 1
+
+# 2. Navigate
+pinchtab nav "https://www.google.com/travel/hotels?q=hotels+in+Bangkok&checkin=2026-11-01&checkout=2026-11-08"
+
+# 3. Wait for results to render
+sleep 4
+
+# 4. Extract results
+pinchtab text
+```
+
+If results are present (hotel names, prices, ratings), extract top 5–10. Done.
+
+---
+
+## Adjusting Guest Count
+
+If the default guest count (2 adults) doesn't match the request:
+
+```bash
+pinchtab snap -i -c
+# Find the "Travelers" or "Guests" selector ref
+pinchtab click {ref}
+sleep 2
+pinchtab snap -i -c
+# Find increment/decrement refs for adults and children
+# Adjust, then close and re-read
+pinchtab text
+```
+
+---
+
+## Applying Filters
+
+| Filter | What to look for in snap -i -c |
+|---|---|
+| Price range | "Price" filter button ref |
+| Star rating | "Hotel class" filter button ref |
+| Sort by price | "Sort" dropdown → "Price: low to high" option ref |
+| Amenities | "Amenities" filter ref |
+
+---
+
+## Result Extraction
+
+From `pinchtab text`, look for:
+- Hotel name
+- Nightly price (e.g. "$89/night")
+- Total price for stay
+- Star rating or guest score
+- Neighbourhood / distance from centre
+
+---
+
+## Fallback: Booking.com
+
+Use for cities where Google Hotels returns sparse results, or for more granular filtering.
+
+```
+https://www.booking.com/searchresults.html?ss={CITY}&checkin={CHECKIN}&checkout={CHECKOUT}&group_adults={ADULTS}&no_rooms=1&group_children={CHILDREN}&age={CHILD_AGE_1}&age={CHILD_AGE_2}
+```
+
+```bash
+pinchtab nav "https://www.booking.com/searchresults.html?ss=Bangkok&checkin=2026-11-01&checkout=2026-11-08&group_adults=2&no_rooms=1&group_children=2&age=7&age=3"
+sleep 4
+pinchtab text
+```
+
+**Known issue — cookie consent banner**: Booking.com shows a GDPR consent dialog on first load. If `pinchtab text` returns no hotel results:
+
+```bash
+pinchtab snap -i -c
+# Find the "Accept" or "I agree" button ref
+pinchtab click {ref}
+sleep 2
+pinchtab text
+```
+
+---
+
+## Fallback: Airbnb (for apartment-style or vacation rental framing)
+
+Use when the user says "Airbnb", "vacation rental", or "apartment with kitchen":
+
+```
+https://www.airbnb.com/s/{CITY}/homes?checkin={CHECKIN}&checkout={CHECKOUT}&adults={ADULTS}&children={CHILDREN}
+```
+
+```bash
+pinchtab nav "https://www.airbnb.com/s/Bangkok/homes?checkin=2026-11-01&checkout=2026-11-08&adults=2&children=2"
+sleep 5   # Airbnb is React-heavy, needs extra time
+pinchtab text
+```
+
+---
+
+## Token Efficiency
+
+- `pinchtab text` (~800 tokens) is sufficient to read hotel names, prices, and ratings.
+- Use `pinchtab snap -i -c` only when adjusting guest counts or applying filters.

package/examples/extensions/yahoo-mail/cli/bun.lock

@@ -0,0 +1,66 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "ymail",
+      "dependencies": {
+        "imapflow": "^1.0.171",
+        "nodemailer": "^8.0.5",
+      },
+    },
+  },
+  "packages": {
+    "@pinojs/redact": ["@pinojs/redact@0.4.0", "", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
+
+    "@zone-eu/mailsplit": ["@zone-eu/mailsplit@5.4.9", "", { "dependencies": { "libbase64": "1.3.0", "libmime": "5.3.8", "libqp": "2.1.1" } }, "sha512-Qq7k6FzA5SmGf5HFPcr17gE7M+O1gttlmWn7tlGUlhGsbbjUaBL/4cEWIwExeCzqu5+kyZJ91mcBZbQ9zEwwYA=="],
+
+    "atomic-sleep": ["atomic-sleep@1.0.0", "", {}, "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ=="],
+
+    "encoding-japanese": ["encoding-japanese@2.2.0", "", {}, "sha512-EuJWwlHPZ1LbADuKTClvHtwbaFn4rOD+dRAbWysqEOXRc2Uui0hJInNJrsdH0c+OhJA4nrCBdSkW4DD5YxAo6A=="],
+
+    "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
+
+    "imapflow": ["imapflow@1.3.3", "", { "dependencies": { "@zone-eu/mailsplit": "5.4.9", "encoding-japanese": "2.2.0", "iconv-lite": "0.7.2", "libbase64": "1.3.0", "libmime": "5.3.8", "libqp": "2.1.1", "nodemailer": "8.0.7", "pino": "10.3.1", "socks": "2.8.8" } }, "sha512-lx7nWcUDfNgITEKYYfunUDqJ3LT6ImuiA1ReqJepVEA2nqBQNUqa3ppF7Yz5CNjuDYG95pmzsCcNqRjMrwh/Vg=="],
+
+    "ip-address": ["ip-address@10.2.0", "", {}, "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA=="],
+
+    "libbase64": ["libbase64@1.3.0", "", {}, "sha512-GgOXd0Eo6phYgh0DJtjQ2tO8dc0IVINtZJeARPeiIJqge+HdsWSuaDTe8ztQ7j/cONByDZ3zeB325AHiv5O0dg=="],
+
+    "libmime": ["libmime@5.3.8", "", { "dependencies": { "encoding-japanese": "2.2.0", "iconv-lite": "0.7.2", "libbase64": "1.3.0", "libqp": "2.1.1" } }, "sha512-ZrCY+Q66mPvasAfjsQ/IgahzoBvfE1VdtGRpo1hwRB1oK3wJKxhKA3GOcd2a6j7AH5eMFccxK9fBoCpRZTf8ng=="],
+
+    "libqp": ["libqp@2.1.1", "", {}, "sha512-0Wd+GPz1O134cP62YU2GTOPNA7Qgl09XwCqM5zpBv87ERCXdfDtyKXvV7c9U22yWJh44QZqBocFnXN11K96qow=="],
+
+    "nodemailer": ["nodemailer@8.0.7", "", {}, "sha512-pkjE4mkBzQjdJT4/UmlKl3pX0rC9fZmjh7c6C9o7lv66Ac6w9WCnzPzhbPNxwZAzlF4mdq4CSWB5+FbK6FWCow=="],
+
+    "on-exit-leak-free": ["on-exit-leak-free@2.1.2", "", {}, "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA=="],
+
+    "pino": ["pino@10.3.1", "", { "dependencies": { "@pinojs/redact": "^0.4.0", "atomic-sleep": "^1.0.0", "on-exit-leak-free": "^2.1.0", "pino-abstract-transport": "^3.0.0", "pino-std-serializers": "^7.0.0", "process-warning": "^5.0.0", "quick-format-unescaped": "^4.0.3", "real-require": "^0.2.0", "safe-stable-stringify": "^2.3.1", "sonic-boom": "^4.0.1", "thread-stream": "^4.0.0" }, "bin": { "pino": "bin.js" } }, "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg=="],
+
+    "pino-abstract-transport": ["pino-abstract-transport@3.0.0", "", { "dependencies": { "split2": "^4.0.0" } }, "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg=="],
+
+    "pino-std-serializers": ["pino-std-serializers@7.1.0", "", {}, "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw=="],
+
+    "process-warning": ["process-warning@5.0.0", "", {}, "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA=="],
+
+    "quick-format-unescaped": ["quick-format-unescaped@4.0.4", "", {}, "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg=="],
+
+    "real-require": ["real-require@0.2.0", "", {}, "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg=="],
+
+    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "smart-buffer": ["smart-buffer@4.2.0", "", {}, "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg=="],
+
+    "socks": ["socks@2.8.8", "", { "dependencies": { "ip-address": "^10.1.1", "smart-buffer": "^4.2.0" } }, "sha512-NlGELfPrgX2f1TAAcz0WawlLn+0r3FyhhCRpFFK2CemXenPYvzMWWZINv3eDNo9ucdwme7oCHRY0Jnbs4aIkog=="],
+
+    "sonic-boom": ["sonic-boom@4.2.1", "", { "dependencies": { "atomic-sleep": "^1.0.0" } }, "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q=="],
+
+    "split2": ["split2@4.2.0", "", {}, "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg=="],
+
+    "thread-stream": ["thread-stream@4.1.0", "", { "dependencies": { "real-require": "^1.0.0" } }, "sha512-Bw6h2iBDt16v6iHLChBIoVYU8CBo9GPsW8TG7h1hRVhqKhIkH6N8qkxNSmiOZTKsCLPbtWG4ViWLkU6KeKXpig=="],
+
+    "thread-stream/real-require": ["real-require@1.0.0", "", {}, "sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g=="],
+  }
+}

package/examples/extensions/yahoo-mail/cli/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "ymail",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "ymail": "./ymail.mjs"
+  },
+  "dependencies": {
+    "imapflow": "^1.0.171",
+    "nodemailer": "^8.0.5"
+  }
+}

package/examples/extensions/yahoo-mail/cli/ymail.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+import { ImapFlow } from "imapflow";
+import { createTransport } from "nodemailer";
+
+const IMAP_HOST = "imap.mail.yahoo.com";
+const IMAP_PORT = 993;
+const SMTP_HOST = "smtp.mail.yahoo.com";
+const SMTP_PORT = 465;
+
+function env(name) {
+  const v = process.env[name];
+  if (!v) {
+    console.error(JSON.stringify({ error: `${name} not set` }));
+    process.exit(1);
+  }
+  return v;
+}
+
+async function withClient(fn) {
+  const client = new ImapFlow({
+    host: IMAP_HOST,
+    port: IMAP_PORT,
+    secure: true,
+    auth: {
+      user: env("YAHOO_EMAIL"),
+      pass: env("YAHOO_APP_PASSWORD"),
+    },
+    logger: false,
+  });
+  try {
+    await client.connect();
+    return await fn(client);
+  } finally {
+    await client.logout().catch(() => {});
+  }
+}
+
+function formatMessage(msg) {
+  return {
+    uid: msg.uid,
+    messageId: msg.envelope?.messageId ?? null,
+    inReplyTo: msg.envelope?.inReplyTo ?? null,
+    from: msg.envelope?.from?.map((a) => `${a.name || ""} <${a.address}>`).join(", ") ?? "",
+    to: msg.envelope?.to?.map((a) => `${a.name || ""} <${a.address}>`).join(", ") ?? "",
+    subject: msg.envelope?.subject ?? "",
+    date: msg.envelope?.date?.toISOString() ?? "",
+    flags: [...(msg.flags || [])],
+  };
+}
+
+async function downloadTextBody(client, uid) {
+  const msg = await client.fetchOne(uid, {
+    uid: true,
+    bodyStructure: true,
+  });
+  const parts = flattenParts(msg.bodyStructure);
+  const textPart = parts.find((p) => p.type === "text/plain") || parts.find((p) => p.type === "text/html");
+  if (!textPart) return "(no text body)";
+
+  const { content } = await client.download(uid.toString(), textPart.part, { uid: true });
+  const chunks = [];
+  for await (const chunk of content) {
+    chunks.push(chunk);
+  }
+  let text = Buffer.concat(chunks).toString("utf8");
+  if (textPart.type === "text/html") {
+    text = text.replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  }
+  return text.trim().slice(0, 10_000);
+}
+
+function flattenParts(structure, prefix = "") {
+  const results = [];
+  if (!structure) return results;
+
+  if (structure.childNodes) {
+    for (let i = 0; i < structure.childNodes.length; i++) {
+      const partNum = prefix ? `${prefix}.${i + 1}` : `${i + 1}`;
+      results.push(...flattenParts(structure.childNodes[i], partNum));
+    }
+  } else {
+    results.push({
+      part: prefix || "1",
+      type: structure.type,
+      encoding: structure.encoding,
+      size: structure.size,
+    });
+  }
+  return results;
+}
+
+const commands = {
+  async "list-folders"() {
+    return withClient(async (client) => {
+      const folders = await client.list();
+      const result = folders.map((f) => ({
+        path: f.path,
+        name: f.name,
+        specialUse: f.specialUse || null,
+        messages: f.status?.messages ?? null,
+      }));
+      console.log(JSON.stringify(result));
+    });
+  },
+
+  async "list-inbox"() {
+    const folder = process.argv[3] || "INBOX";
+    const limit = parseInt(process.argv[4] || "50", 10);
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        const status = await client.status(folder, { messages: true });
+        const total = status.messages || 0;
+        const start = Math.max(1, total - limit + 1);
+        const messages = [];
+        for await (const msg of client.fetch(`${start}:*`, {
+          envelope: true,
+          flags: true,
+        })) {
+          messages.push(formatMessage(msg));
+        }
+        messages.reverse();
+        console.log(JSON.stringify({ folder, total, messages }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async search() {
+    const query = process.argv[3];
+    if (!query) {
+      console.error(JSON.stringify({ error: "Usage: ymail search <query> [folder] [limit]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[4] || "INBOX";
+    const limit = parseInt(process.argv[5] || "20", 10);
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        const uids = await client.search(
+          { or: [{ subject: query }, { from: query }, { body: query }] },
+          { uid: true },
+        );
+        const selected = uids.slice(-limit);
+        const messages = [];
+        if (selected.length > 0) {
+          const range = selected.join(",");
+          for await (const msg of client.fetch(range, {
+            envelope: true,
+            flags: true,
+            uid: true,
+          })) {
+            messages.push(formatMessage(msg));
+          }
+        }
+        messages.reverse();
+        console.log(JSON.stringify({ query, folder, total: uids.length, messages }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async read() {
+    const uid = process.argv[3];
+    if (!uid) {
+      console.error(JSON.stringify({ error: "Usage: ymail read <uid> [folder]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[4] || "INBOX";
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        const msg = await client.fetchOne(uid, {
+          envelope: true,
+          flags: true,
+          uid: true,
+        });
+        const body = await downloadTextBody(client, uid);
+        console.log(
+          JSON.stringify({
+            ...formatMessage(msg),
+            body,
+          })
+        );
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async move() {
+    const uid = process.argv[3];
+    const destination = process.argv[4];
+    if (!uid || !destination) {
+      console.error(JSON.stringify({ error: "Usage: ymail move <uid> <destination-folder> [source-folder]" }));
+      process.exit(1);
+    }
+    const source = process.argv[5] || "INBOX";
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(source);
+      try {
+        await client.messageMove(uid, destination, { uid: true });
+        console.log(JSON.stringify({ ok: true, uid, from: source, to: destination }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async delete() {
+    const uid = process.argv[3];
+    if (!uid) {
+      console.error(JSON.stringify({ error: "Usage: ymail delete <uid> [folder]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[4] || "INBOX";
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        await client.messageDelete(uid, { uid: true });
+        console.log(JSON.stringify({ ok: true, uid, folder }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async "mark-read"() {
+    const uid = process.argv[3];
+    if (!uid) {
+      console.error(JSON.stringify({ error: "Usage: ymail mark-read <uid> [folder]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[4] || "INBOX";
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        await client.messageFlagsAdd(uid, ["\\Seen"], { uid: true });
+        console.log(JSON.stringify({ ok: true, uid, folder, marked: "read" }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async "mark-unread"() {
+    const uid = process.argv[3];
+    if (!uid) {
+      console.error(JSON.stringify({ error: "Usage: ymail mark-unread <uid> [folder]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[4] || "INBOX";
+    return withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        await client.messageFlagsRemove(uid, ["\\Seen"], { uid: true });
+        console.log(JSON.stringify({ ok: true, uid, folder, marked: "unread" }));
+      } finally {
+        lock.release();
+      }
+    });
+  },
+
+  async send() {
+    const to = process.argv[3];
+    const subject = process.argv[4];
+    const body = process.argv[5];
+    if (!to || !subject || !body) {
+      console.error(JSON.stringify({ error: "Usage: ymail send <to> <subject> <body>" }));
+      process.exit(1);
+    }
+    const from = env("YAHOO_EMAIL");
+    const transport = createTransport({
+      host: SMTP_HOST,
+      port: SMTP_PORT,
+      secure: true,
+      auth: { user: from, pass: env("YAHOO_APP_PASSWORD") },
+    });
+    const info = await transport.sendMail({ from, to, subject, text: body });
+    console.log(JSON.stringify({ ok: true, messageId: info.messageId, to, subject }));
+  },
+
+  async reply() {
+    const uid = process.argv[3];
+    const body = process.argv[4];
+    if (!uid || !body) {
+      console.error(JSON.stringify({ error: "Usage: ymail reply <uid> <body> [folder]" }));
+      process.exit(1);
+    }
+    const folder = process.argv[5] || "INBOX";
+    const from = env("YAHOO_EMAIL");
+
+    const original = await withClient(async (client) => {
+      const lock = await client.getMailboxLock(folder);
+      try {
+        return await client.fetchOne(uid, { envelope: true, uid: true });
+      } finally {
+        lock.release();
+      }
+    });
+
+    const replyTo = original.envelope?.replyTo?.[0]?.address
+      || original.envelope?.from?.[0]?.address;
+    if (!replyTo) {
+      console.error(JSON.stringify({ error: "Cannot determine reply address from original message" }));
+      process.exit(1);
+    }
+
+    const originalSubject = original.envelope?.subject ?? "";
+    const subject = originalSubject.startsWith("Re:") ? originalSubject : `Re: ${originalSubject}`;
+    const messageId = original.envelope?.messageId;
+
+    const headers = {};
+    if (messageId) {
+      headers["In-Reply-To"] = messageId;
+      headers["References"] = messageId;
+    }
+
+    const transport = createTransport({
+      host: SMTP_HOST,
+      port: SMTP_PORT,
+      secure: true,
+      auth: { user: from, pass: env("YAHOO_APP_PASSWORD") },
+    });
+    const info = await transport.sendMail({
+      from,
+      to: replyTo,
+      subject,
+      text: body,
+      headers,
+    });
+    console.log(JSON.stringify({ ok: true, messageId: info.messageId, to: replyTo, subject }));
+  },
+};
+
+const cmd = process.argv[2];
+if (!cmd || !commands[cmd]) {
+  console.error(
+    JSON.stringify({
+      error: `Unknown command: ${cmd}`,
+      available: Object.keys(commands),
+    })
+  );
+  process.exit(1);
+}
+
+commands[cmd]().catch((err) => {
+  console.error(JSON.stringify({ error: err.message }));
+  process.exit(1);
+});

package/examples/extensions/yahoo-mail/index.ts

@@ -0,0 +1,57 @@
+type ConnectionCategory =
+  | "email"
+  | "drive"
+  | "calendar"
+  | "finance"
+  | "messaging"
+  | "docs"
+  | "workspace"
+  | "other";
+
+type ConnectionAuthType =
+  | "oauth2"
+  | "apikey"
+  | "app-password"
+  | "credentials-file"
+  | "custom";
+
+type MercuryExt = {
+  cli(opts: { name: string; install: string; bin?: string }): void;
+  permission(opts: { defaultRoles: string[] }): void;
+  env(def: { from: string; as?: string }): void;
+  skill(relativePath: string): void;
+  connection(def: {
+    displayName: string;
+    iconUrl?: string;
+    category: ConnectionCategory;
+    authType: ConnectionAuthType;
+    credentialEnvVar?: string;
+    scopes?: string[];
+  }): void;
+};
+
+import manifest from "../../../resources/connection-env-vars.json";
+
+const yahooEnv = manifest["yahoo-mail"];
+
+export default function (mercury: MercuryExt) {
+  mercury.cli({
+    name: "ymail",
+    install: "npm install -g imapflow nodemailer",
+    bin: "./cli/ymail.mjs",
+  });
+
+  mercury.permission({ defaultRoles: ["admin"] });
+
+  mercury.env({ from: yahooEnv.env.email });
+  mercury.env({ from: yahooEnv.env.appPassword });
+
+  mercury.connection({
+    displayName: "Yahoo Mail",
+    category: "email",
+    authType: "app-password",
+    credentialEnvVar: yahooEnv.credentialEnvVar,
+  });
+
+  mercury.skill("./skill");
+}