@xmanrui/dsh-im 4.2.1 → 4.4.0

package/src/channels/shared/bot-workspace-store.mjs

@@ -13,6 +13,10 @@ import {
   normalizeAgentPresetCatalog,
   validateAgentPresetId,
 } from './agent-preset.mjs';
+import {
+  normalizeAccessPolicy,
+  validateAccessPolicy,
+} from './access-policy.mjs';
 import { CONNECTION_TEST_STATE_IDENTITY } from './connection-test.mjs';
 import {
   DEFAULT_CONTEXT_ENHANCEMENT_CONFIG,
@@ -131,6 +135,26 @@ function normalizeDeliveryTargets(value) {
   return deliveryTargets;
 }
 
+function normalizeAccessPolicies(value, workspaces) {
+  const accessPolicies = Object.create(null);
+  if (value === undefined) return accessPolicies;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    // Preserve the distinction between a missing policy (eligible for startup
+    // initialization) and damaged persisted data (fail closed).
+    for (const botId of Object.keys(workspaces)) accessPolicies[botId] = null;
+    return accessPolicies;
+  }
+  for (const [botId, policy] of Object.entries(value)) {
+    try {
+      botIdOf(botId);
+      accessPolicies[botId] = normalizeAccessPolicy(policy);
+    } catch {
+      // An invalid key cannot identify a bot, so it is isolated and ignored.
+    }
+  }
+  return accessPolicies;
+}
+
 function normalizeDocument(value) {
   if (!value || ![1, 2].includes(value.version) || !value.workspaces
     || typeof value.workspaces !== 'object' || Array.isArray(value.workspaces)) return null;
@@ -168,15 +192,52 @@ function normalizeDocument(value) {
   if (value.version === 1 && value.deliveryTargets !== undefined) return null;
   const deliveryTargets = normalizeDeliveryTargets(value.deliveryTargets);
   if (!deliveryTargets) return null;
+  const accessPolicies = normalizeAccessPolicies(value.accessPolicies, workspaces);
+  const version = value.accessPolicies === undefined ? value.version : 2;
   return {
-    version: value.version,
+    // A v1 file cannot be emitted with this optional v2 section. If one is
+    // recovered from an interrupted/manual edit, retain it on the next write.
+    version,
     workspaces,
     agentPresets,
     contextEnhancement,
     deliveryTargets,
+    accessPolicies,
   };
 }
 
+function storedDocument({
+  version,
+  workspaces,
+  agentPresets,
+  contextEnhancement,
+  deliveryTargets,
+  accessPolicies,
+}) {
+  const document = { version, workspaces };
+  if (Object.keys(agentPresets).length > 0) document.agentPresets = agentPresets;
+  if (Object.keys(contextEnhancement).length > 0) {
+    document.contextEnhancement = contextEnhancement;
+  }
+  if (version >= 2 && Object.keys(deliveryTargets).length > 0) {
+    document.deliveryTargets = deliveryTargets;
+  }
+  if (version >= 2 && Object.keys(accessPolicies).length > 0) {
+    document.accessPolicies = accessPolicies;
+  }
+  return document;
+}
+
+async function writeStoredDocument(path, document) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+  await rename(temporary, path);
+}
+
 export async function validateWorkspacePath(value) {
   if (typeof value !== 'string' || !value.trim() || !isAbsolute(value.trim())) {
     const error = new Error('工作区必须是绝对路径。');
@@ -208,6 +269,7 @@ export class BotWorkspaceStore {
   #agentPresets = {};
   #contextEnhancement = {};
   #deliveryTargets = Object.create(null);
+  #accessPolicies = Object.create(null);
   #generations = new Map();
   #nextGeneration = 1;
   #incarnations = new Map();
@@ -233,6 +295,7 @@ export class BotWorkspaceStore {
       this.#agentPresets = normalized.agentPresets;
       this.#contextEnhancement = normalized.contextEnhancement;
       this.#deliveryTargets = normalized.deliveryTargets;
+      this.#accessPolicies = normalized.accessPolicies;
     } catch (error) {
       if (error?.code !== 'ENOENT') throw error;
       this.#version = 1;
@@ -240,6 +303,7 @@ export class BotWorkspaceStore {
       this.#agentPresets = {};
       this.#contextEnhancement = {};
       this.#deliveryTargets = Object.create(null);
+      this.#accessPolicies = Object.create(null);
     }
     this.#generations.clear();
     this.#nextGeneration = 1;
@@ -278,6 +342,13 @@ export class BotWorkspaceStore {
       : DEFAULT_CONTEXT_ENHANCEMENT_CONFIG;
   }
 
+  accessPolicyFor(botId) {
+    const id = botIdOf(botId);
+    return this.has(id) && Object.hasOwn(this.#accessPolicies, id)
+      ? this.#accessPolicies[id]
+      : null;
+  }
+
   listDeliveryTargets(botId) {
     const id = botIdOf(botId);
     if (!this.has(id)) throw deliveryTargetError('unknown-bot', 'Unknown bot');
@@ -373,28 +444,53 @@ export class BotWorkspaceStore {
     }
   }
 
-  async ensure(botId, { workspace = this.#defaultWorkspace, defaultAgentPreset } = {}) {
+  async ensure(botId, {
+    workspace = this.#defaultWorkspace,
+    defaultAgentPreset,
+    initialAccessPolicy,
+  } = {}) {
     const id = botIdOf(botId);
     const initialWorkspace = resolve(workspace);
     return this.#enqueue(id, async () => {
-      if (!this.#workspaces[id]) {
-        const agentPreset = validateAgentPresetId(defaultAgentPreset);
+      const createsBot = !this.#workspaces[id];
+      const initializesAccessPolicy = initialAccessPolicy !== undefined
+        && !Object.hasOwn(this.#accessPolicies, id);
+      if (createsBot || initializesAccessPolicy) {
+        const accessPolicy = initializesAccessPolicy
+          ? validateAccessPolicy(initialAccessPolicy)
+          : undefined;
+        const agentPreset = createsBot ? validateAgentPresetId(defaultAgentPreset) : null;
         const hadAgentPreset = Object.hasOwn(this.#agentPresets, id);
         const previousAgentPreset = this.#agentPresets[id];
-        this.#workspaces[id] = initialWorkspace;
-        if (agentPreset) this.#agentPresets[id] = agentPreset;
-        this.#generations.set(id, this.#freshGeneration());
-        this.#incarnations.set(id, this.#freshIncarnation());
+        const nextAccessPolicies = initializesAccessPolicy
+          ? { ...this.#accessPolicies, [id]: accessPolicy }
+          : this.#accessPolicies;
+        if (createsBot) {
+          this.#workspaces[id] = initialWorkspace;
+          if (agentPreset) this.#agentPresets[id] = agentPreset;
+          this.#generations.set(id, this.#freshGeneration());
+          this.#incarnations.set(id, this.#freshIncarnation());
+        }
+        const nextVersion = initializesAccessPolicy ? 2 : this.#version;
         try {
-          await this.#persist();
+          await this.#persist(
+            this.#contextEnhancement,
+            this.#deliveryTargets,
+            nextVersion,
+            nextAccessPolicies,
+          );
         } catch (error) {
-          delete this.#workspaces[id];
-          if (hadAgentPreset) this.#agentPresets[id] = previousAgentPreset;
-          else delete this.#agentPresets[id];
-          this.#generations.delete(id);
-          this.#incarnations.delete(id);
+          if (createsBot) {
+            delete this.#workspaces[id];
+            if (hadAgentPreset) this.#agentPresets[id] = previousAgentPreset;
+            else delete this.#agentPresets[id];
+            this.#generations.delete(id);
+            this.#incarnations.delete(id);
+          }
           throw error;
         }
+        this.#accessPolicies = nextAccessPolicies;
+        this.#version = nextVersion;
       } else if (!this.#generations.has(id)) {
         this.#generations.set(id, this.#freshGeneration());
       }
@@ -487,6 +583,30 @@ export class BotWorkspaceStore {
     });
   }
 
+  async setAccessPolicy(botId, value, { incarnation } = {}) {
+    const id = botIdOf(botId);
+    const expectedIncarnation = incarnation === undefined ? this.incarnationFor(id) : incarnation;
+    const policy = validateAccessPolicy(value);
+    return this.#enqueue(id, async () => {
+      if (!this.has(id) || expectedIncarnation !== this.incarnationFor(id)) {
+        const error = new Error('找不到要修改的机器人。');
+        error.code = 'workspace-bot-not-found';
+        throw error;
+      }
+      const next = { ...this.#accessPolicies, [id]: policy };
+      // Inbound messages keep the previous committed snapshot until rename succeeds.
+      await this.#persist(
+        this.#contextEnhancement,
+        this.#deliveryTargets,
+        2,
+        next,
+      );
+      this.#accessPolicies = next;
+      this.#version = 2;
+      return policy;
+    });
+  }
+
   async bindWorkspaceSession(botId, value, {
     conversationKey,
     sessionId,
@@ -646,6 +766,7 @@ export class BotWorkspaceStore {
       ...Object.keys(this.#agentPresets),
       ...Object.keys(this.#contextEnhancement),
       ...Object.keys(this.#deliveryTargets),
+      ...Object.keys(this.#accessPolicies),
       ...this.#dirtyRemovals,
     ]);
     for (const botId of candidates) {
@@ -663,6 +784,7 @@ export class BotWorkspaceStore {
           workspace: this.workspaceFor(bot.botId),
           agentPreset: this.agentPresetFor(bot.botId),
           contextEnhancement: this.contextEnhancementFor(bot.botId),
+          accessPolicy: this.accessPolicyFor(bot.botId),
         }
         : bot),
     };
@@ -694,12 +816,14 @@ export class BotWorkspaceStore {
     const hadPreset = Object.hasOwn(this.#agentPresets, id);
     const hadContextEnhancement = Object.hasOwn(this.#contextEnhancement, id);
     const hadDeliveryTargets = Object.hasOwn(this.#deliveryTargets, id);
+    const hadAccessPolicy = Object.hasOwn(this.#accessPolicies, id);
     const needsCleanup = hadWorkspace || hadPreset || hadContextEnhancement
-      || hadDeliveryTargets || this.#dirtyRemovals.has(id);
+      || hadDeliveryTargets || hadAccessPolicy || this.#dirtyRemovals.has(id);
     delete this.#workspaces[id];
     delete this.#agentPresets[id];
     delete this.#contextEnhancement[id];
     delete this.#deliveryTargets[id];
+    delete this.#accessPolicies[id];
     this.#generations.delete(id);
     this.#incarnations.delete(id);
     if (!needsCleanup) return {
@@ -733,24 +857,16 @@ export class BotWorkspaceStore {
     contextEnhancement = this.#contextEnhancement,
     deliveryTargets = this.#deliveryTargets,
     version = this.#version,
+    accessPolicies = this.#accessPolicies,
   ) {
-    const document = { version, workspaces: this.#workspaces };
-    if (Object.keys(this.#agentPresets).length > 0) {
-      document.agentPresets = this.#agentPresets;
-    }
-    if (Object.keys(contextEnhancement).length > 0) {
-      document.contextEnhancement = contextEnhancement;
-    }
-    if (version >= 2 && Object.keys(deliveryTargets).length > 0) {
-      document.deliveryTargets = deliveryTargets;
-    }
-    await mkdir(dirname(this.#path), { recursive: true, mode: 0o700 });
-    const temporary = `${this.#path}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
-      encoding: 'utf8',
-      mode: 0o600,
-    });
-    await rename(temporary, this.#path);
+    await writeStoredDocument(this.#path, storedDocument({
+      version,
+      workspaces: this.#workspaces,
+      agentPresets: this.#agentPresets,
+      contextEnhancement,
+      deliveryTargets,
+      accessPolicies,
+    }));
     this.#dirtyRemovals.clear();
   }
 
@@ -758,7 +874,8 @@ export class BotWorkspaceStore {
     if (Object.keys(this.#workspaces).length > 0
       || Object.keys(this.#agentPresets).length > 0
       || Object.keys(this.#contextEnhancement).length > 0
-      || Object.keys(this.#deliveryTargets).length > 0) {
+      || Object.keys(this.#deliveryTargets).length > 0
+      || Object.keys(this.#accessPolicies).length > 0) {
       await this.#persist();
       return;
     }
@@ -1280,6 +1397,31 @@ export function createWorkspaceAwareController(controller, { workspaces, stateFo
       return result;
     });
   };
+  const updateAccessPolicy = (botId, value, projectStatus) => {
+    const incarnation = workspaces.incarnationFor(botId);
+    const policy = validateAccessPolicy(value);
+    return withBotTransition(botId, async () => {
+      const snapshot = await controller.status();
+      if (!snapshot?.bots?.some((bot) => bot?.botId === botId)) {
+        const error = new Error('找不到要修改的机器人。');
+        error.code = 'workspace-bot-not-found';
+        throw error;
+      }
+      const catalog = await resolveAgentPresetCatalog(agentPresetCatalog);
+      const decorated = workspaces.decorateStatus(snapshot);
+      const updated = {
+        ...decorated,
+        bots: decorated.bots.map((bot) => bot?.botId === botId
+          ? { ...bot, accessPolicy: policy } : bot),
+        ...(catalog ? { agentPresetCatalog: catalog } : {}),
+      };
+      // Prepare the complete channel-specific response before commit. Failed
+      // projections and disk writes must leave the live policy unchanged.
+      const result = projectStatus ? await projectStatus(updated) : updated;
+      await workspaces.setAccessPolicy(botId, policy, { incarnation });
+      return result;
+    });
+  };
   const deleteWithWorkspace = (botId, invokeDelete) => withBotTransition(botId, async () => {
     // Fence the old runtime without changing the durable mapping. A crash
     // before the controller removes its config therefore keeps the bot's
@@ -1320,6 +1462,7 @@ export function createWorkspaceAwareController(controller, { workspaces, stateFo
       if (property === 'updateWorkspace') return updateWorkspace;
       if (property === 'updateAgentPreset') return updateAgentPreset;
       if (property === 'updateContextEnhancement') return updateContextEnhancement;
+      if (property === 'updateAccessPolicy') return updateAccessPolicy;
       const value = Reflect.get(target, property, target);
       if (typeof value !== 'function') return value;
       if (property === 'deleteBot') {

package/src/channels/shared/command-permission.mjs

@@ -0,0 +1,32 @@
+import { isBatchInputCommand } from './batch-input.mjs';
+import { isCompactCommand } from './compact-command.mjs';
+import { isControlCommand } from './control-command.mjs';
+import { isHistoryCommand } from './history-command.mjs';
+import { isModelCommand } from './model-command.mjs';
+import { isPresetCommand } from './preset-command.mjs';
+import { isWorkspaceCommand } from './workspace-command.mjs';
+
+const SIMPLE_TEXT_COMMANDS = new Set(['/help', '/status', '/new']);
+
+/**
+ * Match only commands that the shared bridges already execute locally.
+ * Unknown slash-prefixed text remains an ordinary prompt.
+ */
+export function isSharedLocalCommand(text, {
+  hasImages = false,
+  hasFiles = false,
+} = {}) {
+  if (typeof text !== 'string') return false;
+  const command = text.trim();
+  if (!command) return false;
+  if (isBatchInputCommand(command) || isHistoryCommand(command)) return true;
+  if (!hasFiles && (
+    isControlCommand(command)
+    || isModelCommand(command)
+    || isPresetCommand(command)
+  )) return true;
+  if (hasImages || hasFiles) return false;
+  return SIMPLE_TEXT_COMMANDS.has(command.toLowerCase())
+    || isWorkspaceCommand(command)
+    || isCompactCommand(command);
+}

package/src/channels/shared/compact-command.mjs

@@ -70,9 +70,8 @@ function compactErrorMessage(error) {
  * Unknown input returns null so the caller may continue ordinary message routing.
  */
 export async function runCompactCommand(text, harness, state, conversationKey, options = {}) {
-  if (typeof text !== 'string') return null;
+  if (!isCompactCommand(text)) return null;
   const match = COMPACT_COMMAND.exec(text.trim());
-  if (!match) return null;
   if (match[1].trim()) return commandResult(t(COMPACT_USAGE));
   if (typeof state?.sessionFor !== 'function') {
     return commandResult(t('当前机器人没有可用的会话状态。'));
@@ -94,3 +93,7 @@ export async function runCompactCommand(text, harness, state, conversationKey, o
     return commandResult(compactErrorMessage(error));
   }
 }
+
+export function isCompactCommand(text) {
+  return typeof text === 'string' && COMPACT_COMMAND.test(text.trim());
+}

package/src/channels/shared/context-enhancement.mjs

@@ -4,6 +4,12 @@ export const CONTEXT_ENHANCEMENT_FIELDS = Object.freeze([
 ]);
 
 export const CONTEXT_ENHANCEMENT_GUIDANCE_MAX_LENGTH = 8_000;
+export const CONTEXT_GROUP_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
+当前消息来自群聊，请使用严肃、克制、简洁的表达方式。`;
+export const CONTEXT_DIRECT_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
+当前消息来自私聊，可以使用更轻松、幽默、详细的表达方式。`;
+
+// Kept for integrations that imported the original combined example.
 export const CONTEXT_GUIDANCE_EXAMPLE = `仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
 conversationType是群聊时回复严肃一点，conversationType是私聊时回复一定要幽默搞笑，像周星驰的电影一样搞笑`;
 
@@ -11,13 +17,21 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回
 export const DEFAULT_CONTEXT_GUIDANCE = CONTEXT_GUIDANCE_EXAMPLE;
 
 export const DEFAULT_CONTEXT_ENHANCEMENT_CONFIG = Object.freeze({
-  groupEnabled: false,
-  directEnabled: false,
-  fields: Object.freeze(['senderId']),
-  guidance: '',
+  group: Object.freeze({
+    enabled: false,
+    fields: Object.freeze(['senderId']),
+    guidance: '',
+  }),
+  direct: Object.freeze({
+    enabled: false,
+    fields: Object.freeze(['senderId']),
+    guidance: '',
+  }),
 });
 
-const CONFIG_KEYS = ['groupEnabled', 'directEnabled', 'fields', 'guidance'];
+const CONFIG_KEYS = ['group', 'direct'];
+const SCOPE_KEYS = ['enabled', 'fields', 'guidance'];
+const LEGACY_CONFIG_KEYS = ['groupEnabled', 'directEnabled', 'fields', 'guidance'];
 const CHANNELS = new Set([
   'wecom', 'weixin', 'feishu', 'dingtalk', 'qq',
   'slack', 'telegram', 'discord', 'whatsapp',
@@ -31,16 +45,19 @@ function invalidConfig(message) {
   return error;
 }
 
-/** Validate the complete atomic save, preserving explicit empty selections/text. */
-export function validateContextEnhancementConfig(input) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)
-    || ![Object.prototype, null].includes(Object.getPrototypeOf(input))
-    || Reflect.ownKeys(input).length !== CONFIG_KEYS.length
-    || !CONFIG_KEYS.every((key) => Object.hasOwn(input, key))) {
+function hasExactKeys(input, keys) {
+  return input && typeof input === 'object' && !Array.isArray(input)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(input))
+    && Reflect.ownKeys(input).length === keys.length
+    && keys.every((key) => Object.hasOwn(input, key));
+}
+
+function validateContextEnhancementScope(input) {
+  if (!hasExactKeys(input, SCOPE_KEYS)) {
     throw invalidConfig('请提交完整的上下文增强设置。');
   }
-  const { groupEnabled, directEnabled, fields, guidance } = input;
-  if (typeof groupEnabled !== 'boolean' || typeof directEnabled !== 'boolean') {
+  const { enabled, fields, guidance } = input;
+  if (typeof enabled !== 'boolean') {
     throw invalidConfig('群聊和私聊开关必须是布尔值。');
   }
   if (!Array.isArray(fields) || ![...fields].every((field) => CONTEXT_ENHANCEMENT_FIELDS.includes(field))) {
@@ -50,19 +67,51 @@ export function validateContextEnhancementConfig(input) {
     throw invalidConfig(`增强提示词不得超过 ${CONTEXT_ENHANCEMENT_GUIDANCE_MAX_LENGTH} 个字符。`);
   }
   return Object.freeze({
-    groupEnabled,
-    directEnabled,
+    enabled,
     fields: Object.freeze(CONTEXT_ENHANCEMENT_FIELDS.filter((field) => fields.includes(field))),
     guidance: guidance.trim() ? guidance : '',
   });
 }
 
+/** Validate the complete atomic save, preserving explicit empty selections/text. */
+export function validateContextEnhancementConfig(input) {
+  if (!hasExactKeys(input, CONFIG_KEYS)) {
+    throw invalidConfig('请提交完整的上下文增强设置。');
+  }
+  return Object.freeze({
+    group: validateContextEnhancementScope(input.group),
+    direct: validateContextEnhancementScope(input.direct),
+  });
+}
+
+function migrateLegacyContextEnhancementConfig(input) {
+  if (!hasExactKeys(input, LEGACY_CONFIG_KEYS)) {
+    throw invalidConfig('请提交完整的上下文增强设置。');
+  }
+  return validateContextEnhancementConfig({
+    group: {
+      enabled: input.groupEnabled,
+      fields: input.fields,
+      guidance: input.guidance,
+    },
+    direct: {
+      enabled: input.directEnabled,
+      fields: input.fields,
+      guidance: input.guidance,
+    },
+  });
+}
+
 /** Missing or damaged enhancement settings must never break an existing bot. */
 export function normalizeContextEnhancementConfig(input) {
   try {
     return validateContextEnhancementConfig(input);
   } catch {
-    return DEFAULT_CONTEXT_ENHANCEMENT_CONFIG;
+    try {
+      return migrateLegacyContextEnhancementConfig(input);
+    } catch {
+      return DEFAULT_CONTEXT_ENHANCEMENT_CONFIG;
+    }
   }
 }
 
@@ -71,11 +120,15 @@ export function captureContextEnhancement(provider, conversationType) {
   if (conversationType !== 'group' && conversationType !== 'direct') return null;
   try {
     const settings = provider?.getSettings?.();
-    const enabledKey = conversationType === 'group' ? 'groupEnabled' : 'directEnabled';
-    if (settings?.[enabledKey] !== true) return null;
+    const legacyEnabledKey = conversationType === 'group' ? 'groupEnabled' : 'directEnabled';
+    const enabled = Object.hasOwn(settings ?? {}, conversationType)
+      ? settings?.[conversationType]?.enabled
+      : settings?.[legacyEnabledKey];
+    if (enabled !== true) return null;
     const config = normalizeContextEnhancementConfig(settings);
-    if (config[enabledKey] !== true) return null;
-    return Object.freeze({ config, botId: provider.botId, conversationType });
+    const scope = config[conversationType];
+    if (scope.enabled !== true) return null;
+    return Object.freeze({ config: scope, botId: provider.botId, conversationType });
   } catch {
     return null;
   }

package/src/channels/shared/i18n-en/shared-c.mjs

@@ -185,4 +185,6 @@ export default {
     'Collected {count}/{limit} messages. The batch is full; send /send or /cancel.',
   '批量内容提交失败，已保留 {count} 条消息。\n请再次发送 /send 重试或 /cancel 取消。':
     'Batch submission failed; {count} messages were retained.\nSend /send to retry or /cancel to cancel.',
+  '你可以发送普通消息，但没有执行命令的权限。':
+    'You can send regular messages, but you do not have permission to run commands.',
 };

package/src/channels/shared/inbound-access.mjs

@@ -0,0 +1,43 @@
+import { evaluateAccessPolicy } from './access-policy.mjs';
+import { isSharedLocalCommand } from './command-permission.mjs';
+
+export const COMMAND_PERMISSION_DENIED_MESSAGE = '你可以发送普通消息，但没有执行命令的权限。';
+
+const POLICY_NOT_CONFIGURED = Object.freeze({ allowed: true, reason: 'policy-not-configured' });
+const PRIVILEGED_SENDER = Object.freeze({ allowed: true, reason: 'privileged-sender' });
+
+/**
+ * Read one committed policy snapshot and decide a single inbound event.
+ * A missing provider is kept backward-compatible for direct bridge fixtures;
+ * production always injects a provider, whose missing/damaged value fails closed.
+ */
+export function evaluateInboundAccess(accessPolicy, {
+  conversationType,
+  senderIds,
+  text = '',
+  hasImages = false,
+  hasFiles = false,
+  isCommand = isSharedLocalCommand(text, { hasImages, hasFiles }),
+} = {}) {
+  if (!accessPolicy) return POLICY_NOT_CONFIGURED;
+  try {
+    if (typeof accessPolicy.isPrivileged === 'function'
+      && accessPolicy.isPrivileged(senderIds, conversationType) === true) {
+      return PRIVILEGED_SENDER;
+    }
+  } catch {
+    // A broken privilege lookup must not bypass the persisted policy.
+  }
+  let policy = null;
+  try {
+    policy = accessPolicy.getSettings();
+  } catch {
+    // Provider failures are equivalent to an unavailable persisted policy.
+  }
+  return evaluateAccessPolicy(policy, {
+    conversationType,
+    senderIds,
+    isCommand,
+    ...(typeof accessPolicy.equals === 'function' ? { equals: accessPolicy.equals } : {}),
+  });
+}