@animalabs/agent-framework 0.19.0 → 0.21.0

package/src/mcpl/transport.ts

@@ -101,6 +101,72 @@ 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,
+ * network proxies, 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. Proxy URLs may include
+ * credentials. This limits accidental inheritance, not access by a hostile
+ * same-user child process; it is not a process isolation boundary.
+ */
+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',
+  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+  'http_proxy', 'https_proxy', 'no_proxy',
+  '__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. Windows names merge case-insensitively;
+ *  POSIX names remain case-sensitive. `inheritEnv: true` restores full inheritance. */
+export function buildChildEnv(
+  config: Pick<McplServerConfig, 'env' | 'inheritEnv'>,
+  hostEnv: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): NodeJS.ProcessEnv {
+  const win = platform === 'win32';
+  const env: NodeJS.ProcessEnv = config.inheritEnv ? { ...hostEnv } : {};
+  if (!config.inheritEnv) {
+    for (const [key, value] of Object.entries(hostEnv)) {
+      if (value === undefined) continue;
+      // Windows commonly enumerates Path/SystemRoot rather than PATH/SYSTEMROOT.
+      const probe = win ? key.toUpperCase() : key;
+      if (CHILD_ENV_ALLOWLIST.includes(probe) || probe.startsWith('LC_')) env[key] = value;
+    }
+  }
+  if (!win) return { ...env, ...config.env };
+
+  // Windows spawn folds environment names case-insensitively and may choose
+  // an earlier host spelling over a differently cased declared override.
+  // Select Node's first lexicographic spelling within each source, then layer
+  // declared values (including '') over host values. Source precedence and
+  // duplicate-name resolution are separate decisions.
+  const merged: NodeJS.ProcessEnv = {};
+  const spellings = new Map<string, string>();
+  for (const source of [env, config.env ?? {}]) {
+    const seen = new Set<string>();
+    for (const key of Object.keys(source).sort()) {
+      const canonical = key.toUpperCase();
+      if (seen.has(canonical)) continue;
+      seen.add(canonical);
+      const previous = spellings.get(canonical);
+      if (previous !== undefined && previous !== key) delete merged[previous];
+      merged[key] = source[key];
+      spellings.set(canonical, key);
+    }
+  }
+  return merged;
+}
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
 
@@ -139,7 +205,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,22 @@ 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, TLS CA bundles, and HTTP(S) proxy settings — see
+   * CHILD_ENV_ALLOWLIST) plus exactly these. Proxy URLs can contain credentials.
+   * This limits accidental inheritance; it does not isolate a hostile child.
+   */
   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 +408,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 +664,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 +706,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 +1146,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 +1195,7 @@ export interface ChannelsIncomingResult {
 
 /** Result for a single incoming message. */
 export interface ChannelIncomingMessageResult {
+  coalesce?: PushEventResult['coalesce'];
   messageId: string;
   accepted: boolean;
   conversationId?: string;
@@ -1190,6 +1253,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);