mercury-agent 0.9.0 → 0.10.0

package/README.md

@@ -422,6 +422,8 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 | `MERCURY_TRIGGER_MATCH` | `mention` | `mention`, `prefix`, `always` |
 | `MERCURY_TRIGGER_PATTERNS` | `@Mercury,Mercury` | Trigger patterns |
 | `MERCURY_ADMINS` | — | Pre-seeded admin user IDs |
+| `MERCURY_AMBIENT_TTL_DAYS` | `14` | Days before overheard (ambient) group messages are aged out |
+| `MERCURY_AMBIENT_CONTEXT_ROWS` | `30` | Max ambient rows injected into a single prompt |
 
 ### DM Auto-Space
 

package/docs/configuration.md

@@ -39,6 +39,15 @@ context:
 
 Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
 
+## Ambient group context
+
+In linked group chats, messages that don't trigger the bot are stored as **ambient context** (author-attributed) so it can answer questions about conversation it overheard. Every message in a linked group becomes a row, bounded on both ends:
+
+- **`MERCURY_AMBIENT_TTL_DAYS`** (default `14`) — days before ambient rows are aged out by the storage cleanup. Real user/assistant turns are never touched.
+- **`MERCURY_AMBIENT_CONTEXT_ROWS`** (default `30`) — max ambient rows injected into a single prompt. Ambient has its own budget, so overheard chatter can't crowd real turns out of the context window.
+
+Per-space: `mrctl config set ambient.enabled false` disables capture entirely (tag-only mode).
+
 You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
 
 ## Container env passthrough (`agent.env_passthrough`)

package/docs/dashboard.md

@@ -29,7 +29,7 @@ Lists all memory spaces with platform badges, conversation count, message count,
 | **Conversations** | View linked conversations, unlink them |
 | **Roles** | Promote members to admin, demote admins |
 | **Mutes** | Mute/unmute users with optional duration and reason |
-| **Triggers & Ambient** | Set `trigger.match` (mention/prefix/always), patterns, case sensitivity, media-in-groups, and ambient mode |
+| **Triggers & Ambient** | Set `trigger.match` (mention/prefix/always), patterns, case sensitivity, media-in-groups, `trigger.mention_always` (verified @-mentions trigger regardless of patterns), and ambient mode |
 | **Context** | Choose context mode (clear/context), window size, reply-chain depth |
 | **Rate limits** | Set burst-per-minute and daily caps for members and admins |
 | **Voice** | Configure per-space STT (transcription preset or custom model) and TTS (on-demand vs auto) |

package/docs/pipeline.md

@@ -20,7 +20,8 @@ Platform (WhatsApp / Discord / Telegram / Slack)
   ├─► Unified handler (src/core/handler.ts)
   │     • Parse platform thread into an external conversation ID
   │     • Resolve/create conversation in DB
-  │     • Ignore unlinked conversations
+  │     • Ignore unlinked conversations (seeded admins may `/spaces list`
+  │       and `/spaces switch <id>` to re-link; everything else is dropped)
   │     • Pre-route trigger check (cheap, sync)
   │     • Start typing indicator if matched
   │     • Call bridge.normalize(..., spaceId) → IngressMessage
@@ -29,7 +30,8 @@ Platform (WhatsApp / Discord / Telegram / Slack)
   ├─► core.handleRawInput(IngressMessage)
   │     • Route: trigger match, permissions, command detection
   │     • If triggered → queue → container run → ContainerResult
-  │     • If not triggered → store as ambient context
+  │     • If not triggered → store as ambient context (author-attributed,
+  │       aged out after `ambientTtlDays`)
   │     • If command → execute immediately (stop, compact)
   │     • If denied → return reason
   │
