@animalabs/agent-framework 0.26.2 → 0.27.0

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

@@ -62,7 +62,7 @@ export interface TuneOutParams {
  * 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}`. */
+/** A registered channel entry, keyed by its server and id (destinationKey). */
 interface ChannelEntry {
     serverId: string;
     descriptor: ChannelDescriptor;
@@ -131,17 +131,35 @@ export declare const NON_HOLDER_CHANNEL_DESCRIPTIONS: Readonly<Record<'channel_o
  *  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. */
-export interface PublishDestination {
+/**
+ * A registered channel, by its server and its id. MCPL requires a channel id
+ * to be unique only within one server's connection (§14.2), so two servers
+ * can each register `general`, and only the pair names one of them.
+ */
+export interface ChannelRef {
     serverId: string;
     channelId: string;
+}
+/** Where a publish was resolved to go — named by the registry, never by
+ *  the caller's spelling. */
+export interface PublishDestination extends ChannelRef {
     /** 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;
+/** One key per channel, its server and id: unlike joining the two with a
+ *  separator, no two channels share one, whatever their ids hold. */
+export declare function destinationKey(to: ChannelRef): string;
+/** Whether two refs name the same channel. Two absent refs are the same:
+ *  neither names a channel. */
+export declare function sameChannel(a: ChannelRef | null | undefined, b: ChannelRef | null | undefined): boolean;
+/**
+ * A channel's server-qualified name, `serverId:channelId`. A name given as a
+ * string (a tool's channelId, a `>>` target, a host's call) may take this
+ * form to pick one server's channel where several servers register the id.
+ * It is looked up among the registered pairs, never split at a colon, since
+ * ids hold colons (ChannelRegistry.entriesNamed).
+ */
+export declare function qualifiedChannelName(ref: ChannelRef): string;
 /**
  * What one channels/publish attempt established (ChannelRegistry.publish).
  * - `delivered`: the connector returned `delivered: true`. A historical
@@ -173,7 +191,9 @@ export interface PublishOutcome {
 /**
  * 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
+ * registered here, the name given means more than one registered channel
+ * (`shared-id`: a ref picks one, as a server-qualified name does where it names
+ * one channel alone), 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
@@ -181,7 +201,7 @@ export interface PublishOutcome {
  * 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';
+export type PublishRefusalReason = 'channel-not-registered' | 'shared-id' | '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
@@ -229,6 +249,8 @@ interface ChannelRegistryOptions {
     onRouteFailure?: (info: {
         conversationId: string;
         channelId: string | null;
+        /** The channel's server, beside `channelId` whenever the failure names a channel. */
+        serverId?: string;
         reason: string;
         textLen: number;
         /** `failed`: nothing was posted; `unknown`: the request was dispatched
@@ -270,7 +292,7 @@ interface ChannelRegistryOptions {
      * 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;
+    homeChannelResolver?: (agentName: string) => ChannelRef | undefined;
     /**
      * Resolve an agent's channel for its CURRENT inference turn, by agent name:
      * the turn's locus once it has one, else the channel that triggered the
@@ -285,9 +307,11 @@ interface ChannelRegistryOptions {
      * 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`.
+     * `defaultPublishChannel`. Null where the turn deliberately has no channel,
+     * as one woken for a channel id two servers register, given without its
+     * server: that takes no fallback either.
      */
-    activeChannelResolver?: (agentName: string) => string | undefined;
+    activeChannelResolver?: (agentName: string) => ChannelRef | null | undefined;
     /**
      * Whether a conversation takes the process-global fallback, the channel of
      * the most recent delivered inbound message: as where its plain speech lands
@@ -323,11 +347,23 @@ export type ChannelToolOrigin = {
 } | {
     kind: 'agent';
     agentName: string;
+    /** For a call made inside one of the agent's turns, that turn's own
+     *  channels, every channel that has been its trigger or its locus: a
+     *  name one of them answers to by its id means that channel
+     *  (ChannelRegistry.ownChannelNamed). */
+    own?: readonly ChannelRef[];
 };
 /** 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. */
 export declare const MACHINE_CLOSE_SOURCES: Set<string>;
