@animalabs/agent-framework 0.21.1 → 0.22.1

package/src/types/module.ts

@@ -109,6 +109,21 @@ export interface Module {
    */
   gatherContext?(agentName: string): Promise<ContextInjection[]>;
 
+  /**
+   * Called once an agent's tool batch has completed — when the round's last
+   * pending result arrives, before it is provided to the agent and before
+   * anything that continues the turn (re-inference, stream resume). The
+   * framework awaits it, bounded at 30 s and fail-open, so a module can
+   * bring its state up to date with what the batch's tools did (the
+   * workspace's `watch: 'on-agent-action'` mounts scan disk here) before the
+   * agent's next inference. It's awaited in the framework's event loop, so
+   * a slow hook holds every agent's event processing, not only this one's.
+   * A hook still running from an earlier batch is skipped, not called again.
+   * Not called for script-inner tool calls, nor when the framework fills in
+   * error results for a batch whose stream ended before its tools answered.
+   */
+  onToolBatchComplete?(agentName: string): Promise<void>;
+
   /**
    * Declare extra settings for the synthesized `agent_settings` tool.
    * Modules owning hot-tunable runtime state (e.g. a host settings module
@@ -202,14 +217,19 @@ export interface ModuleContext {
   getLogLength(name: string): number;
 
   /**
-   * Process queue for pushing events from external listeners.
+   * Process queue for pushing events from external listeners. Once stop()
+   * has begun, a push is dropped with a log line naming this module, as
+   * pushEvent()'s is.
    * @deprecated Use pushEvent() instead — it also emits process:received traces.
    */
   readonly queue: ProcessQueue;
 
   /**
    * Push a process event to the queue and emit a process:received trace.
-   * Preferred over direct queue.push() for proper observability.
+   * Preferred over direct queue.push() for proper observability. Once stop()
+   * has begun, nothing will process the event: it's dropped with a log line
+   * naming this module, untraced, rather than thrown into the listener or
+   * stop() that pushed it.
    */
   pushEvent(event: ProcessEvent): void;
 
@@ -355,14 +375,17 @@ export interface ProcessState {
   getActiveTools(): ToolDefinition[];
 
   /**
-   * Queue for emitting follow-up events.
+   * Queue for emitting follow-up events. Once stop() has begun, a push is
+   * dropped with a log line naming the module, as pushEvent()'s is.
    * @deprecated Use pushEvent() instead — it also emits process:received traces.
    */
   readonly queue: ProcessQueue;
 
   /**
    * Push a process event to the queue and emit a process:received trace.
-   * Preferred over direct queue.push() for proper observability.
+   * Preferred over direct queue.push() for proper observability. Once stop()
+   * has begun, the event is dropped with a log line naming the module,
+   * untraced.
    */
   pushEvent(event: ProcessEvent): void;
 }

package/src/types/trace.ts

@@ -66,20 +66,29 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'inference:failed';
       agentName: string;
+      /** The failure's message, bounded as every trace event's `error` is (2,000 characters). */
       error: string;
+      /** Bounded like `error`. */
       stack?: string;
     })
   | (TraceEventBase & {
       type: 'inference:exhausted';
       agentName: string;
+      /** The failure's message, bounded as every trace event's `error` is (2,000 characters). */
       error: string;
       /** Whether membrane classified the failure as retryable (observability). */
       retryable?: boolean;
       /**
-       * The membrane error type (e.g. 'invalid_request', 'auth', 'context_length').
-       * The poison-history breaker fires only on 'invalid_request'.
+       * The membrane error type (e.g. 'invalid_request', 'auth', 'context_length'),
+       * at most 128 characters. The poison-history breaker fires only on
+       * 'invalid_request' at HTTP 400, 413 or 422 or with no status, and on
+       * 'context_length' at 413 (shedMayHelp).
        */
       errorType?: string;
+      /** The provider's HTTP status, when the failure carried one. */
+      httpStatus?: number;
+      /** The provider's own error code, when it sent one (at most 128 characters). */
+      providerErrorCode?: string;
     })
 
   // Streaming inference lifecycle
@@ -171,6 +180,16 @@ export type TraceEvent =
       agentStatus: string;
       result: unknown;
     })
