@animalabs/agent-framework 0.1.0 → 0.3.0

package/src/mcpl/channel-registry.ts

@@ -38,6 +38,21 @@ import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js
 
 const TYPING_INTERVAL_MS = 7_000;
 
+function shallowEqualRecord(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const k of keysA) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
+
 // ============================================================================
 // Internal Types
 // ============================================================================
@@ -179,7 +194,12 @@ export class ChannelRegistry {
   private featureSetManager: FeatureSetManager;
   private pushEventFn: (event: ProcessEvent) => void;
   private emitTraceFn: (event: { type: string; [key: string]: unknown }) => void;
-  private sendTypingFn?: (serverId: string, channelId: string) => void;
+  private sendTypingFn?: (
+    serverId: string,
+    channelId: string,
+    metadata?: Record<string, unknown>,
+    op?: 'start' | 'stop',
+  ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
 
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
@@ -195,13 +215,29 @@ export class ChannelRegistry {
   /** Per-channel typing indicator timers. */
   private typingIntervals = new Map<string, ReturnType<typeof setInterval>>();
 
+  /** Per-channel typing metadata — carried on the 7s refresh so the target
+   *  server keeps getting the same routing hints (e.g. Zulip topic). */
+  private typingMetadata = new Map<string, Record<string, unknown>>();
+
+  /**
+   * Per-server channel auto-open policy. Populated by the framework from
+   * each McplServerConfig at connect time; default ('auto') applies when
+   * unset.
+   */
+  private subscriptionPolicies = new Map<string, 'auto' | 'manual' | string[]>();
+
   constructor(
     serverRegistry: McplServerRegistry,
     featureSetManager: FeatureSetManager,
     pushEventFn: (event: ProcessEvent) => void,
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
     options?: ChannelRegistryOptions & {
-      sendTypingFn?: (serverId: string, channelId: string) => void;
+      sendTypingFn?: (
+        serverId: string,
+        channelId: string,
+        metadata?: Record<string, unknown>,
+        op?: 'start' | 'stop',
+      ) => void;
     },
   ) {
     this.serverRegistry = serverRegistry;
@@ -212,6 +248,14 @@ export class ChannelRegistry {
     this.shouldTriggerInference = options?.shouldTriggerInference;
   }
 
+  /**
+   * Set the channel auto-open policy for a server. Called by the framework
+   * when each MCPL server is registered.
+   */
+  setSubscriptionPolicy(serverId: string, policy: 'auto' | 'manual' | string[]): void {
+    this.subscriptionPolicies.set(serverId, policy);
+  }
+
   // ==========================================================================
   // Handler Methods (called from framework.ts wireMcplEvents)
   // ==========================================================================
@@ -339,7 +383,7 @@ export class ChannelRegistry {
           textContent,
           {
             ...message.metadata,
-            eventType: 'channel:incoming',
+            eventType: 'mcpl:channel-incoming',
             serverId,
             channelId: message.channelId,
             messageId: message.messageId,
@@ -398,9 +442,27 @@ export class ChannelRegistry {
    *
    * No-op if already typing on this channel.
    */
-  startTyping(channelId: string): void {
+  startTyping(channelId: string, metadata?: Record<string, unknown>): void {
+    const metadataChanged =
+      metadata !== undefined &&
+      !shallowEqualRecord(this.typingMetadata.get(channelId), metadata);
+    if (metadata) {
+      this.typingMetadata.set(channelId, metadata);
+    }
+
     if (this.typingIntervals.has(channelId)) {
-      return; // Already typing
+      // Already typing. If the caller supplied new routing metadata (e.g. the
+      // relevant Zulip topic just moved because a newer message arrived),
+      // dispatch an immediate refresh so the server sees the new routing
+      // within this request instead of waiting up to TYPING_INTERVAL_MS for
+      // the next tick.
+      if (metadataChanged) {
+        const entry = this.findChannelEntry(channelId);
+        if (entry) {
+          this.sendTypingNotification(entry.serverId, channelId);
+        }
+      }
+      return;
     }
 
     // Find the channel entry and its server
@@ -412,7 +474,9 @@ export class ChannelRegistry {
     // Send typing immediately
     this.sendTypingNotification(entry.serverId, channelId);
 
-    // Set up interval
+    // Set up interval — pulls the latest metadata on each tick so mid-stream
+    // updates (e.g. a newer incoming message switching the relevant topic)
+    // take effect on the next refresh.
     const interval = setInterval(() => {
       this.sendTypingNotification(entry.serverId, channelId);
     }, TYPING_INTERVAL_MS);
@@ -432,13 +496,32 @@ export class ChannelRegistry {
       if (interval) {
         clearInterval(interval);
         this.typingIntervals.delete(channelId);
+        // Dispatch an explicit 'stop' so servers that support it (e.g. Zulip)
+        // clear the indicator immediately rather than waiting for auto-expire.
+        // Metadata still carries the routing hint so the stop hits the same
+        // topic/thread as the start. Guarded by `interval`: matches the
+        // global-clear branch's semantics, and keeps defensive stopTyping(ch)
+        // calls from spamming stops at a server that never saw a start.
+        const entry = this.findChannelEntry(channelId);
+        if (entry && this.sendTypingFn) {
+          this.sendTypingFn(entry.serverId, channelId, this.typingMetadata.get(channelId), 'stop');
+        }
       }
+      this.typingMetadata.delete(channelId);
     } else {
-      // Clear all typing intervals
+      // Clear all typing intervals and dispatch stop for each known channel
+      const channels = Array.from(this.typingIntervals.keys());
       for (const interval of this.typingIntervals.values()) {
         clearInterval(interval);
       }
       this.typingIntervals.clear();
+      if (this.sendTypingFn) {
+        for (const id of channels) {
+          const entry = this.findChannelEntry(id);
+          if (entry) this.sendTypingFn(entry.serverId, id, this.typingMetadata.get(id), 'stop');
+        }
+      }
+      this.typingMetadata.clear();
     }
   }
 
@@ -574,7 +657,23 @@ export class ChannelRegistry {
     const server = this.serverRegistry.getServer(serverId);
     if (!server) return;
 
+    const policy = this.subscriptionPolicies.get(serverId) ?? 'auto';
+    if (policy === 'manual') {
+      this.emitTraceFn({
+        type: 'mcpl:channels-auto-open-skipped',
+        serverId,
+        reason: 'manual',
+        count: channels.length,
+      });
+      return;
+    }
+
+    const allowList = Array.isArray(policy) ? new Set(policy) : null;
+    let opened = 0;
+
     for (const channel of channels) {
+      if (allowList && !allowList.has(channel.id)) continue;
+
       const key = `${serverId}:${channel.id}`;
       try {
         await server.sendChannelsOpen({
@@ -585,6 +684,7 @@ export class ChannelRegistry {
         if (entry) {
           entry.open = true;
         }
+        opened++;
       } catch (err) {
         this.emitTraceFn({
           type: 'mcpl:channel-open-failed',
@@ -594,6 +694,18 @@ export class ChannelRegistry {
         });
       }
     }
+
+    // Surface the common typo failure mode: allow-list set but nothing
+    // matched. Without this trace a one-char typo in a channel id looks
+    // identical to "MCPL didn't register the channel".
+    if (allowList && opened === 0 && channels.length > 0) {
+      this.emitTraceFn({
+        type: 'mcpl:channels-allow-list-empty',
+        serverId,
+        allowList: [...allowList],
+        registered: channels.map(c => c.id),
+      });
+    }
   }
 
   // ==========================================================================
@@ -608,7 +720,7 @@ export class ChannelRegistry {
    */
   private sendTypingNotification(serverId: string, channelId: string): void {
     if (this.sendTypingFn) {
-      this.sendTypingFn(serverId, channelId);
+      this.sendTypingFn(serverId, channelId, this.typingMetadata.get(channelId));
     }
     // TODO: When server-connection exposes a public sendNotification or
     // sendTyping method, wire it here directly instead of using a callback.

package/src/mcpl/push-handler.ts

@@ -195,7 +195,7 @@ export class PushHandler {
         serverId,
         featureSet: params.featureSet,
         eventId: params.eventId,
-        eventType: 'push:event',
+        eventType: 'mcpl:push-event',
         ...(params.origin ?? {}),
       };
       triggerInference = this.shouldTriggerInference(textContent, metadata);

package/src/mcpl/server-connection.ts

@@ -95,6 +95,9 @@ export class McplServerConnection extends EventEmitter {
   private reconnectIntervalMs = 5000;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Swaps the line handler on the current child's stderr pipe. Re-bound on reconnect. */
+  private rebindStderr: ((next: (line: string) => void) => void) | null = null;
+
   /**
    * Private constructor. Use `McplServerConnection.connect()` instead.
    */
@@ -151,6 +154,33 @@ export class McplServerConnection extends EventEmitter {
   // Static factory
   // ==========================================================================
 
+  /**
+   * Wire stderr forwarding on a child process. Lines are forwarded to the
+   * supplied callback. The callback can be swapped at any time via `rebind`
+   * (used during reconnect, when we want already-wired pipes to target a new
+   * emitter).
+   */
+  private static wireStderrForwarding(
+    child: ChildProcess,
+    initialLineHandler: (line: string) => void,
+  ): { rebind: (next: (line: string) => void) => void } {
+    let onLine = initialLineHandler;
+    let carry = '';
+    child.stderr?.on('data', (chunk: Buffer) => {
+      const text = carry + chunk.toString('utf8');
+      const lines = text.split('\n');
+      carry = lines.pop() ?? '';
+      for (const line of lines) {
+        if (line.length > 0) onLine(line);
+      }
+    });
+    return {
+      rebind(next) {
+        onLine = next;
+      },
+    };
+  }
+
   /**
    * Spawn a server process, perform the MCP initialize handshake with MCPL
    * capability negotiation, and return a ready-to-use connection.
@@ -166,6 +196,14 @@ export class McplServerConnection extends EventEmitter {
       env: { ...process.env, ...config.env },
     });
 
+    // Capture child stderr so it isn't silently dropped. During the handshake
+    // window (before the instance exists) lines are buffered; the buffer is
+    // drained once we have an instance to emit 'stderr' events on.
+    const earlyStderrBuffer: string[] = [];
+    const attachStderr = McplServerConnection.wireStderrForwarding(child, (line) =>
+      earlyStderrBuffer.push(line),
+    );
+
     // Fail fast if the process exits before the handshake completes
     const earlyExitPromise = new Promise<never>((_resolve, reject) => {
       child.on('error', (err) => {
@@ -251,6 +289,16 @@ export class McplServerConnection extends EventEmitter {
 
     const connection = new McplServerConnection(config.id, mcplCaps, child, rl);
 
+    // Swap the stderr handler to emit events on the instance, then drain
+    // anything that arrived during the handshake window. Keep the rebind
+    // handle on the instance so reconnect can re-target it later.
+    connection.rebindStderr = attachStderr.rebind;
+    attachStderr.rebind((line: string) => connection.emit('stderr', { line }));
+    for (const line of earlyStderrBuffer) {
+      connection.emit('stderr', { line });
+    }
+    earlyStderrBuffer.length = 0;
+
     // Store config for reconnection
     if (config.reconnect) {
       connection.config = config;
@@ -395,9 +443,21 @@ export class McplServerConnection extends EventEmitter {
     this.sendNotification(McplMethod.ChannelsOutgoingComplete, params as unknown as Record<string, unknown>);
   }
 
-  /** Send `channels/typing` notification (best-effort). */
-  sendChannelsTyping(channelId: string): void {
-    this.sendNotification(McplMethod.ChannelsTyping, { channelId });
+  /** Send `channels/typing` notification (best-effort).
+   *  `metadata` is opaque routing hints for the server — e.g. Zulip uses
+   *  `topic` to target a specific thread; other servers ignore what they don't
+   *  recognize. Typically sourced from the most recent incoming message's
+   *  metadata on the same channel.
+   *  `op` defaults to 'start'; pass 'stop' to clear an active indicator
+   *  immediately rather than waiting for server-side auto-expire. */
+  sendChannelsTyping(
+    channelId: string,
+    metadata?: Record<string, unknown>,
+    op: 'start' | 'stop' = 'start',
+  ): void {
+    const params: Record<string, unknown> = { channelId, op };
+    if (metadata) params.metadata = metadata;
+    this.sendNotification(McplMethod.ChannelsTyping, params);
   }
 
   // ==========================================================================
@@ -499,6 +559,21 @@ export class McplServerConnection extends EventEmitter {
       this.nextRequestId = 1;
       this.pendingRequests.clear();
 
+      // Re-target stderr forwarding from the throwaway `fresh` instance to `this`.
+      //
+      // Note: this follows the same "transfer internals, leak listeners on the
+      // dead instance" pattern as the message-routing and lifecycle rewiring
+      // below — `fresh`'s own readline 'line' handler and process 'exit'
+      // handler stay registered on the transferred child, short-circuited by
+      // `fresh.closed = true` set in extractInternals(). Rebinding fresh's
+      // stderr listener (rather than removing it) keeps that invariant: if we
+      // ever clean up the message-routing duplication, fresh's stderr data
+      // listener closure-holds onLine and would need the same teardown.
+      if (fresh.rebindStderr) {
+        fresh.rebindStderr((line: string) => this.emit('stderr', { line }));
+        this.rebindStderr = fresh.rebindStderr;
+      }
+
       // Re-wire message routing and lifecycle on the new process
       this.setupMessageRouting();
       this.setupLifecycle();

package/src/mcpl/tool-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool allow/deny policy for MCPL servers.
+ *
+ * `enabledTools` and `disabledTools` on McplServerConfig hold bare tool names
+ * (no toolPrefix) with `*` substring wildcards. This module owns the predicate
+ * used at both tool-list time and dispatch time.
+ *
+ * Semantics:
+ *   - No fields set                 → all tools allowed.
+ *   - Only enabledTools set         → tool must match at least one pattern.
+ *   - Only disabledTools set        → tool must NOT match any pattern.
+ *   - Both set                      → must match enabledTools AND not match disabledTools.
+ *                                     (deny wins on overlap.)
+ */
+
+/**
+ * Compile a pattern with `*` substring wildcards into a regex.
+ * `*` matches any run of characters (including empty); other characters are literal.
+ */
+function compilePattern(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function anyMatch(patterns: string[], name: string): boolean {
+  for (const p of patterns) {
+    if (compilePattern(p).test(name)) return true;
+  }
+  return false;
+}
+
+export interface ToolPolicy {
+  enabledTools?: string[];
+  disabledTools?: string[];
+}
+
+/**
+ * Returns true if `bareToolName` (server-native name, no prefix) is allowed
+ * under the supplied policy.
+ */
+export function isToolAllowed(bareToolName: string, policy: ToolPolicy | undefined): boolean {
+  if (!policy) return true;
+  const { enabledTools, disabledTools } = policy;
+
+  if (disabledTools && disabledTools.length > 0 && anyMatch(disabledTools, bareToolName)) {
+    return false;
+  }
+  if (enabledTools && enabledTools.length > 0) {
+    return anyMatch(enabledTools, bareToolName);
+  }
+  return true;
+}

package/src/mcpl/types.ts

@@ -180,6 +180,24 @@ export interface McplServerConfig {
   /** Feature sets to explicitly disable on connect */
   disabledFeatureSets?: string[];
 
+  /**
+   * Tool allow-list (bare tool names as the server exports them, no toolPrefix).
+   * Supports `*` as a substring wildcard (e.g. `read_*`, `*_file`, `*`).
+   * If set, only tools matching at least one pattern are exposed.
+   * `disabledTools` takes precedence on conflict.
+   *
+   * Filter is applied in two places: at tool-list time (model never sees the
+   * tool) and at dispatch time (call rejected with a tool-result error, in
+   * case the model imitates a prior call from message history).
+   */
+  enabledTools?: string[];
+
+  /**
+   * Tool deny-list (bare tool names, same wildcard syntax as enabledTools).
+   * Wins over enabledTools on conflict.
+   */
+  disabledTools?: string[];
+
   /** Scope configurations per feature set */
   scopes?: Record<string, ScopeConfig>;
 
@@ -222,6 +240,22 @@ export interface McplServerConfig {
    * Must not collide with any module name or another server's prefix.
    */
   toolPrefix?: string;
+
+  /**
+   * How channels registered by this server are opened.
+   * - `'auto'` (default) — every registered channel is auto-opened; the host
+   *   receives all traffic. Matches prior behavior. Right for agents that
+   *   should listen passively (e.g. a frontdesk clerk).
+   * - `'manual'` — registered channels are listed but not opened. The agent
+   *   must call the `channel_open` tool to start receiving messages. Right
+   *   for focused agents that should not be flooded with chatter from
+   *   servers that advertise many public channels (e.g. Zulip's full stream
+   *   list).
+   * - `string[]` — allow-list of channel ids; only matching channels are
+   *   auto-opened. Ids are server-scoped (the raw id the server registers,
+   *   e.g. `"zulip:tracker-miner-f"`).
+   */
+  channelSubscription?: 'auto' | 'manual' | string[];
 }
 
 // ============================================================================