@animalabs/agent-framework 0.22.1 → 0.22.3

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

@@ -12,11 +12,16 @@
  * - Expose synthesized tools: channel_list, channel_open, channel_close, channel_publish
  * - Build channel context for beforeInference params
  */
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
+import { convertBlock } from './convert-block.js';
+import { ensureStateRegistered } from '../module-registry.js';
 import { expandCoreTags } from './tags.js';
-import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
-import { isVisiblyEmptyContent } from './visible-content.js';
+import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { isVisiblyEmptyConversion } from './visible-content.js';
+import { logDetail, logValue } from './log-value.js';
+import { RefusalLines } from './refusal-lines.js';
 import { CapabilityGrant } from './capability-grant.js';
+import { McplRequestError } from './server-connection.js';
+import { readSkipReplyWake } from './skip-reply-wake.js';
 // ============================================================================
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
 // ============================================================================
@@ -81,68 +86,6 @@ function shallowEqualRecord(a, b) {
     return true;
 }
 // ============================================================================
-// Content Conversion: McplContentBlock → membrane ContentBlock
-// ============================================================================
-/**
- * Convert a single MCPL wire-format content block to a membrane ContentBlock.
- */
-function convertBlock(block) {
-    switch (block.type) {
-        case 'text':
-            return { type: 'text', text: block.text };
-        case 'image':
-            if (isInlineContradiction(block)) {
-                // RFC-005 vector 2: inline data claiming bulk disposition — fail
-                // closed, withhold the data (checked BEFORE the data branch).
-                return { type: 'text', text: INLINE_WITHHELD_TEXT };
-            }
-            if (block.uri && block.disposition) {
-                // RFC-005 uri-form media with a disposition claim: stub, do not
-                // hand the URI to the provider or inline it.
-                return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-            }
-            if (block.data && block.mimeType) {
-                return {
-                    type: 'image',
-                    source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-                };
-            }
-            if (block.uri) {
-                return {
-                    type: 'image',
-                    source: { type: 'url', url: block.uri },
-                };
-            }
-            return { type: 'text', text: '[Image: no data]' };
-        case 'audio':
-            if (isInlineContradiction(block)) {
-                // RFC-005 vector 2: inline data claiming bulk disposition — fail
-                // closed, withhold the data (checked BEFORE the data branch).
-                return { type: 'text', text: INLINE_WITHHELD_TEXT };
-            }
-            if (block.uri && block.disposition) {
-                // RFC-005 uri-form media with a disposition claim: stub, do not
-                // hand the URI to the provider or inline it.
-                return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-            }
-            if (block.data && block.mimeType) {
-                return {
-                    type: 'audio',
-                    source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-                };
-            }
-            return { type: 'text', text: '[Audio: no data]' };
-        case 'resource':
-            // RFC-005: reference blocks become bounded stubs — never raw URIs
-            // (a signed URL is a bearer credential that looks like a location).
-            return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-        default:
-            // Unknown wire block types previously fell off the exhaustive switch
-            // and propagated `undefined` into ContentBlock[]. Fail visibly.
-            return { type: 'text', text: `[unrecognized content block: ${block.type ?? 'untyped'}]` };
-    }
-}
-// ============================================================================
 // Channel Tool Definitions
 // ============================================================================
 const CHANNEL_TOOL_DEFINITIONS = [
@@ -153,9 +96,8 @@ const CHANNEL_TOOL_DEFINITIONS = [
     },
     {
         name: 'channel_open',
-        description: 'Open a channel to start receiving its ordinary ongoing traffic. The MCPL ' +
-            'integration performs its own subscribe/join/attach operation. Optionally request ' +
-            'history preceding the message that invited you into the channel.',
+        description: 'Open a channel. What an open channel delivers to you depends on its MCPL server. ' +
+            'Optionally request history preceding the message that invited you into the channel.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -194,7 +136,8 @@ const CHANNEL_TOOL_DEFINITIONS = [
     },
     {
         name: 'channel_close',
-        description: 'Close a channel to stop receiving messages',
+        description: 'Close a channel. Messages that address you still reach you; what else stops reaching you ' +
+            'depends on its server.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -268,14 +211,90 @@ const CHANNEL_TOOL_DEFINITIONS = [
                 wake_in_seconds: {
                     type: 'number',
                     description: 'Optional self-wake: if nothing else wakes you first, you wake again after this ' +
-                        'many seconds (1 = go again almost immediately; clamped to 1–3600). Any other ' +
-                        'wake before then cancels it. Omit to stay idle until the next external wake.',
+                        'many seconds, from 1 to 3600; a larger number waits 3600 (1 = go again almost ' +
+                        'immediately). Any other wake before then cancels it. Omit to stay idle until the ' +
+                        'next external wake.',
                 },
             },
             required: [],
         },
     },
 ];
