mercury-agent 0.24.3-beta.0 → 0.24.3-beta.2

package/docs/pending-verification.md

@@ -2286,12 +2286,24 @@ The review of the seven 2026-10-02 fixes landed follow-ups on `dev`. Three baked
 
 ## Plan unattended-1003 / S6
 
-The WhatsApp media download now closes its socket when a bound fires, through a Baileys patch (`patches/`). Host-only, nothing baked: a **sync** (which runs `bun install` because `package.json` and `bun.lock` changed) **and a restart**. No image rebuild.
+The WhatsApp media download now closes its socket when a bound fires, through a Baileys patch (`patches/`). *(Superseded 2026-10-07: the patch never reached npm-installed hosts, so it was removed and the media `fetch` is now owned by `fetchDecryptedMedia` — `docs/debug/moderate/2026-10-07-baileys-patch-never-reaches-an-npm-installed-host.md`. The greps below for `signal: options.signal` in `node_modules` now print 0 by design.)* Host-only, nothing baked: a **sync** (which runs `bun install` because `package.json` and `bun.lock` changed) **and a restart**. No image rebuild.
 
 - [x] *(Verified 2026-10-05 on the WSL box, dev `6ddb895`, base `mercury-agent:0.24.2-beta.2` = `63637858e06b`, derived `mercury-agent-ext:b2acae430168` (built 13:36:22 IDT, 482 s), restart 13:28:17 IDT: the sync ran `bun install` and the grep prints `1`.)* MANUAL-VERIFY(2026-10-04): After the sync, `grep -c -F "signal: options.signal" ~/mercury-src/node_modules/@whiskeysockets/baileys/lib/Utils/messages-media.js` prints 1. A 0 means `bun install` did not run or did not apply the patch, and the fix is not deployed even though the code is.
 - [x] *(Verified 2026-10-05 on the WSL box, dev `6ddb895`, base `mercury-agent:0.24.2-beta.2` = `63637858e06b`, derived `mercury-agent-ext:b2acae430168` (built 13:36:22 IDT, 482 s), restart 13:28:17 IDT. Rehearsed, not waited for: the deployed `downloadWhatsAppMedia` from `~/mercury-src`, with production bounds and its patched `node_modules`, against a local raw-TCP server. Open stall: `bound fired while opening` at 30.0 s, `download_failed` to `onSkipped`, server saw the socket close 2 ms later. Body stall after 64 KB: `read bound fired` (idle) at 30.0 s, `download_failed`, socket closed 1 ms later. The live-journal half is still worth a glance the next time a real download stalls.)* MANUAL-VERIFY(2026-10-04): The next time the journal shows `WhatsApp media read bound fired` or `bound fired while opening`, `ss -tnp | grep -c <bun pid>` taken a few seconds later shows no connection to the WhatsApp media host left open for that download, and the user was told the file could not be downloaded.
 - [x] *(Verified 2026-10-05: `docker build -f Dockerfile.host` from `~/mercury-src` at `6ddb895` exited 0, `COPY patches/` ran before `bun install --production`, and the built image's `node_modules/@whiskeysockets/baileys/lib/Utils/messages-media.js` has `signal: options.signal` (1). Throwaway tag removed.)* MANUAL-VERIFY(2026-10-04): If any box builds `Dockerfile.host`, its next build passes the `bun install --production` step (it now copies `patches/` first; without it the install fails with `Couldn't find patch file`).
 
+## baileys-patch-never-reaches-an-npm-installed-host (2026-10-07)
+
+The media download fetches and decrypts itself instead of through a patched Baileys. Host-only: a sync (`bun install`, since `package.json` and `bun.lock` changed) and a restart; no image rebuild.
+
+- [ ] MANUAL-VERIFY(2026-10-07): After deploying, send the bot a photo, a voice note and a PDF in a group it answers in, and confirm it describes each one — real WhatsApp media must decrypt through the new path, which the tests only exercise with media they encrypted themselves.
+
+## spent-brave-budget-leaves-no-web-search (2026-10-08)
+
+Host-side only (`examples/extensions/web-search`): a sync and a restart; no image rebuild.
+
+- [ ] MANUAL-VERIFY(2026-10-08): On the VPS, once October's Brave budget (600) is spent, ask the bot a keyword question; it should answer by searching in the browser rather than saying it cannot search.
+
 ## Plan unattended-1003 / S7
 
 `pinchtab_nav` and the session injector now ship as files in the pinchtab extension's `bin/`. They reach the box through the installed snapshot, which is refreshed on restart, and from there into the **derived** image, whose hash includes the bin files. So this is a restart, then wait for the journal's `Built derived agent image` line. No base rebuild.

package/docs/web-search.md

@@ -12,12 +12,13 @@ Or install from the dashboard's **Features** page (one click).
 
 No API key is required for the browser. The extension uses [pinchtab](https://www.npmjs.com/package/pinchtab) to control a local headless Chromium and opens pages the same way a human would. It states no search policy: it does not tell the agent to search through a search engine's own site, because a scraped `search.brave.com` is unmetered and ends in a "Verifying you're not a bot" page after a few queries.
 
-The separate `web-search` extension (`mercury add web-search`) adds structured site search (flights, hotels, cars, apartments) on top of pinchtab and, for fast keyword and news lookups, exposes the Brave Search **API** as a host-side capability: set `MERCURY_BRAVE_API_KEY` in `.env` and the agent can run `mrctl capability web-search news '{"q":"..."}'` (or `web`). While `web-search` is loaded **and the host has a key**, every run's system prompt says keyword search goes only through that capability, never through a search engine's site in the browser, and its refusals (budget spent, Brave unavailable) say the same instead of pointing at the browser. Without a key the capability answers every call with a 503, so that rule is not emitted: a keyless host states no search policy, like a host without `web-search`. The key is declared `hostOnly`, so it never enters a container; the host makes the call, applies a per-space hourly cap (`brave_hourly_cap`, default 60), and returns trimmed results.
+The separate `web-search` extension (`mercury add web-search`) adds structured site search (flights, hotels, cars, apartments) on top of pinchtab and, for fast keyword and news lookups, exposes the Brave Search **API** as a host-side capability: set `MERCURY_BRAVE_API_KEY` in `.env` and the agent can run `mrctl capability web-search news '{"q":"..."}'` (or `web`). While `web-search` is loaded **and the host has a key**, every run's system prompt says keyword search goes only through that capability, never through a search engine's site in the browser, and its run-cap, hourly-cap and broken-key (401/403) refusals say the same instead of pointing at the browser. Once the month's credit is gone (the monthly budget below is spent, or Brave answers 402), that rule is replaced: the prompt and the refusal tell the agent to search in the browser until the month resets, because a box with a key and no credit would otherwise have no keyword search at all. Without a key the capability answers every call with a 503, so that rule is not emitted: a keyless host states no search policy, like a host without `web-search`. The key is declared `hostOnly`, so it never enters a container; the host makes the call, applies a per-space hourly cap (`brave_hourly_cap`, default 60), and returns trimmed results.
 
 Three more brakes sit behind it:
 - **Per run:** `run_cap`, default 20 billed calls. The same query (same `q`, `count` and `freshness`) asked twice in one run is answered once, including two copies sent at the same time and a repeat after the run was refused. A cap set to a number too large to be exact (past 2^53 - 1) is rejected and falls back to the default.
 - **Per host per calendar month (UTC):** `monthly_budget`, default 1000, about Brave's free grant. It is read from the `@global` scope only, so a space cannot change it. It counts attempts, so calls that time out or fail upstream count too.
-- **Monthly warnings:** the host's operators (`admins`) get one message at 80%, one at 95%, and one at 100%, when web search starts refusing on that host until the next month.
+- **Monthly warnings:** the host's operators (`admins`) get one message at 80%, one at 95%, and one at 100%, when Brave search stops on that host and the bot searches in the browser until the next month.
+- **Brave's own 402:** prepaid credit can run out before this host's count does (another bot on the key, or usage from before the count existed). A 402 marks the month spent at the current `monthly_budget` and sends the 100% message in Brave's terms. Raising `monthly_budget` after topping up brings Brave back the same month.
 
 Each host counts only its own calls, so when two bots share one key, set each host's `monthly_budget` to its share. The query log line carries `monthUsed` and, when Brave's response headers report it, `braveMonthlyRemaining`. That figure is the account total across every bot on the key.
 

package/examples/extensions/web-search/brave.ts

@@ -20,6 +20,7 @@ import {
   type LedgerDecision,
   type LedgerThreshold,
   ledgerMonth,
+  markMonthExhausted,
   parseBraveQuota,
   reserveBilledCall,
 } from "./ledger.js";
@@ -83,6 +84,18 @@ export const BRAVE_PROVIDER = "brave";
 export const NO_SCRAPED_SEARCH =
   "Answer from the results you already have. Do not run the search on a search engine's own site in the browser (search.brave.com, Google, Bing, DuckDuckGo). You may still open pages those results link to, and the specialist sites the web-search skill names.";
 
+/**
+ * What the agent is told once the month's credit is gone — our budget spent,
+ * or Brave's 402. The ban above protects the metered path from a runaway loop
+ * (run cap, hourly cap) or a broken key (401/403); with no credit left there
+ * is no metered path to protect, and keeping the ban left a box *with* a key
+ * worse off than one without (bug spent-brave-budget-leaves-no-web-search).
+ * Until the month resets, search goes to the browser, as on a keyless box.
+ * The prompt (index.ts) and both refusals carry this one text.
+ */
+export const SEARCH_IN_BROWSER =
+  "This month's web-search credit is used up, so do not call web-search again this month: search in the browser instead (pinchtab), e.g. on DuckDuckGo or Google, then open the pages the results link to. The specialist sites the web-search skill names still apply.";
+
 /** Brave freshness codes: past day / week / month / year. */
 const FRESHNESS = new Set(["pd", "pw", "pm", "py"]);
 const MAX_QUERY_CHARS = 400;
@@ -523,7 +536,7 @@ export async function handleBraveCapability(
     run.stop = {
       status: 429,
       data: {
-        error: `This host's Brave search budget for ${ledgerMonth(nowMs)} (${deps.monthlyBudget} searches) is spent. Do not call web-search again in this run. ${NO_SCRAPED_SEARCH}`,
+        error: `This host's Brave search budget for ${ledgerMonth(nowMs)} (${deps.monthlyBudget} searches) is spent. ${SEARCH_IN_BROWSER}`,
       },
     };
     return run.stop;
