@agentforge/core 0.16.18 → 0.16.19

package/dist/index.cjs

@@ -1846,6 +1846,12 @@ var ManagedTool = class {
     failedExecutions: 0
   };
   _healthCheckTimer;
+  _beforeExitHandler;
+  _healthCheckInFlight = false;
+  _cleaningUp = false;
+  _cleanupPromise;
+  _initializePromise;
+  _lifecycleGeneration = 0;
   constructor(config) {
     this.name = config.name;
     this.description = config.description;
@@ -1856,17 +1862,7 @@ var ManagedTool = class {
     this.autoCleanup = config.autoCleanup ?? true;
     this.healthCheckInterval = config.healthCheckInterval;
     this._context = config.context;
-    if (this.autoCleanup) {
-      process.on("beforeExit", () => {
-        this.cleanup().catch(
-          (err) => logger3.error("Cleanup failed", {
-            toolName: this.name,
-            error: err instanceof Error ? err.message : String(err),
-            ...err instanceof Error && err.stack ? { stack: err.stack } : {}
-          })
-        );
-      });
-    }
+    this.ensureBeforeExitHandler();
   }
   /**
    * Get the tool context (e.g., connection pool, API client)
@@ -1890,28 +1886,26 @@ var ManagedTool = class {
    * Initialize the tool
    */
   async initialize() {
-    if (this._initialized) {
+    if (this._initializePromise) {
+      await this._initializePromise;
       return;
     }
-    if (this.initializeFn) {
-      await this.initializeFn();
+    if (this._cleanupPromise) {
+      await this._cleanupPromise;
+      if (this._initializePromise) {
+        await this._initializePromise;
+        return;
+      }
     }
-    this._initialized = true;
-    this._stats.initialized = true;
-    if (this.healthCheckInterval && this.healthCheckFn) {
-      this._healthCheckTimer = setInterval(async () => {
-        try {
-          const result = await this.healthCheckFn();
-          this._stats.lastHealthCheck = result;
-          this._stats.lastHealthCheckTime = Date.now();
-        } catch (error) {
-          this._stats.lastHealthCheck = {
-            healthy: false,
-            error: error.message
-          };
-          this._stats.lastHealthCheckTime = Date.now();
-        }
-      }, this.healthCheckInterval);
+    if (this._initialized) {
+      return;
+    }
+    const initializePromise = this.performInitialize();
+    this._initializePromise = initializePromise;
+    try {
+      await initializePromise;
+    } finally {
+      this._initializePromise = void 0;
     }
   }
   /**
@@ -1938,24 +1932,55 @@ var ManagedTool = class {
    * Cleanup the tool
    */
   async cleanup() {
-    if (!this._initialized) {
+    if (this._cleanupPromise) {
+      await this._cleanupPromise;
       return;
     }
+    if (this._initializePromise) {
+      try {
+        await this._initializePromise;
+      } catch {
+      }
+    }
+    const cleanupPromise = this.performCleanup();
+    this._cleanupPromise = cleanupPromise;
+    try {
+      await cleanupPromise;
+    } finally {
+      this._cleanupPromise = void 0;
+    }
+  }
+  async performCleanup() {
+    this._cleaningUp = true;
     if (this._healthCheckTimer) {
       clearInterval(this._healthCheckTimer);
       this._healthCheckTimer = void 0;
     }
-    if (this.cleanupFn) {
-      await this.cleanupFn();
+    if (this._beforeExitHandler) {
+      process.off("beforeExit", this._beforeExitHandler);
+      this._beforeExitHandler = void 0;
+    }
+    if (!this._initialized) {
+      this._cleaningUp = false;
+      return;
     }
     this._initialized = false;
     this._stats.initialized = false;
+    if (this.cleanupFn) {
+      try {
+        await this.cleanupFn();
+      } finally {
+        this._cleaningUp = false;
+      }
+      return;
+    }
+    this._cleaningUp = false;
   }
   /**
    * Run health check
    */
   async healthCheck() {
-    if (!this._initialized) {
+    if (!this._initialized || this._cleaningUp) {
       return {
         healthy: false,
         error: "Tool is not initialized"
@@ -1967,15 +1992,28 @@ var ManagedTool = class {
         metadata: { message: "No health check configured" }
       };
     }
+    const lifecycleGeneration = this._lifecycleGeneration;
     try {
       const result = await this.healthCheckFn();
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return {
+          healthy: false,
+          error: "Tool is not initialized"
+        };
+      }
       this._stats.lastHealthCheck = result;
       this._stats.lastHealthCheckTime = Date.now();
       return result;
     } catch (error) {
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return {
+          healthy: false,
+          error: "Tool is not initialized"
+        };
+      }
       const result = {
         healthy: false,
-        error: error.message
+        error: getErrorMessage(error)
       };
       this._stats.lastHealthCheck = result;
       this._stats.lastHealthCheckTime = Date.now();
@@ -2009,10 +2047,68 @@ var ManagedTool = class {
       }
     };
   }
+  async runPeriodicHealthCheck() {
+    if (!this.healthCheckFn || this._healthCheckInFlight || !this._initialized || this._cleaningUp) {
+      return;
+    }
+    this._healthCheckInFlight = true;
+    const lifecycleGeneration = this._lifecycleGeneration;
+    try {
+      const result = await this.healthCheckFn();
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return;
+      }
+      this._stats.lastHealthCheck = result;
+      this._stats.lastHealthCheckTime = Date.now();
+    } catch (error) {
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return;
+      }
+      this._stats.lastHealthCheck = {
+        healthy: false,
+        error: getErrorMessage(error)
+      };
+      this._stats.lastHealthCheckTime = Date.now();
+    } finally {
+      this._healthCheckInFlight = false;
+    }
+  }
+  async performInitialize() {
+    this.ensureBeforeExitHandler();
+    this._lifecycleGeneration++;
+    if (this.initializeFn) {
+      await this.initializeFn();
+    }
+    this._initialized = true;
+    this._stats.initialized = true;
+    if (this.healthCheckInterval && this.healthCheckFn) {
+      this._healthCheckTimer = setInterval(() => {
+        void this.runPeriodicHealthCheck();
+      }, this.healthCheckInterval);
+    }
+  }
+  ensureBeforeExitHandler() {
+    if (!this.autoCleanup || this._beforeExitHandler) {
+      return;
+    }
+    this._beforeExitHandler = () => {
+      this.cleanup().catch(
+        (err) => logger3.error("Cleanup failed", {
+          toolName: this.name,
+          error: getErrorMessage(err),
+          ...err instanceof Error && err.stack ? { stack: err.stack } : {}
+        })
+      );
+    };
+    process.on("beforeExit", this._beforeExitHandler);
+  }
 };
 function createManagedTool(config) {
   return new ManagedTool(config);
 }
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 // src/tools/composition.ts
 function isConditionalStep(step) {

package/dist/index.d.cts

@@ -1570,26 +1570,38 @@ declare function createToolExecutor(config?: ToolExecutorConfig): {
     };
 };
 
+/**
+ * Shared JSON-safe payload contracts for observability and monitoring paths.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+
 /**
  * Tool Lifecycle Management - Manage tool initialization, cleanup, and resources
  * @module tools/lifecycle
  */
+
 interface ToolHealthCheckResult {
     healthy: boolean;
     error?: string;
-    metadata?: Record<string, any>;
+    metadata?: JsonObject;
 }
-interface ManagedToolConfig<TContext = any, TInput = any, TOutput = any> {
+interface ManagedToolConfigBase<TContext, TInput, TOutput> {
     name: string;
     description: string;
     initialize?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
     execute: (this: ManagedTool<TContext, TInput, TOutput>, input: TInput) => Promise<TOutput>;
     cleanup?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
     healthCheck?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<ToolHealthCheckResult>;
-    context?: TContext;
     autoCleanup?: boolean;
     healthCheckInterval?: number;
 }
+interface ManagedToolConfig<TContext = undefined, TInput = unknown, TOutput = unknown> extends ManagedToolConfigBase<TContext, TInput, TOutput> {
+    context?: TContext;
+}
 interface ManagedToolStats {
     initialized: boolean;
     totalExecutions: number;
@@ -1602,7 +1614,7 @@ interface ManagedToolStats {
 /**
  * Managed tool with lifecycle hooks
  */
-declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
+declare class ManagedTool<TContext = undefined, TInput = unknown, TOutput = unknown> {
     readonly name: string;
     readonly description: string;
     private readonly initializeFn?;
@@ -1615,15 +1627,21 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
     private _context;
     private _stats;
     private _healthCheckTimer?;
+    private _beforeExitHandler?;
+    private _healthCheckInFlight;
+    private _cleaningUp;
+    private _cleanupPromise?;
+    private _initializePromise?;
+    private _lifecycleGeneration;
     constructor(config: ManagedToolConfig<TContext, TInput, TOutput>);
     /**
      * Get the tool context (e.g., connection pool, API client)
      */
-    get context(): TContext;
+    get context(): TContext | undefined;
     /**
      * Set the tool context
      */
-    set context(value: TContext);
+    set context(value: TContext | undefined);
     /**
      * Check if tool is initialized
      */
@@ -1640,6 +1658,7 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
      * Cleanup the tool
      */
     cleanup(): Promise<void>;
+    private performCleanup;
     /**
      * Run health check
      */
@@ -1660,11 +1679,14 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
         description: string;
         invoke: (input: TInput) => Promise<TOutput>;
     };
+    private runPeriodicHealthCheck;
+    private performInitialize;
+    private ensureBeforeExitHandler;
 }
 /**
  * Create a managed tool
  */
-declare function createManagedTool<TContext = any, TInput = any, TOutput = any>(config: ManagedToolConfig<TContext, TInput, TOutput>): ManagedTool<TContext, TInput, TOutput>;
+declare function createManagedTool<TContext = undefined, TInput = unknown, TOutput = unknown>(config: ManagedToolConfig<TContext, TInput, TOutput>): ManagedTool<TContext, TInput, TOutput>;
 
 /**
  * Tool Composition - Compose tools into higher-level operations
@@ -2815,15 +2837,6 @@ interface ErrorHandlerOptions<State> {
  */
 declare function withErrorHandler<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: ErrorHandlerOptions<State>): (state: State) => Promise<State | Partial<State>>;
 
-/**
- * Shared JSON-safe payload contracts for observability and monitoring paths.
- */
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-interface JsonObject {
-    [key: string]: JsonValue;
-}
-
 /**
  * Structured Logging Utilities
  *

package/dist/index.d.ts

@@ -1570,26 +1570,38 @@ declare function createToolExecutor(config?: ToolExecutorConfig): {
     };
 };
 
+/**
+ * Shared JSON-safe payload contracts for observability and monitoring paths.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+
 /**
  * Tool Lifecycle Management - Manage tool initialization, cleanup, and resources
  * @module tools/lifecycle
  */
+
 interface ToolHealthCheckResult {
     healthy: boolean;
     error?: string;
-    metadata?: Record<string, any>;
+    metadata?: JsonObject;
 }
-interface ManagedToolConfig<TContext = any, TInput = any, TOutput = any> {
+interface ManagedToolConfigBase<TContext, TInput, TOutput> {
     name: string;
     description: string;
     initialize?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
     execute: (this: ManagedTool<TContext, TInput, TOutput>, input: TInput) => Promise<TOutput>;
     cleanup?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
     healthCheck?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<ToolHealthCheckResult>;
-    context?: TContext;
     autoCleanup?: boolean;
     healthCheckInterval?: number;
 }
+interface ManagedToolConfig<TContext = undefined, TInput = unknown, TOutput = unknown> extends ManagedToolConfigBase<TContext, TInput, TOutput> {
+    context?: TContext;
+}
 interface ManagedToolStats {
     initialized: boolean;
     totalExecutions: number;
@@ -1602,7 +1614,7 @@ interface ManagedToolStats {
 /**
  * Managed tool with lifecycle hooks
  */
-declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
+declare class ManagedTool<TContext = undefined, TInput = unknown, TOutput = unknown> {
     readonly name: string;
     readonly description: string;
     private readonly initializeFn?;
@@ -1615,15 +1627,21 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
     private _context;
     private _stats;
     private _healthCheckTimer?;
+    private _beforeExitHandler?;
+    private _healthCheckInFlight;
+    private _cleaningUp;
+    private _cleanupPromise?;
+    private _initializePromise?;
+    private _lifecycleGeneration;
     constructor(config: ManagedToolConfig<TContext, TInput, TOutput>);
     /**
      * Get the tool context (e.g., connection pool, API client)
      */
-    get context(): TContext;
+    get context(): TContext | undefined;
     /**
      * Set the tool context
      */
-    set context(value: TContext);
+    set context(value: TContext | undefined);
     /**
      * Check if tool is initialized
      */
@@ -1640,6 +1658,7 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
      * Cleanup the tool
      */
     cleanup(): Promise<void>;
+    private performCleanup;
     /**
      * Run health check
      */
@@ -1660,11 +1679,14 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
         description: string;
         invoke: (input: TInput) => Promise<TOutput>;
     };
+    private runPeriodicHealthCheck;
+    private performInitialize;
+    private ensureBeforeExitHandler;
 }
 /**
  * Create a managed tool
  */
-declare function createManagedTool<TContext = any, TInput = any, TOutput = any>(config: ManagedToolConfig<TContext, TInput, TOutput>): ManagedTool<TContext, TInput, TOutput>;
+declare function createManagedTool<TContext = undefined, TInput = unknown, TOutput = unknown>(config: ManagedToolConfig<TContext, TInput, TOutput>): ManagedTool<TContext, TInput, TOutput>;
 
 /**
  * Tool Composition - Compose tools into higher-level operations
@@ -2815,15 +2837,6 @@ interface ErrorHandlerOptions<State> {
  */
 declare function withErrorHandler<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: ErrorHandlerOptions<State>): (state: State) => Promise<State | Partial<State>>;
 
-/**
- * Shared JSON-safe payload contracts for observability and monitoring paths.
- */
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-interface JsonObject {
-    [key: string]: JsonValue;
-}
-
 /**
  * Structured Logging Utilities
  *

package/dist/index.js

@@ -1671,6 +1671,12 @@ var ManagedTool = class {
     failedExecutions: 0
   };
   _healthCheckTimer;
+  _beforeExitHandler;
+  _healthCheckInFlight = false;
+  _cleaningUp = false;
+  _cleanupPromise;
+  _initializePromise;
+  _lifecycleGeneration = 0;
   constructor(config) {
     this.name = config.name;
     this.description = config.description;
@@ -1681,17 +1687,7 @@ var ManagedTool = class {
     this.autoCleanup = config.autoCleanup ?? true;
     this.healthCheckInterval = config.healthCheckInterval;
     this._context = config.context;
-    if (this.autoCleanup) {
-      process.on("beforeExit", () => {
-        this.cleanup().catch(
-          (err) => logger3.error("Cleanup failed", {
-            toolName: this.name,
-            error: err instanceof Error ? err.message : String(err),
-            ...err instanceof Error && err.stack ? { stack: err.stack } : {}
-          })
-        );
-      });
-    }
+    this.ensureBeforeExitHandler();
   }
   /**
    * Get the tool context (e.g., connection pool, API client)
@@ -1715,28 +1711,26 @@ var ManagedTool = class {
    * Initialize the tool
    */
   async initialize() {
-    if (this._initialized) {
+    if (this._initializePromise) {
+      await this._initializePromise;
       return;
     }
-    if (this.initializeFn) {
-      await this.initializeFn();
+    if (this._cleanupPromise) {
+      await this._cleanupPromise;
+      if (this._initializePromise) {
+        await this._initializePromise;
+        return;
+      }
     }
-    this._initialized = true;
-    this._stats.initialized = true;
-    if (this.healthCheckInterval && this.healthCheckFn) {
-      this._healthCheckTimer = setInterval(async () => {
-        try {
-          const result = await this.healthCheckFn();
-          this._stats.lastHealthCheck = result;
-          this._stats.lastHealthCheckTime = Date.now();
-        } catch (error) {
-          this._stats.lastHealthCheck = {
-            healthy: false,
-            error: error.message
-          };
-          this._stats.lastHealthCheckTime = Date.now();
-        }
-      }, this.healthCheckInterval);
+    if (this._initialized) {
+      return;
+    }
+    const initializePromise = this.performInitialize();
+    this._initializePromise = initializePromise;
+    try {
+      await initializePromise;
+    } finally {
+      this._initializePromise = void 0;
     }
   }
   /**
@@ -1763,24 +1757,55 @@ var ManagedTool = class {
    * Cleanup the tool
    */
   async cleanup() {
-    if (!this._initialized) {
+    if (this._cleanupPromise) {
+      await this._cleanupPromise;
       return;
     }
+    if (this._initializePromise) {
+      try {
+        await this._initializePromise;
+      } catch {
+      }
+    }
+    const cleanupPromise = this.performCleanup();
+    this._cleanupPromise = cleanupPromise;
+    try {
+      await cleanupPromise;
+    } finally {
+      this._cleanupPromise = void 0;
+    }
+  }
+  async performCleanup() {
+    this._cleaningUp = true;
     if (this._healthCheckTimer) {
       clearInterval(this._healthCheckTimer);
       this._healthCheckTimer = void 0;
     }
-    if (this.cleanupFn) {
-      await this.cleanupFn();
+    if (this._beforeExitHandler) {
+      process.off("beforeExit", this._beforeExitHandler);
+      this._beforeExitHandler = void 0;
+    }
+    if (!this._initialized) {
+      this._cleaningUp = false;
+      return;
     }
     this._initialized = false;
     this._stats.initialized = false;
+    if (this.cleanupFn) {
+      try {
+        await this.cleanupFn();
+      } finally {
+        this._cleaningUp = false;
+      }
+      return;
+    }
+    this._cleaningUp = false;
   }
   /**
    * Run health check
    */
   async healthCheck() {
-    if (!this._initialized) {
+    if (!this._initialized || this._cleaningUp) {
       return {
         healthy: false,
         error: "Tool is not initialized"
@@ -1792,15 +1817,28 @@ var ManagedTool = class {
         metadata: { message: "No health check configured" }
       };
     }
+    const lifecycleGeneration = this._lifecycleGeneration;
     try {
       const result = await this.healthCheckFn();
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return {
+          healthy: false,
+          error: "Tool is not initialized"
+        };
+      }
       this._stats.lastHealthCheck = result;
       this._stats.lastHealthCheckTime = Date.now();
       return result;
     } catch (error) {
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return {
+          healthy: false,
+          error: "Tool is not initialized"
+        };
+      }
       const result = {
         healthy: false,
-        error: error.message
+        error: getErrorMessage(error)
       };
       this._stats.lastHealthCheck = result;
       this._stats.lastHealthCheckTime = Date.now();
@@ -1834,10 +1872,68 @@ var ManagedTool = class {
       }
     };
   }
+  async runPeriodicHealthCheck() {
+    if (!this.healthCheckFn || this._healthCheckInFlight || !this._initialized || this._cleaningUp) {
+      return;
+    }
+    this._healthCheckInFlight = true;
+    const lifecycleGeneration = this._lifecycleGeneration;
+    try {
+      const result = await this.healthCheckFn();
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return;
+      }
+      this._stats.lastHealthCheck = result;
+      this._stats.lastHealthCheckTime = Date.now();
+    } catch (error) {
+      if (!this._initialized || this._cleaningUp || this._lifecycleGeneration !== lifecycleGeneration) {
+        return;
+      }
+      this._stats.lastHealthCheck = {
+        healthy: false,
+        error: getErrorMessage(error)
+      };
+      this._stats.lastHealthCheckTime = Date.now();
+    } finally {
+      this._healthCheckInFlight = false;
+    }
+  }
+  async performInitialize() {
+    this.ensureBeforeExitHandler();
+    this._lifecycleGeneration++;
+    if (this.initializeFn) {
+      await this.initializeFn();
+    }
+    this._initialized = true;
+    this._stats.initialized = true;
+    if (this.healthCheckInterval && this.healthCheckFn) {
+      this._healthCheckTimer = setInterval(() => {
+        void this.runPeriodicHealthCheck();
+      }, this.healthCheckInterval);
+    }
+  }
+  ensureBeforeExitHandler() {
+    if (!this.autoCleanup || this._beforeExitHandler) {
+      return;
+    }
+    this._beforeExitHandler = () => {
+      this.cleanup().catch(
+        (err) => logger3.error("Cleanup failed", {
+          toolName: this.name,
+          error: getErrorMessage(err),
+          ...err instanceof Error && err.stack ? { stack: err.stack } : {}
+        })
+      );
+    };
+    process.on("beforeExit", this._beforeExitHandler);
+  }
 };
 function createManagedTool(config) {
   return new ManagedTool(config);
 }
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 // src/tools/composition.ts
 function isConditionalStep(step) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.16.18",
+  "version": "0.16.19",
   "description": "Production-ready TypeScript agent framework built on LangGraph with orchestration, middleware, and typed abstractions.",
   "type": "module",
   "main": "./dist/index.cjs",