@animalabs/agent-framework 0.6.8 → 0.7.0

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

@@ -190,6 +190,7 @@ export class ChannelRegistry {
     sendTypingFn;
     shouldTriggerInference;
     onRouteFailure;
+    onChannelAutoOpened;
     homeChannelResolver;
     activeChannelResolver;
     store;
@@ -220,6 +221,7 @@ export class ChannelRegistry {
         this.sendTypingFn = options?.sendTypingFn;
         this.shouldTriggerInference = options?.shouldTriggerInference;
         this.onRouteFailure = options?.onRouteFailure;
+        this.onChannelAutoOpened = options?.onChannelAutoOpened;
         this.homeChannelResolver = options?.homeChannelResolver;
         this.activeChannelResolver = options?.activeChannelResolver;
         this.store = options?.store;
@@ -398,6 +400,7 @@ export class ChannelRegistry {
                 content: convertedContent,
                 timestamp: message.timestamp,
                 metadata: message.metadata,
+                ...(message.tags ? { tags: message.tags } : {}),
                 triggerInference,
             };
             // Push to the processing queue
@@ -434,9 +437,19 @@ export class ChannelRegistry {
      * channels/register or channels/changed overwrites this descriptor with the
      * richer one.
      */
-    ensureChannelRegistered(serverId, channelId, label) {
+    ensureChannelRegistered(serverId, channelId, label, extraMetadata) {
         const existing = this.findChannelEntry(channelId);
         if (existing) {
+            // Backfill identity onto a bare lazy registration: a DM that first
+            // arrived with no label/recipient info gets a usable name the next
+            // time a message reveals it (labels must show people, not ids).
+            if (existing.descriptor.metadata?.lazyRegistered &&
+                label && existing.descriptor.label === channelId) {
+                existing.descriptor.label = label;
+                if (extraMetadata) {
+                    existing.descriptor.metadata = { ...existing.descriptor.metadata, ...extraMetadata };
+                }
+            }
             return;
         }
         const key = `${serverId}:${channelId}`;
@@ -447,7 +460,7 @@ export class ChannelRegistry {
                 type: serverId,
                 label: label ?? channelId,
                 direction: 'bidirectional',
-                metadata: { lazyRegistered: true },
+                metadata: { lazyRegistered: true, ...(extraMetadata ?? {}) },
             },
             open: false,
         });
@@ -775,25 +788,64 @@ export class ChannelRegistry {
             timestamp: new Date().toISOString(),
         });
     }
+    /**
+     * True when the server's recipe subscription policy wants this channel
+     * open. This is an ONGOING admission policy (subscribed ⇒ open, no matter
+     * when the channel is discovered) — not just a bootstrap seed. Allow-list
+     * entries may be composite MCPL ids or raw server-internal ids.
+     */
+    policyWantsOpen(serverId, channel) {
+        const policy = this.legacyPolicies.get(serverId) ?? 'manual';
+        if (policy === 'auto')
+            return true;
+        if (Array.isArray(policy)) {
+            if (policy.includes(channel.id))
+                return true;
+            const raw = channel.address?.channelId;
+            return typeof raw === 'string' && raw.length > 0 && policy.includes(raw);
+        }
+        return false;
+    }
+    /**
+     * Returns true when this call made a FRESH subscription-policy decision to
+     * open the channel — the caller announces those to the agent (once per
+     * channel ever: the decision persists in chronicle, so reboots see an
+     * existing non-default source and never re-fire).
+     */
     ensureInitialDesiredState(serverId, channel) {
+        const byPolicy = this.policyWantsOpen(serverId, channel);
+        const wantsOpen = channel.initiallyOpen === true || byPolicy;
         const existing = this.desiredStates.get(this.lifecycleKey(serverId, channel.id));
         if (existing) {
-            // A server upgrading its descriptor to initiallyOpen may lift a pure
-            // default — 'default-closed' means nobody ever decided. Real decisions
+            // A server upgrading its descriptor to initiallyOpen — or a channel
+            // matching the subscription policy — may lift a pure default:
+            // 'default-closed' means nobody ever decided. Real decisions
             // (agent-tool, invitation-declined, legacy migration, …) always stick.
-            if (channel.initiallyOpen === true && existing.state === 'closed' && existing.source === 'default-closed') {
-                this.setDesiredState(serverId, channel.id, 'open', 'server-bootstrap');
+            if (wantsOpen && existing.state === 'closed' && existing.source === 'default-closed') {
+                this.setDesiredState(serverId, channel.id, 'open', channel.initiallyOpen === true ? 'server-bootstrap' : 'subscription-policy');
+                return channel.initiallyOpen !== true && byPolicy;
             }
-            return;
+            return false;
         }
-        this.setDesiredState(serverId, channel.id, channel.initiallyOpen === true ? 'open' : 'closed', channel.initiallyOpen === true ? 'server-bootstrap' : 'default-closed');
+        this.setDesiredState(serverId, channel.id, wantsOpen ? 'open' : 'closed', channel.initiallyOpen === true
+            ? 'server-bootstrap'
+            : wantsOpen
+                ? 'subscription-policy'
+                : 'default-closed');
+        return channel.initiallyOpen !== true && byPolicy;
     }
     async reconcileChannels(serverId, channels) {
         const server = this.serverRegistry.getServer(serverId);
         if (!server)
             return;
+        // Channels the subscription policy freshly admitted in THIS pass —
+        // announced to the agent as one batched notice after the loop, so a
+        // first boot on a new policy doesn't produce one notice per channel.
+        const policyOpened = [];
         for (const channel of channels) {
-            this.ensureInitialDesiredState(serverId, channel);
+            if (this.ensureInitialDesiredState(serverId, channel)) {
+                policyOpened.push({ channelId: channel.id, label: channel.label });
+            }
             const key = `${serverId}:${channel.id}`;
             const desired = this.getDesiredState(serverId, channel.id);
             const entry = this.channels.get(key);
@@ -835,6 +887,21 @@ export class ChannelRegistry {
                 });
             }
         }
+        // Announce policy admissions to the agent — nothing may start flowing
+        // traffic into their window without them being told, and told how to
+        // opt out (channel_close; their decision outranks policy).
+        if (policyOpened.length > 0) {
+            try {
+                this.onChannelAutoOpened?.({
+                    serverId,
+                    source: 'subscription-policy',
+                    channels: policyOpened,
+                });
+            }
+            catch (err) {
+                console.error('onChannelAutoOpened (policy) failed:', err);
+            }
+        }
     }
     // ==========================================================================
     // Private: Typing notification
