@animalabs/agent-framework 0.14.0 → 0.16.0

package/dist/src/mcpl/channel-registry.js

@@ -20,6 +20,49 @@ import { CapabilityGrant } from './capability-grant.js';
 // ============================================================================
 const TYPING_INTERVAL_MS = 7_000;
 const CHANNEL_LIFECYCLE_LOG_ID = 'mcpl/channel-lifecycle';
+/**
+ * Durable "which label did this channelId have, each time we saw it" log.
+ * `resolveProseTarget()` resolves a label to an id only for channels
+ * currently in the live `channels` map — fine for normal addressing, but
+ * useless for browsing history on a channel the bot has since disconnected
+ * from (or that didn't survive a restart). This log lets that lookup survive
+ * a disconnect/restart by replaying the most recent label sighting per
+ * channelId. See `labelHistory`, `appendLabelSighting`, and
+ * `resolveProseTargetDurable`.
+ */
+const CHANNEL_LABEL_HISTORY_LOG_ID = 'mcpl/channel-label-history';
+/** Extract a DM's identity/classification fields from a descriptor's
+ *  metadata, if present — mirrors `resolveProseTarget()`'s own local
+ *  `dmMeta()` read (`recipientId`, `recipientName`, `channelType`). Used
+ *  to durably persist them alongside a label sighting (see
+ *  `ChannelLabelSightingEvent`'s corresponding fields), captured at the
+ *  SAME point (sighting time) rather than re-derived later from id/label
+ *  shape, which is exactly what the live resolver does NOT do either. */
+function extractDmMeta(metadata) {
+    const recipientId = typeof metadata?.recipientId === 'string' ? metadata.recipientId : undefined;
+    const recipientName = typeof metadata?.recipientName === 'string' ? metadata.recipientName : undefined;
+    const isDm = metadata?.channelType === 'dm' ? true : undefined;
+    return { recipientId, recipientName, isDm };
+}
+/**
+ * Case-insensitive channel-label comparison key: strips a leading '#' and
+ * lowercases. Mirrors the normalization `resolveProseTarget()` applies to
+ * its live-channel label matches (see the local `norm` there) — factored out
+ * so `resolveLabelFromHistory()` recognizes the same spellings without
+ * duplicating (and risking drift from) the live matching rules.
+ */
+function normalizeChannelLabel(s) {
+    return s.replace(/^#/, '').toLowerCase();
+}
+/**
+ * Same as `normalizeChannelLabel`, but also strips a trailing parenthetical
+ * guild/server suffix (e.g. "#fable (antra's server)" -> "fable") so a bare
+ * channel name matches the disambiguated label agents often omit. Mirrors
+ * `resolveProseTarget()`'s local `nameOf` helper.
+ */
+function normalizeChannelLabelName(label) {
+    return normalizeChannelLabel(label.replace(/\s*\([^)]*\)\s*$/, ''));
+}
 function shallowEqualRecord(a, b) {
     if (a === b)
         return true;
@@ -233,6 +276,51 @@ export class ChannelRegistry {
     store;
     /** Registered channels, keyed by `{serverId}:{channelId}`. */
     channels = new Map();
+    /**
+     * Most-recently-known label per channelId, replayed from
+     * `CHANNEL_LABEL_HISTORY_LOG_ID` (last sighting wins) and kept current by
+     * `appendLabelSighting()`. Unlike `channels`, this survives disconnect and
+     * restart — it's what lets `resolveProseTargetDurable()` resolve a label
+     * for a channel that's no longer live. Keyed by bare channelId, not
+     * `{serverId}:{channelId}` — the label history exists to answer "what id
+     * did this label refer to", independent of which server it came through.
+     */
+    labelHistory = new Map();
+    /**
+     * EVERY distinct label a channelId has ever been durably seen with (not
+     * just the latest) — additive alongside `labelHistory`, populated by the
+     * same replay-at-boot loop and the same `appendLabelSighting()` call.
+     * `labelHistory` alone can only resolve a channel's CURRENT/latest name;
+     * this is what lets `resolveLabelFromHistory()` find a channel by a label
+     * it used to have before a rename — the exact case this whole durable log
+     * exists for (finding an old/renamed channel while browsing history).
+     */
+    allLabelsSeen = new Map();
+    /**
+     * DM recipientId per channelId, durably replayed alongside `labelHistory`
+     * — the piece a `<@id>` mention-form lookup needs that `allLabelsSeen`'s
+     * label strings alone can't provide. See `resolveLabelFromHistory()`'s
+     * DM-aware arm.
+     */
+    dmRecipientIds = new Map();
+    /**
+     * DM recipient's actual username per channelId — can differ from the
+     * channel's display label (`resolveProseTarget()`'s live DM matching
+     * prefers this over the label for exactly that reason). See
+     * `resolveDmFromHistory()`.
+     */
+    dmRecipientNames = new Map();
+    /**
+     * channelId -> true, for every channel EXPLICITLY classified as a DM via
+     * `metadata.channelType === 'dm'` at some sighting — an id/label-shape-
+     * independent classification signal, the same one `resolveProseTarget()`
+     * checks live. Only ever holds `true`; a channel with no explicit
+     * classification is simply absent (not `false`), so `isDmChannelId()`
+     * falls back to id/label-shape heuristics for it rather than durably
+     * asserting a negative for the common case where this metadata was never
+     * sent at all.
+     */
+    dmClassified = new Map();
     /** Most recent incoming channel ID — used for speech routing / default publish. */
     defaultPublishChannel = null;
     /** Most recent incoming message metadata, used for buildChannelContext. */
@@ -263,6 +351,7 @@ export class ChannelRegistry {
         this.activeChannelResolver = options?.activeChannelResolver;
         this.store = options?.store;
         this.initializeLifecycleStore();
+        this.initializeLabelHistoryStore();
     }
     /**
      * Supply a legacy recipe policy for one-time migration into Chronicle.
@@ -300,6 +389,7 @@ export class ChannelRegistry {
                 descriptor: channel,
                 open: false,
             });
+            this.appendLabelSighting(channel.id, channel.label, extractDmMeta(channel.metadata));
             registeredIds.push(channel.id);
             results.push({ id: channel.id, accepted: true });
         }
@@ -360,6 +450,7 @@ export class ChannelRegistry {
                     continue;
                 }
                 existing.descriptor = channel;
+                this.appendLabelSighting(channel.id, channel.label, extractDmMeta(channel.metadata));
                 addedResults.push({ id: channel.id, accepted: true });
             }
         }
@@ -378,6 +469,7 @@ export class ChannelRegistry {
                     descriptor: channel,
                     open: false,
                 });
+                this.appendLabelSighting(channel.id, channel.label, extractDmMeta(channel.metadata));
                 addedResults.push({ id: channel.id, accepted: true });
                 accepted.push(channel);
             }
@@ -539,6 +631,8 @@ export class ChannelRegistry {
                 if (extraMetadata) {
                     existing.descriptor.metadata = { ...existing.descriptor.metadata, ...extraMetadata };
                 }
+                // The channel now has a real label, not just the bare id — durable.
+                this.appendLabelSighting(existing.descriptor.id, existing.descriptor.label, extractDmMeta(existing.descriptor.metadata));
             }
             return;
         }
@@ -554,6 +648,20 @@ export class ChannelRegistry {
             },
             open: false,
         });
+        // Only persist a REAL label durably. Falling back to the bare
+        // channelId as a placeholder (no server-supplied label at all — e.g. a
+        // Discord DM push missing both channelName and an author name,
+        // framework.ts's derivePushEventChannel) must never overwrite a real
+        // label already on file from a previous boot: after a restart the live
+        // `channels` map starts empty, so THIS is the very branch a
+        // label-less post-restart event takes — recording the placeholder here
+        // would clobber the good label initializeLabelHistoryStore() just
+        // replayed, defeating the entire point of the durable log. The live
+        // descriptor above still carries the placeholder for in-process
+        // routing; only the durable write is skipped when there's no real
+        // label to record.
+        if (label)
+            this.appendLabelSighting(channelId, label, extractDmMeta(extraMetadata));
         this.emitTraceFn({
             type: 'mcpl:channel-lazy-registered',
             serverId,
@@ -864,6 +972,340 @@ export class ChannelRegistry {
     appendLifecycleEvent(event) {
         this.store?.appendToStateJson(CHANNEL_LIFECYCLE_LOG_ID, event);
     }
+    // ==========================================================================
+    // Private: Durable channel-label history (disconnected-channel resolution)
+    // ==========================================================================
+    /**
+     * Replay `CHANNEL_LABEL_HISTORY_LOG_ID` into `labelHistory`. Same
+     * construction-time timing as `initializeLifecycleStore()`, and the same
+     * register-if-missing / swallow-"already exists" pattern. The log is
+     * chronological, so folding forward and letting each record overwrite the
+     * map entry for its channelId naturally keeps only the latest sighting.
+     */
+    initializeLabelHistoryStore() {
+        if (!this.store)
+            return;
+        try {
+            this.store.registerState({ id: CHANNEL_LABEL_HISTORY_LOG_ID, strategy: 'append_log' });
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !error.message.includes('State already exists')) {
+                throw error;
+            }
+        }
+        const raw = this.store.getStateJson(CHANNEL_LABEL_HISTORY_LOG_ID);
+        if (!Array.isArray(raw))
+            return;
+        for (const item of raw) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const event = item;
+            if (typeof event.channelId !== 'string' || typeof event.label !== 'string' || !event.label)
+                continue;
+            this.labelHistory.set(event.channelId, event.label);
+            let seen = this.allLabelsSeen.get(event.channelId);
+            if (!seen) {
+                seen = new Set();
+                this.allLabelsSeen.set(event.channelId, seen);
+            }
+            seen.add(event.label);
+            if (typeof event.recipientId === 'string' && event.recipientId) {
+                this.dmRecipientIds.set(event.channelId, event.recipientId);
+            }
+            if (typeof event.recipientName === 'string' && event.recipientName) {
+                this.dmRecipientNames.set(event.channelId, event.recipientName);
+            }
+            if (event.isDm === true) {
+                this.dmClassified.set(event.channelId, true);
+            }
+        }
+    }
+    /**
+     * Record that `channelId` was most recently seen with `label` (and,
+     * optionally, DM identity/classification fields). Called from every
+     * place a `ChannelDescriptor` is set into the live `channels` map
+     * (`handleRegister`, `handleChanged`'s update/add branches,
+     * `ensureChannelRegistered`) so the label survives disconnect and restart
+     * for `resolveLabelFromHistory()` / `resolveProseTargetDurable()`.
+     *
+     * Guarded like `setDesiredState()`: a reconnect or re-registration that
+     * reports the same label AND the same dmMeta fields as last time is a
+     * no-op, so the append log doesn't grow without bound on every
+     * boot/resubscribe — but a later call that newly supplies (or changes)
+     * any dmMeta field for an already-known label (label unchanged) still
+     * records, since that's genuinely new durable information, not a no-op
+     * resighting. `isDm` only ever compares against a possible narrowing:
+     * once durably `true`, a later sighting without `channelType==='dm'`
+     * metadata (i.e. `dmMeta.isDm === undefined`, NOT `false` — see
+     * `extractDmMeta`) is simply silent on the question, not a "no longer a
+     * DM" downgrade, so it never counts as a change on its own.
+     *
+     * `label` is `string | undefined` (not just `string`) even though
+     * `ChannelDescriptor.label` is typed `string`: that typing is a
+     * compile-time-only assertion over untrusted wire data from an MCPL
+     * server, and only `channel.id` is runtime-validated on the way in
+     * (`handleRegister`/`handleChanged`). A missing/undefined label is
+     * dropped rather than recorded — durable garbage here would later throw
+     * inside `resolveLabelFromHistory()`'s normalization, which every
+     * `HistoryModule` tool call passes through unguarded via
+     * `resolveProseTargetDurable()`.
+     */
+    appendLabelSighting(channelId, label, dmMeta = {}) {
+        if (typeof label !== 'string' || !label)
+            return;
+        const { recipientId, recipientName, isDm } = dmMeta;
+        // Never let a bare-id placeholder (ensureChannelRegistered's fallback
+        // `label ?? channelId` when no real label was ever supplied — e.g. a
+        // Discord DM push missing both channelName and an author name) durably
+        // overwrite a real label already on file. This is exactly the restart
+        // scenario the durable log exists to survive: the live `channels` map
+        // is empty after a restart, so the next label-less event would
+        // otherwise take the "first sighting" path and clobber a good label
+        // the replay above just restored. (Belt-and-braces alongside
+        // ensureChannelRegistered's own guard, which should stop this before
+        // it ever gets here — see there for the primary fix.)
+        if (label === channelId && this.labelHistory.has(channelId))
+            return;
+        const labelUnchanged = this.labelHistory.get(channelId) === label;
+        const recipientIdUnchanged = recipientId === undefined || recipientId === this.dmRecipientIds.get(channelId);
+        const recipientNameUnchanged = recipientName === undefined || recipientName === this.dmRecipientNames.get(channelId);
+        const isDmUnchanged = isDm === undefined || this.dmClassified.get(channelId) === true;
+        if (labelUnchanged && recipientIdUnchanged && recipientNameUnchanged && isDmUnchanged)
+            return;
+        this.labelHistory.set(channelId, label);
+        let seen = this.allLabelsSeen.get(channelId);
+        if (!seen) {
+            seen = new Set();
+            this.allLabelsSeen.set(channelId, seen);
+        }
+        seen.add(label);
+        if (recipientId)
+            this.dmRecipientIds.set(channelId, recipientId);
+        if (recipientName)
+            this.dmRecipientNames.set(channelId, recipientName);
+        if (isDm)
+            this.dmClassified.set(channelId, true);
+        this.store?.appendToStateJson(CHANNEL_LABEL_HISTORY_LOG_ID, {
+            channelId,
+            label,
+            ts: Date.now(),
+            ...(recipientId ? { recipientId } : {}),
+            ...(recipientName ? { recipientName } : {}),
+            ...(isDm ? { isDm } : {}),
+        });
+    }
+    /**
+     * Look up a label spec against label *history* rather than the live
+     * `channels` map — the fallback path for a channel the bot isn't
+     * currently connected to. Applies the same normalization
+     * `resolveProseTarget()` uses for its live label/name matches
+     * (`normalizeChannelLabel` / `normalizeChannelLabelName`), plus a raw-id
+     * fast path (mirroring `resolveProseTarget()`'s own raw-id acceptance).
+     *
+     * Matches against `allLabelsSeen` — EVERY label a channel has ever had —
+     * not just its current/latest one in `labelHistory`, so a channel renamed
+     * A -> B -> A is still resolvable by a name from BEFORE the most recent
+     * rename (the point of a history-browsing tool is finding things by what
+     * they used to be called). Ambiguity is genuine here: if the same
+     * normalized spec matches historical labels belonging to two DIFFERENT
+     * channelIds (an actual rename collision, not just the same channel seen
+     * twice), that's a real ambiguity, not a false positive from re-scanning
+     * one channel's own label list — `byLabel`/`byName` tracking below
+     * already only flags ambiguous when the matched channelId itself differs.
+     *
+     * Returns undefined — rather than raising an ambiguity error — when a
+     * normalized spec matches more than one distinct channelId in history;
+     * callers fall back to `resolveProseTarget()`'s original error in that
+     * case via `resolveProseTargetDurable()`.
+     */
+    resolveLabelFromHistory(spec) {
+        const trimmed = spec.trim();
+        if (!trimmed)
+            return undefined;
+        // Fast path: spec is already a channelId we have label history for.
+        if (this.labelHistory.has(trimmed))
+            return trimmed;
+        // DM-aware arm, mirroring resolveProseTarget()'s own `@name` / `<@id>`
+        // handling (see there) — but over durable history instead of the live
+        // `channels` map, so a disconnected/post-restart DM stays addressable
+        // by the natural forms an agent would type, not just the exact stored
+        // label string. Tried BEFORE the generic byLabel/byName loop below
+        // because a bare `@antra` would otherwise also partially match via
+        // normalizeChannelLabel's '#'-only stripping (which does nothing for a
+        // leading '@') and fail confusingly instead of going through DM rules.
+        const mention = /^<@!?(\d+)>$/.exec(trimmed);
+        if (trimmed.startsWith('@') || mention) {
+            return this.resolveDmFromHistory(trimmed, mention);
+        }
+        const normSpec = normalizeChannelLabel(trimmed);
+        let byLabel;
+        let byLabelAmbiguous = false;
+        let byName;
+        let byNameAmbiguous = false;
+        for (const [channelId, labels] of this.allLabelsSeen) {
+            for (const label of labels) {
+                // `?? ''` is belt-and-braces: appendLabelSighting/replay already
+                // refuse to store a falsy label, so this should never see one, but
+                // normalizeChannelLabel has no internal guard of its own (unlike
+                // resolveProseTarget's `e.descriptor.label ?? ''`), and this is
+                // exactly the kind of one-bad-record-poisons-every-future-call path
+                // that caused finding #2.
+                const normLabel = normalizeChannelLabel(label ?? '');
+                const normName = normalizeChannelLabelName(label ?? '');
+                if (normLabel === normSpec) {
+                    if (byLabel !== undefined && byLabel !== channelId)
+                        byLabelAmbiguous = true;
+                    byLabel = channelId;
+                }
+                if (normName === normSpec) {
+                    if (byName !== undefined && byName !== channelId)
+                        byNameAmbiguous = true;
+                    byName = channelId;
+                }
+            }
+        }
+        if (byLabel !== undefined && !byLabelAmbiguous)
+            return byLabel;
+        if (byName !== undefined && !byNameAmbiguous)
+            return byName;
+        return undefined;
+    }
+    /**
+     * A channel counts as a DM (for the purposes of durable-history lookup)
+     * if: it was EXPLICITLY classified as one via `metadata.channelType ===
+     * 'dm'` at some sighting (`dmClassified` — the same classification
+     * signal `resolveProseTarget()`'s live `isDmEntry()` checks FIRST, before
+     * any naming convention, so an id/label that don't follow the usual
+     * `:dm:`/`DM: ` shape still get recognized correctly — this is what
+     * `private-room-42` labeled just `Tess` needs); OR, as a fallback for
+     * descriptors that never carried that metadata at all, its id shape says
+     * so, or any label it has ever carried says so.
+     */
+    isDmChannelId(channelId) {
+        if (this.dmClassified.get(channelId) === true)
+            return true;
+        if (channelId.includes(':dm:'))
+            return true;
+        const labels = this.allLabelsSeen.get(channelId);
+        if (!labels)
+            return false;
+        for (const label of labels) {
+            if (label.toLowerCase().startsWith('dm: '))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Durable-history counterpart to `resolveProseTarget()`'s DM-matching arm
+     * (see there for the live version this mirrors). Handles the two forms
+     * `resolveProseTarget()` supports: a `<@id>` mention (matched against
+     * `dmRecipientIds`, persisted alongside a label sighting specifically for
+     * this) and a bare `@name` (matched against EITHER the persisted
+     * `dmRecipientNames` — the DM's actual username, which the live resolver
+     * prefers and which can differ from the display label, e.g. label
+     * "DM: Tess" but username "antra_tessera" — OR the `DM: `-stripped form
+     * of each DM channel's CURRENT label in `labelHistory`, as a fallback for
+     * descriptors that never carried a recipientName; historical DM labels
+     * aren't name-matched here the way non-DM labels are in
+     * `resolveLabelFromHistory`'s main loop, since a DM's label is a person's
+     * name, not a channel name subject to the same kind of rename).
+     *
+     * Returns undefined on no-match OR ambiguity, same contract as
+     * `resolveLabelFromHistory` — the caller falls back to the live
+     * resolver's original error.
+     */
+    resolveDmFromHistory(trimmed, mention) {
+        // dmClassified/dmRecipientIds/dmRecipientNames are always populated
+        // alongside allLabelsSeen (same appendLabelSighting call, same
+        // falsy-label early return) — so allLabelsSeen's keys are a superset
+        // of every channel any DM signal could exist for.
+        const dmChannelIds = [...this.allLabelsSeen.keys()].filter((id) => this.isDmChannelId(id));
+        if (mention) {
+            const id = mention[1];
+            const matches = dmChannelIds.filter((cid) => this.dmRecipientIds.get(cid) === id);
+            return matches.length === 1 ? matches[0] : undefined;
+        }
+        const name = trimmed.slice(1).toLowerCase();
+        const labelName = (channelId) => {
+            const label = (this.labelHistory.get(channelId) ?? '').toLowerCase();
+            return label.startsWith('dm: ') ? label.slice(4) : label;
+        };
+        // Three strict tiers, mirroring the LIVE resolver's precedence (which
+        // prefers recipientName over the label outright, never a flat pool of
+        // equal-priority candidates): (1) EXACT match against a channel's own
+        // recorded recipientName, (2) EXACT match against a channel's label
+        // (only tried when tier 1 found NOTHING — not merely "didn't match
+        // this channel", genuinely zero matches across every dm channel), (3)
+        // fuzzy/substring match across the combined name pool, as a last
+        // resort. Each tier stops at real ambiguity (2+ matches) rather than
+        // falling through — an ambiguous EXACT recipientName match is a
+        // genuine collision between two real usernames, not something a
+        // weaker label-based tier should silently resolve.
+        //
+        // Tier 1 taking outright precedence (not "additive" the way label
+        // fuzzy-matching is within a single channel) is the actual fix: a flat
+        // combined pool let a DIFFERENT channel's stale/unrelated display
+        // label collide with THIS channel's real recorded username, making an
+        // otherwise-unique lookup falsely ambiguous after a restart — even
+        // though the persisted recipientName data was sufficient on its own to
+        // resolve it. See the regression for the exact collision shape.
+        const exactRecipientName = dmChannelIds.filter((cid) => this.dmRecipientNames.get(cid)?.toLowerCase() === name);
+        if (exactRecipientName.length === 1)
+            return exactRecipientName[0];
+        if (exactRecipientName.length > 1)
+            return undefined;
+        const exactLabel = dmChannelIds.filter((cid) => labelName(cid) === name);
+        if (exactLabel.length === 1)
+            return exactLabel[0];
+        if (exactLabel.length > 1)
+            return undefined;
+        const candidateNames = (channelId) => {
+            const names = [];
+            const recipientName = this.dmRecipientNames.get(channelId);
+            if (recipientName)
+                names.push(recipientName.toLowerCase());
+            const label = labelName(channelId);
+            if (label)
+                names.push(label);
+            return names;
+        };
+        const fuzzy = dmChannelIds.filter((cid) => candidateNames(cid).some((n) => n.length >= 3 && (n.startsWith(name) || name.startsWith(n) || n.includes(name))));
+        return fuzzy.length === 1 ? fuzzy[0] : undefined;
+    }
+    /**
+     * Durable-history-aware counterpart to `resolveProseTarget()`. Resolves a
+     * label or channelId to a canonical channel id even for a channel the bot
+     * is not currently connected to (browsing message history is exactly the
+     * case where you want to look at an old/quiet/disconnected channel, so the
+     * live-only `resolveProseTarget()` isn't enough).
+     *
+     * Tries the live path first — unchanged, so ordinary addressing keeps its
+     * exact current behavior — and only consults `labelHistory` on a live
+     * miss. If history has no answer either, the original error/candidates
+     * from `resolveProseTarget()` are returned unchanged, so callers keep the
+     * same debuggability they'd get from the live-only path.
+     *
+     * CAVEAT (prose-misdelivery safety): if two channels once shared a label
+     * but only ONE of them ever got a durable label-history record (e.g. the
+     * other was lazily registered label-less, or predates this feature), this
+     * can return a single confident answer where `resolveProseTarget()` on
+     * fuller live data would have said "ambiguous" — the durable fallback
+     * only sees what was actually persisted, not what's structurally true.
+     * This is harmless for the current sole caller
+     * (`HistoryModule.resolveChannel`, read-only), but a future caller wiring
+     * this into a SEND path should be aware the ambiguity guarantee is weaker
+     * here than on the live path.
+     */
+    resolveProseTargetDurable(spec) {
+        const live = this.resolveProseTarget(spec);
+        if (!('error' in live))
+            return live;
+        const channelId = this.resolveLabelFromHistory(spec);
+        if (channelId !== undefined) {
+            return { channelId, label: this.labelHistory.get(channelId) };
+        }
+        return live;
+    }
     setDesiredState(serverId, channelId, desired, source) {
         const key = this.lifecycleKey(serverId, channelId);
         if (this.desiredStates.get(key)?.state === desired)
@@ -1316,7 +1758,7 @@ export class ChannelRegistry {
                 candidates: raw.map((e) => e.descriptor.id),
             };
         }
-        const norm = (s) => s.replace(/^#/, '').toLowerCase();
+        const norm = normalizeChannelLabel;
         // DM addressing is PEOPLE-first: usernames and mention tokens, never
         // ids-only (2026-07-24, antra + Fable's live-canary bug report). A DM
         // entry is matched by, in order: recipientId (from a `<@id>` mention
@@ -1384,7 +1826,7 @@ export class ChannelRegistry {
         // must resolve. Strip a trailing parenthetical from the stored label and
         // compare the bare channel name. Same name in several guilds is a real
         // ambiguity: error with full labels so the agent can use the exact id.
-        const nameOf = (label) => norm(label.replace(/\s*\([^)]*\)\s*$/, ''));
+        const nameOf = normalizeChannelLabelName;
         const byName = entries.filter((e) => nameOf(e.descriptor.label ?? '') === norm(trimmed));
         if (byName.length === 1) {
             return { channelId: byName[0].descriptor.id, label: byName[0].descriptor.label };