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

package/docs/pending-verification.md

@@ -2298,6 +2298,12 @@ The media download fetches and decrypts itself instead of through a patched Bail
 
 - [ ] 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.1",
+  "version": "0.24.3-beta.2",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",