@animalabs/agent-framework 0.5.7 → 0.6.2

package/src/index.ts

@@ -63,6 +63,16 @@ export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
 
+// MCPL server config (exposed for hosts that manage servers at runtime via
+// connectMcplServer / disconnectMcplServer / restartMcplServer)
+export type { McplServerConfig } from './mcpl/index.js';
+
+// MCPL client connection (exposed so external tooling — server playtests,
+// health probes, protocol harnesses — can dial an MCPL server exactly the
+// way the framework host does, over stdio or WebSocket)
+export { McplServerConnection } from './mcpl/index.js';
+export type { McplHostCapabilities } from './mcpl/index.js';
+
 // Per-channel conversation routing
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './mcpl/index.js';
 export type {

package/src/mcpl/channel-registry.ts

@@ -234,6 +234,31 @@ interface ChannelRegistryOptions {
     reason: string;
     textLen: number;
   }) => void;
+  /**
+   * Resolve a conversation fork's HOME channel from its agent name. Conversation
+   * 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
+   * no home and correctly falls back to the global locus (heartbeats, etc.).
+   */
+  homeChannelResolver?: (agentName: string) => string | undefined;
+  /**
+   * Resolve the channel that triggered an agent's CURRENT inference turn, by
+   * agent name. 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 tracks the triggering
+   * channel of the live turn per-agent and exposes it here; resolves to
+   * undefined for a heartbeat / no-trigger turn, which correctly keeps the
+   * global fallback. Consulted AFTER `homeChannelResolver` (a fork's home always
+   * wins), BEFORE `defaultPublishChannel`.
+   */
+  activeChannelResolver?: (agentName: string) => string | undefined;
 }
 
 // ============================================================================
@@ -258,6 +283,8 @@ export class ChannelRegistry {
     reason: string;
     textLen: number;
   }) => void;
+  private homeChannelResolver?: (agentName: string) => string | undefined;
+  private activeChannelResolver?: (agentName: string) => string | undefined;
 
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
   private channels = new Map<string, ChannelEntry>();
@@ -304,6 +331,8 @@ export class ChannelRegistry {
     this.sendTypingFn = options?.sendTypingFn;
     this.shouldTriggerInference = options?.shouldTriggerInference;
     this.onRouteFailure = options?.onRouteFailure;
+    this.homeChannelResolver = options?.homeChannelResolver;
+    this.activeChannelResolver = options?.activeChannelResolver;
   }
 
   /**
@@ -484,6 +513,7 @@ export class ChannelRegistry {
             messageId: message.messageId,
             threadId: message.threadId,
             author: message.author,
+            ...(message.tags ? { tags: message.tags } : {}),
           },
         );
       }
@@ -525,6 +555,50 @@ export class ChannelRegistry {
     });
   }
 
+  /**
+   * Ensure a channel is registered AND open so it can serve as an outbound
+   * routing locus, lazy-registering it if unseen and opening it if closed.
+   *
+   * 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; re-opening an already-open channel is a no-op.
+   */
+  ensureChannelRegistered(serverId: string, channelId: string, label?: string): void {
+    const existing = this.findChannelEntry(channelId);
+    if (existing) {
+      if (!existing.open) {
+        existing.open = true;
+        this.emitTraceFn({ type: 'mcpl:channel-opened', serverId: existing.serverId, channelId });
+      }
+      return;
+    }
+
+    const key = `${serverId}:${channelId}`;
+    this.channels.set(key, {
+      serverId,
+      descriptor: {
+        id: channelId,
+        type: serverId,
+        label: label ?? channelId,
+        direction: 'bidirectional',
+        metadata: { lazyRegistered: true },
+      },
+      open: true,
+    });
+    this.emitTraceFn({
+      type: 'mcpl:channel-lazy-registered',
+      serverId,
+      channelId,
+      label: label ?? channelId,
+    });
+  }
+
   // ==========================================================================
   // Typing Indicator Management
   // ==========================================================================
