@animalabs/agent-framework 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
   "license": "MIT",
   "dependencies": {
     "@animalabs/chronicle": "^0.4.0",
-    "@animalabs/context-manager": "^0.12.0",
+    "@animalabs/context-manager": "^0.13.0",
     "@animalabs/membrane": "^0.5.78",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",

package/src/framework.ts

@@ -6994,6 +6994,11 @@ export class AgentFramework {
       if (this.conversationRouter && this.conversationAgentHomes.has(target.name)) {
         metadata.triggered = event.triggerInference ?? false;
         const id = target.getContextManager().addMessage('user', event.content, metadata);
+        // A correction may target an older engagement. Refresh only the
+        // binding whose agent actually received the message.
+        if (this.conversationRouter.getBinding(event.channelId)?.agentName === target.name) {
+          this.conversationRouter.touch(event.channelId);
+        }
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
         if (event.triggerInference) {
           this.pendingRequests.push({
@@ -7173,6 +7178,7 @@ export class AgentFramework {
     messageMetadata.triggered = trigger;
 
     const id = agent.getContextManager().addMessage('user', event.content, messageMetadata);
+    router.touch(event.channelId);
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
 
     if (trigger) {

package/src/mcpl/conversation-router.ts

@@ -95,8 +95,6 @@ export interface IncomingMessageFacts {
   mentioned: boolean;
   /** Channel classification (see classifyChannel). */
   kind: ChannelKind;
-  /** Clock injection for tests; defaults to Date.now(). */
-  now?: number;
 }
 
 export type RoutingDecision =
@@ -149,17 +147,15 @@ export class ConversationRouter {
   }
 
   /**
-   * Decide where an incoming message goes. Pure read except for refreshing
-   * lastActivity on an existing binding — a 'spawn' decision does NOT create
-   * the binding; the framework calls bind() after the fork agent actually
-   * exists, so a failed spawn doesn't leave a dangling route.
+   * Decide where an incoming message goes without changing router state.
+   * The framework calls bind() after a fork exists and touch() after a
+   * message is delivered. Queries and failed deliveries leave idle clocks
+   * unchanged; a failed spawn doesn't leave a dangling route.
    */
   route(facts: IncomingMessageFacts): RoutingDecision {
-    const now = facts.now ?? Date.now();
     const existing = this.bindings.get(facts.channelId);
 
     if (existing) {
-      existing.lastActivity = now;
       return {
         kind: 'existing',
         agentName: existing.agentName,
@@ -202,6 +198,14 @@ export class ConversationRouter {
     return binding;
   }
 
+  /** Record delivered activity on an existing binding. Does not bind a
+   * channel or advance its generation. Call after successful delivery, not
+   * when previewing a route. The optional clock supports deterministic use. */
+  touch(channelId: string, now = Date.now()): void {
+    const binding = this.bindings.get(channelId);
+    if (binding) binding.lastActivity = now;
+  }
+
   unbind(channelId: string): void {
     this.bindings.delete(channelId);
   }

package/src/mcpl/references.ts

@@ -56,12 +56,20 @@ function isRecord(x: unknown): x is Record<string, unknown> {
 
 function takeString(
   raw: unknown, field: keyof typeof REFERENCE_LIMITS & string,
-  out: { rejected: string[]; truncated: string[] },
+  out: { rejected: string[] },
 ): string | undefined {
   if (raw === undefined) return undefined;
   if (typeof raw !== 'string') { out.rejected.push(field); return undefined; }
-  const limit = REFERENCE_LIMITS[field];
-  if (raw.length > limit) { out.truncated.push(field); return raw.slice(0, limit); }
+  // JSON Schema maxLength counts Unicode code points, not UTF-16 units.
+  // Stop as soon as the optional field is invalid, without allocating a copy
+  // of an arbitrarily large server string. Display truncation happens later.
+  let length = 0;
+  for (const _codePoint of raw) {
+    if (++length > REFERENCE_LIMITS[field]) {
+      out.rejected.push(field);
+      return undefined;
+    }
+  }
   return raw;
 }
 

package/src/mcpl/tool-lifecycle.ts

@@ -106,7 +106,7 @@ export interface ToolLifecycleConfig {
 export const DEFAULT_MAX_INPUT_BYTES = 16 * 1024;
 
 /** Accepted sizes for a `tools/observe` request (RFC-007 §6.6 asks hosts to
- *  accept at least 64 rules, 64 paths per rule, 256-character strings). */
+ *  accept at least 64 rules, 64 paths per rule, 256-code-point strings). */
 export const TOOL_OBSERVE_LIMITS = {
   rules: 256,
   pathsPerRule: 256,
@@ -128,6 +128,16 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** JSON Schema maxLength counts code points, not UTF-16 code units.
+ *  Stop at the limit rather than allocating a copy of an oversized input. */
+function exceedsCodePointLimit(value: string, limit: number): boolean {
+  let count = 0;
+  for (const _point of value) {
+    if (++count > limit) return true;
+  }
+  return false;
+}
+
 /**
  * Validate `tools/observe` params. `rules` absent or null clears the filter
  * (`{ok, rules: null}`); `[]` is a valid filter that reports nothing. Unknown
@@ -135,7 +145,9 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * make a rule match more than its author wrote.
  */
 export function parseToolObserveParams(params: unknown): ToolObserveParseResult {
-  if (params === undefined || params === null) return { ok: true, rules: null };
+  // Omitted transport params normalize to {}, but explicit JSON null is
+  // not an object and must not clear an existing restrictive filter.
+  if (params === undefined) return { ok: true, rules: null };
   if (!isPlainObject(params)) return { ok: false, message: 'tools/observe params must be an object' };
   // Unknown members are rejected here too (MCP's own `_meta` excepted): a
   // misspelled `rules` must not read as "no rules" and silently clear a
@@ -145,6 +157,9 @@ export function parseToolObserveParams(params: unknown): ToolObserveParseResult
       return { ok: false, message: `tools/observe: unknown params member "${key}"` };
     }
   }
+  if (params._meta !== undefined && !isPlainObject(params._meta)) {
+    return { ok: false, message: 'tools/observe: _meta must be an object' };
+  }
   const raw = params.rules;
   if (raw === undefined || raw === null) return { ok: true, rules: null };
   if (!Array.isArray(raw)) return { ok: false, message: 'tools/observe: rules must be an array or null' };
@@ -173,7 +188,7 @@ export function parseToolObserveParams(params: unknown): ToolObserveParseResult
         continue;
       }
       if (typeof value !== 'string') return { ok: false, message: `tools/observe: ${at}.match.${key} must be a string` };
-      if (value.length > TOOL_OBSERVE_LIMITS.stringLength) {
+      if (exceedsCodePointLimit(value, TOOL_OBSERVE_LIMITS.stringLength)) {
         return { ok: false, message: `tools/observe: ${at}.match.${key} is too long`, data: { limit: 'stringLength' } };
       }
       (match as Record<string, string>)[key] = value;
@@ -196,7 +211,7 @@ export function parseToolObserveParams(params: unknown): ToolObserveParseResult
           if (typeof path !== 'string' || path.length === 0) {
             return { ok: false, message: `tools/observe: ${at}.input must hold non-empty strings` };
           }
-          if (path.length > TOOL_OBSERVE_LIMITS.stringLength) {
+          if (exceedsCodePointLimit(path, TOOL_OBSERVE_LIMITS.stringLength)) {
             return { ok: false, message: `tools/observe: ${at}.input path is too long`, data: { limit: 'stringLength' } };
           }
           paths.push(path);

package/src/mcpl/transport.ts

@@ -104,10 +104,12 @@ export abstract class McplTransport extends EventEmitter {
 /**
  * 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
+ * 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.
+ * `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',
@@ -115,24 +117,54 @@ export const CHILD_ENV_ALLOWLIST = [
   '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. `inheritEnv: true` restores full inheritance. */
+ *  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 {
-  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;
+  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 { ...env, ...config.env };
+  return merged;
 }
 
 export class StdioTransport extends McplTransport {

package/src/mcpl/types.ts

@@ -229,7 +229,9 @@ export interface McplServerConfig {
   /**
    * 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.
+   * 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>;