mercury-agent 0.16.2 → 0.17.0

package/src/core/routes/dashboard.ts

@@ -379,6 +379,9 @@ export function createDashboardRoutes(ctx: DashboardContext) {
     });
     const ambientOn =
       core.db.getSpaceConfig(spaceId, "ambient.enabled") !== "false";
+    // Absent is false: a space opts *in* to owning its persona.
+    const personaExclusive =
+      core.db.getSpaceConfig(spaceId, "persona.exclusive") === "true";
     // Read through the same helper the router uses, so the default cannot
     // drift between what this page shows and what actually gates a message.
     const mentionAlwaysOn = mentionAlwaysEnabled(core.db, spaceId);
@@ -469,6 +472,14 @@ export function createDashboardRoutes(ctx: DashboardContext) {
       ${row("trigger.media_in_groups", "trigger.media_in_groups", boolSelect("trigger.media_in_groups", tc.mediaInGroups))}
       ${row("trigger.mention_always", "trigger.mention_always", boolSelect("trigger.mention_always", mentionAlwaysOn))}
       ${row("ambient.enabled", "ambient.enabled", boolSelect("ambient.enabled", ambientOn))}
+      <p class="muted" style="margin:14px 0 10px;line-height:1.5">
+        <span class="mono">persona.exclusive</span> — when true, this space's
+        <span class="mono">AGENTS.md</span> is the only persona the model hears:
+        the owner's global character and the global
+        <span class="mono">AGENTS.md</span> are left out of its prompt. Off by
+        default; meant for a space whose standard is repo-owned.
+      </p>
+      ${row("persona.exclusive", "persona.exclusive", boolSelect("persona.exclusive", personaExclusive))}
     `;
   }
 
@@ -1799,7 +1810,9 @@ export function createDashboardRoutes(ctx: DashboardContext) {
                 <td class="muted">${formatRelativeTime(run.startedAt)}</td>
                 <td>${outcomeCell(run)}</td>
                 <td class="mono muted">${run.model ? escapeHtml(run.model) : "—"}</td>
-                <td class="mono">${run.totalTokens === null ? "—" : formatTokenCount(run.totalTokens)}</td>
+                <td class="mono" title="The prompt, measured on the first billed round. Comparable between runs — unlike the billed total, which multiplies by the number of rounds.">${run.promptPrefixTokens === null ? "—" : formatTokenCount(run.promptPrefixTokens)}</td>
+                <td class="mono muted" title="Billed model rounds. Every round re-sends the prompt, which is why cost tracks rounds x prefix.">${run.rounds === null ? "—" : run.rounds}</td>
+                <td class="mono muted" title="Every input-side token billed, summed across all rounds. This is what cost is proportional to. It is NOT the prompt size. A dash on a run that has a cost means the row predates the cache columns and its billed input was never recorded.">${run.billedPromptTokens === null ? "—" : formatTokenCount(run.billedPromptTokens)}</td>
                 <td class="mono">${run.cost === null ? "—" : formatCost(run.cost)}</td>
                 <td class="mono muted">${duration}</td>
                 <td class="mono muted">${run.replyChars === null ? "—" : run.replyChars}</td>
@@ -1811,7 +1824,7 @@ export function createDashboardRoutes(ctx: DashboardContext) {
             `;
             })
             .join("")
