mercury-agent 0.8.11 → 0.9.0

package/docs/authoring-profiles.md

@@ -136,6 +136,14 @@ the extension's `SKILL.md` or the profile's `AGENTS.md`.
 - **`member_permissions` is exhaustive.** List every permission a member may
   hold, including the capability name (e.g. `rooms`). Anything not listed —
   including raw capabilities like `gws` — is unavailable to members.
+  One back-compat exception: a list that mentions neither `media.receive` nor
+  `media.send` gets both appended at load time (media exchange predates these
+  permissions, so their absence carries no revocation intent). To restrict
+  media for members, list at least one of them explicitly — a list mentioning
+  either is taken verbatim. `media.purge` does not count as an opt-out.
+  Known limitation: denying *both* media permissions cannot be expressed in a
+  profile list (mentioning one grants it; mentioning neither appends both) —
+  use a per-space override (`mrctl permissions set member …`) for a full deny.
 - **Authorization = permission named after the capability.** The broker route
   requires the caller to hold the `<name>` permission; the same grant gates both
   the `mrctl capability <name> …` CLI and the route. Keep capability name =

package/docs/media/overview.md

@@ -48,6 +48,15 @@ interface MessageAttachment {
 | `MERCURY_MEDIA_ENABLED` | `true` | Enable/disable media downloads |
 | `MERCURY_MEDIA_MAX_SIZE_MB` | `10` | Max file size to download (MB) |
 
+## Permission Gating
+
+The pipeline is gated per caller role, per space by two built-in permissions (both granted to `member` by default — see [permissions.md](../permissions.md)):
+
+- **`media.receive`** — when the caller's role lacks it, incoming files are deleted from `inbox/` before the container runs and dropped from the stored message. The message text still goes through, and the agent receives a system note that files arrived but were blocked. Covers all media types including voice notes (revoking it disables voice transcription for that role).
+- **`media.send`** — when the caller's role lacks it, files produced during that caller's turn are not delivered; the reply carries a one-line notice. The files stay in `outbox/` (TTL cleanup applies).
+
+`admin` and `system` callers (scheduled tasks) are exempt. Gating is per-caller-turn: in a shared group, a blocked member's turns are gated while an admin's turns deliver files normally. Bridges still download media before routing — the write is transient; the gate deletes it before the message is saved or any agent code runs.
+
 ## Storage
 
 ### Ingress (inbox/)

package/docs/permissions.md

@@ -28,7 +28,7 @@ Message arrives
 |------|---------------------|-------------|
 | `system` | All | Internal system caller (scheduler, etc.) — not assignable |
 | `admin` | All | Full control over the space |
-| `member` | `prompt`, `prefs.get` | Can chat and read space preferences (default for new users) |
+| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send` | Can chat, read space preferences, and exchange files (default for new users) |
 
 Custom roles can be created by assigning permissions to any role name.
 
@@ -56,6 +56,19 @@ Custom roles can be created by assigning permissions to any role name.
 | `spaces.list` | View all spaces |
 | `spaces.rename` | Rename a space and link/unlink conversations |
 | `spaces.delete` | Delete current space and all related DB data |
+| `media.receive` | Incoming attachments are saved to `inbox/` and shown to the agent |
+| `media.send` | Outbox files produced on this caller's turn are delivered back to the chat |
+
+### Media permissions
+
+`media.receive` and `media.send` gate the media pipeline per caller role, per space. Both are granted to `member` by default, so behavior is unchanged unless an operator revokes them (e.g. `mrctl permissions set member prompt,prefs.get` — omitting the media names revokes them in that space).
+
+Denials are never silent:
+
+- **Blocked receive** — the caller's inbox files are deleted from disk before the container runs and dropped from the stored message; the message text still goes through, and the agent is told via a system note that files arrived but were blocked. `media.receive` covers all media types, including voice notes — revoking it also disables voice-message transcription for that role.
+- **Blocked send** — files produced during that caller's turn are not delivered; the reply carries a one-line notice. The files remain in `outbox/` for admin retrieval until TTL cleanup removes them.
+
+`admin` and `system` callers (scheduled tasks) are always exempt — the gates never fire for them. Lists that predate these permissions (profile manifests, stored per-space overrides, operator `defaultMemberPermissions` configs) get both names appended automatically for backwards compatibility; a list that mentions either name is taken verbatim (`media.purge` predates the pair and does not count as an opt-out).
 
 ## Mutes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.8.11",
+  "version": "0.9.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -93,7 +93,7 @@
     "commander": "^14.0.3",
     "cron-parser": "^5.5.0",
     "discord.js": "^14.26.3",
-    "hono": "^4.12.25",
+    "hono": "^4.12.34",
     "qrcode-terminal": "^0.12.0",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"

package/resources/templates/mercury.example.yaml

@@ -87,6 +87,13 @@
 #   default_system_prompt: ""                   # seeded into auto-created user spaces
 #   default_member_permissions: "prompt,prefs.get"  # restrict users to chat only
 
+# ─── System messages ────────────────────────────────────────────────────────
+# Deployment-wide default language for Mercury-generated system messages
+# (rate-limit denials, error messages, permission denials). Overridable
+# per-space from the dashboard or chat: mrctl config set messages.locale he
+# messages:
+#   locale: en                    # en | he
+
 # ─── Extension config defaults ──────────────────────────────────────────────
 # Deployment-wide defaults for extension config keys, applied to every space
 # (incl. auto-created DM spaces) unless overridden per-space or in the

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);

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/agent/user-error-messages.ts

@@ -1,3 +1,8 @@
+import {
+  formatSystemMessage,
+  type MessageLocale,
+} from "../core/system-messages.js";
+
 export type UserErrorCategory =
   | "auth"
   | "key-limit"
@@ -28,50 +33,19 @@ export function classifyUserError(errorText: string): UserErrorCategory {
   return "generic";
 }
 
-const MESSAGES: Record<UserErrorCategory, { platform: string; byok: string }> =
-  {
-    "key-limit": {
-      platform: "I've reached my usage limit for now. Please try again later.",
-      byok: "Your API key has hit its spending limit. Check your provider's key settings to increase it.",
-    },
-    "rate-limit": {
-      platform:
-        "I'm handling too many requests right now — please try again in a moment.",
-      byok: "Your API key is being rate-limited. Try again in a moment.",
-    },
-    auth: {
-      platform:
-        "Something went wrong on my end. This has been logged and the admin will be notified.",
-      byok: "Your API key appears to be invalid or expired. Please update it.",
-    },
-    credits: {
-      platform: "I've reached my usage limit for now. Please try again later.",
-      byok: "Your API provider account has insufficient credits. Add credits to continue.",
-    },
-    "server-error": {
-      platform:
-        "The AI service is temporarily unavailable. Please try again in a few minutes.",
-      byok: "The AI service is temporarily unavailable. Please try again in a few minutes.",
-    },
-    generic: {
-      platform:
-        "Something went wrong processing your request. Please try again.",
-      byok: "Something went wrong processing your request. Please try again, or check your API key and provider status.",
-    },
-  };
-
 export function friendlyErrorMessage(
   category: UserErrorCategory,
   mode: "platform" | "byok",
   consoleUrl?: string,
+  locale: MessageLocale = "en",
 ): string {
-  let message = MESSAGES[category][mode];
+  let message = formatSystemMessage(locale, `err_${category}_${mode}`);
   const base = consoleUrl?.replace(/\/+$/, "");
   if (base && mode === "platform") {
     if (category === "key-limit" || category === "credits") {
-      message += `\n\nUpgrade your plan: ${base}/dashboard/billing`;
+      message += `\n\n${formatSystemMessage(locale, "err_upgrade_suffix", { url: base })}`;
     } else if (category === "auth") {
-      return `Your Anthropic session has expired. Please reconnect: ${base}/dashboard/model`;
+      return formatSystemMessage(locale, "err_session_expired", { url: base });
     }
   }
   return message;

package/src/config-file.ts

@@ -166,6 +166,13 @@ const mercuryFileSchema = z
       .strip()
       .optional(),
 
+    messages: z
+      .object({
+        locale: z.enum(["en", "he"]).optional(),
+      })
+      .strip()
+      .optional(),
+
     dm_auto_space: z
       .object({
         enabled: z.boolean().optional(),
@@ -211,6 +218,7 @@ const KNOWN_TOP_KEYS = new Set([
   "telegram",
   "media",
   "permissions",
+  "messages",
   "dm_auto_space",
   "extensions",
 ]);
@@ -254,6 +262,7 @@ const KNOWN_SECTION_KEYS: Record<string, Set<string>> = {
   telegram: new Set(["format_enabled"]),
   media: new Set(["enabled", "max_size_mb"]),
   permissions: new Set(["admins"]),
+  messages: new Set(["locale"]),
   dm_auto_space: new Set([
     "enabled",
     "admin_ids",
@@ -407,6 +416,8 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
 
   if (f.permissions?.admins != null) o.admins = f.permissions.admins;
 
+  if (f.messages?.locale != null) o.messagesLocale = f.messages.locale;
+
   if (f.dm_auto_space?.enabled != null) {
     o.dmAutoSpaceEnabled = f.dm_auto_space.enabled;
   }
@@ -484,6 +495,7 @@ const CAMEL_TO_ENV: Record<string, string> = {
   mediaEnabled: "MERCURY_MEDIA_ENABLED",
   mediaMaxSizeMb: "MERCURY_MEDIA_MAX_SIZE_MB",
   admins: "MERCURY_ADMINS",
+  messagesLocale: "MERCURY_MESSAGES_LOCALE",
   profile: "MERCURY_PROFILE",
   apiSecret: "MERCURY_API_SECRET",
   callerTokenKey: "MERCURY_CALLER_TOKEN_KEY",

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";
@@ -220,6 +221,14 @@ const schema = z.object({
   // ─── Permissions ────────────────────────────────────────────────────
   admins: z.string().default(""),
 
+  // ─── System Messages ────────────────────────────────────────────────
+  /**
+   * Deployment-wide default locale for host-generated system messages
+   * (rate-limit denials, error messages, permission denials). Overridable
+   * per-space via the `messages.locale` space config key. Env: MERCURY_MESSAGES_LOCALE.
+   */
+  messagesLocale: z.enum(["en", "he"]).default("en"),
+
   // ─── Applicative Profile ────────────────────────────────────────────
   /**
    * Name of the active applicative profile (informational at runtime; the
@@ -305,7 +314,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/core/conversation.ts

@@ -1,6 +1,7 @@
 import { logger } from "../logger.js";
 import type { Db } from "../storage/db.js";
 import type { Conversation } from "../types.js";
+import { withMediaBackCompat } from "./permissions.js";
 
 export interface ConversationResolution {
   conversation: Conversation;
@@ -159,11 +160,17 @@ export function resolveConversation(
   seedSpaceConfigIfAbsent(db, spaceId, "context.mode", "context");
   seedSpaceConfigIfAbsent(db, spaceId, "debounce.idle_timeout_ms", "2000");
   if (autoSpace.defaultMemberPermissions) {
+    // Seed-time back-compat: an operator config authored before the media
+    // permissions existed must not deny media in newly auto-created spaces
+    // while migrated older spaces allow it. A list mentioning either media
+    // transfer name is an explicit choice and is seeded verbatim.
     seedSpaceConfigIfAbsent(
       db,
       spaceId,
       "role.member.permissions",
-      autoSpace.defaultMemberPermissions,
+      withMediaBackCompat(
+        autoSpace.defaultMemberPermissions.split(",").map((s) => s.trim()),
+      ).join(","),
     );
   }
   if (autoSpace.defaultSystemPrompt) {

package/src/core/media-gate.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../logger.js";
+import type { EgressFile, MessageAttachment } from "../types.js";
+
+/**
+ * Enforcement helpers for the `media.receive` / `media.send` permissions.
+ *
+ * Pure with respect to permission resolution: callers decide whether the
+ * caller's role holds the permission and only invoke these on denial. Denials
+ * are never silent — the receive gate tells the agent via a prompt note, the
+ * send gate tells the user via a reply notice, and both log at WARN.
+ */
+
+export interface IncomingMediaGateResult {
+  /** Attachments to persist/prompt with — undefined when blocked. */
+  attachments: MessageAttachment[] | undefined;
+  /** System note to append to the agent prompt, or null when nothing was blocked. */
+  promptNote: string | null;
+}
+
+/**
+ * Apply a `media.receive` denial: delete the caller's inbox files from disk
+ * (before the container mounts the workspace) and drop the attachments from
+ * the message.
+ *
+ * Deletion is workspace-scoped: only paths resolving inside
+ * `<workspacePath>/inbox/` are deleted; anything else is logged and skipped.
+ * FS errors are logged and the attachment is still dropped — the inbox TTL
+ * cleanup is the backstop.
+ */
+export function gateIncomingMedia(opts: {
+  workspacePath: string;
+  spaceId: string;
+  callerRole: string;
+  attachments: MessageAttachment[] | undefined;
+  hadIncomingAttachments: boolean;
+}): IncomingMediaGateResult {
+  const { workspacePath, spaceId, callerRole, attachments } = opts;
+  const count = attachments?.length ?? 0;
+
+  if (count === 0 && !opts.hadIncomingAttachments) {
+    return { attachments, promptNote: null };
+  }
+
+  const inboxRoot = path.resolve(workspacePath, "inbox");
+  for (const att of attachments ?? []) {
+    const resolved = path.resolve(workspacePath, att.path);
+    // Strictly inside inbox/ — the inbox root itself is never a deletion target.
+    if (!resolved.startsWith(inboxRoot + path.sep)) {
+      logger.warn(
+        "media.receive gate: attachment path outside workspace inbox, not deleting",
+        { spaceId, path: att.path },
+      );
+      continue;
+    }
+    try {
+      fs.rmSync(resolved, { force: true });
+    } catch (error) {
+      logger.warn("media.receive gate: failed to delete inbox file", {
+        spaceId,
+        path: att.path,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  logger.warn("Blocked incoming media (role lacks media.receive)", {
+    spaceId,
+    callerRole,
+    count,
+  });
+
+  // count === 0 means the platform reported attachments but nothing was
+  // persisted upstream (media disabled, size limit, download failure) — don't
+  // attribute that solely to the permission.
+  const promptNote =
+    count > 0
+      ? `[system] The user sent ${count} ${count === 1 ? "file" : "files"} with this message, but file receiving is disabled ` +
+        `for their role, so the ${count === 1 ? "file was" : "files were"} not kept and cannot be read. ` +
+        `If relevant, let the user know that sending files is not available to them.`
+      : `[system] The user attempted to send one or more files with this message, but they were not received ` +
+        `(file receiving is disabled for their role, or the files could not be downloaded). ` +
+        `If relevant, let the user know that sending files is not available to them.`;
+  return { attachments: undefined, promptNote };
+}
+
+export interface OutgoingMediaGateResult {
+  /** Files to deliver — empty when blocked. */
+  files: EgressFile[];
+  /** Reply text, with a withhold notice appended when files were blocked. */
+  reply: string;
+}
+
+/**
+ * Apply a `media.send` denial: withhold this turn's outbox files and append a
+ * one-line notice to the reply. Files stay in `outbox/` for admin retrieval;
+ * the outbox TTL cleanup removes them later.
+ */
+export function gateOutgoingMedia(opts: {
+  spaceId: string;
+  callerRole: string;
+  files: EgressFile[];
+  reply: string;
+}): OutgoingMediaGateResult {
+  const { spaceId, callerRole, files, reply } = opts;
+  if (files.length === 0) return { files, reply };
+
+  logger.warn("Withheld outgoing media (role lacks media.send)", {
+    spaceId,
+    callerRole,
+    count: files.length,
+  });
+
+  const noun = files.length === 1 ? "file was" : "files were";
+  const notice = `(${files.length} generated ${noun} not delivered because file delivery is disabled for your role.)`;
+  return {
+    files: [],
+    reply: reply ? `${reply}\n\n${notice}` : notice,
+  };
+}