@@ -919,6 +986,198 @@ export class ChannelRegistry {
             data: allChannels,
         };
     }
+    /**
+     * The single open executor: record durable desired-open intent, tell the
+     * server to subscribe, mark the live entry open. Every path that opens a
+     * channel — the agent's channel_open tool, delivery into a closed locus,
+     * an explicit send into a closed channel — funnels here, so lifecycle
+     * events, desired state, and live state can never diverge by path.
+     * Desired state is recorded BEFORE the server round-trip: intent sticks
+     * even if the subscribe fails, and reconciliation retries later.
+     */
+    async openChannelNow(entry, source, history) {
+        this.setDesiredState(entry.serverId, entry.descriptor.id, 'open', source);
+        const server = this.serverRegistry.getServer(entry.serverId);
+        if (!server) {
+            throw new Error(`Server not found: ${entry.serverId}`);
+        }
+        const result = await server.sendChannelsOpen({
+            channelId: entry.descriptor.id,
+            type: entry.descriptor.type,
+            address: entry.descriptor.address,
+            ...(history ? { history } : {}),
+        });
+        entry.open = true;
+        return result;
+    }
+    /**
+     * Resolve a `>>` prose-routing target (explicit prose routing —
+     * docs/explicit-prose-routing.md) to a registered channel.
+     *
+     * Accepted spellings, tried in order:
+     *   1. exact descriptor id (`discord:guild:123`, always unambiguous)
+     *   2. exact raw server-internal id (`address.channelId`)
+     *   3. `#label` / bare label — case-insensitive match on descriptor label
+     *      with any leading '#' stripped from both sides
+     *   4. `@name` — DM descriptor labels (`DM: name`), case-insensitive
+     *
+     * Ambiguity is an error carrying candidates — never a guess: this is the
+     * mechanism that makes prose misdelivery structurally impossible.
+     */
+    resolveProseTarget(spec) {
+        const entries = [...this.channels.values()];
+        const trimmed = spec.trim();
+        if (!trimmed)
+            return { error: 'empty target' };
+        const exact = entries.filter((e) => e.descriptor.id === trimmed);
+        if (exact.length === 1) {
+            return { channelId: exact[0].descriptor.id, label: exact[0].descriptor.label };
+        }
+        if (exact.length > 1) {
+            return {
+                error: `channel id "${trimmed}" is ambiguous across servers`,
+                candidates: exact.map((e) => `${e.serverId}:${e.descriptor.id}`),
+            };
+        }
+        const raw = entries.filter((e) => e.descriptor.address?.channelId === trimmed);
+        if (raw.length === 1) {
+            return { channelId: raw[0].descriptor.id, label: raw[0].descriptor.label };
+        }
+        if (raw.length > 1) {
+            return {
+                error: `raw id "${trimmed}" is ambiguous`,
+                candidates: raw.map((e) => e.descriptor.id),
+            };
+        }
+        const norm = (s) => s.replace(/^#/, '').toLowerCase();
+        // 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
+        // token), exact recipient/label name, then prefix-lenient name (handles
+        // "@antra_tessera" vs a display name "antra" and vice versa).
+        const mention = /^<@!?(\d+)>$/.exec(trimmed);
+        if (trimmed.startsWith('@') || mention) {
+            const dmMeta = (e) => e.descriptor.metadata;
+            const dmName = (e) => {
+                const meta = dmMeta(e);
+                if (meta?.recipientName)
+                    return meta.recipientName.toLowerCase();
+                const label = (e.descriptor.label ?? '').toLowerCase();
+                return label.startsWith('dm: ') ? label.slice(4) : label;
+            };
+            const isDmEntry = (e) => dmMeta(e)?.channelType === 'dm' ||
+                (e.descriptor.label ?? '').toLowerCase().startsWith('dm: ') ||
+                e.descriptor.id.includes(':dm:');
+            const dms = entries.filter(isDmEntry);
+            if (mention) {
+                const id = mention[1];
+                const byId = dms.filter((e) => dmMeta(e)?.recipientId === id);
+                if (byId.length === 1) {
+                    return { channelId: byId[0].descriptor.id, label: byId[0].descriptor.label };
+                }
+                return {
+                    error: `no registered DM matches the mention <@${id}>`,
+                    candidates: dms.map((e) => e.descriptor.label ?? e.descriptor.id).slice(0, 6),
+                };
+            }
+            const name = trimmed.slice(1).toLowerCase();
+            const exact = dms.filter((e) => dmName(e) === name);
+            const pool = exact.length > 0
+                ? exact
+                : dms.filter((e) => {
+                    const n = dmName(e);
+                    return n.length >= 3 && (n.startsWith(name) || name.startsWith(n) || n.includes(name));
+                });
+            if (pool.length === 1) {
+                return { channelId: pool[0].descriptor.id, label: pool[0].descriptor.label };
+            }
+            if (pool.length > 1) {
+                return {
+                    error: `"${trimmed}" matches several DMs`,
+                    candidates: pool.map((e) => e.descriptor.label ?? e.descriptor.id),
+                };
+            }
+            return {
+                error: `no registered DM found for "${trimmed}" — for someone without a registered DM channel, use the send_dm tool`,
+                ...(dms.length ? { candidates: dms.map((e) => e.descriptor.label ?? e.descriptor.id).slice(0, 6) } : {}),
+            };
+        }
+        const byLabel = entries.filter((e) => norm(e.descriptor.label ?? '') === norm(trimmed));
+        if (byLabel.length === 1) {
+            return { channelId: byLabel[0].descriptor.id, label: byLabel[0].descriptor.label };
+        }
+        if (byLabel.length > 1) {
+            return {
+                error: `label "${trimmed}" matches several channels`,
+                candidates: byLabel.map((e) => e.descriptor.id),
+            };
+        }
+        // Name-segment match: server labels carry a disambiguating suffix
+        // (`#fable (antra's server)`) that agents naturally omit — `>>#fable`
+        // 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 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 };
+        }
+        if (byName.length > 1) {
+            return {
+                error: `"${trimmed}" matches several channels`,
+                candidates: byName.map((e) => `${e.descriptor.label} = ${e.descriptor.id}`),
+            };
+        }
+        // No match: offer near-candidates (labels containing the name) so the
+        // bounce notice is self-healing rather than a dead end.
+        const near = entries
+            .filter((e) => norm(e.descriptor.label ?? '').includes(norm(trimmed)))
+            .slice(0, 5)
+            .map((e) => `${e.descriptor.label} = ${e.descriptor.id}`);
+        return { error: `no channel matches "${trimmed}"`, ...(near.length ? { candidates: near } : {}) };
+    }
+    /**
+     * Open a channel because something was DELIVERED into it (explicit send
+     * tool or routed speech). Sending into a closed channel is not a thing:
+     * engaging a channel opens it, so typing indicators, reaction machinery,
+     * and inbound forwarding all come alive with the first outbound message.
+     * Accepts composite MCPL ids or raw server-internal ids (explicit send
+     * tools receive whatever the agent typed).
+     */
+    async openIfClosedForSend(rawChannelId, serverId) {
+        let matches = [...this.channels.values()].filter((e) => e.descriptor.id === rawChannelId && (!serverId || e.serverId === serverId));
+        if (matches.length === 0) {
+            matches = [...this.channels.values()].filter((e) => e.descriptor.address?.channelId === rawChannelId &&
+                (!serverId || e.serverId === serverId));
+        }
+        if (matches.length === 0)
+            return { status: 'unknown-channel' };
+        if (matches.length > 1)
+            return { status: 'ambiguous' };
+        const entry = matches[0];
+        const resolved = { channelId: entry.descriptor.id, label: entry.descriptor.label };
+        if (entry.open && this.getDesiredState(entry.serverId, entry.descriptor.id) === 'open') {
+            return { status: 'already-open', ...resolved };
+        }
+        try {
+            await this.openChannelNow(entry, 'opened-by-reply');
+            this.emitTraceFn({
+                type: 'mcpl:channel-opened-by-send',
+                serverId: entry.serverId,
+                channelId: entry.descriptor.id,
+            });
+            return { status: 'opened', ...resolved };
+        }
+        catch (err) {
+            this.emitTraceFn({
+                type: 'mcpl:channel-open-failed',
+                serverId: entry.serverId,
+                channelId: entry.descriptor.id,
+                error: err.message,
+            });
+            return { status: 'open-failed', ...resolved };
+        }
+    }
     async handleToolOpen(input) {
         const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
         const entry = resolved.entry;
@@ -936,15 +1195,6 @@ export class ChannelRegistry {
                 data: { channelId: input.channelId, status: 'already open' },
             };
         }