-        : `<tr><td colspan="11" class="empty">No runs recorded yet${
+        : `<tr><td colspan="13" class="empty">No runs recorded yet${
             task.lastRunAt === null
               ? ""
               : " — this task last ran before the ledger existed"
@@ -1829,7 +1842,9 @@ export function createDashboardRoutes(ctx: DashboardContext) {
                 <th>When</th>
                 <th>Outcome</th>
                 <th>Model</th>
-                <th>Tokens</th>
+                <th>Prefix</th>
+                <th>Rounds</th>
+                <th>Billed</th>
                 <th>Cost</th>
                 <th>Took</th>
                 <th>Chars</th>
@@ -2164,8 +2179,47 @@ export function createDashboardRoutes(ctx: DashboardContext) {
             .join("")
         : '<tr><td colspan="5" class="empty">No extensions installed. Add one from the catalog below.</td></tr>';
 
+    // Extensions present on disk but absent from the registry. Without this the
+    // page cannot tell them apart from "not installed" and offers an Install
+    // button that the installer rejects because the files are already there.
+    const inactive = registry.listSkipped();
+    const inactiveNames = new Set(inactive.map((s) => s.name));
+
+    const inactiveRows = inactive
+      .map((skip) => {
+        const cat = getCatalogEntryByName(skip.name);
+        const label = cat?.label ?? skip.name;
+        const desc =
+          cat?.description ?? "Installed extension (outside catalog).";
+        const hint = skip.missingEnvVar
+          ? `Set <span class="mono">${escapeHtml(skip.missingEnvVar)}</span> in the project root <span class="mono">.env</span> and restart Mercury.`
+          : escapeHtml(skip.message);
+        return `
+              <tr>
+                <td class="mono">${escapeHtml(skip.name)}</td>
+                <td>${escapeHtml(label)}</td>
+                <td class="muted" style="max-width:320px">
+                  ${escapeHtml(desc)}
+                  <div class="muted" style="font-size:12px;margin-top:4px">${hint}</div>
+                </td>
+                <td class="muted">${skip.reason === "credential" ? "missing credential" : "load error"}</td>
+                <td>${
+                  // Only the project extensions dir is removable — built-ins ship
+                  // with Mercury and removeInstalledExtension cannot delete them.
+                  skip.source === "project"
+                    ? `<button type="button" class="btn btn-sm btn-danger"
+                    hx-delete="/dashboard/api/extensions/${encodeURIComponent(skip.name)}"
+                    hx-target="#features-toast"
+                    hx-swap="innerHTML"
+                    hx-confirm="Remove extension &quot;${escapeHtml(skip.name)}&quot;? It is installed — removing deletes its files.">Remove</button>`
+                    : '<span class="muted">built-in</span>'
+                }</td>
+              </tr>`;
+      })
+      .join("");
+
     const available = EXTENSION_CATALOG.filter(
-      (e) => !installedNames.has(e.name),
+      (e) => !installedNames.has(e.name) && !inactiveNames.has(e.name),
     );
     const availableRows =
       available.length > 0
@@ -2226,11 +2280,15 @@ export function createDashboardRoutes(ctx: DashboardContext) {
         </div>
         <div class="panel">
           <div class="panel-header">Extension counts</div>
-          <div class="panel-body stats" style="grid-template-columns: 1fr 1fr">
+          <div class="panel-body stats" style="grid-template-columns: 1fr 1fr 1fr">
             <div class="stat">
               <div class="stat-value">${installed.length}</div>
               <div class="stat-label">Installed</div>
             </div>
+            <div class="stat">
+              <div class="stat-value">${inactive.length}</div>
+              <div class="stat-label">Inactive</div>
+            </div>
             <div class="stat">
               <div class="stat-value">${nAvail}</div>
               <div class="stat-label">Available to add</div>
@@ -2261,6 +2319,34 @@ export function createDashboardRoutes(ctx: DashboardContext) {
         </div>
       </div>
 
+      ${
+        inactive.length > 0
+          ? raw(`
+      <div class="panel">
+        <div class="panel-header">Installed but inactive</div>
+        <div class="panel-body">
+          <p class="muted" style="margin-bottom:10px;font-size:13px">These extensions are installed on disk but did not load. Installing again will fail — fix the cause below and restart Mercury.</p>
+          <div class="table-scroll">
+            <table class="table">
+              <thead>
+                <tr>
+                  <th>Name</th>
+                  <th>Label</th>
+                  <th>Description</th>
+                  <th>Reason</th>
+                  <th></th>
+                </tr>
+              </thead>
+              <tbody>
+                ${inactiveRows}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>`)
+          : ""
+      }
+
       <div class="panel">
         <div class="panel-header">Available features</div>
         <div class="panel-body">

package/src/core/runtime.ts

@@ -19,6 +19,7 @@ import {
 import type {
   ContainerResult,
   IngressMessage,
+  InputSource,
   MessageAttachment,
   MessageRunMeta,
   MessageSender,
@@ -39,10 +40,19 @@ import {
   createOperatorAlerter,
   registerCredentialAlertSink,
 } from "./operator-alerts.js";
-import { hasPermission, resolveRole } from "./permissions.js";
+import {
+  getRolePermissions,
+  hasPermission,
+  resolveRole,
+} from "./permissions.js";
 import { reapProcessTree } from "./process-tree.js";
 import { getActiveProfilePrompt } from "./profiles.js";
 import { RateLimiter } from "./rate-limiter.js";
+import {
+  hasReplyToBlock,
+  scrubDeliverySuffix,
+  stripReplyToBlocks,
+} from "./reply-context.js";
 import { type RouteResult, routeInput } from "./router.js";
 import { SpaceQueue } from "./space-queue.js";
 import {
@@ -50,14 +60,16 @@ import {
   formatSystemMessage,
   resolveLocale,
 } from "./system-messages.js";
-import { isNoOpTaskReply } from "./task-output.js";
+import { isNoOpTaskReply, isSilenceSentinel } from "./task-output.js";
 import {
   TaskDeliveryError,
   type TaskFailure,
   TaskScheduler,
 } from "./task-scheduler.js";
 
-export type InputSource = "cli" | "scheduler" | "chat-sdk";
+// Defined in types.ts so the storage layer can name it; re-exported here for
+// callers that have always imported it from the runtime.
+export type { InputSource };
 
 export type ShutdownHook = () => Promise<void> | void;
 
@@ -839,6 +851,25 @@ export class MercuryCoreRuntime {
             );
             return { type: "denied", reason };
           }
+          case "sandbox-unconfined": {
+            // Host refused to start the container rather than silently weaken
+            // its sandbox. An operator config choice, not a model or auth
+            // failure — the actionable detail is in the host log, so the reply
+            // stays generic rather than telling the user to try again.
+            logger.error(
+              "Container start refused: sandbox would be unconfined",
+              {
+                detail: error.message,
+              },
+            );
+            const reason = friendlyErrorMessage(
+              "generic",
+              this.config.apiKeyMode,
+              this.config.consoleUrl,
+              locale,
+            );
+            return { type: "denied", reason };
+          }
           case "error": {
             logger.error(
               "Container error",
@@ -1607,7 +1638,11 @@ export class MercuryCoreRuntime {
       // keep isolating. Fail-safe: if outbound recording ever missed the
       // message, the lookup returns null and isolation still fires.
       let replyIsolated = false;
-      let finalPrompt = prompt;
+      // The `_(responded in Ns)_` suffix is delivery decoration the bot never
+      // said (`handler.ts` adds it after the reply is stored). When a member
+      // quotes that reply the adapter copies it into the quote; it comes out
+      // here, at the join, before anything reads or stores the prompt.
+      let finalPrompt = scrubDeliverySuffix(prompt);
       if (
         replyFlags?.isReplyToBot &&
         !replyFlags.isDM &&
@@ -1622,10 +1657,7 @@ export class MercuryCoreRuntime {
         const earlyRole = resolveRole(this.db, spaceId, callerId, seededAdmins);
         if (earlyRole !== "admin" && earlyRole !== "system") {
           replyIsolated = true;
-          finalPrompt = finalPrompt.replace(
-            /\n*<reply_to[^>]*>[\s\S]*?<\/reply_to>/g,
-            "",
-          );
+          finalPrompt = stripReplyToBlocks(finalPrompt);
         }
       }
       // ────────────────────────────────────────────────────────────────────
@@ -1685,6 +1717,7 @@ export class MercuryCoreRuntime {
 
       // Emit before_container hook
       let extraEnv: Record<string, string> | undefined;
+      let ephemeralAppend = "";
       if (this.hooks && this.extensionCtx) {
         const result = await this.hooks.emitBeforeContainer(
           {
@@ -1715,6 +1748,10 @@ export class MercuryCoreRuntime {
               .filter(Boolean)
               .join("\n\n");
           }
+          // Kept out of `finalPrompt` on purpose — see `containerPrompt` below.
+          if (result.ephemeralAppend) {
+            ephemeralAppend = result.ephemeralAppend;
+          }
         }
       }
 
@@ -1731,8 +1768,17 @@ export class MercuryCoreRuntime {
         };
       }
 
+      // A space that owns its editorial standard can declare its AGENTS.md the
+      // only persona: the owner's global character is left out of this run's
+      // system prompt and the global AGENTS.md is not mounted (see the runner
+      // input below). Absent is false — every other space is byte-identical.
+      const personaExclusive =
+        this.db.getSpaceConfig(spaceId, "persona.exclusive") === "true";
+
       // Inject global character (owner-set voice, deploy-safe, global-admin gated).
-      const characterPrompt = this.db.getProjectConfig("character");
+      const characterPrompt = personaExclusive
+        ? null
+        : this.db.getProjectConfig("character");
       if (characterPrompt) {
         const existing = extraEnv?.MERCURY_EXT_SYSTEM_PROMPT;
         const block = `## Bot Character (set by the owner — applies to all conversations)\n${characterPrompt}`;
@@ -1785,12 +1831,16 @@ export class MercuryCoreRuntime {
             : (this.config.contextWindowSize ?? 10);
 
           if (replyMercuryMsgId !== null) {
-            const trimmedWindow = Math.floor(windowSize / 2);
+            // The anchor chain is *added to* the window, not carved out of it.
+            // Halving the window on a swipe-reply meant a reply saw five turns
+            // where a plain message saw ten, and in a space with scheduled
+            // runs those five were mostly procedure. `replyChainDepth` already
+            // bounds the chain, so the total stays bounded either way.
             const anchored = this.db.getAnchoredContext(
               spaceId,
               replyMercuryMsgId,
               replyChainDepth,
-              trimmedWindow,
+              windowSize,
             );
             anchorMessages = anchored.anchor;
             history = anchored.recent;
@@ -1825,6 +1875,52 @@ export class MercuryCoreRuntime {
         }
       }
 
+      // ── One copy of the quote ──────────────────────────────────────────
+      // A swipe-reply arrives with the adapter's `<reply_to>` rendering of the
+      // quoted message inside the body. When the same message is about to be
+      // rendered from the DB anyway — in `<reply_anchor>` (context mode) or as
+      // the reply chain (clear mode) — the body copy is dropped, so the turn
+      // reads quote → question and not quote → question → quote. The DB copy
+      // is the better one: it carries the timestamp, the chain above it and
+      // the bot's stored text rather than WhatsApp's rendering of it.
+      //
+      // Keyed on the rows the container will actually see, not on the id
+      // lookup alone: a `/clear` boundary or a zero chain depth can resolve
+      // the id and still leave the message out of the chain, and then the
+      // body copy is the only one. A body that is nothing but the quote is
+      // left whole for the same reason — an empty turn is worse than a
+      // repeated one.
+      if (replyMercuryMsgId !== null && hasReplyToBlock(finalPrompt)) {
+        const quoteRendered = [...(anchorMessages ?? []), ...history].some(
+          (m) => m.id === replyMercuryMsgId,
+        );
+        // "Nothing but the quote" is measured on what the person sent, not
+        // on `finalPrompt`: by now a hook append or a media-gate note may
+        // have been joined on, and those would make an empty body look
+        // non-empty.
+        const personOnly = stripReplyToBlocks(prompt).trim();
+        if (quoteRendered && personOnly) {
+          finalPrompt = stripReplyToBlocks(finalPrompt);
+        }
+      }
+      // ────────────────────────────────────────────────────────────────────
+
+      // What the container is sent, as opposed to what the turn is remembered
+      // as. They differ by `ephemeralAppend`: per-run context an extension
+      // expands for this run only.
+      //
+      // The stored turn keeps the *marker* that asked for the expansion, not
+      // the expansion. Storing the expanded text is what made feed-watch's
+      // 103 KB digest an input to every following run — this space replays the
+      // last N turns (`context.mode = context`), so a block written once was
+      // re-sent, and re-paid for, by every verify run for the rest of the day
+      // (`docs/debug/major/2026-08-31-feed-watch-digest-persisted-and-replayed.md`).
+      //
+      // `AfterContainerResult.storedReply` is the same split on the reply side.
+      const containerPrompt = [finalPrompt, ephemeralAppend]
+        .filter(Boolean)
+        .join("\n\n");
+
       const userMessageId = this.db.addMessage(
         spaceId,
         "user",
@@ -1832,6 +1928,7 @@ export class MercuryCoreRuntime {
         effectiveAttachments,
         userReplyToId,
         { id: callerId, name: authorName },
+        source,
       );
 
       // Record platform message ID mapping for the inbound user message
@@ -1849,16 +1946,21 @@ export class MercuryCoreRuntime {
       }
 
       // Compute caller role, denied CLIs, and permitted env vars
-      let callerRole = "member";
+      const seededAdmins = this.config.admins
+        ? this.config.admins
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+      const callerRole = resolveRole(this.db, spaceId, callerId, seededAdmins);
+      // The caller's effective permission set, handed to the container so the
+      // platform prompt can leave out instructions about tools this caller
+      // cannot use ("set a preference", "mute") instead of telling the model to
+      // do a thing and then to refuse it in the same turn.
+      const callerPermissions = [
+        ...getRolePermissions(this.db, spaceId, callerRole),
+      ];
       if (this.extensionRegistry) {
-        const seededAdmins = this.config.admins
-          ? this.config.admins
-              .split(",")
-              .map((s) => s.trim())
-              .filter(Boolean)
-          : [];
-        callerRole = resolveRole(this.db, spaceId, callerId, seededAdmins);
-
         const cliExtensions = this.extensionRegistry.getCliExtensions();
         if (cliExtensions.length > 0) {
           const denied = cliExtensions
@@ -1947,15 +2049,17 @@ export class MercuryCoreRuntime {
           spaceWorkspace: workspace,
           messages: history,
           anchorMessages,
-          prompt: finalPrompt,
+          prompt: containerPrompt,
           callerId,
           callerRole,
+          callerPermissions,
           authorName,
           attachments: effectiveAttachments,
           preferences,
           members,
           extraEnv,
           claimedEnvSources: this.extensionRegistry?.getClaimedEnvSources(),
+          mountGlobalAgentsMd: !personaExclusive,
         });
       } catch (err) {
         this.db.updateMessageRunMeta(userMessageId, userTurnRunMeta(undefined));
@@ -1970,6 +2074,8 @@ export class MercuryCoreRuntime {
             "[System: this run was killed at the container time limit before replying. Partial work may exist in the workspace.]",
             undefined,
             userMessageId,
+            undefined,
+            source,
           );
         }
         throw err;
@@ -1990,7 +2096,7 @@ export class MercuryCoreRuntime {
             spaceId,
             workspace,
             callerId,
-            prompt: finalPrompt,
+            prompt: containerPrompt,
             reply: containerResult.reply,
             durationMs,
           },
@@ -2076,12 +2182,54 @@ export class MercuryCoreRuntime {
       }
       // ─────────────────────────────────────────────────────────────────────
 
+      // ── Chat silence: the sentinel is a legal reply to a person too ──────
+      // "If you have nothing to add, don't" was a rule the space could write
+      // but the runtime could not honour: a chat turn always sent *something*,
+      // and an empty reply became the "Done." placeholder. So the model
+      // answered "מקובל." to "אל תענה לי".
+      //
+      // Narrower than the scheduler's guard on purpose: only the explicit
+      // `NO_UPDATE` sentinel counts, never a bare "ok" or the "Done."
+      // placeholder. In chat those are still the answer to *someone* — a person
+      // who says "thanks" and gets "ok" back got a reply, and a run that
+      // produced no text at all is a failure the person should see, not a
+      // choice the model made. The person's own row stays (they really did
+      // say it); only the assistant row is not written. Files are never
+      // silenced — same rule as the scheduler.
+      const chatSilence =
+        source !== "scheduler" &&
+        containerResult.files.length === 0 &&
+        isSilenceSentinel(containerResult.reply);
+
+      if (chatSilence) {
+        if (containerResult.usage) {
+          this.db.recordUsage(spaceId, containerResult.usage);
+        }
+        this.db.updateMessageRunMeta(
+          userMessageId,
+          userTurnRunMeta(containerResult.usage),
+        );
+        // Info, not debug: the re-audit counts these. A model that goes quiet
+        // often is dodging, and D-018 says that is when the standard's
+        // priorities section needs to say where silence is not allowed.
+        logger.info("Chat turn answered with silence — sending nothing", {
+          spaceId,
+          source,
+          userMessageId,
+          suppressed: containerResult.reply.slice(0, 80),
+        });
+        return { ...containerResult, reply: "", silent: true };
+      }
+      // ─────────────────────────────────────────────────────────────────────
+
       const assistantMessageId = this.db.addMessage(
         spaceId,
         "assistant",
         storedReply,
         undefined,
         userMessageId, // reply chain: assistant replies to user message
+        undefined,
+        source,
       );
 
       if (containerResult.usage) {

package/src/core/task-output.ts

@@ -80,6 +80,41 @@ const DECORATION =
  */
 const INVISIBLE_CONTROLS = /[؜​-‏‪-‮⁦-⁩]/g;
 
+const normalize = (s: string) =>
+  s.replace(DECORATION, "").toLowerCase().replace(/\s+/g, " ");
+
+/**
+ * True when the model *chose* silence: the sentinel stands on its own line,
+ * first or last.
+ *
+ * This is the one no-op case that is a decision rather than an absence, and
+ * the only one the chat path honours. "Done." is a placeholder the parser
+ * substitutes for no text at all, and a bare "ok" in chat is an answer to
+ * someone; neither is the model saying "nothing to add". The sentinel is.
+ *
+ * A model told to emit exactly NO_UPDATE complies partially in both
+ * directions — the gloss before the token as often as after — and either way
+ * the raw token must not reach the chat. Checking only whole-string equality
+ * published it; checking only the first line published it whenever the gloss
+ * came first.
+ *
+ * Still safe against a genuine report that mentions the token: "3 transfers
+ * found. NO_UPDATE was not emitted." is a single line, and that line is not
+ * the sentinel. (A whole-string check would be redundant with these two: a
+ * one-line reply is both its first and its last line.)
+ */
+export function isSilenceSentinel(reply: string | null | undefined): boolean {
+  if (!reply) return false;
+  const stripped = reply
+    .replace(INVISIBLE_CONTROLS, "")
+    .replace(DECORATION, "");
+  const sentinel = NO_OUTPUT_SENTINEL.toLowerCase();
+  const lines = stripped.split("\n");
+  const firstLine = normalize(lines[0] ?? "");
+  const lastLine = normalize(lines[lines.length - 1] ?? "");
+  return firstLine === sentinel || lastLine === sentinel;
+}
+
 /**
  * True when the reply should not be sent anywhere.
  *
@@ -106,24 +141,7 @@ export function isNoOpTaskReply(reply: string | null | undefined): boolean {
   const stripped = visible.replace(DECORATION, "");
   if (stripped.length === 0) return true;
 
-  const normalize = (s: string) =>
-    s.replace(DECORATION, "").toLowerCase().replace(/\s+/g, " ");
-
-  // The sentinel on its own line, first or last. A model told to emit exactly
-  // NO_UPDATE complies partially in both directions — the gloss before the
-  // token as often as after — and either way the raw token must not reach the
-  // chat. Checking only whole-string equality published it; checking only the
-  // first line published it whenever the gloss came first.
-  //
-  // Still safe against a genuine report that mentions the token: "3 transfers
-  // found. NO_UPDATE was not emitted." is a single line, and that line is not
-  // the sentinel. (A whole-string check would be redundant with these two: a
-  // one-line reply is both its first and its last line.)
-  const sentinel = NO_OUTPUT_SENTINEL.toLowerCase();
-  const lines = stripped.split("\n");
-  const firstLine = normalize(lines[0] ?? "");
-  const lastLine = normalize(lines[lines.length - 1] ?? "");
-  if (firstLine === sentinel || lastLine === sentinel) return true;
+  if (isSilenceSentinel(reply)) return true;
 
   return ACKNOWLEDGEMENT_ONLY.has(normalize(stripped));
 }

package/src/core/task-scheduler.ts

@@ -1,6 +1,10 @@
 import { CronExpressionParser } from "cron-parser";
 import { logger } from "../logger.js";
-import { type Db, TASK_LAST_ERROR_MAX_LENGTH } from "../storage/db.js";
+import {
+  type Db,
+  TASK_LAST_ERROR_MAX_LENGTH,
+  taskRunBilledPromptTokens,
+} from "../storage/db.js";
 import type { ScheduledTask, TaskRunDetail, TaskRunStatus } from "../types.js";
 
 /**
@@ -363,6 +367,19 @@ export class TaskScheduler {
       outcome: run.status === "error" ? "error" : (run.detail?.outcome ?? null),
       model: run.detail?.usage?.model ?? null,
       durationMs: finishedAt - run.startedAt,
+      // The prompt (comparable between runs), the multiplier, and the input
+      // side the run was actually billed. `totalTokens` is input + output and
+      // excludes both cache legs — on a cached leg it is a sliver of the cost
+      // and reads as "6.7k tokens, $0.42", which is the misreading this ledger
+      // exists to end. Kept for continuity, never alone.
+      promptPrefixTokens: run.detail?.usage?.promptPrefixTokens ?? null,
+      rounds: run.detail?.usage?.rounds ?? null,
+      billedPromptTokens: taskRunBilledPromptTokens({
+        inputTokens: run.detail?.usage?.inputTokens ?? null,
+        cacheReadTokens: run.detail?.usage?.cacheReadTokens ?? null,
+        cacheWriteTokens: run.detail?.usage?.cacheWriteTokens ?? null,
+        rounds: run.detail?.usage?.rounds ?? null,
+      }),
       totalTokens: run.detail?.usage?.totalTokens ?? null,
       cost: run.detail?.usage?.cost ?? null,
       replyChars: run.detail?.replyChars ?? null,

package/src/extensions/catalog.ts

@@ -66,6 +66,7 @@ export const EXTENSION_CATALOG: ExtensionCatalogEntry[] = [
     description: "Google Workspace integration (see extension skill).",
     category: "other",
     sourceDir: "gws",
+    requiredEnvVars: ["MERCURY_GWS_CREDENTIALS_JSON"],
     requiresRestart: true,
   },
   {

package/src/extensions/hooks.ts

@@ -48,6 +48,7 @@ export class HookDispatcher {
    * Mutation semantics:
    * - systemPrompt: concatenated across handlers (newline-separated)
    * - promptAppend: concatenated across handlers (newline-separated)
+   * - ephemeralAppend: same, but the caller must keep it out of the stored turn
    * - env: merged (last-write-wins on key conflict)
    * - block: first handler to block stops the chain
    */
@@ -60,6 +61,7 @@ export class HookDispatcher {
 
     const systemPromptParts: string[] = [];
     const promptAppendParts: string[] = [];
+    const ephemeralAppendParts: string[] = [];
     let env: Record<string, string> = {};
     let hasMutations = false;
 
@@ -79,6 +81,9 @@ export class HookDispatcher {
         if (result.promptAppend) {
           promptAppendParts.push(result.promptAppend);
         }
+        if (result.ephemeralAppend) {
+          ephemeralAppendParts.push(result.ephemeralAppend);
+        }
         if (result.env) {
           env = { ...env, ...result.env };
         }
@@ -103,6 +108,9 @@ export class HookDispatcher {
       ...(promptAppendParts.length > 0
         ? { promptAppend: promptAppendParts.join("\n") }
         : {}),
+      ...(ephemeralAppendParts.length > 0
+        ? { ephemeralAppend: ephemeralAppendParts.join("\n") }
+        : {}),
       ...(Object.keys(env).length > 0 ? { env } : {}),
     };
   }