mercury-agent 0.8.10 → 0.8.12

package/docs/media/whatsapp.md

@@ -47,7 +47,13 @@ Saved to: {workspace}/inbox/{timestamp}-{type}.{ext}
 function detectWhatsAppMedia(message: proto.IMessage): WhatsAppMediaInfo | null
 ```
 
-Checks message for media fields in order:
+The message is first unwrapped with Baileys' `normalizeMessageContent()` —
+WhatsApp wraps some payloads in FutureProofMessage envelopes
+(`documentWithCaptionMessage` for documents sent with a caption,
+`ephemeralMessage` in disappearing chats, `viewOnceMessage`/`viewOnceMessageV2`,
+`editedMessage`). Without unwrapping, a captioned PDF is invisible.
+
+Then checks the unwrapped content for media fields in order:
 1. `audioMessage?.ptt` → voice note
 2. `audioMessage` → audio
 3. `imageMessage` → image
@@ -157,7 +163,7 @@ Unknown MIME types default to `.bin`.
 
 2. **No built-in transcription** — Voice notes are saved as audio files; pi cannot play them. Install the **voice-transcribe** extension (local Whisper or cloud OpenAI/Groq/Gemini) to prepend a text transcript — see [overview.md](overview.md#voice-transcription).
 
-3. **Reply context doesn't include file** — When replying to a media message, we include metadata but not the actual file path. The original attachment would need to be looked up.
+3. **Quoted media re-download is partial** — Replying to a voice/audio/document/image message re-downloads the quoted file into the inbox (so "read this" replies work even if the original send was missed). Quoted videos are not re-fetched — too large to download speculatively on every reply.
 
 4. **Ephemeral media** — WhatsApp media URLs expire. Download must happen immediately when the message arrives.
 

package/examples/extensions/napkin/index.ts

@@ -10,7 +10,7 @@ import {
 } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir, tmpdir } from "node:os";
-import { delimiter, dirname, join } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
@@ -451,7 +451,13 @@ export default function (mercury: {
     }
 
     // 2. Fall back to Mercury's auth.json (OAuth token refresh)
-    const authPath = config.authPath ?? join(config.globalDir, "auth.json");
+    // Resolved, not raw: extensions receive `ctx.config` with `globalDir` still
+    // relative, while the container runner resolves it. Both spellings name the
+    // same file, and naming it the same way keeps the error strings below (and
+    // the refresh dedupe in getPiAuthCredential) consistent between the two.
+    const authPath = resolve(
+      config.authPath ?? join(config.globalDir, "auth.json"),
+    );
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,

package/package.json

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

package/src/adapters/whatsapp-media.ts

@@ -10,6 +10,7 @@ import fs from "node:fs";
 import path from "node:path";
 import {
   downloadMediaMessage,
+  normalizeMessageContent,
   type proto,
   type WAMessage,
   type WASocket,
@@ -64,8 +65,11 @@ export interface MediaDownloadOptions {
  * Returns null if the message has no media.
  */
 export function detectWhatsAppMedia(
-  message: proto.IMessage | null | undefined,
+  rawMessage: proto.IMessage | null | undefined,
 ): WhatsAppMediaInfo | null {
+  // Captioned documents (and ephemeral/view-once media) arrive wrapped in a
+  // FutureProofMessage envelope, e.g. documentWithCaptionMessage.message.
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return null;
 
   // Voice note (push-to-talk)
@@ -238,9 +242,18 @@ export async function downloadWhatsAppMedia(
   }
 }
 
+/** Media types worth re-fetching when someone replies to the message. */
+const QUOTED_DOWNLOAD_TYPES: ReadonlySet<MediaType> = new Set([
+  "voice",
+  "audio",
+  "document",
+  "image",
+]);
+
 /**
- * Download audio from a quoted (replied-to) WhatsApp message.
- * Only downloads voice/audio types — other media types are skipped.
+ * Download media from a quoted (replied-to) WhatsApp message.
+ * Downloads voice/audio/document/image — video is skipped (too large to
+ * re-fetch speculatively on every reply).
  */
 export async function downloadQuotedMedia(
   contextInfo: proto.IContextInfo,
@@ -253,7 +266,7 @@ export async function downloadQuotedMedia(
   const mediaInfo = detectWhatsAppMedia(quotedMessage);
   if (!mediaInfo) return null;
 
-  if (mediaInfo.type !== "voice" && mediaInfo.type !== "audio") return null;
+  if (!QUOTED_DOWNLOAD_TYPES.has(mediaInfo.type)) return null;
 
   const syntheticMsg: WAMessage = {
     key: {
@@ -310,7 +323,12 @@ export async function downloadQuotedMedia(
     fs.mkdirSync(mediaDir, { recursive: true });
 
     const ext = mimeToExt(mediaInfo.mimeType);
-    const filename = `${Date.now()}-${mediaInfo.type}.${ext}`;
+    const safeName = mediaInfo.filename
+      ? path.basename(mediaInfo.filename).replace(/[^a-zA-Z0-9._-]/g, "_")
+      : undefined;
+    const filename = safeName
+      ? `${Date.now()}-${safeName}`
+      : `${Date.now()}-${mediaInfo.type}.${ext}`;
     const filePath = path.join(mediaDir, filename);
 
     fs.writeFileSync(filePath, buffer);
@@ -327,6 +345,7 @@ export async function downloadQuotedMedia(
       path: filePath,
       type: mediaInfo.type,
       mimeType: mediaInfo.mimeType,
+      filename: mediaInfo.filename,
       sizeBytes: buffer.length,
     };
   } catch (error) {

package/src/adapters/whatsapp.ts

@@ -6,6 +6,7 @@ import makeWASocket, {
   fetchLatestWaWebVersion,
   jidDecode,
   makeCacheableSignalKeyStore,
+  normalizeMessageContent,
   type proto,
   useMultiFileAuthState,
   type WAMessage,
@@ -45,7 +46,11 @@ type WhatsAppThreadId = {
   threadJid: string;
 };
 
-function extractText(message?: proto.IMessage | null): string {
+function extractText(rawMessage?: proto.IMessage | null): string {
+  // Unwrap FutureProofMessage envelopes (documentWithCaptionMessage,
+  // ephemeralMessage, viewOnceMessage, …) — a document sent with a caption
+  // arrives as documentWithCaptionMessage.message.documentMessage.
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return "";
   return (
     message.conversation ||
@@ -58,8 +63,9 @@ function extractText(message?: proto.IMessage | null): string {
 }
 
 function getContextInfo(
-  message?: proto.IMessage | null,
+  rawMessage?: proto.IMessage | null,
 ): proto.IContextInfo | undefined {
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return undefined;
   const contextInfo =
     message.extendedTextMessage?.contextInfo ||
@@ -601,7 +607,16 @@ export class WhatsAppBaileysAdapter
     }
 
     const text = [baseText, replyContext].filter(Boolean).join("\n\n").trim();
-    if (!text && !hasMedia) return;
+    if (!text && !hasMedia) {
+      // Neither text nor media extracted — an unrecognized message shape would
+      // otherwise vanish silently (this is how captioned documents got lost
+      // before documentWithCaptionMessage unwrapping was added).
+      logger.debug("WhatsApp message dropped: no text or media extracted", {
+        remoteJid: chatJid,
+        messageKeys: Object.keys(msg.message ?? {}),
+      });
+      return;
+    }
 
     const threadId = this.encodeThreadId({
       chatJid,

package/src/agent/container-entry.ts

@@ -12,8 +12,10 @@ import {
 import path from "node:path";
 import type { MessageAttachment, StoredMessage } from "../types.js";
 import {
+  type CapabilitySource,
   DEFAULT_CAPABILITIES,
   type ModelCapabilities,
+  type WireModelCapabilities,
 } from "./model-capabilities-core.js";
 import { classifyPiFailure } from "./pi-failure-class.js";
 import {
@@ -59,48 +61,60 @@ function backoffMs(attemptIndex: number): number {
   return Math.min(cap, base + jitter);
 }
 
-function parsePartialCapabilities(obj: unknown): ModelCapabilities {
-  if (!obj || typeof obj !== "object") return { ...DEFAULT_CAPABILITIES };
+const CAPABILITY_SOURCES: readonly CapabilitySource[] = [
+  "env",
+  "yaml",
+  "builtin",
+  "default",
+];
+
+/** Guessed capabilities, explicitly marked as such. */
+function unverifiedCapabilities(): WireModelCapabilities {
+  return { ...DEFAULT_CAPABILITIES, source: "default" };
+}
+
+function parsePartialCapabilities(obj: unknown): WireModelCapabilities {
+  if (!obj || typeof obj !== "object") return unverifiedCapabilities();
   const o = obj as Record<string, unknown>;
-  const out = { ...DEFAULT_CAPABILITIES };
+  const out: WireModelCapabilities = unverifiedCapabilities();
   if (typeof o.tools === "boolean") out.tools = o.tools;
   if (typeof o.vision === "boolean") out.vision = o.vision;
   if (typeof o.audio_input === "boolean") out.audio_input = o.audio_input;
   if (typeof o.audio_output === "boolean") out.audio_output = o.audio_output;
   if (typeof o.extended_thinking === "boolean")
     out.extended_thinking = o.extended_thinking;
+  if (
+    typeof o.source === "string" &&
+    (CAPABILITY_SOURCES as readonly string[]).includes(o.source)
+  ) {
+    out.source = o.source as CapabilitySource;
+  }
   return out;
 }
 
 /**
  * Per-leg capabilities from host (MODEL_CHAIN_CAPABILITIES JSON array).
- * When missing or invalid, defaults to DEFAULT_CAPABILITIES for each leg.
+ * When missing or invalid, falls back to guessed capabilities marked
+ * `source: "default"` so no unverified limitation is asserted to the model.
  */
 function parseModelChainCapabilitiesFromEnv(
   legCount: number,
-): ModelCapabilities[] {
+): WireModelCapabilities[] {
+  const fallback = (): WireModelCapabilities[] =>
+    Array.from({ length: legCount }, unverifiedCapabilities);
+
   const raw = process.env.MODEL_CHAIN_CAPABILITIES?.trim();
-  if (!raw) {
-    return Array.from({ length: legCount }, () => ({
-      ...DEFAULT_CAPABILITIES,
-    }));
-  }
+  if (!raw) return fallback();
   try {
     const arr = JSON.parse(raw) as unknown;
-    if (!Array.isArray(arr)) {
-      return Array.from({ length: legCount }, () => ({
-        ...DEFAULT_CAPABILITIES,
-      }));
-    }
-    const out: ModelCapabilities[] = [];
+    if (!Array.isArray(arr)) return fallback();
+    const out: WireModelCapabilities[] = [];
     for (let i = 0; i < legCount; i++) {
       out.push(parsePartialCapabilities(arr[i]));
     }
     return out;
   } catch {
-    return Array.from({ length: legCount }, () => ({
-      ...DEFAULT_CAPABILITIES,
-    }));
+    return fallback();
   }
 }
 
@@ -191,33 +205,20 @@ function formatContextTimestamp(ms: number): string {
   });
 }
 
-function hasImageAttachments(
-  attachments: MessageAttachment[] | undefined,
-): boolean {
-  if (!attachments?.length) return false;
-  return attachments.some(
-    (a) =>
-      a.type === "image" ||
-      (a.mimeType?.toLowerCase().startsWith("image/") ?? false),
-  );
-}
-
-function hasAudioAttachments(
-  attachments: MessageAttachment[] | undefined,
-): boolean {
-  if (!attachments?.length) return false;
-  return attachments.some(
-    (a) =>
-      a.type === "audio" ||
-      a.type === "voice" ||
-      (a.mimeType?.toLowerCase().startsWith("audio/") ?? false),
-  );
-}
-
-function buildCapabilitySection(
-  caps: ModelCapabilities,
-  payload: Payload,
-): string {
+/**
+ * Narrates only `tools` — the one capability pi does not track and Mercury can
+ * state as fact, since a `false` can only come from operator config.
+ *
+ * Vision and audio are deliberately absent. pi's `read` tool already emits
+ * "[Current model does not support images...]" at the moment an image is read,
+ * keyed to the model it is actually calling, and stays silent for model ids it
+ * does not recognise. Mercury's up-front version had to guess for unknown ids,
+ * and `DEFAULT_CAPABILITIES` guesses `vision: false` — which told every model
+ * newer than the pinned pi registry that it was blind. The audio flags could
+ * never be anything but `false` from a lookup (pi has no audio models, and
+ * voice notes are transcribed host-side), so they only ever added noise.
+ */
+export function buildCapabilitySection(caps: WireModelCapabilities): string {
   const parts: string[] = ["## Current model capabilities"];
   parts.push(
     `This turn uses a model with the following constraints (do not assume you can exceed them):`,
@@ -225,15 +226,6 @@ function buildCapabilitySection(
   parts.push(
     `- **tools (bash / read / write / edit):** ${caps.tools ? "available" : "NOT available — you cannot run shell commands, read/write workspace files via tools, or use mrctl"}`,
   );
-  parts.push(
-    `- **vision (images):** ${caps.vision ? "available" : "NOT available"}`,
-  );
-  parts.push(
-    `- **audio input:** ${caps.audio_input ? "available" : "NOT available"}`,
-  );
-  parts.push(
-    `- **audio output:** ${caps.audio_output ? "available" : "NOT available"}`,
-  );
 
   if (!caps.tools) {
     parts.push("");
@@ -242,20 +234,6 @@ function buildCapabilitySection(
     );
   }
 
-  if (!caps.vision && hasImageAttachments(payload.attachments)) {
-    parts.push("");
-    parts.push(
-      `**Note:** This model cannot process image pixels. Image files are still listed in <attachments /> with paths — you may reference paths and filenames but cannot interpret visual content.`,
-    );
-  }
-
-  if (!caps.audio_input && hasAudioAttachments(payload.attachments)) {
-    parts.push("");
-    parts.push(
-      `**Note:** This model cannot process audio. Voice attachments are listed with paths only.`,
-    );
-  }
-
   return parts.join("\n");
 }
 
@@ -356,7 +334,7 @@ Your prompt may include \`<active_episodes>\` XML with time-bounded topics relev
     parts.push(claudeCodePreamble);
   }
   parts.push(mercuryPlatform);
-  parts.push(buildCapabilitySection(caps, payload));
+  parts.push(buildCapabilitySection(caps));
   parts.push(memory);
   parts.push(destructiveOps);
   parts.push(toolResultPresentation);
@@ -723,6 +701,18 @@ function buildPrompt(payload: Payload): string {
   return parts.join("\n");
 }
 
+/** Read-only bwrap binds for each resource entry the host mounted into pi's agent dir. */
+function piAgentRoBindArgs(): string[] {
+  const agentDir = "/home/mercury/.pi/agent";
+  if (!existsSync(agentDir)) return [];
+  const args: string[] = [];
+  for (const entry of readdirSync(agentDir)) {
+    const p = `${agentDir}/${entry}`;
+    args.push("--ro-bind", p, p);
+  }
+  return args;
+}
+
 /**
  * Build bwrap args for sandboxing the agent process.
  * Uses bubblewrap for defense-in-depth: Docker isolates from host, bwrap restricts within container.
@@ -762,9 +752,11 @@ function buildBwrapArgs(
     "--bind",
     "/home/mercury",
     "/home/mercury",
-    "--ro-bind",
-    "/home/mercury/.pi/agent",
-    "/home/mercury/.pi/agent",
+    // The host mounts the global resource dir entry by entry (auth.json stays
+    // on the host), so `.pi/agent` is a plain dir holding N read-only submounts
+    // rather than a single one. Re-bind each entry explicitly instead of relying
+    // on a recursive bind of the parent to carry the read-only flag down.
+    ...piAgentRoBindArgs(),
     "--proc",
     "/proc",
     "--dev",
@@ -836,11 +828,14 @@ function invokePiOnce(
       "--mode",
       "json",
       // Skip pi's project-trust store entirely. The store lives in
-      // /home/mercury/.pi/agent (mounted :ro) and even a read locks it via
-      // proper-lockfile (mkdir trust.json.lock → EROFS). Workspaces with
-      // trust-requiring resources already resolved to "untrusted" in
-      // non-interactive mode, and without such resources nothing trust-gated
-      // loads — so --no-approve preserves behavior either way.
+      // /home/mercury/.pi/agent, whose resource entries are read-only bind
+      // mounts, and even a read locks it via proper-lockfile (mkdir
+      // trust.json.lock). Workspaces with trust-requiring resources already
+      // resolved to "untrusted" in non-interactive mode, and without such
+      // resources nothing trust-gated loads — so --no-approve preserves
+      // behavior either way (the agent dir itself is now a Docker-created
+      // mount parent owned by root, so writing the trust file there would fail
+      // with EACCES rather than EROFS — still a failure, still skipped).
       "--no-approve",
       ...sessionArgs,
       "--provider",

package/src/agent/container-runner.ts

@@ -8,7 +8,12 @@ import { mintCallerToken } from "../core/caller-token.js";
 import { scanOutbox } from "../core/outbox.js";
 import type { ExtImageBuildState } from "../extensions/image-builder.js";
 import { type Logger, logger } from "../logger.js";
-import { getPiAuthCredential } from "../storage/pi-auth.js";
+import { ensurePiResourceDir } from "../storage/memory.js";
+import {
+  getPiAuthCredential,
+  hasOAuthEntry,
+  providerCredentialEnvVar,
+} from "../storage/pi-auth.js";
 import type {
   ContainerResult,
   MessageAttachment,
@@ -34,6 +39,60 @@ import { ContainerError } from "./container-error.js";
  */
 const INNER_IO_DIR = "/run/mercury-io";
 
+/** Where pi looks for global agent resources inside the inner container (PI_CODING_AGENT_DIR). */
+const INNER_PI_AGENT_DIR = "/home/mercury/.pi/agent";
+
+/**
+ * Entries of the host global dir that are mounted into `INNER_PI_AGENT_DIR`.
+ * Everything pi loads as a resource — and nothing else. `auth.json` (and the
+ * `.tmp` siblings an interrupted rotation can leave next to it) is deliberately
+ * absent: it carries the OAuth refresh token, and the container only ever needs
+ * the short-lived access token handed to it via ANTHROPIC_OAUTH_TOKEN.
+ *
+ * A superset of what Mercury itself writes (`.pi/`, `AGENTS.md`, `skills/`) —
+ * the remaining entries are pi resource kinds a user may drop in by hand, none
+ * of which can hold a credential.
+ */
+const PI_AGENT_RESOURCE_ENTRIES = [
+  ".pi",
+  "AGENTS.md",
+  "skills",
+  "agents",
+  "commands",
+  "prompts",
+  "extensions",
+] as const;
+
+/**
+ * Docker `-v` args exposing the global dir's resource entries at
+ * `INNER_PI_AGENT_DIR`, one mount per entry rather than one mount of the
+ * directory itself. Binding the directory would carry `auth.json` — and the
+ * `auth.json.<pid>.tmp` siblings an interrupted rotation can leave next to it
+ * (see `writeAuthFile` in storage/pi-auth.ts) — into the least-trusted part of
+ * the system, handing it the long-lived refresh token when all it needs is the
+ * access token injected as ANTHROPIC_OAUTH_TOKEN. The allowlist fails closed:
+ * anything new that lands in the global dir must be opted in here.
+ *
+ * `hostGlobalDir` is the path this process can stat; `innerGlobalDir` is the
+ * path the Docker daemon resolves the bind source against (they differ under
+ * MERCURY_HOST_DATA_DIR). Absent entries are skipped — Docker would otherwise
+ * create the missing source as a directory, turning `AGENTS.md` into a folder.
+ */
+export function buildPiAgentMountArgs(
+  hostGlobalDir: string,
+  innerGlobalDir: string,
+): string[] {
+  const args: string[] = [];
+  for (const entry of PI_AGENT_RESOURCE_ENTRIES) {
+    if (!fs.existsSync(path.join(hostGlobalDir, entry))) continue;
+    args.push(
+      "-v",
+      `${path.join(innerGlobalDir, entry)}:${INNER_PI_AGENT_DIR}/${entry}:ro`,
+    );
+  }
+  return args;
+}
+
 /** Poll interval (ms) while waiting for the inner container's result file. */
 const RESULT_POLL_MS = 150;
 /** Run a `docker inspect` liveness probe every Nth poll (~2s) to fail fast on crash. */
@@ -647,6 +706,62 @@ export class AgentContainerRunner {
       : `mercury-${timestamp}-${id}`;
   }
 
+  /**
+   * Resolve each OAuth provider in the model chain from the host's auth.json
+   * and append its credential to `envPairs` as the env var pi reads it from.
+   *
+   * Only providers pi can be handed a token for are servable: `openai-codex`
+   * has no env var at all (see `providerCredentialEnvVar`), so a codex leg is
+   * dead on arrival and says so in the log rather than failing obscurely inside
+   * the container. Providers already carrying a credential through passthrough
+   * env are left alone — an explicit `MERCURY_*` value outranks the file.
+   *
+   * A leg that cannot be served is logged, not thrown: `MODEL_CHAIN` exists so
+   * a later leg can carry the turn when an earlier one fails, and refusing the
+   * whole spawn over one unusable leg would defeat that. The Anthropic
+   * fail-fast above is unaffected — it guards the primary provider.
+   */
+  private async injectChainOAuthCredentials(
+    envPairs: Array<{ key: string; value: string }>,
+    extraEnv: Record<string, string> | undefined,
+    authPath: string,
+    spaceId: string,
+    // Injected like `OAuthSpawnDeps` above, so a test can exercise the
+    // refresh-failure branch without a token endpoint.
+    resolveCredential: typeof getPiAuthCredential = getPiAuthCredential,
+  ): Promise<void> {
+    const providers = new Set(
+      (this.config.resolvedModelChain ?? []).map((leg) => leg.provider),
+    );
+    for (const provider of providers) {
+      const envVar = providerCredentialEnvVar(provider);
+      if (!envVar) {
+        if (hasOAuthEntry(authPath, provider)) {
+          logger.warn(
+            `Model chain leg "${provider}" has OAuth credentials in ${authPath}, but pi reads no env var for that provider — the credential cannot be passed to the container (auth.json stays on the host). This leg will fail; use a provider with an API key env var, or drop the leg.`,
+            { spaceId, provider },
+          );
+        }
+        continue;
+      }
+
+      const alreadySet =
+        envPairs.some((p) => p.key === envVar && p.value) ||
+        Boolean(extraEnv?.[envVar]);
+      if (alreadySet) continue;
+
+      const credential = await resolveCredential({ provider, authPath });
+      if (credential.status === "ok") {
+        envPairs.push({ key: envVar, value: credential.apiKey });
+      } else if (credential.status === "refresh-failed") {
+        logger.warn(
+          `OAuth refresh failed for model chain leg "${provider}" (${authPath}) — the container starts without that credential. Re-authenticate on the host with mercury auth login.`,
+          { spaceId, provider },
+        );
+      }
+    }
+  }
+
   async reply(input: {
     spaceId: string;
     spaceWorkspace: string;
@@ -664,7 +779,11 @@ export class AgentContainerRunner {
     const globalDir = path.resolve(this.config.globalDir);
     const spacesRoot = path.resolve(this.config.spacesDir);
 
-    fs.mkdirSync(globalDir, { recursive: true });
+    // Resource structure, not a bare mkdir: the global dir is mounted entry by
+    // entry (see PI_AGENT_RESOURCE_ENTRIES), so an empty dir would leave the
+    // container without PI_CODING_AGENT_DIR at all. Idempotent — the same helper
+    // runtime.ts calls at startup.
+    ensurePiResourceDir(globalDir);
     fs.mkdirSync(spacesRoot, { recursive: true });
     try {
       execFileSync("chown", ["-R", "1000:1000", globalDir], { stdio: "pipe" });
@@ -799,6 +918,17 @@ export class AgentContainerRunner {
       }
     }
 
+    // Every other OAuth provider in the resolved chain. The container used to
+    // read auth.json itself (the global dir was mounted wholesale); that file
+    // now stays on the host because it carries refresh tokens, so each leg's
+    // credential must be resolved here and handed over as env instead.
+    await this.injectChainOAuthCredentials(
+      passthroughEnvPairs,
+      input.extraEnv,
+      this.config.authPath ?? path.join(globalDir, "auth.json"),
+      input.spaceId,
+    );
+
     const envPairs = [
       // Internal vars (set by code, not from env)
       { key: "HOME", value: "/home/mercury" },
@@ -807,7 +937,7 @@ export class AgentContainerRunner {
         value:
           "/home/mercury/.local/bin:/home/mercury/.bun/bin:/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin",
       },
-      { key: "PI_CODING_AGENT_DIR", value: "/home/mercury/.pi/agent" },
+      { key: "PI_CODING_AGENT_DIR", value: INNER_PI_AGENT_DIR },
       { key: "CALLER_ID", value: input.callerId },
       { key: "SPACE_ID", value: input.spaceId },
       {
@@ -957,8 +1087,6 @@ export class AgentContainerRunner {
       "-v",
       `${innerSpaceDir}:/spaces/${input.spaceId}`,
       "-v",
-      `${innerGlobalDir}:/home/mercury/.pi/agent:ro`,
-      "-v",
       `${readmePath}:/docs/mercury/README.md:ro`,
       "-v",
       `${docsDir}:/docs/mercury/docs:ro`,
@@ -968,6 +1096,8 @@ export class AgentContainerRunner {
       `IO_DIR=${INNER_IO_DIR}`,
     );
 
+    args.push(...buildPiAgentMountArgs(globalDir, innerGlobalDir));
+
     if (this.config.containerRuntime === "runsc") {
       // Mount the per-agent run dir so the inner container can reach the outer's
       // API unix socket (api-<hostname>.sock, created in main.ts). Mirrors the

package/src/agent/model-capabilities-core.ts

@@ -13,6 +13,22 @@ export type ModelCapabilities = {
 
 export type ModelCapabilityKey = keyof ModelCapabilities;
 
+/**
+ * Where a capability set came from. `"default"` means the model id matched
+ * nothing — the flags below are guesses, not facts, and callers must not
+ * present them to the model as constraints. See `buildCapabilitySection`.
+ */
+export type CapabilitySource = "env" | "yaml" | "builtin" | "default";
+
+/**
+ * Capabilities as serialized to the container over `MODEL_CHAIN_CAPABILITIES`.
+ * `source` rides along so the container can tell a looked-up `false` from an
+ * assumed one.
+ */
+export type WireModelCapabilities = ModelCapabilities & {
+  source?: CapabilitySource;
+};
+
 /** Fallback when no builtin / YAML / env match. */
 export const DEFAULT_CAPABILITIES: ModelCapabilities = {
   tools: true,

package/src/agent/model-capabilities.ts

@@ -9,18 +9,23 @@ import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import type { ModelLeg } from "../config.js";
 import {
+  type CapabilitySource,
   DEFAULT_CAPABILITIES,
   type ModelCapabilities,
   type ModelCapabilityKey,
+  type WireModelCapabilities,
 } from "./model-capabilities-core.js";
 
 export type {
+  CapabilitySource,
   ModelCapabilities,
   ModelCapabilityKey,
+  WireModelCapabilities,
 } from "./model-capabilities-core.js";
 export { DEFAULT_CAPABILITIES } from "./model-capabilities-core.js";
 
-export type CapabilityResolveSource = "env" | "yaml" | "builtin" | "default";
+/** @deprecated Use `CapabilitySource` from model-capabilities-core. */
+export type CapabilityResolveSource = CapabilitySource;
 
 export type ResolvedModelCapabilities = {
   capabilities: ModelCapabilities;
@@ -164,22 +169,40 @@ export function resolveModelChainCapabilities(
   dataDirAbsolute: string,
   envCaps: ModelCapabilities | null,
 ): {
-  chainCaps: ModelCapabilities[];
+  chainCaps: WireModelCapabilities[];
   userMap: UserModelCapabilitiesMap | null;
 } {
   const userMap = loadUserModelCapabilitiesMap(dataDirAbsolute);
-  const chainCaps = chain.map((leg) =>
-    resolveModelCapabilities(leg.model, leg.provider, userMap, envCaps),
-  );
+  const chainCaps = chain.map((leg) => {
+    const { capabilities, source } = resolveModelCapabilitiesWithSource(
+      leg.model,
+      leg.provider,
+      userMap,
+      envCaps,
+    );
+    return { ...capabilities, source };
+  });
   return { chainCaps, userMap };
 }
 
 export function chainSupportsRequirements(
   requires: ModelCapabilityKey[],
-  chainCaps: ModelCapabilities[],
+  chainCaps: WireModelCapabilities[],
 ): boolean {
   if (requires.length === 0) return true;
-  return chainCaps.some((caps) => requires.every((key) => caps[key] === true));
+  // A `false` from an unresolved model id (`source: "default"`) is a guess, not
+  // a fact — `DEFAULT_CAPABILITIES` assumes no vision, so every model newer
+  // than the pinned pi registry looks incapable here. Dropping a
+  // capability-gated extension or skill on that guess removes function from a
+  // model that may well support it, and does so invisibly at startup. Treat
+  // unknown as permissive: let the extension install and fail visibly at use
+  // time instead. This is the last consumer of `source` — the system prompt no
+  // longer narrates vision or audio at all (see `buildCapabilitySection`).
+  const satisfies = (caps: WireModelCapabilities, key: ModelCapabilityKey) =>
+    caps[key] === true || caps.source === "default";
+  return chainCaps.some((caps) =>
+    requires.every((key) => satisfies(caps, key)),
+  );
 }
 
 /** Log warnings for models that fell back to defaults (once per distinct model id). */

package/src/bridges/whatsapp.ts

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { proto, WAMessage } from "@whiskeysockets/baileys";
+import {
+  normalizeMessageContent,
+  type proto,
+  type WAMessage,
+} from "@whiskeysockets/baileys";
 import type { Message } from "chat";
 import type { WhatsAppBaileysAdapter } from "../adapters/whatsapp.js";
 import {
@@ -79,13 +83,14 @@ export class WhatsAppBridge implements PlatformBridge {
       }
 
       if (attachments.length === 0) {
+        const content = normalizeMessageContent(rawMsg.message ?? undefined);
         const contextInfo =
-          rawMsg.message?.extendedTextMessage?.contextInfo ||
-          rawMsg.message?.audioMessage?.contextInfo ||
-          rawMsg.message?.imageMessage?.contextInfo ||
-          rawMsg.message?.videoMessage?.contextInfo ||
-          rawMsg.message?.documentMessage?.contextInfo ||
-          rawMsg.message?.stickerMessage?.contextInfo;
+          content?.extendedTextMessage?.contextInfo ||
+          content?.audioMessage?.contextInfo ||
+          content?.imageMessage?.contextInfo ||
+          content?.videoMessage?.contextInfo ||
+          content?.documentMessage?.contextInfo ||
+          content?.stickerMessage?.contextInfo;
         if (contextInfo?.quotedMessage) {
           if (await ctx.isOverQuota()) {
             logger.warn(

package/src/config.ts

@@ -4,6 +4,7 @@ import {
   type ModelCapabilities,
   parseModelCapabilitiesEnv,
   resolveModelChainCapabilities,
+  type WireModelCapabilities,
 } from "./agent/model-capabilities.js";
 import { mergeRawMercuryConfig } from "./config-file.js";
 import { parseModelLegsArray } from "./config-model-chain.js";
@@ -305,7 +306,7 @@ export type AppConfig = z.infer<typeof schema> & {
   /** Parsed MERCURY_MODEL_CAPABILITIES override, if valid. */
   parsedModelCapabilitiesEnv: ModelCapabilities | null;
   /** Capabilities per chain leg (same order as resolvedModelChain). */
-  resolvedModelChainCapabilities: ModelCapabilities[];
+  resolvedModelChainCapabilities: WireModelCapabilities[];
   /** Effective budget after clamping to container timeout. */
   effectiveModelChainBudgetMs: number;
   /** Parsed `extensionDefaults` JSON: flat "ext.key" → value map. */

package/src/storage/pi-auth.ts

@@ -1,12 +1,48 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
   getOAuthApiKey,
+  getOAuthProvider,
   type OAuthCredentials,
   type OAuthProviderId,
 } from "@earendil-works/pi-ai/oauth";
 import { logger } from "../logger.js";
 
+/**
+ * Env var pi reads a provider's credential from, for the OAuth providers
+ * `mercury auth login` can write to auth.json. Mirrors `getApiKeyEnvVars` in
+ * `@earendil-works/pi-ai/dist/env-api-keys.js` (see its `anthropic` and
+ * `github-copilot` cases) — that mapping is not exported, so it is restated
+ * here rather than reached into.
+ *
+ * `openai-codex` is deliberately absent: pi has no env var for it, so a codex
+ * credential can only travel in auth.json — which Mercury no longer mounts into
+ * the container (it carries the refresh token). A codex leg is unservable.
+ */
+const PROVIDER_CREDENTIAL_ENV_VAR: Record<string, string> = {
+  anthropic: "ANTHROPIC_OAUTH_TOKEN",
+  "github-copilot": "COPILOT_GITHUB_TOKEN",
+};
+
+/**
+ * The env var that carries this provider's credential into the agent container,
+ * or undefined when pi has no env var for it (the credential cannot be passed).
+ */
+export function providerCredentialEnvVar(provider: string): string | undefined {
+  return PROVIDER_CREDENTIAL_ENV_VAR[provider];
+}
+
+/**
+ * Whether auth.json holds an OAuth entry for this provider — asked before
+ * resolving one, so a credential that could never be passed on (no env var for
+ * it) is reported without spending a single-use refresh token to find out.
+ */
+export function hasOAuthEntry(authPath: string, provider: string): boolean {
+  const entry = readAuthFile(path.resolve(authPath))[provider];
+  return Boolean(entry && typeof entry === "object" && entry.type === "oauth");
+}
+
 type AuthEntry =
   | ({ type: "oauth" } & OAuthCredentials)
   | { type: "api_key"; key: string }
@@ -27,10 +63,55 @@ function readAuthFile(authPath: string): AuthFile {
   }
 }
 
+/**
+ * Persist the auth file atomically: write a sibling temp file, then rename over
+ * the target. A torn or partially-written auth.json is unrecoverable — Anthropic
+ * rotates refresh tokens on every refresh, so the copy on disk is the only
+ * record of the current link in the chain.
+ *
+ * The rename is retried because on Windows a concurrent reader holding a handle
+ * makes `renameSync` fail with EPERM/EBUSY; the operation succeeds moments later.
+ */
 function writeAuthFile(authPath: string, auth: AuthFile): void {
   fs.mkdirSync(path.dirname(authPath), { recursive: true });
-  fs.writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf8");
-  fs.chmodSync(authPath, 0o600);
+  const tmpPath = `${authPath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(auth, null, 2), "utf8");
+  try {
+    fs.chmodSync(tmpPath, 0o600);
+  } catch {
+    // chmod is best-effort (no-op on some Windows setups); never fail the
+    // persist over file permissions when a credential is waiting to be saved.
+  }
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      fs.renameSync(tmpPath, authPath);
+      return;
+    } catch (err) {
+      lastError = err;
+      // Busy-wait briefly: this path is rare (~3x/day) and must stay sync so
+      // callers cannot observe a half-persisted credential.
+      const until = Date.now() + 20;
+      while (Date.now() < until) {
+        /* spin */
+      }
+    }
+  }
+  try {
+    fs.rmSync(tmpPath, { force: true });
+  } catch {
+    // Leaving a stray temp file is preferable to masking the rename error.
+  }
+  throw lastError;
+}
+
+/**
+ * Short, non-reversible fingerprint of a secret, safe to log. Used to make token
+ * rotations identifiable after the fact without ever recording the token.
+ */
+function fingerprint(secret: string): string {
+  return crypto.createHash("sha256").update(secret).digest("hex").slice(0, 12);
 }
 
 export type OAuthTokenEnvValue =
