mercury-agent 0.8.9 → 0.8.10

package/docs/configuration.md

@@ -41,6 +41,30 @@ Per-space overrides via `mrctl config set context.<key> <value>` always win over
 
 You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
 
+## Container env passthrough (`agent.env_passthrough`)
+
+Controls which host `MERCURY_*` variables reach agent containers:
+
+```yaml
+agent:
+  env_passthrough: all       # all (default) | claimed
+```
+
+- **`all`** — every `MERCURY_*` var except a fixed blocklist is passed into the container with the prefix stripped (`MERCURY_BRAVE_API_KEY` → `BRAVE_API_KEY`). Convenient, but blunt: a secret added to `.env` for one purpose reaches **every space's container**, regardless of who triggered the turn or whether that space has anything to do with it.
+- **`claimed`** — only variables an extension declared via `mercury.env()` are passed, and only when the triggering caller holds that extension's permission. Undeclared variables stay on the host.
+
+**Model-provider credentials are exempt** and pass in both modes (`MERCURY_ANTHROPIC_API_KEY`, `MERCURY_ANTHROPIC_OAUTH_TOKEN`, `MERCURY_GEMINI_API_KEY`, `MERCURY_GROQ_API_KEY`, and the rest of the provider list). pi reads them inside the container, and no extension declares them — without the exemption, `claimed` would leave the agent unable to reach any model. They remain subject to the blocklist.
+
+Env: `MERCURY_CONTAINER_ENV_PASSTHROUGH`.
+
+`claimed` is opt-in because it breaks setups that rely on blind passthrough for anything other than provider keys — API keys consumed by skills (search, TTS, scrapers) and any credential you added by hand. To migrate, declare those in an extension (see [extensions.md](extensions.md)) before switching. At startup with `all`, Mercury logs the vars it is passing that are neither declared nor provider credentials — names only, so a genuine outlier stands out:
+
+```
+Container env passthrough: all — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_BRAVE_API_KEY, MERCURY_BILLING_API_KEY
+```
+
+For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result.
+
 ## Extension config defaults (`extensions:`)
 
 Deployment-wide defaults for extension config keys, applied to **every space** (including auto-created DM spaces) at read time:

package/package.json

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

package/resources/templates/mercury.example.yaml

@@ -62,6 +62,10 @@
 #   image: ghcr.io/avishai-tsabari/mercury-agent:latest
 #   container_timeout_ms: 300000
 #   container_bwrap_docker_compat: false
+#   # Which MERCURY_* vars reach containers. "all" (default) passes every
+#   # non-blocked var into every space's container; "claimed" passes only
+#   # extension-declared vars, gated by the caller's permission.
+#   env_passthrough: all
 
 # discord:
 #   gateway_duration_ms: 600000

package/src/agent/container-env.ts

