mcp-agent-foundry 1.3.0 → 2.0.0

package/dist/hooks/hook-executor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Hook Executor
+ *
+ * Executes hook commands and parses their output.
+ * Handles variable substitution, timeouts, and process management.
+ */
+import type { Logger } from '../observability/logger.js';
+import type { HookDefinition, HookInput, HookVariables, HookExecutionResult } from './types.js';
+/**
+ * Executes hook commands in child processes.
+ * Handles variable substitution, timeouts, and output parsing.
+ */
+export declare class HookExecutor {
+    private readonly logger;
+    private readonly defaultTimeout;
+    constructor(logger: Logger, defaultTimeout?: number);
+    /**
+     * Execute a hook command and parse its output.
+     *
+     * @param hook - Hook definition to execute
+     * @param input - Input data to pass to the hook
+     * @returns Hook execution result
+     */
+    execute(hook: HookDefinition, input: HookInput): Promise<HookExecutionResult>;
+    /**
+     * Substitute variables in a command string.
+     * Variables use the ${VAR_NAME} syntax.
+     *
+     * @param command - Command string with variable placeholders
+     * @param variables - Variable values to substitute
+     * @returns Command with variables substituted
+     */
+    substituteVariables(command: string, variables: Partial<HookVariables>): string;
+    /**
+     * Build environment variables for hook process.
+     * Merges current environment with hook-specific env and variables.
+     *
+     * @param hook - Hook definition
+     * @param input - Hook input data
+     * @param variables - Computed variable values
+     * @returns Environment variables for the process
+     */
+    buildEnv(hook: HookDefinition, input: HookInput, variables: Partial<HookVariables>): Record<string, string>;
+    /**
+     * Build variable values from hook input.
+     *
+     * @param input - Hook input data
+     * @returns Variable values for substitution
+     */
+    private buildVariables;
+    /**
+     * Run a shell command with timeout and input handling.
+     *
+     * @param command - Shell command to execute
+     * @param options - Execution options
+     * @returns Hook output parsed from stdout
+     */
+    private runCommand;
+    /**
+     * Parse hook output from stdout.
+     * Attempts to parse as JSON, falls back to raw output.
+     *
+     * @param stdout - Raw stdout from the hook
+     * @param stderr - Raw stderr from the hook
+     * @param exitCode - Process exit code
+     * @returns Parsed hook output
+     */
+    private parseOutput;
+    /**
+     * Escape a string for safe use in shell commands.
+     *
+     * @param value - String to escape
+     * @returns Shell-safe string
+     */
+    private escapeForShell;
+}
+//# sourceMappingURL=hook-executor.d.ts.map

package/dist/hooks/hook-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-executor.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EAET,aAAa,EACb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAoBpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,MAAM,EAAE,cAAc,GAAE,MAAa;IAKzD;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsEnF;;;;;;;OAOG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM;IAY/E;;;;;;;;OAQG;IACH,QAAQ,CACN,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA8BzB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;;;;OAMG;YACW,UAAU;IAyFxB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAiCnB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CASvB"}

package/dist/hooks/hook-executor.js

