@animalabs/agent-framework 0.19.0 → 0.20.0

package/src/mcpl/transport.ts

@@ -101,6 +101,40 @@ export abstract class McplTransport extends EventEmitter {
 // stdio
 // ---------------------------------------------------------------------------
 
+/**
+ * Host variables a stdio child gets by default: just enough for an ordinary
+ * process to run (find binaries, a home dir, temp dir, locale, TLS roots,
+ * a display for GUI helpers). Everything else in the host env — notably API
+ * keys and bot tokens — is NOT passed on; a server that needs a variable must
+ * declare it in its `env` (recipes can `${VAR}`-substitute from .env), or set
+ * `inheritEnv: true` to get the whole host env as before.
+ */
+export const CHILD_ENV_ALLOWLIST = [
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'LANG', 'TZ',
+  'TMPDIR', 'TMP', 'TEMP',
+  'DISPLAY', 'WAYLAND_DISPLAY',
+  'XDG_RUNTIME_DIR', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME',
+  'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+  '__CF_USER_TEXT_ENCODING',
+  // Windows equivalents, harmless elsewhere.
+  'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT', 'APPDATA', 'LOCALAPPDATA', 'USERPROFILE',
+];
+
+/** Environment for a stdio child: allowlisted host vars (+ LC_*), then the
+ *  server's declared `env` on top. `inheritEnv: true` restores full inheritance. */
+export function buildChildEnv(
+  config: Pick<McplServerConfig, 'env' | 'inheritEnv'>,
+  hostEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  if (config.inheritEnv) return { ...hostEnv, ...config.env };
+  const env: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(hostEnv)) {
+    if (value === undefined) continue;
+    if (CHILD_ENV_ALLOWLIST.includes(key) || key.startsWith('LC_')) env[key] = value;
+  }
+  return { ...env, ...config.env };
+}
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
 
@@ -139,7 +173,7 @@ export class StdioTransport extends McplTransport {
     }
     const child = spawn(config.command, config.args ?? [], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, ...config.env },
+      env: buildChildEnv(config),
     });
     const rl = createInterface({ input: child.stdout! });
     return new StdioTransport(child, rl);

package/src/mcpl/types.ts