-        this.setDesiredState(entry.serverId, input.channelId, 'open', 'agent-tool');
-        const server = this.serverRegistry.getServer(entry.serverId);
-        if (!server) {
-            return {
-                success: false,
-                error: `Server not found: ${entry.serverId}`,
-                isError: true,
-            };
-        }
         try {
             const history = input.backscroll
                 ? {
@@ -952,13 +1202,7 @@ export class ChannelRegistry {
                     ...(input.beforeMessageId ? { beforeMessageId: input.beforeMessageId } : {}),
                 }
                 : undefined;
-            const result = await server.sendChannelsOpen({
-                channelId: entry.descriptor.id,
-                type: entry.descriptor.type,
-                address: entry.descriptor.address,
-                ...(history ? { history } : {}),
-            });
-            entry.open = true;
+            const result = await this.openChannelNow(entry, 'agent-tool', history);
             return {
                 success: true,
                 data: {
@@ -1144,12 +1388,14 @@ export class ChannelRegistry {
         return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;
     }
     async routeSpeech(conversationId, text, 
-    /** Pin the outbound locus, skipping resolution. Callers delivering MULTIPLE
-     *  segments of ONE turn snapshot resolveLocus() once and pass it here, so a
-     *  new turn starting mid-dispatch (segments run after the agent is idle,
-     *  PR #32) can't overwrite the per-agent triggering channel between segments
-     *  and split one reply across channels. */
-    overrideChannelId) {
+    /** The turn's FROZEN locus, snapshotted once by the caller (resolveLocus
+     *  at turn start) and passed to every segment of the turn. Mandatory:
+     *  there is deliberately no live-resolution fallback here — a late
+     *  dispatch resolving live can read the NEXT turn's trigger state or a
+     *  stale global default and land the reply in the wrong channel (item-3,
+     *  PR #32, and the 2026-07-22 Sol DM misroute). Explicit `null` means
+     *  "this turn is pinned to no locus": fail loudly rather than guess. */
+    locusChannelId) {
         // Surface a routing failure: emit a trace AND notify the host (which drops
         // a `[discord-send-failed]` marker into chronicle) so the agent learns her
         // reply never reached the human, instead of it vanishing silently.
@@ -1157,6 +1403,7 @@ export class ChannelRegistry {
             console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
             this.emitTraceFn({
                 type: 'mcpl:speech-route-failed',
+                conversationId,
                 channelId: channelId ?? '',
                 reason,
                 textLen: text.length,
@@ -1164,29 +1411,54 @@ export class ChannelRegistry {
             this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length });
             return null;
         };
-        // Resolve the outbound locus, in precedence order:
-        //   1. fork HOME channel — a conversation fork always replies in the channel
-        //      it was spawned to serve (item 3, forks).
-        //   2. this turn's TRIGGERING channel — a single trunk agent (connectome-
-        //      host's only mode) replies in the channel whose message woke THIS
-        //      inference, so a concurrent inbound elsewhere can't hijack the reply
-        //      (item-3 redux, trunk agents). Also carries DM channels, which arrive
-        //      as push/events and never touch `defaultPublishChannel`.
-        //   3. the process-global `defaultPublishChannel` — last resort for turns
-        //      with no triggering channel (heartbeats, timers).
-        // Using the global for a fork or a concurrent trunk turn is the item-3 bug:
-        // it tracks the most-recent inbound across ALL channels, so a reply lands
-        // wherever a message last happened to arrive rather than where it belongs.
-        const channelId = overrideChannelId ?? this.resolveLocus(conversationId);
+        // Runtime backstop for JS callers the compiler can't see: an omitted
+        // locus is a routing bug at the call site, never something to paper over
+        // with a live re-resolution.
+        if (locusChannelId === undefined) {
+            return fail(null, 'caller passed no locus (routing bug: every speech path must snapshot the turn locus)');
+        }
+        const channelId = locusChannelId;
         if (!channelId) {
-            // Reached only when the agent has no home, no active triggering channel,
-            // AND no global inbound was ever seen.
-            return fail(null, 'no locus (no home/active channel, defaultPublishChannel null)');
+            // The turn froze with no locus (no home, no triggering channel, no
+            // global inbound ever seen) — the agent was told its prose stays in
+            // the archive; honor that.
+            return fail(null, 'turn has no locus (no home/trigger channel; nothing to deliver into)');
         }
         const entry = this.findChannelEntry(channelId);
         if (!entry) {
             return fail(channelId, `no registered channel for locus "${channelId}"`);
         }
+        // INVARIANT: it is not possible to send into a closed channel. Speech
+        // routed into a closed-but-registered locus (the canonical case: a DM
+        // that woke the agent — DMs register closed) OPENS the channel first,
+        // so typing indicators, reaction machinery, and inbound forwarding come
+        // alive with the reply. If the open fails, the speech does NOT go out:
+        // a half-alive delivery is worse than a loud marker.
+        if (!entry.open) {
+            try {
+                await this.openChannelNow(entry, 'opened-by-delivery');
+                console.error(`[routeSpeech] ${conversationId}: locus ${channelId} was closed — opened by delivery (speech implies engagement)`);
+                this.emitTraceFn({
+                    type: 'mcpl:channel-opened-by-send',
+                    serverId: entry.serverId,
+                    channelId,
+                });
+                try {
+                    this.onChannelAutoOpened?.({
+                        conversationId,
+                        serverId: entry.serverId,
+                        source: 'opened-by-delivery',
+                        channels: [{ channelId, label: entry.descriptor.label }],
+                    });
+                }
+                catch (err) {
+                    console.error('onChannelAutoOpened (delivery) failed:', err);
+                }
+            }
+            catch (err) {
+                return fail(channelId, `locus channel is closed and open failed: ${err.message}`);
+            }
+        }
         const server = this.serverRegistry.getServer(entry.serverId);
         if (!server) {
             return fail(channelId, `server "${entry.serverId}" not found`);
@@ -1198,6 +1470,11 @@ export class ChannelRegistry {
         };
         const result = await server.sendChannelsPublish(publishParams);
         const delivered = result?.delivered ?? true;
+        // Surface the posted message's id (ChannelsPublishResult.messageId) so
+        // trace consumers can act on the just-posted message — e.g. a TTS-relay
+        // tap editing it down to the words actually voiced on interruption.
+        // Previously this was silently dropped here.
+        const messageId = result?.messageId;
         // The server accepted the publish RPC but reported the message was not
         // actually delivered (e.g. missing Send Messages permission). Previously
         // this returned `{ delivered: true }`, masking the failure. Surface it.
@@ -1207,12 +1484,15 @@ export class ChannelRegistry {
         console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
         this.emitTraceFn({
             type: 'mcpl:speech-routed',
+            conversationId,
             serverId: entry.serverId,
             channelId,
             delivered,
             textLen: text.length,
+            text,
+            ...(messageId !== undefined ? { messageId } : {}),
         });
-        return { delivered, channelId };
+        return { delivered, channelId, ...(messageId !== undefined ? { messageId } : {}) };
     }
     async handleToolPublish(input) {
         // Resolve content: accept both `content` and `text` (backward compat)