@@ -0,0 +1,308 @@
+/**
+ * Hook Executor
+ *
+ * Executes hook commands and parses their output.
+ * Handles variable substitution, timeouts, and process management.
+ */
+import { spawn } from 'child_process';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Maximum output buffer size in bytes (1MB).
+ */
+const MAX_OUTPUT_SIZE = 1024 * 1024;
+/**
+ * Regex pattern for variable substitution: ${VAR_NAME}
+ */
+const VARIABLE_PATTERN = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+// ============================================================================
+// Hook Executor Class
+// ============================================================================
+/**
+ * Executes hook commands in child processes.
+ * Handles variable substitution, timeouts, and output parsing.
+ */
+export class HookExecutor {
+    logger;
+    defaultTimeout;
+    constructor(logger, defaultTimeout = 5000) {
+        this.logger = logger.child({ component: 'HookExecutor' });
+        this.defaultTimeout = defaultTimeout;
+    }
+    /**
+     * Execute a hook command and parse its output.
+     *
+     * @param hook - Hook definition to execute
+     * @param input - Input data to pass to the hook
+     * @returns Hook execution result
+     */
+    async execute(hook, input) {
+        const startTime = Date.now();
+        // Check if hook is enabled
+        if (hook.enabled === false) {
+            this.logger.debug('Hook disabled, skipping', { hookName: hook.name });
+            return {
+                hook,
+                success: true,
+                output: {},
+                durationMs: 0,
+            };
+        }
+        const timeout = hook.timeout_ms ?? this.defaultTimeout;
+        const variables = this.buildVariables(input);
+        const command = this.substituteVariables(hook.command, variables);
+        const env = this.buildEnv(hook, input, variables);
+        const cwd = hook.cwd ?? process.cwd();
+        this.logger.debug('Executing hook', {
+            hookName: hook.name,
+            event: input.event,
+            command: command.substring(0, 100), // Truncate for logging
+            timeout,
+            cwd,
+        });
+        try {
+            const output = await this.runCommand(command, {
+                cwd,
+                env,
+                timeout,
+                input: JSON.stringify(input),
+            });
+            const durationMs = Date.now() - startTime;
+            this.logger.debug('Hook completed', {
+                hookName: hook.name,
+                durationMs,
+                exitCode: output.exitCode,
+                hasOutput: !!output.stdout,
+            });
+            return {
+                hook,
+                success: output.exitCode === 0,
+                output,
+                durationMs,
+            };
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.warn('Hook execution failed', {
+                hookName: hook.name,
+                durationMs,
+                error: errorMessage,
+            });
+            return {
+                hook,
+                success: false,
+                error: error instanceof Error ? error : new Error(errorMessage),
+                durationMs,
+            };
+        }
+    }
+    /**
+     * Substitute variables in a command string.
+     * Variables use the ${VAR_NAME} syntax.
+     *
+     * @param command - Command string with variable placeholders
+     * @param variables - Variable values to substitute
+     * @returns Command with variables substituted
+     */
+    substituteVariables(command, variables) {
+        return command.replace(VARIABLE_PATTERN, (match, varName) => {
+            const value = variables[varName];
+            if (value !== undefined) {
+                // Escape special characters for shell safety
+                return this.escapeForShell(value);
+            }
+            // Leave unmatched variables as-is
+            return match;
+        });
+    }
+    /**
+     * Build environment variables for hook process.
+     * Merges current environment with hook-specific env and variables.
+     *
+     * @param hook - Hook definition
+     * @param input - Hook input data
+     * @param variables - Computed variable values
+     * @returns Environment variables for the process
+     */
+    buildEnv(hook, input, variables) {
+        // Start with current environment
+        const env = { ...process.env };
+        // Add hook variables as environment variables
+        for (const [key, value] of Object.entries(variables)) {
+            if (value !== undefined) {
+                env[`HOOK_${key}`] = value;
+            }
+        }
+        // Add convenience variables
+        env['HOOK_EVENT'] = input.event;
+        env['HOOK_NAME'] = hook.name;
+        if (input.timestamp) {
+            env['HOOK_TIMESTAMP'] = input.timestamp.toISOString();
+        }
+        // Add hook-specific environment variables (highest priority)
+        if (hook.env) {
+            for (const [key, value] of Object.entries(hook.env)) {
+                // Substitute variables in env values too
+                env[key] = this.substituteVariables(value, variables);
+            }
+        }
+        return env;
+    }
+    /**
+     * Build variable values from hook input.
+     *
+     * @param input - Hook input data
+     * @returns Variable values for substitution
+     */
+    buildVariables(input) {
+        return {
+            CLAUDE_SESSION_ID: input.sessionId ?? '',
+            TASK_ID: input.taskId ?? '',
+            WORKTREE_PATH: input.worktreePath ?? '',
+            TOOL_NAME: input.toolName ?? '',
+            PROVIDER: input.provider ?? '',
+            MODEL: input.model ?? '',
+            ROLE: input.role ?? '',
+            ERROR_CODE: input.errorCode?.toString() ?? '',
+            ERROR_MESSAGE: input.errorMessage ?? '',
+            FROM_PROVIDER: input.fromProvider ?? '',
+            TO_PROVIDER: input.toProvider ?? '',
+            ATTEMPT_NUMBER: input.attemptNumber?.toString() ?? '',
+        };
+    }
+    /**
+     * Run a shell command with timeout and input handling.
+     *
+     * @param command - Shell command to execute
+     * @param options - Execution options
+     * @returns Hook output parsed from stdout
+     */
+    async runCommand(command, options) {
+        return new Promise((resolve, reject) => {
+            let child;
+            let killed = false;
+            let stdout = '';
+            let stderr = '';
+            // Spawn shell process
+            try {
+                child = spawn('/bin/sh', ['-c', command], {
+                    cwd: options.cwd,
+                    env: options.env,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch (error) {
+                reject(new Error(`Failed to spawn process: ${error instanceof Error ? error.message : String(error)}`));
+                return;
+            }
+            // Setup timeout
+            const timer = setTimeout(() => {
+                killed = true;
+                child.kill('SIGTERM');
+                // Give it a moment to clean up, then force kill
+                setTimeout(() => {
+                    if (!child.killed) {
+                        child.kill('SIGKILL');
+                    }
+                }, 1000);
+                reject(new Error(`Hook timed out after ${options.timeout}ms`));
+            }, options.timeout);
+            // Collect stdout
+            if (child.stdout) {
+                child.stdout.on('data', (data) => {
+                    if (stdout.length < MAX_OUTPUT_SIZE) {
+                        stdout += data.toString();
+                    }
+                });
+            }
+            // Collect stderr
+            if (child.stderr) {
+                child.stderr.on('data', (data) => {
+                    if (stderr.length < MAX_OUTPUT_SIZE) {
+                        stderr += data.toString();
+                    }
+                });
+            }
+            // Write input to stdin
+            if (options.input && child.stdin) {
+                child.stdin.write(options.input);
+                child.stdin.end();
+            }
+            // Handle process exit
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                if (killed) {
+                    // Already rejected due to timeout
+                    return;
+                }
+                const exitCode = code ?? 1;
+                const output = this.parseOutput(stdout, stderr, exitCode);
+                resolve(output);
+            });
+            // Handle spawn errors
+            child.on('error', (error) => {
+                clearTimeout(timer);
+                if (!killed) {
+                    reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Parse hook output from stdout.
+     * Attempts to parse as JSON, falls back to raw output.
+     *
+     * @param stdout - Raw stdout from the hook
+     * @param stderr - Raw stderr from the hook
+     * @param exitCode - Process exit code
+     * @returns Parsed hook output
+     */
+    parseOutput(stdout, stderr, exitCode) {
+        const trimmedStdout = stdout.trim();
+        const trimmedStderr = stderr.trim();
+        // Try to parse stdout as JSON
+        if (trimmedStdout) {
+            try {
+                const parsed = JSON.parse(trimmedStdout);
+                return {
+                    ...parsed,
+                    exitCode,
+                    stdout: trimmedStdout,
+                    stderr: trimmedStderr || undefined,
+                };
+            }
+            catch {
+                // Not JSON, treat as message
+                return {
+                    message: trimmedStdout,
+                    exitCode,
+                    stdout: trimmedStdout,
+                    stderr: trimmedStderr || undefined,
+                };
+            }
+        }
+        // No stdout, return basic output
+        return {
+            exitCode,
+            stdout: trimmedStdout || undefined,
+            stderr: trimmedStderr || undefined,
+        };
+    }
+    /**
+     * Escape a string for safe use in shell commands.
+     *
+     * @param value - String to escape
+     * @returns Shell-safe string
+     */
+    escapeForShell(value) {
+        // For simple alphanumeric strings, no escaping needed
+        if (/^[a-zA-Z0-9_\-./]+$/.test(value)) {
+            return value;
+        }
+        // Escape single quotes and wrap in single quotes
+        return `'${value.replace(/'/g, "'\\''")}'`;
+    }
+}
+//# sourceMappingURL=hook-executor.js.map

package/dist/hooks/hook-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-executor.js","sourceRoot":"","sources":["../../src/hooks/hook-executor.ts"],"names":[],"mappings":"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"}

package/dist/hooks/hook-manager.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Hook Manager
+ *
+ * Central manager for hook registration, filtering, and execution.
+ * Handles hook lifecycle, session tracking, and event triggering.
+ */
+import { EventEmitter } from 'events';
+import type { Logger } from '../observability/logger.js';
+import type { HooksConfig, HookDefinition, HookEvent, HookInput, HookTriggerResult, HookManagerEvents } from './types.js';
+/**
+ * Manages hook registration, filtering, and execution.
+ * Provides an event-based API for hook lifecycle notifications.
+ */
+export declare class HookManager extends EventEmitter {
+    private readonly logger;
+    private readonly executor;
+    private config;
+    private hooks;
+    private runTracker;
+    private sessionId;
+    private hooksFilePath?;
+    private fileWatcher?;
+    constructor(config: Partial<HooksConfig> | undefined, logger: Logger);
+    /**
+     * Check if hooks system is enabled.
+     */
+    get isEnabled(): boolean;
+    /**
+     * Get the current session ID.
+     */
+    getSessionId(): string;
+    /**
+     * Register hooks from configuration.
+     * Validates and indexes hooks by event type.
+     *
+     * @param hooks - Hook definitions to register
+     */
+    registerHooks(hooks: HookDefinition[]): void;
+    /**
+     * Unregister a hook by name.
+     *
+     * @param name - Name of the hook to unregister
+     */
+    unregisterHook(name: string): void;
+    /**
+     * Get all hooks registered for an event.
+     *
+     * @param event - Hook event type
+     * @returns Array of hook definitions
+     */
+    getHooksForEvent(event: HookEvent): HookDefinition[];
+    /**
+     * Trigger all hooks for an event.
+     * Executes matching hooks in registration order.
+     *
+     * @param event - Event to trigger
+     * @param input - Input data (without event and timestamp)
+     * @returns Combined result from all hooks
+     */
+    trigger(event: HookEvent, input: Omit<HookInput, 'event' | 'timestamp'>): Promise<HookTriggerResult>;
+    /**
+     * Check if a hook should run based on filters and run tracking.
+     *
+     * @param hook - Hook definition to check
+     * @param input - Hook input data
+     * @returns True if hook should run
+     */
+    shouldRun(hook: HookDefinition, input: HookInput): boolean;
+    /**
+     * Mark a hook as having run (for once: true hooks).
+     *
+     * @param hookName - Name of the hook
+     */
+    markRun(hookName: string): void;
+    /**
+     * Check if a hook has already run this session.
+     *
+     * @param hookName - Name of the hook
+     * @returns True if hook has run
+     */
+    hasRun(hookName: string): boolean;
+    /**
+     * Reset run tracking (for new session).
+     */
+    resetSession(): void;
+    /**
+     * Load hooks from an external file.
+     *
+     * @param path - Path to hooks configuration file (JSON or YAML)
+     */
+    loadFromFile(path: string): Promise<void>;
+    /**
+     * Start watching hooks file for changes.
+     * Automatically reloads hooks when file changes.
+     */
+    watchFile(): void;
+    /**
+     * Stop watching hooks file.
+     */
+    stopWatching(): void;
+    /**
+     * Hot-reload hooks from file.
+     */
+    reload(): Promise<void>;
+    /**
+     * Update configuration.
+     *
+     * @param config - New configuration (partial)
+     */
+    updateConfig(config: Partial<HooksConfig>): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): HooksConfig;
+    /**
+     * Shutdown hook manager and cleanup resources.
+     */
+    shutdown(): void;
+    /**
+     * Generate a unique session ID.
+     */
+    private generateSessionId;
+    /**
+     * Parse hooks file content (JSON).
+     */
+    private parseHooksFile;
+    /**
+     * Match a string against a pattern (supports * wildcard).
+     */
+    private matchesPattern;
+    /**
+     * Merge two hook outputs, with later values taking precedence.
+     */
+    private mergeOutputs;
+}
+export interface HookManager {
+    on<K extends keyof HookManagerEvents>(event: K, listener: (payload: HookManagerEvents[K]) => void): this;
+    emit<K extends keyof HookManagerEvents>(event: K, payload: HookManagerEvents[K]): boolean;
+}
+//# sourceMappingURL=hook-manager.d.ts.map

package/dist/hooks/hook-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-manager.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,SAAS,EACT,SAAS,EAGT,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAC,CAAY;gBAEpB,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,YAAK,EAAE,MAAM,EAAE,MAAM;IAqB7D;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAuD5C;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAalC;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,EAAE;IAIpD;;;;;;;OAOG;IACG,OAAO,CACX,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC,GAC5C,OAAO,CAAC,iBAAiB,CAAC;IAoJ7B;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO;IA6C1D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,YAAY,IAAI,IAAI;IAMpB;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/C;;;OAGG;IACH,SAAS,IAAI,IAAI;IA6BjB;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAe7B;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAahD;;OAEG;IACH,SAAS,IAAI,WAAW;IAIxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAYhB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACH,OAAO,CAAC,YAAY;CA4BrB;AAOD,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAClC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAChD,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CAC3F"}