@animalabs/agent-framework 0.19.0 → 0.21.0

package/src/mcpl/push-handler.ts

@@ -18,6 +18,7 @@ import type {
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
 import { expandCoreTags } from './tags.js';
+import { validateCoalescedContent } from './push-coalescer.js';
 
 // ============================================================================
 // McplPushEvent (the ProcessEvent shape pushed to the queue)
@@ -42,6 +43,10 @@ export interface McplPushEvent {
   inferenceId: string;
   triggerInference?: boolean;
   targetAgents?: string[];
+  /** RFC-006: set when the coalescer delivers; rides the wake it queues. */
+  coalescingSubject?: string;
+  /** RFC-006 assembly: materialized for this agent's turn (store directly). */
+  assemblingFor?: string;
 }
 
 // ============================================================================
@@ -171,6 +176,7 @@ export class PushHandler {
     pushEventFn: (event: McplPushEvent) => void,
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
     shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean,
+    private readonly handleCoalesced?: (serverId: string, params: PushEventParams, event: McplPushEvent) => Promise<PushEventResult>,
   ) {
     this.featureSetManager = featureSetManager;
     this.pushEventFn = pushEventFn;
@@ -189,11 +195,11 @@ export class PushHandler {
    * 6. Emit trace
    * 7. Respond with accepted + inferenceId
    */
-  handlePushEvent(
+  async handlePushEvent(
     serverId: string,
     params: PushEventParams,
     responder?: Responder,
-  ): void {
+  ): Promise<void> {
     // §16.3: expand the normative chat:* core closure once, at entry, so
     // every downstream consumer (wake matching, metadata, the queued event)
     // sees the closed set. Producer `implies` edges are NOT consumed —
@@ -223,8 +229,22 @@ export class PushHandler {
       return;
     }
 
-    // 2. Deduplicate by eventId
-    if (this.dedup.checkAndAdd(params.eventId)) {
+    // 2. Deduplicate by eventId. A coalesced occurrence is deduplicated by the
+    // coalescer's receipts instead (RFC-006 §3.1: a retry within the window
+    // gets its original result, which this set could not return).
+    const coalesced = params.coalesce !== undefined && !!this.handleCoalesced;
+    if (coalesced) {
+      // RFC-006 §13: malformed content is a -32602, checked before conversion.
+      try {
+        validateCoalescedContent(params.payload?.content);
+      } catch (error) {
+        const err = error as Error & { code?: number; field?: string };
+        if (responder?.respondError) responder.respondError(err.code ?? -32602, err.message, { field: err.field });
+        else responder?.respond({ accepted: false, reason: err.message });
+        return;
+      }
+    }
+    if (!coalesced && this.dedup.checkAndAdd(params.eventId)) {
       console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=duplicate`);
       responder?.respond({ accepted: false, reason: 'duplicate' });
       return;
@@ -267,6 +287,22 @@ export class PushHandler {
       inferenceId,
       triggerInference,
     };
+    if (coalesced) {
+      // RFC-006: the coalescer decides whether this occurrence replaces an
+      // unread one, appends, or withdraws; it delivers through the same event
+      // the ordinary path would have queued.
+      try {
+        const result = await this.handleCoalesced!(serverId, params, pushEvent);
+        this.emitTraceFn({ type: 'mcpl:push_event', serverId, eventId: params.eventId, featureSet: params.featureSet, coalesce: result.coalesce });
+        responder?.respond(result);
+      } catch (error) {
+        const err = error as Error & { code?: number; field?: string };
+        console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${err.message}`);
+        if (responder?.respondError) responder.respondError(typeof err.code === 'number' ? err.code : -32603, err.message, { field: err.field });
+        else responder?.respond({ accepted: false, reason: err.message });
+      }
+      return;
+    }
     this.pushEventFn(pushEvent);
 
     // 7. Emit trace

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/server-connection.ts

@@ -46,6 +46,7 @@ import type {
 } from './types.js';
 
 import { McplMethod } from './types.js';
+import type { ToolLifecycleParams, ToolObserveRule } from './tool-lifecycle.js';
 
 /** Timeout for the initialize handshake in milliseconds.
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
@@ -135,6 +136,19 @@ export class McplServerConnection extends EventEmitter {
   /** True once the §5.3 initial policy Request has been answered. */
   policyEstablished = false;
 
+  /**
+   * RFC-007 §6: the server's `tools/observe` filter — interest, never
+   * authority (it only narrows what the grant allows). Null = no filter in
+   * force, which means every granted call is reported with METADATA ONLY
+   * (§5.1). Per connection epoch: discarded on reconnect and whenever
+   * `toolLifecycle.observe` leaves the grant (§6.5).
+   */
+  toolObserveFilter: ToolObserveRule[] | null = null;
+
+  /** Increments at every transport boundary. RFC-007 terminals go only to
+   *  the epoch their opening went to, never across a reconnect. */
+  transportEpoch = 0;
+
   /**
    * §17 manifest tracking (host side of RFC-003): what this host actually
    * fetched and acted on — never the server's announcement log (§17.10:
@@ -157,6 +171,9 @@ export class McplServerConnection extends EventEmitter {
   establishGrant(grant: CapabilityGrant): void {
     this.grant = grant;
     this.policyEstablished = true;
+    // RFC-007 §6.5: revoking observe discards the filter; the server sends
+    // it again if the capability is granted later.
+    if (!grant.has('toolLifecycle.observe')) this.toolObserveFilter = null;
   }
 
   /** A §5.3 grant belongs to one initialized transport epoch. Reconnecting
@@ -165,6 +182,10 @@ export class McplServerConnection extends EventEmitter {
   private resetPolicyForTransportBoundary(): void {
     this.grant = CapabilityGrant.empty();
     this.policyEstablished = false;
+    this.transportEpoch++;
+    // RFC-007 §6.5: a filter is per connection epoch — after a reconnect the
+    // server sends it again, and until then receives metadata only.
+    this.toolObserveFilter = null;
     // §17 tracking is per-epoch for the same reason the grant is: these are
     // facts about what THIS host fetched/negotiated on THIS initialized
     // transport, and a fresh initialize starts a fresh manifest history
@@ -186,7 +207,7 @@ export class McplServerConnection extends EventEmitter {
   private pendingRequests = new Map<string | number, PendingRequest>();
   /** Metadata retained after selected request deadlines so a late response is
    * observable even though its original promise has already been rejected. */
-  private orphanedRequests = new Map<string | number, { method: string }>();
+  private orphanedRequests = new Map<string | number, { method: string; renderParams?: Record<string, unknown> }>();
   private closed = false;
 
   /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
@@ -402,6 +423,9 @@ export class McplServerConnection extends EventEmitter {
     'channels-changed': 'channels.register',
     'channels-incoming': 'channels.incoming',
     'channels-list': 'channels.register',
+    // RFC-007 §4.1: tools/observe is accepted only under toolLifecycle.observe
+    // (-32002 otherwise, including before the §5.3 policy exchange).
+    'tools-observe': 'toolLifecycle.observe',
   };
 
   private static isControlPlaneEvent(event: string): boolean {
@@ -410,6 +434,9 @@ export class McplServerConnection extends EventEmitter {
       || event === 'channels-register'
       || event === 'channels-changed'
       || event === 'tools-list-changed'
+      // RFC-007: a filter is policy-shaped and only narrows; applying it
+      // while the data plane is paused can only reduce what is sent.
+      || event === 'tools-observe'
       || event === 'connect-failed'
       || event === 'reconnect-failed'
       || event === 'orphaned-response'
@@ -629,6 +656,11 @@ export class McplServerConnection extends EventEmitter {
     return this.sendRequest(McplMethod.BeforeInference, params as unknown as Record<string, unknown>) as Promise<BeforeInferenceResult>;
   }
 
+  /** RFC-006 deferred push rendering; its own timeout bounds context assembly. */
+  sendPushRender(params: import('./push-coalescer.js').PushRenderParams): Promise<import('./push-coalescer.js').PushRenderResult> {
+    return this.sendRequest('push/render', params as unknown as Record<string, unknown>, { timeoutMs: 5000, surfaceOrphanedResponse: true }) as Promise<import('./push-coalescer.js').PushRenderResult>;
+  }
+
 
   /** Send `featureSets/update` as a Notification. §6.7: valid ONLY for
    *  purely descriptive metadata that does not alter the grant. Any grant
@@ -666,6 +698,13 @@ export class McplServerConnection extends EventEmitter {
     this.sendNotification(McplMethod.InferenceLifecycle, params as unknown as Record<string, unknown>);
   }
 
+  /** Send `tools/lifecycle` notification (RFC-007). Best-effort. The
+   *  caller (ToolLifecycleEmitter) has already applied grant, narrowing,
+   *  class exclusions and this connection's filter. */
+  sendToolLifecycle(params: ToolLifecycleParams): void {
+    this.sendNotification(McplMethod.ToolsLifecycle, params as unknown as Record<string, unknown>);
+  }
+
   /**
    * Fetch the server's complete current manifest (§17.4) — the
    * experimental.mcpl object in the same shape initialize carries, never a
@@ -952,7 +991,8 @@ export class McplServerConnection extends EventEmitter {
         pending.timer = setTimeout(() => {
           this.pendingRequests.delete(id);
           if (options.surfaceOrphanedResponse) {
-            this.orphanedRequests.set(id, { method });
+            this.orphanedRequests.set(id, { method, ...(method === 'push/render' ? { renderParams: { featureSet: params.featureSet, key: params.key, eventId: params.eventId } } : {}) });
+            if (this.orphanedRequests.size > 4096) this.orphanedRequests.delete(this.orphanedRequests.keys().next().value!);
           }
           reject(new Error(
             `MCPL server "${this.id}" did not respond to ${method} (id=${id}) ` +
@@ -1012,6 +1052,7 @@ export class McplServerConnection extends EventEmitter {
     [McplMethod.ManifestChanged]: 'manifest-changed',
     [McplMethod.ChannelsList]: 'channels-list',
     'notifications/tools/list_changed': 'tools-list-changed',
+    [McplMethod.ToolsObserve]: 'tools-observe',
     // Host-level admin commands initiated from a surface (e.g. a Discord
     // slash command). Params: { command, ... }; host responds with a
     // command-specific result object.
@@ -1043,6 +1084,7 @@ export class McplServerConnection extends EventEmitter {
     [McplMethod.ChannelsChanged]: 'channels.register',
     [McplMethod.ChannelsIncoming]: 'channels.incoming',
     [McplMethod.ChannelsList]: 'channels.register',
+    [McplMethod.ToolsObserve]: 'toolLifecycle.observe',
   };
 
   /**
@@ -1142,6 +1184,10 @@ export class McplServerConnection extends EventEmitter {
       // re-inject either result because the original dispatch context is gone.
       const orphaned = this.orphanedRequests.get(response.id);
       this.orphanedRequests.delete(response.id);
+      if (orphaned?.renderParams) {
+        this.emit('orphaned-render-response', { params: orphaned.renderParams, result: response.result, error: response.error });
+        return; // audit only: a timeout fallback can never be replaced
+      }
       const result = response.result;
       if (result && typeof result === 'object') {
         const r = result as { state?: unknown; checkpoint?: unknown };

package/src/mcpl/tool-classes.ts

@@ -0,0 +1,188 @@
+/**
+ * Tool classes (MCPL RFC-008) — a coarse, fixed vocabulary for what a tool
+ * DOES, used as a key for host policy (RFC-007's argument exclusions today;
+ * approvals, audit grouping and caps later).
+ *
+ * A class is a HINT at the tier of MCP `annotations`, never a grant: it
+ * confers no authority, gates no method, and never changes what the model
+ * sees. The providing server declares it on its MCP tool definition as
+ * `_meta["mcpl/class"]`; the host computes an EFFECTIVE class per tool from
+ * (in precedence order, first source that yields a class wins entirely):
+ *
+ *   1. operator override (FrameworkConfig.toolClassOverrides),
+ *   2. the host's own knowledge of tools it implements (BUILTIN_TOOL_CLASSES
+ *      plus FrameworkConfig.hostToolClasses for an embedding host's modules),
+ *   3. the server's declaration.
+ *
+ * An UNCLASSED tool is handled as the most restrictive class for every
+ * question asked of it (RFC-008 §5.2): classing is how a tool earns looser
+ * handling, never how it is denied. A tool with several classes gets the
+ * union of their restrictions (§5.3).
+ */
+
+import { globMatch } from './tool-glob.js';
+
+export const TOOL_CLASSES = [
+  'comms',
+  'memory',
+  'notes',
+  'files',
+  'shell',
+  'web',
+  'computer',
+  'media',
+  'body',
+  'control',
+] as const;
+
+export type ToolClass = (typeof TOOL_CLASSES)[number];
+
+const CLASS_SET: ReadonlySet<string> = new Set(TOOL_CLASSES);
+
+export function isToolClass(value: unknown): value is ToolClass {
+  return typeof value === 'string' && CLASS_SET.has(value);
+}
+
+/** The `_meta` key a server declares a tool's class under (RFC-008 §3). */
+export const TOOL_CLASS_META_KEY = 'mcpl/class';
+
+/**
+ * Classes whose arguments are ordinarily safe to show an observer (RFC-007
+ * §4.3's recommended default `inputs` policy). `memory`, `notes` and
+ * `control` are left to explicit operator choice; `comms` is never a choice.
+ */
+export const DEFAULT_INPUT_CLASSES: readonly ToolClass[] = [
+  'computer',
+  'shell',
+  'files',
+  'web',
+  'media',
+  'body',
+];
+
+/**
+ * Classes of the tools this framework implements itself — the host's own
+ * knowledge (RFC-008 §5.1 source 2). Keys use the RFC-007 §6.2 pattern
+ * grammar over the model-facing tool name. Anything not listed here, not
+ * overridden and not declared by its server is UNCLASSED, which is the
+ * restrictive answer — so an omission here fails closed.
+ */
+export const BUILTIN_TOOL_CLASSES: Readonly<Record<string, readonly ToolClass[]>> = {
+  // Synthesized channel tools: speech to and from people (RFC-008 §4:
+  // speech that reaches a person is comms, wherever it goes).
+  'channel_*': ['comms'],
+  // Deliberately staying silent in a conversation is still about that
+  // conversation; its reason text can quote it.
+  skip_reply: ['comms'],
+  // The agent's private interior.
+  think: ['memory'],
+  journal: ['memory'],
+  // Host and agent settings, wake policy, routing help.
+  utils: ['control'],
+  agent_settings: ['control'],
+  gate_status: ['control'],
+  tune_out: ['control'],
+  sleep: ['control'],
+  wake: ['control'],
+  wake_add_rule: ['control'],
+  wake_remove_rule: ['control'],
+  event_tags: ['control'],
+  prose_help: ['control'],
+  // Files and blobs in the agent's own stores.
+  save_recent_image: ['files'],
+  read_image: ['files'],
+  // RFC-005 references resolve to the agent's own or private documents, not
+  // the public network (RFC-008 §4: private fetches are files/notes).
+  fetch_reference: ['files'],
+  // Runs code that may do anything: the class describes the tool.
+  code_execution: ['shell'],
+  // Built-in modules.
+  'discord--*': ['comms'],
+  'history--*': ['memory'],
+  'workspace--*': ['files'],
+  'health--*': ['control'],
+  'api--*': ['control'],
+};
+
+/**
+ * Read a server's class declaration from a tool definition's `_meta`.
+ * Returns the known classes it names (deduplicated, in order), or undefined
+ * when it names none — which makes the tool unclassed. Unknown strings are
+ * ignored for policy and logged (RFC-008 §3, vectors 3 and 4); a non-array
+ * value is malformed and ignored the same way.
+ */
+export function parseDeclaredClasses(meta: unknown, toolName = '(unnamed)'): ToolClass[] | undefined {
+  if (!meta || typeof meta !== 'object') return undefined;
+  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`);
+    return undefined;
+  }
+  const out: ToolClass[] = [];
+  for (const value of raw) {
+    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)`);
+    }
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/**
+ * Validate a pattern → classes table from configuration. Unknown class
+ * strings are dropped with a diagnostic; an entry left with no class is
+ * dropped entirely (it cannot classify anything).
+ */
+export function normalizeClassTable(
+  table: Record<string, readonly string[]> | undefined,
+  label: string,
+): Array<[string, ToolClass[]]> {
+  if (!table) return [];
+  const out: Array<[string, ToolClass[]]> = [];
+  for (const [pattern, classes] of Object.entries(table)) {
+    const known: ToolClass[] = [];
+    for (const c of Array.isArray(classes) ? classes : []) {
+      if (isToolClass(c)) {
+        if (!known.includes(c)) known.push(c);
+      } else {
+        console.error(`[mcpl] ${label}["${pattern}"]: unknown tool class ${JSON.stringify(c)} ignored`);
+      }
+    }
+    if (known.length > 0) out.push([pattern, known]);
+  }
+  return out;
+}
+
+export type ToolClassSource = 'override' | 'host' | 'server' | 'none';
+
+export interface EffectiveToolClass {
+  /** Empty for an unclassed tool. */
+  classes: ToolClass[];
+  source: ToolClassSource;
+}
+
+/**
+ * Compute a tool's effective class (RFC-008 §5.1). `overrides` and `host`
+ * are ordered pattern tables (first matching pattern wins within a source);
+ * the first SOURCE that yields a class wins entirely — sources never merge,
+ * so an override can tighten or correct a server's declaration.
+ */
+export function resolveToolClass(
+  toolName: string,
+  declared: readonly ToolClass[] | undefined,
+  tables: {
+    overrides: ReadonlyArray<readonly [string, readonly ToolClass[]]>;
+    host: ReadonlyArray<readonly [string, readonly ToolClass[]]>;
+  },
+): EffectiveToolClass {
+  for (const [pattern, classes] of tables.overrides) {
+    if (globMatch(pattern, toolName)) return { classes: [...classes], source: 'override' };
+  }
+  for (const [pattern, classes] of tables.host) {
+    if (globMatch(pattern, toolName)) return { classes: [...classes], source: 'host' };
+  }
+  if (declared && declared.length > 0) return { classes: [...declared], source: 'server' };
+  return { classes: [], source: 'none' };
+}

package/src/mcpl/tool-glob.ts

@@ -0,0 +1,36 @@
+/**
+ * The portable pattern grammar of MCPL RFC-007 §6.2, used for `tools/observe`
+ * filters and (RFC-007 §17 open question 2) for this host's own tool-lifecycle
+ * narrowing and tool-class tables:
+ *
+ *   - `*` matches any sequence of zero or more characters;
+ *   - every other character matches itself (no escapes, no other metachars);
+ *   - matching is against the whole string, case-sensitive.
+ *
+ * Patterns are server-supplied, so matching must not backtrack without bound
+ * (RFC-007 §10 "Matching cost"). This is the classic two-pointer wildcard
+ * match: it remembers only the most recent `*`, so it runs in
+ * O(pattern × subject) worst case and never recurses.
+ */
+export function globMatch(pattern: string, subject: string): boolean {
+  let p = 0;
+  let s = 0;
+  let star = -1;
+  let mark = 0;
+  while (s < subject.length) {
+    if (p < pattern.length && pattern[p] !== '*' && pattern[p] === subject[s]) {
+      p++;
+      s++;
+    } else if (p < pattern.length && pattern[p] === '*') {
+      star = p++;
+      mark = s;
+    } else if (star !== -1) {
+      p = star + 1;
+      s = ++mark;
+    } else {
+      return false;
+    }
+  }
+  while (p < pattern.length && pattern[p] === '*') p++;
+  return p === pattern.length;
+}