@animalabs/agent-framework 0.21.0 → 0.22.0

package/src/mcpl/push-coalescer.ts

@@ -18,6 +18,7 @@
  * bookkeeping and is unit-tested without a framework.
  */
 import type { McplContentBlock, PushEventResult } from './types.js';
+import { isVisiblyEmptyContent } from './visible-content.js';
 
 export const PUSH_COALESCING_SUPPORT = {
   pushEvents: true, channelsIncoming: true, deferred: true, channelScopedPush: true,
@@ -36,6 +37,15 @@ export class CoalesceError extends Error {
   }
 }
 
+/** Content with nothing model-visible (see visible-content.ts): -32602. */
+export class EmptyContentError extends CoalesceError {
+  readonly reason = 'empty-content';
+  constructor(field = 'payload.content') {
+    super(field, 'content has no visible content: send at least one non-text block or non-whitespace text');
+    this.name = 'EmptyContentError';
+  }
+}
+
 /** Where an unread occurrence currently lives. */
 export interface CoalescingPlacement {
   agent: string;
@@ -100,6 +110,18 @@ interface Rendering<E> {
   batch: DeferredBatch<E>;
   cancelled: boolean;
   done: Promise<void>;
+  /** Set once the render (or its fallback) was delivered as content. */
+  materialized?: boolean;
+}
+
+/** What an assembly did, per subject, for the turn being assembled. */
+export interface AssemblyResult {
+  /** Subjects whose render this assembly waited on to completion. */
+  settled: Set<string>;
+  /** Of those, the subjects whose render or fallback was delivered as content.
+   *  A settled subject that is not here gave the turn nothing to read: empty
+   *  or blank render (§5.2), cancelled, or revoked at response. */
+  materialized: Set<string>;
 }
 
 interface SubjectState<E> {
@@ -207,8 +229,20 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
   return out;
 }
 
-/** Validate wire content before it is stored, rendered or converted. */
-export function validateCoalescedContent(content: unknown, maxBytes = 1024 * 1024): asserts content is McplContentBlock[] {
+/**
+ * Validate wire content before it is stored, rendered or converted.
+ *
+ * Visibly-empty content is refused unless `allowEmpty`: an admitted
+ * occurrence with nothing to show would wake the model with no visible cause.
+ * Empty is legitimate only where the RFC gives it a meaning — a retraction
+ * with nothing to announce (§6) and a render result that says nothing
+ * happened (§5.2) — and for the silent-heartbeat marker.
+ */
+export function validateCoalescedContent(
+  content: unknown,
+  maxBytes = 1024 * 1024,
+  options: { allowEmpty?: boolean } = {},
+): asserts content is McplContentBlock[] {
   if (!Array.isArray(content)) throw new CoalesceError('payload.content', 'content must be an array');
   for (const b of content as Array<Record<string, unknown>>) {
     if (!b || typeof b !== 'object' || Array.isArray(b)) throw new CoalesceError('payload.content', 'invalid content block');
@@ -219,6 +253,7 @@ export function validateCoalescedContent(content: unknown, maxBytes = 1024 * 102
     throw new CoalesceError('payload.content', 'invalid content block');
   }
   if (Buffer.byteLength(JSON.stringify(content)) > maxBytes) throw new CoalesceError('payload.content', 'content exceeds host byte limit');
+  if (!options.allowEmpty && isVisiblyEmptyContent(content)) throw new EmptyContentError();
 }
 
 /** Validate the `coalesce` member of either lane (§13). */
@@ -486,7 +521,9 @@ export class PushCoalescer<E = unknown> {
     this.host.cancelWake(subject);
     state.consumedEventId = undefined;
     if (state.history === 'none') return 'retracted';
-    if (!occurrence.content.length) return 'consumed';
+    // An empty notice — or one with only blank text, which would reach the
+    // model as an empty message — is pure withdrawal: append nothing.
+    if (isVisiblyEmptyContent(occurrence.content)) return 'consumed';
     // The notice is an ordinary occurrence: it rides the normal delivery path
     // (tags → gate policy → wake) and is consumed like any message — in the
     // context that read a version, never a new one (§3.2).
@@ -563,20 +600,29 @@ export class PushCoalescer<E = unknown> {
    * Render and materialize every pending batch whose audience includes
    * `agentName`. Called by the host at a turn's assembly boundary, before the
    * compile. Bounded by the host's render timeout; a failed or late render
-   * materializes the admitted fallback (§5.3).
+   * materializes the admitted fallback (§5.3). Reports which subjects
+   * settled and which of them produced content, so the host can tell a turn
+   * whose only cause rendered nothing.
    */
-  async assemble(agentName: string): Promise<void> {
-    if (this.suspended) return;
+  async assemble(agentName: string): Promise<AssemblyResult> {
+    const result: AssemblyResult = { settled: new Set(), materialized: new Set() };
+    if (this.suspended) return result;
     const work: Promise<void>[] = [];
     for (const subject of [...this.subjects.keys()]) {
       // The handle is wrapped: a bare promise returned through `locked` would
       // be flattened by `then`, holding the lock until the render settled —
       // and the settlement itself needs the lock.
       const started = await this.locked(() => this.freeze(subject, agentName));
-      if (started) work.push(started.done);
+      if (started) {
+        work.push(started.done.then(() => {
+          result.settled.add(subject);
+          if (started.rendering.materialized) result.materialized.add(subject);
+        }));
+      }
     }
     await Promise.all(work);
     this.persist();
+    return result;
   }
 
   /**
@@ -585,13 +631,13 @@ export class PushCoalescer<E = unknown> {
    * the RPC. Returns the render's completion (shared by every assembly that
    * waits on this batch, vector 25) or undefined when nothing was started.
    */
-  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void> } | undefined> {
+  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void>; rendering: Rendering<E> } | undefined> {
     const state = this.subjects.get(subject);
     if (!state || this.suspended) return undefined;
     if (state.rendering) {
       // Another assembly froze this batch; share its outcome (vector 25).
       const rendering = state.rendering;
-      return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done } : undefined;
+      return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done, rendering } : undefined;
     }
     const batch = state.batch;
     if (!batch) return undefined;
@@ -634,7 +680,7 @@ export class PushCoalescer<E = unknown> {
       return undefined;
     }
     rendering.done = this.render(subject, state, rendering, agentName);
-    return { done: rendering.done };
+    return { done: rendering.done, rendering };
   }
 
   private async render(subject: string, state: SubjectState<E>, rendering: Rendering<E>, assemblingFor: string): Promise<void> {
@@ -654,7 +700,8 @@ export class PushCoalescer<E = unknown> {
       try {
         const result = await this.host.render(occurrence, params);
         if (rendering.cancelled) { this.host.audit({ kind: 'late-render', subject, eventId: occurrence.eventId, discarded: true }); }
-        else validateCoalescedContent(result?.content, this.options.maxContentBytes);
+        // §5.2: an empty result is legitimate ("nothing happened").
+        else validateCoalescedContent(result?.content, this.options.maxContentBytes, { allowEmpty: true });
         if (rendering.cancelled) throw new CancelledRender();
         content = result.content;
         timestamp = typeof result.timestamp === 'string' ? result.timestamp : new Date().toISOString();
@@ -673,9 +720,11 @@ export class PushCoalescer<E = unknown> {
         if (rendering.cancelled || state.rendering !== rendering || this.suspended) return;
         // Rule 4: authority is re-checked at response.
         if (!this.host.authorized(occurrence)) { this.host.audit({ kind: 'revoked', subject, eventId: occurrence.eventId }); return; }
-        this.host.audit({ kind: 'rendered', subject, eventId: occurrence.eventId, source, empty: content.length === 0 });
-        if (!content.length) return; // §5.2: nothing happened
+        const empty = isVisiblyEmptyContent(content);
+        this.host.audit({ kind: 'rendered', subject, eventId: occurrence.eventId, source, empty });
+        if (empty) return; // §5.2: nothing happened (blank text included)
         const placement = await this.host.deliver({ ...occurrence, timestamp, content }, content, assemblingFor);
+        rendering.materialized = true;
         if (placement?.deferredId) {
           // Landed in another agent's deferred queue (its turn is alive): still
           // unread there, so it stays replaceable and withdrawable.

package/src/mcpl/push-handler.ts

@@ -18,7 +18,8 @@ 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';
+import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { isSilentHeartbeatMarker, isVisiblyEmptyContent } from './visible-content.js';
 
 // ============================================================================
 // McplPushEvent (the ProcessEvent shape pushed to the queue)
@@ -188,9 +189,9 @@ export class PushHandler {
    * Handle a push/event message from an MCPL server.
    *
    * 1. Validate feature set
-   * 2. Deduplicate by eventId
-   * 3. Optionally check shouldTriggerInference callback
-   * 4. Convert content blocks
+   * 2. Convert content blocks; reject visibly-empty content
+   * 3. Deduplicate by eventId
+   * 4. Optionally check shouldTriggerInference callback
    * 5. Push event to queue
    * 6. Emit trace
    * 7. Respond with accepted + inferenceId
@@ -229,30 +230,46 @@ export class PushHandler {
       return;
     }
 
-    // 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;
+    // Empty content is meaningful only for a coalescing retraction (pure
+    // withdrawal, RFC-006 §6 — the coalescer appends nothing for it) and for
+    // the silent-heartbeat marker. Anything else that shows the model nothing
+    // would wake it with no visible cause.
+    const emptyAllowed = (coalesced && params.coalesce?.retract === true)
+      || isSilentHeartbeatMarker({ serverId, featureSet: params.featureSet, origin: params.origin, content: params.payload?.content });
     if (coalesced) {
       // RFC-006 §13: malformed content is a -32602, checked before conversion.
       try {
-        validateCoalescedContent(params.payload?.content);
+        validateCoalescedContent(params.payload?.content, undefined, { allowEmpty: emptyAllowed });
       } catch (error) {
         const err = error as Error & { code?: number; field?: string };
+        if (err instanceof EmptyContentError) this.traceEmptyRejection(serverId, params);
         if (responder?.respondError) responder.respondError(err.code ?? -32602, err.message, { field: err.field });
-        else responder?.respond({ accepted: false, reason: err.message });
+        else responder?.respond({ accepted: false, reason: err instanceof EmptyContentError ? err.reason : err.message });
         return;
       }
     }
+
+    // 2. Convert content blocks, and refuse content with nothing visible in
+    // it — before dedup, so a refused eventId is not burned for a retry.
+    const content: ContentBlock[] = params.payload.content.map(convertBlock);
+    if (!emptyAllowed && isVisiblyEmptyContent(content)) {
+      const err = new EmptyContentError();
+      this.traceEmptyRejection(serverId, params);
+      if (responder?.respondError) responder.respondError(err.code, err.message, { field: err.field });
+      else responder?.respond({ accepted: false, reason: err.reason });
+      return;
+    }
+
+    // 3. 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).
     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;
     }
 
-    // 3. Convert content blocks
-    const content: ContentBlock[] = params.payload.content.map(convertBlock);
-
     // 4. Check shouldTriggerInference callback
     let triggerInference = true;
     if (this.shouldTriggerInference) {
@@ -316,4 +333,16 @@ export class PushHandler {
     // 8. Respond
     responder?.respond({ accepted: true, inferenceId });
   }
+
+  /** Loud, like every other push rejection: the producer's wake went nowhere. */
+  private traceEmptyRejection(serverId: string, params: PushEventParams): void {
+    console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=empty-content`);
+    this.emitTraceFn({
+      type: 'mcpl:push-event-rejected',
+      serverId,
+      eventId: params.eventId,
+      featureSet: params.featureSet,
+      reason: 'empty-content',
+    });
+  }
 }

package/src/mcpl/server-connection.ts

@@ -209,6 +209,9 @@ export class McplServerConnection extends EventEmitter {
    * observable even though its original promise has already been rejected. */
   private orphanedRequests = new Map<string | number, { method: string; renderParams?: Record<string, unknown> }>();
   private closed = false;
+  private closePromise: Promise<void> | null = null;
+  private closeIncomplete = false;
+  private reconnectPromise: Promise<void> | null = null;
 
   /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
   private requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
@@ -837,10 +840,10 @@ export class McplServerConnection extends EventEmitter {
       this.reconnectTimer = null;
     }
 
-    if (this.closed) {
-      return;
-    }
+    if (this.closePromise) return this.closePromise;
+    if (this.closed && !this.closeIncomplete && !this.reconnectPromise) return;
     this.closed = true;
+    this.closeIncomplete = true;
     this.resetPolicyForTransportBoundary();
 
     // Reject all pending requests
@@ -854,11 +857,20 @@ export class McplServerConnection extends EventEmitter {
     // Tear down the transport (kills the child / closes the socket). The
     // transport's own 'close' event is short-circuited by `this.closed` in
     // setupLifecycle, so this is the single source of the connection 'close'.
-    if (this.transport) {
-      await this.transport.close();
-    }
-
-    this.emit('close');
+    const attempt = Promise.resolve().then(async () => {
+      // An already opened handshake owns a transport too. It hands that
+      // transport back without admission once reconnect has been disabled.
+      // The registry bounds this wait; retry reuses this real close attempt.
+      if (this.reconnectPromise) await this.reconnectPromise;
+      if (this.transport) await this.transport.close();
+      this.closeIncomplete = false;
+      this.emit('close');
+    });
+    this.closePromise = attempt;
+    void attempt.catch(() => {
+      if (this.closePromise === attempt) this.closePromise = null;
+    });
+    return attempt;
   }
 
   /**
@@ -912,8 +924,19 @@ export class McplServerConnection extends EventEmitter {
    * approach this builds no throwaway connection instance, so there are no
    * leaked listeners on a dead object.
    */
-  private async attemptReconnect(): Promise<void> {
-    if (!this.reconnectEnabled || !this.config || !this.hostCapabilities) return;
+  private attemptReconnect(): Promise<void> {
+    if (this.reconnectPromise) return this.reconnectPromise;
+    const attempt = this.reconnectOnce();
+    this.reconnectPromise = attempt;
+    const clear = () => { if (this.reconnectPromise === attempt) this.reconnectPromise = null; };
+    void attempt.then(clear, clear);
+    return attempt;
+  }
+
+  private async reconnectOnce(): Promise<void> {
+    // A queued recovery timer may outlive an earlier successful handshake.
+    // Recheck disconnection before opening or replacing any owned transport.
+    if (!this.closed || !this.reconnectEnabled || !this.config || !this.hostCapabilities) return;
 
     // Ordinal of this attempt: 0 was the initial connect, so the Nth retry
     // reports attempt N (reconnectAttempts counts failures so far).
@@ -925,6 +948,14 @@ export class McplServerConnection extends EventEmitter {
         this.hostCapabilities,
       );
 
+      if (!this.reconnectEnabled) {
+        // The prior transport was disconnected before this retry began. Keep
+        // the fresh, unadmitted transport owned by close(), including on a
+        // failed transport cleanup, instead of reviving a stopped connection.
+        this.transport = transport;
+        return;
+      }
+
       // Close the data plane before the new transport can emit. The reconnect
       // lifecycle event bypasses buffering; its framework listener installs the
       // awareness barrier synchronously, then releases control traffic needed

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.`
+  );
+}