@agentforge/tools 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,6 @@
 # @agentforge/tools
 
-> Production-ready tools collection for AgentForge - 69 tools for web, data, file, and utility operations
+> Production-ready tools collection for AgentForge - 70 tools for web, data, file, utility, and agent operations
 
 [![npm version](https://img.shields.io/npm/v/@agentforge/tools)](https://www.npmjs.com/package/@agentforge/tools)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
@@ -8,7 +8,7 @@
 
 ## 🎉 Status: Production Ready & Published
 
-**69 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
+**70 production-ready tools** | **Full TypeScript support** | **Comprehensive documentation** | **LangChain compatible**
 
 ## 📦 Installation
 
@@ -22,12 +22,13 @@ yarn add @agentforge/tools
 
 ## 🎯 Overview
 
-This package provides **69 ready-to-use tools** organized into 4 categories:
+This package provides **70 ready-to-use tools** organized into 5 categories:
 
 - **🌐 Web Tools** (11 tools) - HTTP requests, web search, web scraping, HTML parsing, URL manipulation
 - **📊 Data Tools** (18 tools) - JSON, CSV, XML processing and data transformation
 - **📁 File Tools** (18 tools) - File operations, directory management, path utilities
 - **🔧 Utility Tools** (22 tools) - Date/time, strings, math, validation
+- **🤖 Agent Tools** (1 tool) - Human-in-the-loop and agent interaction
 
 All tools feature:
 - ✅ Full TypeScript support with type inference

package/dist/index.cjs

@@ -10,6 +10,7 @@ var fastXmlParser = require('fast-xml-parser');
 var fs = require('fs');
 var path3 = require('path');
 var dateFns = require('date-fns');
+var crypto = require('crypto');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -1993,14 +1994,94 @@ var uuidValidator = core.toolBuilder().name("uuid-validator").description("Valid
     message: valid ? `Valid UUID v${version}` : "Invalid UUID format"
   };
 }).build();
+var AskHumanInputSchema = zod.z.object({
+  /**
+   * The question to ask the human
+   */
+  question: zod.z.string().min(1).describe("The question to ask the human"),
+  /**
+   * Optional context to help the human understand the question
+   */
+  context: zod.z.record(zod.z.any()).optional().describe("Additional context for the question"),
+  /**
+   * Priority level for this request
+   */
+  priority: zod.z.enum(["low", "normal", "high", "critical"]).default("normal").describe("Priority level for this request"),
+  /**
+   * Timeout in milliseconds (0 = no timeout)
+   */
+  timeout: zod.z.number().min(0).default(0).describe("Timeout in milliseconds (0 = no timeout)"),
+  /**
+   * Default response if timeout occurs
+   */
+  defaultResponse: zod.z.string().optional().describe("Default response if timeout occurs"),
+  /**
+   * Suggested responses (for UI to show as options)
+   */
+  suggestions: zod.z.array(zod.z.string()).optional().describe("Suggested responses for the human")
+});
+function createAskHumanTool() {
+  return core.toolBuilder().name("ask-human").description(
+    "Ask a human for input or approval. Use this when you need human guidance, approval for a critical action, or clarification on ambiguous requirements. The agent execution will pause until the human responds."
+  ).category(core.ToolCategory.UTILITY).schema(AskHumanInputSchema).implement(async (input) => {
+    const validatedInput = input;
+    const requestId = crypto.randomUUID();
+    const requestedAt = Date.now();
+    let interrupt;
+    try {
+      const langgraph = await import('@langchain/langgraph');
+      interrupt = langgraph.interrupt;
+    } catch (error) {
+      throw new Error(
+        "askHuman tool requires @langchain/langgraph to be installed. Install it with: npm install @langchain/langgraph"
+      );
+    }
+    if (!interrupt) {
+      throw new Error(
+        "interrupt function not found in @langchain/langgraph. Make sure you are using a compatible version of LangGraph."
+      );
+    }
+    const humanRequest = {
+      id: requestId,
+      question: validatedInput.question,
+      context: validatedInput.context,
+      priority: validatedInput.priority,
+      createdAt: requestedAt,
+      timeout: validatedInput.timeout,
+      defaultResponse: validatedInput.defaultResponse,
+      suggestions: validatedInput.suggestions,
+      status: "pending"
+    };
+    const response = interrupt(humanRequest);
+    const respondedAt = Date.now();
+    const duration = respondedAt - requestedAt;
+    const timedOut = validatedInput.timeout > 0 && duration >= validatedInput.timeout;
+    const finalResponse = timedOut && validatedInput.defaultResponse ? validatedInput.defaultResponse : response || "";
+    return {
+      response: finalResponse,
+      metadata: {
+        requestId,
+        requestedAt,
+        respondedAt,
+        duration,
+        timedOut,
+        priority: validatedInput.priority
+      }
+    };
+  }).build();
+}
+var askHumanTool = createAskHumanTool();
 
+exports.AskHumanInputSchema = AskHumanInputSchema;
 exports.DuckDuckGoProvider = DuckDuckGoProvider;
 exports.SerperProvider = SerperProvider;
 exports.arrayFilter = arrayFilter;
 exports.arrayGroupBy = arrayGroupBy;
 exports.arrayMap = arrayMap;
 exports.arraySort = arraySort;
+exports.askHumanTool = askHumanTool;
 exports.calculator = calculator;
+exports.createAskHumanTool = createAskHumanTool;
 exports.createDuckDuckGoProvider = createDuckDuckGoProvider;
 exports.createSerperProvider = createSerperProvider;
 exports.creditCardValidator = creditCardValidator;