@@ -619,14 +632,45 @@ async function callBrave(
         permanent,
         detail,
       });
+      // 402 is Brave saying the prepaid credit is gone: the month is spent
+      // whatever our count says, for every later run too (the prompt reads
+      // the same row), until the month resets.
+      const creditGone = res.status === 402;
+      if (creditGone) {
+        const at = (deps.now ?? Date.now)();
+        // Operators hear it now, not on a later call: the prompt stops sending
+        // the agent here, so there may never be one. Once per budget, even if
+        // 100% was announced earlier in budget terms. A failed ledger write
+        // must not hide the 402 from the agent, so it is logged and passed.
+        try {
+          const mark = markMonthExhausted(
+            deps.store,
+            BRAVE_PROVIDER,
+            deps.monthlyBudget,
+            at,
+          );
+          if (mark.newlyMarked) {
+            announceBudget(deps, 100, mark.used, at, "provider-402");
+          }
+        } catch (error) {
+          deps.log?.warn(
+            "web-search: could not record Brave's 402 in the ledger",
+            {
+              error: error instanceof Error ? error.message : String(error),
+            },
+          );
+        }
+      }
       // Same rule as the cap branch: mrctl shows only the error string, so
       // the "stop retrying" instruction has to live inside it.
       const failed: CapabilityResult = {
         status: 502,
         data: {
-          error: permanent
-            ? `Brave search is unavailable this run (Brave returned ${res.status}: ${detail}). Do not retry web-search. ${NO_SCRAPED_SEARCH}`
-            : `Brave returned ${res.status}: ${detail}`,
+          error: creditGone
+            ? `Brave search credit is used up (Brave returned 402: ${detail}). ${SEARCH_IN_BROWSER}`
+            : permanent
+              ? `Brave search is unavailable this run (Brave returned ${res.status}: ${detail}). Do not retry web-search. ${NO_SCRAPED_SEARCH}`
+              : `Brave returned ${res.status}: ${detail}`,
         },
       };
       // A permanent status will not clear this run: every later call gets it