+// ============================================================================
+// Constructor Options
+// ============================================================================
+/** Bound connector values for notices, logs and an outcome's reason. A
+ *  PublishOutcome keeps the connector's structured data (`detail`) whole. */
+export function connectorText(value) {
+    let text;
+    try {
+        text = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return '[unserializable connector value]';
+    }
+    const limit = 2000;
+    const suffix = '… [truncated]';
+    return text.length > limit ? text.slice(0, limit - suffix.length) + suffix : text;
+}
+/**
+ * What a channels/publish request that threw establishes. Only a request
+ * that never left the host proves nothing was posted. An error response may
+ * follow a partial post (a multi-part send whose later part failed), so it
+ * is unknown, with the connector's own words, bounded, and its data kept for
+ * the resident to judge. The publish executor and channel_publish both read
+ * a failed request this way.
+ */
+function publishErrorOutcome(err, destination, at) {
+    const message = connectorText(err instanceof Error ? err.message : String(err));
+    const notSent = err instanceof McplRequestError && err.outcome === 'not-sent';
+    const detail = err instanceof McplRequestError ? err.data : undefined;
+    return {
+        status: notSent ? 'failed' : 'unknown',
+        destination,
+        reason: notSent ? message : `${message} (delivery uncertain)`,
+        ...(detail !== undefined ? { detail } : {}),
+        at,
+    };
+}
+/**
+ * What a channels/publish answer establishes. A final publish is a request,
+ * so success requires an explicit receipt; a missing or malformed one leaves
+ * delivery uncertain (anima-research/agent-framework#163's rule).
+ * `delivered: false` proves nothing went out only when the receipt names no
+ * message at all: a message id beside it, valid or malformed, contradicts it,
+ * since something may have been posted. The publish executor and
+ * channel_publish both read an answer this way.
+ */
+function publishReceiptOutcome(result, destination, at) {
+    const receipt = (result ?? {});
+    const messageId = typeof receipt.messageId === 'string' && receipt.messageId ? receipt.messageId : undefined;
+    if (receipt.delivered === true) {
+        return { status: 'delivered', destination, ...(messageId ? { messageId } : {}), at };
+    }
+    if (receipt.delivered === false) {
+        if (receipt.messageId === undefined || receipt.messageId === null) {
+            return { status: 'failed', destination, reason: `server "${destination.serverId}" reported delivered:false`, at };
+        }
+        return {
+            status: 'unknown',
+            destination,
+            ...(messageId ? { messageId } : {}),
+            reason: messageId
+                ? `server "${destination.serverId}" reported delivered:false but named posted message ${connectorText(messageId)} (delivery uncertain)`
+                : `server "${destination.serverId}" reported delivered:false beside a malformed message id ` +
+                    `${connectorText(receipt.messageId)} (contradictory receipt; delivery uncertain)`,
+            at,
+        };
+    }
+    return {
+        status: 'unknown',
+        destination,
+        ...(messageId ? { messageId } : {}),
+        reason: `server "${destination.serverId}" returned no valid delivery receipt (delivery uncertain)`,
+        at,
+    };
+}
 /** The machine decision sources a module-origin channel_close may record.
  *  Closed on purpose: honest provenance means a small, auditable vocabulary,
  *  not arbitrary self-description. */
