@agentforge/core 0.16.17 → 0.16.19

package/dist/index.cjs

@@ -991,6 +991,79 @@ function emitRegistryEvent(eventHandlers, event, data) {
   });
 }
 
+// src/tools/registry-mutations.ts
+function eraseToolType(tool) {
+  return tool;
+}
+function registerRegistryTool(tools, tool, emit, events) {
+  const name = tool.metadata.name;
+  if (tools.has(name)) {
+    throw new Error(
+      `Tool with name "${name}" is already registered. Use update() to modify it.`
+    );
+  }
+  tools.set(name, eraseToolType(tool));
+  emit(events.registered, tool);
+}
+function removeRegistryTool(tools, name, emit, events) {
+  const tool = tools.get(name);
+  if (!tool) {
+    return false;
+  }
+  tools.delete(name);
+  emit(events.removed, tool);
+  return true;
+}
+function updateRegistryTool(tools, name, tool, emit, events) {
+  if (!tools.has(name)) {
+    return false;
+  }
+  if (tool.metadata.name !== name) {
+    throw new Error(
+      `Cannot update tool: metadata.name "${tool.metadata.name}" does not match registry key "${name}". To rename a tool, remove it and register it again with the new name.`
+    );
+  }
+  tools.set(name, eraseToolType(tool));
+  emit(events.updated, { name, tool });
+  return true;
+}
+function registerManyRegistryTools(tools, toolsToRegister, emit, events) {
+  const pendingTools = Array.from(toolsToRegister);
+  const inputNames = /* @__PURE__ */ new Set();
+  const duplicatesInInput = [];
+  for (const tool of pendingTools) {
+    const name = tool.metadata.name;
+    if (inputNames.has(name)) {
+      duplicatesInInput.push(name);
+    } else {
+      inputNames.add(name);
+    }
+  }
+  if (duplicatesInInput.length > 0) {
+    throw new Error(
+      `Cannot register tools: duplicate names in input list: ${duplicatesInInput.join(", ")}`
+    );
+  }
+  const conflicts = [];
+  for (const tool of pendingTools) {
+    if (tools.has(tool.metadata.name)) {
+      conflicts.push(tool.metadata.name);
+    }
+  }
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Cannot register tools: the following names already exist: ${conflicts.join(", ")}`
+    );
+  }
+  for (const tool of pendingTools) {
+    registerRegistryTool(tools, tool, emit, events);
+  }
+}
+function clearRegistryTools(tools, emit, events) {
+  tools.clear();
+  emit(events.cleared, null);
+}
+
 // src/tools/registry-prompt.ts
 var import_zod3 = require("zod");
 
@@ -1261,33 +1334,31 @@ var RegistryEvent = /* @__PURE__ */ ((RegistryEvent2) => {
   RegistryEvent2["REGISTRY_CLEARED"] = "registry:cleared";
   return RegistryEvent2;
 })(RegistryEvent || {});
-function eraseToolType(tool) {
-  return tool;
-}
 var ToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
+  mutationEvents = {
+    registered: "tool:registered" /* TOOL_REGISTERED */,
+    removed: "tool:removed" /* TOOL_REMOVED */,
+    updated: "tool:updated" /* TOOL_UPDATED */,
+    cleared: "registry:cleared" /* REGISTRY_CLEARED */
+  };
+  emitMutation = (event, data) => {
+    this.emit(event, data);
+  };
   /**
    * Register a tool in the registry
    * 
    * @param tool - The tool to register
    * @throws Error if a tool with the same name already exists
    * 
-   * @example
-   * ```ts
-   * registry.register(readFileTool);
+  * @example
+  * ```ts
+  * registry.register(readFileTool);
    * ```
    */
   register(tool) {
-    const erasedTool = eraseToolType(tool);
-    const name = tool.metadata.name;
-    if (this.tools.has(name)) {
-      throw new Error(
-        `Tool with name "${name}" is already registered. Use update() to modify it.`
-      );
-    }
-    this.tools.set(name, erasedTool);
-    this.emit("tool:registered" /* TOOL_REGISTERED */, tool);
+    registerRegistryTool(this.tools, tool, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get a tool by name
@@ -1328,20 +1399,14 @@ var ToolRegistry = class {
    * @param name - The tool name
    * @returns True if the tool was removed, false if it didn't exist
    * 
-   * @example
-   * ```ts
-   * const removed = registry.remove('read-file');
-   * console.log(removed ? 'Removed' : 'Not found');
+  * @example
+  * ```ts
+  * const removed = registry.remove('read-file');
+  * console.log(removed ? 'Removed' : 'Not found');
    * ```
    */
   remove(name) {
-    const tool = this.tools.get(name);
-    if (!tool) {
-      return false;
-    }
-    this.tools.delete(name);
-    this.emit("tool:removed" /* TOOL_REMOVED */, tool);
-    return true;
+    return removeRegistryTool(this.tools, name, this.emitMutation, this.mutationEvents);
   }
   /**
    * Update an existing tool
@@ -1351,24 +1416,13 @@ var ToolRegistry = class {
    * @returns True if updated, false if the tool didn't exist
    * @throws Error if the tool's metadata.name doesn't match the name parameter
    *
-   * @example
-   * ```ts
-   * const updated = registry.update('read-file', newReadFileTool);
+  * @example
+  * ```ts
+  * const updated = registry.update('read-file', newReadFileTool);
    * ```
    */
   update(name, tool) {
-    const erasedTool = eraseToolType(tool);
-    if (!this.tools.has(name)) {
-      return false;
-    }
-    if (tool.metadata.name !== name) {
-      throw new Error(
-        `Cannot update tool: metadata.name "${tool.metadata.name}" does not match registry key "${name}". To rename a tool, remove it and register it again with the new name.`
-      );
-    }
-    this.tools.set(name, erasedTool);
-    this.emit("tool:updated" /* TOOL_UPDATED */, { name, tool });
-    return true;
+    return updateRegistryTool(this.tools, name, tool, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get all registered tools
@@ -1435,55 +1489,25 @@ var ToolRegistry = class {
    * @param tools - Iterable of tools to register
    * @throws Error if any tool name conflicts with existing tools
    *
-   * @example
-   * ```ts
-   * registry.registerMany([tool1, tool2, tool3]);
+  * @example
+  * ```ts
+  * registry.registerMany([tool1, tool2, tool3]);
    * ```
    */
   registerMany(tools) {
-    const toolsToRegister = Array.from(tools);
-    const inputNames = /* @__PURE__ */ new Set();
-    const duplicatesInInput = [];
-    for (const tool of toolsToRegister) {
-      const name = tool.metadata.name;
-      if (inputNames.has(name)) {
-        duplicatesInInput.push(name);
-      } else {
-        inputNames.add(name);
-      }
-    }
-    if (duplicatesInInput.length > 0) {
-      throw new Error(
-        `Cannot register tools: duplicate names in input list: ${duplicatesInInput.join(", ")}`
-      );
-    }
-    const conflicts = [];
-    for (const tool of toolsToRegister) {
-      if (this.tools.has(tool.metadata.name)) {
-        conflicts.push(tool.metadata.name);
-      }
-    }
-    if (conflicts.length > 0) {
-      throw new Error(
-        `Cannot register tools: the following names already exist: ${conflicts.join(", ")}`
-      );
-    }
-    for (const tool of toolsToRegister) {
-      this.register(tool);
-    }
+    registerManyRegistryTools(this.tools, tools, this.emitMutation, this.mutationEvents);
   }
   /**
    * Clear all tools from the registry
    *
-   * @example
-   * ```ts
-   * registry.clear();
-   * console.log(registry.size()); // 0
+  * @example
+  * ```ts
+  * registry.clear();
+  * console.log(registry.size()); // 0
    * ```
    */
   clear() {
-    this.tools.clear();
-    this.emit("registry:cleared" /* REGISTRY_CLEARED */, null);
+    clearRegistryTools(this.tools, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get the number of registered tools
@@ -1822,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;
@@ -1832,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)
@@ -1866,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;
     }
   }
   /**
@@ -1914,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"
@@ -1943,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();
@@ -1985,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

@@ -1257,15 +1257,17 @@ interface PromptOptions extends RegistryPromptOptions {
 declare class ToolRegistry {
     private tools;
     private eventHandlers;
+    private readonly mutationEvents;
+    private readonly emitMutation;
     /**
      * Register a tool in the registry
      *
      * @param tool - The tool to register
      * @throws Error if a tool with the same name already exists
      *
-     * @example
-     * ```ts
-     * registry.register(readFileTool);
+    * @example
+    * ```ts
+    * registry.register(readFileTool);
      * ```
      */
     register<TInput, TOutput>(tool: Tool<TInput, TOutput>): void;
@@ -1304,10 +1306,10 @@ declare class ToolRegistry {
      * @param name - The tool name
      * @returns True if the tool was removed, false if it didn't exist
      *
-     * @example
-     * ```ts
-     * const removed = registry.remove('read-file');
-     * console.log(removed ? 'Removed' : 'Not found');
+    * @example
+    * ```ts
+    * const removed = registry.remove('read-file');
+    * console.log(removed ? 'Removed' : 'Not found');
      * ```
      */
     remove(name: string): boolean;
@@ -1319,9 +1321,9 @@ declare class ToolRegistry {
      * @returns True if updated, false if the tool didn't exist
      * @throws Error if the tool's metadata.name doesn't match the name parameter
      *
-     * @example
-     * ```ts
-     * const updated = registry.update('read-file', newReadFileTool);
+    * @example
+    * ```ts
+    * const updated = registry.update('read-file', newReadFileTool);
      * ```
      */
     update<TInput, TOutput>(name: string, tool: Tool<TInput, TOutput>): boolean;
@@ -1382,19 +1384,19 @@ declare class ToolRegistry {
      * @param tools - Iterable of tools to register
      * @throws Error if any tool name conflicts with existing tools
      *
-     * @example
-     * ```ts
-     * registry.registerMany([tool1, tool2, tool3]);
+    * @example
+    * ```ts
+    * registry.registerMany([tool1, tool2, tool3]);
      * ```
      */
     registerMany(tools: Iterable<RegisterManyTool>): void;
     /**
      * Clear all tools from the registry
      *
-     * @example
-     * ```ts
-     * registry.clear();
-     * console.log(registry.size()); // 0
+    * @example
+    * ```ts
+    * registry.clear();
+    * console.log(registry.size()); // 0
      * ```
      */
     clear(): void;
@@ -1568,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;
@@ -1600,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?;
@@ -1613,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
      */
@@ -1638,6 +1658,7 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
      * Cleanup the tool
      */
     cleanup(): Promise<void>;
+    private performCleanup;
     /**
      * Run health check
      */
@@ -1658,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
@@ -2813,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

@@ -1257,15 +1257,17 @@ interface PromptOptions extends RegistryPromptOptions {
 declare class ToolRegistry {
     private tools;
     private eventHandlers;
+    private readonly mutationEvents;
+    private readonly emitMutation;
     /**
      * Register a tool in the registry
      *
      * @param tool - The tool to register
      * @throws Error if a tool with the same name already exists
      *
-     * @example
-     * ```ts
-     * registry.register(readFileTool);
+    * @example
+    * ```ts
+    * registry.register(readFileTool);
      * ```
      */
     register<TInput, TOutput>(tool: Tool<TInput, TOutput>): void;
@@ -1304,10 +1306,10 @@ declare class ToolRegistry {
      * @param name - The tool name
      * @returns True if the tool was removed, false if it didn't exist
      *
-     * @example
-     * ```ts
-     * const removed = registry.remove('read-file');
-     * console.log(removed ? 'Removed' : 'Not found');
+    * @example
+    * ```ts
+    * const removed = registry.remove('read-file');
+    * console.log(removed ? 'Removed' : 'Not found');
      * ```
      */
     remove(name: string): boolean;
@@ -1319,9 +1321,9 @@ declare class ToolRegistry {
      * @returns True if updated, false if the tool didn't exist
      * @throws Error if the tool's metadata.name doesn't match the name parameter
      *
-     * @example
-     * ```ts
-     * const updated = registry.update('read-file', newReadFileTool);
+    * @example
+    * ```ts
+    * const updated = registry.update('read-file', newReadFileTool);
      * ```
      */
     update<TInput, TOutput>(name: string, tool: Tool<TInput, TOutput>): boolean;
@@ -1382,19 +1384,19 @@ declare class ToolRegistry {
      * @param tools - Iterable of tools to register
      * @throws Error if any tool name conflicts with existing tools
      *
-     * @example
-     * ```ts
-     * registry.registerMany([tool1, tool2, tool3]);
+    * @example
+    * ```ts
+    * registry.registerMany([tool1, tool2, tool3]);
      * ```
      */
     registerMany(tools: Iterable<RegisterManyTool>): void;
     /**
      * Clear all tools from the registry
      *
-     * @example
-     * ```ts
-     * registry.clear();
-     * console.log(registry.size()); // 0
+    * @example
+    * ```ts
+    * registry.clear();
+    * console.log(registry.size()); // 0
      * ```
      */
     clear(): void;
@@ -1568,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;
@@ -1600,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?;
@@ -1613,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
      */
@@ -1638,6 +1658,7 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
      * Cleanup the tool
      */
     cleanup(): Promise<void>;
+    private performCleanup;
     /**
      * Run health check
      */
@@ -1658,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
@@ -2813,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

@@ -816,6 +816,79 @@ function emitRegistryEvent(eventHandlers, event, data) {
   });
 }
 
+// src/tools/registry-mutations.ts
+function eraseToolType(tool) {
+  return tool;
+}
+function registerRegistryTool(tools, tool, emit, events) {
+  const name = tool.metadata.name;
+  if (tools.has(name)) {
+    throw new Error(
+      `Tool with name "${name}" is already registered. Use update() to modify it.`
+    );
+  }
+  tools.set(name, eraseToolType(tool));
+  emit(events.registered, tool);
+}
+function removeRegistryTool(tools, name, emit, events) {
+  const tool = tools.get(name);
+  if (!tool) {
+    return false;
+  }
+  tools.delete(name);
+  emit(events.removed, tool);
+  return true;
+}
+function updateRegistryTool(tools, name, tool, emit, events) {
+  if (!tools.has(name)) {
+    return false;
+  }
+  if (tool.metadata.name !== name) {
+    throw new Error(
+      `Cannot update tool: metadata.name "${tool.metadata.name}" does not match registry key "${name}". To rename a tool, remove it and register it again with the new name.`
+    );
+  }
+  tools.set(name, eraseToolType(tool));
+  emit(events.updated, { name, tool });
+  return true;
+}
+function registerManyRegistryTools(tools, toolsToRegister, emit, events) {
+  const pendingTools = Array.from(toolsToRegister);
+  const inputNames = /* @__PURE__ */ new Set();
+  const duplicatesInInput = [];
+  for (const tool of pendingTools) {
+    const name = tool.metadata.name;
+    if (inputNames.has(name)) {
+      duplicatesInInput.push(name);
+    } else {
+      inputNames.add(name);
+    }
+  }
+  if (duplicatesInInput.length > 0) {
+    throw new Error(
+      `Cannot register tools: duplicate names in input list: ${duplicatesInInput.join(", ")}`
+    );
+  }
+  const conflicts = [];
+  for (const tool of pendingTools) {
+    if (tools.has(tool.metadata.name)) {
+      conflicts.push(tool.metadata.name);
+    }
+  }
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Cannot register tools: the following names already exist: ${conflicts.join(", ")}`
+    );
+  }
+  for (const tool of pendingTools) {
+    registerRegistryTool(tools, tool, emit, events);
+  }
+}
+function clearRegistryTools(tools, emit, events) {
+  tools.clear();
+  emit(events.cleared, null);
+}
+
 // src/tools/registry-prompt.ts
 import { z as z3 } from "zod";
 
@@ -1086,33 +1159,31 @@ var RegistryEvent = /* @__PURE__ */ ((RegistryEvent2) => {
   RegistryEvent2["REGISTRY_CLEARED"] = "registry:cleared";
   return RegistryEvent2;
 })(RegistryEvent || {});
-function eraseToolType(tool) {
-  return tool;
-}
 var ToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
+  mutationEvents = {
+    registered: "tool:registered" /* TOOL_REGISTERED */,
+    removed: "tool:removed" /* TOOL_REMOVED */,
+    updated: "tool:updated" /* TOOL_UPDATED */,
+    cleared: "registry:cleared" /* REGISTRY_CLEARED */
+  };
+  emitMutation = (event, data) => {
+    this.emit(event, data);
+  };
   /**
    * Register a tool in the registry
    * 
    * @param tool - The tool to register
    * @throws Error if a tool with the same name already exists
    * 
-   * @example
-   * ```ts
-   * registry.register(readFileTool);
+  * @example
+  * ```ts
+  * registry.register(readFileTool);
    * ```
    */
   register(tool) {
-    const erasedTool = eraseToolType(tool);
-    const name = tool.metadata.name;
-    if (this.tools.has(name)) {
-      throw new Error(
-        `Tool with name "${name}" is already registered. Use update() to modify it.`
-      );
-    }
-    this.tools.set(name, erasedTool);
-    this.emit("tool:registered" /* TOOL_REGISTERED */, tool);
+    registerRegistryTool(this.tools, tool, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get a tool by name
@@ -1153,20 +1224,14 @@ var ToolRegistry = class {
    * @param name - The tool name
    * @returns True if the tool was removed, false if it didn't exist
    * 
-   * @example
-   * ```ts
-   * const removed = registry.remove('read-file');
-   * console.log(removed ? 'Removed' : 'Not found');
+  * @example
+  * ```ts
+  * const removed = registry.remove('read-file');
+  * console.log(removed ? 'Removed' : 'Not found');
    * ```
    */
   remove(name) {
-    const tool = this.tools.get(name);
-    if (!tool) {
-      return false;
-    }
-    this.tools.delete(name);
-    this.emit("tool:removed" /* TOOL_REMOVED */, tool);
-    return true;
+    return removeRegistryTool(this.tools, name, this.emitMutation, this.mutationEvents);
   }
   /**
    * Update an existing tool
@@ -1176,24 +1241,13 @@ var ToolRegistry = class {
    * @returns True if updated, false if the tool didn't exist
    * @throws Error if the tool's metadata.name doesn't match the name parameter
    *
-   * @example
-   * ```ts
-   * const updated = registry.update('read-file', newReadFileTool);
+  * @example
+  * ```ts
+  * const updated = registry.update('read-file', newReadFileTool);
    * ```
    */
   update(name, tool) {
-    const erasedTool = eraseToolType(tool);
-    if (!this.tools.has(name)) {
-      return false;
-    }
-    if (tool.metadata.name !== name) {
-      throw new Error(
-        `Cannot update tool: metadata.name "${tool.metadata.name}" does not match registry key "${name}". To rename a tool, remove it and register it again with the new name.`
-      );
-    }
-    this.tools.set(name, erasedTool);
-    this.emit("tool:updated" /* TOOL_UPDATED */, { name, tool });
-    return true;
+    return updateRegistryTool(this.tools, name, tool, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get all registered tools
@@ -1260,55 +1314,25 @@ var ToolRegistry = class {
    * @param tools - Iterable of tools to register
    * @throws Error if any tool name conflicts with existing tools
    *
-   * @example
-   * ```ts
-   * registry.registerMany([tool1, tool2, tool3]);
+  * @example
+  * ```ts
+  * registry.registerMany([tool1, tool2, tool3]);
    * ```
    */
   registerMany(tools) {
-    const toolsToRegister = Array.from(tools);
-    const inputNames = /* @__PURE__ */ new Set();
-    const duplicatesInInput = [];
-    for (const tool of toolsToRegister) {
-      const name = tool.metadata.name;
-      if (inputNames.has(name)) {
-        duplicatesInInput.push(name);
-      } else {
-        inputNames.add(name);
-      }
-    }
-    if (duplicatesInInput.length > 0) {
-      throw new Error(
-        `Cannot register tools: duplicate names in input list: ${duplicatesInInput.join(", ")}`
-      );
-    }
-    const conflicts = [];
-    for (const tool of toolsToRegister) {
-      if (this.tools.has(tool.metadata.name)) {
-        conflicts.push(tool.metadata.name);
-      }
-    }
-    if (conflicts.length > 0) {
-      throw new Error(
-        `Cannot register tools: the following names already exist: ${conflicts.join(", ")}`
-      );
-    }
-    for (const tool of toolsToRegister) {
-      this.register(tool);
-    }
+    registerManyRegistryTools(this.tools, tools, this.emitMutation, this.mutationEvents);
   }
   /**
    * Clear all tools from the registry
    *
-   * @example
-   * ```ts
-   * registry.clear();
-   * console.log(registry.size()); // 0
+  * @example
+  * ```ts
+  * registry.clear();
+  * console.log(registry.size()); // 0
    * ```
    */
   clear() {
-    this.tools.clear();
-    this.emit("registry:cleared" /* REGISTRY_CLEARED */, null);
+    clearRegistryTools(this.tools, this.emitMutation, this.mutationEvents);
   }
   /**
    * Get the number of registered tools
@@ -1647,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;
@@ -1657,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)
@@ -1691,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;
     }
   }
   /**
@@ -1739,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"
@@ -1768,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();
@@ -1810,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.17",
+  "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",