@@ -196,6 +198,10 @@ All platforms share the same trigger engine. A pre-route check runs before `norm
 
 DMs always match regardless of mode.
 
+**Verified @-mentions always trigger.** When a platform confirms the bot was tagged (matched on the mention's JID, not on text), the message triggers regardless of `trigger.patterns` — a space that defines its own patterns replaces the default list, which used to silently drop the auto-injected `@<botUsername>` and ignore genuine tags. Set per-space `trigger.mention_always=false` to require the trigger word even when tagged. Wired for WhatsApp; Discord's structured mention is not yet carried through.
+
+**Slash commands bypass the trigger gate.** A `/`-prefixed message naming a real command (e.g. `/spaces list`, `/stop`) executes untagged in groups. Unknown slash words (`/shrug`) still fall through to ambient.
+
 **Attachment-only in groups** (voice note, image with no caption): by default these do **not** match `mention` or `prefix` — use `trigger.match=always`, reply to the bot’s message, or set per-space `trigger.media_in_groups=true` so voice/media alone can trigger without spamming text-only noise.
 
 ### Reply-to-Bot

package/examples/extensions/docs/index.ts

@@ -0,0 +1,28 @@
+export default function (mercury: {
+  cli(opts: { name: string; install: string }): void;
+  skill(relativePath: string): void;
+  permission(opts: { defaultRoles: string[] }): void;
+  requires(
+    capabilities: (
+      | "tools"
+      | "vision"
+      | "audio_input"
+      | "audio_output"
+      | "extended_thinking"
+    )[],
+  ): void;
+}) {
+  // NOTE: never put a backtick anywhere in this install string. It sits inside
+  // a template literal when the image builder assembles the Dockerfile, so a
+  // stray backtick terminates the literal and the whole extension stops
+  // loading — which surfaces in the dashboard as "uninstalled", not as a
+  // syntax error. Run "mercury extensions validate docs" after editing.
+  mercury.cli({
+    name: "docs",
+    install:
+      "apt-get update && apt-get install -y --no-install-recommends pandoc && python3 -m pip install --break-system-packages python-docx openpyxl odfpy && echo '#!/bin/sh' > /usr/local/bin/docs && echo 'echo \"docs extension dependencies installed. Use the docs skill from the agent.\"' >> /usr/local/bin/docs && chmod +x /usr/local/bin/docs && rm -rf /var/lib/apt/lists/*",
+  });
+  mercury.permission({ defaultRoles: ["admin", "member"] });
+  mercury.requires(["tools"]);
+  mercury.skill("./skill");
+}

package/examples/extensions/docs/skill/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: docs
+description: Use this skill whenever the user asks for a document, a Word file, a .docx, a spreadsheet, an .xlsx, an ODF file, or asks you to "write up", "put together", or "send me" something they will open in Word, Google Docs, Excel, or LibreOffice. Activate when document output is requested, not when merely discussing text.
+---
+
+# Documents Skill
+
+Produce real office files — `.docx`, `.xlsx`, `.odt` — and deliver them in chat.
+
+Without this skill the honest answer to "make me a doc" is markdown in a chat
+bubble, or an `.html` attachment the user has to convert themselves. Do not do
+that any more. Produce the actual file.
+
+## Deliver by writing to `outbox/`
+
+Anything written to `outbox/` is sent to the user as an attachment when the
+turn ends. That is the whole delivery mechanism — there is nothing to call.
+
+```python
+from docx import Document
+
+doc = Document()
+doc.add_heading("Trip plan", level=1)
+doc.add_paragraph("Flights land Thursday morning.")
+doc.save("outbox/trip-plan.docx")
+```
+
+Use a filename the user would recognise. `outbox/trip-plan.docx` beats
+`outbox/output.docx`.
+
+## Pick the right tool
+
+| Ask | Use |
+|---|---|
+| A document, letter, report, notes | `python-docx` → `.docx` |
+| Existing markdown you already wrote | `pandoc` → `.docx` |
+| A table of numbers, a budget, a list to sort | `openpyxl` → `.xlsx` |
+| LibreOffice/OpenOffice specifically | `odfpy` → `.odt` |
+
+`.docx` is the default. It opens in Word, Google Docs, LibreOffice, and the
+WhatsApp document viewer.
+
+### Markdown you already have → .docx
+
+Fastest path when you have composed the content as markdown already:
+
+```bash
+pandoc notes.md -o outbox/notes.docx
+```
+
+Pandoc handles headings, lists, tables, bold/italic, and links. Reach for
+`python-docx` instead when you need control it does not give you.
+
+### Structured document
+
+```python
+from docx import Document
+from docx.shared import Pt
+
+doc = Document()
+doc.add_heading("Quarterly summary", level=1)
+doc.add_paragraph("Prepared for the team.")
+
+doc.add_heading("Numbers", level=2)
+table = doc.add_table(rows=1, cols=2)
+table.style = "Light Grid Accent 1"
+head = table.rows[0].cells
+head[0].text, head[1].text = "Item", "Amount"
+for item, amount in [("Flights", "1,200"), ("Hotel", "900")]:
+    row = table.add_row().cells
+    row[0].text, row[1].text = item, amount
+
+doc.save("outbox/quarterly-summary.docx")
+```
+
+### Spreadsheet
+
+```python
+from openpyxl import Workbook
+
+wb = Workbook()
+ws = wb.active
+ws.title = "Budget"
+ws.append(["Item", "Amount"])
+for row in [("Flights", 1200), ("Hotel", 900)]:
+    ws.append(row)
+wb.save("outbox/budget.xlsx")
+```
+
+## Right-to-left text
+
+Hebrew and Arabic need the paragraph marked RTL, or Word renders the alignment
+wrong even though the characters are correct:
+
+```python
+from docx import Document
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+doc = Document()
+p = doc.add_paragraph("שלום, זה מסמך לדוגמה")
+p.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+doc.save("outbox/hebrew.docx")
+```
+
+## Rules
+
+1. **Never claim you produced a file you did not write.** Save it to `outbox/`,
+   confirm the file exists, and only then say you have sent it.
+2. **Do not hand over markdown or HTML as a substitute** for a requested
+   document and ask the user to convert it. Produce the real format.
+3. **Do not promise a Google Docs link.** You produce files, not Drive
+   documents. A `.docx` opens in Google Docs, so offer that instead.
+4. Keep documents short unless asked otherwise — these are usually read on a
+   phone.

package/examples/extensions/pinchtab/index.ts

@@ -8,7 +8,7 @@ export default function (mercury: {
   mercury.cli({
     name: "pinchtab",
     install:
-      'npm install -g pinchtab@0.13.2 playwright && npx playwright install --with-deps chromium && CHROMIUM=$(NODE_PATH="$(npm root -g)" node -e "try{process.stdout.write(require(\'playwright\').chromium.executablePath())}catch(e){}" 2>/dev/null) && { test -x "$CHROMIUM" || CHROMIUM=$(find /home/mercury/.cache/ms-playwright -type f -path \'*/chrome-linux/chrome\' ! -path \'*headless_shell*\' 2>/dev/null | head -1); } && test -n "$CHROMIUM" && test -x "$CHROMIUM" && ln -sf "$CHROMIUM" /usr/local/bin/chromium && ln -sf "$CHROMIUM" /usr/bin/chromium && rm -rf /var/lib/apt/lists/*',
+      'npm install -g pinchtab@0.13.2 playwright && npx playwright install --with-deps chromium && CHROMIUM=$(NODE_PATH="$(npm root -g)" node -e "try{process.stdout.write(require(\'playwright\').chromium.executablePath())}catch(e){}" 2>/dev/null) && { test -x "$CHROMIUM" || CHROMIUM=$(find /home/mercury/.cache/ms-playwright -type f -path \'*/chrome-linux/chrome\' ! -path \'*headless_shell*\' 2>/dev/null | head -1); } && test -n "$CHROMIUM" && test -x "$CHROMIUM" && ln -sf "$CHROMIUM" /usr/local/bin/chromium && ln -sf "$CHROMIUM" /usr/bin/chromium && HOME=/home/mercury pinchtab config set security.allowedDomains "*" && chown -R mercury:mercury /home/mercury/.pinchtab && rm -rf /var/lib/apt/lists/*',
   });
   mercury.permission({ defaultRoles: ["admin", "member"] });
   mercury.skill("./skill");
@@ -23,6 +23,10 @@ export default function (mercury: {
   local log="\${PINCHTAB_LOG:-/tmp/pinchtab.log}"
   local max_wait="\${1:-120}"
   mkdir -p "$(dirname "$log")" 2>/dev/null || true
+  # Belt and braces alongside the container-level "--ulimit core=0": Chromium
+  # helper processes segfault under the sandbox and each dump is ~300 MB landing
+  # in the agent workspace. Navigation succeeds regardless.
+  ulimit -c 0 2>/dev/null || true
   : >"$log"
   if [ ! -x "\${CHROME_BINARY:-}" ]; then
     for _c in /usr/local/bin/chromium /usr/bin/chromium; do
@@ -33,12 +37,31 @@ export default function (mercury: {
     echo "No executable Chromium (CHROME_BINARY=\${CHROME_BINARY:-}; tried /usr/local/bin/chromium, /usr/bin/chromium). Rebuild mercury-agent-ext (restart Mercury)." | tee -a "$log"
     return 1
   fi
-  _pinchtab_port_open() { (echo >/dev/tcp/$bind/$port) 2>/dev/null; }
+  # /dev/tcp is a bash builtin that dash does not implement. pi currently runs
+  # the agent shell as bash, so this is portability insurance rather than a live
+  # fix: under dash the redirect always fails and the caller would burn the full
+  # max_wait against an already-READY daemon. Any HTTP response, 404 included,
+  # proves the port is listening.
+  _pinchtab_port_open() {
+    if command -v curl >/dev/null 2>&1; then
+      curl -s -o /dev/null --max-time 2 "http://$bind:$port/" >/dev/null 2>&1
+      return $?
+    fi
+    (echo >/dev/tcp/$bind/$port) 2>/dev/null
+  }
   if command -v pinchtab >/dev/null 2>&1 && _pinchtab_port_open; then
     return 0
   fi
   pkill -f '[p]inchtab' 2>/dev/null || true
-  nohup pinchtab >>"$log" 2>&1 &
+  # pinchtab >=0.13 ships IDPI enforcing with a loopback-only website
+  # whitelist, so every public URL is refused with 403 idpi_domain_blocked --
+  # including the Brave search this skill tells the agent to run. Widen the
+  # allowlist but keep IDPI strict mode and the content guard ON, so fetched
+  # pages still arrive wrapped in untrusted_web_content tags. Do NOT use
+  # "pinchtab security down" -- that turns the prompt-injection guard off too.
+  # NOTE: no backticks in this comment. It is inside a TS template literal.
+  pinchtab config set security.allowedDomains "*" >/dev/null 2>&1 || true
+  nohup pinchtab server >>"$log" 2>&1 &
   local pid=$!
   sleep 2
   if ! kill -0 "$pid" 2>/dev/null; then

package/examples/extensions/pinchtab/skill/SKILL.md

@@ -17,7 +17,7 @@ The 30-second pattern for browser tasks:
 
 ```bash
 # 1. Start Pinchtab (runs forever, local on :9867)