@@ -145,6 +145,10 @@ export interface McplCapabilities {
   /** Server consumes inference/lifecycle notifications (§10.5). */
   inferenceLifecycle?: boolean;
 
+  /** RFC-007 tool lifecycle: observe (metadata) and inputs (requested
+   *  argument fields). `true` = both leaves. */
+  toolLifecycle?: boolean | { observe?: boolean; inputs?: boolean };
+
   /** Server supports model/info requests */
   modelInfo?: boolean;
 
@@ -161,6 +165,15 @@ export interface McplCapabilities {
  */
 export interface McplHostCapabilities {
   version: string;
+  /** RFC-006 support, independent of capability grants. */
+  eventCoalescing?: boolean | {
+    pushEvents?: boolean;
+    channelsIncoming?: boolean;
+    deferred?: boolean;
+    channelScopedPush?: boolean;
+    /** Retry-window guarantee in ms (integer ≥ 3,600,000; default 3,600,000). */
+    retryWindowMs?: number;
+  };
   pushEvents?: boolean;
   contextHooks?: {
     beforeInference?: boolean | {
@@ -170,6 +183,10 @@ export interface McplHostCapabilities {
   };
   inferenceRequest?: boolean | { streaming?: boolean };
   inferenceLifecycle?: boolean;
+
+  /** RFC-007 tool lifecycle: observe (metadata) and inputs (requested
+   *  argument fields). `true` = both leaves. */
+  toolLifecycle?: boolean | { observe?: boolean; inputs?: boolean };
   modelInfo?: boolean;
   featureSets?: boolean;
   channels?: boolean | McplChannelCapabilities;
@@ -209,9 +226,20 @@ export interface McplServerConfig {
   /** Arguments for the command */
   args?: string[];
 
-  /** Environment variables for the child process */
+  /**
+   * Environment variables for the child process. Stdio children do NOT inherit
+   * the host environment wholesale: they get a small allowlist (PATH, HOME,
+   * LANG, LC_*, TMPDIR, ... — see CHILD_ENV_ALLOWLIST) plus exactly these.
+   */
   env?: Record<string, string>;
 
+  /**
+   * Escape hatch: pass the host's entire environment (including secrets) to
+   * the stdio child, as older versions did. Only for servers that genuinely
+   * need it. Default false.
+   */
+  inheritEnv?: boolean;
+
   /**
    * WebSocket URL for the network transport (`ws://` or `wss://`). Mutually
    * exclusive with `command`. When set (or `transport: 'websocket'`), the host
@@ -378,6 +406,17 @@ export interface McplServerConfig {
    *  cumulative per-server byte budget (reference-fetcher.ts defaults apply
    *  when absent). */
   autofetch?: { maxBytes?: number; maxTotalBytes?: number };
+
+  /**
+   * RFC-007 tool lifecycle policy for this server: narrowing for the
+   * `toolLifecycle.observe` and `toolLifecycle.inputs` grants, and the
+   * `input` size bound. Both paths are DENIED BY DEFAULT; stating a key here
+   * (or naming the path in enabledCapabilities) is the explicit grant.
+   * `inputs` without a `tools` or `classes` term delivers no arguments, and
+   * `comms` or unclassed tools never carry arguments whatever it says.
+   * See src/mcpl/tool-lifecycle.ts.
+   */
+  toolLifecycle?: import('./tool-lifecycle.js').ToolLifecycleConfig;
 }
 
 // ============================================================================
@@ -623,6 +662,21 @@ export interface StateRollbackResult {
  * Spec Section 9.1.
  */
 export interface PushEventParams {
+  /** RFC-006 event coalescing (mcpl PR #5, revision 7). */
+  coalesce?: {
+    /** Subject key, 1..256 UTF-8 bytes, opaque to the host. */
+    key: string;
+    /** push/event only: address a registered channel's subject namespace. */
+    channelId?: string;
+    /** push/event only: deferred mode — the host calls push/render at assembly. */
+    deferred?: boolean;
+    /** The subject ceased to exist; `payload.content` is the deletion notice. */
+    retract?: boolean;
+    /** No earlier occurrence of this subject was ever sent (§3.3). */
+    initial?: boolean;
+    /** deferred only; ≤ 4 KiB serialized; server-private, echoed by push/render. */
+    data?: unknown;
+  };
   /** Declaring feature set */
   featureSet: string;
 
@@ -650,6 +704,10 @@ export interface PushEventParams {
  * Spec Section 9.3.
  */
 export interface PushEventResult {
+  coalesce?: {
+    outcome: 'first' | 'replaced' | 'appended' | 'retracted' | 'noted' | 'consumed';
+    priorEventId?: string;
+  };
   /** Whether the event was accepted */
   accepted: boolean;
 
@@ -1086,6 +1144,8 @@ export interface ChannelsPublishResult {
  * Spec Section 14.3.
  */
 export interface ChannelIncomingMessage {
+  eventId?: string;
+  coalesce?: Omit<NonNullable<PushEventParams['coalesce']>, 'channelId' | 'deferred'>;
   /** Channel this message came from */
   channelId: string;
 
@@ -1133,6 +1193,7 @@ export interface ChannelsIncomingResult {
 
 /** Result for a single incoming message. */
 export interface ChannelIncomingMessageResult {
+  coalesce?: PushEventResult['coalesce'];
   messageId: string;
   accepted: boolean;
   conversationId?: string;
@@ -1190,6 +1251,13 @@ export const McplMethod = {
   // context/afterInference. Metadata only; BEST-EFFORT delivery.
   InferenceLifecycle: 'inference/lifecycle',
 
+  // Tool lifecycle (RFC-007). tools/lifecycle is Host → Server,
+  // Notification, metadata plus (under its own grant) requested argument
+  // fields — never results. tools/observe is Server → Host, Request: the
+  // server's filter over what it is sent (interest, never authority).
+  ToolsLifecycle: 'tools/lifecycle',
+  ToolsObserve: 'tools/observe',
+
   // Server manifest changes (§17). manifestChanged is S→H Notification —
   // an opaque revision plus changed domains, NO payload, deliberately
   // ungated (§17.3: gating it would silence exactly the servers whose

package/src/modules/discord/index.ts

@@ -153,7 +153,7 @@ export class DiscordModule implements Module {
       this.unsubscribeTrace = ctx.onTrace((event: TraceEvent) => {
         const agentName = (event as { agentName?: string }).agentName;
         if (!agentName) return;
-        if (event.type === 'inference:started') {
+        if (event.type === 'inference:started' && !event.silent) {
           this.startTypingLoop(agentName);
         } else if (TURN_TERMINAL_TRACES.has(event.type)) {
           this.stopTypingLoop(agentName);