@@ -61,6 +142,15 @@ export function parseOAuthTokenEnv(raw: string): OAuthTokenEnvValue {
   return { status: "corrupt-blob" };
 }
 
+/** Whether the environment names an Anthropic credential that can actually be used. */
+function hasAnthropicEnvOverride(): boolean {
+  if (process.env.MERCURY_ANTHROPIC_API_KEY) return true;
+  const raw = process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN;
+  if (!raw) return false;
+  const parsed = parseOAuthTokenEnv(raw);
+  return parsed.status === "token" || parsed.status === "blob";
+}
+
 export type PiAuthCredential =
   | { status: "ok"; apiKey: string }
   /** No usable oauth entry (or an env override takes precedence). */
@@ -76,24 +166,47 @@ export async function getPiAuthCredential(options: {
   provider: string;
   authPath: string;
 }): Promise<PiAuthCredential> {
-  if (
-    process.env.MERCURY_ANTHROPIC_API_KEY ||
-    process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN
-  ) {
+  // Anthropic-only override: a *usable* MERCURY_ANTHROPIC_* value is the
+  // operator naming the credential to use, so the file is not consulted. No
+  // other provider has such a variable — theirs arrive as ordinary passthrough
+  // env, which the caller checks before asking us.
+  //
+  // A corrupt blob is not an override: it names nothing, and treating its mere
+  // presence as one would suppress the file fallback that is the only remaining
+  // way to authenticate.
+  if (options.provider === "anthropic" && hasAnthropicEnvOverride()) {
     return { status: "none" };
   }
 
-  if (options.provider !== "anthropic") {
+  // Only providers pi can refresh an OAuth token for. Anything else in the file
+  // (a hand-written api_key entry, a provider from a newer pi) is not ours to
+  // interpret, and getOAuthApiKey would throw on an unknown id.
+  if (!getOAuthProvider(options.provider)) {
     return { status: "none" };
   }
 
   // Coalesce concurrent refreshes for the same auth file so only one
-  // token-endpoint call is made; the rest share its result.
-  const key = options.authPath;
+  // token-endpoint call is made; the rest share its result. Keyed per provider
+  // as well as per file: one auth.json holds an entry per provider, and a
+  // shared promise would hand a copilot caller the anthropic token.
+  //
+  // The key must be canonical, not the caller's spelling: callers reach this
+  // function with the same file written different ways (a relative
+  // `.mercury/global/auth.json` from an extension, an absolute path from the
+  // container runner). Relative paths already resolve against `process.cwd()`
+  // inside `fs`, so `path.resolve` names the exact same file the raw spelling
+  // would have opened — it only removes the caller's freedom to defeat the
+  // dedupe by spelling. The resolved path is also what gets read, written and
+  // logged, so one file never appears under two names in the logs. (The map is
+  // process-local; coalescing across processes would need a lock file.)
+  const authPath = path.resolve(options.authPath);
+  // "|" is not legal in a Windows path and never appears in a provider id,
+  // so the two halves can never run together into a colliding key.
+  const key = `${authPath}|${options.provider}`;
   const existing = inflightRefresh.get(key);
   if (existing) return existing;
 
-  const promise = doGetPiAuthCredential(options);
+  const promise = doGetPiAuthCredential({ ...options, authPath });
   inflightRefresh.set(key, promise);
   try {
     return await promise;
@@ -107,9 +220,10 @@ async function doGetPiAuthCredential(options: {
   authPath: string;
 }): Promise<PiAuthCredential> {
   const authPath = options.authPath;
+  const provider = options.provider;
   const auth = readAuthFile(authPath);
 
-  const entry = auth.anthropic;
+  const entry = auth[provider];
   if (!entry || typeof entry !== "object" || entry.type !== "oauth") {
     return { status: "none" };
   }
@@ -121,33 +235,23 @@ async function doGetPiAuthCredential(options: {
     return { status: "none" };
   }
 
+  // Step 1 — obtain a usable key. getOAuthApiKey only contacts the token
+  // endpoint when the access token has expired; otherwise it returns the
+  // existing credentials untouched. A throw here means the refresh itself was
+  // rejected, which is a genuine credential failure.
+  let result: Awaited<ReturnType<typeof getOAuthApiKey>>;
   try {
-    const result = await getOAuthApiKey("anthropic" satisfies OAuthProviderId, {
-      anthropic: {
+    result = await getOAuthApiKey(provider as OAuthProviderId, {
+      [provider]: {
+        ...entry,
         access,
         refresh,
         expires,
       },
     });
-
-    if (!result) return { status: "refresh-failed" };
-
-    const nextAuth = {
-      ...auth,
-      anthropic: {
-        type: "oauth" as const,
-        ...result.newCredentials,
-      },
-    };
-
-    writeAuthFile(authPath, nextAuth);
-    logger.debug("Loaded anthropic oauth token from pi auth.json", {
-      authPath,
-    });
-    return { status: "ok", apiKey: result.apiKey };
   } catch (error) {
     logger.warn(
-      `Failed to load anthropic oauth token from pi auth.json at ${authPath}`,
+      `Failed to load ${provider} oauth token from pi auth.json at ${authPath}`,
       error instanceof Error ? error : undefined,
     );
     return {
@@ -155,6 +259,66 @@ async function doGetPiAuthCredential(options: {
       error: error instanceof Error ? error : undefined,
     };
   }
+
+  if (!result) return { status: "refresh-failed" };
+
+  // Step 2 — persist, in its own scope. Providers rotate the refresh token on
+  // every refresh (the old one is consumed server-side), so when a rotation has
+  // happened the value in memory is the ONLY copy of the current chain link.
+  // A failure to save it is therefore unrecoverable — but it is emphatically not
+  // a refresh failure, and must not be reported as one: the key we hold is
+  // valid, and failing the call here would break the chain instead of preserving
+  // the one chance to use and re-save it.
+  const nextCredentials = result.newCredentials;
+  const rotated =
+    typeof nextCredentials.refresh === "string" &&
+    nextCredentials.refresh !== refresh;
+
+  try {
+    // Re-read immediately before merging: another provider's refresh may have
+    // rewritten the file since this call read it, and a stale snapshot would
+    // drop that provider's rotation on the floor.
+    writeAuthFile(authPath, {
+      ...readAuthFile(authPath),
+      [provider]: {
+        type: "oauth" as const,
+        ...nextCredentials,
+      },
+    });
+    if (rotated) {
+      // The single log line that makes a broken chain diagnosable after the
+      // fact: which link was replaced by which, without recording either token.
+      logger.info(`Rotated ${provider} oauth refresh token`, {
+        authPath,
+        previousRefresh: fingerprint(refresh),
+        newRefresh: fingerprint(nextCredentials.refresh as string),
+      });
+    }
+  } catch (error) {
+    if (rotated) {
+      logger.error(
+        `CRITICAL: ${provider} OAuth credential was rotated but could NOT be saved to ${authPath} — the previous refresh token is already consumed server-side, so this space will fail to authenticate once the current access token expires. Re-run mercury auth login from the project directory that owns this file.`,
+        {
+          authPath,
+          previousRefresh: fingerprint(refresh),
+          unsavedRefresh: fingerprint(nextCredentials.refresh as string),
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+    } else {
+      // No rotation occurred, so the on-disk copy is still current and nothing
+      // was lost — the rewrite was a no-op carrying identical content.
+      logger.warn(
+        `Could not rewrite pi auth.json at ${authPath} (no rotation occurred, stored credential is unchanged)`,
+        error instanceof Error ? error : undefined,
+      );
+    }
+  }
+
+  logger.debug(`Loaded ${provider} oauth token from pi auth.json`, {
+    authPath,
+  });
+  return { status: "ok", apiKey: result.apiKey };
 }
 
 /** Back-compat wrapper: returns the key on success, undefined otherwise. */