-pinchtab &
+pinchtab server &
 
 # 2. In your agent, follow this loop:
 #    a) Navigate to a URL
@@ -31,7 +31,7 @@ pinchtab &
 
 ## Mercury / Docker (required)
 
-In the Mercury agent container, `pinchtab &` plus a short `sleep` often races the HTTP bridge: the CLI then hits `127.0.0.1:9867` before the daemon listens (`connection refused`). The host injects `CHROME_BINARY` and `CHROME_FLAGS` (`--no-sandbox` as root). **Always** wait until the port is open and capture daemon logs.
+In the Mercury agent container, `pinchtab server &` plus a short `sleep` often races the HTTP bridge: the CLI then hits `127.0.0.1:9867` before the daemon listens (`connection refused`). The host injects `CHROME_BINARY` and `CHROME_FLAGS` (`--no-sandbox` as root). **Always** wait until the port is open and capture daemon logs.
 
 ```bash
 pinchtab_ensure() {
@@ -40,6 +40,9 @@ pinchtab_ensure() {
   local log="${PINCHTAB_LOG:-/tmp/pinchtab.log}"
   local max_wait="${1:-120}"
   mkdir -p "$(dirname "$log")" 2>/dev/null || true
+  # Chromium helper processes segfault under the container sandbox; each dump is
+  # ~300 MB landing in the agent workspace. Navigation succeeds regardless.
+  ulimit -c 0 2>/dev/null || true
   : >"$log"
   if [ ! -x "${CHROME_BINARY:-}" ]; then
     for _c in /usr/local/bin/chromium /usr/bin/chromium; do
@@ -50,12 +53,21 @@ pinchtab_ensure() {
     echo "No executable Chromium (CHROME_BINARY=${CHROME_BINARY:-}; tried /usr/local/bin/chromium, /usr/bin/chromium). Rebuild mercury-agent-ext (restart Mercury)." | tee -a "$log"
     return 1
   fi
-  _pinchtab_port_open() { (echo >/dev/tcp/$bind/$port) 2>/dev/null; }
+  # /dev/tcp is bash-only. pi runs the agent shell as bash today, so this is
+  # portability insurance. Any HTTP response (404 included) proves the port is
+  # listening.
+  _pinchtab_port_open() {
+    if command -v curl >/dev/null 2>&1; then
+      curl -s -o /dev/null --max-time 2 "http://$bind:$port/" >/dev/null 2>&1
+      return $?
+    fi
+    (echo >/dev/tcp/$bind/$port) 2>/dev/null
+  }
   if command -v pinchtab >/dev/null 2>&1 && _pinchtab_port_open; then
     return 0
   fi
   pkill -f '[p]inchtab' 2>/dev/null || true
-  nohup pinchtab >>"$log" 2>&1 &
+  nohup pinchtab server >>"$log" 2>&1 &
   local pid=$!
   sleep 2
   if ! kill -0 "$pid" 2>/dev/null; then
@@ -100,7 +112,7 @@ If `pinchtab_ensure` fails, show the user the tail of `/tmp/pinchtab.log`; do no
 BRIDGE_BIND=127.0.0.1 \
 BRIDGE_TOKEN="your-strong-secret" \
 BRIDGE_PROFILE=~/.pinchtab/automation-profile \
-pinchtab &
+pinchtab server &
 ```
 
 **Never expose to 0.0.0.0 without a token. Never point at your daily Chrome profile.**
