@compilr-dev/agents 0.0.1

package/dist/hooks/manager.js

@@ -0,0 +1,600 @@
+/**
+ * HooksManager - Manages lifecycle hooks for agent customization
+ *
+ * Provides:
+ * - Hook registration with priorities
+ * - Sequential execution in priority order
+ * - Type-safe hook invocation
+ * - Error handling and recovery
+ */
+/**
+ * Manages lifecycle hooks for agent customization
+ */
+export class HooksManager {
+    beforeIterationHooks = [];
+    afterIterationHooks = [];
+    beforeLLMHooks = [];
+    afterLLMHooks = [];
+    beforeToolHooks = [];
+    afterToolHooks = [];
+    onErrorHooks = [];
+    onEvent;
+    hookIdCounter = 0;
+    constructor(options = {}) {
+        this.onEvent = options.onEvent;
+        // Register initial hooks from config
+        if (options.hooks) {
+            this.registerFromConfig(options.hooks);
+        }
+    }
+    // ============================================================
+    // Registration Methods
+    // ============================================================
+    /**
+     * Register hooks from a configuration object
+     */
+    registerFromConfig(config) {
+        if (config.beforeIteration) {
+            for (const hook of config.beforeIteration) {
+                this.registerBeforeIteration(hook);
+            }
+        }
+        if (config.afterIteration) {
+            for (const hook of config.afterIteration) {
+                this.registerAfterIteration(hook);
+            }
+        }
+        if (config.beforeLLM) {
+            for (const hook of config.beforeLLM) {
+                this.registerBeforeLLM(hook);
+            }
+        }
+        if (config.afterLLM) {
+            for (const hook of config.afterLLM) {
+                this.registerAfterLLM(hook);
+            }
+        }
+        if (config.beforeTool) {
+            for (const hook of config.beforeTool) {
+                this.registerBeforeTool(hook);
+            }
+        }
+        if (config.afterTool) {
+            for (const hook of config.afterTool) {
+                this.registerAfterTool(hook);
+            }
+        }
+        if (config.onError) {
+            for (const hook of config.onError) {
+                this.registerOnError(hook);
+            }
+        }
+    }
+    /**
+     * Register a before:iteration hook
+     */
+    registerBeforeIteration(hook, options) {
+        const id = this.generateId();
+        this.beforeIterationHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.beforeIterationHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'beforeIteration',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register an after:iteration hook
+     */
+    registerAfterIteration(hook, options) {
+        const id = this.generateId();
+        this.afterIterationHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.afterIterationHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'afterIteration',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register a before:llm hook
+     */
+    registerBeforeLLM(hook, options) {
+        const id = this.generateId();
+        this.beforeLLMHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.beforeLLMHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'beforeLLM',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register an after:llm hook
+     */
+    registerAfterLLM(hook, options) {
+        const id = this.generateId();
+        this.afterLLMHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.afterLLMHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'afterLLM',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register a before:tool hook
+     */
+    registerBeforeTool(hook, options) {
+        const id = this.generateId();
+        this.beforeToolHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.beforeToolHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'beforeTool',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register an after:tool hook
+     */
+    registerAfterTool(hook, options) {
+        const id = this.generateId();
+        this.afterToolHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.afterToolHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'afterTool',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Register an onError hook
+     */
+    registerOnError(hook, options) {
+        const id = this.generateId();
+        this.onErrorHooks.push({
+            id,
+            hook,
+            name: options?.name,
+            priority: options?.priority ?? 0,
+        });
+        this.sortByPriority(this.onErrorHooks);
+        this.emitEvent({
+            type: 'hook:registered',
+            hookType: 'onError',
+            hookId: id,
+            hookName: options?.name,
+        });
+        return id;
+    }
+    /**
+     * Unregister a hook by ID
+     */
+    unregister(hookId) {
+        const arrays = [
+            { arr: this.beforeIterationHooks, type: 'beforeIteration' },
+            { arr: this.afterIterationHooks, type: 'afterIteration' },
+            { arr: this.beforeLLMHooks, type: 'beforeLLM' },
+            { arr: this.afterLLMHooks, type: 'afterLLM' },
+            { arr: this.beforeToolHooks, type: 'beforeTool' },
+            { arr: this.afterToolHooks, type: 'afterTool' },
+            { arr: this.onErrorHooks, type: 'onError' },
+        ];
+        for (const { arr, type } of arrays) {
+            const index = arr.findIndex((h) => h.id === hookId);
+            if (index !== -1) {
+                const hook = arr[index];
+                arr.splice(index, 1);
+                this.emitEvent({ type: 'hook:unregistered', hookType: type, hookId, hookName: hook.name });
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Clear all hooks
+     */
+    clear() {
+        this.beforeIterationHooks = [];
+        this.afterIterationHooks = [];
+        this.beforeLLMHooks = [];
+        this.afterLLMHooks = [];
+        this.beforeToolHooks = [];
+        this.afterToolHooks = [];
+        this.onErrorHooks = [];
+    }
+    // ============================================================
+    // Execution Methods
+    // ============================================================
+    /**
+     * Run before:iteration hooks
+     *
+     * @returns true to continue, false to skip iteration
+     */
+    async runBeforeIteration(context) {
+        for (const registered of this.beforeIterationHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'beforeIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                const result = await registered.hook(context);
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'beforeIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+                if (result && typeof result === 'object' && 'skip' in result) {
+                    return false; // Skip iteration
+                }
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'beforeIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+                // Continue with other hooks on error
+            }
+        }
+        return true;
+    }
+    /**
+     * Run after:iteration hooks
+     */
+    async runAfterIteration(context) {
+        for (const registered of this.afterIterationHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'afterIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                await registered.hook(context);
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'afterIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'afterIteration',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+    }
+    /**
+     * Run before:llm hooks
+     *
+     * @returns potentially modified messages and tools
+     */
+    async runBeforeLLM(context) {
+        let messages = context.messages;
+        let tools = context.tools;
+        for (const registered of this.beforeLLMHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'beforeLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                const result = await registered.hook({ ...context, messages, tools });
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'beforeLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+                if (result && typeof result === 'object') {
+                    const hookResult = result;
+                    if (hookResult.messages)
+                        messages = hookResult.messages;
+                    if (hookResult.tools)
+                        tools = hookResult.tools;
+                }
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'beforeLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        return { messages, tools };
+    }
+    /**
+     * Run after:llm hooks
+     */
+    async runAfterLLM(context) {
+        for (const registered of this.afterLLMHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'afterLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                await registered.hook(context);
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'afterLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'afterLLM',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+    }
+    /**
+     * Run before:tool hooks
+     *
+     * @returns whether to proceed and potentially modified input or skip result
+     */
+    async runBeforeTool(context) {
+        let input = context.input;
+        for (const registered of this.beforeToolHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'beforeTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                const result = await registered.hook({ ...context, input });
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'beforeTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+                if (result && typeof result === 'object') {
+                    const hookResult = result;
+                    if (hookResult.skip) {
+                        return {
+                            proceed: false,
+                            input,
+                            skipResult: hookResult.result ?? { success: false, error: 'Skipped by hook' },
+                        };
+                    }
+                    if (hookResult.input)
+                        input = hookResult.input;
+                }
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'beforeTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        return { proceed: true, input };
+    }
+    /**
+     * Run after:tool hooks
+     *
+     * @returns potentially modified result
+     */
+    async runAfterTool(context) {
+        let result = context.result;
+        for (const registered of this.afterToolHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'afterTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                const hookReturn = await registered.hook({ ...context, result });
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'afterTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+                if (hookReturn && typeof hookReturn === 'object') {
+                    const hookResult = hookReturn;
+                    if (hookResult.result)
+                        result = hookResult.result;
+                }
+            }
+            catch (error) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'afterTool',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Run onError hooks
+     *
+     * @returns error handling result
+     */
+    async runOnError(context) {
+        let finalResult = {};
+        for (const registered of this.onErrorHooks) {
+            const start = Date.now();
+            try {
+                this.emitEvent({
+                    type: 'hook:started',
+                    hookType: 'onError',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                });
+                const result = await registered.hook(context);
+                this.emitEvent({
+                    type: 'hook:completed',
+                    hookType: 'onError',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    durationMs: Date.now() - start,
+                });
+                if (result && typeof result === 'object') {
+                    const hookResult = result;
+                    if (hookResult.handled) {
+                        finalResult = hookResult;
+                        break; // Stop processing if error is handled
+                    }
+                    if (hookResult.error) {
+                        finalResult.error = hookResult.error;
+                    }
+                    if (hookResult.recovery) {
+                        finalResult.recovery = hookResult.recovery;
+                    }
+                }
+            }
+            catch (hookError) {
+                this.emitEvent({
+                    type: 'hook:error',
+                    hookType: 'onError',
+                    hookId: registered.id,
+                    hookName: registered.name,
+                    error: hookError instanceof Error ? hookError : new Error(String(hookError)),
+                });
+                // Continue with other error hooks
+            }
+        }
+        return finalResult;
+    }
+    // ============================================================
+    // Query Methods
+    // ============================================================
+    /**
+     * Check if any hooks are registered
+     */
+    hasHooks() {
+        return (this.beforeIterationHooks.length > 0 ||
+            this.afterIterationHooks.length > 0 ||
+            this.beforeLLMHooks.length > 0 ||
+            this.afterLLMHooks.length > 0 ||
+            this.beforeToolHooks.length > 0 ||
+            this.afterToolHooks.length > 0 ||
+            this.onErrorHooks.length > 0);
+    }
+    /**
+     * Get hook counts by type
+     */
+    getHookCounts() {
+        return {
+            beforeIteration: this.beforeIterationHooks.length,
+            afterIteration: this.afterIterationHooks.length,
+            beforeLLM: this.beforeLLMHooks.length,
+            afterLLM: this.afterLLMHooks.length,
+            beforeTool: this.beforeToolHooks.length,
+            afterTool: this.afterToolHooks.length,
+            onError: this.onErrorHooks.length,
+        };
+    }
+    /**
+     * Get all registered hook IDs
+     */
+    getHookIds() {
+        return [
+            ...this.beforeIterationHooks.map((h) => h.id),
+            ...this.afterIterationHooks.map((h) => h.id),
+            ...this.beforeLLMHooks.map((h) => h.id),
+            ...this.afterLLMHooks.map((h) => h.id),
+            ...this.beforeToolHooks.map((h) => h.id),
+            ...this.afterToolHooks.map((h) => h.id),
+            ...this.onErrorHooks.map((h) => h.id),
+        ];
+    }
+    // ============================================================
+    // Private Methods
+    // ============================================================
+    generateId() {
+        return `hook_${String(++this.hookIdCounter)}_${String(Date.now())}`;
+    }
+    sortByPriority(hooks) {
+        hooks.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    }
+    emitEvent(event) {
+        this.onEvent?.(event);
+    }
+}