@animalabs/agent-framework 0.32.0 → 0.34.0

package/dist/src/gate/event-gate.js

@@ -15,10 +15,16 @@ import { cutToFit, quotedJson, quotedValue, suppliedValue } from '../supplied-te
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
+import { SuppressScripts } from './suppress-scripts.js';
+import { firstCatchAll, namesSomething } from './rule-scope.js';
 import { canonical, duplicateName, lastRecipePath, noChanges, reconcileLine, reconcileWithRecipe } from './recipe-reconcile.js';
 import { closestNames, isNearMiss } from '../closest-names.js';
 import { MAX_TIMER_MS } from '../deadline-timer.js';
 import { safeSlice } from '../safe-slice.js';
+import { failureWords } from '../failure-text.js';
+import { JudgeFailure } from './reply-judge.js';
+import { isSystemNotice } from '../mcpl/tags.js';
+import { appendAll } from '../append-all.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -102,15 +108,25 @@ function isMetadataTruthy(value) {
     return Boolean(value);
 }
 /**
- * Provenance of a batched wake: the newest ADDRESSED channel-bearing event
- * wins (mention / reply / DM outranks newer ambient chatter — the framework's
- * own locus rule); else the newest channel-bearing event. Channel, author and
- * addressed all come from that one event, so they can never disagree.
+ * Provenance of a batched wake: the newest ADDRESSED event that names a
+ * channel or an author wins (mention / reply / DM outranks newer ambient
+ * chatter — the framework's own locus rule); else the newest event that
+ * names either. An addressed event's resolved route counts as its channel;
+ * an ambient one's doesn't. Channel, author and addressed all come from
+ * that one event, so they can never disagree. A `chat:system` notice is
+ * never chosen for the batch's route, channel or addressed flag, even one
+ * addressed by its place (a pin in a DM), since a notice never decides where
+ * the agent's speech goes; a coalesced render whose latest occurrence is a
+ * notice isn't taken as one (GateEventInfo.folds). A batch with no such event
+ * carries only its `batchChannels` when it has them; else its chosen event is
+ * its newest notice that has an author, of which it takes only the author
+ * and time.
  */
 export function wakeProvenance(events) {
+    const said = events.filter((e) => !e.systemNotice);
     let newest;
     let newestAddressed;
-    for (const e of events) {
+    for (const e of said) {
         // A resolved route counts as naming a channel only for an ADDRESSED
         // event: a push whose origin declares only `mcplChannelId` (no raw
         // channel id, no author) is still a routable addressed message, and
@@ -126,22 +142,40 @@ export function wakeProvenance(events) {
             newestAddressed = e;
     }
     const pick = newestAddressed ?? newest;
-    if (!pick)
-        return undefined;
+    const channels = said.some((e) => e.addressed) ? [] : batchRoutes(said);
+    if (!pick && channels.length === 0) {
+        const notice = events.reduce((n, e) => (e.systemNotice && e.authorId && (!n || e.timestamp >= n.timestamp) ? e : n), undefined);
+        return notice ? { counterparty: counterpartyOf(notice), at: notice.timestamp } : undefined;
+    }
     // push-event channel ids are the adapter's raw ids (a Discord snowflake):
     // not a composite channel id, so not reported as one
-    const channelId = pick.channelId && pick.eventType !== 'mcpl:push-event' ? pick.channelId : undefined;
-    const ns = pick.serverId || (pick.channelId ? pick.channelId.split(':')[0] : '') || 'channel';
+    const channelId = pick?.channelId && pick.eventType !== 'mcpl:push-event' ? pick.channelId : undefined;
     return {
         ...(channelId ? { channelId } : {}),
-        ...(pick.authorId ? { counterparty: `${ns}:user:${pick.authorId}` } : {}),
-        ...(pick.addressed ? { addressed: true } : {}),
-        ...(pick.addressed && pick.routeChannelId
+        ...(pick?.authorId ? { counterparty: counterpartyOf(pick) } : {}),
+        ...(pick?.addressed ? { addressed: true } : {}),
+        ...(pick?.addressed && pick.routeChannelId
             ? { routeChannelId: pick.routeChannelId, ...(pick.serverId ? { routeServerId: pick.serverId } : {}) }
             : {}),
-        at: pick.timestamp,
+        ...(channels.length > 0 ? { batchChannels: channels } : {}),
+        ...(pick ? { at: pick.timestamp } : {}),
     };
 }
+function counterpartyOf(e) {
+    const ns = e.serverId || (e.channelId ? e.channelId.split(':')[0] : '') || 'channel';
+    return `${ns}:user:${e.authorId}`;
+}
+function batchRoutes(events) {
+    const routes = [];
+    for (const e of events) {
+        if (!e.routeChannelId)
+            continue;
+        if (routes.some((r) => r.channelId === e.routeChannelId && r.serverId === e.serverId))
+            continue;
+        routes.push({ channelId: e.routeChannelId, ...(e.serverId ? { serverId: e.serverId } : {}) });
+    }
+    return routes;
+}
 /** A `[Gate: …]` line's reference to messages already in the window: how
  *  many, in which channel, and how long ago the oldest arrived, as of `now`. */
 function referenceLine(count, channel, oldest, now) {
@@ -252,7 +286,7 @@ function behaviorFingerprint(b) {
 // file for a null or a "" (a passthrough, a behavior's kind, gate.json's
 // default), it now loads without it.
 const CONFIG_FIELDS = ['default', 'policies'];
-const POLICY_FIELDS = ['name', 'match', 'behavior', 'resets', 'passthrough'];
+const POLICY_FIELDS = ['name', 'match', 'behavior', 'resets', 'passthrough', 'suppress'];
 const MATCH_FIELDS = [
     'scope', 'source', 'channel', 'mount', 'pathGlob', 'tagsAny', 'tagsAll', 'tagsNone', 'metadataTrue', 'filter',
 ];
@@ -261,6 +295,7 @@ const BEHAVIOR_KINDS = ['debounce', 'rate_limit', 'passive_sample', 'judge'];
 const RATE_LIMIT_FIELDS = ['tokens', 'refillIntervalMs', 'keyBy'];
 const PASSIVE_SAMPLE_FIELDS = ['every', 'keyBy'];
 const JUDGE_FIELDS = ['debounceMs', 'maxWaitMs', 'instructions'];
+const SUPPRESS_FIELDS = ['description', 'script'];
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -650,6 +685,7 @@ function readRule(raw, unnamed, file = 'gate.json', named = asGateNames) {
     const match = readMatch(r, obj.match);
     const resets = readResets(r, obj.resets);
     const passthrough = readPassthrough(r, obj.passthrough, kind);
+    const suppress = readSuppress(r, obj.suppress, obj.behavior, match, obj.match);
     const reading = {
         where: r.where, problems: r.problems, notes: r.notes, quiet: kind === 'skip' || kind === 'defer' || r.noTokens === true,
     };
@@ -659,6 +695,8 @@ function readRule(raw, unnamed, file = 'gate.json', named = asGateNames) {
             policy.resets = resets;
         if (passthrough)
             policy.passthrough = true;
+        if (suppress)
+            policy.suppress = suppress;
         reading.policy = policy;
         if (r.matchesAll)
             reading.matchesAll = true;
@@ -1071,8 +1109,7 @@ function readMatch(r, value) {
     // Left with nothing that narrows it once something in it was named, it
     // matches every event. Empty lists and nulls alone always meant no
     // constraint, and name nothing.
-    const narrows = Object.entries(match).some(([field, v]) => !(field === 'scope' && Array.isArray(v) && v.length === 0));
-    if (!narrows && r.problems.length + r.notes.length > named)
+    if (!matchNarrows(match) && r.problems.length + r.notes.length > named)
         r.matchesAll = true;
     return match;
 }
@@ -1120,6 +1157,137 @@ function readPassthrough(r, value, kind) {
     });
     return false;
 }
+/** Whether a match narrows what it matches: anything but an empty scope. */
+export function matchNarrows(match) {
+    return Object.entries(match).some(([field, v]) => !(field === 'scope' && Array.isArray(v) && v.length === 0));
+}
+/**
+ * Whether a suppress rule's match names what it hides: an event type, or a
+ * source, channel, mount, path or tag pattern that isn't only wildcards
+ * (namesSomething), a metadata flag, or a content filter. A pattern of
+ * wildcards alone, such as `source: "*"`, or only `tagsNone`, takes every
+ * event, which a suppress rule may not.
+ */
+function suppressMatchNarrows(match) {
+    if ((match.scope ?? []).length > 0 || (match.metadataTrue ?? []).length > 0 || match.filter !== undefined)
+        return true;
+    if ([match.source, match.channel, match.mount, match.pathGlob].some(namesSomething))
+        return true;
+    return [...(match.tagsAny ?? []), ...(match.tagsAll ?? [])].some(namesSomething);
+}
+/** Longest suppress description, in characters: the review sends it with every rule it judges. */
+export const MAX_SUPPRESS_DESCRIPTION = 2_000;
+/** Longest suppress script, in characters. */
+export const MAX_SUPPRESS_SCRIPT = 20_000;
+const SUPPRESS_EXAMPLE = '{"description": "the eye going on and off"}';
+/**
+ * A rule's `suppress`. Every problem with it is read as a rule that doesn't
+ * suppress, which is how a release without suppression reads the rule:
+ * its behavior then decides the event, and the event is rendered. The
+ * behavior has to be written out as "defer" (or "skip"), not left to
+ * default, because such a release reads a rule with no behavior as
+ * "always" and would wake the agent on every event the rule was meant to
+ * hide.
+ */
+function readSuppress(r, value, behavior, match, rawMatch) {
+    if (value === undefined || value === false)
+        return undefined;
+    const without = "so the rule doesn't suppress, and its behavior decides its events as for any other rule";
+    if (!isPlainObject(value)) {
+        r.problems.push({ text: `suppress is ${shownValue(value)}, where an object such as ${SUPPRESS_EXAMPLE} is needed`, read: without });
+        return undefined;
+    }
+    const before = r.problems.length;
+    // A script given as null or "" is a script that's missing, not one left
+    // out: read as left out, the rule would hide every event its match takes.
+    const { script: _givenScript, ...rest } = value;
+    const emptyScript = Object.hasOwn(value, 'script') && (value.script === null || value.script === '');
+    if (emptyScript) {
+        r.problems.push({ text: `suppress.script is ${shownValue(value.script)}, where the source of a function such as "(event, state) => false" is needed`, read: without });
+    }
+    const given = withoutEmpty(`${r.where}: suppress`, emptyScript ? rest : value, r.notes);
+    const reported = r.problems.length;
+    readFieldNames(r, 'suppress', given, SUPPRESS_FIELDS);
+    // A field it doesn't read can't be left aside here, as elsewhere in a
+    // rule: one meant as a condition, left out, would hide every event the
+    // match takes.
+    const unread = Object.keys(given).filter((key) => !SUPPRESS_FIELDS.includes(key));
+    if (unread.length > 0 && r.problems.length === reported) {
+        r.problems.push({ text: `suppress has ${quotedList(unread)}, and a suppress rule reads only "description" and "script"`, read: without });
+    }
+    const config = { description: '' };
+    if (typeof given.description !== 'string' || given.description.trim() === '') {
+        r.problems.push({
+            text: `suppress.description is ${given.description === undefined ? 'missing' : shownValue(given.description)}, where the rule's `
+                + 'purpose in a few words is needed: the review checks what the rule hides against it',
+            read: without,
+        });
+    }
+    else if ([...given.description].length > MAX_SUPPRESS_DESCRIPTION) {
+        r.problems.push({
+            text: `suppress.description is ${[...given.description].length.toLocaleString('en-US')} characters, over the `
+                + `${MAX_SUPPRESS_DESCRIPTION.toLocaleString('en-US')} allowed`,
+            read: without,
+        });
+    }
+    else {
+        config.description = given.description.trim();
+    }
+    if (given.script !== undefined) {
+        if (typeof given.script !== 'string' || given.script.trim() === '') {
+            r.problems.push({ text: `suppress.script is ${shownValue(given.script)}, where the source of a function such as "(event, state) => false" is needed`, read: without });
+        }
+        else if ([...given.script].length > MAX_SUPPRESS_SCRIPT) {
+            r.problems.push({
+                text: `suppress.script is ${[...given.script].length.toLocaleString('en-US')} characters, over the ${MAX_SUPPRESS_SCRIPT.toLocaleString('en-US')} allowed`,
+                read: without,
+            });
+        }
+        else {
+            // Parsed only, never run here: the script runs on its worker.
+            try {
+                new Function(`"use strict";\nreturn (${given.script}\n);`);
+                config.script = given.script;
+            }
+            catch (e) {
+                r.problems.push({ text: `suppress.script doesn't parse (${quotedValue(errorText(e))})`, read: without });
+            }
+        }
+    }
+    if (behavior !== 'defer' && behavior !== 'skip') {
+        r.problems.push({
+            text: `suppress is given, and a rule that suppresses needs "behavior": "defer" written out, so a release that `
+                + `doesn't know "suppress" defers its events instead of waking you on them; it has `
+                + (behavior === undefined ? 'no behavior' : `behavior ${shownValue(behavior)}`),
+            read: without,
+        });
+    }
+    // A match field the gate doesn't read would, left aside, hide more than was
+    // written: the condition it was meant to add is gone.
+    if (isPlainObject(rawMatch)) {
+        const rawFilter = isPlainObject(rawMatch.filter) ? Object.keys(rawMatch.filter).filter((key) => !FILTER_FIELDS.includes(key)).map((key) => `filter.${key}`) : [];
+        const unreadMatch = [...Object.keys(rawMatch).filter((key) => !MATCH_FIELDS.includes(key)), ...rawFilter];
+        if (unreadMatch.length > 0) {
+            r.problems.push({ text: `suppress is given, and match has ${quotedList(unreadMatch)}, which the gate doesn't read, so the rule would hide more than was written`, read: without });
+        }
+    }
+    if (!suppressMatchNarrows(match)) {
+        r.problems.push({
+            text: 'suppress is given, and the rule\'s match names nothing it hides: a suppress rule needs a match that names '
+                + 'a scope, a source, a channel, tags, a mount or path, metadata or a filter (not a pattern of wildcards alone, or tagsNone alone), '
+                + 'so it can\'t hide everything',
+            read: without,
+        });
+    }
+    // Only a rule read without any problem suppresses: one read past a problem
+    // (a slip of a field, a match read without a part of it) matches more, or
+    // decides otherwise, than its author wrote, and hiding is what can't be
+    // seen to go wrong. Its behavior decides its events instead.
+    if (before > 0) {
+        r.problems.push({ text: 'suppress is given on a rule with problems, and a rule suppresses only when it has none', read: without });
+    }
+    return r.problems.length === 0 ? config : undefined;
+}
 /**
  * A rule with no problem is in force as written. One with a problem is read
  * past it, the way earlier releases read it, so it wakes the agent wherever
@@ -1266,7 +1434,7 @@ function readConfig(raw, file, start) {
         }
     }
     for (const rule of rules)
-        sentences.push(...readingSentences(rule.reading, rule.outcome));
+        appendAll(sentences, readingSentences(rule.reading, rule.outcome));
     // A list with no rules, or none the gate reads, where no sentence above said it has none.
     if (notUsed !== undefined && !sentences.some((said) => said.includes(notUsed))) {
         sentences.push(`${File} has no rules${rules.length > 0 ? ' but ones the gate leaves out' : ''}, so ${notUsedWhy}.`);
@@ -1613,7 +1781,9 @@ export function findShadowedPolicies(policies, eventTypesFrom) {
     const out = [];
     for (let i = 0; i < policies.length; i++) {
         const earlier = policies[i];
-        if (earlier.passthrough)
+        // A suppress rule lets addressed events and the heartbeat's by, so it
+        // can't be said to take every event of a later rule.
+        if (earlier.passthrough || earlier.suppress)
             continue;
         for (let j = i + 1; j < policies.length; j++) {
             const found = subsumedEventTypes(earlier, policies[j], eventTypesFrom);
@@ -1645,15 +1815,53 @@ export function formatShadowWarning(w) {
         + `Nothing to do unless ${later} is meant for ${types} events; then ${move}. `
         + `A scope on ${later} naming the event types it's for clears this note.`;
 }
+function judgeFailureWords(err) {
+    if (err instanceof JudgeFailure)
+        return err.message;
+    return err instanceof Error ? failureWords(err, 'the call failed') : 'the call failed';
+}
 /** The text of a thrown value, for a log line. It never throws itself, whatever was thrown. */
 function errorText(err) {
     try {
+        if (err instanceof JudgeFailure && err.detail !== undefined)
+            return `${err.message} (${err.detail})`;
         return err instanceof Error ? err.message : String(err);
     }
     catch {
         return 'a value that could not be printed';
     }
 }
+class PartialDelivery extends Error {
+    woke;
+    notWoken;
+    constructor(woke, notWoken, cause) {
+        super(errorText(cause), { cause });
+        this.woke = woke;
+        this.notWoken = notWoken;
+    }
+}
+/**
+ * Runs a batch's delivery to `woken`, which pushes each agent it wakes to
+ * `woke`: a throw once any is woken is a PartialDelivery naming them and the
+ * rest; one before any wake is thrown as it is.
+ */
+function deliveredTracking(woke, woken, deliver) {
+    try {
+        deliver();
+    }
+    catch (err) {
+        if (woke.length === 0)
+            throw err;
+        throw new PartialDelivery(woke, woken.filter((name) => !woke.includes(name)), err);
+    }
+}
+function deliveredInPart(err) {
+    if (!(err instanceof PartialDelivery))
+        return undefined;
+    const one = err.notWoken.length === 1;
+    return `woke ${joinedList(err.woke)}, and delivering it threw (${err.message}), `
+        + `so it's dropped for ${joinedList(err.notWoken)}, who ${one ? "isn't" : "aren't"} woken`;
+}
 /**
  * Run a caller's callback once the change it's told of is made and traced. A
  * throw from it is logged, not thrown, so the call answers as the change it
@@ -1766,6 +1974,8 @@ export class EventGate {
     droppedBufferedEvents = 0;
     // Per-policy stats
     stats = new Map();
+    /** Suppress rules' scripts and their state (suppress-scripts.ts), kept beside gate.json. */
+    suppressScripts;
     // The shadow lint's last findings (see refreshShadowWarnings), recomputed
     // on every config change and fingerprinted so an unchanged set doesn't
     // re-trace.
@@ -1823,6 +2033,11 @@ export class EventGate {
     now;
     constructor(opts) {
         this.configPath = opts.configPath;
+        // Before the rules are read: a start's merge can clear a rule's state, its script's included.
+        this.suppressScripts = new SuppressScripts({
+            statePath: join(dirname(opts.configPath), 'suppress-state.json'),
+            ...(opts.suppressScriptTimeoutMs !== undefined ? { timeoutMs: opts.suppressScriptTimeoutMs } : {}),
+        });
         this.privilegedUsersPath = opts.privilegedUsersPath;
         this.emitTrace = opts.emitTrace;
         this.addMessageFn = opts.addMessage;
@@ -2108,7 +2323,6 @@ export class EventGate {
                 ...changes,
                 // Every name the start added to gate.json, as an append's trace gave.
                 addedPolicies: names,
-                timestamp: Date.now(),
             });
         }
         if (!appended && (!last.recipe || canonical({ rules: last.recipe.rules, default: last.recipe.default }) !== canonical({ rules: starting.rules.map((rule) => rule.raw), default: given.default }))) {
@@ -2208,7 +2422,6 @@ export class EventGate {
                 type: 'gate:config-error',
                 error: why,
                 configPath: this.configPath,
-                timestamp: Date.now(),
             });
         }
         this.configError = problem;
@@ -2358,8 +2571,11 @@ export class EventGate {
     clearStateFor(was, next) {
         const behaviorsByName = (config) => {
             const byName = new Map();
-            for (const p of config.policies)
-                byName.set(p.name, [...(byName.get(p.name) ?? []), behaviorFingerprint(p.behavior)]);
+            for (const p of config.policies) {
+                // A suppress rule's script is part of what it is: a changed script starts from a fresh state.
+                const fingerprint = behaviorFingerprint(p.behavior) + (p.suppress ? ` suppress:${p.suppress.script ?? ''}` : '');
+                byName.set(p.name, [...(byName.get(p.name) ?? []), fingerprint]);
+            }
             return new Map([...byName].map(([name, behaviors]) => [name, JSON.stringify(behaviors)]));
         };
         const before = behaviorsByName(was);
@@ -2412,7 +2628,6 @@ export class EventGate {
                 policyCount: newConfig.policies.length,
                 removedPolicies: removedPolicies.length > 0 ? removedPolicies : undefined,
                 stateClearedPolicies: stateClearedPolicies.length > 0 ? stateClearedPolicies : undefined,
-                timestamp: now,
             });
         }
         catch {
@@ -2523,7 +2738,6 @@ export class EventGate {
             configPath: this.configPath,
             policyName: policy.name,
             replaced: idx >= 0,
-            timestamp: Date.now(),
         });
         if (ignored.length > 0) {
             // A caller that doesn't take the notes still gets them said, in the log.
@@ -2570,7 +2784,6 @@ export class EventGate {
             type: 'gate:policy-removed',
             configPath: this.configPath,
             policyName: name,
-            timestamp: Date.now(),
         });
         return true;
     }
@@ -2585,6 +2798,15 @@ export class EventGate {
         const current = read.state === 'loaded' ? read.config : this.config;
         return current.policies.map((p) => p.name);
     }
+    /** The rules in force, in order (copies): what the last decision was made by. */
+    policiesInForce() {
+        return this.config.policies.map((p) => structuredClone(p));
+    }
+    /** The rule in force by this name (a copy), or undefined. */
+    policyInForce(name) {
+        const p = this.config.policies.find((x) => x.name === name);
+        return p ? structuredClone(p) : undefined;
+    }
     /** @internal For `wake_add_rule`'s and `wake_remove_rule`'s refusals; not a host API. */
     ruleNamesForChange() {
         const edit = this.rulesForChange();
@@ -2763,7 +2985,6 @@ export class EventGate {
                     matchedPolicy: 'asleep',
                     trigger: false,
                     behavior: 'skip',
-                    timestamp: this.now(),
                 });
                 return { trigger: false, policyName: 'asleep', behavior: 'skip' };
             }
@@ -2786,6 +3007,12 @@ export class EventGate {
         }
         else {
             for (const compiled of this.compiledPolicies) {
+                // A suppress rule doesn't decide a wake for an event suppression was
+                // asked about: one it takes was suppressed before the gate was asked,
+                // and one that reaches here is one it let by. Where suppression wasn't
+                // asked (no view to hide it from), it defers, as its behavior says.
+                if (compiled.policy.suppress && this.passesOverSuppress(info))
+                    continue;
                 if (!this.compiledMatches(compiled, info))
                     continue;
                 const candidate = this.computeDecision(compiled.policy, info);
@@ -2822,7 +3049,6 @@ export class EventGate {
             trigger: decision.trigger,
             behavior: formatBehavior(decision.behavior),
             ...(observed.length > 0 ? { observed } : {}),
-            timestamp: this.now(),
         });
         return decision;
     }
@@ -2843,7 +3069,6 @@ export class EventGate {
             behavior: formatBehavior(policy.behavior),
             eventType: info.eventType,
             source: info.serverId || undefined,
-            timestamp: this.now(),
         });
         if (policy.behavior === 'defer' || policy.behavior === 'skip') {
             // Report the configured name faithfully ('defer' or legacy 'skip').
@@ -2975,6 +3200,7 @@ export class EventGate {
         const debounce = this.debounceTimers.get(name);
         if (debounce)
             clearTimeout(debounce.timer);
+        this.suppressScripts.forget(name);
         this.rateLimitBuckets.delete(name);
         this.passiveSampleCounters.delete(name);
         this.rateLimitDenied.delete(name);
@@ -3032,6 +3258,8 @@ export class EventGate {
      */
     probe(info) {
         for (const compiled of this.compiledPolicies) {
+            if (compiled.policy.suppress && this.passesOverSuppress(info))
+                continue; // as evaluate does
             if (!this.compiledMatches(compiled, info))
                 continue;
             const trigger = this.wouldTrigger(compiled.policy, info);
@@ -3042,6 +3270,140 @@ export class EventGate {
         const trigger = (this.config.default ?? 'always') === 'always';
         return { trigger, policyName: null, behavior: this.config.default ?? 'always' };
     }
+    /**
+     * The suppress rule that takes this event, or null when none does.
+     * Side-effect-free, like probe: no counter moves, no batch forms, nothing
+     * is traced, and a rule's script runs on a copy of its state, which is
+     * then dropped. (A closure a script builds for itself is its own, and a
+     * dry run's timeout counts toward setting a script aside, as it costs the same.) The probe table and other dry runs ask this; the
+     * framework asks decideSuppression instead, once per event.
+     *
+     * It reads the rules as evaluate does, first match deciding: a rule ahead
+     * of the suppress rule that matches the event decides it instead (it isn't
+     * suppressed), unless it's a passthrough rule that wouldn't fire. A rule
+     * with a script (`suppress.script`) takes an event its match takes only
+     * when the script says to hide it; otherwise the event goes on to the rules
+     * after it, as one the rule doesn't match does. Sleep and gate.js aren't
+     * consulted: they decide wakes, and suppression decides what's rendered.
+     *
+     * Never suppressed, whatever the rules say: an event addressed to the
+     * agent (tagged `chat:addressed`: a mention, a reply, a DM) and the
+     * heartbeat's (the agent's own clock). A suppress rule lets them by to the
+     * rules after it, and its script isn't asked. The framework itself never
+     * asks about console or API input.
+     */
+    suppressionFor(info) {
+        return this.walkSuppression(info, false);
+    }
+    /**
+     * suppressionFor, for an event that is arriving now: each script asked
+     * keeps the state it leaves, whatever later rules do with the event, and a
+     * suppressed event counts in the passthrough rules ahead of its rule. Ask
+     * once per event.
+     */
+    decideSuppression(info) {
+        return this.walkSuppression(info, true);
+    }
+    walkSuppression(info, commit) {
+        this.reloadIfChanged();
+        this.syncSuppressScripts();
+        if (info.serverId === 'heartbeat')
+            return null;
+        const addressed = Array.isArray(info.tags) && info.tags.includes('chat:addressed');
+        let event;
+        const observers = [];
+        for (const compiled of this.compiledPolicies) {
+            if (!this.compiledMatches(compiled, info))
+                continue;
+            const suppress = compiled.policy.suppress;
+            if (suppress) {
+                if (addressed)
+                    continue;
+                if (suppress.script !== undefined) {
+                    event ??= this.suppressScriptEvent(info);
+                    const ran = this.suppressScripts.run(compiled.policy.name, event, commit);
+                    // A script that failed shows the event: it goes on to the rules after.
+                    if (!ran || !('hide' in ran) || !ran.hide)
+                        continue;
+                }
+                // A suppressed event never reaches evaluate, so the passthrough rules
+                // ahead of this one count it here, as evaluate would have: none of
+                // them fires for it, and each fires on its schedule. A dry run counts
+                // nothing.
+                if (commit)
+                    for (const observer of observers)
+                        this.computeDecision(observer, info);
+                return compiled.policy.name;
+            }
+            if (compiled.policy.passthrough && !this.wouldTrigger(compiled.policy, info)) {
+                observers.push(compiled.policy);
+                continue;
+            }
+            return null;
+        }
+        return null;
+    }
+    /** Whether evaluate and probe pass over a suppress rule for this event: suppression was asked about it, or it's one suppression always lets by. */
+    passesOverSuppress(info) {
+        return info.suppressionAsked === true || info.serverId === 'heartbeat'
+            || (Array.isArray(info.tags) && info.tags.includes('chat:addressed'));
+    }
+    /** The scripts in step with the rules in force (SuppressScripts.sync: only changed ones are compiled). */
+    syncSuppressScripts() {
+        this.suppressScripts.sync(this.config.policies.map((p) => ({ name: p.name, ...(p.suppress?.script !== undefined ? { script: p.suppress.script } : {}) })));
+    }
+    /** What a suppress script is given for an event: plain JSON, its metadata included where it can be. */
+    suppressScriptEvent(info) {
+        let metadata = {};
+        try {
+            metadata = JSON.parse(JSON.stringify(info.metadata ?? {}));
+        }
+        catch {
+            metadata = {};
+        }
+        const channel = this.routeChannelFor(info) ?? (info.channelId || undefined);
+        const author = this.extractAuthorId(info.metadata);
+        return {
+            eventType: info.eventType,
+            source: info.serverId,
+            ...(channel ? { channel } : {}),
+            ...(author ? { author } : {}),
+            tags: [...(info.tags ?? [])],
+            text: info.content,
+            at: this.now(),
+            metadata,
+        };
+    }
+    /**
+     * Whether a suppress script compiles to a function, on the scripts' worker:
+     * an error's text, or null. wake_add_rule asks before it saves a rule.
+     */
+    checkSuppressScript(script) {
+        return this.suppressScripts.check(script);
+    }
+    /** A suppress rule's script state as it stands (a copy), for a host or a test. */
+    suppressScriptState(name) {
+        this.syncSuppressScripts();
+        return this.suppressScripts.stateOf(name);
+    }
+    /**
+     * Count a row the framework suppressed by `name` (suppressionFor's
+     * answer) once it's written. The rule's stats count it as a match, so
+     * gate_status shows how many events each suppress rule took since start.
+     */
+    noteSuppressed(name, info) {
+        const policyStats = this.stats.get(name) ?? { matchCount: 0, lastMatchTimestamp: null };
+        policyStats.matchCount++;
+        policyStats.lastMatchTimestamp = this.now();
+        this.stats.set(name, policyStats);
+        this.emitTrace({
+            type: 'gate:suppressed',
+            policyName: name,
+            eventType: info.eventType,
+            ...(info.serverId ? { serverId: info.serverId } : {}),
+            ...(info.channelId ? { channelId: info.channelId } : {}),
+        });
+    }
     /** The canonical synthetic events the probe table runs: chat shapes as MCPL delivers them, and a heartbeat. */
     probeEvents() {
         const chat = (label, eventType, metadata, tags) => ({
@@ -3100,7 +3462,12 @@ export class EventGate {
      */
     probeTable() {
         return this.probeEvents().map(({ label, info }) => {
-            const d = this.probe(info);
+            const suppressedBy = this.suppressionFor(info);
+            if (suppressedBy !== null) {
+                return { probe: label, eventType: info.eventType, policy: suppressedBy, behavior: 'suppress', wouldWake: false };
+            }
+            // As admission asks: suppression first, so a script that says show lets the probe on.
+            const d = this.probe({ ...info, suppressionAsked: true });
             return {
                 probe: label,
                 eventType: info.eventType,
@@ -3147,7 +3514,6 @@ export class EventGate {
                 type: 'gate:shadow-warnings',
                 reason,
                 warnings: warnings.map(formatShadowWarning),
-                timestamp: this.now(),
             });
         }
     }
@@ -3201,9 +3567,11 @@ export class EventGate {
             authorId: this.extractAuthorId(info.metadata) ?? undefined,
             serverId: info.serverId || undefined,
             addressed: Array.isArray(info.tags) && info.tags.includes('chat:addressed'),
+            ...(isSystemNotice(info.tags) && !info.folds ? { systemNotice: true } : {}),
             routeChannelId: this.routeChannelFor(info),
             ...(typeof info.metadata?.messageId === 'string' ? { messageId: info.metadata.messageId } : {}),
             ...(typeof info.metadata?.eventId === 'string' ? { eventId: info.metadata.eventId } : {}),
+            ...(info.recipients !== undefined ? { recipients: [...info.recipients] } : {}),
         };
         const existing = this.debounceTimers.get(policy.name);
         // A judge's maxWaitMs caps how far new events push the batch back: it's
@@ -3258,15 +3626,14 @@ export class EventGate {
         }
         catch (err) {
             const one = events.length === 1;
-            console.error(`[gate] Rule ${quotedValue(policyName)}: its pending batch of ${events.length} ${one ? 'event' : 'events'} couldn't be delivered `
-                + `(${errorText(err)}), so the batch is dropped`);
+            console.error(`[gate] Rule ${quotedValue(policyName)}: its pending batch of ${events.length} ${one ? 'event' : 'events'} `
+                + (deliveredInPart(err) ?? `couldn't be delivered (${errorText(err)}), so the batch is dropped`));
             return;
         }
         this.emitTrace({
             type: 'gate:debounce-delivered',
             policyName,
             eventCount: events.length,
-            timestamp: Date.now(),
         });
     }
     // =========================================================================
@@ -3286,11 +3653,37 @@ export class EventGate {
                 type: 'gate:held-dropped',
                 dropped: batched.length - events.length,
                 channels: [...new Set(batched.filter((e) => !events.includes(e)).map(heldAt))],
-                timestamp: this.now(),
             });
         }
         if (events.length === 0)
             return;
+        // Who each delivery woke, so that a throw after a wake is told as a
+        // delivery in part (PartialDelivery), the batch dropped only for those
+        // it didn't wake.
+        const woke = [];
+        if (events.every((e) => e.recipients === undefined)) {
+            const names = this.getAgentNamesFn();
+            deliveredTracking(woke, names, () => this.deliverBatch(events, names, undefined, woke));
+            return;
+        }
+        const woken = new Set(events.flatMap((e) => e.recipients ?? []));
+        if (events.some((e) => e.recipients === undefined))
+            for (const name of this.getAgentNamesFn())
+                woken.add(name);
+        const groups = new Map();
+        for (const agentName of woken) {
+            const seen = events.filter((e) => e.recipients === undefined || e.recipients.includes(agentName));
+            const key = seen.map((e) => events.indexOf(e)).join(',');
+            const group = groups.get(key) ?? { agents: [], events: seen };
+            group.agents.push(agentName);
+            groups.set(key, group);
+        }
+        deliveredTracking(woke, [...woken], () => {
+            for (const group of groups.values())
+                this.deliverBatch(group.events, group.agents, group.agents, woke);
+        });
+    }
+    deliverBatch(events, woken, audience, woke) {
         const policyNames = [...new Set(events.map(e => e.policyName))];
         // Events whose content the framework already stored at arrival (MCPL
         // channel-incoming / push-event) get a compact REFERENCE — re-quoting
@@ -3346,7 +3739,12 @@ export class EventGate {
         const text = `[${NOTICE_TAG.gate}: ${events.length} event${events.length > 1 ? 's' : ''} matched]\n\n${lines.join('\n')}`;
         const only = events.length === 1 && events[0].inContext ? events[0] : undefined;
         let line;
-        if (only && this.newestEntry(only)) {
+        // Where a line stored now landed, for the delivery agent's wake, as the
+        // self-wake's notice places its own (readsRowFor): a live turn that
+        // carried and answered the line drops the wake. Other agents' wakes stay
+        // plain by readsRowFor's rule.
+        const placement = {};
+        if (only && this.newestEntry(only, audience)) {
             const shownChannel = only.routeChannelId ?? only.channelId;
             line = {
                 entry: entryRef(only),
@@ -3360,29 +3758,31 @@ export class EventGate {
             this.addMessageFn('user', [{ type: 'text', text }], {
                 source: 'gate:debounce',
                 policies: policyNames,
-            });
+            }, undefined, placement, audience);
         }
         // Provenance of the batched wake (who/where woke the agent): the newest
         // ADDRESSED event first, else the newest event naming a channel or an
-        // author; channel + author + addressed from that ONE event. When that
-        // event addressed the agent and its registered channel is known,
-        // `routeChannelId` names the turn's speech locus too — the reply goes
-        // back to whoever addressed the agent, not to whichever channel last saw
-        // any traffic. Ambient-only batches set no locus. A batch whose line the
-        // gate left to the turn's start carries it too (`line`), one object
-        // shared by every agent the batch wakes, so it is written once.
+        // author, `chat:system` notices aside; channel + author + addressed from
+        // that ONE event. When that event addressed the agent and its registered
+        // channel is known, `routeChannelId` names the turn's speech locus too —
+        // the reply goes back to whoever addressed the agent, not to whichever
+        // channel last saw any traffic. Ambient-only batches set no locus, and
+        // name the channels they came from (`batchChannels`). A batch whose line
+        // the gate left to the turn's start carries it too (`line`), one object
+        // shared by every agent woken with these messages, so it is written once.
         const chosen = wakeProvenance(events);
         const provenance = line ? { ...chosen, line } : chosen;
-        for (const agentName of this.getAgentNamesFn()) {
-            this.requestInferenceFn(agentName, 'gate:debounce', 'gate', provenance);
+        for (const agentName of woken) {
+            this.requestInferenceFn(agentName, 'gate:debounce', 'gate', provenance, line ? undefined : placement);
+            woke?.push(agentName);
         }
     }
     /** isNewestEntry for one event; a callback fault keeps the line. */
-    newestEntry(event) {
+    newestEntry(event, recipients) {
         if (!this.isNewestEntryFn)
             return false;
         try {
-            return this.isNewestEntryFn(entryRef(event)) === true;
+            return this.isNewestEntryFn(entryRef(event), recipients) === true;
         }
         catch {
             return false;
@@ -3405,7 +3805,7 @@ export class EventGate {
             return;
         const deciding = this.judging.get(policyName);
         if (deciding) {
-            deciding.queued.push(...events);
+            appendAll(deciding.queued, events);
             this.capJudgeEvents(deciding.queued);
             return;
         }
@@ -3424,8 +3824,8 @@ export class EventGate {
         this.judging.set(policyName, state);
         const timedOut = new Promise((_, reject) => {
             state.timer = setTimeout(() => {
+                reject(new JudgeFailure(`the judge took more than ${this.judgeTimeoutMs} ms`));
                 abort.abort();
-                reject(new Error(`the judge took more than ${this.judgeTimeoutMs} ms`));
             }, this.judgeTimeoutMs);
             // Never keep the process alive on the judge's account.
             state.timer.unref?.();
@@ -3456,7 +3856,7 @@ export class EventGate {
     holdForJudge(policyName, events, judge) {
         const held = this.judgeHeld.get(policyName);
         if (held) {
-            held.events.push(...events);
+            appendAll(held.events, events);
             held.judge = judge;
             this.capJudgeEvents(held.events);
         }
@@ -3496,7 +3896,8 @@ export class EventGate {
      * the judge to weigh what waiting costs: each agent's pending self-wake
      * (skip_reply's wake_in_seconds), the end of a sleep, and the pending
      * batches of rules other than `exceptPolicy` (a debounce's wakes the agent
-     * when it fires; a judge rule's goes to the judge, so it only may).
+     * when it fires; a judge rule's goes to the judge, so it only may). A batch,
+     * and a sleep with no agent named, reach the gate's recipients alone.
      */
     upcomingWakes(agentNames, exceptPolicy) {
         const wakes = [];
@@ -3504,20 +3905,22 @@ export class EventGate {
         for (const name of agentNames) {
             const due = this.selfWakeDue.get(name);
             if (due && this.selfWakeTimers.has(name)) {
-                wakes.push({ at: due.at, certain: true, what: `${agentNames.length > 1 ? `${name}'s` : 'its'} own ${due.source} timer` });
+                wakes.push({ at: due.at, certain: true, kind: 'self-wake', what: `${agentNames.length > 1 ? `${name}'s` : 'its'} own ${due.source} timer` });
             }
         }
-        if (this.sleepUntil > now && (this.sleepAgent === undefined || agentNames.includes(this.sleepAgent))) {
-            wakes.push({ at: this.sleepUntil, certain: true, what: 'the end of its sleep' });
+        const recipients = this.getAgentNamesFn();
+        const recipient = agentNames.some((name) => recipients.includes(name));
+        if (this.sleepUntil > now && (this.sleepAgent === undefined ? recipient : agentNames.includes(this.sleepAgent))) {
+            wakes.push({ at: this.sleepUntil, certain: true, kind: 'sleep-end', what: 'the end of its sleep' });
         }
         for (const [name, state] of this.debounceTimers) {
-            if (name === exceptPolicy || state.events.length === 0)
+            if (!recipient || name === exceptPolicy || state.events.length === 0)
                 continue;
             const n = state.events.length;
             const batch = `${n} ${n === 1 ? 'event' : 'events'}`;
             wakes.push(state.judge
-                ? { at: state.dueAt, certain: false, what: `rule ${quotedValue(name)}'s batch of ${batch} goes to the judge` }
-                : { at: state.dueAt, certain: true, what: `rule ${quotedValue(name)}'s debounced batch of ${batch}` });
+                ? { at: state.dueAt, certain: false, kind: 'judge-batch', what: `rule ${quotedValue(name)}'s batch of ${batch} goes to the judge` }
+                : { at: state.dueAt, certain: true, kind: 'debounce', what: `rule ${quotedValue(name)}'s debounced batch of ${batch}` });
         }
         return wakes.sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
     }
@@ -3579,7 +3982,7 @@ export class EventGate {
         }
         const outcome = failed ? 'error' : verdict.reply ? 'reply' : 'wait';
         const reason = failed
-            ? (err !== undefined ? errorText(err) : 'the judge gave no verdict')
+            ? (err !== undefined ? judgeFailureWords(err) : 'the judge gave no verdict')
             : typeof verdict.reason === 'string' ? verdict.reason : '';
         const record = this.judgeRecords.get(policyName) ?? { verdicts: { reply: 0, wait: 0, error: 0 } };
         record.verdicts[outcome]++;
@@ -3602,7 +4005,7 @@ export class EventGate {
         }
         const wake = outcome === 'reply' || (outcome === 'error' && this.judgeOnError === 'wake');
         if (failed) {
-            console.error(`[gate] Rule ${quotedValue(policyName)}: the reply judge failed (${reason}), so its batch of ${state.events.length} `
+            console.error(`[gate] Rule ${quotedValue(policyName)}: the reply judge failed (${err !== undefined ? errorText(err) : reason}), so its batch of ${state.events.length} `
                 + `${state.events.length === 1 ? 'event' : 'events'} ${wake ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`);
         }
         this.emitTrace({
@@ -3616,7 +4019,6 @@ export class EventGate {
             ...(!failed && typeof verdict.inputTokens === 'number' ? { inputTokens: verdict.inputTokens } : {}),
             ...(!failed && typeof verdict.cacheReadTokens === 'number' ? { cacheReadTokens: verdict.cacheReadTokens } : {}),
             ...(!failed && typeof verdict.outputTokens === 'number' ? { outputTokens: verdict.outputTokens } : {}),
-            timestamp: Date.now(),
         });
         if (this.disposed)
             return;
@@ -3643,8 +4045,8 @@ export class EventGate {
         }
         catch (err) {
             const one = events.length === 1;
-            console.error(`[gate] a judged batch of ${events.length} ${one ? 'event' : 'events'} couldn't be delivered `
-                + `(${errorText(err)}), so the batch is dropped`);
+            console.error(`[gate] a judged batch of ${events.length} ${one ? 'event' : 'events'} `
+                + (deliveredInPart(err) ?? `couldn't be delivered (${errorText(err)}), so the batch is dropped`));
         }
     }
     changesJudgedContext(agentName) {
@@ -3713,8 +4115,8 @@ export class EventGate {
      * buffer through the same path a turn's end uses. Self-wake and sleep-expiry
      * timers deliberately do NOT route through this — their inference requests
      * are per-agent targeted pushes that the framework's quiesce wake gate parks
-     * and releases at resume, whereas the buffer's deliverEvents broadcasts a
-     * wake to every agent.
+     * and releases at resume, whereas the buffer's deliverEvents wakes every
+     * agent a batch is for.
      */
     setQuiesced(quiesced) {
         if (this.quiesced === quiesced)
@@ -3745,8 +4147,12 @@ export class EventGate {
                 }
                 catch (err) {
                     const one = events.length === 1;
-                    console.error(`[gate] ${events.length} ${one ? 'event' : 'events'} held for an agent's turn or the host's quiesce couldn't be `
-                        + `delivered (${errorText(err)}), so ${one ? "it's" : "they're"} dropped`);
+                    const held = `${events.length} ${one ? 'event' : 'events'}`;
+                    const partly = deliveredInPart(err);
+                    console.error(partly
+                        ? `[gate] a batch of ${held}, held for an agent's turn or the host's quiesce, ${partly}`
+                        : `[gate] ${held} held for an agent's turn or the host's quiesce couldn't be delivered (${errorText(err)}), `
+                            + `so ${one ? "it's" : "they're"} dropped`);
                 }
             });
         }
@@ -3815,7 +4221,6 @@ export class EventGate {
             matchedPolicy: 'asleep',
             trigger: false,
             behavior: 'skip',
-            timestamp: this.now(),
         });
         return { until: this.sleepUntil };
     }
@@ -3876,13 +4281,13 @@ export class EventGate {
                 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).
+            // before the inference request so it rides the wake turn: it is stored
+            // at once, and while a turn of the agent's is alive it is kept out of
+            // the window until the agent's next presentation point.
             const nowIso = new Date(this.now()).toISOString().slice(0, 19) + 'Z';
             // Deliver the notice into the WAKING agent's window — a self-wake
             // armed by a non-primary agent (e.g. a subconscious cadence) must not
@@ -3905,7 +4310,6 @@ export class EventGate {
             matchedPolicy: 'self-wake',
             trigger: false,
             behavior: 'skip',
-            timestamp: this.now(),
         });
         return { inMs: ms, armed: true };
     }
@@ -3953,7 +4357,6 @@ export class EventGate {
             matchedPolicy: 'asleep',
             trigger: true,
             behavior: 'always',
-            timestamp: this.now(),
         });
         const detail = note ? `${reason}: ${note}` : reason;
         const targets = agent ? [agent] : this.getAgentNamesFn();
@@ -4088,6 +4491,7 @@ export class EventGate {
         return { success: true, data: status };
     }
     getStatus() {
+        this.syncSuppressScripts();
         const policies = this.config.policies.map(p => {
             const stats = this.stats.get(p.name);
             const debounce = this.debounceTimers.get(p.name);
@@ -4096,6 +4500,9 @@ export class EventGate {
                 behavior: p.behavior,
                 matchCount: stats?.matchCount ?? 0,
                 lastMatchTimestamp: stats?.lastMatchTimestamp ?? null,
+                ...(p.suppress
+                    ? { suppress: { ...p.suppress, ...(p.suppress.script !== undefined && this.suppressScripts.status(p.name) ? { scriptStatus: this.suppressScripts.status(p.name) } : {}) } }
+                    : {}),
             };
             if (typeof p.behavior === 'object' && 'debounce' in p.behavior) {
                 result.debounceState = {
@@ -4157,6 +4564,13 @@ export class EventGate {
             // Fresh, not the cache: the sources the host knows (eventTypesFrom)
             // change as servers connect, with no change to the rules.
             shadowWarnings: this.lintShadows().map(formatShadowWarning),
+            ...(() => {
+                const rule = firstCatchAll(this.config.policies, { lettingBy: true });
+                return rule ? { catchAll: {
+                        rule,
+                        note: `${JSON.stringify(rule)} lets MCPL events by without waking you and without naming a server, a channel or a tag, so a server connected later is handled by it until a rule for that server goes ahead of it.`,
+                    } } : {};
+            })(),
             totalEvaluations: this.totalEvaluations,
             defaultDecisions: {
                 triggered: this.defaultTriggered,
@@ -4192,6 +4606,7 @@ export class EventGate {
     // =========================================================================
     dispose() {
         this.gateScript.dispose();
+        this.suppressScripts.dispose();
         for (const state of this.debounceTimers.values()) {
             clearTimeout(state.timer);
         }