@@ -685,6 +729,7 @@ function announceBudget(
   threshold: LedgerThreshold,
   used: number,
   now: number,
+  cause: "budget" | "provider-402" = "budget",
 ): void {
   const month = ledgerMonth(now);
   deps.log?.warn("web-search: Brave monthly budget threshold", {
@@ -692,11 +737,15 @@ function announceBudget(
     used,
     budget: deps.monthlyBudget,
     month,
+    cause,
   });
-  const head = `Brave search on this host: ${used} of ${deps.monthlyBudget} billed searches used in ${month} (${threshold}% of web-search.monthly_budget).`;
+  const head =
+    cause === "provider-402"
+      ? `Brave search on this host: Brave answered 402 (prepaid credit used up) in ${month}, after ${used} billed searches counted here.`
+      : `Brave search on this host: ${used} of ${deps.monthlyBudget} billed searches used in ${month} (${threshold}% of web-search.monthly_budget).`;
   deps.alertOperators(
     threshold === 100
-      ? `${head} Web search now refuses on this host until next month. After topping up the Brave account, raise web-search.monthly_budget in the @global scope.`
-      : `${head} At 100% web search stops on this host until next month.`,
+      ? `${head} Until next month the bot searches in the browser instead (scraped, may hit CAPTCHAs). After topping up the Brave account, raise web-search.monthly_budget in the @global scope to bring Brave back.`
+      : `${head} At 100% web search moves to the browser on this host until next month.`,
   );
 }

package/examples/extensions/web-search/index.ts

@@ -5,13 +5,16 @@ import type {
 } from "../../../src/extensions/types.js";
 import {
   BRAVE_ENV,
+  BRAVE_PROVIDER,
   braveApiKey,
   DEFAULT_HOURLY_CAP,
   DEFAULT_MONTHLY_BUDGET,
   DEFAULT_RUN_CAP,
   handleBraveCapability,
   RunBudgets,
+  SEARCH_IN_BROWSER,
 } from "./brave.js";
+import { isMonthSpent } from "./ledger.js";
 
 // `mercury.config()` takes the bare key and namespaces it (config-registry.ts:
 // `${extension}.${key}`); every reader must therefore ask for the namespaced
@@ -85,19 +88,39 @@ export const SEARCH_ROUTING_PROMPT =
   "AutoScout24, Airbnb). " +
   PRICE_ROUTING_PROMPT;
 
+/** The rule while the month's Brave credit is gone: the browser searches. */
+export const CREDIT_GONE_ROUTING_PROMPT = `Web search: ${SEARCH_IN_BROWSER} ${PRICE_ROUTING_PROMPT}`;
+
 /**
- * The fragment a run gets, given the host's Brave key. The rule forbids every
- * keyword-search path but the capability, so it is only true while the
- * capability can answer: with no key every call is a 503, and the prompt would
- * leave a keyless install with no keyword search at all. Without a key this
- * extension states no search policy, exactly like a box without web-search
- * (the browser extension states none either); the skill and its 503 remain.
+ * The fragment a run gets, given the host's Brave key and whether this month's
+ * credit is gone. The rule forbids every keyword-search path but the
+ * capability, so it is only true while the capability can answer:
+ * - no key: every call is a 503, so this extension states no search policy,
+ *   exactly like a box without web-search; the skill and its 503 remain.
+ * - credit gone (budget spent, or Brave's 402): every call is refused until
+ *   the month resets, so the rule is replaced by "search in the browser" —
+ *   keeping it left a box with a key worse off than one without.
  * The price pointer is not search policy — Zap needs no key — so it stays.
  */
-export function searchRoutingPrompt(rawKey: string | undefined): string {
-  return braveApiKey(rawKey) === ""
-    ? PRICE_ROUTING_PROMPT
-    : SEARCH_ROUTING_PROMPT;
+export function searchRoutingPrompt(
+  rawKey: string | undefined,
+  creditGone = false,
+): string {
+  if (braveApiKey(rawKey) === "") return PRICE_ROUTING_PROMPT;
+  return creditGone ? CREDIT_GONE_ROUTING_PROMPT : SEARCH_ROUTING_PROMPT;
+}
+
+/**
+ * The host's monthly budget: @global only, so a space cannot raise it. The
+ * capability and the per-run prompt both read it here, so they cannot drift.
+ */
+function readMonthlyBudget(
+  ctx: Pick<MercuryExtensionContext, "getConfig">,
+): number {
+  return readCap(
+    ctx.getConfig(GLOBAL_SCOPE, MONTHLY_BUDGET_CONFIG_FULL_KEY),
+    DEFAULT_MONTHLY_BUDGET,
+  );
 }
 
 export default function (mercury: MercuryExtensionAPI) {
@@ -126,7 +149,7 @@ export default function (mercury: MercuryExtensionAPI) {
 
   mercury.config(MONTHLY_BUDGET_CONFIG_KEY, {
     description:
-      "Max billed Brave API calls this host makes per calendar month (UTC), across all spaces. Read from the global scope only. Warns operators at 80% and 95%, refuses at 100%. 0 blocks every call.",
+      "Max billed Brave API calls this host makes per calendar month (UTC), across all spaces. Read from the global scope only. Warns operators at 80% and 95%; at 100% Brave is refused and the bot searches in the browser until next month. 0 blocks every Brave call (browser search from the start).",
     default: String(DEFAULT_MONTHLY_BUDGET),
     validate: isValidCap,
   });
@@ -152,10 +175,7 @@ export default function (mercury: MercuryExtensionAPI) {
           DEFAULT_RUN_CAP,
         ),
         runs,
-        monthlyBudget: readCap(
-          ctx.getConfig(GLOBAL_SCOPE, MONTHLY_BUDGET_CONFIG_FULL_KEY),
-          DEFAULT_MONTHLY_BUDGET,
-        ),
+        monthlyBudget: readMonthlyBudget(ctx),
         alertOperators: (text) =>
           ctx.alertOperators({ extension: "web-search", text }),
         log: ctx.log,
@@ -168,7 +188,27 @@ export default function (mercury: MercuryExtensionAPI) {
   // per run, from the same env the capability reads, so the prompt and the
   // capability's 503 agree. The browser extension's fragment states no search
   // policy at all.
-  mercury.on("before_container", async () => {
-    return { systemPrompt: searchRoutingPrompt(process.env[BRAVE_ENV]) };
+  // Credit is read from the same ledger row and the same global budget the
+  // capability reads, so the prompt never sends the agent to a refusal.
+  mercury.on("before_container", async (_event, ctx) => {
+    // A hook that throws blocks the run (src/extensions/hooks.ts), so a ledger
+    // read failure must not cost every run on the host its turn: it falls
+    // back to "credit left", the rule before this check existed, and says so.
+    let creditGone = false;
+    try {
+      creditGone = isMonthSpent(
+        mercury.store,
+        BRAVE_PROVIDER,
+        readMonthlyBudget(ctx),
+        Date.now(),
+      );
+    } catch (error) {
+      ctx.log?.warn("web-search: ledger read failed; assuming credit left", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+    return {
+      systemPrompt: searchRoutingPrompt(process.env[BRAVE_ENV], creditGone),
+    };
   });
 }

package/examples/extensions/web-search/ledger.ts

@@ -34,6 +34,15 @@ interface LedgerRow {
   count: number;
   /** Thresholds already announced this month. */
   announced: number[];
+  /**
+   * The provider itself said this month's credit is gone (Brave's 402), which
+   * can come before our count does — another bot on the same key, or usage
+   * from before the ledger existed. Lives in the month's row, so it clears on
+   * the 1st with everything else. Holds only while the budget is the one it
+   * was recorded under: the 100% alert tells the operator to top up and raise
+   * `monthly_budget`, and doing that must bring search back this month.
+   */
+  exhaustedAtBudget?: number;
 }
 
 /**
@@ -53,6 +62,9 @@ function readRow(
       return {
         count: p.count,
         announced: p.announced.filter((n) => typeof n === "number"),
+        ...(typeof p.exhaustedAtBudget === "number"
+          ? { exhaustedAtBudget: p.exhaustedAtBudget }
+          : {}),
         corrupt: false,
       };
     }
@@ -63,9 +75,11 @@ function readRow(
 }
 
 /**
- * Read-only: is this month's budget already spent? For checks that must run
- * before something else is written (the hourly window), so a spent month is
- * reported as itself rather than as whichever limit happened to come first.
+ * Read-only: is this month's credit gone — our budget spent, or the provider
+ * already said so? For checks that must run before something else is written
+ * (the hourly window), so a spent month is reported as itself rather than as
+ * whichever limit happened to come first. The per-run prompt asks the same
+ * question, so what the agent is told and what the capability does agree.
  */
 export function isMonthSpent(
   store: ExtensionStore,
@@ -73,7 +87,39 @@ export function isMonthSpent(
   budget: number,
   now: number,
 ): boolean {
-  return readRow(store, ledgerKey(provider, ledgerMonth(now))).count >= budget;
+  const row = readRow(store, ledgerKey(provider, ledgerMonth(now)));
+  return row.exhaustedAtBudget === budget || row.count >= budget;
+}
+
+/**
+ * Record that the provider refused for lack of credit (402) this month, under
+ * the current `budget` (see `exhaustedAtBudget`). Every threshold counts as
+ * announced, so a later refusal does not announce one again in budget terms. Returns
+ * whether this is news (not already recorded under this budget) and the count,
+ * so the caller announces it exactly once per budget.
+ */
+export function markMonthExhausted(
+  store: ExtensionStore,
+  provider: string,
+  budget: number,
+  now: number,
+): { newlyMarked: boolean; used: number } {
+  const key = ledgerKey(provider, ledgerMonth(now));
+  const { corrupt: _corrupt, ...row } = readRow(store, key);
+  if (row.exhaustedAtBudget === budget) {
+    return { newlyMarked: false, used: row.count };
+  }
+  // Every threshold: the 402 is the 100% message, and a later refusal must
+  // not then announce an 80% or 95% the month has already passed.
+  const announced = [
+    ...row.announced,
+    ...LEDGER_THRESHOLDS.filter((t) => !row.announced.includes(t)),
+  ];
+  store.set(
+    key,
+    JSON.stringify({ ...row, announced, exhaustedAtBudget: budget }),
+  );
+  return { newlyMarked: true, used: row.count };
 }
 
 export interface LedgerDecision {
@@ -104,7 +150,7 @@ export function reserveBilledCall(
 ): LedgerDecision {
   const key = ledgerKey(provider, ledgerMonth(now));
   const { corrupt, ...row } = readRow(store, key);
-  const allowed = row.count < budget;
+  const allowed = row.exhaustedAtBudget !== budget && row.count < budget;
   if (allowed) row.count += 1;
   const pct = budget > 0 ? (row.count / budget) * 100 : 100;
   // At the refusal the month is spent whatever the count says (budget 0, or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.24.3-beta.0",
+  "version": "0.24.3-beta.2",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -151,8 +151,5 @@
     "ws": ">=8.20.1",
     "qs": ">=6.15.2",
     "lodash": ">=4.18.1"
-  },
-  "patchedDependencies": {
-    "@whiskeysockets/baileys@7.0.0-rc14": "patches/@whiskeysockets%2Fbaileys@7.0.0-rc14.patch"
   }
 }

package/src/adapters/whatsapp-media.ts

@@ -6,10 +6,17 @@
  * can be reused by other adapters.
  */
 
+import { createDecipheriv } from "node:crypto";
 import path from "node:path";
-import type { Readable } from "node:stream";
+import { Readable, Transform } from "node:stream";
+import type { ReadableStream as WebReadableStream } from "node:stream/web";
 import {
-  downloadMediaMessage,
+  type MediaType as BaileysMediaType,
+  DEFAULT_ORIGIN,
+  extractMessageContent,
+  getContentType,
+  getMediaKeys,
+  getUrlFromDirectPath,
   normalizeMessageContent,
   type proto,
   type WAMessage,
@@ -35,26 +42,6 @@ import type {
   MessageAttachment,
 } from "../types.js";
 
-const silentBaileysLogger: {
-  level: string;
-  child: () => typeof silentBaileysLogger;
-  trace: () => void;
-  debug: () => void;
-  info: () => void;
-  warn: () => void;
-  error: () => void;
-  fatal: () => void;
-} = {
-  level: "silent",
-  child: () => silentBaileysLogger,
-  trace: () => undefined,
-  debug: () => undefined,
-  info: () => undefined,
-  warn: () => undefined,
-  error: () => undefined,
-  fatal: () => undefined,
-};
-
 /**
  * Media info extracted from a WhatsApp message.
  * Used internally before download.
@@ -81,8 +68,8 @@ export interface MediaDownloadOptions {
    */
   onSkipped?: (info: DroppedAttachment) => void;
   /**
-   * The byte stream for a message. Default: Baileys' `downloadMediaMessage`
-   * over the socket, in stream mode. Injected only so the write legs below
+   * The byte stream for a message. Default: `fetchDecryptedMedia` — our
+   * `fetch` of the media URL, decrypted with Baileys' media keys. Injected only so the write legs below
    * can be exercised without a socket; production passes nothing.
    */
   download?: (
@@ -100,18 +87,23 @@ export interface MediaDownloadOptions {
 export interface MediaDownloadContext {
   /** Aborted on every exit but a clean end; this is what closes the socket. */
   signal: AbortSignal;
-  /** Baileys' re-upload request, under the re-upload bound instead of the open one. */
+  /**
+   * The phone re-upload, for an injected download that asks for one (production
+   * never does; see `WHATSAPP_REUPLOAD_BOUND_MS`), under the re-upload bound.
+   */
   reuploadRequest: (msg: WAMessage) => Promise<WAMessage>;
 }
 
 // The time bounds (`MediaReadBounds`, `MEDIA_READ_BOUNDS`) live in
 // `core/media.ts`, shared with the URL legs so the two readers cannot drift.
-// Baileys' `fetch` carries no timeout, so without them a stalled connection
+// The media `fetch` carries no timeout, so without them a stalled connection
 // holds the turn forever; here the idle bound is also what ends a body whose
 // connection died mid-download, because `pipe()` never tells the decrypt
 // Transform that its source errored (see `readStreamCapped`). A fired bound
-// closes the socket only through the request's `AbortSignal`, which Baileys
-// passes to `fetch` by our patch (`patches/@whiskeysockets%2Fbaileys@*.patch`).
+// closes the socket only through the request's `AbortSignal`, which is why
+// `fetchDecryptedMedia` owns the `fetch`: Baileys' `getHttpStream` takes no
+// signal, and the dependency patch that once threaded one in never reached an
+// npm-installed host (`patchedDependencies` applies to the root project only).
 
 /**
  * The bound on the phone re-upload Baileys requests when a media URL has
@@ -124,10 +116,12 @@ export interface MediaDownloadContext {
  * plain server round trip. Past it the turn reports `download_failed`, which
  * is the right answer for a phone that is offline.
  *
- * Unreachable on Baileys 7.0.0-rc14: it requests the re-upload only when
- * `error.status` is 404/410, and its own fetch error is a Boom carrying the
- * code in `output.statusCode`. `tests/whatsapp-media-socket-close.test.ts`
- * pins that fact, so a Baileys bump that makes the path live goes red there.
+ * Unreachable in production: `fetchDecryptedMedia` never requests a
+ * re-upload, which keeps the behaviour Baileys 7.0.0-rc14 had (it asked only
+ * when `error.status` was 404/410, and its own fetch error carried the code in
+ * `output.statusCode`, so never). An expired URL is `download_failed`.
+ * Making it live is a behaviour change that needs a real old quoted message
+ * to verify against; `tests/whatsapp-media-socket-close.test.ts` pins the 410.
  */
 export const WHATSAPP_REUPLOAD_BOUND_MS = 2 * 60_000;
 
@@ -173,8 +167,8 @@ function destroyWithSource(stream: Readable): void {
  * The returned promise is itself the race: whichever of end, error, the cap or
  * a bound comes first settles it, and every exit clears both timers.
  *
- * Baileys' stream is a decrypt `Transform` that the HTTP body is `pipe`d
- * into. Destroying the Transform alone only unpipes the body, and Bun's fetch
+ * The download's stream is a decrypt `Transform` that the HTTP body is
+ * `pipe`d into (`fetchDecryptedMedia`, the shape Baileys' own download had). Destroying the Transform alone only unpipes the body, and Bun's fetch
  * keeps buffering a body nobody reads (measured 2026-10-02: 591 MB RSS for a
  * 512 MB body, against 54 MB when the source is destroyed too). The source is
  * not exposed, so it is taken from the `unpipe` event every exit triggers:
@@ -188,13 +182,13 @@ function destroyWithSource(stream: Readable): void {
  * - **No early listener.** The destination of a `pipe()` holds no reference
  *   to its source (the closures in `pipe` do), so the source cannot be
  *   reached until it unpipes. That is safe only because the listener below is
- *   attached synchronously on entry, and Baileys' path from
- *   `fetched.pipe(output)` to our caller is promise resolutions only: `pipe`
+ *   attached synchronously on entry, and `fetchDecryptedMedia`'s path from
+ *   `body.pipe(decrypt)` to our caller is promise resolutions only: `pipe`
  *   starts the flow with `process.nextTick`, which runs after the microtask
  *   queue drains, so no chunk and no decrypt error can reach the Transform
  *   before this listener exists — even with the body already buffered. A
- *   macrotask inserted between Baileys' `pipe` and its `return` would open
- *   that window; `tests/whatsapp-media-capped-read.test.ts` pins the shape.
+ *   macrotask inserted between that `pipe` and its `return` would open that
+ *   window; `tests/whatsapp-media-capped-read.test.ts` pins the shape.
  * - **A dead body is silent.** When the connection resets mid-body, Bun's
  *   `Readable.fromWeb` source closes errored and emits no `'error'`, and
  *   `pipe()` forwards neither, so the Transform simply stops receiving. No
@@ -290,7 +284,7 @@ export function readStreamCapped(
 }
 
 /**
- * The bound on Baileys' open: the media fetch up to its response headers, under
+ * The bound on the download's open: the media fetch up to its response headers, under
  * the idle bound, and a phone re-upload in between, under its own bound. One
  * timer, re-armed as the phase changes; `rejected` settles when it fires.
  */
@@ -342,6 +336,119 @@ function openBound(
   };
 }
 
+/** WhatsApp media is AES-256-CBC in 16-byte blocks, followed by a 10-byte MAC. */
+const AES_BLOCK = 16;
+
+/** Thrown for a media URL that did not answer 2xx; the caller reports `download_failed`. */
+export class MediaFetchError extends Error {
+  override readonly name = "MediaFetchError";
+  constructor(readonly status: number) {
+    super(`WhatsApp media fetch failed: HTTP ${status}`);
+  }
+}
+
+/**
+ * Decrypt WhatsApp's media encryption as a stream: feed whole AES blocks to
+ * the decipher and hold back the remainder, which at the end is the 10-byte
+ * MAC and is dropped. The same arithmetic as Baileys' `downloadEncryptedContent`
+ * (no range support: we always fetch the whole file).
+ */
+function decryptMediaStream(cipherKey: Uint8Array, iv: Uint8Array): Transform {
+  const decipher = createDecipheriv("aes-256-cbc", cipherKey, iv);
+  let remainder: Buffer = Buffer.alloc(0);
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      const data = remainder.length ? Buffer.concat([remainder, chunk]) : chunk;
+      const whole = Math.floor(data.length / AES_BLOCK) * AES_BLOCK;
+      remainder = data.subarray(whole);
+      try {
+        callback(null, decipher.update(data.subarray(0, whole)));
+      } catch (error) {
+        callback(error as Error);
+      }
+    },
+    flush(callback) {
+      try {
+        callback(null, decipher.final());
+      } catch (error) {
+        callback(error as Error);
+      }
+    },
+  });
+}
+
+/** `new URL(url).host`, or undefined for a missing or unparsable URL. */
+function hostOf(url: string | null | undefined): string | undefined {
+  if (!url) return undefined;
+  try {
+    return new URL(url).host;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The production download: the media URL, fetched by us so the request
+ * carries `context.signal` (the only thing that closes its socket), and piped
+ * through the decrypt. Baileys supplies what it is the authority on — which
+ * content is the media, the URL from its `directPath`, the keys — and none of
+ * the I/O. Mirrors Baileys 7.0.0-rc14's `downloadMediaMessage` except that it
+ * never requests a phone re-upload (see `WHATSAPP_REUPLOAD_BOUND_MS`).
+ */
+async function fetchDecryptedMedia(
+  msg: WAMessage,
+  _sock: WASocket,
+  context: MediaDownloadContext,
+): Promise<Readable> {
+  const content = extractMessageContent(msg.message);
+  const contentType = content ? getContentType(content) : undefined;
+  const media = (content && contentType ? content[contentType] : undefined) as
+    | {
+        url?: string | null;
+        directPath?: string | null;
+        thumbnailDirectPath?: string | null;
+        mediaKey?: Uint8Array | null;
+      }
+    | undefined;
+  if (
+    !contentType ||
+    !media ||
+    typeof media !== "object" ||
+    (!("url" in media) && !("thumbnailDirectPath" in media))
+  ) {
+    throw new Error(`"${contentType}" message is not a media message`);
+  }
+  // Baileys' keying: the HKDF info string comes from the content type, and a
+  // wrong one decrypts to garbage silently (CBC does not authenticate).
+  let mediaType = contentType.replace("Message", "") as BaileysMediaType;
+  let directPath = media.directPath;
+  if ("thumbnailDirectPath" in media && !("url" in media)) {
+    directPath = media.thumbnailDirectPath;
+    mediaType = "thumbnail-link";
+  }
+  const url = directPath
+    ? getUrlFromDirectPath(directPath, hostOf(media.url))
+    : media.url;
+  if (!url) throw new Error("No media URL or directPath in the message");
+
+  const { cipherKey, iv } = await getMediaKeys(media.mediaKey, mediaType);
+  const response = await fetch(url, {
+    signal: context.signal,
+    headers: { Origin: DEFAULT_ORIGIN },
+  });
+  if (!response.ok || !response.body) {
+    // A non-2xx body is never read; `downloadBytes`' abort closes the socket.
+    response.body?.cancel().catch((error: unknown) =>
+      logger.debug("WhatsApp media non-2xx body cancel failed", {
+        error: error instanceof Error ? error.message : String(error),
+      }),
+    );
+    throw new MediaFetchError(response.status);
+  }
+  const body = Readable.fromWeb(response.body as WebReadableStream);
+  return body.pipe(decryptMediaStream(cipherKey, iv));
+}
+
 async function downloadBytes(
   msg: WAMessage,
   sock: WASocket,
@@ -352,7 +459,7 @@ async function downloadBytes(
     bounds.idleMs,
     options.reuploadBoundMs ?? WHATSAPP_REUPLOAD_BOUND_MS,
   );
-  // Destroying the stream Baileys returns, or its HTTP source, releases the
+  // Destroying the download's stream, or its HTTP source, releases the
   // reader but leaves the socket draining the body (measured on Bun 1.3.14:
   // still receiving after the destroy, closed within 1 ms of an abort). So
   // every exit aborts; after a clean end the abort is a no-op. The abort can
@@ -375,18 +482,11 @@ async function downloadBytes(
   };
   try {
     open.arm("open");
-    const opening = options.download
-      ? options.download(msg, sock, context)
-      : (downloadMediaMessage(
-          msg,
-          "stream",
-          { options: { signal: controller.signal } },
-          {
-            // biome-ignore lint/suspicious/noExplicitAny: Baileys logger type is complex
-            logger: silentBaileysLogger as any,
-            reuploadRequest: context.reuploadRequest,
-          },
-        ) as Promise<Readable>);
+    const opening = (options.download ?? fetchDecryptedMedia)(
+      msg,
+      sock,
+      context,
+    );
     // A stream that arrives after the bound fired is torn down on arrival.
     opening.then(
       (stream) => {