@robota-sdk/agent-core 3.0.0-beta.1

package/dist/plugins/event-emitter/types.d.ts

@@ -0,0 +1,112 @@
+declare const EXECUTION_EVENT_NAMES: {
+    readonly START: "execution.start";
+    readonly COMPLETE: "execution.complete";
+    readonly ERROR: "execution.error";
+};
+declare const TOOL_EVENT_NAMES: {
+    readonly CALL_START: "tool.call_start";
+    readonly CALL_COMPLETE: "tool.call_complete";
+    readonly CALL_ERROR: "tool.call_error";
+};
+declare const AGENT_EVENT_NAMES: {
+    readonly EXECUTION_START: "agent.execution_start";
+    readonly EXECUTION_COMPLETE: "agent.execution_complete";
+    readonly EXECUTION_ERROR: "agent.execution_error";
+    readonly CREATED: "agent.created";
+};
+type TExecutionEventName = typeof EXECUTION_EVENT_NAMES[keyof typeof EXECUTION_EVENT_NAMES];
+type TToolEventName = typeof TOOL_EVENT_NAMES[keyof typeof TOOL_EVENT_NAMES];
+type TAgentEventName = typeof AGENT_EVENT_NAMES[keyof typeof AGENT_EVENT_NAMES];
+/**
+ * Event types that can be emitted.
+ *
+ * IMPORTANT:
+ * - Do not use string literals for event names outside this module.
+ * - Import and use EVENT_EMITTER_EVENTS instead.
+ */
+export declare const EVENT_EMITTER_EVENTS: {
+    readonly EXECUTION_START: "execution.start";
+    readonly EXECUTION_COMPLETE: "execution.complete";
+    readonly EXECUTION_ERROR: "execution.error";
+    readonly TOOL_BEFORE_EXECUTE: "tool.beforeExecute";
+    readonly TOOL_AFTER_EXECUTE: "tool.afterExecute";
+    readonly TOOL_SUCCESS: "tool.success";
+    readonly TOOL_ERROR: "tool.call_error";
+    readonly CONVERSATION_START: "conversation.start";
+    readonly CONVERSATION_COMPLETE: "conversation.complete";
+    readonly CONVERSATION_ERROR: "conversation.error";
+    readonly AGENT_EXECUTION_START: "agent.execution_start";
+    readonly AGENT_EXECUTION_COMPLETE: "agent.execution_complete";
+    readonly AGENT_EXECUTION_ERROR: "agent.execution_error";
+    readonly AGENT_CREATED: "agent.created";
+    readonly AGENT_DESTROYED: "agent.destroyed";
+    readonly PLUGIN_LOADED: "plugin.loaded";
+    readonly PLUGIN_UNLOADED: "plugin.unloaded";
+    readonly PLUGIN_ERROR: "plugin.error";
+    readonly ERROR_OCCURRED: "error.occurred";
+    readonly WARNING_OCCURRED: "warning.occurred";
+    readonly MODULE_INITIALIZE_START: "module.initialize.start";
+    readonly MODULE_INITIALIZE_COMPLETE: "module.initialize.complete";
+    readonly MODULE_INITIALIZE_ERROR: "module.initialize.error";
+    readonly MODULE_EXECUTION_START: "module.execution.start";
+    readonly MODULE_EXECUTION_COMPLETE: "module.execution.complete";
+    readonly MODULE_EXECUTION_ERROR: "module.execution.error";
+    readonly MODULE_DISPOSE_START: "module.dispose.start";
+    readonly MODULE_DISPOSE_COMPLETE: "module.dispose.complete";
+    readonly MODULE_DISPOSE_ERROR: "module.dispose.error";
+    readonly MODULE_REGISTERED: "module.registered";
+    readonly MODULE_UNREGISTERED: "module.unregistered";
+    readonly EXECUTION_HIERARCHY: "execution.hierarchy";
+    readonly EXECUTION_REALTIME: "execution.realtime";
+    readonly TOOL_REALTIME: "tool.realtime";
+    readonly CUSTOM: "custom";
+};
+export type TEventName = TExecutionEventName | TToolEventName | TAgentEventName | 'tool.beforeExecute' | 'tool.afterExecute' | 'tool.success' | 'conversation.start' | 'conversation.complete' | 'conversation.error' | 'agent.destroyed' | 'plugin.loaded' | 'plugin.unloaded' | 'plugin.error' | 'error.occurred' | 'warning.occurred' | 'module.initialize.start' | 'module.initialize.complete' | 'module.initialize.error' | 'module.execution.start' | 'module.execution.complete' | 'module.execution.error' | 'module.dispose.start' | 'module.dispose.complete' | 'module.dispose.error' | 'module.registered' | 'module.unregistered' | 'execution.hierarchy' | 'execution.realtime' | 'tool.realtime' | 'custom';
+/**
+ * Valid event data value types
+ */
+export type TEventDataValue = string | number | boolean | Date | null | undefined | TEventDataValue[] | {
+    [key: string]: TEventDataValue;
+};
+/**
+ * Event data structure
+ */
+export interface IEventEmitterEventData {
+    type: TEventName;
+    timestamp: Date;
+    executionId?: string;
+    sessionId?: string;
+    userId?: string;
+    data?: Record<string, TEventDataValue>;
+    error?: Error;
+    metadata?: Record<string, TEventDataValue>;
+}
+/**
+ * Event listener function
+ */
+export type TEventEmitterListener = (event: IEventEmitterEventData) => void | Promise<void>;
+/**
+ * Console-like interface for the EventEmitterPlugin.
+ *
+ * Use this interface for typing instead of the concrete EventEmitterPlugin class.
+ */
+export interface IEventEmitterPlugin {
+    on(eventType: TEventName, listener: TEventEmitterListener, options?: {
+        once?: boolean;
+        filter?: (event: IEventEmitterEventData) => boolean;
+    }): string;
+    once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
+    off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
+    emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
+}
+/**
+ * Event handler with metadata
+ */
+export interface IEventEmitterHandler {
+    id: string;
+    listener: TEventEmitterListener;
+    once: boolean;
+    filter?: (event: IEventEmitterEventData) => boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/event-emitter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/plugins/event-emitter/types.ts"],"names":[],"mappings":"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"}

package/dist/plugins/event-emitter/types.js

@@ -0,0 +1,65 @@
+import { AGENT_EVENTS, AGENT_EVENT_PREFIX } from '../../agents/constants';
+import { EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX } from '../../services/execution-service';
+import { TOOL_EVENTS, TOOL_EVENT_PREFIX } from '../../services/tool-execution-service';
+const buildEventName = (prefix, localName) => `${prefix}.${localName}`;
+const EXECUTION_EVENT_NAMES = {
+    START: buildEventName(EXECUTION_EVENT_PREFIX, EXECUTION_EVENTS.START),
+    COMPLETE: buildEventName(EXECUTION_EVENT_PREFIX, EXECUTION_EVENTS.COMPLETE),
+    ERROR: buildEventName(EXECUTION_EVENT_PREFIX, EXECUTION_EVENTS.ERROR)
+};
+const TOOL_EVENT_NAMES = {
+    CALL_START: buildEventName(TOOL_EVENT_PREFIX, TOOL_EVENTS.CALL_START),
+    CALL_COMPLETE: buildEventName(TOOL_EVENT_PREFIX, TOOL_EVENTS.CALL_COMPLETE),
+    CALL_ERROR: buildEventName(TOOL_EVENT_PREFIX, TOOL_EVENTS.CALL_ERROR)
+};
+const AGENT_EVENT_NAMES = {
+    EXECUTION_START: buildEventName(AGENT_EVENT_PREFIX, AGENT_EVENTS.EXECUTION_START),
+    EXECUTION_COMPLETE: buildEventName(AGENT_EVENT_PREFIX, AGENT_EVENTS.EXECUTION_COMPLETE),
+    EXECUTION_ERROR: buildEventName(AGENT_EVENT_PREFIX, AGENT_EVENTS.EXECUTION_ERROR),
+    CREATED: buildEventName(AGENT_EVENT_PREFIX, AGENT_EVENTS.CREATED)
+};
+/**
+ * Event types that can be emitted.
+ *
+ * IMPORTANT:
+ * - Do not use string literals for event names outside this module.
+ * - Import and use EVENT_EMITTER_EVENTS instead.
+ */
+export const EVENT_EMITTER_EVENTS = {
+    EXECUTION_START: EXECUTION_EVENT_NAMES.START,
+    EXECUTION_COMPLETE: EXECUTION_EVENT_NAMES.COMPLETE,
+    EXECUTION_ERROR: EXECUTION_EVENT_NAMES.ERROR,
+    TOOL_BEFORE_EXECUTE: 'tool.beforeExecute',
+    TOOL_AFTER_EXECUTE: 'tool.afterExecute',
+    TOOL_SUCCESS: 'tool.success',
+    TOOL_ERROR: TOOL_EVENT_NAMES.CALL_ERROR,
+    CONVERSATION_START: 'conversation.start',
+    CONVERSATION_COMPLETE: 'conversation.complete',
+    CONVERSATION_ERROR: 'conversation.error',
+    AGENT_EXECUTION_START: AGENT_EVENT_NAMES.EXECUTION_START,
+    AGENT_EXECUTION_COMPLETE: AGENT_EVENT_NAMES.EXECUTION_COMPLETE,
+    AGENT_EXECUTION_ERROR: AGENT_EVENT_NAMES.EXECUTION_ERROR,
+    AGENT_CREATED: AGENT_EVENT_NAMES.CREATED,
+    AGENT_DESTROYED: 'agent.destroyed',
+    PLUGIN_LOADED: 'plugin.loaded',
+    PLUGIN_UNLOADED: 'plugin.unloaded',
+    PLUGIN_ERROR: 'plugin.error',
+    ERROR_OCCURRED: 'error.occurred',
+    WARNING_OCCURRED: 'warning.occurred',
+    MODULE_INITIALIZE_START: 'module.initialize.start',
+    MODULE_INITIALIZE_COMPLETE: 'module.initialize.complete',
+    MODULE_INITIALIZE_ERROR: 'module.initialize.error',
+    MODULE_EXECUTION_START: 'module.execution.start',
+    MODULE_EXECUTION_COMPLETE: 'module.execution.complete',
+    MODULE_EXECUTION_ERROR: 'module.execution.error',
+    MODULE_DISPOSE_START: 'module.dispose.start',
+    MODULE_DISPOSE_COMPLETE: 'module.dispose.complete',
+    MODULE_DISPOSE_ERROR: 'module.dispose.error',
+    MODULE_REGISTERED: 'module.registered',
+    MODULE_UNREGISTERED: 'module.unregistered',
+    EXECUTION_HIERARCHY: 'execution.hierarchy',
+    EXECUTION_REALTIME: 'execution.realtime',
+    TOOL_REALTIME: 'tool.realtime',
+    CUSTOM: 'custom'
+};
+//# sourceMappingURL=types.js.map

package/dist/plugins/event-emitter/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/plugins/event-emitter/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAEvF,MAAM,cAAc,GAAG,CACnB,MAAe,EACf,SAAiB,EACK,EAAE,CAAC,GAAG,MAAM,IAAI,SAAS,EAAE,CAAC;AAEtD,MAAM,qBAAqB,GAAG;IAC1B,KAAK,EAAE,cAAc,CAAC,sBAAsB,EAAE,gBAAgB,CAAC,KAAK,CAAC;IACrE,QAAQ,EAAE,cAAc,CAAC,sBAAsB,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAC3E,KAAK,EAAE,cAAc,CAAC,sBAAsB,EAAE,gBAAgB,CAAC,KAAK,CAAC;CAC/D,CAAC;AAEX,MAAM,gBAAgB,GAAG;IACrB,UAAU,EAAE,cAAc,CAAC,iBAAiB,EAAE,WAAW,CAAC,UAAU,CAAC;IACrE,aAAa,EAAE,cAAc,CAAC,iBAAiB,EAAE,WAAW,CAAC,aAAa,CAAC;IAC3E,UAAU,EAAE,cAAc,CAAC,iBAAiB,EAAE,WAAW,CAAC,UAAU,CAAC;CAC/D,CAAC;AAEX,MAAM,iBAAiB,GAAG;IACtB,eAAe,EAAE,cAAc,CAAC,kBAAkB,EAAE,YAAY,CAAC,eAAe,CAAC;IACjF,kBAAkB,EAAE,cAAc,CAAC,kBAAkB,EAAE,YAAY,CAAC,kBAAkB,CAAC;IACvF,eAAe,EAAE,cAAc,CAAC,kBAAkB,EAAE,YAAY,CAAC,eAAe,CAAC;IACjF,OAAO,EAAE,cAAc,CAAC,kBAAkB,EAAE,YAAY,CAAC,OAAO,CAAC;CAC3D,CAAC;AAMX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,eAAe,EAAE,qBAAqB,CAAC,KAAK;IAC5C,kBAAkB,EAAE,qBAAqB,CAAC,QAAQ;IAClD,eAAe,EAAE,qBAAqB,CAAC,KAAK;IAC5C,mBAAmB,EAAE,oBAAoB;IACzC,kBAAkB,EAAE,mBAAmB;IACvC,YAAY,EAAE,cAAc;IAC5B,UAAU,EAAE,gBAAgB,CAAC,UAAU;IACvC,kBAAkB,EAAE,oBAAoB;IACxC,qBAAqB,EAAE,uBAAuB;IAC9C,kBAAkB,EAAE,oBAAoB;IACxC,qBAAqB,EAAE,iBAAiB,CAAC,eAAe;IACxD,wBAAwB,EAAE,iBAAiB,CAAC,kBAAkB;IAC9D,qBAAqB,EAAE,iBAAiB,CAAC,eAAe;IACxD,aAAa,EAAE,iBAAiB,CAAC,OAAO;IACxC,eAAe,EAAE,iBAAiB;IAClC,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,kBAAkB;IACpC,uBAAuB,EAAE,yBAAyB;IAClD,0BAA0B,EAAE,4BAA4B;IACxD,uBAAuB,EAAE,yBAAyB;IAClD,sBAAsB,EAAE,wBAAwB;IAChD,yBAAyB,EAAE,2BAA2B;IACtD,sBAAsB,EAAE,wBAAwB;IAChD,oBAAoB,EAAE,sBAAsB;IAC5C,uBAAuB,EAAE,yBAAyB;IAClD,oBAAoB,EAAE,sBAAsB;IAC5C,iBAAiB,EAAE,mBAAmB;IACtC,mBAAmB,EAAE,qBAAqB;IAC1C,mBAAmB,EAAE,qBAAqB;IAC1C,kBAAkB,EAAE,oBAAoB;IACxC,aAAa,EAAE,eAAe;IAC9B,MAAM,EAAE,QAAQ;CACV,CAAC"}

package/dist/plugins/event-emitter-plugin.d.ts

@@ -0,0 +1,222 @@
+import { AbstractPlugin, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginErrorContext, type IPluginOptions, type IPluginStats } from '../abstracts/abstract-plugin';
+import type { IToolExecutionContext, TToolParameters, IToolResult } from '../interfaces/tool';
+import { type IEventEmitterEventData, type TEventName, type TEventEmitterListener } from './event-emitter/types';
+import { type IEventEmitterMetrics } from './event-emitter/metrics';
+export type { TEventName };
+/**
+ * Basic event execution value types - compatible with IPluginExecutionResult
+ */
+export type TEventExecutionValue = string | number | boolean | Date | string[] | number[] | boolean[] | Record<string, string | number | boolean | null> | null | undefined;
+/**
+ * Event execution context data following semantic naming conventions
+ * Supports nested structures with proper type safety
+ */
+export interface IEventExecutionContextData {
+    messageCount?: number | undefined;
+    config?: Record<string, TEventExecutionValue> | undefined;
+    result?: IPluginExecutionResult | undefined;
+    duration?: number | undefined;
+    tokensUsed?: number | undefined;
+    toolsExecuted?: number | undefined;
+    messages?: Record<string, TEventExecutionValue>[] | undefined;
+    response?: string | undefined;
+    toolCalls?: Record<string, TEventExecutionValue>[] | undefined;
+    [key: string]: TEventExecutionValue | Record<string, TEventExecutionValue> | Record<string, TEventExecutionValue>[] | IPluginExecutionResult | undefined;
+}
+/**
+ * Event metadata following semantic naming conventions
+ */
+export type TEventEmitterMetadata = Record<string, string | number | boolean | Date | string[] | number[] | undefined>;
+/**
+ * Plugin execution context for event emitter
+ */
+export interface IEventEmitterPluginExecutionContext extends IPluginExecutionContext {
+}
+/**
+ * Plugin execution result for event emitter
+ */
+export interface IEventEmitterPluginExecutionResult {
+    content?: string;
+    response?: string;
+    duration?: number;
+    tokensUsed?: number;
+    toolsExecuted?: number;
+    usage?: Record<string, TEventExecutionValue>;
+    toolCalls?: Record<string, TEventExecutionValue>[];
+    [key: string]: TEventExecutionValue | Record<string, TEventExecutionValue> | Record<string, TEventExecutionValue>[] | undefined;
+}
+/**
+ * Event data structure
+ */
+export type { IEventEmitterEventData };
+/**
+ * 🆕 Enhanced event data for hierarchical execution tracking
+ * Extends IEventEmitterEventData with additional fields for parent-child relationships and real-time data
+ */
+export interface IEventEmitterHierarchicalEventData extends IEventEmitterEventData {
+    /** Parent execution ID for hierarchical tracking */
+    parentExecutionId?: string;
+    /** Root execution ID (Team/Agent level) */
+    rootExecutionId?: string;
+    /** Execution depth level (0: Team, 1: Agent, 2: Tool, etc.) */
+    executionLevel: number;
+    /** Execution path showing complete hierarchy */
+    executionPath: string[];
+    /** Real-time execution data (no simulation) */
+    realTimeData?: {
+        /** Actual execution start time */
+        startTime: Date;
+        /** Actual duration in milliseconds (when completed) */
+        actualDuration?: number;
+        /** Actual input parameters */
+        actualParameters?: TToolParameters;
+        /** Actual execution result */
+        actualResult?: IToolResult;
+    };
+}
+/**
+ * Event listener function
+ */
+export type { TEventEmitterListener };
+/**
+ * Event emitter configuration
+ */
+export interface IEventEmitterPluginOptions extends IPluginOptions {
+    /** Events to listen for */
+    events?: TEventName[];
+    /** Maximum number of listeners per event type */
+    maxListeners?: number;
+    /** Whether to emit events asynchronously */
+    async?: boolean;
+    /** Whether to catch and log listener errors */
+    catchErrors?: boolean;
+    /** Custom event filters */
+    filters?: Record<TEventName, (event: IEventEmitterEventData) => boolean>;
+    /** Event buffering options */
+    buffer?: {
+        enabled: boolean;
+        maxSize: number;
+        flushInterval: number;
+    };
+    /** Metrics collector (optional) */
+    metrics?: IEventEmitterMetrics;
+}
+/**
+ * Event emitter plugin statistics
+ */
+export interface IEventEmitterPluginStats extends IPluginStats {
+    eventTypes: TEventName[];
+    listenerCounts: Record<TEventName, number>;
+    totalListeners: number;
+    bufferedEvents: number;
+    totalEmitted: number;
+    totalErrors: number;
+}
+/**
+ * Plugin for event detection and propagation
+ * Emits events during agent execution lifecycle
+ */
+export declare class EventEmitterPlugin extends AbstractPlugin<IEventEmitterPluginOptions, IEventEmitterPluginStats> {
+    name: string;
+    version: string;
+    private pluginOptions;
+    private logger;
+    private handlers;
+    private eventBuffer;
+    private nextHandlerId;
+    private bufferTimer?;
+    private metrics;
+    constructor(options?: IEventEmitterPluginOptions);
+    /**
+     * Before execution starts
+     */
+    beforeExecution(context: IPluginExecutionContext): Promise<void>;
+    /**
+     * After execution completes
+     */
+    afterExecution(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    /**
+     * Before conversation starts
+     */
+    beforeConversation(context: IPluginExecutionContext): Promise<void>;
+    /**
+     * After conversation completes
+     */
+    afterConversation(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    /**
+     * Before tool execution - emits tool.beforeExecute event
+     */
+    beforeToolExecution(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void>;
+    /**
+     * After tool execution - emits tool.success or tool.error events
+     */
+    afterToolExecution(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void>;
+    /**
+     * On error
+     *
+     * REASON: Error context structure varies by execution phase and error type, needs flexible handling
+     * ALTERNATIVES_CONSIDERED:
+     * 1. Strict error context interface (breaks error handling flexibility)
+     * 2. Union types (insufficient for dynamic error contexts)
+     * 3. Generic constraints (too complex for error handling)
+     * 4. Interface definitions (too rigid for varied error contexts)
+     * 5. Type assertions (decreases type safety)
+     * TODO: Consider standardized error context interface
+     */
+    onError(error: Error, context?: IPluginErrorContext): Promise<void>;
+    /**
+     * Register event listener
+     */
+    on(eventType: TEventName, listener: TEventEmitterListener, options?: {
+        once?: boolean;
+        filter?: (event: IEventEmitterEventData) => boolean;
+    }): string;
+    /**
+     * Register one-time event listener
+     */
+    once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
+    /**
+     * Remove event listener
+     */
+    off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
+    /**
+     * Emit an event
+     */
+    emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
+    /**
+     * Process a single event
+     */
+    private processEvent;
+    private executeHandler;
+    /**
+     * Buffer an event
+     */
+    private bufferEvent;
+    /**
+     * Setup event buffering
+     */
+    private setupBuffering;
+    /**
+     * Flush buffered events
+     */
+    flushBuffer(): Promise<void>;
+    /**
+     * Get event emitter statistics
+     */
+    getStats(): IEventEmitterPluginStats;
+    /**
+     * Clear all listeners
+     */
+    clearAllListeners(): void;
+    /**
+     * Cleanup on plugin destruction
+     */
+    destroy(): Promise<void>;
+    /**
+     * Validates the plugin options.
+     * @param options The options to validate.
+     * @throws PluginError if options are invalid.
+     */
+    private validateOptions;
+}
+//# sourceMappingURL=event-emitter-plugin.d.ts.map

package/dist/plugins/event-emitter-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/event-emitter-plugin.ts"],"names":[],"mappings":"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"}