@@ -109,16 +121,16 @@ pinchtab &
 
 ```bash
 # Headless (default) — no visible window
-pinchtab &
+pinchtab server &
 
 # Headed — visible Chrome window for human debugging
-BRIDGE_HEADLESS=false pinchtab &
+BRIDGE_HEADLESS=false pinchtab server &
 
 # With auth token
-BRIDGE_TOKEN="your-secret-token" pinchtab &
+BRIDGE_TOKEN="your-secret-token" pinchtab server &
 
 # Custom port
-BRIDGE_PORT=8080 pinchtab &
+BRIDGE_PORT=8080 pinchtab server &
 ```
 
 Default: **port 9867**, no auth required (local). Set `BRIDGE_TOKEN` for remote access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/resources/skills/spaces/SKILL.md

@@ -15,4 +15,24 @@ mrctl spaces delete
 
 - `list` — shows all spaces with display names (admin-only; members get 403)
 - `name` — with no argument, shows current space name; with argument, renames
-- `delete` — deletes the current space and all its data (irreversible)
+- `delete` — deletes the **current** space and all its data (irreversible)
+
+## `mrctl` can only ever act on the current space
+
+Every `mrctl spaces` command targets the space you are running in. There is no
+way to name a different space, and none of these commands accept a space id.
+
+**`mrctl spaces delete` takes no argument.** Do not pass one. Listing a space
+id does not target that space — the command refuses outright rather than
+deleting the wrong thing, because it previously ignored the argument and
+destroyed the current space instead of the one named.
+
+Cross-space deletion is a **chat** action for a seeded admin only:
+
+```
+/spaces delete <id>
+```
+
+If a user asks you to delete a space other than this one, do not reach for
+`mrctl`. Tell them to run that chat command themselves, and that it asks for a
+`yes` confirmation before anything is destroyed.