@@ -294,6 +313,9 @@ export class ChannelRegistry {
     store;
     /** Registered channels, keyed by `{serverId}:{channelId}`. */
     channels = new Map();
+    /** Holds back repeats of the line for a message refused because its
+     *  channel isn't registered (RefusalLines). */
+    unknownChannelLines = new RefusalLines();
     /**
      * Most-recently-known label per channelId, replayed from
      * `CHANNEL_LABEL_HISTORY_LOG_ID` (last sighting wins) and kept current by
@@ -357,8 +379,22 @@ export class ChannelRegistry {
     legacyPolicies = new Map();
     migratedLegacyPolicies = new Set();
     handleCoalescedIncoming;
+    acceptInbound;
+    channelTools;
     constructor(serverRegistry, featureSetManager, pushEventFn, emitTraceFn, options) {
         this.handleCoalescedIncoming = options?.handleCoalescedIncoming;
+        this.acceptInbound = options?.acceptInbound;
+        this.channelTools = CHANNEL_TOOL_DEFINITIONS.map((tool) => {
+            if (tool.name !== 'skip_reply' || options?.eventGatePresent === true)
+                return tool;
+            const schema = tool.inputSchema;
+            const { wake_in_seconds: _wake, ...properties } = schema.properties;
+            return {
+                ...tool,
+                description: tool.description.replace(' To end this turn but come back on your own shortly, set wake_in_seconds.', ''),
+                inputSchema: { ...schema, properties },
+            };
+        });
         this.serverRegistry = serverRegistry;
         this.featureSetManager = featureSetManager;
         this.pushEventFn = pushEventFn;
@@ -512,6 +548,37 @@ export class ChannelRegistry {
             updated: params.updated?.map((c) => c.id) ?? [],
         });
     }
+    /**
+     * A coalesced message the host refused. Until now the host said nothing, so
+     * a dropped message (agent-framework#266: every Discord message with a
+     * screenshot) left no trace where operators look. The sender gets the
+     * per-message result this lane gives: `coalesce_invalid` for a malformed
+     * item, or the thrown error's message for anything else. `answered` is the
+     * code that result stands for (-32602 for `coalesce_invalid`), and the
+     * reason follows it (coalesceRejectionReason): `coalesce-failed` when the
+     * host itself failed, `coalesce-invalid` when the sender's item was
+     * refused, with the failing `field` and the error's message as `detail`.
+     * The line prints the ids the sender sent, whatever their type; the trace
+     * carries them when they are strings.
+     */
+    traceCoalesceRejection(serverId, message, error, answered) {
+        const reason = coalesceRejectionReason(answered);
+        const field = typeof error.field === 'string' && error.field ? error.field : undefined;
+        const channelId = typeof message?.channelId === 'string' ? message.channelId : '';
+        const messageId = typeof message?.messageId === 'string' && message.messageId ? message.messageId : undefined;
+        console.error(`[channel-incoming-rejected] server=${serverId} channel=${logValue(message?.channelId ?? '')} ` +
+            `messageId=${logValue(message?.messageId ?? '')} ` +
+            `reason=${reason}${field ? ` field=${logValue(field)}` : ''}: ${logDetail(error.message)}`);
+        this.emitTraceFn({
+            type: 'mcpl:channel-incoming-rejected',
+            serverId,
+            channelId,
+            ...(messageId ? { messageId } : {}),
+            reason,
+            ...(field ? { field } : {}),
+            detail: error.message,
+        });
+    }
     /**
      * Handle `channels/incoming` from a server.
      *
@@ -523,10 +590,20 @@ export class ChannelRegistry {
         for (const message of params.messages) {
             if (!message || typeof message.channelId !== 'string' || !message.channelId
                 || typeof message.messageId !== 'string' || !message.messageId) {
+                // The same gate as admission below: with no coalescer wired, a
+                // message carrying `coalesce` is handled uncoalesced, and refused as
+                // any uncoalesced message without an identity is.
+                const coalescedItem = message?.coalesce !== undefined && !!this.handleCoalescedIncoming;
+                if (coalescedItem) {
+                    this.traceCoalesceRejection(serverId, message, {
+                        field: typeof message.channelId !== 'string' || !message.channelId ? 'channelId' : 'messageId',
+                        message: 'a coalesced message needs a channelId and a messageId',
+                    }, -32602);
+                }
                 results.push({
                     messageId: typeof message?.messageId === 'string' ? message.messageId : '',
                     accepted: false,
-                    reason: message?.coalesce !== undefined ? 'coalesce_invalid' : 'invalid channel/message identity',
+                    reason: coalescedItem ? 'coalesce_invalid' : 'invalid channel/message identity',
                 });
                 continue;
             }
@@ -557,11 +634,22 @@ export class ChannelRegistry {
             // routable entry rather than an open self-attested one.
             const incomingKey = `${serverId}:${message.channelId}`;
             if (!this.channels.has(incomingKey)) {
+                // Loud, coalesced or not, like every other refusal of a message, but
+                // at most once a minute per channel (RefusalLines): a server that
+                // never registered a busy channel would otherwise print a line for
+                // every message in it. Every refusal is traced.
+                const held = this.unknownChannelLines.admit(serverId, message.channelId);
+                if (held !== null) {
+                    console.error(`[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} ` +
+                        `messageId=${logValue(message.messageId)} reason=unknown-channel ` +
+                        `(not registered, §14.5${held ? `; ${held} more since the last line` : ''})`);
+                }
                 this.emitTraceFn({
                     type: 'mcpl:channel-incoming-rejected',
                     serverId,
                     channelId: message.channelId,
-                    reason: 'unknown channel — not registered (§14.5)',
+                    messageId: message.messageId,
+                    reason: 'unknown-channel',
                 });
                 results.push({
                     messageId: message.messageId,
@@ -578,7 +666,7 @@ export class ChannelRegistry {
             // shows the model nothing would wake it with no visible cause.
             const emptyAllowed = coalesced && message.coalesce?.retract === true;
             const rejectEmpty = () => {
-                console.error(`[channel-incoming-rejected] server=${serverId} channel=${message.channelId} messageId=${message.messageId} reason=empty-content`);
+                console.error(`[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} messageId=${logValue(message.messageId)} reason=empty-content`);
                 this.emitTraceFn({
                     type: 'mcpl:channel-incoming-rejected',
                     serverId,
@@ -592,20 +680,23 @@ export class ChannelRegistry {
                 // RFC-006 §13: malformed content on a coalesced item is that item's
                 // failure, not the batch's — check the shape before converting.
                 try {
-                    validateCoalescedContent(message.content, undefined, { allowEmpty: emptyAllowed });
+                    validateCoalescedContent(message.content, { allowEmpty: emptyAllowed });
                 }
                 catch (error) {
                     if (error instanceof EmptyContentError)
                         rejectEmpty();
-                    else
+                    else {
+                        // Answered coalesce_invalid whatever the error's code: -32602.
+                        this.traceCoalesceRejection(serverId, message, error, -32602);
                         results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+                    }
                     continue;
                 }
             }
             if (message.tags)
                 message.tags = expandCoreTags(message.tags);
-            const convertedContent = message.content.map(convertBlock);
-            if (!emptyAllowed && isVisiblyEmptyContent(convertedContent)) {
+            const convertedContent = message.content.map((block) => convertBlock(block, 'attachment on channel message', serverId));
+            if (!emptyAllowed && isVisiblyEmptyConversion(message.content, convertedContent)) {
                 rejectEmpty();
                 continue;
             }
@@ -630,7 +721,10 @@ export class ChannelRegistry {
             // Determine whether to trigger inference
             let triggerInference = true;
             if (this.shouldTriggerInference) {
-                const textContent = message.content
+                // The text the agent's context gets, as the push lane's filter reads
+                // it: the converted text blocks, a placeholder or reference stub
+                // among them, NON_STRING_TEXT_PLACEHOLDER included.
+                const textContent = convertedContent
                     .filter((b) => b.type === 'text')
                     .map((b) => b.text)
                     .join('\n');
@@ -658,6 +752,7 @@ export class ChannelRegistry {
                 metadata: message.metadata,
                 ...(message.tags ? { tags: message.tags } : {}),
                 triggerInference,
+                acceptedAt: Date.now(),
             };
             if (coalesced) {
                 // RFC-006 §14.3: a coalesced message is admitted like any other and
@@ -672,6 +767,9 @@ export class ChannelRegistry {
                 }
                 catch (error) {
                     const err = error;
+                    // -32602 is answered coalesce_invalid; anything else as its message,
+                    // a plain Error standing for an internal error (-32603).
+                    this.traceCoalesceRejection(serverId, message, err, typeof err.code === 'number' ? err.code : -32603);
                     results.push({
                         messageId: message.messageId,
                         accepted: false,
@@ -680,6 +778,12 @@ export class ChannelRegistry {
                 }
                 continue;
             }
+            // The source envelope is frozen here, at admission, before the message
+            // is queued or acknowledged: a rename or rebind while it waits in the
+            // queue cannot change where it says it came from.
+            const inboundSource = this.acceptInbound?.(event);
+            if (inboundSource)
+                event.inboundSource = inboundSource;
             // Push to the processing queue
             // Cast through unknown because McplChannelIncomingEvent matches the
             // CustomEvent `${string}:${string}` type pattern but lacks an index signature.
@@ -722,27 +826,19 @@ export class ChannelRegistry {
             // 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 };
-                }
+                const metadata = extraMetadata
+                    ? { ...existing.descriptor.metadata, ...extraMetadata }
+                    : existing.descriptor.metadata;
                 // 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));
+                // Recorded before the live descriptor takes it, since this branch's
+                // guard reads the descriptor: an append that throws leaves the
+                // placeholder, so the next push tries again.
+                this.appendLabelSighting(existing.descriptor.id, label, extractDmMeta(metadata));
+                existing.descriptor.label = label;
+                existing.descriptor.metadata = metadata;
             }
             return;
         }
-        const key = `${serverId}:${channelId}`;
-        this.channels.set(key, {
-            serverId,
-            descriptor: {
-                id: channelId,
-                type: serverId,
-                label: label ?? channelId,
-                direction: 'bidirectional',
-                metadata: { lazyRegistered: true, ...(extraMetadata ?? {}) },
-            },
-            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,
@@ -752,11 +848,24 @@ export class ChannelRegistry {
         // 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
+        // descriptor below still carries the placeholder for in-process
         // routing; only the durable write is skipped when there's no real
-        // label to record.
+        // label to record. A real label is recorded before the entry exists:
+        // an append that throws registers nothing, so the next push tries again.
         if (label)
             this.appendLabelSighting(channelId, label, extractDmMeta(extraMetadata));
+        const key = `${serverId}:${channelId}`;
+        this.channels.set(key, {
+            serverId,
+            descriptor: {
+                id: channelId,
+                type: serverId,
+                label: label ?? channelId,
+                direction: 'bidirectional',
+                metadata: { lazyRegistered: true, ...(extraMetadata ?? {}) },
+            },
+            open: false,
+        });
         this.emitTraceFn({
             type: 'mcpl:channel-lazy-registered',
             serverId,
@@ -879,6 +988,12 @@ export class ChannelRegistry {
     getDescriptor(channelId) {
         return this.findChannelEntry(channelId)?.descriptor;
     }
+    /** The registered label of `channelId` on exactly `serverId` (no
+     *  cross-server first match), or undefined when it has none. */
+    getChannelLabel(serverId, channelId) {
+        const label = this.channels.get(`${serverId}:${channelId}`)?.descriptor.label;
+        return typeof label === 'string' && label.length > 0 ? label : undefined;
+    }
     isChannelOpen(channelId) {
         return this.findChannelEntry(channelId)?.open === true;
     }
@@ -904,7 +1019,7 @@ export class ChannelRegistry {
      * Get synthesized tool definitions for channel operations.
      */
     getChannelTools() {
-        return CHANNEL_TOOL_DEFINITIONS;
+        return this.channelTools;
     }
     /**
      * Handle a call to one of the synthesized channel tools.
@@ -952,8 +1067,9 @@ export class ChannelRegistry {
         const openChannels = this.getOpenChannels();
         // Resolve the outbound locus the SAME way routeSpeech does, so the agent is
         // told the channel its speech will actually land in: a conversation fork's
-        // home channel, else this turn's triggering channel (single trunk agent —
-        // item-3 redux), else the global default (heartbeats). Without this, a fork
+        // home channel, else this turn's channel (single trunk agent — item-3
+        // redux: its locus, else its triggering channel), else the global default
+        // (heartbeats). Without this, a fork
         // was advertised the global locus but published somewhere else; and a trunk
         // agent was told the wrong channel under concurrency.
         const home = agentName ? this.homeChannelResolver?.(agentName) : undefined;
@@ -1032,14 +1148,7 @@ export class ChannelRegistry {
     initializeLifecycleStore() {
         if (!this.store)
             return;
-        try {
-            this.store.registerState({ id: CHANNEL_LIFECYCLE_LOG_ID, strategy: 'append_log' });
-        }
-        catch (error) {
-            if (!(error instanceof Error) || !error.message.includes('State already exists')) {
-                throw error;
-            }
-        }
+        ensureStateRegistered(this.store, { id: CHANNEL_LIFECYCLE_LOG_ID, strategy: 'append_log' });
         const raw = this.store.getStateJson(CHANNEL_LIFECYCLE_LOG_ID);
         if (!Array.isArray(raw))
             return;
@@ -1077,6 +1186,15 @@ export class ChannelRegistry {
             }
         }
     }
+    /**
+     * Each writer appends its record here before it changes memory for it, so
+     * an append that throws, as on a full disk, fails the operation with that
+     * change unmade, and memory and the log still agree. A retry then records
+     * the change rather than finding it in memory already, where
+     * setDesiredState's same-state return would record nothing, and a restart
+     * replays what memory held. appendLabelSighting keeps the same order for
+     * the label history.
+     */
     appendLifecycleEvent(event) {
         this.store?.appendToStateJson(CHANNEL_LIFECYCLE_LOG_ID, event);
     }
@@ -1093,14 +1211,7 @@ export class ChannelRegistry {
     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;
-            }
-        }
+        ensureStateRegistered(this.store, { id: CHANNEL_LABEL_HISTORY_LOG_ID, strategy: 'append_log' });
         const raw = this.store.getStateJson(CHANNEL_LABEL_HISTORY_LOG_ID);
         if (!Array.isArray(raw))
             return;
@@ -1180,6 +1291,16 @@ export class ChannelRegistry {
         const isDmUnchanged = isDm === undefined || this.dmClassified.get(channelId) === true;
         if (labelUnchanged && recipientIdUnchanged && recipientNameUnchanged && isDmUnchanged)
             return;
+        // The log first, as for lifecycle events: an append that throws leaves
+        // the history in memory as it was, so the next sighting records it.
+        this.store?.appendToStateJson(CHANNEL_LABEL_HISTORY_LOG_ID, {
+            channelId,
+            label,
+            ts: Date.now(),
+            ...(recipientId ? { recipientId } : {}),
+            ...(recipientName ? { recipientName } : {}),
+            ...(isDm ? { isDm } : {}),
+        });
         this.labelHistory.set(channelId, label);
         let seen = this.allLabelsSeen.get(channelId);
         if (!seen) {
@@ -1193,14 +1314,6 @@ export class ChannelRegistry {
             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
@@ -1418,7 +1531,6 @@ export class ChannelRegistry {
         const key = this.lifecycleKey(serverId, channelId);
         if (this.desiredStates.get(key)?.state === desired)
             return;
-        this.desiredStates.set(key, { state: desired, source });
         this.appendLifecycleEvent({
             kind: 'desired-state',
             serverId,
@@ -1427,6 +1539,7 @@ export class ChannelRegistry {
             source,
             timestamp: new Date().toISOString(),
         });
+        this.desiredStates.set(key, { state: desired, source });
     }
     // ==========================================================================
     // Tune-out state (issue #77) — durable in the lifecycle log
@@ -1439,12 +1552,6 @@ export class ChannelRegistry {
      */
     enterTuneOut(serverId, channelId, params, source) {
         const key = this.lifecycleKey(serverId, channelId);
-        this.desiredStates.set(key, {
-            state: 'tuned-out',
-            source,
-            tuneOut: params,
-            wakeCount: 0,
-        });
         this.appendLifecycleEvent({
             kind: 'desired-state',
             serverId,
@@ -1454,6 +1561,12 @@ export class ChannelRegistry {
             source,
             timestamp: new Date().toISOString(),
         });
+        this.desiredStates.set(key, {
+            state: 'tuned-out',
+            source,
+            tuneOut: params,
+            wakeCount: 0,
+        });
     }
     /**
      * End the active tune-out, returning the channel to `nextState`.
@@ -1467,7 +1580,6 @@ export class ChannelRegistry {
         if (current?.state !== 'tuned-out' || !current.tuneOut)
             return null;
         const ended = { params: current.tuneOut, wakeCount: current.wakeCount ?? 0 };
-        this.desiredStates.set(key, { state: nextState, source });
         this.appendLifecycleEvent({
             kind: 'desired-state',
             serverId,
@@ -1476,6 +1588,7 @@ export class ChannelRegistry {
             source,
             timestamp: new Date().toISOString(),
         });
+        this.desiredStates.set(key, { state: nextState, source });
         return ended;
     }
     /**
@@ -1490,16 +1603,17 @@ export class ChannelRegistry {
         const current = this.desiredStates.get(key);
         if (current?.state !== 'tuned-out' || !current.tuneOut)
             return null;
-        current.wakeCount = (current.wakeCount ?? 0) + 1;
+        const wakeCount = (current.wakeCount ?? 0) + 1;
         this.appendLifecycleEvent({
             kind: 'tune-out-wake',
             serverId,
             channelId,
             epochId: current.tuneOut.epochId,
-            wakeCount: current.wakeCount,
+            wakeCount,
             timestamp: new Date().toISOString(),
         });
-        return { params: current.tuneOut, wakeCount: current.wakeCount };
+        current.wakeCount = wakeCount;
+        return { params: current.tuneOut, wakeCount };
     }
     /** Active tune-out params + wake count for a channel, or null. */
     getTuneOutState(serverId, channelId) {
@@ -1523,19 +1637,13 @@ export class ChannelRegistry {
     readCoordinatorState(stateId) {
         if (!this.store)
             return null;
-        try {
-            this.store.registerState({ id: stateId, strategy: 'snapshot' });
-        }
-        catch { /* already registered */ }
+        ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
         return this.store.getStateJson(stateId);
     }
     writeCoordinatorState(stateId, value) {
         if (!this.store)
             return;
-        try {
-            this.store.registerState({ id: stateId, strategy: 'snapshot' });
-        }
-        catch { /* already registered */ }
+        ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
         this.store.setStateJson(stateId, value);
     }
     /**
@@ -1566,13 +1674,13 @@ export class ChannelRegistry {
                 : 'closed';
             this.setDesiredState(serverId, channel.id, desired, 'legacy-recipe-migration');
         }
-        this.migratedLegacyPolicies.add(serverId);
         this.appendLifecycleEvent({
             kind: 'legacy-policy-migrated',
             serverId,
             source: Array.isArray(policy) ? 'allow-list' : policy,
             timestamp: new Date().toISOString(),
         });
+        this.migratedLegacyPolicies.add(serverId);
     }
     /**
      * True when the server's recipe subscription policy wants this channel
@@ -1688,9 +1796,9 @@ 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).
+        // Announce policy admissions to the agent — no channel may open without
+        // them being told, and told how to opt out (channel_close; their
+        // decision outranks policy).
         if (policyOpened.length > 0) {
             try {
                 this.onChannelAutoOpened?.({
@@ -2048,11 +2156,13 @@ export class ChannelRegistry {
         // A tuned-out channel is transport-open but attention-diverted; a plain
         // open would silently discard the epoch (and its pending backlog dump).
         // Cancelling is the tune-out coordinator's flow, reached via its own
-        // tool — refuse with the pointer rather than eat the state.
+        // tool — refuse with the pointer rather than eat the state. As an error
+        // result, the agent reads the pointer itself; `data` names the refusal
+        // for an in-process caller.
         if (this.getDesiredState(entry.serverId, input.channelId) === 'tuned-out') {
             return {
                 success: false,
-                isError: false,
+                isError: true,
                 error: `Channel ${input.channelId} is tuned out. Cancel the tune-out ` +
                     `(tune_out with mode: 'cancel') to resume normal attention — ` +
                     `cancelling delivers the diverted backlog.`,
@@ -2189,7 +2299,7 @@ export class ChannelRegistry {
         if (entry.open || this.getDesiredState(entry.serverId, input.channelId) === 'open') {
             return {
                 success: false,
-                error: `Channel is already open: ${input.channelId}. Use channel_close to leave it.`,
+                error: `Channel is already open: ${input.channelId}. Use channel_close to close it.`,
                 isError: true,
             };
         }
@@ -2295,12 +2405,13 @@ export class ChannelRegistry {
      */
     handleToolSkipReply(input) {
         // The self-wake itself is armed by the framework (which owns the
-        // EventGate) BEFORE this dispatch; when the gate is absent the framework
-        // strips the field so this confirmation stays truthful.
-        const wakeSecs = Number(input.wake_in_seconds);
-        const selfWake = Number.isFinite(wakeSecs) && wakeSecs > 0
-            ? Math.max(1, Math.min(3600, Math.floor(wakeSecs)))
-            : undefined;
+        // EventGate) BEFORE its dispatch reaches this handler, from the same
+        // reading, and the framework refuses a wake the host can't set before
+        // dispatching. A caller of this registry's handleChannelToolCall
+        // (AgentFramework.channels) goes past both, so its note names a wake
+        // nothing armed.
+        const wake = readSkipReplyWake(input);
+        const selfWake = wake.kind === 'wake' ? wake.seconds : undefined;
         return {
             success: true,
             // The note says "ended the turn" — make it TRUE. Without endTurn the
@@ -2386,7 +2497,158 @@ export class ChannelRegistry {
         const home = this.homeChannelResolver?.(conversationId);
         return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;
     }
-    async routeSpeech(conversationId, text, 
+    /**
+     * Resolve a publish target to exactly one registered channel: `serverId`
+     * plus `channelId` when the caller has the server, otherwise a channel id
+     * registered by exactly one server. A shared id is refused, never resolved
+     * to whichever server registered it first.
+     */
+    resolveDestination(target) {
+        const entry = this.findExactEntry(target);
+        if ('error' in entry)
+            return entry;
+        return {
+            destination: {
+                serverId: entry.entry.serverId,
+                channelId: entry.entry.descriptor.id,
+                ...(entry.entry.descriptor.label ? { label: entry.entry.descriptor.label } : {}),
+            },
+        };
+    }
+    findExactEntry(target) {
+        // A supplied selector is checked, never read as omission: an empty or
+        // non-string serverId would otherwise widen to "any server".
+        if (typeof target.channelId !== 'string' || !target.channelId) {
+            return { error: 'the destination names no channel id' };
+        }
+        if (target.serverId !== undefined && (typeof target.serverId !== 'string' || !target.serverId)) {
+            return { error: 'serverId must name a server (omit it to resolve the channel id alone)' };
+        }
+        const matches = [...this.channels.values()].filter((e) => e.descriptor.id === target.channelId && (!target.serverId || e.serverId === target.serverId));
+        if (matches.length === 0) {
+            return {
+                error: target.serverId
+                    ? `no registered channel "${target.channelId}" on server "${target.serverId}"`
+                    : `no registered channel "${target.channelId}"`,
+            };
+        }
+        if (matches.length > 1) {
+            return {
+                error: `channel id "${target.channelId}" is registered by more than one MCPL server; the destination must name its server`,
+            };
+        }
+        return { entry: matches[0] };
+    }
+    /**
+     * Publish `text` to one registered channel and report what the attempt
+     * established (PublishOutcome). The delivery executor behind plain speech
+     * (deliverSpeech / routeSpeech) and resident resends of held drafts.
+     * channel_publish (and publishForAgent, which shares its handler) resolves
+     * and sends on its own path, and reads its answer through the same
+     * publishReceiptOutcome and publishErrorOutcome.
+     *
+     * Resolution is exact (resolveDestination): `serverId` plus `channelId`
+     * when the caller has the server, otherwise the channel id must be
+     * registered by exactly one server (a shared id is refused, never routed
+     * through whichever server came first). An omitted `serverId` means "not
+     * in use"; a supplied one must be a non-empty server id, and an empty or
+     * non-string selector is refused rather than read as omission. It is not
+     * possible to send into a closed channel: a closed but registered
+     * destination is opened first (`openSource` names why), once its server
+     * and that server's channels.publish grant are known to take the send, so
+     * a refused send opens nothing; and a failed open sends nothing.
+     *
+     * Only the connector's `delivered: true` confirms a post. `failed` means
+     * nothing was posted: the attempt stopped before the request was written,
+     * or the connector answered `delivered: false` and named no message (no
+     * `messageId`, or null). Everything else is `unknown`: once the request
+     * has been handed to the transport, an error response, a timeout, a lost
+     * connection, or a missing, malformed or contradictory receipt (such as
+     * `delivered: false` beside a message id, valid or not) means the post may
+     * or may not exist, and the caller must not treat it as safe to retry
+     * blindly.
+     */
+    async publish(conversationId, text, target, openSource = 'opened-by-delivery') {
+        const at = () => Date.now();
+        const found = this.findExactEntry(target);
+        if ('error' in found)
+            return { status: 'failed', reason: found.error, at: at() };
+        const entry = found.entry;
+        const destination = {
+            serverId: entry.serverId,
+            channelId: entry.descriptor.id,
+            ...(entry.descriptor.label ? { label: entry.descriptor.label } : {}),
+        };
+        // A send that would be refused is refused before anything opens: a
+        // closed channel opens only for words that can go out.
+        const server = this.serverRegistry.getServer(entry.serverId);
+        if (!server) {
+            return { status: 'failed', destination, reason: `server "${entry.serverId}" not found`, at: at() };
+        }
+        // §14.1: channels/publish requires channels.publish in the grant. The
+        // host not sending is the enforcement.
+        if (!CapabilityGrant.of(server).has('channels.publish')) {
+            return {
+                status: 'failed',
+                destination,
+                reason: `channels.publish not in "${entry.serverId}"'s effective grant (§14.1)`,
+                at: at(),
+            };
+        }
+        if (!entry.open) {
+            try {
+                await this.openChannelNow(entry, openSource);
+                if (target.routed) {
+                    console.error(`[routeSpeech] ${conversationId}: locus ${logValue(entry.descriptor.id)} was closed — opened by delivery (speech implies engagement)`);
+                }
+                this.emitTraceFn({
+                    type: 'mcpl:channel-opened-by-send',
+                    serverId: entry.serverId,
+                    channelId: entry.descriptor.id,
+                });
+                if (openSource === 'opened-by-delivery') {
+                    try {
+                        this.onChannelAutoOpened?.({
+                            conversationId,
+                            serverId: entry.serverId,
+                            source: 'opened-by-delivery',
+                            channels: [{ channelId: entry.descriptor.id, label: entry.descriptor.label }],
+                        });
+                    }
+                    catch (err) {
+                        console.error('onChannelAutoOpened (delivery) failed:', err);
+                    }
+                }
+            }
+            catch (err) {
+                return {
+                    status: 'failed',
+                    destination,
+                    reason: `channel is closed and open failed: ${connectorText(err instanceof Error ? err.message : String(err))}`,
+                    at: at(),
+                };
+            }
+        }
+        let result;
+        try {
+            result = await server.sendChannelsPublish({
+                conversationId,
+                channelId: entry.descriptor.id,
+                content: [{ type: 'text', text }],
+            });
+        }
+        catch (err) {
+            return publishErrorOutcome(err, destination, at());
+        }
+        return publishReceiptOutcome(result, destination, at());
+    }
+    /**
+     * Plain speech for one turn segment: publish `text` to the turn's frozen
+     * locus and report the PublishOutcome. A failure (or an uncertain outcome)
+     * is surfaced as a trace and through onRouteFailure, so the agent learns
+     * its words did not (or may not have) reached anyone.
+     */
+    async deliverSpeech(conversationId, text, 
     /** 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
@@ -2394,110 +2656,75 @@ export class ChannelRegistry {
      *  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.
-        const fail = (channelId, reason) => {
-            console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
+    locusChannelId, 
+    /** `heldOnFailure`: the caller holds a `failed` delivery's words as a
+     *  draft with its own notice, so no failure marker is written for it.
+     *  An `unknown` outcome still gets its marker. */
+    opts) {
+        const fail = (channelId, reason, outcome) => {
+            const status = outcome.status === 'unknown' ? 'unknown' : 'failed';
+            const detail = outcome.detail !== undefined ? connectorText(outcome.detail) : undefined;
+            const detailText = detail !== undefined ? `; connector detail: ${detail}` : '';
+            console.error(`[routeSpeech] ${conversationId}: ${reason}${detailText} — speech ${status === 'unknown' ? 'delivery NOT confirmed' : 'NOT routed'} (${text.length} chars stay in chronicle)`);
             this.emitTraceFn({
                 type: 'mcpl:speech-route-failed',
                 conversationId,
                 channelId: channelId ?? '',
                 reason,
                 textLen: text.length,
+                outcome: status,
+                ...(detail !== undefined ? { detail } : {}),
             });
-            this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length });
-            return null;
+            if (status === 'unknown' || !opts?.heldOnFailure) {
+                this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length, outcome: status, ...(detail !== undefined ? { detail } : {}) });
+            }
+            return outcome;
         };
         // 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 reason = 'caller passed no locus (routing bug: every speech path must snapshot the turn locus)';
+            return fail(null, reason, { status: 'failed', reason, at: Date.now() });
         }
-        const channelId = locusChannelId;
-        if (!channelId) {
+        if (!locusChannelId) {
             // 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 reason = 'turn has no locus (no home/trigger channel; nothing to deliver into)';
+            return fail(null, reason, { status: 'failed', reason, at: Date.now() });
         }
-        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 outcome = await this.publish(conversationId, text, { channelId: locusChannelId, routed: true });
+        const channelId = outcome.destination?.channelId ?? locusChannelId;
+        if (outcome.status !== 'delivered') {
+            return fail(channelId, outcome.reason ?? 'delivery not confirmed', outcome);
         }
-        const server = this.serverRegistry.getServer(entry.serverId);
-        if (!server) {
-            return fail(channelId, `server "${entry.serverId}" not found`);
-        }
-        // §14.1: channels/publish requires channels.publish in the grant. The
-        // host not sending is the enforcement — a send to an ungranted server
-        // would have it act on authority it was never told it has.
-        if (!CapabilityGrant.of(server).has('channels.publish')) {
-            return fail(channelId, `channels.publish not in "${entry.serverId}"'s effective grant (§14.1)`);
-        }
-        const publishParams = {
-            conversationId,
-            channelId,
-            content: [{ type: 'text', text }],
-        };
-        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.
-        if (delivered === false) {
-            return fail(channelId, `server "${entry.serverId}" reported delivered:false for "${channelId}"`);
-        }
-        console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
+        console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${logValue(channelId)} (server=${outcome.destination.serverId}, delivered=true)`);
         this.emitTraceFn({
             type: 'mcpl:speech-routed',
             conversationId,
-            serverId: entry.serverId,
+            serverId: outcome.destination.serverId,
             channelId,
-            delivered,
+            delivered: true,
             textLen: text.length,
             text,
-            ...(messageId !== undefined ? { messageId } : {}),
+            // 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.
+            ...(outcome.messageId !== undefined ? { messageId: outcome.messageId } : {}),
         });
-        return { delivered, channelId, ...(messageId !== undefined ? { messageId } : {}) };
+        return outcome;
+    }
+    /** deliverSpeech, reduced to the confirmed delivery (null when there was none). */
+    async routeSpeech(conversationId, text, locusChannelId) {
+        const outcome = await this.deliverSpeech(conversationId, text, locusChannelId);
+        if (outcome.status !== 'delivered')
+            return null;
+        return {
+            delivered: true,
+            channelId: outcome.destination.channelId,
+            ...(outcome.messageId !== undefined ? { messageId: outcome.messageId } : {}),
+        };
     }
     async handleToolPublish(input) {
         // Resolve content: accept both `content` and `text` (backward compat)
@@ -2534,32 +2761,46 @@ export class ChannelRegistry {
                 isError: true,
             };
         }
-        try {
-            if (!CapabilityGrant.of(server).has('channels.publish')) {
-                return {
-                    success: false,
-                    error: `channels.publish not in "${server.id}"'s effective grant (§14.1)`,
-                    isError: true,
-                };
-            }
-            const publishParams = {
-                conversationId: '', // Framework will fill this when wired
-                channelId,
-                content: [{ type: 'text', text: messageText }],
-            };
-            const result = await server.sendChannelsPublish(publishParams);
-            return {
-                success: true,
-                data: result ?? { delivered: true },
-            };
-        }
-        catch (err) {
+        if (!CapabilityGrant.of(server).has('channels.publish')) {
             return {
                 success: false,
-                error: `Failed to publish to channel: ${err.message}`,
+                error: `channels.publish not in "${server.id}"'s effective grant (§14.1)`,
                 isError: true,
             };
         }
+        const publishParams = {
+            conversationId: '', // Framework will fill this when wired
+            channelId,
+            content: [{ type: 'text', text: messageText }],
+        };
+        const destination = {
+            serverId: entry.serverId,
+            channelId: entry.descriptor.id,
+            ...(entry.descriptor.label ? { label: entry.descriptor.label } : {}),
+        };
+        // The answer counts by the same rule as plain speech's: only the
+        // connector's delivered:true confirms a post.
+        let result;
+        let outcome;
+        try {
+            result = await server.sendChannelsPublish(publishParams);
+            outcome = publishReceiptOutcome(result, destination, Date.now());
+        }
+        catch (err) {
+            outcome = publishErrorOutcome(err, destination, Date.now());
+        }
+        if (outcome.status === 'delivered')
+            return { success: true, data: result };
+        // The connector's data may say what a multi-part send already posted.
+        const detail = outcome.status === 'unknown' && outcome.detail !== undefined ? ` Connector detail: ${connectorText(outcome.detail)}` : '';
+        return {
+            success: false,
+            error: (outcome.status === 'failed'
+                ? `Publish to ${channelId} failed: ${outcome.reason}. Nothing was posted.`
+                : `Publish to ${channelId} wasn't confirmed: ${outcome.reason}. ` +
+                    'It may or may not have been posted, so sending it again could post it twice.') + detail,
+            isError: true,
+        };
     }
 }
 //# sourceMappingURL=channel-registry.js.map