@animalabs/agent-framework 0.22.0 → 0.22.2

package/src/mcpl/server-connection.ts

@@ -15,6 +15,7 @@ import { openTransport, type McplTransport, type TransportCloseInfo } from './tr
 import { maskNegotiatedCapabilities } from './capability-mask.js';
 import { CapabilityGrant, expandAdvertisementShorthand } from './capability-grant.js';
 import { CAPABILITY_DISABLED } from './errors.js';
+import { logDetail, logValue } from './log-value.js';
 
 import type {
   McplServerConfig,
@@ -48,10 +49,52 @@ import type {
 import { McplMethod } from './types.js';
 import type { ToolLifecycleParams, ToolObserveRule } from './tool-lifecycle.js';
 
+/**
+ * Payload of the connection `'close'` event (third argument; the first two
+ * stay `(code, signal)` for existing listeners). Lets a host see WHY the
+ * link went down — in particular a WebSocket close code such as 4001 from
+ * a server that refused or expired the credential — so it can refresh what
+ * `accessProvider` will hand the next dial instead of replaying it.
+ */
+export interface McplConnectionCloseInfo {
+  /** Transport kind that closed; null when the connection never had one
+   *  (a disconnected stub torn down before its first reconnect). */
+  transport: McplTransport['kind'] | null;
+  /** WebSocket close code (e.g. 4001) or stdio child exit code; null when unknown. */
+  code: number | null;
+  /** Signal that ended a stdio child; null otherwise. */
+  signal: NodeJS.Signals | null;
+  /** WebSocket close reason, or a short description of the cause. */
+  reason?: string;
+  /** True when `reason` is the peer's own text, a WebSocket server's close
+   *  reason, rather than the transport's or the host's words. */
+  reasonFromPeer?: boolean;
+  /** True when the host closed the link (`close()` / `reconnectAfterFailure()`),
+   *  false when the transport dropped unexpectedly. */
+  byHost: boolean;
+}
+
 /** Timeout for the initialize handshake in milliseconds.
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
 
+/** A failed connect's `stderrTail`, the last of the server's stderr that its
+ *  handshake's error keeps, when there is one. */
+export function stderrTailOf(error: unknown): string | undefined {
+  const tail = (error as { stderrTail?: unknown } | null | undefined)?.stderrTail;
+  return typeof tail === 'string' && tail !== '' ? tail : undefined;
+}
+
+/** For the host's own log line about a failed connect: the server's stderr
+ *  that the error keeps as `stderrTail`, one marked line per line of it,
+ *  each through log-value, since it's the server's text. '' when there's
+ *  none. */
+export function withStderr(error: unknown): string {
+  const tail = stderrTailOf(error);
+  if (tail === undefined) return '';
+  return '. The last of its stderr:' + tail.split('\n').map((line) => `\n  stderr: ${logDetail(line)}`).join('');
+}
+
 /** Default per-request timeout in milliseconds (see McplServerConfig.requestTimeoutMs).
  *  A live-but-wedged server (accepts requests, never answers, never closes its
  *  transport) would otherwise freeze the awaiting agent turn forever — no
@@ -93,9 +136,14 @@ interface RequestOptions {
  * - `'channels-changed'`   — Server sent `channels/changed`
  * - `'channels-incoming'`  — Server sent `channels/incoming`
  * - `'error'`              — Connection-level error
- * - `'close'`              — Connection closed
- * - `'connect-failed'`     — Initial connect failed; background retry scheduled
- * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled
+ * - `'close'`              — Connection closed: `(code, signal, info: McplConnectionCloseInfo)`
+ * - `'connect-failed'`     — Initial connect failed; background retry scheduled:
+ *   `{ error, stderrTail?, attempt }`
+ * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled:
+ *   `{ error, stderrTail?, attempt }`. `stderrTail` is the last of the
+ *   server's stderr when its handshake failed by its transport closing, a
+ *   transport error or its timeout and it had written any; `error` never
+ *   carries it.
  * - `'reconnect'`          — Background reconnect succeeded
  */
 export class McplServerConnection extends EventEmitter {
@@ -209,6 +257,9 @@ export class McplServerConnection extends EventEmitter {
    * observable even though its original promise has already been rejected. */
   private orphanedRequests = new Map<string | number, { method: string; renderParams?: Record<string, unknown> }>();
   private closed = false;
+  /** Set by `reconnectAfterFailure()` before it closes a live transport, so
+   *  the transport close handler reports that teardown as `byHost: true`. */
+  private hostCloseRequested = false;
   private closePromise: Promise<void> | null = null;
   private closeIncomplete = false;
   private reconnectPromise: Promise<void> | null = null;
@@ -378,7 +429,7 @@ export class McplServerConnection extends EventEmitter {
         if (responder?.respondError) {
           responder.respondError(CAPABILITY_DISABLED, `${name} rejected: capability "${requiredCap}" ${phase}`, { capability: requiredCap });
         } else {
-          console.error(`[mcpl] ${this.id}: discarded ${name} — "${requiredCap}" ${phase}`);
+          console.error(`[mcpl] ${this.id}: discarded ${logValue(name)} — "${requiredCap}" ${phase}`);
         }
         return true;
       }
@@ -506,6 +557,15 @@ export class McplServerConnection extends EventEmitter {
     hostCapabilities: McplHostCapabilities,
   ): Promise<{ transport: McplTransport; capabilities: McplCapabilities | null; droppedCapabilities: ReadonlySet<string>; mcpToolsAdvertised: boolean }> {
     const transport = await openTransport(config);
+    // Once the handshake stops listening for 'error', this logs what the
+    // transport reports, until the handshake hands the transport on, or for
+    // good if the handshake fails. EventEmitter throws an 'error' that has no
+    // listener, and from an I/O callback nothing catches it. A malformed
+    // WebSocket frame that arrives with the initialize response, or while a
+    // failed handshake's close() runs, is such an error.
+    const logAfterSettled = (err: Error) => {
+      console.error(`[mcpl] ${config.id}: transport error after the handshake settled: ${err.message}`);
+    };
 
     try {
       const initId = 0; // use id=0 for the handshake
@@ -523,10 +583,20 @@ export class McplServerConnection extends EventEmitter {
       // Await the initialize response, racing an early transport close/error and
       // a timeout. All three paths clean up their listeners.
       const { mcpl: rawCapabilities, mcpToolsAdvertised } = await new Promise<{ mcpl: McplCapabilities | null; mcpToolsAdvertised: boolean }>((resolve, reject) => {
+        // When the transport fails, the end of the server's stderr often says
+        // why, such as a missing token or a crash at startup. It goes on the
+        // error as `stderrTail`, never into the message: an error's message
+        // travels to traces and tool results, and a server's stderr is its
+        // own text, which can hold a credential.
+        const failed = (failure: string): Error & { stderrTail?: string } => {
+          const tail = transport.stderrTail.trimEnd();
+          return Object.assign(new Error(failure), tail ? { stderrTail: tail } : {});
+        };
         const cleanup = () => {
           transport.off('line', onLine);
           transport.off('close', onClose);
           transport.off('error', onError);
+          transport.on('error', logAfterSettled);
           clearTimeout(timer);
         };
         const onLine = (line: string) => {
@@ -555,15 +625,15 @@ export class McplServerConnection extends EventEmitter {
         };
         const onClose = (info: TransportCloseInfo) => {
           cleanup();
-          reject(new Error(`MCPL server "${config.id}" transport closed before handshake completed (${info.reason ?? 'unknown'})`));
+          reject(failed(`MCPL server "${config.id}" transport closed before handshake completed (${info.reason ?? 'unknown'})`));
         };
         const onError = (err: Error) => {
           cleanup();
-          reject(new Error(`MCPL server "${config.id}" transport error during handshake: ${err.message}`));
+          reject(failed(`MCPL server "${config.id}" transport error during handshake: ${err.message}`));
         };
         const timer = setTimeout(() => {
           cleanup();
-          reject(new Error(`MCPL server "${config.id}" initialize handshake timed out`));
+          reject(failed(`MCPL server "${config.id}" initialize handshake timed out`));
         }, INITIALIZE_TIMEOUT_MS);
 
         transport.on('line', onLine);
@@ -585,9 +655,13 @@ export class McplServerConnection extends EventEmitter {
       // had never been advertised (hooks, streaming, queries all read this).
       const { capabilities: scoped, dropped } = maskNegotiatedCapabilities(capabilities, config);
       if (dropped.length > 0) {
-        console.error(`MCPL server "${config.id}" capabilities masked by host config: ${dropped.join(', ')}`);
+        console.error(`MCPL server "${config.id}" capabilities masked by host config: ${dropped.map(logValue).join(', ')}`);
       }
 
+      // The caller wires the transport, or keeps it for close() with a
+      // listener of its own, in the continuation of this return, before any
+      // I/O callback can emit.
+      transport.off('error', logAfterSettled);
       return { transport, capabilities: scoped, droppedCapabilities: new Set(dropped), mcpToolsAdvertised };
     } catch (err) {
       // Never leak the child / socket if the handshake fails.
@@ -614,12 +688,13 @@ export class McplServerConnection extends EventEmitter {
       }
 
       // Non-blocking start: create a disconnected stub that will reconnect in background
-      console.error(`MCPL server "${config.id}" initial connect failed, will retry:`, (error as Error).message);
+      console.error(`MCPL server "${config.id}" initial connect failed, will retry: ${(error as Error).message}${withStderr(error)}`);
       const stub = McplServerConnection.createDisconnectedStub(config, hostCapabilities);
       // Surface the initial failure. The event is buffered by the emit()
       // override until the host wires listeners and calls ready(), so it is
       // not lost in the window before wireMcplEvents runs.
-      stub.emit('connect-failed', { error: (error as Error).message, attempt: 0 });
+      const stderrTail = stderrTailOf(error);
+      stub.emit('connect-failed', { error: (error as Error).message, ...(stderrTail ? { stderrTail } : {}), attempt: 0 });
       return stub;
     }
   }
@@ -864,7 +939,7 @@ export class McplServerConnection extends EventEmitter {
       if (this.reconnectPromise) await this.reconnectPromise;
       if (this.transport) await this.transport.close();
       this.closeIncomplete = false;
-      this.emit('close');
+      this.emit('close', null, null, this.closeInfoByHost());
     });
     this.closePromise = attempt;
     void attempt.catch(() => {
@@ -886,14 +961,26 @@ export class McplServerConnection extends EventEmitter {
       return;
     }
     if (this.transport) {
+      this.hostCloseRequested = true;
       await this.transport.close();
       return;
     }
     this.closed = true;
-    this.emit('close');
+    this.emit('close', null, null, this.closeInfoByHost());
     this.scheduleReconnect();
   }
 
+  /** 'close' payload for a host-initiated teardown (no transport close code). */
+  private closeInfoByHost(): McplConnectionCloseInfo {
+    return {
+      transport: this.transport?.kind ?? null,
+      code: null,
+      signal: null,
+      reason: 'closed by host',
+      byHost: true,
+    };
+  }
+
   /**
    * Schedule a background reconnection attempt.
    *
@@ -952,6 +1039,13 @@ export class McplServerConnection extends EventEmitter {
         // The prior transport was disconnected before this retry began. Keep
         // the fresh, unadmitted transport owned by close(), including on a
         // failed transport cleanup, instead of reviving a stopped connection.
+        // It isn't wired, and the handshake has removed its own listeners, so
+        // an error it reports from here on, such as a malformed frame from a
+        // WebSocket server while close() closes it, is logged here rather than
+        // thrown where nothing catches it.
+        transport.on('error', (err: Error) => {
+          console.error(`[mcpl] ${this.id}: a transport kept for close() reported an error: ${err.message}`);
+        });
         this.transport = transport;
         return;
       }
@@ -976,9 +1070,10 @@ export class McplServerConnection extends EventEmitter {
       this.reconnectAttempts = 0;
       this.emit('reconnect', { attempts: attempt });
     } catch (error) {
-      console.error(`MCPL server "${this.id}" reconnect failed:`, (error as Error).message);
+      console.error(`MCPL server "${this.id}" reconnect failed: ${(error as Error).message}${withStderr(error)}`);
       this.reconnectAttempts = attempt + 1;
-      this.emit('reconnect-failed', { error: (error as Error).message, attempt });
+      const stderrTail = stderrTailOf(error);
+      this.emit('reconnect-failed', { error: (error as Error).message, ...(stderrTail ? { stderrTail } : {}), attempt });
       this.scheduleReconnect();
     }
   }
@@ -1285,6 +1380,7 @@ export class McplServerConnection extends EventEmitter {
    * and — when enabled — schedules a background reconnect.
    */
   private setupLifecycle(transport: McplTransport): void {
+    this.hostCloseRequested = false;
     transport.on('error', (err: Error) => {
       this.emit('error', new Error(`MCPL server "${this.id}" transport error: ${err.message}`));
     });
@@ -1306,7 +1402,21 @@ export class McplServerConnection extends EventEmitter {
         this.pendingRequests.clear();
         this.orphanedRequests.clear();
 
-        this.emit('close', info.code ?? null, info.signal ?? null);
+        // Forward the transport's close info so listeners can tell a server
+        // that refused the credential (WebSocket 4001) from a crash, and act
+        // before the reconnect below redials. A teardown the host asked for
+        // via reconnectAfterFailure() arrives here too; report it as such.
+        const byHost = this.hostCloseRequested;
+        this.hostCloseRequested = false;
+        const closeInfo: McplConnectionCloseInfo = {
+          transport: transport.kind,
+          code: info.code ?? null,
+          signal: info.signal ?? null,
+          reason: info.reason ?? (byHost ? 'closed by host' : undefined),
+          ...(info.reasonFromPeer ? { reasonFromPeer: true } : {}),
+          byHost,
+        };
+        this.emit('close', closeInfo.code, closeInfo.signal, closeInfo);
 
         // Schedule reconnect if enabled (unexpected disconnect triggers auto-reconnect)
         if (this.reconnectEnabled) {

package/src/mcpl/tool-classes.ts

@@ -21,6 +21,7 @@
  */
 
 import { globMatch } from './tool-glob.js';
+import { logValue } from './log-value.js';
 
 export const TOOL_CLASSES = [
   'comms',
@@ -116,7 +117,7 @@ export function parseDeclaredClasses(meta: unknown, toolName = '(unnamed)'): Too
   const raw = (meta as Record<string, unknown>)[TOOL_CLASS_META_KEY];
   if (raw === undefined) return undefined;
   if (!Array.isArray(raw)) {
-    console.error(`[mcpl] ${toolName}: _meta["${TOOL_CLASS_META_KEY}"] is not an array — treated as unclassed`);
+    console.error(`[mcpl] ${logValue(toolName)}: _meta["${TOOL_CLASS_META_KEY}"] is not an array — treated as unclassed`);
     return undefined;
   }
   const out: ToolClass[] = [];
@@ -124,7 +125,7 @@ export function parseDeclaredClasses(meta: unknown, toolName = '(unnamed)'): Too
     if (isToolClass(value)) {
       if (!out.includes(value)) out.push(value);
     } else {
-      console.error(`[mcpl] ${toolName}: unknown tool class ${JSON.stringify(value)} ignored (RFC-008 §3)`);
+      console.error(`[mcpl] ${logValue(toolName)}: unknown tool class ${logValue(value)} ignored (RFC-008 §3)`);
     }
   }
   return out.length > 0 ? out : undefined;

package/src/mcpl/transport.ts

@@ -19,6 +19,7 @@
 import { spawn, type ChildProcess } from 'node:child_process';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
@@ -29,6 +30,9 @@ export interface TransportCloseInfo {
   code?: number | null;
   signal?: NodeJS.Signals | null;
   reason?: string;
+  /** True when `reason` is the peer's own text, a WebSocket server's close
+   *  reason, rather than the transport's words. */
+  reasonFromPeer?: boolean;
 }
 
 /**
@@ -71,6 +75,16 @@ export abstract class McplTransport extends EventEmitter {
     return this._closed;
   }
 
+  /**
+   * The last of what the server wrote to its diagnostic stream: at most its
+   * last {@link STDERR_TAIL_CHARS} UTF-16 code units, never opening inside a
+   * surrogate pair, after a '…' when earlier ones were dropped. A stdio
+   * child's stderr, and '' for a transport that has none.
+   */
+  get stderrTail(): string {
+    return '';
+  }
+
   /** Deliver an inbound line, buffering it if nobody is listening yet. */
   protected pushLine(line: string): void {
     if (this.listenerCount('line') > 0) this.emit('line', line);
@@ -167,8 +181,19 @@ export function buildChildEnv(
   return merged;
 }
 
+/** The most of a stdio child's stderr a transport keeps for {@link McplTransport.stderrTail}. */
+export const STDERR_TAIL_CHARS = 2_048;
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
+  /** The first error on the child's stdin or stdout, named in the close reason. */
+  private pipeError: Error | undefined;
+  private stderrEnd = '';
+  private stderrCut = false;
+
+  override get stderrTail(): string {
+    return (this.stderrCut ? '…' : '') + this.stderrEnd;
+  }
 
   private constructor(
     private readonly child: ChildProcess,
@@ -178,26 +203,70 @@ export class StdioTransport extends McplTransport {
 
     this.rl.on('line', (line: string) => this.pushLine(line));
 
-    // Stitch stderr chunks into whole lines (a chunk can split a line).
+    // Stitch stderr chunks into whole lines (a chunk can split a line, and a
+    // character's bytes), and keep the stream's last characters for
+    // stderrTail.
     let carry = '';
-    this.child.stderr?.on('data', (chunk: Buffer) => {
-      const text = carry + chunk.toString('utf8');
-      const lines = text.split('\n');
+    const decoder = new StringDecoder('utf8');
+    const received = (text: string) => {
+      const end = this.stderrEnd + text;
+      this.stderrCut ||= end.length > STDERR_TAIL_CHARS;
+      let kept = end.slice(-STDERR_TAIL_CHARS);
+      // A cut between a surrogate pair's halves drops the low half too.
+      if (/^[\uDC00-\uDFFF]/.test(kept) && end.length > STDERR_TAIL_CHARS) kept = kept.slice(1);
+      this.stderrEnd = kept;
+      const lines = (carry + text).split('\n');
       carry = lines.pop() ?? '';
       for (const l of lines) if (l.length > 0) this.pushStderr(l);
+    };
+    this.child.stderr?.on('data', (chunk: Buffer) => received(decoder.write(chunk)));
+    // A last line with no newline is complete once the stream ends.
+    this.child.stderr?.on('end', () => {
+      received(decoder.end());
+      if (carry.length > 0) this.pushStderr(carry);
     });
 
     this.child.on('error', (err) => this.emit('error', err));
-    this.child.on('exit', (code, signal) =>
-      this.markClosed({ code, signal, reason: 'child process exited' }),
-    );
+    // The child's stdin and stdout carry the protocol, so after an error on
+    // either, a write's EPIPE or a read error, this transport can't reach the
+    // child even if it's still running. The handler sends a running child
+    // SIGTERM, and the exit's close names the error, so the connection handles
+    // it as any other exit. The close is the report: no 'error' is emitted,
+    // nothing is thrown. Nothing here escalates to SIGKILL, so a child that
+    // ignores SIGTERM keeps running, unreported. A child that stops reading
+    // without closing its stdin raises no error: the writes are buffered, and
+    // only request timeouts bound it (McplServerConfig.requestTimeoutMs).
+    const endOnPipeError = (err: Error) => {
+      this.pipeError ??= err;
+      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+    };
+    this.child.stdin?.on('error', endOnPipeError);
+    // On the stream itself, since close() closes readline, which takes its own
+    // listener off the stream. While readline is open, its listener, which
+    // came first, re-emits the error on the interface, where an empty
+    // listener absorbs that copy.
+    this.child.stdout?.on('error', endOnPipeError);
+    this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
+    // stderr carries diagnostics only: a read error on it is reported if
+    // anyone listens and never thrown. It ends nothing once the connection
+    // is wired; during a handshake the listener is the handshake's, which
+    // fails it.
+    this.child.stderr?.on('error', (err) => {
+      if (this.listenerCount('error') > 0) this.emit('error', err);
+    });
+    this.child.on('exit', (code, signal) => this.markClosed({
+      code,
+      signal,
+      reason: this.pipeError ? `child process exited, and its pipe failed with ${this.pipeError.message}` : 'child process exited',
+    }));
   }
 
   /**
-   * Spawn `config.command` and return a ready stdio transport. Rejects if the
-   * command is missing (a config bug) or the process fails to spawn.
+   * Spawn `config.command` and resolve with a ready stdio transport once the
+   * child has spawned. Rejects if the command is missing (a config bug) or the
+   * process fails to spawn.
    */
-  static spawn(config: McplServerConfig): StdioTransport {
+  static async spawn(config: McplServerConfig): Promise<StdioTransport> {
     if (!config.command) {
       throw new Error(
         `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
@@ -207,6 +276,22 @@ export class StdioTransport extends McplTransport {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: buildChildEnv(config),
     });
+    // Node reports a failed spawn (a command that doesn't exist, say) as an
+    // 'error' on a tick after spawn() returns, and no 'exit' follows. It is
+    // settled here, where it is listened for. A caller that listens only once
+    // this resolves, as the handshake does, would be too late when reached
+    // from a timer callback, as a reconnect is: Node runs that tick before the
+    // caller's promise continuation, and throws an 'error' nothing listens for.
+    await new Promise<void>((resolve, reject) => {
+      const failed = (err: Error) => {
+        reject(new Error(`MCPL server "${config.id}" could not be started: ${err.message}`, { cause: err }));
+      };
+      child.once('error', failed);
+      child.once('spawn', () => {
+        child.off('error', failed);
+        resolve();
+      });
+    });
     const rl = createInterface({ input: child.stdout! });
     return new StdioTransport(child, rl);
   }
@@ -223,7 +308,12 @@ export class StdioTransport extends McplTransport {
       this.child.kill();
     }
     await new Promise<void>((resolve) => {
-      if (!this.child || this.child.exitCode !== null || this.child.killed) {
+      // Once Node has seen a child exit, it has its exitCode set, or its
+      // signalCode when a signal ended it, and its 'exit' event has fired. A
+      // signal that didn't come through kill() (an OOM kill, a crash) leaves
+      // `killed` false. A child that has exited but isn't reaped yet still
+      // takes the kill() above, which sets `killed`.
+      if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null || this.child.killed) {
         resolve();
       } else {
         this.child.once('exit', () => resolve());
@@ -256,9 +346,10 @@ export class WebSocketTransport extends McplTransport {
     });
 
     this.ws.on('error', (err: Error) => this.emit('error', err));
-    this.ws.on('close', (code: number, reason: Buffer) =>
-      this.markClosed({ code, reason: reason?.toString('utf8') || 'websocket closed' }),
-    );
+    this.ws.on('close', (code: number, reason: Buffer) => {
+      const text = reason?.toString('utf8');
+      this.markClosed(text ? { code, reason: text, reasonFromPeer: true } : { code, reason: 'websocket closed' });
+    });
   }
 
   /**

package/src/mcpl/types.ts

@@ -374,7 +374,11 @@ export interface McplServerConfig {
    * accepts a request and never responds would otherwise freeze the awaiting
    * agent turn forever; with the timeout the pending request rejects with a
    * descriptive error, which the framework surfaces as a normal isError
-   * tool_result. Set 0 to disable. Default: 60000 (60 seconds).
+   * tool_result. Request timeouts are the only bound for a stdio server that
+   * stops reading its stdin without closing it: the host's writes are
+   * buffered, no error is raised, and the connection stays up. This is the
+   * timeout of every request that names none; the handshake's initialize has
+   * its own. Set 0 to disable. Default: 60000 (60 seconds).
    */
   requestTimeoutMs?: number;
 

package/src/module-registry.ts

@@ -26,6 +26,12 @@ import type {
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 
+/** How the registry queues a module's event: its push names the module. A
+ * `ProcessQueue` serves too, ignoring the name. */
+export interface ModuleQueue {
+  push(event: ProcessEvent, moduleName?: string): void;
+}
+
 const MODULE_STATE_PREFIX = 'modules/';
 
 /**
@@ -78,7 +84,7 @@ export class ModuleRegistry {
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
-  private queue: ProcessQueue;
+  private queue: ModuleQueue;
   private getAgents: () => Agent[];
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
@@ -86,7 +92,7 @@ export class ModuleRegistry {
   private getMessageFn: (id: MessageId) => StoredMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
-  private pushEventFn: (event: ProcessEvent) => void;
+  private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
   /** Framework ops-alert channel, surfaced to modules via
@@ -101,7 +107,7 @@ export class ModuleRegistry {
 
   constructor(
     store: JsStore,
-    queue: ProcessQueue,
+    queue: ModuleQueue,
     options: {
       getAgents: () => Agent[];
       addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
@@ -109,7 +115,8 @@ export class ModuleRegistry {
       removeMessage: (id: MessageId) => void;
       getMessage: (id: MessageId) => StoredMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
-      pushEvent: (event: ProcessEvent) => void;
+      /** Called with the pushing module's name. */
+      pushEvent: (event: ProcessEvent, moduleName?: string) => void;
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
       notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
@@ -537,7 +544,7 @@ class ModuleContextImpl implements ModuleContext {
   private removeMessageFn: (id: MessageId) => void;
   private getMessageFn: (id: MessageId) => StoredMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
-  private pushEventFn: (event: ProcessEvent) => void;
+  private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
@@ -548,7 +555,7 @@ class ModuleContextImpl implements ModuleContext {
     moduleName: string,
     store: JsStore,
     stateId: string,
-    queue: ProcessQueue,
+    queue: ModuleQueue,
     registry: ModuleRegistry,
     isRestart: boolean,
     getAgents: () => Agent[],
@@ -557,14 +564,15 @@ class ModuleContextImpl implements ModuleContext {
     removeMessage: (id: MessageId) => void,
     getMessage: (id: MessageId) => StoredMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
-    pushEvent: (event: ProcessEvent) => void,
+    pushEvent: (event: ProcessEvent, moduleName?: string) => void,
     onTrace: (listener: TraceEventListener) => () => void,
     callTool: (call: ToolCall) => Promise<ToolResult>
   ) {
     this.moduleName = moduleName;
     this.store = store;
     this.stateId = stateId;
-    this.queue = queue;
+    // The deprecated handle: a push names this module, as pushEvent() does.
+    this.queue = { push: (event) => queue.push(event, moduleName) };
     this.registry = registry;
     this.isRestart = isRestart;
     this.getAgentsFn = getAgents;
@@ -747,7 +755,7 @@ class ModuleContextImpl implements ModuleContext {
   }
 
   pushEvent(event: ProcessEvent): void {
-    this.pushEventFn(event);
+    this.pushEventFn(event, this.moduleName);
   }
 
   private persistExternalIdMap(): void {

package/src/modules/discord/index.ts

@@ -67,9 +67,11 @@ const TYPING_REFRESH_MS = 8_000;
 // stuck on forever.
 const TYPING_MAX_MS = 5 * 60_000;
 
-// Trace event types that terminate an agent's turn — any of these stops the
-// typing keepalive. They fire once per turn, after all tool-call cycles.
+// Trace event types that end an agent's turn (onTrace's contract) — any of
+// these stops the typing keepalive. A turn's tool-call cycles stay inside its
+// stream, so they come after them. inference:completed is the normal end.
 const TURN_TERMINAL_TRACES = new Set([
+  'inference:completed',
   'inference:turn_ended',
   'inference:aborted',
   'inference:failed',