@animalabs/agent-framework 0.5.6 → 0.6.0

package/src/mcpl/channel-registry.ts

@@ -174,6 +174,43 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
       required: [],
     },
   },
+  {
+    name: 'think',
+    description:
+      'Reason privately. The content stays in your own context and is NOT sent to any ' +
+      'channel or surface. This does NOT end or silence your turn: if you also write ' +
+      'plain text this turn, that text is still posted as your reply. Use think() purely ' +
+      'to work things out before (or instead of) speaking. To deliberately NOT reply this ' +
+      'turn, call skip_reply instead.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        content: {
+          type: 'string',
+          description: 'Your private thought / reasoning (optional; not sent anywhere).',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'skip_reply',
+    description:
+      'End your turn WITHOUT sending anything to any channel or surface. Use when you have ' +
+      'read the messages but deliberately choose not to reply right now — ambient chatter, ' +
+      'nothing to add, or you are waiting. Any plain text you wrote this turn stays private ' +
+      'and is NOT posted. To reply instead, just write plain text (no tool call).',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        reason: {
+          type: 'string',
+          description: 'Optional private note on why you are not replying (not sent anywhere).',
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
 // ============================================================================
@@ -183,6 +220,45 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
 interface ChannelRegistryOptions {
   /** 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`. 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;
+    channelId: string | null;
+    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;
 }
 
 // ============================================================================
@@ -201,6 +277,14 @@ export class ChannelRegistry {
     op?: 'start' | 'stop',
   ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
+  private onRouteFailure?: (info: {
+    conversationId: string;
+    channelId: string | null;
+    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>();
@@ -246,6 +330,9 @@ export class ChannelRegistry {
     this.emitTraceFn = emitTraceFn;
     this.sendTypingFn = options?.sendTypingFn;
     this.shouldTriggerInference = options?.shouldTriggerInference;
+    this.onRouteFailure = options?.onRouteFailure;
+    this.homeChannelResolver = options?.homeChannelResolver;
+    this.activeChannelResolver = options?.activeChannelResolver;
   }
 
   /**
@@ -372,6 +459,43 @@ export class ChannelRegistry {
       this.defaultPublishMessageId = message.messageId;
       this.defaultPublishThreadId = message.threadId;
 
+      // Lazy-register the channel if we've never seen it. A channel can deliver
+      // an incoming message before its channels/register (boot enumeration) or
+      // channels/changed (post-boot create / View-permission grant) round-trip
+      // lands — or the registration event can be missed entirely (e.g. the bot
+      // gains visibility in a way that fires neither `channelCreate` nor a
+      // View-permission transition). Without a registry entry, routeSpeech()
+      // can't resolve this channel as an outbound locus and the agent's reply
+      // is silently dropped, even though this very message proves the channel
+      // is reachable. The inbound message carries enough to make it publishable,
+      // so register it here; a later authoritative channels/register or
+      // channels/changed will overwrite this descriptor with the richer one.
+      const incomingKey = `${serverId}:${message.channelId}`;
+      if (!this.channels.has(incomingKey)) {
+        const channelLabel =
+          typeof message.metadata?.channelName === 'string' && message.metadata.channelName
+            ? (message.metadata.channelName as string)
+            : message.channelId;
+        this.channels.set(incomingKey, {
+          serverId,
+          descriptor: {
+            id: message.channelId,
+            type: serverId,
+            label: channelLabel,
+            direction: 'bidirectional',
+            address: message.threadId ? { threadId: message.threadId } : undefined,
+            metadata: { lazyRegistered: true },
+          },
+          open: true,
+        });
+        this.emitTraceFn({
+          type: 'mcpl:channel-lazy-registered',
+          serverId,
+          channelId: message.channelId,
+          label: channelLabel,
+        });
+      }
+
       // Determine whether to trigger inference
       let triggerInference = true;
       if (this.shouldTriggerInference) {
@@ -389,6 +513,7 @@ export class ChannelRegistry {
             messageId: message.messageId,
             threadId: message.threadId,
             author: message.author,
+            ...(message.tags ? { tags: message.tags } : {}),
           },
         );
       }
@@ -430,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
   // ==========================================================================
@@ -536,6 +705,14 @@ export class ChannelRegistry {
     return this.defaultPublishChannel;
   }
 
+  /**
+   * Get the descriptor for a channel by its channelId (first match across
+   * servers). Used by the conversation router for DM classification.
+   */
+  getDescriptor(channelId: string): ChannelDescriptor | undefined {
+    return this.findChannelEntry(channelId)?.descriptor;
+  }
+
   /**
    * Get all open channels.
    */
@@ -577,6 +754,12 @@ export class ChannelRegistry {
       case 'channel_publish':
         return this.handleToolPublish(input as { channelId: string; content: string });
 
+      case 'think':
+        return this.handleToolThink(input as { content?: string });
+
+      case 'skip_reply':
+        return this.handleToolSkipReply(input as { reason?: string });
+
       default:
         return { success: false, error: `Unknown channel tool: ${toolName}`, isError: true };
     }
@@ -591,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,
@@ -608,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,
       };
     }
 
@@ -730,6 +926,11 @@ export class ChannelRegistry {
   // Private: Channel Lookup
   // ==========================================================================
 
+  /** Server id owning a registered channel (by descriptor id), or null. */
+  getChannelServerId(channelId: string): string | null {
+    return this.findChannelEntry(channelId)?.serverId ?? null;
+  }
+
   /**
    * Find a channel entry by channelId (searches across all servers).
    * Returns the first match.
@@ -874,6 +1075,130 @@ export class ChannelRegistry {
     }
   }
 
+  /**
+   * Handle the synthesized `think` tool — a private reasoning scratchpad. It
+   * sends nothing, and (unlike before) does NOT silence the turn: trailing
+   * plain text is still routed as the reply. The thought stays in the agent's
+   * own context/chronicle. To deliberately not reply, the agent uses skip_reply.
+   */
+  private handleToolThink(input: { content?: string }): ToolResult {
+    return {
+      success: true,
+      data: {
+        noted: true,
+        note:
+          'Thought recorded (private — not sent anywhere). This did NOT silence your turn: ' +
+          'write plain text to reply, or call skip_reply to end the turn without replying.',
+        content: typeof input?.content === 'string' ? input.content : undefined,
+      },
+    };
+  }
+
+  /**
+   * Handle the synthesized `skip_reply` tool — the deliberate "stay silent"
+   * signal. A no-op as far as any surface is concerned (sends nothing); its
+   * effect is that the framework's output routing treats this as a silencing
+   * tool, so any trailing prose this turn is NOT posted. Replaces the old
+   * overloaded use of `think` for staying silent.
+   */
+  private handleToolSkipReply(input: { reason?: string }): ToolResult {
+    return {
+      success: true,
+      data: {
+        skipped: true,
+        note: 'Ended the turn without replying — nothing was sent to any channel.',
+        reason: typeof input?.reason === 'string' ? input.reason : undefined,
+      },
+    };
+  }
+
+  /**
+   * 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).
+   */
+  async routeSpeech(
+    conversationId: string,
+    text: string,
+  ): 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
+    // reply never reached the human, instead of it vanishing silently.
+    const fail = (channelId: string | null, reason: string): null => {
+      console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
+      this.emitTraceFn({
+        type: 'mcpl:speech-route-failed',
+        channelId: channelId ?? '',
+        reason,
+        textLen: text.length,
+      });
+      this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length });
+      return null;
+    };
+
+    // Resolve the outbound locus, in precedence order:
+    //   1. fork HOME channel — a conversation fork always replies in the channel
+    //      it was spawned to serve (item 3, forks).
+    //   2. this turn's TRIGGERING channel — a single trunk agent (connectome-
+    //      host's only mode) replies in the channel whose message woke THIS
+    //      inference, so a concurrent inbound elsewhere can't hijack the reply
+    //      (item-3 redux, trunk agents). Also carries DM channels, which arrive
+    //      as push/events and never touch `defaultPublishChannel`.
+    //   3. the process-global `defaultPublishChannel` — last resort for turns
+    //      with no triggering channel (heartbeats, timers).
+    // Using the global for a fork or a concurrent trunk turn is the item-3 bug:
+    // it tracks the most-recent inbound across ALL channels, so a reply lands
+    // wherever a message last happened to arrive rather than where it belongs.
+    const home = this.homeChannelResolver?.(conversationId);
+    const channelId =
+      home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel;
+    if (!channelId) {
+      // Reached only when the agent has no home, no active triggering channel,
+      // AND no global inbound was ever seen.
+      return fail(null, 'no locus (no home/active channel, defaultPublishChannel null)');
+    }
+
+    const entry = this.findChannelEntry(channelId);
+    if (!entry) {
+      return fail(channelId, `no registered channel for locus "${channelId}"`);
+    }
+
+    const server = this.serverRegistry.getServer(entry.serverId);
+    if (!server) {
+      return fail(channelId, `server "${entry.serverId}" not found`);
+    }
+
+    const publishParams: ChannelsPublishParams = {
+      conversationId,
+      channelId,
+      content: [{ type: 'text', text }],
+    };
+    const result = await server.sendChannelsPublish(publishParams);
+    const delivered = (result as { delivered?: boolean } | undefined)?.delivered ?? true;
+
+    // The server accepted the publish RPC but reported the message was not
+    // actually delivered (e.g. missing Send Messages permission). Previously
+    // this returned `{ delivered: true }`, masking the failure. Surface it.
+    if (delivered === false) {
+      return fail(channelId, `server "${entry.serverId}" reported delivered:false for "${channelId}"`);
+    }
+
+    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
+    this.emitTraceFn({
+      type: 'mcpl:speech-routed',
+      serverId: entry.serverId,
+      channelId,
+      delivered,
+      textLen: text.length,
+    });
+
+    return { delivered, channelId };
+  }
+
   private async handleToolPublish(input: { channelId?: string; content?: string; text?: string }): Promise<ToolResult> {
     // Resolve content: accept both `content` and `text` (backward compat)
     const messageText = input.content ?? input.text;

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
   // ==========================================================================