+  | (TraceEventBase & {
+      /**
+       * A module's onToolBatchComplete threw or outlasted its bound; the
+       * round went on without it.
+       */
+      type: 'module:batch_hook_failed';
+      agentName: string;
+      module: string;
+      error: string;
+    })
   | (TraceEventBase & {
       /**
        * A writable workspace existed but the oversized-result spill write
@@ -217,6 +236,33 @@ export type TraceEvent =
       messageId: string;
       source: string;
     })
+  /** A push/event refused at the MCPL boundary (today: visibly-empty content). */
+  | (TraceEventBase & {
+      type: 'mcpl:push-event-rejected';
+      serverId: string;
+      eventId: string;
+      featureSet: string;
+      reason: string;
+    })
+  /** A channels/incoming message refused at the MCPL boundary: unregistered
+   *  channel (§14.5), or visibly-empty content (then `messageId` is set). */
+  | (TraceEventBase & {
+      type: 'mcpl:channel-incoming-rejected';
+      serverId: string;
+      channelId: string;
+      messageId?: string;
+      reason: string;
+    })
+  /** MCPL content with nothing model-visible reached the store/wake site
+   *  (module-emitted or coalescer-delivered) and was dropped: no row, no wake. */
+  | (TraceEventBase & {
+      type: 'mcpl:empty-content-dropped';
+      lane: 'push' | 'channel';
+      serverId: string;
+      eventId?: string;
+      channelId?: string;
+      messageId?: string;
+    })
   /** RFC-006 coalescing decision record (received / displaced / removed /
    *  rendered / revoked / render-cancelled / late-render / render-failed). */
   | (TraceEventBase & {
@@ -430,6 +476,49 @@ export type TraceEvent =
       serverId: string;
       error: string;
     })
+  // Configuration that is accepted but silently does nothing. Each mirrors
+  // a console line, so hosts that keep per-server logs from the trace bus
+  // see it too.
+  | (TraceEventBase & {
+      /** §5.3/§6.7: the server refused the host's policy Request. */
+      type: 'mcpl:policy-refused';
+      serverId: string;
+      /** The initial policy at connect, or the re-negotiation after a manifest change. */
+      phase: 'initial' | 'manifest-change';
+      reason: string | null;
+      /** `close`: the host closed the connection. `mcp-only`: the grant
+       *  stays empty and only plain MCP tools work. */
+      fallback: 'close' | 'mcp-only';
+    })
+  | (TraceEventBase & {
+      /** §6.4 derivation disabled a declared feature set. */
+      type: 'mcpl:feature-set-disabled';
+      serverId: string;
+      featureSet: string;
+      /** `invalid_uses`: `uses` absent, empty or unrecognized.
+       *  `missing_capabilities`: `uses` names capabilities the grant lacks. */
+      reason: 'invalid_uses' | 'missing_capabilities';
+      /** True when config selected the set (enabledFeatureSets omitted or
+       *  matching it, and not disabledFeatureSets): derivation overrode it. */
+      selectedByConfig: boolean;
+      /** invalid_uses: the unrecognized entries (empty when `uses` was absent or empty). */
+      unrecognized?: string[];
+      /** missing_capabilities: the capability paths the grant lacks. */
+      missing?: string[];
+    })
+  | (TraceEventBase & {
+      /** An operator tool-name pattern matches no model-facing tool. Emitted
+       *  once per pattern, after the servers it could name have listed. */
+      type: 'mcpl:tool-pattern-unmatched';
+      /** `toolClassOverrides`, `toolLifecycle.observe.tools` or `toolLifecycle.inputs.tools`. */
+      setting: string;
+      /** The server whose toolLifecycle config holds the pattern. */
+      serverId?: string;
+      pattern: string;
+      /** The pattern rewritten under the server's actual tool prefix. */
+      suggestion?: string;
+      hint: string;
+    })
   | (TraceEventBase & {
       type: 'mcpl:orphaned-response';
       serverId: string;
@@ -454,8 +543,10 @@ export type TraceEvent =
       kind: string;
       /** Agent name, or a server/component id for non-agent alerts (e.g. mcpl-down). */
       agentName: string;
+      /** At most 2,000 characters. */
       message: string;
-      /** Kind-specific structured payload (mirrors the failures.log record). */
+      /** Kind-specific structured payload (mirrors the failures.log record),
+       *  bounded field by field as that record is. */
       data?: Record<string, unknown>;
     })