package/src/adapters/whatsapp-media.ts

@@ -17,7 +17,11 @@ import {
 } from "@whiskeysockets/baileys";
 import { mimeToExt } from "../core/media.js";
 import { logger } from "../logger.js";
-import type { MediaType, MessageAttachment } from "../types.js";
+import type {
+  DroppedAttachment,
+  MediaType,
+  MessageAttachment,
+} from "../types.js";
 
 const silentBaileysLogger: {
   level: string;
@@ -58,6 +62,12 @@ export interface MediaDownloadOptions {
   maxSizeBytes: number;
   /** Base directory for media storage (group workspace) */
   outputDir: string;
+  /**
+   * Called when media was detected but is not being delivered. Returning null
+   * told the caller only that nothing arrived, never why — so the agent got a
+   * caption with no file and no explanation, and invented one.
+   */
+  onSkipped?: (info: DroppedAttachment) => void;
 }
 
 /**
@@ -168,6 +178,12 @@ export async function downloadWhatsAppMedia(
       sizeBytes: mediaInfo.fileLength,
       maxBytes: options.maxSizeBytes,
     });
+    options.onSkipped?.({
+      type: mediaInfo.type,
+      reason: "too_large",
+      sizeBytes: Number(mediaInfo.fileLength),
+      maxBytes: options.maxSizeBytes,
+    });
     return null;
   }
 
@@ -185,6 +201,7 @@ export async function downloadWhatsAppMedia(
 
     if (!buffer || buffer.length === 0) {
       logger.error("Failed to download media: empty buffer", { messageId });
+      options.onSkipped?.({ type: mediaInfo.type, reason: "download_failed" });
       return null;
     }
 
@@ -196,6 +213,12 @@ export async function downloadWhatsAppMedia(
         sizeBytes: buffer.length,
         maxBytes: options.maxSizeBytes,
       });
+      options.onSkipped?.({
+        type: mediaInfo.type,
+        reason: "too_large",
+        sizeBytes: buffer.length,
+        maxBytes: options.maxSizeBytes,
+      });
       return null;
     }
 
@@ -238,6 +261,7 @@ export async function downloadWhatsAppMedia(
       type: mediaInfo.type,
       error: error instanceof Error ? error.message : String(error),
     });
+    options.onSkipped?.({ type: mediaInfo.type, reason: "download_failed" });
     return null;
   }
 }
@@ -287,6 +311,12 @@ export async function downloadQuotedMedia(
       sizeBytes: mediaInfo.fileLength,
       maxBytes: options.maxSizeBytes,
     });
+    options.onSkipped?.({
+      type: mediaInfo.type,
+      reason: "too_large",
+      sizeBytes: Number(mediaInfo.fileLength),
+      maxBytes: options.maxSizeBytes,
+    });
     return null;
   }
 

package/src/adapters/whatsapp.ts

@@ -33,6 +33,7 @@ import { normalizeChatMarkdown } from "../text/markdown.js";
 import { applyRtlDirection } from "../text/rtl.js";
 import { installLibsignalConsoleFilter } from "./whatsapp-console-filter.js";
 import {
+  canonicalizeJid,
   canonicalizeJidSync,
   resolveKeyIdentities,
   resolveKeyIdentitiesSync,
@@ -79,10 +80,20 @@ function getContextInfo(
   return contextInfo ?? undefined;
 }
 
-function buildReplyContext(
+/**
+ * These attribute values are user-controlled — a push name is whatever the
+ * sender typed — and the block is handed to the model as markup. A stray
+ * double quote would close the attribute and let a sender inject their own.
+ */
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, """);
+}
+
+export function buildReplyContext(
   message?: proto.IMessage | null,
   pushNames?: Map<string, string>,
   canonicalize?: (jid: string) => string,
+  nameLookup?: (jid: string) => string | undefined,
 ): string | undefined {
   const contextInfo = getContextInfo(message);
   if (!contextInfo?.quotedMessage) return undefined;
@@ -91,17 +102,23 @@ function buildReplyContext(
   const rawQuotedJid = contextInfo.participant || "unknown";
   // pushNames is keyed by canonical jid — resolve before lookup.
   const quotedJid = canonicalize ? canonicalize(rawQuotedJid) : rawQuotedJid;
+  // pushNames lives only in memory and is empty after every restart;
+  // nameLookup is the durable fallback (space_roles.display_name), so a quoted
+  // sender keeps their name instead of degrading to a bare LID.
   const quotedName =
-    pushNames?.get(quotedJid) || quotedJid.split("@")[0] || "unknown";
+    pushNames?.get(quotedJid) ||
+    nameLookup?.(quotedJid) ||
+    quotedJid.split("@")[0] ||
+    "unknown";
   const quotedMessageId = contextInfo.stanzaId || "unknown";
 
   // Check if quoted message has media
   const quotedMedia = detectWhatsAppMedia(contextInfo.quotedMessage);
 
   const attrs = [
-    `name="${quotedName}"`,
-    `jid="${quotedJid}"`,
-    `message_id="${quotedMessageId}"`,
+    `name="${escapeAttr(quotedName)}"`,
+    `jid="${escapeAttr(quotedJid)}"`,
+    `message_id="${escapeAttr(quotedMessageId)}"`,
   ];
 
   if (quotedMedia) {
@@ -175,6 +192,13 @@ export class WhatsAppBaileysAdapter
   /** Persistent LID↔phone alias store — assigned by main.ts after core init. */
   aliasStore?: WaAliasStore;
 
+  /**
+   * Durable display-name lookup by canonical jid — assigned by main.ts after
+   * core init. Backs `pushNames`, which is memory-only and starts empty on
+   * every restart.
+   */
+  displayNameLookup?: (canonicalJid: string) => string | undefined;
+
   constructor(options?: WhatsAppAdapterOptions) {
     this.userName = options?.userName ?? "mercury";
     this.authDir =
@@ -193,6 +217,28 @@ export class WhatsAppBaileysAdapter
   private canonicalizeQuoted = (jid: string): string =>
     canonicalizeJidSync(jid, undefined, this.aliasStore).canonical;
 
+  /**
+   * Resolve a quoted message's participant through Baileys' async LID store.
+   *
+   * The reply-context builder is synchronous, so it can only see mappings the
+   * alias store already knows. Running the async resolution first *learns* the
+   * pair into that store, after which the sync path finds it — which is how an
+   * otherwise-unknown LID ends up rendered as a name. Failures are non-fatal:
+   * canonicalizeJid swallows lookup errors and degrades to the LID.
+   */
+  private async learnQuotedParticipant(
+    message?: proto.IMessage | null,
+  ): Promise<void> {
+    const participant = getContextInfo(message)?.participant;
+    if (!participant) return;
+    await canonicalizeJid(
+      participant,
+      undefined,
+      this.aliasStore,
+      this.lidLookup,
+    );
+  }
+
   /**
    * Get current QR status for API endpoint
    */
@@ -460,6 +506,7 @@ export class WhatsAppBaileysAdapter
       raw.message,
       this.pushNames,
       this.canonicalizeQuoted,
+      this.displayNameLookup,
     );
     const text = [baseText, replyContext].filter(Boolean).join("\n\n").trim();
     const threadId = this.encodeThreadId({
@@ -560,10 +607,13 @@ export class WhatsAppBaileysAdapter
     }
 
     let baseText = extractText(msg.message).trim();
+    // Learn the quoted sender's LID→phone mapping before the sync builder runs.
+    await this.learnQuotedParticipant(msg.message);
     const replyContext = buildReplyContext(
       msg.message,
       this.pushNames,
       this.canonicalizeQuoted,
+      this.displayNameLookup,
     );
 
     // WhatsApp @-mentions embed JIDs in text (e.g. "@52669955764381").
@@ -582,9 +632,19 @@ export class WhatsAppBaileysAdapter
       ? isBotJid(quotedParticipant)
       : false;
 
-    // Replace bot's JID mention with configured userName so trigger patterns match
+    // Replace bot's JID mention with configured userName so trigger patterns match.
+    //
+    // isBotMentioned is set from the JID comparison alone and travels onward as
+    // a flag. The rewrite below is only cosmetic — it makes the trigger word
+    // strippable and the text readable — and it can legitimately find nothing:
+    // WhatsApp puts the mentioned user's *LID* digits in the text for
+    // LID-addressed accounts, so any divergence between that string and the jid
+    // we decode leaves the text untouched. Deriving "was I addressed" from the
+    // result of this replace is what made a correct tag look like idle chatter.
+    let isBotMentioned = false;
     for (const jid of mentionedJids) {
       if (isBotJid(jid)) {
+        isBotMentioned = true;
         const user = jidDecode(jid)?.user;
         if (user) {
           baseText = baseText.replace(
@@ -666,6 +726,7 @@ export class WhatsAppBaileysAdapter
         // Using spread to add custom properties (not in MessageMetadata type)
         ...({
           isReplyToBot,
+          isBotMentioned,
           replyToMessageId: contextInfo?.stanzaId ?? undefined,
           platformMessageId: msg.key.id ?? undefined,
           aliasThreadId,