@@ -0,0 +1,137 @@
+/**
+ * Which host environment variables reach agent containers.
+ *
+ * Mercury passes `MERCURY_*` vars into containers with the prefix stripped.
+ * That is convenient but blunt: a secret added to `.env` for one purpose is
+ * exposed to every space's container, whoever triggered the turn. Vars an
+ * extension declares via `mercury.env()` avoid this — they are injected in
+ * runtime.ts behind the extension's permission gate instead.
+ *
+ * `containerEnvPassthrough: "claimed"` narrows the blunt path to nothing, so
+ * declared vars are the only way in.
+ */
+
+/** Vars that must never reach a container, regardless of passthrough mode. */
+export const BLOCKED_ENV_VARS = new Set([
+  "MERCURY_API_SECRET",
+  // Host-only: signs per-turn caller tokens. Injecting it would let the
+  // agent forge a token for any caller, defeating the whole mechanism.
+  "MERCURY_CALLER_TOKEN_KEY",
+  // Host-only: the inner→outer API socket path is set by code per spawn;
+  // never let an agent override which socket mrctl targets.
+  "MERCURY_API_SOCKET",
+  "MERCURY_CHAT_API_KEY",
+  "MERCURY_ADMINS",
+  // Host-only: affects `docker run` flags, not the agent process inside the container
+  "MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT",
+  // Host-only: selects the OCI runtime for `docker run --runtime`; not meaningful inside the container
+  "MERCURY_CONTAINER_RUNTIME",
+  // Host-only: resolved volume mountpoint on the host; inner containers don't need it
+  "MERCURY_HOST_DATA_DIR",
+  "MERCURY_SLACK_BOT_TOKEN",
+  "MERCURY_SLACK_SIGNING_SECRET",
+  "MERCURY_DISCORD_BOT_TOKEN",
+  "MERCURY_DISCORD_GATEWAY_SECRET",
+  "MERCURY_TELEGRAM_BOT_TOKEN",
+  "MERCURY_TELEGRAM_WEBHOOK_SECRET_TOKEN",
+  "MERCURY_TEAMS_APP_ID",
+  "MERCURY_TEAMS_APP_PASSWORD",
+  "MERCURY_WHATSAPP_AUTH_DIR",
+]);
+
+/**
+ * Model-provider credentials. pi reads these inside the container, so they are
+ * runtime plumbing rather than user secrets — and no extension declares them,
+ * which means "claimed" mode would otherwise leave the agent with no way to
+ * reach a model at all. Exempt from the claimed filter for that reason; still
+ * subject to BLOCKED_ENV_VARS.
+ *
+ * Mirrors the provider list in core/routes/dashboard.ts (drift is covered by a
+ * test), plus MERCURY_ANTHROPIC_OAUTH_TOKEN, which console provisioning sets
+ * instead of an API key.
+ */
+export const MODEL_PROVIDER_ENV_VARS = new Set([
+  "MERCURY_AI_GATEWAY_API_KEY",
+  "MERCURY_ANTHROPIC_API_KEY",
+  "MERCURY_ANTHROPIC_OAUTH_TOKEN",
+  "MERCURY_AWS_BEARER_TOKEN_BEDROCK",
+  "MERCURY_AZURE_OPENAI_API_KEY",
+  "MERCURY_CEREBRAS_API_KEY",
+  "MERCURY_DEEPSEEK_API_KEY",
+  "MERCURY_GEMINI_API_KEY",
+  "MERCURY_GITHUB_COPILOT_OAUTH_TOKEN",
+  "MERCURY_GOOGLE_CLOUD_API_KEY",
+  "MERCURY_GROQ_API_KEY",
+  "MERCURY_HF_TOKEN",
+  "MERCURY_KIMI_API_KEY",
+  "MERCURY_MINIMAX_API_KEY",
+  "MERCURY_MINIMAX_CN_API_KEY",
+  "MERCURY_MISTRAL_API_KEY",
+  "MERCURY_OPENAI_API_KEY",
+  "MERCURY_OPENROUTER_API_KEY",
+  "MERCURY_XAI_API_KEY",
+  "MERCURY_ZAI_API_KEY",
+]);
+
+export type EnvPassthroughMode = "all" | "claimed";
+
+/**
+ * Host `MERCURY_*` var names that are neither blocked nor claimed by an
+ * extension — the ones the blind passthrough carries into every container.
+ *
+ * Sorted, and names only: callers log these, and the values are the secrets.
+ */
+export function listUnclaimedPassthroughVars(
+  env: NodeJS.ProcessEnv,
+  claimed: Set<string> | undefined,
+): string[] {
+  return Object.keys(env)
+    .filter(
+      (key) =>
+        key.startsWith("MERCURY_") &&
+        env[key] !== undefined &&
+        !BLOCKED_ENV_VARS.has(key) &&
+        !claimed?.has(key),
+    )
+    .sort();
+}
+
+/**
+ * Undeclared vars that are not model-provider plumbing — the ones worth
+ * surfacing at startup. Provider keys are expected to be here and would only
+ * add noise; a var in this list is one nobody scoped to anything.
+ */
+export function listUnexpectedPassthroughVars(
+  env: NodeJS.ProcessEnv,
+  claimed: Set<string> | undefined,
+): string[] {
+  return listUnclaimedPassthroughVars(env, claimed).filter(
+    (key) => !MODEL_PROVIDER_ENV_VARS.has(key),
+  );
+}
+
+/**
+ * The blind-passthrough pairs for a container spawn, with `MERCURY_` stripped.
+ *
+ * Extension-declared vars are excluded here on purpose — runtime.ts injects
+ * those separately, behind the permission check. In "claimed" mode only
+ * model-provider credentials pass, so the agent can still reach a model.
+ */
+export function selectPassthroughEnv(
+  env: NodeJS.ProcessEnv,
+  claimed: Set<string> | undefined,
+  mode: EnvPassthroughMode,
+): Array<{ key: string; value: string }> {
+  const names =
+    mode === "claimed"
+      ? listUnclaimedPassthroughVars(env, claimed).filter((key) =>
+          MODEL_PROVIDER_ENV_VARS.has(key),
+        )
+      : listUnclaimedPassthroughVars(env, claimed);
+
+  return names.map((key) => ({
+    key: key.replace("MERCURY_", ""),
+    // listUnclaimedPassthroughVars already filtered out undefined values.
+    value: env[key] as string,
+  }));
+}

