@animalabs/agent-framework 0.23.1 → 0.24.0

package/dist/src/mcpl/channel-registry.d.ts

@@ -19,6 +19,10 @@ import type { McplServerRegistry } from './server-registry.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import type { InboundSource } from './inbound-source.js';
+/** Why a channel is selected for opening after a failed open by speech or a
+ *  reply: its put-back couldn't be recorded, or the server's latest
+ *  announcement or the subscription policy lifted the default it restored. */
+export type SelectedForOpening = 'unrecorded' | 'server-bootstrap' | 'subscription-policy';
 type DesiredChannelState = 'open' | 'closed' | 'tuned-out';
 /**
  * Parameters of an active tune-out (issue #77), carried on the
@@ -34,8 +38,11 @@ export interface TuneOutParams {
     epochId: string;
     /** Subconscious summary cadence, in seconds. */
     cadenceSeconds: number;
-    /** Maximum messages dumped raw at cancel; above the cap the subconscious
-     *  curates a digest and `fetch_history` covers the rest. */
+    /** Maximum messages dumped raw at cancel, the newest. Where the residents'
+     *  strategies cap a message's size, the dump holds as many as fit whole in
+     *  one message, or, when even the newest doesn't, as much of the newest as
+     *  fits beside the cut's mark, if any does. For those left out the
+     *  subconscious curates a digest, and `fetch_history` covers them. */
     backlogCap: number;
     /** Wake invocations before the tune-out auto-cancels. */
     maxWakes: number;
@@ -47,6 +54,14 @@ export interface TuneOutParams {
      *  period chosen by the agent"). Unset = until cancelled. */
     expiresAtMs?: number;
 }