+/** A close a module made through its own tool call (ctx.callTool) without a
+ *  machine source, such as connectome-host's mentions mode: a decision the
+ *  module owns, with its own way back. Speech leaves it closed, as it does a
+ *  channel the agent closed (speechOpens), but the agent isn't told how to
+ *  open it, since channel_open alone would undo only part of what the
+ *  module did. */
+export declare const MODULE_CLOSE_SOURCE = "module-tool";
 export declare class ChannelRegistry {
     private serverRegistry;
     private featureSetManager;
@@ -342,7 +378,11 @@ export declare class ChannelRegistry {
     private takesGlobalFallback?;
     private serverConnecting?;
     private store?;
-    /** Registered channels, keyed by `{serverId}:{channelId}`. */
+    /**
+     * Registered channels, keyed by their server and id (destinationKey): a
+     * key that joined the two with a separator would let server `a`'s channel
+     * `b:room` and server `a:b`'s channel `room` share one entry.
+     */
     private channels;
     /**
      * Each outgoing stream, by `inferenceId`, with the destinations it has
@@ -407,10 +447,12 @@ export declare class ChannelRegistry {
     /** The same message's id and thread, used for buildChannelContext. */
     private defaultPublishMessageId;
     private defaultPublishThreadId;
-    /** Per-channel typing indicator timers. */
+    /** Per-channel typing indicator timers, by destinationKey, with the
+     *  channel each one types in. */
     private typingIntervals;
-    /** Per-channel typing metadata — carried on the 7s refresh so the target
-     *  server keeps getting the same routing hints (e.g. Zulip topic). */
+    /** Per-channel typing metadata, by destinationKey — carried on the 7s
+     *  refresh so the target server keeps getting the same routing hints (e.g.
+     *  Zulip topic). */
     private typingMetadata;
     /** Chronicle-projected desired lifecycle state, keyed by server + channel.
      *  Provenance is kept so reconcile can tell a pure default (nobody ever
@@ -424,6 +466,7 @@ export declare class ChannelRegistry {
     private lifecycleOutstanding;
     private lifecycleQueuedRemovals;
     private unconfirmedChannelTargets;
+    private answeredElsewhere;
     private failedCloseTargets;
     private tuneOutOpens;
     private untargetedPushEntries;
@@ -436,7 +479,7 @@ export declare class ChannelRegistry {
     /** 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. */
+     *  as the open step reads it too (speechOpens). */
     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.
@@ -555,32 +598,42 @@ export declare class ChannelRegistry {
      */
     ensureChannelRegistered(serverId: string, channelId: string, label?: string, extraMetadata?: Record<string, unknown>): void;
     /**
-     * Start sending typing indicators for a channel.
+     * Start sending typing indicators for a channel: the channel a ref names,
+     * or each channel a name given as a string means (entriesNamed). A host
+     * names channels by the ids it keeps (connectome-host's activity module),
+     * and typing posts nothing, so a name two servers' channels answer to
+     * shows typing in both, rather than in neither or in whichever registered
+     * first. Where two servers reach one platform channel, two bots can then
+     * show typing there.
      *
      * Sends a typing notification immediately and every 7 seconds thereafter.
      * Discord typing indicators last ~10s, so 7s keeps them alive.
      *
-     * No-op if already typing on this channel.
+     * No-op for a channel already typing, or not registered.
      */
-    startTyping(channelId: string, metadata?: Record<string, unknown>): void;
+    startTyping(channel: string | ChannelRef, metadata?: Record<string, unknown>): void;
+    private startTypingAt;
     /**
      * Stop sending typing indicators.
      *
-     * If channelId is specified, stops typing on that channel only.
-     * If no channelId, stops all typing indicators.
-     */
-    stopTyping(channelId?: string): void;
+     * Given a ref, stops typing in that channel. Given a name as a string,
+     * stops typing in each channel the name means, by its id or its
+     * server-qualified name (entriesNamed), as startTyping started it: a
+     * channel types only while it's registered, since startTypingAt starts
+     * none that isn't and each removal stops its channel's typing. Given
+     * nothing, stops all typing indicators.
+     */
+    stopTyping(channel?: string | ChannelRef): void;
+    /** The explicit 'stop' for a channel whose typing ended, while its
+     *  server still registers it. */
+    private sendTypingStop;
     /**
      * 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;
-    /**
-     * Get the descriptor for a channel by its channelId (first match across
-     * servers). Used by the conversation router for DM classification.
-     */
+    getDefaultPublishChannel(): ChannelRef | null;
     /**
      * RFC-006 §3.2: is `channelId` registered BY `serverId` through a server
      * declaration (channels/register, channels/changed) or an authorized open?
@@ -589,16 +642,13 @@ export declare class ChannelRegistry {
      * registration.
      */
     isDeclaredChannel(serverId: string, channelId: string): boolean;
-    getDescriptor(channelId: string): ChannelDescriptor | undefined;
+    /** A registered channel's descriptor. Used by the conversation router for
+     *  DM classification. */
+    getDescriptor(ref: ChannelRef): ChannelDescriptor | undefined;
     /** 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;
-    /** 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;
+    isChannelOpen(ref: ChannelRef): boolean;
     getDesiredState(serverId: string, channelId: string): DesiredChannelState | undefined;
     /**
      * Get all open channels.
@@ -620,13 +670,42 @@ export declare class ChannelRegistry {
      * decision it actually is. Absent origin is treated as agent-origin (the
      * untrusted-safe default).
      */
-    handleChannelToolCall(toolName: string, input: unknown, origin?: ChannelToolOrigin): Promise<ToolResult>;
-    /**
-     * Build channel context for inclusion in beforeInference params.
-     *
-     * Returns undefined if no channels are active.
-     */
-    buildChannelContext(agentName?: string): ChannelContext | undefined;
+    handleChannelToolCall(toolName: string, input: unknown, origin?: ChannelToolOrigin, 
+    /** Filled with a channel_publish's outcome once its request is
+     *  attempted, so the caller learns where it was delivered. */
+    seen?: {
+        outcome?: PublishOutcome;
+    }): Promise<ToolResult>;
+    /**
+     * The message the agent is replying to, with its channel: the most recent
+     * inbound 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. Left process-global: per-channel inbound tracking
+     * (the right messageId for a fork's own channel) is a separate concern from
+     * the outbound routing fix. An ephemeral run has none (takesGlobalFallback),
+     * so a subagent's refusal marks no one else's channel. Nor has a turn that
+     * deliberately has no channel (activeChannelResolver's null): woken for a
+     * channel id two servers register, it isn't replying to the latest inbound
+     * message, which may be anywhere. A fork's turn always has a channel, its
+     * home, so it's taken to be replying to the latest inbound message as every
+     * fork's turn is, in explicit mode as in locus mode, where its locus is
+     * its home.
+     */
+    incomingFor(agentName?: string): {
+        channel: ChannelRef;
+        messageId: string;
+        threadId?: string;
+    } | undefined;
+    /**
+     * The channel context one server is told for an agent's inference
+     * (context/beforeInference, §14.4). Each server is told only of its own
+     * channels: ids are unique only within one server's connection (§14.2), so
+     * another server's channel named by its id alone could read as this
+     * server's own, and §14.4 leaves the field to the host. So `incoming` and
+     * `defaultOutgoing` appear only where that channel is `serverId`'s, and
+     * `candidates` lists only its open channels. Undefined when none applies.
+     */
+    buildChannelContext(agentName: string | undefined, serverId: string): ChannelContext | undefined;
     /**
      * Remove all channel state belonging to a single server. Called by the
      * framework when an MCPL server is disconnected at runtime, so a dead
@@ -926,8 +1005,16 @@ export declare class ChannelRegistry {
      * 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<{
+     *
+     * The channel is a ref, or a name given as a string, which resolves as
+     * channel_publish's channelId does: one channel the name means, which may
+     * be server-qualified, and a name two servers' channels answer to is
+     * refused with them as candidates (`shared-id`). A host keeps channels by
+     * their ids (connectome-host's notices module). Where several servers
+     * register an id, a ref picks one server's channel, as a qualified name does
+     * where it names one channel alone.
+     */
+    publishForAgent(channel: string | ChannelRef, text: string, agentName: string): Promise<{
         success: boolean;
         data?: unknown;
         error?: string;
@@ -1019,25 +1106,121 @@ export declare class ChannelRegistry {
     private sendTypingNotification;
     /** Descriptors registered by one server — the §14.3 channels/list answer. */
     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.
+     * undefined when it isn't one, or isn't registered. The notices name that
+     * server.
+     */
+    inboundOnlyServer(ref: ChannelRef): string | undefined;
+    /** A channel's entry, by its server and id: the map is keyed by destinationKey. */
+    private entryAt;
+    /**
+     * The registered channels a name given as a string can mean (a tool's
+     * channelId, a `>>` target, a host's call): those whose id is the name and
+     * those whose server-qualified name (qualifiedChannelName) is the name,
+     * taken together. The qualified form is matched against the registered
+     * pairs, never split at a colon, since ids hold colons (discord-mcpl's are
+     * `discord:<guild>:<channel>`). So a name that two entries answer to, in
+     * either form, means both of them, and a caller that has to pick one
+     * refuses it with both as candidates rather than taking the first.
+     */
+    private entriesNamed;
+    /** The channels a name given as a string means (entriesNamed), by ref:
+     *  for a caller that has to settle a host's or a tool's name itself. */
+    channelsNamed(name: string): ChannelRef[];
+    /**
+     * The name to show an agent for a channel: one that picks it alone, which
+     * a channel tool's channelId takes back, and a `>>` target too where the
+     * name is one (isProseTargetToken: a single token other than `skip_reply`,
+     * which a `>>` line reads as private speech); proseTargetFor gives the
+     * target to write. A registered
+     * channel's is nameFor's: its id, or, where another server registers the
+     * same id, its server-qualified name. A channel no string picks alone, as
+     * where qualified names collide too, is shown by its id and its server, as
+     * the refusals show it (channelOnServer), which no input takes for a name.
+     * A channel no longer registered is shown by its id, or by its qualified
+     * name, only where no registered channel takes that name, as a channel
+     * tool reads it or a `>>` target does (by label or raw id too), so the
+     * name can't send anything to another channel; else by its id and server.
+     */
+    nameShown(ref: ChannelRef): string;
+    /**
+     * A tool's refusal of a tuned-out channel, whose decision is the tune-out:
+     * its cancel is what ends it (tuneOutEndText), and a decision recorded over
+     * it would end it without that cancel, so the backlog it diverted would
+     * never reach the agent.
+     */
+    private tunedOutRefusal;
+    /**
+     * How a tuned-out channel's tune-out ends, for the texts that tell an agent
+     * channel_open doesn't change it: a tune_out cancel, by the name that
+     * picks the channel (nameFor), or, where no name picks it alone, its own
+     * end, since tune_out takes a name.
+     * For channel_close, which refuses a tuned-out channel too, it adds that
+     * the close comes after that.
+     */
+    /** How this channel's tune-out ends, as tune_out's own refusals say it
+     *  (tuneOutEndText), or undefined for a channel no longer registered. */
+    tuneOutEnd(ref: ChannelRef): string | undefined;
+    private tuneOutEndText;
+    /**
+     * A channel's name as nameShown gives it, quoted for a sentence: the name
+     * in quotes, or the id-and-server form, whose parts are quoted already.
+     */
+    quotedShown(ref: ChannelRef): string;
+    /**
+     * The string that names exactly this entry by entriesNamed: its id when no
+     * other entry answers to that (the id is unique), else its server-qualified
+     * name when no other entry answers to that, else undefined. The last can
+     * happen only where qualified names collide, as server `a`'s channel
+     * `b:room` and server `a:b`'s channel `room` do; such a channel is named
+     * only by its server and id apart.
+     */
+    private nameFor;
+    /**
+     * The refusal for a name that more than one registered channel answers
+     * to (entriesNamed). Where each one has a name that picks it alone
+     * (nameFor), as two servers' channels with one id do, it lists those.
+     * Where one has none, the name reads two ways, as server `a`'s `b:room`
+     * and server `a:b`'s `room` both answer to `a:b:room`, and the refusal
+     * gives a line per channel, each with its own route, or, where the tool
+     * has none to it, saying that no channelId reaches it alone.
+     * `takesServerId` says whether the tool also takes a serverId to pick
+     * with; `nothing` says what didn't happen, "nothing ran" unless given.
+     */
+    private sharedNameRefusal;
+    /**
+     * The refusal for a name more than one registered channel answers to, for
+     * a tool outside the registry whose schema has no serverId (tune_out, the
+     * subconscious's cancel_tuneout and deliver_summary), or undefined when the
+     * name means one channel or none. `nothing` says what didn't happen,
+     * "nothing ran" unless given.
+     */
+    sharedNameRefusalFor(name: string, nothing?: string): string | undefined;
+    /**
+     * Where a channel id given with a server that doesn't have it is, for that
+     * refusal: the servers that register the id, each a serverId to call again
+     * with, and leaving serverId out only where the id alone then names one
+     * channel (entriesNamed), since another channel's qualified name can be
+     * the same string. For a publish, whose schema has no serverId
+     * (`takesServerId` false: a channel_publish given one the agent added, or
+     * a host's publishForAgent given a ref), where the id is, by the names its
+     * channelId takes (nameFor), and no advice to post there, since each is
+     * another destination, perhaps another community's.
+     */
+    private elsewhereText;
+    /**
+     * The channel a channel tool names: the channel with id `channelId` on
+     * `serverId` when the call gives a serverId, the exact pair, as every
+     * selector that gives a server reads it; otherwise the one channel its
+     * name means (entriesNamed), which may be server-qualified. A name more
+     * than one channel answers to is refused with them as candidates, never
+     * resolved to the first. Its callers are the tools that take a serverId
+     * (channel_open, channel_close, channel_decline), so the refusal offers
+     * one. `own` is the calling turn's own channels, for an agent's call made
+     * inside it (ChannelToolOrigin.own).
      */
-    private findChannelEntry;
     private resolveToolChannelEntry;
-    /**
-     * Find the composite key for a channel by its channelId.
-     */
-    private findChannelKey;
     private handleToolList;
     /**
      * Record durable desired-open intent, then queue the channel's lifecycle
@@ -1097,7 +1280,10 @@ export declare class ChannelRegistry {
      * docs/explicit-prose-routing.md) to a registered channel.
      *
      * Accepted spellings, tried in order:
-     *   1. exact descriptor id (`discord:guild:123`, always unambiguous)
+     *   1. exact descriptor id (`discord:guild:123`), or its server-qualified
+     *      name (`a:discord:guild:123`), as entriesNamed matches them; a name
+     *      two channels answer to, such as an id two servers register, is
+     *      refused with both as candidates
      *   2. exact raw server-internal id (`address.channelId`)
      *   3. `#label` / bare label — case-insensitive match on descriptor label
      *      with any leading '#' stripped from both sides
@@ -1112,17 +1298,68 @@ export declare class ChannelRegistry {
      * 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.
+     *
+     * `own` is the turn's own channels, for a target its speech names: a name
+     * one of them answers to by its id means that channel, on its server,
+     * before any other spelling (ownChannelNamed).
      */
     resolveProseTarget(spec: string, opts?: {
         forSpeech?: boolean;
-    }): {
-        channelId: string;
-        label?: string;
-    } | {
+        own?: readonly ChannelRef[];
+    }): PublishDestination | {
         error: string;
         candidates?: string[];
         refusedChannelId?: string;
     };
+    /**
+     * The turn's own channel a name means: where the name is the id of one of
+     * the turn's own channels, a channel that has been its trigger or its
+     * locus, that channel, on its server, whether or not that server still
+     * registers it. A message's
+     * reply goes where the message came from, so another server that
+     * registers the id, or takes it once the message's server withdrew it,
+     * isn't reached through the name. Where the turn's channels with that id
+     * are on more than one server, the name means neither. Undefined where no
+     * channel of the turn's has that id.
+     */
+    private ownChannelNamed;
+    /** Why a name the turn's own channel answers to (ownChannelNamed) reaches
+     *  nothing once that channel's server no longer registers it. It offers no
+     *  other channel with the id, since that's another server's. */
+    private ownChannelGoneText;
+    /**
+     * A name the calling turn's own channels answer to by their id, for a tool
+     * outside the registry that takes a channel's name (tune_out, and the
+     * subconscious's cancel_tuneout, speak_in_channel and deliver_summary),
+     * read as the registry's channel tools read it: the turn's channel, or a
+     * refusal where its server no longer registers it, or where the name is
+     * the id of the turn's channels on more than one server. Undefined where
+     * none of the turn's channels has that id. `tool` words the refusal for
+     * what the tool would have done: posted (speak_in_channel), delivered
+     * (deliver_summary) or run (the others).
+     */
+    ownChannelFor(name: string, own: readonly ChannelRef[] | undefined, tool?: 'publish' | 'deliver' | 'other'): {
+        channel: ChannelRef;
+    } | {
+        error: string;
+    } | undefined;
+    /** A refusal of a name the turn's own channel answers to, once its server
+     *  no longer registers it: nothing was posted (channel_publish,
+     *  speak_in_channel), delivered (deliver_summary) or ran (the other channel
+     *  tools, tune_out, cancel_tuneout), and nothing can be until it does
+     *  again. */
+    private ownChannelGoneRefusal;
+    /**
+     * The turn's channels a name means neither of (ownChannelNamed), each by a
+     * string that reaches it outside the turn's rule: its server-qualified
+     * name, where that picks it alone, since its id is the name refused. One
+     * no string picks alone, and one its server no longer registers, is named
+     * by its id and server, saying so; `reaches` says which a name reaches.
+     */
+    private ownCandidates;
+    /** A tool's refusal of a name the turn's channels on more than one server
+     *  answer to by their id (ownChannelNamed's neither). */
+    private ownNeitherRefusal;
     private resolveTargetByName;
     /**
      * The `>>` target to show an agent for a channel: one whitespace-free token
@@ -1131,22 +1368,98 @@ export declare class ChannelRegistry {
      * a space can't be quoted verbatim: `>>#DM: alice` parses as target `#DM:`
      * plus body `alice …`, and `>>#fable (antra's server)` delivers
      * `(antra's server)` as text. Tried in order: `@name` for a DM, `#label`,
-     * `#name` (label without its server suffix), the descriptor id.
+     * `#name` (label without its server suffix), the name that picks the
+     * channel alone (nameFor): its id, or, where another server registers the
+     * same id, its server-qualified name; and last its server-qualified name,
+     * for a channel whose id is no target (isProseTargetToken), as
+     * `skip_reply` isn't.
      *
-     * Undefined when there is no safe token: the channel isn't registered (on
-     * `serverId`, when given), no candidate is whitespace-free and resolves back,
-     * or the id is registered by more than one server. A resolved target names a
-     * channel by id alone, and ids are unique only within a connection, so a
-     * shared id could route the reply through the wrong server.
-     */
-    proseTargetFor(channelId: string, serverId?: string): string | undefined;
-    /**
-     * Open a channel because something was DELIVERED into it (explicit send
-     * tool or routed speech). Sending into a closed channel is not a thing:
-     * engaging a channel opens it, so typing indicators, reaction machinery,
-     * and inbound forwarding all come alive with the first outbound message.
-     * Accepts composite MCPL ids or raw server-internal ids (explicit send
-     * tools receive whatever the agent typed). An `open-failed` answer says
+     * Undefined when there is no safe token: the channel isn't registered, or
+     * no candidate is whitespace-free and resolves back to this channel, on
+     * this server.
+     */
+    proseTargetFor(ref: ChannelRef): string | undefined;
+    /** Whether the decision on record is a close the agent or a module made
+     *  (isCloseDecision). */
+    private closeDecided;
+    /**
+     * Whether the agent's words delivered into this channel open it first, by
+     * publish() or after an explicit send (openIfClosedForSend): one that isn't
+     * open, or whose close stands (closeStands: a close that failed may have
+     * left its transport open), unless speech leaves it as it stands
+     * (speechLeavesAsItStands). Where nobody decided (no record, a pure
+     * default) or a machine closed the channel (subscription-gc,
+     * housekeeping), it opens, as it always did, and so does one decided open
+     * whose transport isn't confirmed. A tuned-out channel whose transport
+     * isn't open is opened for its traffic, and its tune-out stays
+     * (openChannelNow). A server that isn't up isn't one this host can't
+     * direct, though a drop empties its grant until its next exchange, so
+     * speech there is refused as it always was: by the open's failure, which
+     * says the server is connecting or reconnecting, or, where its grant is
+     * empty, by publish()'s grant check before any open.
+     */
+    speechOpens(ref: ChannelRef): boolean;
+    /** Whether speech leaves this registration as it stands, never opening
+     *  it, and words go into it as it is: the decision on record is a close
+     *  the agent made itself (channel_close, channel_decline) or a module made
+     *  (MODULE_CLOSE_SOURCE), which stands against the agent's own speech
+     *  whatever the channel's transport is; or its server is up and this host
+     *  doesn't direct its lifecycle (lifecycleWithheld), so nothing opens
+     *  there. A wait or an open that failed gives way to such a registration,
+     *  as when the agent closed the channel while the words waited, since
+     *  there's nothing for the words to wait for (refusalGivesWay). */
+    private speechLeavesAsItStands;
+    /** Whether words a wait or an open refused go into the channel after all:
+     *  its registration `now` is one speech leaves as it stands
+     *  (speechLeavesAsItStands), such as one the agent closed or declined
+     *  while the words waited, and the failure isn't convergence that never
+     *  established its target (convergeFailure). A registration that went
+     *  still fails them, and publish() refuses one the server last answered
+     *  for another channel (answeredElsewhere), whenever that happened. */
+    private refusalGivesWay;
+    /** Whether this host doesn't direct the server's channel lifecycle: the
+     *  server is up, and its grant lacks channels.lifecycle, so nothing opens
+     *  or closes its channels. A server that isn't up has an empty grant from
+     *  a drop until its next exchange, which says nothing yet of what it
+     *  grants, so it isn't counted. */
+    lifecycleWithheld(serverId: string): boolean;
+    /** Whether the agent's words go into this channel and leave it closed: it
+     *  isn't open at the transport, and speech leaves it as it stands
+     *  (speechLeavesAsItStands: the agent's or a module's close, or a server
+     *  that's up without channels.lifecycle). False for a channel open at the
+     *  transport, whose traffic still flows, and for one speech opens. */
+    speechLeavesClosed(ref: ChannelRef): boolean;
+    /**
+     * How the agent kept this registered channel closed itself, if it did:
+     * 'closed' for its channel_close, 'declined' for its channel_decline. Its
+     * speech there leaves such a channel as it stands (speechOpens). A
+     * channel no longer registered has nothing to keep closed, whatever its
+     * record says, so it answers undefined.
+     */
+    closedByAgent(ref: ChannelRef): 'closed' | 'declined' | undefined;
+    /** The registered channels an explicit send tool may have delivered into,
+     *  from the id the tool reported or was given: a composite MCPL id, or the
+     *  raw server-internal id (`address.channelId`), since send tools receive
+     *  whatever the agent typed. Matches on `serverId` when it is given,
+     *  across every server otherwise. */
+    private sendTargets;
+    /** The one registered channel an explicit send tool delivered into
+     *  (sendTargets), or undefined when none or more than one matches. A
+     *  lookup only, for what's said beside the send's answer before it's
+     *  queued; openIfClosedForSend decides whether the send opens it. */
+    resolveSendTarget(rawChannelId: string, serverId?: string): ChannelRef | undefined;
+    /**
+     * Open a channel because something was DELIVERED into it by an explicit
+     * send tool, so typing indicators, reaction machinery and inbound
+     * forwarding all come alive with the first outbound message, unless
+     * speech leaves it as it stands (speechLeavesAsItStands: the agent closed
+     * or declined it itself, a module closed it, or its server is up and this
+     * host doesn't direct its lifecycle). Such a channel opens nothing, and
+     * answers `stays-closed`, or `already-open` where its transport is open
+     * with no close standing, whether the send found it so or it became so
+     * while the send's wait or open was out.
+     * Accepts composite MCPL ids or raw server-internal ids (sendTargets). 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
@@ -1159,12 +1472,19 @@ export declare class ChannelRegistry {
      * (`selected-again`).
      */
     openIfClosedForSend(rawChannelId: string, serverId?: string): Promise<{
-        status: 'opened' | 'already-open' | 'unknown-channel' | 'ambiguous' | 'open-failed';
+        status: 'opened' | 'already-open' | 'stays-closed' | 'unknown-channel' | 'ambiguous' | 'open-failed';
         channelId?: string;
+        /** The channel's server, beside `channelId` whenever it names one. */
+        serverId?: string;
         label?: string;
         opening?: boolean;
         selectedForOpening?: SelectedForOpening;
     }>;
+    /** What a send answers for a channel it leaves as it is
+     *  (speechLeavesAsItStands):
+     *  `already-open` where its transport is open with no close standing,
+     *  `stays-closed` otherwise. */
+    private sendLeavesChannel;
     private handleToolOpen;
     private handleToolClose;
     private handleToolDecline;
@@ -1215,40 +1535,37 @@ export declare class ChannelRegistry {
      * 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.
+     * publish delivered before it.
      */
-    sendOutgoingChunk(to: string | PublishDestination, conversationId: string, inferenceId: string, index: number, delta: string): void;
+    sendOutgoingChunk(to: PublishDestination, conversationId: string, inferenceId: string, index: number, delta: string): void;
     /**
      * 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).
+     * 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.
      */
-    sendOutgoingComplete(to: string | PublishDestination, conversationId: string, inferenceId: string, text: string): void;
-    private streamingServerFor;
+    sendOutgoingComplete(to: PublishDestination, conversationId: string, inferenceId: string, text: string): void;
     /**
      * 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.
+     * registers that channel, and its grant has `channels.streaming` (§5.4:
+     * the grant gates streaming, not the raw advertisement). 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;
+     *  process-global default), with its server. Public so a multi-segment
+     *  caller can snapshot it ONCE and pin every segment to it via
+     *  routeSpeech's locus. */
+    resolveLocus(conversationId: string): ChannelRef | null;
     /** The process-global fallback channel for this conversation, or null when it takes none (takesGlobalFallback). */
     private globalFallbackFor;
     /**
      * 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.
+     * plus `channelId` when the caller has the server, otherwise the one
+     * channel the id, or its server-qualified name, means (entriesNamed). A
+     * shared id is refused, never resolved to whichever server registered it
+     * first.
      */
     resolveDestination(target: {
         serverId?: string;
@@ -1268,16 +1585,19 @@ export declare class ChannelRegistry {
      * 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
+     * when the caller has the server, otherwise the channel id, or its
+     * server-qualified name, must mean exactly one channel (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 send refused before the open opens nothing; and a failed open sends
-     * nothing.
+     * possible to send into a closed channel that speech opens (speechOpens):
+     * it's opened first (`openSource` names why), once its server and that
+     * server's channels.publish grant are known to take the send, so a send
+     * refused before the open opens nothing; and a failed open sends nothing.
+     * A channel speech leaves as it stands (speechLeavesAsItStands), one the
+     * agent closed or declined itself or a module closed, or a closed one on
+     * a server that's up but whose lifecycle this host doesn't direct, takes
+     * the words as it is, once its queued lifecycle work has settled.
      *
      * A channel its server declared inbound-only (isInboundOnly) takes nothing
      * the host would post, whichever path the words took, a drafts resend
@@ -1335,7 +1655,7 @@ export declare class ChannelRegistry {
      * that used to live in discord-mcpl.
      */
     deliverSpeech(conversationId: string, text: string, 
-    /** The turn's FROZEN locus, snapshotted once by the caller (resolveLocus
+    /** The turn's FROZEN locus, with its server, snapshotted once by the caller (resolveLocus
      *  at turn start) and passed to every segment of the turn. Mandatory:
      *  there is deliberately no live-resolution fallback here — a late
      *  dispatch resolving live can read the NEXT turn's trigger state or a
@@ -1344,7 +1664,7 @@ export declare class ChannelRegistry {
      *  "this turn is pinned to no locus": fail loudly rather than guess,
      *  except for an ephemeral run, whose speech is then its caller's
      *  result. */
-    locusChannelId: string | null, 
+    locus: ChannelRef | null, 
     /** `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. */
@@ -1352,7 +1672,7 @@ export declare class ChannelRegistry {
         heldOnFailure?: boolean;
     }): Promise<PublishOutcome>;
     /** deliverSpeech, reduced to the confirmed delivery (null when there was none). */
-    routeSpeech(conversationId: string, text: string, locusChannelId: string | null): Promise<{
+    routeSpeech(conversationId: string, text: string, locus: ChannelRef | null): Promise<{
         delivered: boolean;
         serverId: string;
         channelId: string;