package/src/agent/container-runner.ts

@@ -20,6 +20,7 @@ import {
   INNER_RUN_DIR,
   innerApiSocketPath,
 } from "./api-socket.js";
+import { selectPassthroughEnv } from "./container-env.js";
 import { ContainerError } from "./container-error.js";
 
 /**
@@ -677,48 +678,15 @@ export class AgentContainerRunner {
       );
     }
 
-    // Env vars that should never be passed to containers
-    const BLOCKED_ENV_VARS = new Set([
-      "MERCURY_API_SECRET",
-      // Host-only: signs per-turn caller tokens. Injecting it would let the
-      // agent forge a token for any caller, defeating the whole mechanism.
-      "MERCURY_CALLER_TOKEN_KEY",
-      // Host-only: the inner→outer API socket path is set by code per spawn;
-      // never let an agent override which socket mrctl targets.
-      "MERCURY_API_SOCKET",
-      "MERCURY_CHAT_API_KEY",
-      "MERCURY_ADMINS",
-      // Host-only: affects `docker run` flags, not the agent process inside the container
-      "MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT",
-      // Host-only: selects the OCI runtime for `docker run --runtime`; not meaningful inside the container
-      "MERCURY_CONTAINER_RUNTIME",
-      // Host-only: resolved volume mountpoint on the host; inner containers don't need it
-      "MERCURY_HOST_DATA_DIR",
-      "MERCURY_SLACK_BOT_TOKEN",
-      "MERCURY_SLACK_SIGNING_SECRET",
-      "MERCURY_DISCORD_BOT_TOKEN",
-      "MERCURY_DISCORD_GATEWAY_SECRET",
-      "MERCURY_TELEGRAM_BOT_TOKEN",
-      "MERCURY_TELEGRAM_WEBHOOK_SECRET_TOKEN",
-      "MERCURY_TEAMS_APP_ID",
-      "MERCURY_TEAMS_APP_PASSWORD",
-      "MERCURY_WHATSAPP_AUTH_DIR",
-    ]);
-
-    // Pass MERCURY_* vars to container with prefix stripped, excluding blocked vars
-    const claimed = input.claimedEnvSources;
-    const passthroughEnvPairs = Object.entries(process.env)
-      .filter(
-        (entry): entry is [string, string] =>
-          entry[0].startsWith("MERCURY_") &&
-          entry[1] !== undefined &&
-          !BLOCKED_ENV_VARS.has(entry[0]) &&
-          !claimed?.has(entry[0]),
-      )
-      .map(([key, value]) => ({
-        key: key.replace("MERCURY_", ""),
-        value: value,
-      }));
+    // Pass MERCURY_* vars to container with prefix stripped, excluding blocked
+    // and extension-claimed vars. In "claimed" mode this yields nothing and
+    // extension-declared vars (injected in runtime.ts behind the permission
+    // check) are the only way a secret reaches a container.
+    const passthroughEnvPairs = selectPassthroughEnv(
+      process.env,
+      input.claimedEnvSources,
+      this.config.containerEnvPassthrough,
+    );
 
     // Legacy path: older console versions stored the OAuth credential blob in
     // MERCURY_ANTHROPIC_API_KEY instead of MERCURY_ANTHROPIC_OAUTH_TOKEN.

package/src/config-file.ts

@@ -127,6 +127,7 @@ const mercuryFileSchema = z
           .optional(),
         container_bwrap_docker_compat: z.boolean().optional(),
         override_pi_system_prompt: z.boolean().optional(),
+        env_passthrough: z.enum(["all", "claimed"]).optional(),
       })
       .strip()
       .optional(),
@@ -247,6 +248,7 @@ const KNOWN_SECTION_KEYS: Record<string, Set<string>> = {
     "container_timeout_ms",
     "container_bwrap_docker_compat",
     "override_pi_system_prompt",
+    "env_passthrough",
   ]),
   discord: new Set(["gateway_duration_ms"]),
   telegram: new Set(["format_enabled"]),
@@ -388,6 +390,9 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
   if (f.agent?.override_pi_system_prompt != null) {
     o.overridePiSystemPrompt = f.agent.override_pi_system_prompt;
   }
+  if (f.agent?.env_passthrough != null) {
+    o.containerEnvPassthrough = f.agent.env_passthrough;
+  }
 
   if (f.discord?.gateway_duration_ms != null) {
     o.discordGatewayDurationMs = f.discord.gateway_duration_ms;
@@ -461,6 +466,7 @@ const CAMEL_TO_ENV: Record<string, string> = {
   containerNetwork: "MERCURY_CONTAINER_NETWORK",
   containerApiHost: "MERCURY_CONTAINER_API_HOST",
   containerBwrapDockerCompat: "MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT",
+  containerEnvPassthrough: "MERCURY_CONTAINER_ENV_PASSTHROUGH",
   overridePiSystemPrompt: "MERCURY_OVERRIDE_PI_SYSTEM_PROMPT",
   maxConcurrency: "MERCURY_MAX_CONCURRENCY",
   rateLimitPerUser: "MERCURY_RATE_LIMIT_PER_USER",

package/src/config.ts

@@ -133,6 +133,19 @@ const schema = z.object({
    *   Requires gVisor installed on the compute node (auto-installed by cloud-init on provisioned nodes).
    */
   containerRuntime: z.enum(["runc", "runsc"]).default("runc"),
