@animalabs/agent-framework 0.7.4 → 0.9.0

package/src/gate/event-gate.ts

@@ -366,6 +366,13 @@ export class EventGate {
   private sleepTimer: ReturnType<typeof setTimeout> | null = null;
   private sleepAgent: string | undefined;
 
+  // Self-wake timers per agent (skip_reply's wake_in_seconds). Unlike sleep,
+  // a self-wake suppresses NOTHING — it means "if nothing else wakes me by
+  // then, wake me". Any turn start for the agent cancels its pending
+  // self-wake (an external wake supersedes it; the timer would otherwise
+  // land as a redundant empty wake right after the turn).
+  private selfWakeTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
   // Privileged users who may wake the agent through sleep. Hot-reloaded from
   // privilegedUsersPath on change.
   private privilegedUsersPath: string | undefined;
@@ -1135,6 +1142,14 @@ export class EventGate {
 
   onInferenceStarted(agentName: string): void {
     this.inferring.add(agentName);
+    // A turn is starting — whatever caused it supersedes any pending
+    // self-wake. (Arming happens MID-turn via skip_reply, i.e. after this
+    // ran for the arming turn, so a fresh arm always survives its own turn.)
+    const selfWake = this.selfWakeTimers.get(agentName);
+    if (selfWake) {
+      clearTimeout(selfWake);
+      this.selfWakeTimers.delete(agentName);
+    }
   }
 
   onInferenceEnded(agentName: string): void {
@@ -1206,6 +1221,59 @@ export class EventGate {
     return { until: this.sleepUntil };
   }
 
+  // =========================================================================
+  // Self-wake (skip_reply wake_in_seconds)
+  // =========================================================================
+
+  /**
+   * Arm a one-shot self-wake for `agentName` in `seconds` (clamped to
+   * [1, 3600]). Fires a normal inference request when it elapses — no
+   * suppression window, unlike sleep. Re-arming replaces the pending timer.
+   * Cancelled by the agent's next turn start (see onInferenceStarted):
+   * the semantics are "if nothing else wakes me by then, wake me".
+   */
+  armSelfWake(agentName: string, seconds: number, source = 'skip_reply'): { inMs: number } {
+    const ms = Math.max(1_000, Math.min(3_600_000, Math.floor(seconds * 1000)));
+    const prev = this.selfWakeTimers.get(agentName);
+    if (prev) clearTimeout(prev);
+    const timer = setTimeout(() => {
+      this.selfWakeTimers.delete(agentName);
+      this.emitTrace({
+        type: 'gate:decision',
+        eventType: 'selfwake:fired',
+        matchedPolicy: 'self-wake',
+        trigger: true,
+        behavior: 'always',
+        timestamp: this.now(),
+      });
+      // Compact in-window notice: without it the wake turn contains nothing
+      // new, so the agent can't tell WHAT woke it (its own timer vs. a
+      // heartbeat) or WHEN. One line, timestamped to the second. Added
+      // before the inference request so it rides the wake turn (addMessage's
+      // turn-alive guard defers it to that turn's start if needed).
+      const nowIso = new Date(this.now()).toISOString().slice(0, 19) + 'Z';
+      this.addMessageFn('user', [{
+        type: 'text',
+        text: `[self-wake] your ${source} timer (${Math.round(ms / 1000)}s) elapsed — now ${nowIso}`,
+      }], { source: 'gate:self-wake' });
+      this.requestInferenceFn(
+        agentName,
+        `self-scheduled wake (${source}, ${Math.round(ms / 1000)}s)`,
+        'self-wake',
+      );
+    }, ms);
+    this.selfWakeTimers.set(agentName, timer);
+    this.emitTrace({
+      type: 'gate:decision',
+      eventType: 'selfwake:set',
+      matchedPolicy: 'self-wake',
+      trigger: false,
+      behavior: 'skip',
+      timestamp: this.now(),
+    });
+    return { inMs: ms };
+  }
+
   /** End sleep immediately. Returns true if the agent was asleep. */
   clearSleep(): boolean {
     const wasAsleep = this.sleepUntil > this.now();
@@ -1387,6 +1455,10 @@ export class EventGate {
       clearTimeout(state.timer);
     }
     this.debounceTimers.clear();
+    for (const timer of this.selfWakeTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.selfWakeTimers.clear();
     this.rateLimitBuckets.clear();
     this.passiveSampleCounters.clear();
     this.rateLimitDenied.clear();

package/src/index.ts

@@ -8,6 +8,7 @@ export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
 export { formatZonedDateTime, formatZonedTime, isValidTimeZone, resolveTimeZone } from './timezone.js';
+export { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK, REFUSAL_REACTION_BASELINE } from './refusal-reactions.js';
 
 // Built-in modules
 export * from './modules/index.js';

package/src/mcpl/capability-grant.ts

@@ -0,0 +1,319 @@
+/**
+ * Capability grants — the MCPL 0.5 security boundary (SPEC §5.4).
+ *
+ * Three layers, kept deliberately distinct:
+ *
+ *  1. **Advertisement walk** — what the server *can* do, read from its
+ *     initialize response by a generic recursive walk over the §6.2
+ *     vocabulary. Boolean `true` at any level is shorthand for every leaf
+ *     beneath it (§5.1). An unrecognized member name cannot mint a
+ *     capability. Advertisement is an input, never an authorization.
+ *
+ *  2. **Config mask** — host policy from `enabledCapabilities` /
+ *     `disabledCapabilities` (folded in from PR #75, Meganeuridae's
+ *     capability-scoping work, semantics unchanged). This is the DENY
+ *     direction, so a pattern matching a parent masks the whole subtree —
+ *     deny-safe by construction.
+ *
+ *  3. **The grant** — the intersection, expressed as an explicit allowlist
+ *     of full capability paths. `effectiveCapabilities` is the sole
+ *     normative allowlist; **absence is denial and there is no unspecified
+ *     state**. Matching here is NOT the mask's subtree matching: `*` matches
+ *     exactly one segment, segment counts must agree, and a bare parent
+ *     grants nothing beneath it (§5.4 as pinned 2026-08-02 — the suffix
+ *     reading was implemented once and adjudicated out; see mcpl e869744).
+ *
+ * §13.4: `contextHooks.beforeInference.inject.system` is DENIED BY DEFAULT.
+ * A server that needs it must be granted it explicitly via
+ * `enabledCapabilities`. This is the one place the default is not
+ * "everything advertised survives the mask", and it is loud when it fires.
+ */
+
+import type { McplCapabilities, McplServerConfig } from './types.js';
+
+// ============================================================================
+// §6.2 vocabulary
+// ============================================================================
+
+/**
+ * The closed capability-path vocabulary (SPEC §6.2). A tree, not a flat
+ * list, because the advertisement walk and boolean-shorthand expansion are
+ * defined over the tree. Leaves are `null`; interior nodes that are
+ * themselves grantable paths (e.g. `inferenceRequest`) appear as nodes whose
+ * path is also emitted when advertised.
+ */
+const VOCABULARY: CapNode = {
+  pushEvents: null,
+  tools: null,
+  modelInfo: null,
+  inferenceRequest: { streaming: null },
+  inferenceLifecycle: null,
+  contextHooks: {
+    beforeInference: {
+      observe: null,
+      inject: { system: null, beforeUser: null, afterUser: null },
+    },
+  },
+  channels: {
+    register: null,
+    lifecycle: null,
+    publish: null,
+    incoming: null,
+    streaming: null,
+    acknowledge: null,
+    typing: null,
+  },
+};
+
+interface CapNodeMap {
+  [key: string]: CapNode;
+}
+type CapNode = CapNodeMap | null;
+
+/** Interior nodes that are grantable paths in their own right (§6.2 lists
+ *  `inferenceRequest` alongside `inferenceRequest.streaming`). Namespaces
+ *  (`contextHooks`, `channels`, `inject`) are not: they hold no authority. */
+const SELF_GRANTABLE_INTERIOR = new Set(['inferenceRequest']);
+
+/** Every full path in the vocabulary (leaves plus self-grantable interiors). */
+export const ALL_CAPABILITY_PATHS: readonly string[] = (() => {
+  const out: string[] = [];
+  const walk = (node: CapNodeMap, prefix: string): void => {
+    for (const [key, child] of Object.entries(node)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (child === null) {
+        out.push(path);
+      } else {
+        if (SELF_GRANTABLE_INTERIOR.has(path)) out.push(path);
+        walk(child, path);
+      }
+    }
+  };
+  walk(VOCABULARY, '');
+  return out;
+})();
+
+const KNOWN_PATHS = new Set(ALL_CAPABILITY_PATHS);
+
+/** Is this exact string a §6.2 capability path? (Used by §6.4 `uses`
+ *  validation — `uses` MUST contain only these values.) */
+export function isKnownCapabilityPath(path: string): boolean {
+  return KNOWN_PATHS.has(path);
+}
+
+// ============================================================================
+// Advertisement walk (§5.1)
+// ============================================================================
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function collectSubtree(node: CapNode, path: string, out: Set<string>): void {
+  if (node === null) {
+    out.add(path);
+    return;
+  }
+  if (SELF_GRANTABLE_INTERIOR.has(path)) out.add(path);
+  for (const [key, child] of Object.entries(node)) {
+    collectSubtree(child, path ? `${path}.${key}` : key, out);
+  }
+}
+
+/**
+ * The set of full capability paths a capabilities object advertises.
+ * Generic recursive walk; `true` at any level advertises every leaf beneath
+ * it; `false`/absent advertises nothing; unrecognized member names are
+ * ignored — an unknown name cannot mint a capability.
+ *
+ * `tools` is deliberately NOT sourced here. §5.1 sources it from the OUTER
+ * standard MCP `capabilities.tools` only — the experimental manifest cannot
+ * mint standard MCP tool capability (review blocker 2 on PR #79). A nested
+ * `experimental.mcpl.tools` is treated as an unknown member. Callers join
+ * the outer signal via computeGrant's mcpToolsAdvertised.
+ */
+export function advertisedPaths(capabilities: McplCapabilities | null): Set<string> {
+  const out = new Set<string>();
+  if (!capabilities) return out;
+  const walk = (vocab: CapNode, value: unknown, prefix: string): void => {
+    if (vocab === null || !isPlainObject(value)) return;
+    for (const [key, child] of Object.entries(vocab)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (path === 'tools') continue; // outer MCP caps only — see doc comment
+      const v = value[key];
+      if (v === true) {
+        collectSubtree(child, path, out);
+      } else if (isPlainObject(v)) {
+        if (child !== null) {
+          if (SELF_GRANTABLE_INTERIOR.has(path)) out.add(path);
+          walk(child, v, path);
+        }
+      }
+      // false / absent / non-object-non-true: advertises nothing.
+    }
+  };
+  walk(VOCABULARY, capabilities as unknown as Record<string, unknown>, '');
+  return out;
+}
+
+/**
+ * Expand §5.1 boolean shorthand into the explicit leaf tree, IN PLACE of the
+ * boolean, for every vocabulary node — so the config mask's generic child
+ * walk can address sub-leaves. Without this, `channels: true` is an atomic
+ * top-level leaf to the mask: `disabledCapabilities:['channels.streaming']`
+ * silently no-ops and `enabledCapabilities:['channels.publish']` drops the
+ * whole tree (review blocker 1 — live release geometry, since discord
+ * truthfully keeps `channels: true`).
+ *
+ * Unrecognized members and non-capability members (`version`, `revision`,
+ * `featureSets`) pass through untouched. The wire keeps its shorthand; this
+ * expanded form is the host's POLICY representation.
+ */
+export function expandAdvertisementShorthand(capabilities: McplCapabilities | null): McplCapabilities | null {
+  if (!capabilities) return capabilities;
+  const expandNode = (node: CapNode): unknown => {
+    if (node === null) return true;
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(node)) out[key] = expandNode(child);
+    return out;
+  };
+  const walk = (vocab: CapNodeMap, value: Record<string, unknown>): Record<string, unknown> => {
+    const out: Record<string, unknown> = { ...value };
+    for (const [key, child] of Object.entries(vocab)) {
+      if (key === 'tools') continue; // never expanded from experimental
+      const v = value[key];
+      if (child === null) continue; // leaf: boolean stays a boolean
+      if (v === true) {
+        out[key] = expandNode(child);
+      } else if (isPlainObject(v)) {
+        out[key] = walk(child, v);
+      }
+    }
+    return out;
+  };
+  return walk(VOCABULARY as CapNodeMap, capabilities as unknown as Record<string, unknown>) as unknown as McplCapabilities;
+}
+
+// ============================================================================
+// Grant matching (§5.4) — one-segment wildcards, equal counts
+// ============================================================================
+
+/**
+ * `*` matches exactly one dot-segment; literal segments match exactly;
+ * segment counts MUST agree. A bare parent does not match its subtree and a
+ * trailing `*` is not a suffix wildcard (SPEC §5.4, pinned 2026-08-02).
+ */
+export function capabilityPatternMatches(pattern: string, path: string): boolean {
+  const p = pattern.split('.');
+  const n = path.split('.');
+  if (p.length !== n.length) return false;
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] !== '*' && p[i] !== n[i]) return false;
+  }
+  return true;
+}
+
+// ============================================================================
+// The grant
+// ============================================================================
+
+/** §13.4: denied unless explicitly enabled by host config. */
+const DENY_BY_DEFAULT: readonly string[] = ['contextHooks.beforeInference.inject.system'];
+
+export class CapabilityGrant {
+  /** Exact granted paths (already expanded — no patterns stored). */
+  private readonly granted: ReadonlySet<string>;
+  /** Advertised-but-denied paths, for the §5.3 diagnostic field only. */
+  readonly deniedPaths: readonly string[];
+
+  constructor(granted: Set<string>, deniedPaths: string[]) {
+    this.granted = granted;
+    this.deniedPaths = deniedPaths;
+  }
+
+  /** Sole authorization question. Absence is denial (§5.4). */
+  has(path: string): boolean {
+    return this.granted.has(path);
+  }
+
+  /** Sorted list for `effectiveCapabilities` (§5.3). */
+  effectiveList(): string[] {
+    return [...this.granted].sort();
+  }
+
+  /** True when nothing at all is granted. */
+  isEmpty(): boolean {
+    return this.granted.size === 0;
+  }
+
+  static empty(): CapabilityGrant {
+    return new CapabilityGrant(new Set(), []);
+  }
+
+  /**
+   * The grant carried by a connection-like object, failing CLOSED when the
+   * object has none. Registry consumers receive whatever the registry holds
+   * — including test stubs and objects created before the field existed —
+   * and a missing grant must mean "nothing granted" (§5.4 absence is
+   * denial), never a TypeError that takes the gate down open-ended.
+   */
+  static of(conn: { grant?: CapabilityGrant } | null | undefined): CapabilityGrant {
+    return conn?.grant ?? CapabilityGrant.empty();
+  }
+
+  /**
+   * A copy of this grant with the named paths removed — the reduction
+   * primitive. §6.7's ordering contract lives at the call site: install the
+   * narrowed grant (establishGrant) BEFORE sending the reducing
+   * featureSets/update Request; security cannot wait on consent.
+   */
+  without(...paths: string[]): CapabilityGrant {
+    const granted = new Set(this.granted);
+    const denied = new Set(this.deniedPaths);
+    for (const p of paths) {
+      if (granted.delete(p)) denied.add(p);
+    }
+    return new CapabilityGrant(granted, [...denied].sort());
+  }
+}
+
+/**
+ * Compute the effective grant for a connection: the server's advertisement
+ * (post config-mask — the mask runs first at handshake, so `capabilities`
+ * here is already the masked object) intersected with the deny-by-default
+ * floor. `enabledCapabilities` config patterns can re-grant a
+ * deny-by-default path — that is the explicit decision §13.4 asks for.
+ */
+export function computeGrant(
+  capabilities: McplCapabilities | null,
+  config: Pick<McplServerConfig, 'enabledCapabilities'>,
+  opts?: {
+    /** §5.1: `tools` is sourced from the OUTER standard MCP
+     *  `capabilities.tools` — pass its presence here. The experimental
+     *  manifest cannot mint it. Without this signal, every
+     *  `uses: ['tools']` feature set fails §6.4 derivation. */
+    mcpToolsAdvertised?: boolean;
+  },
+): CapabilityGrant {
+  const advertised = advertisedPaths(capabilities);
+  if (opts?.mcpToolsAdvertised) advertised.add('tools');
+  const granted = new Set<string>();
+  const denied: string[] = [];
+
+  const explicitlyEnabled = (path: string): boolean =>
+    !!config.enabledCapabilities?.some((pat) => capabilityPatternMatches(pat, path));
+
+  for (const path of advertised) {
+    if (DENY_BY_DEFAULT.includes(path) && !explicitlyEnabled(path)) {
+      denied.push(path);
+      console.error(
+        `[mcpl] "${path}" advertised but DENIED BY DEFAULT (SPEC §13.4) — ` +
+          `grant it explicitly via enabledCapabilities if intended`,
+      );
+      continue;
+    }
+    granted.add(path);
+  }
+
+  return new CapabilityGrant(granted, denied.sort());
+}

package/src/mcpl/capability-mask.ts

@@ -0,0 +1,228 @@
+/**
+ * Host-side capability scoping for MCPL servers.
+ *
+ * A server names its own capabilities in its initialize response, and
+ * everything downstream — hook fan-out, channel streaming, push handling —
+ * keys off that self-advertisement. `enabledCapabilities` /
+ * `disabledCapabilities` in McplServerConfig let the host intersect the
+ * advertisement with its own policy at handshake time, so a capability the
+ * config masks behaves exactly as if the server had never advertised it.
+ *
+ * The mask is applied once, where the negotiated capabilities are stored
+ * (McplServerConnection.handshake), rather than re-checked at each consumer:
+ * hook orchestration, streaming observation, and capability queries all read
+ * the already-masked object. Inbound server-initiated methods gated by a
+ * masked capability are additionally rejected at the connection
+ * (see METHOD_TO_REQUIRED_CAPABILITY in server-connection.ts).
+ *
+ * Matching is a generic recursive walk per SPEC 0.5 §5.4: every path at
+ * every depth is addressable (`contextHooks.beforeInference.inject.system`
+ * works the day the host stores that shape), and a pattern matching a parent
+ * masks the whole subtree. No hardcoded set of nestable keys.
+ */
+
+import type { McplCapabilities, McplServerConfig } from './types.js';
+
+/** Result of masking: the surviving capabilities plus what was dropped. */
+export interface MaskedCapabilities {
+  capabilities: McplCapabilities | null;
+  /**
+   * Dotted paths of advertised capabilities removed by the mask (e.g.
+   * `contextHooks.afterInference`). When an entire multi-flag capability is
+   * removed (`channels` advertised as a boolean, denied as a parent, or
+   * every advertised flag masked), the bare parent path (`channels`) is
+   * included so inbound enforcement can key on it.
+   */
+  dropped: string[];
+}
+
+/**
+ * Segment-wise wildcard match, same rules as feature-set patterns:
+ * `*` matches exactly one dot-segment, literal segments match exactly,
+ * segment counts must agree.
+ */
+function wildcardMatch(pattern: string, name: string): boolean {
+  const patternParts = pattern.split('.');
+  const nameParts = name.split('.');
+
+  if (patternParts.length !== nameParts.length) {
+    return false;
+  }
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+    if (p === '*') {
+      continue;
+    }
+    if (p !== nameParts[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether a pattern matches a capability path or any ancestor prefix of it —
+ * `contextHooks` (or `*`) covers `contextHooks.beforeInference.inject.system`
+ * at any depth, so masking a parent masks everything beneath it.
+ */
+function patternMatchesPath(pattern: string, path: string): boolean {
+  const parts = path.split('.');
+  for (let depth = parts.length; depth >= 1; depth--) {
+    if (wildcardMatch(pattern, parts.slice(0, depth).join('.'))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function anyMatches(patterns: string[], path: string): boolean {
+  return patterns.some((pattern) => patternMatchesPath(pattern, path));
+}
+
+/** Keys that are negotiation metadata, not grantable capabilities. */
+const UNMASKABLE_KEYS = new Set(['version', 'featureSets']);
+
+/**
+ * Interior object paths whose object value is itself the capability, with
+ * children as refinements — dropping a refinement leaves the capability
+ * granted (`inferenceRequest` minus `.streaming` is still inferenceRequest).
+ * Every other interior object is a pure namespace (`contextHooks`,
+ * `channels`, a future `inject`): it holds no authority of its own and is
+ * pruned when all its advertised children are masked.
+ *
+ * This is a retention-shape distinction only — matching and addressability
+ * are fully generic and depth-unbounded either way.
+ */
+const OBJECT_CAPABILITY_PATHS = new Set(['inferenceRequest', 'contextHooks.afterInference']);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Intersect a server's advertised MCPL capabilities with the host config's
+ * `enabledCapabilities` / `disabledCapabilities`.
+ *
+ * Semantics mirror enabledTools/disabledTools: if `enabledCapabilities` is
+ * set, only advertised capabilities matching at least one pattern survive;
+ * `disabledCapabilities` removes matches and wins on conflict. Patterns are
+ * dotted paths with `*` matching one segment, and a pattern that matches a
+ * parent (`contextHooks`) covers every path beneath it. `version` and
+ * `featureSets` are never masked here — feature sets have their own
+ * enable/disable knobs.
+ *
+ * With neither list set, the advertisement passes through untouched.
+ */
+export function maskNegotiatedCapabilities(
+  capabilities: McplCapabilities | null,
+  config: Pick<McplServerConfig, 'enabledCapabilities' | 'disabledCapabilities'>,
+): MaskedCapabilities {
+  const enabled = config.enabledCapabilities;
+  const disabled = config.disabledCapabilities;
+
+  if (capabilities === null || (!enabled && !disabled)) {
+    return { capabilities, dropped: [] };
+  }
+
+  const denied = (path: string): boolean => !!disabled && anyMatches(disabled, path);
+  const allowed = (path: string): boolean => !enabled || anyMatches(enabled, path);
+  const keep = (path: string): boolean => !denied(path) && allowed(path);
+
+  const dropped: string[] = [];
+
+  /**
+   * Mask one interior object node. Returns the surviving object, or
+   * undefined when the node is pruned entirely. Falsy children are carried
+   * through untouched (they advertise nothing, so there is nothing to mask).
+   */
+  const maskNode = (node: Record<string, unknown>, path: string): Record<string, unknown> | undefined => {
+    if (denied(path)) {
+      dropped.push(path);
+      return undefined;
+    }
+
+    const survivors: Record<string, unknown> = {};
+    let advertised = 0;
+    let survived = 0;
+
+    for (const [key, value] of Object.entries(node)) {
+      if (value === undefined) continue;
+      if (!value) {
+        // false / 0 / '' advertise nothing — preserve for fidelity.
+        survivors[key] = value;
+        continue;
+      }
+      advertised++;
+      const childPath = path ? `${path}.${key}` : key;
+
+      if (isPlainObject(value)) {
+        const masked = maskNode(value, childPath);
+        if (masked !== undefined) {
+          survivors[key] = masked;
+          survived++;
+        }
+        continue;
+      }
+
+      // Truthy leaf.
+      if (keep(childPath)) {
+        survivors[key] = value;
+        survived++;
+      } else {
+        dropped.push(childPath);
+      }
+    }
+
+    if (advertised === 0) {
+      // No truthy children: the object itself is the advert (e.g.
+      // `inferenceRequest: {}`), so its own path decides.
+      if (keep(path)) return survivors;
+      dropped.push(path);
+      return undefined;
+    }
+    if (survived > 0) {
+      return survivors;
+    }
+
+    // Every advertised child was masked. An object-capability keeps its
+    // (still-granted) hull; a namespace holds no authority of its own and
+    // is pruned, recording the bare path for inbound enforcement.
+    if (OBJECT_CAPABILITY_PATHS.has(path) && keep(path)) {
+      return survivors;
+    }
+    dropped.push(path);
+    return undefined;
+  };
+
+  const masked: Record<string, unknown> = {};
+  const source = capabilities as unknown as Record<string, unknown>;
+
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+
+    if (UNMASKABLE_KEYS.has(key) || !value) {
+      masked[key] = value;
+      continue;
+    }
+
+    if (isPlainObject(value)) {
+      const node = maskNode(value, key);
+      if (node !== undefined) {
+        masked[key] = node;
+      }
+      continue;
+    }
+
+    // Truthy leaf at the top level (booleans, or `channels: true` from
+    // servers that advertise the boolean form).
+    if (keep(key)) {
+      masked[key] = value;
+    } else {
+      dropped.push(key);
+    }
+  }
+
+  return { capabilities: masked as unknown as McplCapabilities, dropped };
+}