@@ -700,15 +774,28 @@ export class ChannelRegistry {
    *
    * Returns undefined if no channels are active.
    */
-  buildChannelContext(): ChannelContext | undefined {
+  buildChannelContext(agentName?: string): ChannelContext | undefined {
     const openChannels = this.getOpenChannels();
-    if (openChannels.length === 0 && !this.defaultPublishChannel) {
+
+    // Resolve the outbound locus the SAME way routeSpeech does, so the agent is
+    // told the channel its speech will actually land in: a conversation fork's
+    // home channel, else this turn's triggering channel (single trunk agent —
+    // item-3 redux), else the global default (heartbeats). Without this, a fork
+    // was advertised the global locus but published somewhere else; and a trunk
+    // agent was told the wrong channel under concurrency.
+    const home = agentName ? this.homeChannelResolver?.(agentName) : undefined;
+    const active = agentName ? this.activeChannelResolver?.(agentName) : undefined;
+    const outgoing = home ?? active ?? this.defaultPublishChannel;
+
+    if (openChannels.length === 0 && !outgoing) {
       return undefined;
     }
 
     const context: ChannelContext = {};
 
-    // Incoming: from defaultPublishChannel if set
+    // Incoming: the most-recent inbound message (what the agent is replying to).
+    // 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.
     if (this.defaultPublishChannel && this.defaultPublishMessageId) {
       context.incoming = {
         channelId: this.defaultPublishChannel,
@@ -717,10 +804,10 @@ export class ChannelRegistry {
       };
     }
 
-    // Default outgoing: same as incoming (reply to last channel)
-    if (this.defaultPublishChannel) {
+    // Default outgoing: the resolved outbound locus (home channel for forks).
+    if (outgoing) {
       context.defaultOutgoing = {
-        channelId: this.defaultPublishChannel,
+        channelId: outgoing,
       };
     }
 
@@ -736,6 +823,25 @@ export class ChannelRegistry {
   // Lifecycle
   // ==========================================================================
 
+  /**
+   * Remove all channel state belonging to a single server. Called by the
+   * framework when an MCPL server is disconnected at runtime, so a dead
+   * server's channels don't linger and route speech into the void.
+   */
+  removeServer(serverId: string): void {
+    for (const [key, entry] of this.channels) {
+      if (entry.serverId !== serverId) continue;
+      this.channels.delete(key);
+      this.stopTyping(entry.descriptor.id);
+      if (this.defaultPublishChannel === entry.descriptor.id) {
+        this.defaultPublishChannel = null;
+        this.defaultPublishMessageId = null;
+        this.defaultPublishThreadId = undefined;
+      }
+    }
+    this.subscriptionPolicies.delete(serverId);
+  }
+
   /**
    * Stop all typing intervals and clear all channel registrations.
    */
@@ -1034,9 +1140,23 @@ export class ChannelRegistry {
    * is no locus / the channel or its server can't be resolved (in which case
    * the speech simply stays in chronicle + module surfaces).
    */
+  /** 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 {
+    const home = this.homeChannelResolver?.(conversationId);
+    return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;
+  }
+
   async routeSpeech(
     conversationId: string,
     text: string,
+    /** Pin the outbound locus, skipping resolution. Callers delivering MULTIPLE
+     *  segments of ONE turn snapshot resolveLocus() once and pass it here, so a
+     *  new turn starting mid-dispatch (segments run after the agent is idle,
+     *  PR #32) can't overwrite the per-agent triggering channel between segments
+     *  and split one reply across channels. */
+    overrideChannelId?: string | null,
   ): Promise<{ delivered: boolean; channelId: string } | null> {
     // Surface a routing failure: emit a trace AND notify the host (which drops
     // a `[discord-send-failed]` marker into chronicle) so the agent learns her
@@ -1053,9 +1173,24 @@ export class ChannelRegistry {
       return null;
     };
 
-    const channelId = this.defaultPublishChannel;
+    // Resolve the outbound locus, in precedence order:
+    //   1. fork HOME channel — a conversation fork always replies in the channel
+    //      it was spawned to serve (item 3, forks).
+    //   2. this turn's TRIGGERING channel — a single trunk agent (connectome-
+    //      host's only mode) replies in the channel whose message woke THIS
+    //      inference, so a concurrent inbound elsewhere can't hijack the reply
+    //      (item-3 redux, trunk agents). Also carries DM channels, which arrive
+    //      as push/events and never touch `defaultPublishChannel`.
+    //   3. the process-global `defaultPublishChannel` — last resort for turns
+    //      with no triggering channel (heartbeats, timers).
+    // Using the global for a fork or a concurrent trunk turn is the item-3 bug:
+    // it tracks the most-recent inbound across ALL channels, so a reply lands
+    // wherever a message last happened to arrive rather than where it belongs.
+    const channelId = overrideChannelId ?? this.resolveLocus(conversationId);
     if (!channelId) {
-      return fail(null, 'no locus (defaultPublishChannel null)');
+      // Reached only when the agent has no home, no active triggering channel,
+      // AND no global inbound was ever seen.
+      return fail(null, 'no locus (no home/active channel, defaultPublishChannel null)');
     }
 
     const entry = this.findChannelEntry(channelId);

package/src/mcpl/checkpoint-manager.ts

@@ -368,6 +368,22 @@ export class CheckpointManager {
     return null;
   }
 
+  /**
+   * Get the server's host-managed (hostState) feature set. Host-managed state is
+   * single-valued by protocol (one unkeyed `state` per tool call), so there is at
+   * most one such set — return it so its state is threaded correctly even when the
+   * server also declares server-managed (rollback) sets. Returns null if none.
+   */
+  getHostManagedFeatureSet(serverId: string): string | null {
+    const prefix = `${serverId}:`;
+    for (const [key, tree] of this.trees) {
+      if (key.startsWith(prefix) && tree.hostState) {
+        return key.slice(prefix.length);
+      }
+    }
+    return null;
+  }
+
   // ==========================================================================
   // Rollback
   // ==========================================================================

package/src/mcpl/push-handler.ts

@@ -171,12 +171,16 @@ export class PushHandler {
       const reason = err instanceof McplFeatureSetError
         ? err.message
         : 'Feature set validation failed';
+      // Loud rejection — a rejected push event is an agent that silently
+      // never hears the message. (2026-07-09 diagnosability pass.)
+      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${reason}`);
       responder?.respond({ accepted: false, reason });
       return;
     }
 
     // 2. Deduplicate by eventId
     if (this.dedup.checkAndAdd(params.eventId)) {
+      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=duplicate`);
       responder?.respond({ accepted: false, reason: 'duplicate' });
       return;
     }
@@ -197,6 +201,7 @@ export class PushHandler {
         eventId: params.eventId,
         eventType: 'mcpl:push-event',
         ...(params.origin ?? {}),
+        ...(params.tags ? { tags: params.tags } : {}),
       };
       triggerInference = this.shouldTriggerInference(textContent, metadata);
     }