@animalabs/agent-framework 0.21.1 → 0.22.1

package/src/mcpl/server-registry.ts

@@ -6,6 +6,7 @@
 
 import type { McplServerConfig, McplHostCapabilities } from './types.js';
 import { McplServerConnection } from './server-connection.js';
+import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from '../shutdown.js';
 
 /**
  * Capability keys that can be queried via `getServersWithCapability`.
@@ -25,6 +26,7 @@ export type McplCapabilityQuery =
  */
 export class McplServerRegistry {
   private servers = new Map<string, McplServerConnection>();
+  private closing = new Map<McplServerConnection, Promise<void>>();
 
   /**
    * Connect to an MCPL server and register it.
@@ -70,8 +72,7 @@ export class McplServerRegistry {
     if (!connection) {
       return;
     }
-    this.servers.delete(id);
-    await connection.close();
+    await this.closeServer(id, connection);
   }
 
   /**
@@ -135,11 +136,27 @@ export class McplServerRegistry {
   }
 
   /**
-   * Close all server connections and clear the registry.
+   * Close all server connections, retaining failed or pending attempts.
+   * An explicit timeout bounds the caller's wait without cancelling cleanup.
    */
-  async closeAll(): Promise<void> {
-    const connections = Array.from(this.servers.values());
-    this.servers.clear();
-    await Promise.all(connections.map((c) => c.close()));
+  async closeAll(timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS): Promise<void> {
+    validateShutdownTimeout(timeoutMs);
+    await waitForShutdown(Array.from(this.servers, ([id, connection]) => ({
+      label: `mcpl:${id}`, promise: this.closeServer(id, connection),
+    })), timeoutMs);
+  }
+
+  private closeServer(id: string, connection: McplServerConnection): Promise<void> {
+    const existing = this.closing.get(connection);
+    if (existing) return existing;
+    const attempt = Promise.resolve().then(() => connection.close()).then(() => {
+      if (this.servers.get(id) === connection) this.servers.delete(id);
+      this.closing.delete(connection);
+    }, error => {
+      this.closing.delete(connection);
+      throw error;
+    });
+    this.closing.set(connection, attempt);
+    return attempt;
   }
 }

package/src/mcpl/tool-lifecycle.ts

@@ -50,8 +50,20 @@ export interface ToolLifecycleParams {
   inputWithheld?: boolean;
   isError?: boolean;
   durationMs?: number;
+  /**
+   * MCP's extension slot. Carries only SCRIPT_PARENT_META_KEY, on calls a
+   * code_execution script made: RFC-007 has no field for a call's origin,
+   * and the `mcpl/` prefix is reserved for keys MCPL defines (RFC-008 §3).
+   */
+  _meta?: Record<string, unknown>;
 }
 
+/**
+ * `_meta` key naming the `toolCallId` of the code_execution call whose script
+ * made this call. Host-specific: not defined by RFC-007.
+ */
+export const SCRIPT_PARENT_META_KEY = 'agent-framework/parentToolCallId';
+
 export interface ToolObserveMatch {
   tool?: string;
   serverTool?: string;
@@ -78,7 +90,8 @@ export interface ToolObserveRule {
  * RFC-007 §6.2 grammar.
  */
 export interface ToolLifecycleNarrowing {
-  /** Patterns over the model-facing tool name (`computer--*`). */
+  /** Patterns over the model-facing tool name (`computer--*`): for an MCPL
+   *  tool `<toolPrefix>--<tool>`, toolPrefix defaulting to `mcpl--<serverId>`. */
   tools?: string[];
   /** The tool's effective class must intersect this set. `'default'` is
    *  DEFAULT_INPUT_CLASSES (computer, shell, files, web, media, body). */
@@ -242,6 +255,8 @@ export interface ToolCallDescriptor {
   serverId?: string;
   serverTool?: string;
   input: unknown;
+  /** Script-inner calls: the code_execution call's `toolCallId`, when it had one. */
+  parentToolCallId?: string;
 }
 
 function anyGlob(patterns: readonly string[], subject: string): boolean {
@@ -466,6 +481,7 @@ function baseParams(call: ToolCallDescriptor, phase: ToolPhase): ToolLifecyclePa
     class: [...call.class],
     ...(call.serverId !== undefined ? { serverId: call.serverId, serverTool: call.serverTool } : {}),
     phase,
+    ...(call.parentToolCallId !== undefined ? { _meta: { [SCRIPT_PARENT_META_KEY]: call.parentToolCallId } } : {}),
   };
 }
 
@@ -537,10 +553,23 @@ export interface ToolLifecycleHost {
   describe(tool: string): { class: ToolClass[]; serverId?: string; serverTool?: string };
 }
 
+/**
+ * What a call made from inside a code_execution script inherits from the
+ * code_execution call that ran the script (scriptOrigin()).
+ */
+export interface ScriptCallOrigin {
+  /** The inference whose output requested the code_execution call. */
+  inferenceId: string;
+  /** That call's `toolCallId`. Absent when nothing observed it, so it has none. */
+  parentToolCallId?: string;
+}
+
 interface TrackedCall {
   agentName: string;
   modelCallId: string;
   call: ToolCallDescriptor;
+  /** Made by a code_execution script, not by the model (registerScriptCall). */
+  scriptInner: boolean;
   /** Connection id → transport epoch the opening went to. */
   openedTo: Map<string, number>;
   /** `started` has been sent (open() ran and the call was not refused). */
@@ -569,6 +598,9 @@ export class ToolLifecycleEmitter {
   private readonly recentIds = new Set<string>();
   private readonly recentOrder: string[] = [];
   private mintSeq = 0;
+  /** The call between register() and open(), kept even when nothing observes,
+   *  so a code_execution dispatch can learn its inference (scriptOrigin()). */
+  private dispatching: { agentName: string; callId: string; inferenceId: string } | null = null;
 
   constructor(host: ToolLifecycleHost, now: () => number = Date.now) {
     this.host = host;
@@ -608,6 +640,44 @@ export class ToolLifecycleEmitter {
    * host may still refuse it (refuse()) before it executes.
    */
   register(agentName: string, inferenceId: string, call: { id: string; name: string; input: unknown }): void {
+    this.dispatching = { agentName, callId: call.id, inferenceId };
+    this.track(agentName, inferenceId, call, false);
+  }
+
+  /**
+   * A call a code_execution script made, about to go through the same
+   * dispatch as a model call (then refuse() / open() / onResult() as for
+   * one). Its class, provider, grant narrowing and filter matching are the
+   * INNER tool's own; its inference is the one that issued the
+   * code_execution call. Unlike a model call it is not aborted when its
+   * stream ends: the tool keeps running after the turn or the script is
+   * gone, so its terminal is the result's, or `failed` when the host gives
+   * up waiting for one.
+   */
+  registerScriptCall(agentName: string, origin: ScriptCallOrigin, call: { id: string; name: string; input: unknown }): void {
+    this.track(agentName, origin.inferenceId, call, true, origin.parentToolCallId);
+  }
+
+  /**
+   * The origin a code_execution call passes to the calls its script makes.
+   * Valid only while that call is being dispatched (between register() and
+   * open()), which is where the framework asks.
+   */
+  scriptOrigin(agentName: string, callId: string): ScriptCallOrigin | undefined {
+    const tracked = this.calls.get(callKey(agentName, callId));
+    if (tracked) return { inferenceId: tracked.call.inferenceId, parentToolCallId: tracked.call.toolCallId };
+    const d = this.dispatching;
+    if (d && d.agentName === agentName && d.callId === callId) return { inferenceId: d.inferenceId };
+    return undefined;
+  }
+
+  private track(
+    agentName: string,
+    inferenceId: string,
+    call: { id: string; name: string; input: unknown },
+    scriptInner: boolean,
+    parentToolCallId?: string,
+  ): void {
     if (!this.anyObserver()) return;
     const described = this.host.describe(call.name);
     this.calls.set(callKey(agentName, call.id), {
@@ -623,7 +693,9 @@ export class ToolLifecycleEmitter {
           ? { serverId: described.serverId, serverTool: described.serverTool }
           : {}),
         input: call.input,
+        ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
       },
+      scriptInner,
       openedTo: new Map(),
       opened: false,
       // Taken before dispatch, so durationMs includes work a synchronous
@@ -652,6 +724,7 @@ export class ToolLifecycleEmitter {
    * run synchronously inside dispatch, before this.
    */
   open(agentName: string, callId: string): void {
+    this.dispatching = null;
     const key = callKey(agentName, callId);
     const tracked = this.calls.get(key);
     if (!tracked || tracked.opened) return;
@@ -725,12 +798,14 @@ export class ToolLifecycleEmitter {
    * A stream ended: its calls still open were cancelled before a result.
    * Scoped to the inference ids that stream minted, so a successor stream
    * for the same agent (a budget restart overlapping this one's teardown)
-   * keeps its live calls. A result arriving later finds nothing.
+   * keeps its live calls. A result arriving later finds nothing. Calls a
+   * script made are left open: they end with their own result.
    */
   abortOpen(agentName: string, inferenceIds: Iterable<string>): void {
     if (this.calls.size === 0) return;
     const ids = new Set(inferenceIds);
     for (const tracked of [...this.calls.values()]) {
+      if (tracked.scriptInner) continue;
       if (tracked.agentName === agentName && ids.has(tracked.call.inferenceId)) {
         if (tracked.opened) this.terminate(tracked, 'aborted');
         else this.calls.delete(callKey(tracked.agentName, tracked.modelCallId));

package/src/mcpl/tool-pattern-check.ts

@@ -0,0 +1,106 @@
+/**
+ * Zero-match diagnostics for operator tool-name patterns.
+ *
+ * `toolClassOverrides` keys and `toolLifecycle.{observe,inputs}.tools` are
+ * RFC-007 §6.2 patterns over the MODEL-FACING tool name. For an MCPL tool
+ * that is `<toolPrefix>--<tool>`, and `toolPrefix` defaults to
+ * `mcpl--<serverId>`. A pattern written against the bare server id
+ * (`search--*` for server `search` with no toolPrefix) is valid config that
+ * matches nothing, and nothing else reports it: the override classes no tool
+ * and the narrowing admits no call. This module decides, for one pattern and
+ * the current tool listing, whether that is the case and what was probably
+ * meant.
+ */
+
+import { globMatch } from './tool-glob.js';
+
+export interface PatternServer {
+  id: string;
+  /** Effective tool prefix: config `toolPrefix ?? mcpl--<id>`. */
+  prefix: string;
+  /** True when this server's tools are in the current listing. */
+  listed: boolean;
+}
+
+export type ToolPatternVerdict =
+  | { kind: 'matched' }
+  /** Could still match tools of servers whose listing is not in (yet). */
+  | { kind: 'pending'; servers: string[] }
+  | { kind: 'unmatched'; suggestion?: string; hint: string };
+
+/**
+ * Could `pattern` match some name under `<prefix>--`? Decided on the literal
+ * text before the first `*`; anything after it is not consulted, so this
+ * errs toward "could" (which only defers a warning, never invents one).
+ */
+export function couldMatchUnderPrefix(pattern: string, prefix: string): boolean {
+  const head = `${prefix}--`;
+  const star = pattern.indexOf('*');
+  if (star === -1) return pattern.startsWith(head);
+  const literal = pattern.slice(0, star);
+  return literal.startsWith(head) || head.startsWith(literal);
+}
+
+/**
+ * Check one pattern against the model-facing tool names offered right now.
+ *
+ * `pending` while a server whose tools the pattern could name has not
+ * listed them (not connected yet, reconnecting, or removed): its listing is
+ * the only evidence, and an early verdict would be a false alarm.
+ */
+export function checkToolPattern(
+  pattern: string,
+  toolNames: Iterable<string>,
+  servers: readonly PatternServer[],
+): ToolPatternVerdict {
+  const names = [...toolNames];
+  for (const name of names) {
+    if (globMatch(pattern, name)) return { kind: 'matched' };
+  }
+  const pending = servers.filter((s) => !s.listed && couldMatchUnderPrefix(pattern, s.prefix));
+  if (pending.length > 0) return { kind: 'pending', servers: [...new Set(pending.map((s) => s.id))] };
+
+  // Written against the wrong namespace for a known server: the bare id
+  // (`<id>--…`) where the effective prefix differs, or the default form
+  // (`mcpl--<id>--…`) for a server that set its own toolPrefix. Never when
+  // the namespace as written is real — another server's toolPrefix or a
+  // module's tools — since the pattern then names that, not a mistake.
+  const inRealNamespace = (ns: string) =>
+    servers.some((o) => o.prefix === ns) || names.some((n) => n.startsWith(`${ns}--`));
+  for (const s of servers) {
+    let rest: string | undefined;
+    if (s.prefix !== s.id && pattern.startsWith(`${s.id}--`) && !inRealNamespace(s.id)) {
+      rest = pattern.slice(s.id.length + 2);
+    } else if (
+      s.prefix !== `mcpl--${s.id}` && pattern.startsWith(`mcpl--${s.id}--`) && !inRealNamespace(`mcpl--${s.id}`)
+    ) {
+      rest = pattern.slice(s.id.length + 8);
+    }
+    if (rest === undefined) continue;
+    const why = s.prefix === `mcpl--${s.id}` ? ' (no toolPrefix set; the default is "mcpl--<serverId>")' : '';
+    return {
+      kind: 'unmatched',
+      suggestion: `${s.prefix}--${rest}`,
+      hint: `server "${s.id}" names its tools "${s.prefix}--<tool>"${why}`,
+    };
+  }
+
+  if (pattern.includes('--') && !servers.some((s) => couldMatchUnderPrefix(pattern, s.prefix))) {
+    return { kind: 'unmatched', hint: 'no connected MCPL server has a toolPrefix it could match' };
+  }
+  return { kind: 'unmatched', hint: 'no tool the framework offers has a matching name' };
+}
+
+/** The operator-facing line for an `unmatched` verdict. */
+export function describeUnmatchedPattern(
+  where: string,
+  pattern: string,
+  verdict: Extract<ToolPatternVerdict, { kind: 'unmatched' }>,
+): string {
+  const meant = verdict.suggestion ? ` — did you mean ${JSON.stringify(verdict.suggestion)}?` : '';
+  return (
+    `[mcpl] ${where} pattern ${JSON.stringify(pattern)} matches no tool${meant} ` +
+    `(${verdict.hint}). Patterns match the full model-facing tool name, ` +
+    `"<toolPrefix>--<tool>" for MCPL tools.`
+  );
+}

package/src/mcpl/types.ts

@@ -282,10 +282,16 @@ export interface McplServerConfig {
    */
   allowHostCommands?: boolean;
 
-  /** Feature sets to enable on connect */
+  /**
+   * Feature sets to enable on connect (`.`-segment wildcards). Omitted:
+   * every declared set is a candidate. `[]`: none. Either way a set is
+   * enabled only if its declared `uses` are recognized capabilities the
+   * grant covers (§6.4) — a set declaring no `uses` stays disabled even when
+   * listed here (logged, and traced as `mcpl:feature-set-disabled`).
+   */
   enabledFeatureSets?: string[];
 
-  /** Feature sets to explicitly disable on connect */
+  /** Feature sets to explicitly disable on connect (wins over enabledFeatureSets). */
   disabledFeatureSets?: string[];
 
   /**
@@ -388,11 +394,15 @@ export interface McplServerConfig {
 
   /**
    * Tool name prefix for this server's tools.
-   * Tools are exposed as `{toolPrefix}:{toolName}`.
+   * Tools are exposed as `{toolPrefix}--{toolName}`.
    *
-   * Default: `mcpl:{id}` (e.g., `mcpl:zk:lobby_start_game`).
+   * Default: `mcpl--{id}` (e.g., `mcpl--zk--lobby_start_game`).
    * Set to the server ID for cleaner names (e.g., `toolPrefix: 'zk'`
-   * gives `zk:lobby_start_game`).
+   * gives `zk--lobby_start_game`).
+   *
+   * Tool-name patterns elsewhere (`toolClassOverrides` keys,
+   * `toolLifecycle.*.tools`) match these full names; `enabledTools` /
+   * `disabledTools` use the bare server-side names.
    *
    * Must not collide with any module name or another server's prefix.
    */

package/src/mcpl/visible-content.ts

@@ -0,0 +1,57 @@
+/**
+ * Visibly-empty MCPL content, and the one empty push that is allowed.
+ *
+ * A push event or channel message whose content gives the model nothing to
+ * read cannot be shown: the request sanitizer strips empty text blocks and
+ * drops the message they leave empty, so a wake queued for it presents the
+ * model with `[Continue]` or with an older message re-presented as the newest.
+ * That is a wake with no visible cause, and it invites the model to invent
+ * one. Such content is rejected at the MCPL boundary, and the store/wake site
+ * drops it as a backstop.
+ *
+ * The exception is the silent-heartbeat marker: the heartbeat server's own
+ * scheduled tick, which wakes with ephemeral host-supplied context instead of
+ * a stored message.
+ */
+
+/**
+ * True when `content` holds nothing the model would see: no non-text block,
+ * and no text block whose text has a non-whitespace character. Mirrors the
+ * request sanitizer, which drops text that is not a string or trims to ''.
+ * Accepts MCPL wire blocks and converted membrane blocks alike.
+ */
+export function isVisiblyEmptyContent(content: readonly unknown[] | null | undefined): boolean {
+  if (!Array.isArray(content)) return true;
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as { type?: unknown; text?: unknown };
+    if (b.type !== 'text') return false;
+    if (typeof b.text === 'string' && b.text.trim() !== '') return false;
+  }
+  return true;
+}
+
+/** The server id and feature set the marker must carry. */
+export const SILENT_HEARTBEAT_SERVER_ID = 'heartbeat';
+export const SILENT_HEARTBEAT_FEATURE_SET = 'heartbeat';
+
+/**
+ * The exact silent-heartbeat marker: an empty push from the `heartbeat`
+ * server on its `heartbeat` feature set, with `origin.source === 'heartbeat'`
+ * and `origin.silent === true`. Anything else that is empty is not a silent
+ * tick — arbitrary servers cannot claim the silent path by setting
+ * `origin.silent`, and a marker that carries content is ordinary content.
+ */
+export function isSilentHeartbeatMarker(event: {
+  serverId: string;
+  featureSet?: string;
+  origin?: Record<string, unknown> | null;
+  content: readonly unknown[] | null | undefined;
+}): boolean {
+  return event.serverId === SILENT_HEARTBEAT_SERVER_ID
+    && event.featureSet === SILENT_HEARTBEAT_FEATURE_SET
+    && event.origin?.source === 'heartbeat'
+    && event.origin?.silent === true
+    && Array.isArray(event.content)
+    && event.content.length === 0;
+}