+/**
+ * The desired state `store`'s lifecycle log records for `channelId` on
+ * `serverId`, for a reader with no registry yet, as a serving boot's
+ * deferred-write flush is, before initializeMcpl: the last decision wins, as
+ * the registry's replay reads it (getDesiredState answers once there is a
+ * registry). undefined when no decision names it.
+ */
+export declare function desiredStateInLog(store: JsStore, serverId: string, channelId: string): DesiredChannelState | undefined;
 /** A registered channel entry, keyed by `{serverId}:{channelId}`. */
 interface ChannelEntry {
     serverId: string;
@@ -94,8 +109,27 @@ interface McplChannelIncomingEvent {
  * turn going on.
  */
 export declare function journalToolDescription(canSkipReply: boolean): string;
+/**
+ * channel_open's and channel_close's descriptions for an agent whose window doesn't hold a channel's traffic: an
+ * ephemeral run, whose store is its own unless it's where channel messages are stored (on a host with no residents,
+ * the first registered agent), and on a host that routes conversations every agent but a fork, since a channel's
+ * messages go to its fork or, unrouted, nowhere. The descriptions in CHANNEL_TOOL_DEFINITIONS, written for the agents
+ * that read a channel, promised such an agent what it never gets: "Messages that address you still reach you", and
+ * history "preceding the message that invited you" when nothing invites it. Given per agent (AgentFramework's
+ * getToolsForAgent), so a holder's cached tool list doesn't change.
+ *
+ * Both say the call is for every agent: the decision is recorded per server and channel (setDesiredState), so a run's
+ * close closes the channel for the agents whose windows hold it, which "its messages don't come to you" alone could
+ * read as costing nothing. They claim only what holds on both lanes: a push that names a channel is stored in the
+ * residents' shared slot whether or not the channel is open (handleMcplPushEvent), so on a routed host the residents
+ * get the channel's pushes, and a server may push while a channel is closed and send channels/incoming once it's
+ * open. So opening brings the caller none of the channel's messages, and closing stops none reaching it. The history
+ * channel_open asks for comes back in its result (handleToolOpen), so that clause is true for anyone.
+ */
+export declare const NON_HOLDER_CHANNEL_DESCRIPTIONS: Readonly<Record<'channel_open' | 'channel_close', string>>;
 /** Bound connector values for notices, logs and an outcome's reason. A
- *  PublishOutcome keeps the connector's structured data (`detail`) whole. */
+ *  PublishOutcome keeps the connector's structured data (`detail`) as the
+ *  connection gives it, its strings redacted (redactedData). */
 export declare function connectorText(value: unknown): string;
 /** Where a publish was resolved to go — named by the registry, never by
  *  the caller's spelling. */
@@ -105,6 +139,9 @@ export interface PublishDestination {
     /** The channel's registered label when the attempt was made. */
     label?: string;
 }
+/** One key per destination, its server and channel: unlike joining the two
+ *  with a separator, no two destinations share one, whatever their ids hold. */
+export declare function destinationKey(to: PublishDestination): string;
 /**
  * What one channels/publish attempt established (ChannelRegistry.publish).
  * - `delivered`: the connector returned `delivered: true`. A historical
@@ -127,11 +164,29 @@ export interface PublishOutcome {
     /** Why it failed, or why its outcome is unknown — for a connector error,
      *  its message, bounded (which may say what was already posted). */
     reason?: string;
-    /** The connector error's structured `data`, verbatim, when it sent one. */
+    /** The connector error's structured `data`, with the strings in it
+     *  redacted (redactedData), when it sent one. */
     detail?: unknown;
     /** When the outcome was established (epoch ms). */
     at: number;
 }
+/**
+ * Why the destination refused a publishForAgent before anything went out.
+ * Its words say the same, since both come from one check: the channel isn't
+ * registered here, it takes no posts, or its server is gone, this host is
+ * connecting to it, it's reconnecting, or it's up without channels.publish
+ * (serverReach); or the request wasn't sent, as its connection refused it
+ * before anything was written (McplRequestError's `not-sent`). A refusal of
+ * the caller's own input, such as no text or no channel id, carries none,
+ * and so does a publish that went out, whatever became of it: its words say
+ * whether it may have been posted.
+ */
+export type PublishRefusalReason = 'channel-not-registered' | 'inbound-only' | 'server-gone' | 'server-connecting' | 'server-down' | 'not-permitted' | 'not-sent';
+/** A tune-out's open answered for a tune-out that ended, or that a later
+ *  decision or a later tune-out replaced, while the open was out: by
+ *  openForTuneOut, and by a repeated tune_out whose tune-out isn't the one it
+ *  read before it waited. */
+export declare const TUNE_OUT_REPLACED: string;
 interface ChannelRegistryOptions {
     /**
      * An ordinary (uncoalesced) `channels/incoming` message has just been
@@ -144,22 +199,32 @@ interface ChannelRegistryOptions {
      * RFC-006: an admitted `channels/incoming` message carrying `coalesce`, with
      * the event the ordinary path would have queued. The handler decides
      * replace / append / withdraw and returns the per-message result. Throws a
-     * `CoalesceError` for a malformed or unauthorized occurrence.
+     * `CoalesceError` for a malformed or unauthorized occurrence. `firstView`
+     * says the coalescer delivered the message as the agent's first view of it,
+     * with the delivery's own `firstView` mark; it is the host's own, and isn't
+     * in the answer to the server.
      */
-    handleCoalescedIncoming?: (serverId: string, message: ChannelIncomingMessage, event: McplChannelIncomingEvent) => Promise<ChannelIncomingMessageResult>;
+    handleCoalescedIncoming?: (serverId: string, message: ChannelIncomingMessage, event: McplChannelIncomingEvent) => Promise<ChannelIncomingMessageResult & {
+        firstView?: true;
+    }>;
     /** Chronicle store used for durable desired channel lifecycle state. */
     store?: JsStore;
     /** Callback to determine whether an incoming message should trigger inference. */
     shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
     /**
-     * Called when a text-only turn's speech could NOT be delivered to its
-     * conversational locus — no locus, an unregistered channel, a missing
-     * server, or the server reporting `delivered: false`. Not called for an
-     * ephemeral run's speech with no locus, which is its caller's result
-     * (`takesGlobalFallback`). The host wires this to drop a
-     * `[discord-send-failed]` marker into chronicle so the failure is
-     * visible to the agent (and operator) rather than silently lost. Must not
-     * itself trigger inference (avoid wake loops).
+     * Called when a text-only turn's speech was not delivered to its
+     * conversational locus (`failed`), or may not have been (`unknown`), for
+     * whatever reason deliverSpeech gives, such as no locus, a channel that
+     * isn't registered or refuses speech, a missing server or grant, a failed
+     * open, the server reporting `delivered: false`, or a publish answered
+     * with an error, a timeout or a lost connection, after which whether it
+     * was posted is unknown. It isn't called for an ephemeral run's speech
+     * whose turn has no locus (a null locus), which is its caller's result
+     * (`takesGlobalFallback`), nor for a `failed` delivery whose caller holds
+     * its words with a notice of its own (deliverSpeech's `heldOnFailure`).
+     * The host wires this to drop a `[discord-send-failed]` marker into
+     * chronicle so the failure is visible to the agent (and operator) rather
+     * than silently lost. Must not itself trigger inference (avoid wake loops).
      */
     onRouteFailure?: (info: {
         conversationId: string;
@@ -198,9 +263,11 @@ interface ChannelRegistryOptions {
      * forks are spawned bound to a single channel (the framework tracks this in
      * `conversationAgentHomes` / `ConversationRouter.channelForAgent`); their
      * plain-text speech must route THERE. The process-global `defaultPublishChannel`
-     * tracks only the most-recent inbound across ALL channels, so with one fork per
-     * channel running concurrently it misroutes a fork's reply to whichever channel
-     * last spoke (item 3). Returns undefined for the trunk/primary agent, which has
+     * tracks only the most recent inbound message across ALL channels (reaction,
+     * reaction-removal, edit and deletion markers aside, apart from an edit the
+     * coalescer delivers on acceptance as the agent's first view), so with one
+     * fork per channel running concurrently it misroutes a fork's reply to
+     * whichever channel last spoke (item 3). Returns undefined for the trunk/primary agent, which has
      * no home and correctly falls back to the global locus (heartbeats, etc.).
      */
     homeChannelResolver?: (agentName: string) => string | undefined;
@@ -210,11 +277,12 @@ interface ChannelRegistryOptions {
      * turn. This is the fix for single-TRUNK agents (the only mode
      * connectome-host runs — it never exposes conversation forks). A trunk agent
      * has no fork home, so without this its plain-text speech falls back to the
-     * process-global `defaultPublishChannel`, which tracks the most-recent inbound
-     * across ALL channels and misroutes a reply to whichever channel last spoke
-     * under concurrency (item-3 redux). The framework keeps both on the live
-     * turn's routing state and exposes them here. For a heartbeat / no-trigger
-     * turn it resolves to undefined until the turn's locus is resolved, so that
+     * process-global `defaultPublishChannel`, which tracks the most recent inbound
+     * message across ALL channels (markers aside) and misroutes a reply to
+     * whichever channel last spoke under concurrency (item-3 redux). The
+     * framework keeps both on the live turn's routing state and exposes them
+     * here. For a heartbeat / no-trigger turn it resolves to undefined until the
+     * turn's locus is resolved, so that
      * resolution takes the global fallback, which the turn then keeps.
      * Consulted AFTER `homeChannelResolver` (a fork's home always wins), BEFORE
      * `defaultPublishChannel`.
@@ -234,6 +302,14 @@ interface ChannelRegistryOptions {
     takesGlobalFallback?: (conversationId: string) => boolean;
     /** Whether this framework has EventGate and can honor skip_reply self-wakes. */
     eventGatePresent?: boolean;
+    /**
+     * Whether this host is connecting to the server of this id: a connect or a
+     * restart of the id is in flight, or the policy exchange of the transport
+     * its registered connection is on is. Its channel tools and speech then say
+     * so, as its tool calls do, rather than read the empty grant meanwhile as a
+     * refusal (serverReach). It words a refusal only: the grant decides.
+     */
+    serverConnecting?: (serverId: string) => boolean;
 }
 /**
  * Who is actually making a channel tool call, as established by the
@@ -264,9 +340,17 @@ export declare class ChannelRegistry {
     private homeChannelResolver?;
     private activeChannelResolver?;
     private takesGlobalFallback?;
+    private serverConnecting?;
     private store?;
     /** Registered channels, keyed by `{serverId}:{channelId}`. */
     private channels;
+    /**
+     * Each outgoing stream, by `inferenceId`, with the destinations it has
+     * started at (destinationKey): the rest of the stream there goes on there,
+     * and its `complete` goes only there (sendOutgoingChunk). An entry goes
+     * with the stream's `complete` for its destination.
+     */
+    private takenStreams;
     /** Holds back repeats of the line for a message refused because its
      *  channel isn't registered (RefusalLines). */
     private unknownChannelLines;
@@ -315,9 +399,12 @@ export declare class ChannelRegistry {
      * sent at all.
      */
     private dmClassified;
-    /** Most recent incoming channel ID — used for speech routing / default publish. */
+    /** The channel of the most recent incoming message that isn't a reaction,
+     *  reaction removal, edit or deletion marker, apart from an edit the
+     *  coalescer delivers on acceptance as the agent's first view: used for
+     *  speech routing and the default publish. */
     private defaultPublishChannel;
-    /** Most recent incoming message metadata, used for buildChannelContext. */
+    /** The same message's id and thread, used for buildChannelContext. */
     private defaultPublishMessageId;
     private defaultPublishThreadId;
     /** Per-channel typing indicator timers. */
@@ -335,14 +422,71 @@ export declare class ChannelRegistry {
     private channelLifecycleTails;
     private serverRemovals;
     private lifecycleOutstanding;
+    private lifecycleQueuedRemovals;
     private unconfirmedChannelTargets;
+    private failedCloseTargets;
+    private tuneOutOpens;
+    private untargetedPushEntries;
+    private transportCloses;
     private invalidateTransportConfirmation;
     /** Whether the host directs this server's channel lifecycle (§14.1: its
      *  `channels.lifecycle` grant). Where it doesn't, the server opens and
      *  closes its own channels, and sends no receipt the host could wait for. */
-    private directsLifecycle;
-    /** A registration's entry: nothing about its transport is known until a
-     *  receipt for its target confirms it open or closed. */
+    directsLifecycle(serverId: string): boolean;
+    /** Whether a decided close holds words back from a channel: only where
+     *  the host directs the server's lifecycle. Without that grant the host
+     *  can't close the channel, and words go into a transport that is open,
+     *  as the open step's engagesDecidedClosed reads it too. */
+    private closeStands;
+    /** Where this server stands for a request this host would make of it
+     *  (ServerReach). One without a connection's state reads as connected.
+     *  A closed connection the host is restarting reads as connecting, as
+     *  one being connected does. */
+    private serverReach;
+    /**
+     * Why this host won't open or close this server's channels, for a caller
+     * that found its grant without channels.lifecycle (§14.1), which decides:
+     * the server's state says why. It isn't up, or it's up without that grant.
+     * Neither the grant's name, which is the operator's, nor an empty grant's
+     * refusal, which needn't be the server's, reaches the agent.
+     */
+    private lifecycleRefusal;
+    /**
+     * Why a send to this server's channels is refused before anything goes
+     * out, as one clause with what works from there, for a caller that found
+     * no server or a grant without channels.publish (§14.1), which decides:
+     * the server's state says why. Plain speech gives it as its reason, and
+     * channel_publish and speak_in_channel as theirs, so one refusal has one
+     * wording. `checked` is the connection whose grant refused, where that
+     * was read before the words waited: one the registry has replaced since
+     * says nothing about the server that stands now.
+     */
+    private sendRefusal;
+    /**
+     * What a failed channel_open or channel_close tells the agent. Its
+     * decision was recorded before the server was asked, and reconciling
+     * applies it when the server next registers the channel (for a push's
+     * placeholder, if it ever does), if this host directs their lifecycle then
+     * (laterClause). A decision the log refused changed nothing, so that comes
+     * first. A channel no longer registered
+     * can't be reached by any channel tool, so its text names none. A later
+     * decision that came first is what stands, so that comes next. Then the
+     * server's state: one that isn't up gets the change when it's back, though
+     * not a backscroll's history. For the request's own failure, its state is
+     * read now, since a request out when the server dropped may have taken
+     * effect, and reconciling settles it either way. A decision already in
+     * effect, with no other work for the channel under way, says so, as one
+     * whose backscroll alone failed is. Then the failure's kind, since each
+     * has its own next step (ChannelLifecycleError). A request's own failure
+     * is in the connection's words.
+     */
+    private lifecycleFailureText;
+    /** A registration's entry, or a push's (ensureChannelRegistered): nothing
+     *  about its transport is known until a receipt for its target confirms it
+     *  open or closed, or the channel's traffic shows it open, which it does
+     *  where the host doesn't direct the lifecycle, and for a push's entry
+     *  decided open or tuned out that no update has given a target
+     *  (handleIncoming). */
     private registerEntry;
     private hasPendingLifecycle;
     private handleCoalescedIncoming?;
@@ -397,15 +541,17 @@ export declare class ChannelRegistry {
      * locus. A push event from a closed channel must never mutate lifecycle
      * state: direct-address events are intentionally usable without subscribing.
      *
-     * Mirrors the lazy-registration inside handleIncoming(), but for channels
-     * that only ever arrive as push/events rather than channels/incoming — the
-     * motivating case is Discord DMs, which discord-mcpl forwards via push/event
-     * with the channel closed (`channelIsOpen:false`). Such a channel is never
-     * registered, so routeSpeech() can't resolve it and the agent's reply is
-     * silently dropped even though the inbound message proves the channel is
-     * reachable (item-3 redux, DM sub-case). Idempotent: a later authoritative
-     * channels/register or channels/changed overwrites this descriptor with the
-     * richer one.
+     * For channels that only ever arrive as push/events rather than
+     * channels/incoming — the motivating case is Discord DMs, which
+     * discord-mcpl forwards via push/event with the channel closed
+     * (`channelIsOpen:false`). Such a channel is never registered, so
+     * routeSpeech() can't resolve it and the agent's reply is silently dropped
+     * even though the inbound message proves the channel is reachable (item-3
+     * redux, DM sub-case). Its entry starts with its transport unknown, as a
+     * registration's does. Its traffic shows it open, for a channel decided
+     * open or tuned out, until an update gives it a target (handleIncoming).
+     * Idempotent: a later authoritative channels/register or channels/changed
+     * overwrites this descriptor with the richer one.
      */
     ensureChannelRegistered(serverId: string, channelId: string, label?: string, extraMetadata?: Record<string, unknown>): void;
     /**
@@ -425,7 +571,10 @@ export declare class ChannelRegistry {
      */
     stopTyping(channelId?: string): void;
     /**
-     * Get the default publish channel ID (most recent incoming channel).
+     * Get the default publish channel ID: the channel of the most recent
+     * incoming message that isn't a reaction, reaction removal, edit or
+     * deletion marker, apart from an edit the coalescer delivers on acceptance
+     * as the agent's first view.
      */
     getDefaultPublishChannel(): string | null;
     /**
@@ -444,7 +593,12 @@ export declare class ChannelRegistry {
     /** The registered label of `channelId` on exactly `serverId` (no
      *  cross-server first match), or undefined when it has none. */
     getChannelLabel(serverId: string, channelId: string): string | undefined;
-    isChannelOpen(channelId: string): boolean;
+    /** Whether `channelId`'s transport is open: on `serverId` where the caller
+     *  knows the channel's server, and otherwise on the first server found to
+     *  register that id (findChannelEntry). The map's key joins the two ids
+     *  with a colon, so another server's entry can sit under a key: it has to
+     *  be this server's (as in streamingServerAt). */
+    isChannelOpen(channelId: string, serverId?: string): boolean;
     getDesiredState(serverId: string, channelId: string): DesiredChannelState | undefined;
     /**
      * Get all open channels.
@@ -479,6 +633,36 @@ export declare class ChannelRegistry {
      * server's channels don't linger and route speech into the void.
      */
     removeServer(serverId: string): void;
+    /**
+     * The server's transport closed. Whatever it confirmed about a channel,
+     * open or closed, held for that transport only, so each of the server's
+     * channels reads as a registration's does: not open, and not confirmed
+     * closed. Where the host directs the server's lifecycle, a receipt
+     * confirms it again: a `channel_open` asks the server, and delivery opens
+     * before it publishes (an untargeted push entry's traffic confirms it, as
+     * before). Where the host doesn't, its traffic does, as after a
+     * registration. The entries, their desired state, labels and tune-out
+     * state stay, since the server is expected back (`removeServer` is for one
+     * that isn't).
+     *
+     * What was under way here at the close confirms nothing afterwards
+     * (transportCloses). Traffic that arrived before the close and is admitted
+     * after it, behind the coalescer's await, marks nothing open
+     * (handleIncoming). A lifecycle request sent before the close is answered
+     * for an older transport: its failure withdraws the open flag, and its
+     * receipt confirms nothing, and the operation tries again, which on the
+     * closed connection is refused as unreachable, so the decision waits for
+     * the next registration (runLifecycleOperation's sameTarget). What the
+     * connection holds across the boundary is another matter: it reaches
+     * handleIncoming after the next transport's grant, as that transport's
+     * traffic (resetPolicyForTransportBoundary), as it does after a
+     * registration.
+     *
+     * The framework calls this first in its handler for the connection's
+     * `close`, so a registration on the next transport, whose entries are new,
+     * can't come first and lose its confirmations to it.
+     */
+    transportClosed(serverId: string): void;
     /**
      * Stop all typing intervals and clear all channel registrations.
      */
@@ -488,7 +672,9 @@ export declare 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
+     * change unmade, and memory and the log still agree. A record that changes
+     * no memory, as a decline's of the invitation it declined, is its
+     * caller's to handle (handleToolDecline). 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
@@ -627,9 +813,59 @@ export declare class ChannelRegistry {
      * Enter (or re-enter with fresh params) the tuned-out state for a channel.
      * Re-entering under a new epochId replaces the active epoch; the previous
      * epoch's stamped messages stay excluded (stamps are permanent) and its
-     * wake count is superseded. Transport stays open (see reconcile).
+     * wake count is superseded. Its transport is kept open: tune_out opens a
+     * closed one (openForTuneOut), and reconcile opens it at the channel's
+     * registration.
      */
     enterTuneOut(serverId: string, channelId: string, params: TuneOutParams, source: string): void;
+    /**
+     * Make a tuned-out channel's transport match its tune-out, which keeps it
+     * open so its traffic reaches the subconscious (TuneOutParams). The
+     * tune-out is recorded first (enterTuneOut), and this writes no decision,
+     * so the tune-out stands whatever becomes of the open. Lifecycle work
+     * queued for the channel goes first, until none is left, since each
+     * operation reads the decision when it runs and so opens a channel tuned
+     * out meanwhile; its own failure, such as a close the server refused,
+     * isn't this open's. Then the state is read. Where this host directs the
+     * lifecycle and the transport isn't confirmed open, the channel's
+     * lifecycle queue opens it once (applyDesiredChannelState reads a
+     * tune-out as open), and the answer waits for the work queued after it
+     * too, such as a registration that came back, and comes from the state
+     * that work leaves. Returns nothing where the transport is open, or, for
+     * tune_out's answer, why the channel's messages don't or may not reach the
+     * subconscious yet and when they will, or that the tune-out isn't in
+     * effect any more. A call while this tune-out's open is in flight, as a
+     * repeated tune_out makes, gets that open's answer rather than send
+     * another.
+     */
+    openForTuneOut(serverId: string, channelId: string): Promise<string | undefined>;
+    /**
+     * Whether a tune_out repeated now has nothing to wait for and finds its
+     * channel's transport open, as the tune-out reads it: no lifecycle work
+     * queued for the channel, since the tune-out's own call may still be
+     * waiting for the work queued after its open; its server up; and an open
+     * flag the tune-out takes as open (tuneOutReadsOpen). Where it doesn't,
+     * the repeat goes through openForTuneOut, which joins this tune-out's open
+     * in flight, or waits for the queued work and, where this host can open
+     * the channel, tries the open again.
+     */
+    tuneOutTransportOpen(serverId: string, channelId: string): boolean;
+    /**
+     * Whether a tune-out takes an entry's transport as open: its open flag,
+     * unless a close for it failed since it was confirmed (failedCloseTargets),
+     * since that close may have taken effect. The other readers take any flag
+     * a failed request left as it was (runLifecycleOperation), since a send
+     * through it fails where it can be seen, and channel_open sends an open
+     * after a failed close anyway, its decision having been closed. A
+     * tune-out's success says traffic will arrive, nothing would show it
+     * doesn't, and the decision it replaced isn't known here. An open that
+     * failed, as a redundant one queued behind a confirming one may, can't
+     * have closed the channel: one for the current target leaves the flag as
+     * it was, so an open flag stays open (one for a target no longer current
+     * withdraws it).
+     */
+    private tuneOutReadsOpen;
+    private openTuneOutTransport;
     /**
      * End the active tune-out, returning the channel to `nextState`.
      * The caller (tune-out coordinator) owns the dump/notice flow; this is
@@ -670,14 +906,24 @@ export declare class ChannelRegistry {
     writeCoordinatorState(stateId: string, value: unknown): void;
     /**
      * Publish into a channel on behalf of a named non-resident agent (the
-     * subconscious's speak_in_channel). Same delivery path as the
-     * channel_publish tool; the agent name rides the speech-routed trace.
+     * subconscious's speak_in_channel). Same delivery path, and the same result
+     * as the channel_publish tool apart from `reason` below. Its traces carry the agent's name and follow
+     * the publish's outcome as deliverSpeech's do: speech-routed after a
+     * confirmed delivery, and speech-route-failed otherwise, `unknown` when the
+     * words may have been posted and `failed` when nothing was, a refusal before
+     * the publish included. The routed trace carries no message id, as before:
+     * nothing here reads one, and a consumer that edits the newest traced
+     * message in a channel would have this post to edit when an interruption of
+     * the resident matches none. A refusal of the destination before anything
+     * went out carries its `reason` (PublishRefusalReason), so a caller can act
+     * on why nothing was posted without reading the words.
      */
     publishForAgent(channelId: string, text: string, agentName: string): Promise<{
         success: boolean;
         data?: unknown;
         error?: string;
         isError?: boolean;
+        reason?: PublishRefusalReason;
     }>;
     /**
      * Consume the old recipe policy exactly once. It seeds Chronicle for
@@ -707,6 +953,25 @@ export declare class ChannelRegistry {
     private applyDesiredChannelState;
     /** One queued lifecycle operation, run when its turn in the queue comes. */
     private runLifecycleOperation;
+    /** Whether lifecycle work already outstanding for the channel will carry out
+     *  its current decision: some is, and the newest was queued since its
+     *  server's registrations were last removed, so it won't cancel when it
+     *  would run. Each operation reads the decision when it runs. It answers for
+     *  now: a removal after it cancels that work too, and takes the channel's
+     *  entry with it, so the channel's next registration by channels/register,
+     *  or as added by channels/changed, carries the decision out, where this
+     *  host directs the lifecycle then. A push's registration
+     *  (ensureChannelRegistered) queues no lifecycle work. So where a push
+     *  re-makes an entry that a channels/changed removal took while an RPC for
+     *  the old entry was out, the operation running that RPC carries the
+     *  decision out for the push's entry only if the RPC is answered: a failed
+     *  one rethrows, since its retry covers only a retarget of its own entry.
+     *  This answers true meanwhile, so a channels/changed update that retargets
+     *  the push's entry is left to that operation, and stays undone after a
+     *  failed RPC until lifecycle work is queued for the channel again
+     *  (applyDesiredChannelState). No server we know of sends `updated` for a
+     *  channel it has removed. */
+    private outstandingWorkCarriesOut;
     /**
      * A server that answered an open with another channel really opened that
      * one. When it's registered here and the host wants it closed, close it
@@ -717,11 +982,22 @@ export declare class ChannelRegistry {
      * doesn't know needs nothing: §14.5 refuses its traffic.
      */
     private closeSubstitutedChannel;
+    /**
+     * Carry out a channel's decision through its lifecycle queue, for a
+     * transport the server may have opened without the host's knowing: one it
+     * opened for another channel's request (closeSubstitutedChannel), or one a
+     * failed open's request may have reached (openChannelNow). The decision is
+     * a closed one, except after a failed open whose put-back the server's
+     * latest announcement or the policy lifted. A failure is reported as a
+     * trace; the decision stands.
+     */
+    private applyThroughQueue;
     /**
      * Join outstanding lifecycle work without recording new intent. Retargeting
      * may have invalidated open confirmation while the decision remains pending.
-     * A close that settles during the wait remains authoritative; waiting for
-     * it is not an instruction to open the channel again.
+     * A close that settles during the wait remains authoritative where the host
+     * directs the server's lifecycle (closeStands); waiting for it is not an
+     * instruction to open the channel again.
      */
     private waitForOpenChannel;
     private reconcileChannels;
@@ -736,6 +1012,13 @@ export declare class ChannelRegistry {
     descriptorsForServer(serverId: string): ChannelDescriptor[];
     /** Server id owning a registered channel (by descriptor id), or null. */
     getChannelServerId(channelId: string): string | null;
+    /**
+     * The server that declared this channel inbound-only (isInboundOnly), or
+     * undefined when it isn't one. The notices name that server. A caller that
+     * knows the channel's server passes it; otherwise the channel is found by
+     * its id alone (findChannelEntry).
+     */
+    inboundOnlyServer(channelId: string, serverId?: string): string | undefined;
     /**
      * Find a channel entry by channelId (searches across all servers).
      * Returns the first match.
@@ -750,21 +1033,56 @@ export declare class ChannelRegistry {
     /**
      * Record durable desired-open intent, then queue the channel's lifecycle
      * work (applyDesiredChannelState), which tells the server to subscribe and
-     * marks the live entry open on a receipt for its current target. Every
-     * open the agent or its speech asks for — the channel_open tool, delivery
+     * marks the live entry open on a receipt for its current target, applying
+     * an inbound-only declaration the answer carries (applyOpenDeclaration).
+     * Every open the agent or its speech asks for — the channel_open tool, delivery
      * into a closed locus, an explicit send into a closed channel — comes
      * here. Reconciliation queues that work directly, as the closes do
      * (channel_close, a decline, and the close of a substituted channel).
-     * Desired state is recorded BEFORE the server round-trip: intent sticks
-     * even if the subscribe fails, and reconciliation retries later.
-     * Automatic delivery needs open transport, not a change of attention:
-     * preserve tune-out epochs both before and during the round-trip.
+     * Desired state is recorded BEFORE the server round-trip. The agent's own
+     * open is a decision about the channel: it sticks even if the subscribe
+     * fails, and reconciliation retries later. An open by speech or a reply is
+     * incidental to its words: when its round-trip fails, the decision it
+     * wrote goes back to the one it replaced, so the agent, told the channel
+     * is closed and the open failed, isn't later put into it by that decision.
+     * That holds only while the record is still the one it wrote: a decision
+     * made meanwhile stands, and the failure then comes as `overtaken`
+     * (ChannelLifecycleError). Where the decision put back is a pure default,
+     * nobody had decided, so the channel then follows its server's latest
+     * announcement and the policy: a re-announcement during the round-trip
+     * found the open's own record and lifted nothing. If they select it for
+     * opening, the failure says so (`selected-again`). And since
+     * a failed request may have reached the server, the decision that stands
+     * is carried out on the wire too. An open by speech or a reply that can't
+     * send its request, on a server without channels.lifecycle, writes
+     * nothing. Automatic delivery needs open transport, not a change of
+     * attention: preserve tune-out epochs both before and during the
+     * round-trip.
      *
      * `opened` says whether this call turned a closed channel open, which is
      * what the delivery and reply notices tell the resident. Reconfirming the
      * transport of a channel already decided open or tuned out isn't one.
      */
     private openChannelNow;
+    /**
+     * An open's answer carries the server's descriptor for the channel
+     * (§14.3), the first place a lazily registered channel's own declaration
+     * can arrive. runLifecycleOperation hands it here, wherever the host opens
+     * a channel, once the answer is known to be for the channel's current
+     * entry and target. An answer that names another channel never arrives
+     * here: it's a substitution, which fails the open. One whose channel names
+     * no id is this channel's, as runLifecycleOperation takes it, so its
+     * declaration applies too.
+     *
+     * Only an inbound-only declaration is applied. The answer isn't always the
+     * server's latest word: a `channels/changed` that arrives in the same read
+     * as the answer is handled before the open's operation resumes, so the
+     * answer is applied over it. Applying only a refusal keeps that race
+     * fail-closed: a stale answer can keep a channel refused until the
+     * server's next update, but never lift a newer refusal. A server lifts its
+     * declaration by changing or registering the channel again.
+     */
+    private applyOpenDeclaration;
     /**
      * Resolve a `>>` prose-routing target (explicit prose routing —
      * docs/explicit-prose-routing.md) to a registered channel.
@@ -778,14 +1096,25 @@ export declare class ChannelRegistry {
      *
      * Ambiguity is an error carrying candidates — never a guess: this is the
      * mechanism that makes prose misdelivery structurally impossible.
+     *
+     * `forSpeech` is for a target the agent's speech will be posted to: a
+     * channel its server declared inbound-only (isInboundOnly) then resolves
+     * to an error that says so, since nothing is published there, and that
+     * names the channel as `refusedChannelId`, so a caller can tell a refused
+     * channel from a name that resolved to nothing. Without it, as for reading
+     * a channel's history, any registered channel resolves.
      */
-    resolveProseTarget(spec: string): {
+    resolveProseTarget(spec: string, opts?: {
+        forSpeech?: boolean;
+    }): {
         channelId: string;
         label?: string;
     } | {
         error: string;
         candidates?: string[];
+        refusedChannelId?: string;
     };
+    private resolveTargetByName;
     /**
      * The `>>` target to show an agent for a channel: one whitespace-free token
      * that `resolveProseTarget()` maps back to this same channel. The prefix
@@ -808,12 +1137,24 @@ export declare class ChannelRegistry {
      * 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).
+     * tools receive whatever the agent typed). An `open-failed` answer says
+     * whether the open that failed was one that would have opened a channel
+     * not selected open (`opening`), as opposed to one reconfirming the
+     * transport of a channel already selected open or tuned out. It isn't one
+     * either where a decision made during its round-trip replaced it
+     * (`overtaken`), or where queued lifecycle work left the
+     * channel closed before any open was sent. `selectedForOpening` says the
+     * channel is selected for opening after the failure, and why: the put-back
+     * couldn't be recorded (`put-back-unrecorded`), or the server's latest
+     * announcement or the policy lifted the default it restored
+     * (`selected-again`).
      */
     openIfClosedForSend(rawChannelId: string, serverId?: string): Promise<{
         status: 'opened' | 'already-open' | 'unknown-channel' | 'ambiguous' | 'open-failed';
         channelId?: string;
         label?: string;
+        opening?: boolean;
+        selectedForOpening?: SelectedForOpening;
     }>;
     private handleToolOpen;
     private handleToolClose;
@@ -850,29 +1191,47 @@ export declare class ChannelRegistry {
      */
     private handleToolSkipReply;
     /**
-     * Host-owned output routing (see forking-knowledge-miner LOCUS-ROUTING-DESIGN).
-     * Publish the agent's plain-text speech to the current conversational locus
-     * (the most recent incoming channel, tracked cross-surface here in the host).
-     * Called by the framework on a text-only turn — replaces the per-surface
-     * sticky auto-post that used to live in discord-mcpl. Returns null when there
-     * is no locus / the channel or its server can't be resolved (in which case
-     * the speech simply stays in chronicle + module surfaces).
+     * MCPL Spec 14.3 outgoing streaming: forward a text delta to the server
+     * owning the channel. The framework sends each piece of prose once its
+     * publish succeeds, so a stream carries only what was published.
+     * Emitted only when that server's grant has `channels.streaming` —
+     * servers that never opted in receive nothing. Fire-and-forget and never
+     * throws: streaming is an observer surface; the authoritative delivery is
+     * channels/publish.
+     *
+     * `to` is the destination the publish went to, its server and channel.
+     * The chunk goes there while that server registers that channel (Spec
+     * 14.3: the recipient is "the server that registered the target
+     * channel"). A stream doesn't start in a channel its server has declared
+     * inbound-only (#350's rule), not even for a publish delivered there just
+     * before the declaration. One that started there before it goes on, since
+     * the declaration doesn't unregister the channel: a later chunk is for a
+     * publish delivered before it. A bare channel id is resolved as before, to
+     * the one server that registers it, at each call (streamingServerFor), and
+     * keeps no record: a stream sent by destination ends by destination, since
+     * only a destination's `complete` removes its record.
      */
-    /** Resolve the outbound locus (fork HOME → this-turn's TRIGGERING channel →
-     *  process-global default). Public so a multi-segment caller can snapshot it
-     *  ONCE and pin every segment to it via routeSpeech's `overrideChannelId`. */
+    sendOutgoingChunk(to: string | PublishDestination, conversationId: string, inferenceId: string, index: number, delta: string): void;
     /**
-     * MCPL Spec 14.3 outgoing streaming: forward a moderated text delta to the
-     * server owning the channel, AS THE MODEL GENERATES. Emitted only when that
-     * server declared `channels.streaming` in its initialize capabilities —
-     * servers that never opted in (the whole existing fleet) receive nothing.
-     * Fire-and-forget and never throws: streaming is an observer surface; the
-     * authoritative delivery is the eventual channels/publish.
+     * Spec 14.3 companion: final moderated content per channel at stream end.
+     * Given a destination, it goes only where the stream started
+     * (sendOutgoingChunk), while that server still registers that channel,
+     * inbound-only or not, and its grant has `channels.streaming`: once per
+     * destination, whose consumer, such as a TTS utterance, finalizes on it
+     * and reconciles any chunk it missed. A bare channel id is resolved as
+     * before (streamingServerFor).
      */
-    sendOutgoingChunk(channelId: string, conversationId: string, inferenceId: string, index: number, delta: string): void;
-    /** Spec 14.3 companion: final moderated content per channel at stream end. */
-    sendOutgoingComplete(channelId: string, conversationId: string, inferenceId: string, text: string): void;
+    sendOutgoingComplete(to: string | PublishDestination, conversationId: string, inferenceId: string, text: string): void;
     private streamingServerFor;
+    /**
+     * A destination's server, for a stream message: while that server
+     * registers that channel, and its grant has `channels.streaming` (as in
+     * streamingServerFor). A stream doesn't start in an inbound-only channel.
+     */
+    private streamingServerAt;
+    /** Resolve the outbound locus (fork HOME → this-turn's TRIGGERING channel →
+     *  process-global default). Public so a multi-segment caller can snapshot it
+     *  ONCE and pin every segment to it via routeSpeech's `overrideChannelId`. */
     resolveLocus(conversationId: string): string | null;
     /** The process-global fallback channel for this conversation, or null when it takes none (takesGlobalFallback). */
     private globalFallbackFor;
@@ -908,7 +1267,33 @@ export declare class ChannelRegistry {
      * 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.
+     * a send refused before the open opens nothing; and a failed open sends
+     * nothing.
+     *
+     * A channel its server declared inbound-only (isInboundOnly) takes nothing
+     * the host would post, whichever path the words took, a drafts resend
+     * included: it's refused before anything opens. The channel's queued
+     * lifecycle work and the open await the server, and a channels/changed
+     * update, a re-register or the open's own answer (applyOpenDeclaration)
+     * may declare the channel inbound-only meanwhile, or a removal take it
+     * away. So the check just before the publish, after every await, reads
+     * the channel's registration as it is then, and refuses one that is gone
+     * or inbound-only, or whose server's grant no longer has channels.publish.
+     * A removal during a wait already fails it there (waitForOpenChannel); the
+     * check also catches one made after the last wait, as the opening's notice
+     * can. A registration nothing has confirmed open, such as one that
+     * replaced the one waited for or a retarget of it, or one whose close now
+     * stands (where the host directs the server's lifecycle), is treated as at
+     * the first wait: the words wait for its queued lifecycle work, and the
+     * check runs again on the registration that work leaves. Words refused
+     * after an open for a declaration leave the channel open, and the agent
+     * gets the failure for the words. An open by delivery (`openSource`
+     * 'opened-by-delivery', the default) that turned a closed channel open
+     * also gives the notice that it's open, which says how to close it to a
+     * reader that can.
+     * One that only reconfirmed the transport of a channel already decided
+     * open or tuned out changes no decision, and gives none. When the
+     * registration is gone, the failure says the channel was removed.
      *
      * Only the connector's `delivered: true` confirms a post. `failed` means
      * nothing was posted: the attempt stopped before the request was written,
@@ -932,9 +1317,13 @@ export declare class ChannelRegistry {
      * 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. An ephemeral run's
-     * speech with no locus is the exception: it is its caller's result, so it
-     * returns as not delivered and surfaces nothing.
+     * its words did not (or may not have) reached anyone. A `failed` one whose
+     * caller holds its words with a notice of its own (`heldOnFailure`) gets
+     * the trace but not onRouteFailure. An ephemeral run's speech with no locus
+     * (null) is its caller's result: it returns as not delivered and surfaces
+     * nothing. This is host-owned output routing (see forking-knowledge-miner
+     * LOCUS-ROUTING-DESIGN), which replaced the per-surface sticky auto-post
+     * that used to live in discord-mcpl.
      */
     deliverSpeech(conversationId: string, text: string, 
     /** The turn's FROZEN locus, snapshotted once by the caller (resolveLocus
@@ -956,9 +1345,16 @@ export declare class ChannelRegistry {
     /** deliverSpeech, reduced to the confirmed delivery (null when there was none). */
     routeSpeech(conversationId: string, text: string, locusChannelId: string | null): Promise<{
         delivered: boolean;
+        serverId: string;
         channelId: string;
         messageId?: string;
     } | null>;
+    /**
+     * channel_publish, and the subconscious's speak_in_channel
+     * (publishForAgent), which shares its delivery. Where an agent finds a
+     * channel id differs: the subconscious isn't offered channel_list, and is
+     * given speak_in_channel for the tuned-out channels whose messages it reads.
+     */
     private handleToolPublish;
 }
 export {};