+  /**
+   * Which MERCURY_* env vars reach agent containers.
+   * - "all" (default): every MERCURY_* var except the blocklist is passed with
+   *   the prefix stripped. Convenient, but a secret added to .env is exposed to
+   *   every space's container regardless of who triggered the turn.
+   * - "claimed": only vars an extension declared via `mercury.env()` are passed,
+   *   and only when the caller holds that extension's permission. Undeclared
+   *   vars stay on the host.
+   *
+   * "claimed" is opt-in because it breaks setups that rely on blind passthrough;
+   * declare the vars you need in an extension before switching.
+   */
+  containerEnvPassthrough: z.enum(["all", "claimed"]).default("all"),
   /**
    * @deprecated Use MERCURY_CONTAINER_RUNTIME=runsc instead.
    * When true, `docker run` uses looser outer sandbox so bubblewrap can nest (e.g. Docker Desktop).

package/src/main.ts

@@ -22,6 +22,7 @@ import {
   apiSocketPath,
   sweepOrphanApiSockets,
 } from "./agent/api-socket.js";
+import { listUnexpectedPassthroughVars } from "./agent/container-env.js";
 import {
   logExtensionCapabilityMismatches,
   logUnknownModelCapabilityWarnings,
@@ -617,6 +618,27 @@ async function main() {
   if (adapters.telegram) {
     logger.info("Telegram enabled (webhook or polling)");
   }
+
+  // Inventory of what the blind passthrough carries. Names only — the values
+  // are the secrets. Logged once per start, not per container: the point is
+  // that an unnoticed entry here (a password added to .env for one space) is
+  // reaching every space's container, whoever triggered the turn.
+  if (config.containerEnvPassthrough === "claimed") {
+    logger.info(
+      "Container env passthrough: claimed — only extension-declared vars and model-provider credentials reach containers",
+    );
+  } else {
+    const unexpected = listUnexpectedPassthroughVars(
+      process.env,
+      registry.getClaimedEnvSources(),
+    );
+    if (unexpected.length > 0) {
+      logger.info(
+        "Container env passthrough: all — these vars reach every space's container and are scoped to nothing. Declare them in an extension, or set agent.env_passthrough=claimed.",
+        { vars: unexpected.join(", ") },
+      );
+    }
+  }
 }
 
 main().catch((error) => {